.. _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 `_. :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 `_. :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 `_ 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 `_. :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 `_. :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 `_. :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/