zenit 1.0.0__py3-none-any.whl

scaffolder/addons/_registry.py

@@ -0,0 +1,30 @@
+"""Addon registry — discovers ``addon.py`` files and returns ``AddonConfig`` objects."""
+
+import importlib.util
+from pathlib import Path
+
+from scaffolder.schema import AddonConfig
+
+_HERE = Path(__file__).parent.absolute()
+
+
+def get_available_addons() -> list[AddonConfig]:
+    """Return one ``AddonConfig`` for every addon directory found under this package."""
+    addons: list[AddonConfig] = []
+    for addon_dir in sorted(
+        p for p in _HERE.iterdir() if p.is_dir() and not p.name.startswith("_")
+    ):
+        try:
+            spec = importlib.util.spec_from_file_location(
+                "addon_config", addon_dir / "addon.py"
+            )
+            if spec is None:
+                continue
+            mod = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(mod)  # type: ignore[union-attr]
+            cfg: AddonConfig = mod.config
+            cfg._module = mod  # attach module so post_apply can be called later
+            addons.append(cfg)
+        except FileNotFoundError, AttributeError:
+            continue
+    return addons

scaffolder/addons/celery/addon.py

@@ -0,0 +1,68 @@
+from pathlib import Path
+
+from scaffolder.schema import AddonConfig, ComposeService, FileContribution
+
+_HERE = Path(__file__).parent.absolute()
+
+config = AddonConfig(
+    id="celery",
+    description="Celery worker + beat scheduler, backed by Redis",
+    requires=["redis"],
+    files=[
+        FileContribution(
+            dest="src/{{pkg_name}}/tasks/__init__.py",
+            content="",
+        ),
+        FileContribution(
+            dest="src/{{pkg_name}}/tasks/celery_app.py",
+            source=str(_HERE / "files" / "tasks" / "celery_app.py.j2"),
+            template=True,
+        ),
+        FileContribution(
+            dest="src/{{pkg_name}}/tasks/example_tasks.py",
+            source=str(_HERE / "files" / "tasks" / "example_tasks.py.j2"),
+            template=True,
+        ),
+    ],
+    compose_services=[
+        ComposeService(
+            name="celery-worker",
+            build=".",
+            command="celery -A {{pkg_name}}.tasks.celery_app worker --loglevel=info",
+            env_file=[".env"],
+            environment={"REDIS_URL": "redis://redis:6379/0"},
+            depends_on={
+                "redis": {"condition": "service_healthy"},
+            },
+            develop_watch=[{"action": "sync", "path": "./src", "target": "/app/src"}],
+        ),
+        ComposeService(
+            name="celery-beat",
+            build=".",
+            command="celery -A {{pkg_name}}.tasks.celery_app beat --loglevel=info",
+            env_file=[".env"],
+            environment={"REDIS_URL": "redis://redis:6379/0"},
+            depends_on={
+                "redis": {"condition": "service_healthy"},
+            },
+            develop_watch=[{"action": "sync", "path": "./src", "target": "/app/src"}],
+        ),
+    ],
+    deps=["celery[redis]>=5", "flower"],
+    dev_deps=["pytest-celery"],
+    just_recipes=[
+        "# start celery worker and beat scheduler\n"
+        "celery-up:\n"
+        "    docker compose up -d celery-worker celery-beat",
+        "# stop celery worker and beat scheduler\n"
+        "celery-down:\n"
+        "    docker compose stop celery-worker celery-beat",
+        "# open flower monitoring UI on port 5555\n"
+        "celery-flower:\n"
+        "    docker compose run --rm celery-worker "
+        "celery -A (( pkg_name )).tasks.celery_app flower --port=5555",
+        "# tail celery worker logs\n"
+        "celery-logs:\n"
+        "    docker compose logs -f celery-worker",
+    ],
+)

scaffolder/addons/celery/files/tasks/celery_app.py.j2

@@ -0,0 +1,37 @@
+"""Celery application instance.
+
+Start the worker:
+    celery -A (( pkg_name )).tasks.celery_app worker --loglevel=info
+
+Start the beat scheduler:
+    celery -A (( pkg_name )).tasks.celery_app beat --loglevel=info
+"""
+
+import os
+
+from celery import Celery
+
+REDIS_URL = os.getenv("REDIS_URL", "redis://localhost:6379/0")
+
+celery_app = Celery(
+    __name__,
+    broker=REDIS_URL,
+    backend=REDIS_URL,
+    include=["(( pkg_name )).tasks.example_tasks"],
+)
+
+celery_app.conf.update(
+    task_serializer="json",
+    result_serializer="json",
+    accept_content=["json"],
+    timezone="UTC",
+    enable_utc=True,
+    # Beat schedule — add periodic tasks here:
+    # beat_schedule={
+    #     "example-every-30s": {
+    #         "task": "(( pkg_name )).tasks.example_tasks.add",
+    #         "schedule": 30.0,
+    #         "args": (1, 2),
+    #     },
+    # },
+)

scaffolder/addons/celery/files/tasks/example_tasks.py.j2

@@ -0,0 +1,15 @@
+"""Example Celery tasks.
+
+Usage:
+    from (( pkg_name )).tasks.example_tasks import add
+    result = add.delay(1, 2)
+    print(result.get(timeout=10))  # 3
+"""
+
+from .celery_app import celery_app
+
+
+@celery_app.task  # type: ignore[untyped-decorator]
+def add(x: int, y: int) -> int:
+    """Example task — replace or delete."""
+    return x + y

scaffolder/addons/docker/addon.py

@@ -0,0 +1,31 @@
+from pathlib import Path
+
+from scaffolder.schema import AddonConfig, FileContribution
+
+_HERE = Path(__file__).parent.absolute()
+
+config = AddonConfig(
+    id="docker",
+    description="Dockerfile + compose.yml + .dockerignore",
+    requires=[],
+    files=[
+        FileContribution(
+            dest="Dockerfile",
+            source=str(_HERE / "files" / "Dockerfile.j2"),
+            template=True,
+        ),
+        FileContribution(
+            dest="compose.yml",
+            source=str(_HERE / "files" / "compose.yml.j2"),
+            template=True,
+        ),
+        FileContribution(
+            dest=".dockerignore",
+            source=str(_HERE / "files" / ".dockerignore"),
+        ),
+    ],
+    just_recipes=[
+        "# build and start all services\ndocker-up:\n    docker compose up --build",
+        "# stop all services\ndocker-down:\n    docker compose down",
+    ],
+)

scaffolder/addons/docker/files/.dockerignore

@@ -0,0 +1,14 @@
+.venv/
+.direnv/
+.git/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+htmlcov/
+.coverage
+*.db
+.env
+result
+result-*

scaffolder/addons/docker/files/Dockerfile.j2

@@ -0,0 +1,34 @@
+# syntax=docker/dockerfile:1
+FROM python:3.14-slim AS base
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    UV_PYTHON_DOWNLOADS=never
+
+WORKDIR /app
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+RUN addgroup --system app && adduser --system --ingroup app app
+
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+
+COPY src/ ./src/
+
+RUN uv sync --frozen --no-dev
+
+RUN chown -R app:app /app
+
+USER app
+
+ENV PATH="/app/.venv/bin:$PATH" \
+    PYTHONPATH="/app/src"
+
+EXPOSE 8000
+
+[% if template == "fastapi" %]
+CMD ["uvicorn", "(( pkg_name )).main:app", "--host", "0.0.0.0", "--port", "8000"]
+[% else %]
+CMD ["python", "-m", "(( pkg_name ))"]
+[% endif %]

scaffolder/addons/docker/files/compose.yml.j2

@@ -0,0 +1,26 @@
+services:
+  app:
+    build: .
+    ports:
+      - "8000:8000"
+[% if template == "fastapi" %]
+    env_file:
+      - .env
+    command: uvicorn (( pkg_name )).main:app --host 0.0.0.0 --port 8000 --reload
+[% endif %]
+    develop:
+      watch:
+        - action: sync
+          path: ./src
+          target: /app/src
+[% if template == "fastapi" %]
+
+  db:
+    image: postgres:16
+    environment:
+      POSTGRES_PASSWORD: postgres
+    ports:
+      - "5432:5432"
+    volumes:
+      - ./.pgdata:/var/lib/postgresql/data
+[% endif %]

scaffolder/addons/github-actions/addon.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+
+from scaffolder.schema import AddonConfig, FileContribution
+
+_HERE = Path(__file__).parent.absolute()
+
+config = AddonConfig(
+    id="github-actions",
+    description="CI workflow (lint, type-check, test on push/PR)",
+    requires=[],
+    files=[
+        FileContribution(
+            dest=".github/workflows/ci.yml",
+            source=str(_HERE / "files" / "ci.yml.j2"),
+            template=True,
+        ),
+    ],
+)

scaffolder/addons/github-actions/files/ci.yml.j2

@@ -0,0 +1,83 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+[% if has_postgres or has_redis %]
+    services:
+[% if has_postgres %]
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: (( name ))_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+[% endif %]
+[% if has_redis %]
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+[% endif %]
+[% endif %]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+[% if has_postgres %]
+
+      - name: Run migrations
+        env:
+          DATABASE_URL: postgresql+asyncpg://postgres:postgres@localhost:5432/(( name ))_test
+        run: uv run alembic upgrade head
+[% endif %]
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run mypy src/
+
+      - name: Test
+        env:
+[% if has_postgres %]
+          DATABASE_URL: postgresql+asyncpg://postgres:postgres@localhost:5432/(( name ))_test
+[% endif %]
+[% if has_redis %]
+          REDIS_URL: redis://localhost:6379/0
+[% endif %]
+        run: uv run pytest -v
+

scaffolder/addons/redis/addon.py

@@ -0,0 +1,61 @@
+"""Declarative config for the redis addon."""
+
+from pathlib import Path
+
+from scaffolder.schema import (
+    AddonConfig,
+    ComposeService,
+    EnvVar,
+    FileContribution,
+    Injection,
+)
+
+_HERE = Path(__file__).parent.absolute()
+
+config = AddonConfig(
+    id="redis",
+    description="Redis service + connection helper + compose service",
+    requires=[],
+    files=[
+        FileContribution(
+            dest="src/{{pkg_name}}/integrations/__init__.py",
+            content="",
+        ),
+        FileContribution(
+            dest="src/{{pkg_name}}/integrations/redis.py",
+            source=str(_HERE / "files" / "redis.py"),
+        ),
+    ],
+    compose_services=[
+        ComposeService(
+            name="redis",
+            image="redis:7-alpine",
+            ports=["6379:6379"],
+            volumes=["redis-data:/data"],
+            command="redis-server --appendonly yes",
+            healthcheck={
+                "test": ["CMD", "redis-cli", "ping"],
+                "interval": "1s",
+                "timeout": "3s",
+                "retries": 5,
+            },
+        )
+    ],
+    compose_volumes=["redis-data"],
+    env_vars=[
+        EnvVar(key="REDIS_URL", default="redis://localhost:6379/0"),
+    ],
+    deps=["redis>=5", "hiredis"],
+    dev_deps=["fakeredis[aioredis]"],
+    just_recipes=[
+        "# start redis\nredis-up:\n    docker compose up -d redis",
+        "# stop redis\nredis-down:\n    docker compose stop redis",
+        "# open redis-cli\nredis-cli:\n    redis-cli",
+    ],
+    injections=[
+        Injection(
+            point="settings_fields",
+            content='    redis_url: str = "redis://localhost:6379/0"',
+        ),
+    ],
+)

scaffolder/addons/redis/files/compose.redis.yml.j2

@@ -0,0 +1,11 @@
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis-data:/data
+    command: redis-server --appendonly yes
+
+volumes:
+  redis-data:

scaffolder/addons/redis/files/redis.py

@@ -0,0 +1,48 @@
+"""Redis connection helper.
+
+Usage:
+    from mypackage.integrations.redis import get_redis
+
+    @router.get("/example")
+    async def example(redis: Redis = Depends(get_redis)) -> dict:
+        await redis.set("key", "value", ex=60)
+        value = await redis.get("key")
+        return {"value": value}
+"""
+
+import os
+from collections.abc import AsyncGenerator
+
+import redis.asyncio as aioredis
+from redis.asyncio import Redis
+
+# REDIS_URL is read from the environment directly.
+# For FastAPI projects, settings.py exposes this via the redis_url field,
+# which is set from the REDIS_URL environment variable.
+REDIS_URL = os.getenv("REDIS_URL", "redis://localhost:6379/0")
+
+_pool: aioredis.ConnectionPool | None = None
+
+
+def _get_pool() -> aioredis.ConnectionPool:
+    global _pool
+    if _pool is None:
+        _pool = aioredis.ConnectionPool.from_url(
+            REDIS_URL,
+            decode_responses=True,
+        )
+    return _pool
+
+
+async def get_redis() -> AsyncGenerator[Redis]:
+    """FastAPI dependency that yields a Redis client from the shared pool."""
+    async with aioredis.Redis(connection_pool=_get_pool()) as client:
+        yield client
+
+
+async def close_redis() -> None:
+    """Call from lifespan shutdown to cleanly drain the pool."""
+    global _pool
+    if _pool is not None:
+        await _pool.aclose()
+        _pool = None

scaffolder/addons/sentry/addon.py

@@ -0,0 +1,41 @@
+from pathlib import Path
+
+from scaffolder.schema import AddonConfig, EnvVar, FileContribution, Injection
+
+_HERE = Path(__file__).parent.absolute()
+
+config = AddonConfig(
+    id="sentry",
+    description="Sentry error tracking + performance monitoring",
+    requires=[],
+    files=[
+        FileContribution(
+            dest="src/{{pkg_name}}/integrations/__init__.py",
+            content="",
+        ),
+        FileContribution(
+            dest="src/{{pkg_name}}/integrations/sentry.py",
+            source=str(_HERE / "files" / "sentry.py.j2"),
+            template=True,
+        ),
+    ],
+    env_vars=[
+        EnvVar(key="SENTRY_DSN", default=""),
+        EnvVar(key="SENTRY_ENVIRONMENT", default="development"),
+    ],
+    deps=["sentry-sdk[fastapi]"],
+    just_recipes=[
+        "# print sentry-sdk version\nsentry-check:\n    uv run python -c \"import sentry_sdk; print('sentry-sdk', sentry_sdk.VERSION)\"",
+        "# check whether SENTRY_DSN is set\nsentry-test:\n    uv run python -c \"from (( pkg_name )).integrations.sentry import init_sentry; import os; init_sentry(); print('Sentry DSN:', os.environ.get('SENTRY_DSN') or 'not set')\"",
+    ],
+    injections=[
+        Injection(
+            point="lifespan_startup",
+            content="    from .integrations.sentry import init_sentry\n    init_sentry()",
+        ),
+        Injection(
+            point="settings_fields",
+            content='    sentry_dsn: str = ""\n    sentry_environment: str = "development"',
+        ),
+    ],
+)

scaffolder/addons/sentry/files/sentry.py.j2

@@ -0,0 +1,35 @@
+"""Sentry initialisation.
+
+Set SENTRY_DSN in your .env to enable. Leave blank to disable (safe for local dev).
+
+Get your DSN at: https://sentry.io/settings/<org>/projects/<project>/keys/
+"""
+
+# ruff: noqa: I001
+import os
+
+import sentry_sdk
+[% if template == "fastapi" %]
+from sentry_sdk.integrations.fastapi import FastApiIntegration
+from sentry_sdk.integrations.sqlalchemy import SqlalchemyIntegration
+[% endif %]
+
+
+def init_sentry() -> None:
+    dsn = os.getenv("SENTRY_DSN", "")
+    if not dsn:
+        return
+
+    sentry_sdk.init(
+        dsn=dsn,
+        environment=os.getenv("SENTRY_ENVIRONMENT", "development"),
+        traces_sample_rate=1.0,
+        profiles_sample_rate=1.0,
+[% if template == "fastapi" %]
+        integrations=[
+            FastApiIntegration(),
+            SqlalchemyIntegration(),
+        ],
+[% endif %]
+        send_default_pii=False,
+    )