openai-sdk-helpers 0.0.8__py3-none-any.whl → 0.1.0__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,116 +56,122 @@ 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:
-            env_file_values = dotenv_values()
-
-        timeout_raw = (
-            overrides.get("timeout")
-            or env_file_values.get("OPENAI_TIMEOUT")
-            or os.getenv("OPENAI_TIMEOUT")
-        )
-        max_retries_raw = (
-            overrides.get("max_retries")
-            or env_file_values.get("OPENAI_MAX_RETRIES")
-            or os.getenv("OPENAI_MAX_RETRIES")
-        )
-
-        values: Dict[str, Any] = {
-            "api_key": overrides.get("api_key")
-            or env_file_values.get("OPENAI_API_KEY")
-            or os.getenv("OPENAI_API_KEY"),
-            "org_id": overrides.get("org_id")
-            or env_file_values.get("OPENAI_ORG_ID")
-            or os.getenv("OPENAI_ORG_ID"),
-            "project_id": overrides.get("project_id")
-            or env_file_values.get("OPENAI_PROJECT_ID")
-            or os.getenv("OPENAI_PROJECT_ID"),
-            "base_url": overrides.get("base_url")
-            or env_file_values.get("OPENAI_BASE_URL")
-            or os.getenv("OPENAI_BASE_URL"),
-            "default_model": overrides.get("default_model")
-            or env_file_values.get("OPENAI_MODEL")
-            or os.getenv("OPENAI_MODEL"),
+
+        def first_non_none(*candidates: Any) -> Any:
+            for candidate in candidates:
+                if candidate is not None:
+                    return candidate
+            return None
+
+        def resolve_value(override_key: str, env_var: str) -> Any:
+            if dotenv_path is not None:
+                return first_non_none(
+                    overrides.get(override_key),
+                    env_file_values.get(env_var),
+                    os.getenv(env_var),
+                )
+            return first_non_none(
+                overrides.get(override_key),
+                os.getenv(env_var),
+            )
+
+        timeout_raw = resolve_value("timeout", "OPENAI_TIMEOUT")
+        max_retries_raw = resolve_value("max_retries", "OPENAI_MAX_RETRIES")
+
+        values: dict[str, Any] = {
+            "api_key": resolve_value("api_key", "OPENAI_API_KEY"),
+            "org_id": resolve_value("org_id", "OPENAI_ORG_ID"),
+            "project_id": resolve_value("project_id", "OPENAI_PROJECT_ID"),
+            "base_url": resolve_value("base_url", "OPENAI_BASE_URL"),
+            "default_model": resolve_value("default_model", "OPENAI_MODEL"),
             "timeout": coerce_optional_float(timeout_raw),
             "max_retries": coerce_optional_int(max_retries_raw),
             "extra_client_kwargs": coerce_dict(overrides.get("extra_client_kwargs")),
@@ -161,16 +191,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 +219,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