djblets.deprecation¶
Support for handling deprecations.
The version-specific objects in this module are not considered stable between releases, and may be removed at any point.
The base objects are considered stable.
BaseRemovedInProductVersionWarning
and the utility functions can
be used by consumers to manage their own deprecations.
- exception BaseRemovedInProductVersionWarning¶
Bases:
DeprecationWarning
Base class for product deprecation warnings.
This can be used by consumers of Djblets to provide similar deprecation functionality, making use of deprecation utility functions.
New in version 3.2.
- classmethod warn(message, stacklevel=2)¶
Emit the deprecation warning.
This is a convenience function that emits a deprecation warning using this class, with a suitable default stack level. Callers can provide a useful message and a custom stack level.
New in version 3.0.
- __annotations__ = {'product': 'str', 'version': 'str'}¶
- exception BaseRemovedInDjbletsVersionWarning¶
Bases:
BaseRemovedInProductVersionWarning
Base class for a Djblets deprecation warning.
All version-specific deprecation warnings inherit from this, allowing callers to check for Djblets deprecations without being tied to a specific version.
- exception RemovedInDjblets40Warning¶
Bases:
BaseRemovedInDjbletsVersionWarning
Deprecations for features scheduled for removal in Djblets 4.0.
Note that this class will itself be removed in Djblets 4.0. If you need to check against Djblets deprecation warnings, please see
BaseRemovedInDjbletsVersionWarning
. Alternatively, you can use the alias for this class,RemovedInNextDjbletsVersionWarning
.
- exception RemovedInDjblets50Warning¶
Bases:
BaseRemovedInDjbletsVersionWarning
Deprecations for features scheduled for removal in Djblets 5.0.
Note that this class will itself be removed in Djblets 5.0. If you need to check against Djblets deprecation warnings, please see
BaseRemovedInDjbletsVersionWarning
. Alternatively, you can use the alias for this class,RemovedInNextDjbletsVersionWarning
.
- RemovedInNextDjbletsVersionWarning¶
An alias for the next release of Djblets where features would be removed.
- deprecated_arg_value(owner_name: str, value: ~typing.Any, old_arg_name: str, new_arg_name: ~typing.Optional[str] = None, warning_cls: ~typing.Type[DeprecationWarning] = <class 'DeprecationWarning'>) SimpleLazyObject ¶
Wrap a value in a lazy object to warn when used.
Changed in version 3.2: Specifying a
BaseRemovedInProductVersionWarning
subclass will now result in product/version information in the warning message.- Parameters:
owner_name (
str
) – The name of the owner of this argument.value (
object
) – The argument value.old_arg_name (
str
) – The name of the argument that was deprecated.new_arg_name (
str
, optional) – The optional name of the argument to use in the deprecated argument’s place, if one is available.warning_cls (
type
, optional) –The class to use for the warning. This should be
DeprecationWarning
,PendingDeprecationWarning
, or a subclass of one.If a
BaseRemovedInProductVersionWarning
subclass is provided, the error message will include warning information. This is recommended and may be required in a future version.
- Returns:
The value wrapped in a lazy object. The first time it is accessed, a warning will be emitted.
- Return type:
django.utils.functional.SimpleLazyObject
- deprecate_non_keyword_only_args(warning_cls: Type[BaseRemovedInProductVersionWarning], message: Optional[str] = None) Callable[[_FuncT], _FuncT] ¶
Deprecate calls passing keyword-only arguments as positional arguments.
This decorator allows code transitioning to keyword-only arguments to continue working when passing values as positional arguments.
Upon the first call, it will record information about the signature of the function and then compare that to any future calls. If any positional argument values are passed to keyword-only arguments, the arguments will be rewritten to work correctly, and a deprecation warning will be emitted.
New in version 3.2.
- Parameters:
warning_cls (
type
) – The specific deprecation warning class to use. This must be a subclass ofDeprecationWarning
.message (
str
, optional) – An optional message to use instead of the default.
- Returns:
The function decorator.
- Return type:
callable
- Raises:
AssertionError – The function being called does not provide keyword-only arguments.