On this page

• SpellBinder
  • SpellBinder
    • SpellBinder.cleanup()
    • SpellBinder.bind()
    • SpellBinder.with_existence()
    • SpellBinder.as_unique()
    • SpellBinder.as_many()
    • SpellBinder.as_unique_per_conduit()
    • SpellBinder.as_unique_per_conduit_cluster()
    • SpellBinder.as_unique_per_conduit_lineage()
    • SpellBinder.as_unique_per_spell_space()
    • SpellBinder.with_permissions()
    • SpellBinder.under_spellframe()
    • SpellBinder.named()
    • SpellBinder.with_kwargs()
    • SpellBinder.with_pre_hook()
    • SpellBinder.with_pre_hooks()
    • SpellBinder.with_activation_hook()
    • SpellBinder.with_activation_hooks()
    • SpellBinder.with_post_hook()
    • SpellBinder.with_post_hooks()
    • SpellBinder.finalize()

SpellBinder

Use md.SpellBinder from the public package namespace.

Implementation source

class SpellBinder(spellbook: Spellbook, *, default_existence: Existence = Existence.unique, default_permissions: str = 'create', default_profile: str = 'general')

Fluent registration helper for configuring one Spellbook bind operation at a time.

SpellBinder is a temporary configuration object layered on top of Spellbook.bind(...). It accumulates bind-time choices such as existence, permissions, spellframe, binding name, and hook lists, then forwards the assembled payload only when finalize() is called.

Contract:

• Holds in-flight configuration for exactly one pending registration at a time.

• bind(...) resets any unfinished state before targeting a new spell.

• finalize() delegates the assembled payload to Spellbook.bind(...) and then resets the binder for reuse.

• Uses a weak reference to the target Spellbook, so the binder does not own Spellbook lifetime.

• Becomes permanently unusable after cleanup() completes.

Guardrails:

• Only one registration can be active at a time; every bind(...) call resets any in-flight state.

• All fluent methods guard with check_cleaned() plus live Spellbook resolution and raise RuntimeError if the binder has been cleaned or its Spellbook weak reference is dead.

• Uses an internal RLock to serialize binder mutation and cleanup.

• cleanup() is idempotent but permanently invalidates the binder for further use.

Registration:

MELDER KERNEL - guarded. Obtained from a Spellbook; a fluent adapter over bind(...).

Subsystem Context:

The fluent alternative to calling Spellbook.bind(...) with a long argument list. It accumulates bind-time choices and forwards them only at finalize().

System Context:

The WEAK REFERENCE to the target Spellbook is the design decision worth noticing: a binder is a transient authoring helper, and holding a strong reference would let a forgotten binder keep an entire spellbook - and through it a frame's worth of runtime - alive. Every fluent method therefore resolves the live spellbook and raises if it is gone, rather than operating against a book the runtime has already released. ONE registration at a time, with bind(...) RESETTING any unfinished state, is the second guardrail. A binder that accumulated across targets could silently carry one spell's permissions onto the next; resetting makes each registration independent, and the reset-after-finalize keeps the object safely reusable.

AGENT_ACCESS: public

AGENT_PURPOSE:

access: public. Fluent alternative to Spellbook.bind(...). Chain the bind-time choices then finalize() to submit. Holds one pending registration at a time; bind(...) resets in-flight state. Holds the Spellbook weakly.

cleanup() → None

Deterministically cleans up the SpellBinder.

Releases the weak reference to the Spellbook and clears all internal states. After cleanup, this instance cannot be used; subsequent API calls will fail via check_cleaned() / live Spellbook resolution. The method is idempotent.

Contract:

• IDEMPOTENT under double-checked locking: it returns immediately if already cleaned, then re-checks inside the lock so concurrent callers cannot both run teardown.

• Releases only binder-owned state; the spellbook it binds into is BORROWED and is not cleaned here.

Threading:

Double-checked around the binder lock.

Lifecycle / Cleanup:

Safe to call more than once and from more than one thread.

Returns:

None.

bind(spell: Any, *, existence: Existence | None = None, permissions: str | None = None, profile: str | None = None, spellframe: Any | None = None, binding_name: str | None = None, **kwargs: Any) → SpellBinder

Start a new fluent registration chain for one spell target.

Contract:

• Clears any previous unfinished registration state before targeting the provided spell.

• Reinitialize existence, permissions, and profile to the defaults captured at binder construction time.

• Applies any immediate overrides supplied in the call itself.

• Merges passthrough kwargs into the payload later sent to Spellbook.bind(...); later values overwrite earlier keys.

Parameters:

• spell (Any) -- The class, function, or object to register.

• existence (Existence, optional) -- Immediate override for lifecycle scope.

• permissions (str, optional) -- Immediate override for access permissions.

• profile (str, optional) -- Immediate override for the spell profile family.

• spellframe (Any, optional) -- Interface, protocol, or other frame key for the registration.

• binding_name (str, optional) -- Secondary key used to disambiguate this binding.

• **kwargs -- Passthrough bind-time keyword arguments, including lifecycle hooks.

Returns:

This binder instance so the caller can continue the fluent chain.

Return type:

SpellBinder

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weak reference is no longer alive.

with_existence(existence: Existence) → SpellBinder

Manually set the Existence lifecycle for this registration.

Use this if you need a specific existence mode not covered by the convenience methods below (e.g., a custom extension).

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weakener is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

Parameters:

existence -- Existence member or its string name setting instance lifetime.

as_unique() → SpellBinder

Configures the spell as a Global Singleton (Unique per Aetheric Frame).

Behaviour:

• Only one instance is created for the entire Aetheric Frame.

• Shared by ALL conduits in that frame.

Use Case:

• Global configuration managers.

• Heavy, thread-safe resources (e.g., Database Connection Pools).

• Centralized logging or telemetry services.

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weakener is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

as_many() → SpellBinder

Configures the spell as Transient (Many Instances).

Behaviour:

• A new instance is created every time it is requested.

• No caching occurs.

Use Case:

• Lightweight, stateless objects.

• Request-specific data holders.

• Objects that are cheap to create and should not be shared.

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weakener is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

as_unique_per_conduit() → SpellBinder

Configures the spell as Scoped to Conduit.

Behaviour:

• Each Conduit gets its own unique instance.

• Within a single Conduit, the instance is reused (singleton-per-conduit).

Use Case:

• Conduit-local caches.

• Services that maintain state specific to a specific module or plugin.

• Is isolating "sub-applications" from one another.

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weakener is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

as_unique_per_conduit_cluster() → SpellBinder

Configures the spell as Scoped to Cluster.

Behaviour:

• Conduits in the same named cluster share a single instance.

• Conduits in different clusters get different instances.

Use Case:

• Sharing resources across a specific subsystem (e.g., "AuthCluster").

• Grouping related services that need a shared state but shouldn't leak globally.

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weakener is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

as_unique_per_conduit_lineage() → SpellBinder

Configures the spell as Scoped to Lineage (Hierarchical).

Behaviour:

• An instance is shared down a specific parent -> child -> grandchild chain.

• Useful for recursive structures or inheritance-based contexts.

Use Case:

• Context propagation in a specific execution tree.

• Sharing configuration overrides down a specific branch of the graph.

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weakener is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

as_unique_per_spell_space() → SpellBinder

Configures the spell as Scoped to SpellSpace (Session/Request).

Behaviour:

• The instance lives only as long as the manually managed SpellSpace.

• When the space is closed/reset, the instance is discarded.

Use Case:

• Per-request handling (e.g., HTTP Request context).

• Batch processing jobs where the state must be cleared between batches.

• "Unit of Work" patterns where objects must live for a transaction duration.

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weakref is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

with_permissions(permissions: str) → SpellBinder

Set the access permissions for the pending registration.

Contract:

• Stores the raw permission string for later validation inside Spellbook.bind(...).

• Does not normalize or validate the permission value by itself.

• Overwrites any permission value already staged on this binder.

Typical values:

• create

• read

• block

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weak reference is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

Parameters:

permissions -- Permissions member or its string name setting the capability ceiling for this lineage.

under_spellframe(spellframe: Any) → SpellBinder

Stage a spellframe for the pending registration.

Purpose:

Bind the pending spell under a shared interface, protocol, or other frame key so downstream resolution can target the frame instead of the concrete implementation directly.

Parameters:

spellframe (Any) -- Protocol, abstract base class, or other frame key to associate with the pending registration.

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weak reference is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

named(binding_name: str) → SpellBinder

Stage a binding name for the pending registration.

Purpose:

Disambiguate multiple registrations that share the same spellframe but should still resolve as distinct bindings.

Parameters:

binding_name (str) -- Secondary key for the pending registration.

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weak reference is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

with_kwargs(**kwargs: Any) → SpellBinder

Pass arbitrary keyword arguments directly to the Spellbook's bind method.

This acts as a catch-all for advanced or future parameters that might not have dedicated fluent methods yet.

Later calls override existing keys in the passthrough payload.

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weakener is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

with_pre_hook(hook: Callable[[...], Any]) → SpellBinder

Adds a Pre-Cast Hook.

Executed before the object is instantiated. Useful for validation, logging, or setting up thread-local context.

Hooks are appended in call order; callability is validated later by Spellbook.bind(...) when the registration is finalized.

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weakener is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

Parameters:

hook -- Callable invoked before the spell is constructed.

with_pre_hooks(*hooks: Callable[[...], Any]) → SpellBinder

Adds multiple Pre-Cast Hooks at once, preserving the provided order.

An empty invocation is a no-op. Hook callability is validated later by Spellbook.bind(...).

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weakener is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

with_activation_hook(hook: Callable[[...], Any]) → SpellBinder

Adds an Activation Hook.

Executed during instantiation (or immediately after). Useful for setter injection, initialization logic, or wiring up event listeners. Receives the instance as an argument.

Hooks are appended in call order; callability is validated later by Spellbook.bind(...).

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weakener is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

Parameters:

hook -- Callable invoked when the spell is activated.

with_activation_hooks(*hooks: Callable[[...], Any]) → SpellBinder

Adds multiple Activation Hooks at once, preserving the provided order.

An empty invocation is a no-op. Hook callability is validated later by Spellbook.bind(...).

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weakener is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

with_post_hook(hook: Callable[[...], Any]) → SpellBinder

Adds a Post-Cast Hook.

Executed after the object is fully ready and returned to the system. Useful for final validation or registration with external systems.

Hooks are appended in call order; callability is validated later by Spellbook.bind(...).

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weakener is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

Parameters:

hook -- Callable invoked after construction completes.

with_post_hooks(*hooks: Callable[[...], Any]) → SpellBinder

Adds multiple Post-Cast Hooks at once, preserving the provided order.

An empty invocation is a no-op. Hook callability is validated later by Spellbook.bind(...).

Raises:

RuntimeError -- If the binder has been cleaned or its Spellbook weakener is dead.

Returns:

This binder, for fluent chaining. Call finalize() to submit the

assembled registration to the Spellbook.

Return type:

SpellBinder

finalize() → str

Commit the current fluent configuration into the target Spellbook.

Contract:

• Requires a prior bind(...) call to have selected a spell target.

• Delegates the assembled payload to Spellbook.bind(...).

• Resets the binder's in-flight state after a successful bind so the instance can be reused for another registration.

• Propagates any staged hook lists and passthrough kwargs directly into the underlying Spellbook bind call.

Returns:

The unique SHA256 spell_id of the registered spell.

Return type:

str

Raises:

• RuntimeError -- If called without first calling bind(), or if the binder has been cleaned or its Spellbook weak reference is dead.

• Exception -- Any error raised by Spellbook.bind(...), such as duplicate bindings or invalid hook payloads.

Topic reference · Full contents