pydantic-claude-code 0.1.0__tar.gz → 0.2.0__tar.gz

{pydantic_claude_code-0.1.0 → pydantic_claude_code-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pydantic-claude-code
-Version: 0.1.0
+Version: 0.2.0
 Summary: Use your Claude Code subscription from a Pydantic AI Agent, with full tool support
 Project-URL: Repository, https://github.com/mpfaffenberger/pydantic-ai-claude-code
 Project-URL: Homepage, https://pypi.org/project/pydantic-claude-code/
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: <3.15,>=3.11
+Requires-Dist: keyring<26,>=23
 Requires-Dist: pydantic-ai-slim[anthropic]<3,>=2.31.0
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.23.1; extra == 'dev'
@@ -36,8 +37,8 @@ The repo is `mpfaffenberger/pydantic-ai-claude-code` and the import is
 pydantic-ai gained a Codex OAuth path where `openai-codex:gpt-6-astra` just
 works against a ChatGPT subscription. This wheel brings the same experience to
 Claude: authenticate once, then run pydantic-ai agents against your Claude
-subscription, using `claude-sonnet-4-5`, `claude-opus-5`, or whatever model you
-subscribe to.
+subscription, using `claude-fable-5-1`, `claude-sonnet-5`, `claude-opus-5`, or
+whatever model you subscribe to.
 
 Two deliberate design choices distinguish this from a fork of pydantic-ai:
 
@@ -64,7 +65,7 @@ async def main() -> None:
     await login()
 
     provider = ClaudeCodeProvider()  # loads the stored tokens
-    agent = Agent(provider.model('claude-sonnet-4-5'))
+    agent = Agent(provider.model('claude-fable-5-1'))
 
     result = await agent.run('Say hi in three words.')
     print(result.data)
@@ -78,7 +79,7 @@ asyncio.run(main())
 from pydantic_ai import Agent
 
 provider = ClaudeCodeProvider()
-agent = Agent(provider.model('claude-sonnet-4-5'))
+agent = Agent(provider.model('claude-fable-5-1'))
 
 @agent.tool_plain
 def add(a: int, b: int) -> int:
@@ -90,6 +91,32 @@ Tools defined on the agent are passed to the API as standard Anthropic tool
 definitions, and structured output works the same way as with the built-in
 `anthropic` provider. That's the whole point of the wheel.
 
+### Structured output
+
+```python
+from pydantic import BaseModel
+from pydantic_ai import Agent
+
+class Weather(BaseModel):
+    city: str
+    temperature_c: float
+
+agent = Agent(ClaudeCodeProvider().model('claude-fable-5-1'), output_type=Weather)
+result = await agent.run('Weather in Paris right now?')
+assert result.output.city == 'Paris'
+```
+
+### Streaming
+
+```python
+from pydantic_ai import Agent
+
+agent = Agent(ClaudeCodeProvider().model('claude-fable-5-1'))
+async with agent.run_stream('Count from 1 to 3.') as stream:
+    async for chunk in stream.stream_text():
+        print(chunk, end='', flush=True)
+```
+
 ## How auth works
 
 The flow uses the same shared OAuth client the Claude Code CLI uses:
@@ -98,14 +125,18 @@ The flow uses the same shared OAuth client the Claude Code CLI uses:
 - Token URL: `https://platform.claude.com/v1/oauth/token`
 - Scopes: `org:create_api_key user:profile user:inference`
 
-Tokens are stored in (overridable via `CLAUDE_CODE_AUTH_FILE`):
+Tokens are saved to the OS keyring by default: the Keychain on macOS, Credential
+Manager on Windows, and Secret Service on Linux. On machines without a keychain,
+credentials fall back to a JSON file (overridable via `CLAUDE_CODE_AUTH_FILE`):
 
 ```
 ~/.local/share/pydantic-ai-claude-code/auth.json
 ```
 
-The file is written with `0o600` permissions and only ever contains what the
-issuer gave us. We never read the CLI's own credential files.
+The fallback file is written with `0644` permissions and only ever contains what
+the issuer gave us. We never read the CLI's own credential files.
+
+Force a backend with the `CLAUDE_CODE_CREDENTIALS` env var: `keyring` or `file`.
 
 Refreshes happen automatically in the background: the auth shim refreshes
 before expiry and retries once on a 401, exactly like the codex provider does.

{pydantic_claude_code-0.1.0 → pydantic_claude_code-0.2.0}/README.md

@@ -13,8 +13,8 @@ The repo is `mpfaffenberger/pydantic-ai-claude-code` and the import is
 pydantic-ai gained a Codex OAuth path where `openai-codex:gpt-6-astra` just
 works against a ChatGPT subscription. This wheel brings the same experience to
 Claude: authenticate once, then run pydantic-ai agents against your Claude
-subscription, using `claude-sonnet-4-5`, `claude-opus-5`, or whatever model you
-subscribe to.
+subscription, using `claude-fable-5-1`, `claude-sonnet-5`, `claude-opus-5`, or
+whatever model you subscribe to.
 
 Two deliberate design choices distinguish this from a fork of pydantic-ai:
 
@@ -41,7 +41,7 @@ async def main() -> None:
     await login()
 
     provider = ClaudeCodeProvider()  # loads the stored tokens
-    agent = Agent(provider.model('claude-sonnet-4-5'))
+    agent = Agent(provider.model('claude-fable-5-1'))
 
     result = await agent.run('Say hi in three words.')
     print(result.data)
@@ -55,7 +55,7 @@ asyncio.run(main())
 from pydantic_ai import Agent
 
 provider = ClaudeCodeProvider()
-agent = Agent(provider.model('claude-sonnet-4-5'))
+agent = Agent(provider.model('claude-fable-5-1'))
 
 @agent.tool_plain
 def add(a: int, b: int) -> int:
@@ -67,6 +67,32 @@ Tools defined on the agent are passed to the API as standard Anthropic tool
 definitions, and structured output works the same way as with the built-in
 `anthropic` provider. That's the whole point of the wheel.
 
+### Structured output
+
+```python
+from pydantic import BaseModel
+from pydantic_ai import Agent
+
+class Weather(BaseModel):
+    city: str
+    temperature_c: float
+
+agent = Agent(ClaudeCodeProvider().model('claude-fable-5-1'), output_type=Weather)
+result = await agent.run('Weather in Paris right now?')
+assert result.output.city == 'Paris'
+```
+
+### Streaming
+
+```python
+from pydantic_ai import Agent
+
+agent = Agent(ClaudeCodeProvider().model('claude-fable-5-1'))
+async with agent.run_stream('Count from 1 to 3.') as stream:
+    async for chunk in stream.stream_text():
+        print(chunk, end='', flush=True)
+```
+
 ## How auth works
 
 The flow uses the same shared OAuth client the Claude Code CLI uses:
@@ -75,14 +101,18 @@ The flow uses the same shared OAuth client the Claude Code CLI uses:
 - Token URL: `https://platform.claude.com/v1/oauth/token`
 - Scopes: `org:create_api_key user:profile user:inference`
 
-Tokens are stored in (overridable via `CLAUDE_CODE_AUTH_FILE`):
+Tokens are saved to the OS keyring by default: the Keychain on macOS, Credential
+Manager on Windows, and Secret Service on Linux. On machines without a keychain,
+credentials fall back to a JSON file (overridable via `CLAUDE_CODE_AUTH_FILE`):
 
 ```
 ~/.local/share/pydantic-ai-claude-code/auth.json
 ```
 
-The file is written with `0o600` permissions and only ever contains what the
-issuer gave us. We never read the CLI's own credential files.
+The fallback file is written with `0644` permissions and only ever contains what
+the issuer gave us. We never read the CLI's own credential files.
+
+Force a backend with the `CLAUDE_CODE_CREDENTIALS` env var: `keyring` or `file`.
 
 Refreshes happen automatically in the background: the auth shim refreshes
 before expiry and retries once on a 401, exactly like the codex provider does.

{pydantic_claude_code-0.1.0 → pydantic_claude_code-0.2.0}/examples/basic.py

@@ -11,12 +11,12 @@ import asyncio
 
 from pydantic_ai import Agent
 
-from pydantic_ai_claude_code import ClaudeCodeProvider, ClaudeCodeTokenStore, login
+from pydantic_ai_claude_code import ClaudeCodeProvider, default_store, login
 
 
 async def main() -> None:
     # Only run the browser flow when no usable credentials are stored yet.
-    if ClaudeCodeTokenStore().load() is None:
+    if default_store().load() is None:
         await login()
 
     provider = ClaudeCodeProvider()

{pydantic_claude_code-0.1.0 → pydantic_claude_code-0.2.0}/pyproject.toml

@@ -4,11 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pydantic-claude-code"
-version = "0.1.0"
+version = "0.2.0"
 description = "Use your Claude Code subscription from a Pydantic AI Agent, with full tool support"
 readme = "README.md"
 requires-python = ">=3.11,<3.15"
 dependencies = [
+    "keyring>=23,<26",
     "pydantic-ai-slim[anthropic]>=2.31.0,<3",
 ]
 license = { text = "MIT" }

{pydantic_claude_code-0.1.0 → pydantic_claude_code-0.2.0}/src/pydantic_ai_claude_code/__init__.py

@@ -6,7 +6,7 @@ Quick start:
     from pydantic_ai_claude_code import ClaudeCodeProvider
 
     provider = ClaudeCodeProvider()
-    agent = Agent(provider.model('claude-sonnet-4-5'))
+    agent = Agent(provider.model('claude-fable-5-1'))
 """
 
 from .credentials import ClaudeCodeCredentials
@@ -19,7 +19,7 @@ from .flow import (
 )
 from .model import ClaudeCodeModel
 from .provider import ClaudeCodeProvider
-from .storage import ClaudeCodeTokenStore, default_auth_path
+from .storage import ClaudeCodeTokenStore, KeyringTokenStore, default_auth_path, default_store
 
 __all__ = [
     "ClaudeCodeCredentials",
@@ -27,7 +27,9 @@ __all__ = [
     "ClaudeCodeOAuthFlow",
     "ClaudeCodeProvider",
     "ClaudeCodeTokenStore",
+    "KeyringTokenStore",
     "default_auth_path",
+    "default_store",
     "exchange_code",
     "login",
     "parse_pasteback",

{pydantic_claude_code-0.1.0 → pydantic_claude_code-0.2.0}/src/pydantic_ai_claude_code/flow.py

@@ -184,10 +184,10 @@ async def login(*, store: Any = None) -> ClaudeCodeCredentials:
     Returns:
         The credentials that were persisted.
     """
-    from .storage import ClaudeCodeTokenStore
+    from .storage import default_store
 
     if store is None:
-        store = ClaudeCodeTokenStore()
+        store = default_store()
     server = start_login_callback_server()
     try:
         redirect_uri = f"{config.REDIRECT_HOST}:{server.server_address[1]}/{config.REDIRECT_PATH}"

{pydantic_claude_code-0.1.0 → pydantic_claude_code-0.2.0}/src/pydantic_ai_claude_code/provider.py

@@ -15,7 +15,7 @@ from . import config
 from .model import ClaudeCodeModel
 from .auth import _ClaudeCodeAuth
 from .credentials import ClaudeCodeCredentials
-from .storage import ClaudeCodeTokenStore
+from .storage import TokenStore, default_store
 
 
 class ClaudeCodeProvider(AnthropicProvider):
@@ -34,7 +34,7 @@ class ClaudeCodeProvider(AnthropicProvider):
         self,
         credentials: ClaudeCodeCredentials | None = None,
         *,
-        store: ClaudeCodeTokenStore | None = None,
+        store: TokenStore | None = None,
         on_credentials_refresh: Any = None,
         http_client: httpx2.AsyncClient | None = None,
         base_url: str | None = None,
@@ -43,7 +43,7 @@ class ClaudeCodeProvider(AnthropicProvider):
 
         Args:
             credentials: Credentials to use. When omitted, they are loaded from
-                the store (which defaults to the standard token file).
+                the store (which defaults to the OS keyring, falling back to a file).
             store: Token store used to persist refreshed credentials. When
                 credentials are loaded from the store, refreshes are persisted
                 back to it automatically.
@@ -54,7 +54,7 @@ class ClaudeCodeProvider(AnthropicProvider):
         """
         if credentials is None:
             if store is None:
-                store = ClaudeCodeTokenStore()
+                store = default_store()
             creds = store.load()
             if creds is None:
                 raise UserError(
@@ -98,9 +98,9 @@ class ClaudeCodeProvider(AnthropicProvider):
     def from_token_store(
         cls,
         *,
-        store: ClaudeCodeTokenStore | None = None,
+        store: TokenStore | None = None,
         http_client: httpx2.AsyncClient | None = None,
         base_url: str | None = None,
     ) -> "ClaudeCodeProvider":
-        """Build a provider from the stored token file."""
+        """Build a provider from the default store."""
         return cls(store=store, http_client=http_client, base_url=base_url)

pydantic_claude_code-0.2.0/src/pydantic_ai_claude_code/storage.py

@@ -0,0 +1,135 @@
+"""Token storage for Claude Code credentials.
+
+By default credentials live in the OS keyring: the Keychain on macOS, Credential
+Manager on Windows, Secret Service on Linux. When no keychain is available, a
+JSON file with `0644` permissions is used instead. Force a backend with the
+`CLAUDE_CODE_CREDENTIALS` env var (`keyring` or `file`); the file path honors
+`CLAUDE_CODE_AUTH_FILE`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Protocol
+
+from pydantic_ai.exceptions import UserError
+
+from .credentials import ClaudeCodeCredentials
+
+_FILE_PERMISSIONS = 0o644
+
+
+class TokenStore(Protocol):
+    """Sibling store backends must both implement this shape."""
+
+    def load(self) -> ClaudeCodeCredentials | None:
+        """Return stored credentials, or `None` when nothing is stored yet."""
+        ...
+
+    def save(self, credentials: ClaudeCodeCredentials) -> None:
+        """Persist credentials for the next run."""
+        ...
+
+
+def default_auth_path() -> Path:
+    """The fallback token file path, honoring the `CLAUDE_CODE_AUTH_FILE` override."""
+    env_path = os.environ.get("CLAUDE_CODE_AUTH_FILE")
+    if env_path:
+        return Path(env_path).expanduser()
+    data_dir = Path(os.environ.get("XDG_DATA_HOME", "") or (Path.home() / ".local" / "share"))
+    return data_dir / "pydantic-ai-claude-code" / "auth.json"
+
+
+def default_store() -> TokenStore:
+    """The default store: keyring when available, otherwise the JSON file."""
+    backend = os.environ.get("CLAUDE_CODE_CREDENTIALS", "auto").lower()
+    if backend not in ("auto", "keyring", "file"):
+        raise UserError(f"Unknown CLAUDE_CODE_CREDENTIALS backend {backend!r}; expected 'auto', 'keyring', or 'file'.")
+    if backend == "file":
+        return ClaudeCodeTokenStore()
+    if backend == "keyring" or _keyring_available():
+        return KeyringTokenStore()
+    return ClaudeCodeTokenStore()
+
+
+class ClaudeCodeTokenStore:
+    """JSON-file store with `0644` permissions, the no-keychain fallback."""
+
+    def __init__(self, path: str | Path | None = None) -> None:
+        self.path = Path(path) if path is not None else default_auth_path()
+
+    def load(self) -> ClaudeCodeCredentials | None:
+        """Return stored credentials, or `None` when nothing is stored yet."""
+        try:
+            data = json.loads(self.path.read_text())
+        except FileNotFoundError:
+            return None
+        except (OSError, json.JSONDecodeError) as exc:
+            raise UserError(f"Unable to read Claude Code credentials from {str(self.path)!r}.") from exc
+        return ClaudeCodeCredentials.from_token_file(data)
+
+    def save(self, credentials: ClaudeCodeCredentials) -> None:
+        """Persist credentials atomically with `0644` permissions."""
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(credentials.to_wire_dict(), indent=2))
+        tmp.chmod(_FILE_PERMISSIONS)
+        os.replace(tmp, self.path)
+
+
+class KeyringTokenStore:
+    """OS-keyring store backed by the `keyring` package.
+
+    The service name is `pydantic-ai-claude-code` and credentials are stored as
+    a single JSON blob under the `default` user name.
+    """
+
+    SERVICE = "pydantic-ai-claude-code"
+    USERNAME = "default"
+
+    def __init__(self, service: str = SERVICE, username: str = USERNAME) -> None:
+        self.service = service
+        self.username = username
+
+    def load(self) -> ClaudeCodeCredentials | None:
+        """Return stored credentials from the keyring, or `None` when absent."""
+        raw = self._keyring_get()
+        if not raw:
+            return None
+        return ClaudeCodeCredentials.from_token_file(json.loads(raw))
+
+    def save(self, credentials: ClaudeCodeCredentials) -> None:
+        """Persist credentials to the keyring."""
+        self._keyring_require()
+        import keyring
+
+        keyring.set_password(self.service, self.username, json.dumps(credentials.to_wire_dict()))
+
+    def _keyring_get(self) -> str | None:
+        self._keyring_require()
+        import keyring
+
+        return keyring.get_password(self.service, self.username)
+
+    @staticmethod
+    def _keyring_require() -> None:
+        try:
+            import keyring
+
+            keyring.get_keyring()
+        except Exception as exc:  # noqa: BLE001 - no keychain service on this machine
+            raise UserError(
+                "No OS keyring is available. Set CLAUDE_CODE_CREDENTIALS=file to use the JSON file store."
+            ) from exc
+
+
+def _keyring_available() -> bool:
+    try:
+        import keyring
+
+        keyring.get_keyring()
+        return True
+    except Exception:  # noqa: BLE001 - probe only; the store validates again on use
+        return False

pydantic_claude_code-0.2.0/tests/test_keyring_store.py

@@ -0,0 +1,77 @@
+"""Tests for keyring-backed storage and `default_store()` selection."""
+
+from __future__ import annotations
+
+import json
+
+import keyring
+import pytest
+from pydantic_ai.exceptions import UserError
+
+from pydantic_ai_claude_code.credentials import ClaudeCodeCredentials
+from pydantic_ai_claude_code.storage import (
+    ClaudeCodeTokenStore,
+    KeyringTokenStore,
+    default_store,
+)
+
+
+@pytest.fixture
+def fake_keyring(monkeypatch) -> dict[str, str]:
+    store: dict[str, str] = {}
+
+    def set_password(service: str, username: str, password: str) -> None:
+        store[(service, username)] = password
+
+    def get_password(service: str, username: str) -> str | None:
+        return store.get((service, username))
+
+    def get_keyring() -> object:
+        # Pretend a keychain backend exists.
+        return object()
+
+    monkeypatch.setattr(keyring, "set_password", set_password)
+    monkeypatch.setattr(keyring, "get_password", get_password)
+    monkeypatch.setattr(keyring, "get_keyring", get_keyring)
+    return store
+
+
+def test_keyring_roundtrip(fake_keyring) -> None:
+    store = KeyringTokenStore()
+    creds = ClaudeCodeCredentials(access_token="a", refresh_token="b")
+    store.save(creds)
+    assert store.load() == creds
+    stored = fake_keyring[(KeyringTokenStore.SERVICE, KeyringTokenStore.USERNAME)]
+    assert json.loads(stored)["access_token"] == "a"
+
+
+def test_default_store_prefers_keyring(fake_keyring, monkeypatch) -> None:
+    monkeypatch.delenv("CLAUDE_CODE_CREDENTIALS", raising=False)
+    assert isinstance(default_store(), KeyringTokenStore)
+
+
+def test_default_store_falls_back_to_file(monkeypatch, tmp_path) -> None:
+    monkeypatch.delenv("CLAUDE_CODE_CREDENTIALS", raising=False)
+
+    def no_keyring() -> object:
+        raise RuntimeError("no keychain (headless)")
+
+    monkeypatch.setattr(keyring, "get_keyring", no_keyring)
+    assert isinstance(default_store(), ClaudeCodeTokenStore)
+    # The real (working) backend is irrelevant: with keyring out of the picture the
+    # file store must be used, and it must respect CLAUDE_CODE_AUTH_FILE.
+    monkeypatch.setenv("CLAUDE_CODE_AUTH_FILE", str(tmp_path / "custom.json"))
+    assert default_store().path == tmp_path / "custom.json"  # type: ignore[attr-defined]
+
+
+def test_default_store_env_override(monkeypatch, fake_keyring) -> None:
+    monkeypatch.setenv("CLAUDE_CODE_CREDENTIALS", "file")
+    assert isinstance(default_store(), ClaudeCodeTokenStore)
+    monkeypatch.setenv("CLAUDE_CODE_CREDENTIALS", "keyring")
+    assert isinstance(default_store(), KeyringTokenStore)
+
+
+def test_default_store_bad_env_raises(monkeypatch) -> None:
+    monkeypatch.setenv("CLAUDE_CODE_CREDENTIALS", "bogus")
+    with pytest.raises(UserError):
+        default_store()

{pydantic_claude_code-0.1.0 → pydantic_claude_code-0.2.0}/tests/test_storage.py

@@ -18,11 +18,11 @@ def test_save_load_roundtrip(tmp_path) -> None:
     assert store.load() == creds
 
 
-def test_save_sets_0600_perm(tmp_path) -> None:
+def test_save_sets_0644_perm(tmp_path) -> None:
     store = ClaudeCodeTokenStore(path=tmp_path / "auth.json")
     store.save(ClaudeCodeCredentials(access_token="a", refresh_token="b"))
     mode = stat.S_IMODE((tmp_path / "auth.json").stat().st_mode)
-    assert mode == 0o600
+    assert mode == 0o644
 
 
 def test_load_missing_returns_none(tmp_path) -> None:

pydantic_claude_code-0.1.0/src/pydantic_ai_claude_code/storage.py

@@ -1,50 +0,0 @@
-"""Persistent token storage for Claude Code credentials.
-
-The file lives under the user's data directory, is created with `0o600`
-permissions, and its path can be overridden with the `CLAUDE_CODE_AUTH_FILE`
-environment variable.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-from pathlib import Path
-
-from pydantic_ai.exceptions import UserError
-
-from .credentials import ClaudeCodeCredentials
-
-
-def default_auth_path() -> Path:
-    """The token file path, honoring the `CLAUDE_CODE_AUTH_FILE` override."""
-    env_path = os.environ.get("CLAUDE_CODE_AUTH_FILE")
-    if env_path:
-        return Path(env_path).expanduser()
-    data_dir = Path(os.environ.get("XDG_DATA_HOME", "") or (Path.home() / ".local" / "share"))
-    return data_dir / "pydantic-ai-claude-code" / "auth.json"
-
-
-class ClaudeCodeTokenStore:
-    """Read and write `ClaudeCodeCredentials` to a single JSON file."""
-
-    def __init__(self, path: str | Path | None = None) -> None:
-        self.path = Path(path) if path is not None else default_auth_path()
-
-    def load(self) -> ClaudeCodeCredentials | None:
-        """Return stored credentials, or `None` when nothing is stored yet."""
-        try:
-            data = json.loads(self.path.read_text())
-        except FileNotFoundError:
-            return None
-        except (OSError, json.JSONDecodeError) as exc:
-            raise UserError(f"Unable to read Claude Code credentials from {str(self.path)!r}.") from exc
-        return ClaudeCodeCredentials.from_token_file(data)
-
-    def save(self, credentials: ClaudeCodeCredentials) -> None:
-        """Persist credentials atomically with restrictive permissions."""
-        self.path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = self.path.with_suffix(".tmp")
-        tmp.write_text(json.dumps(credentials.to_wire_dict(), indent=2))
-        tmp.chmod(0o600)
-        os.replace(tmp, self.path)