facetkit 0.2.0__tar.gz → 0.3.0__tar.gz

facetkit-0.3.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# 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.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.3.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: facetkit
+Version: 0.3.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 mounting, component lifecycle |
+| [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 |
+
+```
+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.mount_facet("cli", CliFacet())
+app.mount_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, mounting
+- [Components](docs/component.md) — attach/detach, 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.3.0`) — public APIs may change between minor releases.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

facetkit-0.3.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 mounting, component lifecycle |
+| [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 |
+
+```
+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.mount_facet("cli", CliFacet())
+app.mount_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, mounting
+- [Components](docs/component.md) — attach/detach, 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.3.0`) — public APIs may change between minor releases.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

facetkit-0.3.0/docs/component.md

@@ -0,0 +1,124 @@
+# Components
+
+A **Component** is an active plugin that registers into [facets](facet.md) on attach and cleans up on detach. This keeps feature setup and teardown in one place instead of scattered across your application.
+
+## Types and exceptions
+
+**Protocol**
+
+```python
+class MyComponent:
+    def attach(self, ctx): ...
+    def detach(self, ctx): ...
+```
+
+Optional class attributes — see [Declared dependencies](#declared-dependencies).
+
+**Exceptions**
+
+| Exception | When | Attributes |
+|-----------|------|------------|
+| `DuplicateComponentError` | `add_component(overwrite=False)` | `.name` |
+| `MissingComponentDependencyError` | `add_component` — required component absent | `.component`, `.missing` |
+| `MissingFacetDependencyError` | `add_component` — required facet not mounted | `.component`, `.missing` |
+| `DependentComponentsError` | `remove_component` — another component depends on it | `.component`, `.dependents` |
+
+`FacetInUseError` (raised on `unmount_facet`) is documented in [Facets](facet.md).
+
+## Lifecycle
+
+Components are registered and removed through the container:
+
+```python
+from facetkit import Container, CliFacet, ServiceFacet
+
+class StatusComponent:
+    required_facets = ("cli", "service")
+
+    def attach(self, ctx):
+        ctx.facets["cli"].add_command("status", self.show_status)
+        ctx.facets["service"].add_provider("status", {"healthy": True})
+
+    def detach(self, ctx):
+        ctx.facets["cli"].remove_command("status")
+        ctx.facets["service"].remove_provider("status")
+
+    def show_status(self):
+        """Show application status."""
+        return "ok"
+
+app = Container({"app": {"name": "demo"}})
+app.mount_facet("cli", CliFacet())
+app.mount_facet("service", ServiceFacet())
+app.add_component("status", StatusComponent())
+app.remove_component("status")
+```
+
+**`add_component(name, comp, *, overwrite=True)`** — validates declared dependencies, calls `attach(ctx)`, then stores the instance. The [container](container.md) is passed as `ctx`. When `overwrite=True` (the default), an existing registration of the same name is detached and replaced without a dependent check. Pass `overwrite=False` to raise `DuplicateComponentError` instead:
+
+```python
+app.add_component("logger", Logger(), overwrite=False)
+```
+
+If validation fails, `attach` is not called.
+
+**`remove_component(name)`** — calls `detach(ctx)`, then removes the instance. Raises `DependentComponentsError` if any other attached component lists `name` in `required_components`.
+
+Inside `attach` / `detach`, components typically:
+
+- Register or unregister entries on `ctx.facets[...]`
+- Read shared state from `ctx.config`
+- Reach peer plugins via `ctx.components["name"]`
+
+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 attach. Both attributes are optional class-level tuples:
+
+```python
+class ApiComponent:
+    required_components = ("logger", "database") # peer components
+    required_facets = ("cli", "web")             # mounted facet names
+
+    def attach(self, ctx):
+        logger = ctx.components["logger"]
+        ctx.facets["cli"].add_command("api-status", self.status)
+        ctx.facets["web"].add_route("api-status", "/status", self.status)
+
+    def detach(self, ctx):
+        ctx.facets["cli"].remove_command("api-status")
+        ctx.facets["web"].remove_route("api-status")
+```
+
+The container enforces these at lifecycle boundaries:
+
+| Action | Validation |
+|--------|------------|
+| `add_component` | Every name in `required_components` must already be registered; every name in `required_facets` must already be mounted. `attach` is not called if anything is missing. |
+| `remove_component` | Blocked if any other attached component lists this name in `required_components`. |
+| `unmount_facet` | Blocked if any attached component lists this mount name in `required_facets`. |
+| Replace same name | Allowed — dependent checks are skipped so the slot stays filled. |
+
+Register dependencies before dependents:
+
+```python
+app.add_component("logger", LoggerComponent())
+app.add_component("database", DatabaseComponent())
+app.add_component("api", ApiComponent()) # OK
+
+app.add_component("api", ApiComponent()) # raises MissingComponentDependencyError
+```
+
+Tear down in reverse:
+
+```python
+app.remove_component("api")    # OK
+app.remove_component("logger") # OK once api is gone
+
+app.unmount_facet("cli")       # raises FacetInUseError while a component still requires it
+```

facetkit-0.3.0/docs/container.md

@@ -0,0 +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"]
+```

facetkit-0.3.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 attach(self, ctx):
+        ctx.facets["service"].add_provider("logger", self)
+
+    def detach(self, ctx):
+        ctx.facets["service"].remove_provider("logger")
+
+    def info(self, msg):
+        print(msg)
+
+
+class StatusComponent:
+    required_components = ("logger",)
+    required_facets = ("cli", "service")
+
+    def attach(self, ctx):
+        self._logger = ctx.components["logger"]
+        ctx.facets["cli"].add_command("status", self.show_status)
+        ctx.facets["service"].add_provider("status", {"healthy": True})
+
+    def detach(self, ctx):
+        ctx.facets["cli"].remove_command("status")
+        ctx.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.mount_facet("cli", CliFacet())
+    app.mount_facet("service", ServiceFacet())
+    app.add_component("logger", LoggerComponent())
+    app.add_component("status", StatusComponent())
+
+    print("Registered CLI commands:")
+    for name, cmd in app.facets["cli"].commands.items():
+        print(f"  {name}: {cmd.description}")
+
+
+if __name__ == "__main__":
+    main()

facetkit-0.3.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. 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
+```

{facetkit-0.2.0 → facetkit-0.3.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 (
+    DependentComponentsError,
+    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",
+    "DependentComponentsError",
+    "DuplicateComponentError",
+    "DuplicateFacetError",
+    "FacetInUseError",
+    "MissingComponentDependencyError",
+    "MissingFacetDependencyError",
+    "Facet",
+    "Command",
+    "TaskDescriptor",
+    "ScreenDescriptor",
+    "KeybindingDescriptor",
+    "WidgetDescriptor",
+    "MenuDescriptor",
+    "ToolbarDescriptor",
+    "LayoutDescriptor",
+    "RouteDescriptor",
+    "MiddlewareDescriptor",
+    "ErrorHandlerDescriptor",
+    "CliFacet",
+    "ServiceFacet",
+    "TuiFacet",
+    "GuiFacet",
+    "WebFacet",
+]
+
+__version__ = "0.3.0"