Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 584cb19

Browse files
rhettingerrhettinger
committed
Load docs for sets.py
1 parent e399d08 commit 584cb19

2 files changed

Lines changed: 220 additions & 0 deletions

File tree

‎Doc/lib/lib.tex‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,7 @@ \chapter*{Front Matter\label{front}}
122122
\input{libbisect}
123123
\input{libheapq}
124124
\input{libarray}
125+
\input{libsets}
125126
\input{libcfgparser}
126127
\input{libfileinput}
127128
\input{libxreadlines}

‎Doc/lib/libsets.tex‎

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
\section{\module{sets} ---
2+
Unordered collections of unique elements}
3+
4+
\declaremodule{standard}{sets}
5+
\modulesynopsis{Implementation of sets of unique elements.}
6+
\moduleauthor{Greg V. Wilson}{[email protected]}
7+
\moduleauthor{Alex Martelli}{[email protected]}
8+
\moduleauthor{Guido van Rossum}{[email protected]}
9+
\sectionauthor{Raymond D. Hettinger}{[email protected]}
10+
11+
\versionadded{2.3}
12+
13+
The \module{sets} module provides classes for constructing and manipulating
14+
unordered collections of unique elements. Common uses include membership
15+
testing, removing duplicates from a sequence, and computing standard math
16+
operations on sets such as intersection, union, difference, and symmetric
17+
difference.
18+
19+
Like other collections, sets support \code{x in s}, \code{len(s)}, and
20+
\code{for x in s}. Being an unordered collection, sets do not record element
21+
position or order of insertion. Accordingly, sets do not support indexing,
22+
slicing or other sequence-like behavior.
23+
24+
Most set applications use the \class{Set} class which provides every set
25+
method except for \method{__hash__()}. For advanced applications requiring
26+
a hash method, the \class{ImmutableSet} class adds a \method{__hash__()}
27+
method but omits methods which alter the contents of the set. Both
28+
\class{Set} and \class{ImmutableSet} derive from \class{BaseSet}, an
29+
abstract class useful for determining whether something is a set:
30+
\code{isinstance(x, BaseSet)}.
31+
32+
The set classes are implemented using dictionaries. As a result, sets cannot
33+
contain mutable elements such as lists or dictionaries. However, they can
34+
contain immutable collections such as tuples or instances of
35+
\class(ImmutableSet). For convenience in implementing sets of sets,
36+
inner sets are automatically converted to immutable form, for example,
37+
\code{Set([Set(['dog'])])} is transformed to
38+
\code{Set([ImmutableSet(['dog'])])}.
39+
40+
\begin{classdesc}{Set}{\optional{iterable}}
41+
Constructs a new empty \class{Set} object. If the optional \var{iterable}
42+
parameter is supplied, updates the set with elements obtained from iteration.
43+
All of the elements in \var{iterable} should be immutable or be transformable
44+
to an immutable using the protocol described at \ref{immutable-transforms}.
45+
\end{classdesc}
46+
47+
\begin{classdesc}{ImmutableSet}{\optional{iterable}}
48+
Constructs a new empty \class{ImmutableSet} object. If the optional
49+
\var{iterable} parameter is supplied, updates the set with elements obtained
50+
from iteration. All of the elements in \var{iterable} should be immutable or
51+
be transformable to an immutable using the protocol described at
52+
\ref{immutable-transforms}.
53+
54+
Because \class{ImmutableSet} objects provide a \method{__hash__()} method,
55+
they can be used as set elements or as dictionary keys. \class{ImmutableSet}
56+
objects do not have methods for adding or removing elements, so all of the
57+
elements must be known when the constructor is called.
58+
\end{classdesc}
59+
60+
61+
\subsection{set Objects}
62+
63+
Instances of \class{Set} and \class{ImmutableSet} both provide
64+
the following operations:
65+
66+
\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
67+
\lineiii{len(\var{s})}{cardinality of set \var{s}}{}
68+
69+
\hline
70+
\lineiii{\var{x} in \var{s}}
71+
{test \var{x} for membership in \var{s}}{}
72+
\lineiii{\var{x} not in \var{s}}
73+
{test \var{x} for non-membership in \var{s}}{}
74+
\lineiii{\var{s}.issubset(\var{t})}
75+
{test whether every element in \var{s} is in \var{t}}{}
76+
\lineiii{\var{s}.issuperset(\var{t})}
77+
{test whether every element in \var{t} is in \var{s}}{}
78+
79+
\hline
80+
\lineiii{\var{s} | \var{t}}
81+
{new set with elements from both \var{s} and \var{t}}{}
82+
\lineiii{\var{s}.union(\var{t})}
83+
{new set with elements from both \var{s} and \var{t}}{}
84+
\lineiii{\var{s} & \var{t}}
85+
{new set with elements common to \var{s} and \var{t}}{}
86+
\lineiii{\var{s}.intersection(\var{t})}
87+
{new set with elements common to \var{s} and \var{t}}{}
88+
\lineiii{\var{s} - \var{t}}
89+
{new set with elements in \var{s} but not in \var{t}}{}
90+
\lineiii{\var{s}.difference(\var{t})}
91+
{new set with elements in \var{s} but not in \var{t}}{}
92+
\lineiii{\var{s} ^ \var{t}}
93+
{new set with elements in either \var{s} or \var{t} but not both}{}
94+
\lineiii{\var{s}.symmetric_difference(\var{t})}
95+
{new set with elements in either \var{s} or \var{t} but not both}{}
96+
\lineiii{\var{s}.copy()}
97+
{new set with a shallow copy of \var{s}}{}
98+
\end{tableiii}
99+
100+
In addition to the above operations, both \class{Set} and \class{ImmutableSet}
101+
support set to set comparison operators based on the contents of their
102+
internal dictionaries. Two sets are equal if and only if every element of
103+
each set is contained in the other.
104+
105+
The following table lists operations available in \class{ImmutableSet}
106+
but not found in \class{Set}:
107+
108+
\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
109+
\lineiii{hash(\var{s})}{returns a hash value for \var{s}}{}
110+
\end{tableiii}
111+
112+
The following table lists operations available in \class{Set}
113+
but not found in \class{ImmutableSet}:
114+
115+
\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
116+
\lineiii{\var{s} |= \var{t}}
117+
{return set \var{s} with elements added from \var{t}}{}
118+
\lineiii{\var{s}.union_update(\var{t})}
119+
{return set \var{s} with elements added from \var{t}}{}
120+
\lineiii{\var{s} &= \var{t}}
121+
{return set \var{s} keeping only elements also found in \var{t}}{}
122+
\lineiii{\var{s}.intersection_update(\var{t})}
123+
{return set \var{s} keeping only elements also found in \var{t}}{}
124+
\lineiii{\var{s} -= \var{t}}
125+
{return set \var{s} after removing elements found in \var{t}}{}
126+
\lineiii{\var{s}.difference_update(\var{t})}
127+
{return set \var{s} after removing elements found in \var{t}}{}
128+
\lineiii{\var{s} ^= \var{t}}
129+
{return set \var{s} with elements from \var{s} or \var{t} but not both}{}
130+
\lineiii{\var{s}.symmetric_difference_update(\var{t})}
131+
{return set \var{s} with elements from \var{s} or \var{t} but not both}{}
132+
133+
\hline
134+
\lineiii{\var{s}.add(\var{x})}
135+
{Add element \var{x} to set \var{s}}{}
136+
\lineiii{\var{s}.remove(\var{x})}
137+
{Remove element \var{x} from set \var{s}}{}
138+
\lineiii{\var{s}.discard(\var{x})}
139+
{Removes element \var{x} from set \var{s} like \var{s}.remove(\var{x})
140+
but does not raise a KeyError if \var{x} is not in \var{s}}{}
141+
\lineiii{\var{s}.pop()}
142+
{Remove and return a randomly-chosen element from \var{s}}{}
143+
\lineiii{\var{s}.update(\var{t})}
144+
{Add elements from \var{t} to set \var{s}}{}
145+
\lineiii{\var{s}.clear()}
146+
{Remove all elements from set \var{s}}{}
147+
\end{tableiii}
148+
149+
150+
\subsection{Example}
151+
152+
\begin{verbatim}
153+
>>> from sets import Set
154+
>>> engineers = Set(['John', 'Jane', 'Jack', 'Janice'])
155+
>>> programmers = Set(['Jack', 'Sam', 'Susan', 'Janice'])
156+
>>> management = Set(['Jane', 'Jack', 'Susan', 'Zack'])
157+
>>> employees = engineers | programmers | management # union
158+
>>> engineering_management = engineers & programmers # intersection
159+
>>> fulltime_management = management - engineers - programmers # difference
160+
>>> engineers.add('Marvin') # add element
161+
>>> print engineers
162+
Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])
163+
>>> employees.issuperset(engineers) # superset test
164+
False
165+
>>> employees.update(engineers) # update from another set
166+
>>> employees.issuperset(engineers)
167+
True
168+
>>> for group in [engineers, programmers, management, employees]:
169+
group.discard('Susan') # unconditionally remove element
170+
print group
171+
172+
Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])
173+
Set(['Janice', 'Jack', 'Sam'])
174+
Set(['Jane', 'Zack', 'Jack'])
175+
Set(['Jack', 'Sam', 'Jane', 'Marvin', 'Janice', 'John', 'Zack'])
176+
\end{verbatim}
177+
178+
179+
\subsection{Protocol for automatic conversion to immutable
180+
\label{immutable-transforms}}
181+
182+
Sets can only contain immutable elements. For convenience, mutable
183+
\class{Set} objects are automatically copied to an \class{ImmutableSet}
184+
before being added as a set element.
185+
186+
The mechanism is to always add a hashable element, or if it is not hashable,
187+
the element is checked to see if it has an \method{_as_immutable()} method
188+
which returns an immutable equivalent.
189+
190+
Since \class{Set} objects have a \method{_as_immutable()} method
191+
returning an instance of \class{ImmutableSet}, it is possible to
192+
construct sets of sets.
193+
194+
A similar mechanism is needed by the \method{__contains__()} and
195+
\method{remove()} methods which need to hash an element to check
196+
for membership in a set. Those methods check an element for hashability
197+
and, if not, check for a \method{_as_Temporarily_Immutable} method
198+
which returns the element wrapped by a class that provides temporary
199+
methods for \method{__hash__()}, \method{__eq__()}, and \method{__ne__()}.
200+
201+
The alternate mechanism spares the need to build a separate copy of
202+
the original mutable object.
203+
204+
\class{Set} objects implement the \method{_as_Temporarily_Immutable} method
205+
which returns the \class{Set} object wrapped by a new class
206+
\class{_TemporarilyImmutableSet}.
207+
208+
The two mechanisms for adding hashability are normally invisible to the
209+
user; however, a conflict can arise in a multi-threaded environment
210+
where one thread is updating a Set while another has temporarily wrapped it
211+
in \class{_TemporarilyImmutableSet}. In other words, sets of mutable sets
212+
are not thread-safe.
213+
214+
215+
216+
217+
218+
219+

0 commit comments

Comments
 (0)