.bumpversion.cfg

 [bumpversion]
-current_version = 1.2.5
+current_version = 1.2.6
 commit = True
-tag = True
+tag = False
+message = Prepare next version {new_version} (unreleased)
 
 [bumpversion:file:setup.py]
 search = version='{current_version}'

CHANGELOG.rst

@@ -18,6 +18,28 @@ and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0
       (only in comment or documentation).
 
 
+v1.2.6 (2019-07-06)
+===================
+
+Bug fix release
+
+Fix
+---
+
+- Fix #9: Change the project's configuration: reinforce the constraint to the Wrapt requirement.
+
+Other
+-----
+
+- Upgrade project configuration (``setup.py``) to add the *project_urls* property:
+  Documentation, Source and Bug Tracker URLs.
+
+- Change the Tox configuration to test the library against different Wrapt versions.
+
+- Fix an issue with the AppVeyor build: upgrade setuptools version in ``appveyor.yml``,
+  change the Tox configuration: set ``py27,py34,py35: pip >= 9.0.3, < 19.2``.
+
+
 v1.2.5 (2019-02-28)
 ===================
 
@@ -158,7 +180,7 @@ Bug fix release
 Fix
 ---
 
-- Fix #4: Correct the function :funct:`~deprecated.deprecated`:
+- Fix #4: Correct the function :func:`~deprecated.deprecated`:
   Don't pass arguments to :meth:`object.__new__` (other than *cls*).
 
 Other

appveyor.yml

@@ -42,6 +42,7 @@ init:
 
 install:
   - "%PYTHON%/Scripts/easy_install -U pip"
+  - "%PYTHON%/Scripts/pip install -U setuptools"
   - "%PYTHON%/Scripts/pip install tox"
   - "%PYTHON%/Scripts/pip install wheel"
 

debian/changelog

+python-deprecated (1.2.6-1) unstable; urgency=medium
+
+  * New upstream release.
+
+ -- Bas Couwenberg <sebastic@debian.org>  Sat, 20 Jul 2019 07:02:47 +0200
+
 python-deprecated (1.2.5-3) unstable; urgency=medium
 
   * Update gbp.conf to use --source-only-changes by default.

deprecated/__init__.py

@@ -8,6 +8,6 @@ Python ``@deprecated`` decorator to deprecate old python classes, functions or m
 """
 
 #: Module Version Number, see `PEP 396 <https://www.python.org/dev/peps/pep-0396/>`_.
-__version__ = "1.2.5"
+__version__ = "1.2.6"
 
 from deprecated.classic import deprecated

docs/source/conf.py

@@ -59,7 +59,7 @@ author = 'Marcos CARDOSO & Laurent LAPORTE'
 # built documents.
 #
 # The full version, including alpha/beta/rc tags.
-release = "1.2.5"
+release = "1.2.6"
 # The short X.Y version.
 version = release.rpartition('.')[0]
 
@@ -169,7 +169,11 @@ texinfo_documents = [
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/3/': None,
-                       'http://wrapt.readthedocs.io/en/latest/': None}
+                       'https://wrapt.readthedocs.io/en/latest/': None,
+                       'http://flask.pocoo.org/docs/1.0/': None,
+                       'django': ('https://docs.djangoproject.com/en/2.1/',
+                                  'https://docs.djangoproject.com/en/2.1/_objects/'),
+                       }
 
 # -- Options for EPub output -------------------------------------------
 

docs/source/index.rst

@@ -23,6 +23,7 @@ instructions for using Deprecated.
    installation
    introduction
    tutorial
+   white_paper
 
 
 API Reference

docs/source/white_paper.rst

+.. _white_paper:
+
+White Paper
+===========
+
+This white paper shows some examples of how function deprecation is implemented in the Python Standard Library and Famous Open Source libraries.
+
+You will see which kind of deprecation you can find in such libraries, and how it is documented in the user manuel.
+
+.. _Python Standard Library:
+
+The Python Standard Library
+---------------------------
+
+:Library: Python_
+:GitHub: `python/cpython <https://github.com/python/cpython.git>`_.
+:Version: v3.8.dev
+
+An example of function deprecation can be found in the :mod:`urllib` module (:file:`Lib/urllib/parse.py`):
+
+.. code-block:: python
+
+    def to_bytes(url):
+        warnings.warn("urllib.parse.to_bytes() is deprecated as of 3.8",
+                      DeprecationWarning, stacklevel=2)
+        return _to_bytes(url)
+
+In the Python library, a warning is emitted in the function body using the function :func:`warnings.warn`.
+This implementation is straightforward, it uses the category :exc:`DeprecationWarning` for warning filtering.
+
+Another example is the deprecation of the *collections* ABC, which are now moved in the :mod:`collections.abc` module.
+This example is available in the :mod:`collections` module (:file:`Lib/collections/__init__.py`):
+
+.. code-block:: python
+
+    def __getattr__(name):
+        if name in _collections_abc.__all__:
+            obj = getattr(_collections_abc, name)
+            import warnings
+            warnings.warn("Using or importing the ABCs from 'collections' instead "
+                          "of from 'collections.abc' is deprecated, "
+                          "and in 3.8 it will stop working",
+                          DeprecationWarning, stacklevel=2)
+            globals()[name] = obj
+            return obj
+        raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+
+The warning is only emitted when an ABC is accessed from the :mod:`collections` instead of :mod:`collections.abc` module.
+
+We can also see an example of keyword argument deprecation in the :class:`~collections.UserDict` class:
+
+.. code-block:: python
+
+    def __init__(*args, **kwargs):
+        if not args:
+            raise TypeError("descriptor '__init__' of 'UserDict' object "
+                            "needs an argument")
+        self, *args = args
+        if len(args) > 1:
+            raise TypeError('expected at most 1 arguments, got %d' % len(args))
+        if args:
+            dict = args[0]
+        elif 'dict' in kwargs:
+            dict = kwargs.pop('dict')
+            import warnings
+            warnings.warn("Passing 'dict' as keyword argument is deprecated",
+                          DeprecationWarning, stacklevel=2)
+        else:
+            dict = None
+        self.data = {}
+        if dict is not None:
+            self.update(dict)
+        if len(kwargs):
+            self.update(kwargs)
+
+Again, this implementation is straightforward: if the *dict* keyword argument is used, a warning is emitted.
+
+Python make also use of the category :exc:`PendingDeprecationWarning` for instance in the :mod:`asyncio.tasks` module
+(:file:`Lib/asyncio/tasks.py`):
+
+.. code-block:: python
+
+    @classmethod
+    def current_task(cls, loop=None):
+        warnings.warn("Task.current_task() is deprecated, "
+                      "use asyncio.current_task() instead",
+                      PendingDeprecationWarning,
+                      stacklevel=2)
+        if loop is None:
+            loop = events.get_event_loop()
+        return current_task(loop)
+
+The category :exc:`FutureWarning` is also used to emit a warning when the functions is broken and will be
+fixed in a "future" release. We can see for instance the method :meth:`~xml.etree.ElementTree.ElementTree.find`
+of the class :class:`~xml.etree.ElementTree.ElementTree` (:file:`Lib/xml/etree/ElementTree.py`):
+
+.. code-block:: python
+
+    def find(self, path, namespaces=None):
+        if path[:1] == "/":
+            path = "." + path
+            warnings.warn(
+                "This search is broken in 1.3 and earlier, and will be "
+                "fixed in a future version.  If you rely on the current "
+                "behaviour, change it to %r" % path,
+                FutureWarning, stacklevel=2
+                )
+        return self._root.find(path, namespaces)
+
+As a conclusion:
+
+-   Python library uses :func:`warnings.warn` to emit a deprecation warning in the body of functions.
+-   3 categories are used: :exc:`DeprecationWarning`, :exc:`PendingDeprecationWarning` and :exc:`FutureWarning`.
+-   The docstring doesn't show anything about deprecation.
+-   The documentation warns about some, but not all, deprecated usages.
+
+.. _Python: https://docs.python.org/fr/3/
+
+.. _Flask Library:
+
+The Flask Library
+-----------------
+
+:Library: Flask_
+:GitHub: `pallets/flask <https://github.com/pallets/flask.git>`_.
+:Version: v1.1.dev
+
+In the source code of Flask, we find only few deprecations: in the :mod:`~flask.app` (:file:`flask/app.py`)
+and in the :mod:`~flask.helpers` (:file:`flask/helpers.py`) modules.
+
+In the Flask Library, like in the `Python Standard Library`_, deprecation warnings are emitted during function calls.
+The implementation make use of the category :exc:`DeprecationWarning`.
+
+Unlike the `Python Standard Library`_, the docstring documents explicitly the deprecation.
+Flask uses Sphinx_’s `deprecated directive`_:
+
+The bellow example shows the deprecation of the :meth:`~flask.Flask.open_session` method:
+
+.. code-block:: python
+
+    def open_session(self, request):
+        """Creates or opens a new session.  Default implementation stores all
+        session data in a signed cookie.  This requires that the
+        :attr:`secret_key` is set.  Instead of overriding this method
+        we recommend replacing the :class:`session_interface`.
+
+        .. deprecated: 1.0
+            Will be removed in 1.1. Use ``session_interface.open_session``
+            instead.
+
+        :param request: an instance of :attr:`request_class`.
+        """
+
+        warnings.warn(DeprecationWarning(
+            '"open_session" is deprecated and will be removed in 1.1. Use'
+            ' "session_interface.open_session" instead.'
+        ))
+        return self.session_interface.open_session(self, request)
+
+.. _deprecated directive: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated
+.. _Sphinx: http://www.sphinx-doc.org/en/stable/index.html
+
+.. hint::
+
+    When the function :func:`warnings.warn` is called with a :exc:`DeprecationWarning` instance,
+    the instance class is used like a warning category.
+
+The documentation also mention a :exc:`flask.exthook.ExtDeprecationWarning` (which is not found in Flask’s source code):
+
+.. code-block:: rst
+
+    Extension imports
+    `````````````````
+
+    Extension imports of the form ``flask.ext.foo`` are deprecated, you should use
+    ``flask_foo``.
+
+    The old form still works, but Flask will issue a
+    ``flask.exthook.ExtDeprecationWarning`` for each extension you import the old
+    way. We also provide a migration utility called `flask-ext-migrate
+    <https://github.com/pallets/flask-ext-migrate>`_ that is supposed to
+    automatically rewrite your imports for this.
+
+As a conclusion:
+
+-   Flask library uses :func:`warnings.warn` to emit a deprecation warning in the body of functions.
+-   Only one category is used: :exc:`DeprecationWarning`.
+-   The docstring use `Sphinx`_’s `deprecated directive`_.
+-   The API documentation contains the deprecated usages.
+
+.. _Flask: http://flask.pocoo.org/docs/
+
+.. _Django Library:
+
+The Django Library
+------------------
+
+:Library: Django
+:GitHub: `django/django <https://github.com/django/django.git>`_.
+:Version: v3.0.dev
+
+The `Django`_ Library defines several categories for deprecation in the module :mod:`django.utils.deprecation`:
+
+-   The category :exc:`~django.utils.deprecation.RemovedInDjango31Warning` which inherits
+    from :exc:`DeprecationWarning`.
+-   The category :exc:`~django.utils.deprecation.RemovedInDjango40Warning` which inherits
+    from :exc:`PendingDeprecationWarning`.
+-   The category :exc:`~django.utils.deprecation.RemovedInNextVersionWarning` which is an alias
+    of :exc:`~django.utils.deprecation.RemovedInDjango40Warning`.
+
+The `Django`_ Library don't use :exc:`DeprecationWarning` or :exc:`PendingDeprecationWarning` directly,
+but always use one of this 2 classes. The category :exc:`~django.utils.deprecation.RemovedInNextVersionWarning`
+is only used in unit tests.
+
+There are a lot of class deprecation examples. The deprecation warning is emitted during the call
+of the ``__init__`` method. For instance in the class :class:`~django.contrib.postgres.forms.ranges.FloatRangeField`
+(:file:`django/contrib/staticfiles/storage.py`):
+
+.. code-block:: python
+
+    class FloatRangeField(DecimalRangeField):
+        base_field = forms.FloatField
+
+        def __init__(self, **kwargs):
+            warnings.warn(
+                'FloatRangeField is deprecated in favor of DecimalRangeField.',
+                RemovedInDjango31Warning, stacklevel=2,
+            )
+            super().__init__(**kwargs)
+
+The implementation in the Django Library is similar to the one done in the `Python Standard Library`_:
+deprecation warnings are emitted during function calls.
+The implementation use the category :exc:`~django.utils.deprecation.RemovedInDjango31Warning`.
+
+In the Django Library, we also find an example of property deprecation:
+The property :meth:`~django.conf.LazySettings.FILE_CHARSET` of the class :class:`django.conf.LazySettings`.
+The implementation of this property is:
+
+.. code-block:: python
+
+    @property
+    def FILE_CHARSET(self):
+        stack = traceback.extract_stack()
+        # Show a warning if the setting is used outside of Django.
+        # Stack index: -1 this line, -2 the caller.
+        filename, _line_number, _function_name, _text = stack[-2]
+        if not filename.startswith(os.path.dirname(django.__file__)):
+            warnings.warn(
+                FILE_CHARSET_DEPRECATED_MSG,
+                RemovedInDjango31Warning,
+                stacklevel=2,
+            )
+        return self.__getattr__('FILE_CHARSET')
+
+We also find function deprecations, mainly with the category :exc:`~django.utils.deprecation.RemovedInDjango40Warning`.
+For instance, the function :func:`~django.utils.encoding.smart_text` emits a deprecation warning as follow:
+
+.. code-block:: python
+
+    def smart_text(s, encoding='utf-8', strings_only=False, errors='strict'):
+        warnings.warn(
+            'smart_text() is deprecated in favor of smart_str().',
+            RemovedInDjango40Warning, stacklevel=2,
+        )
+        return smart_str(s, encoding, strings_only, errors)
+
+The Django Library also define a decorator :class:`~django.utils.deprecation.warn_about_renamed_method`
+which is used internally in the metaclass :class:`~django.utils.deprecation.RenameMethodsBase`.
+This metaclass is only used in unit tests to check renamed methods.
+
+As a conclusion:
+
+-   The Django library uses :func:`warnings.warn` to emit a deprecation warning in the body of functions.
+-   It uses two categories which inherits the standard categories :exc:`DeprecationWarning`
+    and :exc:`PendingDeprecationWarning`.
+-   The source code of the Django Library doesn't contains much docstring.
+    The deprecation never appears in the docstring anyway.
+-   The release notes contain information about deprecated features.
+
+.. _Django: https://docs.djangoproject.com/
+
+The lxml Library
+----------------
+
+:Library: lxml_
+:GitHub: `lxml/lxml <https://github.com/lxml/lxml.git>`_.
+:Version: v4.3.2.dev
+
+The lxml_ Library is developed in Cython, not Python. But, it is a similar language.
+This library mainly use comments or docstring to mark function as deprecated.
+
+For instance, in the class :class:`lxml.xpath._XPathEvaluatorBase`(:file:`src/lxml/xpath.pxi`),
+the ``evaluate`` method is deprecated as follow:
+
+.. code-block:: python
+
+    def evaluate(self, _eval_arg, **_variables):
+        u"""evaluate(self, _eval_arg, **_variables)
+
+        Evaluate an XPath expression.
+
+        Instead of calling this method, you can also call the evaluator object
+        itself.
+
+        Variables may be provided as keyword arguments.  Note that namespaces
+        are currently not supported for variables.
+
+        :deprecated: call the object, not its method.
+        """
+        return self(_eval_arg, **_variables)
+
+There is only one example of usage of the function :func:`warnings.warn`:
+in the :class:`~lxml.etree._ElementTree` class (:file:`src/lxml/etree.pyx`):
+
+.. code-block:: python
+
+    if docstring is not None and doctype is None:
+        import warnings
+        warnings.warn(
+            "The 'docstring' option is deprecated. Use 'doctype' instead.",
+            DeprecationWarning)
+        doctype = docstring
+
+
+As a conclusion:
+
+-   Except in one example, the lxml library doesn't use :func:`warnings.warn` to emit a deprecation warnings.
+-   The deprecations are described in the function docstrings.
+-   The release notes contain information about deprecated features.
+
+.. _lxml: https://lxml.de
+
+The openpyxl Library
+--------------------
+
+:Library: openpyxl
+:Bitbucket: `openpyxl/openpyxl <https://bitbucket.org/openpyxl/openpyxl>`_.
+:Version: v2.6.1.dev
+
+openpyxl_ is a Python library to read/write Excel 2010 xlsx/xlsm/xltx/xltm files.
+Tu warn about deprecation, this library uses a home-made ``@deprecated`` decorator.
+
+The implementation of this decorator is an adapted copy of the first version of Tantale’s ``@deprecated`` decorator.
+It has the enhancement to update the docstring of the decorated function.
+So, this is similar to the function :func:`deprecated.sphinx.deprecated`.
+
+.. code-block:: python
+
+    string_types = (type(b''), type(u''))
+    def deprecated(reason):
+
+        if isinstance(reason, string_types):
+
+            def decorator(func1):
+
+                if inspect.isclass(func1):
+                    fmt1 = "Call to deprecated class {name} ({reason})."
+                else:
+                    fmt1 = "Call to deprecated function {name} ({reason})."
+
+                @wraps(func1)
+                def new_func1(*args, **kwargs):
+                    #warnings.simplefilter('default', DeprecationWarning)
+                    warnings.warn(
+                        fmt1.format(name=func1.__name__, reason=reason),
+                        category=DeprecationWarning,
+                        stacklevel=2
+                    )
+                    return func1(*args, **kwargs)
+
+                # Enhance docstring with a deprecation note
+                deprecationNote = "\n\n.. note::\n    Deprecated: " + reason
+                if new_func1.__doc__:
+                    new_func1.__doc__ += deprecationNote
+                else:
+                    new_func1.__doc__ = deprecationNote
+                return new_func1
+
+            return decorator
+
+        elif inspect.isclass(reason) or inspect.isfunction(reason):
+            raise TypeError("Reason for deprecation must be supplied")
+
+        else:
+            raise TypeError(repr(type(reason)))
+
+As a conclusion:
+
+-   The openpyxl library uses a decorator to deprecate functions.
+-   It uses the category :exc:`DeprecationWarning`.
+-   The decorator update the docstring and add a ``.. note::`` directive,
+    which is visible in the documentation.
+
+.. _openpyxl: https://openpyxl.readthedocs.io/

setup.py

@@ -143,8 +143,12 @@ from setuptools import setup
 
 setup(
     name='Deprecated',
-    version='1.2.5',
+    version='1.2.6',
     url='https://github.com/tantale/deprecated',
+    project_urls={
+        "Documentation": "https://deprecated.readthedocs.io/en/latest/",
+        "Source": "https://github.com/tantale/deprecated",
+        "Bug Tracker": "https://github.com/tantale/deprecated/issues"},
     license='MIT',
     author='Laurent LAPORTE',  # since v1.1.0
     author_email='tantale.solutions@gmail.com',
@@ -153,7 +157,7 @@ setup(
     keywords='deprecate,deprecated,deprecation,warning,warn,decorator',
     packages=['deprecated'],
     install_requires=[
-        'wrapt < 2, >= 1',
+        'wrapt < 2, >= 1.10',
     ],
     zip_safe=False,
     include_package_data=True,

tox.ini

@@ -8,15 +8,21 @@
 
 [tox]
 # py32 not supported by tox and pytest
-envlist = py27,py34,py35,py36,py37,pypy,docs
+envlist =
+    py{27,34,35,36,37}-wrapt{1.10,1.11}
+    pypy
+    docs
 
 [testenv]
 commands = pytest --cov-report term-missing --cov=deprecated tests/
 deps =
+    py27,py34,py35: pip >= 9.0.3, < 19.2
     py27,py34: PyTest < 5
     py35,py36,py37,pypy: PyTest
     py27,py34: PyTest-Cov < 2.6
     py35,py36,py37,pypy: PyTest-Cov
+    wrapt1.10: wrapt ~= 1.10.0
+    wrapt1.11: wrapt ~= 1.11.0
 
 [testenv:docs]
 basepython = python