some updates for dev documentation
Merged
AJ
3mo ago+92+92+01234567890123456789-0-0-0123456789
trying to distill the changes from #10052 into something more repeatable
truly not sure if some of this might be better as dev/guides/backend/creating-new-components.md
Summary by cubic
Improves backend dev docs on constructor-first wiring, interfaces/protocols, configuration invariants, and testing doubles. Extends the API backpressure example to show named-event observers, a single _notify, and how protocols keep third‑party deps out of core logic.
- Documentation
- Wiring: no late registration; pass deps to
__init__(0+ as requiredlist[...]); build near entry points; factories resolve settings and accept adapters; configure at construction; process‑global registries build lazily in their own module. - Interfaces/Protocols: choose implicit
Protocolor explicit interface module (prefer explicit); never put an ABC in the consumer; name methods in the consumer’s vocabulary; adapters live in their own module; only the wiring imports both; verify no third‑party imports under logic. - Configuration: tightly bound numeric fields with
allow_inf_nan=False; enforce cross‑field rules with@model_validatorand clear, greppable messages; test the validator and shipped defaults; use enums for values that leave the process and pass enum members. - Testing: two doubles for collaborators — a recording double for exact call sequences/values, and a failing double to prove failure containment; keep helpers shared and prefer adapters over patching.
- API backpressure example: events are named methods; one
_notifyfans out with per‑observer failure containment; collaborators arrive via the constructor; wiring inserver.pychooses sinks soapi/admissionstays decoupled behindProtocols.
- Wiring: no late registration; pass deps to