From ab1cbff0217c0f3db18b6f6a5061e8d955b5f29e Mon Sep 17 00:00:00 2001 From: Michele Simionato Date: Sat, 16 Mar 2019 07:40:19 +0100 Subject: Doc fixes --- docs/documentation.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/documentation.md b/docs/documentation.md index 2c0db63..72ab411 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -111,19 +111,20 @@ can be used as a decorator. However, this definition is somewhat too large to be really useful. It is more convenient to split the generic class of decorators in two subclasses: -*signature-preserving* decorators: - Callable objects which accept a function as input and return - a function as output, *with the same signature*. -*signature-changing* decorators: - Decorators which change the signature of their input function, - or decorators that return non-callable objects. - -**Signature-changing** decorators have their use: for instance, the +1. **signature-preserving decorators**, callable objects which accept + a function as input and return a function as output, *with the + same signature* + +2. **signature-changing** decorators, i.e. decorators + which change the signature of their input function, or decorators + that return non-callable objects + +Signature-changing decorators have their use: for instance, the builtin classes ``staticmethod`` and ``classmethod`` are in this group. They take functions and return descriptor objects which are neither functions, nor callables. -Still, **signature-preserving** decorators are more common, and easier +Still, signature-preserving decorators are more common, and easier to reason about. In particular, they can be composed together, whereas other decorators generally cannot. @@ -218,7 +219,7 @@ Python 3.5. This is pretty bad: ``pydoc`` will tell you that the function accepts the generic signature ``*args, **kw``, but calling the function with more than one argument raises an error: -``` +```python >>> f1(0, 1) Traceback (most recent call last): ... @@ -371,7 +372,8 @@ FullArgSpec(args=['x', 'y', 'z'], varargs='args', varkw='kw', defaults=(1, 2), k Function annotations --------------------------------------------- -Python 3 introduced the concept of `function annotations`_: the ability +Python 3 introduced the concept of [function annotations]( +http://www.python.org/dev/peps/pep-3107/): the ability to annotate the signature of a function with additional information, stored in a dictionary named ``__annotations__``. The ``decorator`` module (starting from release 3.3) will understand and preserve these annotations. @@ -609,6 +611,8 @@ TypeError: You are decorating a non function: ``` +Be careful! + ``decorator(cls)`` -------------------------------------------- -- cgit v1.2.1