ubelt.orderedset module

This module exposes the OrderedSet class, which is a collection of unique items that maintains the order in which the items were added. An OrderedSet (or its alias oset) behaves very similarly to Python’s builtin set object, the main difference being that an OrderedSet can efficiently lookup its items by index.

Example

>>> import ubelt as ub
>>> ub.oset([1, 2, 3])
OrderedSet([1, 2, 3])
>>> (ub.oset([1, 2, 3]) - {2}) | {2}
OrderedSet([1, 3, 2])
>>> [ub.oset([1, 2, 3])[i] for i in [1, 0, 2]]
[2, 1, 3]

As of version (0.8.5), ubelt contains its own internal copy of OrderedSet in order to reduce external dependencies. The original standalone implementation lives in https://github.com/LuminosoInsight/ordered-set.

The original documentation is as follows:

An OrderedSet is a custom MutableSet that remembers its order, so that every entry has an index that can be looked up.

Based on a recipe originally posted to ActiveState Recipes by Raymond Hettiger, and released under the MIT license.

class ubelt.orderedset.OrderedSet(iterable=None)

Bases: MutableSet, Sequence

An OrderedSet is a custom MutableSet that remembers its order, so that every entry has an index that can be looked up.

Variables:

• items (List[Any]) – internal ordered representation.

• map (Dict[Any, int]) – internal mapping from items to indices.

Example

>>> OrderedSet([1, 1, 2, 3, 2])
OrderedSet([1, 2, 3])

Parameters:

iterable (None | Iterable) – input data

copy()

Return a shallow copy of this object.

Returns:

OrderedSet

Example

>>> this = OrderedSet([1, 2, 3])
>>> other = this.copy()
>>> this == other
True
>>> this is other
False

add(key)

Add key as an item to this OrderedSet, then return its index.

If key is already in the OrderedSet, return the index it already had.

Parameters:

key (Any) – the item to add

Returns:

the index of the items. Note, violates the Liskov Substitution Principle and might be changed.

Return type:

int

Example

>>> oset = OrderedSet()
>>> oset.append(3)
0
>>> print(oset)
OrderedSet([3])

append(key)

Add key as an item to this OrderedSet, then return its index.

If key is already in the OrderedSet, return the index it already had.

Parameters:

key (Any) – the item to add

Returns:

the index of the items. Note, violates the Liskov Substitution Principle and might be changed.

Return type:

int

Example

>>> oset = OrderedSet()
>>> oset.append(3)
0
>>> print(oset)
OrderedSet([3])

update(sequence)

Update the set with the given iterable sequence, then return the index of the last element inserted.

Parameters:

sequence (Iterable) – items to add to this set

Example

>>> oset = OrderedSet([1, 2, 3])
>>> oset.update([3, 1, 5, 1, 4])
4
>>> print(oset)
OrderedSet([1, 2, 3, 5, 4])

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

Get the index of a given entry, raising an IndexError if it’s not present.

key can be a non-string iterable of entries, in which case this returns a list of indices.

Parameters:

• key (Any) – item to find the position of

• start (int) – not supported yet

• stop (int | None) – not supported yet

Returns:

int

Example

>>> oset = OrderedSet([1, 2, 3])
>>> oset.index(2)
1

get_loc(key, start=0, stop=None)

Get the index of a given entry, raising an IndexError if it’s not present.

key can be a non-string iterable of entries, in which case this returns a list of indices.

Parameters:

• key (Any) – item to find the position of

• start (int) – not supported yet

• stop (int | None) – not supported yet

Returns:

int

Example

>>> oset = OrderedSet([1, 2, 3])
>>> oset.index(2)
1

get_indexer(key, start=0, stop=None)

Get the index of a given entry, raising an IndexError if it’s not present.

key can be a non-string iterable of entries, in which case this returns a list of indices.

Parameters:

• key (Any) – item to find the position of

• start (int) – not supported yet

• stop (int | None) – not supported yet

Returns:

int

Example

>>> oset = OrderedSet([1, 2, 3])
>>> oset.index(2)
1

pop()

Remove and return the last element from the set.

Raises KeyError if the set is empty.

Returns:

Any

Example

>>> oset = OrderedSet([1, 2, 3])
>>> oset.pop()
3

discard(key)

Remove an element. Do not raise an exception if absent.

The MutableSet mixin uses this to implement the .remove() method, which does raise an error when asked to remove a non-existent item.

Parameters:

key (Any) – item to remove.

Example

>>> oset = OrderedSet([1, 2, 3])
>>> oset.discard(2)
>>> print(oset)
OrderedSet([1, 3])
>>> oset.discard(2)
>>> print(oset)
OrderedSet([1, 3])

clear()

Remove all items from this OrderedSet.

union(*sets)

Combines all unique items. Each items order is defined by its first appearance.

Parameters:

*sets – zero or more other iterables to operate on

Returns:

OrderedSet

Example

>>> oset = OrderedSet.union(OrderedSet([3, 1, 4, 1, 5]), [1, 3], [2, 0])
>>> print(oset)
OrderedSet([3, 1, 4, 5, 2, 0])
>>> oset.union([8, 9])
OrderedSet([3, 1, 4, 5, 2, 0, 8, 9])
>>> oset | {10}
OrderedSet([3, 1, 4, 5, 2, 0, 10])

intersection(*sets)

Returns elements in common between all sets. Order is defined only by the first set.

Parameters:

*sets – zero or more other iterables to operate on

Returns:

OrderedSet

Example

>>> from ubelt.orderedset import *  # NOQA
>>> oset = OrderedSet.intersection(OrderedSet([0, 1, 2, 3]), [1, 2, 3])
>>> print(oset)
OrderedSet([1, 2, 3])
>>> oset.intersection([2, 4, 5], [1, 2, 3, 4])
OrderedSet([2])
>>> oset.intersection()
OrderedSet([1, 2, 3])

difference(*sets)

Returns all elements that are in this set but not the others.

Parameters:

*sets – zero or more other iterables to operate on

Returns:

OrderedSet

Example

>>> OrderedSet([1, 2, 3]).difference(OrderedSet([2]))
OrderedSet([1, 3])
>>> OrderedSet([1, 2, 3]).difference(OrderedSet([2]), OrderedSet([3]))
OrderedSet([1])
>>> OrderedSet([1, 2, 3]) - OrderedSet([2])
OrderedSet([1, 3])
>>> OrderedSet([1, 2, 3]).difference()
OrderedSet([1, 2, 3])

issubset(other)

Report whether another set contains this set.

Parameters:

other (Iterable) – check if items in other are all contained in self.

Returns:

bool

Example

>>> OrderedSet([1, 2, 3]).issubset({1, 2})
False
>>> OrderedSet([1, 2, 3]).issubset({1, 2, 3, 4})
True
>>> OrderedSet([1, 2, 3]).issubset({1, 4, 3, 5})
False

issuperset(other)

Report whether this set contains another set.

Parameters:

other (Iterable) – check all items in self are contained in other.

Returns:

bool

Example

>>> OrderedSet([1, 2]).issuperset([1, 2, 3])
False
>>> OrderedSet([1, 2, 3, 4]).issuperset({1, 2, 3})
True
>>> OrderedSet([1, 4, 3, 5]).issuperset({1, 2, 3})
False

symmetric_difference(other)

Return the symmetric difference of two OrderedSets as a new set. That is, the new set will contain all elements that are in exactly one of the sets.

Their order will be preserved, with elements from self preceding elements from other.

Parameters:

other (Iterable) – items to operate on

Returns:

OrderedSet

Example

>>> this = OrderedSet([1, 4, 3, 5, 7])
>>> other = OrderedSet([9, 7, 1, 3, 2])
>>> this.symmetric_difference(other)
OrderedSet([4, 5, 9, 2])

_update_items(items)

Replace the ‘items’ list of this OrderedSet with a new one, updating self.map accordingly.

difference_update(*sets)

Update this OrderedSet to remove items from one or more other sets.

Example

>>> this = OrderedSet([1, 2, 3])
>>> this.difference_update(OrderedSet([2, 4]))
>>> print(this)
OrderedSet([1, 3])

>>> this = OrderedSet([1, 2, 3, 4, 5])
>>> this.difference_update(OrderedSet([2, 4]), OrderedSet([1, 4, 6]))
>>> print(this)
OrderedSet([3, 5])

intersection_update(other)

Update this OrderedSet to keep only items in another set, preserving their order in this set.

Parameters:

other (Iterable) – items to operate on

Example

>>> this = OrderedSet([1, 4, 3, 5, 7])
>>> other = OrderedSet([9, 7, 1, 3, 2])
>>> this.intersection_update(other)
>>> print(this)
OrderedSet([1, 3, 7])

symmetric_difference_update(other)

Update this OrderedSet to remove items from another set, then add items from the other set that were not present in this set.

Parameters:

other (Iterable) – items to operate on

Example

>>> this = OrderedSet([1, 4, 3, 5, 7])
>>> other = OrderedSet([9, 7, 1, 3, 2])
>>> this.symmetric_difference_update(other)
>>> print(this)
OrderedSet([4, 5, 9, 2])

_abc_impl = <_abc._abc_data object>

ubelt.orderedset.oset

alias of OrderedSet