api

Module contents

collections_extended contains a few extra basic data structures.

collections_extended.collection(iterable=None, mutable=True, ordered=False, unique=False)[source]

Return a Collection with the specified properties.

Parameters:
  • iterable (Iterable) – collection to instantiate new collection from.
  • mutable (bool) – Whether or not the new collection is mutable.
  • ordered (bool) – Whether or not the new collection is ordered.
  • unique (bool) – Whether or not the new collection contains only unique values.
class collections_extended.setlist(iterable=None, raise_on_duplicate=False)[source]

Bases: collections_extended.setlists._basesetlist, collections.abc.MutableSequence, collections.abc.MutableSet

A mutable (unhashable) setlist.

add(item)[source]

Add an item.

Note

This does not raise a ValueError for an already present value like append does. This is to match the behavior of set.add

Parameters:item – Item to add
Raises:TypeError – If item isn’t hashable.
append(value)[source]

Append value to the end.

Parameters:

value – Value to append

Raises:
  • ValueError – If value alread in self
  • TypeError – If value isn’t hashable
clear()[source]

Remove all elements from self.

copy()
count(value)

Return the number of occurences of value in self.

This runs in O(1)

Parameters:value – The value to count
Returns:1 if the value is in the setlist, otherwise 0
Return type:int
difference(other)
difference_update(other)[source]

Update self to include only the differene with other.

discard(value)[source]

Discard an item.

Note

This does not raise a ValueError for a missing value like remove does. This is to match the behavior of set.discard

discard_all(elems_to_delete)[source]

Discard all the elements from elems_to_delete.

This is much faster than removing them one by one. This runs in O(len(self) + len(elems_to_delete))

Parameters:elems_to_delete (Iterable) – Elements to discard.
Raises:TypeError – If any of the values aren’t hashable.
extend(values)[source]

Append all values to the end.

If any of the values are present, ValueError will be raised and none of the values will be appended.

Parameters:

values (Iterable) – Values to append

Raises:
  • ValueError – If any values are already present or there are duplicates in the passed values.
  • TypeError – If any of the values aren’t hashable.
index(value, start=0, end=None)

Return the index of value between start and end.

By default, the entire setlist is searched.

This runs in O(1)

Parameters:
  • value – The value to find the index of
  • start (int) – The index to start searching at (defaults to 0)
  • end (int) – The index to stop searching at (defaults to the end of the list)
Returns:

The index of the value

Return type:

int

Raises:
  • ValueError – If the value is not in the list or outside of start - end
  • IndexError – If start or end are out of range
insert(index, value)[source]

Insert value at index.

Parameters:
  • index (int) – Index to insert value at
  • value – Value to insert
Raises:
  • ValueError – If value already in self
  • IndexError – If start or end are out of range
intersection(other)
intersection_update(other)[source]

Update self to include only the intersection with other.

isdisjoint(other)

Return True if two sets have a null intersection.

issubset(other)
issuperset(other)
pop(index=-1)[source]

Remove and return the item at index.

remove(value)[source]

Remove value from self.

Parameters:value – Element to remove from self
Raises:ValueError – if element is already present
remove_all(elems_to_delete)[source]

Remove all elements from elems_to_delete, raises ValueErrors.

See also

discard_all

Parameters:

elems_to_delete (Iterable) – Elements to remove.

Raises:
  • ValueError – If the count of any element is greater in elems_to_delete than self.
  • TypeError – If any of the values aren’t hashable.
reverse()

S.reverse() – reverse IN PLACE

shuffle(random=None)[source]

Shuffle all of the elements in self randomly.

sort(*args, **kwargs)[source]

Sort this setlist in place.

sub_index(sub, start=0, end=None)

Return the index of a subsequence.

This runs in O(len(sub))

Parameters:

sub (Sequence) – An Iterable to search for

Returns:

The index of the first element of sub

Return type:

int

Raises:
  • ValueError – If sub isn’t a subsequence
  • TypeError – If sub isn’t iterable
  • IndexError – If start or end are out of range
symmetric_difference(other)
symmetric_difference_update(other)[source]

Update self to include only the symmetric difference with other.

union(other)
update(values)[source]

Add all values to the end.

If any of the values are present, silently ignore them (as opposed to extend which raises an Error).

See also

extend

Parameters:values (Iterable) – Values to add
Raises:TypeError – If any of the values are unhashable.
class collections_extended.frozensetlist(iterable=None, raise_on_duplicate=False)[source]

Bases: collections_extended.setlists._basesetlist, collections.abc.Hashable

An immutable (hashable) setlist.

copy()
count(value)

Return the number of occurences of value in self.

This runs in O(1)

Parameters:value – The value to count
Returns:1 if the value is in the setlist, otherwise 0
Return type:int
difference(other)
index(value, start=0, end=None)

Return the index of value between start and end.

By default, the entire setlist is searched.

This runs in O(1)

Parameters:
  • value – The value to find the index of
  • start (int) – The index to start searching at (defaults to 0)
  • end (int) – The index to stop searching at (defaults to the end of the list)
Returns:

The index of the value

Return type:

int

Raises:
  • ValueError – If the value is not in the list or outside of start - end
  • IndexError – If start or end are out of range
intersection(other)
isdisjoint(other)

Return True if two sets have a null intersection.

issubset(other)
issuperset(other)
sub_index(sub, start=0, end=None)

Return the index of a subsequence.

This runs in O(len(sub))

Parameters:

sub (Sequence) – An Iterable to search for

Returns:

The index of the first element of sub

Return type:

int

Raises:
  • ValueError – If sub isn’t a subsequence
  • TypeError – If sub isn’t iterable
  • IndexError – If start or end are out of range
symmetric_difference(other)
union(other)
class collections_extended.bag(iterable=None)[source]

Bases: collections_extended.bags._basebag, collections.abc.MutableSet

bag is a mutable unhashable bag.

add(elem)[source]

Add elem to self.

clear()[source]

Remove all elements from this bag.

copy()

Create a shallow copy of self.

This runs in O(len(self.num_unique_elements()))

count(value)

Return the number of value present in this bag.

If value is not in the bag no Error is raised, instead 0 is returned.

This runs in O(1) time

Parameters:value – The element of self to get the count of
Returns:The count of value in self
Return type:int
discard(elem)[source]

Remove elem from this bag, silent if it isn’t present.

discard_all(other)[source]

Discard all of the elems from other.

classmethod from_mapping(mapping)

Create a bag from a dict of elem->count.

Each key in the dict is added if the value is > 0.

isdisjoint(other)

Return if this bag is disjoint with the passed collection.

This runs in O(len(other))

TODO move isdisjoint somewhere more appropriate

nlargest(n=None)

List the n most common elements and their counts.

List is from the most common to the least. If n is None, the list all element counts.

Run time should be O(m log m) where m is len(self) :param n: The number of elements to return :type n: int

num_unique_elements()

Return the number of unique elements.

This runs in O(1) time

pop()[source]

Remove and return an element of self.

remove(elem)[source]

Remove elem from this bag, raising a ValueError if it isn’t present.

Parameters:elem – object to remove from self
Raises:ValueError – if the elem isn’t present
remove_all(other)[source]

Remove all of the elems from other.

Raises a ValueError if the multiplicity of any elem in other is greater than in self.

unique_elements()

Return a view of unique elements in this bag.

In Python 3:
This runs in O(1) time and returns a view of the unique elements
In Python 2:
This runs in O(n) and returns set of the current elements.
class collections_extended.frozenbag(iterable=None)[source]

Bases: collections_extended.bags._basebag, collections.abc.Hashable

frozenbag is an immutable, hashable bab.

copy()

Create a shallow copy of self.

This runs in O(len(self.num_unique_elements()))

count(value)

Return the number of value present in this bag.

If value is not in the bag no Error is raised, instead 0 is returned.

This runs in O(1) time

Parameters:value – The element of self to get the count of
Returns:The count of value in self
Return type:int
classmethod from_mapping(mapping)

Create a bag from a dict of elem->count.

Each key in the dict is added if the value is > 0.

isdisjoint(other)

Return if this bag is disjoint with the passed collection.

This runs in O(len(other))

TODO move isdisjoint somewhere more appropriate

nlargest(n=None)

List the n most common elements and their counts.

List is from the most common to the least. If n is None, the list all element counts.

Run time should be O(m log m) where m is len(self) :param n: The number of elements to return :type n: int

num_unique_elements()

Return the number of unique elements.

This runs in O(1) time

unique_elements()

Return a view of unique elements in this bag.

In Python 3:
This runs in O(1) time and returns a view of the unique elements
In Python 2:
This runs in O(n) and returns set of the current elements.
class collections_extended.bijection(iterable=None, **kwarg)[source]

Bases: collections.abc.MutableMapping

A one-to-one onto mapping, a dict with unique values.

clear()[source]

Remove everything from this bijection.

copy()[source]

Return a copy of this bijection.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.
inverse

Return the inverse of this bijection.

items()[source]

See Mapping.items.

keys()[source]

See Mapping.keys.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
update([E, ]**F) → None. Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values()[source]

See Mapping.values.

class collections_extended.RangeMap(iterable=None, **kwargs)[source]

Bases: collections.abc.Mapping

Map ranges of orderable elements to values.

clear()[source]

Remove all elements.

delete(start=None, stop=None)[source]

Delete the range from start to stop from self.

Raises:KeyError – If part of the passed range isn’t mapped.
empty(start=None, stop=None)[source]

Empty the range from start to stop.

Like delete, but no Error is raised if the entire range isn’t mapped.

end

Get the stop key of the last range.

None if RangeMap is empty or unbounded to the right.

classmethod from_iterable(iterable)[source]

Create a RangeMap from an iterable of tuples defining each range.

Each element of the iterable is a tuple (start, stop, value).

classmethod from_mapping(mapping)[source]

Create a RangeMap from a mapping of interval starts to values.

get(key, restval=None)[source]

Get the value of the range containing key, otherwise return restval.

get_range(start=None, stop=None)[source]

Return a RangeMap for the range start to stop.

Returns:A RangeMap
items()[source]

Return a view of the item pairs.

keys()[source]

Return a view of the keys.

ranges(start=None, stop=None)[source]

Generate MappedRanges for all mapped ranges.

Yields:MappedRange
set(value, start=None, stop=None)[source]

Set the range from start to stop to value.

start

Get the start key of the first range.

None if RangeMap is empty or unbounded to the left.

values()[source]

Return a view of the values.

class collections_extended.MappedRange(start, stop, value)

Bases: tuple

count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

start

Alias for field number 0

stop

Alias for field number 1

value

Alias for field number 2

class collections_extended.Collection[source]

Bases: collections.abc.Sized, collections.abc.Iterable, collections.abc.Container

Backport from Python3.6.