Skip to content

CLAUDE.md

Latest commit

 

History

History
46 lines (35 loc) · 3.97 KB

CLAUDE.md

File metadata and controls

46 lines (35 loc) · 3.97 KB
Raw

Didit Python SDK (sdk-python)

The official Didit server-side library for Python: didit-sdk on PyPI (name transfer pending, see docs/DESIGN.md 2.1). Status: released (1.0.0 on 2026-10-29). Merging the release-please pull request publishes the next version.

Read first

  • docs/DESIGN.md is the shared contract of all seven Didit server SDKs (sdk-python, sdk-node, sdk-go, sdk-java, sdk-php, sdk-ruby, sdk-dotnet). It is binding: when this code and the design disagree, the code is wrong.
  • openapi/ holds the API contract this SDK is generated from (see DESIGN.md section 3).

Toolchain

uv for environments and locking, hatchling for the build, pytest, mypy --strict, pyright, ruff.

Commands

Task Command
Install (dev environment, from uv.lock) uv sync
Generate src/didit/types, src/didit/resources, tests/generated from openapi/ uv run python codegen/generate.py
Check the committed generated code is current (CI) uv run python codegen/generate.py --check
Sync openapi/ with docs.didit.me (spec-sync workflow) uv run python codegen/spec_sync.py --summary spec-sync-summary.md
Test (unit, generated, contract, webhooks, Authentication, codegen) uv run pytest
Test with the core coverage gate uv run pytest --cov --cov-report=term-missing --cov-fail-under=90
Live sandbox smoke tests (only with DIDIT_SANDBOX_API_KEY) uv run pytest -m live
Lint and format uv run ruff check . and uv run ruff format .
Type-check uv run mypy and uv run pyright
Build the sdist and wheel uv build

Layout

  • Generated (never edit by hand): src/didit/types/, src/didit/resources/, tests/generated/. The generator is codegen/didit_codegen/; its tests are in codegen/tests/.
  • Core (hand-written): everything else in src/didit/ (_base_client.py transport and retries, _client.py options, _exceptions.py, _pagination.py, _files.py, _response.py, _models.py), src/didit/webhooks/ and src/didit/authentication/.
  • openapi/deprecated-operations.json (written by codegen/spec_sync.py) keeps methods whose operation was removed or renamed upstream as deprecated methods until remove_in (the next minor version); tests/test_contract.py fails once that version is reached, and the entry is then deleted.

Rules

  • Generated code is never edited by hand. Change the generator in codegen/ or openapi/overlay.json, then regenerate; CI fails when the committed generated code is stale.
  • openapi/verification.json, openapi/account.json and openapi/webhook-vectors.json are upstream copies; never edit them by hand. Only the spec sync workflow updates them.
  • Keep the SDKs in sync (HARD RULE). Any public API change in service-didit-verification or service-didit-auth must reach the OpenAPI documents in mintlify-docs, and from there every server SDK through the spec sync pull request. A change to hand-written core behaviour that DESIGN.md describes (client options, errors, retries, pagination, webhooks, Authentication) is made in all seven SDK repositories, one pull request each, and DESIGN.md is updated in all seven in the same words.
  • Feature parity across languages: a capability shipped in one server SDK ships in the other six.
  • Releases publish straight from this repository (Alex, 2026-10-29): merging the release-please pull request is the release approval, and the release workflow then creates the vX.Y.Z tag and publishes to the registry. Never push a release tag, create a release or publish by hand outside that flow, and never store a registry token where trusted publishing works.
  • Unit tests never touch the network. Live smoke tests run only when DIDIT_SANDBOX_API_KEY is set.
  • Never commit secrets, API keys or real customer data. Fixtures are synthetic.
  • CHANGELOG.md is generated by release-please from conventional commits; never edit it by hand.
  • Public API changes need tests, README updates and a conventional commit type that matches their semver impact.