On this page

• scan_bind
  • scan_bind()

scan_bind

Use md.scan_bind from the public package namespace.

Implementation source

scan_bind(*, existence: Existence | str, permissions: Permissions | str, spellframe: Any = None, binding_name: str | None = None, profile: str = 'general', pre_hooks: Sequence[Callable[[...], Any]] | None = None, activation_hooks: Sequence[Callable[[...], Any]] | None = None, post_hooks: Sequence[Callable[[...], Any]] | None = None, resolvable: bool = True, disposal_method_names: Sequence[str] | None = None, managed_spell_mode: ManagedSpellMode | str | None = None, managed_spell_limit: int | None = None, managed_spell_timeout_seconds: float | None = None, managed_spell_reset_methods: Sequence[str] | None = None, **spell_metadata: Any) → Callable[[Any], Any]

Attaches explicit binding metadata to a class/function for module scanning.

This decorator does not bind anything by itself. It only stores the metadata needed by Scan.scan_module(...) or Spellbook.scan(...).

Runtime model:

• decoration time: capture binding intent only

• scan time: verify module ownership and re-export rules

• bind time: delegate to Spellbook.bind for actual registration

Contract:

• Returns a decorator that leaves the target object otherwise unchanged.

• Stores one immutable ScanBindMetadata payload on the decorated object under the reserved scan-bind attribute.

• Does not register anything, allocate Spell objects, or talk to a Spellbook directly.

• Hook values are validated immediately so invalid metadata does not sit silently on the object until module scan time.

• Accepts every option Spellbook.bind accepts for a target, with the same defaults: resolvable, per-target disposal_method_names, the four managed options and keyword application metadata. A scan replays them through Spellbook.bind, so a scanned registration matches a direct bind of the same target with the same options.

• Intentional differences from direct binding: permissions is required here (direct bind defaults to "create"), and hook groups, disposal-name groups and metadata keys are checked now, at decoration, rather than when the module is scanned.

• resolvable is stored exactly as given, with no truthiness coercion; Bind's strict bool check and its Protocol rules apply at scan time.

• Disposal names and metadata are snapshotted: later changes to the caller's list or dict do not reach the declaration. Metadata values are kept by identity (a shallow copy), never copied or frozen.

• Only the decorated object itself carries the declaration. Subclasses and instances of a decorated class are not scan targets unless they are decorated themselves.

Parameters:

• existence (Union[Existence, str]) -- Explicit lifecycle scope for the spell (required).

• permissions (Union[Permissions, str]) -- Explicit permissions for the spell (required).

• spellframe (Any, optional) -- Optional spellframe/Protocol grouping key.

• binding_name (Optional[str]) -- Optional binding name for disambiguation.

• profile (str) -- Spell profile family to attach after bind completion.

• pre_hooks (Optional[Sequence[Callable[..., Any]]]) -- Optional pre-activation hooks.

• activation_hooks (Optional[Sequence[Callable[..., Any]]]) -- Optional activation hooks.

• post_hooks (Optional[Sequence[Callable[..., Any]]]) -- Optional post-activation hooks.

• resolvable (bool) -- Native per-version resolution capability, default True. False registers a non-resolvable definition, such as a Protocol that implementations are checked against. Forwarded unchanged to Spellbook.bind.

• disposal_method_names (Optional[Sequence[str]]) -- Ordered per-target disposal candidates, as a list or tuple of method names. At scan time they combine with the Book's configured candidates exactly as in Spellbook.bind; None and an empty group both leave the Book's candidates in force.

• managed_spell_mode (Optional[Union[ManagedSpellMode, str]]) -- Pool policy of an Existence.managed_spell_quantity target (elastic by default).

• managed_spell_limit (Optional[int]) -- elastic: the most idle objects kept (default 256); limited_quantity and queue: the most objects alive at once (required).

• managed_spell_timeout_seconds (Optional[float]) -- queue only, required there: how long a lease waits for a release.

• managed_spell_reset_methods (Optional[Sequence[str]]) -- Zero-argument methods run on every release, as a list or tuple of names (checked here); the other managed rules are Bind's, at scan time.

• **spell_metadata (Any) -- Application metadata for the registered Spell (Spell.metadata), as direct bind stores its extra keywords. Keys that the bind pipeline takes natively (ScanBindMetadata.RESERVED_SPELL_METADATA_KEYS) are refused.

Returns:

A decorator that tags the target object.

Return type:

Callable[[Any], Any]

Raises:

• ValueError -- If existence or permissions is None.

• TypeError -- If any hook list is not a list/tuple of callables, if disposal_method_names or managed_spell_reset_methods is not a list/tuple of strings, or if a metadata key is reserved.

Topic reference · Full contents