From 205dd4e14de77f9c8ed2903ddebbcf9968bbb6a9 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 12 Oct 2017 09:33:05 -0700 Subject: [PATCH] [3.6] bpo-31567: add or fix decorator markup in docs (GH-3959) (GH-3966) (cherry picked from commit 0e61e67a57deb4abc677808201d7cf3c38138e02) --- Doc/library/abc.rst | 2 +- Doc/library/functions.rst | 21 +++++++++++++++------ Doc/library/functools.rst | 4 ++-- Doc/library/test.rst | 2 +- Doc/library/typing.rst | 6 +++--- Lib/test/test_typing.py | 4 ++-- 6 files changed, 24 insertions(+), 15 deletions(-) diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst index 6001db32df4..9522dd62049 100644 --- a/Doc/library/abc.rst +++ b/Doc/library/abc.rst @@ -278,7 +278,7 @@ The :mod:`abc` module also provides the following decorators: :func:`abstractmethod`, making this decorator redundant. -.. decorator:: abstractproperty(fget=None, fset=None, fdel=None, doc=None) +.. decorator:: abstractproperty A subclass of the built-in :func:`property`, indicating an abstract property. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index bd4c94fcae1..7a7a84d1d42 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -182,9 +182,9 @@ are always available. They are listed here in alphabetical order. base 16). :exc:`ValueError` will be raised if *i* is outside that range. -.. function:: classmethod(function) +.. decorator:: classmethod - Return a class method for *function*. + Transform a method into a class method. A class method receives the class as implicit first argument, just like an instance method receives the instance. To declare a class method, use this @@ -1384,9 +1384,9 @@ are always available. They are listed here in alphabetical order. For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`. -.. function:: staticmethod(function) +.. decorator:: staticmethod - Return a static method for *function*. + Transform a method into a static method. A static method does not receive an implicit first argument. To declare a static method, use this idiom:: @@ -1405,12 +1405,21 @@ are always available. They are listed here in alphabetical order. :func:`classmethod` for a variant that is useful for creating alternate class constructors. + Like all decorators, it is also possible to call ``staticmethod`` as + a regular function and do something with its result. This is needed + in some cases where you need a reference to a function from a class + body and you want to avoid the automatic transformation to instance + method. For these cases, use this idiom: + + class C: + builtin_open = staticmethod(open) + For more information on static methods, consult the documentation on the standard type hierarchy in :ref:`types`. - .. index:: - single: string; str() (built-in function) +.. index:: + single: string; str() (built-in function) .. _func-str: .. class:: str(object='') diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 9a8defee546..28062c11890 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -264,9 +264,9 @@ The :mod:`functools` module defines the following functions: return value -.. decorator:: singledispatch(default) +.. decorator:: singledispatch - Transforms a function into a :term:`single-dispatch ` :term:`generic function`. To define a generic function, decorate it with the ``@singledispatch`` diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 9d4ff7ad8b4..1a3f8f9c5dc 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -440,7 +440,7 @@ The :mod:`test.support` module defines the following functions: otherwise. -.. decorator:: skip_unless_symlink() +.. decorator:: skip_unless_symlink A decorator for running tests that require support for symbolic links. diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index bd04f731a12..9883d8bbe86 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -897,17 +897,17 @@ The module defines the following classes, functions and decorators: See :pep:`484` for details and comparison with other typing semantics. -.. decorator:: no_type_check(arg) +.. decorator:: no_type_check Decorator to indicate that annotations are not type hints. - The argument must be a class or function; if it is a class, it + This works as class or function :term:`decorator`. With a class, it applies recursively to all methods defined in that class (but not to methods defined in its superclasses or subclasses). This mutates the function(s) in place. -.. decorator:: no_type_check_decorator(decorator) +.. decorator:: no_type_check_decorator Decorator to give another decorator the :func:`no_type_check` effect. diff --git a/Lib/test/test_typing.py b/Lib/test/test_typing.py index a3b2ea7f03e..ffefa8ed2dd 100644 --- a/Lib/test/test_typing.py +++ b/Lib/test/test_typing.py @@ -1471,8 +1471,8 @@ class ForwardRefTests(BaseTestCase): def test_meta_no_type_check(self): @no_type_check_decorator - def magic_decorator(deco): - return deco + def magic_decorator(func): + return func self.assertEqual(magic_decorator.__name__, 'magic_decorator')