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

openai_sdk_helpers/async_utils.py

@@ -0,0 +1,132 @@
+"""Async/sync bridge utilities with proper error handling.
+
+Provides thread-safe wrappers for running async code from sync contexts
+with proper exception propagation and timeout handling.
+"""
+
+import asyncio
+import queue
+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
+
+
+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.
+
+    Uses a queue to safely communicate results and exceptions between threads.
+    Ensures exceptions from the async operation are properly propagated.
+
+    Parameters
+    ----------
+    coro : Coroutine
+        The coroutine to execute.
+    timeout : float
+        Maximum time in seconds to wait for the coroutine to complete.
+        Default is 300 (5 minutes).
+
+    Returns
+    -------
+    Any
+        Result from the coroutine.
+
+    Raises
+    ------
+    AsyncExecutionError
+        If the coroutine fails or timeout occurs.
+
+    Examples
+    --------
+    >>> async def fetch_data():
+    ...     return "data"
+    >>> result = run_coroutine_thread_safe(fetch_data())
+    """
+    result_queue: queue.Queue[T | Exception] = queue.Queue()
+
+    def _thread_runner() -> None:
+        """Run coroutine and put result in queue."""
+        try:
+            result = asyncio.run(coro)
+            result_queue.put(result)
+        except Exception as exc:
+            # Queue stores the exception to propagate later
+            result_queue.put(exc)
+
+    thread = threading.Thread(target=_thread_runner, daemon=False)
+    thread.start()
+
+    try:
+        result = result_queue.get(timeout=timeout)
+        if isinstance(result, Exception):
+            # Re-raise the exception from the thread
+            raise result
+        return result
+    except queue.Empty:
+        raise AsyncExecutionError(
+            f"Coroutine execution timed out after {timeout} seconds"
+        ) from None
+    finally:
+        # 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
+            )
+
+
+def run_coroutine_with_fallback(
+    coro: Coroutine[Any, Any, T],
+) -> T:
+    """Run a coroutine, falling back to thread if event loop is already running.
+
+    Attempts to run the coroutine directly if no event loop is present.
+    If an event loop is already running (nested scenario), creates a new
+    thread to avoid the "RuntimeError: asyncio.run() cannot be called from a
+    running event loop" error.
+
+    Parameters
+    ----------
+    coro : Coroutine
+        The coroutine to execute.
+
+    Returns
+    -------
+    Any
+        Result from the coroutine.
+
+    Raises
+    ------
+    AsyncExecutionError
+        If execution fails or times out.
+
+    Examples
+    --------
+    >>> async def fetch_data():
+    ...     return "data"
+    >>> result = run_coroutine_with_fallback(fetch_data())
+    """
+    try:
+        # Try to get currently running loop
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        # No running loop, safe to use asyncio.run()
+        return asyncio.run(coro)
+
+    # Loop is already running, must use thread
+    if loop.is_running():
+        return run_coroutine_thread_safe(coro)
+
+    # This shouldn't happen but handle defensive
+    return loop.run_until_complete(coro)

openai_sdk_helpers/config.py

@@ -1,10 +1,15 @@
-"""Shared configuration for OpenAI SDK usage."""
+"""Shared configuration for OpenAI SDK usage.
+
+This module provides the OpenAISettings class for centralized management of
+OpenAI client configuration, reading from environment variables and .env files.
+"""
 
 from __future__ import annotations
 
 import os
+from collections.abc import Mapping
 from pathlib import Path
-from typing import Any, Dict, Mapping, Optional
+from typing import Any
 
 from dotenv import dotenv_values
 from openai import OpenAI
@@ -20,6 +25,25 @@ from openai_sdk_helpers.utils import (
 class OpenAISettings(BaseModel):
     """Configuration helpers for constructing OpenAI clients.
 
+    This class centralizes OpenAI SDK configuration by reading from environment
+    variables and optional `.env` files, enabling consistent client setup across
+    your application.
+
+    Examples
+    --------
+    Load settings from environment and create a client:
+
+    >>> from openai_sdk_helpers import OpenAISettings
+    >>> settings = OpenAISettings.from_env()
+    >>> client = settings.create_client()
+
+    Override specific settings:
+
+    >>> settings = OpenAISettings.from_env(
+    ...     default_model="gpt-4o",
+    ...     timeout=60.0
+    ... )
+
     Methods
     -------
     from_env(dotenv_path, **overrides)
@@ -32,84 +56,92 @@ class OpenAISettings(BaseModel):
 
     model_config = ConfigDict(extra="ignore")
 
-    api_key: Optional[str] = Field(
+    api_key: str | None = Field(
         default=None,
         description=(
-            "API key used to authenticate requests. Defaults to ``OPENAI_API_KEY``"
+            "API key used to authenticate requests. Defaults to OPENAI_API_KEY"
             " from the environment."
         ),
     )
-    org_id: Optional[str] = Field(
+    org_id: str | None = Field(
         default=None,
         description=(
             "Organization identifier applied to outgoing requests. Defaults to"
-            " ``OPENAI_ORG_ID``."
+            " OPENAI_ORG_ID."
         ),
     )
-    project_id: Optional[str] = Field(
+    project_id: str | None = Field(
         default=None,
         description=(
             "Project identifier used for billing and resource scoping. Defaults to"
-            " ``OPENAI_PROJECT_ID``."
+            " OPENAI_PROJECT_ID."
         ),
     )
-    base_url: Optional[str] = Field(
+    base_url: str | None = Field(
         default=None,
         description=(
             "Custom base URL for self-hosted or proxied deployments. Defaults to"
-            " ``OPENAI_BASE_URL``."
+            " OPENAI_BASE_URL."
         ),
     )
-    default_model: Optional[str] = Field(
+    default_model: str | None = Field(
         default=None,
         description=(
             "Model name used when constructing agents if no model is explicitly"
-            " provided. Defaults to ``OPENAI_MODEL``."
+            " provided. Defaults to OPENAI_MODEL."
         ),
     )
-    timeout: Optional[float] = Field(
+    timeout: float | None = Field(
         default=None,
         description=(
             "Request timeout in seconds applied to all OpenAI client calls."
-            " Defaults to ``OPENAI_TIMEOUT``."
+            " Defaults to OPENAI_TIMEOUT."
         ),
     )
-    max_retries: Optional[int] = Field(
+    max_retries: int | None = Field(
         default=None,
         description=(
             "Maximum number of automatic retries for transient failures."
-            " Defaults to ``OPENAI_MAX_RETRIES``."
+            " Defaults to OPENAI_MAX_RETRIES."
         ),
     )
-    extra_client_kwargs: Dict[str, Any] = Field(
+    extra_client_kwargs: dict[str, Any] = Field(
         default_factory=dict,
         description=(
-            "Additional keyword arguments forwarded to ``openai.OpenAI``. Use"
-            " this for less common options like ``default_headers`` or"
-            " ``http_client``."
+            "Additional keyword arguments forwarded to openai.OpenAI. Use"
+            " this for less common options like default_headers or"
+            " http_client."
         ),
     )
 
     @classmethod
     def from_env(
-        cls, dotenv_path: Optional[Path] = None, **overrides: Any
-    ) -> "OpenAISettings":
+        cls, dotenv_path: Path | None = None, **overrides: Any
+    ) -> OpenAISettings:
         """Load settings from the environment and optional overrides.
 
+        Reads configuration from environment variables and an optional .env
+        file, with explicit overrides taking precedence.
+
         Parameters
         ----------
-        dotenv_path : Path | None
-            Path to a ``.env`` file to load before reading environment
-            variables. Default ``None``.
+        dotenv_path : Path or None, optional
+            Path to a .env file to load before reading environment
+            variables, by default None.
         overrides : Any
             Keyword overrides applied on top of environment values.
 
         Returns
         -------
         OpenAISettings
-        Settings instance populated from environment variables and overrides.
+            Settings instance populated from environment variables and overrides.
+
+        Raises
+        ------
+        ValueError
+            If OPENAI_API_KEY is not found in environment or dotenv file.
         """
-        env_file_values: Mapping[str, Optional[str]]
+        env_file_values: Mapping[str, str | None]
         if dotenv_path is not None:
             env_file_values = dotenv_values(dotenv_path)
         else:
@@ -126,7 +158,7 @@ class OpenAISettings(BaseModel):
             or os.getenv("OPENAI_MAX_RETRIES")
         )
 
-        values: Dict[str, Any] = {
+        values: dict[str, Any] = {
             "api_key": overrides.get("api_key")
             or env_file_values.get("OPENAI_API_KEY")
             or os.getenv("OPENAI_API_KEY"),
@@ -161,16 +193,19 @@ class OpenAISettings(BaseModel):
 
         return settings
 
-    def client_kwargs(self) -> Dict[str, Any]:
-        """Return keyword arguments for constructing an ``OpenAI`` client.
+    def client_kwargs(self) -> dict[str, Any]:
+        """Return keyword arguments for constructing an OpenAI client.
+
+        Builds a dictionary containing all configured authentication and
+        routing parameters suitable for OpenAI client initialization.
 
         Returns
         -------
-        dict
-        Keyword arguments populated with available authentication and routing
-        values.
+        dict[str, Any]
+            Keyword arguments populated with available authentication and
+            routing values.
         """
-        kwargs: Dict[str, Any] = dict(self.extra_client_kwargs)
+        kwargs: dict[str, Any] = dict(self.extra_client_kwargs)
         if self.api_key:
             kwargs["api_key"] = self.api_key
         if self.org_id:
@@ -186,12 +221,15 @@ class OpenAISettings(BaseModel):
         return kwargs
 
     def create_client(self) -> OpenAI:
-        """Instantiate an ``OpenAI`` client using the stored configuration.
+        """Instantiate an OpenAI client using the stored configuration.
+
+        Uses client_kwargs() to build the client with all configured
+        authentication and routing parameters.
 
         Returns
         -------
         OpenAI
-        Client initialized with ``client_kwargs``.
+            Client initialized with the configured settings.
         """
         return OpenAI(**self.client_kwargs())
 

openai_sdk_helpers/context_manager.py

@@ -0,0 +1,241 @@
+"""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.utils.core 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/enums/__init__.py

@@ -1,4 +1,12 @@
-"""Enum helpers for openai-sdk-helpers."""
+"""Enum utilities for OpenAI SDK helpers.
+
+This module provides specialized enum base classes with metadata capabilities.
+
+Classes
+-------
+CrosswalkJSONEnum
+    String-based enum with crosswalk metadata support.
+"""
 
 from __future__ import annotations
 

openai_sdk_helpers/enums/base.py

@@ -1,29 +1,88 @@
-"""Base enum helpers."""
+"""Base enum classes with metadata support.
+
+This module defines specialized enum base classes that extend the standard
+library's Enum class with additional metadata and serialization capabilities.
+"""
 
 from __future__ import annotations
 
 from enum import Enum
+from typing import Any
 
 
 class CrosswalkJSONEnum(str, Enum):
-    """Enum base class with crosswalk metadata hooks.
+    """String-based enum with crosswalk metadata support.
+
+    Extends both str and Enum to provide string-compatible enum values
+    with optional metadata mappings. Subclasses must implement the
+    CROSSWALK class method to provide structured metadata for each
+    enum member.
+
+    This design allows enums to carry additional context beyond their
+    values, useful for configuration, validation, or documentation purposes.
 
     Methods
     -------
     CROSSWALK()
-        Return metadata describing enum values keyed by name.
+        Return metadata describing enum values keyed by member name.
+
+    Examples
+    --------
+    >>> class Status(CrosswalkJSONEnum):
+    ...     ACTIVE = "active"
+    ...     INACTIVE = "inactive"
+    ...
+    ...     @classmethod
+    ...     def CROSSWALK(cls):
+    ...         return {
+    ...             "ACTIVE": {"description": "Currently active"},
+    ...             "INACTIVE": {"description": "Not active"}
+    ...         }
+    >>> Status.ACTIVE.value
+    'active'
+    >>> Status.CROSSWALK()["ACTIVE"]["description"]
+    'Currently active'
     """
 
     @classmethod
-    def CROSSWALK(cls) -> dict[str, dict[str, object]]:
-        """Return metadata describing enum values keyed by name.
+    def CROSSWALK(cls) -> dict[str, dict[str, Any]]:
+        """Return metadata describing enum values keyed by member name.
+
+        Subclasses must override this method to provide structured
+        metadata for each enum member. The outer dictionary keys
+        correspond to enum member names, and values are dictionaries
+        containing arbitrary metadata.
 
         Returns
         -------
-        dict[str, dict[str, object]]
-            Mapping of enum member names to structured metadata details.
+        dict[str, dict[str, Any]]
+            Mapping of enum member names to their metadata dictionaries.
+            Each metadata dictionary can contain any relevant key-value
+            pairs describing that enum member.
+
+        Raises
+        ------
+        NotImplementedError
+            If called on a subclass that has not implemented this method.
+
+        Examples
+        --------
+        >>> class Priority(CrosswalkJSONEnum):
+        ...     HIGH = "high"
+        ...     LOW = "low"
+        ...
+        ...     @classmethod
+        ...     def CROSSWALK(cls):
+        ...         return {
+        ...             "HIGH": {"value": "high", "weight": 10},
+        ...             "LOW": {"value": "low", "weight": 1}
+        ...         }
+        >>> Priority.CROSSWALK()["HIGH"]["weight"]
+        10
         """
-        raise NotImplementedError("CROSSWALK must be implemented by subclasses.")
+        raise NotImplementedError(
+            f"{cls.__name__}.CROSSWALK() must be implemented by subclasses"
+        )
 
 
 __all__ = ["CrosswalkJSONEnum"]