listutils - list derivatives

Python’s builtin list is a very fast and efficient sequence type, but it could be better for certain access patterns, such as non-sequential insertion into a large lists. listutils provides a pure-Python solution to this problem.

For utilities for working with iterables and lists, check out iterutils. For the a list-based version of collections.namedtuple, check out namedutils.

boltons.listutils.BList

alias of BarrelList

class boltons.listutils.BarrelList(iterable=None)

The BarrelList is a list subtype backed by many dynamically-scaled sublists, to provide better scaling and random insertion/deletion characteristics. It is a subtype of the builtin list and has an identical API, supporting indexing, slicing, sorting, etc. If application requirements call for something more performant, consider the blist module available on PyPI.

The name comes by way of Kurt Rose, who said it reminded him of barrel shifters. Not sure how, but it’s BList-like, so the name stuck. BList is of course a reference to B-trees.

Parameters:

iterable – An optional iterable of initial values for the list.

>>> blist = BList(range(100000))
>>> blist.pop(50000)
50000
>>> len(blist)
99999
>>> len(blist.lists)  # how many underlying lists
8
>>> slice_idx = blist.lists[0][-1]
>>> blist[slice_idx:slice_idx + 2]
BarrelList([11637, 11638])

Slicing is supported and works just fine across list borders, returning another instance of the BarrelList.

append(item)

Append object to the end of the list.

count(item)

Return number of occurrences of value.

del_slice(start, stop, step=None)

extend(iterable)

Extend list by appending elements from the iterable.

classmethod from_iterable(it)

index(item)

Return first index of value.

Raises ValueError if the value is not present.

insert(index, item)

Insert object before index.

iter_slice(start, stop, step=None)

pop(*a)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

reverse()

Reverse IN PLACE.

sort()

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.