Getting started

Configuration

In order to provide a module-wide configuration for the decorators deprecated() and refactored() include the following code-snippet in your module.

from tests.example import __version__

from pyoneering import DevUtils

_module = DevUtils(__version__)
deprecated, refactored = _module.deprecated, _module.refactored

Then these functions are accessible from anywhere in your module.

from tests.example.utils import deprecated, refactored

Examples

The examples are generated with __version__='1.0'.

deprecated class

@deprecated('0.6', '1.8')
class DeprecatedClass:
    """Example of a deprecated class."""
    pass
class tests.example.DeprecatedClass[source]

Example of a deprecated class.

Deprecated since version 0.6: Will be removed in 1.8.

>>> DeprecatedClass()  # Generates warning:
DeprecatedClass :: Deprecated since 0.6. Will be removed in 1.8.

deprecated method

@deprecated('0.2', '0.8', details='Use new method instead')
def deprecated_method():
    """Example of a deprecated method."""
    pass
example.deprecated_method()

Example of a deprecated method.

Deprecated since version 0.2: Use new method instead

>>> deprecated_method()  # Generates warning:
deprecated_method :: Removed since 0.8. Use new method instead

renamed parameter

@refactored('0.4', '2.0', parameter_map={'old_kwarg2': 'new_kwarg1'})
def renamed_parameter(kwarg1=5, new_kwarg1=False):
    """Example of a method with changed signature."""
    pass
example.renamed_parameter(new_kwarg1=False)

Example of a method with changed signature.

Deprecated since version 0.4: Will be removed in 2.0.

Parameter:(old_kwarg2) replaced with (new_kwarg1).
>>> renamed_parameter(old_kwarg2=True)  # Generates warning:
renamed_parameter :: Deprecated since 0.4. Will be removed in 2.0.
Replace (old_kwarg2=True) with (new_kwarg1=True).

merged parameter

def _merged_parameters(old_kwarg2=True, old_kwarg3=False):
    if not old_kwarg2 and not old_kwarg3:
        new_kwarg1 = 'cat-1'
    elif old_kwarg2 and not old_kwarg3:
        new_kwarg1 = 'cat-2'
    else:
        new_kwarg1 = 'error'

    return dict(new_kwarg1=new_kwarg1)
@refactored('0.4', parameter_map=_merged_parameters)
def merged_parameter(kwarg1=5, new_kwarg1='error'):
    """Example of a method with changed signature."""
    pass
example.merged_parameter(new_kwarg1='error')

Example of a method with changed signature.

Deprecated since version 0.4.

Parameter:(old_kwarg2, old_kwarg3) replaced with (new_kwarg1).
>>> merged_parameter(old_kwarg2=True)  # Generates warning:
merged_parameter :: Deprecated since 0.4.
Replace (old_kwarg2=True) with (new_kwarg1='cat-2').
>>> merged_parameter(old_kwarg2=False, old_kwarg3=True)  # Generates warning:
merged_parameter :: Deprecated since 0.4.
Replace (old_kwarg2=False, old_kwarg3=True) with (new_kwarg1='error').