Python3 wabisabi. Automatically write boilerplate code for many kinds of deperecations through python decorators.
- Free software: BSD license
- Documentation
Link above not working for now: https://deprecation-factory.readthedocs.io/en/latest/?badge=latest
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
- Make the useful modification to your code.
- Decide on when the old behaviour should be switched over.
- Add warnings INSIDE your function to warn users.
- Change the function signature to something non-sensical to detect the default behaviour.
- Add messages in the documentation (numpydoc compatible)
Finally, when the behaviour is official depreprecated, you need to do all these changes again.
- Remove the warnings.
- Remove the documentation messages.
- Remove the old behaviour.
- 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. You write your code how it is supposed to look, this library, makes ensures your users have enough time to update their code.
This library
- Modifies function signatures so to ensure correctness for the current version. This should help with autocompletions.
- Adds a warning section to the docstrings. An attempt is made to properly indent the docstring.
- Point the user to their line of code, so that they know where to make make the appropriate modification.
- Leaving deprecators in place after the desired threshold results in a noop. This means that you can be lazy about ripping them out of code. Deprecations should not have to be blockers for your development.
- If numpydoc > 0.7 is installed, the "Warns" sections are combined into a single section allowing you to chain deprecators.
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.
- Deprecator for change of default values in
kwargs
. Handleskwargs
passed as positional arguments too! - Transitionning to keyword only arguments.
kwarg
renaming
- Swapping the order of positional arguments
- Making an old
kwarg
a manditory positionalarg
- Feature requests are welcome!
- Mark Harfouche
Could be you!
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.
This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.