Skip to content

Breaking renames, migration guide gaps and stale docs before 4.0.0 #614

Closed

Description

@lesnik512

This was generated by AI during a third pre-4.0 audit of main at f6e343d.

Renames that are cheap only before 4.0.0, plus docs and docstrings that drifted from the code. None of the 13 integrations read the renamed names. Blocks the 4.0.0 tag.

Renames (breaking)

  1. ProviderNotRegisteredError.provider_type holds the requested type, while DuplicateProviderTypeError.provider_type holds a bound type. Rename to .dependency_type (the parameter name on resolve / find_provider). Reword "Provider of type <class 'x.B'> is not registered in providers registry." to "No provider is registered for B.", matching the troubleshooting page title. Update docs/providers/errors-and-exceptions.md:8 and docs/troubleshooting/missing-provider.md:10.
  2. FinalizerError(finalizer_errors=) and ValidationFailedError(errors=) name attributes 4.0 replaced with .exceptions. Rename both keywords to exceptions=.

Migration guide gaps (docs/migration/to-4.x.md)

  1. The deleted modules modern_di.registries.cache_registry and context_registry, and the private helpers removed from modern_di.scope. One paragraph stating the four-public-modules rule (modern_di, .providers, .exceptions, .integrations).
  2. ArgumentResolutionError(...) now requires creator=. The guide only mentions the renamed keywords.
  3. Entries for every rename above and for the stricter validate() from validate() bugs: Container under a custom scope enum, reference-only providers, Alias scope #612.

Stale text

  1. "context registry" (removed in perf: registry hooks, container-owned cache and context, cheaper child build (#605) #610): modern_di/container.py:55, providers/context_provider.py:11,54, docs/providers/context.md:8,135, docs/troubleshooting/context-not-set.md:3. "cache registry": docs/providers/factories.md:274. docs/introduction/performance.md:255 cites CacheRegistry.fetch_cache_item.
  2. docs/providers/errors-and-exceptions.md, InvalidChildScopeError: "(or the constructor receives a parent at an equal/shallower scope)". The constructor no longer takes a parent.
  3. docs/providers/lifecycle.md:232 names the internal register.
  4. docs/providers/container.md: H1 "Container provider" vs nav "Container"; the "Explicit injection" example annotates the parameter as Container, contradicting its own reason.
  5. docs/providers/factories.md:108: finalizer=lambda res: res.close() fails pyright (res is object). Use a def.
  6. types.P = ParamSpec("P") (modern_di/types.py:7) is unused in the package, tests and integrations. Delete.

Decided: CacheSettings.clear_cache keeps its name. It exists in 3.6.0, so a rename would break working code for little gain.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or requestready-for-agentFully specified, ready for an AFK agent

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions