RFC: Resolve "Define deprecation policy"

Based on:

• numpy: https://numpy.org/neps/nep-0023-backwards-compatibility.html#policy
• scipy: https://docs.scipy.org/doc/scipy/reference/dev/core-dev/index.html#deprecations
• pandas: https://pandas.pydata.org/pandas-docs/stable/development/policies.html

A deprecation policy could follow this guidelines:

• Deprecations in minor releases.

• Deprecation proposal ( issue maybe? )

• Include the version numbers:

  • when the functionality was deprecated and
  • when it will be removed

• Add a DeprecationWarning:

  • How to achieve similar behavior if an alternative is available or
  • a reason for the deprecation if no clear alternative is available.

• Deprecations will only be enforced in major releases

• decorator idea:

import warnings
from functools import wraps

def deprecate_function(reason, deprecation_version, removing_version):
    def inner_function(function):
        @wraps(function)
        def wrapper(*args, **kwargs):
            warnings.warn((
                f"'{function.__name__}' function was deprecated on version {deprecation_version}. "
                f"Because {reason}. "
                f"It will be removed on next major release {removing_version}."
            ), DeprecationWarning, stacklevel=2)
            function(*args, **kwargs)
        return wrapper
    return inner_function

• usage:

@deprecate_function("we didn't like it so much. Use 'add_multiple_numbers' function instead", '1.0.1', '2.0.0')
def a_plus_b(a, b):
    return a + b

• preview:

>>> a_plus_b(1, 2)
... <ipython-input-65-cc562de3010f>:5: DeprecationWarning: 'a_plus_b' function was deprecated at version 1.0.1.
... Because we didn't like it so much. Use 'add_multiple_numbers' function instead. It will be removed at next
... major realease 2.0.0.
...  a_plus_b(1, 2)

• Alternative deprecated library:

To use this, decorate your deprecated function with @deprecated decorator:

from deprecated import deprecated

@deprecated
def some_old_function(x, y):
    return x + y

You can also decorate a class or a method:

from deprecated import deprecated


class SomeClass(object):
    @deprecated
    def some_old_method(self, x, y):
        return x + y


@deprecated
class SomeOldClass(object):
    pass

You can give a "reason" message to help the developer to choose another function/class:

from deprecated import deprecated


@deprecated(reason="use another function")
def some_old_function(x, y):
    return x + y

Closes #72 (closed)