Skip to content

docs: add "Writing an integration" guide#253

Merged
lesnik512 merged 2 commits into
mainfrom
docs/writing-integrations-guide
Jul 1, 2026
Merged

docs: add "Writing an integration" guide#253
lesnik512 merged 2 commits into
mainfrom
docs/writing-integrations-guide

Conversation

@lesnik512

Copy link
Copy Markdown
Member

What

Adds a published docs page, Integrations → Writing an integration, aimed at agents authoring official modern-di integrations.

The guide is distilled from the five existing integration packages (modern-di-fastapi, -faststream, -litestar, -typer, -pytest) and covers:

  • The integration contract — the five things every integration provides (connection ContextProviders, setup_di, fetch_di_container, per-unit-of-work child-container builder, FromDI + Dependency resolver), each with signature and responsibility.
  • Lifecycle rules — reopen-root-on-startup to survive restarts (ContainerClosedError), always close the child in finally, close_async/close_sync matching.
  • Scope mapping table (request → REQUEST, websocket → SESSION, message/command → REQUEST, nested action → ACTION).
  • Realization table — how each of the four app integrations implements each contract point, plus a pytest note for test-runner integrations.
  • Repo scaffolding — naming, main.py + re-exporting __init__.py, pyproject.toml shape, test layout, mirrored tooling, and a docs/nav entry in this repo.
  • Planning — recommends following planning-convention.
  • A copy-pasteable checklist.

Adds the page to the mkdocs.yml Integrations nav.

Verification

just docs-build (mkdocs build --strict) passes — broken links or nav warnings would fail the strict build.

🤖 Generated with Claude Code

lesnik512 and others added 2 commits July 2, 2026 00:05
Agent-facing spec for authoring official modern-di integrations,
distilled from the FastAPI/FastStream/Litestar/Typer/pytest packages:
the five-point integration contract, lifecycle and scope-mapping rules,
a per-framework realization table, repo scaffolding, and a checklist.
Adds the page to the Integrations nav.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Frameworks without a per-handler injection seam (Typer/Click, argparse,
task runners) can't use the native-marker FromDI path. Document the
decorator injection pattern generalized from modern-di-typer's @Inject:
inert FromDI marker, decoration-time signature rewrite, call-time
resolution, plus the pitfalls (setting __signature__, stripping only DI
params, decorator order, ctx.meta isolation). Splits FromDI into two
modes, adds a dedicated section and table, and a checklist item.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@lesnik512 lesnik512 merged commit 47358d7 into main Jul 1, 2026
7 checks passed
@lesnik512 lesnik512 deleted the docs/writing-integrations-guide branch July 1, 2026 21:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant