composat 1.0.0__tar.gz

composat-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HivertMoZara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

composat-1.0.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: composat
+Version: 1.0.0
+Summary: Component lifespan interface
+Keywords: asyncio,component,dependency-injection,lifecycle,plugin,reload
+Author-Email: HivertMoZara <worldmozara@163.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/NCBM/composat
+Project-URL: Repository, https://github.com/NCBM/composat
+Project-URL: Issues, https://github.com/NCBM/composat/issues
+Requires-Python: >=3.12
+Requires-Dist: typing-extensions>=4.16.0
+Description-Content-Type: text/markdown
+
+# 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
+
+```python
+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
+
+```python
+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:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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`](https://github.com/NCBM/composat/blob/main/.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.

composat-1.0.0/README.md

@@ -0,0 +1,167 @@
+# 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
+
+```python
+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
+
+```python
+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:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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`](https://github.com/NCBM/composat/blob/main/.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.

composat-1.0.0/pyproject.toml

@@ -0,0 +1,126 @@
+[project]
+name = "composat"
+version = "1.0.0"
+description = "Component lifespan interface"
+keywords = [
+    "asyncio",
+    "component",
+    "dependency-injection",
+    "lifecycle",
+    "plugin",
+    "reload",
+]
+authors = [
+    { name = "HivertMoZara", email = "worldmozara@163.com" },
+]
+dependencies = [
+    "typing-extensions>=4.16.0",
+]
+requires-python = ">=3.12"
+readme = "README.md"
+license = "MIT"
+license-files = [
+    "LICENSE",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/NCBM/composat"
+Repository = "https://github.com/NCBM/composat"
+Issues = "https://github.com/NCBM/composat/issues"
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.40.2",
+    "hypothesis>=6.170.14",
+    "pytest>=9.1.1",
+    "ruff>=0.17.0",
+]
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.basedpyright]
+typeCheckingMode = "recommended"
+failOnWarnings = true
+pythonVersion = "3.12"
+
+[tool.pdm]
+distribution = true
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+    "examples",
+]
+pythonpath = [
+    "src",
+]
+addopts = "--strict-markers"
+filterwarnings = [
+    "error::RuntimeWarning",
+]
+
+[tool.ruff]
+src = [
+    "src",
+    "tests",
+    "examples",
+]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "C4",
+    "SIM",
+    "RUF",
+    "PERF",
+    "PIE",
+    "RET",
+    "N",
+    "PTH",
+    "TID",
+    "FURB",
+    "FLY",
+    "ISC",
+    "T20",
+    "DTZ",
+    "LOG",
+    "G",
+    "BLE",
+    "PT",
+    "S",
+    "ANN",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",
+    "PT011",
+    "PT018",
+]
+"examples/**" = [
+    "S101",
+    "PT011",
+    "PT018",
+]

composat-1.0.0/src/composat/__init__.py

@@ -0,0 +1,70 @@
+"""composat: a component lifespan interface.
+
+An assembly brings instances up and takes them down in dependency order, and the modules here are the
+layers it stands on — identities and keys, effect scopes, the call level that says whose work a read
+belongs to and where its effects end, the component base and what it declares, the state machine and
+the manager that drives it, the dependency graph, the registry of declarations, and the assembly: the
+table of what is up, the rule a requirement is answered by, the batch verbs that fill the table and
+empty it, the report they hand back, and the stream of moves they report while they run.
+
+``composat.std`` adds what a deployment needs on top of that: the loader that turns a path into the
+module there and the components it exports, the component that owns moving a loaded module onto a new
+generation, the wait for a swap to land, and the drain of an instance's work.
+"""
+
+from . import context as context
+from .assembly import Assembly as Assembly
+from .assembly import AssemblyResult as AssemblyResult
+from .assembly import Candidates as Candidates
+from .assembly import Claim as Claim
+from .assembly import Event as Event
+from .assembly import Policy as Policy
+from .assembly import Replacement as Replacement
+from .assembly import answering_from as answering_from
+from .assembly import default_rule as default_rule
+from .component import LIFECYCLE_HOOKS as LIFECYCLE_HOOKS
+from .component import Component as Component
+from .component import RequirementResolver as RequirementResolver
+from .component import attach as attach
+from .component import capabilities_of as capabilities_of
+from .component import reopen_epoch as reopen_epoch
+from .component import require as require
+from .component import requirements_of as requirements_of
+from .context import CallContext as CallContext
+from .context import current as current
+from .context import current_or_none as current_or_none
+from .context import open_call as open_call
+from .context import put as put
+from .context import resolve as resolve
+from .dependency import DependencyCycleError as DependencyCycleError
+from .dependency import DependencyError as DependencyError
+from .dependency import DependencyGraph as DependencyGraph
+from .dependency import DependencyInUseError as DependencyInUseError
+from .errors import KeyInTransitError as KeyInTransitError
+from .errors import LifecycleReentryError as LifecycleReentryError
+from .errors import NoCallContextError as NoCallContextError
+from .errors import ServiceNotUpError as ServiceNotUpError
+from .errors import UnboundRequirementError as UnboundRequirementError
+from .errors import UnboundServiceError as UnboundServiceError
+from .identity import ComponentIdentity as ComponentIdentity
+from .identity import ComponentKey as ComponentKey
+from .loader import LoadedUnit as LoadedUnit
+from .loader import Unit as Unit
+from .loader import components_of as components_of
+from .loader import fingerprint_of as fingerprint_of
+from .loader import load_unit as load_unit
+from .loader import load_units as load_units
+from .loader import loaded_unit as loaded_unit
+from .manager import ComponentManager as ComponentManager
+from .registry import ComponentRegistry as ComponentRegistry
+from .registry import Declaration as Declaration
+from .scope import EffectScope as EffectScope
+from .scope import Reclaimable as Reclaimable
+from .scope import name_of as name_of
+from .spec import RequirementSpec as RequirementSpec
+from .state import Committed as Committed
+from .state import ComponentState as ComponentState
+from .state import ComponentStateControl as ComponentStateControl
+from .state import ComponentStateError as ComponentStateError
+from .state import Migration as Migration
+from .state import Operation as Operation