Metadata-Version: 2.4
Name: kayframework
Version: 0.2.1
Summary: A scaffold-first FastAPI micro-framework with a module-oriented CLI
Author: kayjs
License-Expression: MIT
Project-URL: Homepage, https://github.com/kayjs/kayframework
Project-URL: Package, https://pypi.org/project/kayframework/
Project-URL: Documentation, https://github.com/kayjs/kayframework/tree/main/docs
Project-URL: Repository, https://github.com/kayjs/kayframework
Project-URL: Issues, https://github.com/kayjs/kayframework/issues
Keywords: fastapi,framework,cli,scaffold,microframework
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: fastapi-utils>=0.8
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: passlib[bcrypt]>=1.7
Requires-Dist: bcrypt==4.0.1
Requires-Dist: python-jose[cryptography]>=3.3
Requires-Dist: jinja2>=3.1
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: pydantic[email]>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9; extra == "postgres"
Dynamic: license-file

# KAYFRAMEWORK

A scaffold-first FastAPI micro-framework for teams that want a repeatable starting architecture, a consistent CLI workflow, and full ownership of generated application code.

PyPI: `https://pypi.org/project/kayframework/`

## Quickstart

```bash
pip install kayframework
kay new app myservice
cd myservice
pip install -e .
uvicorn app.main:app --reload
```

## Why This Framework Exists

KAYFRAMEWORK exists to solve a practical gap:

- FastAPI gives primitives, not a standardized project system.
- Teams often rebuild the same app skeleton and CLI scripts repeatedly.
- Starter templates become unmaintained, inconsistent, or hard to scale across services.

KAYFRAMEWORK provides a stable scaffold workflow while keeping generated projects decoupled from framework internals.

## Who It Is For / Not For

For:

- Teams building multiple FastAPI services with a shared baseline architecture.
- Developers who want opinionated scaffolding but flexible implementation.
- Projects that value CLI-driven consistency (`new`, `module`, `lint`, `doctor`, `build`).

Not for:

- Teams needing a batteries-included monolith like Django admin + ORM conventions.
- Projects expecting runtime plugin magic managed by the framework package itself.
- Users who only need a single minimal script-level API app.

## Key Features

- `src`-layout packaging with clean import boundaries.
- Scaffold template separated from runtime package internals.
- CLI for project/module generation and developer workflow commands.
- Module-oriented generated app structure (`app/modules/...`).
- GitHub-ready repo baseline (CI, contribution docs, issue/PR templates).

## Architecture Overview

```text
src/
  kayframework/
    cli/
      main.py
    core/
      scaffold.py
    modules/
      scaffold.py
    utils/
      process.py
    project_template/
      app/
        ... generated application scaffold ...

docs/
examples/
tests/
```

Design model:

- `kayframework` package: tooling, scaffolding, CLI.
- `project_template`: copied into new projects by `kay new app`.
- Generated apps: independent codebases you fully own and modify.

## CLI

```bash
kay new app <name> [--dir .]
kay new module <name> [--app-dir app]
kay run [--app app.main:app] [--host 127.0.0.1] [--port 8000] [--no-reload]
kay test [path]
kay lint [path]
kay format [path]
kay typecheck [path]
kay build
kay clean [--dir .]
kay init [--dir .]
kay doctor [--dir .]
kay version
```

CLI conventions:

- Non-zero exit codes on failure.
- Deterministic scaffold generation.
- Commands target local project directories explicitly.

## Module System

Generated apps include module loading via `MODULES` in `.env`.

Example:

```env
MODULES=billing,notifications
```

Each module lives under `app/modules/<module_name>/` and exposes `router` in `routes.py`.

## Comparison

| Capability | KAYFRAMEWORK | FastAPI | Flask | Django |
|---|---|---|---|---|
| Opinionated scaffold generation | Yes | No | No | Yes |
| Lightweight micro-framework runtime | Yes | Yes | Yes | No |
| Built-in monolith features (admin, ORM conventions) | No | No | No | Yes |
| CLI-first project/module generation | Yes | Partial | Partial | Yes |
| Generated code ownership model | Full | N/A | N/A | Partial |

## Installation

Framework package:

```bash
pip install kayframework
```

Development setup:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

## Development Workflow

```bash
kay lint
kay typecheck
kay test
kay build
```

CI mirrors the same checks in `.github/workflows/ci.yml`.

## Security Notes

For generated projects:

- Replace `SECRET_KEY` before deployment.
- Use `ENV=prod` and `COOKIE_SECURE=true` under HTTPS.
- Do not commit `.env`.
- Add rate limiting, audit logging, and deployment hardening based on your risk model.

## License

See `LICENSE`.
