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