Metadata-Version: 2.5
Name: boltra
Version: 0.5.0
Summary: A Python development toolkit for creating and running FastAPI projects
Project-URL: Homepage, https://github.com/babar-xagi/boltra
Project-URL: Repository, https://github.com/babar-xagi/boltra
Project-URL: Documentation, https://github.com/babar-xagi/boltra/tree/main/doc
Project-URL: Changelog, https://github.com/babar-xagi/boltra/blob/main/doc/plan/CHANGELOG.md
Author: Boltra Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: async,cli,fastapi,python,scaffolding
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# Boltra

**A Python development toolkit for FastAPI.**

Boltra is a Python development toolkit that creates small, readable FastAPI
projects and runs them with one command. Boltra is designed specifically for
FastAPI applications. Generated applications use ordinary
`FastAPI()` code, so you can extend them with the FastAPI APIs you already know.

The current source version is **0.5.0**. Boltra is in early development and ships
as a **pure Python package**. Its CLI uses the standard library; installing Boltra
does not require a compiler or native build toolchain.

## 📖 Contents

- [Implemented features](#-implemented-features)
- [Quick start](#-quick-start)
- [Generated project and configuration](#-project-layout-and-configuration)
- [Documentation](#-documentation)
- [Development](#-develop-boltra)

## 🧩 Implemented features

| Feature | What it does |
|---------|--------------|
| `boltra new <name>` | Creates a direct FastAPI app, settings, dependencies, and `.env.example` |
| `boltra dev` | Discovers the project, launches Uvicorn, and reloads Python changes |
| `boltra add app <name>` | Creates an app package and registers a working FastAPI router |
| Typed settings | Reads environment variables and `.env` with Pydantic settings |
| Project validation | Rejects invalid names and existing destinations; reports write failures |
| Configurable server | Reads app target, host, and port from `[tool.boltra]` |
| Windows reload support | Uses a Python compatibility runner for reliable worker restart |
| Help and version | Supports `--help`, `--version`, and `python -m boltra` |

App removal, router discovery, ORM, admin, authentication, workers, and AI are
**planned**. They are not available commands yet. See the [roadmap](https://github.com/babar-xagi/boltra/blob/main/doc/plan/phase.md).

## 🚀 Quick start

Requirements: **Python 3.12+** and **uv**. Install Boltra from PyPI as
a separate CLI tool, keeping Boltra independent of your generated app's environment.

```bash
uv tool install boltra==0.5.0

boltra new school_api
cd school_api
uv sync
cp .env.example .env
boltra dev
```

On PowerShell, `Copy-Item .env.example .env` also copies the environment example.
Set your own `SECRET_KEY` in `.env`. The generated default triggers a warning.

You can also install with `python -m pip install boltra==0.5.0` inside a Python
environment. Run `python -m boltra --help` if the console script is not on your PATH.

Open the app at [localhost:8000](http://127.0.0.1:8000/) and interactive API docs
at [localhost:8000/docs](http://127.0.0.1:8000/docs).

The home endpoint returns:

```json
{"message": "Hello from FastAPI + Boltra Kit"}
```

For other installation options and troubleshooting, read the
[installation guide](https://github.com/babar-xagi/boltra/blob/main/doc/user/installation.md).

## 📁 Project layout and configuration

```text
school_api/
├── main.py          # Your ordinary FastAPI application
├── settings.py      # Typed settings and environment loading
├── pyproject.toml   # App dependencies and development-server configuration
└── .env.example     # Example local environment variables
```

The app depends on FastAPI, Pydantic settings, and Uvicorn. Boltra itself is a CLI
tool and is not added as an app runtime dependency.

For example, add this route to `main.py` while `boltra dev` is running:

```python
@app.get("/health")
async def health() -> dict[str, str]:
    return {"status": "ok"}
```

The server reloads the change. Open `/health` or try it from `/docs`.

For routes grouped into their own package:

```bash
boltra add app students
```

This creates `apps/students/router.py` and registers its `APIRouter` in the
configured FastAPI application. Open `/students/` to receive
`{"app": "students", "status": "ok"}`. Add more routes to that router as your
app grows. See the [modular apps guide](https://github.com/babar-xagi/boltra/blob/main/doc/user/apps.md) for examples, supported
project layouts, and recovery behavior.

Change the server port in the generated `pyproject.toml`:

```toml
[tool.boltra]
mode = "fastapi-kit"
app = "main:app"
settings = "settings.py"
host = "127.0.0.1"
port = 8080
```

Restart `boltra dev` after changing `.env` or server configuration. Automatic
reload watches Python source files, not environment/configuration changes.

## 📚 Documentation

| Audience | Guide |
|----------|-------|
| Getting started | [Complete quickstart](https://github.com/babar-xagi/boltra/blob/main/doc/user/quickstart.md) |
| CLI users | [Commands, options, errors, and examples](https://github.com/babar-xagi/boltra/blob/main/doc/user/cli.md) |
| Modular API routes | [App creation and registration](https://github.com/babar-xagi/boltra/blob/main/doc/user/apps.md) |
| App developers | [Settings reference](https://github.com/babar-xagi/boltra/blob/main/doc/user/settings.md) |
| Contributors | [Developer guide](https://github.com/babar-xagi/boltra/blob/main/doc/developer/README.md) |
| Understanding the code | [Detailed file-by-file reference](https://github.com/babar-xagi/boltra/blob/main/doc/developer/file-reference.md) |
| Understanding the layout | [Repository structure](https://github.com/babar-xagi/boltra/blob/main/doc/developer/project-structure.md) |
| Validation results | [Verification report](https://github.com/babar-xagi/boltra/blob/main/doc/developer/verification.md) |
| Future work | [Python-first roadmap](https://github.com/babar-xagi/boltra/blob/main/doc/plan/phase.md) |

## 🛠️ Develop Boltra

```bash
uv sync --locked --group dev
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest
uv run pytest --cov=boltra --cov-report=term-missing
uv build
```

Source code is organized by responsibility:

```text
src/boltra/
├── cli/             # cli.py: entry point and command routing; parser.py: arguments
├── project/         # Generator, shared validation, and readable template assets
├── apps/            # App packages, name validation, and AST-based registration
└── dev/             # Project configuration, server launcher, and Windows runner
```

See [CONTRIBUTING.md](https://github.com/babar-xagi/boltra/blob/main/CONTRIBUTING.md) for checks and commit conventions.
Windows development reload terminates the old worker; application shutdown hooks
are not guaranteed during these restarts. Use normal Uvicorn without reload for
production serving.

## License

[MIT](https://github.com/babar-xagi/boltra/blob/main/LICENSE) — Boltra Contributors.
