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)[source]¶
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.
Example
>>> OrderedSet([1, 1, 2, 3, 2]) OrderedSet([1, 2, 3])
- copy()[source]¶
Return a shallow copy of this object.
Example
>>> this = OrderedSet([1, 2, 3]) >>> other = this.copy() >>> this == other True >>> this is other False
- add(key)[source]¶
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.
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.
Example
>>> oset = OrderedSet() >>> oset.append(3) 0 >>> print(oset) OrderedSet([3])
- update(sequence)[source]¶
Update the set with the given iterable sequence, then return the index of the last element inserted.
Example
>>> oset = OrderedSet([1, 2, 3]) >>> oset.update([3, 1, 5, 1, 4]) 4 >>> print(oset) OrderedSet([1, 2, 3, 5, 4])
- index(key)[source]¶
Get the index of a given entry, raising an IndexError if it’s not present.
key can be an iterable of entries that is not a string, in which case this returns a list of indices.
Example
>>> oset = OrderedSet([1, 2, 3]) >>> oset.index(2) 1
- get_loc(key)¶
Get the index of a given entry, raising an IndexError if it’s not present.
key can be an iterable of entries that is not a string, in which case this returns a list of indices.
Example
>>> oset = OrderedSet([1, 2, 3]) >>> oset.index(2) 1
- get_indexer(key)¶
Get the index of a given entry, raising an IndexError if it’s not present.
key can be an iterable of entries that is not a string, in which case this returns a list of indices.
Example
>>> oset = OrderedSet([1, 2, 3]) >>> oset.index(2) 1
- pop()[source]¶
Remove and return the last element from the set.
Raises KeyError if the set is empty.
Example
>>> oset = OrderedSet([1, 2, 3]) >>> oset.pop() 3
- discard(key)[source]¶
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.
Example
>>> oset = OrderedSet([1, 2, 3]) >>> oset.discard(2) >>> print(oset) OrderedSet([1, 3]) >>> oset.discard(2) >>> print(oset) OrderedSet([1, 3])
- union(*sets)[source]¶
Combines all unique items. Each items order is defined by its first appearance.
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)[source]¶
Returns elements in common between all sets. Order is defined only by the first set.
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)[source]¶
Returns all elements that are in this set but not the others.
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)[source]¶
Report whether another set contains this set.
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)[source]¶
Report whether this set contains another set.
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)[source]¶
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.
Example
>>> this = OrderedSet([1, 4, 3, 5, 7]) >>> other = OrderedSet([9, 7, 1, 3, 2]) >>> this.symmetric_difference(other) OrderedSet([4, 5, 9, 2])
- difference_update(*sets)[source]¶
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)[source]¶
Update this OrderedSet to keep only items in another set, preserving their order in this set.
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)[source]¶
Update this OrderedSet to remove items from another set, then add items from the other set that were not present in this set.
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])
- ubelt.orderedset.oset¶
alias of
OrderedSet