facetkit 0.3.0__tar.gz → 0.4.0__tar.gz

{facetkit-0.3.0 → facetkit-0.4.0}/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-06-21
+
+### Changed
+
+- `mount_facet` was renamed to `bind_facet`
+- `unmount_facet` was renamed to `unbind_facet`
+- `add_component` was renamed to `bind_component`
+- `remove_component` was renamed to `unbind_component`
+- `attach` was renamed to `on_bind`
+- `detach` was renamed to `on_unbind`
+- Function signature for facet functions were normalized to use *_id params
+- Container bind/unbind methods now take `facet_id` and `component_id`
+- `DependentComponentsError` was renamed to `ComponentInUseError`
+- Exception attributes normalized to `facet_id` / `component_id`
+- GUI descriptor and method `parent` renamed to `parent_id`
+- Descriptor identity fields normalized to `id`
+
+[0.4.0]: https://github.com/Dev-DanielR/py_facetkit/releases/tag/v0.4.0
+
 ## [0.3.0] - 2026-06-20
 
 ### Added

{facetkit-0.3.0 → facetkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: facetkit
-Version: 0.3.0
+Version: 0.4.0
 Summary: A composable dependency container with passive UI and service facets.
 Author-email: "Daniel R. Vásquez Montes" <dev.DanielR@gmail.composable>
 License: MIT
@@ -32,9 +32,9 @@ facetkit separates three pieces:
 
 | Piece | Role |
 |-------|------|
-| [Container](docs/container.md) | Application root — config, facet mounting, component lifecycle |
+| [Container](docs/container.md) | Application root — config, facet & component binding |
 | [Facet](docs/facet.md) | Passive registry for a surface area (commands, routes, widgets, …) |
-| [Component](docs/component.md) | Plugin that registers into facets on attach and cleans up on detach |
+| [Component](docs/component.md) | Plugin that connects to one or several facets in on_bind and cleans up in on_unbind  |
 
 ```
 Container
@@ -74,8 +74,8 @@ from facetkit import Container, CliFacet, WebFacet
 
 app = Container({"app": {"name": "demo"}})
 
-app.mount_facet("cli", CliFacet())
-app.mount_facet("web", WebFacet())
+app.bind_facet("cli", CliFacet())
+app.bind_facet("web", WebFacet())
 
 def hello():
     """Say hello."""
@@ -90,8 +90,8 @@ Register directly on facets (as above) or through [components](docs/component.md
 ## Documentation
 
 - [Container](docs/container.md) — config, lifecycle, introspection
-- [Facets](docs/facet.md) — facet types, registries, mounting
-- [Components](docs/component.md) — attach/detach, dependencies
+- [Facets](docs/facet.md) — facet types, registries, binding
+- [Components](docs/component.md) — on_bind/on_unbind, dependencies
 - [Examples](docs/examples/composed_app.py) — composed app with logger and status components
 
 ## Development
@@ -101,7 +101,7 @@ pip install -e ".[dev]"
 pytest
 ```
 
-See [CHANGELOG.md](CHANGELOG.md) for release notes. Pre-1.0 (`0.3.0`) — public APIs may change between minor releases.
+See [CHANGELOG.md](CHANGELOG.md) for release notes. Pre-1.0 (`0.4.0`) — public APIs may change between minor releases.
 
 ## License
 

{facetkit-0.3.0 → facetkit-0.4.0}/README.md

@@ -6,9 +6,9 @@ facetkit separates three pieces:
 
 | Piece | Role |
 |-------|------|
-| [Container](docs/container.md) | Application root — config, facet mounting, component lifecycle |
+| [Container](docs/container.md) | Application root — config, facet & component binding |
 | [Facet](docs/facet.md) | Passive registry for a surface area (commands, routes, widgets, …) |
-| [Component](docs/component.md) | Plugin that registers into facets on attach and cleans up on detach |
+| [Component](docs/component.md) | Plugin that connects to one or several facets in on_bind and cleans up in on_unbind  |
 
 ```
 Container
@@ -48,8 +48,8 @@ from facetkit import Container, CliFacet, WebFacet
 
 app = Container({"app": {"name": "demo"}})
 
-app.mount_facet("cli", CliFacet())
-app.mount_facet("web", WebFacet())
+app.bind_facet("cli", CliFacet())
+app.bind_facet("web", WebFacet())
 
 def hello():
     """Say hello."""
@@ -64,8 +64,8 @@ Register directly on facets (as above) or through [components](docs/component.md
 ## Documentation
 
 - [Container](docs/container.md) — config, lifecycle, introspection
-- [Facets](docs/facet.md) — facet types, registries, mounting
-- [Components](docs/component.md) — attach/detach, dependencies
+- [Facets](docs/facet.md) — facet types, registries, binding
+- [Components](docs/component.md) — on_bind/on_unbind, dependencies
 - [Examples](docs/examples/composed_app.py) — composed app with logger and status components
 
 ## Development
@@ -75,7 +75,7 @@ pip install -e ".[dev]"
 pytest
 ```
 
-See [CHANGELOG.md](CHANGELOG.md) for release notes. Pre-1.0 (`0.3.0`) — public APIs may change between minor releases.
+See [CHANGELOG.md](CHANGELOG.md) for release notes. Pre-1.0 (`0.4.0`) — public APIs may change between minor releases.
 
 ## License
 

facetkit-0.4.0/docs/component.md

@@ -0,0 +1,124 @@
+# Components
+
+A **Component** is an active plugin that connects to one or several [facets](facet.md) in `on_bind` and cleans up in `on_unbind`. This keeps feature setup and teardown in one place instead of scattered across your application.
+
+## Types and exceptions
+
+**Protocol**
+
+```python
+class MyComponent:
+    def on_bind(self, container): ...
+    def on_unbind(self, container): ...
+```
+
+Optional class attributes — see [Declared dependencies](#declared-dependencies).
+
+**Exceptions**
+
+| Exception | When | Attributes |
+|-----------|------|------------|
+| `DuplicateComponentError` | `bind_component(overwrite=False)` | `.component_id` |
+| `MissingComponentDependencyError` | `bind_component` — required component absent | `.component_id`, `.missing` |
+| `MissingFacetDependencyError` | `bind_component` — required facet not bound | `.component_id`, `.missing` |
+| `ComponentInUseError` | `unbind_component` — another component depends on it | `.component_id`, `.dependents` |
+
+`FacetInUseError` (raised on `unbind_facet`) is documented in [Facets](facet.md).
+
+## Lifecycle
+
+Components are bound and unbound through the container:
+
+```python
+from facetkit import Container, CliFacet, ServiceFacet
+
+class StatusComponent:
+    required_facets = ("cli", "service")
+
+    def on_bind(self, container):
+        container.facets["cli"].add_command("status", self.show_status)
+        container.facets["service"].add_provider("status", {"healthy": True})
+
+    def on_unbind(self, container):
+        container.facets["cli"].remove_command("status")
+        container.facets["service"].remove_provider("status")
+
+    def show_status(self):
+        """Show application status."""
+        return "ok"
+
+app = Container({"app": {"name": "demo"}})
+app.bind_facet("cli", CliFacet())
+app.bind_facet("service", ServiceFacet())
+app.bind_component("status", StatusComponent())
+app.unbind_component("status")
+```
+
+**`bind_component(component_id, comp, *, overwrite=True)`** — validates declared dependencies, calls `on_bind(container)`, then stores the instance. When `overwrite=True` (the default), if a component has already been bound with the same id it is unbound without a dependent check before replacing it with the new component. Pass `overwrite=False` to raise `DuplicateComponentError` instead:
+
+```python
+app.bind_component("logger", Logger(), overwrite=False)
+```
+
+If validation fails, `on_bind` is not called.
+
+**`unbind_component(component_id)`** — calls `on_unbind(container)`, then removes the instance. Raises `ComponentInUseError` if any other bound component lists `component_id` in `required_components`.
+
+Inside `on_bind` / `on_unbind`, components typically:
+
+- Register or unregister entries on `container.facets[...]`
+- Read shared state from `container.config`
+- Reach peer plugins via `container.components["component_id"]`
+
+See [examples/composed_app.py](examples/composed_app.py) for a full walkthrough with peer dependencies and CLI dispatch.
+
+```bash
+python docs/examples/composed_app.py
+```
+
+## Declared dependencies
+
+Components can declare what must already be present before they bind. Both attributes are optional class-level tuples:
+
+```python
+class ApiComponent:
+    required_components = ("logger", "database") # peer components
+    required_facets = ("cli", "web")             # bound facet ids
+
+    def on_bind(self, container):
+        logger = container.components["logger"]
+        container.facets["cli"].add_command("api-status", self.status)
+        container.facets["web"].add_route("api-status", "/status", self.status)
+
+    def on_unbind(self, container):
+        container.facets["cli"].remove_command("api-status")
+        container.facets["web"].remove_route("api-status")
+```
+
+The container enforces these at lifecycle boundaries:
+
+| Action | Validation |
+|--------|------------|
+| `bind_component` | Every component_id in `required_components` must already be bound; every facet_id in `required_facets` must already be bound. `on_bind` is not called if anything is missing. |
+| `unbind_component` | Blocked if any other bound component lists this component_id in `required_components`. |
+| `unbind_facet` | Blocked if any bound component lists this facet_id in `required_facets`. |
+| Replace component | Allowed — dependent checks are skipped so the slot stays filled. |
+
+Register dependencies before dependents:
+
+```python
+app.bind_component("logger", LoggerComponent())
+app.bind_component("database", DatabaseComponent())
+app.bind_component("api", ApiComponent()) # OK
+
+app.bind_component("api", ApiComponent()) # raises MissingComponentDependencyError
+```
+
+Tear down in reverse:
+
+```python
+app.unbind_component("api")    # OK
+app.unbind_component("logger") # OK once api is gone
+
+app.unbind_facet("cli")       # raises FacetInUseError while a component still requires it
+```

{facetkit-0.3.0 → facetkit-0.4.0}/docs/container.md

@@ -1,75 +1,75 @@
-# Container
-
-The **Container** is the application root. It holds shared configuration, a map of [mounted facets](facet.md), and a registry of [attached components](component.md).
-
-```
-Container
-├── config          → shared application settings
-├── components      → named plugins (attach / detach lifecycle)
-└── facets          → passive registries, keyed by mount name
-```
-
-Create one at startup and pass it through your app:
-
-```python
-from facetkit import Container
-
-app = Container({"app": {"name": "demo"}, "port": 8080})
-```
-
-## Config
-
-The constructor takes a plain dict. Components and application code read it through `ctx.config` or `ctx.get("config....")`.
-
-```python
-app.config["port"]           # 8080
-app.get("config.app.name")   # "demo"
-```
-
-## Lifecycle
-
-The container exposes lifecycle methods for [facets](facet.md) (`mount_facet`, `unmount_facet`) and [components](component.md) (`add_component`, `remove_component`). Both mount and add accept an `overwrite` flag (default `True`) to control duplicate-name behavior.
-
-## Boot order
-
-Typical startup sequence:
-
-1. Create a `Container` with config
-2. `mount_facet` for each surface your app uses
-3. `add_component` for each feature plugin — register dependencies before dependents
-
-Your framework layer (argparse, FastAPI, Textual, Qt, etc.) then reads the facet registries and dispatches.
-
-## Introspection with `get()`
-
-`Container.get(path)` uses [glom](https://glom.readthedocs.io/) to read nested state:
-
-```python
-app.get("")                        # the container itself
-app.get("config.app.name")         # config values
-app.get("facets")                  # all mounted facets
-app.get("facets.cli")              # CliFacet instance
-app.get("facets.cli.commands")     # command registry
-app.get("facets.web.routes.users") # a single route entry
-```
-
-Without `default`, resolution errors propagate (missing paths, glom failures, etc.):
-
-```python
-app.get("facets.cli.commands") # works when the cli facet is mounted
-app.get("facets.missing")      # raises glom.PathAccessError
-```
-
-Pass `default` for optional lookups — any resolution error returns that value:
-
-```python
-app.get("facets.missing", default=None) # None
-app.get("facets.missing", default={})   # {}
-```
-
-Direct dict access also works when you know a facet is mounted:
-
-```python
-app.facets["cli"].commands["hello"]
-app.components["logger"]
+# Container
+
+The **Container** is the application root. It holds shared configuration, a map of [bound facets](facet.md), and a registry of [bound components](component.md).
+
+```
+Container
+├── config          → shared application settings
+├── components      → named plugins (on_bind / on_unbind lifecycle)
+└── facets          → passive registries, keyed by facet id
+```
+
+Create one at startup and pass it through your app:
+
+```python
+from facetkit import Container
+
+app = Container({"app": {"name": "demo"}, "port": 8080})
+```
+
+## Config
+
+The constructor takes a plain dict. Components and application code read it through `container.config` or `container.get("config....")`.
+
+```python
+app.config["port"]           # 8080
+app.get("config.app.name")   # "demo"
+```
+
+## Lifecycle
+
+The container exposes lifecycle methods for [facets](facet.md) (`bind_facet`, `unbind_facet`) and [components](component.md) (`bind_component`, `unbind_component`). Both bind methods accept an `overwrite` flag (default `True`) to control duplicate-id behavior.
+
+## Boot order
+
+Typical startup sequence:
+
+1. Create a `Container` with config
+2. `bind_facet` for each surface your app uses
+3. `bind_component` for each feature plugin — bind dependencies before dependents
+
+Your framework layer (argparse, FastAPI, Textual, Qt, etc.) then reads the facet registries and dispatches.
+
+## Introspection with `get()`
+
+`Container.get(path)` uses [glom](https://glom.readthedocs.io/) to read nested state:
+
+```python
+app.get("")                        # the container itself
+app.get("config.app.name")         # config values
+app.get("facets")                  # all bound facets
+app.get("facets.cli")              # CliFacet instance
+app.get("facets.cli.commands")     # command registry
+app.get("facets.web.routes.users") # a single route entry
+```
+
+Without `default`, resolution errors propagate (missing paths, glom failures, etc.):
+
+```python
+app.get("facets.cli.commands") # works when the cli facet is bound
+app.get("facets.missing")      # raises glom.PathAccessError
+```
+
+Pass `default` for optional lookups — any resolution error returns that value:
+
+```python
+app.get("facets.missing", default=None) # None
+app.get("facets.missing", default={})   # {}
+```
+
+Direct dict access also works when you know a facet is bound:
+
+```python
+app.facets["cli"].commands["hello"]
+app.components["logger"]
 ```

facetkit-0.4.0/docs/examples/composed_app.py

@@ -0,0 +1,57 @@
+"""Compose a container with logger and status components.
+
+Demonstrates component dependencies, facet registration, and dispatch
+over the CLI command registry.
+
+Run from the project root after installing facetkit:
+
+    python docs/examples/composed_app.py
+"""
+
+from facetkit import Container, CliFacet, ServiceFacet
+
+
+class LoggerComponent:
+    def on_bind(self, container):
+        container.facets["service"].add_provider("logger", self)
+
+    def on_unbind(self, container):
+        container.facets["service"].remove_provider("logger")
+
+    def info(self, msg):
+        print(msg)
+
+
+class StatusComponent:
+    required_components = ("logger",)
+    required_facets = ("cli", "service")
+
+    def on_bind(self, container):
+        self._logger = container.components["logger"]
+        container.facets["cli"].add_command("status", self.show_status)
+        container.facets["service"].add_provider("status", {"healthy": True})
+
+    def on_unbind(self, container):
+        container.facets["cli"].remove_command("status")
+        container.facets["service"].remove_provider("status")
+
+    def show_status(self):
+        """Show application status."""
+        self._logger.info("status check")
+        return "ok"
+
+
+def main():
+    app = Container({"app": {"name": "demo"}})
+    app.bind_facet("cli", CliFacet())
+    app.bind_facet("service", ServiceFacet())
+    app.bind_component("logger", LoggerComponent())
+    app.bind_component("status", StatusComponent())
+
+    print("Registered CLI commands:")
+    for command_id, cmd in app.facets["cli"].commands.items():
+        print(f"  {command_id}: {cmd.description}")
+
+
+if __name__ == "__main__":
+    main()

{facetkit-0.3.0 → facetkit-0.4.0}/docs/facet.md

@@ -1,74 +1,74 @@
-# Facets
-
-A **Facet** is a passive registry for an application surface — CLI commands, web routes, GUI widgets, background tasks, and so on. Facets collect descriptors; your dispatch layer reads them and runs the app. Mount only what you need on the [Container](container.md).
-
-## Types and exceptions
-
-**Protocol**
-
-- `Facet` — `name: str`, `clear()`
-
-**Implementations**
-
-| Facet | Registries | Purpose |
-|-------|------------|---------|
-| `CliFacet` | `commands` | Named CLI commands. Description is taken from the handler's docstring |
-| `TuiFacet` | `screens`, `keybindings`, `current_screen` | Terminal UI descriptors |
-| `GuiFacet` | `widgets`, `menus`, `toolbars`, `layouts` | Desktop UI descriptors |
-| `WebFacet` | `routes`, `middleware`, `error_handlers` | HTTP/API descriptors |
-| `ServiceFacet` | `tasks`, `providers` | Background work and shared providers |
-
-**Descriptor types** — `Command`, `ScreenDescriptor`, `KeybindingDescriptor`, `WidgetDescriptor`, `MenuDescriptor`, `ToolbarDescriptor`, `LayoutDescriptor`, `RouteDescriptor`, `MiddlewareDescriptor`, `ErrorHandlerDescriptor`, `TaskDescriptor`
-
-**Exceptions**
-
-| Exception | When | Attributes |
-|-----------|------|------------|
-| `DuplicateFacetError` | `mount_facet(overwrite=False)` | `.name` |
-| `FacetInUseError` | `unmount_facet` while a component requires the mount name | `.facet`, `.dependents` |
-
-## Lifecycle
-
-Facets are mounted and unmounted through the container:
-
-```python
-from facetkit import Container, CliFacet, WebFacet
-
-app = Container({})
-app.mount_facet("cli", CliFacet())
-app.unmount_facet("cli")
-```
-
-**`mount_facet(name, facet, *, overwrite=True)`** — stores the facet under `name`. When `overwrite=True` (the default), an existing mount of the same name is cleared and replaced without a dependent check. Pass `overwrite=False` to raise `DuplicateFacetError` instead:
-
-```python
-app.mount_facet("cli", CliFacet(), overwrite=False)
-```
-
-**`unmount_facet(name)`** — pops the facet and calls `clear()` on it. Raises `FacetInUseError` if any attached [component](component.md) lists `name` in `required_facets`. Remove those components first.
-
-Replacing a facet reuses the mount name — dependent checks are skipped on replacement so the slot stays available.
-
-## Registering entries
-
-Populate registries directly or through [components](component.md) during `attach`:
-
-```python
-def hello():
-    """Say hello."""
-    return "Hello!"
-
-app.facets["cli"].add_command("hello", hello)
-app.facets["web"].add_route("hello", "/hello", lambda: {"message": "Hello!"}, methods=["GET"])
-```
-
-Each facet exposes typed `add_*` / `remove_*` helpers over plain dict registries. Your application dispatches however you like — argparse, FastAPI, Textual, Qt, etc.
-
-## Mount names
-
-The mount name is arbitrary. The library does not require `"cli"` for a `CliFacet`, though consistent naming helps components declare `required_facets`:
-
-```python
-app.mount_facet("cli", CliFacet())      # conventional
-app.mount_facet("commands", CliFacet()) # also valid
+# Facets
+
+A **Facet** is a passive registry for an application surface — CLI commands, web routes, GUI widgets, background tasks, and so on. Facets collect descriptors; your dispatch layer reads them and runs the app. Bind only what you need on the [Container](container.md).
+
+## Types and exceptions
+
+**Protocol**
+
+- `Facet` — `name: str`, `clear()`
+
+**Implementations**
+
+| Facet | Registries | Purpose |
+|-------|------------|---------|
+| `CliFacet` | `commands` | Named CLI commands. Description is taken from the handler's docstring |
+| `TuiFacet` | `screens`, `keybindings`, `current_screen` | Terminal UI descriptors |
+| `GuiFacet` | `widgets`, `menus`, `toolbars`, `layouts` | Desktop UI descriptors |
+| `WebFacet` | `routes`, `middleware`, `error_handlers` | HTTP/API descriptors |
+| `ServiceFacet` | `tasks`, `providers` | Background work and shared providers |
+
+**Descriptor types** — `Command`, `ScreenDescriptor`, `KeybindingDescriptor`, `WidgetDescriptor`, `MenuDescriptor`, `ToolbarDescriptor`, `LayoutDescriptor`, `RouteDescriptor`, `MiddlewareDescriptor`, `ErrorHandlerDescriptor`, `TaskDescriptor`
+
+**Exceptions**
+
+| Exception | When | Attributes |
+|-----------|------|------------|
+| `DuplicateFacetError` | `bind_facet(overwrite=False)` | `.facet_id` |
+| `FacetInUseError` | `unbind_facet` while a component requires the facet id | `.facet_id`, `.dependents` |
+
+## Lifecycle
+
+Facets are bound and unbound through the container:
+
+```python
+from facetkit import Container, CliFacet, WebFacet
+
+app = Container({})
+app.bind_facet("cli", CliFacet())
+app.unbind_facet("cli")
+```
+
+**`bind_facet(facet_id, facet, *, overwrite=True)`** — stores the facet under `facet_id`. When `overwrite=True` (the default), an existing binding of the same id is cleared and replaced without a dependent check. Pass `overwrite=False` to raise `DuplicateFacetError` instead:
+
+```python
+app.bind_facet("cli", CliFacet(), overwrite=False)
+```
+
+**`unbind_facet(facet_id)`** — pops the facet and calls `clear()` on it. Raises `FacetInUseError` if any bound [component](component.md) lists `facet_id` in `required_facets`. Unbind those components first.
+
+Replacing a facet reuses the facet id — dependent checks are skipped on replacement so the slot stays available.
+
+## Registering entries
+
+Populate registries directly or through [components](component.md) during `on_bind`:
+
+```python
+def hello():
+    """Say hello."""
+    return "Hello!"
+
+app.facets["cli"].add_command("hello", hello)
+app.facets["web"].add_route("hello", "/hello", lambda: {"message": "Hello!"}, methods=["GET"])
+```
+
+Each facet exposes typed `add_*` / `remove_*` helpers over plain dict registries. Your application dispatches however you like — argparse, FastAPI, Textual, Qt, etc.
+
+## Facet ids
+
+The facet id is arbitrary. The library does not require `"cli"` for a `CliFacet`, though consistent naming helps components declare `required_facets`:
+
+```python
+app.bind_facet("cli", CliFacet())      # conventional
+app.bind_facet("commands", CliFacet()) # also valid
 ```

{facetkit-0.3.0 → facetkit-0.4.0}/facetkit/__init__.py

@@ -1,6 +1,6 @@
 from facetkit.container import Container
 from facetkit.exceptions import (
-    DependentComponentsError,
+    ComponentInUseError,
     DuplicateComponentError,
     DuplicateFacetError,
     FacetInUseError,
@@ -27,7 +27,7 @@ from facetkit.facets import CliFacet, ServiceFacet, TuiFacet, GuiFacet, WebFacet
 __all__ = [
     "Container",
     "Component",
-    "DependentComponentsError",
+    "ComponentInUseError",
     "DuplicateComponentError",
     "DuplicateFacetError",
     "FacetInUseError",
@@ -52,4 +52,4 @@ __all__ = [
     "WebFacet",
 ]
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"