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 (numpydoc compatible)

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. 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.

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.

Current deprecators

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

Future deprecators

  • kwarg renaming
  • Swapping the order of positional arguments
  • Making an old kwarg a manditory positional arg
  • Feature requests are welcome!

Development Lead

  • Mark Harfouche

Contributors

Could be you!

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.2.2 (2018.08.13)

  • Check for numpydoc 0.7
  • Fix a typo in the docstring message

0.2.2 (2018.08.12)

  • API change. change_default_parameter now takes a dictionary for the old_kwargs so that parameter names don't conflict

0.2.1 (2018.08.12)

  • Merge with other numpydocs so that documentation in Sphinx doesn't crash

0.2.0 (2018.08.11)

  • Provide a deprecator for changing the number of keyword only arguments.

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.4.tar.gz (33.9 kB view details)

Uploaded Source

Built Distribution

deprecation_factory-0.2.4-py3-none-any.whl (18.0 kB view details)

Uploaded Python 3

File details

Details for the file deprecation_factory-0.2.4.tar.gz.

File metadata

  • Download URL: deprecation_factory-0.2.4.tar.gz
  • Upload date:
  • Size: 33.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.0.0 requests-toolbelt/0.8.0 tqdm/4.24.0 CPython/3.6.3

File hashes

Hashes for deprecation_factory-0.2.4.tar.gz
Algorithm Hash digest
SHA256 2fe8a2d9d867391e8a7e792e5eaebadb5c8939cdb3083efb0a84cc9ffdee95e4
MD5 313042ceff35a5a231600196022d6320
BLAKE2b-256 dc13e9574e769d1342e6326b5bba90991a4ec2eff23bb63e6f3167d4fbacf2c7

See more details on using hashes here.

File details

Details for the file deprecation_factory-0.2.4-py3-none-any.whl.

File metadata

  • Download URL: deprecation_factory-0.2.4-py3-none-any.whl
  • Upload date:
  • Size: 18.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.0.0 requests-toolbelt/0.8.0 tqdm/4.24.0 CPython/3.6.3

File hashes

Hashes for deprecation_factory-0.2.4-py3-none-any.whl
Algorithm Hash digest
SHA256 0f51cc9db29e23dda53f4d09fdf7b64d34578e38483c68f27da6f78ab5e1ee37
MD5 e427fa5d9cb850c823a3754831ff3451
BLAKE2b-256 c6331424305412901bd1cbc82d214a5cc8d81b3e6ddeccfd08214489a40270d0

See more details on using hashes here.

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