nv-ingest-api 2025.8.14.dev20250814__py3-none-any.whl → 2025.8.16.dev20250816__py3-none-any.whl

nv_ingest_api/util/introspection/class_inspect.py

@@ -0,0 +1,145 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-25, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import inspect
+from typing import Optional, Type, Union, Callable
+
+from pydantic import BaseModel
+
+
+def find_pydantic_config_schema(
+    actor_class: Type,
+    base_class_to_find: Type,
+    param_name: str = "config",
+) -> Optional[Type[BaseModel]]:
+    """
+    Introspects a class's MRO to find a Pydantic model in its __init__ signature.
+
+    This function is designed to find the specific Pydantic configuration model
+    for a pipeline actor, which might be a direct class or a proxy object.
+
+    Parameters
+    ----------
+    actor_class : Type
+        The actor class or proxy object to inspect.
+    base_class_to_find : Type
+        The specific base class (e.g., RaySource, RayStage) to look for when
+        resolving the true actor class from a proxy.
+    param_name : str, optional
+        The name of the __init__ parameter to inspect for the Pydantic schema,
+        by default "config".
+
+    Returns
+    -------
+    Optional[Type[BaseModel]]
+        The Pydantic BaseModel class if found, otherwise None.
+    """
+    # 1. Find the actual class to inspect, handling proxy objects.
+    cls_to_inspect = None
+    if inspect.isclass(actor_class):
+        cls_to_inspect = actor_class
+    else:
+        for base in actor_class.__class__.__mro__:
+            if inspect.isclass(base) and issubclass(base, base_class_to_find) and base is not base_class_to_find:
+                cls_to_inspect = base
+                break
+
+    if not cls_to_inspect:
+        return None
+
+    # 2. Walk the MRO of the real class to find the __init__ with the typed parameter.
+    for cls in cls_to_inspect.__mro__:
+        if param_name in getattr(cls.__init__, "__annotations__", {}):
+            try:
+                init_sig = inspect.signature(cls.__init__)
+                config_param = init_sig.parameters.get(param_name)
+                if (
+                    config_param
+                    and config_param.annotation is not BaseModel
+                    and issubclass(config_param.annotation, BaseModel)
+                ):
+                    return config_param.annotation  # Found the schema
+            except (ValueError, TypeError):
+                # This class's __init__ is not inspectable (e.g., a C-extension), continue up the MRO.
+                continue
+
+    return None
+
+
+def find_pydantic_config_schema_for_callable(
+    callable_fn: Callable,
+    param_name: str = "stage_config",
+) -> Optional[Type[BaseModel]]:
+    """
+    Introspects a callable's signature to find a Pydantic model parameter.
+
+    This function is designed to find the specific Pydantic configuration model
+    for a pipeline callable function.
+
+    Parameters
+    ----------
+    callable_fn : Callable
+        The callable function to inspect.
+    param_name : str, optional
+        The name of the parameter to inspect for the Pydantic schema,
+        by default "stage_config".
+
+    Returns
+    -------
+    Optional[Type[BaseModel]]
+        The Pydantic BaseModel class if found, otherwise None.
+    """
+    try:
+        sig = inspect.signature(callable_fn)
+        config_param = sig.parameters.get(param_name)
+        if (
+            config_param
+            and config_param.annotation is not BaseModel
+            and hasattr(config_param.annotation, "__mro__")
+            and issubclass(config_param.annotation, BaseModel)
+        ):
+            return config_param.annotation
+    except (ValueError, TypeError):
+        # Function signature is not inspectable
+        pass
+
+    return None
+
+
+def find_pydantic_config_schema_unified(
+    target: Union[Type, Callable],
+    base_class_to_find: Optional[Type] = None,
+    param_name: str = "config",
+) -> Optional[Type[BaseModel]]:
+    """
+    Unified function to find Pydantic schema for either classes or callables.
+
+    Parameters
+    ----------
+    target : Union[Type, Callable]
+        The class or callable to inspect.
+    base_class_to_find : Optional[Type], optional
+        The specific base class to look for when resolving actor classes from proxies.
+        Only used for class inspection.
+    param_name : str, optional
+        The name of the parameter to inspect for the Pydantic schema.
+        For classes: defaults to "config"
+        For callables: should be "stage_config"
+
+    Returns
+    -------
+    Optional[Type[BaseModel]]
+        The Pydantic BaseModel class if found, otherwise None.
+    """
+    if callable(target) and not inspect.isclass(target):
+        # Handle callable function
+        return find_pydantic_config_schema_for_callable(target, param_name)
+    elif inspect.isclass(target) or hasattr(target, "__class__"):
+        # Handle class or proxy object
+        if base_class_to_find is None:
+            # If no base class specified, we can't use the original function
+            return None
+        return find_pydantic_config_schema(target, base_class_to_find, param_name)
+    else:
+        return None

nv_ingest_api/util/introspection/function_inspect.py

@@ -0,0 +1,65 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Utilities for introspecting and analyzing UDF function specifications.
+"""
+
+import re
+from typing import Optional
+
+
+def infer_udf_function_name(udf_function: str) -> Optional[str]:
+    """
+    Attempts to infer the UDF function name from the provided function string.
+
+    Supports three formats:
+    1. Inline function: 'def my_func(control_message): ...' -> 'my_func'
+    2. Import path: 'my_module.my_function' -> 'my_function'
+    3. File path: '/path/to/file.py:function_name' -> 'function_name'
+
+    Parameters
+    ----------
+    udf_function : str
+        The UDF function string.
+
+    Returns
+    -------
+    Optional[str]
+        The inferred UDF function name, or None if inference is not possible.
+
+    Examples
+    --------
+    >>> infer_udf_function_name("def my_custom_func(control_message): pass")
+    'my_custom_func'
+
+    >>> infer_udf_function_name("my_module.submodule.process_data")
+    'process_data'
+
+    >>> infer_udf_function_name("/path/to/script.py:custom_function")
+    'custom_function'
+
+    >>> infer_udf_function_name("/path/to/script.py")
+    None
+    """
+    udf_function = udf_function.strip()
+
+    # Format 3: File path with explicit function name
+    if ":" in udf_function and ("/" in udf_function or "\\" in udf_function):
+        # File path with explicit function name: '/path/to/file.py:function_name'
+        return udf_function.split(":")[-1].strip()
+
+    # Format 2: Import path like 'module.submodule.function'
+    elif "." in udf_function and not udf_function.startswith("def "):
+        # Import path: extract the last part as function name
+        return udf_function.split(".")[-1].strip()
+
+    # Format 1: Inline function definition
+    elif udf_function.startswith("def "):
+        # Parse inline function definition to extract function name
+        match = re.match(r"def\s+(\w+)\s*\(", udf_function)
+        if match:
+            return match.group(1)
+
+    return None

nv_ingest_api/util/logging/configuration.py

@@ -4,7 +4,7 @@
 
 
 import logging
-import sys
+import logging.config
 from enum import Enum
 
 
@@ -30,9 +30,73 @@ def configure_logging(level_name: str) -> None:
     if not isinstance(numeric_level, int):
         raise ValueError(f"Invalid log level: {level_name}")
 
-    logging.basicConfig(
-        level=numeric_level,
-        format="%(asctime)s - %(levelname)s - %(name)s - %(message)s",
-        stream=sys.stdout,
-        force=True,  # <- reconfigures even if basicConfig was called earlier (Python 3.8+)
-    )
+    # Scorched-earth reset: remove ALL existing handlers from root and named loggers
+    # to ensure there is exactly one handler after configuration.
+    root_logger = logging.getLogger()
+    for h in list(root_logger.handlers):
+        root_logger.removeHandler(h)
+        try:
+            h.close()
+        except Exception:
+            pass
+
+    # Clear handlers from all known loggers and make them propagate to root
+    for name, logger_obj in list(logging.Logger.manager.loggerDict.items()):
+        if isinstance(logger_obj, logging.Logger):
+            for h in list(logger_obj.handlers):
+                logger_obj.removeHandler(h)
+                try:
+                    h.close()
+                except Exception:
+                    pass
+            # Ensure messages bubble to root; levels will be controlled centrally
+            logger_obj.propagate = True
+            logger_obj.setLevel(logging.NOTSET)
+
+    # Use dictConfig to establish a single console handler on the root logger.
+    config_dict = {
+        "version": 1,
+        # We already cleared handlers above; keep loggers enabled so they propagate to root
+        "disable_existing_loggers": False,
+        "formatters": {
+            "standard": {
+                "format": "%(asctime)s - %(levelname)s - %(name)s - %(message)s",
+            }
+        },
+        "handlers": {
+            "console": {
+                "class": "logging.StreamHandler",
+                "level": numeric_level,
+                "formatter": "standard",
+                "stream": "ext://sys.stdout",
+            }
+        },
+        "root": {
+            "level": numeric_level,
+            "handlers": ["console"],
+        },
+    }
+
+    logging.config.dictConfig(config_dict)
+
+    # Enforce exactly one handler remains attached to root (keep first StreamHandler)
+    root_logger = logging.getLogger()
+    if len(root_logger.handlers) > 1:
+        keep = None
+        for h in list(root_logger.handlers):
+            if keep is None and isinstance(h, logging.StreamHandler):
+                keep = h
+                continue
+            root_logger.removeHandler(h)
+            try:
+                h.close()
+            except Exception:
+                pass
+
+    # Route warnings module through logging
+    try:
+        import logging as _logging
+
+        _logging.captureWarnings(True)
+    except Exception:
+        pass