Metadata-Version: 2.4
Name: fastsprout
Version: 0.1.0
Summary: Python backend framework that grows from a seed. Modular monolith first, async-native, built on FastAPI.
Project-URL: Homepage, https://fastsprout.dev
Project-URL: Documentation, https://fastsprout.dev
Project-URL: Repository, https://forgejo.3dcra.eu/fastsprout/fastsprout
Project-URL: Issues, https://forgejo.3dcra.eu/fastsprout/fastsprout/issues
Project-URL: Changelog, https://forgejo.3dcra.eu/fastsprout/fastsprout/releases
Author-email: Illia Bahlai <bahlai.illia@gmail.com>
Maintainer-email: Illia Bahlai <bahlai.illia@gmail.com>
License: MIT
License-File: LICENSE
Keywords: async,backend,fastapi,framework,modular,modular-monolith,spring
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

# FastSprout

> Python backend framework that grows from a seed.
> Modular monolith first. Async-native. Built on FastAPI.

[![PyPI version](https://img.shields.io/pypi/v/fastsprout.svg)](https://pypi.org/project/fastsprout/)
[![Python versions](https://img.shields.io/pypi/pyversions/fastsprout.svg)](https://pypi.org/project/fastsprout/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**⚠️ Early preview — 0.1.0 is a foundation release. Full framework is in active development.**

## The seed metaphor

Your backend starts as a single module — a seed. As your application grows, new modules sprout: `users`, `billing`, `notifications`. Each module is isolated, has its own boundaries (enforced by import-linter), and can be distributed as a PyPI package.

When you're ready, split into microservices. The same modules. Different deployment.

## Why FastSprout

Python lacks a Spring Boot equivalent that respects Python idioms.

- **Django** is sync-first and not truly modular
- **FastAPI** is bare metal — no structure, no modules
- **PySpring** violates Zen of Python with Java-style decorators (`@GetMapping`) and JSON config

FastSprout is **Spring-inspired but Pythonic**:

| | PySpring | FastSprout |
|---|---|---|
| Decorators | `@GetMapping` (Java-style) | `@rest(method="GET")` (Pythonic) |
| Config | JSON files | pydantic-settings |
| Repository | Method name DSL | Filter objects + `q: Select` escape hatch |
| Modules | Components in flat structure | Modular monolith with boundaries |
| Type safety | Magic at startup | mypy sees everything |
| Stack | FastAPI + Pydantic | FastAPI + SQLModel + TaskIQ + FastStream |

## Future API (in development)

```python
from fastsprout.core import BaseAction
from fastsprout.web import rest
from fastsprout.tasks import taskable
from fastsprout.events import emits

@rest(method="POST", path="/")
@taskable(retries=3)
@emits(UserCreated)
class CreateUserAction(BaseAction):
    async def __call__(self, data: UserCreate) -> User:
        ...
```

One declaration → REST endpoint + background task + emitted event. Each channel is a separate decorator from a separate fastsprout package.

## Installation

```bash
pip install fastsprout
```

## Status

This is **0.1.0** — a foundation release with the `BaseAction` protocol. The full framework is in active development.

### Roadmap

- [x] **0.1.0** — Foundation (`BaseAction` protocol)
- [ ] **0.2.0** — `fastsprout-data` (Unit of Work, Repository, Alembic helper)
- [ ] **0.3.0** — `fastsprout-web` (`@rest` decorator, FastAPI integration)
- [ ] **0.4.0** — `fastsprout-tasks` (`@taskable`, TaskIQ integration)
- [ ] **0.5.0** — `fastsprout-events` (event bus, `@event_handler`)
- [ ] **0.6.0** — `fastsprout-modulith` (module discovery, boundaries)
- [ ] **0.7.0** — `fastsprout-security` (auth, permissions)
- [ ] **0.8.0** — `fastsprout-observability` (logging, metrics, tracing)
- [ ] **0.9.0** — `fastsprout-boot` (autoconfiguration)
- [ ] **1.0.0** — Production ready

## Architecture

FastSprout is built in layers:
┌─────────────────────────────────────┐
│       USER MODULES                  │  ← your business logic
├─────────────────────────────────────┤
│       BOOT                          │  ← autoconfiguration
├─────────────────────────────────────┤
│       MODULITH                      │  ← module discovery, boundaries
├─────────────────────────────────────┤
│       INTERFACES                    │  ← @rest, @taskable, @event_handler
│       (web, tasks, events)          │     security guards here
├─────────────────────────────────────┤
│       DATA                          │  ← UoW, repositories
├─────────────────────────────────────┤
│       CORE                          │  ← contracts, BaseAction, exceptions
└─────────────────────────────────────┘
OBSERVABILITY = cross-cutting, wraps everything

Each layer is a separate PyPI package. Use what you need.

## Modules as PyPI packages

The core idea: domain modules are distributed via pip.

```bash
pip install your-billing-module
```

The module is auto-discovered through entry points, its routes/CLI/tasks/migrations are registered, its settings are merged into your app settings. No manual wiring.

```toml
# your-billing-module/pyproject.toml
[project]
dependencies = [
    "fastsprout>=1.0",
    "your-users-module>=1.0",  # module dependencies via pip
]

[project.entry-points."fastsprout.modules"]
billing = "your_billing_module"
```

## Links

- **Website**: [fastsprout.dev](https://fastsprout.dev)
- **Repository**: [forgejo.3dcra.eu/fastsprout/fastsprout](https://forgejo.3dcra.eu/fastsprout/fastsprout)
- **PyPI**: [pypi.org/project/fastsprout](https://pypi.org/project/fastsprout/)

## Author

**Illia Bahlai** — [bahlai.illia@gmail.com](mailto:bahlai.illia@gmail.com)

## License

MIT — see [LICENSE](LICENSE)
