nat.utils.decorators#

Deprecation utilities.

This module provides helpers to standardize deprecation signaling across the codebase:

  • issue_deprecation_warning: Builds and emits a single deprecation message per function using the standard logging pipeline.

  • deprecated: A decorator that wraps sync/async functions and generators to log a one-time deprecation message upon first use. It supports optional metadata, a planned removal version, a suggested replacement, and an optional feature name label.

Messages are emitted via logging.getLogger(__name__).warning (not warnings.warn) so they appear in normal application logs and respect global logging configuration. Each unique function logs at most once per process.

Attributes#

logger

_warning_issued

F

Functions#

issue_deprecation_warning(→ None)

Log a deprecation warning message for the function.

deprecated(…)

Decorator that can wrap any type of function (sync, async, generator,

Module Contents#

logger#
_warning_issued#
F#
issue_deprecation_warning(
function_name: str,
removal_version: str | None = None,
replacement: str | None = None,
reason: str | None = None,
feature_name: str | None = None,
metadata: dict[str, Any] | None = None,
) → None#

Log a deprecation warning message for the function.

A warning is emitted only once per function. When a metadata dict is supplied, it is appended to the log entry to provide extra context (e.g., version, author, feature flag).

Args:

function_name: The name of the deprecated function removal_version: The version when the function will be removed replacement: What to use instead of this function reason: Why the function is being deprecated feature_name: Optional name of the feature that is deprecated metadata: Optional dictionary of metadata to log with the warning

deprecated(
func: F,
*,
removal_version: str | None = None,
replacement: str | None = None,
reason: str | None = None,
feature_name: str | None = None,
metadata: dict[str, Any] | None = None,
) → F#
deprecated(
*,
removal_version: str | None = None,
replacement: str | None = None,
reason: str | None = None,
feature_name: str | None = None,
metadata: dict[str, Any] | None = None,
) → collections.abc.Callable[[F], F]

Decorator that can wrap any type of function (sync, async, generator, async generator) and logs a deprecation warning.

Args:

func: The function to be decorated. removal_version: The version when the function will be removed replacement: What to use instead of this function reason: Why the function is being deprecated feature_name: Optional name of the feature that is deprecated. If provided, the warning will be prefixed with “The <feature_name> feature is deprecated”. metadata: Optional dictionary of metadata to log with the warning. This can include information like version, author, etc. If provided, the metadata will be logged alongside the deprecation warning.