Initial Python SDK import

.github/workflows/lint.yml

@@ -0,0 +1,33 @@
+name: Lint
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Run ruff
+      run: |
+        ruff check src/ tests/
+        ruff format --check src/ tests/
+
+    - name: Run mypy
+      run: |
+        mypy src/

.github/workflows/publish.yml

@@ -0,0 +1,111 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to publish (e.g., 0.1.0)'
+        required: true
+        type: string
+      test_pypi:
+        description: 'Publish to Test PyPI first'
+        required: false
+        type: boolean
+        default: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Run tests
+      run: |
+        python -m pytest tests/ -v
+
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Run ruff
+      run: |
+        ruff check src/ tests/
+        ruff format --check src/ tests/
+
+    - name: Run mypy
+      run: |
+        mypy src/
+
+  publish:
+    needs: [test, lint]
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Update version
+      run: |
+        # Update version in pyproject.toml
+        sed -i 's/version = ".*"/version = "${{ github.event.inputs.version }}"/' pyproject.toml
+        sed -i 's/__version__ = ".*"/__version__ = "${{ github.event.inputs.version }}"/' src/claude_code_sdk/__init__.py
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build package
+      run: python -m build
+
+    - name: Check package
+      run: twine check dist/*
+
+    - name: Publish to Test PyPI
+      if: ${{ github.event.inputs.test_pypi == 'true' }}
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }}
+      run: |
+        twine upload --repository testpypi dist/*
+        echo "Package published to Test PyPI"
+        echo "Install with: pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ claude-code-sdk==${{ github.event.inputs.version }}"
+
+    - name: Publish to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: |
+        twine upload dist/*
+        echo "Package published to PyPI"
+        echo "Install with: pip install claude-code-sdk==${{ github.event.inputs.version }}"

.github/workflows/test.yml

@@ -0,0 +1,37 @@
+name: Test
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Run tests
+      run: |
+        python -m pytest tests/ -v --cov=claude_code_sdk --cov-report=xml
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: false

.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/
+htmlcov/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anthropic, PBC
+
+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.

README.md

@@ -1 +1,132 @@
-# claude-code-sdk-python
+# Claude Code SDK for Python
+
+Python SDK for Claude Code. See the [Claude Code SDK documentation](https://docs.anthropic.com/en/docs/claude-code/sdk) for more information.
+
+## Installation
+
+```bash
+pip install claude-code-sdk
+```
+
+**Prerequisites:**
+- Python 3.10+
+- Node.js 
+- Claude Code: `npm install -g @anthropic-ai/claude-code`
+
+## Quick Start
+
+```python
+import anyio
+from claude_code_sdk import query
+
+async def main():
+    async for message in query(prompt="What is 2 + 2?"):
+        print(message)
+
+anyio.run(main)
+```
+
+## Usage
+
+### Basic Query
+
+```python
+from claude_code_sdk import query, ClaudeCodeOptions, AssistantMessage, TextBlock
+
+# Simple query
+async for message in query(prompt="Hello Claude"):
+    if isinstance(message, AssistantMessage):
+        for block in message.content:
+            if isinstance(block, TextBlock):
+                print(block.text)
+
+# With options
+options = ClaudeCodeOptions(
+    system_prompt="You are a helpful assistant",
+    max_turns=1
+)
+
+async for message in query(prompt="Tell me a joke", options=options):
+    print(message)
+```
+
+### Using Tools
+
+```python
+options = ClaudeCodeOptions(
+    allowed_tools=["Read", "Write", "Bash"],
+    permission_mode='acceptEdits'  # auto-accept file edits
+)
+
+async for message in query(
+    prompt="Create a hello.py file", 
+    options=options
+):
+    # Process tool use and results
+    pass
+```
+
+### Working Directory
+
+```python
+from pathlib import Path
+
+options = ClaudeCodeOptions(
+    cwd="/path/to/project"  # or Path("/path/to/project")
+)
+```
+
+## API Reference
+
+### `query(prompt, options=None)`
+
+Main async function for querying Claude.
+
+**Parameters:**
+- `prompt` (str): The prompt to send to Claude
+- `options` (ClaudeCodeOptions): Optional configuration
+
+**Returns:** AsyncIterator[Message] - Stream of response messages
+
+### Types
+
+See [src/claude_code_sdk/types.py](src/claude_code_sdk/types.py) for complete type definitions:
+- `ClaudeCodeOptions` - Configuration options
+- `AssistantMessage`, `UserMessage`, `SystemMessage`, `ResultMessage` - Message types
+- `TextBlock`, `ToolUseBlock`, `ToolResultBlock` - Content blocks
+
+## Error Handling
+
+```python
+from claude_code_sdk import (
+    ClaudeSDKError,      # Base error
+    CLINotFoundError,    # Claude Code not installed
+    CLIConnectionError,  # Connection issues
+    ProcessError,        # Process failed
+    CLIJSONDecodeError,  # JSON parsing issues
+)
+
+try:
+    async for message in query(prompt="Hello"):
+        pass
+except CLINotFoundError:
+    print("Please install Claude Code")
+except ProcessError as e:
+    print(f"Process failed with exit code: {e.exit_code}")
+except CLIJSONDecodeError as e:
+    print(f"Failed to parse response: {e}")
+```
+
+See [src/claude_code_sdk/_errors.py](src/claude_code_sdk/_errors.py) for all error types.
+
+## Available Tools
+
+See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/security#tools-available-to-claude) for a complete list of available tools.
+
+## Examples
+
+See [examples/quick_start.py](examples/quick_start.py) for a complete working example.
+
+## License
+
+MIT