nvidia-nat 1.3.0.dev2__py3-none-any.whl → 1.3.0rc2__py3-none-any.whl

nat/utils/decorators.py

@@ -0,0 +1,210 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""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.
+"""
+
+import functools
+import inspect
+import logging
+from collections.abc import AsyncGenerator
+from collections.abc import Callable
+from collections.abc import Generator
+from typing import Any
+from typing import TypeVar
+from typing import overload
+
+logger = logging.getLogger(__name__)
+
+_warning_issued = set()
+
+# Type variables for overloads
+F = TypeVar('F', bound=Callable[..., Any])
+
+
+def 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
+    """
+    if function_name not in _warning_issued:
+        # Build the deprecation message
+        if feature_name:
+            warning_message = f"{feature_name} is deprecated"
+        else:
+            warning_message = f"Function {function_name} is deprecated"
+
+        if removal_version:
+            warning_message += f" and will be removed in version {removal_version}"
+        else:
+            warning_message += " and will be removed in a future release"
+
+        warning_message += "."
+
+        if reason:
+            warning_message += f" Reason: {reason}."
+
+        if replacement:
+            warning_message += f" Use '{replacement}' instead."
+
+        if metadata:
+            warning_message += f" | Metadata: {metadata}"
+
+        # Issue warning and save function name to avoid duplicate warnings
+        logger.warning(warning_message)
+        _warning_issued.add(function_name)
+
+
+# Overloads for different function types
+@overload
+def 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:
+    """Overload for direct decorator usage (when called without parentheses)."""
+    ...
+
+
+@overload
+def 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) -> Callable[[F], F]:
+    """Overload for decorator factory usage (when called with parentheses)."""
+    ...
+
+
+def deprecated(func: Any = None,
+               *,
+               removal_version: str | None = None,
+               replacement: str | None = None,
+               reason: str | None = None,
+               feature_name: str | None = None,
+               metadata: dict[str, Any] | None = None) -> Any:
+    """
+    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.
+    """
+    function_name: str = f"{func.__module__}.{func.__qualname__}" if func else "<unknown_function>"
+
+    # If called as @deprecated(...) but not immediately passed a function
+    if func is None:
+
+        def decorator_wrapper(actual_func):
+            return deprecated(actual_func,
+                              removal_version=removal_version,
+                              replacement=replacement,
+                              reason=reason,
+                              feature_name=feature_name,
+                              metadata=metadata)
+
+        return decorator_wrapper
+
+    # --- Validate metadata ---
+    if metadata is not None:
+        if not isinstance(metadata, dict):
+            raise TypeError("metadata must be a dict[str, Any].")
+        if any(not isinstance(k, str) for k in metadata.keys()):
+            raise TypeError("All metadata keys must be strings.")
+
+    # --- Now detect the function type and wrap accordingly ---
+    if inspect.isasyncgenfunction(func):
+        # ---------------------
+        # ASYNC GENERATOR
+        # ---------------------
+
+        @functools.wraps(func)
+        async def async_gen_wrapper(*args, **kwargs) -> AsyncGenerator[Any, Any]:
+            issue_deprecation_warning(function_name, removal_version, replacement, reason, feature_name, metadata)
+            async for item in func(*args, **kwargs):
+                yield item  # yield the original item
+
+        return async_gen_wrapper
+
+    if inspect.iscoroutinefunction(func):
+        # ---------------------
+        # ASYNC FUNCTION
+        # ---------------------
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs) -> Any:
+            issue_deprecation_warning(function_name, removal_version, replacement, reason, feature_name, metadata)
+            result = await func(*args, **kwargs)
+            return result
+
+        return async_wrapper
+
+    if inspect.isgeneratorfunction(func):
+        # ---------------------
+        # SYNC GENERATOR
+        # ---------------------
+        @functools.wraps(func)
+        def sync_gen_wrapper(*args, **kwargs) -> Generator[Any, Any, Any]:
+            issue_deprecation_warning(function_name, removal_version, replacement, reason, feature_name, metadata)
+            yield from func(*args, **kwargs)  # yield the original item
+
+        return sync_gen_wrapper
+
+    @functools.wraps(func)
+    def sync_wrapper(*args, **kwargs) -> Any:
+        issue_deprecation_warning(function_name, removal_version, replacement, reason, feature_name, metadata)
+        result = func(*args, **kwargs)
+        return result
+
+    return sync_wrapper

nat/utils/exception_handlers/automatic_retries.py

@@ -26,8 +26,6 @@ from collections.abc import Sequence
 from typing import Any
 from typing import TypeVar
 
-# pylint: disable=inconsistent-return-statements
-
 T = TypeVar("T")
 Exc = tuple[type[BaseException], ...]  # exception classes
 CodePattern = int | str | range  # for retry_codes argument
@@ -120,6 +118,7 @@ def _retry_decorator(
     retry_codes: Sequence[CodePattern] | None = None,
     retry_on_messages: Sequence[str] | None = None,
     deepcopy: bool = False,
+    instance_context_aware: bool = False,
 ) -> Callable[[Callable[..., T]], Callable[..., T]]:
     """
     Build a decorator that retries with exponential back-off *iff*:
@@ -132,69 +131,122 @@ def _retry_decorator(
     deepcopy:
         If True, each retry receives deep‑copied *args and **kwargs* to avoid
         mutating shared state between attempts.
+
+    instance_context_aware:
+        If True, the decorator will check for a retry context flag on the first
+        argument (assumed to be 'self'). If the flag is set, retries are skipped
+        to prevent retry storms in nested method calls.
     """
 
     def decorate(fn: Callable[..., T]) -> Callable[..., T]:
         use_deepcopy = deepcopy
+        use_context_aware = instance_context_aware
 
-        async def _call_with_retry_async(*args, **kw) -> T:
-            delay = base_delay
-            for attempt in range(retries):
-                call_args = copy.deepcopy(args) if use_deepcopy else args
-                call_kwargs = copy.deepcopy(kw) if use_deepcopy else kw
+        class _RetryContext:
+            """Context manager for instance-level retry gating."""
+
+            __slots__ = ("_obj", "_enabled", "_active")
+
+            def __init__(self, args: tuple[Any, ...]):
+                self._obj = args[0] if (use_context_aware and args) else None
+                self._enabled = bool(self._obj)
+                self._active = False
+
+            def __enter__(self):
+                if not self._enabled:
+                    return False
                 try:
-                    return await fn(*call_args, **call_kwargs)
-                except retry_on as exc:
-                    if (not _want_retry(exc, code_patterns=retry_codes, msg_substrings=retry_on_messages)
-                            or attempt == retries - 1):
-                        raise
-                    await asyncio.sleep(delay)
-                    delay *= backoff
+                    # If already in retry context, signal caller to skip retries
+                    if getattr(self._obj, "_in_retry_context", False):
+                        return True
+                    object.__setattr__(self._obj, "_in_retry_context", True)
+                    self._active = True
+                    return False
+                except Exception:
+                    # If we cannot set the attribute, behave as if context isn't enabled
+                    self._enabled = False
+                    return False
+
+            def __exit__(self, _exc_type, _exc, _tb):
+                if self._enabled and self._active:
+                    try:
+                        object.__setattr__(self._obj, "_in_retry_context", False)
+                    except Exception:
+                        pass
+
+        async def _call_with_retry_async(*args, **kw) -> T:
+            with _RetryContext(args) as already_in_context:
+                if already_in_context:
+                    return await fn(*args, **kw)
+                delay = base_delay
+                for attempt in range(retries):
+                    call_args = copy.deepcopy(args) if use_deepcopy else args
+                    call_kwargs = copy.deepcopy(kw) if use_deepcopy else kw
+                    try:
+                        return await fn(*call_args, **call_kwargs)
+                    except retry_on as exc:
+                        if (not _want_retry(exc, code_patterns=retry_codes, msg_substrings=retry_on_messages)
+                                or attempt == retries - 1):
+                            raise
+                        await asyncio.sleep(delay)
+                        delay *= backoff
 
         async def _agen_with_retry(*args, **kw):
-            delay = base_delay
-            for attempt in range(retries):
-                call_args = copy.deepcopy(args) if use_deepcopy else args
-                call_kwargs = copy.deepcopy(kw) if use_deepcopy else kw
-                try:
-                    async for item in fn(*call_args, **call_kwargs):
+            with _RetryContext(args) as already_in_context:
+                if already_in_context:
+                    async for item in fn(*args, **kw):
                         yield item
                     return
-                except retry_on as exc:
-                    if (not _want_retry(exc, code_patterns=retry_codes, msg_substrings=retry_on_messages)
-                            or attempt == retries - 1):
-                        raise
-                    await asyncio.sleep(delay)
-                    delay *= backoff
+                delay = base_delay
+                for attempt in range(retries):
+                    call_args = copy.deepcopy(args) if use_deepcopy else args
+                    call_kwargs = copy.deepcopy(kw) if use_deepcopy else kw
+                    try:
+                        async for item in fn(*call_args, **call_kwargs):
+                            yield item
+                        return
+                    except retry_on as exc:
+                        if (not _want_retry(exc, code_patterns=retry_codes, msg_substrings=retry_on_messages)
+                                or attempt == retries - 1):
+                            raise
+                        await asyncio.sleep(delay)
+                        delay *= backoff
 
         def _gen_with_retry(*args, **kw) -> Iterable[Any]:
-            delay = base_delay
-            for attempt in range(retries):
-                call_args = copy.deepcopy(args) if use_deepcopy else args
-                call_kwargs = copy.deepcopy(kw) if use_deepcopy else kw
-                try:
-                    yield from fn(*call_args, **call_kwargs)
+            with _RetryContext(args) as already_in_context:
+                if already_in_context:
+                    yield from fn(*args, **kw)
                     return
-                except retry_on as exc:
-                    if (not _want_retry(exc, code_patterns=retry_codes, msg_substrings=retry_on_messages)
-                            or attempt == retries - 1):
-                        raise
-                    time.sleep(delay)
-                    delay *= backoff
+                delay = base_delay
+                for attempt in range(retries):
+                    call_args = copy.deepcopy(args) if use_deepcopy else args
+                    call_kwargs = copy.deepcopy(kw) if use_deepcopy else kw
+                    try:
+                        yield from fn(*call_args, **call_kwargs)
+                        return
+                    except retry_on as exc:
+                        if (not _want_retry(exc, code_patterns=retry_codes, msg_substrings=retry_on_messages)
+                                or attempt == retries - 1):
+                            raise
+                        time.sleep(delay)
+                        delay *= backoff
 
         def _sync_with_retry(*args, **kw) -> T:
-            delay = base_delay
-            for attempt in range(retries):
-                call_args = copy.deepcopy(args) if use_deepcopy else args
-                call_kwargs = copy.deepcopy(kw) if use_deepcopy else kw
-                try:
-                    return fn(*call_args, **call_kwargs)
-                except retry_on as exc:
-                    if (not _want_retry(exc, code_patterns=retry_codes, msg_substrings=retry_on_messages)
-                            or attempt == retries - 1):
-                        raise
-                    time.sleep(delay)
-                    delay *= backoff
+            with _RetryContext(args) as already_in_context:
+                if already_in_context:
+                    return fn(*args, **kw)
+                delay = base_delay
+                for attempt in range(retries):
+                    call_args = copy.deepcopy(args) if use_deepcopy else args
+                    call_kwargs = copy.deepcopy(kw) if use_deepcopy else kw
+                    try:
+                        return fn(*call_args, **call_kwargs)
+                    except retry_on as exc:
+                        if (not _want_retry(exc, code_patterns=retry_codes, msg_substrings=retry_on_messages)
+                                or attempt == retries - 1):
+                            raise
+                        time.sleep(delay)
+                        delay *= backoff
 
         # Decide which wrapper to return
         if inspect.iscoroutinefunction(fn):
@@ -247,6 +299,7 @@ def patch_with_retry(
         retry_codes=retry_codes,
         retry_on_messages=retry_on_messages,
         deepcopy=deepcopy,
+        instance_context_aware=True,  # Prevent retry storms
     )
 
     # Choose attribute source: the *class* to avoid triggering __getattr__
@@ -257,7 +310,7 @@ def patch_with_retry(
         descriptor = inspect.getattr_static(cls, name)
 
         # Skip dunders, privates and all descriptors we must not wrap
-        if (name.startswith("_") or isinstance(descriptor, (property, staticmethod, classmethod))):
+        if (name.startswith("_") or isinstance(descriptor, property | staticmethod | classmethod)):
             continue
 
         original = descriptor.__func__ if isinstance(descriptor, types.MethodType) else descriptor

nat/utils/exception_handlers/schemas.py

@@ -21,7 +21,7 @@ from pydantic import ValidationError
 logger = logging.getLogger(__name__)
 
 
-def schema_exception_handler(func, **kwargs):  # pylint: disable=unused-argument
+def schema_exception_handler(func, **kwargs):
     """
     A decorator that handles `ValidationError` exceptions for schema validation functions.
 

nat/utils/io/yaml_tools.py

@@ -57,7 +57,7 @@ def yaml_load(config_path: StrPath) -> dict:
     """
 
     # Read YAML file
-    with open(config_path, "r", encoding="utf-8") as stream:
+    with open(config_path, encoding="utf-8") as stream:
         config_str = stream.read()
 
     return yaml_loads(config_str)
@@ -85,7 +85,7 @@ def yaml_loads(config: str) -> dict:
     try:
         config_data = yaml.safe_load(stream)
     except yaml.YAMLError as e:
-        logger.error("Error loading YAML: %s", interpolated_config_str, exc_info=True)
+        logger.error("Error loading YAML: %s", interpolated_config_str)
         raise ValueError(f"Error loading YAML: {e}") from e
 
     assert isinstance(config_data, dict)

nat/utils/log_levels.py

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+
+# Define log level choices
+LOG_LEVELS = {
+    'DEBUG': logging.DEBUG,
+    'INFO': logging.INFO,
+    'WARNING': logging.WARNING,
+    'ERROR': logging.ERROR,
+    'CRITICAL': logging.CRITICAL
+}

nat/utils/reactive/base/observable_base.py

@@ -25,8 +25,8 @@ from nat.utils.reactive.subscription import Subscription
 
 # Covariant type param: An Observable producing type X can also produce
 # a subtype of X.
-_T_out_co = TypeVar("_T_out_co", covariant=True)  # pylint: disable=invalid-name
-_T = TypeVar("_T")  # pylint: disable=invalid-name
+_T_out_co = TypeVar("_T_out_co", covariant=True)
+_T = TypeVar("_T")
 
 OnNext = Callable[[_T], None]
 OnError = Callable[[Exception], None]

nat/utils/reactive/base/observer_base.py

@@ -20,7 +20,7 @@ from typing import TypeVar
 
 # Contravariant type param: An Observer that can accept type X can also
 # accept any supertype of X.
-_T_in_contra = TypeVar("_T_in_contra", contravariant=True)  # pylint: disable=invalid-name
+_T_in_contra = TypeVar("_T_in_contra", contravariant=True)
 
 
 class ObserverBase(Generic[_T_in_contra], ABC):

nat/utils/reactive/observable.py

@@ -24,8 +24,8 @@ from nat.utils.type_utils import override
 
 # Covariant type param: An Observable producing type X can also produce
 # a subtype of X.
-_T_out_co = TypeVar("_T_out_co", covariant=True)  # pylint: disable=invalid-name
-_T = TypeVar("_T")  # pylint: disable=invalid-name
+_T_out_co = TypeVar("_T_out_co", covariant=True)
+_T = TypeVar("_T")
 
 OnNext = Callable[[_T], None]
 OnError = Callable[[Exception], None]

nat/utils/reactive/observer.py

@@ -23,8 +23,8 @@ logger = logging.getLogger(__name__)
 
 # Contravariant type param: An Observer that can accept type X can also
 # accept any supertype of X.
-_T_in_contra = TypeVar("_T_in_contra", contravariant=True)  # pylint: disable=invalid-name
-_T = TypeVar("_T")  # pylint: disable=invalid-name
+_T_in_contra = TypeVar("_T_in_contra", contravariant=True)
+_T = TypeVar("_T")
 
 OnNext = Callable[[_T], None]
 OnError = Callable[[Exception], None]
@@ -64,7 +64,7 @@ class Observer(ObserverBase[_T_in_contra]):
                 try:
                     self._on_error(exc)
                 except Exception as e:
-                    logger.exception("Error in on_error callback: %s", e, exc_info=True)
+                    logger.exception("Error in on_error callback: %s", e)
 
     def on_complete(self) -> None:
         if not self._stopped:
@@ -73,4 +73,4 @@ class Observer(ObserverBase[_T_in_contra]):
                 try:
                     self._on_complete()
                 except Exception as e:
-                    logger.exception("Error in on_complete callback: %s", e, exc_info=True)
+                    logger.exception("Error in on_complete callback: %s", e)

nat/utils/reactive/subscription.py

@@ -21,7 +21,7 @@ from typing import TypeVar
 if typing.TYPE_CHECKING:
     from nat.utils.reactive.base.subject_base import SubjectBase
 
-_T = TypeVar("_T")  # pylint: disable=invalid-name
+_T = TypeVar("_T")
 
 OnNext = Callable[[_T], None]
 OnError = Callable[[Exception], None]

nat/utils/settings/global_settings.py

@@ -47,7 +47,7 @@ def configure_registry_channel(config_type: RegistryHandlerBaseConfig, channel_n
             user_input = input(f"{human_prompt}: ")
             model_fields = {}
             model_fields[field] = (info.annotation, ...)
-            DynamicFieldModel = create_model("DynamicFieldModel", **model_fields)  # pylint: disable=C0103
+            DynamicFieldModel = create_model("DynamicFieldModel", **model_fields)
             dynamic_inputs = {field: user_input}
 
             try:
@@ -55,7 +55,7 @@ def configure_registry_channel(config_type: RegistryHandlerBaseConfig, channel_n
                 channel_registry_pre[field] = getattr(validated_field_model, field)
                 break
             except Exception as e:
-                logger.exception(e, exc_info=True)
+                logger.exception(e)
                 logger.warning("Invalid '%s' input, input must be of type %s.", field, info.annotation)
 
     validated_model = config_type(**channel_registry_pre)
@@ -76,10 +76,9 @@ def add_channel_interative(channel_type: str) -> None:
     registry = GlobalTypeRegistry.get()
 
     try:
-        ChannelConfigType = registry.get_registered_channel_info_by_channel_type(  # pylint: disable=C0103
-            channel_type=channel_type).config_type
+        ChannelConfigType = registry.get_registered_channel_info_by_channel_type(channel_type=channel_type).config_type
     except Exception as e:
-        logger.exception("Invalid channel type: %s", e, exc_info=True)
+        logger.exception("Invalid channel type: %s", e)
         return
 
     while (True):
@@ -92,8 +91,7 @@ def add_channel_interative(channel_type: str) -> None:
             settings.channels[channel_name] = {}
             break
 
-    ChannelConfigType = registry.get_registered_channel_info_by_channel_type(  # pylint: disable=C0103
-        channel_type=channel_type).config_type
+    ChannelConfigType = registry.get_registered_channel_info_by_channel_type(channel_type=channel_type).config_type
 
     configure_registry_channel(config_type=ChannelConfigType, channel_name=channel_name)
 
@@ -181,7 +179,7 @@ def match_valid_channel(channel_name: str) -> None:
 
     channals_settings = settings.channels
     channel_settings = channals_settings.get(channel_name)
-    ChannelConfigType = registry.get_registered_channel_info_by_channel_type(  # pylint: disable=C0103
+    ChannelConfigType = registry.get_registered_channel_info_by_channel_type(
         channel_type=channel_settings.static_type()).config_type
 
     configure_registry_channel(config_type=ChannelConfigType, channel_name=channel_name)

nat/utils/type_converter.py

@@ -90,7 +90,7 @@ class TypeConverter:
         decomposed = DecomposedType(to_type)
 
         # 1) If data is already correct type, return it
-        if to_type is None or decomposed.is_instance((data, to_type)):
+        if to_type is None or decomposed.is_instance(data):
             return data
 
         root = decomposed.root
@@ -198,16 +198,17 @@ class TypeConverter:
         """
         visited = set()
         final = self._try_indirect_conversion(data, to_type, visited)
+        src_type = type(data)
         if final is not None:
             # Warn once if found a chain
-            self._maybe_warn_indirect(type(data), to_type)
+            self._maybe_warn_indirect(src_type, to_type)
             return final
 
         # If no success, try parent's indirect
         if self._parent is not None:
             parent_final = self._parent._try_indirect_convert(data, to_type)
             if parent_final is not None:
-                self._maybe_warn_indirect(type(data), to_type)
+                self._maybe_warn_indirect(src_type, to_type)
                 return parent_final
 
         return None