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

openai_sdk_helpers/utils/core.py

@@ -1,28 +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
     ------
@@ -30,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
@@ -43,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
     ------
@@ -62,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
@@ -77,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 {}
@@ -106,18 +147,32 @@ 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 []
@@ -133,12 +188,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
     -------
@@ -148,7 +206,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.")
@@ -165,6 +230,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
@@ -173,7 +241,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
@@ -195,17 +267,72 @@ def _to_jsonable(value: Any) -> Any:
     return value
 
 
+def coerce_jsonable(value: Any) -> Any:
+    """Convert value into a JSON-serializable representation.
+
+    Handles BaseStructure, BaseResponse, dataclasses, and other complex
+    types by recursively converting them to JSON-compatible forms.
+
+    Parameters
+    ----------
+    value : Any
+        Object to convert into a JSON-friendly structure.
+
+    Returns
+    -------
+    Any
+        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
+
+    if value is None:
+        return None
+    if isinstance(value, BaseStructure):
+        return value.model_dump()
+    if isinstance(value, BaseResponse):
+        return coerce_jsonable(value.messages.to_json())
+    if is_dataclass(value) and not isinstance(value, type):
+        return {key: coerce_jsonable(item) for key, item in asdict(value).items()}
+    coerced = _to_jsonable(value)
+    try:
+        json.dumps(coerced)
+        return coerced
+    except TypeError:
+        return str(coerced)
+
+
 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
         ----------
@@ -215,7 +342,7 @@ class customJSONEncoder(json.JSONEncoder):
         Returns
         -------
         Any
-            JSON-safe representation of ``o``.
+            JSON-safe representation of o.
         """
         return _to_jsonable(o)
 
@@ -223,21 +350,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()}
@@ -249,6 +399,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
@@ -258,6 +411,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))
@@ -275,12 +433,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:
@@ -294,6 +461,7 @@ def log(message: str, level: int = logging.INFO) -> None:
 __all__ = [
     "ensure_list",
     "check_filepath",
+    "coerce_jsonable",
     "JSONSerializable",
     "customJSONEncoder",
     "log",