fastapi-fastio 0.1.2__py3-none-any.whl

fastio/main.py

@@ -0,0 +1,5 @@
+from fastio.cli.app import app
+
+
+def run() -> None:
+    app()

fastio/models/options.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+
+Mode = Literal["service", "monolith", "monorepo"]
+Blueprint = Literal["base", "crud-service", "user-service", "telegram-bot"]
+Database = Literal["sqlite", "postgres"]
+AlchemyMode = Literal["sync", "async"]
+TelegramTemplate = Literal["membership", "police-group", "airdrop", "ecommerce"]
+
+
+class ProjectOptions(BaseModel):
+    name: str = Field(min_length=2)
+    output_dir: Path
+    mode: Mode = "service"
+    blueprint: Blueprint = "base"
+    database: Database = "sqlite"
+    sqlalchemy_mode: AlchemyMode = "sync"
+    use_sqladmin: bool = True
+    use_celery: bool = True
+    use_docker: bool = True
+    use_tests: bool = True
+    use_ci: bool = True
+    use_fastapi_users: bool = False
+    use_google_oauth: bool = False
+    use_telegram_bot: bool = False
+    telegram_template: Optional[TelegramTemplate] = None
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, value: str) -> str:
+        clean = value.strip()
+        if not clean:
+            raise ValueError("Project name cannot be empty.")
+        return clean
+
+    @property
+    def project_dir(self) -> Path:
+        return self.output_dir / self.name
+
+    @property
+    def package_name(self) -> str:
+        return self.name.replace("-", "_")
+
+    @property
+    def app_import_path(self) -> str:
+        return "app.main:app"
+
+    @property
+    def uses_async(self) -> bool:
+        return self.sqlalchemy_mode == "async"
+
+    def normalized(self) -> "ProjectOptions":
+        data = self.model_dump()
+        if self.blueprint == "user-service":
+            data["use_fastapi_users"] = True
+            data["use_google_oauth"] = True
+            data["sqlalchemy_mode"] = "async"
+        elif self.blueprint == "telegram-bot":
+            data["use_telegram_bot"] = True
+        return ProjectOptions(**data)

fastio/renderers/jinja.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader, StrictUndefined, select_autoescape
+
+_TEMPLATES_DIR = Path(__file__).parent.parent / "templates"
+
+
+@lru_cache(maxsize=1)
+def get_environment() -> Environment:
+    return Environment(
+        loader=FileSystemLoader(str(_TEMPLATES_DIR)),
+        autoescape=select_autoescape(enabled_extensions=("html", "xml")),
+        keep_trailing_newline=True,
+        lstrip_blocks=True,
+        trim_blocks=True,
+        undefined=StrictUndefined,
+    )

fastio/renderers/writer.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def write_text(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8", newline="\n")

fastio/templates/common/Dockerfile.j2

@@ -0,0 +1,9 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY . /app
+
+RUN pip install uv && uv sync --frozen || uv sync
+
+EXPOSE 8000
+CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

fastio/templates/common/compose.yml.j2

@@ -0,0 +1,58 @@
+version: '3.8'
+
+services:
+  app:
+    build: .
+    ports:
+      - "8000:8000"
+    environment:
+      - DATABASE_URL=postgresql://{{ project_name }}:password@db:5432/{{ project_name }}
+      - REDIS_URL=redis://redis:6379/0
+    depends_on:
+      - db
+      - redis
+    volumes:
+      - .:/app
+    command: uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+
+{% if project.database == "postgres" %}
+  db:
+    image: postgres:16-alpine
+    environment:
+      - POSTGRES_USER={{ project_name }}
+      - POSTGRES_PASSWORD=password
+      - POSTGRES_DB={{ project_name }}
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+{% endif %}
+
+{% if project.use_celery %}
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+
+  celery:
+    build: .
+    command: uv run celery -A app.tasks.celery_app worker --loglevel=info
+    environment:
+      - DATABASE_URL=postgresql://{{ project_name }}:password@db:5432/{{ project_name }}
+      - REDIS_URL=redis://redis:6379/0
+    depends_on:
+      - db
+      - redis
+    volumes:
+      - .:/app
+{% endif %}
+
+volumes:
+{% if project.database == "postgres" %}
+  postgres_data:
+{% endif %}
+{% if project.use_celery %}
+  redis_data:
+{% endif %}

fastio/templates/common/env.example.j2

@@ -0,0 +1,20 @@
+APP_NAME={{ project_name }}
+ENVIRONMENT=local
+DEBUG=true
+{% if project.database == "postgres" %}
+DATABASE_URL=postgresql://{{ project_name }}:password@localhost:5432/{{ project_name }}
+{% else %}
+DATABASE_URL=sqlite:///./{{ package_name }}.db
+{% endif %}
+SECRET_KEY=change-me
+{% if project.use_celery %}
+CELERY_BROKER_URL=redis://localhost:6379/0
+CELERY_RESULT_BACKEND=redis://localhost:6379/1
+{% endif %}
+{% if project.use_google_oauth %}
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+{% endif %}
+{% if project.use_telegram_bot %}
+TELEGRAM_BOT_TOKEN=
+{% endif %}

fastio/templates/common/gitignore.j2

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.db
+*.sqlite3
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage

fastio/templates/common/publish.yml.j2

@@ -0,0 +1,33 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Build
+        run: |
+          uv sync --group dev
+          uv run python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fastio/templates/common/test_smoke.py.j2

@@ -0,0 +1,2 @@
+def test_smoke() -> None:
+    assert True

fastio/templates/monolith/README.md.j2

@@ -0,0 +1,11 @@
+# {{ project_name }}
+
+Generated modular monolith by `fastio`.
+
+## Run locally
+
+```bash
+uv sync
+uv run alembic upgrade head
+uv run fastapi dev app.main:app
+```

fastio/templates/monolith/alembic.ini.j2

@@ -0,0 +1,7 @@
+[alembic]
+script_location = alembic
+{% if project.database == "postgres" %}
+sqlalchemy.url = postgresql://{{ project_name }}:password@localhost:5432/{{ project_name }}
+{% else %}
+sqlalchemy.url = sqlite:///./{{ package_name }}.db
+{% endif %}

fastio/templates/monolith/app/core/config.py.j2

@@ -0,0 +1,22 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    app_name: str = "{{ project_name }}"
+    environment: str = "local"
+    debug: bool = True
+{% if project.database == "postgres" %}
+    database_url: str = "postgresql://{{ project_name }}:password@localhost:5432/{{ project_name }}"
+{% else %}
+    database_url: str = "sqlite:///./{{ package_name }}.db"
+{% endif %}
+    secret_key: str = "change-me"
+{% if project.use_celery %}
+    celery_broker_url: str = "redis://localhost:6379/0"
+    celery_result_backend: str = "redis://localhost:6379/1"
+{% endif %}
+
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+
+
+settings = Settings()

fastio/templates/monolith/app/main.py.j2

@@ -0,0 +1,11 @@
+from fastapi import FastAPI
+
+from app.modules.users.api import router as users_router
+
+app = FastAPI(title="{{ project_name }}", docs_url="/docs")
+app.include_router(users_router, prefix="/api/v1/users", tags=["users"])
+
+
+@app.get("/health/live")
+def live() -> dict[str, str]:
+    return {"status": "ok"}

fastio/templates/monolith/app/modules/users/api.py.j2

@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("/")
+def list_users() -> list[dict[str, str]]:
+    return [{"id": "1", "email": "admin@example.com"}]

fastio/templates/monolith/app/modules/users/models.py.j2

@@ -0,0 +1,2 @@
+class User:
+    pass

fastio/templates/monolith/app/modules/users/schemas.py.j2

@@ -0,0 +1,6 @@
+from pydantic import BaseModel
+
+
+class UserRead(BaseModel):
+    id: str
+    email: str

fastio/templates/monolith/app/modules/users/service.py.j2

@@ -0,0 +1,3 @@
+class UserService:
+    def list_users(self) -> list[dict[str, str]]:
+        return [{"id": "1", "email": "admin@example.com"}]

fastio/templates/monolith/app/tasks/celery_app.py.j2

@@ -0,0 +1,18 @@
+from celery import Celery
+
+from app.core.config import settings
+
+celery_app = Celery(
+    "{{ project_name }}",
+    broker=settings.celery_broker_url,
+    backend=settings.celery_result_backend,
+)
+
+celery_app.conf.update(
+    task_serializer="json",
+    accept_content=["json"],
+    result_serializer="json",
+    timezone="UTC",
+    enable_utc=True,
+    task_track_started=True,
+)

fastio/templates/monolith/pyproject.toml.j2

@@ -0,0 +1,43 @@
+[project]
+name = "{{ project_name }}"
+version = "0.1.0"
+description = "{{ project_name }} generated by fastio"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "fastapi[standard]>=0.115.0",
+  "sqlalchemy>=2.0.35",
+  "alembic>=1.13.2",
+  "pydantic>=2.8.2",
+  "pydantic-settings>=2.4.0",
+{% if project.use_sqladmin %}
+  "sqladmin>=0.18.0",
+{% endif %}
+{% if project.use_celery %}
+  "celery[redis]>=5.4.0",
+{% endif %}
+{% if project.uses_async and project.database == "postgres" %}
+  "asyncpg>=0.29.0",
+{% elif project.uses_async %}
+  "aiosqlite>=0.20.0",
+{% elif project.database == "postgres" %}
+  "psycopg2-binary>=2.9.9",
+{% endif %}
+{% if project.use_fastapi_users %}
+  "fastapi-users[sqlalchemy,oauth]>=13.0.0",
+{% endif %}
+]
+
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+package = false
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3.2",
+  "httpx>=0.27.2",
+  "ruff>=0.6.5",
+]

fastio/templates/monorepo/README.md.j2

@@ -0,0 +1,9 @@
+# {{ project_name }}
+
+Generated monorepo by `fastio`.
+
+## Layout
+
+- `services/` independent services
+- `packages/` shared internal packages
+- each service owns its DB and migrations

fastio/templates/monorepo/packages/shared-auth/README.md.j2

@@ -0,0 +1,3 @@
+# shared-auth
+
+JWT verification helpers, service tokens, and role constants.

fastio/templates/monorepo/packages/shared-clients/README.md.j2

@@ -0,0 +1,3 @@
+# shared-clients
+
+Internal HTTP clients, retry helpers, and auth header helpers.

fastio/templates/monorepo/packages/shared-events/README.md.j2

@@ -0,0 +1,3 @@
+# shared-events
+
+Event names, task payload schemas, and event contracts.

fastio/templates/monorepo/packages/shared-schemas/README.md.j2

@@ -0,0 +1,3 @@
+# shared-schemas
+
+Common DTOs, pagination schemas, and API response envelopes.

fastio/templates/monorepo/pyproject.toml.j2

@@ -0,0 +1,11 @@
+[project]
+name = "{{ project_name }}"
+version = "0.1.1"
+requires-python = ">=3.11"
+
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[tool.uv.workspace]
+members = ["services/*", "packages/*"]

fastio/templates/service/README.md.j2

@@ -0,0 +1,47 @@
+# {{ project_name }}
+
+Generated by `fastio`.
+
+## Run locally
+
+```bash
+uv sync
+uv run alembic upgrade head
+uv run fastapi dev app.main:app
+```
+
+## Structure
+
+- `app/api/v1` for versioned routes
+- `app/services` for business logic
+{% if project.use_celery %}
+- `app/tasks` for Celery jobs
+{% endif %}
+- `app/db` for SQLAlchemy setup
+{% if project.use_sqladmin %}
+- `app/admin.py` for SQLAdmin at `/admin`
+{% endif %}
+{% if project.use_celery %}
+
+## Celery
+
+Start a worker:
+
+```bash
+uv run celery -A app.tasks.celery_app worker --loglevel=info
+```
+
+> **Windows:** Celery's default prefork pool is not supported on Windows.
+> Use `--pool=solo` for local development:
+> ```bash
+> uv run celery -A app.tasks.celery_app worker --loglevel=info --pool=solo
+> ```
+{% endif %}
+{% if project.use_docker %}
+
+## Docker
+
+```bash
+docker compose up --build
+```
+{% endif %}

fastio/templates/service/alembic.ini.j2

@@ -0,0 +1,7 @@
+[alembic]
+script_location = alembic
+{% if project.database == "postgres" %}
+sqlalchemy.url = postgresql://{{ project_name }}:password@localhost:5432/{{ project_name }}
+{% else %}
+sqlalchemy.url = sqlite:///./{{ package_name }}.db
+{% endif %}

fastio/templates/service/app/admin.py.j2

@@ -0,0 +1,137 @@
+from fastapi import FastAPI
+from sqladmin import Admin, ModelView
+
+from app.db.session import engine
+
+{% if project.blueprint == "crud-service" %}
+from app.db.models.item import Item
+
+
+class ItemAdmin(ModelView, model=Item):
+    name = "Item"
+    name_plural = "Items"
+    icon = "fa-solid fa-box"
+    column_list = [Item.id, Item.name, Item.slug]
+    column_searchable_list = [Item.name, Item.slug]
+    column_sortable_list = [Item.id, Item.name]
+
+{% elif project.blueprint == "user-service" %}
+class UserAdmin:
+    pass
+
+{% elif project.blueprint == "telegram-bot" and project.telegram_template == "membership" %}
+from app.db.models.member import Member
+
+
+class MemberAdmin(ModelView, model=Member):
+    name = "Member"
+    name_plural = "Members"
+    icon = "fa-solid fa-users"
+    column_list = [Member.id, Member.telegram_id, Member.first_name, Member.username, Member.phone, Member.is_active, Member.created_at]
+    column_searchable_list = [Member.first_name, Member.username, Member.phone]
+    column_sortable_list = [Member.id, Member.first_name, Member.created_at]
+    column_filters = [Member.is_active]
+    can_create = True
+    can_edit = True
+    can_delete = True
+    can_view_details = True
+    form_columns = [Member.first_name, Member.username, Member.phone, Member.is_active]
+
+{% elif project.blueprint == "telegram-bot" and project.telegram_template == "police-group" %}
+from app.db.models.report import Report, Warning
+
+
+class ReportAdmin(ModelView, model=Report):
+    name = "Report"
+    name_plural = "Reports"
+    icon = "fa-solid fa-flag"
+    column_list = [Report.id, Report.group_id, Report.reporter_id, Report.reported_id, Report.reported_username, Report.reason, Report.created_at]
+    column_searchable_list = [Report.reported_username, Report.reason]
+    column_sortable_list = [Report.id, Report.created_at]
+    can_create = False
+    can_edit = False
+    can_delete = True
+    can_view_details = True
+
+
+class WarningAdmin(ModelView, model=Warning):
+    name = "Warning"
+    name_plural = "Warnings"
+    icon = "fa-solid fa-triangle-exclamation"
+    column_list = [Warning.id, Warning.group_id, Warning.user_id, Warning.username, Warning.reason, Warning.issued_by, Warning.created_at]
+    column_searchable_list = [Warning.username, Warning.reason]
+    column_sortable_list = [Warning.id, Warning.user_id, Warning.created_at]
+    can_create = False
+    can_edit = False
+    can_delete = True
+    can_view_details = True
+
+{% elif project.blueprint == "telegram-bot" and project.telegram_template == "airdrop" %}
+from app.db.models.participant import Participant
+
+
+class ParticipantAdmin(ModelView, model=Participant):
+    name = "Participant"
+    name_plural = "Participants"
+    icon = "fa-solid fa-parachute-box"
+    column_list = [Participant.id, Participant.telegram_id, Participant.first_name, Participant.username, Participant.wallet_address, Participant.referral_code, Participant.points, Participant.is_verified, Participant.created_at]
+    column_searchable_list = [Participant.first_name, Participant.username, Participant.wallet_address, Participant.referral_code]
+    column_sortable_list = [Participant.id, Participant.points, Participant.created_at]
+    column_filters = [Participant.is_verified]
+    can_create = False
+    can_edit = True
+    can_delete = True
+    can_view_details = True
+    form_columns = [Participant.wallet_address, Participant.points, Participant.is_verified]
+
+{% elif project.blueprint == "telegram-bot" and project.telegram_template == "ecommerce" %}
+from app.db.models.order import Order
+from app.db.models.product import Product
+
+
+class ProductAdmin(ModelView, model=Product):
+    name = "Product"
+    name_plural = "Products"
+    icon = "fa-solid fa-tag"
+    column_list = [Product.id, Product.name, Product.price, Product.stock, Product.is_active, Product.created_at]
+    column_searchable_list = [Product.name]
+    column_sortable_list = [Product.id, Product.name, Product.price, Product.stock]
+    column_filters = [Product.is_active]
+    can_create = True
+    can_edit = True
+    can_delete = True
+    can_view_details = True
+    form_columns = [Product.name, Product.description, Product.price, Product.stock, Product.is_active]
+
+
+class OrderAdmin(ModelView, model=Order):
+    name = "Order"
+    name_plural = "Orders"
+    icon = "fa-solid fa-cart-shopping"
+    column_list = [Order.id, Order.telegram_id, Order.username, Order.product_id, Order.quantity, Order.total_price, Order.status, Order.created_at]
+    column_searchable_list = [Order.username, Order.status]
+    column_sortable_list = [Order.id, Order.total_price, Order.status, Order.created_at]
+    column_filters = [Order.status]
+    can_create = False
+    can_edit = True
+    can_delete = True
+    can_view_details = True
+    form_columns = [Order.status]
+
+{% endif %}
+
+def setup_admin(app: FastAPI) -> None:
+    admin = Admin(app, engine, base_url="/admin")
+{% if project.blueprint == "crud-service" %}
+    admin.add_view(ItemAdmin)
+{% elif project.blueprint == "telegram-bot" and project.telegram_template == "membership" %}
+    admin.add_view(MemberAdmin)
+{% elif project.blueprint == "telegram-bot" and project.telegram_template == "police-group" %}
+    admin.add_view(ReportAdmin)
+    admin.add_view(WarningAdmin)
+{% elif project.blueprint == "telegram-bot" and project.telegram_template == "airdrop" %}
+    admin.add_view(ParticipantAdmin)
+{% elif project.blueprint == "telegram-bot" and project.telegram_template == "ecommerce" %}
+    admin.add_view(ProductAdmin)
+    admin.add_view(OrderAdmin)
+{% endif %}

fastio/templates/service/app/api/deps.py.j2

@@ -0,0 +1,13 @@
+from collections.abc import Generator
+
+from sqlalchemy.orm import Session
+
+from app.db.session import SessionLocal
+
+
+def get_db() -> Generator[Session, None, None]:
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()