8000 Docs: mark up NotImplemented using the :data: role throughout the doc… · python/cpython@dbe44f1 · GitHub
[go: up one dir, main page]
Skip to content
8000

Commit dbe44f1

Browse files
erlend-aaslanderlend-aasland
authored
Docs: mark up NotImplemented using the :data: role throughout the docs (#116135)
1 parent 0656509 commit dbe44f1

File tree

16 files changed

+39
-39
lines changed

16 files changed

+39
-39
lines changed

‎Doc/library/abc.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -101,11 +101,11 @@ a helper class :class:`ABC` to alternatively define ABCs through inheritance:
101101
subclass of the ABC. (This class method is called from the
102102
:meth:`~class.__subclasscheck__` method of the ABC.)
103103

104-
This method should return ``True``, ``False`` or ``NotImplemented``. If
104+
This method should return ``True``, ``False`` or :data:`NotImplemented`. If
105105
it returns ``True``, the *subclass* is considered a subclass of this ABC.
106106
If it returns ``False``, the *subclass* is not considered a subclass of
107107
this ABC, even if it would normally be one. If it returns
108-
``NotImplemented``, the subclass check is continued with the usual
108+
:data:`!NotImplemented`, the subclass check is continued with the usual
109109
mechanism.
110110

111111
.. XXX explain the "usual mechanism"

‎Doc/library/constants.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -33,27 +33,27 @@ A small number of constants live in the built-in namespace. They are:
3333
the other type; may be returned by the in-place binary special methods
3434
(e.g. :meth:`~object.__imul__`, :meth:`~object.__iand__`, etc.) for the same purpose.
3535
It should not be evaluated in a boolean context.
36-
``NotImplemented`` is the sole instance of the :data:`types.NotImplementedType` type.
36+
:data:`!NotImplemented` is the sole instance of the :data:`types.NotImplementedType` type.
3737

3838
.. note::
3939

40-
When a binary (or in-place) method returns ``NotImplemented`` the
40+
When a binary (or in-place) method returns :data:`!NotImplemented` the
4141
interpreter will try the reflected operation on the other type (or some
4242
other fallback, depending on the operator). If all attempts return
43-
``NotImplemented``, the interpreter will raise an appropriate exception.
44-
Incorrectly returning ``NotImplemented`` will result in a misleading
45-
error message or the ``NotImplemented`` value being returned to Python code.
43+
:data:`!NotImplemented`, the interpreter will raise an appropriate exception.
44+
Incorrectly returning :data:`!NotImplemented` will result in a misleading
45+
error message or the :data:`!NotImplemented` value being returned to Python code.
4646

4747
See :ref:`implementing-the-arithmetic-operations` for examples.
4848

4949
.. note::
5050

51-
``NotImplementedError`` and ``NotImplemented`` are not interchangeable,
51+
``NotImplementedError`` and :data:`!NotImplemented` are not interchangeable,
5252
even though they have similar names and purposes.
5353
See :exc:`NotImplementedError` for details on when to use it.
5454

5555
.. versionchanged:: 3.9
56-
Evaluating ``NotImplemented`` in a boolean context is deprecated. While
56+
Evaluating :data:`!NotImplemented` in a boolean context is deprecated. While
5757
it currently evaluates as true, it will emit a :exc:`DeprecationWarning`.
5858
It will raise a :exc:`TypeError` in a future version of Python.
5959

‎Doc/library/exceptions.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -335,9 +335,9 @@ The following exceptions are the exceptions that are usually raised.
335335

336336
.. note::
337337

338-
``NotImplementedError`` and ``NotImplemented`` are not interchangeable,
338+
``NotImplementedError`` and :data:`NotImplemented` are not interchangeable,
339339
even though they have similar names and purposes. See
340-
:data:`NotImplemented` for details on when to use it.
340+
:data:`!NotImplemented` for details on when to use it.
341341

342342
.. exception:: OSError([arg])
343343
OSError(errno, strerror[, filename[, winerror[, filename2]]])

‎Doc/library/importlib.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -265,7 +265,7 @@ ABC hierarchy::
265265
when invalidating the caches of all finders on :data:`sys.meta_path`.
266266

267267
.. versionchanged:: 3.4
268-
Returns ``None`` when called instead of ``NotImplemented``.
268+
Returns ``None`` when called instead of :data:`NotImplemented`.
269269

270270

271271
.. class:: PathEntryFinder

‎Doc/library/numbers.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,7 @@ Complex``. I'll consider ``a + b``:
166166
2. If ``A`` falls back to the boilerplate code, and it were to
167167
return a value from :meth:`~object.__add__`, we'd miss the possibility
168168
that ``B`` defines a more intelligent :meth:`~object.__radd__`, so the
169-
boilerplate should return :const:`NotImplemented` from
169+
boilerplate should return :data:`NotImplemented` from
170170
:meth:`!__add__`. (Or ``A`` may not implement :meth:`!__add__` at
171171
all.)
172172
3. Then ``B``'s :meth:`~object.__radd__` gets a chance. If it accepts

‎Doc/library/pickle.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -377,7 +377,7 @@ The :mod:`pickle` module exports three classes, :class:`Pickler`,
377377
Special reducer that can be defined in :class:`Pickler` subclasses. This
378378
method has priority over any reducer in the :attr:`dispatch_table`. It
379379
should conform to the same interface as a :meth:`~object.__reduce__` method, and
380-
can optionally return ``NotImplemented`` to fallback on
380+
can optionally return :data:`NotImplemented` to fallback on
381381
:attr:`dispatch_table`-registered reducers to pickle ``obj``.
382382

383383
For a detailed example, see :ref:`reducer_override`.
@@ -503,7 +503,7 @@ What can be pickled and unpickled?
503503
The following types can be pickled:
504504

505505
* built-in constants (``None``, ``True``, ``False``, ``Ellipsis``, and
506-
``NotImplemented``);
506+
:data:`NotImplemented`);
507507

508508
* integers, floating-point numbers, complex numbers;
509509

@@ -905,7 +905,7 @@ functions and classes.
905905
For those cases, it is possible to subclass from the :class:`Pickler` class and
906906
implement a :meth:`~Pickler.reducer_override` method. This method can return an
907907
arbitrary reduction tuple (see :meth:`~object.__reduce__`). It can alternatively return
908-
``NotImplemented`` to fallback to the traditional behavior.
908+
:data:`NotImplemented` to fallback to the traditional behavior.
909909

910910
If both the :attr:`~Pickler.dispatch_table` and
911911
:meth:`~Pickler.reducer_override` are defined, then

‎Doc/library/stdtypes.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5450,10 +5450,10 @@ The NotImplemented Object
54505450

54515451
This object is returned from comparisons and binary operations when they are
54525452
asked to operate on types they don't support. See :ref:`comparisons` for more
5453-
information. There is exactly one ``NotImplemented`` object.
5454-
``type(NotImplemented)()`` produces the singleton instance.
5453+
information. There is exactly one :data:`NotImplemented` object.
5454+
:code:`type(NotImplemented)()` produces the singleton instance.
54555455

5456-
It is written as ``NotImplemented``.
5456+
It is written as :code:`NotImplemented`.
54575457

54585458

54595459
.. _typesinternal:

‎Doc/library/unittest.mock.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2143,10 +2143,10 @@ to change the default.
21432143

21442144
Methods and their defaults:
21452145

2146-
* ``__lt__``: ``NotImplemented``
2147-
* ``__gt__``: ``NotImplemented``
2148-
* ``__le__``: ``NotImplemented``
2149-
* ``__ge__``: ``NotImplemented``
2146+
* ``__lt__``: :data:`NotImplemented`
2147+
* ``__gt__``: :data:`!NotImplemented`
2148+
* ``__le__``: :data:`!NotImplemented`
2149+
* ``__ge__``: :data:`!NotImplemented`
21502150
* ``__int__``: ``1``
21512151
* ``__contains__``: ``False``
21522152
* ``__len__``: ``0``

‎Doc/reference/datamodel.rst

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,7 @@ NotImplemented
159159
.. index:: pair: object; NotImplemented
160160

161161
This type has a single value. There is a single object with this value. This
162-
object is accessed through the built-in name ``NotImplemented``. Numeric methods
162+
object is accessed through the built-in name :data:`NotImplemented`. Numeric methods
163163
and rich comparison methods should return this value if they do not implement the
164164
operation for the operands provided. (The interpreter will then try the
165165
reflected operation, or some other fallback, depending on the operator.) It
@@ -170,7 +170,7 @@ See
170170
for more details.
171171

172172
.. versionchanged:: 3.9
173-
Evaluating ``NotImplemented`` in a boolean context is deprecated. While
173+
Evaluating :data:`NotImplemented` in a boolean context is deprecated. While
174174
it currently evaluat 10000 es as true, it will emit a :exc:`DeprecationWarning`.
175175
It will raise a :exc:`TypeError` in a future version of Python.
176176

@@ -1787,18 +1787,18 @@ Basic customization
17871787
``x.__ne__(y)``, ``x>y`` calls ``x.__gt__(y)``, and ``x>=y`` calls
17881788
``x.__ge__(y)``.
17891789

1790-
A rich comparison method may return the singleton ``NotImplemented`` if it does
1790+
A rich comparison method may return the singleton :data:`NotImplemented` if it does
17911791
not implement the operation for a given pair of arguments. By convention,
17921792
``False`` and ``True`` are returned for a successful comparison. However, these
17931793
methods can return any value, so if the comparison operator is used in a Boolean
17941794
context (e.g., in the condition of an ``if`` statement), Python will call
17951795
:func:`bool` on the value to determine if the result is true or false.
17961796

17971797
By default, ``object`` implements :meth:`__eq__` by using ``is``, returning
1798-
``NotImplemented`` in the case of a false comparison:
1798+
:data:`NotImplemented` in the case of a false comparison:
17991799
``True if x is y else NotImplemented``. For :meth:`__ne__`, by default it
18001800
delegates to :meth:`__eq__` and inverts the result unless it is
1801-
``NotImplemented``. There are no other implied relationships among the
1801+
:data:`!NotImplemented`. There are no other implied relationships among the
18021802
comparison operators or default implementations; for example, the truth of
18031803
``(x<y or x==y)`` does not imply ``x<=y``. To automatically generate ordering
18041804
operations from a single root operation, see :func:`functools.total_ordering`.
@@ -2828,7 +2828,7 @@ through the object's keys; for sequences, it should iterate through the values.
28282828
Called to implement :func:`operator.length_hint`. Should return an estimated
28292829
length for the object (which may be greater or less than the actual length).
28302830
The length must be an integer ``>=`` 0. The return value may also be
2831-
:const:`NotImplemented`, which is treated the same as if the
2831+
:data:`NotImplemented`, which is treated the same as if the
28322832
``__length_hint__`` method didn't exist at all. This method is purely an
28332833
optimization and is never required for correctness.
28342834

@@ -2980,7 +2980,7 @@ left undefined.
29802980
function is to be supported.
29812981

29822982
If one of those methods does not support the operation with the supplied
2983-
arguments, it should return ``NotImplemented``.
2983+
arguments, it should return :data:`NotImplemented`.
29842984

29852985

29862986
.. method:: object.__radd__(self, other)
@@ -3010,7 +3010,7 @@ left undefined.
30103010
types. [#]_ For instance, to evaluate the expression ``x - y``, where *y* is
30113011
an instance of a class that has an :meth:`__rsub__` method,
30123012
``type(y).__rsub__(y, x)`` is called if ``type(x).__sub__(x, y)`` returns
3013-
*NotImplemented*.
3013+
:data:`NotImplemented`.
30143014

30153015
.. index:: pair: built-in function; pow
30163016

@@ -3503,7 +3503,7 @@ An example of an asynchronous context manager class::
35033503
the behavior that ``None`` is not callable.
35043504
35053505
.. [#] "Does not support" here means that the class has no such method, or
3506-
the method returns ``NotImplemented``. Do not set the method to
3506+
the method returns :data:`NotImplemented`. Do not set the method to
35073507
``None`` if you want to force fallback to the right operand's reflected
35083508
method—that will instead have the opposite effect of explicitly
35093509
*blocking* such fallback.

‎Doc/reference/expressions.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1539,7 +1539,7 @@ built-in types.
15391539
``x == x`` are all false, while ``x != x`` is true. This behavior is
15401540
compliant with IEEE 754.
15411541

1542-
* ``None`` and ``NotImplemented`` are singletons. :PEP:`8` advises that
1542+
* ``None`` and :data:`NotImplemented` are singletons. :PEP:`8` advises that
15431543
comparisons for singletons should always be done with ``is`` or ``is not``,
15441544
never the equality operators.
15451545

0 commit comments

Comments
 (0)
0