Workos Python CLAUDE.md

> Sourced from [workos/workos-python](https://github.com/workos/workos-python) — [MIT](https://github.com/workos/workos-python/blob/a75e51fa11aead2d3ebca12011395c25daa5f55b/CLAUDE.md).

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Code Generation

Most of the SDK is **auto-generated** by `oagen` (an internal OpenAPI code generator). Generated files begin with `# This file is auto-generated by oagen. Do not edit.` Hand-maintained code is fenced with `@oagen-ignore-start` / `@oagen-ignore-end` markers or marked with `# @oagen-ignore-file` (e.g., `session.py`, `passwordless.py`, `vault.py`, `public_client.py`, `pkce.py`, `actions.py`).

## Development Commands

### Installation and Setup

```bash
uv sync --locked --dev # Install package in development mode with dev dependencies
```

### Code Quality

```bash
uv run ruff format .          # Format code
uv run ruff format --check .  # Check formatting without making changes
uv run ruff check .           # Lint code
uv run pyright                # Type checking
```

### Testing

The SDK uses [nox](https://nox.thea.codes/) with [nox-uv](https://github.com/dantebben/nox-uv) for multi-version Python testing. This ensures compatibility across all supported Python versions (3.10-3.14).

**Quick testing with the test script:**

```bash
./scripts/test.sh              # Run tests on all Python versions
./scripts/test.sh 3.12         # Run tests on Python 3.12 only
./scripts/test.sh 3.11 3.12    # Run tests on Python 3.11 and 3.12
./scripts/test.sh --coverage   # Run tests with coverage on all versions
./scripts/test.sh --ci         # Run full CI checks (lint, type, tests)
./scripts/test.sh --fresh      # Recreate virtual environments
./scripts/test.sh 3.12 -- -k "test_sso" -v  # Pass pytest arguments
```

**Direct nox commands:**

```bash
uv run nox                       # Run tests on all Python versions
uv run nox -s tests-3.12         # Run tests on specific Python version
uv run nox -s coverage           # Run tests with coverage
uv run nox -s lint               # Run linting
uv run nox -s typecheck          # Run type checking
uv run nox -s ci                 # Run all CI checks
uv run nox -l                    # List all available sessions
```

**Single-version testing (faster for development):**

```bash
uv run pytest                    # Run all tests on current Python
uv run pytest tests/test_sso.py  # Run specific test file
uv run pytest -k "test_name"     # Run tests matching pattern
uv run pytest --cov=workos       # Run tests with coverage
```

### Build and Distribution

```bash
uv build --sdist --wheel               # Build distribution packages
bash scripts/build_and_upload_dist.sh  # Build and upload to PyPI
```

## Architecture Overview

### Client Architecture

The SDK provides both synchronous and asynchronous clients:

- `WorkOSClient` (sync) and `AsyncWorkOSClient` (async) are the main entry points (exported from `workos/__init__.py`)
- Both inherit from `_BaseWorkOSClient` (in `workos/_client.py`) which handles configuration, HTTP transport, retry logic, and error mapping
- Each feature area (SSO, Organizations, etc.) is exposed as a `@functools.cached_property` on the client for lazy loading
- HTTP transport uses `httpx` directly; there is no separate HTTP client abstraction layer

### Module Structure

Each feature module follows this layout:

```
src/workos/{module_name}/
  __init__.py        # Re-exports from _resource and models
  _resource.py       # Sync and Async resource classes (e.g., SSO + AsyncSSO)
  models/
    __init__.py      # Re-exports all model classes
    {model}.py       # Individual dataclass model files
```

Resource classes take a `WorkOSClient` or `AsyncWorkOSClient` client reference and call `self._client.request()` or `self._client.request_page()` for paginated endpoints.

### Type System

- All models use `@dataclass(slots=True)` — **not** Pydantic
- Each model implements `from_dict(cls, data) -> Self` for deserialization and `to_dict() -> Dict` for serialization
- The `Deserializable` protocol in `workos/_types.py` defines the `from_dict` contract
- `RequestOptions` (a `TypedDict`) allows per-call overrides for headers, timeout, retries, etc.
- Type checking uses **pyright** (configured in `pyrightconfig.json`)

### Pagination

- `SyncPage[T]` and `AsyncPage[T]` dataclasses in `workos/_pagination.py` represent paginated results
- Cursor-based: `before`/`after` properties, `has_more()` check
- `auto_paging_iter()` transparently fetches subsequent pages

### Error Handling

All exceptions live in `workos/_errors.py` and inherit from `WorkOSError`:

- `BadRequestError` (400), `AuthenticationError` (401), `AuthorizationError` (403), `NotFoundError` (404), `ConflictError` (409), `UnprocessableEntityError` (422), `RateLimitExceededError` (429), `ServerError` (5xx)
- `ConfigurationError`, `WorkOSConnectionError`, `WorkOSTimeoutError` for non-HTTP errors
- `STATUS_CODE_TO_ERROR` dict maps status codes to exception classes

### Testing Framework

- Uses **pytest** with **pytest-httpx** for HTTP mocking (provides the `httpx_mock` fixture)
- Separate test classes for sync (`TestSSO`) and async (`TestAsyncSSO`) variants
- Async tests use `@pytest.mark.asyncio`
- JSON fixtures in `tests/fixtures/`, loaded via `load_fixture()` from `tests/generated_helpers.py`
- Client fixtures `workos` and `async_workos` defined in `tests/conftest.py`

### Configuration

- Environment variable support: `WORKOS_API_KEY`, `WORKOS_CLIENT_ID`, `WORKOS_BASE_URL`, `WORKOS_REQUEST_TIMEOUT`
- Retry logic: exponential backoff with jitter, retries on 429/5xx, respects `Retry-After` headers
- Default timeout: 60 seconds