閱讀 Michele Simionato 先生寫作之

The decorator module

Author:	Michele Simionato
E-mail:	michele.simionato@gmail.com
Version:	4.1.1 (2017-07-16)
Supports:	Python 2.6, 2.7, 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6
Download page:	http://pypi.python.org/pypi/decorator/4.1.1
Installation:	pip install decorator
License:	BSD license

說明文件︰

 

讓人眼界大開，了解『裝飾子』之用處︰

 

而且點出不留心、可能生潛在問題︰

Statement of the problem

A very common use case for decorators is the memoization of functions. A memoize decorator works by caching the result of the function call in a dictionary, so that the next time the function is called with the same input parameters the result is retrieved from the cache and not recomputed.

There are many implementations of memoize in http://www.python.org/moin/PythonDecoratorLibrary, but they do not preserve the signature. In recent versions of Python you can find a sophisticated lru_cache decorator in the standard library’s functools. Here I am just interested in giving an example.

Consider the following simple implementation (note that it is generally impossible to correctly memoize something that depends on non-hashable arguments):

def memoize_uw(func):
    func.cache = {}

    def memoize(*args, **kw):
        if kw:  # frozenset is used to ensure hashability
            key = args, frozenset(kw.items())
        else:
            key = args
        if key not in func.cache:
            func.cache[key] = func(*args, **kw)
        return func.cache[key]
    return functools.update_wrapper(memoize, func)

 

Here I used the functools.update_wrapper utility, which was added in Python 2.5 to simplify the writing of decorators. (Previously, you needed to manually copy the function attributes __name__, __doc__, __module__, and __dict__ to the decorated function by hand).

Here is an example of usage:

@memoize_uw
def f1(x):
    "Simulate some long computation"
    time.sleep(1)
    return x

 

This works insofar as the decorator accepts functions with generic signatures. Unfortunately, it is not a signature-preserving decorator, since memoize_uw generally returns a function with a different signature from the original.

Consider for instance the following case:

@memoize_uw
def f1(x):
    "Simulate some long computation"
    time.sleep(1)
    return x

 

Here, the original function takes a single argument named x, but the decorated function takes any number of arguments and keyword arguments:

>>> from decorator import getargspec  # akin to inspect.getargspec
>>> print(getargspec(f1))
ArgSpec(args=[], varargs='args', varkw='kw', defaults=None)

 

This means that introspection tools (like pydoc) will give false information about the signature of f1 – unless you are using 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:

>>> f1(0, 1)
Traceback (most recent call last):
   ...
TypeError: f1() takes exactly 1 positional argument (2 given)

 

Notice that inspect.getargspec and inspect.getfullargspec will give the wrong signature. This even occurs in Python 3.5, although both functions were deprecated in that release.

※ 參考

pi@raspberrypi:~ $ python3
Python 3.5.3 (default, Jan 19 2017, 14:11:04) 
[GCC 6.3.0 20170124] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import functools
>>> import time
>>> 
>>> def memoize_uw(func):
...     func.cache = {}
...     def memoize(*args, **kw):
...         if kw:  # frozenset is used to ensure hashability
...             key = args, frozenset(kw.items())
...         else:
...             key = args
...         if key not in func.cache:
...             func.cache[key] = func(*args, **kw)
...         return func.cache[key]
...     return functools.update_wrapper(memoize, func)
... 
>>> @memoize_uw
... def f1(x):
...     "Simulate some long computation"
...     time.sleep(1)
...     return x
... 
>>> f1(3)
3
>>> from decorator import getargspec
>>> print(getargspec(f1))
ArgSpec(args=[], varargs='args', varkw='kw', defaults=None)
>>> 
>>> f1(0,1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 9, in memoize
TypeError: f1() takes 1 positional argument but 2 were given
>>> 
>>> import inspect
>>> print(inspect.getargspec(f1))
ArgSpec(args=[], varargs='args', keywords='kw', defaults=None)
>>> 

 

派生程式學習者或該反思

PEP 362 — Function Signature Object

Signature Object

A Signature object represents the call signature of a function and its return annotation. For each parameter accepted by the function it stores a Parameter object in its parameters collection.

A Signature object has the following public attributes and methods:

• return_annotation : object

  The “return” annotation for the function. If the function has no “return” annotation, this attribute is set to Signature.empty.

• parameters : OrderedDict

  An ordered mapping of parameters’ names to the corresponding Parameter objects.

• bind(*args, **kwargs) -> BoundArguments

  Creates a mapping from positional and keyword arguments to parameters. Raises a TypeError if the passed arguments do not match the signature.

• bind_partial(*args, **kwargs) -> BoundArguments

  Works the same way as bind(), but allows the omission of some required arguments (mimics functools.partial behavior.) Raises a TypeError if the passed arguments do not match the signature.

• replace(parameters=<optional>, *, return_annotation=<optional>) -> Signature

  Creates a new Signature instance based on the instance replace was invoked on. It is possible to pass different parameters and/or return_annotation to override the corresponding properties of the base signature. To remove return_annotation from the copied Signature, pass in Signature.empty.

  Note that the ‘=<optional>’ notation, means that the argument is optional. This notation applies to the rest of this PEP.

 

的內容！評估實踐之反省？

29.12.3. Introspecting callables with the Signature object

The Signature object represents the call signature of a callable object and its return annotation. To retrieve a Signature object, use the signature() function.

inspect.signature(callable, *, follow_wrapped=True)

Return a Signature object for the given callable:

>>> from inspect import signature
>>> def foo(a, *, b:int, **kwargs):
...     pass

>>> sig = signature(foo)

>>> str(sig)
'(a, *, b:int, **kwargs)'

>>> str(sig.parameters['b'])
'b:int'

>>> sig.parameters['b'].annotation
<class 'int'>

 

Accepts a wide range of python callables, from plain functions and classes to functools.partial() objects.

Raises ValueError if no signature can be provided, and TypeError if that type of object is not supported.