endow

formplan v0.1

Status

Implementation has started. Real behavioral pytest coverage is now in progress; the runtime is intentionally still missing.

Answers

Project name: endow
Tagline: to provide with something freely or naturally
Primary authoring style: typed attributes declare dependencies and wiring is inferred from annotations.
Implementation selection: service/domain classes own concrete selection via from_env(...).
Graph lifecycle: one shared object graph per Backend.from_env(...) call.
Cycles: direct cyclic references such as Products <-> Methods should work transparently in user code.
Overrides: environment-driven factory selection is sufficient for MVP mocking; no separate override API is required yet.
Construction style: user classes should not need manual constructor wiring for injected dependencies.
Runtime inputs: nested from_env(...) factories may request values such as db as needed.
Naming direction: shared base Injectable, semantic bases Service and Domain, composition root entrypoint Backend.from_env(...).
First milestone: a working endow package MVP, not just a spec or example-only prototype.

Description

endow is a small dependency-injection library for Python backends. The MVP should make the DX from example.py real: annotation-first dependencies, environment-aware implementation selection, per-root shared graphs, and transparent cyclic domain references, with naming that distinguishes infrastructure services from domain-level backend components.

To-do

Capture agreed DX, naming, and MVP scope in this plan file.
Create the initial src/ layout for the package and tests.
Rewrite example.py as the contract for later implementation.
Add pyproject.toml using a non-setuptools backend, Python 3.12+, and version metadata from src/endow/__about__.py.
Add real behavioral pytest coverage for graph construction, factory selection, runtime inputs, cycle handling, and graph isolation.
Create the endow package with public bases Injectable, Service, Domain, and root construction via Backend.from_env(...).
Implement graph construction from type annotations with per-root shared instances.
Support from_env(...) factory hooks that can consume runtime inputs and choose concrete implementations.
Make direct dependency cycles work transparently without requiring user-facing lazy/provider wrapper types.
Replace the placeholder example.py with a truthful runnable example using Mailer, Applog, Products, and Methods.
Add tests covering simple wiring, env-based implementation selection, cycle handling, and per-root graph isolation.
Keep this formplan file current as implementation progresses.

Log

Reviewed the placeholder example.py and confirmed it was a DX sketch rather than working code.
Collected DX decisions for declaration style, resolution model, graph lifecycle, cycle behavior, overrides, constructor policy, and runtime input flow.
Selected naming direction: Injectable as the minimal shared base, Service for infrastructure capabilities, Domain for backend domain components, and Backend.from_env(...) as the composition-root entrypoint.
Confirmed project identity as endow with the tagline to provide with something freely or naturally.
Chose the first milestone to be a working library MVP with a real example and tests, rather than a spec-only pass.
Created the initial src/endow and tests directories.
Rewrote example.py into a contract-style example that defines the intended public naming and runtime behavior.
Added pyproject.toml with a non-setuptools build backend, Python 3.12+, and dynamic version metadata from src/endow/__about__.py.
Replaced the earlier contract-test direction with behavioral pytest coverage that should fail until the runtime exists.
Added a dev optional dependency so uv pip install -e .[dev] installs pytest.