A set object is an unordered collection of immutable values. They are of two types: set and frozenset. Some common uses include membership testing, removing duplicates from a sequence, and computing mathematical operations such as intersection, union, difference, and symmetric difference.
Like other collections, set objects support x in set, len(set), and for x in set. Being an unordered collection, sets do not record element position or order of insertion. They also do not support indexing, slicing, or other sequence-like behavior.
Of the two built-in set types, the type set are able to be changed by using methods like add() and remove(). Since it is mutable, set objects have no hash value and cannot be used as either a dictionary key or as an element of another set. As a complement to set functionality, the frozenset type is immutable and hashable; the values of the set cannot be altered after being created/initiated. It can, however, be used as a dictionary key or as an element of another set.
Instances of set and frozenset allow the following functionality:
- len(s): returns the length of set s
- c in s: test for membership of c in s
- c not in s: test for non-membership of c in s
- s.issubset(t) : test whether every element in s can be found in t (Equivalent to: s <= t)
- s.issuperset(t): test whether every element in t is found in s (Equivalent to: s >= t)
- s.union(t): create a new set that incorporates all elements from both s and t (Equivalent to: s | t )
- s.intersection(t): create a new set from the elements held in common between s and t (Equivalent to: s & t)
- s.difference(t): create a new set from the elements that are in s but not in t (Equivalent to: s - t)
- s.symmetric_difference(t): create a new set from the elements peculiar to s or t; this is the logical opposite of s.union(t) (Equivalent to : s ^ t)
- s.copy(): create a new set from a shallow copy of s
It is worth noting that the non-operator versions of union(), intersection(), difference(), and symmetric_difference(), issubset(), and issuperset() methods 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').
Both set and frozenset support set-to-set comparisons. Two sets are 'equal' if and only if every element of each set is contained in the other (i.e., 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 (i.e., it 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 (i.e., it is a superset but is not equal).
Instances of set are compared to instances of frozenset based on their members. For example, set('abc') == frozenset('abc') returns True.
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.
Set elements are like dictionary keys; they need to define both __hash__ and __eq__ methods.
Binary operations that mix set instances with frozenset return the type of the first operand. For example: frozenset('ab') | set('bc') returns an instance of frozenset.
The following table lists operations available for set that do not apply to immutable instances of frozenset:
- s.update(t): update set s, adding elements from t (Equivalent to: s |= t)
- s.intersection_update(t): update set s, keeping only elements found in both s and t (Equivalent to: s &= t)
- s.difference_update(t): update set s, removing elements found in t (Equivalent to: s -= t)
- s.symmetric_difference_update(t): update set s, keeping only elements found in either s or t but not in both (Equivalent to: s ^= t)
- s.add(c): add element c to set s
- s.remove(c): remove c from set s; raises KeyError if not present
- s.discard(c): removes c from set s if present
- s.pop(): remove and return an arbitrary element from s; raises KeyError if empty
- s.clear(): remove all elements from set s
