feat!: Generate the Python SDK via the OpenAPI spec

[gjtorikian]

This branch moves the Python SDK from the old handwritten surface to the OpenAPI-generated client surface, with a small set of targeted aliases kept where they still help. The result is a much larger API, more consistent resource naming, better typed request and error handling, and a cleaner package layout for the next major release.

Removed

Handwritten compatibility internals

• Removed the old client internals and compatibility plumbing:
  • src/workos/_base_client.py
  • src/workos/_client_configuration.py
  • src/workos/client.py
  • src/workos/async_client.py
• Removed the legacy exception module at src/workos/exceptions.py.
• Removed the legacy src/workos/types/ tree and its broad re-export surface.

Flat handwritten resource modules

• Removed the old single-file resource implementations in favor of generated resource packages.
• That includes legacy modules such as:
  • src/workos/api_keys.py
  • src/workos/audit_logs.py
  • src/workos/authorization.py
  • src/workos/connect.py
  • src/workos/directory_sync.py
  • src/workos/organizations.py
  • src/workos/portal.py
  • src/workos/user_management.py
• Removed a large amount of handwritten test utility scaffolding that only existed to support the old surface.

Old tooling and model assumptions

• Removed pydantic from the runtime dependencies; @dataclass is now used instead.
• Removed mypy as the primary type checker in favor of pyright.
• Removed the old WorkOSListResource-style pagination surface.

Added

Generated sync and async clients

• Added generated WorkOSClient and AsyncWorkOSClient as the main SDK entrypoints.
• Kept top-level WorkOS and AsyncWorkOS aliases for ergonomics.
• Added shared generated request handling with:
  • httpx sync/async clients
  • retry/backoff support
  • automatic POST idempotency keys
  • per-request overrides through RequestOptions

Generated resource packages and models

• Added generated resource packages across the SDK, including:
  • admin_portal
  • applications
  • application_client_secrets
  • connections
  • directories
  • directory_groups
  • directory_users
  • feature_flags
  • multi_factor_auth
  • permissions
  • radar
  • workos_connect
• Added generated dataclass-style models with from_dict() / to_dict() behavior.
• Added generated pagination types:
  • SyncPage
  • AsyncPage

Better runtime error handling

• Added a normalized exception hierarchy in src/workos/_errors.py.
• Exceptions now consistently expose fields like status_code, message, request_id, raw_body, request_url, and request_method.
• Added explicit timeout and connection exceptions:
  • WorkOSTimeoutException
  • WorkOSConnectionException

Coverage and maintenance improvements

• Added broad generated test coverage, including model round-trip tests and generated client tests.
• Added a dedicated lint workflow and pyrightconfig.json.
• Added pytest-httpx for HTTP client testing.

Changed

Public API shape

• The SDK now centers on generated resource namespaces instead of the old handwritten helper modules.
• Several legacy top-level aliases are gone or split up:
  • client.connect becomes client.applications and client.application_client_secrets
  • client.directory_sync becomes client.directories, client.directory_groups, and client.directory_users
  • client.portal becomes client.admin_portal
• Some compatibility aliases were intentionally kept:
  • WorkOS / AsyncWorkOS
  • client.mfa as an alias for client.multi_factor_auth
  • client.user_management.load_sealed_session(...)
  • selected resource-level compatibility methods in areas like Admin Portal, Audit Logs, and Authorization

Client configuration expectations

• Minimum supported Python is now 3.10+.
• Client construction now accepts either api_key or client_id, and only raises if neither is configured.
• Flows that rely on a client ID fallback still require client_id at call time, via constructor configuration, or through WORKOS_CLIENT_ID.
• Retry behavior is now built into the generated client and can be configured globally or per request.

Model behavior

• SDK models are no longer Pydantic models.
• Code that relied on model_validate(), model_dump(), or other Pydantic behaviors now needs to move to the generated dataclass-style API.
• Direct model imports should come from generated workos.<resource>.models packages rather than workos.types.*.

Development workflow

• Type checking moved from mypy to pyright --strict.
• Dependency baselines were refreshed, including the Python floor and package constraints.
• CI and local dev scripts now reflect the generated-client world instead of the old handwritten one.

Migration Notes

Biggest user-facing updates

• Import clients from workos, not workos.client / workos.async_client.
• Update code that used old helper namespaces like connect, portal, and directory_sync.
• Update any code treating SDK models as Pydantic models.
• Review flows that depend on client_id defaults and either pass it explicitly or configure it on the client / environment.
• If you depend on 5.x-style “fail immediately” request behavior, set max_retries=0.

What should feel familiar

• Top-level client construction is still straightforward.
• Sync and async clients still exist.
• Sealed session loading still has a first-class helper.
• A few high-value aliases remain in place to keep the upgrade from being harsher than it needs to be.