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

openai_sdk_helpers/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/environment.py

@@ -20,6 +20,8 @@ from __future__ import annotations
 
 from pathlib import Path
 
+from openai_sdk_helpers.utils import ensure_directory
+
 DATETIME_FMT = "%Y%m%d_%H%M%S"
 DEFAULT_MODEL = "gpt-4o-mini"
 
@@ -50,5 +52,4 @@ def get_data_path(name: str) -> Path:
     """
     base = Path.home() / ".openai-sdk-helpers"
     path = base / name
-    path.mkdir(parents=True, exist_ok=True)
-    return path
+    return ensure_directory(path)

openai_sdk_helpers/errors.py

@@ -4,11 +4,8 @@ Provides specific exception types for different error scenarios,
 improving error handling and debugging capabilities.
 """
 
-import logging
 from collections.abc import Mapping
 
-from openai_sdk_helpers.utils.core import log
-
 
 class OpenAISDKError(Exception):
     """Base exception for openai-sdk-helpers library.
@@ -40,15 +37,6 @@ class OpenAISDKError(Exception):
         """Initialize the exception with message and optional context."""
         super().__init__(message)
         self.context = dict(context) if context is not None else {}
-        self._log_context()
-
-    def _log_context(self) -> None:
-        """Log error with context for debugging."""
-        context_str = f"\nContext: {self.context}" if self.context else ""
-        log(
-            f"{self.__class__.__name__}: {str(self)}{context_str}",
-            level=logging.ERROR,
-        )
 
 
 class ConfigurationError(OpenAISDKError):

openai_sdk_helpers/logging_config.py

@@ -1,105 +1,34 @@
-"""Centralized logging configuration for openai-sdk-helpers.
-
-Provides a centralized factory for creating and configuring loggers
-with consistent formatting and handler management.
-"""
+"""Centralized logging configuration for openai-sdk-helpers."""
 
 import logging
-import threading
-from typing import Any
-
 
-class LoggerFactory:
-    """Centralized logger creation and configuration.
 
-    Manages logger initialization and configuration to ensure consistent
-    logging behavior across the entire SDK. Thread-safe.
+def log(
+    message: str,
+    level: int = logging.INFO,
+    *,
+    logger_name: str = "openai_sdk_helpers",
+) -> None:
+    """Log a message using Python's standard logging.
+
+    Parameters
+    ----------
+    message : str
+        The message to log.
+    level : int
+        Logging level (e.g., logging.DEBUG, logging.INFO).
+        Default is logging.INFO.
+    logger_name : str
+        Name of the logger. Default is "openai_sdk_helpers".
 
     Examples
     --------
-    Configure logging once at application startup:
-
-    >>> from openai_sdk_helpers.logging_config import LoggerFactory
-    >>> import logging
-    >>> LoggerFactory.configure(
-    ...     level=logging.DEBUG,
-    ...     handlers=[logging.StreamHandler()],
-    ... )
-
-    Get a logger instance in your module:
-
-    >>> logger = LoggerFactory.get_logger("openai_sdk_helpers.agent")
-    >>> logger.debug("Debug message")
+    >>> from openai_sdk_helpers.logging_config import log
+    >>> log("Operation completed")
+    >>> log("Debug info", level=logging.DEBUG)
     """
+    logger = logging.getLogger(logger_name)
+    logger.log(level, message)
 
-    _initialized = False
-    _log_level = logging.INFO
-    _handlers: list[logging.Handler] = []
-    _lock = threading.Lock()
-
-    @classmethod
-    def configure(
-        cls,
-        level: int = logging.INFO,
-        handlers: list[logging.Handler] | None = None,
-    ) -> None:
-        """Configure logging globally.
-
-        Parameters
-        ----------
-        level : int
-            Logging level (e.g., logging.DEBUG, logging.INFO).
-            Default is logging.INFO.
-        handlers : list[logging.Handler] | None
-            List of logging handlers. If None, a default
-            StreamHandler is created. Default is None.
-
-        Notes
-        -----
-        This method is thread-safe and can be called multiple times.
-        """
-        with cls._lock:
-            cls._log_level = level
-            if handlers:
-                cls._handlers = handlers
-            else:
-                handler = logging.StreamHandler()
-                handler.setLevel(level)
-                formatter = logging.Formatter(
-                    "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-                )
-                handler.setFormatter(formatter)
-                cls._handlers = [handler]
-            cls._initialized = True
-
-    @classmethod
-    def get_logger(cls, name: str) -> logging.Logger:
-        """Get configured logger instance.
-
-        Parameters
-        ----------
-        name : str
-            Logger name, typically __name__ of calling module.
-
-        Returns
-        -------
-        logging.Logger
-            Configured logger instance.
-        """
-        logger = logging.getLogger(name)
-
-        # Skip configuration if already configured
-        if logger.handlers:
-            return logger
-
-        with cls._lock:
-            if not cls._initialized:
-                cls.configure()
-
-            for handler in cls._handlers:
-                logger.addHandler(handler)
-
-            logger.setLevel(cls._log_level)
-            logger.propagate = False
 
-        return logger
+__all__ = ["log"]

openai_sdk_helpers/prompt/base.py

@@ -176,7 +176,7 @@ class PromptRenderer:
         ...     context={"key": "value"}
         ... )
         """
-        from openai_sdk_helpers.validation import validate_safe_path
+        from openai_sdk_helpers.utils.validation import validate_safe_path
 
         path = Path(template_path)
         if path.is_absolute():