DX polish: repr, keyword-only build_child_container, typed UNSET, error hints

[lesnik512]

Summary

Six Tier-1/2 items from plan.md (#4, #6, #7, #8, #10, #15–#17). Each is small and topically diverse; bundled into one PR because they share verification (lint + full test suite) and individually wouldn't warrant their own review cycle.

#4 — set_context propagation docs

ContextRegistry is per-container. Calling set_context on a parent after build_child_container doesn't propagate to the already-built child. Added a docstring on Container.set_context and a "Context Propagation" !!! warning section in docs/providers/container.md showing the broken pattern plus both fixes (set first, or pass context={...} to build_child_container).

#6 — override generic typing

Container.override(provider, override_object: object) lost the generic T. Tightened to override_object: types.T so type checkers catch shape mismatches in tests. All existing call sites (tests + docs) pass real subclass instances; no breakage.

#7 — __repr__ shows parent

Old: Container(scope=<Scope.APP: 1>, providers=1, cached=0)
New: Container(scope=APP, parent=APP, providers=1, cached=0) (child container example).
Replaces the verbose enum repr with scope.name and adds the parent's scope. Useful for nested debugging.

#8 — build_child_container keyword-only, swap order

Old: (self, context=None, scope=None) — positional, with the inconvenient order.
New: (self, *, scope=None, context=None) — keyword-only, scope-first.

Audited every caller across the ecosystem: 38 sites in this repo + all 5 sibling integration repos (modern-di-fastapi, modern-di-faststream, modern-di-litestar, modern-di-pytest, modern-di-typer). Zero positional callers. Safe across the modern-python ecosystem.

External breaking change: downstream users passing positionally will need to update.

#10 — typed UNSET sentinel removes # ty: ignore

UNSET = object() had no useful type, so bound_type: type | None = types.UNSET needed # ty: ignore[invalid-parameter-default] on three provider constructors. Replaced with a real UnsetType class; three constructors now declare bound_type: type | None | types.UnsetType = types.UNSET and the suppression comments are gone. Body sites use isinstance(bound_type, types.UnsetType) for proper narrowing.

#15-17 — error message polish

• InvalidChildScopeError: appends "(child scope value must be strictly greater than parent scope value)".
• MaxScopeReachedError: appends "To go deeper, build a child container with a custom IntEnum scope whose value is higher." (custom scopes are documented but invisible in this error).
• ScopeSkippedError: gained container_scope field and a much clearer message: "No APP-scope container exists in this chain; this chain starts at {container_scope}. Build an APP-scope container as the root."

Test plan

• just lint — clean (ruff format + check, ty)
• just test — 122 passed
• Manual repr smoke check: root + child reprs match new format
• Updated tests/test_container.py:repr and :scope_skipped for new strings; tests/test_custom_scope.py:68 substring match still passes; MaxScopeReachedError / InvalidChildScopeError substring assertions in test_container.py still pass since the new messages embed the old phrasing
• skip_creator_parsing warning test in test_factory.py still passes — guards UNSET-vs-explicit-bound_type semantics in Add LiteStar Example #10

🤖 Generated with Claude Code