Metadata-Version: 2.4
Name: fastappkit
Version: 0.1.8
Summary: A toolkit for building FastAPI projects with apps - internal and external pluggable apps
License: MIT
License-File: LICENSE
Keywords: fastapi,apps,plugins,migrations,framework,django-like,modular,alembic
Author: VanyLabs
Author-email: desaiparth971@gmail.com
Requires-Python: >=3.11.6,<4.0.0
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: alembic (>=1.17.2,<1.18)
Requires-Dist: fastapi (>=0.120.0,<0.130)
Requires-Dist: jinja2 (>=3.1.6,<4.0)
Requires-Dist: pydantic-settings (>=2.10.0,<3.0)
Requires-Dist: rich (>=14.0.0,<15.0)
Requires-Dist: sqlalchemy (>=2.0,<3.0)
Requires-Dist: tomlkit (>=0.13.3,<0.14)
Requires-Dist: typer (>=0.20.0,<0.21)
Requires-Dist: uvicorn[standard] (>=0.38.0,<0.39)
Project-URL: Documentation, https://fastappkit.readthedocs.io
Project-URL: Homepage, https://github.com/vanylabs/fastappkit
Project-URL: Repository, https://github.com/vanylabs/fastappkit
Description-Content-Type: text/markdown

# fastappkit

> A toolkit for building FastAPI projects with apps — internal and external pluggable apps

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

**fastappkit** brings Django-like app architecture to FastAPI, enabling modular development with both project-specific internal apps and reusable external pluggable apps.

## What is fastappkit?

**fastappkit** is a toolkit for building FastAPI projects with a modular app architecture. It enables:

-   **Internal apps** — project-specific feature modules (like Django apps)
-   **External apps** — reusable, pluggable packages (like WordPress plugins)
-   **Unified migrations** — coordinated database schema management
-   **Automatic router mounting** — seamless integration of app routes
-   **App validation and isolation** — ensure apps don't conflict with each other

## ✨ Key Features

-   ✅ **Clean project structure** with automatic app discovery
-   ✅ **Shared migrations** for internal apps, isolated migrations for external apps
-   ✅ **Automatic router mounting** with configurable prefixes
-   ✅ **Fail-fast validation** and error handling
-   ✅ **Support for both monorepo and multi-repo workflows**
-   ✅ **Simple CLI** for project and app management

## 📦 Installation

Install fastappkit using pip or poetry:

```bash
pip install fastappkit
```

or

```bash
poetry add fastappkit
```

## 🏃 Quick Start

### 1. Create a new project

```bash
fastappkit core new myproject
cd myproject
```

This creates a complete FastAPI project structure with:

-   Core application setup (including `core/models.py` with SQLAlchemy Base class)
-   Database configuration
-   Migration system
-   App directory structure

**Note:** Dependency versions in `pyproject.toml` are set to `*` by default. Update them according to your needs, especially for production deployments.

### 2. Create an internal app

```bash
fastappkit app new blog
```

This creates a new internal app in `apps/blog/` with models, router, and registers it in `fastappkit.toml`.

### 3. Run migrations

```bash
fastappkit migrate all
```

This runs all migrations in the correct order: core → internal apps → external apps.

### 4. Start the development server

```bash
fastappkit core dev
```

Your FastAPI application is now running at `http://127.0.0.1:8000`!

## 📚 Documentation

Comprehensive documentation is available at [Read the Docs](https://fastappkit.readthedocs.io/) (coming soon).

For now, see [docs/Usage.md](docs/Usage.md) for detailed usage instructions.

## 🎯 Core Concepts

### Internal Apps

Internal apps are project-specific modules that live in your project's `apps/` directory. They share the same migration system and database connection.

```bash
fastappkit app new blog
# Creates apps/blog/ with models, router, etc.
```

**Key points:**

-   Internal apps import `Base` from `core.models` for SQLAlchemy models
-   The `register()` function can return `Optional[APIRouter]` - return a router for fastappkit to mount, or mount it yourself and return `None`

### External Apps

External apps are reusable packages that can be installed via pip and plugged into any fastappkit project.

```bash
fastappkit app new payments --as-package
# Creates a standalone package structure
```

**Key points:**

-   External apps must use their own `Base` class (isolated metadata) - cannot import from core
-   The `register()` function can return `Optional[APIRouter]` - return a router for fastappkit to mount, or mount it yourself and return `None`
-   External apps must have `fastappkit.toml` manifest in the package directory

### Migrations

fastappkit provides unified migration management:

-   **Core migrations**: Project-level schema changes
-   **Internal app migrations**: Shared migration directory for all internal apps
-   **External app migrations**: Isolated migrations per external app

```bash
# Create migrations for an internal app
fastappkit migrate app blog makemigrations -m "Add post model"

# Run all migrations
fastappkit migrate all

# Preview SQL before applying
fastappkit migrate preview
```

## 🛠️ CLI Commands

### Project Management

```bash
fastappkit core new <name>          # Create a new project
fastappkit core dev                  # Run development server
```

### App Management

```bash
fastappkit app new <name>            # Create an internal app
fastappkit app new <name> --as-package  # Create an external app
fastappkit app list                  # List all apps
fastappkit app validate <name>       # Validate an app
```

### Migration Management

```bash
fastappkit migrate core -m "message"           # Create core migration
fastappkit migrate app <name> makemigrations -m "message"  # Create app migration (internal only)
fastappkit migrate app <name> upgrade [--revision <rev>]  # Upgrade app migrations (external only)
fastappkit migrate app <name> downgrade --revision <rev>  # Downgrade app migrations (external only, --revision required)
fastappkit migrate app <name> preview [--revision <rev>]  # Preview SQL for app migrations (external only)
fastappkit migrate all                        # Run all migrations
fastappkit migrate preview [--revision <rev>]  # Preview SQL for core + internal app migrations
fastappkit migrate upgrade [--revision <rev>]  # Upgrade core + internal app migrations
fastappkit migrate downgrade <rev>            # Downgrade core + internal app migrations (<rev> required)
```

## 📖 Example Project Structure

```
myproject/
├── core/
│   ├── config.py          # Settings (loads from .env)
│   ├── models.py          # SQLAlchemy Base class (DeclarativeBase)
│   ├── app.py             # create_app() factory
│   └── db/
│       └── migrations/    # Core migrations
├── apps/                   # Internal apps directory
│   └── blog/
│       ├── models.py       # Imports Base from core.models
│       └── router.py
├── fastappkit.toml        # Project configuration
├── .env                   # Environment variables
└── main.py                # Entry point
```

## 🔧 Configuration

fastappkit uses `fastappkit.toml` for project configuration:

```toml
[tool.fastappkit]
apps = [
    "apps.blog",
    "apps.users",
    "external_package_name"
]
```

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

-   Inspired by Django's app system
-   Built with [FastAPI](https://fastapi.tiangolo.com/), [SQLAlchemy](https://www.sqlalchemy.org/), [Alembic](https://alembic.sqlalchemy.org/), and [Typer](https://typer.tiangolo.com/)

## 📞 Support

-   📖 [Documentation](docs/Usage.md)
-   🐛 [Issue Tracker](https://github.com/vanylabs/fastappkit/issues)
-   💬 [Discussions](https://github.com/vanylabs/fastappkit/discussions)

---

**Made with ❤️ for the FastAPI community**

