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