Declaration-based plugin lookup (from 0.14.0)#
DeclaredRegistry is the additive public capability implemented under
DepDigest #34 and admitted in
DepDigest 0.14.0, with publication tracked in
DepDigest #35. Public consumers
require a published DepDigest >=0.14.0; 0.13.0 does not provide this API.
Source experiments must identify the exact provider commit. MolSysMT adoption
and conversion parity remain in
MolSysMT #382.
The host supplies canonical identity-to-plugin declarations from its catalogue:
from depdigest import DeclaredRegistry
formats = DeclaredRegistry(
package_prefix="my_package.formats",
directory="my_package/formats",
declarations={"native": "native_form", "openmm": "openmm_form"},
attr_name="format_name",
)
list(formats.keys()) # visible names; no implementation imports
formats.declared_keys() # all declarations, including hidden optional formats
formats.loaded_keys() # visible successful caches and manual overrides
native = formats["native"] # imports only native_form
The host owns catalogue parsing, aliases, argument validation and converter capabilities. DepDigest owns filtering, loading, caching and diagnostics. A plugin, package initializer or dependency probe can itself import other modules; the registry cannot suppress those consumer import effects.
Enumeration and mutation#
keys(), iteration, length and membership inspect visible declarations. Membership does not certify loadability: failed/stale declarations remain listed.declared_keys()returns all declarations, including hidden ones.values()anditems()are mapping views. Iterating their values,dict(formats),get(),pop()and other operations that request a value can import plugins. Failed materialization raisesKeyError;get()returns its default.DeclaredRegistryimplementsMutableMapping, rather than subclassingdict. LegacyLazyRegistryretains its existing first-access full scan, including keys.Declarations preserve input order. New manual identities follow in assignment order. An override of a declared identity keeps its position and takes precedence over imports and filtering. The host owns that supplied implementation.
Deletion removes the declaration, override and cached value.
clear()removes all entries without importing anything. Neither operation unloads modules.
Declaration and discovery policy#
Declarations accept a mapping or iterable of (identity, plugin_key) pairs. Both
must be nonempty strings, with one canonical identity per plugin. Duplicate identities
or plugin keys raise ValueError at construction. A mapping cannot retain duplicates
already discarded by the host’s parser.
In filesystem mode plugin keys name immediate package directories using Python
identifiers. The implementation’s attr_name must match the declaration exactly.
Missing directories, missing attributes and mismatches fail lookup without removing
the declaration or admitting a cached implementation.
Entry-point mode accepts discovery_mode="entry_points" and entrypoint_group as
with LazyRegistry. Declarations refer to entry-point names, also used as configuration
mapping keys. Only the requested entry point’s load() runs. A missing identity
attribute falls back to its entry-point name. Zero or multiple matches fail before
loading. Modern select(group=...) and legacy group dictionaries are supported.
Undeclared plugins are excluded from indexed lookup. Explicit discover() imports
eligible undeclared candidates in sorted plugin-key order and adds their identities.
Existing declarations and overrides win; the first newly discovered identity wins.
Failures, missing identities and collisions are diagnosed and skipped. This fallback
may import many implementations and is never triggered by metadata or missing-key
lookup. Successful declarations are not reloaded by discovery.
Caching, freshness and diagnostics#
Successful and failed requests are cached. Failures raise KeyError chained from
the cause. Repeated lookups do not retry or repeat load diagnostics. retry(identity)
clears one failure and requests it again. refresh() clears failures and the registry’s
entry-point snapshot, retaining declarations, overrides and successful implementations.
Repeat discover() skips failures until refresh. A removed entry point with an already
cached implementation remains usable. Refresh does not unload/reimport modules.
Same-plugin recursive loads raise KeyError; independent nested loads work.
The supported concurrent reader scope is defined below.
Each access or enumeration resolves current package configuration. Registered and
temporary overrides affect an existing registry. Restricted soft capabilities are
hidden, even if cached; restoring visibility exposes the same cached implementation.
With SHOW_ALL_CAPABILITIES=True, names stay visible, but requesting an unavailable
soft dependency in the default strict policy emits existing availability diagnostics
and fails before plugin import.
Hard dependencies remain visible. Manual overrides take precedence over filtering.
Availability does not certify versions or successful scientific execution.
Executable availability follows current PATH. Python availability retains
is_installed’s cache: clear it after installation and refresh the registry before
retrying. File-based configuration changes require the existing configuration-cache
discipline; registered overrides invalidate their own cache. Recorded load failures
still need retry/refresh after configuration changes.
Load diagnostics identify the plugin, requested identity trigger and actual call site.
Fallback uses the discover() trigger. Emission failures do not discard successful
implementations or replace original load errors.
Explicit adapter inspection (from 0.15.0, #36)#
DepDigest 0.15.0 adds a keyword-only constructor policy:
adapters = DeclaredRegistry(
"my_package.formats",
"my_package/formats",
{"optional": "optional_form"},
attr_name="format_name",
load_policy="adapter",
)
adapter = adapters["optional"] # inspect Python adapter metadata
load_policy="strict" is the default and preserves the 0.14.0 pre-import soft
dependency check. Explicit "adapter" omits that check when materializing a value;
the requested adapter must still import successfully and match its declared identity.
Unknown policy values raise ValueError. This policy is selected per registry and
does not change LazyRegistry, dependency configuration, engine choice or inventory.
Current visibility remains authoritative: an absent soft engine is hidden with
SHOW_ALL_CAPABILITIES=False, including cached adapters. With all capabilities
shown, an importable adapter may expose metadata while its engine is absent.
Manual caller overrides retain their existing precedence. A plugin initializer
that eagerly imports its engine can still fail; real import and transitive errors
remain chained causes rather than being relabeled as engine absence.
The same identity, failure/success cache, retry/refresh, mutation, diagnostics and
explicit discover() rules apply to both policies and discovery modes. Discovery
in adapter policy may inspect eligible absent-engine adapters; it still imports
only when explicitly requested and may visit many implementations. Metadata-only
enumeration and selective indexed lookup retain their scope.
Importability and a successful load event certify adapter materialization only.
get_info() still reports actual engine availability. Hosts must keep
dep_digest/check_dependency at execution-dependent operations; an absent
requested engine still raises, and no alternative engine is selected. Adapter
inspection is not execution, version compatibility or scientific qualification.
This option is not in published 0.14.0. Public consumers require DepDigest
=0.15.0 after its admission under DepDigest #37; preparing these docs is not publication proof. Source experiments must pin the implementation commit. Source checks, provider publication, MolSysMT #382 adoption/conversion parity and speed measurements remain separate, coordinated in MolSysSuite #115.
Concurrent declared value requests (from 0.15.1, #39)#
On one shared registry, overlapping declared value requests wait for initialization and share the same cached implementation or failure cause. A failed request stays cached until an explicit retry/refresh. The guarantee covers strict and adapter policies, with filesystem and entry-point discovery. Unrelated plugins stay lazy; load diagnostics retain the initiating request’s identity and call site.
A reentrant lock serializes each value request through initialization, including
requests for different identities and cached values. Same-thread recursion into
the loading plugin still fails with KeyError; independent nested loads work.
Initialization remains synchronous. An initializer must not wait for another
thread that needs the same registry while it holds this lock.
Mutation, discover(), retry(), refresh(), declaration/configuration changes
and their overlap with readers require external exclusive coordination. Metadata
and views do not provide atomic multi-operation snapshots. Arbitrary cyclic
cross-registry or cross-thread import interactions are outside this guarantee.
LazyRegistry retains its existing contract.
Public adoption requires admitted DepDigest >=0.15.1, tracked in #39. Published 0.15.0 has no concurrent-access synchronization. Source qualification and public admission precede MolSysMT #382 adoption; neither establishes consumer conversion or scientific parity.