[Python-checkins] [3.6] bpo-31567: add or fix decorator markup in docs (GH-3959) (GH-3966)
Éric Araujo
webhook-mailer at python.org
Thu Oct 12 12:33:08 EDT 2017
https://github.com/python/cpython/commit/205dd4e14de77f9c8ed2903ddebbcf9968bbb6a9
commit: 205dd4e14de77f9c8ed2903ddebbcf9968bbb6a9
branch: 3.6
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Éric Araujo <merwok at users.noreply.github.com>
date: 2017-10-12T12:33:05-04:00
summary:
[3.6] bpo-31567: add or fix decorator markup in docs (GH-3959) (GH-3966)
(cherry picked from commit 0e61e67a57deb4abc677808201d7cf3c38138e02)
files:
M Doc/library/abc.rst
M Doc/library/functions.rst
M Doc/library/functools.rst
M Doc/library/test.rst
M Doc/library/typing.rst
M Lib/test/test_typing.py
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 <single
+ Transform a function into a :term:`single-dispatch <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 D(C):
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')
More information about the Python-checkins
mailing list