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).