diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/glossary.rst | 7 | ||||
| -rw-r--r-- | Doc/library/collections.rst | 23 | ||||
| -rw-r--r-- | Doc/library/decimal.rst | 6 | ||||
| -rw-r--r-- | Doc/library/difflib.rst | 5 | ||||
| -rw-r--r-- | Doc/library/doctest.rst | 5 | ||||
| -rw-r--r-- | Doc/library/inspect.rst | 22 | ||||
| -rw-r--r-- | Doc/library/re.rst | 4 |
7 files changed, 47 insertions, 25 deletions
diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 6d12d0f..194fbd9 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -327,6 +327,13 @@ Glossary mutable Mutable objects can change their value but keep their :func:`id`. See also :term:`immutable`. + + named tuple + A tuple subclass whose elements also are accessible as attributes via + fixed names (the class name and field names are indicated in the + individual documentation of a named tuple type, like ``TestResults(failed, + attempted)``). Named tuple classes are created by + :func:`collections.namedtuple`. namespace The place where a variable is stored. Namespaces are implemented as diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index fdfdefe..f1a8fff 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -397,8 +397,8 @@ they add the ability to access fields by name instead of position index. method which lists the tuple contents in a ``name=value`` format. The *fieldnames* are a single string with each fieldname separated by whitespace - and/or commas (for example 'x y' or 'x, y'). Alternatively, *fieldnames* - can be a sequence of strings (such as ['x', 'y']). + and/or commas, for example ``'x y'`` or ``'x, y'``. Alternatively, *fieldnames* + can be a sequence of strings such as ``['x', 'y']``. Any valid Python identifier may be used for a fieldname except for names starting with an underscore. Valid identifiers consist of letters, digits, @@ -406,7 +406,7 @@ they add the ability to access fields by name instead of position index. a :mod:`keyword` such as *class*, *for*, *return*, *global*, *pass*, *print*, or *raise*. - If *verbose* is true, will print the class definition. + If *verbose* is true, the class definition is printed just before being built. Named tuple instances do not have per-instance dictionaries, so they are lightweight and require no more memory than regular tuples. @@ -533,7 +533,7 @@ function:: >>> getattr(p, 'x') 11 -To cast a dictionary to a named tuple, use the double-star-operator [#]_:: +To convert a dictionary to a named tuple, use the double-star-operator [#]_:: >>> d = {'x': 11, 'y': 22} >>> Point(**d) @@ -544,23 +544,24 @@ functionality with a subclass. Here is how to add a calculated field and a fixed-width print format:: >>> class Point(namedtuple('Point', 'x y')): + ... __slots__ = () ... @property ... def hypot(self): ... return (self.x ** 2 + self.y ** 2) ** 0.5 ... def __str__(self): - ... return 'Point: x=%6.3f y=%6.3f hypot=%6.3f' % (self.x, self.y, self.hypot) + ... return 'Point: x=%6.3f y=%6.3f hypot=%6.3f' % (self.x, self.y, self.hypot) - >>> for p in Point(3,4), Point(14,5), Point(9./7,6): + >>> for p in Point(3, 4), Point(14, 5/7.): ... print(p) - Point: x= 3.000 y= 4.000 hypot= 5.000 - Point: x=14.000 y= 5.000 hypot=14.866 - Point: x= 1.286 y= 6.000 hypot= 6.136 + Point: x= 3.000 y= 4.000 hypot= 5.000 + Point: x=14.000 y= 0.714 hypot=14.018 Another use for subclassing is to replace performance critcal methods with -faster versions that bypass error-checking and that localize variable access:: +faster versions that bypass error-checking:: class Point(namedtuple('Point', 'x y')): + __slots__ = () _make = classmethod(tuple.__new__) def _replace(self, _map=map, **kwds): return self._make(_map(kwds.get, ('x', 'y'), self)) @@ -569,7 +570,7 @@ faster versions that bypass error-checking and that localize variable access:: Subclassing is not useful for adding new, stored fields. Instead, simply create a new named tuple type from the :attr:`_fields` attribute:: - >>> Pixel = namedtuple('Pixel', Point._fields + Color._fields) + >>> Point3D = namedtuple('Point3D', Point._fields + ('z',)) Default values can be implemented by using :meth:`_replace` to customize a prototype instance:: diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index e29e4ea..fbd6f43 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -328,7 +328,11 @@ also have a number of specialized methods: .. method:: Decimal.as_tuple() - Return a tuple representation of the number: ``(sign, digit_tuple, exponent)``. + Return a :term:`named tuple` representation of the number: + ``DecimalTuple(sign, digits, exponent)``. + + .. versionchanged:: 2.6 + Use a named tuple. .. method:: Decimal.canonical() diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst index 34dbcfd..7e61aa9 100644 --- a/Doc/library/difflib.rst +++ b/Doc/library/difflib.rst @@ -336,7 +336,7 @@ use :meth:`set_seq2` to set the commonly used sequence once and call Find longest matching block in ``a[alo:ahi]`` and ``b[blo:bhi]``. - If *isjunk* was omitted or ``None``, :meth:`get_longest_match` returns ``(i, j, + If *isjunk* was omitted or ``None``, :meth:`find_longest_match` returns ``(i, j, k)`` such that ``a[i:i+k]`` is equal to ``b[j:j+k]``, where ``alo <= i <= i+k <= ahi`` and ``blo <= j <= j+k <= bhi``. For all ``(i', j', k')`` meeting those conditions, the additional conditions ``k >= k'``, ``i <= i'``, and if ``i == @@ -365,6 +365,9 @@ use :meth:`set_seq2` to set the commonly used sequence once and call If no blocks match, this returns ``(alo, blo, 0)``. + .. versionchanged:: 2.6 + This method returns a :term:`named tuple` ``Match(a, b, size)``. + .. method:: SequenceMatcher.get_matching_blocks() diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index 04bc219..ce8b9f0 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -1436,11 +1436,14 @@ DocTestRunner objects .. method:: DocTestRunner.summarize([verbose]) Print a summary of all the test cases that have been run by this DocTestRunner, - and return a tuple ``(failure_count, test_count)``. + and return a :term:`named tuple` ``TestResults(failed, attempted)``. The optional *verbose* argument controls how detailed the summary is. If the verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is used. + .. versionchanged:: 2.6 + Use a named tuple. + .. _doctest-outputchecker: diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index e5008f6..5daa496 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -188,7 +188,8 @@ attributes: .. function:: getmoduleinfo(path) - Return a tuple of values that describe how Python will interpret the file + Returns a :term:`named tuple` ``ModuleInfo(name, suffix, mode, + module_type)`` of values that describe how Python will interpret the file identified by *path* if it is a module, or ``None`` if it would not be identified as a module. The return tuple is ``(name, suffix, mode, mtype)``, where *name* is the name of the module without the name of any enclosing @@ -377,8 +378,9 @@ Classes and functions .. function:: getargspec(func) - Get the names and default values of a function's arguments. A tuple of four - things is returned: ``(args, varargs, varkw, defaults)``. *args* is a list of + Get the names and default values of a function's arguments. A + :term:`named tuple` ``ArgSpec(args, varargs, keywords, + defaults)`` is returned. *args* is a list of the argument names. *varargs* and *varkw* are the names of the ``*`` and ``**`` arguments or ``None``. *defaults* is a tuple of default argument values or None if there are no default arguments; if this tuple has *n* @@ -391,10 +393,10 @@ Classes and functions .. function:: getfullargspec(func) - Get the names and default values of a function's arguments. A tuple of seven - things is returned: + Get the names and default values of a function's arguments. A :term:`named tuple` + is returned: - ``(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations)`` + ``FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations)`` *args* is a list of the argument names. *varargs* and *varkw* are the names of the ``*`` and ``**`` arguments or ``None``. *defaults* is an n-tuple of @@ -408,8 +410,8 @@ Classes and functions .. function:: getargvalues(frame) - Get information about arguments passed into a particular frame. A tuple of four - things is returned: ``(args, varargs, varkw, locals)``. *args* is a list of the + Get information about arguments passed into a particular frame. A :term:`named tuple` + ``ArgInfo(args, varargs, keywords, locals)`` is returned. *args* is a list of the argument names (it may contain nested lists). *varargs* and *varkw* are the names of the ``*`` and ``**`` arguments or ``None``. *locals* is the locals dictionary of the given frame. @@ -476,8 +478,8 @@ line. .. function:: getframeinfo(frame[, context]) - Get information about a frame or traceback object. A 5-tuple is returned, the - last five elements of the frame's frame record. + Get information about a frame or traceback object. A :term:`named tuple` + ``Traceback(filename, lineno, function, code_context, index)`` is returned. .. function:: getouterframes(frame[, context]) diff --git a/Doc/library/re.rst b/Doc/library/re.rst index 49c5215..7de088a 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -98,7 +98,9 @@ The special characters are: string, and in :const:`MULTILINE` mode also matches before a newline. ``foo`` matches both 'foo' and 'foobar', while the regular expression ``foo$`` matches only 'foo'. More interestingly, searching for ``foo.$`` in ``'foo1\nfoo2\n'`` - matches 'foo2' normally, but 'foo1' in :const:`MULTILINE` mode. + matches 'foo2' normally, but 'foo1' in :const:`MULTILINE` mode; searching for + a single ``$`` in ``'foo\n'`` will find two (empty) matches: one just before + the newline, and one at the end of the string. ``'*'`` Causes the resulting RE to match 0 or more repetitions of the preceding RE, as |