Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Issue #19190: Improve cross-references in builtin types and functions documentation.

This commit is contained in:
Serhiy Storchaka 2013-10-09 14:02:31 +03:00
parent 0b68a2d675
commit 0d196edc37
5 changed files with 100 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
Doc/glossary.rst
View File

@ -547,9 +547,9 @@ Glossary
dictionaries. There are the local, global and built-in namespaces as well
as nested namespaces in objects (in methods). Namespaces support
modularity by preventing naming conflicts. For instance, the functions
:func:`builtins.open` and :func:`os.open` are distinguished by their
namespaces. Namespaces also aid readability and maintainability by making
it clear which module implements a function. For instance, writing
:func:`builtins.open <.open>` and :func:`os.open` are distinguished by
their namespaces. Namespaces also aid readability and maintainability by
making it clear which module implements a function. For instance, writing
:func:`random.seed` or :func:`itertools.islice` makes it clear that those
functions are implemented by the :mod:`random` and :mod:`itertools`
modules, respectively.
@ -574,8 +574,8 @@ Glossary
new-style class
Old name for the flavor of classes now used for all class objects. In
earlier Python versions, only new-style classes could use Python's newer,
versatile features like :attr:`__slots__`, descriptors, properties,
:meth:`__getattribute__`, class methods, and static methods.
versatile features like :attr:`~object.__slots__`, descriptors,
properties, :meth:`__getattribute__`, class methods, and static methods.
object
Any data with state (attributes or value) and defined behavior
@ -790,7 +790,8 @@ Glossary
type
The type of a Python object determines what kind of object it is; every
object has a type. An object's type is accessible as its
:attr:`__class__` attribute or can be retrieved with ``type(obj)``.
:attr:`~instance.__class__` attribute or can be retrieved with
``type(obj)``.
universal newlines
A manner of interpreting text streams in which all of the following are

60
Doc/library/functions.rst
View File

@ -219,8 +219,8 @@ are always available. They are listed here in alphabetical order.
Future statements are specified by bits which can be bitwise ORed together to
specify multiple statements. The bitfield required to specify a given feature
can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature`
instance in the :mod:`__future__` module.
can be found as the :attr:`~__future__._Feature.compiler_flag` attribute on
the :class:`~__future__._Feature` instance in the :mod:`__future__` module.
The argument *optimize* specifies the optimization level of the compiler; the
default value of ``-1`` selects the optimization level of the interpreter as
@ -707,7 +707,7 @@ are always available. They are listed here in alphabetical order.
One useful application of the second form of :func:`iter` is to read lines of
a file until a certain line is reached. The following example reads a file
until the :meth:`readline` method returns an empty string::
until the :meth:`~io.TextIOBase.readline` method returns an empty string::
with open('mydata.txt') as fp:
for line in iter(fp.readline, ''):
@ -810,8 +810,8 @@ are always available. They are listed here in alphabetical order.
.. note::
:class:`object` does *not* have a :attr:`__dict__`, so you can't assign
arbitrary attributes to an instance of the :class:`object` class.
:class:`object` does *not* have a :attr:`~object.__dict__`, so you can't
assign arbitrary attributes to an instance of the :class:`object` class.
.. function:: oct(x)
@ -889,9 +889,9 @@ are always available. They are listed here in alphabetical order.
size" and falling back on :attr:`io.DEFAULT_BUFFER_SIZE`. On many systems,
the buffer will typically be 4096 or 8192 bytes long.
* "Interactive" text files (files for which :meth:`isatty` returns True) use
line buffering. Other text files use the policy described above for binary
files.
* "Interactive" text files (files for which :meth:`~io.IOBase.isatty`
returns True) use line buffering. Other text files use the policy
described above for binary files.
*encoding* is the name of the encoding used to decode or encode the file.
This should only be used in text mode. The default encoding is platform
@ -1096,10 +1096,10 @@ are always available. They are listed here in alphabetical order.
turns the :meth:`voltage` method into a "getter" for a read-only attribute
with the same name.
A property object has :attr:`getter`, :attr:`setter`, and :attr:`deleter`
methods usable as decorators that create a copy of the property with the
corresponding accessor function set to the decorated function. This is
best explained with an example::
A property object has :attr:`~property.getter`, :attr:`~property.setter`,
and :attr:`~property.deleter` methods usable as decorators that create a
copy of the property with the corresponding accessor function set to the
decorated function. This is best explained with an example::
class C:
def __init__(self):
@ -1205,13 +1205,13 @@ are always available. They are listed here in alphabetical order.
Return a :term:`slice` object representing the set of indices specified by
``range(start, stop, step)``. The *start* and *step* arguments default to
``None``. Slice objects have read-only data attributes :attr:`start`,
:attr:`stop` and :attr:`step` which merely return the argument values (or their
default). They have no other explicit functionality; however they are used by
Numerical Python and other third party extensions. Slice objects are also
generated when extended indexing syntax is used. For example:
``a[start:stop:step]`` or ``a[start:stop, i]``. See :func:`itertools.islice`
for an alternate version that returns an iterator.
``None``. Slice objects have read-only data attributes :attr:`~slice.start`,
:attr:`~slice.stop` and :attr:`~slice.step` which merely return the argument
values (or their default). They have no other explicit functionality;
however they are used by Numerical Python and other third party extensions.
Slice objects are also generated when extended indexing syntax is used. For
example: ``a[start:stop:step]`` or ``a[start:stop, i]``. See
:func:`itertools.islice` for an alternate version that returns an iterator.
.. function:: sorted(iterable[, key][, reverse])
@ -1291,9 +1291,10 @@ are always available. They are listed here in alphabetical order.
been overridden in a class. The search order is same as that used by
:func:`getattr` except that the *type* itself is skipped.
The :attr:`__mro__` attribute of the *type* lists the method resolution
search order used by both :func:`getattr` and :func:`super`. The attribute
is dynamic and can change whenever the inheritance hierarchy is updated.
The :attr:`~class.__mro__` attribute of the *type* lists the method
resolution search order used by both :func:`getattr` and :func:`super`. The
attribute is dynamic and can change whenever the inheritance hierarchy is
updated.
If the second argument is omitted, the super object returned is unbound. If
the second argument is an object, ``isinstance(obj, type)`` must be true. If
@ -1356,7 +1357,8 @@ are always available. They are listed here in alphabetical order.
With one argument, return the type of an *object*. The return value is a
type object and generally the same object as returned by ``object.__class__``.
type object and generally the same object as returned by
:attr:`object.__class__ <instance.__class__>`.
The :func:`isinstance` built-in function is recommended for testing the type
of an object, because it takes subclasses into account.
@ -1364,11 +1366,11 @@ are always available. They are listed here in alphabetical order.
With three arguments, return a new type object. This is essentially a
dynamic form of the :keyword:`class` statement. The *name* string is the
class name and becomes the :attr:`__name__` attribute; the *bases* tuple
itemizes the base classes and becomes the :attr:`__bases__` attribute;
and the *dict* dictionary is the namespace containing definitions for class
body and becomes the :attr:`__dict__` attribute. For example, the
following two statements create identical :class:`type` objects:
class name and becomes the :attr:`~class.__name__` attribute; the *bases*
tuple itemizes the base classes and becomes the :attr:`~class.__bases__`
attribute; and the *dict* dictionary is the namespace containing definitions
for class body and becomes the :attr:`~object.__dict__` attribute. For
example, the following two statements create identical :class:`type` objects:
>>> class X:
... a = 1
@ -1380,7 +1382,7 @@ are always available. They are listed here in alphabetical order.
.. function:: vars([object])
Return the :attr:`__dict__` attribute for a module, class, instance,
Return the :attr:`~object.__dict__` attribute for a module, class, instance,
or any other object with a :attr:`__dict__` attribute.
Objects such as modules and instances have an updateable :attr:`__dict__`

43
Doc/library/stdtypes.rst
View File

@ -339,8 +339,8 @@ Notes:
pair: C; language
Conversion from floating point to integer may round or truncate
as in C; see functions :func:`floor` and :func:`ceil` in the :mod:`math` module
for well-defined conversions.
as in C; see functions :func:`math.floor` and :func:`math.ceil` for
well-defined conversions.
(4)
float also accepts the strings "nan" and "inf" with an optional prefix "+"
@ -631,7 +631,7 @@ efficiency across a variety of numeric types (including :class:`int`,
:class:`float`, :class:`decimal.Decimal` and :class:`fractions.Fraction`)
Python's hash for numeric types is based on a single mathematical function
that's defined for any rational number, and hence applies to all instances of
:class:`int` and :class:`fraction.Fraction`, and all finite instances of
:class:`int` and :class:`fractions.Fraction`, and all finite instances of
:class:`float` and :class:`decimal.Decimal`. Essentially, this function is
given by reduction modulo ``P`` for a fixed prime ``P``. The value of ``P`` is
made available to Python as the :attr:`modulus` attribute of
@ -1303,7 +1303,7 @@ The advantage of the :class:`range` type over a regular :class:`list` or
only stores the ``start``, ``stop`` and ``step`` values, calculating individual
items and subranges as needed).
Range objects implement the :class:`collections.Sequence` ABC, and provide
Range objects implement the :class:`collections.abc.Sequence` ABC, and provide
features such as containment tests, element index lookup, slicing and
support for negative indices (see :ref:`typesseq`):
@ -1326,9 +1326,9 @@ support for negative indices (see :ref:`typesseq`):
Testing range objects for equality with ``==`` and ``!=`` compares
them as sequences. That is, two range objects are considered equal if
they represent the same sequence of values. (Note that two range
objects that compare equal might have different :attr:`start`,
:attr:`stop` and :attr:`step` attributes, for example ``range(0) ==
range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.)
objects that compare equal might have different :attr:`~range.start`,
:attr:`~range.stop` and :attr:`~range.step` attributes, for example
``range(0) == range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.)
.. versionchanged:: 3.2
Implement the Sequence ABC.
@ -1342,7 +1342,8 @@ range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.)
object identity).
.. versionadded:: 3.3
The :attr:`start`, :attr:`stop` and :attr:`step` attributes.
The :attr:`~range.start`, :attr:`~range.stop` and :attr:`~range.step`
attributes.
.. index::
@ -2298,7 +2299,7 @@ in the range 0 to 255 (inclusive) as well as bytes and byte array sequences.
(inclusive) as their first argument.
Each bytes and bytearray instance provides a :meth:`decode` convenience
Each bytes and bytearray instance provides a :meth:`~bytes.decode` convenience
method that is the inverse of :meth:`str.encode`:
.. method:: bytes.decode(encoding="utf-8", errors="strict")
@ -2805,11 +2806,11 @@ other sequence-like behavior.
There are currently two built-in set types, :class:`set` and :class:`frozenset`.
The :class:`set` type is mutable --- the contents can be changed using methods
like :meth:`add` and :meth:`remove`. Since it is mutable, it has no hash value
and cannot be used as either a dictionary key or as an element of another set.
The :class:`frozenset` type is immutable and :term:`hashable` --- its contents cannot be
altered after it is created; it can therefore be used as a dictionary key or as
an element of another set.
like :meth:`~set.add` and :meth:`~set.remove`. Since it is mutable, it has no
hash value and cannot be used as either a dictionary key or as an element of
another set. The :class:`frozenset` type is immutable and :term:`hashable` ---
its contents cannot be altered after it is created; it can therefore be used as
a dictionary key or as an element of another set.
Non-empty sets (not frozensets) can be created by placing a comma-separated list
of elements within braces, for example: ``{'jack', 'sjoerd'}``, in addition to the
@ -3350,12 +3351,12 @@ statement is not, strictly speaking, an operation on a module object; ``import
foo`` does not require a module object named *foo* to exist, rather it requires
an (external) *definition* for a module named *foo* somewhere.)
A special attribute of every module is :attr:`__dict__`. This is the dictionary
containing the module's symbol table. Modifying this dictionary will actually
change the module's symbol table, but direct assignment to the :attr:`__dict__`
attribute is not possible (you can write ``m.__dict__['a'] = 1``, which defines
``m.a`` to be ``1``, but you can't write ``m.__dict__ = {}``). Modifying
:attr:`__dict__` directly is not recommended.
A special attribute of every module is :attr:`~object.__dict__`. This is the
dictionary containing the module's symbol table. Modifying this dictionary will
actually change the module's symbol table, but direct assignment to the
:attr:`__dict__` attribute is not possible (you can write
``m.__dict__['a'] = 1``, which defines ``m.a`` to be ``1``, but you can't write
``m.__dict__ = {}``). Modifying :attr:`__dict__` directly is not recommended.
Modules built into the interpreter are written like this: ``<module 'sys'
(built-in)>``. If loaded from a file, they are written as ``<module 'os' from
@ -3590,7 +3591,7 @@ types, where they are relevant. Some of these are not reported by the
This method can be overridden by a metaclass to customize the method
resolution order for its instances. It is called at class instantiation, and
its result is stored in :attr:`__mro__`.
its result is stored in :attr:`~class.__mro__`.
.. method:: class.__subclasses__

46
Doc/reference/datamodel.rst
View File

@ -316,7 +316,7 @@ Sequences
represented by integers in the range 0 <= x < 256. Bytes literals
(like ``b'abc'``) and the built-in function :func:`bytes` can be used to
construct bytes objects. Also, bytes objects can be decoded to strings
via the :meth:`decode` method.
via the :meth:`~bytes.decode` method.
Mutable sequences
.. index::
@ -378,7 +378,7 @@ Set types
These represent a mutable set. They are created by the built-in :func:`set`
constructor and can be modified afterwards by several methods, such as
:meth:`add`.
:meth:`~set.add`.
Frozen sets
.. index:: object: frozenset
@ -604,7 +604,7 @@ Callable types
A function or method which uses the :keyword:`yield` statement (see section
:ref:`yield`) is called a :dfn:`generator function`. Such a function, when
called, always returns an iterator object which can be used to execute the
body of the function: calling the iterator's :meth:`iterator__next__`
body of the function: calling the iterator's :meth:`iterator.__next__`
method will cause the function to execute until it provides a value
using the :keyword:`yield` statement. When the function executes a
:keyword:`return` statement or falls off the end, a :exc:`StopIteration`
@ -748,10 +748,10 @@ Custom classes
Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is
the module name in which the class was defined; :attr:`__dict__` is the
dictionary containing the class's namespace; :attr:`__bases__` is a tuple
(possibly empty or a singleton) containing the base classes, in the order of
their occurrence in the base class list; :attr:`__doc__` is the class's
documentation string, or None if undefined.
dictionary containing the class's namespace; :attr:`~class.__bases__` is a
tuple (possibly empty or a singleton) containing the base classes, in the
order of their occurrence in the base class list; :attr:`__doc__` is the
class's documentation string, or None if undefined.
Class instances
.. index::
@ -793,8 +793,8 @@ Class instances
single: __dict__ (instance attribute)
single: __class__ (instance attribute)
Special attributes: :attr:`__dict__` is the attribute dictionary;
:attr:`__class__` is the instance's class.
Special attributes: :attr:`~object.__dict__` is the attribute dictionary;
:attr:`~instance.__class__` is the instance's class.
I/O objects (also known as file objects)
.. index::
@ -812,9 +812,9 @@ I/O objects (also known as file objects)
A :term:`file object` represents an open file. Various shortcuts are
available to create file objects: the :func:`open` built-in function, and
also :func:`os.popen`, :func:`os.fdopen`, and the :meth:`makefile` method
of socket objects (and perhaps by other functions or methods provided
by extension modules).
also :func:`os.popen`, :func:`os.fdopen`, and the
:meth:`~socket.socket.makefile` method of socket objects (and perhaps by
other functions or methods provided by extension modules).
The objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are
initialized to file objects corresponding to the interpreter's standard
@ -983,9 +983,9 @@ Internal types
single: stop (slice object attribute)
single: step (slice object attribute)
Special read-only attributes: :attr:`start` is the lower bound; :attr:`stop` is
the upper bound; :attr:`step` is the step value; each is ``None`` if omitted.
These attributes can have any type.
Special read-only attributes: :attr:`~slice.start` is the lower bound;
:attr:`~slice.stop` is the upper bound; :attr:`~slice.step` is the step
value; each is ``None`` if omitted. These attributes can have any type.
Slice objects support one method:
@ -1039,7 +1039,8 @@ When implementing a class that emulates any built-in type, it is important that
the emulation only be implemented to the degree that it makes sense for the
object being modelled. For example, some sequences may work well with retrieval
of individual elements, but extracting a slice may not make sense. (One example
of this is the :class:`NodeList` interface in the W3C's Document Object Model.)
of this is the :class:`~xml.dom.NodeList` interface in the W3C's Document
Object Model.)
.. _customization:
@ -1763,10 +1764,10 @@ case the instance is itself a class.
:pep:`3119` - Introducing Abstract Base Classes
Includes the specification for customizing :func:`isinstance` and
:func:`issubclass` behavior through :meth:`__instancecheck__` and
:meth:`__subclasscheck__`, with motivation for this functionality in the
context of adding Abstract Base Classes (see the :mod:`abc` module) to the
language.
:func:`issubclass` behavior through :meth:`~class.__instancecheck__` and
:meth:`~class.__subclasscheck__`, with motivation for this functionality
in the context of adding Abstract Base Classes (see the :mod:`abc`
module) to the language.
.. _callable-types:
@ -1796,9 +1797,10 @@ a sequence, the allowable keys should be the integers *k* for which ``0 <= k <
N`` where *N* is the length of the sequence, or slice objects, which define a
range of items. It is also recommended that mappings provide the methods
:meth:`keys`, :meth:`values`, :meth:`items`, :meth:`get`, :meth:`clear`,
:meth:`setdefault`, :meth:`pop`, :meth:`popitem`, :meth:`copy`, and
:meth:`setdefault`, :meth:`pop`, :meth:`popitem`, :meth:`!copy`, and
:meth:`update` behaving similar to those for Python's standard dictionary
objects. The :mod:`collections` module provides a :class:`MutableMapping`
objects. The :mod:`collections` module provides a
:class:`~collections.abc.MutableMapping`
abstract base class to help create those methods from a base set of
:meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and :meth:`keys`.
Mutable sequences should provide methods :meth:`append`, :meth:`count`,

29
Doc/reference/expressions.rst
View File

@ -336,10 +336,10 @@ the internal evaluation stack. When the execution is resumed by calling one of
the generator's methods, the function can proceed exactly as if the
:keyword:`yield` expression was just another external call. The value of the
:keyword:`yield` expression after resuming depends on the method which resumed
the execution. If :meth:`__next__` is used (typically via either a
the execution. If :meth:`~generator.__next__` is used (typically via either a
:keyword:`for` or the :func:`next` builtin) then the result is :const:`None`,
otherwise, if :meth:`send` is used, then the result will be the value passed
in to that method.
otherwise, if :meth:`~generator.send` is used, then the result will be the
value passed in to that method.
.. index:: single: coroutine
@ -352,16 +352,17 @@ transferred to the generator's caller.
:keyword:`yield` expressions are allowed in the :keyword:`try` clause of a
:keyword:`try` ... :keyword:`finally` construct. If the generator is not
resumed before it is finalized (by reaching a zero reference count or by being
garbage collected), the generator-iterator's :meth:`close` method will be
called, allowing any pending :keyword:`finally` clauses to execute.
garbage collected), the generator-iterator's :meth:`~generator.close` method
will be called, allowing any pending :keyword:`finally` clauses to execute.
When ``yield from <expr>`` is used, it treats the supplied expression as
a subiterator. All values produced by that subiterator are passed directly
to the caller of the current generator's methods. Any values passed in with
:meth:`send` and any exceptions passed in with :meth:`throw` are passed to
the underlying iterator if it has the appropriate methods. If this is not the
case, then :meth:`send` will raise :exc:`AttributeError` or :exc:`TypeError`,
while :meth:`throw` will just raise the passed in exception immediately.
:meth:`~generator.send` and any exceptions passed in with
:meth:`~generator.throw` are passed to the underlying iterator if it has the
appropriate methods. If this is not the case, then :meth:`~generator.send`
will raise :exc:`AttributeError` or :exc:`TypeError`, while
:meth:`~generator.throw` will just raise the passed in exception immediately.
When the underlying iterator is complete, the :attr:`~StopIteration.value`
attribute of the raised :exc:`StopIteration` instance becomes the value of
@ -388,6 +389,7 @@ Note that calling any of the generator methods below when the generator
is already executing raises a :exc:`ValueError` exception.
.. index:: exception: StopIteration
.. class:: generator
.. method:: generator.__next__()
@ -438,6 +440,7 @@ is already executing raises a :exc:`ValueError` exception.
other exception, it is propagated to the caller. :meth:`close` does nothing
if the generator has already exited due to an exception or normal exit.
.. class:: .
.. index:: single: yield; examples
@ -630,10 +633,10 @@ follows. If the slice list contains at least one comma, the key is a tuple
containing the conversion of the slice items; otherwise, the conversion of the
lone slice item is the key. The conversion of a slice item that is an
expression is that expression. The conversion of a proper slice is a slice
object (see section :ref:`types`) whose :attr:`start`, :attr:`stop` and
:attr:`step` attributes are the values of the expressions given as lower bound,
upper bound and stride, respectively, substituting ``None`` for missing
expressions.
object (see section :ref:`types`) whose :attr:`~slice.start`,
:attr:`~slice.stop` and :attr:`~slice.step` attributes are the values of the
expressions given as lower bound, upper bound and stride, respectively,
substituting ``None`` for missing expressions.
.. index::