Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 8a1caa2

Browse filesBrowse files
birkenfeldbirkenfeld
committed
#6522: add a "decorator" directive to explicitly document decorators, and use it in a few places.
1 parent b0a4e3c commit 8a1caa2
Copy full SHA for 8a1caa2

File tree

Expand file treeCollapse file tree

7 files changed

+75
-16
lines changed
Filter options
Expand file treeCollapse file tree

7 files changed

+75
-16
lines changed

‎Doc/documenting/markup.rst

Copy file name to clipboardExpand all lines: Doc/documenting/markup.rst
+32Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -177,6 +177,34 @@ The directives are:
177177
are modified), side effects, and possible exceptions. A small example may be
178178
provided.
179179

180+
.. describe:: decorator
181+
182+
Describes a decorator function. The signature should *not* represent the
183+
signature of the actual function, but the usage as a decorator. For example,
184+
given the functions
185+
186+
.. code-block:: python
187+
188+
def removename(func):
189+
func.__name__ = ''
190+
return func
191+
192+
def setnewname(name):
193+
def decorator(func):
194+
func.__name__ = name
195+
return func
196+
return decorator
197+
198+
the descriptions should look like this::
199+
200+
.. decorator:: removename
201+
202+
Remove name of the decorated function.
203+
204+
.. decorator:: setnewname(name)
205+
206+
Set name of the decorated function to *name*.
207+
180208
.. describe:: class
181209

182210
Describes a class. The signature can include parentheses with parameters
@@ -194,6 +222,10 @@ The directives are:
194222
parameter. The description should include similar information to that
195223
described for ``function``.
196224

225+
.. describe:: decoratormethod
226+
227+
Same as ``decorator``, but for decorators that are methods.
228+
197229
.. describe:: opcode
198230

199231
Describes a Python :term:`bytecode` instruction.

‎Doc/library/abc.rst

Copy file name to clipboardExpand all lines: Doc/library/abc.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@ This module provides the following class:
122122

123123
It also provides the following decorators:
124124

125-
.. function:: abstractmethod(function)
125+
.. decorator:: abstractmethod(function)
126126

127127
A decorator indicating abstract methods.
128128

‎Doc/library/contextlib.rst

Copy file name to clipboardExpand all lines: Doc/library/contextlib.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ statement. For more information see also :ref:`typecontextmanager` and
1212
Functions provided:
1313

1414

15-
.. function:: contextmanager(func)
15+
.. decorator:: contextmanager
1616

1717
This function is a :term:`decorator` that can be used to define a factory
1818
function for :keyword:`with` statement context managers, without needing to

‎Doc/library/functools.rst

Copy file name to clipboardExpand all lines: Doc/library/functools.rst
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ The :mod:`functools` module defines the following functions:
3737

3838
.. versionadded:: 3.2
3939

40-
.. function:: total_ordering(cls)
40+
.. decorator:: total_ordering
4141

4242
Given a class defining one or more rich comparison ordering methods, this
4343
class decorator supplies the rest. This simplifies the effort involved
@@ -122,7 +122,7 @@ The :mod:`functools` module defines the following functions:
122122
than helpful.
123123

124124

125-
.. function:: wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)
125+
.. decorator:: wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)
126126

127127
This is a convenience function for invoking ``partial(update_wrapper,
128128
wrapped=wrapped, assigned=assigned, updated=updated)`` as a function decorator

‎Doc/library/importlib.rst

Copy file name to clipboardExpand all lines: Doc/library/importlib.rst
+3-3Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -469,7 +469,7 @@ find and load modules.
469469
This module contains the various objects that help in the construction of
470470
an :term:`importer`.
471471

472-
.. function:: module_for_loader(method)
472+
.. decorator:: module_for_loader
473473

474474
A :term:`decorator` for a :term:`loader` method,
475475
to handle selecting the proper
@@ -494,15 +494,15 @@ an :term:`importer`.
494494
Use of this decorator handles all the details of which module object a
495495
loader should initialize as specified by :pep:`302`.
496496

497-
.. function:: set_loader(fxn)
497+
.. decorator:: set_loader
498498

499499
A :term:`decorator` for a :term:`loader` method,
500500
to set the :attr:`__loader__`
501501
attribute on loaded modules. If the attribute is already set the decorator
502502
does nothing. It is assumed that the first positional argument to the
503503
wrapped method is what :attr:`__loader__` should be set to.
504504

505-
.. function:: set_package(fxn)
505+
.. decorator:: set_package
506506

507507
A :term:`decorator` for a :term:`loader` to set the :attr:`__package__`
508508
attribute on the module returned by the loader. If :attr:`__package__` is

‎Doc/library/unittest.rst

Copy file name to clipboardExpand all lines: Doc/library/unittest.rst
+8-8Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -621,20 +621,20 @@ the test unless the passed object has a certain attribute: ::
621621

622622
The following decorators implement test skipping and expected failures:
623623

624-
.. function:: skip(reason)
624+
.. decorator:: skip(reason)
625625

626626
Unconditionally skip the decorated test. *reason* should describe why the
627627
test is being skipped.
628628

629-
.. function:: skipIf(condition, reason)
629+
.. decorator:: skipIf(condition, reason)
630630

631631
Skip the decorated test if *condition* is true.
632632

633-
.. function:: skipUnless(condition, reason)
633+
.. decorator:: skipUnless(condition, reason)
634634

635635
Skip the decoratored test unless *condition* is true.
636636

637-
.. function:: expectedFailure
637+
.. decorator:: expectedFailure
638638

639639
Mark the test as an expected failure. If the test fails when run, the test
640640
is not counted as a failure.
@@ -1048,11 +1048,11 @@ Test cases
10481048
:attr:`exception` attribute. This can be useful if the intention
10491049
is to perform additional checks on the exception raised::
10501050

1051-
with self.assertRaises(SomeException) as cm:
1052-
do_something()
1051+
with self.assertRaises(SomeException) as cm:
1052+
do_something()
10531053

1054-
the_exception = cm.exception
1055-
self.assertEqual(the_exception.error_code, 3)
1054+
the_exception = cm.exception
1055+
self.assertEqual(the_exception.error_code, 3)
10561056

10571057
.. versionchanged:: 3.1
10581058
Added the ability to use :meth:`assertRaises` as a context manager.

‎Doc/tools/sphinxext/pyspecific.py

Copy file name to clipboardExpand all lines: Doc/tools/sphinxext/pyspecific.py
+28-1Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,32 @@ def run(self):
7272
return [pnode]
7373

7474

75+
# Support for documenting decorators
76+
77+
from sphinx import addnodes
78+
from sphinx.domains.python import PyModulelevel, PyClassmember
79+
80+
class PyDecoratorMixin(object):
81+
def handle_signature(self, sig, signode):
82+
ret = super(PyDecoratorMixin, self).handle_signature(sig, signode)
83+
signode.insert(0, addnodes.desc_addname('@', '@'))
84+
return ret
85+
86+
def needs_arglist(self):
87+
return False
88+
89+
class PyDecoratorFunction(PyDecoratorMixin, PyModulelevel):
90+
def run(self):
91+
# a decorator function is a function after all
92+
self.name = 'py:function'
93+
return PyModulelevel.run(self)
94+
95+
class PyDecoratorMethod(PyDecoratorMixin, PyClassmember):
96+
def run(self):
97+
self.name = 'py:method'
98+
return PyClassmember.run(self)
99+
100+
75101
# Support for building "topic help" for pydoc
76102

77103
pydoc_topic_labels = [
@@ -147,7 +173,6 @@ def finish(self):
147173
# Support for documenting Opcodes
148174

149175
import re
150-
from sphinx import addnodes
151176

152177
opcode_sig_re = re.compile(r'(\w+(?:\+\d)?)(?:\s*\((.*)\))?')
153178

@@ -197,3 +222,5 @@ def setup(app):
197222
app.add_description_unit('pdbcommand', 'pdbcmd', '%s (pdb command)',
198223
parse_pdb_command)
199224
app.add_description_unit('2to3fixer', '2to3fixer', '%s (2to3 fixer)')
225+
app.add_directive_to_domain('py', 'decorator', PyDecoratorFunction)
226+
app.add_directive_to_domain('py', 'decoratormethod', PyDecoratorMethod)

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.