diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst index adb9dc9a4879eb..5f2c5994a2e2bb 100644 --- a/Doc/howto/enum.rst +++ b/Doc/howto/enum.rst @@ -509,7 +509,7 @@ to use the standard :func:`repr`. .. note:: - Adding :deco:`~dataclasses.dataclass` decorator to :class:`Enum` + Adding :deco:`dataclass ` decorator to :class:`Enum` and its subclasses is not supported. It will not raise any errors, but it will produce very strange results at runtime, such as members being equal to each other:: diff --git a/Doc/howto/sorting.rst b/Doc/howto/sorting.rst index b511aa4e59fe1e..f20782e19f047e 100644 --- a/Doc/howto/sorting.rst +++ b/Doc/howto/sorting.rst @@ -372,7 +372,8 @@ Odds and Ends :meth:`~object.__lt__` is not implemented (see :func:`object.__lt__` for details on the mechanics). To avoid surprises, :pep:`8` recommends that all six comparison methods be implemented. - The :deco:`~functools.total_ordering` decorator is provided to make that + The :deco:`total_ordering ` decorator is provided + to make that task easier. * Key functions need not depend directly on the objects being sorted. A key diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index 666f8599744888..6757f01ffb544f 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -101,7 +101,8 @@ Functions and classes provided: .. decorator:: asynccontextmanager - Similar to :deco:`~contextlib.contextmanager`, but creates an + Similar to :deco:`contextmanager `, but creates + an :ref:`asynchronous context manager `. This function is a :term:`decorator` that can be used to define a factory diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 559a76bb3963e0..ec2d93e3efcaf4 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -115,7 +115,7 @@ Module contents :class:`StrEnum` defaults to the lower-cased version of the member name, while other Enums default to 1 and increase from there. - :deco:`~enum.property` + :deco:`property ` Allows :class:`Enum` members to have attributes without conflicting with member names. The ``value`` and ``name`` attributes are implemented this diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index debb7a7c3c2cc0..04146dbca530e5 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -709,7 +709,8 @@ The :mod:`!functools` module defines the following functions: return not arg The same pattern can be used for other similar decorators: - :deco:`staticmethod`, :deco:`~abc.abstractmethod`, and others. + :deco:`staticmethod`, :deco:`abstractmethod `, and + others. .. versionadded:: 3.8 diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst index 1e8acb0cb51c91..ede241cd64c95e 100644 --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -611,7 +611,7 @@ Available Functions The deprecation message passed to the decorator is saved in the ``__deprecated__`` attribute on the decorated object. If applied to an overload, the decorator - must be after the :deco:`~typing.overload` decorator + must be after the :deco:`overload ` decorator for the attribute to exist on the overload as returned by :func:`typing.get_overloads`. diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 2e0b6621eb11c8..e27ba8a255053c 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -2234,7 +2234,7 @@ some consistency rules, if possible: The last two expressions apply to totally ordered collections (e.g. to sequences, but not to sets or mappings). See also the - :deco:`~functools.total_ordering` decorator. + :deco:`total_ordering ` decorator. * The :func:`hash` result should be consistent with equality. Objects that are equal should either have the same hash value, diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst index 33d8b741ba1766..aff2eed1b30803 100644 --- a/Doc/whatsnew/2.5.rst +++ b/Doc/whatsnew/2.5.rst @@ -745,7 +745,8 @@ The contextlib module The new :mod:`contextlib` module provides some functions and a decorator that are useful for writing objects for use with the ':keyword:`with`' statement. -The decorator is called :deco:`~contextlib.contextmanager`, and lets you write a single +The decorator is called :deco:`contextmanager `, and +lets you write a single generator function instead of defining a new class. The generator should yield exactly one value. The code up to the :keyword:`yield` will be executed as the :meth:`~object.__enter__` method, and the value yielded will be the method's return diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index 3f4645d2b5b483..b5ea72ee6b1aef 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -431,7 +431,8 @@ The contextlib module The :mod:`contextlib` module provides some functions and a decorator that are useful when writing objects for use with the ':keyword:`with`' statement. -The decorator is called :deco:`~contextlib.contextmanager`, and lets you write +The decorator is called :deco:`contextmanager `, and +lets you write a single generator function instead of defining a new class. The generator should yield exactly one value. The code up to the :keyword:`yield` will be executed as the :meth:`~object.__enter__` method, and the value yielded will @@ -1274,7 +1275,8 @@ of :meth:`!draw_doubled`, though they can do so. An implementation of :meth:`!draw` is necessary, though; the ABC can't provide a useful generic implementation. -You can apply the :deco:`~abc.abstractmethod` decorator to methods such as +You can apply the :deco:`abstractmethod ` decorator to +methods such as :meth:`!draw` that must be implemented; Python will then raise an exception for classes that don't define the method. Note that the exception is only raised when you actually @@ -1558,8 +1560,9 @@ Some smaller changes made to the core Python language are: .. Revision 57619 -* Properties now have three decorators, :deco:`~property.getter`, - :deco:`~property.setter` and :deco:`~property.deleter`, that are +* Properties now have three decorators, :deco:`getter `, + :deco:`setter ` and :deco:`deleter `, that + are decorators providing useful shortcuts for adding a getter, setter or deleter function to an existing property. You would use them like this:: diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst index de90c37a38d38f..3c97d96f647de7 100644 --- a/Doc/whatsnew/2.7.rst +++ b/Doc/whatsnew/2.7.rst @@ -1267,7 +1267,8 @@ changes, or look through the Subversion logs for all the details. uploads thanks to an added *rest* parameter (patch by Pablo Mouzo; :issue:`6845`.) -* New class decorator: :deco:`~functools.total_ordering` in the :mod:`functools` +* New class decorator: :deco:`total_ordering ` in the + :mod:`functools` module takes a class that defines an :meth:`~object.__eq__` method and one of :meth:`~object.__lt__`, :meth:`~object.__le__`, :meth:`~object.__gt__`, or :meth:`~object.__ge__`, and generates the missing comparison methods. Since the diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst index 390b82d5a1fdc1..96d7488c6d9b4e 100644 --- a/Doc/whatsnew/3.10.rst +++ b/Doc/whatsnew/3.10.rst @@ -1485,7 +1485,8 @@ is a :class:`typing.TypedDict`. Subclasses of ``typing.Protocol`` which only have data variables declared will now raise a ``TypeError`` when checked with ``isinstance`` unless they -are decorated with :deco:`~typing.runtime_checkable`. Previously, these checks +are decorated with :deco:`runtime_checkable `. +Previously, these checks passed silently. Users should decorate their subclasses with the :deco:`!runtime_checkable` decorator if they want runtime protocols. diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 4adb5cbd1b7d3b..e948e51faa336b 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -388,7 +388,7 @@ Kumar Srinivasan and Graham Bleaney.) PEP 681: Data class transforms ------------------------------ -:deco:`~typing.dataclass_transform` may be used to +:deco:`dataclass_transform ` may be used to decorate a class, metaclass, or a function that is itself a decorator. The presence of ``@dataclass_transform()`` tells a static type checker that the decorated object performs runtime "magic" that transforms a class, @@ -686,7 +686,7 @@ enum * Added the :func:`~enum.member` and :func:`~enum.nonmember` decorators, to ensure the decorated object is/is not converted to an enum member. -* Added the :deco:`~enum.property` decorator, +* Added the :deco:`property ` decorator, which works like :deco:`property` except for enums. Use this instead of :func:`types.DynamicClassAttribute`. diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst index 78ddc627fcf4d7..dfd2b433340b50 100644 --- a/Doc/whatsnew/3.12.rst +++ b/Doc/whatsnew/3.12.rst @@ -1749,7 +1749,8 @@ Changes in the Python API around process-global resources, which are best managed from the main interpreter. (Contributed by Donghee Na in :gh:`99127`.) -* The undocumented locking behavior of :deco:`~functools.cached_property` +* The undocumented locking behavior of + :deco:`cached_property ` is removed, because it locked across all instances of the class, leading to high lock contention. This means that a cached property getter function could now run more than once for a single instance, if two threads race. For most simple diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst index c61eb659ccc0f6..2e585fe90f91c5 100644 --- a/Doc/whatsnew/3.2.rst +++ b/Doc/whatsnew/3.2.rst @@ -809,7 +809,8 @@ functools methods to fill in the remaining methods. For example, supplying *__eq__* and *__lt__* will enable - :deco:`~functools.total_ordering` to fill-in *__le__*, *__gt__* and *__ge__*:: + :deco:`total_ordering ` to fill-in *__le__*, + *__gt__* and *__ge__*:: @total_ordering class Student: @@ -1097,8 +1098,9 @@ logarithm of the gamma function: abc --- -The :mod:`abc` module now supports :deco:`~abc.abstractclassmethod` and -:deco:`~abc.abstractstaticmethod`. +The :mod:`abc` module now supports +:deco:`abstractclassmethod ` and +:deco:`abstractstaticmethod `. These tools make it possible to define an :term:`abstract base class` that requires a particular :deco:`classmethod` or :deco:`staticmethod` to be @@ -1155,7 +1157,8 @@ self-reference by displaying "..." in the recursive part of the representation string. To help write such :meth:`~object.__repr__` methods, the :mod:`reprlib` module has a new -decorator, :deco:`~reprlib.recursive_repr`, for detecting recursive calls to +decorator, :deco:`recursive_repr `, for detecting +recursive calls to :meth:`!__repr__` and substituting a placeholder string instead:: >>> class MyList(list): @@ -1241,7 +1244,8 @@ There is a new and slightly mind-blowing tool :term:`context manager` that does double duty as a function decorator. As a convenience, this new functionality is used by -:deco:`~contextlib.contextmanager` so that no extra effort is needed to support +:deco:`contextmanager ` so that no extra effort is +needed to support both roles. The basic idea is that both context managers and function decorators can be used @@ -1253,7 +1257,8 @@ write a pre-action or post-action wrapper that can be used in either role. For example, it is sometimes useful to wrap functions or groups of statements with a logger that can track the time of entry and time of exit. Rather than writing both a function decorator and a context manager for the task, the -:deco:`~contextlib.contextmanager` provides both capabilities in a single +:deco:`contextmanager ` provides both capabilities +in a single definition:: from contextlib import contextmanager diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst index 0067491c569cc0..9b08c3a781eac0 100644 --- a/Doc/whatsnew/3.4.rst +++ b/Doc/whatsnew/3.4.rst @@ -858,7 +858,8 @@ to behave like normal instance methods when included in a class definition. .. _whatsnew-singledispatch: -The new :deco:`~functools.singledispatch` decorator brings support for +The new :deco:`singledispatch ` decorator brings +support for single-dispatch generic functions to the Python standard library. Where object oriented programming focuses on grouping multiple operations on a common set of data into a class, a generic function focuses on grouping @@ -870,7 +871,8 @@ multiple implementations of an operation that allows it to work with :pep:`443` -- Single-dispatch generic functions PEP written and implemented by Łukasz Langa. -:deco:`~functools.total_ordering` now supports a return value of +:deco:`total_ordering ` now supports a return value +of :data:`NotImplemented` from the underlying comparison function. (Contributed by Katie Miller in :issue:`10042`.) diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst index 24a2ffbefd0cfb..34bd1be104d10f 100644 --- a/Doc/whatsnew/3.5.rst +++ b/Doc/whatsnew/3.5.rst @@ -1148,7 +1148,8 @@ functools .. _whatsnew-lrucache: -Most of the :deco:`~functools.lru_cache` machinery is now implemented in C, making +Most of the :deco:`lru_cache ` machinery is now +implemented in C, making it significantly faster. (Contributed by Matt Joiner, Alexey Kachayev, and Serhiy Storchaka in :issue:`14373`.) diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst index 6900c97e9546c9..f74dd9df0500ea 100644 --- a/Doc/whatsnew/3.7.rst +++ b/Doc/whatsnew/3.7.rst @@ -571,7 +571,8 @@ decimal operations to work with the correct context in asynchronous code. dataclasses ----------- -The new :deco:`~dataclasses.dataclass` decorator provides a way to declare +The new :deco:`dataclass ` decorator provides a way to +declare *data classes*. A data class describes its attributes using class variable annotations. Its constructor and other magic methods, such as :meth:`~object.__repr__`, :meth:`~object.__eq__`, and @@ -830,7 +831,7 @@ The new :func:`~contextlib.nullcontext` is a simpler and faster no-op context manager than :class:`~contextlib.ExitStack`. (Contributed by Jesse-Bakker in :issue:`10049`.) -The new :deco:`~contextlib.asynccontextmanager`, +The new :deco:`asynccontextmanager `, :class:`~contextlib.AbstractAsyncContextManager`, and :class:`~contextlib.AsyncExitStack` have been added to complement their synchronous counterparts. (Contributed