Skip to main content
Yanked

This release has been yanked by its maintainers, and will be ignored by installers, except when explicitly specified.
Consider using release 1.0.2 instead.

composat

A component lifespan interface. Components declare what they need, an application declares what exists, and an assembly brings instances up and takes them down: it fills a table in dependency order, reports what happened, and keeps a key answering through a swap.

Requires Python 3.12+.

A component

from composat import Component, require


class Store(Component): ...


class Engine(Component):
    store: Store = require()

A field marked with require() is a requirement, and its annotation says what the field reads as. Nothing is inferred from the annotation's shape, so an ordinary field stays ordinary. Reading the field answers the instance that provides it, at the reader's own key — it is a live read, not a copy taken at construction. The annotation may name a class defined further down the module: the requirement is settled the first time anything asks the class what it requires.

The framework drives six hooks — load, unload, reload, enable, disable, drain — and a type that writes none of them is one nothing drives. A hook is written with @override, which is also what turns a misspelled hook into a checker error instead of a hook that silently never runs.

Declaring and running

from composat import Assembly, ComponentIdentity, ComponentKey, ComponentRegistry, Declaration

registry = ComponentRegistry()
_ = registry.declare_all((Declaration(Store), Declaration(Engine)))
assembly = Assembly(registry, up={})

key = ComponentKey(ComponentIdentity.of(Engine))
result = await assembly.start(key)  # brings Store up too: what a requirement needs is the closure
assert result.ok
await assembly.stop(*result.completed)  # what this batch built, not what it named

Neither batch verb raises for what a component did: both report it, so one tenant's broken configuration stays that tenant's problem. strict=True is the other reading of the same batch — what that call brought up is taken back down, and the original failure goes on to the caller. assembly.replace(key, Declaration(NewEngine)) puts a new generation behind a key without a gap in what the key answers. A reader that arrives in such a window meets a generation that is built and not yet serving: composat.std.wait.serving(assembly, key) waits it out, and refuses a key that rests below serving with no move taking it there instead of spending its deadline on it.

The verbs are one vocabulary:

verb what it is for
start(*keys, enable=True, strict=False) the keys named and what they require, built — serving unless told otherwise
stop(*keys) the keys named, taken down; a key that is not up is passed over, so stop(*assembly.keys()) is the teardown a host runs unconditionally
migrate(*keys, to=level) the keys named, moved to a level an assembly holds: LOADED, DRAINING or ENABLED
enable(*keys) that move, to serving
quiesce(*keys) that move, out of service and still built: what enable puts back
admit(*declarations, enable=True) a declaration and the batch that brings it up, as one call
evict(*keys) a key taken down and its declaration withdrawn: the other end of admit
replace(key, declaration) a new generation behind a key that is serving; the instance, or a Replacement when part of it did not go through

What a key is between levels is readable as well: Assembly.in_transit(key) answers what a move is doing to it and where that move ends, which is how a reader tells a swap worth waiting out from a teardown worth failing on. docs/best-practices/ is what to do with that when a request arrives in the middle of one.

A key is an identity plus a qualifier: ComponentIdentity is the class's own path (module.qualname), and the qualifier is whatever tells instances of it apart — a tenant, a row id, or nothing at all. Declaration(Store, instance="tenant-a") is how a deployment puts an instance at one, and args/kwargs are passed to the component's constructor as they are.

Loading a directory

load_units(root) answers one Unit per module: the module, the component classes its entry namespace holds, and a hash of its source. Declaring what those hold is the application's, and so is deciding which of them are roots:

from composat import Declaration, load_units

for unit in load_units(root):
    _ = registry.declare_all(Declaration(cls) for cls in unit.components)

result = await assembly.start(*roots)  # the rest come up as requirements of these

Which keys are roots is a deployment decision: a manifest can be grown in stages, and "nothing needs it" then does not mean "it should be up". Tolerating one broken module is also the caller's — load_unit raises, so the policy is written in a loop with a try in it.

Editing a running module

composat.std.pluggable.UnitLoader holds the modules one root loaded and answers which of them no longer match their source. It is a component, declared like any other:

from composat import Declaration
from composat.std.pluggable import UnitLoader

_ = registry.declare_all((Declaration(UnitLoader, args=(root,)),))

Two verbs, because moving code and moving instances are two decisions:

for name in loader.stale():
    _ = loader.reload_module(name)  # a new generation of the module, under the same name
    _ = await loader.swap_instances(assembly, name)  # every key built from the old one, on the new

A reload replaces the classes, not the module's globals: what has to survive a generation belongs outside the module and is restored in load. A unit whose class the edit renamed has no counterpart to swap to, and is reported.

What this is not

These are the boundaries a reader needs before choosing. The refusals that cost a design argument are recorded in docs/adr/, each with the alternatives it turned down.

  • A discovery mechanism. The framework loads the paths it is handed; it does not go looking for components in entry points, in a directory or in configuration.
  • A version axis. An identity is module.qualname; which version a deployment runs is decided where the classes are declared.
  • A file watcher. composat.std.pluggable answers what a module's source says now and how to move a generation; the loop, the debounce and the ignore rules are the application's.
  • An event dispatcher. Priorities, rules, permissions and session continuation are a loop the application writes — including a plugin registering its matchers into a shared dispatcher.
  • A configuration system. The framework does not read the application's self-description (author, description, version, a schema), and has no settings of its own.
  • A runtime. It does not run a loop, a scheduler or a server; it is driven from the one the application already has, and timed work beyond a one-shot EffectScope.after is the application's.
  • Reactive or conditional requirements. A requirement is declared and unconditional; there is no activation on demand, no requirement that applies to some callers only, and no lexical isolation between components.
  • Surgery on a host application. It does not reach into another framework's cache or registry to take a component over: a component is declared to this assembly, not captured from somewhere else.
  • An introspection tool. A batch answers with a report, a move with an event, and the table with what is up now — "why is this key not here" is a record the application keeps itself.
  • Effect bookkeeping beyond a scope. A scope holds what was registered on it and answers the names of those effects; there are no effect labels, no hierarchy and no global ledger.
  • A swap across identities. replace moves one key to a new class at the same identity; replacing a tree of keys in one step is not offered.

The gate

The checks a change has to pass are the ones in .github/workflows/checks.yml; pdm install -G dev at the root installs what they need.

Documentation

file what it holds
docs/architecture.md how the layers fit, the direction of imports, and what holds across modules
docs/adr/ the decisions behind those shapes, numbered in the order they were made, with the alternatives each refused
docs/best-practices/ what to do with the shapes: the verbs a host calls and their order, how a request reads through a swap, what a replaced component registers, and how a directory of code is reloaded
examples/README.md one row per shape an application takes, each a working directory
CHANGELOG.md what changed in each release

There is no separate API reference: a public symbol's docstring is the reference, and the pages above point into the code.

Metadata

Release files for composat 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for composat 1.0.0
File Size Uploaded Provenance Actions
composat-1.0.0.tar.gz 117.3 kB With provenance Details for composat-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for composat 1.0.0
File Interpreter ABI Platform Actions
composat-1.0.0-py3-none-any.whl Python 3 none any Details for composat-1.0.0-py3-none-any.whl

Total release size: 199.0 kB

Release files / composat-1.0.0.tar.gz

Download URL composat-1.0.0.tar.gz
Size 117.3 kB
Tags Source
SHA-256 checksum
How to use checksums
d851f47db2f2ba869e9237ff766d4e03ed2e410721e6a26017ed514b67548ee7
BLAKE2b-256 checksum
How to use checksums
8676c7d8454c624615e9580b2023b75a6696af6cb201fdce5b5c4e59fd37b369
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / composat-1.0.0-py3-none-any.whl

Download URL composat-1.0.0-py3-none-any.whl
Size 81.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dc71142d01e995b33ae83e5c30c616702bc65a94eda5509e5fa317f5a30654a9
BLAKE2b-256 checksum
How to use checksums
84860468be9e856c81d775d872f4d4b459b85b501e4009d17d495e20e58af089
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Security for composat 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for composat-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page