Deprecations and Other Changes#

Documenting changes and informing uses about them is a very important part of maintaining a library. Handling this is even discussed at length in Maintenance Schedules.

In order to facilitate this, we have a collection of utilities.

Helpers for declaring deprecations, changes, renames, etc.

ppb.changelib.deprecated(reason='', version='', line_length=70, **kwargs)[source]#

This decorator can be used to insert a “deprecated” directive in your function/class docstring in order to documents the version of the project which deprecates this functionality in your library.

Parameters:

  • reason (str) – Reason message which documents the deprecation in your library (can be omitted).

  • version (str) – Version of your project which deprecates this feature. If you follow the Semantic Versioning, the version number has the format “MAJOR.MINOR.PATCH”.

  • line_length (int) – Max line length of the directive text. If non nul, a long text is wrapped in several lines.

Keyword arguments can be:

  • “action”: A warning filter used to activate or not the deprecation warning. Can be one of “error”, “ignore”, “always”, “default”, “module”, or “once”. If None, empty or missing, the the global filtering mechanism is used.

  • “category”: The warning category to use for the deprecation warning. By default, the category class is DeprecationWarning, you can inherit this class to define your own deprecation warning category.

Returns:

a decorator used to deprecate a function.

Changed in version 1.2.13: Change the signature of the decorator to reflect the valid use cases.

ppb.changelib.renamed(old: str, new: Any, *, version: str, **kwargs)[source]#

Creates a name alias for a function, class, or method.

Parameters:

  • reason (str) – Reason message which documents the rename.

  • version (str) – Version in which this rename occurred.

ppb.changelib.versionadded(reason='', version='', line_length=70)[source]#

This decorator can be used to insert a “versionadded” directive in your function/class docstring in order to documents the version of the project which adds this new functionality in your library.

Parameters:

  • reason (str) – Reason message which documents the addition in your library (can be omitted).

  • version (str) –

    Version of your project which adds this feature. If you follow the Semantic Versioning, the version number has the format “MAJOR.MINOR.PATCH”, and, in the case of a new functionality, the “PATCH” component should be “0”.

  • line_length (int) – Max line length of the directive text. If non nul, a long text is wrapped in several lines.

Returns:

the decorated function.

ppb.changelib.versionchanged(reason='', version='', line_length=70)[source]#

This decorator can be used to insert a “versionchanged” directive in your function/class docstring in order to documents the version of the project which modifies this functionality in your library.

Parameters:

  • reason (str) – Reason message which documents the modification in your library (can be omitted).

  • version (str) –

    Version of your project which modifies this feature. If you follow the Semantic Versioning, the version number has the format “MAJOR.MINOR.PATCH”.

  • line_length (int) – Max line length of the directive text. If non nul, a long text is wrapped in several lines.

Returns:

the decorated function.