oauth-codex 2.3.0__tar.gz → 2.3.1__tar.gz

{oauth_codex-2.3.0 → oauth_codex-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oauth-codex
-Version: 2.3.0
+Version: 2.3.1
 Summary: Codex OAuth-based Python SDK with a single Client and generate-first API
 Author: Codex
 Requires-Python: >=3.11
@@ -41,6 +41,12 @@ text = client.generate([{"role": "user", "content": "hello"}])
 print(text)
 ```
 
+Authenticate immediately during client construction:
+
+```python
+client = Client(authenticate_on_init=True)
+```
+
 ## Image Input
 
 ```python

{oauth_codex-2.3.0 → oauth_codex-2.3.1}/README.md

@@ -27,6 +27,12 @@ text = client.generate([{"role": "user", "content": "hello"}])
 print(text)
 ```
 
+Authenticate immediately during client construction:
+
+```python
+client = Client(authenticate_on_init=True)
+```
+
 ## Image Input
 
 ```python

{oauth_codex-2.3.0 → oauth_codex-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "oauth-codex"
-version = "2.3.0"
+version = "2.3.1"
 description = "Codex OAuth-based Python SDK with a single Client and generate-first API"
 readme = "README.md"
 requires-python = ">=3.11"

{oauth_codex-2.3.0 → oauth_codex-2.3.1}/src/oauth_codex/_client.py

@@ -26,6 +26,29 @@ StructuredOutputSchema = type[BaseModel] | dict[str, Any]
 
 
 class OAuthCodexClient(SyncAPIClient):
+    """Public single-entry client for oauth-codex.
+
+    This client wraps the OAuth-backed responses engine and exposes a
+    generate-first workflow:
+
+    - `generate` and `agenerate` return final text, or a validated JSON object
+      when `output_schema` is provided.
+    - `stream` and `astream` yield text deltas while still supporting
+      automatic tool-call continuation rounds.
+
+    Public attributes:
+        default_model: Model used when `model` is omitted. Defaults to
+            `"gpt-5.3-codex"`.
+        max_tool_rounds: Maximum number of automatic tool continuation rounds
+            before raising `RuntimeError`.
+
+    Example:
+        from oauth_codex import Client
+
+        client = Client(authenticate_on_init=True)
+        text = client.generate([{"role": "user", "content": "hello"}])
+    """
+
     def __init__(
         self,
         *,
@@ -40,7 +63,28 @@ class OAuthCodexClient(SyncAPIClient):
         on_request_end: Any | None = None,
         on_auth_refresh: Any | None = None,
         on_error: Any | None = None,
+        authenticate_on_init: bool = False,
     ) -> None:
+        """Create a `Client` instance.
+
+        Args:
+            oauth_config: Optional OAuth endpoint/client configuration.
+            token_store: Token persistence backend. If omitted, a fallback
+                keyring/file store is used.
+            base_url: Base URL for Codex backend requests.
+            chatgpt_base_url: Legacy alias for `base_url`. `base_url` takes
+                precedence when both are provided.
+            timeout: Request timeout in seconds.
+            max_retries: Number of retry attempts for retryable failures.
+            compat_storage_dir: Optional local compatibility storage path.
+            on_request_start: Optional callback invoked when a request starts.
+            on_request_end: Optional callback invoked when a request ends.
+            on_auth_refresh: Optional callback invoked after token refresh.
+            on_error: Optional callback invoked when request/auth errors occur.
+            authenticate_on_init: When `True`, perform authentication during
+                client construction. If no stored token exists, interactive
+                login is started immediately.
+        """
         super().__init__()
 
         resolved_base_url = (
@@ -63,23 +107,76 @@ class OAuthCodexClient(SyncAPIClient):
         )
         self.default_model = DEFAULT_MODEL
         self.max_tool_rounds = DEFAULT_MAX_TOOL_ROUNDS
+        if authenticate_on_init:
+            self.authenticate()
 
     def is_authenticated(self) -> bool:
+        """Return whether usable OAuth tokens are currently available.
+
+        Returns:
+            `True` when a token is available, otherwise `False`.
+        """
         return self._engine.is_authenticated()
 
     def is_expired(self, *, leeway_seconds: int = 60) -> bool:
+        """Return whether the current token is expired or near expiry.
+
+        Args:
+            leeway_seconds: Safety margin in seconds added before expiry check.
+
+        Returns:
+            `True` if the token is expired within the given leeway.
+        """
         return self._engine.is_expired(leeway_seconds=leeway_seconds)
 
     def refresh_if_needed(self, *, force: bool = False) -> bool:
+        """Refresh tokens when needed.
+
+        Args:
+            force: Refresh even when token is not currently expired.
+
+        Returns:
+            `True` if refresh happened and succeeded, otherwise `False`.
+        """
         return self._engine.refresh_if_needed(force=force)
 
     async def arefresh_if_needed(self, *, force: bool = False) -> bool:
+        """Async version of `refresh_if_needed`.
+
+        Args:
+            force: Refresh even when token is not currently expired.
+
+        Returns:
+            `True` if refresh happened and succeeded, otherwise `False`.
+        """
         return await self._engine.arefresh_if_needed(force=force)
 
+    def authenticate(self) -> None:
+        """Ensure usable OAuth credentials are available now.
+
+        This loads stored credentials, starts interactive login when missing,
+        and refreshes tokens when expired.
+        """
+        self._engine._ensure_authenticated_sync()
+
     def login(self) -> None:
+        """Run interactive OAuth login flow in the current thread.
+
+        Raises:
+            OAuthCallbackParseError: If callback URL parsing fails.
+            OAuthStateMismatchError: If OAuth state verification fails.
+            TokenExchangeError: If code-to-token exchange fails.
+        """
         self._engine.login()
 
     async def alogin(self) -> None:
+        """Run interactive OAuth login flow without blocking the event loop.
+
+        Raises:
+            OAuthCallbackParseError: If callback URL parsing fails.
+            OAuthStateMismatchError: If OAuth state verification fails.
+            TokenExchangeError: If code-to-token exchange fails.
+        """
         await asyncio.to_thread(self._engine.login)
 
     def generate(
@@ -95,6 +192,53 @@ class OAuthCodexClient(SyncAPIClient):
         output_schema: StructuredOutputSchema | None = None,
         strict_output: bool | None = None,
     ) -> str | dict[str, Any]:
+        """Generate a final response with automatic tool execution.
+
+        Args:
+            messages: Non-empty list of response input messages.
+            tools: Optional list of Python callables used for automatic
+                function-calling rounds.
+            model: Optional model override. Uses `default_model` when omitted.
+            reasoning_effort: Reasoning intensity (`"low"`, `"medium"`,
+                `"high"`).
+            temperature: Sampling temperature.
+            top_p: Nucleus sampling probability.
+            max_output_tokens: Maximum generated output tokens.
+            output_schema: Optional structured-output schema. Accepts a
+                Pydantic model type or JSON schema dict.
+            strict_output: Strict schema mode. When `output_schema` is set and
+                `strict_output` is omitted, strict mode is enabled by default.
+
+        Returns:
+            Final text output, or a validated JSON object when `output_schema`
+            is provided.
+
+        Raises:
+            ValueError: If `messages` is missing/empty, or structured output is
+                not valid JSON.
+            TypeError: If `messages` is not a list, `tools` are invalid, or
+                structured output is not a JSON object.
+            RuntimeError: If automatic tool execution exceeds
+                `max_tool_rounds`.
+            pydantic.ValidationError: If a Pydantic `output_schema` fails
+                strict validation.
+
+        Examples:
+            Basic text generation:
+                text = client.generate([{"role": "user", "content": "hello"}])
+
+            Structured output:
+                from pydantic import BaseModel
+
+                class Summary(BaseModel):
+                    title: str
+                    score: int
+
+                data = client.generate(
+                    [{"role": "user", "content": "Return JSON"}],
+                    output_schema=Summary,
+                )
+        """
         messages = self._normalize_initial_messages(messages)
         normalized_tools, tools_by_name = self._normalize_tools(tools)
         response_format, effective_strict_output = self._resolve_structured_output_options(
@@ -155,6 +299,40 @@ class OAuthCodexClient(SyncAPIClient):
         output_schema: StructuredOutputSchema | None = None,
         strict_output: bool | None = None,
     ) -> str | dict[str, Any]:
+        """Async response generation with automatic tool execution.
+
+        Args:
+            messages: Non-empty list of response input messages.
+            tools: Optional list of Python callables used for automatic
+                function-calling rounds.
+            model: Optional model override. Uses `default_model` when omitted.
+            reasoning_effort: Reasoning intensity (`"low"`, `"medium"`,
+                `"high"`).
+            temperature: Sampling temperature.
+            top_p: Nucleus sampling probability.
+            max_output_tokens: Maximum generated output tokens.
+            output_schema: Optional structured-output schema. Accepts a
+                Pydantic model type or JSON schema dict.
+            strict_output: Strict schema mode. When `output_schema` is set and
+                `strict_output` is omitted, strict mode is enabled by default.
+
+        Returns:
+            Final text output, or a validated JSON object when `output_schema`
+            is provided.
+
+        Raises:
+            ValueError: If `messages` is missing/empty, or structured output is
+                not valid JSON.
+            TypeError: If `messages` is not a list, `tools` are invalid, or
+                structured output is not a JSON object.
+            RuntimeError: If automatic tool execution exceeds
+                `max_tool_rounds`.
+            pydantic.ValidationError: If a Pydantic `output_schema` fails
+                strict validation.
+
+        Examples:
+            text = await client.agenerate([{"role": "user", "content": "hello"}])
+        """
         messages = self._normalize_initial_messages(messages)
         normalized_tools, tools_by_name = self._normalize_tools(tools)
         response_format, effective_strict_output = self._resolve_structured_output_options(
@@ -215,6 +393,32 @@ class OAuthCodexClient(SyncAPIClient):
         output_schema: StructuredOutputSchema | None = None,
         strict_output: bool | None = None,
     ) -> Iterator[str]:
+        """Stream text deltas with automatic tool execution rounds.
+
+        Args:
+            messages: Non-empty list of response input messages.
+            tools: Optional list of Python callables used for automatic
+                function-calling rounds.
+            model: Optional model override. Uses `default_model` when omitted.
+            reasoning_effort: Reasoning intensity (`"low"`, `"medium"`,
+                `"high"`).
+            temperature: Sampling temperature.
+            top_p: Nucleus sampling probability.
+            max_output_tokens: Maximum generated output tokens.
+            output_schema: Optional structured-output schema forwarded to the
+                backend. Stream output is still text deltas only.
+            strict_output: Strict schema mode. When `output_schema` is set and
+                `strict_output` is omitted, strict mode is enabled by default.
+
+        Yields:
+            Text delta chunks as they arrive.
+
+        Raises:
+            ValueError: If `messages` is missing/empty.
+            TypeError: If `messages` is not a list or `tools` are invalid.
+            RuntimeError: If automatic tool execution exceeds
+                `max_tool_rounds`.
+        """
         messages = self._normalize_initial_messages(messages)
         normalized_tools, tools_by_name = self._normalize_tools(tools)
         response_format, effective_strict_output = self._resolve_structured_output_options(
@@ -275,6 +479,32 @@ class OAuthCodexClient(SyncAPIClient):
         output_schema: StructuredOutputSchema | None = None,
         strict_output: bool | None = None,
     ) -> AsyncIterator[str]:
+        """Async stream of text deltas with automatic tool execution rounds.
+
+        Args:
+            messages: Non-empty list of response input messages.
+            tools: Optional list of Python callables used for automatic
+                function-calling rounds.
+            model: Optional model override. Uses `default_model` when omitted.
+            reasoning_effort: Reasoning intensity (`"low"`, `"medium"`,
+                `"high"`).
+            temperature: Sampling temperature.
+            top_p: Nucleus sampling probability.
+            max_output_tokens: Maximum generated output tokens.
+            output_schema: Optional structured-output schema forwarded to the
+                backend. Stream output is still text deltas only.
+            strict_output: Strict schema mode. When `output_schema` is set and
+                `strict_output` is omitted, strict mode is enabled by default.
+
+        Yields:
+            Text delta chunks as they arrive.
+
+        Raises:
+            ValueError: If `messages` is missing/empty.
+            TypeError: If `messages` is not a list or `tools` are invalid.
+            RuntimeError: If automatic tool execution exceeds
+                `max_tool_rounds`.
+        """
         messages = self._normalize_initial_messages(messages)
         normalized_tools, tools_by_name = self._normalize_tools(tools)
         response_format, effective_strict_output = self._resolve_structured_output_options(

{oauth_codex-2.3.0 → oauth_codex-2.3.1}/src/oauth_codex/_exceptions.py

@@ -6,14 +6,29 @@ import httpx
 
 
 class OAuthCodexError(Exception):
+    """Base class for all public oauth-codex exceptions."""
+
     pass
 
 
 class OpenAIError(OAuthCodexError):
+    """Compatibility base error alias for OpenAI-style exception handling."""
+
     pass
 
 
 class APIError(OpenAIError):
+    """Base error for request/response failures returned by the API layer.
+
+    Attributes:
+        message: Human-readable error message.
+        request: Originating `httpx.Request` when available.
+        body: Raw parsed error body when available.
+        code: Provider error code extracted from `body` when present.
+        param: Provider parameter field extracted from `body` when present.
+        type: Provider error type extracted from `body` when present.
+    """
+
     def __init__(self, message: str, request: httpx.Request | None = None, *, body: object | None = None) -> None:
         super().__init__(message)
         self.message = message
@@ -32,6 +47,14 @@ class APIError(OpenAIError):
 
 
 class APIStatusError(APIError):
+    """HTTP status error with access to response metadata.
+
+    Attributes:
+        response: Full `httpx.Response`.
+        status_code: HTTP status code from the response.
+        request_id: Request identifier from `x-request-id` header when present.
+    """
+
     def __init__(self, message: str, *, response: httpx.Response, body: object | None = None) -> None:
         super().__init__(message, response.request, body=body)
         self.response = response
@@ -40,48 +63,70 @@ class APIStatusError(APIError):
 
 
 class APIConnectionError(APIError):
+    """Network-level connection failure while talking to the API."""
+
     def __init__(self, *, message: str = "Connection error.", request: httpx.Request | None = None) -> None:
         super().__init__(message, request, body=None)
 
 
 class APITimeoutError(APIConnectionError):
+    """Request timeout while waiting for API response."""
+
     def __init__(self, request: httpx.Request | None = None) -> None:
         super().__init__(message="Request timed out.", request=request)
 
 
 class BadRequestError(APIStatusError):
+    """HTTP 400 response from the API."""
+
     pass
 
 
 class AuthenticationError(APIStatusError):
+    """HTTP 401 response from the API."""
+
     pass
 
 
 class PermissionDeniedError(APIStatusError):
+    """HTTP 403 response from the API."""
+
     pass
 
 
 class NotFoundError(APIStatusError):
+    """HTTP 404 response from the API."""
+
     pass
 
 
 class ConflictError(APIStatusError):
+    """HTTP 409 response from the API."""
+
     pass
 
 
 class UnprocessableEntityError(APIStatusError):
+    """HTTP 422 response from the API."""
+
     pass
 
 
 class RateLimitError(APIStatusError):
+    """HTTP 429 response from the API."""
+
     pass
 
 
 class InternalServerError(APIStatusError):
+    """HTTP 5xx server error returned by the API."""
+
     pass
 
 
 class APIResponseValidationError(APIError):
+    """API response payload failed SDK-side schema validation."""
+
     def __init__(self, response: httpx.Response, body: object | None, *, message: str | None = None) -> None:
         super().__init__(message or "Data returned by API invalid for expected schema.", response.request, body=body)
         self.response = response
@@ -89,56 +134,95 @@ class APIResponseValidationError(APIError):
 
 
 class OAuthCallbackParseError(OAuthCodexError):
+    """OAuth browser callback could not be parsed."""
+
     pass
 
 
 class OAuthStateMismatchError(OAuthCodexError):
+    """OAuth callback state does not match the initiated login request."""
+
     pass
 
 
 class TokenExchangeError(OAuthCodexError):
+    """OAuth authorization code exchange for tokens failed."""
+
     pass
 
 
 class TokenRefreshError(OAuthCodexError):
+    """Refreshing an existing OAuth token failed."""
+
     pass
 
 
 class AuthRequiredError(OAuthCodexError):
+    """Authenticated call was attempted without valid credentials."""
+
     pass
 
 
 class ParameterValidationError(OAuthCodexError):
+    """Input parameters failed SDK validation before sending request."""
+
     pass
 
 
 class ModelValidationError(OAuthCodexError):
+    """Model capability or model name validation failed."""
+
     pass
 
 
 class ContinuityError(OAuthCodexError):
+    """Response continuity state is invalid for continuation requests."""
+
     pass
 
 
 class TokenStoreError(OAuthCodexError):
+    """Base class for token persistence layer failures.
+
+    Attributes:
+        cause: Original exception raised by the storage backend, when present.
+    """
+
     def __init__(self, message: str, *, cause: Exception | None = None) -> None:
         super().__init__(message)
         self.cause = cause
 
 
 class TokenStoreReadError(TokenStoreError):
+    """Token load/read operation failed."""
+
     pass
 
 
 class TokenStoreWriteError(TokenStoreError):
+    """Token save/write operation failed."""
+
     pass
 
 
 class TokenStoreDeleteError(TokenStoreError):
+    """Token delete operation failed."""
+
     pass
 
 
 class SDKRequestError(OAuthCodexError):
+    """Normalized SDK error for provider and compatibility request failures.
+
+    Attributes:
+        status_code: HTTP-like status code when available.
+        provider_code: Provider-specific machine-readable error code.
+        user_message: Human-readable message intended for callers.
+        retryable: Whether the request may succeed on retry.
+        request_id: Provider request identifier when available.
+        raw_error: Original provider payload or underlying exception data.
+    """
+
     def __init__(
         self,
         *,
@@ -159,6 +243,8 @@ class SDKRequestError(OAuthCodexError):
 
 
 class NotSupportedError(SDKRequestError):
+    """Requested operation is not supported by the active backend/profile."""
+
     def __init__(self, message: str, *, code: str = "not_supported") -> None:
         super().__init__(
             status_code=400,
@@ -170,6 +256,13 @@ class NotSupportedError(SDKRequestError):
 
 
 class ToolCallRequiredError(OAuthCodexError):
+    """Model response requires tool execution before completion.
+
+    Attributes:
+        message: Human-readable explanation for the tool requirement.
+        tool_calls: Tool call payloads that must be executed.
+    """
+
     def __init__(self, message: str, tool_calls: list[dict[str, Any]] | None = None) -> None:
         super().__init__(message)
         self.message = message

{oauth_codex-2.3.0 → oauth_codex-2.3.1}/src/oauth_codex/core_types.py

@@ -1,10 +1,26 @@
+"""Core public data types used by oauth-codex.
+
+`Message` represents a single response input message dictionary, and
+`listMessage` is the list container passed to `Client.generate`,
+`Client.stream`, `Client.agenerate`, and `Client.astream`.
+
+Recommended minimal message shape:
+
+    [{"role": "user", "content": "hello"}]
+
+`content` may also be a list of input items such as `input_text` and
+`input_image`.
+"""
+
 from __future__ import annotations
 
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Callable, Literal, Protocol, TypeAlias
 
+#: A single response input message item (for example role/content dict).
 Message: TypeAlias = dict[str, Any]
+#: List of response input messages accepted by `Client` generation methods.
 listMessage: TypeAlias = list[Message]
 ValidationMode: TypeAlias = Literal["warn", "error", "ignore"]
 StoreBehavior: TypeAlias = Literal["auto_disable", "error", "passthrough"]

{oauth_codex-2.3.0 → oauth_codex-2.3.1}/src/oauth_codex.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oauth-codex
-Version: 2.3.0
+Version: 2.3.1
 Summary: Codex OAuth-based Python SDK with a single Client and generate-first API
 Author: Codex
 Requires-Python: >=3.11
@@ -41,6 +41,12 @@ text = client.generate([{"role": "user", "content": "hello"}])
 print(text)
 ```
 
+Authenticate immediately during client construction:
+
+```python
+client = Client(authenticate_on_init=True)
+```
+
 ## Image Input
 
 ```python

{oauth_codex-2.3.0 → oauth_codex-2.3.1}/src/oauth_codex.egg-info/SOURCES.txt

@@ -55,8 +55,10 @@ src/oauth_codex/types/vector_stores/vector_store_deleted.py
 src/oauth_codex/types/vector_stores/vector_store_file.py
 src/oauth_codex/types/vector_stores/vector_store_file_batch.py
 src/oauth_codex/types/vector_stores/vector_store_search_response.py
+tests/test_client_authentication.py
 tests/test_engine_stream_and_continuity.py
 tests/test_generate_async.py
 tests/test_generate_sync.py
+tests/test_public_api_docstrings.py
 tests/test_public_surface.py
 tests/test_tooling_strict_schema.py

oauth_codex-2.3.1/tests/test_client_authentication.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import pytest
+
+from conftest import InMemoryTokenStore
+from oauth_codex import Client
+from oauth_codex._client import _EngineClient
+from oauth_codex.core_types import OAuthTokens
+
+
+def _tokens() -> OAuthTokens:
+    return OAuthTokens(access_token="a", refresh_token="r", expires_at=9_999_999_999)
+
+
+def test_client_does_not_authenticate_on_init_by_default(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    ensure_calls = 0
+
+    def fake_ensure(self: _EngineClient) -> OAuthTokens:
+        nonlocal ensure_calls
+        ensure_calls += 1
+        return _tokens()
+
+    monkeypatch.setattr(_EngineClient, "_ensure_authenticated_sync", fake_ensure)
+
+    Client(token_store=InMemoryTokenStore(_tokens()))
+
+    assert ensure_calls == 0
+
+
+def test_client_authenticates_on_init_when_enabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    ensure_calls = 0
+
+    def fake_ensure(self: _EngineClient) -> OAuthTokens:
+        nonlocal ensure_calls
+        ensure_calls += 1
+        return _tokens()
+
+    monkeypatch.setattr(_EngineClient, "_ensure_authenticated_sync", fake_ensure)
+
+    Client(token_store=InMemoryTokenStore(), authenticate_on_init=True)
+
+    assert ensure_calls == 1

oauth_codex-2.3.1/tests/test_public_api_docstrings.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import inspect
+
+import oauth_codex
+import oauth_codex.core_types as core_types
+
+
+def test_client_class_docstring_exists() -> None:
+    doc = inspect.getdoc(oauth_codex.Client)
+    assert doc is not None
+    assert "default_model" in doc
+    assert "max_tool_rounds" in doc
+
+
+def test_generate_docstring_includes_key_sections() -> None:
+    doc = inspect.getdoc(oauth_codex.Client.generate)
+    assert doc is not None
+    for keyword in ("messages", "tools", "output_schema", "Returns", "Raises"):
+        assert keyword in doc
+
+
+def test_agenerate_docstring_includes_key_sections() -> None:
+    doc = inspect.getdoc(oauth_codex.Client.agenerate)
+    assert doc is not None
+    for keyword in ("messages", "tools", "output_schema", "Returns", "Raises"):
+        assert keyword in doc
+
+
+def test_stream_docstring_includes_streaming_context() -> None:
+    doc = inspect.getdoc(oauth_codex.Client.stream)
+    assert doc is not None
+    for keyword in ("messages", "tools", "output_schema", "Yields", "Raises"):
+        assert keyword in doc
+
+
+def test_root_exported_exceptions_have_docstrings() -> None:
+    for name in oauth_codex.__all__:
+        exported = getattr(oauth_codex, name)
+        if inspect.isclass(exported) and issubclass(exported, Exception):
+            assert inspect.getdoc(exported), f"missing docstring for {name}"
+
+
+def test_core_types_module_doc_mentions_list_message() -> None:
+    doc = inspect.getdoc(core_types)
+    assert doc is not None
+    assert "Message" in doc
+    assert "listMessage" in doc