openai-sdk-helpers 0.4.1__py3-none-any.whl → 0.4.3__py3-none-any.whl

openai_sdk_helpers/context_manager.py

@@ -1,241 +0,0 @@
-"""Context manager utilities for resource cleanup.
-
-Provides base classes and utilities for proper resource management
-with guaranteed cleanup on exit or exception.
-"""
-
-from __future__ import annotations
-
-import asyncio
-from contextlib import asynccontextmanager
-from types import TracebackType
-from typing import Any, AsyncIterator, Generic, Optional, TypeVar
-
-from openai_sdk_helpers.logging_config import log
-
-T = TypeVar("T")
-
-
-class ManagedResource(Generic[T]):
-    """Base class for resources that need cleanup.
-
-    Provides context manager support for guaranteed resource cleanup
-    even when exceptions occur.
-
-    Examples
-    --------
-    >>> class DatabaseConnection(ManagedResource[Connection]):
-    ...     def __init__(self, connection):
-    ...         self.connection = connection
-    ...
-    ...     def close(self) -> None:
-    ...         if self.connection:
-    ...             self.connection.close()
-
-    >>> with DatabaseConnection(connect()) as db:
-    ...     db.query("SELECT ...")
-    """
-
-    def __enter__(self) -> T:
-        """Enter context manager.
-
-        Returns
-        -------
-        T
-            The resource instance (self cast appropriately).
-        """
-        return self  # type: ignore
-
-    def __exit__(
-        self,
-        exc_type: Optional[type[BaseException]],
-        exc_val: Optional[BaseException],
-        exc_tb: Optional[TracebackType],
-    ) -> bool:
-        """Exit context manager with cleanup.
-
-        Parameters
-        ----------
-        exc_type : type[BaseException] | None
-            Type of exception if one was raised, None otherwise.
-        exc_val : BaseException | None
-            Exception instance if one was raised, None otherwise.
-        exc_tb : TracebackType | None
-            Traceback if exception was raised, None otherwise.
-
-        Returns
-        -------
-        bool
-            False to re-raise exceptions, True to suppress them.
-        """
-        try:
-            self.close()
-        except Exception as exc:
-            log(f"Error during cleanup: {exc}", level=30)  # logging.WARNING
-            # Don't suppress cleanup errors
-            if exc_type is None:
-                raise
-
-        return False  # Re-raise exceptions
-
-    def close(self) -> None:
-        """Close and cleanup the resource.
-
-        Should be overridden by subclasses to perform actual cleanup.
-        Should not raise exceptions, but may log them.
-
-        Raises
-        ------
-        Exception
-            May raise if cleanup fails catastrophically.
-        """
-        pass
-
-
-class AsyncManagedResource(Generic[T]):
-    """Base class for async resources that need cleanup.
-
-    Provides async context manager support for guaranteed resource cleanup
-    even when exceptions occur.
-
-    Examples
-    --------
-    >>> class AsyncDatabaseConnection(AsyncManagedResource[AsyncConnection]):
-    ...     def __init__(self, connection):
-    ...         self.connection = connection
-    ...
-    ...     async def close(self) -> None:
-    ...         if self.connection:
-    ...             await self.connection.close()
-
-    >>> async with AsyncDatabaseConnection(await connect()) as db:
-    ...     await db.query("SELECT ...")
-    """
-
-    async def __aenter__(self) -> T:
-        """Enter async context manager.
-
-        Returns
-        -------
-        T
-            The resource instance (self cast appropriately).
-        """
-        return self  # type: ignore
-
-    async def __aexit__(
-        self,
-        exc_type: Optional[type[BaseException]],
-        exc_val: Optional[BaseException],
-        exc_tb: Optional[TracebackType],
-    ) -> bool:
-        """Exit async context manager with cleanup.
-
-        Parameters
-        ----------
-        exc_type : type[BaseException] | None
-            Type of exception if one was raised, None otherwise.
-        exc_val : BaseException | None
-            Exception instance if one was raised, None otherwise.
-        exc_tb : TracebackType | None
-            Traceback if exception was raised, None otherwise.
-
-        Returns
-        -------
-        bool
-            False to re-raise exceptions, True to suppress them.
-        """
-        try:
-            await self.close()
-        except Exception as exc:
-            log(f"Error during async cleanup: {exc}", level=30)  # logging.WARNING
-            # Don't suppress cleanup errors
-            if exc_type is None:
-                raise
-
-        return False  # Re-raise exceptions
-
-    async def close(self) -> None:
-        """Close and cleanup the resource asynchronously.
-
-        Should be overridden by subclasses to perform actual cleanup.
-        Should not raise exceptions, but may log them.
-
-        Raises
-        ------
-        Exception
-            May raise if cleanup fails catastrophically.
-        """
-        pass
-
-
-def ensure_closed(resource: Any) -> None:
-    """Safely close a resource if it has a close method.
-
-    Logs errors but doesn't raise them.
-
-    Parameters
-    ----------
-    resource : Any
-        Object that may have a close() method.
-    """
-    if resource is None:
-        return
-
-    close_method = getattr(resource, "close", None)
-    if callable(close_method):
-        try:
-            close_method()
-        except Exception as exc:
-            log(f"Error closing {type(resource).__name__}: {exc}", level=30)
-
-
-async def ensure_closed_async(resource: Any) -> None:
-    """Safely close a resource asynchronously if it has an async close method.
-
-    Logs errors but doesn't raise them.
-
-    Parameters
-    ----------
-    resource : Any
-        Object that may have an async close() method.
-    """
-    if resource is None:
-        return
-
-    close_method = getattr(resource, "close", None)
-    if callable(close_method):
-        try:
-            if asyncio.iscoroutinefunction(close_method):
-                await close_method()
-            else:
-                close_method()
-        except Exception as exc:
-            log(
-                f"Error closing async {type(resource).__name__}: {exc}",
-                level=30,
-            )
-
-
-@asynccontextmanager
-async def async_context(resource: AsyncManagedResource[T]) -> AsyncIterator[T]:
-    """Context manager for async resources.
-
-    Parameters
-    ----------
-    resource : AsyncManagedResource
-        Async resource to manage.
-
-    Yields
-    ------
-    T
-        The resource instance.
-
-    Examples
-    --------
-    >>> async with async_context(my_resource) as resource:
-    ...     await resource.do_something()
-    """
-    try:
-        yield await resource.__aenter__()
-    finally:
-        await resource.__aexit__(None, None, None)

openai_sdk_helpers/deprecation.py

@@ -1,167 +0,0 @@
-"""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/retry.py

@@ -1,175 +0,0 @@
-"""Retry decorators with exponential backoff for API operations.
-
-Provides decorators for retrying async and sync functions with
-exponential backoff and jitter when rate limiting or transient
-errors occur.
-"""
-
-import asyncio
-import logging
-import random
-import time
-from functools import wraps
-from typing import Any, Callable, ParamSpec, TypeVar
-
-from openai import APIError, RateLimitError
-
-from openai_sdk_helpers.errors import AsyncExecutionError
-from openai_sdk_helpers.logging_config import log
-
-P = ParamSpec("P")
-T = TypeVar("T")
-
-# Default retry configuration constants
-DEFAULT_MAX_RETRIES = 3
-DEFAULT_BASE_DELAY = 1.0
-DEFAULT_MAX_DELAY = 60.0
-
-# HTTP status codes for transient errors
-TRANSIENT_HTTP_STATUS_CODES = frozenset({408, 429, 500, 502, 503})
-
-
-def with_exponential_backoff(
-    max_retries: int = DEFAULT_MAX_RETRIES,
-    base_delay: float = DEFAULT_BASE_DELAY,
-    max_delay: float = DEFAULT_MAX_DELAY,
-) -> Callable[[Callable[P, T]], Callable[P, T]]:
-    """Decorate functions with exponential backoff on transient errors.
-
-    Retries on RateLimitError or transient API errors (5xx, 408, 429).
-    Uses exponential backoff with jitter to avoid thundering herd.
-
-    Parameters
-    ----------
-    max_retries : int
-        Maximum number of retry attempts (total attempts = max_retries + 1).
-        Default is 3.
-    base_delay : float
-        Initial delay in seconds before first retry. Default is 1.0.
-    max_delay : float
-        Maximum delay in seconds between retries. Default is 60.0.
-
-    Returns
-    -------
-    Callable
-        Decorator function.
-
-    Examples
-    --------
-    >>> @with_exponential_backoff(max_retries=3, base_delay=1.0)
-    ... def call_api(query: str) -> str:
-    ...     # API call that may fail with rate limiting
-    ...     return client.call(query)
-    """
-
-    def decorator(func: Callable[P, T]) -> Callable[P, T]:
-        """Apply retry logic to function."""
-        if asyncio.iscoroutinefunction(func):
-
-            @wraps(func)
-            async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
-                """Async wrapper with retry logic."""
-                last_exc: Exception | None = None
-                for attempt in range(max_retries + 1):
-                    try:
-                        return await func(*args, **kwargs)
-                    except RateLimitError as exc:
-                        last_exc = exc
-                        if attempt >= max_retries:
-                            raise
-                        delay = min(
-                            base_delay * (2**attempt) + random.uniform(0, 1),
-                            max_delay,
-                        )
-                        log(
-                            f"Rate limited on {func.__name__}, retrying in "
-                            f"{delay:.2f}s (attempt {attempt + 1}/{max_retries + 1})",
-                            level=logging.WARNING,
-                        )
-                        await asyncio.sleep(delay)
-                    except APIError as exc:
-                        last_exc = exc
-                        status_code: int | None = getattr(exc, "status_code", None)
-                        # Only retry on transient errors
-                        if (
-                            not status_code
-                            or status_code not in TRANSIENT_HTTP_STATUS_CODES
-                        ):
-                            raise
-                        if attempt >= max_retries:
-                            raise
-                        delay = min(
-                            base_delay * (2**attempt),
-                            max_delay,
-                        )
-                        log(
-                            f"Transient API error on {func.__name__}: "
-                            f"{status_code}, retrying in {delay:.2f}s "
-                            f"(attempt {attempt + 1}/{max_retries + 1})",
-                            level=logging.WARNING,
-                        )
-                        await asyncio.sleep(delay)
-
-                # Should never reach here, but handle edge case
-                if last_exc:
-                    raise last_exc
-                raise AsyncExecutionError(
-                    f"Unexpected state in {func.__name__} after retries"
-                )
-
-            return async_wrapper  # type: ignore
-
-        @wraps(func)
-        def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
-            """Sync wrapper with retry logic."""
-            last_exc: Exception | None = None
-            for attempt in range(max_retries + 1):
-                try:
-                    return func(*args, **kwargs)
-                except RateLimitError as exc:
-                    last_exc = exc
-                    if attempt >= max_retries:
-                        raise
-                    delay = min(
-                        base_delay * (2**attempt) + random.uniform(0, 1),
-                        max_delay,
-                    )
-                    log(
-                        f"Rate limited on {func.__name__}, retrying in "
-                        f"{delay:.2f}s (attempt {attempt + 1}/{max_retries + 1})",
-                        level=logging.WARNING,
-                    )
-                    time.sleep(delay)
-                except APIError as exc:
-                    last_exc = exc
-                    status_code: int | None = getattr(exc, "status_code", None)
-                    # Only retry on transient errors
-                    if (
-                        not status_code
-                        or status_code not in TRANSIENT_HTTP_STATUS_CODES
-                    ):
-                        raise
-                    if attempt >= max_retries:
-                        raise
-                    delay = min(
-                        base_delay * (2**attempt),
-                        max_delay,
-                    )
-                    log(
-                        f"Transient API error on {func.__name__}: "
-                        f"{status_code}, retrying in {delay:.2f}s "
-                        f"(attempt {attempt + 1}/{max_retries + 1})",
-                        level=logging.WARNING,
-                    )
-                    time.sleep(delay)
-
-            # Should never reach here, but handle edge case
-            if last_exc:
-                raise last_exc
-            raise AsyncExecutionError(
-                f"Unexpected state in {func.__name__} after retries"
-            )
-
-        return sync_wrapper  # type: ignore
-
-    return decorator