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.pluggableanswers 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.afteris 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.
replacemoves 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.