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.

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
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
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.

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.

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.