[Python-checkins] r83234 - in python/branches/py3k/Doc: documenting/markup.rst library/abc.rst library/contextlib.rst library/functools.rst library/importlib.rst library/unittest.rst tools/sphinxext/pyspecific.py
georg.brandl
python-checkins at python.org
Thu Jul 29 18:01:11 CEST 2010
Author: georg.brandl
Date: Thu Jul 29 18:01:11 2010
New Revision: 83234
Log:
#6522: add a "decorator" directive to explicitly document decorators, and use it in a few places.
Modified:
python/branches/py3k/Doc/documenting/markup.rst
python/branches/py3k/Doc/library/abc.rst
python/branches/py3k/Doc/library/contextlib.rst
python/branches/py3k/Doc/library/functools.rst
python/branches/py3k/Doc/library/importlib.rst
python/branches/py3k/Doc/library/unittest.rst
python/branches/py3k/Doc/tools/sphinxext/pyspecific.py
Modified: python/branches/py3k/Doc/documenting/markup.rst
==============================================================================
--- python/branches/py3k/Doc/documenting/markup.rst (original)
+++ python/branches/py3k/Doc/documenting/markup.rst Thu Jul 29 18:01:11 2010
@@ -177,6 +177,34 @@
are modified), side effects, and possible exceptions. A small example may be
provided.
+.. describe:: decorator
+
+ Describes a decorator function. The signature should *not* represent the
+ signature of the actual function, but the usage as a decorator. For example,
+ given the functions
+
+ .. code-block:: python
+
+ def removename(func):
+ func.__name__ = ''
+ return func
+
+ def setnewname(name):
+ def decorator(func):
+ func.__name__ = name
+ return func
+ return decorator
+
+ the descriptions should look like this::
+
+ .. decorator:: removename
+
+ Remove name of the decorated function.
+
+ .. decorator:: setnewname(name)
+
+ Set name of the decorated function to *name*.
+
.. describe:: class
Describes a class. The signature can include parentheses with parameters
@@ -194,6 +222,10 @@
parameter. The description should include similar information to that
described for ``function``.
+.. describe:: decoratormethod
+
+ Same as ``decorator``, but for decorators that are methods.
+
.. describe:: opcode
Describes a Python :term:`bytecode` instruction.
Modified: python/branches/py3k/Doc/library/abc.rst
==============================================================================
--- python/branches/py3k/Doc/library/abc.rst (original)
+++ python/branches/py3k/Doc/library/abc.rst Thu Jul 29 18:01:11 2010
@@ -122,7 +122,7 @@
It also provides the following decorators:
-.. function:: abstractmethod(function)
+.. decorator:: abstractmethod(function)
A decorator indicating abstract methods.
Modified: python/branches/py3k/Doc/library/contextlib.rst
==============================================================================
--- python/branches/py3k/Doc/library/contextlib.rst (original)
+++ python/branches/py3k/Doc/library/contextlib.rst Thu Jul 29 18:01:11 2010
@@ -12,7 +12,7 @@
Functions provided:
-.. function:: contextmanager(func)
+.. decorator:: contextmanager
This function is a :term:`decorator` that can be used to define a factory
function for :keyword:`with` statement context managers, without needing to
Modified: python/branches/py3k/Doc/library/functools.rst
==============================================================================
--- python/branches/py3k/Doc/library/functools.rst (original)
+++ python/branches/py3k/Doc/library/functools.rst Thu Jul 29 18:01:11 2010
@@ -37,7 +37,7 @@
.. versionadded:: 3.2
-.. function:: total_ordering(cls)
+.. decorator:: total_ordering
Given a class defining one or more rich comparison ordering methods, this
class decorator supplies the rest. This simplifies the effort involved
@@ -122,7 +122,7 @@
than helpful.
-.. function:: wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)
+.. decorator:: wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)
This is a convenience function for invoking ``partial(update_wrapper,
wrapped=wrapped, assigned=assigned, updated=updated)`` as a function decorator
Modified: python/branches/py3k/Doc/library/importlib.rst
==============================================================================
--- python/branches/py3k/Doc/library/importlib.rst (original)
+++ python/branches/py3k/Doc/library/importlib.rst Thu Jul 29 18:01:11 2010
@@ -469,7 +469,7 @@
This module contains the various objects that help in the construction of
an :term:`importer`.
-.. function:: module_for_loader(method)
+.. decorator:: module_for_loader
A :term:`decorator` for a :term:`loader` method,
to handle selecting the proper
@@ -494,7 +494,7 @@
Use of this decorator handles all the details of which module object a
loader should initialize as specified by :pep:`302`.
-.. function:: set_loader(fxn)
+.. decorator:: set_loader
A :term:`decorator` for a :term:`loader` method,
to set the :attr:`__loader__`
@@ -502,7 +502,7 @@
does nothing. It is assumed that the first positional argument to the
wrapped method is what :attr:`__loader__` should be set to.
-.. function:: set_package(fxn)
+.. decorator:: set_package
A :term:`decorator` for a :term:`loader` to set the :attr:`__package__`
attribute on the module returned by the loader. If :attr:`__package__` is
Modified: python/branches/py3k/Doc/library/unittest.rst
==============================================================================
--- python/branches/py3k/Doc/library/unittest.rst (original)
+++ python/branches/py3k/Doc/library/unittest.rst Thu Jul 29 18:01:11 2010
@@ -621,20 +621,20 @@
The following decorators implement test skipping and expected failures:
-.. function:: skip(reason)
+.. decorator:: skip(reason)
Unconditionally skip the decorated test. *reason* should describe why the
test is being skipped.
-.. function:: skipIf(condition, reason)
+.. decorator:: skipIf(condition, reason)
Skip the decorated test if *condition* is true.
-.. function:: skipUnless(condition, reason)
+.. decorator:: skipUnless(condition, reason)
Skip the decoratored test unless *condition* is true.
-.. function:: expectedFailure
+.. decorator:: expectedFailure
Mark the test as an expected failure. If the test fails when run, the test
is not counted as a failure.
@@ -1048,11 +1048,11 @@
:attr:`exception` attribute. This can be useful if the intention
is to perform additional checks on the exception raised::
- with self.assertRaises(SomeException) as cm:
- do_something()
+ with self.assertRaises(SomeException) as cm:
+ do_something()
- the_exception = cm.exception
- self.assertEqual(the_exception.error_code, 3)
+ the_exception = cm.exception
+ self.assertEqual(the_exception.error_code, 3)
.. versionchanged:: 3.1
Added the ability to use :meth:`assertRaises` as a context manager.
Modified: python/branches/py3k/Doc/tools/sphinxext/pyspecific.py
==============================================================================
--- python/branches/py3k/Doc/tools/sphinxext/pyspecific.py (original)
+++ python/branches/py3k/Doc/tools/sphinxext/pyspecific.py Thu Jul 29 18:01:11 2010
@@ -72,6 +72,32 @@
return [pnode]
+# Support for documenting decorators
+
+from sphinx import addnodes
+from sphinx.domains.python import PyModulelevel, PyClassmember
+
+class PyDecoratorMixin(object):
+ def handle_signature(self, sig, signode):
+ ret = super(PyDecoratorMixin, self).handle_signature(sig, signode)
+ signode.insert(0, addnodes.desc_addname('@', '@'))
+ return ret
+
+ def needs_arglist(self):
+ return False
+
+class PyDecoratorFunction(PyDecoratorMixin, PyModulelevel):
+ def run(self):
+ # a decorator function is a function after all
+ self.name = 'py:function'
+ return PyModulelevel.run(self)
+
+class PyDecoratorMethod(PyDecoratorMixin, PyClassmember):
+ def run(self):
+ self.name = 'py:method'
+ return PyClassmember.run(self)
+
+
# Support for building "topic help" for pydoc
pydoc_topic_labels = [
@@ -147,7 +173,6 @@
# Support for documenting Opcodes
import re
-from sphinx import addnodes
opcode_sig_re = re.compile(r'(\w+(?:\+\d)?)(?:\s*\((.*)\))?')
@@ -197,3 +222,5 @@
app.add_description_unit('pdbcommand', 'pdbcmd', '%s (pdb command)',
parse_pdb_command)
app.add_description_unit('2to3fixer', '2to3fixer', '%s (2to3 fixer)')
+ app.add_directive_to_domain('py', 'decorator', PyDecoratorFunction)
+ app.add_directive_to_domain('py', 'decoratormethod', PyDecoratorMethod)
More information about the Python-checkins
mailing list