API reference

All of the public types and functions are available from the pcollections package. The abstract base classes are in pcollections.abc.

Persistent collections

class pcollections.plist

A persistent (immutable) list.

Usage:

plist() -> an empty plist
plist(iterable) -> a plist of the elements of iterable

Methods that would change a list instead return a new plist (set, append, prepend, extend, insert, delete, drop, remove, pop, sort, reverse, clear). A plist is hashable if its elements are. transient() returns a tlist copy in constant time.

append(obj, /)

Returns a new list with object appended.

clear()

Returns the empty plist.

copy()

Returns the persistent object (persistent objects needn’t be copied).

count(value)

Returns the number of occurrences of value.

delete(index=-1, /)

Returns a copy of the plist with the item at index removed (default: last).

drop(index=-1, error=False)

Returns a copy of the persistent sequence with the element at the given index removed.

If the index is out of range, drop returns the sequence itself, or, if error is true, raises IndexError.

empty = [||]

extend(iterable)

Returns a copy of the persistent sequence with the iterable’s elements appended.

index(value, start=0, stop=None)

Returns the first index of value.

Raises ValueError if value is not present.

insert(index, obj, /)

Returns a new plist with object inserted before index.

pop(index=-1)

Returns a tuple of the value at the given index and a copy of the persistent sequence with the item at that index removed (default index: last).

prepend(obj, /)

Returns a new list with object prepended.

remove(value)

Returns a copy of the sequence with the first occurence of value removed.

Raises ValueError if the value is not present.

reverse()

Returns a reversed copy of the persistent sequence.

set(index, obj, /)

Returns a copy of the list with the given index set to the given object.

sort(key=None, reverse=False)

Returns a sorted copy of the given persistent sequence.

transient()

Efficiently copies the plist into a tlist and returns the tlist.

class pcollections.pset

A persistent (immutable) set.

Usage:

pset() -> an empty pset
pset(iterable) -> a pset of the elements of iterable

Methods that would change a set instead return a new pset (add, addall, discard, discardall, remove, removeall, drop, pop, clear). A pset remembers the order in which its elements were added, and has the same hash as an equal frozenset. transient() returns a tset copy in constant time.

add(obj, /)

Returns a copy of the pset that includes the given object.

addall(iterable)

Returns a copy of the persistent set with the given elements included.

clear()

Returns the empty pset.

copy()

Returns the persistent object (persistent objects needn’t be copied).

difference(*args)

Returns the difference of two or more sets as a new persistent set.

(I.e., all elements that are in this set but not the others.)

discard(obj, /)

Returns a copy of the pset that does not include the given object.

discardall(iterable)

Returns a copy of the persistent set with the given elements discarded.

If any element is not found, then it is ignored.

drop(obj, error=False)

Returns a copy of the persistent set without the given object.

If the object is not a member, drop returns the set itself, or, if error is true, raises KeyError.

empty = {||}

intersection(*args)

Return the intersection of two sets as a new persistent set.

(I.e., all elements that are in both sets.)

isdisjoint(other)

Returns True if two sets have a null intersection.

issubset(other)

Report whether another set contains this set.

issuperset(other)

Report whether this set contains another set.

pop()

Returns a tuple of the last element of the persistent set and a copy of the set with that element removed.

The last element is the one most recently added (the last one that iteration yields). Raises KeyError if the set is empty.

remove(element)

Removes an element from the persistent set; it must be a member.

Raises a KeyError if the element is not a member.

removeall(iterable)

Returns a copy of the persistent set with the given elements discarded.

If any element is not found, then it is ignored.

symmetric_difference(*args)

Return the symmetric difference of two sets as a new set.

(I.e., all elements that are in exactly one of the sets.)

transient()

Efficiently copies the pset into a tset and returns the tset.

union(*args)

Returns the union of the persistent set and all arguments.

class pcollections.pdict

A persistent (immutable) dictionary.

Usage:

pdict() -> an empty pdict
pdict(mapping) -> a pdict with the items of mapping
pdict(iterable) -> a pdict with the (key, value) pairs of iterable
pdict(**kwargs) -> a pdict with the given keyword items

The arguments are those of dict. Methods that would change a dict instead return a new pdict (set, setall, update, drop, dropall, delete, deleteall, setdefault, pop, popitem, clear). A pdict remembers the order in which its keys were added, and is hashable if its values are. transient() returns a tdict copy in constant time.

clear()

Returns the empty pdict.

copy()

Returns the persistent object (persistent objects needn’t be copied).

delete(key)

Returns a copy of the persistent mapping that excludes the given key.

If the key is not found in the mapping, a KeyError is raised.

deleteall(keys)

Returns a copy of the persistent mapping that excludes all the keys in the given iterable.

If any key is not found in the mapping, then a KeyError error is raised.

drop(key, error=False)

Returns a copy of the pdict without the given key; if the key is absent, returns the pdict itself, or raises KeyError if error is true.

dropall(keys)

Returns a copy of the persistent mapping that excludes all the keys in the given iterable.

Keys that are not found in the mapping are ignored.

empty = {||}

classmethod fromkeys(iterable, value=None)

Returns a new mapping with keys from iterable, each mapped to value.

get(key, default=None, /)

Returns the value for key if key is in the pdict, else default.

items()

Returns a view of the items.

keys()

Returns a view of the keys.

pop(key, *args)

Returns a tuple of the value mapped to the given key and a copy of the persistent mapping with that key removed.

If the key is not found, the second argument is returned, if given, otherwise, a KeyError is raised.

popitem()

Returns a 2-tuple whose first element is itself a 2-tuple, (key, value), of the last item in the persistent mapping, and whose second element is a copy of the mapping with that item removed.

As with dict.popitem, the last item is the one most recently inserted. Raises KeyError if the persistent mapping is empty.

set(key, val, /)

Returns a copy of the pdict that maps the given key to the given value.

setall(keys, vals)

Returns a copy of the persistent mapping that includes all the object in the given iterables of keys and values.

setdefault(key, default=None)

Returns a copy of the persistent mapping with the key inserted with a value of default, if key is not already in the mapping.

transient()

Efficiently copies the pdict into a tdict and returns the tdict.

update(*args, **kw)

Returns a copy of the persistent mapping with the key-value pairs in the iterable/mapping arg and the keyword arguments included.

Multiple arguments may be provided, but they must each be a mapping or an iterable of items.

values()

Returns a view of the values.

Transient collections

class pcollections.tlist

A transient (mutable) list.

Usage:

tlist() -> an empty tlist
tlist(iterable) -> a tlist of the elements of iterable

A tlist has the interface of list, plus prepend. persistent() returns a plist copy in constant time. A tlist is meant to be used by one thread at a time; a modification that overlaps another modification raises RuntimeError.

append(obj, /)

Appends object to the end of the list.

clear()

Clears all elements from the tlist.

copy()

Returns a copy of the given transient sequence.

count(value)

Returns the number of occurrences of value.

classmethod empty()

Returns a new, empty tlist.

extend(iterable)

Extends tlist by appending elements from the iterable.

index(value, start=0, stop=None)

Returns the first index of value.

Raises ValueError if value is not present.

insert(index, obj, /)

Inserts the given object before the given index.

persistent()

Efficiently copies the tlist into a plist and returns the plist.

pop(index=-1, /)

Removes and returns the item at index (default last).

prepend(obj, /)

Prepends object to the beginning of the tlist.

remove(value)

Removes the first occurence of value.

Raises ValueError if the value is not present.

reverse()

Reverses IN PLACE.

sort(key=None, reverse=False)

Sort the tlist in ascending order and return None.

The sort is in-place (i.e. the tlist 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.

class pcollections.tset

A transient (mutable) set.

Usage:

tset() -> an empty tset
tset(iterable) -> a tset of the elements of iterable

A tset has the interface of set, plus addall, discardall, and removeall. persistent() returns a pset copy in constant time. A tset is meant to be used by one thread at a time; a modification that overlaps another modification raises RuntimeError.

add(obj, /)

Adds the given object to the tset.

addall(iterable)

Returns a copy of the persistent set with the given elements included.

clear()

Clears all elements from the tset.

copy()

Returns a copy of the transient set.

difference(*args)

Returns the difference of two or more sets as a new transient set.

(I.e., all elements that are in this set but not the others.)

difference_update(*args)

Remove all elements of another set from this set.

discard(obj, /)

Discards the given object from the tset.

discardall(iterable)

Returns a copy of the persistent set with the given elements discarded.

If any element is not found, then it is ignored.

classmethod empty()

Returns a new, empty tset.

intersection(*args)

Return the intersection of two sets as a new transient set.

(I.e., all elements that are in both sets.)

intersection_update(*args)

Update a set with the intersection of itself and another.

isdisjoint(other)

Returns True if two sets have a null intersection.

issubset(other)

Report whether another set contains this set.

issuperset(other)

Report whether this set contains another set.

persistent()

Efficiently copies the tset into a pset and returns the pset.

pop()

Removes the last element from the transient set and returns it.

The last element is the one most recently added (the last one that iteration yields). Raises KeyError if the set is empty.

remove(element)

Removes an element from the persistent set; it must be a member.

Raises a KeyError if the element is not a member.

removeall(iterable)

Returns a copy of the persistent set with the given elements discarded.

If any element is not found, then a KeyError is raised.

symmetric_difference(other)

Return the symmetric difference of two sets as a new set.

(I.e., all elements that are in exactly one of the sets.)

symmetric_difference_update(other)

Update a set with the symmetric difference of itself and another.

union(*args)

Returns the union of the transient set and all arguments.

update(*args)

class pcollections.tdict

A transient (mutable) dictionary.

Usage:

tdict() -> an empty tdict
tdict(mapping) -> a tdict with the items of mapping
tdict(iterable) -> a tdict with the (key, value) pairs of iterable
tdict(**kwargs) -> a tdict with the given keyword items

A tdict has the interface of dict. persistent() returns a pdict copy in constant time. A tdict is meant to be used by one thread at a time; a modification that overlaps another modification raises RuntimeError.

clear()

Clears all elements from the tdict.

copy()

Returns a copy of the transient mapping.

classmethod empty()

Returns a new, empty tdict.

classmethod fromkeys(iterable, value=None)

Returns a new mapping with keys from iterable, each mapped to value.

get(key, default=None, /)

Returns the value for key if key is in the tdict, else default.

items()

Returns a view of the items.

keys()

Returns a view of the keys.

persistent()

Efficiently copies the tdict into a pdict and returns the pdict.

pop(key, *args)

Removes the specified key and returns the corresponding value.

If the key is not found, the second argument is returned, if given, otherwise, a KeyError is raised.

popitem()

Removes the last item from the transient mapping and returns it as a (key, value) 2-tuple.

As with dict.popitem, the last item is the one most recently inserted. Raises KeyError if the transient mapping is empty.

setdefault(key, default=None)

Insert key with a value of default if key is not in the dictionary.

Return the value for the key if key is in the dictionary, else default.

update(*args, **kw)

Updates the transient mapping with items from the arguments and options.

Multiple arguments may be provided, but they must each be either a mapping or an iterable of items.

values()

Returns a view of the values.

Lazy values

class pcollections.lazy(func, /, *args, **kwargs)

A value computed, at most once, by calling a function.

Calling a lazy object returns the value of func called with args and kwargs, computing it on the first call and releasing func and its arguments afterwards. The lazy collections (ldict, llist, tldict, tllist) compute their lazy values when they are read.

If func raises an exception, every call raises a new LazyError whose __cause__ is that exception. A lazy value whose computation requests its own value raises LazyError. Set lazy.trace (or the environment variable PCOLLECTIONS_LAZY_TRACE) to record the stack at each lazy’s creation. Pickling a lazy computes it and pickles its value.

is_ready()

Returns True if the value has been computed, otherwise False.

trace = False

pcollections.unlazy(object, /)

Returns the cached value of a lazy object, or the object itself if it is not lazy.

pcollections.holdlazy(obj, require_lazy=False)

Returns a lazy collection as the equivalent plain collection, with its lazy values uncomputed, by calling obj.__holdlazy__(). Other objects are returned unchanged, or, if require_lazy is true, raise TypeError.

exception pcollections.LazyError

The error raised when a lazy value cannot be computed.

When the computation raised an exception, that exception is the LazyError’s __cause__ (also available as cause). A lazy value that fails remembers its failure: every later request for it raises a new LazyError with the same cause, without running the computation again. A lazy value whose computation requests the value itself raises a LazyError with no cause.

When a computation fails because a lazy value it depends on failed, its cause is that value’s LazyError, so the chain of causes follows the dependencies down to the original exception, which is root_cause.

Variables:

• cause (BaseException or None) – The exception raised by the computation.

• root_cause (BaseException or None) – The first exception in the chain of causes that is not a LazyError: the exception that started the failure. It is None if the chain ends in a LazyError with no cause (a lazy value that depends on itself).

• func_kwargs (func, func_args,) – The function of the lazy value and the arguments it was called with.

• origin (tuple or None) – (filename, lineno, function_name) of the code that created the lazy value.

• origin_stack (list of str or None) – The formatted stack at the lazy value’s creation, if lazy.trace was true when it was created.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

args

property cause

The exception that caused this error, or None.

func = None

func_args = None

func_kwargs = None

origin = None

origin_stack = None

property root_cause

The exception that started the failure, or None (see the class documentation).

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

pcollections.lazy_error_unwrap

A function and context manager for unwrapping LazyError exceptions. lazy_error_unwrap(error) returns the cause of error if it is a LazyError with a cause, and otherwise returns error. Used as a context manager (with lazy_error_unwrap: ...), it re-raises the cause of any LazyError that propagates out of its block.

Lazy collections

class pcollections.llist

A persistent list whose lazy elements are computed when read.

An llist is a plist. Reading an element (by indexing, iteration, comparison, or conversion to another collection) computes it if it is a lazy object. The constructor keeps lazy elements uncomputed. getlazy, held_plist, and holdlazy return the lazy objects themselves.

append(obj, /)

Returns a new list with object appended.

clear()

Returns the empty plist.

copy()

Returns the persistent object (persistent objects needn’t be copied).

count(value)

Returns the number of occurrences of value.

delete(index=-1, /)

Returns a copy of the plist with the item at index removed (default: last).

drop(index=-1, error=False)

Returns a copy of the persistent sequence with the element at the given index removed.

If the index is out of range, drop returns the sequence itself, or, if error is true, raises IndexError.

empty = [||]

extend(iterable)

Returns a copy of the persistent sequence with the iterable’s elements appended.

getlazy(index, /)

Like self[index], but returns a lazy element itself rather than its value.

held_plist()

Returns a plist of the list’s elements with lazy elements left uncomputed.

index(value, start=0, stop=None)

Returns the first index of value.

Raises ValueError if value is not present.

insert(index, obj, /)

Returns a new plist with object inserted before index.

is_lazy(index, /)

Returns True if the element at index is a lazy object.

is_ready(index, /)

Returns True if the element at index is not lazy or has been computed.

pop(index=-1)

Returns a tuple of the value at the given index and a copy of the persistent sequence with the item at that index removed (default index: last).

prepend(obj, /)

Returns a new list with object prepended.

ready_all()

Computes all lazy elements, then returns the list.

remove(value)

Returns a copy of the sequence with the first occurence of value removed.

Raises ValueError if the value is not present.

reverse()

Returns a reversed copy of the persistent sequence.

set(index, obj, /)

Returns a copy of the list with the given index set to the given object.

sort(key=None, reverse=False)

Returns a sorted copy of the given persistent sequence.

transient()

Efficiently copies the plist into a tlist and returns the tlist.

class pcollections.tllist

A transient list whose lazy elements are computed when read.

A tllist is a tlist. Reading an element computes it if it is a lazy object. getlazy, held_tlist, and holdlazy return the lazy objects themselves.

append(obj, /)

Appends object to the end of the list.

clear()

Clears all elements from the tlist.

copy()

Returns a copy of the given transient sequence.

count(value)

Returns the number of occurrences of value.

classmethod empty()

Returns a new, empty tlist.

extend(iterable)

Extends tlist by appending elements from the iterable.

getlazy(index, /)

Like self[index], but returns a lazy element itself rather than its value.

held_tlist()

Returns a tlist of the list’s elements with lazy elements left uncomputed.

index(value, start=0, stop=None)

Returns the first index of value.

Raises ValueError if value is not present.

insert(index, obj, /)

Inserts the given object before the given index.

is_lazy(index, /)

Returns True if the element at index is a lazy object.

is_ready(index, /)

Returns True if the element at index is not lazy or has been computed.

persistent()

Efficiently copies the tlist into a plist and returns the plist.

pop(index=-1, /)

Removes and returns the (computed) element at index (default last).

prepend(obj, /)

Prepends object to the beginning of the tlist.

ready_all()

Computes all lazy elements, then returns the list.

remove(value)

Removes the first occurence of value.

Raises ValueError if the value is not present.

reverse()

Reverses IN PLACE.

sort(key=None, reverse=False)

Sort the tlist in ascending order and return None.

The sort is in-place (i.e. the tlist 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.

class pcollections.ldict

A persistent dictionary whose lazy values are computed when read.

An ldict is a pdict. Reading a value (by indexing, get, values, items, iteration, comparison, or conversion to another collection) computes it if it is a lazy object. The constructor keeps lazy values uncomputed. getlazy, held_pdict, and holdlazy return the lazy objects themselves.

clear()

Returns the empty pdict.

copy()

Returns the persistent object (persistent objects needn’t be copied).

delete(key)

Returns a copy of the persistent mapping that excludes the given key.

If the key is not found in the mapping, a KeyError is raised.

deleteall(keys)

Returns a copy of the persistent mapping that excludes all the keys in the given iterable.

If any key is not found in the mapping, then a KeyError error is raised.

drop(key, error=False)

Returns a copy of the pdict without the given key; if the key is absent, returns the pdict itself, or raises KeyError if error is true.

dropall(keys)

Returns a copy of the persistent mapping that excludes all the keys in the given iterable.

Keys that are not found in the mapping are ignored.

empty = {||}

classmethod fromkeys(iterable, value=None)

Returns a new mapping with keys from iterable, each mapped to value.

get(key, default=None, /)

Returns the (computed) value for key, or default if key is absent.

getlazy(key, default=None, /)

Like get(), but returns a lazy value itself rather than its value.

held_pdict()

Returns a pdict of the dict’s items with lazy values left uncomputed.

is_lazy(key, /)

Returns True if key is mapped to a lazy object.

is_ready(key, /)

Returns True if key is mapped to a non-lazy value or a computed lazy value.

items()

Returns a view of the items, with lazy values computed.

keys()

Returns a view of the keys.

pop(key, *args)

Returns a tuple of the value mapped to the given key and a copy of the persistent mapping with that key removed.

If the key is not found, the second argument is returned, if given, otherwise, a KeyError is raised.

popitem()

Returns a 2-tuple whose first element is itself a 2-tuple, (key, value), of the last item in the persistent mapping, and whose second element is a copy of the mapping with that item removed.

As with dict.popitem, the last item is the one most recently inserted. Raises KeyError if the persistent mapping is empty.

ready_all()

Computes all lazy values, then returns the dict.

set(key, val, /)

Returns a copy of the pdict that maps the given key to the given value.

setall(keys, vals)

Returns a copy of the persistent mapping that includes all the object in the given iterables of keys and values.

setdefault(key, default=None)

Returns a copy of the persistent mapping with the key inserted with a value of default, if key is not already in the mapping.

transient()

Efficiently copies the pdict into a tdict and returns the tdict.

update(*args, **kw)

Returns a copy of the persistent mapping with the key-value pairs in the iterable/mapping arg and the keyword arguments included.

Multiple arguments may be provided, but they must each be a mapping or an iterable of items.

values()

Returns a view of the values, with lazy values computed.

class pcollections.tldict

A transient dictionary whose lazy values are computed when read.

A tldict is a tdict. Reading a value computes it if it is a lazy object. getlazy, held_tdict, and holdlazy return the lazy objects themselves.

clear()

Clears all elements from the tdict.

copy()

Returns a copy of the transient mapping.

classmethod empty()

Returns a new, empty tdict.

classmethod fromkeys(iterable, value=None)

Returns a new mapping with keys from iterable, each mapped to value.

get(key, default=None, /)

Returns the (computed) value for key, or default if key is absent.

getlazy(key, default=None, /)

Like get(), but returns a lazy value itself rather than its value.

held_tdict()

Returns a tdict of the dict’s items with lazy values left uncomputed.

is_lazy(key, /)

Returns True if key is mapped to a lazy object.

is_ready(key, /)

Returns True if key is mapped to a non-lazy value or a computed lazy value.

items()

Returns a view of the items, with lazy values computed.

keys()

Returns a view of the keys.

persistent()

Efficiently copies the tdict into a pdict and returns the pdict.

pop()

Removes key and returns its (computed) value.

popitem()

Removes the last item from the transient mapping and returns it as a (key, value) 2-tuple.

As with dict.popitem, the last item is the one most recently inserted. Raises KeyError if the transient mapping is empty.

ready_all()

Computes all lazy values, then returns the dict.

setdefault(key, default=None)

Insert key with a value of default if key is not in the dictionary.

Return the value for the key if key is in the dictionary, else default.

update(*args, **kw)

Updates the transient mapping with items from the arguments and options.

Multiple arguments may be provided, but they must each be either a mapping or an iterable of items.

values()

Returns a view of the values, with lazy values computed.

Backend information

pcollections.using_c_extension

True if the C implementation is in use, and False if the pure-Python implementation is.

pcollections.backend_error

The exception that prevented the C implementation from loading, or None.

Abstract base classes

Abstract base classes for persistent and transient collections for Python.

Utilities

Utility functions for persistent and transient collections.