diff -pruN 4.3.0-1.1/CHANGES.md 4.4.2-0ubuntu1/CHANGES.md --- 4.3.0-1.1/CHANGES.md 2018-04-15 12:45:04.000000000 +0000 +++ 4.4.2-0ubuntu1/CHANGES.md 2020-02-29 05:22:24.000000000 +0000 @@ -1,7 +1,47 @@ HISTORY -------- -## Unreleased +## unreleased + +## 4.4.2 (2020-02-29) + +Sylvan Mosberger (https://github.com/Infinisil) contributed a patch to +some doctests that were breaking on NixOS. +John Vandenberg (https://github.com/jayvdb) made a case for removing the usage +of `__file__`, that was breaking PyOxidizer. +Miro Hrončok (https://github.com/hroncok) contributed some fixes for the +future Python 3.9. +Hugo van Kemenade (https://github.com/hugovk) contributed some fixes for the +future Python 3.10. + +## 4.4.1 (2019-10-27) + +Changed the description to "Decorators for Humans" are requested by +several users. Fixed a .rst bug in the description as seen in PyPI. + +## 4.4.0 (2019-03-16) + +Fixed a regression with decorator factories breaking the case with no +arguments by going back to the syntax used in version 4.2. +Accepted a small fix from Eric Larson (https://github.com/larsoner) affecting +`isgeneratorfunction` for old Python versions. +Moved the documentation from ReadTheDocs to GitHub to simplify the +release process and replaced ReStructuredText with Markdown: it is +an inferior solution, but it works better with GitHub and it is good enough. + +## 4.3.2 (2019-01-24) + +Accepted a patch from Sylvain Marie (https://github.com/smarie): now the +decorator module can decorate generator functions by preserving their +being generator functions. Set `python_requires='>=2.6, !=3.0.*, !=3.1.*'` +in setup.py, as suggested by https://github.com/hugovk. + +## 4.3.1 (2018-08-04) + +Added a section "For the impatient" to the README, addressing an issue +raised by Amir Malekpour. Added support for Python 3.7. Now +the path to the decorator module appears in the tracebacks, as suggested +by an user at EuroPython 2018. ## 4.3.0 (2018-04-15) @@ -205,7 +245,7 @@ Added a note on 'inspect.getsource' not functions; referenced PEP 326; highlighted the snippets in the documentation with pygments; slightly simplified the code. -## 2.1.0. (3/07/2007) +## 2.1.0. (2007-07-03) Replaced the utility 'update_wrapper' with 'new_wrapper' and updated the documentation accordingly; fixed and improved the diff -pruN 4.3.0-1.1/debian/changelog 4.4.2-0ubuntu1/debian/changelog --- 4.3.0-1.1/debian/changelog 2018-12-30 22:37:21.000000000 +0000 +++ 4.4.2-0ubuntu1/debian/changelog 2020-03-23 14:04:19.000000000 +0000 @@ -1,3 +1,17 @@ +python-decorator (4.4.2-0ubuntu1) focal; urgency=medium + + * d/gbp.conf: Update gbp configuration file. + * d/control: Update Vcs-* links and maintainers. + * New upstream release. + + -- Corey Bryant Mon, 23 Mar 2020 10:04:19 -0400 + +python-decorator (4.3.0-1.1build1) focal; urgency=medium + + * No-change rebuild to generate dependencies on python2. + + -- Matthias Klose Tue, 17 Dec 2019 12:42:01 +0000 + python-decorator (4.3.0-1.1) unstable; urgency=medium * Non-maintainer upload. diff -pruN 4.3.0-1.1/debian/control 4.4.2-0ubuntu1/debian/control --- 4.3.0-1.1/debian/control 2018-12-30 22:36:38.000000000 +0000 +++ 4.4.2-0ubuntu1/debian/control 2020-03-23 14:04:19.000000000 +0000 @@ -1,15 +1,16 @@ Source: python-decorator Section: python Priority: optional -Maintainer: Debian Python Modules Team +Maintainer: Ubuntu Developers +XSBC-Original-Maintainer: Debian Python Modules Team Uploaders: Piotr Ożarowski Build-Depends: debhelper (>= 10), dh-python, python-all (>= 2.6.6-3), python3-all, python-setuptools (>= 0.6b3~), python3-setuptools Rules-Requires-Root: no Standards-Version: 4.1.1 -Vcs-Git: https://salsa.debian.org/python-team/modules/python-decorator.git -Vcs-Browser: https://salsa.debian.org/python-team/modules/python-decorator +Vcs-Git: https://git.launchpad.net/~ubuntu-server-dev/ubuntu/+source/python-decorator +Vcs-Browser: https://git.launchpad.net/~ubuntu-server-dev/ubuntu/+source/python-decorator Homepage: https://pypi.python.org/pypi/decorator Package: python-decorator diff -pruN 4.3.0-1.1/debian/gbp.conf 4.4.2-0ubuntu1/debian/gbp.conf --- 4.3.0-1.1/debian/gbp.conf 1970-01-01 00:00:00.000000000 +0000 +++ 4.4.2-0ubuntu1/debian/gbp.conf 2020-03-23 14:04:19.000000000 +0000 @@ -0,0 +1,7 @@ +[DEFAULT] +debian-branch = master +upstream-tag = %(version)s +pristine-tar = True + +[buildpackage] +export-dir = ../build-area diff -pruN 4.3.0-1.1/docs/README.rst 4.4.2-0ubuntu1/docs/README.rst --- 4.3.0-1.1/docs/README.rst 2018-01-14 09:40:35.000000000 +0000 +++ 4.4.2-0ubuntu1/docs/README.rst 1970-01-01 00:00:00.000000000 +0000 @@ -1,57 +0,0 @@ -Decorator module -================= - -:Author: Michele Simionato -:E-mail: michele.simionato@gmail.com -:Requires: Python from 2.6 to 3.6 -:Download page: http://pypi.python.org/pypi/decorator -:Installation: ``pip install decorator`` -:License: BSD license - -Installation -------------- - -If you are lazy, just perform - - `$ pip install decorator` - -which will install just the module on your system. - -If you prefer to install the full distribution from source, including -the documentation, clone the `GitHub repo`_ or download the tarball_, unpack it and run - - `$ pip install .` - -in the main directory, possibly as superuser. - -.. _tarball: http://pypi.python.org/pypi/decorator -.. _GitHub repo: https://github.com/micheles/decorator - -Testing --------- - -If you have the source code installation you can run the tests with - - `$ python src/tests/test.py -v` - -or (if you have setuptools installed) - - `$ python setup.py test` - -Notice that you may run into trouble if in your system there -is an older version of the decorator module; in such a case remove the -old version. It is safe even to copy the module `decorator.py` over -an existing one, since we kept backward-compatibility for a long time. - -Repository ---------------- - -The project is hosted on GitHub. You can look at the source here: - - https://github.com/micheles/decorator - -Documentation ---------------- - -The documentation has been moved to http://decorator.readthedocs.io/en/latest/ -You can download a PDF version of it from http://media.readthedocs.org/pdf/decorator/latest/decorator.pdf diff -pruN 4.3.0-1.1/LICENSE.txt 4.4.2-0ubuntu1/LICENSE.txt --- 4.3.0-1.1/LICENSE.txt 2017-01-15 09:59:31.000000000 +0000 +++ 4.4.2-0ubuntu1/LICENSE.txt 2019-03-16 14:21:37.000000000 +0000 @@ -1,4 +1,4 @@ -Copyright (c) 2005-2017, Michele Simionato +Copyright (c) 2005-2018, Michele Simionato All rights reserved. Redistribution and use in source and binary forms, with or without diff -pruN 4.3.0-1.1/MANIFEST.in 4.4.2-0ubuntu1/MANIFEST.in --- 4.3.0-1.1/MANIFEST.in 2016-06-02 06:41:09.000000000 +0000 +++ 4.4.2-0ubuntu1/MANIFEST.in 2019-03-16 14:21:37.000000000 +0000 @@ -1,2 +1,2 @@ -include docs/README.rst LICENSE.txt CHANGES.md performance.sh documentation.pdf +include README.rst LICENSE.txt CHANGES.md performance.sh documentation.pdf recursive-include src/tests *.py diff -pruN 4.3.0-1.1/PKG-INFO 4.4.2-0ubuntu1/PKG-INFO --- 4.3.0-1.1/PKG-INFO 2018-04-15 12:50:29.000000000 +0000 +++ 4.4.2-0ubuntu1/PKG-INFO 2020-02-29 05:24:41.000000000 +0000 @@ -1,38 +1,38 @@ -Metadata-Version: 1.1 +Metadata-Version: 1.2 Name: decorator -Version: 4.3.0 -Summary: Better living through Python with decorators +Version: 4.4.2 +Summary: Decorators for Humans Home-page: https://github.com/micheles/decorator Author: Michele Simionato Author-email: michele.simionato@gmail.com License: new BSD License -Description: Decorator module - ================= +Description: Decorators for Humans + ===================== - :Author: Michele Simionato - :E-mail: michele.simionato@gmail.com - :Requires: Python from 2.6 to 3.6 - :Download page: http://pypi.python.org/pypi/decorator - :Installation: ``pip install decorator`` - :License: BSD license + The goal of the decorator module is to make it easy to define + signature-preserving function decorators and decorator factories. + It also includes an implementation of multiple dispatch and other niceties + (please check the docs). It is released under a two-clauses + BSD license, i.e. basically you can do whatever you want with it but I am not + responsible. Installation ------------- If you are lazy, just perform - `$ pip install decorator` + ``$ pip install decorator`` which will install just the module on your system. If you prefer to install the full distribution from source, including the documentation, clone the `GitHub repo`_ or download the tarball_, unpack it and run - `$ pip install .` + ``$ pip install .`` in the main directory, possibly as superuser. - .. _tarball: http://pypi.python.org/pypi/decorator + .. _tarball: https://pypi.org/project/decorator/#files .. _GitHub repo: https://github.com/micheles/decorator Testing @@ -61,8 +61,49 @@ Description: Decorator module Documentation --------------- - The documentation has been moved to http://decorator.readthedocs.io/en/latest/ - You can download a PDF version of it from http://media.readthedocs.org/pdf/decorator/latest/decorator.pdf + The documentation has been moved to https://github.com/micheles/decorator/blob/master/docs/documentation.md + + From there you can get a PDF version by simply using the print + functionality of your browser. + + Here is the documentation for previous versions of the module: + + https://github.com/micheles/decorator/blob/4.3.2/docs/tests.documentation.rst + https://github.com/micheles/decorator/blob/4.2.1/docs/tests.documentation.rst + https://github.com/micheles/decorator/blob/4.1.2/docs/tests.documentation.rst + https://github.com/micheles/decorator/blob/4.0.0/documentation.rst + https://github.com/micheles/decorator/blob/3.4.2/documentation.rst + + For the impatient + ----------------- + + Here is an example of how to define a family of decorators tracing slow + operations: + + .. code-block:: python + + from decorator import decorator + + @decorator + def warn_slow(func, timelimit=60, *args, **kw): + t0 = time.time() + result = func(*args, **kw) + dt = time.time() - t0 + if dt > timelimit: + logging.warn('%s took %d seconds', func.__name__, dt) + else: + logging.info('%s took %d seconds', func.__name__, dt) + return result + + @warn_slow # warn if it takes more than 1 minute + def preprocess_input_files(inputdir, tempdir): + ... + + @warn_slow(timelimit=600) # warn if it takes more than 10 minutes + def run_calculation(tempdir, outdir): + ... + + Enjoy! Keywords: decorators generic utility Platform: All @@ -81,6 +122,8 @@ Classifier: Programming Language :: Pyth Classifier: Programming Language :: Python :: 3.4 Classifier: Programming Language :: Python :: 3.5 Classifier: Programming Language :: Python :: 3.6 +Classifier: Programming Language :: Python :: 3.7 Classifier: Programming Language :: Python :: Implementation :: CPython Classifier: Topic :: Software Development :: Libraries Classifier: Topic :: Utilities +Requires-Python: >=2.6, !=3.0.*, !=3.1.* diff -pruN 4.3.0-1.1/README.md 4.4.2-0ubuntu1/README.md --- 4.3.0-1.1/README.md 2015-07-28 03:49:22.000000000 +0000 +++ 4.4.2-0ubuntu1/README.md 1970-01-01 00:00:00.000000000 +0000 @@ -1,3 +0,0 @@ -[See the real README](docs/README.rst) - -[![Build Status](https://secure.travis-ci.org/micheles/decorator.png?branch=master)](https://travis-ci.org/micheles/decorator) diff -pruN 4.3.0-1.1/README.rst 4.4.2-0ubuntu1/README.rst --- 4.3.0-1.1/README.rst 1970-01-01 00:00:00.000000000 +0000 +++ 4.4.2-0ubuntu1/README.rst 2019-10-27 08:10:40.000000000 +0000 @@ -0,0 +1,98 @@ +Decorators for Humans +===================== + +The goal of the decorator module is to make it easy to define +signature-preserving function decorators and decorator factories. +It also includes an implementation of multiple dispatch and other niceties +(please check the docs). It is released under a two-clauses +BSD license, i.e. basically you can do whatever you want with it but I am not +responsible. + +Installation +------------- + +If you are lazy, just perform + + ``$ pip install decorator`` + +which will install just the module on your system. + +If you prefer to install the full distribution from source, including +the documentation, clone the `GitHub repo`_ or download the tarball_, unpack it and run + + ``$ pip install .`` + +in the main directory, possibly as superuser. + +.. _tarball: https://pypi.org/project/decorator/#files +.. _GitHub repo: https://github.com/micheles/decorator + +Testing +-------- + +If you have the source code installation you can run the tests with + + `$ python src/tests/test.py -v` + +or (if you have setuptools installed) + + `$ python setup.py test` + +Notice that you may run into trouble if in your system there +is an older version of the decorator module; in such a case remove the +old version. It is safe even to copy the module `decorator.py` over +an existing one, since we kept backward-compatibility for a long time. + +Repository +--------------- + +The project is hosted on GitHub. You can look at the source here: + + https://github.com/micheles/decorator + +Documentation +--------------- + +The documentation has been moved to https://github.com/micheles/decorator/blob/master/docs/documentation.md + +From there you can get a PDF version by simply using the print +functionality of your browser. + +Here is the documentation for previous versions of the module: + +https://github.com/micheles/decorator/blob/4.3.2/docs/tests.documentation.rst +https://github.com/micheles/decorator/blob/4.2.1/docs/tests.documentation.rst +https://github.com/micheles/decorator/blob/4.1.2/docs/tests.documentation.rst +https://github.com/micheles/decorator/blob/4.0.0/documentation.rst +https://github.com/micheles/decorator/blob/3.4.2/documentation.rst + +For the impatient +----------------- + +Here is an example of how to define a family of decorators tracing slow +operations: + +.. code-block:: python + + from decorator import decorator + + @decorator + def warn_slow(func, timelimit=60, *args, **kw): + t0 = time.time() + result = func(*args, **kw) + dt = time.time() - t0 + if dt > timelimit: + logging.warn('%s took %d seconds', func.__name__, dt) + else: + logging.info('%s took %d seconds', func.__name__, dt) + return result + + @warn_slow # warn if it takes more than 1 minute + def preprocess_input_files(inputdir, tempdir): + ... + + @warn_slow(timelimit=600) # warn if it takes more than 10 minutes + def run_calculation(tempdir, outdir): + ... + +Enjoy! diff -pruN 4.3.0-1.1/setup.py 4.4.2-0ubuntu1/setup.py --- 4.3.0-1.1/setup.py 2018-01-14 09:38:21.000000000 +0000 +++ 4.4.2-0ubuntu1/setup.py 2019-10-27 07:59:44.000000000 +0000 @@ -1,15 +1,15 @@ from setuptools import setup -dic = {} -exec(open('src/decorator.py').read(), dic) +dic = dict(__file__=None) +exec(open('src/decorator.py').read(), dic) # extract the __version__ VERSION = dic['__version__'] if __name__ == '__main__': setup(name='decorator', version=VERSION, - description='Better living through Python with decorators', - long_description=open('docs/README.rst').read(), + description='Decorators for Humans', + long_description=open('README.rst').read(), author='Michele Simionato', author_email='michele.simionato@gmail.com', url='https://github.com/micheles/decorator', @@ -18,6 +18,7 @@ if __name__ == '__main__': py_modules=['decorator'], keywords="decorators generic utility", platforms=["All"], + python_requires='>=2.6, !=3.0.*, !=3.1.*', classifiers=['Development Status :: 5 - Production/Stable', 'Intended Audience :: Developers', 'License :: OSI Approved :: BSD License', @@ -33,6 +34,7 @@ if __name__ == '__main__': 'Programming Language :: Python :: 3.4', 'Programming Language :: Python :: 3.5', 'Programming Language :: Python :: 3.6', + 'Programming Language :: Python :: 3.7', 'Programming Language :: Python :: Implementation :: CPython', 'Topic :: Software Development :: Libraries', 'Topic :: Utilities'], diff -pruN 4.3.0-1.1/src/decorator.egg-info/PKG-INFO 4.4.2-0ubuntu1/src/decorator.egg-info/PKG-INFO --- 4.3.0-1.1/src/decorator.egg-info/PKG-INFO 2018-04-15 12:50:28.000000000 +0000 +++ 4.4.2-0ubuntu1/src/decorator.egg-info/PKG-INFO 2020-02-29 05:24:40.000000000 +0000 @@ -1,38 +1,38 @@ -Metadata-Version: 1.1 +Metadata-Version: 1.2 Name: decorator -Version: 4.3.0 -Summary: Better living through Python with decorators +Version: 4.4.2 +Summary: Decorators for Humans Home-page: https://github.com/micheles/decorator Author: Michele Simionato Author-email: michele.simionato@gmail.com License: new BSD License -Description: Decorator module - ================= +Description: Decorators for Humans + ===================== - :Author: Michele Simionato - :E-mail: michele.simionato@gmail.com - :Requires: Python from 2.6 to 3.6 - :Download page: http://pypi.python.org/pypi/decorator - :Installation: ``pip install decorator`` - :License: BSD license + The goal of the decorator module is to make it easy to define + signature-preserving function decorators and decorator factories. + It also includes an implementation of multiple dispatch and other niceties + (please check the docs). It is released under a two-clauses + BSD license, i.e. basically you can do whatever you want with it but I am not + responsible. Installation ------------- If you are lazy, just perform - `$ pip install decorator` + ``$ pip install decorator`` which will install just the module on your system. If you prefer to install the full distribution from source, including the documentation, clone the `GitHub repo`_ or download the tarball_, unpack it and run - `$ pip install .` + ``$ pip install .`` in the main directory, possibly as superuser. - .. _tarball: http://pypi.python.org/pypi/decorator + .. _tarball: https://pypi.org/project/decorator/#files .. _GitHub repo: https://github.com/micheles/decorator Testing @@ -61,8 +61,49 @@ Description: Decorator module Documentation --------------- - The documentation has been moved to http://decorator.readthedocs.io/en/latest/ - You can download a PDF version of it from http://media.readthedocs.org/pdf/decorator/latest/decorator.pdf + The documentation has been moved to https://github.com/micheles/decorator/blob/master/docs/documentation.md + + From there you can get a PDF version by simply using the print + functionality of your browser. + + Here is the documentation for previous versions of the module: + + https://github.com/micheles/decorator/blob/4.3.2/docs/tests.documentation.rst + https://github.com/micheles/decorator/blob/4.2.1/docs/tests.documentation.rst + https://github.com/micheles/decorator/blob/4.1.2/docs/tests.documentation.rst + https://github.com/micheles/decorator/blob/4.0.0/documentation.rst + https://github.com/micheles/decorator/blob/3.4.2/documentation.rst + + For the impatient + ----------------- + + Here is an example of how to define a family of decorators tracing slow + operations: + + .. code-block:: python + + from decorator import decorator + + @decorator + def warn_slow(func, timelimit=60, *args, **kw): + t0 = time.time() + result = func(*args, **kw) + dt = time.time() - t0 + if dt > timelimit: + logging.warn('%s took %d seconds', func.__name__, dt) + else: + logging.info('%s took %d seconds', func.__name__, dt) + return result + + @warn_slow # warn if it takes more than 1 minute + def preprocess_input_files(inputdir, tempdir): + ... + + @warn_slow(timelimit=600) # warn if it takes more than 10 minutes + def run_calculation(tempdir, outdir): + ... + + Enjoy! Keywords: decorators generic utility Platform: All @@ -81,6 +122,8 @@ Classifier: Programming Language :: Pyth Classifier: Programming Language :: Python :: 3.4 Classifier: Programming Language :: Python :: 3.5 Classifier: Programming Language :: Python :: 3.6 +Classifier: Programming Language :: Python :: 3.7 Classifier: Programming Language :: Python :: Implementation :: CPython Classifier: Topic :: Software Development :: Libraries Classifier: Topic :: Utilities +Requires-Python: >=2.6, !=3.0.*, !=3.1.* diff -pruN 4.3.0-1.1/src/decorator.egg-info/SOURCES.txt 4.4.2-0ubuntu1/src/decorator.egg-info/SOURCES.txt --- 4.3.0-1.1/src/decorator.egg-info/SOURCES.txt 2018-04-15 12:50:29.000000000 +0000 +++ 4.4.2-0ubuntu1/src/decorator.egg-info/SOURCES.txt 2020-02-29 05:24:41.000000000 +0000 @@ -1,11 +1,10 @@ CHANGES.md LICENSE.txt MANIFEST.in -README.md +README.rst performance.sh setup.cfg setup.py -docs/README.rst src/decorator.py src/decorator.egg-info/PKG-INFO src/decorator.egg-info/SOURCES.txt diff -pruN 4.3.0-1.1/src/decorator.py 4.4.2-0ubuntu1/src/decorator.py --- 4.3.0-1.1/src/decorator.py 2018-04-15 12:45:04.000000000 +0000 +++ 4.4.2-0ubuntu1/src/decorator.py 2020-02-29 05:20:33.000000000 +0000 @@ -40,9 +40,9 @@ import operator import itertools import collections -__version__ = '4.3.0' +__version__ = '4.4.2' -if sys.version >= '3': +if sys.version_info >= (3,): from inspect import getfullargspec def get_init(cls): @@ -65,6 +65,12 @@ except AttributeError: # let's assume there are no coroutine functions in old Python def iscoroutinefunction(f): return False +try: + from inspect import isgeneratorfunction +except ImportError: + # assume no generator function in old Python versions + def isgeneratorfunction(caller): + return False DEF = re.compile(r'\s*def\s*([_\w][_\w\d]*)\s*\(') @@ -173,7 +179,7 @@ class FunctionMaker(object): # Ensure each generated function has a unique filename for profilers # (such as cProfile) that depend on the tuple of (, # , ) being unique. - filename = '' % (next(self._compile_count),) + filename = '' % next(self._compile_count) try: code = compile(src, filename, 'single') exec(code, evaldict) @@ -218,6 +224,8 @@ class FunctionMaker(object): def decorate(func, caller, extras=()): """ decorate(func, caller) decorates a function using a caller. + If the caller is a generator function, the resulting function + will be a generator function. """ evaldict = dict(_call_=caller, _func_=func) es = '' @@ -225,9 +233,23 @@ def decorate(func, caller, extras=()): ex = '_e%d_' % i evaldict[ex] = extra es += ex + ', ' - fun = FunctionMaker.create( - func, "return _call_(_func_, %s%%(shortsignature)s)" % es, - evaldict, __wrapped__=func) + + if '3.5' <= sys.version < '3.6': + # with Python 3.5 isgeneratorfunction returns True for all coroutines + # however we know that it is NOT possible to have a generator + # coroutine in python 3.5: PEP525 was not there yet + generatorcaller = isgeneratorfunction( + caller) and not iscoroutinefunction(caller) + else: + generatorcaller = isgeneratorfunction(caller) + if generatorcaller: + fun = FunctionMaker.create( + func, "for res in _call_(_func_, %s%%(shortsignature)s):\n" + " yield res" % es, evaldict, __wrapped__=func) + else: + fun = FunctionMaker.create( + func, "return _call_(_func_, %s%%(shortsignature)s)" % es, + evaldict, __wrapped__=func) if hasattr(func, '__qualname__'): fun.__qualname__ = func.__qualname__ return fun @@ -261,12 +283,12 @@ def decorator(caller, _func=None): doc = caller.__call__.__doc__ evaldict = dict(_call=caller, _decorate_=decorate) dec = FunctionMaker.create( - '%s(%s func)' % (name, defaultargs), + '%s(func, %s)' % (name, defaultargs), 'if func is None: return lambda func: _decorate_(func, _call, (%s))\n' 'return _decorate_(func, _call, (%s))' % (defaultargs, defaultargs), evaldict, doc=doc, module=caller.__module__, __wrapped__=caller) if defaults: - dec.__defaults__ = defaults + (None,) + dec.__defaults__ = (None,) + defaults return dec diff -pruN 4.3.0-1.1/src/tests/documentation.py 4.4.2-0ubuntu1/src/tests/documentation.py --- 4.3.0-1.1/src/tests/documentation.py 2018-04-15 12:48:08.000000000 +0000 +++ 4.4.2-0ubuntu1/src/tests/documentation.py 2020-02-29 05:10:07.000000000 +0000 @@ -1,17 +1,29 @@ from __future__ import print_function +import sys +import threading +import time +import functools +import itertools +import collections +try: + import collections.abc as c +except ImportError: + c = collections + collections.abc = collections +from decorator import (decorator, decorate, FunctionMaker, contextmanager, + dispatch_on, __version__) -doc = r"""\ -The ``decorator`` module - -:Author: Michele Simionato -:E-mail: michele.simionato@gmail.com -:Version: $VERSION ($DATE) -: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/$VERSION -:Installation: ``pip install decorator`` -:License: BSD license +doc = r"""Decorators for Humans +---------------------------------- -.. contents:: +|Author | Michele Simionato| +|---|---| +|E-mail | michele.simionato@gmail.com| +|Version| $VERSION ($DATE)| +|Supports| Python 2.6, 2.7, 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8| +|Download page| http://pypi.python.org/pypi/decorator/$VERSION| +|Installation| ``pip install decorator``| +|License | BSD license| Introduction ----------------------------------------- @@ -28,13 +40,12 @@ decision made it possible to use a singl 2,000 lines of duplicated documentation/doctests. Having to maintain separate docs for Python 2 and Python 3 effectively stopped any development on the module for several years. Moreover, it is now -trivial to distribute the module as an universal wheel_ since 2to3 is no more +trivial to distribute the module as an universal + [wheel](http://pythonwheels.com) since 2to3 is no more required. Since Python 2.5 has been released ages ago (in 2006), I felt that it was reasonable to drop the support for it. If you need to support ancient versions of Python, stick with the decorator module version -3.4.2. The current version supports all Python releases from 2.6 up to 3.6. - -.. _wheel: http://pythonwheels.com/ +3.4.2. The current version supports all Python releases from 2.6 up. What's New in version 4 ----------------------- @@ -115,19 +126,20 @@ can be used as a decorator. However, thi 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. +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 +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. @@ -168,8 +180,6 @@ Here is an example of usage: $$f1 -.. _functools.update_wrapper: https://docs.python.org/3/library/functools.html#functools.update_wrapper - 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* @@ -183,11 +193,12 @@ Here, the original function takes a sing but the decorated function takes any number of arguments and keyword arguments: -.. code-block:: python +```python +>>> from decorator import getfullargspec +>>> print(getfullargspec(f1)) +FullArgSpec(args=[], varargs='args', varkw='kw', defaults=None, kwonlyargs=[], kwonlydefaults=None, annotations={}) - >>> from decorator import getfullargspec - >>> print(getfullargspec(f1)) - FullArgSpec(args=[], varargs='args', varkw='kw', defaults=None, kwonlyargs=[], kwonlydefaults=None, annotations={}) +``` This means that introspection tools (like ``pydoc``) will give false information about the signature of ``f1`` -- unless you are using @@ -195,12 +206,13 @@ Python 3.5. This is pretty bad: ``pydoc` function accepts the generic signature ``*args, **kw``, but calling the function with more than one argument raises an error: -.. code-block:: python +```python +>>> f1(0, 1) # doctest: +IGNORE_EXCEPTION_DETAIL +Traceback (most recent call last): + ... +TypeError: f1() takes exactly 1 positional argument (2 given) - >>> f1(0, 1) # doctest: +IGNORE_EXCEPTION_DETAIL - Traceback (most recent call last): - ... - TypeError: f1() takes exactly 1 positional argument (2 given) +``` Notice that ``inspect.getfullargspec`` will give the wrong signature, even in the latest Python, i.e. version 3.6 @@ -214,9 +226,10 @@ hides the complexity of making signature from the application programmer. The ``decorate`` function in the ``decorator`` module is such a factory: -.. code-block:: python +```python +>>> from decorator import decorate - >>> from decorator import decorate +``` ``decorate`` takes two arguments: @@ -241,25 +254,27 @@ function you want to decorate; there are Here is a test of usage: -.. code-block:: python +```python +>>> @memoize +... def heavy_computation(): +... time.sleep(2) +... return "done" - >>> @memoize - ... def heavy_computation(): - ... time.sleep(2) - ... return "done" +>>> print(heavy_computation()) # the first time it will take 2 seconds +done - >>> print(heavy_computation()) # the first time it will take 2 seconds - done +>>> print(heavy_computation()) # the second time it will be instantaneous +done - >>> print(heavy_computation()) # the second time it will be instantaneous - done +``` The signature of ``heavy_computation`` is the one you would expect: -.. code-block:: python +```python +>>> print(getfullargspec(heavy_computation)) +FullArgSpec(args=[], varargs=None, varkw=None, defaults=None, kwonlyargs=[], kwonlydefaults=None, annotations={}) - >>> print(getfullargspec(heavy_computation)) - FullArgSpec(args=[], varargs=None, varkw=None, defaults=None, kwonlyargs=[], kwonlydefaults=None, annotations={}) +``` A ``trace`` decorator ------------------------------------------------------ @@ -273,40 +288,43 @@ $$trace Here is an example of usage: -.. code-block:: python +```python +>>> @trace +... def f1(x): +... pass - >>> @trace - ... def f1(x): - ... pass +``` It is immediate to verify that ``f1`` works... -.. code-block:: python +```python +>>> f1(0) +calling f1 with args (0,), {} - >>> f1(0) - calling f1 with args (0,), {} +``` ...and it that it has the correct signature: -.. code-block:: python +```python +>>> print(getfullargspec(f1)) +FullArgSpec(args=['x'], varargs=None, varkw=None, defaults=None, kwonlyargs=[], kwonlydefaults=None, annotations={}) - >>> print(getfullargspec(f1)) - FullArgSpec(args=['x'], varargs=None, varkw=None, defaults=None, kwonlyargs=[], kwonlydefaults=None, annotations={}) +``` The decorator works with functions of any signature: -.. code-block:: python - - >>> @trace - ... def f(x, y=1, z=2, *args, **kw): - ... pass +```python +>>> @trace +... def f(x, y=1, z=2, *args, **kw): +... pass - >>> f(0, 3) - calling f with args (0, 3, 2), {} +>>> f(0, 3) +calling f with args (0, 3, 2), {} - >>> print(getfullargspec(f)) - FullArgSpec(args=['x', 'y', 'z'], varargs='args', varkw='kw', defaults=(1, 2), kwonlyargs=[], kwonlydefaults=None, annotations={}) +>>> print(getfullargspec(f)) +FullArgSpec(args=['x', 'y', 'z'], varargs='args', varkw='kw', defaults=(1, 2), kwonlyargs=[], kwonlydefaults=None, annotations={}) +``` $FUNCTION_ANNOTATIONS ``decorator.decorator`` @@ -320,12 +338,12 @@ to convert the caller function into a si It is the ``decorator`` function: -.. code-block:: python - - >>> from decorator import decorator - >>> print(decorator.__doc__) - decorator(caller) converts a caller function into a decorator +```python +>>> from decorator import decorator +>>> print(decorator.__doc__) +decorator(caller) converts a caller function into a decorator +``` The ``decorator`` function can be used as a signature-changing decorator, just like ``classmethod`` and ``staticmethod``. But ``classmethod`` and ``staticmethod`` return generic @@ -334,64 +352,67 @@ signature-preserving decorators (i.e. fu For instance, you can write: -.. code-block:: python +```python +>>> @decorator +... def trace(f, *args, **kw): +... kwstr = ', '.join('%r: %r' % (k, kw[k]) for k in sorted(kw)) +... print("calling %s with args %s, {%s}" % (f.__name__, args, kwstr)) +... return f(*args, **kw) - >>> @decorator - ... def trace(f, *args, **kw): - ... kwstr = ', '.join('%r: %r' % (k, kw[k]) for k in sorted(kw)) - ... print("calling %s with args %s, {%s}" % (f.__name__, args, kwstr)) - ... return f(*args, **kw) +``` And ``trace`` is now a decorator! -.. code-block:: python +```python +>>> trace # doctest: +ELLIPSIS + - >>> trace # doctest: +ELLIPSIS - +``` Here is an example of usage: -.. code-block:: python +```python +>>> @trace +... def func(): pass - >>> @trace - ... def func(): pass +>>> func() +calling func with args (), {} - >>> func() - calling func with args (), {} +``` The `decorator` function can also be used to define factories of decorators, i.e. functions returning decorators. In general you can just write something like this: -.. code-block:: python - - def decfactory(param1, param2, ...): - def caller(f, *args, **kw): - return somefunc(f, param1, param2, .., *args, **kw) - return decorator(caller) +```python +def decfactory(param1, param2, ...): + def caller(f, *args, **kw): + return somefunc(f, param1, param2, .., *args, **kw) + return decorator(caller) +``` This is fully general but requires an additional level of nesting. For this -reasone since version 4.2 there is a facility to build +reason since version 4.2 there is a facility to build decorator factories by using a single caller with default arguments i.e. writing something like this: -.. code-block:: python - - def caller(f, param1=default1, param2=default2, ..., *args, **kw): - return somefunc(f, param1, param2, *args, **kw) - decfactory = decorator(caller) +```python +def caller(f, param1=default1, param2=default2, ..., *args, **kw): + return somefunc(f, param1, param2, *args, **kw) +decfactory = decorator(caller) +``` Notice that this simplified approach *only works with default arguments*, i.e. `param1`, `param2` etc must have known defaults. Thanks to this restriction, there exists an unique default decorator, i.e. the member of the family which uses the default values for all parameters. Such -decorator can be written as `decfactory()` with no parameters specified; +decorator can be written as ``decfactory()`` with no parameters specified; moreover, as a shortcut, it is also possible to elide the parenthesis, a feature much requested by the users. For years I have been opposite -to this feature request, since having expliciti parenthesis to me is more clear +to this feature request, since having explicit parenthesis to me is more clear and less magic; however once this feature entered in decorators of -the Python standard library (I am referring to the `dataclass` decorator -https://www.python.org/dev/peps/pep-0557/) I finally gave up. +the Python standard library (I am referring to the [dataclass decorator]( +https://www.python.org/dev/peps/pep-0557/)) I finally gave up. The example below will show how it works in practice. @@ -410,27 +431,28 @@ Functions decorated with ``blocking`` wi the resource is unavailable, and the intended result if the resource is available. For instance: -.. code-block:: python +```python +>>> @blocking(msg="Please wait ...") +... def read_data(): +... time.sleep(3) # simulate a blocking resource +... return "some data" + +>>> print(read_data()) # data is not available yet +Please wait ... + +>>> time.sleep(1) +>>> print(read_data()) # data is not available yet +Please wait ... + +>>> time.sleep(1) +>>> print(read_data()) # data is not available yet +Please wait ... + +>>> time.sleep(1.1) # after 3.1 seconds, data is available +>>> print(read_data()) +some data - >>> @blocking("Please wait ...") - ... def read_data(): - ... time.sleep(3) # simulate a blocking resource - ... return "some data" - - >>> print(read_data()) # data is not available yet - Please wait ... - - >>> time.sleep(1) - >>> print(read_data()) # data is not available yet - Please wait ... - - >>> time.sleep(1) - >>> print(read_data()) # data is not available yet - Please wait ... - - >>> time.sleep(1.1) # after 3.1 seconds, data is available - >>> print(read_data()) - some data +``` Decorator factories are most useful to framework builders. Here is an example that gives an idea of how you could manage permissions in a framework: @@ -441,16 +463,16 @@ where ``restricted`` is a decorator fact $$restricted -In general a decorator factory has a signature +Notice that if you forget to use the keyword argument notation, i.e. if you +write ``restricted(User)`` instead of ``restricted(user_class=User)`` you +will get an error -.. code-block:: python +```python +TypeError: You are decorating a non function: - def decfactory(func, par1=default1, .., parN=defaultN, *a, **k): - ... +``` -Each parameter must have a default, so that ``decfactory`` can work -as an alias for ``decfactory()``, i.e. the decorator in which all parameters -have the default value. +Be careful! ``decorator(cls)`` -------------------------------------------- @@ -476,17 +498,18 @@ the final result. Here is the minimalistic usage: -.. code-block:: python +```python +>>> @decorator(Future) +... def long_running(x): +... time.sleep(.5) +... return x + +>>> fut1 = long_running(1) +>>> fut2 = long_running(2) +>>> fut1.result() + fut2.result() +3 - >>> @decorator(Future) - ... def long_running(x): - ... time.sleep(.5) - ... return x - - >>> fut1 = long_running(1) - >>> fut2 = long_running(2) - >>> fut1.result() + fut2.result() - 3 +``` contextmanager ------------------------------------- @@ -495,27 +518,28 @@ Python's standard library has the ``cont which converts a generator function into a ``GeneratorContextManager`` factory. For instance, if you write this... -.. code-block:: python - - >>> from contextlib import contextmanager - >>> @contextmanager - ... def before_after(before, after): - ... print(before) - ... yield - ... print(after) +```python +>>> from contextlib import contextmanager +>>> @contextmanager +... def before_after(before, after): +... print(before) +... yield +... print(after) +``` ...then ``before_after`` is a factory function that returns ``GeneratorContextManager`` objects, which provide the use of the ``with`` statement: -.. code-block:: python +```python +>>> with before_after('BEFORE', 'AFTER'): +... print('hello') +BEFORE +hello +AFTER - >>> with before_after('BEFORE', 'AFTER'): - ... print('hello') - BEFORE - hello - AFTER +``` Basically, it is as if the content of the ``with`` block was executed in the place of the ``yield`` expression in the generator function. @@ -523,16 +547,19 @@ in the place of the ``yield`` expression In Python 3.2, ``GeneratorContextManager`` objects were enhanced with a ``__call__`` method, so that they can be used as decorators, like so: -.. code-block:: python +```python +>>> ba = before_after('BEFORE', 'AFTER') +>>> +>>> @ba # doctest: +SKIP +... def hello(): +... print('hello') +... +>>> hello() # doctest: +SKIP +BEFORE +hello +AFTER - >>> @ba # doctest: +SKIP - ... def hello(): - ... print('hello') - ... - >>> hello() # doctest: +SKIP - BEFORE - hello - AFTER +``` The ``ba`` decorator basically inserts a ``with ba:`` block inside the function. @@ -579,14 +606,15 @@ where the function is generated by ``exe Here's an example: -.. code-block:: python - - >>> def f(*args, **kw): # a function with a generic signature - ... print(args, kw) +```python +>>> def f(*args, **kw): # a function with a generic signature +... print(args, kw) + +>>> f1 = FunctionMaker.create('f1(a, b)', 'f(a, b)', dict(f=f)) +>>> f1(1,2) +(1, 2) {} - >>> f1 = FunctionMaker.create('f1(a, b)', 'f(a, b)', dict(f=f)) - >>> f1(1,2) - (1, 2) {} +``` It is important to notice that the function body is interpolated before being executed; **be careful** with the ``%`` sign! @@ -601,14 +629,15 @@ the source code of the generated functio pass ``addsource=True``, and the generated function will get a ``__source__`` attribute: -.. code-block:: python +```python +>>> f1 = FunctionMaker.create( +... 'f1(a, b)', 'f(a, b)', dict(f=f), addsource=True) +>>> print(f1.__source__) +def f1(a, b): + f(a, b) + - >>> f1 = FunctionMaker.create( - ... 'f1(a, b)', 'f(a, b)', dict(f=f), addsource=True) - >>> print(f1.__source__) - def f1(a, b): - f(a, b) - +``` The first argument to ``FunctionMaker.create`` can be a string (as above), or a function. This is the most common usage, since you typically decorate @@ -640,13 +669,13 @@ Here is what happens: (e.g., something like ``'f1(a, b=None)'``). Just pass ``'f1(a, b)'``, followed by a tuple of defaults: -.. code-block:: python - - >>> f1 = FunctionMaker.create( - ... 'f1(a, b)', 'f(a, b)', dict(f=f), addsource=True, defaults=(None,)) - >>> print(getfullargspec(f1)) - FullArgSpec(args=['a', 'b'], varargs=None, varkw=None, defaults=(None,), kwonlyargs=[], kwonlydefaults=None, annotations={}) +```python +>>> f1 = FunctionMaker.create( +... 'f1(a, b)', 'f(a, b)', dict(f=f), addsource=True, defaults=(None,)) +>>> print(getfullargspec(f1)) +FullArgSpec(args=['a', 'b'], varargs=None, varkw=None, defaults=(None,), kwonlyargs=[], kwonlydefaults=None, annotations={}) +``` Getting the source code --------------------------------------------------- @@ -665,33 +694,34 @@ not what you want: $$identity_dec $$example -.. code-block:: python +```python +>>> import inspect +>>> print(inspect.getsource(example)) + def wrapper(*args, **kw): + return func(*args, **kw) + - >>> import inspect - >>> print(inspect.getsource(example)) - def wrapper(*args, **kw): - return func(*args, **kw) - +``` -(See bug report 1764286_ for an explanation of what is happening). +(See bug report [1764286](http://bugs.python.org/issue1764286) +for an explanation of what is happening). Unfortunately the bug still exists in all versions of Python < 3.5. However, there is a workaround. The decorated function has the ``__wrapped__`` attribute, pointing to the original function. The simplest way to get the source code is to call ``inspect.getsource`` on the undecorated function: -.. code-block:: python - - >>> print(inspect.getsource(factorial.__wrapped__)) - @tail_recursive - def factorial(n, acc=1): - "The good old factorial" - if n == 0: - return acc - return factorial(n-1, n*acc) - +```python +>>> print(inspect.getsource(factorial.__wrapped__)) +@tail_recursive +def factorial(n, acc=1): + "The good old factorial" + if n == 0: + return acc + return factorial(n-1, n*acc) + -.. _1764286: http://bugs.python.org/issue1764286 +``` Dealing with third-party decorators ----------------------------------------------------------------- @@ -735,10 +765,11 @@ Here is how you apply the upgraded decor $$factorial -.. code-block:: python +```python +>>> print(factorial(4)) +24 - >>> print(factorial(4)) - 24 +``` This decorator is pretty impressive, and should give you some food for thought! ;) @@ -770,39 +801,41 @@ Here I will give a single example of usa a coroutine starts and the moment it stops for debugging purposes. You could write code like the following: -.. code-block:: python - - import time - import logging - from asyncio import get_event_loop, sleep, wait - from decorator import decorator +```python +import time +import logging +from asyncio import get_event_loop, sleep, wait +from decorator import decorator @decorator - async def log_start_stop(coro, *args, **kwargs): - logging.info('Starting %s%s', coro.__name__, args) - t0 = time.time() - await coro(*args, **kwargs) - dt = time.time() - t0 - logging.info('Ending %s%s after %d seconds', coro.__name__, args, dt) - - @log_start_stop - async def make_task(n): - for i in range(n): - await sleep(1) - - if __name__ == '__main__': - logging.basicConfig(level=logging.INFO) - tasks = [make_task(3), make_task(2), make_task(1)] - get_event_loop().run_until_complete(wait(tasks)) - -and you will get an output like this:: - - INFO:root:Starting make_task(1,) - INFO:root:Starting make_task(3,) - INFO:root:Starting make_task(2,) - INFO:root:Ending make_task(1,) after 1 seconds - INFO:root:Ending make_task(2,) after 2 seconds - INFO:root:Ending make_task(3,) after 3 seconds +async def log_start_stop(coro, *args, **kwargs): + logging.info('Starting %s%s', coro.__name__, args) + t0 = time.time() + await coro(*args, **kwargs) + dt = time.time() - t0 + logging.info('Ending %s%s after %d seconds', coro.__name__, args, dt) + +@log_start_stop +async def make_task(n): + for i in range(n): + await sleep(1) + +if __name__ == '__main__': + logging.basicConfig(level=logging.INFO) + tasks = [make_task(3), make_task(2), make_task(1)] + get_event_loop().run_until_complete(wait(tasks)) +``` + +and you will get an output like this: + +```bash +INFO:root:Starting make_task(1,) +INFO:root:Starting make_task(3,) +INFO:root:Starting make_task(2,) +INFO:root:Ending make_task(1,) after 1 seconds +INFO:root:Ending make_task(2,) after 2 seconds +INFO:root:Ending make_task(3,) after 3 seconds +``` This may be handy if you have trouble understanding what it going on with a particularly complex chain of coroutines. With a single line you @@ -815,12 +848,12 @@ will return the right answer (i.e. ``Tru It is also possible to define decorators converting coroutine functions into regular functions, such as the following: -.. code-block:: python - - @decorator - def coro_to_func(coro, *args, **kw): - "Convert a coroutine into a function" +```python +@decorator +def coro_to_func(coro, *args, **kw): + "Convert a coroutine into a function" return get_event_loop().run_until_complete(coro(*args, **kw)) +``` Notice the diffence: the caller in ``log_start_stop`` was a coroutine function and the associate decorator was converting coroutines->coroutines; @@ -871,11 +904,12 @@ $$writefloat Now ``XMLWriter`` can serialize floats: -.. code-block:: python +```python +>>> writer = XMLWriter() +>>> writer.write(2.3) +'2.3' - >>> writer = XMLWriter() - >>> writer.write(2.3) - '2.3' +``` I could give a down-to-earth example of situations in which it is desiderable to dispatch on more than one argument--for instance, I once implemented @@ -910,26 +944,27 @@ $$winRockScissors Here is the result: -.. code-block:: python +```python +>>> win(Paper(), Rock()) +1 +>>> win(Scissors(), Paper()) +1 +>>> win(Rock(), Scissors()) +1 +>>> win(Paper(), Paper()) +0 +>>> win(Rock(), Rock()) +0 +>>> win(Scissors(), Scissors()) +0 +>>> win(Rock(), Paper()) +-1 +>>> win(Paper(), Scissors()) +-1 +>>> win(Scissors(), Rock()) +-1 - >>> win(Paper(), Rock()) - 1 - >>> win(Scissors(), Paper()) - 1 - >>> win(Rock(), Scissors()) - 1 - >>> win(Paper(), Paper()) - 0 - >>> win(Rock(), Rock()) - 0 - >>> win(Scissors(), Scissors()) - 0 - >>> win(Rock(), Paper()) - -1 - >>> win(Paper(), Scissors()) - -1 - >>> win(Scissors(), Rock()) - -1 +``` The point of generic functions is that they play well with subclassing. For instance, suppose we define a ``StrongRock``, which does not lose against @@ -941,26 +976,27 @@ $$winStrongRockPaper Then you do not need to define other implementations; they are inherited from the parent: -.. code-block:: python +```python +>>> win(StrongRock(), Scissors()) +1 - >>> win(StrongRock(), Scissors()) - 1 +``` You can introspect the precedence used by the dispath algorithm by calling ``.dispatch_info(*types)``: -.. code-block:: python +```python +>>> win.dispatch_info(StrongRock, Scissors) +[('StrongRock', 'Scissors'), ('Rock', 'Scissors')] - >>> win.dispatch_info(StrongRock, Scissors) - [('StrongRock', 'Scissors'), ('Rock', 'Scissors')] +``` Since there is no direct implementation for (``StrongRock``, ``Scissors``), the dispatcher will look at the implementation for (``Rock``, ``Scissors``) which is available. Internally, the algorithm is doing a cross product of the class precedence lists (or *Method Resolution Orders*, -MRO_ for short) of ``StrongRock`` and ``Scissors``, respectively. - -.. _MRO: http://www.python.org/2.3/mro.html +[MRO](http://www.python.org/2.3/mro.html) for short) of ``StrongRock`` + and ``Scissors``, respectively. Generic functions and virtual ancestors ------------------------------------------------- @@ -973,14 +1009,16 @@ Consider this class: $$WithLength This class defines a ``__len__`` method, and is therefore -considered to be a subclass of the abstract base class ``collections.Sized``: +considered to be a subclass of the abstract base class +``collections.abc.Sized`` (``collections.Sized`` on Python 2): -.. code-block:: python +```python +>>> issubclass(WithLength, collections.abc.Sized) +True - >>> issubclass(WithLength, collections.Sized) - True +``` -However, ``collections.Sized`` is not in the MRO_ of ``WithLength``; it +However, ``collections.abc.Sized`` is not in the MRO_ of ``WithLength``; it is not a true ancestor. Any implementation of generic functions (even with single dispatch) must go through some contorsion to take into account the virtual ancestors. @@ -995,12 +1033,13 @@ $$get_length_sized ...then ``get_length`` must be defined on ``WithLength`` instances... -.. code-block:: python +```python +>>> get_length(WithLength()) +0 - >>> get_length(WithLength()) - 0 +``` -...even if ``collections.Sized`` is not a true ancestor of ``WithLength``. +...even if ``collections.abc.Sized`` is not a true ancestor of ``WithLength``. Of course, this is a contrived example--you could just use the builtin ``len``--but you should get the idea. @@ -1016,16 +1055,17 @@ the following: $$SomeSet Here, the author of ``SomeSet`` made a mistake by inheriting from -``collections.Sized`` (instead of ``collections.Set``). +``collections.abc.Sized`` (instead of ``collections.abc.Set``). This is not a problem. You can register *a posteriori* -``collections.Set`` as a virtual ancestor of ``SomeSet``: +``collections.abc.Set`` as a virtual ancestor of ``SomeSet``: -.. code-block:: python +```python +>>> _ = collections.abc.Set.register(SomeSet) +>>> issubclass(SomeSet, collections.abc.Set) +True - >>> _ = collections.Set.register(SomeSet) - >>> issubclass(SomeSet, collections.Set) - True +``` Now, let's define an implementation of ``get_length`` specific to set: @@ -1035,16 +1075,17 @@ The current implementation (and ``functo is able to discern that a ``Set`` is a ``Sized`` object, by looking at the class registry, so it uses the more specific implementation for ``Set``: -.. code-block:: python +```python +>>> get_length(SomeSet()) # NB: the implementation for Sized would give 0 +1 - >>> get_length(SomeSet()) # NB: the implementation for Sized would give 0 - 1 +``` Sometimes it is not clear how to dispatch. For instance, consider a -class ``C`` registered both as ``collections.Iterable`` and -``collections.Sized``, and defines a generic function ``g`` with -implementations for both ``collections.Iterable`` *and* -``collections.Sized``: +class ``C`` registered both as ``collections.abc.Iterable`` and +``collections.abc.Sized``, and defines a generic function ``g`` with +implementations for both ``collections.abc.Iterable`` *and* +``collections.abc.Sized``: $$singledispatch_example1 @@ -1088,11 +1129,12 @@ looking at the implementations. I will j ``.dispatch_info`` is quite essential to see the class precedence list used by algorithm: -.. code-block:: python +```python +>>> g, V = singledispatch_example2() +>>> g.dispatch_info(V) +[('V',), ('Sized',), ('S',), ('Container',)] - >>> g, V = singledispatch_example2() - >>> g.dispatch_info(V) - [('V',), ('Sized',), ('S',), ('Container',)] +``` The current implementation does not implement any kind of cooperation between implementations. In other words, nothing is akin either to @@ -1107,8 +1149,7 @@ Caveats and limitations One thing you should be aware of, is the performance penalty of decorators. The worse case is shown by the following example: -.. code-block:: bash - +```bash $ cat performance.sh python3 -m timeit -s " from decorator import decorator @@ -1127,13 +1168,15 @@ The worse case is shown by the following pass " "f()" +``` On my laptop, using the ``do_nothing`` decorator instead of the -plain function is five times slower:: +plain function is five times slower: +```bash $ bash performance.sh 1000000 loops, best of 3: 1.39 usec per loop 1000000 loops, best of 3: 0.278 usec per loop - +``` Of course, a real life function probably does something more useful than the function ``f`` here, so the real life performance penalty *could* be negligible. As always, the only way to know if there is a @@ -1144,26 +1187,28 @@ tracebacks longer and more difficult to Consider this example: -.. code-block:: python +```python +>>> @trace +... def f(): +... 1/0 - >>> @trace - ... def f(): - ... 1/0 +``` Calling ``f()`` gives you a ``ZeroDivisionError``. But since the function is decorated, the traceback is longer: -.. code-block:: python +```python +>>> f() # doctest: +ELLIPSIS +Traceback (most recent call last): + ... + File "", line 2, in f + File "", line 4, in trace + return f(*args, **kw) + File "", line 3, in f + 1/0 +ZeroDivisionError: ... - >>> f() # doctest: +ELLIPSIS - Traceback (most recent call last): - ... - File "", line 2, in f - File "", line 4, in trace - return f(*args, **kw) - File "", line 3, in f - 1/0 - ZeroDivisionError: ... +``` You see here the inner call to the decorator ``trace``, which calls ``f(*args, **kw)``, and a reference to ``File "", line 2, in f``. @@ -1192,19 +1237,16 @@ signature internally, as you can see by ``inspect.getfullargspec`` - which has been rightly 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. They cannot be used on generic callable objects or built-in functions, due to limitations of the standard library's ``inspect`` module, especially for Python 2. In Python 3.5, many such limitations have been removed, but -I still think that it is cleaner and safer to decorate only -functions. If you want to decorate things like classmethods/staticmethods +I still think that it is cleaner and safer to decorate only functions and +coroutines. If you want to decorate things like classmethods/staticmethods and general callables - which I will never support in the decorator module - -I suggest you to look at the wrapt_ project by Graeme Dumpleton. - -.. _wrapt: https://wrapt.readthedocs.io/en/latest/ +I suggest you to look at the [wrapt](https://wrapt.readthedocs.io/en/latest/) +project by Graeme Dumpleton. There is a strange quirk when decorating functions with keyword arguments, if one of the arguments has the same name used in the @@ -1213,15 +1255,17 @@ David Goldstein. Here is an example where it is manifest: -.. code-block:: python +```python +>>> @memoize +... def getkeys(**kw): +... return kw.keys() - >>> @memoize - ... def getkeys(**kw): - ... return kw.keys() - >>> getkeys(func='a') # doctest: +ELLIPSIS - Traceback (most recent call last): - ... - TypeError: _memoize() got multiple values for ... 'func' +>>> getkeys(func='a') # doctest: +ELLIPSIS +Traceback (most recent call last): + ... +TypeError: _memoize() got multiple values for ... 'func' + +``` The error message looks really strange... until you realize that the caller function `_memoize` uses `func` as first argument, @@ -1231,19 +1275,20 @@ keywork arguments. The solution is to change the name of the first argument in `_memoize`, or to change the implementation like so: -.. code-block:: python +```python - def _memoize(*all_args, **kw): - func = all_args[0] - args = all_args[1:] - if kw: # frozenset is used to ensure hashability - key = args, frozenset(kw.items()) - else: - key = args - cache = func.cache # attribute added by memoize - if key not in cache: - cache[key] = func(*args, **kw) - return cache[key] +def _memoize(*all_args, **kw): + func = all_args[0] + args = all_args[1:] + if kw: # frozenset is used to ensure hashability + key = args, frozenset(kw.items()) + else: + key = args + cache = func.cache # attribute added by memoize + if key not in cache: + cache[key] = func(*args, **kw) + return cache[key] +``` This avoids the need to name the first argument, so the problem simply disappears. This is a technique that you should keep in mind @@ -1255,42 +1300,40 @@ that. On a similar note, there is a restriction on argument names. For instance, if you name an argument ``_call_`` or ``_func_``, you will get a ``NameError``: -.. code-block:: python +```python +>>> @trace +... def f(_func_): print(f) +... +Traceback (most recent call last): + ... +NameError: _func_ is overridden in +def f(_func_): + return _call_(_func_, _func_) - >>> @trace - ... def f(_func_): print(f) - ... - Traceback (most recent call last): - ... - NameError: _func_ is overridden in - def f(_func_): - return _call_(_func_, _func_) +``` Finally, the implementation is such that the decorated function makes a (shallow) copy of the original function dictionary: -.. code-block:: python +```python +>>> def f(): pass # the original function +>>> f.attr1 = "something" # setting an attribute +>>> f.attr2 = "something else" # setting another attribute + +>>> traced_f = trace(f) # the decorated function + +>>> traced_f.attr1 +'something' +>>> traced_f.attr2 = "something different" # setting attr +>>> f.attr2 # the original attribute did not change +'something else' - >>> def f(): pass # the original function - >>> f.attr1 = "something" # setting an attribute - >>> f.attr2 = "something else" # setting another attribute - - >>> traced_f = trace(f) # the decorated function - - >>> traced_f.attr1 - 'something' - >>> traced_f.attr2 = "something different" # setting attr - >>> f.attr2 # the original attribute did not change - 'something else' - -.. _function annotations: http://www.python.org/dev/peps/pep-3107/ -.. _docutils: http://docutils.sourceforge.net/ -.. _pygments: http://pygments.org/ +``` LICENSE (2-clause BSD) --------------------------------------------- -Copyright (c) 2005-2017, Michele Simionato +Copyright (c) 2005-2020, Michele Simionato All rights reserved. Redistribution and use in source and binary forms, with or without @@ -1325,46 +1368,50 @@ you are unhappy with it, send me a patch function_annotations = """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. Here is an example: -.. code-block:: python +```python +>>> @trace +... def f(x: 'the first argument', y: 'default argument'=1, z=2, +... *args: 'varargs', **kw: 'kwargs'): +... pass - >>> @trace - ... def f(x: 'the first argument', y: 'default argument'=1, z=2, - ... *args: 'varargs', **kw: 'kwargs'): - ... pass +``` In order to introspect functions with annotations, one needs the utility ``inspect.getfullargspec`` (introduced in Python 3, then deprecated in Python 3.5, then undeprecated in Python 3.6): -.. code-block:: python +```python +>>> from inspect import getfullargspec +>>> argspec = getfullargspec(f) +>>> argspec.args +['x', 'y', 'z'] +>>> argspec.varargs +'args' +>>> argspec.varkw +'kw' +>>> argspec.defaults +(1, 2) +>>> argspec.kwonlyargs +[] +>>> argspec.kwonlydefaults - >>> from inspect import getfullargspec - >>> argspec = getfullargspec(f) - >>> argspec.args - ['x', 'y', 'z'] - >>> argspec.varargs - 'args' - >>> argspec.varkw - 'kw' - >>> argspec.defaults - (1, 2) - >>> argspec.kwonlyargs - [] - >>> argspec.kwonlydefaults +``` You can check that the ``__annotations__`` dictionary is preserved: -.. code-block:: python +```python +>>> f.__annotations__ is f.__wrapped__.__annotations__ +True - >>> f.__annotations__ is f.__wrapped__.__annotations__ - True +``` Here ``f.__wrapped__`` is the original undecorated function. This attribute exists for consistency with the behavior of @@ -1374,17 +1421,7 @@ Another attribute copied from the origin the qualified name. This attribute was introduced in Python 3.3. """ -import sys -import threading -import time -import functools -import itertools -import collections -import collections as c -from decorator import (decorator, decorate, FunctionMaker, contextmanager, - dispatch_on, __version__) - -if sys.version < '3': +if sys.version_info < (3,): function_annotations = '' today = time.strftime('%Y-%m-%d') @@ -1496,7 +1533,7 @@ def blocking(f, msg='blocking', *args, * f.thread = threading.Thread(None, set_result) f.thread.start() return msg - elif f.thread.isAlive(): + elif f.thread.is_alive(): return msg else: # the thread is ended, return the stored result del f.thread @@ -1540,15 +1577,15 @@ def restricted(func, user_class=User, *a class Action(object): - @restricted(User) + @restricted(user_class=User) def view(self): "Any user can view objects" - @restricted(PowerUser) + @restricted(user_class=PowerUser) def insert(self): "Only power users can insert objects" - @restricted(Admin) + @restricted(user_class=Admin) def delete(self): "Only the admin can delete objects" @@ -1617,7 +1654,7 @@ def a_test_for_pylons(): """ -if sys.version >= '3': # tests for signatures specific to Python 3 +if sys.version_info >= (3,): # tests for signatures specific to Python 3 def test_kwonlydefaults(): """ @@ -1749,7 +1786,7 @@ class WithLength(object): return 0 -class SomeSet(collections.Sized): +class SomeSet(collections.abc.Sized): # methods that make SomeSet set-like # not shown ... def __len__(self): @@ -1761,12 +1798,12 @@ def get_length(obj): raise NotImplementedError(type(obj)) -@get_length.register(collections.Sized) +@get_length.register(collections.abc.Sized) def get_length_sized(obj): return len(obj) -@get_length.register(collections.Set) +@get_length.register(collections.abc.Set) def get_length_set(obj): return 1 @@ -1775,8 +1812,8 @@ class C(object): "Registered as Sized and Iterable" -collections.Sized.register(C) -collections.Iterable.register(C) +collections.abc.Sized.register(C) +collections.abc.Iterable.register(C) def singledispatch_example1(): @@ -1786,11 +1823,11 @@ def singledispatch_example1(): def g(obj): raise NotImplementedError(type(g)) - @g.register(collections.Sized) + @g.register(collections.abc.Sized) def g_sized(object): return "sized" - @g.register(collections.Iterable) + @g.register(collections.abc.Iterable) def g_iterable(object): return "iterable" @@ -1827,6 +1864,34 @@ def singledispatch_example2(): return g, V +@decorator +def warn_slow(func, duration=0, *args, **kwargs): + t0 = time.time() + res = func(*args, **kwargs) + dt = time.time() - t0 + if dt >= duration: + print('%s is slow' % func.__name__) + return res + + +@warn_slow() # with parens +def operation1(): + """ + >>> operation1() + operation1 is slow + """ + time.sleep(.1) + + +@warn_slow # without parens +def operation2(): + """ + >>> operation2() + operation2 is slow + """ + time.sleep(.1) + + if __name__ == '__main__': import doctest doctest.testmod() diff -pruN 4.3.0-1.1/src/tests/test.py 4.4.2-0ubuntu1/src/tests/test.py --- 4.3.0-1.1/src/tests/test.py 2018-04-15 12:45:04.000000000 +0000 +++ 4.4.2-0ubuntu1/src/tests/test.py 2020-02-29 04:50:53.000000000 +0000 @@ -6,10 +6,15 @@ import decimal import inspect import functools import collections +from collections import defaultdict +try: + c = collections.abc +except AttributeError: + c = collections from decorator import dispatch_on, contextmanager, decorator try: from . import documentation as doc -except: +except (ImportError, ValueError, SystemError): # depending on the py-version import documentation as doc @@ -23,7 +28,8 @@ def assertRaises(etype): else: raise Exception('Expected %s' % etype.__name__) -if sys.version >= '3.5': + +if sys.version_info >= (3, 5): exec('''from asyncio import get_event_loop @decorator @@ -52,6 +58,23 @@ class CoroutineTestCase(unittest.TestCas ''') +def gen123(): + yield 1 + yield 2 + yield 3 + + +class GeneratorCallerTestCase(unittest.TestCase): + def test_gen123(self): + @decorator + def square(func, *args, **kw): + for x in gen123(): + yield x * x + new = square(gen123) + self.assertTrue(inspect.isgeneratorfunction(new)) + self.assertEqual(list(new()), [1, 4, 9]) + + class DocumentationTestCase(unittest.TestCase): def test(self): err = doctest.testmod(doc)[0] @@ -69,7 +92,7 @@ class DocumentationTestCase(unittest.Tes class ExtraTestCase(unittest.TestCase): def test_qualname(self): - if sys.version >= '3.3': + if sys.version_info >= (3, 3): self.assertEqual(doc.hello.__qualname__, 'hello') else: with assertRaises(AttributeError): @@ -134,7 +157,7 @@ class ExtraTestCase(unittest.TestCase): def f(x): return x - self.assertEqual(add(2, f)(0), 2) + self.assertEqual(add(f, 2)(0), 2) # ################### test dispatch_on ############################# # @@ -237,7 +260,6 @@ class TestSingleDispatch(unittest.TestCa self.assertEqual(g(rnd), ("Number got rounded",)) def test_register_abc(self): - c = collections d = {"a": "b"} l = [1, 2, 3] s = set([object(), None]) @@ -348,8 +370,6 @@ class TestSingleDispatch(unittest.TestCa self.assertEqual(g(t), "tuple") def test_mro_conflicts(self): - c = collections - @singledispatch def g(obj): return "base" @@ -410,9 +430,9 @@ class TestSingleDispatch(unittest.TestCa # MutableMapping's bases implicit as well from defaultdict's # perspective. with assertRaises(RuntimeError): - self.assertEqual(h(c.defaultdict(lambda: 0)), "sized") + self.assertEqual(h(defaultdict(lambda: 0)), "sized") - class R(c.defaultdict): + class R(defaultdict): pass c.MutableSequence.register(R)