8000 [3.7] Corrected link targets in collections.rst (GH-1052) by miss-islington · Pull Request #6257 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

[3.7] Corrected link targets in collections.rst (GH-1052) #6257

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 26, 2018
Merged

[3.7] Corrected link targets in collections.rst (GH-1052) #6257

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 31 additions & 24 deletions Doc/library/collections.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ The class can be used to simulate nested scopes and is useful in templating.
for templating is a read-only chain of mappings. It also features
pushing and popping of contexts similar to the
:meth:`~collections.ChainMap.new_child` method and the
:meth:`~collections.ChainMap.parents` property.
:attr:`~collections.ChainMap.parents` property.

* The `Nested Contexts recipe
<https://code.activestate.com/recipes/577434/>`_ has options to control
Expand Down Expand Up @@ -270,7 +270,7 @@ For example::

Return a list of the *n* most common elements and their counts from the
most common to the least. If *n* is omitted or ``None``,
:func:`most_common` returns *all* elements in the counter.
:meth:`most_common` returns *all* elements in the counter.
Elements with equal counts are ordered arbitrarily:

>>> Counter('abracadabra').most_common(3) # doctest: +SKIP
Expand Down Expand Up @@ -357,20 +357,20 @@ or subtracting from an empty counter.
restrictions on its keys and values. The values are intended to be numbers
representing counts, but you *could* store anything in the value field.

* The :meth:`most_common` method requires only that the values be orderable.
* The :meth:`~Counter.most_common` method requires only that the values be orderable.

* For in-place operations such as ``c[key] += 1``, the value type need only
support addition and subtraction. So fractions, floats, and decimals would
work and negative values are supported. The same is also true for
:meth:`update` and :meth:`subtract` which allow negative and zero values
:meth:`~Counter.update` and :meth:`~Counter.subtract` which allow negative and zero values
for both inputs and outputs.

* The multiset methods are designed only for use cases with positive values.
The inputs may be negative or zero, but only outputs with positive values
are created. There are no type restrictions, but the value type needs to
support addition, subtraction, and comparison.

* The :meth:`elements` method requires integer counts. It ignores zero and
* The :meth:`~Counter.elements` method requires integer counts. It ignores zero and
negative counts.

.. seealso::
Expand All @@ -388,9 +388,9 @@ or subtracting from an empty counter.
Section 4.6.3, Exercise 19*.

* To enumerate all distinct multisets of a given size over a given set of
elements, see :func:`itertools.combinations_with_replacement`:
elements, see :func:`itertools.combinations_with_replacement`::

map(Counter, combinations_with_replacement('ABC', 2)) --> AA AB AC BB BC CC
map(Counter, combinations_with_replacement('ABC', 2)) # --> AA AB AC BB BC CC


:class:`deque` objects
Expand Down Expand Up @@ -640,18 +640,18 @@ the :meth:`~deque.rotate` method::
# Remove an exhausted iterator.
iterators.popleft()

The :meth:`rotate` method provides a way to implement :class:`deque` slicing and
The :meth:`~deque.rotate` method provides a way to implement :class:`deque` slicing and
deletion. For example, a pure Python implementation of ``del d[n]`` relies on
the :meth:`rotate` method to position elements to be popped::
the ``rotate()`` method to position elements to be popped::

def delete_nth(d, n):
d.rotate(-n)
d.popleft()
d.rotate(n)

To implement :class:`deque` slicing, use a similar approach applying
:meth:`rotate` to bring a target element to the left side of the deque. Remove
old entries with :meth:`popleft`, add new entries with :meth:`extend`, and then
:meth:`~deque.rotate` to bring a target element to the left side of the deque. Remove
old entries with :meth:`~deque.popleft`, add new entries with :meth:`~deque.extend`, and then
reverse the rotation.
With minor variations on that approach, it is easy to implement Forth style
stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
Expand Down Expand Up @@ -712,7 +712,7 @@ stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
:class:`defaultdict` Examples
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Using :class:`list` as the :attr:`default_factory`, it is easy to group a
Using :class:`list` as the :attr:`~defaultdict.default_factory`, it is easy to group a
sequence of key-value pairs into a dictionary of lists:

>>> 8000 s = [('yellow', 1), ('blue', 2), ('yellow', 3), ('blue', 4), ('red', 1)]
Expand All @@ -724,7 +724,7 @@ sequence of key-value pairs into a dictionary of lists:
[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]

When each key is encountered for the first time, it is not already in the
mapping; so an entry is automatically created using the :attr:`default_factory`
mapping; so an entry is automatically created using the :attr:`~defaultdict.default_factory`
function which returns an empty :class:`list`. The :meth:`list.append`
operation then attaches the value to the new list. When keys are encountered
again, the look-up proceeds normally (returning the list for that key) and the
Expand All @@ -738,7 +738,7 @@ simpler and faster than an equivalent technique using :meth:`dict.setdefault`:
>>> sorted(d.items())
[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]

Setting the :attr:`default_factory` to :class:`int` makes the
Setting the :attr:`~defaultdict.default_factory` to :class:`int` makes the
:class:`defaultdict` useful for counting (like a bag or multiset in other
languages):

Expand All @@ -751,7 +751,7 @@ languages):
[('i', 4), ('m', 1), ('p', 2), ('s', 4)]

When a letter is first encountered, it is missing from the mapping, so the
:attr:`default_factory` function calls :func:`int` to supply a default count of
:attr:`~defaultdict.default_factory` function calls :func:`int` to supply a default count of
zero. The increment operation then builds up the count for each letter.

The function :func:`int` which always returns zero is just a special case of
Expand All @@ -766,7 +766,7 @@ zero):
>>> '%(name)s %(action)s to %(object)s' % d
'John ran to <missing>'

Setting the :attr:`default_factory` to :class:`set` makes the
Setting the :attr:`~defaultdict.default_factory` to :class:`set` makes the
:class:`defaultdict` useful for building a dictionary of sets:

>>> s = [('red', 1), ('blue', 2), ('red', 3), ('blue', 4), ('red', 1), ('blue', 4)]
Expand Down Expand Up @@ -973,7 +973,7 @@ The subclass shown above sets ``__slots__`` to an empty tuple. This helps
keep memory requirements low by preventing the creation of instance dictionaries.

Subclassing is not useful for adding new, stored fields. Instead, simply
create a new named tuple type from the :attr:`_fields` attribute:
create a new named tuple type from the :attr:`~somenamedtuple._fields` attribute:

>>> Point3D = namedtuple('Point3D', Point._fields + ('z',))

Expand All @@ -989,7 +989,7 @@ fields:
.. versionchanged:: 3.5
Property docstrings became writeable.

Default values can be implemented by using :meth:`_replace` to
Default values can be implemented by using :meth:`~somenamedtuple._replace` to
customize a prototype instance:

>>> Account = namedtuple('Account', 'owner balance transaction_count')
Expand Down Expand Up @@ -1200,15 +1200,22 @@ subclass directly from :class:`str`; however, this class can be easier
to work with because the underlying string is accessible as an
attribute.

.. class:: UserString([sequence])
.. class:: UserString(seq)

Class that simulates a string or a Unicode string object. The instance's
Class that simulates a string object. The instance's
content is kept in a regular string object, which is accessible via the
:attr:`data` attribute of :class:`UserString` instances. The instance's
contents are initially set to a copy of *sequence*. The *sequence* can
be an instance of :class:`bytes`, :class:`str`, :class:`UserString` (or a
subclass) or an arbitrary sequence which can be converted into a string using
the built-in :func:`str` function.
contents are initially set to a copy of *seq*. The *seq* argument can
be any object which can be converted into a string using the built-in
:func:`str` function.

In addition to supporting the methods and operations of strings,
:class:`UserString` instances provide the following attribute:

.. attribute:: data

A real :class:`str` object used to store the contents of the
:class:`UserString` class.

.. versionchanged:: 3.5
New methods ``__getnewargs__``, ``__rmod__``, ``casefold``,
Expand Down
0