fapilot 0.1.0__tar.gz

fapilot-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to Fapilot will be documented in this file.
+
+The format is based on Keep a Changelog, and this project follows semantic
+versioning before the public API reaches 1.0.
+
+## [0.1.0] - 2026-09-06
+
+### Added
+
+- Initial Fapilot package with Django-inspired project and app scaffolding.
+- FastAPI application factory, settings loader, app registry, middleware helpers,
+  permissions, pagination, filtering, CRUD utilities, realtime helpers, and
+  Aerich/Tortoise integration.
+- `fapilot` CLI with `startproject`, `startapp`, `makemigrations`, `migrate`,
+  and `runserver` commands.

fapilot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fapilot maintainers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fapilot-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include SECURITY.md
+include fapilot/py.typed
+recursive-include fapilot *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.py[cod]
+prune tests
+prune .github
+prune fapilot.egg-info

fapilot-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.2
+Name: fapilot
+Version: 0.1.0
+Summary: A Django-inspired async application framework built on FastAPI, Tortoise ORM, and Aerich.
+Author: Ali Hajiali
+Maintainer: Ali Hajiali
+License: MIT
+Project-URL: Homepage, https://github.com/alihajiali/fapilot
+Project-URL: Repository, https://github.com/alihajiali/fapilot
+Project-URL: Issues, https://github.com/alihajiali/fapilot/issues
+Project-URL: Changelog, https://github.com/alihajiali/fapilot/blob/main/CHANGELOG.md
+Keywords: fastapi,async,framework,tortoise-orm,aerich,django-inspired
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi<0.142,>=0.141
+Requires-Dist: starlette<0.50,>=0.49
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: pydantic-settings<3,>=2.10
+Requires-Dist: tortoise-orm[asyncpg]<1.2,>=1.1
+Requires-Dist: aerich[toml]<0.11,>=0.10
+Requires-Dist: uvicorn[standard]<0.36,>=0.35
+Requires-Dist: python-jose<4,>=3.5
+Requires-Dist: passlib[bcrypt]<2,>=1.7
+Requires-Dist: python-multipart<0.0.21,>=0.0.20
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.3; extra == "dev"
+Requires-Dist: pytest<9,>=8.4; extra == "dev"
+Requires-Dist: pytest-anyio>=0.0.0; extra == "dev"
+Requires-Dist: httpx<0.29,>=0.28; extra == "dev"
+Requires-Dist: ruff<0.13,>=0.12; extra == "dev"
+Requires-Dist: pyright<2,>=1.1; extra == "dev"
+Requires-Dist: twine<7,>=6.2; extra == "dev"
+
+# Fapilot
+
+Fapilot is an opinionated, async-first backend framework built on FastAPI. It borrows Django's project organization, app registry, settings discipline, scaffolding, and management-command ergonomics while keeping FastAPI's dependency injection, OpenAPI, lifespan, and async runtime model.
+
+## Features
+
+- Django-inspired project and app scaffolding.
+- FastAPI application factory with app registry integration.
+- Pydantic settings loader with uppercase application settings.
+- Tortoise ORM configuration and Aerich migration backend.
+- Pagination, filtering, CRUD, permissions, middleware, events, auth, and realtime helpers.
+- CLI commands for project creation, app creation, migrations, and local serving.
+
+## Installation
+
+For local development from this repository:
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e ".[dev]"
+```
+
+After installation, the `fapilot` command is available on your shell path:
+
+```bash
+fapilot --help
+```
+
+You can also run the CLI directly from a checkout:
+
+```bash
+python3.12 -m fapilot.cli --help
+```
+
+## Quick Start
+
+```bash
+python3.12 -m pip install -e .
+fapilot startproject myproject
+cd myproject
+fapilot startapp users
+fapilot makemigrations
+fapilot migrate
+fapilot runserver
+```
+
+Core stack:
+
+- FastAPI + Starlette lifespan
+- Pydantic v2 + pydantic-settings
+- Tortoise ORM
+- Aerich migrations through a backend abstraction
+- Uvicorn
+- pytest, HTTPX, AnyIO
+- Ruff and Pyright
+
+This repository contains the reusable framework package. Generated projects contain `config/`, `apps/`, `common/`, `manage.py`, Docker files, `.env`, and a project-local `pyproject.toml`.
+
+## CLI
+
+```bash
+fapilot startproject myproject
+fapilot startapp users
+fapilot makemigrations --name initial
+fapilot migrate
+fapilot runserver --host 127.0.0.1 --port 8000
+```
+
+## Development
+
+```bash
+ruff check .
+pyright
+pytest
+python -m build
+twine check dist/*
+```
+
+## Release
+
+See [RELEASE.md](RELEASE.md) for the release checklist and PyPI publishing flow.
+
+## License
+
+Fapilot is released under the MIT License. See [LICENSE](LICENSE).

fapilot-0.1.0/README.md

@@ -0,0 +1,87 @@
+# Fapilot
+
+Fapilot is an opinionated, async-first backend framework built on FastAPI. It borrows Django's project organization, app registry, settings discipline, scaffolding, and management-command ergonomics while keeping FastAPI's dependency injection, OpenAPI, lifespan, and async runtime model.
+
+## Features
+
+- Django-inspired project and app scaffolding.
+- FastAPI application factory with app registry integration.
+- Pydantic settings loader with uppercase application settings.
+- Tortoise ORM configuration and Aerich migration backend.
+- Pagination, filtering, CRUD, permissions, middleware, events, auth, and realtime helpers.
+- CLI commands for project creation, app creation, migrations, and local serving.
+
+## Installation
+
+For local development from this repository:
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e ".[dev]"
+```
+
+After installation, the `fapilot` command is available on your shell path:
+
+```bash
+fapilot --help
+```
+
+You can also run the CLI directly from a checkout:
+
+```bash
+python3.12 -m fapilot.cli --help
+```
+
+## Quick Start
+
+```bash
+python3.12 -m pip install -e .
+fapilot startproject myproject
+cd myproject
+fapilot startapp users
+fapilot makemigrations
+fapilot migrate
+fapilot runserver
+```
+
+Core stack:
+
+- FastAPI + Starlette lifespan
+- Pydantic v2 + pydantic-settings
+- Tortoise ORM
+- Aerich migrations through a backend abstraction
+- Uvicorn
+- pytest, HTTPX, AnyIO
+- Ruff and Pyright
+
+This repository contains the reusable framework package. Generated projects contain `config/`, `apps/`, `common/`, `manage.py`, Docker files, `.env`, and a project-local `pyproject.toml`.
+
+## CLI
+
+```bash
+fapilot startproject myproject
+fapilot startapp users
+fapilot makemigrations --name initial
+fapilot migrate
+fapilot runserver --host 127.0.0.1 --port 8000
+```
+
+## Development
+
+```bash
+ruff check .
+pyright
+pytest
+python -m build
+twine check dist/*
+```
+
+## Release
+
+See [RELEASE.md](RELEASE.md) for the release checklist and PyPI publishing flow.
+
+## License
+
+Fapilot is released under the MIT License. See [LICENSE](LICENSE).

fapilot-0.1.0/SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Supported versions
+
+Fapilot is currently pre-1.0. Security fixes are provided for the latest
+released version.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for suspected vulnerabilities.
+
+Email the maintainers or use GitHub private vulnerability reporting if it is
+enabled for the repository. Include:
+
+- Affected version or commit.
+- Steps to reproduce.
+- Impact and any known workarounds.
+
+We aim to acknowledge reports within 72 hours.

fapilot-0.1.0/fapilot/__init__.py

@@ -0,0 +1,5 @@
+from fapilot.core.application import Fapilot, create_app
+
+__version__ = "0.1.0"
+
+__all__ = ["Fapilot", "__version__", "create_app"]

fapilot-0.1.0/fapilot/apps/__init__.py

@@ -0,0 +1,5 @@
+from fapilot.apps.config import AppConfig
+from fapilot.apps.registry import AppRegistry
+
+__all__ = ["AppConfig", "AppRegistry"]
+

fapilot-0.1.0/fapilot/apps/config.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from fastapi import APIRouter
+
+
+@dataclass(slots=True)
+class AppConfig:
+    name: str
+    label: str | None = None
+    verbose_name: str | None = None
+    router: APIRouter | None = None
+    router_prefix: str | None = None
+    tortoise_models: list[str] = field(default_factory=list)
+    migrations_package: str | None = None
+
+    def ready(self) -> None:
+        """Hook called after every app is imported and registered."""
+
+    @property
+    def app_label(self) -> str:
+        return self.label or self.name.rsplit(".", 1)[-1]
+
+    def as_tortoise_app(self) -> dict[str, Any]:
+        models = [*self.tortoise_models]
+        if self.migrations_package is not None:
+            models.append(self.migrations_package)
+        return {"models": models, "default_connection": "default"}
+

fapilot-0.1.0/fapilot/apps/registry.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from importlib import import_module
+
+from fapilot.apps.config import AppConfig
+
+
+class AppRegistry:
+    def __init__(self) -> None:
+        self._apps: dict[str, AppConfig] = {}
+        self.ready = False
+
+    def populate(self, installed_apps: Iterable[str]) -> None:
+        if self.ready:
+            return
+        for dotted_path in installed_apps:
+            app_config = self._load_config(dotted_path)
+            label = app_config.app_label
+            if label in self._apps:
+                raise RuntimeError(f"Duplicate app label: {label}")
+            self._apps[label] = app_config
+        for app_config in self._apps.values():
+            app_config.ready()
+        self.ready = True
+
+    def get_app(self, label: str) -> AppConfig:
+        return self._apps[label]
+
+    def get_apps(self) -> list[AppConfig]:
+        return list(self._apps.values())
+
+    def _load_config(self, dotted_path: str) -> AppConfig:
+        module_path, _, class_name = dotted_path.rpartition(".")
+        if not module_path:
+            module_path = f"{dotted_path}.apps"
+            class_name = "Config"
+        module = import_module(module_path)
+        config_cls = getattr(module, class_name)
+        config = config_cls()
+        if not isinstance(config, AppConfig):
+            raise TypeError(f"{dotted_path} must instantiate fapilot.apps.AppConfig")
+        return config

fapilot-0.1.0/fapilot/auth/__init__.py

@@ -0,0 +1,5 @@
+from fapilot.auth.jwt import create_access_token, decode_access_token
+from fapilot.auth.passwords import hash_password, verify_password
+
+__all__ = ["create_access_token", "decode_access_token", "hash_password", "verify_password"]
+

fapilot-0.1.0/fapilot/auth/jwt.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+from jose import JWTError, jwt
+
+from fapilot.conf import get_settings
+
+
+def create_access_token(subject: str, claims: dict[str, Any] | None = None) -> str:
+    settings = get_settings()
+    jwt_settings = settings.JWT_SETTINGS
+    expires_at = datetime.now(UTC) + timedelta(minutes=jwt_settings.access_token_expire_minutes)
+    payload = {
+        "sub": subject,
+        "iss": jwt_settings.issuer,
+        "exp": expires_at,
+        **(claims or {}),
+    }
+    return jwt.encode(payload, settings.SECRET_KEY, algorithm=jwt_settings.algorithm)
+
+
+def decode_access_token(token: str) -> dict[str, Any] | None:
+    settings = get_settings()
+    try:
+        return jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.JWT_SETTINGS.algorithm])
+    except JWTError:
+        return None
+

fapilot-0.1.0/fapilot/auth/passwords.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from passlib.context import CryptContext
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+
+def hash_password(password: str) -> str:
+    return pwd_context.hash(password)
+
+
+def verify_password(password: str, hashed_password: str) -> bool:
+    return pwd_context.verify(password, hashed_password)
+

fapilot-0.1.0/fapilot/background/__init__.py

@@ -0,0 +1,4 @@
+from fapilot.background.tasks import TaskQueue
+
+__all__ = ["TaskQueue"]
+

fapilot-0.1.0/fapilot/background/tasks.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+
+class TaskQueue:
+    def spawn(
+        self,
+        func: Callable[..., Coroutine[Any, Any, Any]],
+        *args: Any,
+        **kwargs: Any,
+    ) -> asyncio.Task:
+        return asyncio.create_task(func(*args, **kwargs))

fapilot-0.1.0/fapilot/cli.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import argparse
+import subprocess
+from pathlib import Path
+
+from fapilot.db.migrations import AerichMigrationBackend
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="fapilot")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    startproject = subparsers.add_parser("startproject")
+    startproject.add_argument("name")
+    startapp = subparsers.add_parser("startapp")
+    startapp.add_argument("name")
+    makemigrations = subparsers.add_parser("makemigrations")
+    makemigrations.add_argument("--name")
+    subparsers.add_parser("migrate")
+    runserver = subparsers.add_parser("runserver")
+    runserver.add_argument("--host", default="127.0.0.1")
+    runserver.add_argument("--port", default="8000")
+    args = parser.parse_args()
+
+    if args.command == "startproject":
+        start_project(args.name)
+    elif args.command == "startapp":
+        start_app(args.name)
+    elif args.command == "makemigrations":
+        AerichMigrationBackend().makemigrations(args.name)
+    elif args.command == "migrate":
+        AerichMigrationBackend().migrate()
+    elif args.command == "runserver":
+        subprocess.run(
+            ["uvicorn", "config.asgi:app", "--host", args.host, "--port", args.port, "--reload"],
+            check=True,
+        )
+
+
+def start_project(name: str) -> None:
+    root = Path(name)
+    root.mkdir()
+    for directory in ["config", "apps", "common", "tests"]:
+        (root / directory).mkdir()
+        (root / directory / "__init__.py").write_text("", encoding="utf-8")
+    _write(root / "manage.py", MANAGE)
+    _write(root / "config/settings.py", SETTINGS)
+    _write(root / "config/database.py", DATABASE)
+    _write(root / "config/urls.py", URLS)
+    _write(root / "config/asgi.py", ASGI)
+    _write(root / "config/logging.py", "LOGGING = {}\n")
+    _write(root / "common/crud.py", "from fapilot.crud import CRUDRouterService\n")
+    _write(root / "common/pagination.py", "from fapilot.pagination import Page, Pagination\n")
+    _write(root / "common/filtering.py", "from fapilot.filtering import pick_filters\n")
+    _write(root / "common/exceptions.py", "from fapilot.exceptions import FapilotError\n")
+    _write(
+        root / "common/permissions.py",
+        "from fapilot.permissions import AllowAny, IsAuthenticated\n",
+    )
+    _write(root / "common/middleware.py", "from fapilot.middleware import install_cors\n")
+    _write(root / "common/responses.py", "from fapilot.responses import ok\n")
+    _write(root / "common/events.py", "from fapilot.events import SignalDispatcher\n")
+    _write(root / "common/models.py", "from tortoise import fields, models\n")
+    _write(root / "common/schemas.py", "from pydantic import BaseModel, ConfigDict\n")
+    _write(root / "common/utils.py", "\n")
+    _write(root / ".env", ENV)
+    _write(root / ".env.example", ENV)
+    _write(root / ".gitignore", GITIGNORE)
+    _write(root / "README.md", PROJECT_README.format(name=name))
+    _write(root / "Dockerfile", DOCKERFILE)
+    _write(root / "docker-compose.yml", COMPOSE)
+    _write(root / "pyproject.toml", PROJECT_PYPROJECT.format(name=name))
+
+
+def start_app(name: str) -> None:
+    app_dir = Path("apps") / name
+    app_dir.mkdir(parents=True)
+    (app_dir / "tests").mkdir()
+    (app_dir / "migrations").mkdir()
+    for file_name, content in APP_FILES.items():
+        class_name = name.title().replace("_", "")
+        _write(app_dir / file_name, content.format(name=name, class_name=class_name))
+    _write(app_dir / "tests/__init__.py", "")
+    _write(app_dir / "migrations/__init__.py", "")
+
+
+def _write(path: Path, content: str) -> None:
+    path.write_text(content, encoding="utf-8")
+
+
+MANAGE = """#!/usr/bin/env python
+from fapilot.cli import main
+
+if __name__ == "__main__":
+    main()
+"""
+
+SETTINGS = '''from fapilot.conf import FapilotSettings
+
+DEBUG = True
+SECRET_KEY = "change-me"
+ALLOWED_HOSTS = ["localhost", "127.0.0.1"]
+DATABASE_URL = "sqlite://db.sqlite3"
+INSTALLED_APPS = []
+MIDDLEWARE = ["common.middleware.install_cors"]
+CORS_ALLOWED_ORIGINS = []
+TIME_ZONE = "UTC"
+LANGUAGE_CODE = "en-us"
+API_PREFIX = "/api"
+DEFAULT_PAGE_SIZE = 20
+MAX_PAGE_SIZE = 100
+AUTH_USER_MODEL = "users.User"
+JWT_SETTINGS = FapilotSettings().JWT_SETTINGS
+LOGGING = {}
+'''
+
+DATABASE = """import os
+
+from fapilot.apps import AppRegistry
+from fapilot.conf import load_settings
+from fapilot.db.tortoise import build_tortoise_config
+
+settings = load_settings("config.settings")
+registry = AppRegistry()
+registry.populate(settings.INSTALLED_APPS)
+TORTOISE_ORM = build_tortoise_config(settings, registry)
+"""
+
+URLS = """from fastapi import APIRouter
+
+router = APIRouter()
+"""
+
+ASGI = """import os
+
+from fapilot import create_app
+from fapilot.conf import load_settings
+
+os.environ.setdefault("FAPILOT_SETTINGS_MODULE", "config.settings")
+app = create_app(load_settings("config.settings"))
+"""
+
+ENV = """DEBUG=true
+SECRET_KEY=change-me
+DATABASE_URL=sqlite://db.sqlite3
+"""
+
+GITIGNORE = """.venv/
+__pycache__/
+.env
+db.sqlite3
+.ruff_cache/
+.pytest_cache/
+"""
+
+PROJECT_README = """# {name}
+
+Generated by Fapilot.
+
+```bash
+uv sync
+fapilot startapp users
+fapilot runserver
+```
+"""
+
+PROJECT_PYPROJECT = '''[project]
+name = "{name}"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = ["fapilot"]
+
+[tool.aerich]
+tortoise_orm = "config.database.TORTOISE_ORM"
+location = "./migrations"
+src_folder = "."
+'''
+
+DOCKERFILE = """FROM python:3.12-slim
+WORKDIR /app
+COPY . .
+RUN pip install fapilot
+CMD ["uvicorn", "config.asgi:app", "--host", "0.0.0.0", "--port", "8000"]
+"""
+
+COMPOSE = """services:
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_DB: app
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: app
+    ports:
+      - "5432:5432"
+"""
+
+APP_FILES = {
+    "__init__.py": "",
+    "apps.py": """from fapilot.apps import AppConfig
+
+
+class {class_name}Config(AppConfig):
+    def __init__(self) -> None:
+        super().__init__(name="apps.{name}", label="{name}")
+""",
+    "models.py": "from tortoise import fields, models\n\n\n# Define models here.\n",
+    "schemas.py": "from pydantic import BaseModel, ConfigDict\n\n\n# Define schemas here.\n",
+    "api.py": """from fastapi import APIRouter
+
+router = APIRouter()
+""",
+    "services.py": "",
+    "repositories.py": "",
+    "permissions.py": "from fapilot.permissions import AllowAny, IsAuthenticated\n",
+    "dependencies.py": "",
+    "signals.py": "",
+    "admin.py": "",
+}

fapilot-0.1.0/fapilot/conf/__init__.py

@@ -0,0 +1,4 @@
+from fapilot.conf.settings import FapilotSettings, get_settings, load_settings
+
+__all__ = ["FapilotSettings", "get_settings", "load_settings"]
+