deprecation — deprecation 2.0.7 documentation

# `deprecation`

`deprecation` is a library that enables automated deprecations. It offers the `deprecated()` decorator to wrap functions, providing proper warnings both in documentation and via Python’s `warnings` system, as well as the `deprecation.fail_if_not_removed()` decorator for test methods to ensure that deprecated code is eventually removed.

See API Documentation to jump straight into the options. See the sample module page for an example of `deprecation`’s effect on a module’s Sphinx autodoc generated documentation.

# Installation

>     pip install deprecation

# Using `@deprecated`

To mark a function or method as deprecated, wrap it in the `deprecated()` decorator. This does several things for you:

1. The docstring of the wrapped function will have details appended to it from the arguments you set on `deprecated()`. This takes care of telling your users not only that the function is deprecated, but can also tell them when it’s going away and what they can do in the meantime.

2. In conjunction with the `fail_if_not_removed()` decorator it removes the need for any sort of manual tracking of when a sufficiently deprecated piece of code should be removed from the codebase. It causes tests to fail when they contain code which should be removed.

>     import deprecation

>     @deprecation.deprecated(deprecated_in="1.0", removed_in="2.0",
>                             current_version=__version__,
>                             details="Use the bar function instead")
>     def foo():
>         """Do some stuff"""
>         return 1

Now look at the docs. If you you generate API documentation from your source like the sample module does, you’ll see that the a sentence has been appended to a deprecated function’s docstring to include information about when the function is deprecated, when it’ll be removed, and what you can do instead. For example, run `help(foo)` and this is what you’ll get:

>     Help on function foo in module example:

>     foo()
>         Do some stuff

>         *Deprecated in 1.0, to be removed in 2.0. Use the bar function instead*

You can pass varying amounts of detail to this decorator, but note that in most cases it removes the ability to use `fail_if_not_removed()`. See the API Documentation for full details.

# Using `@fail_if_not_removed`

Once you’ve marked code for deprecation via `deprecated()`, you can sit back and relax as most of the work has been done for you. Assuming you’ve provided sufficient detail to the decorator, you now just wait for your tests to tell you it’s time to delete the code in question.

If you wrap test methods which use your now deprecated code in `fail_if_not_removed()`, the test will fail with a message notifying you that you should remove this code.

>     @deprecation.fail_if_not_removed
>     def test_won(self):
>         self.assertEqual(1, won())

Looking at the sample module docs, we can see that this function would fail the tests at version 2.0, when it should be removed. The following shows what test output will look like for a failure.

>     AssertionError: <function Tests.test_won at 0x10af33268> uses a function
>     that should be removed: who is unsupported as of 2.0. Use the ``one``
>     function instead

# API Documentation

`deprecation.` `deprecated`(deprecated_in=None, removed_in=None, current_version=None, details='')

  Decorate a function to signify its deprecation

  This function wraps a method that will soon be removed and does two things:

    - The docstring of the method will be modified to include a notice about deprecation, e.g., “Deprecated since 0.9.11. Use foo instead.”

    - Raises a `DeprecatedWarning` via the `warnings` module, which is a subclass of the built-in `DeprecationWarning`. Note that built-in `DeprecationWarning`s are ignored by default, so for users to be informed of said warnings they will need to enable them--see the :mod:`warnings` module documentation for more details.

  Parameters

    - deprecated_in – The version at which the decorated method is considered deprecated. This will usually be the next version to be released when the decorator is added. The default is None, which effectively means immediate deprecation. If this is not specified, then the removed_in and current_version arguments are ignored.

    - removed_in – The version or datetime.date when the decorated method will be removed. The default is None, specifying that the function is not currently planned to be removed. Note: This parameter cannot be set to a value if deprecated_in=None.

    - current_version – The source of version information for the currently running code. This will usually be a __version__ attribute on your library. The default is None. When current_version=None the automation to determine if the wrapped function is actually in a period of deprecation or time for removal does not work, causing a `DeprecatedWarning` to be raised in all cases.

    - details – Extra details to be added to the method docstring and warning. For example, the details may point users to a replacement method, such as “Use the foo_bar method instead”. By default there are no details.

`deprecation.` `message_location` = 'bottom'

  Location where the details are added to a deprecated docstring

  When set to `"bottom"`, the details are appended to the end. When set to `"top"`, the details are inserted between the summary line and docstring contents.

`deprecation.` `fail_if_not_removed`(method)

  Decorate a test method to track removal of deprecated code

  This decorator catches `UnsupportedWarning` warnings that occur during testing and causes unittests to fail, making it easier to keep track of when code should be removed.

  Raises

    `AssertionError` if an `UnsupportedWarning` is raised while running the test method.

exception `deprecation.` `DeprecatedWarning`(function, deprecated_in, removed_in, details='')

  A warning class for deprecated methods

  This is a specialization of the built-in `DeprecationWarning`, adding parameters that allow us to get information into the __str__ that ends up being sent through the `warnings` system. The attributes aren’t able to be retrieved after the warning gets raised and passed through the system as only the class–not the instance–and message are what gets preserved.

  Parameters

    - function – The function being deprecated.

    - deprecated_in – The version that `function` is deprecated in

    - removed_in – The version or `datetime.date` specifying when `function` gets removed.

    - details – Optional details about the deprecation. Most often this will include directions on what to use instead of the now deprecated code.

exception `deprecation.` `UnsupportedWarning`(function, deprecated_in, removed_in, details='')

  A warning class for methods to be removed

  This is a subclass of `DeprecatedWarning` and is used to output a proper message about a function being unsupported. Additionally, the `fail_if_not_removed()` decorator will handle this warning and cause any tests to fail if the system under test uses code that raises this warning.