New in version 2.3.

Deprecated since version 2.6: The built-in set/frozenset types replace this module.

8.7.1. Set Objects¶

Instances of Set and ImmutableSet both provide the following operations:

Note, the non-operator versions of union(), intersection(), difference(), and symmetric_difference() will accept any iterable as an argument. In contrast, their operator based counterparts require their arguments to be sets. This precludes error-prone constructions like Set('abc') & 'cbs' in favor of the more readable Set('abc').intersection('cbs').

In addition, both Set and ImmutableSet support set to set comparisons. Two sets are equal if and only if every element of each set is contained in the other (each is a subset of the other). A set is less than another set if and only if the first set is a proper subset of the second set (is a subset, but is not equal). A set is greater than another set if and only if the first set is a proper superset of the second set (is a superset, but is not equal).

The subset and equality comparisons do not generalize to a complete ordering function. For example, any two disjoint sets are not equal and are not subsets of each other, so all of the following return False: a<b, a==b, or a>b. Accordingly, sets do not implement the __cmp__() method.

Since sets only define partial ordering (subset relationships), the output of the list.sort() method is undefined for lists of sets.

The following table lists operations available in ImmutableSet but not found in Set:

The following table lists operations available in Set but not found in ImmutableSet:

Note, the non-operator versions of update(), intersection_update(), difference_update(), and symmetric_difference_update() will accept any iterable as an argument.

Also note, the module also includes a union_update() method which is an alias for update(). The method is included for backwards compatibility. Programmers should prefer the update() method because it is supported by the built-in set() and frozenset() types.

8.7.2. Example¶

>>> 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
>>> print engineers 
Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])
>>> employees.issuperset(engineers)     # superset test
False
>>> employees.update(engineers)         # update from another set
>>> employees.issuperset(engineers)
True
>>> for group in [engineers, programmers, managers, employees]: 
...     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'])

8.7.3. Protocol for automatic conversion to immutable¶

Sets can only contain immutable elements. For convenience, mutable Set objects are automatically copied to an ImmutableSet before being added as a set element.

The mechanism is to always add a hashable element, or if it is not hashable, the element is checked to see if it has an __as_immutable__() method which returns an immutable equivalent.

Since Set objects have a __as_immutable__() method returning an instance of ImmutableSet, it is possible to construct sets of sets.

A similar mechanism is needed by the __contains__() and 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 __as_temporarily_immutable__() method which returns the element wrapped by a class that provides temporary methods for __hash__(), __eq__(), and __ne__().

The alternate mechanism spares the need to build a separate copy of the original mutable object.

Set objects implement the __as_temporarily_immutable__() method which returns the Set object wrapped by a new class _TemporarilyImmutableSet.

The two mechanisms for adding hashability are normally invisible to the user; however, a conflict can arise in a multi-threaded environment where one thread is updating a set while another has temporarily wrapped it in _TemporarilyImmutableSet. In other words, sets of mutable sets are not thread-safe.

8.7.4. Comparison to the built-in set types¶

The built-in set and frozenset types were designed based on lessons learned from the sets module. The key differences are:

• Set and ImmutableSet were renamed to set and frozenset.

• There is no equivalent to BaseSet. Instead, use isinstance(x, (set, frozenset)).

• 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 union_update() method. Instead, use the update() method which is equivalent.

• The built-in versions do not have a _repr(sorted=True) method. Instead, use the built-in repr() and 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.