facetkit 0.1.0__tar.gz

facetkit-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+.env/
+env/
+
+# Test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo

facetkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# 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.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.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel R. Vásquez Montes
+
+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.

facetkit-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: facetkit
+Version: 0.1.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.
+Provides basic functionality for CLI commands, TUI screens, GUI widgets, web routes and background services.
+
+## Design
+
+- **Container** — shared config, component lifecycle, and a map of mounted facets
+- **Facets** — framework-agnostic registries (commands, routes, widgets, tasks, etc)
+- **Components** — plugins that register into facets on `attach` and clean 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) (declared as a dependency)
+
+## 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!"
+
+cli = app.facets["cli"]
+cli.add_command("hello", hello)
+
+web = app.facets["web"]
+web.add_route("hello", "/hello", lambda: {"message": "Hello!"}, methods=["GET"])
+```
+
+Your application reads the registries and dispatches however you like — argparse, FastAPI, Textual, Qt, etc.
+
+## Components
+
+Components implement `attach(ctx)` and `detach(ctx)`. The container is passed as context:
+
+```python
+class StatusComponent:
+    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.mount_facet("cli", CliFacet())
+app.mount_facet("service", ServiceFacet())
+app.add_component("status", StatusComponent())
+```
+
+Replacing or removing a component calls `detach` on the old instance before the new one attaches.
+
+## Facets
+
+| 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 |
+
+Mount only what you need:
+
+```python
+app.mount_facet("cli", CliFacet())
+app.mount_facet("web", WebFacet())
+# No TUI/GUI facets required
+```
+
+Unmounting clears the facet's registries:
+
+```python
+app.unmount_facet("cli")
+```
+
+### Registry behavior
+
+- **Duplicate keys** — registering the same name again overwrites the previous entry (last wins).
+- **Unmount** — `unmount_facet` clears that facet's registries. Attached components are not automatically detached; call `remove_component` first if you need a full teardown.
+- **Facet names** — the mount name is arbitrary (`app.mount_facet("cli", CliFacet())`). The library does not enforce that the name matches the facet type.
+- **Missing facets** — `app.facets["cli"]` raises `KeyError`; `app.get("facets.cli")` returns `None`.
+
+## 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
+```
+
+Missing paths return `default` (or `None`):
+
+```python
+app.get("facets.missing")              # None
+app.get("facets.missing", default={})  # {}
+```
+
+`get()` also returns `default` on any internal error while resolving a path, not only missing keys. That keeps introspection safe but can hide bugs — prefer direct attribute access when you want exceptions to surface.
+
+Direct dict access also works when you know a facet is mounted:
+
+```python
+app.facets["cli"].commands["hello"]
+```
+
+## Public API
+
+```python
+from facetkit import (
+    Container,
+    Component,     # protocol
+    Facet,         # protocol
+    CliFacet,
+    TuiFacet,
+    GuiFacet,
+    WebFacet,
+    ServiceFacet,
+    Command,
+    RouteDescriptor,
+    # ... other descriptor types
+)
+```
+
+## Versioning
+
+This project is pre-1.0 (`0.1.0`). Public APIs may change between minor releases. See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Build a wheel locally:
+
+```bash
+pip install build
+python -m build
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

facetkit-0.1.0/README.md

@@ -0,0 +1,188 @@
+# facetkit
+
+A composable Python container for application state and passive registries.
+Provides basic functionality for CLI commands, TUI screens, GUI widgets, web routes and background services.
+
+## Design
+
+- **Container** — shared config, component lifecycle, and a map of mounted facets
+- **Facets** — framework-agnostic registries (commands, routes, widgets, tasks, etc)
+- **Components** — plugins that register into facets on `attach` and clean 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) (declared as a dependency)
+
+## 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!"
+
+cli = app.facets["cli"]
+cli.add_command("hello", hello)
+
+web = app.facets["web"]
+web.add_route("hello", "/hello", lambda: {"message": "Hello!"}, methods=["GET"])
+```
+
+Your application reads the registries and dispatches however you like — argparse, FastAPI, Textual, Qt, etc.
+
+## Components
+
+Components implement `attach(ctx)` and `detach(ctx)`. The container is passed as context:
+
+```python
+class StatusComponent:
+    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.mount_facet("cli", CliFacet())
+app.mount_facet("service", ServiceFacet())
+app.add_component("status", StatusComponent())
+```
+
+Replacing or removing a component calls `detach` on the old instance before the new one attaches.
+
+## Facets
+
+| 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 |
+
+Mount only what you need:
+
+```python
+app.mount_facet("cli", CliFacet())
+app.mount_facet("web", WebFacet())
+# No TUI/GUI facets required
+```
+
+Unmounting clears the facet's registries:
+
+```python
+app.unmount_facet("cli")
+```
+
+### Registry behavior
+
+- **Duplicate keys** — registering the same name again overwrites the previous entry (last wins).
+- **Unmount** — `unmount_facet` clears that facet's registries. Attached components are not automatically detached; call `remove_component` first if you need a full teardown.
+- **Facet names** — the mount name is arbitrary (`app.mount_facet("cli", CliFacet())`). The library does not enforce that the name matches the facet type.
+- **Missing facets** — `app.facets["cli"]` raises `KeyError`; `app.get("facets.cli")` returns `None`.
+
+## 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
+```
+
+Missing paths return `default` (or `None`):
+
+```python
+app.get("facets.missing")              # None
+app.get("facets.missing", default={})  # {}
+```
+
+`get()` also returns `default` on any internal error while resolving a path, not only missing keys. That keeps introspection safe but can hide bugs — prefer direct attribute access when you want exceptions to surface.
+
+Direct dict access also works when you know a facet is mounted:
+
+```python
+app.facets["cli"].commands["hello"]
+```
+
+## Public API
+
+```python
+from facetkit import (
+    Container,
+    Component,     # protocol
+    Facet,         # protocol
+    CliFacet,
+    TuiFacet,
+    GuiFacet,
+    WebFacet,
+    ServiceFacet,
+    Command,
+    RouteDescriptor,
+    # ... other descriptor types
+)
+```
+
+## Versioning
+
+This project is pre-1.0 (`0.1.0`). Public APIs may change between minor releases. See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Build a wheel locally:
+
+```bash
+pip install build
+python -m build
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

facetkit-0.1.0/facetkit/__init__.py

@@ -0,0 +1,41 @@
+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.1.0"

facetkit-0.1.0/facetkit/container.py

@@ -0,0 +1,51 @@
+#===============================================================================
+# DEPENDENCIES
+
+import glom
+
+from typing import Dict, Any, Optional
+from facetkit.types import Component, Facet
+
+#===============================================================================
+# DEFINITIONS
+
+class Container:
+
+    def __init__(self, config: Dict[str, Any]):
+        self.config     : Dict[str, Any]       = config
+        self.facets     : Dict[str, Facet]     = {}
+        self.components : Dict[str, Component] = {}
+
+    # Public API ===============================================================
+
+    def get(self, path: str, default: Any = None) -> Any:
+        """Retrieve from container using glom."""
+
+        if not path: return self
+        try:
+            return glom.glom(self.__dict__, path)
+        except (glom.PathAccessError, glom.GlomError):
+            return default
+        except Exception:
+            return default
+
+    def mount_facet(self, name: str, facet: Facet) -> None:
+        if name in self.facets: self.unmount_facet(name)
+        self.facets[name] = facet
+
+    def unmount_facet(self, name: str) -> None:
+        facet = self.facets.pop(name, None)
+        if facet: facet.clear()
+
+    def add_component(self, name: str, comp: Component) -> None:
+        """Register a component and attach it to this container."""
+
+        if name in self.components: self.remove_component(name)
+        comp.attach(self)
+        self.components[name] = comp
+
+    def remove_component(self, name: str) -> None:
+        """Remove a component and detach it from this container."""
+
+        comp = self.components.pop(name, None)
+        if comp: comp.detach(self)

facetkit-0.1.0/facetkit/facets/__init__.py

@@ -0,0 +1,7 @@
+from facetkit.facets.cli import CliFacet
+from facetkit.facets.gui import GuiFacet
+from facetkit.facets.service import ServiceFacet
+from facetkit.facets.tui import TuiFacet
+from facetkit.facets.web import WebFacet
+
+__all__ = ["CliFacet", "ServiceFacet", "TuiFacet", "GuiFacet", "WebFacet"]

facetkit-0.1.0/facetkit/facets/cli.py

@@ -0,0 +1,26 @@
+#===============================================================================
+# DEPENDENCIES
+
+from textwrap import dedent
+
+from typing import Any, Callable, Dict
+from facetkit.types import Command, Facet
+
+#===============================================================================
+# DEFINITIONS
+
+class CliFacet(Facet):
+
+    def __init__(self):
+        self.name     = "cli"
+        self.commands : Dict[str, Command] = {}
+
+    def add_command(self, name: str, handler: Callable[..., Any]) -> None:
+        doc = handler.__doc__ or ""
+        self.commands[name] = Command(name, handler, dedent(doc).strip())
+
+    def remove_command(self, name: str) -> None:
+        self.commands.pop(name, None)
+
+    def clear(self) -> None:
+        self.commands.clear()

facetkit-0.1.0/facetkit/facets/gui.py

@@ -0,0 +1,53 @@
+#===============================================================================
+# DEPENDENCIES
+
+from typing import Any, Callable, Dict, Optional
+from facetkit.types import Facet, LayoutDescriptor, MenuDescriptor, ToolbarDescriptor, WidgetDescriptor
+
+#===============================================================================
+# DEFINITIONS
+
+class GuiFacet(Facet):
+
+    def __init__(self):
+        self.name     = "gui"
+        self.widgets  : Dict[str, WidgetDescriptor]   = {}
+        self.menus    : Dict[str, MenuDescriptor]     = {}
+        self.toolbars : Dict[str, ToolbarDescriptor]  = {}
+        self.layouts  : Dict[str, LayoutDescriptor]   = {}
+
+    def add_widget(
+        self,
+        widget_id: str,
+        factory: Callable[..., Any],
+        parent: Optional[str] = None,
+        layout_hints: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self.widgets[widget_id] = WidgetDescriptor(widget_id, factory, parent, layout_hints or {})
+
+    def remove_widget(self, widget_id: str) -> None:
+        self.widgets.pop(widget_id, None)
+
+    def add_menu(self, menu_id: str, factory: Callable[..., Any], parent: Optional[str] = None) -> None:
+        self.menus[menu_id] = MenuDescriptor(menu_id, factory, parent)
+
+    def remove_menu(self, menu_id: str) -> None:
+        self.menus.pop(menu_id, None)
+
+    def add_toolbar(self, toolbar_id: str, factory: Callable[..., Any], parent: Optional[str] = None) -> None:
+        self.toolbars[toolbar_id] = ToolbarDescriptor(toolbar_id, factory, parent)
+
+    def remove_toolbar(self, toolbar_id: str) -> None:
+        self.toolbars.pop(toolbar_id, None)
+
+    def add_layout(self, layout_id: str, factory: Callable[..., Any], hints: Optional[Dict[str, Any]] = None) -> None:
+        self.layouts[layout_id] = LayoutDescriptor(layout_id, factory, hints or {})
+
+    def remove_layout(self, layout_id: str) -> None:
+        self.layouts.pop(layout_id, None)
+
+    def clear(self) -> None:
+        self.widgets.clear()
+        self.menus.clear()
+        self.toolbars.clear()
+        self.layouts.clear()

facetkit-0.1.0/facetkit/facets/service.py

@@ -0,0 +1,31 @@
+#===============================================================================
+# DEPENDENCIES
+
+from typing import Any, Callable, Dict, Optional
+from facetkit.types import Facet, TaskDescriptor
+
+#===============================================================================
+# DEFINITIONS
+
+class ServiceFacet(Facet):
+
+    def __init__(self):
+        self.name      = "service"
+        self.tasks     : Dict[str, TaskDescriptor] = {}
+        self.providers : Dict[str, Any]            = {}
+
+    def add_task(self, name: str, factory: Callable[..., Any], interval: Optional[float] = None) -> None:
+        self.tasks[name] = TaskDescriptor(name, factory, interval)
+
+    def remove_task(self, name: str) -> None:
+        self.tasks.pop(name, None)
+
+    def add_provider(self, name: str, provider: Any) -> None:
+        self.providers[name] = provider
+
+    def remove_provider(self, name: str) -> None:
+        self.providers.pop(name, None)
+
+    def clear(self) -> None:
+        self.tasks.clear()
+        self.providers.clear()