Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 0d85b5c

Browse files
serhiy-storchakaserhiy-storchaka
committed
Issue #19190: Improve cross-references in builtin types and functions documentation.
2 parents d51f423 + 0d196ed commit 0d85b5c

5 files changed

Lines changed: 100 additions & 91 deletions

File tree

‎Doc/glossary.rst‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -556,9 +556,9 @@ Glossary
556556
dictionaries. There are the local, global and built-in namespaces as well
557557
as nested namespaces in objects (in methods). Namespaces support
558558
modularity by preventing naming conflicts. For instance, the functions
559-
:func:`builtins.open` and :func:`os.open` are distinguished by their
560-
namespaces. Namespaces also aid readability and maintainability by making
561-
it clear which module implements a function. For instance, writing
559+
:func:`builtins.open <.open>` and :func:`os.open` are distinguished by
560+
their namespaces. Namespaces also aid readability and maintainability by
561+
making it clear which module implements a function. For instance, writing
562562
:func:`random.seed` or :func:`itertools.islice` makes it clear that those
563563
functions are implemented by the :mod:`random` and :mod:`itertools`
564564
modules, respectively.
@@ -583,8 +583,8 @@ Glossary
583583
new-style class
584584
Old name for the flavor of classes now used for all class objects. In
585585
earlier Python versions, only new-style classes could use Python's newer,
586-
versatile features like :attr:`__slots__`, descriptors, properties,
587-
:meth:`__getattribute__`, class methods, and static methods.
586+
versatile features like :attr:`~object.__slots__`, descriptors,
587+
properties, :meth:`__getattribute__`, class methods, and static methods.
588588

589589
object
590590
Any data with state (attributes or value) and defined behavior
@@ -803,7 +803,8 @@ Glossary
803803
type
804804
The type of a Python object determines what kind of object it is; every
805805
object has a type. An object's type is accessible as its
806-
:attr:`__class__` attribute or can be retrieved with ``type(obj)``.
806+
:attr:`~instance.__class__` attribute or can be retrieved with
807+
``type(obj)``.
807808

808809
universal newlines
809810
A manner of interpreting text streams in which all of the following are

‎Doc/library/functions.rst‎

Lines changed: 31 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -219,8 +219,8 @@ are always available. They are listed here in alphabetical order.
219219

220220
Future statements are specified by bits which can be bitwise ORed together to
221221
specify multiple statements. The bitfield required to specify a given feature
222-
can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature`
223-
instance in the :mod:`__future__` module.
222+
can be found as the :attr:`~__future__._Feature.compiler_flag` attribute on
223+
the :class:`~__future__._Feature` instance in the :mod:`__future__` module.
224224

225225
The argument *optimize* specifies the optimization level of the compiler; the
226226
default value of ``-1`` selects the optimization level of the interpreter as
@@ -717,7 +717,7 @@ are always available. They are listed here in alphabetical order.
717717

718718
One useful application of the second form of :func:`iter` is to read lines of
719719
a file until a certain line is reached. The following example reads a file
720-
until the :meth:`readline` method returns an empty string::
720+
until the :meth:`~io.TextIOBase.readline` method returns an empty string::
721721

722722
with open('mydata.txt') as fp:
723723
for line in iter(fp.readline, ''):
@@ -826,8 +826,8 @@ are always available. They are listed here in alphabetical order.
826826

827827
.. note::
828828

829-
:class:`object` does *not* have a :attr:`__dict__`, so you can't assign
830-
arbitrary attributes to an instance of the :class:`object` class.
829+
:class:`object` does *not* have a :attr:`~object.__dict__`, so you can't
830+
assign arbitrary attributes to an instance of the :class:`object` class.
831831

832832

833833
.. function:: oct(x)
@@ -905,9 +905,9 @@ are always available. They are listed here in alphabetical order.
905905
size" and falling back on :attr:`io.DEFAULT_BUFFER_SIZE`. On many systems,
906906
the buffer will typically be 4096 or 8192 bytes long.
907907

908-
* "Interactive" text files (files for which :meth:`isatty` returns True) use
909-
line buffering. Other text files use the policy described above for binary
910-
files.
908+
* "Interactive" text files (files for which :meth:`~io.IOBase.isatty`
909+
returns True) use line buffering. Other text files use the policy
910+
described above for binary files.
911911

912912
*encoding* is the name of the encoding used to decode or encode the file.
913913
This should only be used in text mode. The default encoding is platform
@@ -1115,10 +1115,10 @@ are always available. They are listed here in alphabetical order.
11151115
turns the :meth:`voltage` method into a "getter" for a read-only attribute
11161116
with the same name.
11171117

1118-
A property object has :attr:`getter`, :attr:`setter`, and :attr:`deleter`
1119-
methods usable as decorators that create a copy of the property with the
1120-
corresponding accessor function set to the decorated function. This is
1121-
best explained with an example::
1118+
A property object has :attr:`~property.getter`, :attr:`~property.setter`,
1119+
and :attr:`~property.deleter` methods usable as decorators that create a
1120+
copy of the property with the corresponding accessor function set to the
1121+
decorated function. This is best explained with an example::
11221122

11231123
class C:
11241124
def __init__(self):
@@ -1224,13 +1224,13 @@ are always available. They are listed here in alphabetical order.
12241224

12251225
Return a :term:`slice` object representing the set of indices specified by
12261226
``range(start, stop, step)``. The *start* and *step* arguments default to
1227-
``None``. Slice objects have read-only data attributes :attr:`start`,
1228-
:attr:`stop` and :attr:`step` which merely return the argument values (or their
1229-
default). They have no other explicit functionality; however they are used by
1230-
Numerical Python and other third party extensions. Slice objects are also
1231-
generated when extended indexing syntax is used. For example:
1232-
``a[start:stop:step]`` or ``a[start:stop, i]``. See :func:`itertools.islice`
1233-
for an alternate version that returns an iterator.
1227+
``None``. Slice objects have read-only data attributes :attr:`~slice.start`,
1228+
:attr:`~slice.stop` and :attr:`~slice.step` which merely return the argument
1229+
values (or their default). They have no other explicit functionality;
1230+
however they are used by Numerical Python and other third party extensions.
1231+
Slice objects are also generated when extended indexing syntax is used. For
1232+
example: ``a[start:stop:step]`` or ``a[start:stop, i]``. See
1233+
:func:`itertools.islice` for an alternate version that returns an iterator.
12341234

12351235

12361236
.. function:: sorted(iterable[, key][, reverse])
@@ -1310,9 +1310,10 @@ are always available. They are listed here in alphabetical order.
13101310
been overridden in a class. The search order is same as that used by
13111311
:func:`getattr` except that the *type* itself is skipped.
13121312

1313-
The :attr:`__mro__` attribute of the *type* lists the method resolution
1314-
search order used by both :func:`getattr` and :func:`super`. The attribute
1315-
is dynamic and can change whenever the inheritance hierarchy is updated.
1313+
The :attr:`~class.__mro__` attribute of the *type* lists the method
1314+
resolution search order used by both :func:`getattr` and :func:`super`. The
1315+
attribute is dynamic and can change whenever the inheritance hierarchy is
1316+
updated.
13161317

13171318
If the second argument is omitted, the super object returned is unbound. If
13181319
the second argument is an object, ``isinstance(obj, type)`` must be true. If
@@ -1375,19 +1376,20 @@ are always available. They are listed here in alphabetical order.
13751376

13761377

13771378
With one argument, return the type of an *object*. The return value is a
1378-
type object and generally the same object as returned by ``object.__class__``.
1379+
type object and generally the same object as returned by
1380+
:attr:`object.__class__ <instance.__class__>`.
13791381

13801382
The :func:`isinstance` built-in function is recommended for testing the type
13811383
of an object, because it takes subclasses into account.
13821384

13831385

13841386
With three arguments, return a new type object. This is essentially a
13851387
dynamic form of the :keyword:`class` statement. The *name* string is the
1386-
class name and becomes the :attr:`__name__` attribute; the *bases* tuple
1387-
itemizes the base classes and becomes the :attr:`__bases__` attribute;
1388-
and the *dict* dictionary is the namespace containing definitions for class
1389-
body and becomes the :attr:`__dict__` attribute. For example, the
1390-
following two statements create identical :class:`type` objects:
1388+
class name and becomes the :attr:`~class.__name__` attribute; the *bases*
1389+
tuple itemizes the base classes and becomes the :attr:`~class.__bases__`
1390+
attribute; and the *dict* dictionary is the namespace containing definitions
1391+
for class body and becomes the :attr:`~object.__dict__` attribute. For
1392+
example, the following two statements create identical :class:`type` objects:
13911393

13921394
>>> class X:
13931395
... a = 1
@@ -1399,7 +1401,7 @@ are always available. They are listed here in alphabetical order.
13991401

14001402
.. function:: vars([object])
14011403

1402-
Return the :attr:`__dict__` attribute for a module, class, instance,
1404+
Return the :attr:`~object.__dict__` attribute for a module, class, instance,
14031405
or any other object with a :attr:`__dict__` attribute.
14041406

14051407
Objects such as modules and instances have an updateable :attr:`__dict__`

‎Doc/library/stdtypes.rst‎

Lines changed: 22 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -339,8 +339,8 @@ Notes:
339339
pair: C; language
340340

341341
Conversion from floating point to integer may round or truncate
342-
as in C; see functions :func:`floor` and :func:`ceil` in the :mod:`math` module
343-
for well-defined conversions.
342+
as in C; see functions :func:`math.floor` and :func:`math.ceil` for
343+
well-defined conversions.
344344

345345
(4)
346346
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`,
631631
:class:`float`, :class:`decimal.Decimal` and :class:`fractions.Fraction`)
632632
Python's hash for numeric types is based on a single mathematical function
633633
that's defined for any rational number, and hence applies to all instances of
634-
:class:`int` and :class:`fraction.Fraction`, and all finite instances of
634+
:class:`int` and :class:`fractions.Fraction`, and all finite instances of
635635
:class:`float` and :class:`decimal.Decimal`. Essentially, this function is
636636
given by reduction modulo ``P`` for a fixed prime ``P``. The value of ``P`` is
637637
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
13031303
only stores the ``start``, ``stop`` and ``step`` values, calculating individual
13041304
items and subranges as needed).
13051305

1306-
Range objects implement the :class:`collections.Sequence` ABC, and provide
1306+
Range objects implement the :class:`collections.abc.Sequence` ABC, and provide
13071307
features such as containment tests, element index lookup, slicing and
13081308
support for negative indices (see :ref:`typesseq`):
13091309

@@ -1326,9 +1326,9 @@ support for negative indices (see :ref:`typesseq`):
13261326
Testing range objects for equality with ``==`` and ``!=`` compares
13271327
them as sequences. That is, two range objects are considered equal if
13281328
they represent the same sequence of values. (Note that two range
1329-
objects that compare equal might have different :attr:`start`,
1330-
:attr:`stop` and :attr:`step` attributes, for example ``range(0) ==
1331-
range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.)
1329+
objects that compare equal might have different :attr:`~range.start`,
1330+
:attr:`~range.stop` and :attr:`~range.step` attributes, for example
1331+
``range(0) == range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.)
13321332

13331333
.. versionchanged:: 3.2
13341334
Implement the Sequence ABC.
@@ -1342,7 +1342,8 @@ range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.)
13421342
object identity).
13431343

13441344
.. versionadded:: 3.3
1345-
The :attr:`start`, :attr:`stop` and :attr:`step` attributes.
1345+
The :attr:`~range.start`, :attr:`~range.stop` and :attr:`~range.step`
1346+
attributes.
13461347

13471348

13481349
.. index::
@@ -2298,7 +2299,7 @@ in the range 0 to 255 (inclusive) as well as bytes and byte array sequences.
22982299
(inclusive) as their first argument.
22992300

23002301

2301-
Each bytes and bytearray instance provides a :meth:`decode` convenience
2302+
Each bytes and bytearray instance provides a :meth:`~bytes.decode` convenience
23022303
method that is the inverse of :meth:`str.encode`:
23032304

23042305
.. method:: bytes.decode(encoding="utf-8", errors="strict")
@@ -2809,11 +2810,11 @@ other sequence-like behavior.
28092810

28102811
There are currently two built-in set types, :class:`set` and :class:`frozenset`.
28112812
The :class:`set` type is mutable --- the contents can be changed using methods
2812-
like :meth:`add` and :meth:`remove`. Since it is mutable, it has no hash value
2813-
and cannot be used as either a dictionary key or as an element of another set.
2814-
The :class:`frozenset` type is immutable and :term:`hashable` --- its contents cannot be
2815-
altered after it is created; it can therefore be used as a dictionary key or as
2816-
an element of another set.
2813+
like :meth:`~set.add` and :meth:`~set.remove`. Since it is mutable, it has no
2814+
hash value and cannot be used as either a dictionary key or as an element of
2815+
another set. The :class:`frozenset` type is immutable and :term:`hashable` ---
2816+
its contents cannot be altered after it is created; it can therefore be used as
2817+
a dictionary key or as an element of another set.
28172818

28182819
Non-empty sets (not frozensets) can be created by placing a comma-separated list
28192820
of elements within braces, for example: ``{'jack', 'sjoerd'}``, in addition to the
@@ -3354,12 +3355,12 @@ statement is not, strictly speaking, an operation on a module object; ``import
33543355
foo`` does not require a module object named *foo* to exist, rather it requires
33553356
an (external) *definition* for a module named *foo* somewhere.)
33563357

3357-
A special attribute of every module is :attr:`__dict__`. This is the dictionary
3358-
containing the module's symbol table. Modifying this dictionary will actually
3359-
change the module's symbol table, but direct assignment to the :attr:`__dict__`
3360-
attribute is not possible (you can write ``m.__dict__['a'] = 1``, which defines
3361-
``m.a`` to be ``1``, but you can't write ``m.__dict__ = {}``). Modifying
3362-
:attr:`__dict__` directly is not recommended.
3358+
A special attribute of every module is :attr:`~object.__dict__`. This is the
3359+
dictionary containing the module's symbol table. Modifying this dictionary will
3360+
actually change the module's symbol table, but direct assignment to the
3361+
:attr:`__dict__` attribute is not possible (you can write
3362+
``m.__dict__['a'] = 1``, which defines ``m.a`` to be ``1``, but you can't write
3363+
``m.__dict__ = {}``). Modifying :attr:`__dict__` directly is not recommended.
33633364

33643365
Modules built into the interpreter are written like this: ``<module 'sys'
33653366
(built-in)>``. If loaded from a file, they are written as ``<module 'os' from
@@ -3594,7 +3595,7 @@ types, where they are relevant. Some of these are not reported by the
35943595

35953596
This method can be overridden by a metaclass to customize the method
35963597
resolution order for its instances. It is called at class instantiation, and
3597-
its result is stored in :attr:`__mro__`.
3598+
its result is stored in :attr:`~class.__mro__`.
35983599

35993600

36003601
.. method:: class.__subclasses__

0 commit comments

Comments
 (0)