mirror of https://github.com/python/cpython
In stdtypes.rst, move methods under class directives where applicable
This commit is contained in:
Benjamin Peterson
parent
f466c2a247
commit
54718dd691
|
|
@ -1502,161 +1502,162 @@ The constructors for both classes work the same:
|
||||||
sets, the inner sets must be :class:`frozenset` objects. If *iterable* is
|
sets, the inner sets must be :class:`frozenset` objects. If *iterable* is
|
||||||
not specified, a new empty set is returned.
|
not specified, a new empty set is returned.
|
||||||
|
|
||||||
Instances of :class:`set` and :class:`frozenset` provide the following
|
Instances of :class:`set` and :class:`frozenset` provide the following
|
||||||
operations:
|
operations:
|
||||||
|
|
||||||
.. describe:: len(s)
|
.. describe:: len(s)
|
||||||
|
|
||||||
Return the cardinality of set *s*.
|
Return the cardinality of set *s*.
|
||||||
|
|
||||||
.. describe:: x in s
|
.. describe:: x in s
|
||||||
|
|
||||||
Test *x* for membership in *s*.
|
Test *x* for membership in *s*.
|
||||||
|
|
||||||
.. describe:: x not in s
|
.. describe:: x not in s
|
||||||
|
|
||||||
Test *x* for non-membership in *s*.
|
Test *x* for non-membership in *s*.
|
||||||
|
|
||||||
.. method:: set.isdisjoint(other)
|
.. method:: isdisjoint(other)
|
||||||
|
|
||||||
Return True if the set has no elements in common with *other*.
|
Return True if the set has no elements in common with *other*. Sets are
|
||||||
Sets are disjoint if and only if their interesection is the empty set.
|
disjoint if and only if their interesection is the empty set.
|
||||||
|
|
||||||
.. versionadded:: 2.6
|
.. versionadded:: 2.6
|
||||||
|
|
||||||
.. method:: set.issubset(other)
|
.. method:: issubset(other)
|
||||||
set <= other
|
set <= other
|
||||||
|
|
||||||
Test whether every element in the set is in *other*.
|
Test whether every element in the set is in *other*.
|
||||||
|
|
||||||
.. method:: set < other
|
.. method:: set < other
|
||||||
|
|
||||||
Test whether the set is a true subset of *other*, that is,
|
Test whether the set is a true subset of *other*, that is,
|
||||||
``set <= other and set != other``.
|
``set <= other and set != other``.
|
||||||
|
|
||||||
.. method:: set.issuperset(other)
|
.. method:: issuperset(other)
|
||||||
set >= other
|
set >= other
|
||||||
|
|
||||||
Test whether every element in *other* is in the set.
|
Test whether every element in *other* is in the set.
|
||||||
|
|
||||||
.. method:: set > other
|
.. method:: set > other
|
||||||
|
|
||||||
Test whether the set is a true superset of *other*, that is,
|
Test whether the set is a true superset of *other*, that is, ``set >=
|
||||||
``set >= other and set != other``.
|
other and set != other``.
|
||||||
|
|
||||||
.. method:: set.union(other)
|
.. method:: union(other)
|
||||||
set | other
|
set | other
|
||||||
|
|
||||||
Return a new set with elements from both sets.
|
Return a new set with elements from both sets.
|
||||||
|
|
||||||
.. method:: set.intersection(other)
|
.. method:: intersection(other)
|
||||||
set & other
|
set & other
|
||||||
|
|
||||||
Return a new set with elements common to both sets.
|
Return a new set with elements common to both sets.
|
||||||
|
|
||||||
.. method:: set.difference(other)
|
.. method:: difference(other)
|
||||||
set - other
|
set - other
|
||||||
|
|
||||||
Return a new set with elements in the set that are not in *other*.
|
Return a new set with elements in the set that are not in *other*.
|
||||||
|
|
||||||
.. method:: set.symmetric_difference(other)
|
.. method:: symmetric_difference(other)
|
||||||
set ^ other
|
set ^ other
|
||||||
|
|
||||||
Return a new set with elements in either the set or *other* but not both.
|
Return a new set with elements in either the set or *other* but not both.
|
||||||
|
|
||||||
.. method:: set.copy()
|
.. method:: copy()
|
||||||
|
|
||||||
Return a new set with a shallow copy of *s*.
|
Return a new set with a shallow copy of *s*.
|
||||||
|
|
||||||
|
|
||||||
Note, the non-operator versions of :meth:`union`, :meth:`intersection`,
|
Note, the non-operator versions of :meth:`union`, :meth:`intersection`,
|
||||||
:meth:`difference`, and :meth:`symmetric_difference`, :meth:`issubset`, and
|
:meth:`difference`, and :meth:`symmetric_difference`, :meth:`issubset`, and
|
||||||
:meth:`issuperset` methods will accept any iterable as an argument. In
|
:meth:`issuperset` methods will accept any iterable as an argument. In
|
||||||
contrast, their operator based counterparts require their arguments to be sets.
|
contrast, their operator based counterparts require their arguments to be
|
||||||
This precludes error-prone constructions like ``set('abc') & 'cbs'`` in favor of
|
sets. This precludes error-prone constructions like ``set('abc') & 'cbs'``
|
||||||
the more readable ``set('abc').intersection('cbs')``.
|
in favor of the more readable ``set('abc').intersection('cbs')``.
|
||||||
|
|
||||||
Both :class:`set` and :class:`frozenset` support set to set comparisons. Two
|
Both :class:`set` and :class:`frozenset` support set to set comparisons. Two
|
||||||
sets are equal if and only if every element of each set is contained in the
|
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
|
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
|
only if the first set is a proper subset of the second set (is a subset, but
|
||||||
not equal). A set is greater than another set if and only if the first set is a
|
is not equal). A set is greater than another set if and only if the first set
|
||||||
proper superset of the second set (is a superset, but is not equal).
|
is a proper superset of the second set (is a superset, but is not equal).
|
||||||
|
|
||||||
Instances of :class:`set` are compared to instances of :class:`frozenset` based
|
Instances of :class:`set` are compared to instances of :class:`frozenset`
|
||||||
on their members. For example, ``set('abc') == frozenset('abc')`` returns
|
based on their members. For example, ``set('abc') == frozenset('abc')``
|
||||||
``True`` and so does ``set('abc') in set([frozenset('abc')])``.
|
returns ``True`` and so does ``set('abc') in set([frozenset('abc')])``.
|
||||||
|
|
||||||
The subset and equality comparisons do not generalize to a complete ordering
|
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
|
function. For example, any two disjoint sets are not equal and are not
|
||||||
of each other, so *all* of the following return ``False``: ``a<b``, ``a==b``,
|
subsets of each other, so *all* of the following return ``False``: ``a<b``,
|
||||||
or ``a>b``. Accordingly, sets do not implement the :meth:`__cmp__` method.
|
``a==b``, or ``a>b``. Accordingly, sets do not implement the :meth:`__cmp__`
|
||||||
|
method.
|
||||||
|
|
||||||
Since sets only define partial ordering (subset relationships), the output of
|
Since sets only define partial ordering (subset relationships), the output of
|
||||||
the :meth:`list.sort` method is undefined for lists of sets.
|
the :meth:`list.sort` method is undefined for lists of sets.
|
||||||
|
|
||||||
Set elements, like dictionary keys, must be :term:`hashable`.
|
Set elements, like dictionary keys, must be :term:`hashable`.
|
||||||
|
|
||||||
Binary operations that mix :class:`set` instances with :class:`frozenset` return
|
Binary operations that mix :class:`set` instances with :class:`frozenset`
|
||||||
the type of the first operand. For example: ``frozenset('ab') | set('bc')``
|
return the type of the first operand. For example: ``frozenset('ab') |
|
||||||
returns an instance of :class:`frozenset`.
|
set('bc')`` returns an instance of :class:`frozenset`.
|
||||||
|
|
||||||
The following table lists operations available for :class:`set` that do not
|
The following table lists operations available for :class:`set` that do not
|
||||||
apply to immutable instances of :class:`frozenset`:
|
apply to immutable instances of :class:`frozenset`:
|
||||||
|
|
||||||
.. method:: set.update(other)
|
.. method:: update(other)
|
||||||
set |= other
|
set |= other
|
||||||
|
|
||||||
Update the set, adding elements from *other*.
|
Update the set, adding elements from *other*.
|
||||||
|
|
||||||
.. method:: set.intersection_update(other)
|
.. method:: intersection_update(other)
|
||||||
set &= other
|
set &= other
|
||||||
|
|
||||||
Update the set, keeping only elements found in it and *other*.
|
Update the set, keeping only elements found in it and *other*.
|
||||||
|
|
||||||
.. method:: set.difference_update(other)
|
.. method:: difference_update(other)
|
||||||
set -= other
|
set -= other
|
||||||
|
|
||||||
Update the set, removing elements found in *other*.
|
Update the set, removing elements found in *other*.
|
||||||
|
|
||||||
.. method:: set.symmetric_difference_update(other)
|
.. method:: symmetric_difference_update(other)
|
||||||
set ^= other
|
set ^= other
|
||||||
|
|
||||||
Update the set, keeping only elements found in either set, but not in both.
|
Update the set, keeping only elements found in either set, but not in both.
|
||||||
|
|
||||||
.. method:: set.add(elem)
|
.. method:: add(elem)
|
||||||
|
|
||||||
Add element *elem* to the set.
|
Add element *elem* to the set.
|
||||||
|
|
||||||
.. method:: set.remove(elem)
|
.. method:: remove(elem)
|
||||||
|
|
||||||
Remove element *elem* from the set. Raises :exc:`KeyError` if *elem* is not
|
Remove element *elem* from the set. Raises :exc:`KeyError` if *elem* is
|
||||||
contained in the set.
|
not contained in the set.
|
||||||
|
|
||||||
.. method:: set.discard(elem)
|
.. method:: discard(elem)
|
||||||
|
|
||||||
Remove element *elem* from the set if it is present.
|
Remove element *elem* from the set if it is present.
|
||||||
|
|
||||||
.. method:: set.pop()
|
.. method:: pop()
|
||||||
|
|
||||||
Remove and return an arbitrary element from the set. Raises :exc:`KeyError`
|
Remove and return an arbitrary element from the set. Raises
|
||||||
if the set is empty.
|
:exc:`KeyError` if the set is empty.
|
||||||
|
|
||||||
.. method:: set.clear()
|
.. method:: clear()
|
||||||
|
|
||||||
Remove all elements from the set.
|
Remove all elements from the set.
|
||||||
|
|
||||||
|
|
||||||
Note, the non-operator versions of the :meth:`update`,
|
Note, the non-operator versions of the :meth:`update`,
|
||||||
:meth:`intersection_update`, :meth:`difference_update`, and
|
:meth:`intersection_update`, :meth:`difference_update`, and
|
||||||
:meth:`symmetric_difference_update` methods will accept any iterable as an
|
:meth:`symmetric_difference_update` methods will accept any iterable as an
|
||||||
argument.
|
argument.
|
||||||
|
|
||||||
Note, the *elem* argument to the :meth:`__contains__`, :meth:`remove`, and
|
Note, the *elem* argument to the :meth:`__contains__`, :meth:`remove`, and
|
||||||
:meth:`discard` methods may be a set. To support searching for an equivalent
|
:meth:`discard` methods may be a set. To support searching for an equivalent
|
||||||
frozenset, the *elem* set is temporarily mutated during the search and then
|
frozenset, the *elem* set is temporarily mutated during the search and then
|
||||||
restored. During the search, the *elem* set should not be read or mutated
|
restored. During the search, the *elem* set should not be read or mutated
|
||||||
since it does not have a meaningful value.
|
since it does not have a meaningful value.
|
||||||
|
|
||||||
|
|
||||||
.. seealso::
|
.. seealso::
|
||||||
|
|
@ -1733,159 +1734,162 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
|
||||||
Support for building a dictionary from keyword arguments added.
|
Support for building a dictionary from keyword arguments added.
|
||||||
|
|
||||||
|
|
||||||
These are the operations that dictionaries support (and therefore, custom mapping
|
These are the operations that dictionaries support (and therefore, custom
|
||||||
types should support too):
|
mapping types should support too):
|
||||||
|
|
||||||
.. describe:: len(d)
|
.. describe:: len(d)
|
||||||
|
|
||||||
Return the number of items in the dictionary *d*.
|
Return the number of items in the dictionary *d*.
|
||||||
|
|
||||||
.. describe:: d[key]
|
.. describe:: d[key]
|
||||||
|
|
||||||
Return the item of *d* with key *key*. Raises a :exc:`KeyError` if *key* is
|
Return the item of *d* with key *key*. Raises a :exc:`KeyError` if *key*
|
||||||
not in the map.
|
is not in the map.
|
||||||
|
|
||||||
.. versionadded:: 2.5
|
.. versionadded:: 2.5
|
||||||
If a subclass of dict defines a method :meth:`__missing__`, if the key
|
If a subclass of dict defines a method :meth:`__missing__`, if the key
|
||||||
*key* is not present, the ``d[key]`` operation calls that method with the
|
*key* is not present, the ``d[key]`` operation calls that method with
|
||||||
key *key* as argument. The ``d[key]`` operation then returns or raises
|
the key *key* as argument. The ``d[key]`` operation then returns or
|
||||||
whatever is returned or raised by the ``__missing__(key)`` call if the key
|
raises whatever is returned or raised by the ``__missing__(key)`` call
|
||||||
is not present. No other operations or methods invoke
|
if the key is not present. No other operations or methods invoke
|
||||||
:meth:`__missing__`. If :meth:`__missing__` is not defined,
|
:meth:`__missing__`. If :meth:`__missing__` is not defined,
|
||||||
:exc:`KeyError` is raised. :meth:`__missing__` must be a method; it
|
:exc:`KeyError` is raised. :meth:`__missing__` must be a method; it
|
||||||
cannot be an instance variable. For an example, see
|
cannot be an instance variable. For an example, see
|
||||||
:class:`collections.defaultdict`.
|
:class:`collections.defaultdict`.
|
||||||
|
|
||||||
.. describe:: d[key] = value
|
.. describe:: d[key] = value
|
||||||
|
|
||||||
Set ``d[key]`` to *value*.
|
Set ``d[key]`` to *value*.
|
||||||
|
|
||||||
.. describe:: del d[key]
|
.. describe:: del d[key]
|
||||||
|
|
||||||
Remove ``d[key]`` from *d*. Raises a :exc:`KeyError` if *key* is not in the
|
Remove ``d[key]`` from *d*. Raises a :exc:`KeyError` if *key* is not in the
|
||||||
map.
|
map.
|
||||||
|
|
||||||
.. describe:: key in d
|
.. describe:: key in d
|
||||||
|
|
||||||
Return ``True`` if *d* has a key *key*, else ``False``.
|
Return ``True`` if *d* has a key *key*, else ``False``.
|
||||||
|
|
||||||
.. versionadded:: 2.2
|
.. versionadded:: 2.2
|
||||||
|
|
||||||
.. describe:: key not in d
|
.. describe:: key not in d
|
||||||
|
|
||||||
Equivalent to ``not key in d``.
|
Equivalent to ``not key in d``.
|
||||||
|
|
||||||
.. versionadded:: 2.2
|
.. versionadded:: 2.2
|
||||||
|
|
||||||
.. method:: dict.clear()
|
.. method:: clear()
|
||||||
|
|
||||||
Remove all items from the dictionary.
|
Remove all items from the dictionary.
|
||||||
|
|
||||||
.. method:: dict.copy()
|
.. method:: copy()
|
||||||
|
|
||||||
Return a shallow copy of the dictionary.
|
Return a shallow copy of the dictionary.
|
||||||
|
|
||||||
.. method:: dict.fromkeys(seq[, value])
|
.. method:: fromkeys(seq[, value])
|
||||||
|
|
||||||
Create a new dictionary with keys from *seq* and values set to *value*.
|
Create a new dictionary with keys from *seq* and values set to *value*.
|
||||||
|
|
||||||
:func:`fromkeys` is a class method that returns a new dictionary. *value*
|
:func:`fromkeys` is a class method that returns a new dictionary. *value*
|
||||||
defaults to ``None``.
|
defaults to ``None``.
|
||||||
|
|
||||||
.. versionadded:: 2.3
|
.. versionadded:: 2.3
|
||||||
|
|
||||||
.. method:: dict.get(key[, default])
|
.. method:: get(key[, default])
|
||||||
|
|
||||||
Return the value for *key* if *key* is in the dictionary, else *default*. If
|
Return the value for *key* if *key* is in the dictionary, else *default*.
|
||||||
*default* is not given, it defaults to ``None``, so that this method never
|
If *default* is not given, it defaults to ``None``, so that this method
|
||||||
raises a :exc:`KeyError`.
|
never raises a :exc:`KeyError`.
|
||||||
|
|
||||||
.. method:: dict.has_key(key)
|
.. method:: has_key(key)
|
||||||
|
|
||||||
``d.has_key(key)`` is equivalent to ``key in d``, but deprecated.
|
``dict.has_key(key)`` is equivalent to ``key in d``, but deprecated.
|
||||||
|
|
||||||
.. method:: dict.items()
|
.. method:: items()
|
||||||
|
|
||||||
Return a copy of the dictionary's list of ``(key, value)`` pairs.
|
Return a copy of the dictionary's list of ``(key, value)`` pairs.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
Keys and values are listed in an arbitrary order which is non-random, varies
|
Keys and values are listed in an arbitrary order which is non-random,
|
||||||
across Python implementations, and depends on the dictionary's history of
|
varies across Python implementations, and depends on the dictionary's
|
||||||
insertions and deletions. If :meth:`items`, :meth:`keys`, :meth:`values`,
|
history of insertions and deletions. If :meth:`items`, :meth:`keys`,
|
||||||
:meth:`iteritems`, :meth:`iterkeys`, and :meth:`itervalues` are called with no
|
:meth:`values`, :meth:`iteritems`, :meth:`iterkeys`, and
|
||||||
intervening modifications to the dictionary, the lists will directly correspond.
|
:meth:`itervalues` are called with no intervening modifications to the
|
||||||
This allows the creation of ``(value, key)`` pairs using :func:`zip`: ``pairs =
|
dictionary, the lists will directly correspond. This allows the
|
||||||
zip(d.values(), d.keys())``. The same relationship holds for the
|
creation of ``(value, key)`` pairs using :func:`zip`: ``pairs =
|
||||||
:meth:`iterkeys` and :meth:`itervalues` methods: ``pairs = zip(d.itervalues(),
|
zip(d.values(), d.keys())``. The same relationship holds for the
|
||||||
d.iterkeys())`` provides the same value for ``pairs``. Another way to create the
|
:meth:`iterkeys` and :meth:`itervalues` methods: ``pairs =
|
||||||
same list is ``pairs = [(v, k) for (k, v) in d.iteritems()]``.
|
zip(d.itervalues(), d.iterkeys())`` provides the same value for
|
||||||
|
``pairs``. Another way to create the same list is ``pairs = [(v, k) for
|
||||||
|
(k, v) in d.iteritems()]``.
|
||||||
|
|
||||||
.. method:: dict.iteritems()
|
.. method:: iteritems()
|
||||||
|
|
||||||
Return an iterator over the dictionary's ``(key, value)`` pairs.
|
Return an iterator over the dictionary's ``(key, value)`` pairs. See the
|
||||||
See the note for :meth:`dict.items`.
|
note for :meth:`dict.items`.
|
||||||
|
|
||||||
.. versionadded:: 2.2
|
.. versionadded:: 2.2
|
||||||
|
|
||||||
.. method:: dict.iterkeys()
|
.. method:: iterkeys()
|
||||||
|
|
||||||
Return an iterator over the dictionary's keys. See the note for
|
Return an iterator over the dictionary's keys. See the note for
|
||||||
:meth:`dict.items`.
|
:meth:`dict.items`.
|
||||||
|
|
||||||
.. versionadded:: 2.2
|
.. versionadded:: 2.2
|
||||||
|
|
||||||
.. method:: dict.itervalues()
|
.. method:: itervalues()
|
||||||
|
|
||||||
Return an iterator over the dictionary's values. See the note for
|
Return an iterator over the dictionary's values. See the note for
|
||||||
:meth:`dict.items`.
|
:meth:`dict.items`.
|
||||||
|
|
||||||
.. versionadded:: 2.2
|
.. versionadded:: 2.2
|
||||||
|
|
||||||
.. method:: dict.keys()
|
.. method:: keys()
|
||||||
|
|
||||||
Return a copy of the dictionary's list of keys. See the note for
|
Return a copy of the dictionary's list of keys. See the note for
|
||||||
:meth:`dict.items`.
|
:meth:`dict.items`.
|
||||||
|
|
||||||
.. method:: dict.pop(key[, default])
|
.. method:: pop(key[, default])
|
||||||
|
|
||||||
If *key* is in the dictionary, remove it and return its value, else return
|
If *key* is in the dictionary, remove it and return its value, else return
|
||||||
*default*. If *default* is not given and *key* is not in the dictionary, a
|
*default*. If *default* is not given and *key* is not in the dictionary,
|
||||||
:exc:`KeyError` is raised.
|
a :exc:`KeyError` is raised.
|
||||||
|
|
||||||
.. versionadded:: 2.3
|
.. versionadded:: 2.3
|
||||||
|
|
||||||
.. method:: dict.popitem()
|
.. method:: popitem()
|
||||||
|
|
||||||
Remove and return an arbitrary ``(key, value)`` pair from the dictionary.
|
Remove and return an arbitrary ``(key, value)`` pair from the dictionary.
|
||||||
|
|
||||||
:func:`popitem` is useful to destructively iterate over a dictionary, as
|
:func:`popitem` is useful to destructively iterate over a dictionary, as
|
||||||
often used in set algorithms. If the dictionary is empty, calling
|
often used in set algorithms. If the dictionary is empty, calling
|
||||||
:func:`popitem` raises a :exc:`KeyError`.
|
:func:`popitem` raises a :exc:`KeyError`.
|
||||||
|
|
||||||
.. method:: dict.setdefault(key[, default])
|
.. method:: setdefault(key[, default])
|
||||||
|
|
||||||
If *key* is in the dictionary, return its value. If not, insert *key* with a
|
If *key* is in the dictionary, return its value. If not, insert *key*
|
||||||
value of *default* and return *default*. *default* defaults to ``None``.
|
with a value of *default* and return *default*. *default* defaults to
|
||||||
|
``None``.
|
||||||
|
|
||||||
.. method:: dict.update([other])
|
.. method:: update([other])
|
||||||
|
|
||||||
Update the dictionary with the key/value pairs from *other*, overwriting existing
|
Update the dictionary with the key/value pairs from *other*, overwriting
|
||||||
keys. Return ``None``.
|
existing keys. Return ``None``.
|
||||||
|
|
||||||
:func:`update` accepts either another dictionary object or an iterable of
|
:func:`update` accepts either another dictionary object or an iterable of
|
||||||
key/value pairs (as a tuple or other iterable of length two). If keyword
|
key/value pairs (as a tuple or other iterable of length two). If keyword
|
||||||
arguments are specified, the dictionary is then is updated with those
|
arguments are specified, the dictionary is then is updated with those
|
||||||
key/value pairs: ``d.update(red=1, blue=2)``.
|
key/value pairs: ``d.update(red=1, blue=2)``.
|
||||||
|
|
||||||
.. versionchanged:: 2.4
|
.. versionchanged:: 2.4
|
||||||
Allowed the argument to be an iterable of key/value pairs and allowed
|
Allowed the argument to be an iterable of key/value pairs and allowed
|
||||||
keyword arguments.
|
keyword arguments.
|
||||||
|
|
||||||
.. method:: dict.values()
|
.. method:: values()
|
||||||
|
|
||||||
Return a copy of the dictionary's list of values. See the note for
|
Return a copy of the dictionary's list of values. See the note for
|
||||||
:meth:`dict.items`.
|
:meth:`dict.items`.
|
||||||
|
|
||||||
|
|
||||||
.. _bltin-file-objects:
|
.. _bltin-file-objects:
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue