Add scoped singleton registries to SingletonConfigurable - #953
Merged
Conversation
Welcome to Codecov 🎉Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests. Thanks for integrating Codecov - We've got you covered ☂️ |
Introduce SingletonScope, an isolated singleton registry activated for a dynamic extent (current thread / async task) via a contextvars.ContextVar. While active, instance() on any subclass of the scope's base resolves within the scope -- creating fresh instances on first use -- without ever reading, creating, or mutating the process-global _instance. The classic (no-scope) instance()/initialized()/clear_instance() paths are left textually unchanged; scoped resolution is prepended as an early branch. - SingletonScope with covers()/get() (MRO-walk parity)/add() (write-through pre-seeding) and a re-enterable __call__ context manager - SingletonConfigurable.scope() factory and _current_scope() helper - Export SingletonScope from traitlets.config - Docs: "Singleton scopes" section with usage and semantics, a per-thread singleton example, a "complete blank slate" section covering every singleton at once via SingletonConfigurable.scope(), and an "injecting a specific instance" section motivating add() - versionadded/versionchanged:: 5.17 directives on the new API and on the instance()/initialized()/clear_instance() behavior change - Tests covering isolation, lazy creation by uncontrolled code, no global side effects, initialized() semantics, re-entry, pre-seeding, blast radius, nesting/LIFO restore, MRO sibling MultipleInstanceError parity, in-scope clear_instance, thread isolation, asyncio task propagation, and the process-wide blank-slate scope Because coverage is just issubclass(cls, base), scoping SingletonConfigurable itself yields a clean-room registry in which no singleton has been created yet. add() is the only way to control *which* object in-scope .instance() calls receive, since they otherwise construct a fresh one; it writes through to singleton ancestors so a pre-seeded subclass instance is also returned when resolving via a parent class. The "threads don't inherit the scope" guarantee only holds when sys.flags.thread_inherit_context is false (the default GIL build). On the free-threaded build (e.g. 3.14t) it defaults to true, so a child thread starts with a copy of the parent context and resolves .instance() within the scope. Activating a scope under that flag emits a RuntimeWarning, the docs carry a matching caveat, and the thread-isolation test is skipped there. The flag is read through a small _threads_inherit_context() helper so tests can patch it without replacing the sys.flags structseq wholesale (which broke on pypy-3.11). Also pin the prettier pre-commit hook to language_version: system, so it uses the system node instead of a downloaded nodeenv build.
Carreau
force-pushed
the
multiton
branch
2 times, most recently
from
August 4, 2026 08:07
1ae2b75 to
9133ced
Compare
Carreau
marked this pull request as ready for review
August 4, 2026 08:25
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.
Introduce SingletonScope, an isolated singleton registry activated for a dynamic extent (current thread / async task) via a contextvars.ContextVar. While active, instance() on any subclass of the scope's base resolves within the scope -- creating fresh instances on first use -- without ever reading, creating, or mutating the process-global _instance. The classic (no-scope) instance()/initialized()/clear_instance() paths are left textually unchanged; scoped resolution is prepended as an early branch.