Contents

Overview

Decorators for deprecating and refactoring

• Free software: Apache Software License 2.0

Installation

pip install pyoneering

Documentation

https://python-pyoneering.readthedocs.io/

Development

To run the all tests run:

tox

Note, to combine the coverage data from all the tox environments run:

Windows	set PYTEST_ADDOPTS=--cov-append tox
Other	PYTEST_ADDOPTS=--cov-append tox

Installation

You can install pyoneering with pip or pipenv.

$ pip install pyoneering

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

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_kwarg3=True, old_kwarg2=False)  # Generates warning:
merged_parameter :: Deprecated since 0.4.
Replace (old_kwarg3=True, old_kwarg2=False) with (new_kwarg1='error').

Reference

pyoneering

class pyoneering.DevUtils(current_version, stages=None, used_in_production=False, preset=None)

This class contains the decorators to annotate objects in a deprecation cycle.

deprecated(*version_identifiers, details=None)

Decorator to mark a class, function, staticmethod, classmethod or instancemethod as deprecated

• Inserts information to the docstring describing the current (and next) deprecation stage.
• Generates a DeprecationWarning if the decorator gets called.

Parameters:

• version_identifiers – Specify versions at which the decorated object enters next stage.
• details – Additional information to integrate in docstring

Raises:

TypeError – If stages not in ascending order.

refactored(*version_identifiers, parameter_map, details=None)

Decorator to mark keyword arguments as deprecated

• Replaces old keywords with new ones.
• Generates a DeprecationWarning with if a deprecated keyword argument was passed.

Parameters:

• version_identifiers – Specify versions at which the decorated object enters next stage.
• parameter_map – If keyword arguments got renamed, pass a dict with (old_keyword=new_keyword) items. Otherwise pass a function with old_keywords and their default values as parameter which returns a dict of new_keywords mapped to new values.
• details – Additional information to integrate in docstring

Raises:

TypeError – If stages not in ascending order.

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Bug reports

When reporting a bug please include:

• Your operating system name and version.
• Any details about your local setup that might be helpful in troubleshooting.
• Detailed steps to reproduce the bug.

Documentation improvements

pyoneering could always use more documentation, whether as part of the official pyoneering docs, in docstrings, or even on the web in blog posts, articles, and such.

Feature requests and feedback

The best way to send feedback is to file an issue at https://github.com/FHaase/python-pyoneering/issues.

If you are proposing a feature:

• Explain in detail how it would work.
• Keep the scope as narrow as possible, to make it easier to implement.
• Remember that this is a volunteer-driven project, and that code contributions are welcome :)

Development

To set up python-pyoneering for local development:

1. Fork python-pyoneering (look for the “Fork” button).

2. Clone your fork locally:

   git clone git@github.com:your_name_here/python-pyoneering.git
   

3. Create a branch for local development:

   git checkout -b name-of-your-bugfix-or-feature
   

   Now you can make your changes locally.

4. When you’re done making changes, run all the checks, doc builder and spell checker with tox one command:

   tox
   

5. Commit your changes and push your branch to GitHub:

   git add .
   git commit -m "Your detailed description of your changes."
   git push origin name-of-your-bugfix-or-feature
   

6. Submit a pull request through the GitHub website.

Pull Request Guidelines

If you need some code review or feedback while you’re developing the code just make the pull request.

For merging, you should:

1. Include passing tests (run tox) [1].
2. Update documentation when there’s new API, functionality etc.
3. Add a note to CHANGELOG.rst about the changes.
4. Add yourself to AUTHORS.rst.

[1]	If you don’t have all the necessary python versions available locally you can rely on Travis - it will run the tests for each change you add in the pull request. It will be slower though …

Tips

To run a subset of tests:

tox -e envname -- pytest -k test_myfeature

To run all the test environments in parallel (you need to pip install detox):

detox

Authors

• Fabian Haase - https://blog.ionelmc.ro

Changelog

0.1.0 (2018-10-12)

• First release on PyPI.

Indices and tables

• Index
• Module Index
• Search Page