facetkit 0.2.0__tar.gz → 0.4.0__tar.gz

facetkit-0.4.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+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
+
+- `overwrite` parameter on `mount_facet` and `add_component` (default `True`; pass `False` to block duplicate keys)
+- `DuplicateFacetError` and `DuplicateComponentError` for blocked duplicate registration
+- `Component.required_components` class attribute for declarative peer dependencies
+- `Component.required_facets` class attribute for declarative facet mount dependencies
+- `MissingComponentDependencyError` raised on attach when required components are absent
+- `MissingFacetDependencyError` raised on attach when required facets are not mounted
+- `DependentComponentsError` raised on remove when other components still depend on it
+- `FacetInUseError` raised on unmount when attached components still depend on the facet
+- Added '/docs' folder, with explanations for container, facet and component.
+- Added '/docs/examples' folder, with an example of a composable app.
+
+[0.3.0]: https://github.com/Dev-DanielR/py_facetkit/releases/tag/v0.3.0
+
+## [0.2.0] - 2026-06-19
+
+### Added
+
+- `Container.get()` now does a strict check if a default value is omitted
+
+[0.2.0]: https://github.com/Dev-DanielR/py_facetkit/releases/tag/v0.2.0
+
+## [0.1.0] - 2026-06-18
+
+### Added
+
+- `Container` with config, component lifecycle, and facet mounting
+- Passive facets: `CliFacet`, `TuiFacet`, `GuiFacet`, `WebFacet`, `ServiceFacet`
+- `Component` attach/detach protocol for composable plugins
+- `Container.get()` introspection via glom paths
+- Descriptor types for registry entries (`Command`, `RouteDescriptor`, etc.)
+- CLI command descriptions derived from handler docstrings
+
+[0.1.0]: https://github.com/Dev-DanielR/py_facetkit/releases/tag/v0.1.0

facetkit-0.4.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: facetkit
+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
+License-File: LICENSE
+Keywords: cli,container,dependency-injection,gui,plugin,registry,tui,web
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: glom>=23.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# facetkit
+
+A composable Python container for application state and passive registries — CLI commands, TUI screens, GUI widgets, web routes, and background services.
+
+facetkit separates three pieces:
+
+| Piece | Role |
+|-------|------|
+| [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 connects to one or several facets in on_bind and cleans up in on_unbind  |
+
+```
+Container
+├── config
+├── components
+└── facets
+    ├── cli      → commands
+    ├── tui      → screens, keybindings
+    ├── gui      → widgets, menus, toolbars, layouts
+    ├── web      → routes, middleware, error handlers
+    └── service  → tasks, providers
+```
+
+## Requirements
+
+- Python 3.10+
+- [glom](https://github.com/mahmoud/glom)
+
+## Installation
+
+```bash
+pip install facetkit
+```
+
+For local development:
+
+```bash
+git clone https://github.com/Dev-DanielR/py_facetkit.git
+cd facetkit
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+from facetkit import Container, CliFacet, WebFacet
+
+app = Container({"app": {"name": "demo"}})
+
+app.bind_facet("cli", CliFacet())
+app.bind_facet("web", WebFacet())
+
+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"])
+```
+
+Register directly on facets (as above) or through [components](docs/component.md). Your dispatch layer reads the registries and wires them to argparse, FastAPI, Textual, Qt, or whatever you use.
+
+## Documentation
+
+- [Container](docs/container.md) — config, lifecycle, introspection
+- [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
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes. Pre-1.0 (`0.4.0`) — public APIs may change between minor releases.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

facetkit-0.4.0/README.md

@@ -0,0 +1,82 @@
+# facetkit
+
+A composable Python container for application state and passive registries — CLI commands, TUI screens, GUI widgets, web routes, and background services.
+
+facetkit separates three pieces:
+
+| Piece | Role |
+|-------|------|
+| [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 connects to one or several facets in on_bind and cleans up in on_unbind  |
+
+```
+Container
+├── config
+├── components
+└── facets
+    ├── cli      → commands
+    ├── tui      → screens, keybindings
+    ├── gui      → widgets, menus, toolbars, layouts
+    ├── web      → routes, middleware, error handlers
+    └── service  → tasks, providers
+```
+
+## Requirements
+
+- Python 3.10+
+- [glom](https://github.com/mahmoud/glom)
+
+## Installation
+
+```bash
+pip install facetkit
+```
+
+For local development:
+
+```bash
+git clone https://github.com/Dev-DanielR/py_facetkit.git
+cd facetkit
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+from facetkit import Container, CliFacet, WebFacet
+
+app = Container({"app": {"name": "demo"}})
+
+app.bind_facet("cli", CliFacet())
+app.bind_facet("web", WebFacet())
+
+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"])
+```
+
+Register directly on facets (as above) or through [components](docs/component.md). Your dispatch layer reads the registries and wires them to argparse, FastAPI, Textual, Qt, or whatever you use.
+
+## Documentation
+
+- [Container](docs/container.md) — config, lifecycle, introspection
+- [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
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes. Pre-1.0 (`0.4.0`) — public APIs may change between minor releases.
+
+## License
+
+MIT — see [LICENSE](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.4.0/docs/container.md

@@ -0,0 +1,75 @@
+# 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.4.0/docs/facet.md

@@ -0,0 +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. 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.2.0 → facetkit-0.4.0}/facetkit/__init__.py

@@ -1,41 +1,55 @@
-from facetkit.container import Container
-from facetkit.types import (
-    Component,
-    Facet,
-    Command,
-    TaskDescriptor,
-    ScreenDescriptor,
-    KeybindingDescriptor,
-    WidgetDescriptor,
-    MenuDescriptor,
-    ToolbarDescriptor,
-    LayoutDescriptor,
-    RouteDescriptor,
-    MiddlewareDescriptor,
-    ErrorHandlerDescriptor,
-)
-from facetkit.facets import CliFacet, ServiceFacet, TuiFacet, GuiFacet, WebFacet
-
-__all__ = [
-    "Container",
-    "Component",
-    "Facet",
-    "Command",
-    "TaskDescriptor",
-    "ScreenDescriptor",
-    "KeybindingDescriptor",
-    "WidgetDescriptor",
-    "MenuDescriptor",
-    "ToolbarDescriptor",
-    "LayoutDescriptor",
-    "RouteDescriptor",
-    "MiddlewareDescriptor",
-    "ErrorHandlerDescriptor",
-    "CliFacet",
-    "ServiceFacet",
-    "TuiFacet",
-    "GuiFacet",
-    "WebFacet",
-]
-
-__version__ = "0.2.0"
+from facetkit.container import Container
+from facetkit.exceptions import (
+    ComponentInUseError,
+    DuplicateComponentError,
+    DuplicateFacetError,
+    FacetInUseError,
+    MissingComponentDependencyError,
+    MissingFacetDependencyError,
+)
+from facetkit.types import (
+    Component,
+    Facet,
+    Command,
+    TaskDescriptor,
+    ScreenDescriptor,
+    KeybindingDescriptor,
+    WidgetDescriptor,
+    MenuDescriptor,
+    ToolbarDescriptor,
+    LayoutDescriptor,
+    RouteDescriptor,
+    MiddlewareDescriptor,
+    ErrorHandlerDescriptor,
+)
+from facetkit.facets import CliFacet, ServiceFacet, TuiFacet, GuiFacet, WebFacet
+
+__all__ = [
+    "Container",
+    "Component",
+    "ComponentInUseError",
+    "DuplicateComponentError",
+    "DuplicateFacetError",
+    "FacetInUseError",
+    "MissingComponentDependencyError",
+    "MissingFacetDependencyError",
+    "Facet",
+    "Command",
+    "TaskDescriptor",
+    "ScreenDescriptor",
+    "KeybindingDescriptor",
+    "WidgetDescriptor",
+    "MenuDescriptor",
+    "ToolbarDescriptor",
+    "LayoutDescriptor",
+    "RouteDescriptor",
+    "MiddlewareDescriptor",
+    "ErrorHandlerDescriptor",
+    "CliFacet",
+    "ServiceFacet",
+    "TuiFacet",
+    "GuiFacet",
+    "WebFacet",
+]
+
+__version__ = "0.4.0"