docs(integrations): codify the canonical-example authoring rule#373
Merged
Conversation
Every integration ships a runnable examples/app.py + a 100%-covering in-memory smoke test (no coverage omit) + a README Usage-example line. Piloted in modern-di-faststream and rolled out to the other 9. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Benchmark
Details
| Benchmark suite | Current: b101c65 | Previous: 606f3a4 | Ratio |
|---|---|---|---|
benchmarks/test_guard_cold.py::test_g8_cold_first_resolve |
19429.630631093445 iter/sec (stddev: 0.0001671957756083564) |
40835.93589989146 iter/sec (stddev: 0.00008563574321656777) |
2.10 |
benchmarks/test_guard_concurrency.py::test_g14_concurrent_cached_hit[1] |
293.16125502522135 iter/sec (stddev: 0.00004682252592769287) |
647.0028790905143 iter/sec (stddev: 0.000017533407907452173) |
2.21 |
benchmarks/test_guard_concurrency.py::test_g14_concurrent_cached_hit[2] |
277.7120514536409 iter/sec (stddev: 0.00004888753763402436) |
607.5042138569954 iter/sec (stddev: 0.000020749992266931318) |
2.19 |
benchmarks/test_guard_concurrency.py::test_g14_concurrent_cached_hit[4] |
259.6217073719326 iter/sec (stddev: 0.00003621705098126102) |
546.3619829500476 iter/sec (stddev: 0.00012123601876523984) |
2.10 |
benchmarks/test_guard_concurrency.py::test_g15_concurrent_first_resolve[1] |
1328.300991232818 iter/sec (stddev: 0.0013415167738355291) |
2360.308021778397 iter/sec (stddev: 0.0009107968322682441) |
1.78 |
benchmarks/test_guard_concurrency.py::test_g15_concurrent_first_resolve[2] |
1237.4867403299024 iter/sec (stddev: 0.0005683786885045567) |
2309.5146035438306 iter/sec (stddev: 0.00030370334967405013) |
1.87 |
benchmarks/test_guard_concurrency.py::test_g15_concurrent_first_resolve[4] |
795.6951302064515 iter/sec (stddev: 0.001662799775343521) |
1540.2824880680978 iter/sec (stddev: 0.0007435161301479087) |
1.94 |
benchmarks/test_guard_lifecycle.py::test_g6_build_child_container |
466042.0491401275 iter/sec (stddev: 0.000010702654412674548) |
838338.9866078722 iter/sec (stddev: 0.0000070672985470577465) |
1.80 |
benchmarks/test_guard_lifecycle.py::test_g6b_build_child_container_auto_scope |
446798.5834162959 iter/sec (stddev: 0.000010211571081024825) |
796895.3588854331 iter/sec (stddev: 0.000006207276311874524) |
1.78 |
benchmarks/test_guard_lifecycle.py::test_g7_request_lifecycle |
64168.54730819743 iter/sec (stddev: 0.000015776976395260843) |
139730.3767975471 iter/sec (stddev: 0.000007982707950047918) |
2.18 |
benchmarks/test_guard_lifecycle.py::test_g13_teardown_at_scale |
41032.675224173174 iter/sec (stddev: 0.00002250994461325005) |
77766.55012365908 iter/sec (stddev: 0.000012370489579591514) |
1.90 |
benchmarks/test_guard_resolve.py::test_g1_transient_resolve |
1179191.0318142022 iter/sec (stddev: 4.5555581006719764e-7) |
2281342.362607366 iter/sec (stddev: 1.7251930556916853e-7) |
1.93 |
benchmarks/test_guard_resolve.py::test_g2_cached_resolve |
2398822.222949425 iter/sec (stddev: 9.058966121780466e-8) |
5125327.379285795 iter/sec (stddev: 1.629647434420831e-8) |
2.14 |
benchmarks/test_guard_resolve.py::test_g3_deep_chain |
479217.68855676206 iter/sec (stddev: 5.580347881606654e-7) |
991079.3346772593 iter/sec (stddev: 2.800805479220972e-7) |
2.07 |
benchmarks/test_guard_resolve.py::test_g4_wide_resolve |
299619.0302634869 iter/sec (stddev: 7.951005270687664e-7) |
594822.116248988 iter/sec (stddev: 2.7037504440064286e-7) |
1.99 |
benchmarks/test_guard_resolve.py::test_g5_cross_scope |
1052122.2799854386 iter/sec (stddev: 3.546541237694462e-7) |
2081025.1550824712 iter/sec (stddev: 1.8192197123732636e-7) |
1.98 |
benchmarks/test_guard_resolve.py::test_g9_context_resolve |
536424.8237093533 iter/sec (stddev: 5.895306274440161e-7) |
1028350.1032020622 iter/sec (stddev: 2.3393695083988623e-7) |
1.92 |
benchmarks/test_guard_resolve.py::test_g12_override_active_resolve |
363555.8607799567 iter/sec (stddev: 4.334079806182322e-7) |
795480.1113773357 iter/sec (stddev: 6.978847263978267e-8) |
2.19 |
benchmarks/test_guard_validate.py::test_g10_validate_deep_chain |
25268.96475610588 iter/sec (stddev: 0.00005092474794978487) |
52609.58075911956 iter/sec (stddev: 0.000012721433383914016) |
2.08 |
benchmarks/test_guard_validate.py::test_g11_validate_wide |
17029.38615853453 iter/sec (stddev: 0.000007781457488989438) |
34375.87533125701 iter/sec (stddev: 0.000004981481983610166) |
2.02 |
This comment was automatically generated by workflow using github-action-benchmark.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Codifies the canonical-example pattern — piloted in
modern-di-faststream(#34) and rolled out to the other 9 integrations — as a documented authoring rule inwriting-integrations.md, so present and future integrations conform instead of copying a de-facto pattern.Rationale in the change file:
planning/changes/2026-07-25.01-codify-canonical-example.md.Adds a Canonical example bullet to Repo scaffolding + a checklist item, capturing the pilot's shape plus the rollout's refinements:
examples/app.py(+ empty__init__.py): APPSettings+ one work-scoped service by type, into one handler/task/command via the framework idiom.typing.Annotated[T, FromDI(...)]marker form (avoids ruffB008).tests/test_example.pysmoke test via the repo's in-memory double, asserting real injected output, covering the example to 100% — no coverageomit;# pragma: no coveronly a real boot line.Usage example: [examples/](./examples)line.CPY001ignored and reflow pre-existing Markdown code fences (every rollout PR hit this).Docs-only; no capability change.
just check-planningandjust lint-cigreen.🤖 Generated with Claude Code