Skip to main content

Python deprecation factory ensuring useful warnings and docstrings for different deprecations.

Project description

Deprecation Factory

pypi Travis Docs

Python3 deprecation factory. Automatically write boilerplate code for many kinds of deperecations through python decorators.

Motivations

Breaking things is important! Breaking other's things is just mean!

The goal of deprecations is to warn other library writers that their code is about to break so you can keep making agressive changes to your own.

Often when you want to deprecate a feature, you end up following a procedure similar to

  1. Make the useful modification to your code.
  2. Decide on when the old behaviour should be switched over.
  3. Add warnings INSIDE your function to warn users.
  4. Change the function signature to something non-sensical to detect the default behaviour.
  5. Add messages in the documentation.

Finally, when the behaviour is official depreprecated, you need to do all these changes again.

  1. Remove the warnings.
  2. Remove the documentation messages.
  3. Remove the old behaviour.
  4. Change the function signature back to something useful.

The goal of this library is to allow you to shortcut steps 3-9. You shouldn't have to revisit the deprecation long after you completed implementing your new features

This library modifies function signatures and docstrings to make the current version of the function appear in autocompletions and on the automatically generated documentation.

The library will point the user to their line of code, so that they can make the appropriate modifications.

It is even safe to leave the deprecators in place after the threshold version has been reached. The decorator will behave as a no-op and your library will use the updated version of your code. Deprecations should not have to be blockers for your development.

Installation

While you can depend on this, I strongly recommend you version the files you need in your project as the API is highly likely to change and break your code.

Make sure you keep a BSD notice in your code when you version this.

Current deprecators

  • Deprecator for change of default values in kwargs. Handles kwargs passed as positional arguments too!

Future deprecators

  • Transitionning to keyword only arguments.
  • Swapping the order of positional arguments
  • Making an old kwarg a manditory positional arg
  • Feature requests are welcome!

Other directions

  • Input sanitization.

Development Lead

  • Mark Harfouche

Contributors

None yet. Why not be the first?

How to contribute

Ready to contribute? We use the standard github contribution model. Scikit-Image has a great writeup on how to setup your environment. Adapt it for our environment.

Cookiecutter

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

History

0.1.1 (2018.08.09)

  • Deprecated arguments appear in order for Python 3.5 as well.

0.1.0 (2018.08.09)

  • New deprecator for changing the default value of kwards. Handles arguments passed as positional argumnets too.

0.0.1 (2018-07-29)

  • First release on PyPi

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

deprecation_factory-0.2.0.tar.gz (29.3 kB view hashes)

Uploaded Source

Built Distribution

deprecation_factory-0.2.0-py3-none-any.whl (9.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page