openai-sdk-helpers 0.0.8__py3-none-any.whl → 0.0.9__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 {}
@@ -107,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 []
@@ -134,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
     -------
@@ -149,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.")
@@ -166,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
@@ -174,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
@@ -197,7 +268,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 +281,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 +310,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 +342,7 @@ class customJSONEncoder(json.JSONEncoder):
         Returns
         -------
         Any
-            JSON-safe representation of ``o``.
+            JSON-safe representation of o.
         """
         return _to_jsonable(o)
 
@@ -256,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()}
@@ -282,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
@@ -291,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))
@@ -308,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:

openai_sdk_helpers/validation.py

@@ -0,0 +1,302 @@
+"""Input validation utilities for openai-sdk-helpers.
+
+Provides validators and validation helpers for ensuring data integrity
+at API boundaries and configuration initialization.
+"""
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Callable, TypeVar
+
+from openai_sdk_helpers.errors import InputValidationError
+
+T = TypeVar("T")
+K = TypeVar("K", bound=str)
+V = TypeVar("V")
+U = TypeVar("U")
+
+
+def validate_non_empty_string(value: str, field_name: str) -> str:
+    """Validate that a string is non-empty.
+
+    Parameters
+    ----------
+    value : str
+        String value to validate.
+    field_name : str
+        Name of the field for error messages.
+
+    Returns
+    -------
+    str
+        The validated (stripped) string.
+
+    Raises
+    ------
+    InputValidationError
+        If string is empty or only whitespace.
+    """
+    if not isinstance(value, str):
+        raise InputValidationError(
+            f"{field_name} must be a string, got {type(value).__name__}"
+        )
+    stripped = value.strip()
+    if not stripped:
+        raise InputValidationError(f"{field_name} must be non-empty")
+    return stripped
+
+
+def validate_max_length(value: str, max_len: int, field_name: str) -> str:
+    """Validate that a string doesn't exceed maximum length.
+
+    Parameters
+    ----------
+    value : str
+        String value to validate.
+    max_len : int
+        Maximum allowed length.
+    field_name : str
+        Name of the field for error messages.
+
+    Returns
+    -------
+    str
+        The validated string.
+
+    Raises
+    ------
+    InputValidationError
+        If string exceeds maximum length.
+    """
+    if len(value) > max_len:
+        raise InputValidationError(
+            f"{field_name} must be <= {max_len} characters, "
+            f"got {len(value)} characters"
+        )
+    return value
+
+
+def validate_url_format(url: str, field_name: str = "URL") -> str:
+    """Validate that a string is a valid URL.
+
+    Parameters
+    ----------
+    url : str
+        URL string to validate.
+    field_name : str
+        Name of the field for error messages. Default is "URL".
+
+    Returns
+    -------
+    str
+        The validated URL.
+
+    Raises
+    ------
+    InputValidationError
+        If URL format is invalid.
+    """
+    if not url.startswith(("http://", "https://")):
+        raise InputValidationError(
+            f"{field_name} must start with http:// or https://, got: {url}"
+        )
+    return url
+
+
+def validate_dict_mapping(
+    mapping: Mapping[K, V],
+    expected_keys: set[K],
+    field_name: str,
+    allow_extra: bool = False,
+) -> dict[K, V]:
+    """Validate that a dict contains expected keys.
+
+    Parameters
+    ----------
+    mapping : Mapping
+        Dictionary-like object to validate.
+    expected_keys : set
+        Set of required key names.
+    field_name : str
+        Name of the field for error messages.
+    allow_extra : bool
+        Whether extra keys are allowed. Default is False.
+
+    Returns
+    -------
+    dict
+        The validated dictionary.
+
+    Raises
+    ------
+    InputValidationError
+        If required keys are missing or unexpected keys present (if not allowed).
+    """
+    if not isinstance(mapping, Mapping):
+        raise InputValidationError(
+            f"{field_name} must be a dict or mapping, got {type(mapping).__name__}"
+        )
+
+    missing_keys = expected_keys - set(mapping.keys())
+    if missing_keys:
+        raise InputValidationError(
+            f"{field_name} missing required keys: {', '.join(sorted(missing_keys))}"
+        )
+
+    if not allow_extra:
+        extra_keys = set(mapping.keys()) - expected_keys
+        if extra_keys:
+            raise InputValidationError(
+                f"{field_name} has unexpected keys: {', '.join(sorted(extra_keys))}"
+            )
+
+    return dict(mapping)
+
+
+def validate_list_items(
+    items: list[U],
+    item_validator: Callable[[U], T],
+    field_name: str,
+    allow_empty: bool = False,
+) -> list[T]:
+    """Validate all items in a list using a validator function.
+
+    Parameters
+    ----------
+    items : list
+        List to validate.
+    item_validator : Callable
+        Function that validates individual items.
+    field_name : str
+        Name of the field for error messages.
+    allow_empty : bool
+        Whether an empty list is allowed. Default is False.
+
+    Returns
+    -------
+    list
+        List of validated items.
+
+    Raises
+    ------
+    InputValidationError
+        If list is empty when not allowed, or if any item fails validation.
+    """
+    if not isinstance(items, list):
+        raise InputValidationError(
+            f"{field_name} must be a list, got {type(items).__name__}"
+        )
+
+    if not items and not allow_empty:
+        raise InputValidationError(f"{field_name} must not be empty")
+
+    validated = []
+    for i, item in enumerate(items):
+        try:
+            validated.append(item_validator(item))
+        except (InputValidationError, ValueError) as exc:
+            raise InputValidationError(f"{field_name}[{i}] is invalid: {exc}") from exc
+
+    return validated
+
+
+def validate_choice(
+    value: U,
+    allowed_values: set[U],
+    field_name: str,
+) -> U:
+    """Validate that a value is one of allowed choices.
+
+    Parameters
+    ----------
+    value : Any
+        Value to validate.
+    allowed_values : set
+        Set of allowed values.
+    field_name : str
+        Name of the field for error messages.
+
+    Returns
+    -------
+    Any
+        The validated value.
+
+    Raises
+    ------
+    InputValidationError
+        If value is not in allowed values.
+    """
+    if value not in allowed_values:
+        raise InputValidationError(
+            f"{field_name} must be one of {', '.join(map(str, sorted(allowed_values, key=str)))}; got: {value}"
+        )
+    return value
+
+
+def validate_safe_path(
+    path: Path | str,
+    base_dir: Path | None = None,
+    field_name: str = "path",
+) -> Path:
+    """Validate that a path is safe and does not escape the base directory.
+
+    Protects against path traversal attacks by ensuring the resolved path
+    is within the base directory when provided.
+
+    Parameters
+    ----------
+    path : Path or str
+        Path to validate. Can be absolute or relative.
+    base_dir : Path or None
+        Base directory to validate against. If None, only checks for
+        suspicious patterns but allows any valid path.
+    field_name : str
+        Name of the field for error messages. Default is "path".
+
+    Returns
+    -------
+    Path
+        Validated resolved path.
+
+    Raises
+    ------
+    InputValidationError
+        If path is invalid, contains suspicious patterns, or escapes
+        the base directory.
+
+    Examples
+    --------
+    >>> from pathlib import Path
+    >>> validate_safe_path(Path("./templates/file.txt"), Path("/base"))
+    PosixPath('/base/templates/file.txt')
+    """
+    if isinstance(path, str):
+        path = Path(path)
+
+    # Check for suspicious patterns
+    path_str = str(path)
+    if ".." in path.parts:
+        raise InputValidationError(
+            f"{field_name} contains suspicious '..' pattern: {path_str}"
+        )
+
+    # Resolve to absolute path
+    try:
+        resolved = path.resolve()
+    except (OSError, RuntimeError) as exc:
+        raise InputValidationError(
+            f"{field_name} cannot be resolved: {path_str}"
+        ) from exc
+
+    # If base_dir provided, ensure path is within it
+    if base_dir is not None:
+        try:
+            base_resolved = base_dir.resolve()
+            resolved.relative_to(base_resolved)
+        except ValueError:
+            raise InputValidationError(
+                f"{field_name} escapes base directory: {path_str} "
+                f"is not within {base_dir}"
+            ) from None
+
+    return resolved