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.

Changed in version 4.0: Projects should now use housekeeping to manage their own deprecations, instead of using this module.

exception BaseRemovedInProductVersionWarning[source]¶

Bases: BaseRemovedInWarning

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.

Deprecated since version 4.0: Consumers should subclass housekeeping.BaseRemovedInWarning instead. This class will be removed in Djblets 6.

New in version 3.2.

__annotations__ = {}¶

exception PendingRemovalInDjbletsWarning[source]¶

Bases: BasePendingRemovalWarning

Pending deprecation for code in Djblets.

New in version 4.0.

housekeeping_skip_warning = True[source]¶

product: str = 'Djblets'[source]¶: The name of the product with the deprecated functionality.

__annotations__ = {'product': 'str', 'version': 'str', 'version_required': 'bool'}¶

exception BaseRemovedInDjbletsVersionWarning[source]¶

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.

product: str = 'Djblets'[source]¶: The name of the product with the deprecated functionality.

__annotations__ = {'product': 'str', 'version': 'str', 'version_required': 'bool'}¶

exception RemovedInDjblets50Warning[source]¶

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.

version: str = '5.0'[source]¶: The version in which the functionality is expected to be removed.

__annotations__ = {'product': 'str', 'version': 'str', 'version_required': 'bool'}¶

exception RemovedInDjblets60Warning[source]¶

Bases: BaseRemovedInDjbletsVersionWarning

Deprecations for features scheduled for removal in Djblets 6.0.

Note that this class will itself be removed in Djblets 6.0. If you need to check against Djblets deprecation warnings, please see BaseRemovedInDjbletsVersionWarning.

version: str = '6.0'[source]¶: The version in which the functionality is expected to be removed.

__annotations__ = {'product': 'str', 'version': 'str', 'version_required': 'bool'}¶

exception RemovedInDjblets70Warning[source]¶

Bases: BaseRemovedInDjbletsVersionWarning

Deprecations for features scheduled for removal in Djblets 7.0.

Note that this class will itself be removed in Djblets 7.0. If you need to check against Djblets deprecation warnings, please see BaseRemovedInDjbletsVersionWarning.

version: str = '7.0'[source]¶: The version in which the functionality is expected to be removed.

__annotations__ = {'product': 'str', 'version': 'str', 'version_required': 'bool'}¶

RemovedInNextDjbletsVersionWarning[source]¶: 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[~housekeeping.base.BaseRemovedInWarning] = <class 'housekeeping.base.BaseRemovedInWarning'>) → LazyObject[source]¶

Wrap a value in a lazy object to warn when used.

Deprecated since version 4.0: Consumers should use housekeeping.deprecated_arg_value() instead.

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][source]¶

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.

Deprecated since version 4.0: Consumers should use housekeeping.deprecate_non_keyword_only_args() instead.

New in version 3.2.

Parameters:

warning_cls (type) – The specific deprecation warning class to use. This must be a subclass of DeprecationWarning.
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.