Hello community, here is the log from the commit of package python-Deprecated for openSUSE:Factory checked in at 2020-05-04 18:41:24 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Comparing /work/SRC/openSUSE:Factory/python-Deprecated (Old) and /work/SRC/openSUSE:Factory/.python-Deprecated.new.2738 (New) ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Package is "python-Deprecated" Mon May 4 18:41:24 2020 rev:4 rq:799995 version:1.2.9 Changes: -------- --- /work/SRC/openSUSE:Factory/python-Deprecated/python-Deprecated.changes 2020-01-13 22:22:48.334553885 +0100 +++ /work/SRC/openSUSE:Factory/.python-Deprecated.new.2738/python-Deprecated.changes 2020-05-04 18:42:47.269331963 +0200 @@ -1,0 +2,14 @@ +Mon May 4 08:17:33 UTC 2020 - Johannes Grassler <johannes.grass...@suse.com> + +- update to 1.2.9 + * Fix #20: Set the :func:warnings.warn stacklevel to 2 if + the Python implementation is PyPy + * Fix packit configuration: use dist-git-branch: fedora-all + * Change the Tox configuration to run tests on PyPy v2.7 and 3.6. + * Fix #15: The @deprecated decorator doesn't set a warning + filter if the action keyword argument is not provided or None. + * Fix #13: Warning displays the correct filename and line + number when decorating a class if wrapt does not have the compiled c + extension. + +------------------------------------------------------------------- Old: ---- Deprecated-1.2.7.tar.gz New: ---- Deprecated-1.2.9.tar.gz ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Other differences: ------------------ ++++++ python-Deprecated.spec ++++++ --- /var/tmp/diff_new_pack.QNx5YT/_old 2020-05-04 18:42:49.185335914 +0200 +++ /var/tmp/diff_new_pack.QNx5YT/_new 2020-05-04 18:42:49.189335923 +0200 @@ -18,7 +18,7 @@ %{?!python_module:%define python_module() python-%{**} python3-%{**}} Name: python-Deprecated -Version: 1.2.7 +Version: 1.2.9 Release: 0 Summary: Python @deprecated decorator License: MIT ++++++ Deprecated-1.2.7.tar.gz -> Deprecated-1.2.9.tar.gz ++++++ diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/.bumpversion.cfg new/Deprecated-1.2.9/.bumpversion.cfg --- old/Deprecated-1.2.7/.bumpversion.cfg 2019-10-02 20:18:27.000000000 +0200 +++ new/Deprecated-1.2.9/.bumpversion.cfg 2020-04-05 22:45:36.000000000 +0200 @@ -1,5 +1,5 @@ [bumpversion] -current_version = 1.2.7 +current_version = 1.2.9 commit = True tag = False message = Prepare next version {new_version} (unreleased) @@ -19,4 +19,3 @@ [bumpversion:file:python-deprecated.spec] search = (?<=Version:\s+){current_version} replace = {new_version} - diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/.editorconfig new/Deprecated-1.2.9/.editorconfig --- old/Deprecated-1.2.7/.editorconfig 2019-10-02 20:18:27.000000000 +0200 +++ new/Deprecated-1.2.9/.editorconfig 2020-04-10 09:54:34.000000000 +0200 @@ -9,5 +9,8 @@ indent_size = 4 charset = utf-8 +[*.{yml,yaml}] +indent_size = 2 + [*.{bat,cmd,ps1}] end_of_line = crlf diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/.packit.yml new/Deprecated-1.2.9/.packit.yml --- old/Deprecated-1.2.7/.packit.yml 1970-01-01 01:00:00.000000000 +0100 +++ new/Deprecated-1.2.9/.packit.yml 2020-04-10 09:54:34.000000000 +0200 @@ -0,0 +1,32 @@ +specfile_path: python-deprecated.spec +synced_files: + - python-deprecated.spec + - .packit.yml +upstream_project_name: Deprecated +downstream_package_name: python-deprecated +create_pr: false +jobs: + - job: propose_downstream + trigger: release + metadata: + dist-git-branch: master + - job: propose_downstream + trigger: release + metadata: + dist-git-branch: fedora-all + - job: propose_downstream + trigger: release + metadata: + dist-git-branch: f30 + - job: propose_downstream + trigger: release + metadata: + dist-git-branch: f29 + - job: copr_build + trigger: pull_request + metadata: + targets: + - fedora-all + - fedora-30-x86_64 + - fedora-29-x86_64 + - fedora-rawhide-x86_64 diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/CHANGELOG.rst new/Deprecated-1.2.9/CHANGELOG.rst --- old/Deprecated-1.2.7/CHANGELOG.rst 2019-11-11 16:04:12.000000000 +0100 +++ new/Deprecated-1.2.9/CHANGELOG.rst 2020-04-10 09:54:34.000000000 +0200 @@ -18,6 +18,58 @@ (only in comment or documentation). +v1.2.9 (2020-04-10) +=================== + +Bug fix release + +Fix +--- + +- Fix #20: Set the :func:`warnings.warn` stacklevel to 2 if the Python implementation is `PyPy <https://www.pypy.org/>`_. + +- Fix packit configuration: use ``dist-git-branch: fedora-all``. + +Other +----- + +- Change the Tox configuration to run tests on PyPy v2.7 and 3.6. + + +v1.2.8 (2020-04-05) +=================== + +Bug fix release + +Fix +--- + +- Fix #15: The ``@deprecated`` decorator doesn't set a warning filter if the *action* keyword argument is + not provided or ``None``. In consequences, the warning messages are only emitted if the global filter allow it. + For more information, see `The Warning Filter <https://docs.python.org/3/library/warnings.html#the-warnings-filter>`_ + in the Python documentation. + +- Fix #13: Warning displays the correct filename and line number when decorating a class if wrapt + does not have the compiled c extension. + +Documentation +------------- + +- The :ref:`api` documentation and the :ref:`tutorial` is improved to explain how to use + custom warning categories and local filtering (warning filtering at function call). + +- Fix #17: Customize the sidebar to add links to the documentation to the source in GitHub and to the Bug tracker. + Add a logo in the sidebar and change the logo in the main page to see the library version. + +- Add a detailed documentation about :ref:`sphinx_deco`. + + +Other +----- + +- Change the Tox configuration to test the library with Wrapt 1.12.x. + + v1.2.7 (2019-11-11) =================== @@ -26,7 +78,7 @@ Fix --- -- Warning displays the correct filename and line number when decorating a function if wrapt +- Fix #13: Warning displays the correct filename and line number when decorating a function if wrapt does not have the compiled c extension. Other diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/Deprecated.egg-info/PKG-INFO new/Deprecated-1.2.9/Deprecated.egg-info/PKG-INFO --- old/Deprecated-1.2.7/Deprecated.egg-info/PKG-INFO 2019-11-11 16:04:57.000000000 +0100 +++ new/Deprecated-1.2.9/Deprecated.egg-info/PKG-INFO 2020-04-10 10:30:26.000000000 +0200 @@ -1,6 +1,6 @@ Metadata-Version: 2.1 Name: Deprecated -Version: 1.2.7 +Version: 1.2.9 Summary: Python @deprecated decorator to deprecate old python classes, functions or methods. Home-page: https://github.com/tantale/deprecated Author: Laurent LAPORTE @@ -165,4 +165,5 @@ Classifier: Programming Language :: Python :: 3.7 Classifier: Topic :: Software Development :: Libraries :: Python Modules Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.* +Description-Content-Type: text/x-rst Provides-Extra: dev diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/Deprecated.egg-info/SOURCES.txt new/Deprecated-1.2.9/Deprecated.egg-info/SOURCES.txt --- old/Deprecated-1.2.7/Deprecated.egg-info/SOURCES.txt 2019-11-11 16:04:57.000000000 +0100 +++ new/Deprecated-1.2.9/Deprecated.egg-info/SOURCES.txt 2020-04-10 10:30:26.000000000 +0200 @@ -1,5 +1,6 @@ .bumpversion.cfg .editorconfig +.packit.yml .travis.yml CHANGELOG.rst CONTRIBUTING.rst @@ -8,6 +9,8 @@ Makefile README.md appveyor.yml +pyproject.toml +python-deprecated.spec setup.cfg setup.py tox.ini @@ -34,10 +37,16 @@ docs/source/installation.rst docs/source/introduction.rst docs/source/license.rst +docs/source/sphinx_deco.rst docs/source/tutorial.rst docs/source/white_paper.rst +docs/source/_static/banner.png docs/source/_static/logo-full.png docs/source/_static/title-page.jpg +docs/source/sphinx/calc_mean.py +docs/source/sphinx/calc_mean_deco.py +docs/source/sphinx/sphinx_demo.py +docs/source/sphinx/use_calc_mean_deco.py docs/source/tutorial/v0/liberty.py docs/source/tutorial/v1/liberty.py docs/source/tutorial/v1/using_liberty.py @@ -47,7 +56,9 @@ docs/source/tutorial/v3/using_liberty.py docs/source/tutorial/v4/liberty.py docs/source/tutorial/v4/using_liberty.py -docs/source/tutorial/v5/sphinx_demo.py +docs/source/tutorial/warning_ctrl/filter_action_demo.py +docs/source/tutorial/warning_ctrl/filter_warnings_demo.py +docs/source/tutorial/warning_ctrl/warning_classes_demo.py tests/__init__.py tests/test.py tests/test_deprecated.py diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/MANIFEST.in new/Deprecated-1.2.9/MANIFEST.in --- old/Deprecated-1.2.7/MANIFEST.in 2019-10-02 20:18:27.000000000 +0200 +++ new/Deprecated-1.2.9/MANIFEST.in 2020-04-05 22:41:59.000000000 +0200 @@ -8,6 +8,8 @@ include .editorconfig include *.rst +include *.spec +include *.yaml include *.yml include Makefile include tox.ini diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/PKG-INFO new/Deprecated-1.2.9/PKG-INFO --- old/Deprecated-1.2.7/PKG-INFO 2019-11-11 16:05:00.000000000 +0100 +++ new/Deprecated-1.2.9/PKG-INFO 2020-04-10 10:30:26.000000000 +0200 @@ -1,6 +1,6 @@ Metadata-Version: 2.1 Name: Deprecated -Version: 1.2.7 +Version: 1.2.9 Summary: Python @deprecated decorator to deprecate old python classes, functions or methods. Home-page: https://github.com/tantale/deprecated Author: Laurent LAPORTE @@ -165,4 +165,5 @@ Classifier: Programming Language :: Python :: 3.7 Classifier: Topic :: Software Development :: Libraries :: Python Modules Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.* +Description-Content-Type: text/x-rst Provides-Extra: dev diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/README.md new/Deprecated-1.2.9/README.md --- old/Deprecated-1.2.7/README.md 2019-10-02 20:18:27.000000000 +0200 +++ new/Deprecated-1.2.9/README.md 2020-04-05 22:17:11.000000000 +0200 @@ -59,7 +59,7 @@ ## Authors The authors of this library are: -[Marcos CARDOSO](https://github.com/tantale), and +[Marcos CARDOSO](https://github.com/vrcmarcos), and [Laurent LAPORTE](https://github.com/tantale). The original code was made in [this StackOverflow post](https://stackoverflow.com/questions/2536307) by diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/deprecated/__init__.py new/Deprecated-1.2.9/deprecated/__init__.py --- old/Deprecated-1.2.7/deprecated/__init__.py 2019-10-02 20:18:27.000000000 +0200 +++ new/Deprecated-1.2.9/deprecated/__init__.py 2020-04-05 22:45:36.000000000 +0200 @@ -8,6 +8,6 @@ """ #: Module Version Number, see `PEP 396 <https://www.python.org/dev/peps/pep-0396/>`_. -__version__ = "1.2.7" +__version__ = "1.2.9" from deprecated.classic import deprecated diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/deprecated/classic.py new/Deprecated-1.2.9/deprecated/classic.py --- old/Deprecated-1.2.7/deprecated/classic.py 2019-11-11 14:45:11.000000000 +0100 +++ new/Deprecated-1.2.9/deprecated/classic.py 2020-04-10 09:53:49.000000000 +0200 @@ -5,22 +5,29 @@ Classic ``@deprecated`` decorator to deprecate old python classes, functions or methods. +.. _The Warnings Filter: https://docs.python.org/3/library/warnings.html#the-warnings-filter """ import functools import inspect import warnings +import platform import wrapt try: - # If the c extension for wrapt was compiled and wrapt/_wrappers.pyd exists, then the + # If the C extension for wrapt was compiled and wrapt/_wrappers.pyd exists, then the # stack level that should be passed to warnings.warn should be 2. However, if using # a pure python wrapt, a extra stacklevel is required. import wrapt._wrappers - _stacklevel = 2 -except ImportError: - _stacklevel = 3 + _routine_stacklevel = 2 + _class_stacklevel = 2 +except ImportError: + _routine_stacklevel = 3 + if platform.python_implementation() == "PyPy": + _class_stacklevel = 2 + else: + _class_stacklevel = 3 string_types = (type(b''), type(u'')) @@ -76,7 +83,7 @@ return x + y """ - def __init__(self, reason="", version="", action='always', category=DeprecationWarning): + def __init__(self, reason="", version="", action=None, category=DeprecationWarning): """ Construct a wrapper adapter. @@ -94,7 +101,8 @@ :param action: A warning filter used to activate or not the deprecation warning. Can be one of "error", "ignore", "always", "default", "module", or "once". - By default the deprecation warning is always emitted (the value is "always"). + If ``None`` or empty, the the global filtering mechanism is used. + See: `The Warnings Filter`_ in the Python documentation. :type category: type :param category: @@ -144,6 +152,9 @@ .. versionchanged:: 1.2.4 Don't pass arguments to :meth:`object.__new__` (other than *cls*). + + .. versionchanged:: 1.2.8 + The warning filter is not set if the *action* parameter is ``None`` or empty. """ if inspect.isclass(wrapped): old_new1 = wrapped.__new__ @@ -151,14 +162,15 @@ def wrapped_cls(cls, *args, **kwargs): msg = self.get_deprecated_msg(wrapped, None) with warnings.catch_warnings(): - warnings.simplefilter(self.action, self.category) - warnings.warn(msg, category=self.category, stacklevel=2) + if self.action: + warnings.simplefilter(self.action, self.category) + warnings.warn(msg, category=self.category, stacklevel=_class_stacklevel) if old_new1 is object.__new__: return old_new1(cls) # actually, we don't know the real signature of *old_new1* - return old_new1(*args, **kwargs) + return old_new1(cls, *args, **kwargs) - wrapped.__new__ = classmethod(wrapped_cls) + wrapped.__new__ = staticmethod(wrapped_cls) return wrapped @@ -199,8 +211,8 @@ class SomeOldClass(object): pass - You can give a "reason" message to help the developer to choose another function/class, - and a "version" number to specify the starting version number of the deprecation. + You can give a *reason* message to help the developer to choose another function/class, + and a *version* number to specify the starting version number of the deprecation. .. code-block:: python @@ -211,6 +223,33 @@ def some_old_function(x, y): return x + y + The *category* keyword argument allow you to specify the deprecation warning class of your choice. + By default, :exc:`DeprecationWarning` is ued but you can choose :exc:`FutureWarning`, + :exc:`PendingDeprecationWarning` or a custom subclass. + + .. code-block:: python + + from deprecated import deprecated + + + @deprecated(category=PendingDeprecationWarning) + def some_old_function(x, y): + return x + y + + The *action* keyword argument allow you to locally change the warning filtering. + *action* can be one of "error", "ignore", "always", "default", "module", or "once". + If ``None``, empty or missing, the the global filtering mechanism is used. + See: `The Warnings Filter`_ in the Python documentation. + + .. code-block:: python + + from deprecated import deprecated + + + @deprecated(action="error") + def some_old_function(x, y): + return x + y + """ if args and isinstance(args[0], string_types): kwargs['reason'] = args[0] @@ -220,7 +259,7 @@ raise TypeError(repr(type(args[0]))) if args: - action = kwargs.get('action', 'always') + action = kwargs.get('action') category = kwargs.get('category', DeprecationWarning) adapter_cls = kwargs.pop('adapter_cls', ClassicAdapter) adapter = adapter_cls(**kwargs) @@ -236,8 +275,9 @@ def wrapper_function(wrapped_, instance_, args_, kwargs_): msg = adapter.get_deprecated_msg(wrapped_, instance_) with warnings.catch_warnings(): - warnings.simplefilter(action, category) - warnings.warn(msg, category=category, stacklevel=_stacklevel) + if action: + warnings.simplefilter(action, category) + warnings.warn(msg, category=category, stacklevel=_routine_stacklevel) return wrapped_(*args_, **kwargs_) return wrapper_function(wrapped) diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/deprecated/sphinx.py new/Deprecated-1.2.9/deprecated/sphinx.py --- old/Deprecated-1.2.7/deprecated/sphinx.py 2019-10-27 16:29:38.000000000 +0100 +++ new/Deprecated-1.2.9/deprecated/sphinx.py 2020-02-23 07:15:14.000000000 +0100 @@ -40,7 +40,7 @@ - The reason message is obviously added in the directive block if not empty. """ - def __init__(self, directive, reason="", version="", action='always', category=DeprecationWarning): + def __init__(self, directive, reason="", version="", action=None, category=DeprecationWarning): """ Construct a wrapper adapter. @@ -62,7 +62,8 @@ :param action: A warning filter used to activate or not the deprecation warning. Can be one of "error", "ignore", "always", "default", "module", or "once". - By default the deprecation warning is always emitted (the value is "always"). + If ``None`` or empty, the the global filtering mechanism is used. + See: `The Warnings Filter`_ in the Python documentation. :type category: type :param category: @@ -170,7 +171,7 @@ - "action": A warning filter used to activate or not the deprecation warning. Can be one of "error", "ignore", "always", "default", "module", or "once". - By default the deprecation warning is always emitted (the value is "always"). + If ``None``, empty or missing, the the global filtering mechanism is used. - "category": The warning category to use for the deprecation warning. Binary files old/Deprecated-1.2.7/docs/source/_static/banner.png and new/Deprecated-1.2.9/docs/source/_static/banner.png differ Binary files old/Deprecated-1.2.7/docs/source/_static/logo-full.png and new/Deprecated-1.2.9/docs/source/_static/logo-full.png differ diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/docs/source/conf.py new/Deprecated-1.2.9/docs/source/conf.py --- old/Deprecated-1.2.7/docs/source/conf.py 2019-10-27 16:48:22.000000000 +0100 +++ new/Deprecated-1.2.9/docs/source/conf.py 2020-04-05 22:45:36.000000000 +0200 @@ -61,7 +61,7 @@ # built documents. # # The full version, including alpha/beta/rc tags. -release = "1.2.7" +release = "1.2.9" # The short X.Y version. version = release.rpartition('.')[0] diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/docs/source/index.rst new/Deprecated-1.2.9/docs/source/index.rst --- old/Deprecated-1.2.7/docs/source/index.rst 2019-10-02 20:18:27.000000000 +0200 +++ new/Deprecated-1.2.9/docs/source/index.rst 2020-04-05 22:24:53.000000000 +0200 @@ -1,7 +1,7 @@ Welcome to Deprecated ===================== -.. image:: _static/logo-full.png +.. image:: _static/banner.png :alt: Deprecated: When once-stable features are removed in upcoming releases Welcome to Deprecated’s Documentation. @@ -23,6 +23,7 @@ installation introduction tutorial + sphinx_deco white_paper diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/docs/source/sphinx/calc_mean.py new/Deprecated-1.2.9/docs/source/sphinx/calc_mean.py --- old/Deprecated-1.2.7/docs/source/sphinx/calc_mean.py 1970-01-01 01:00:00.000000000 +0100 +++ new/Deprecated-1.2.9/docs/source/sphinx/calc_mean.py 2020-04-05 22:17:11.000000000 +0200 @@ -0,0 +1,12 @@ +def mean(values): + """ + Compute the arithmetic mean (“average”) of values. + + :type values: list[float] + :param values: List of floats + :return: Mean of values. + + .. deprecated:: 2.5.0 + Since Python 3.4, you can use the standard function :func:`statistics.mean`. + """ + return sum(values) / len(values) diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/docs/source/sphinx/calc_mean_deco.py new/Deprecated-1.2.9/docs/source/sphinx/calc_mean_deco.py --- old/Deprecated-1.2.7/docs/source/sphinx/calc_mean_deco.py 1970-01-01 01:00:00.000000000 +0100 +++ new/Deprecated-1.2.9/docs/source/sphinx/calc_mean_deco.py 2020-04-05 22:17:11.000000000 +0200 @@ -0,0 +1,16 @@ +from deprecated.sphinx import deprecated + + +@deprecated( + reason="""Since Python 3.4, you can use the standard function :func:`statistics.mean`.""", + version="2.5.0", +) +def mean(values): + """ + Compute the arithmetic mean (“average”) of values. + + :type values: list[float] + :param values: List of floats + :return: Mean of values. + """ + return sum(values) / len(values) diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/docs/source/sphinx/sphinx_demo.py new/Deprecated-1.2.9/docs/source/sphinx/sphinx_demo.py --- old/Deprecated-1.2.7/docs/source/sphinx/sphinx_demo.py 1970-01-01 01:00:00.000000000 +0100 +++ new/Deprecated-1.2.9/docs/source/sphinx/sphinx_demo.py 2020-04-05 22:17:11.000000000 +0200 @@ -0,0 +1,33 @@ +# coding: utf-8 +from deprecated.sphinx import deprecated +from deprecated.sphinx import versionadded +from deprecated.sphinx import versionchanged + + +@deprecated( + reason=""" + This is deprecated, really. So you need to use another function. + But I don\'t know which one. + + - The first, + - The second. + + Just guess! + """, + version='0.3.0', +) +@versionchanged( + reason='Well, I add a new feature in this function. ' + 'It is very useful as you can see in the example below, so try it. ' + 'This is a very very very very very long sentence.', + version='0.2.0', +) +@versionadded(reason='Here is my new function.', version='0.1.0') +def successor(n): + """ + Calculate the successor of a number. + + :param n: a number + :return: number + 1 + """ + return n + 1 diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/docs/source/sphinx/use_calc_mean_deco.py new/Deprecated-1.2.9/docs/source/sphinx/use_calc_mean_deco.py --- old/Deprecated-1.2.7/docs/source/sphinx/use_calc_mean_deco.py 1970-01-01 01:00:00.000000000 +0100 +++ new/Deprecated-1.2.9/docs/source/sphinx/use_calc_mean_deco.py 2020-04-05 22:17:11.000000000 +0200 @@ -0,0 +1,3 @@ +from calc_mean_deco import mean + +print(mean.__doc__) diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/docs/source/sphinx_deco.rst new/Deprecated-1.2.9/docs/source/sphinx_deco.rst --- old/Deprecated-1.2.7/docs/source/sphinx_deco.rst 1970-01-01 01:00:00.000000000 +0100 +++ new/Deprecated-1.2.9/docs/source/sphinx_deco.rst 2020-04-05 22:31:25.000000000 +0200 @@ -0,0 +1,157 @@ +.. _Sphinx: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html +.. _Sphinx directives: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html +.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html +.. _Markdown: https://www.sphinx-doc.org/en/master/usage/markdown.html +.. _docstring: https://docs.python.org/3/glossary.html#term-docstring +.. _autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html + +.. _sphinx_deco: + +The "Sphinx" decorators +======================= + +Overview +-------- + +Developers use the Deprecated library to decorate deprecated functions or classes. This is very practical, +but you know that this library does more: you can also document your source code! How? +It's very simple: instead of using the "classic" decorator, you can use one of the "Sphinx" decorators. + +The "Sphinx" decorators have the same function as the "classic" decorator but also allow you to add +`Sphinx directives`_ in your functions or classes documentation (inside the docstring_). + +.. attention:: + + In Python 3.3 and previous versions, the docstring of a class is immutable [#f1]_, this means that you cannot + use the "Sphinx" decorators. Naturally, this limitation does not exist in Python 3.4 and above. + +What is a Sphinx directive? +--------------------------- + +Sphinx_ is a tool that makes it easy to create intelligent and beautiful documentation. +This tool uses the reStructuredText_ (or Markdown_) syntax to generate the documentation in different formats, +the most common being HTML. Developers generally use this syntax to document the source code of their applications. + +Sphinx_ offers several directives allowing to introduce a text block with a predefined role. +Among all the directives, the ones that interest us are those related to the functions (or classes) +life cycle, namely: ``versionadded``, ``versionchanged`` and ``deprecated``. + +In the following example, the *mean()* function can be documented as follows: + +.. literalinclude:: sphinx/calc_mean.py + +Therefore, the "Sphinx" decorators allow you to add a Sphinx directive to your functions +or classes documentation. In the case of the ``deprecated`` directive, it obviously allows you to emit a +:exc:`DeprecationWarning` warning. + +Using the "Sphinx" decorators +----------------------------- + +The previous example can be writen using a "Sphinx" decorator: + +.. literalinclude:: sphinx/calc_mean_deco.py + +You can see the generated documentation with this simple call: + +.. literalinclude:: sphinx/use_calc_mean_deco.py + +The documentation of the *mean()* function looks like this: + +.. code-block:: rst + + Compute the arithmetic mean (“average”) of values. + + :type values: list[float] + :param values: List of floats + :return: Mean of values. + + .. deprecated:: 2.5.0 + Since Python 3.4, you can use the standard function + :func:`statistics.mean`. + +More elaborate example +---------------------- + +The Deprecated library offers you 3 decorators: + +- :func:`~deprecated.sphinx.deprecated`: insert a ``deprecated`` directive in docstring, and emit a warning on each call. +- :func:`~deprecated.sphinx.versionadded`: insert a ``versionadded`` directive in docstring, don't emit warning. +- :func:`~deprecated.sphinx.versionchanged`: insert a ``versionchanged`` directive in docstring, don't emit warning. + +The decorators can be combined to reflect the life cycle of a function: + +- When it is added in your API, with the ``@versionadded`` decorator, +- When it has an important change, with the ``@versionchanged`` decorator, +- When it is deprecated, with the ``@deprecated`` decorator. + +The example bellow illustrate this life cycle: + +.. literalinclude:: sphinx/sphinx_demo.py + +To see the result, you can use the builtin function :func:`help` to display a formatted help message +of the *successor()* function. It is something like this: + +.. code-block:: text + + Help on function successor in module __main__: + + successor(n) + Calculate the successor of a number. + + :param n: a number + :return: number + 1 + + + .. versionadded:: 0.1.0 + Here is my new function. + + + .. versionchanged:: 0.2.0 + Well, I add a new feature in this function. It is very useful as + you can see in the example below, so try it. This is a very very + very very very long sentence. + + + .. deprecated:: 0.3.0 + This is deprecated, really. So you need to use another function. + But I don't know which one. + + - The first, + - The second. + + Just guess! + +.. note:: Decorators must be writen in reverse order: recent first, older last. + +Building the documentation +-------------------------- + +The easiest way to build your API documentation is to use the autodoc_ plugin. +The directives like ``automodule``, ``autoclass``, ``autofunction`` scan your source code +and generate the documentation from your docstrings. + +Usually, the first thing that we need to do is indicate where the Python package that contains your +source code is in relation to the ``conf.py`` file. + +But here, that will not work! The reason is that your modules must be imported during build: +the Deprecated decorators must be interpreted. + +So, to build the API documentation of your project with Sphinx_ you need to setup a virtualenv, +and install Sphinx, external themes and/or plugins and also your project. +Nowadays, this is the right way to do it. + +For instance, you can configure a documentation building task in your ``tox.ini`` file, for instance: + +.. code-block:: ini + + [testenv:docs] + basepython = python + deps = + sphinx + commands = + sphinx-build -b html -d {envtmpdir}/doctrees docs/source/ {envtmpdir}/html + + +.. rubric:: Footnotes + +.. [#f1] See Issue 12773: `classes should have mutable docstrings <https://bugs.python.org/issue12773>`_. diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/docs/source/tutorial/v5/sphinx_demo.py new/Deprecated-1.2.9/docs/source/tutorial/v5/sphinx_demo.py --- old/Deprecated-1.2.7/docs/source/tutorial/v5/sphinx_demo.py 2019-10-27 16:32:40.000000000 +0100 +++ new/Deprecated-1.2.9/docs/source/tutorial/v5/sphinx_demo.py 1970-01-01 01:00:00.000000000 +0100 @@ -1,36 +0,0 @@ -# coding: utf-8 -from deprecated.sphinx import deprecated -from deprecated.sphinx import versionadded -from deprecated.sphinx import versionchanged - - -@deprecated( - reason=""" - This is deprecated, really. So you need to use another function. - But I don\'t know which one. - - - The first, - - The second. - - Just guess! - """, - version='0.3.0', -) -@versionchanged( - reason='Well, I add a new feature in this function. ' - 'It is very useful as you can see in the example below, so try it. ' - 'This is a very very very very very long sentence.', - version='0.2.0', -) -@versionadded(reason='Here is my new function.', version='0.1.0') -def successor(n): - """ - Calculate the successor of a number. - - :param n: a number - :return: number + 1 - """ - return n + 1 - - -help(successor) diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/docs/source/tutorial/warning_ctrl/filter_action_demo.py new/Deprecated-1.2.9/docs/source/tutorial/warning_ctrl/filter_action_demo.py --- old/Deprecated-1.2.7/docs/source/tutorial/warning_ctrl/filter_action_demo.py 1970-01-01 01:00:00.000000000 +0100 +++ new/Deprecated-1.2.9/docs/source/tutorial/warning_ctrl/filter_action_demo.py 2020-02-22 18:04:29.000000000 +0100 @@ -0,0 +1,12 @@ +import warnings +from deprecated import deprecated + + +@deprecated(reason="do not call it", action="error") +def foo(): + print("foo") + + +if __name__ == '__main__': + warnings.simplefilter("ignore") + foo() diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/docs/source/tutorial/warning_ctrl/filter_warnings_demo.py new/Deprecated-1.2.9/docs/source/tutorial/warning_ctrl/filter_warnings_demo.py --- old/Deprecated-1.2.7/docs/source/tutorial/warning_ctrl/filter_warnings_demo.py 1970-01-01 01:00:00.000000000 +0100 +++ new/Deprecated-1.2.9/docs/source/tutorial/warning_ctrl/filter_warnings_demo.py 2020-02-22 18:04:29.000000000 +0100 @@ -0,0 +1,12 @@ +import warnings +from deprecated import deprecated + + +@deprecated(version='1.2.1', reason="deprecated function") +def fun(): + print("fun") + + +if __name__ == '__main__': + warnings.simplefilter("ignore", category=DeprecationWarning) + fun() diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/docs/source/tutorial/warning_ctrl/warning_classes_demo.py new/Deprecated-1.2.9/docs/source/tutorial/warning_ctrl/warning_classes_demo.py --- old/Deprecated-1.2.7/docs/source/tutorial/warning_ctrl/warning_classes_demo.py 1970-01-01 01:00:00.000000000 +0100 +++ new/Deprecated-1.2.9/docs/source/tutorial/warning_ctrl/warning_classes_demo.py 2020-02-22 18:04:29.000000000 +0100 @@ -0,0 +1,31 @@ +import warnings + +from deprecated import deprecated + + +class MyDeprecationWarning(DeprecationWarning): + """ My DeprecationWarning """ + + +class DeprecatedIn26(MyDeprecationWarning): + """ deprecated in 2.6 """ + + +class DeprecatedIn30(MyDeprecationWarning): + """ deprecated in 3.0 """ + + +@deprecated(category=DeprecatedIn26, reason="deprecated function") +def foo(): + print("foo") + + +@deprecated(category=DeprecatedIn30, reason="deprecated function") +def bar(): + print("bar") + + +if __name__ == '__main__': + warnings.filterwarnings("ignore", category=DeprecatedIn30) + foo() + bar() diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/docs/source/tutorial.rst new/Deprecated-1.2.9/docs/source/tutorial.rst --- old/Deprecated-1.2.7/docs/source/tutorial.rst 2019-10-02 20:18:27.000000000 +0200 +++ new/Deprecated-1.2.9/docs/source/tutorial.rst 2020-04-05 22:17:11.000000000 +0200 @@ -29,10 +29,10 @@ $ python use_liberty.py - using_liberty.py:4: DeprecationWarning: Call to deprecated function print_value. + using_liberty.py:4: DeprecationWarning: Call to deprecated function (or staticmethod) print_value. liberty.print_value("hello") 'hello' - using_liberty.py:5: DeprecationWarning: Call to deprecated function print_value. + using_liberty.py:5: DeprecationWarning: Call to deprecated function (or staticmethod) print_value. liberty.print_value("hello again") 'hello again' 'Hi Tom!' @@ -52,10 +52,10 @@ $ python use_liberty.py - using_liberty.py:4: DeprecationWarning: Call to deprecated function print_value (This function is rotten, use 'better_print' instead). + using_liberty.py:4: DeprecationWarning: Call to deprecated function (or staticmethod) print_value. (This function is rotten, use 'better_print' instead) liberty.print_value("hello") 'hello' - using_liberty.py:5: DeprecationWarning: Call to deprecated function print_value (This function is rotten, use 'better_print' instead). + using_liberty.py:5: DeprecationWarning: Call to deprecated function (or staticmethod) print_value. (This function is rotten, use 'better_print' instead) liberty.print_value("hello again") 'hello again' 'Hi Tom!' @@ -78,10 +78,10 @@ $ python use_liberty.py - using_liberty.py:5: DeprecationWarning: Call to deprecated function print_value (This method is rotten, use 'better_print' instead). + using_liberty.py:5: DeprecationWarning: Call to deprecated method print_value. (This method is rotten, use 'better_print' instead) obj.print_value() 'Greeting' - using_liberty.py:6: DeprecationWarning: Call to deprecated function print_value (This method is rotten, use 'better_print' instead). + using_liberty.py:6: DeprecationWarning: Call to deprecated method print_value. (This method is rotten, use 'better_print' instead) obj.print_value() 'Greeting' 'Greeting' @@ -109,7 +109,7 @@ $ python use_liberty.py - using_liberty.py:4: DeprecationWarning: Call to deprecated class Liberty (This class is not perfect). + using_liberty.py:4: DeprecationWarning: Call to deprecated class Liberty. (This class is not perfect) obj = liberty.Liberty("Salutation") 'Salutation' 'Salutation' @@ -121,3 +121,124 @@ Using this method you can customize the instance creation. the :func:`~deprecated.deprecated` decorator patches the ``__new__`` method in order to emmit the warning message before instance creation. + + +Controlling warnings +-------------------- + +.. _Python warning control: https://docs.python.org/3/library/warnings.html +.. _-W: https://docs.python.org/3/using/cmdline.html#cmdoption-w +.. _PYTHONWARNINGS: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONWARNINGS + +Warnings are emitted using the `Python warning control`_. By default, Python installs several warning filters, +which can be overridden by the `-W`_ command-line option, the `PYTHONWARNINGS`_ environment variable and +calls to :func:`warnings.filterwarnings`. The warnings filter controls whether warnings are ignored, displayed, +or turned into errors (raising an exception). + +For instance: + +.. literalinclude:: tutorial/warning_ctrl/filter_warnings_demo.py + +When the user runs this script, the deprecation warnings are ignored in the main program, +so no warning message are emitted: + +.. code-block:: sh + + $ python filter_warnings_demo.py + + fun + + +Deprecation warning classes +--------------------------- + +The :func:`deprecated.classic.deprecated` and :func:`deprecated.sphinx.deprecated` functions +are using the :exc:`DeprecationWarning` category but you can customize them by using your own category +(or hierarchy of categories). + +* *category* classes which you can use (among other) are: + + +----------------------------------+-----------------------------------------------+ + | Class | Description | + +==================================+===============================================+ + | :exc:`DeprecationWarning` | Base category for warnings about deprecated | + | | features when those warnings are intended for | + | | other Python developers (ignored by default, | + | | unless triggered by code in ``__main__``). | + +----------------------------------+-----------------------------------------------+ + | :exc:`FutureWarning` | Base category for warnings about deprecated | + | | features when those warnings are intended for | + | | end users of applications that are written in | + | | Python. | + +----------------------------------+-----------------------------------------------+ + | :exc:`PendingDeprecationWarning` | Base category for warnings about features | + | | that will be deprecated in the future | + | | (ignored by default). | + +----------------------------------+-----------------------------------------------+ + +You can define your own deprecation warning hierarchy based on the standard deprecation classes. + +For instance: + +.. literalinclude:: tutorial/warning_ctrl/warning_classes_demo.py + +When the user runs this script, the deprecation warnings for the 3.0 version are ignored: + +.. code-block:: sh + + $ python warning_classes_demo.py + + foo + bar + warning_classes_demo.py:30: DeprecatedIn26: Call to deprecated function (or staticmethod) foo. (deprecated function) + foo() + + +Filtering warnings locally +-------------------------- + +The :func:`deprecated.classic.deprecated` and :func:`deprecated.sphinx.deprecated` functions +can change the warning filtering locally (at function calls). + +* *action* is one of the following strings: + + +---------------+----------------------------------------------+ + | Value | Disposition | + +===============+==============================================+ + | ``"default"`` | print the first occurrence of matching | + | | warnings for each location (module + | + | | line number) where the warning is issued | + +---------------+----------------------------------------------+ + | ``"error"`` | turn matching warnings into exceptions | + +---------------+----------------------------------------------+ + | ``"ignore"`` | never print matching warnings | + +---------------+----------------------------------------------+ + | ``"always"`` | always print matching warnings | + +---------------+----------------------------------------------+ + | ``"module"`` | print the first occurrence of matching | + | | warnings for each module where the warning | + | | is issued (regardless of line number) | + +---------------+----------------------------------------------+ + | ``"once"`` | print only the first occurrence of matching | + | | warnings, regardless of location | + +---------------+----------------------------------------------+ + +You can define the *action* keyword parameter to override the filtering warnings locally. + +For instance: + +.. literalinclude:: tutorial/warning_ctrl/filter_action_demo.py + +In this example, even if the global filter is set to "ignore", a call to the ``foo()`` +function will raise an exception because the *action* is set to "error". + +.. code-block:: sh + + $ python filter_action_demo.py + + Traceback (most recent call last): + File "filter_action_demo.py", line 12, in <module> + foo() + File "path/to/deprecated/classic.py", line 274, in wrapper_function + warnings.warn(msg, category=category, stacklevel=_stacklevel) + DeprecationWarning: Call to deprecated function (or staticmethod) foo. (do not call it) diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/pyproject.toml new/Deprecated-1.2.9/pyproject.toml --- old/Deprecated-1.2.7/pyproject.toml 1970-01-01 01:00:00.000000000 +0100 +++ new/Deprecated-1.2.9/pyproject.toml 2020-02-23 18:51:31.000000000 +0100 @@ -0,0 +1,5 @@ +[tool.black] +line-length = 120 +skip-string-normalization = true +target-version = ['py27', 'py34', 'py35', 'py36', 'py37', 'py38'] +include = '\.pyi?$' diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/python-deprecated.spec new/Deprecated-1.2.9/python-deprecated.spec --- old/Deprecated-1.2.7/python-deprecated.spec 1970-01-01 01:00:00.000000000 +0100 +++ new/Deprecated-1.2.9/python-deprecated.spec 2020-04-05 22:57:56.000000000 +0200 @@ -0,0 +1,49 @@ +%global srcname Deprecated +%global pkgname deprecated + +Name: python-%{pkgname} +Version: 1.2.9 +Release: 2%{?dist} +Summary: Python decorator to deprecate old python classes, functions or methods +License: MIT +URL: https://github.com/tantale/%{pkgname} +Source0: https://files.pythonhosted.org/packages/source/D/%{srcname}/%{srcname}-%{version}.tar.gz +BuildArch: noarch + +%description +Python @deprecated decorator to deprecate old python classes, +functions or methods. + +%package -n python3-%{pkgname} +Summary: %{summary} +BuildRequires: python3-devel +BuildRequires: python3-setuptools +%{?python_provide:%python_provide python3-%{pkgname}} + +%description -n python3-%{pkgname} +Python @deprecated decorator to deprecate old python classes, +functions or methods. + +%prep +%autosetup -n %{srcname}-%{version} +rm -rf %{pkgname}.egg-info + +%build +%py3_build + +%install +%py3_install + +%files -n python3-%{pkgname} +%license LICENSE.rst +%doc README.md +%{python3_sitelib}/%{pkgname}/ +%{python3_sitelib}/%{srcname}-%{version}-*.egg-info/ + + +%changelog +* Fri Jul 26 2019 Petr Hracek <phra...@redhat.com> - 1.2.6-2 +- Fix python3_sitelib issue + +* Fri Jul 26 2019 Petr Hracek <phra...@redhat.com> - 1.2.6-1 +- Initial package diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/setup.py new/Deprecated-1.2.9/setup.py --- old/Deprecated-1.2.7/setup.py 2019-10-27 16:32:40.000000000 +0100 +++ new/Deprecated-1.2.9/setup.py 2020-04-10 10:30:23.000000000 +0200 @@ -143,7 +143,7 @@ setup( name='Deprecated', - version='1.2.7', + version='1.2.9', url='https://github.com/tantale/deprecated', project_urls={ "Documentation": "https://deprecated.readthedocs.io/en/latest/", @@ -155,6 +155,7 @@ author_email='tantale.soluti...@gmail.com', description='Python @deprecated decorator to deprecate old python classes, functions or methods.', long_description=__doc__, + long_description_content_type="text/x-rst", keywords='deprecate,deprecated,deprecation,warning,warn,decorator', packages=['deprecated'], install_requires=['wrapt < 2, >= 1.10'], diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/tests/test_deprecated.py new/Deprecated-1.2.9/tests/test_deprecated.py --- old/Deprecated-1.2.7/tests/test_deprecated.py 2019-11-11 14:45:11.000000000 +0100 +++ new/Deprecated-1.2.9/tests/test_deprecated.py 2020-02-22 18:04:29.000000000 +0100 @@ -241,3 +241,15 @@ foo() warn = warns[0] assert issubclass(warn.category, MyDeprecationWarning) + + +def test_respect_global_filter(): + @deprecated.classic.deprecated(version='1.2.1', reason="deprecated function") + def fun(): + print("fun") + + warnings.simplefilter("ignore", category=DeprecationWarning) + + with warnings.catch_warnings(record=True) as warns: + fun() + assert len(warns) == 0 diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Deprecated-1.2.7/tox.ini new/Deprecated-1.2.9/tox.ini --- old/Deprecated-1.2.7/tox.ini 2019-11-11 14:45:11.000000000 +0100 +++ new/Deprecated-1.2.9/tox.ini 2020-04-10 09:53:24.000000000 +0200 @@ -8,9 +8,12 @@ [tox] # py32 not supported by tox and pytest +# PyPy configuration (on Linux/OSX): +# - /usr/local/bin/pypy -> /opt/pypy2.7-v7.3.0-osx64/bin/pypy +# - /usr/local/bin/pypy3 -> /opt/pypy3.6-v7.3.0-osx64/bin/pypy3 envlist = - py{27,34,35,36,37,38}-wrapt{1.10,1.11} - pypy + py{27,34,35,36,37,38}-wrapt{1.10,1.11,1.12} + pypy, pypy3 docs [testenv] @@ -18,11 +21,12 @@ deps = py27,py34,py35: pip >= 9.0.3, < 19.2 py27,py34: PyTest < 5 - py35,py36,py37,py38,pypy: PyTest + py35,py36,py37,py38,pypy,pypy3: PyTest py27,py34: PyTest-Cov < 2.6 - py35,py36,py37,py38,pypy: PyTest-Cov + py35,py36,py37,py38,pypy,pypy3: PyTest-Cov wrapt1.10: wrapt ~= 1.10.0 wrapt1.11: wrapt ~= 1.11.0 + wrapt1.12: wrapt ~= 1.12.0 [testenv:docs] basepython = python