diff options
Diffstat (limited to 'documentation.rst')
| -rw-r--r-- | documentation.rst | 38 |
1 files changed, 26 insertions, 12 deletions
diff --git a/documentation.rst b/documentation.rst index 79f3b06..2c4aa7d 100644 --- a/documentation.rst +++ b/documentation.rst @@ -894,8 +894,8 @@ Now the XMLWriter is able to serialize floats: I could give a down-to-earth example of situations in which it is desiderable to dispatch on more than one argument (for instance once I implemented a database-access library where the first dispatching argument was the -the database driver and the second the database record), but here I prefer -to follow the tradition and show the time-honored +the database driver and the second one was the database record), +but here I prefer to follow the tradition and show the time-honored Rock-Paper-Scissor example: .. code-block:: python @@ -1038,8 +1038,8 @@ The implementation of generic functions in the decorator module is still experimental. In this initial phase implicity was preferred over consistency with the way ``functools.singledispatch`` works in the standard library. So there some subtle differences in special -case. I will only show an example. -Suppose with are using a third party set-like class like +cases. I will only show an example. +Suppose you are using a third party set-like class like the following: .. code-block:: python @@ -1048,7 +1048,7 @@ the following: # methods that make SomeSet set-like # not shown ... def __len__(self): - return 0 + return 0 # in reality one would return more than zero Here the author of ``SomeSet`` made a mistake by not inheriting @@ -1084,7 +1084,11 @@ Generic functions implemented via ``functools.singledispatch`` use a more sophisticated lookup algorithm; in particular they are able to discern that a ``Set`` is a ``Sized`` object, so the implementation for ``Set`` is taken and the result is 1, not 0. -Also, the functions implemented via ``functools.singledispatch`` +Still, the implementation in the decorator module is easy to +undestand, once one declare that real ancestors take the precedence +over virtual ancestors. + +The functions implemented via ``functools.singledispatch`` are smarter when there are conflicting implementations and are able to solve more potential conflicts. Just to have an idea of what I am talking about, here is a situation with a conflict: @@ -1101,10 +1105,11 @@ of what I am talking about, here is a situation with a conflict: RuntimeError: Ambiguous dispatch for WithLength instance: Sized or Iterable? Since ``WithLength`` is both a (virtual) subclass -of ``collections.Iterable`` and of ``collections.Sized``, it is impossible +of ``collections.Iterable`` and of ``collections.Sized``, which are +not related by subclassing, it is impossible to decide which implementation should be taken. Consistently with the *refuse the temptation to guess* philosophy, an error is raised. -``functools.singledispatch`` works exactly the same in this case. +``functools.singledispatch`` would work exactly the same in this case. Finally let me notice that the decorator module implementation does not use any cache, whereas the one in ``singledispatch`` has a cache. @@ -1147,8 +1152,9 @@ performance penalty could be completely negligible. As always, the only way to know if there is a penalty in your specific use case is to measure it. -You should be aware that decorators will make your tracebacks -longer and more difficult to understand. Consider this example: +More importantly, you should be aware that decorators will make your +tracebacks longer and more difficult to understand. Consider this +example: .. code-block:: python @@ -1184,17 +1190,25 @@ would require to change the CPython implementation of functions and add an hook to make it possible to change their signature directly. That could happen in future versions of Python (see PEP 362_) and then the decorator module would become obsolete. However, at present, -even in Python 3.5 it is impossible to change the function signature +even in Python 3.4 it is impossible to change the function signature directly, therefore the ``decorator`` module is still useful. Actually, this is the main reasons why I keep maintaining the module and releasing new versions. +It should be noticed that in Python 3.5 a lot of improvements +have been made: in that version you can decorated a function +with ``func_tools.update_wrapper`` and ``pydoc`` will see the correct +signature; still internally the function will have an incorrect +signature, as you can see by using ``inspect.getfullargspec``: +all documentation tools using such function (which has been +correctly deprecated) will see the wrong signature. .. _362: http://www.python.org/dev/peps/pep-0362 In the present implementation, decorators generated by ``decorator`` can only be used on user-defined Python functions or methods, not on generic callable objects, nor on built-in functions, due to limitations of the -``inspect`` module in the standard library, especially for Python 2.X. +``inspect`` module in the standard library, especially for Python 2.X +(in Python 3.5 a lot of such limitations have been removed). There is a restriction on the names of the arguments: for instance, if try to call an argument ``_call_`` or ``_func_`` |