From 279a7a0c9429f87c9e1f1042f580faf460b176e1 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 5 Nov 2021 09:49:40 -0700 Subject: bpo-45762: Improve docs for ``@singledispatch``/``@singledispatchmethod`` (GH-29426) (GH-29431) (cherry picked from commit 71e8a3e76a32f5eabe20e7fa984f384ca9af6ec6) Co-authored-by: Alex Waygood --- Doc/library/functools.rst | 48 ++++++++++++---------- .../2021-11-05-12-15-24.bpo-45726.GwRr7e.rst | 2 + 2 files changed, 28 insertions(+), 22 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2021-11-05-12-15-24.bpo-45726.GwRr7e.rst diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index e40fe7b..a01b172 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -402,8 +402,8 @@ The :mod:`functools` module defines the following functions: dispatch>` :term:`generic function`. To define a generic function, decorate it with the ``@singledispatch`` - decorator. Note that the dispatch happens on the type of the first argument, - create your function accordingly:: + decorator. When defining a function using ``@singledispatch``, note that the + dispatch happens on the type of the first argument:: >>> from functools import singledispatch >>> @singledispatch @@ -413,9 +413,9 @@ The :mod:`functools` module defines the following functions: ... print(arg) To add overloaded implementations to the function, use the :func:`register` - attribute of the generic function. It is a decorator. For functions - annotated with types, the decorator will infer the type of the first - argument automatically:: + attribute of the generic function, which can be used as a decorator. For + functions annotated with types, the decorator will infer the type of the + first argument automatically:: >>> @fun.register ... def _(arg: int, verbose=False): @@ -441,17 +441,17 @@ The :mod:`functools` module defines the following functions: ... - To enable registering lambdas and pre-existing functions, the - :func:`register` attribute can be used in a functional form:: + To enable registering :term:`lambdas` and pre-existing functions, + the :func:`register` attribute can also be used in a functional form:: >>> def nothing(arg, verbose=False): ... print("Nothing.") ... >>> fun.register(type(None), nothing) - The :func:`register` attribute returns the undecorated function which - enables decorator stacking, pickling, as well as creating unit tests for - each variant independently:: + The :func:`register` attribute returns the undecorated function. This + enables decorator stacking, :mod:`pickling`, and the creation + of unit tests for each variant independently:: >>> @fun.register(float) ... @fun.register(Decimal) @@ -486,11 +486,12 @@ The :mod:`functools` module defines the following functions: Where there is no registered implementation for a specific type, its method resolution order is used to find a more generic implementation. The original function decorated with ``@singledispatch`` is registered - for the base ``object`` type, which means it is used if no better + for the base :class:`object` type, which means it is used if no better implementation is found. - If an implementation registered to :term:`abstract base class`, virtual - subclasses will be dispatched to that implementation:: + If an implementation is registered to an :term:`abstract base class`, + virtual subclasses of the base class will be dispatched to that + implementation:: >>> from collections.abc import Mapping >>> @fun.register @@ -503,7 +504,7 @@ The :mod:`functools` module defines the following functions: >>> fun({"a": "b"}) a => b - To check which implementation will the generic function choose for + To check which implementation the generic function will choose for a given type, use the ``dispatch()`` attribute:: >>> fun.dispatch(float) @@ -526,7 +527,7 @@ The :mod:`functools` module defines the following functions: .. versionadded:: 3.4 .. versionchanged:: 3.7 - The :func:`register` attribute supports using type annotations. + The :func:`register` attribute now supports using type annotations. .. class:: singledispatchmethod(func) @@ -535,8 +536,9 @@ The :mod:`functools` module defines the following functions: dispatch>` :term:`generic function`. To define a generic method, decorate it with the ``@singledispatchmethod`` - decorator. Note that the dispatch happens on the type of the first non-self - or non-cls argument, create your function accordingly:: + decorator. When defining a function using ``@singledispatchmethod``, note + that the dispatch happens on the type of the first non-*self* or non-*cls* + argument:: class Negator: @singledispatchmethod @@ -552,9 +554,10 @@ The :mod:`functools` module defines the following functions: return not arg ``@singledispatchmethod`` supports nesting with other decorators such as - ``@classmethod``. Note that to allow for ``dispatcher.register``, - ``singledispatchmethod`` must be the *outer most* decorator. Here is the - ``Negator`` class with the ``neg`` methods being class bound:: + :func:`@classmethod`. Note that to allow for + ``dispatcher.register``, ``singledispatchmethod`` must be the *outer most* + decorator. Here is the ``Negator`` class with the ``neg`` methods bound to + the class, rather than an instance of the class:: class Negator: @singledispatchmethod @@ -572,8 +575,9 @@ The :mod:`functools` module defines the following functions: def _(cls, arg: bool): return not arg - The same pattern can be used for other similar decorators: ``staticmethod``, - ``abstractmethod``, and others. + The same pattern can be used for other similar decorators: + :func:`@staticmethod`, + :func:`@abstractmethod`, and others. .. versionadded:: 3.8 diff --git a/Misc/NEWS.d/next/Documentation/2021-11-05-12-15-24.bpo-45726.GwRr7e.rst b/Misc/NEWS.d/next/Documentation/2021-11-05-12-15-24.bpo-45726.GwRr7e.rst new file mode 100644 index 0000000..7ff6283 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2021-11-05-12-15-24.bpo-45726.GwRr7e.rst @@ -0,0 +1,2 @@ +Improve documentation for :func:`functools.singledispatch` and +:class:`functools.singledispatchmethod`. -- cgit v0.12