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

openai_sdk_helpers/utils/core.py

@@ -1,29 +1,37 @@
-"""Core utility helpers for openai-sdk-helpers."""
+"""Core utility helpers for openai-sdk-helpers.
+
+This module provides foundational utility functions for type coercion,
+file path validation, JSON serialization, and logging. These utilities
+support consistent data handling across the package.
+"""
 
 from __future__ import annotations
 
 import json
 import logging
 import ast
+from collections.abc import Iterable, Mapping
 from dataclasses import asdict, is_dataclass
 from datetime import datetime
 from enum import Enum
 from pathlib import Path
-from typing import Any, Dict, Iterable, List, Mapping, Optional, TypeVar
+from typing import Any, TypeVar
+
 
+def coerce_optional_float(value: object) -> float | None:
+    """Return a float when the provided value can be coerced, otherwise None.
 
-def coerce_optional_float(value: Any) -> Optional[float]:
-    """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 : Any
+    value : object
         Value to convert into a float. Strings must be parseable as floats.
 
     Returns
     -------
-    float | None
-        Converted float value or ``None`` if the input is ``None``.
+    float or None
+        Converted float value or None if the input is None.
 
     Raises
     ------
@@ -31,6 +39,15 @@ def coerce_optional_float(value: Any) -> Optional[float]:
         If a non-empty string cannot be converted to a float.
     TypeError
         If the value is not a float-compatible type.
+
+    Examples
+    --------
+    >>> coerce_optional_float(3.14)
+    3.14
+    >>> coerce_optional_float("2.5")
+    2.5
+    >>> coerce_optional_float(None) is None
+    True
     """
     if value is None:
         return None
@@ -44,18 +61,21 @@ def coerce_optional_float(value: Any) -> Optional[float]:
     raise TypeError("timeout must be a float, int, str, or None")
 
 
-def coerce_optional_int(value: Any) -> Optional[int]:
-    """Return an int when the provided value can be coerced, otherwise ``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 : Any
+    value : object
         Value to convert into an int. Strings must be parseable as integers.
 
     Returns
     -------
-    int | None
-        Converted integer value or ``None`` if the input is ``None``.
+    int or None
+        Converted integer value or None if the input is None.
 
     Raises
     ------
@@ -63,6 +83,17 @@ def coerce_optional_int(value: Any) -> Optional[int]:
         If a non-empty string cannot be converted to an integer.
     TypeError
         If the value is not an int-compatible type.
+
+    Examples
+    --------
+    >>> coerce_optional_int(42)
+    42
+    >>> coerce_optional_int("100")
+    100
+    >>> coerce_optional_int(3.0)
+    3
+    >>> coerce_optional_int(None) is None
+    True
     """
     if value is None:
         return None
@@ -78,23 +109,32 @@ def coerce_optional_int(value: Any) -> Optional[int]:
     raise TypeError("max_retries must be an int, str, or None")
 
 
-def coerce_dict(value: Any) -> Dict[str, Any]:
-    """Return a string-keyed dictionary built from ``value`` if possible.
+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 : Any
-        Mapping-like value to convert. ``None`` yields an empty dictionary.
+    value : object
+        Mapping-like value to convert. None yields an empty dictionary.
 
     Returns
     -------
     dict[str, Any]
-        Dictionary representation of ``value``.
+        Dictionary representation of value.
 
     Raises
     ------
     TypeError
         If the value cannot be treated as a mapping.
+
+    Examples
+    --------
+    >>> coerce_dict({"a": 1})
+    {'a': 1}
+    >>> coerce_dict(None)
+    {}
     """
     if value is None:
         return {}
@@ -103,22 +143,160 @@ def coerce_dict(value: Any) -> Dict[str, Any]:
     raise TypeError("extra_client_kwargs must be a mapping or None")
 
 
+def build_openai_settings(
+    api_key: str | None = None,
+    org_id: str | None = None,
+    project_id: str | None = None,
+    base_url: str | None = None,
+    default_model: str | None = None,
+    timeout: float | str | None = None,
+    max_retries: int | str | None = None,
+    dotenv_path: Path | None = None,
+    **extra_kwargs: Any,
+) -> Any:  # Returns OpenAISettings but use Any to avoid circular import
+    """Build OpenAI settings from environment with explicit validation.
+
+    Convenience function for creating OpenAISettings with validation and
+    clear error messages. Reads from environment variables and validates
+    required fields, with explicit type coercion for timeout and max_retries.
+
+    Parameters
+    ----------
+    api_key : str or None, default None
+        API key for OpenAI authentication. If None, reads from OPENAI_API_KEY.
+    org_id : str or None, default None
+        Organization ID. If None, reads from OPENAI_ORG_ID.
+    project_id : str or None, default None
+        Project ID. If None, reads from OPENAI_PROJECT_ID.
+    base_url : str or None, default None
+        Base URL for API requests. If None, reads from OPENAI_BASE_URL.
+    default_model : str or None, default None
+        Default model name. If None, reads from OPENAI_MODEL.
+    timeout : float, str, or None, default None
+        Request timeout in seconds. If None, reads from OPENAI_TIMEOUT.
+        Can be string that will be parsed to float.
+    max_retries : int, str, or None, default None
+        Maximum retry attempts. If None, reads from OPENAI_MAX_RETRIES.
+        Can be string that will be parsed to int.
+    dotenv_path : Path or None, default None
+        Path to .env file. If None, searches for .env in current directory.
+    **extra_kwargs : Any
+        Additional keyword arguments for extra_client_kwargs.
+
+    Returns
+    -------
+    OpenAISettings
+        Configured settings instance.
+
+    Raises
+    ------
+    ValueError
+        If OPENAI_API_KEY is not found in environment or parameters.
+        If timeout cannot be parsed as float.
+        If max_retries cannot be parsed as int.
+    TypeError
+        If timeout or max_retries have invalid types.
+
+    Examples
+    --------
+    Build from explicit parameters:
+
+    >>> settings = build_openai_settings(
+    ...     api_key="sk-...",
+    ...     default_model="gpt-4o",
+    ...     timeout=30.0
+    ... )
+
+    Build from environment:
+
+    >>> settings = build_openai_settings()  # doctest: +SKIP
+
+    With custom .env location:
+
+    >>> settings = build_openai_settings(
+    ...     dotenv_path=Path("/path/to/.env")
+    ... )  # doctest: +SKIP
+    """
+    # Import at runtime to avoid circular import
+    from openai_sdk_helpers.config import OpenAISettings
+
+    # Parse timeout with validation
+    parsed_timeout: float | None = None
+    if timeout is not None:
+        try:
+            parsed_timeout = coerce_optional_float(timeout)
+        except (ValueError, TypeError) as exc:
+            raise ValueError(
+                f"Invalid timeout value '{timeout}'. Must be a number or numeric string."
+            ) from exc
+
+    # Parse max_retries with validation
+    parsed_max_retries: int | None = None
+    if max_retries is not None:
+        try:
+            parsed_max_retries = coerce_optional_int(max_retries)
+        except (ValueError, TypeError) as exc:
+            raise ValueError(
+                f"Invalid max_retries value '{max_retries}'. "
+                "Must be an integer or numeric string."
+            ) from exc
+
+    # Build settings using from_env with overrides
+    overrides = {}
+    if api_key is not None:
+        overrides["api_key"] = api_key
+    if org_id is not None:
+        overrides["org_id"] = org_id
+    if project_id is not None:
+        overrides["project_id"] = project_id
+    if base_url is not None:
+        overrides["base_url"] = base_url
+    if default_model is not None:
+        overrides["default_model"] = default_model
+    if parsed_timeout is not None:
+        overrides["timeout"] = parsed_timeout
+    if parsed_max_retries is not None:
+        overrides["max_retries"] = parsed_max_retries
+    if extra_kwargs:
+        overrides["extra_client_kwargs"] = extra_kwargs
+
+    try:
+        return OpenAISettings.from_env(dotenv_path=dotenv_path, **overrides)
+    except ValueError as exc:
+        # Re-raise with more context but preserve original message
+        raise ValueError(f"Failed to build OpenAI settings: {exc}") from exc
+
+
 T = TypeVar("T")
 _configured_logging = False
 
 
-def ensure_list(value: Iterable[T] | T | None) -> List[T]:
+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.
+        Item or iterable to wrap. None yields an empty list.
 
     Returns
     -------
     list[T]
-        Normalized list representation of ``value``.
+        Normalized list representation of value.
+
+    Examples
+    --------
+    >>> ensure_list(None)
+    []
+    >>> ensure_list(5)
+    [5]
+    >>> ensure_list([1, 2, 3])
+    [1, 2, 3]
+    >>> ensure_list(("a", "b"))
+    ['a', 'b']
     """
     if value is None:
         return []
@@ -134,12 +312,15 @@ def check_filepath(
 ) -> Path:
     """Ensure the parent directory for a file path exists.
 
+    Creates parent directories as needed. Exactly one of filepath or
+    fullfilepath must be provided.
+
     Parameters
     ----------
-    filepath : Path | None, optional
-        Path object to validate. Mutually exclusive with ``fullfilepath``.
-    fullfilepath : str | None, optional
-        String path to validate. Mutually exclusive with ``filepath``.
+    filepath : Path or None, optional
+        Path object to validate. Mutually exclusive with fullfilepath.
+    fullfilepath : str or None, optional
+        String path to validate. Mutually exclusive with filepath.
 
     Returns
     -------
@@ -149,7 +330,14 @@ def check_filepath(
     Raises
     ------
     ValueError
-        If neither ``filepath`` nor ``fullfilepath`` is provided.
+        If neither filepath nor fullfilepath is provided.
+
+    Examples
+    --------
+    >>> from pathlib import Path
+    >>> path = check_filepath(filepath=Path("/tmp/test.txt"))
+    >>> isinstance(path, Path)
+    True
     """
     if filepath is None and fullfilepath is None:
         raise ValueError("filepath or fullfilepath is required.")
@@ -166,6 +354,9 @@ def check_filepath(
 def _to_jsonable(value: Any) -> Any:
     """Convert common helper types to JSON-serializable forms.
 
+    Handles Enum, Path, datetime, dataclasses, Pydantic models, dicts,
+    lists, tuples, and sets.
+
     Parameters
     ----------
     value : Any
@@ -174,7 +365,11 @@ def _to_jsonable(value: Any) -> Any:
     Returns
     -------
     Any
-        A JSON-safe representation of ``value``.
+        A JSON-safe representation of value.
+
+    Notes
+    -----
+    This is an internal helper function. Use coerce_jsonable for public API.
     """
     if value is None:
         return None
@@ -197,7 +392,10 @@ def _to_jsonable(value: Any) -> Any:
 
 
 def coerce_jsonable(value: Any) -> Any:
-    """Convert ``value`` into a JSON-serializable representation.
+    """Convert value into a JSON-serializable representation.
+
+    Handles BaseStructure, BaseResponse, dataclasses, and other complex
+    types by recursively converting them to JSON-compatible forms.
 
     Parameters
     ----------
@@ -207,7 +405,14 @@ def coerce_jsonable(value: Any) -> Any:
     Returns
     -------
     Any
-        JSON-serializable representation of ``value``.
+        JSON-serializable representation of value.
+
+    Examples
+    --------
+    >>> from datetime import datetime
+    >>> result = coerce_jsonable({"date": datetime(2024, 1, 1)})
+    >>> isinstance(result, dict)
+    True
     """
     from openai_sdk_helpers.response.base import BaseResponse
     from openai_sdk_helpers.structure.base import BaseStructure
@@ -229,16 +434,29 @@ def coerce_jsonable(value: Any) -> Any:
 
 
 class customJSONEncoder(json.JSONEncoder):
-    """Encode common helper types like enums and paths.
+    """JSON encoder for common helper types like enums and paths.
+
+    Extends json.JSONEncoder to handle Enum, Path, datetime, dataclasses,
+    and Pydantic models automatically.
 
     Methods
     -------
     default(o)
-        Return a JSON-serializable representation of ``o``.
+        Return a JSON-serializable representation of o.
+
+    Examples
+    --------
+    >>> import json
+    >>> from pathlib import Path
+    >>> json.dumps({"path": Path("/tmp")}, cls=customJSONEncoder)
+    '{"path": "/tmp"}'
     """
 
     def default(self, o: Any) -> Any:
-        """Return a JSON-serializable representation of ``o``.
+        """Return a JSON-serializable representation of o.
+
+        Called by the json module when the default serialization fails.
+        Delegates to _to_jsonable for type-specific conversions.
 
         Parameters
         ----------
@@ -248,7 +466,7 @@ class customJSONEncoder(json.JSONEncoder):
         Returns
         -------
         Any
-            JSON-safe representation of ``o``.
+            JSON-safe representation of o.
         """
         return _to_jsonable(o)
 
@@ -256,21 +474,44 @@ class customJSONEncoder(json.JSONEncoder):
 class JSONSerializable:
     """Mixin for classes that can be serialized to JSON.
 
+    Provides to_json() and to_json_file() methods for any class. Works
+    with dataclasses, Pydantic models, and regular classes with __dict__.
+
     Methods
     -------
     to_json()
         Return a JSON-compatible dict representation of the instance.
     to_json_file(filepath)
         Write serialized JSON data to a file path.
+
+    Examples
+    --------
+    >>> from dataclasses import dataclass
+    >>> @dataclass
+    ... class MyClass(JSONSerializable):
+    ...     value: int
+    >>> obj = MyClass(value=42)
+    >>> obj.to_json()
+    {'value': 42}
     """
 
-    def to_json(self) -> Dict[str, Any]:
+    def to_json(self) -> dict[str, Any]:
         """Return a JSON-compatible dict representation.
 
+        Automatically handles dataclasses, Pydantic models, and objects
+        with __dict__ attributes.
+
         Returns
         -------
         dict[str, Any]
             Mapping with only JSON-serializable values.
+
+        Examples
+        --------
+        >>> obj = JSONSerializable()
+        >>> result = obj.to_json()
+        >>> isinstance(result, dict)
+        True
         """
         if is_dataclass(self) and not isinstance(self, type):
             return {k: _to_jsonable(v) for k, v in asdict(self).items()}
@@ -282,6 +523,9 @@ class JSONSerializable:
     def to_json_file(self, filepath: str | Path) -> str:
         """Write serialized JSON data to a file path.
 
+        Creates parent directories as needed. Uses customJSONEncoder for
+        handling special types.
+
         Parameters
         ----------
         filepath : str | Path
@@ -291,6 +535,11 @@ class JSONSerializable:
         -------
         str
             String representation of the file path written.
+
+        Examples
+        --------
+        >>> obj = JSONSerializable()
+        >>> path = obj.to_json_file("/tmp/output.json")  # doctest: +SKIP
         """
         target = Path(filepath)
         check_filepath(fullfilepath=str(target))
@@ -308,12 +557,21 @@ class JSONSerializable:
 def log(message: str, level: int = logging.INFO) -> None:
     """Log a message with a basic configuration.
 
+    Configures logging on first use with a simple timestamp format.
+    Subsequent calls use the existing configuration.
+
     Parameters
     ----------
     message : str
         Message to emit.
     level : int, optional
-        Logging level, by default ``logging.INFO``.
+        Logging level (e.g., logging.INFO, logging.WARNING), by default
+        logging.INFO.
+
+    Examples
+    --------
+    >>> import logging
+    >>> log("Test message", level=logging.INFO)  # doctest: +SKIP
     """
     global _configured_logging
     if not _configured_logging:
@@ -331,4 +589,8 @@ __all__ = [
     "JSONSerializable",
     "customJSONEncoder",
     "log",
+    "coerce_optional_float",
+    "coerce_optional_int",
+    "coerce_dict",
+    "build_openai_settings",
 ]