def deprecated(*args, **kwargs):
"""
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.
Keyword arguments can be:
- "reason":
Reason message which documents the deprecation in your library (can be omitted).
- "version":
Version of your project which deprecates this feature.
If you follow the `Semantic Versioning <https://semver.org/>`_,
the version number has the format "MAJOR.MINOR.PATCH".
- "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 :class:`~DeprecationWarning`,
you can inherit this class to define your own deprecation warning category.
- "line_length":
Max line length of the directive text. If non nul, a long text is wrapped in several lines.
:return: the decorated function.
"""
directive = kwargs.pop('directive', 'deprecated')
adapter_cls = kwargs.pop('adapter_cls', SphinxAdapter)
return _classic_deprecated(*args, directive=directive, adapter_cls=adapter_cls, **kwargs)
def deprecated(*args, **kwargs):
"""
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.
Keyword arguments can be:
- "reason":
Reason message which documents the deprecation in your library (can be omitted).
- "version":
Version of your project which deprecates this feature.
If you follow the `Semantic Versioning <https://semver.org/>`_,
the version number has the format "MAJOR.MINOR.PATCH".
- "action":
A warning filter used to activate or not the deprecation warning.
Can be one of "error", "ignore", "always", "default", "module", or "once".
By default the deprecation warning is always emitted (the value is "always").
- "category":
The warning category to use for the deprecation warning.
By default, the category class is :class:`~DeprecationWarning`,
you can inherit this class to define your own deprecation warning category.
:return: the decorated function.
"""
directive = kwargs.pop('directive', 'deprecated')
adapter_cls = kwargs.pop('adapter_cls', SphinxAdapter)
return _classic_deprecated(*args,
directive=directive,
adapter_cls=adapter_cls,
**kwargs)
def deprecated(*args, **kwargs):
# todo: add docstring with examples
directive = kwargs.pop('directive', 'deprecated')
adapter_cls = kwargs.pop('adapter_cls', SphinxAdapter)
return _classic_deprecated(*args,
directive=directive,
adapter_cls=adapter_cls,
**kwargs)