diff options
Diffstat (limited to 'Doc/library/collections.rst')
| -rw-r--r-- | Doc/library/collections.rst | 40 |
1 files changed, 30 insertions, 10 deletions
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index d0aa62e368..8e2eb4d9b0 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -763,7 +763,7 @@ Named tuples assign meaning to each position in a tuple and allow for more reada self-documenting code. They can be used wherever regular tuples are used, and they add the ability to access fields by name instead of position index. -.. function:: namedtuple(typename, field_names, verbose=False, rename=False) +.. function:: namedtuple(typename, field_names, *, verbose=False, rename=False, module=None) Returns a new tuple subclass named *typename*. The new subclass is used to create tuple-like objects that have fields accessible by attribute lookup as @@ -790,12 +790,21 @@ they add the ability to access fields by name instead of position index. built. This option is outdated; instead, it is simpler to print the :attr:`_source` attribute. + If *module* is defined, the ``__module__`` attribute of the named tuple is + set to that value. + Named tuple instances do not have per-instance dictionaries, so they are lightweight and require no more memory than regular tuples. .. versionchanged:: 3.1 - Added support for *rename*. + Added support for *rename*. + + .. versionchanged:: 3.6 + The *verbose* and *rename* parameters became + :ref:`keyword-only arguments <keyword-only_parameter>`. + .. versionchanged:: 3.6 + Added the *module* parameter. .. doctest:: :options: +NORMALIZE_WHITESPACE @@ -846,7 +855,9 @@ field names, the method and attribute names start with an underscore. .. method:: somenamedtuple._asdict() Return a new :class:`OrderedDict` which maps field names to their corresponding - values:: + values: + + .. doctest:: >>> p = Point(x=11, y=22) >>> p._asdict() @@ -908,7 +919,9 @@ Since a named tuple is a regular Python class, it is easy to add or change functionality with a subclass. Here is how to add a calculated field and a fixed-width print format: - >>> class Point(namedtuple('Point', 'x y')): +.. doctest:: + + >>> class Point(namedtuple('Point', ['x', 'y'])): ... __slots__ = () ... @property ... def hypot(self): @@ -959,6 +972,11 @@ customize a prototype instance: constructor that is convenient for use cases where named tuples are being subclassed. + * See :meth:`types.SimpleNamespace` for a mutable namespace based on an + underlying dictionary instead of a tuple. + + * See :meth:`typing.NamedTuple` for a way to add type hints for named tuples. + :class:`OrderedDict` objects ---------------------------- @@ -980,8 +998,9 @@ the items are returned in the order their keys were first added. .. method:: popitem(last=True) The :meth:`popitem` method for ordered dictionaries returns and removes a - (key, value) pair. The pairs are returned in LIFO order if *last* is true - or FIFO order if false. + (key, value) pair. The pairs are returned in + :abbr:`LIFO (last-in, first-out)` order if *last* is true + or :abbr:`FIFO (first-in, first-out)` order if false. .. method:: move_to_end(key, last=True) @@ -1010,14 +1029,15 @@ Equality tests between :class:`OrderedDict` objects and other dictionaries. This allows :class:`OrderedDict` objects to be substituted anywhere a regular dictionary is used. -The :class:`OrderedDict` constructor and :meth:`update` method both accept -keyword arguments, but their order is lost because Python's function call -semantics pass in keyword arguments using a regular unordered dictionary. - .. versionchanged:: 3.5 The items, keys, and values :term:`views <dictionary view>` of :class:`OrderedDict` now support reverse iteration using :func:`reversed`. +.. versionchanged:: 3.6 + With the acceptance of :pep:`468`, order is retained for keyword arguments + passed to the :class:`OrderedDict` constructor and its :meth:`update` + method. + :class:`OrderedDict` Examples and Recipes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |