Metadata-Version: 2.4
Name: codex-fastapi-cabinet
Version: 0.1.0
Summary: Composable administration interfaces for FastAPI sites and APIs
Project-URL: Homepage, https://github.com/CodexDLC/codex-fastapi-cabinet
Project-URL: Documentation, https://codexdlc.github.io/codex-fastapi-cabinet/
Project-URL: Repository, https://github.com/CodexDLC/codex-fastapi-cabinet
Project-URL: Issues, https://github.com/CodexDLC/codex-fastapi-cabinet/issues
Author: CodexDLC
License: Apache-2.0
License-File: LICENSE
Keywords: admin,dashboard,fastapi,jinja2,management
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.12
Requires-Dist: fastapi<1.0,>=0.115
Requires-Dist: jinja2<4.0,>=3.1
Requires-Dist: pydantic<3.0,>=2.10
Provides-Extra: dev
Requires-Dist: httpx>=0.28; extra == 'dev'
Requires-Dist: mypy>=1.15; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=9.0; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Requires-Dist: twine>=6.1; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mike>=2.1; extra == 'docs'
Requires-Dist: mkdocs-include-markdown-plugin>=7.1; extra == 'docs'
Requires-Dist: mkdocs-material>=9.6; extra == 'docs'
Requires-Dist: mkdocs<2.0,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.29; extra == 'docs'
Description-Content-Type: text/markdown

# codex-fastapi-cabinet

Composable, server-rendered administration interfaces for FastAPI sites and APIs.

The library provides the management shell, routing, navigation, generic pages, dashboard widgets,
permissions port, Jinja templates, and static assets. Your FastAPI application keeps ownership of
authentication, authorization rules, database access, transactions, and business operations.

> Status: alpha. The public API is usable, but may evolve before `1.0`.

## What it provides

- application-scoped admin registry;
- independent mount path, such as `/cabinet` or `/management`;
- generic list, detail, form, and operation pages;
- metric, table, list, and chart dashboard widgets;
- async application-owned data providers;
- permission checks for modules, pages, widgets, navigation, and actions;
- overridable Jinja templates and packaged responsive CSS;
- explicit module discovery without import-time registration side effects.

## Installation

```bash
pip install codex-fastapi-cabinet
```

For local development:

```bash
uv sync --extra dev --extra docs
```

## Quick start

```python
from typing import ClassVar

from fastapi import FastAPI, Request

from fastapi_cabinet import (
    CabinetAdmin,
    CabinetProvider,
    CabinetSite,
    ListPage,
    ListPageMap,
    MetricWidget,
    MetricWidgetMap,
    SidebarItem,
    TableColumnMap,
    include_cabinet,
)


async def user_count(request: Request) -> MetricWidgetMap:
    return MetricWidgetMap(
        key="users-total",
        title="Users",
        value="42",
        subtitle="Registered accounts",
    )


async def user_list(request: Request) -> ListPageMap:
    return ListPageMap(
        title="Users",
        columns=[
            TableColumnMap(key="email", label="Email"),
            TableColumnMap(key="status", label="Status"),
        ],
        rows=[
            {
                "email": "admin@example.test",
                "status": "active",
                "href": "/management/users/1",
            }
        ],
        row_href_key="href",
    )


class UsersAdmin(CabinetAdmin):
    key = "users"
    label = "Users"
    sidebar = (SidebarItem(key="all", label="All users", path="all"),)
    dashboard_widgets = (
        MetricWidget(key="users-total", title="Users", provider="users.count"),
    )
    pages = (
        ListPage(key="all", label="All users", path="all", provider="users.list"),
    )
    providers: ClassVar[dict[str, CabinetProvider]] = {
        "users.count": user_count,
        "users.list": user_list,
    }


app = FastAPI()
site = CabinetSite(brand_name="My service")
site.register(UsersAdmin)
include_cabinet(app, site=site, mount_path="/management")
```

Run the complete example:

```bash
uvicorn examples.basic_app:app --reload
```

Then open `http://127.0.0.1:8000/management`.

## Boundaries

`codex-fastapi-cabinet` is a composition toolkit, not an ORM-aware CRUD generator. Providers return
validated view models, so the same cabinet can sit over SQLAlchemy, another database layer, an HTTP
API, or an in-memory service without coupling the library to any of them.

The host application must secure the cabinet mount and provide real permission checks. The default
permission provider allows every declared permission and is intended only when access control is
enforced outside the library.

## Documentation

- [English documentation](docs/index.md)
- [Русская документация](docs/ru/index.md)
- [Architecture and extension boundaries](docs/architecture.md)
- [Template customization](docs/customization.md)

## Development

```bash
ruff check src tests examples
mypy src tests examples
pytest
python -m build
```

## License

Apache License 2.0. See [LICENSE](LICENSE).
