codex-open-client 0.1.0__tar.gz

codex_open_client-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv run ruff check src/ tests/
+      - run: uv run mypy src/codex_open_client/ tests/ --strict
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv run pytest -x -q

codex_open_client-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,104 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv run ruff check src/ tests/
+      - run: uv run mypy src/codex_open_client/ tests/ --strict
+      - run: uv run pytest -x -q
+
+  check-version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Verify tag matches package version
+        run: |
+          TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+          PKG_VERSION=$(grep '__version__' src/codex_open_client/_version.py | sed "s/.*\"\(.*\)\"/\1/")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag version ($TAG_VERSION) does not match package version ($PKG_VERSION)"
+            exit 1
+          fi
+          echo "Version: $TAG_VERSION"
+
+  publish:
+    needs: [test, check-version]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  docs:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Deploy docs
+        run: |
+          TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+
+          # Extract major.minor for the doc version alias
+          MINOR_VERSION=$(echo "$TAG_VERSION" | grep -oP '^\d+\.\d+')
+
+          # Check if this is a pre-release (alpha/beta/rc)
+          if echo "$TAG_VERSION" | grep -qP '(a|b|rc)\d+'; then
+            # Pre-release: deploy under "X.Y-beta", no alias update
+            uv run mike deploy "${MINOR_VERSION}-beta" --push
+          else
+            # Stable: deploy under "X.Y" and update "latest" alias
+            uv run mike deploy "${MINOR_VERSION}" latest --update-aliases --push
+            uv run mike set-default latest --push
+          fi
+
+  github-release:
+    needs: [publish, docs]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create GitHub Release
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          VERSION="${TAG#v}"
+
+          if echo "$VERSION" | grep -qP '(a|b|rc)\d+'; then
+            PRERELEASE="--prerelease"
+            TITLE="codex-open-client $VERSION (pre-release)"
+          else
+            PRERELEASE=""
+            TITLE="codex-open-client $VERSION"
+          fi
+
+          gh release create "$TAG" \
+            --title "$TITLE" \
+            --generate-notes \
+            $PRERELEASE
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

codex_open_client-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+site/

codex_open_client-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- OAuth 2.0 PKCE authentication with token caching and refresh
+- Three login modes: browser, headless, custom handler
+- Two-step login flow (`start_login` / `finish_login`)
+- `CodexClient` with typed `responses.create()` and `models.list()`
+- Streaming support via `ResponseStream` (SSE parsing, context manager)
+- Function tool calls with roundtrip support
+- Typed dataclasses for all API objects
+- Exception hierarchy with automatic retry on 429/5xx
+- Interop with Codex CLI token storage (`~/.codex/auth.json`)

codex_open_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yegor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codex_open_client-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: codex-open-client
+Version: 0.1.0
+Summary: Python client for OpenAI Codex — use your ChatGPT subscription for API access
+Project-URL: Homepage, https://github.com/lunavod/codex-py
+Project-URL: Documentation, https://lunavod.github.io/codex-py/
+Project-URL: Repository, https://github.com/lunavod/codex-py
+Project-URL: Issues, https://github.com/lunavod/codex-py/issues
+Project-URL: Changelog, https://github.com/lunavod/codex-py/blob/main/CHANGELOG.md
+Author: Yegor
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,chatgpt,codex,oauth,openai,pkce
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# codex-open-client
+
+[![PyPI](https://img.shields.io/pypi/v/codex-open-client)](https://pypi.org/project/codex-open-client/)
+[![Python](https://img.shields.io/pypi/pyversions/codex-open-client)](https://pypi.org/project/codex-open-client/)
+[![License](https://img.shields.io/github/license/lunavod/codex-open-client)](LICENSE)
+[![CI](https://github.com/lunavod/codex-open-client/actions/workflows/ci.yml/badge.svg)](https://github.com/lunavod/codex-open-client/actions/workflows/ci.yml)
+
+Python client for OpenAI Codex — use your ChatGPT Plus/Pro subscription for API access.
+
+**[Documentation](https://lunavod.github.io/codex-open-client/)**
+
+## Installation
+
+```bash
+pip install codex-open-client
+```
+
+## Quick Start
+
+```python
+import codex_open_client
+
+client = codex_open_client.CodexClient()
+
+response = client.responses.create(
+    model="gpt-5.1-codex-mini",
+    instructions="Be brief.",
+    input="What is 2 + 2?",
+)
+print(response.output_text)
+```
+
+On first run, your browser opens for OAuth login. Tokens are cached at `~/.codex/auth.json` (shared with the official Codex CLI) and refreshed automatically after that.
+
+## Authentication
+
+Multiple ways to authenticate, depending on your environment:
+
+```python
+# Default — opens browser, local server catches the callback
+client = codex_open_client.CodexClient()
+
+# Headless — prints URL, you paste the redirect URL back (servers, Docker, CI)
+client = codex_open_client.CodexClient(headless=True)
+
+# Custom handler — full control over the auth UX (GUI apps, bots, web apps)
+def my_handler(url: str) -> str:
+    send_url_to_user(url)
+    return get_callback_url_from_user()
+
+client = codex_open_client.CodexClient(login_handler=my_handler)
+```
+
+For async or multi-step flows, use the two-step API:
+
+```python
+auth = codex_open_client.start_login()
+# present auth.url to the user, collect callback URL however you want
+tokens = codex_open_client.finish_login(auth, callback_url="http://localhost:1455/...")
+```
+
+## Streaming
+
+```python
+with client.responses.create(
+    model="gpt-5.1-codex-mini",
+    instructions="Be helpful.",
+    input="Write a haiku about Python.",
+    stream=True,
+) as stream:
+    for event in stream:
+        if isinstance(event, codex_open_client.ResponseOutputTextDeltaEvent):
+            print(event.delta, end="", flush=True)
+    print()
+```
+
+## Tool Calls
+
+```python
+import json
+
+tool = codex_open_client.FunctionTool(
+    name="get_weather",
+    description="Get weather for a city.",
+    parameters={
+        "type": "object",
+        "properties": {"city": {"type": "string"}},
+        "required": ["city"],
+        "additionalProperties": False,
+    },
+)
+
+response = client.responses.create(
+    model="gpt-5.1-codex-mini",
+    instructions="Use tools when helpful.",
+    input="What's the weather in Tokyo?",
+    tools=[tool],
+)
+
+for call in response.tool_calls:
+    print(f"{call.name}({call.arguments})")
+```
+
+## Features
+
+- **Automatic auth** — OAuth PKCE with token caching and refresh
+- **Typed API** — dataclass-based types for all objects, full mypy strict support
+- **Streaming** — iterate SSE events with context manager support
+- **Tool calls** — function calling with roundtrip helpers
+- **Retries** — built-in exponential backoff for 429/5xx
+- **Models** — list available models with cached metadata
+- **Headless mode** — works on remote servers, Docker, CI
+- **Custom login** — bring your own auth UX with `login_handler`
+- **CLI interop** — shares token storage with the official Codex CLI
+
+## Requirements
+
+- Python 3.10+
+- ChatGPT Plus or Pro subscription
+
+## License
+
+MIT

codex_open_client-0.1.0/README.md

@@ -0,0 +1,123 @@
+# codex-open-client
+
+[![PyPI](https://img.shields.io/pypi/v/codex-open-client)](https://pypi.org/project/codex-open-client/)
+[![Python](https://img.shields.io/pypi/pyversions/codex-open-client)](https://pypi.org/project/codex-open-client/)
+[![License](https://img.shields.io/github/license/lunavod/codex-open-client)](LICENSE)
+[![CI](https://github.com/lunavod/codex-open-client/actions/workflows/ci.yml/badge.svg)](https://github.com/lunavod/codex-open-client/actions/workflows/ci.yml)
+
+Python client for OpenAI Codex — use your ChatGPT Plus/Pro subscription for API access.
+
+**[Documentation](https://lunavod.github.io/codex-open-client/)**
+
+## Installation
+
+```bash
+pip install codex-open-client
+```
+
+## Quick Start
+
+```python
+import codex_open_client
+
+client = codex_open_client.CodexClient()
+
+response = client.responses.create(
+    model="gpt-5.1-codex-mini",
+    instructions="Be brief.",
+    input="What is 2 + 2?",
+)
+print(response.output_text)
+```
+
+On first run, your browser opens for OAuth login. Tokens are cached at `~/.codex/auth.json` (shared with the official Codex CLI) and refreshed automatically after that.
+
+## Authentication
+
+Multiple ways to authenticate, depending on your environment:
+
+```python
+# Default — opens browser, local server catches the callback
+client = codex_open_client.CodexClient()
+
+# Headless — prints URL, you paste the redirect URL back (servers, Docker, CI)
+client = codex_open_client.CodexClient(headless=True)
+
+# Custom handler — full control over the auth UX (GUI apps, bots, web apps)
+def my_handler(url: str) -> str:
+    send_url_to_user(url)
+    return get_callback_url_from_user()
+
+client = codex_open_client.CodexClient(login_handler=my_handler)
+```
+
+For async or multi-step flows, use the two-step API:
+
+```python
+auth = codex_open_client.start_login()
+# present auth.url to the user, collect callback URL however you want
+tokens = codex_open_client.finish_login(auth, callback_url="http://localhost:1455/...")
+```
+
+## Streaming
+
+```python
+with client.responses.create(
+    model="gpt-5.1-codex-mini",
+    instructions="Be helpful.",
+    input="Write a haiku about Python.",
+    stream=True,
+) as stream:
+    for event in stream:
+        if isinstance(event, codex_open_client.ResponseOutputTextDeltaEvent):
+            print(event.delta, end="", flush=True)
+    print()
+```
+
+## Tool Calls
+
+```python
+import json
+
+tool = codex_open_client.FunctionTool(
+    name="get_weather",
+    description="Get weather for a city.",
+    parameters={
+        "type": "object",
+        "properties": {"city": {"type": "string"}},
+        "required": ["city"],
+        "additionalProperties": False,
+    },
+)
+
+response = client.responses.create(
+    model="gpt-5.1-codex-mini",
+    instructions="Use tools when helpful.",
+    input="What's the weather in Tokyo?",
+    tools=[tool],
+)
+
+for call in response.tool_calls:
+    print(f"{call.name}({call.arguments})")
+```
+
+## Features
+
+- **Automatic auth** — OAuth PKCE with token caching and refresh
+- **Typed API** — dataclass-based types for all objects, full mypy strict support
+- **Streaming** — iterate SSE events with context manager support
+- **Tool calls** — function calling with roundtrip helpers
+- **Retries** — built-in exponential backoff for 429/5xx
+- **Models** — list available models with cached metadata
+- **Headless mode** — works on remote servers, Docker, CI
+- **Custom login** — bring your own auth UX with `login_handler`
+- **CLI interop** — shares token storage with the official Codex CLI
+
+## Requirements
+
+- Python 3.10+
+- ChatGPT Plus or Pro subscription
+
+## License
+
+MIT

codex_open_client-0.1.0/docs/api/client.md

@@ -0,0 +1,72 @@
+# CodexClient
+
+The main entry point for the Codex API.
+
+::: codex_open_client.CodexClient
+    options:
+      members:
+        - __init__
+        - login
+        - token
+        - account_id
+
+## Responses
+
+::: codex_open_client._responses.Responses
+    options:
+      members:
+        - create
+
+## ResponseStream
+
+::: codex_open_client._stream.ResponseStream
+    options:
+      members:
+        - __iter__
+        - get_final_response
+        - close
+        - __enter__
+        - __exit__
+
+## Models
+
+::: codex_open_client._models.Models
+    options:
+      members:
+        - list
+
+## Authentication Functions
+
+### login
+
+::: codex_open_client.login
+
+### get_token
+
+::: codex_open_client.get_token
+
+### refresh
+
+::: codex_open_client.refresh
+
+### start_login
+
+::: codex_open_client.start_login
+
+### finish_login
+
+::: codex_open_client.finish_login
+
+### PendingLogin
+
+::: codex_open_client.PendingLogin
+
+## Helper Functions
+
+### build_headers
+
+::: codex_open_client.build_headers
+
+### get_account_id
+
+::: codex_open_client.get_account_id

codex_open_client-0.1.0/docs/api/errors.md

@@ -0,0 +1,47 @@
+# Errors
+
+## Hierarchy
+
+```
+CodexError
+├── APIError
+│   ├── AuthError
+│   ├── RateLimitError
+│   ├── InvalidRequestError
+│   │   └── ContextWindowError
+│   ├── QuotaExceededError
+│   └── ServerError
+├── APIConnectionError
+│   └── APITimeoutError
+└── StreamError
+```
+
+## Base Classes
+
+::: codex_open_client.CodexError
+
+::: codex_open_client.APIError
+
+::: codex_open_client.APIConnectionError
+
+## API Errors
+
+::: codex_open_client.AuthError
+
+::: codex_open_client.RateLimitError
+
+::: codex_open_client.InvalidRequestError
+
+::: codex_open_client.ContextWindowError
+
+::: codex_open_client.QuotaExceededError
+
+::: codex_open_client.ServerError
+
+## Connection Errors
+
+::: codex_open_client.APITimeoutError
+
+## Stream Errors
+
+::: codex_open_client.StreamError

codex_open_client-0.1.0/docs/api/stream-events.md

@@ -0,0 +1,41 @@
+# Stream Events
+
+All stream events are dataclasses with a `type` field matching the SSE event name.
+
+Use `isinstance()` checks to handle specific event types when iterating a `ResponseStream`.
+
+## Response Lifecycle Events
+
+::: codex_open_client.ResponseCreatedEvent
+
+::: codex_open_client.ResponseInProgressEvent
+
+::: codex_open_client.ResponseCompletedEvent
+
+::: codex_open_client.ResponseFailedEvent
+
+::: codex_open_client.ResponseIncompleteEvent
+
+## Text Events
+
+::: codex_open_client.ResponseOutputTextDeltaEvent
+
+::: codex_open_client.ResponseOutputTextDoneEvent
+
+## Output Item Events
+
+::: codex_open_client.ResponseOutputItemAddedEvent
+
+::: codex_open_client.ResponseOutputItemDoneEvent
+
+## Function Call Events
+
+::: codex_open_client.ResponseFunctionCallArgumentsDeltaEvent
+
+::: codex_open_client.ResponseFunctionCallArgumentsDoneEvent
+
+## Reasoning Events
+
+::: codex_open_client.ResponseReasoningSummaryTextDeltaEvent
+
+::: codex_open_client.ResponseReasoningSummaryTextDoneEvent

codex_open_client-0.1.0/docs/api/types.md

@@ -0,0 +1,50 @@
+# Types
+
+All types are dataclasses with `slots=True`.
+
+## Response
+
+::: codex_open_client.Response
+    options:
+      members:
+        - output_text
+        - reasoning_summary
+        - tool_calls
+
+::: codex_open_client.Usage
+
+::: codex_open_client.ResponseError
+
+## Output Types
+
+::: codex_open_client.ResponseOutputMessage
+
+::: codex_open_client.OutputText
+
+::: codex_open_client.ResponseFunctionToolCall
+
+::: codex_open_client.ResponseReasoningItem
+
+::: codex_open_client.ReasoningSummary
+
+## Input Types
+
+::: codex_open_client.InputMessage
+
+::: codex_open_client.InputText
+
+::: codex_open_client.InputImage
+
+::: codex_open_client.FunctionCallOutput
+
+## Tools & Config
+
+::: codex_open_client.FunctionTool
+
+::: codex_open_client.Reasoning
+
+::: codex_open_client.TextConfig
+
+## Model
+
+::: codex_open_client.Model