f | |
| :mod:`sets` --- Unordered collections of unique elements |
| ======================================================== |
| |
| .. module:: sets |
| :synopsis: Implementation of sets of unique elements. |
n | :deprecated: |
| .. moduleauthor:: Greg V. Wilson <gvwilson@nevex.com> |
| .. moduleauthor:: Alex Martelli <aleax@aleax.it> |
| .. moduleauthor:: Guido van Rossum <guido@python.org> |
| .. sectionauthor:: Raymond D. Hettinger <python@rcn.com> |
| |
| |
| .. versionadded:: 2.3 |
n | |
| .. deprecated:: 2.6 |
| The built-in ``set``/``frozenset`` types replace this module. |
| |
| The :mod:`sets` module provides classes for constructing and manipulating |
| unordered collections of unique elements. Common uses include membership |
| testing, removing duplicates from a sequence, and computing standard math |
| operations on sets such as intersection, union, difference, and symmetric |
| difference. |
| |
| Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in |
| | | | *s* | |
| +-------------------------------+------------+---------------------------------+ |
| | ``s.issubset(t)`` | ``s <= t`` | test whether every element in | |
| | | | *s* is in *t* | |
| +-------------------------------+------------+---------------------------------+ |
| | ``s.issuperset(t)`` | ``s >= t`` | test whether every element in | |
| | | | *t* is in *s* | |
| +-------------------------------+------------+---------------------------------+ |
n | | ``s.union(t)`` | *s* \| *t* | new set with elements from both | |
n | | ``s.union(t)`` | ``s | t`` | new set with elements from both | |
| | | | *s* and *t* | |
| +-------------------------------+------------+---------------------------------+ |
n | | ``s.intersection(t)`` | *s* & *t* | new set with elements common to | |
n | | ``s.intersection(t)`` | ``s & t`` | new set with elements common to | |
| | | | *s* and *t* | |
| +-------------------------------+------------+---------------------------------+ |
n | | ``s.difference(t)`` | *s* - *t* | new set with elements in *s* | |
n | | ``s.difference(t)`` | ``s - t`` | new set with elements in *s* | |
| | | | but not in *t* | |
| +-------------------------------+------------+---------------------------------+ |
n | | ``s.symmetric_difference(t)`` | *s* ^ *t* | new set with elements in either | |
n | | ``s.symmetric_difference(t)`` | ``s ^ t`` | new set with elements in either | |
| | | | *s* or *t* but not both | |
| +-------------------------------+------------+---------------------------------+ |
| | ``s.copy()`` | | new set with a shallow copy of | |
| | | | *s* | |
| +-------------------------------+------------+---------------------------------+ |
| |
| Note, the non-operator versions of :meth:`union`, :meth:`intersection`, |
| :meth:`difference`, and :meth:`symmetric_difference` will accept any iterable as |
| Programmers should prefer the :meth:`update` method because it is supported by |
| the builtin :class:`set()` and :class:`frozenset()` types. |
| |
| |
| .. _set-example: |
| |
| Example |
| ------- |
n | |
| :: |
| |
| >>> from sets import Set |
| >>> engineers = Set(['John', 'Jane', 'Jack', 'Janice']) |
| >>> programmers = Set(['Jack', 'Sam', 'Susan', 'Janice']) |
| >>> managers = Set(['Jane', 'Jack', 'Susan', 'Zack']) |
| >>> employees = engineers | programmers | managers # union |
| >>> engineering_management = engineers & managers # intersection |
| >>> fulltime_management = managers - engineers - programmers # difference |
| >>> engineers.add('Marvin') # add element |
n | >>> print engineers |
n | >>> print engineers # doctest: +SKIP |
| Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack']) |
n | >>> employees.issuperset(engineers) # superset test |
n | >>> employees.issuperset(engineers) # superset test |
| False |
n | >>> employees.union_update(engineers) # update from another set |
n | >>> employees.update(engineers) # update from another set |
| >>> employees.issuperset(engineers) |
| True |
n | >>> for group in [engineers, programmers, managers, employees]: |
n | >>> for group in [engineers, programmers, managers, employees]: # doctest: +SKIP |
| ... group.discard('Susan') # unconditionally remove element |
| ... group.discard('Susan') # unconditionally remove element |
| ... print group |
| ... |
| Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack']) |
| Set(['Janice', 'Jack', 'Sam']) |
| Set(['Jane', 'Zack', 'Jack']) |
| Set(['Jack', 'Sam', 'Jane', 'Marvin', 'Janice', 'John', 'Zack']) |
| |
| |
| |
| Protocol for automatic conversion to immutable |
| ---------------------------------------------- |
| |
| Sets can only contain immutable elements. For convenience, mutable :class:`Set` |
| objects are automatically copied to an :class:`ImmutableSet` before being added |
| as a set element. |
| |
n | The mechanism is to always add a hashable element, or if it is not hashable, the |
n | The mechanism is to always add a :term:`hashable` element, or if it is not |
| element is checked to see if it has an :meth:`__as_immutable__` method which |
| hashable, the element is checked to see if it has an :meth:`__as_immutable__` |
| returns an immutable equivalent. |
| method which returns an immutable equivalent. |
| |
| Since :class:`Set` objects have a :meth:`__as_immutable__` method returning an |
| instance of :class:`ImmutableSet`, it is possible to construct sets of sets. |
| |
| A similar mechanism is needed by the :meth:`__contains__` and :meth:`remove` |
| methods which need to hash an element to check for membership in a set. Those |
| methods check an element for hashability and, if not, check for a |
| :meth:`__as_temporarily_immutable__` method which returns the element wrapped by |
| * The hash algorithm for the built-ins performs significantly better (fewer |
| collisions) for most datasets. |
| |
| * The built-in versions have more space efficient pickles. |
| |
| * The built-in versions do not have a :meth:`union_update` method. Instead, use |
| the :meth:`update` method which is equivalent. |
| |
t | * The built-in versions do not have a :meth:`_repr(sorted=True)` method. |
t | * The built-in versions do not have a ``_repr(sorted=True)`` method. |
| Instead, use the built-in :func:`repr` and :func:`sorted` functions: |
| ``repr(sorted(s))``. |
| |
| * The built-in version does not have a protocol for automatic conversion to |
| immutable. Many found this feature to be confusing and no one in the community |
| reported having found real uses for it. |
| |