Skip to content

yggdrasil.disposable

disposable

Disposable 

Disposable(*args, **kwargs)

Bases: ABC

Transactional resource with binary open/close, with-stack nesting, and an owned-children graph.

Reopenable: subclasses inheriting from :class:Disposable are expected to support being reopened after :meth:close. Calling :meth:open on a closed instance must restore it to a fresh, usable state — the same instance can cycle through open → close → open → close any number of times. Subclass :meth:_acquire / :meth:_release implementations must therefore avoid one-shot state that would prevent a subsequent :meth:_acquire from succeeding (e.g. don't null out config the next open will need, and don't leave latch-style flags set after teardown). A with block on a previously-closed instance must reopen it cleanly.

opened property 

opened: bool

True iff :meth:_acquire has run and :meth:_release hasn't.

closed property 

closed: bool

Inverse of :attr:opened.

open 

open() -> 'Disposable'

Acquire the resource and cascade into owned children.

Order:

  1. Run our own :meth:_acquire (subclass body).
  2. Flip :attr:opened to True and mark _self_opened.

  3. For each owned child, in registration order:

  4. If the child is already opened, just :meth:_claim it. It stays self-opened — the existing self-open is what keeps it alive after we let go.

  5. Otherwise, call :meth:open on the child (which recursively cascades into ITS owned children), then clear the child's _self_opened flag so the child knows its open is parent-driven, then :meth:_claim it. Without that flag clear, the eventual :meth:_unclaim would refuse to close — it would see "I'm self-opened, someone explicitly opened me, leave me alone."

Both branches record the child in our per-frame scratch list so :meth:_release knows what to unclaim.

Transactional rollback: if any child's open or claim raises, we walk back through the children we already touched (in reverse), unclaim each, then call our own :meth:_release with committed=False and re-raise the original exception. From the caller's view, the open atomically either succeeded with the whole graph live, or failed with nothing changed.

Not reentrant: raises :class:RuntimeError if already opened. Nesting is expressed via with self: blocks, not via paired :meth:open calls.

commit 

commit()

Commit current state

rollback 

rollback()

Rollback current state

close 

close(force: bool = False) -> None

Release the resource and cascade into owned children.

Order:

  1. If currently held open by an outside parent claim (_claim_count > 0) AND we are not in self-opened state, this is a no-op — the parents that opened us still need us live. (Handled inside :meth:_do_close.)
  2. Walk our scratch list of acquired children in REVERSE registration order; :meth:_unclaim each. A child whose claim count hits zero and isn't otherwise self-opened closes itself.
  3. Run :meth:_before_release, then :meth:_release — with committed reflecting the dirty bit (cleared on exception by __exit__).

Idempotent: no-op when already closed, unless force.

force=True runs teardown even when :attr:closed. Intended for error-recovery paths where subclass state might be inconsistent.

Does NOT touch :attr:depth — the with-stack counter belongs to :meth:__enter__/:meth:__exit__ exclusively. If a caller calls :meth:close inside an active with block, the outer :meth:__exit__ will harmlessly skip the now-no-op close on unwind.

mark_dirty 

mark_dirty() -> None

Signal pending mutations — commit on next clean :meth:close.