From 8fde9506b73ff51753d7df799d1dba3b92101138 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 29 Jul 2011 11:34:17 +0200 Subject: Improve glossary entry for ABCs. - Rename reST target name for collections ABCs to avoid collisions - Link to glossary entry from numbers module doc (other modules already do it) --- Doc/glossary.rst | 11 ++++++----- Doc/library/abc.rst | 4 ++-- Doc/library/collections.rst | 12 ++++++------ Doc/library/numbers.rst | 6 +++--- 4 files changed, 17 insertions(+), 16 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index fa81144..eb72558 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -27,12 +27,13 @@ Glossary :ref:`2to3-reference`. abstract base class - :ref:`abstract-base-classes` complement :term:`duck-typing` by + Abstract base classes complement :term:`duck-typing` by providing a way to define interfaces when other techniques like - :func:`hasattr` would be clumsy. Python comes with many built-in ABCs for + :func:`hasattr` would be clumsy or subtly wrong (for example with + :ref:`magic methods `). Python comes with many built-in ABCs for data structures (in the :mod:`collections` module), numbers (in the :mod:`numbers` module), and streams (in the :mod:`io` module). You can - create your own ABC with the :mod:`abc` module. + create your own ABCs with the :mod:`abc` module. argument A value passed to a function or method, assigned to a named local @@ -424,8 +425,8 @@ Glossary mapping A container object that supports arbitrary key lookups and implements the methods specified in the :class:`Mapping` or :class:`MutableMapping` - :ref:`abstract base classes `. Examples include - :class:`dict`, :class:`collections.defaultdict`, + :ref:`abstract base classes `. Examples + include :class:`dict`, :class:`collections.defaultdict`, :class:`collections.OrderedDict` and :class:`collections.Counter`. metaclass diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst index 9f70b02..0408f30 100644 --- a/Doc/library/abc.rst +++ b/Doc/library/abc.rst @@ -9,8 +9,8 @@ .. versionadded:: 2.6 -This module provides the infrastructure for defining an :term:`abstract base -class` (ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this +This module provides the infrastructure for defining :term:`abstract base +classes ` (ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this was added to Python. (See also :pep:`3141` and the :mod:`numbers` module regarding a type hierarchy for numbers based on ABCs.) diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 0f098f7..9f6d079 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -28,7 +28,7 @@ Python's general purpose built-in containers, :class:`dict`, :class:`list`, ===================== ==================================================================== =========================== In addition to the concrete container classes, the collections module provides -:ref:`abstract-base-classes` that can be used to test whether a class provides a +:ref:`collections-abstract-base-classes` that can be used to test whether a class provides a particular interface, for example, whether it is hashable or a mapping. .. seealso:: @@ -851,8 +851,8 @@ If a new entry overwrites an existing entry, the original insertion position is changed and moved to the end:: class LastUpdatedOrderedDict(OrderedDict): - 'Store items in the order the keys were last added' + def __setitem__(self, key, value): if key in self: del self[key] @@ -871,10 +871,10 @@ so that the counter remembers the order elements are first encountered:: return self.__class__, (OrderedDict(self),) -.. _abstract-base-classes: +.. _collections-abstract-base-classes: -ABCs - abstract base classes ----------------------------- +Collections Abstract Base Classes +--------------------------------- The collections module offers the following :term:`ABCs `: @@ -888,7 +888,7 @@ ABC Inherits from Abstract Methods Mixin :class:`Sized` ``__len__`` :class:`Callable` ``__call__`` -:class:`Sequence` :class:`Sized`, ``__getitem__`` ``__contains__``. ``__iter__``, ``__reversed__``, +:class:`Sequence` :class:`Sized`, ``__getitem__`` ``__contains__``, ``__iter__``, ``__reversed__``, :class:`Iterable`, ``index``, and ``count`` :class:`Container` diff --git a/Doc/library/numbers.rst b/Doc/library/numbers.rst index a0a825f..f46e8ac 100644 --- a/Doc/library/numbers.rst +++ b/Doc/library/numbers.rst @@ -7,9 +7,9 @@ .. versionadded:: 2.6 -The :mod:`numbers` module (:pep:`3141`) defines a hierarchy of numeric abstract -base classes which progressively define more operations. None of the types -defined in this module can be instantiated. +The :mod:`numbers` module (:pep:`3141`) defines a hierarchy of numeric +:term:`abstract base classes ` which progressively define +more operations. None of the types defined in this module can be instantiated. .. class:: Number -- cgit v0.12