Issue #19190: Improve cross-references in builtin types and functions documentation.
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index d40452a..aabf234 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -226,8 +226,8 @@
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.
This function raises :exc:`SyntaxError` if the compiled source is invalid,
and :exc:`TypeError` if the source contains null bytes.
@@ -701,7 +701,7 @@
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, ''):
@@ -1013,10 +1013,10 @@
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(object):
def __init__(self):
@@ -1259,13 +1259,13 @@
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[, cmp[, key[, reverse]]])
@@ -1370,9 +1370,10 @@
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
@@ -1446,10 +1447,10 @@
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;
+ 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:`__dict__` attribute. For example, the
+ body and becomes the :attr:`~object.__dict__` attribute. For example, the
following two statements create identical :class:`type` objects:
>>> class X(object):
@@ -1513,7 +1514,7 @@
.. 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__`
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 756339d..cd7b683 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1734,11 +1734,11 @@
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.
As of Python 2.7, non-empty sets (not frozensets) can be created by placing a
comma-separated list of elements within braces, for example: ``{'jack',
@@ -2828,12 +2828,12 @@
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
@@ -3077,7 +3077,7 @@
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__