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

openai_sdk_helpers/deprecation.py

@@ -0,0 +1,167 @@
+"""Deprecation utilities for managing deprecated features.
+
+This module provides infrastructure for marking and managing deprecated
+functions, classes, and features with consistent warning messages.
+
+Functions
+---------
+deprecated
+    Decorator to mark functions or classes as deprecated.
+warn_deprecated
+    Emit a deprecation warning with optional custom message.
+
+Classes
+-------
+DeprecationHelper
+    Utility class for managing deprecation warnings and versions.
+"""
+
+from __future__ import annotations
+
+import functools
+import warnings
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class DeprecationHelper:
+    """Utility class for managing deprecation warnings.
+
+    Provides consistent formatting and control of deprecation warnings
+    across the package.
+
+    Methods
+    -------
+    warn
+        Emit a deprecation warning with standard formatting.
+    """
+
+    @staticmethod
+    def warn(
+        feature_name: str,
+        removal_version: str,
+        alternative: str | None = None,
+        extra_message: str | None = None,
+    ) -> None:
+        """Emit a deprecation warning for a feature.
+
+        Parameters
+        ----------
+        feature_name : str
+            Name of the deprecated feature (e.g., "MyClass.old_method").
+        removal_version : str
+            Version in which the feature will be removed.
+        alternative : str, optional
+            Recommended alternative to use instead.
+        extra_message : str, optional
+            Additional context or migration instructions.
+
+        Raises
+        ------
+        DeprecationWarning
+            Always issues a DeprecationWarning to stderr.
+        """
+        msg = f"{feature_name} is deprecated and will be removed in version {removal_version}."
+        if alternative:
+            msg += f" Use {alternative} instead."
+        if extra_message:
+            msg += f" {extra_message}"
+
+        warnings.warn(msg, DeprecationWarning, stacklevel=3)
+
+
+def deprecated(
+    removal_version: str,
+    alternative: str | None = None,
+    extra_message: str | None = None,
+) -> Callable[[F], F]:
+    """Mark a function or class as deprecated.
+
+    Parameters
+    ----------
+    removal_version : str
+        Version in which the decorated feature will be removed.
+    alternative : str, optional
+        Recommended alternative to use instead.
+    extra_message : str, optional
+        Additional context or migration instructions.
+
+    Returns
+    -------
+    Callable
+        Decorator function that wraps the target function or class.
+
+    Examples
+    --------
+    >>> @deprecated("1.0.0", "new_function")
+    ... def old_function():
+    ...     pass
+
+    >>> class OldClass:
+    ...     @deprecated("1.0.0", "NewClass")
+    ...     def old_method(self):
+    ...         pass
+    """
+
+    def decorator(func_or_class: F) -> F:
+        feature_name = f"{func_or_class.__module__}.{func_or_class.__qualname__}"
+
+        if isinstance(func_or_class, type):
+            # Handle class deprecation
+            original_init = func_or_class.__init__
+
+            @functools.wraps(original_init)
+            def new_init(self: Any, *args: Any, **kwargs: Any) -> None:
+                DeprecationHelper.warn(
+                    feature_name,
+                    removal_version,
+                    alternative,
+                    extra_message,
+                )
+                original_init(self, *args, **kwargs)
+
+            func_or_class.__init__ = new_init
+        else:
+            # Handle function deprecation
+            @functools.wraps(func_or_class)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                DeprecationHelper.warn(
+                    feature_name,
+                    removal_version,
+                    alternative,
+                    extra_message,
+                )
+                return func_or_class(*args, **kwargs)
+
+            return wrapper  # type: ignore
+
+        return func_or_class  # type: ignore[return-value]
+
+    return decorator
+
+
+def warn_deprecated(
+    feature_name: str,
+    removal_version: str,
+    alternative: str | None = None,
+    extra_message: str | None = None,
+) -> None:
+    """Issue a deprecation warning.
+
+    Parameters
+    ----------
+    feature_name : str
+        Name of the deprecated feature.
+    removal_version : str
+        Version in which the feature will be removed.
+    alternative : str, optional
+        Recommended alternative to use instead.
+    extra_message : str, optional
+        Additional context or migration instructions.
+
+    Examples
+    --------
+    >>> warn_deprecated("old_config_key", "1.0.0", "new_config_key")
+    """
+    DeprecationHelper.warn(feature_name, removal_version, alternative, extra_message)

openai_sdk_helpers/environment.py

@@ -20,6 +20,8 @@ from __future__ import annotations
 
 from pathlib import Path
 
+from openai_sdk_helpers.utils import ensure_directory
+
 DATETIME_FMT = "%Y%m%d_%H%M%S"
 DEFAULT_MODEL = "gpt-4o-mini"
 
@@ -50,5 +52,4 @@ def get_data_path(name: str) -> Path:
     """
     base = Path.home() / ".openai-sdk-helpers"
     path = base / name
-    path.mkdir(parents=True, exist_ok=True)
-    return path
+    return ensure_directory(path)

openai_sdk_helpers/errors.py

@@ -4,11 +4,8 @@ Provides specific exception types for different error scenarios,
 improving error handling and debugging capabilities.
 """
 
-import logging
 from collections.abc import Mapping
 
-from openai_sdk_helpers.utils.core import log
-
 
 class OpenAISDKError(Exception):
     """Base exception for openai-sdk-helpers library.
@@ -40,15 +37,6 @@ class OpenAISDKError(Exception):
         """Initialize the exception with message and optional context."""
         super().__init__(message)
         self.context = dict(context) if context is not None else {}
-        self._log_context()
-
-    def _log_context(self) -> None:
-        """Log error with context for debugging."""
-        context_str = f"\nContext: {self.context}" if self.context else ""
-        log(
-            f"{self.__class__.__name__}: {str(self)}{context_str}",
-            level=logging.ERROR,
-        )
 
 
 class ConfigurationError(OpenAISDKError):

openai_sdk_helpers/files_api.py

@@ -0,0 +1,373 @@
+"""Comprehensive OpenAI Files API wrapper.
+
+This module provides a complete, professional implementation of the OpenAI Files API
+with automatic file tracking, lifecycle management, and cleanup capabilities.
+
+References
+----------
+OpenAI Files API: https://platform.openai.com/docs/api-reference/files
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, BinaryIO, Literal, cast
+
+from openai import OpenAI, NOT_GIVEN
+from openai.types import FileDeleted, FileObject
+from openai.pagination import SyncCursorPage
+
+from .utils import log
+
+# Valid purposes for file uploads
+FilePurpose = Literal[
+    "assistants",
+    "batch",
+    "fine-tune",
+    "user_data",
+    "vision",
+]
+
+
+class FilesAPIManager:
+    """Comprehensive manager for OpenAI Files API operations.
+
+    Provides full access to the OpenAI Files API with automatic file tracking,
+    lifecycle management, and cleanup capabilities. Tracks all uploaded files
+    and ensures proper deletion on cleanup.
+
+    Parameters
+    ----------
+    client : OpenAI
+        OpenAI client instance for API calls.
+    auto_track : bool, default True
+        Automatically track uploaded files for cleanup.
+
+    Attributes
+    ----------
+    tracked_files : dict[str, FileObject]
+        Dictionary of tracked file IDs to FileObject instances.
+
+    Methods
+    -------
+    create(file, purpose)
+        Upload a file to OpenAI Files API.
+    retrieve(file_id)
+        Retrieve information about a specific file.
+    list(purpose, limit)
+        List files, optionally filtered by purpose.
+    delete(file_id)
+        Delete a specific file.
+    retrieve_content(file_id)
+        Download file content.
+    cleanup()
+        Delete all tracked files.
+
+    Examples
+    --------
+    >>> from openai import OpenAI
+    >>> from openai_sdk_helpers.files_api import FilesAPIManager
+    >>>
+    >>> client = OpenAI()
+    >>> files_manager = FilesAPIManager(client)
+    >>>
+    >>> # Upload a file
+    >>> with open("document.pdf", "rb") as f:
+    ...     file_obj = files_manager.create(f, purpose="user_data")
+    >>>
+    >>> # List all user data files
+    >>> user_files = files_manager.list(purpose="user_data")
+    >>>
+    >>> # Retrieve file content
+    >>> content = files_manager.retrieve_content(file_obj.id)
+    >>>
+    >>> # Clean up all tracked files
+    >>> files_manager.cleanup()
+    """
+
+    def __init__(self, client: OpenAI, auto_track: bool = True):
+        """Initialize the Files API manager.
+
+        Parameters
+        ----------
+        client : OpenAI
+            OpenAI client instance.
+        auto_track : bool, default True
+            Automatically track uploaded files for cleanup.
+        """
+        self._client = client
+        self._auto_track = auto_track
+        self.tracked_files: dict[str, FileObject] = {}
+
+    def create(
+        self,
+        file: BinaryIO | Path | str,
+        purpose: FilePurpose,
+        track: bool | None = None,
+        expires_after: int | None = None,
+    ) -> FileObject:
+        """Upload a file to the OpenAI Files API.
+
+        Parameters
+        ----------
+        file : BinaryIO, Path, or str
+            File-like object, path to file, or file path string.
+        purpose : FilePurpose
+            The intended purpose of the uploaded file.
+            Options: "assistants", "batch", "fine-tune", "user_data", "vision"
+        track : bool or None, default None
+            Override auto_track for this file. If None, uses instance setting.
+        expires_after : int or None, default None
+            Number of seconds after which the file expires and is deleted.
+            If None and purpose is "user_data", defaults to 86400 (24 hours).
+            For other purposes, files don't expire unless explicitly set.
+
+        Returns
+        -------
+        FileObject
+            Information about the uploaded file.
+
+        Raises
+        ------
+        FileNotFoundError
+            If file path doesn't exist.
+        ValueError
+            If purpose is invalid.
+
+        Examples
+        --------
+        >>> # Upload from file path (user_data expires in 24h by default)
+        >>> file_obj = manager.create("data.jsonl", purpose="user_data")
+        >>>
+        >>> # Upload with custom expiration (1 hour)
+        >>> file_obj = manager.create("temp.txt", purpose="user_data", expires_after=3600)
+        >>>
+        >>> # Upload from file handle
+        >>> with open("image.png", "rb") as f:
+        ...     file_obj = manager.create(f, purpose="vision")
+        >>>
+        >>> # Upload without tracking
+        >>> file_obj = manager.create("temp.txt", purpose="user_data", track=False)
+        """
+        should_track = track if track is not None else self._auto_track
+
+        # Default to 24 hours expiration for user_data files
+        if expires_after is None and purpose == "user_data":
+            expires_after = 86400  # 24 hours in seconds
+
+        # Handle different file input types
+        # Prepare expires_after in OpenAI API format if provided
+        expires_after_param = None
+        if expires_after is not None:
+            expires_after_param = cast(
+                Any, {"anchor": "created_at", "seconds": expires_after}
+            )
+
+        if isinstance(file, (Path, str)):
+            file_path = Path(file).resolve()
+            if not file_path.exists():
+                raise FileNotFoundError(f"File not found: {file}")
+
+            # Use only the basename as filename (remove path)
+            filename = file_path.name
+            with open(file_path, "rb") as f:
+                # Pass tuple (filename, file_data) to set custom filename
+                if expires_after_param is not None:
+                    file_obj = self._client.files.create(
+                        file=(filename, f),
+                        purpose=purpose,
+                        expires_after=expires_after_param,
+                    )
+                else:
+                    file_obj = self._client.files.create(
+                        file=(filename, f), purpose=purpose
+                    )
+        else:
+            # Assume it's a BinaryIO
+            if expires_after_param is not None:
+                file_obj = self._client.files.create(
+                    file=file,
+                    purpose=purpose,
+                    expires_after=expires_after_param,
+                )
+            else:
+                file_obj = self._client.files.create(file=file, purpose=purpose)
+
+        if should_track:
+            self.tracked_files[file_obj.id] = file_obj
+            expiry_msg = f" (expires in {expires_after}s)" if expires_after else ""
+            log(
+                f"Uploaded and tracking file {file_obj.id} ({file_obj.filename}) "
+                f"with purpose '{purpose}'{expiry_msg}"
+            )
+        else:
+            log(
+                f"Uploaded file {file_obj.id} ({file_obj.filename}) "
+                f"with purpose '{purpose}' (not tracked)"
+            )
+
+        return file_obj
+
+    def retrieve(self, file_id: str) -> FileObject:
+        """Retrieve information about a specific file.
+
+        Parameters
+        ----------
+        file_id : str
+            The ID of the file to retrieve.
+
+        Returns
+        -------
+        FileObject
+            Information about the file.
+
+        Examples
+        --------
+        >>> file_info = manager.retrieve("file-abc123")
+        >>> print(f"Filename: {file_info.filename}")
+        >>> print(f"Size: {file_info.bytes} bytes")
+        """
+        return self._client.files.retrieve(file_id)
+
+    def list(
+        self,
+        purpose: FilePurpose | None = None,
+        limit: int | None = None,
+    ) -> SyncCursorPage[FileObject]:
+        """List files, optionally filtered by purpose.
+
+        Parameters
+        ----------
+        purpose : FilePurpose or None, default None
+            Filter files by purpose. If None, returns all files.
+        limit : int or None, default None
+            Maximum number of files to return. If None, returns all.
+
+        Returns
+        -------
+        SyncCursorPage[FileObject]
+            Page of file objects matching the criteria.
+
+        Examples
+        --------
+        >>> # List all files
+        >>> all_files = manager.list()
+        >>>
+        >>> # List user data files
+        >>> user_files = manager.list(purpose="user_data")
+        >>>
+        >>> # List up to 10 files
+        >>> recent_files = manager.list(limit=10)
+        """
+        limit_param = NOT_GIVEN if limit is None else limit
+        if purpose is not None:
+            return self._client.files.list(
+                purpose=purpose, limit=cast(Any, limit_param)
+            )
+        return self._client.files.list(limit=cast(Any, limit_param))
+
+    def delete(self, file_id: str, untrack: bool = True) -> FileDeleted:
+        """Delete a specific file from OpenAI Files API.
+
+        Parameters
+        ----------
+        file_id : str
+            The ID of the file to delete.
+        untrack : bool, default True
+            Remove from tracked files after deletion.
+
+        Returns
+        -------
+        FileDeleted
+            Confirmation of file deletion.
+
+        Examples
+        --------
+        >>> result = manager.delete("file-abc123")
+        >>> print(f"Deleted: {result.deleted}")
+        """
+        result = self._client.files.delete(file_id)
+
+        if untrack and file_id in self.tracked_files:
+            del self.tracked_files[file_id]
+            log(f"Deleted and untracked file {file_id}")
+        else:
+            log(f"Deleted file {file_id}")
+
+        return result
+
+    def retrieve_content(self, file_id: str) -> bytes:
+        """Download and retrieve the content of a file.
+
+        Parameters
+        ----------
+        file_id : str
+            The ID of the file to download.
+
+        Returns
+        -------
+        bytes
+            The raw bytes of the file content.
+
+        Examples
+        --------
+        >>> content = manager.retrieve_content("file-abc123")
+        >>> with open("downloaded.pdf", "wb") as f:
+        ...     f.write(content)
+        """
+        return self._client.files.content(file_id).read()
+
+    def cleanup(self) -> dict[str, bool]:
+        """Delete all tracked files.
+
+        Returns
+        -------
+        dict[str, bool]
+            Dictionary mapping file IDs to deletion success status.
+
+        Examples
+        --------
+        >>> results = manager.cleanup()
+        >>> print(f"Deleted {sum(results.values())} files")
+        """
+        results = {}
+        file_ids = list(self.tracked_files.keys())
+
+        for file_id in file_ids:
+            try:
+                self.delete(file_id, untrack=True)
+                results[file_id] = True
+            except Exception as exc:
+                log(
+                    f"Error deleting tracked file {file_id}: {exc}",
+                    level=logging.WARNING,
+                )
+                results[file_id] = False
+
+        if results:
+            successful = sum(results.values())
+            log(f"Cleanup complete: {successful}/{len(results)} files deleted")
+        else:
+            log("No tracked files to clean up")
+
+        return results
+
+    def __enter__(self) -> FilesAPIManager:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit with automatic cleanup."""
+        self.cleanup()
+
+    def __len__(self) -> int:
+        """Return number of tracked files."""
+        return len(self.tracked_files)
+
+    def __repr__(self) -> str:
+        """Return string representation of the manager."""
+        return f"FilesAPIManager(tracked_files={len(self.tracked_files)})"
+
+
+__all__ = ["FilesAPIManager", "FilePurpose"]