openai-sdk-helpers 0.0.9__py3-none-any.whl → 0.1.1__py3-none-any.whl

openai_sdk_helpers/utils/__init__.py

@@ -1,51 +1,79 @@
 """Utility helpers for openai-sdk-helpers.
 
-This package provides common utility functions for type coercion, file
-handling, JSON serialization, and logging. These utilities are used
-throughout the openai_sdk_helpers package.
+The utils package collects cross-cutting helpers used across the project:
 
-Functions
----------
-ensure_list(value)
-    Normalize a single item or iterable into a list.
-check_filepath(filepath, fullfilepath)
-    Ensure the parent directory for a file path exists.
-coerce_optional_float(value)
-    Convert a value to float or None.
-coerce_optional_int(value)
-    Convert a value to int or None.
-coerce_dict(value)
-    Convert a value to a string-keyed dictionary.
-coerce_jsonable(value)
-    Convert a value into a JSON-serializable representation.
-log(message, level)
-    Log a message with basic configuration.
+* Core helpers: coercion, path handling, JSON encoding, and logging basics.
+* Validation: input validation helpers for strings, choices, URLs, etc.
+* Concurrency: async bridging helpers.
+* Output validation: JSON Schema and semantic validators.
+* Instrumentation helpers: deprecation utilities.
 
-Classes
--------
-JSONSerializable
-    Mixin for classes that can be serialized to JSON.
-customJSONEncoder
-    JSON encoder for common helper types like enums and paths.
+Import style
+------------
+Public helpers are re-exported from ``openai_sdk_helpers.utils`` for a
+consistent import surface. You can import from submodules when you need a
+smaller surface area, but top-level imports remain stable.
+
+Submodules
+----------
+coercion
+    Numeric coercion helpers and list normalization.
+path_utils
+    File and path helpers.
+json_utils
+    JSON encoding helpers and mixins.
+logging_config
+    Centralized logger factory and convenience log helper.
+validation
+    Input validation helpers for strings, URLs, collections, and paths.
+async_utils
+    Async-to-sync bridging helpers.
+output_validation
+    JSON Schema and semantic output validation utilities.
+deprecation
+    Deprecation helpers and warning utilities.
 """
 
 from __future__ import annotations
 
-from .core import (
-    JSONSerializable,
-    check_filepath,
-    coerce_jsonable,
+from .coercion import (
     coerce_dict,
     coerce_optional_float,
     coerce_optional_int,
-    customJSONEncoder,
     ensure_list,
-    log,
 )
+from .json_utils import (
+    JSONSerializable,
+    coerce_jsonable,
+    customJSONEncoder,
+)
+from .path_utils import check_filepath, ensure_directory
+from openai_sdk_helpers.logging_config import log
+from .validation import (
+    validate_choice,
+    validate_dict_mapping,
+    validate_list_items,
+    validate_max_length,
+    validate_non_empty_string,
+    validate_safe_path,
+    validate_url_format,
+)
+from .async_utils import run_coroutine_thread_safe, run_coroutine_with_fallback
+from .output_validation import (
+    JSONSchemaValidator,
+    LengthValidator,
+    OutputValidator,
+    SemanticValidator,
+    ValidationResult,
+    ValidationRule,
+    validate_output,
+)
+from .deprecation import DeprecationHelper, deprecated, warn_deprecated
 
 __all__ = [
     "ensure_list",
     "check_filepath",
+    "ensure_directory",
     "coerce_optional_float",
     "coerce_optional_int",
     "coerce_dict",
@@ -53,4 +81,27 @@ __all__ = [
     "JSONSerializable",
     "customJSONEncoder",
     "log",
+    # Validation helpers
+    "validate_non_empty_string",
+    "validate_max_length",
+    "validate_url_format",
+    "validate_dict_mapping",
+    "validate_list_items",
+    "validate_choice",
+    "validate_safe_path",
+    # Async helpers
+    "run_coroutine_thread_safe",
+    "run_coroutine_with_fallback",
+    # Output validation
+    "ValidationResult",
+    "ValidationRule",
+    "JSONSchemaValidator",
+    "SemanticValidator",
+    "LengthValidator",
+    "OutputValidator",
+    "validate_output",
+    # Deprecation
+    "deprecated",
+    "warn_deprecated",
+    "DeprecationHelper",
 ]

openai_sdk_helpers/{async_utils.py → utils/async_utils.py}

@@ -10,17 +10,17 @@ import threading
 from typing import Any, Coroutine, Generic, TypeVar
 
 from openai_sdk_helpers.errors import AsyncExecutionError
-from openai_sdk_helpers.utils.core import log
 
 T = TypeVar("T")
 
 # Default timeout constants
 DEFAULT_COROUTINE_TIMEOUT = 300.0  # 5 minutes
-THREAD_JOIN_TIMEOUT = 5.0  # 5 seconds
+THREAD_JOIN_TIMEOUT = 0.5  # 0.5 seconds
 
 
 def run_coroutine_thread_safe(
     coro: Coroutine[Any, Any, T],
+    *,
     timeout: float = DEFAULT_COROUTINE_TIMEOUT,
 ) -> T:
     """Run a coroutine in a thread-safe manner from a sync context.
@@ -80,10 +80,9 @@ def run_coroutine_thread_safe(
         # Ensure thread is cleaned up
         thread.join(timeout=THREAD_JOIN_TIMEOUT)
         if thread.is_alive():
-            log(
-                f"Thread {thread.name} did not terminate within {THREAD_JOIN_TIMEOUT} seconds",
-                level=20,  # logging.INFO
-            )
+            # Thread did not terminate, likely still running async operation
+            # This is expected for timeout scenarios, so we don't log here
+            pass
 
 
 def run_coroutine_with_fallback(

openai_sdk_helpers/utils/coercion.py

@@ -0,0 +1,138 @@
+"""Type coercion and collection normalization helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def coerce_optional_float(value: object) -> float | None:
+    """Return a float when the provided value can be coerced, otherwise None.
+
+    Handles float, int, and string inputs. Empty strings or None return None.
+
+    Parameters
+    ----------
+    value : object
+        Value to convert into a float. Strings must be parseable as floats.
+
+    Returns
+    -------
+    float or None
+        Converted float value or None if the input is None.
+
+    Raises
+    ------
+    ValueError
+        If a non-empty string cannot be converted to a float.
+    TypeError
+        If the value is not a float-compatible type.
+    """
+    if value is None:
+        return None
+    if isinstance(value, (float, int)):
+        return float(value)
+    if isinstance(value, str) and value.strip():
+        try:
+            return float(value)
+        except ValueError as exc:
+            raise ValueError("timeout must be a float-compatible value") from exc
+    raise TypeError("timeout must be a float, int, str, or None")
+
+
+def coerce_optional_int(value: object) -> int | None:
+    """Return an int when the provided value can be coerced, otherwise None.
+
+    Handles int, float (if whole number), and string inputs. Empty strings
+    or None return None. Booleans are not considered valid integers.
+
+    Parameters
+    ----------
+    value : object
+        Value to convert into an int. Strings must be parseable as integers.
+
+    Returns
+    -------
+    int or None
+        Converted integer value or None if the input is None.
+
+    Raises
+    ------
+    ValueError
+        If a non-empty string cannot be converted to an integer.
+    TypeError
+        If the value is not an int-compatible type.
+    """
+    if value is None:
+        return None
+    if isinstance(value, int) and not isinstance(value, bool):
+        return value
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    if isinstance(value, str) and value.strip():
+        try:
+            return int(value)
+        except ValueError as exc:
+            raise ValueError("max_retries must be an int-compatible value") from exc
+    raise TypeError("max_retries must be an int, str, or None")
+
+
+def coerce_dict(value: object) -> dict[str, Any]:
+    """Return a string-keyed dictionary built from value if possible.
+
+    Converts Mapping objects to dictionaries. None returns an empty dict.
+
+    Parameters
+    ----------
+    value : object
+        Mapping-like value to convert. None yields an empty dictionary.
+
+    Returns
+    -------
+    dict[str, Any]
+        Dictionary representation of value.
+
+    Raises
+    ------
+    TypeError
+        If the value cannot be treated as a mapping.
+    """
+    if value is None:
+        return {}
+    if isinstance(value, Mapping):
+        return dict(value)
+    raise TypeError("extra_client_kwargs must be a mapping or None")
+
+
+def ensure_list(value: Iterable[T] | T | None) -> list[T]:
+    """Normalize a single item or iterable into a list.
+
+    Converts None to empty list, tuples to lists, and wraps single items in a list.
+
+    Parameters
+    ----------
+    value : Iterable[T] | T | None
+        Item or iterable to wrap. None yields an empty list.
+
+    Returns
+    -------
+    list[T]
+        Normalized list representation of value.
+    """
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    if isinstance(value, tuple):
+        return list(value)
+    return [value]  # type: ignore[list-item]
+
+
+__all__ = [
+    "coerce_optional_float",
+    "coerce_optional_int",
+    "coerce_dict",
+    "ensure_list",
+]

openai_sdk_helpers/utils/deprecation.py

@@ -0,0 +1,167 @@
+"""Deprecation utilities for managing deprecated features.
+
+This module provides infrastructure for marking and managing deprecated
+functions, classes, and features with consistent warning messages.
+
+Functions
+---------
+deprecated
+    Decorator to mark functions or classes as deprecated.
+warn_deprecated
+    Emit a deprecation warning with optional custom message.
+
+Classes
+-------
+DeprecationHelper
+    Utility class for managing deprecation warnings and versions.
+"""
+
+from __future__ import annotations
+
+import functools
+import warnings
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class DeprecationHelper:
+    """Utility class for managing deprecation warnings.
+
+    Provides consistent formatting and control of deprecation warnings
+    across the package.
+
+    Methods
+    -------
+    warn
+        Emit a deprecation warning with standard formatting.
+    """
+
+    @staticmethod
+    def warn(
+        feature_name: str,
+        removal_version: str,
+        alternative: str | None = None,
+        extra_message: str | None = None,
+    ) -> None:
+        """Emit a deprecation warning for a feature.
+
+        Parameters
+        ----------
+        feature_name : str
+            Name of the deprecated feature (e.g., "MyClass.old_method").
+        removal_version : str
+            Version in which the feature will be removed.
+        alternative : str, optional
+            Recommended alternative to use instead.
+        extra_message : str, optional
+            Additional context or migration instructions.
+
+        Raises
+        ------
+        DeprecationWarning
+            Always issues a DeprecationWarning to stderr.
+        """
+        msg = f"{feature_name} is deprecated and will be removed in version {removal_version}."
+        if alternative:
+            msg += f" Use {alternative} instead."
+        if extra_message:
+            msg += f" {extra_message}"
+
+        warnings.warn(msg, DeprecationWarning, stacklevel=3)
+
+
+def deprecated(
+    removal_version: str,
+    alternative: str | None = None,
+    extra_message: str | None = None,
+) -> Callable[[F], F]:
+    """Mark a function or class as deprecated.
+
+    Parameters
+    ----------
+    removal_version : str
+        Version in which the decorated feature will be removed.
+    alternative : str, optional
+        Recommended alternative to use instead.
+    extra_message : str, optional
+        Additional context or migration instructions.
+
+    Returns
+    -------
+    Callable
+        Decorator function that wraps the target function or class.
+
+    Examples
+    --------
+    >>> @deprecated("1.0.0", "new_function")
+    ... def old_function():
+    ...     pass
+
+    >>> class OldClass:
+    ...     @deprecated("1.0.0", "NewClass")
+    ...     def old_method(self):
+    ...         pass
+    """
+
+    def decorator(func_or_class: F) -> F:
+        feature_name = f"{func_or_class.__module__}.{func_or_class.__qualname__}"
+
+        if isinstance(func_or_class, type):
+            # Handle class deprecation
+            original_init = func_or_class.__init__
+
+            @functools.wraps(original_init)
+            def new_init(self: Any, *args: Any, **kwargs: Any) -> None:
+                DeprecationHelper.warn(
+                    feature_name,
+                    removal_version,
+                    alternative,
+                    extra_message,
+                )
+                original_init(self, *args, **kwargs)
+
+            func_or_class.__init__ = new_init
+        else:
+            # Handle function deprecation
+            @functools.wraps(func_or_class)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                DeprecationHelper.warn(
+                    feature_name,
+                    removal_version,
+                    alternative,
+                    extra_message,
+                )
+                return func_or_class(*args, **kwargs)
+
+            return wrapper  # type: ignore
+
+        return func_or_class  # type: ignore[return-value]
+
+    return decorator
+
+
+def warn_deprecated(
+    feature_name: str,
+    removal_version: str,
+    alternative: str | None = None,
+    extra_message: str | None = None,
+) -> None:
+    """Issue a deprecation warning.
+
+    Parameters
+    ----------
+    feature_name : str
+        Name of the deprecated feature.
+    removal_version : str
+        Version in which the feature will be removed.
+    alternative : str, optional
+        Recommended alternative to use instead.
+    extra_message : str, optional
+        Additional context or migration instructions.
+
+    Examples
+    --------
+    >>> warn_deprecated("old_config_key", "1.0.0", "new_config_key")
+    """
+    DeprecationHelper.warn(feature_name, removal_version, alternative, extra_message)

openai_sdk_helpers/utils/json_utils.py

@@ -0,0 +1,98 @@
+"""JSON serialization helpers for helper types."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, is_dataclass
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from .path_utils import check_filepath
+
+
+def _to_jsonable(value: Any) -> Any:
+    """Convert common helper types to JSON-serializable forms."""
+    from openai_sdk_helpers.structure.base import BaseStructure
+
+    if value is None:
+        return None
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if is_dataclass(value) and not isinstance(value, type):
+        return {k: _to_jsonable(v) for k, v in asdict(value).items()}
+    if hasattr(value, "model_dump"):
+        model_dump = getattr(value, "model_dump")
+        return model_dump()
+    if isinstance(value, dict):
+        return {str(k): _to_jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        return [_to_jsonable(v) for v in value]
+    if isinstance(value, BaseStructure):
+        return value.model_dump()
+    return value
+
+
+def coerce_jsonable(value: Any) -> Any:
+    """Convert value into a JSON-serializable representation."""
+    from openai_sdk_helpers.response.base import BaseResponse
+
+    if value is None:
+        return None
+    if isinstance(value, BaseResponse):
+        return coerce_jsonable(value.messages.to_json())
+    if is_dataclass(value) and not isinstance(value, type):
+        return {key: coerce_jsonable(item) for key, item in asdict(value).items()}
+    coerced = _to_jsonable(value)
+    try:
+        json.dumps(coerced)
+        return coerced
+    except TypeError:
+        return str(coerced)
+
+
+class customJSONEncoder(json.JSONEncoder):
+    """JSON encoder for common helper types like enums and paths."""
+
+    def default(self, o: Any) -> Any:  # noqa: D401
+        """Return JSON-serializable representation of ``o``."""
+        return _to_jsonable(o)
+
+
+class JSONSerializable:
+    """Mixin for classes that can be serialized to JSON."""
+
+    def to_json(self) -> dict[str, Any]:
+        """Return a JSON-compatible dict representation."""
+        if is_dataclass(self) and not isinstance(self, type):
+            return {k: _to_jsonable(v) for k, v in asdict(self).items()}
+        if hasattr(self, "model_dump"):
+            model_dump = getattr(self, "model_dump")
+            return _to_jsonable(model_dump())
+        return _to_jsonable(self.__dict__)
+
+    def to_json_file(self, filepath: str | Path) -> str:
+        """Write serialized JSON data to a file path."""
+        target = Path(filepath)
+        check_filepath(fullfilepath=str(target))
+        with open(target, "w", encoding="utf-8") as handle:
+            json.dump(
+                self.to_json(),
+                handle,
+                indent=2,
+                ensure_ascii=False,
+                cls=customJSONEncoder,
+            )
+        return str(target)
+
+
+__all__ = [
+    "coerce_jsonable",
+    "JSONSerializable",
+    "customJSONEncoder",
+]