karni-cli 0.3.1__py3-none-any.whl

karni_cli/generators/schedule.py

@@ -0,0 +1,174 @@
+"""``karni make schedule <name> --every 15m | --cron "0 3 * * *"`` — a beat schedule.
+
+Appends ``every(...)`` / ``cron(...)`` to ``<app>/schedules.py``
+(:mod:`karni.schedule`; autodiscovered into Celery beat). Without ``--task``
+the schedule runs ``<app>.tasks.<name>``, created when it does not exist yet.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+
+import typer
+
+from karni_cli.generators import task as task_gen
+from karni_cli.generators.core import (
+    APP_OPTION,
+    DRY_RUN_OPTION,
+    FORCE_OPTION,
+    App,
+    Workspace,
+    local_apps,
+    project_workspace,
+    resolve_app,
+)
+from karni_cli.generators.introspect import top_level_functions
+from karni_cli.generators.pysource import (
+    Import,
+    append,
+    call,
+    ensure_imports,
+    parse,
+    pystr,
+    replace_span,
+    span,
+)
+from karni_cli.project import CliError
+
+NAME = "schedule"
+SUMMARY = "Add a beat schedule (every/cron) to <app>/schedules.py, creating the task if needed."
+
+# Mirrors karni.schedule's own validation, so mistakes fail before any write.
+_INTERVAL = re.compile(r"^\s*(?:\d+\s*[dhms]\s*)+$")
+_DOTTED = re.compile(r"^[A-Za-z_]\w*(\.[A-Za-z_]\w*)+$")
+_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.:-]*$")
+
+
+def _declared(ws: Workspace, rel: str, text: str) -> dict[str, ast.stmt]:
+    """``name=`` of each top-level every()/cron() call in a schedules module."""
+    found: dict[str, ast.stmt] = {}
+    if not text:
+        return found
+    for node in parse(ws, rel, text).body:
+        value = node.value if isinstance(node, ast.Expr | ast.Assign) else None
+        if not isinstance(value, ast.Call):
+            continue
+        func = value.func
+        called = func.id if isinstance(func, ast.Name) else getattr(func, "attr", "")
+        if called not in {"every", "cron"}:
+            continue
+        for keyword in value.keywords:
+            if keyword.arg == "name" and isinstance(keyword.value, ast.Constant):
+                found[str(keyword.value.value)] = node
+    return found
+
+
+def _app_schedules(ws: Workspace, app: App) -> dict[str, ast.stmt]:
+    path = app.file("schedules.py")
+    return _declared(ws, ws.rel(path), ws.read(path) or "")
+
+
+def plan(
+    ws: Workspace,
+    app: App,
+    name: str,
+    *,
+    every: str | None,
+    cron: str | None,
+    task: str | None,
+) -> None:
+    if not _NAME.match(name):
+        raise CliError(
+            f"Schedule name {name!r}: use letters, digits, _ - . : (e.g. nightly-report).",
+            code="C103",
+        )
+    if (every is None) == (cron is None):
+        raise CliError(
+            'Give exactly one of --every (e.g. 15m, 1h, 1d) or --cron "0 3 * * *".', code="C004"
+        )
+    if every is not None and not _INTERVAL.match(every):
+        raise CliError(
+            f"--every {every!r}: use a number with s, m, h or d — 30s, 15m, 1h30m, 1d.", code="C106"
+        )
+    if cron is not None and len(cron.split()) != 5:
+        raise CliError(
+            f"--cron {cron!r}: needs 5 fields 'minute hour day-of-month month day-of-week', "
+            "e.g. '0 3 * * *' (03:00 daily).",
+            code="C106",
+        )
+    for other in local_apps(ws):
+        if other != app and name in _app_schedules(ws, other):
+            raise CliError(
+                f"Schedule {name!r} is already declared in {ws.rel(other.file('schedules.py'))} "
+                "— schedule names are project-wide (they become PeriodicTask names).",
+                code="C107",
+            )
+    imports = [Import("karni.schedule", "every" if every is not None else "cron")]
+    if task is not None:
+        if not _DOTTED.match(task):
+            raise CliError(
+                f"--task {task!r}: give the dotted task name, e.g. shop.tasks.sync.", code="C106"
+            )
+        module, _, function = task.rpartition(".")
+        if module == f"{app.module}.tasks" and function not in top_level_functions(
+            ws, app.file("tasks.py")
+        ):
+            raise CliError(
+                f"No task {function} in {ws.rel(app.file('tasks.py'))} — "
+                f"karni make task {function} --app {app.label} (or drop --task).",
+                code="C105",
+            )
+        ref = pystr(task)
+    else:
+        function = re.sub(r"\W", "_", name).lower()
+        if function not in top_level_functions(ws, app.file("tasks.py")):
+            task_gen.plan(ws, app, function, announce=False)
+        ref = f"tasks.{function}"
+        imports.append(Import(app.module, "tasks"))
+    timing = pystr(every.strip() if every is not None else " ".join((cron or "").split()))
+    statement = call(
+        "every" if every is not None else "cron",
+        [timing, ref, f"name={pystr(name)}"],
+        "",
+        ws.line_length,
+    )
+    path = app.file("schedules.py")
+    rel = ws.rel(path)
+    text = ensure_imports(ws, rel, ws.read(path) or "", imports)
+    existing = _declared(ws, rel, text).get(name)
+    if existing is not None:
+        ws.refuse_existing(f"schedule {name!r} in {rel}")
+        first, last = span(text.splitlines(), existing)
+        text = replace_span(text, first, last, statement)
+    else:
+        text = append(text, statement)
+    ws.write(path, text)
+    ws.note(
+        f"schedule: {name} — check with: karni schedule list  ·  run once: karni schedule run {name}"
+    )
+
+
+def command(
+    name: str = typer.Argument(
+        ..., help="Schedule name, unique in the project (e.g. nightly-report)."
+    ),
+    every: str | None = typer.Option(None, "--every", help="Interval: 30s, 15m, 1h, 1h30m, 1d."),
+    cron: str | None = typer.Option(
+        None, "--cron", help='Five-field crontab, e.g. "0 3 * * *" (03:00 daily).'
+    ),
+    task: str | None = typer.Option(
+        None, "--task", help="Dotted task to run (default: APP.tasks.<name>, created if missing)."
+    ),
+    app: str | None = APP_OPTION,
+    force: bool = FORCE_OPTION,
+    dry_run: bool = DRY_RUN_OPTION,
+) -> None:
+    """Add every(...)/cron(...) to APP/schedules.py — merged into Celery beat at startup.
+
+    Without --task the schedule runs APP.tasks.<name> (dashes become
+    underscores), which is created when missing.
+    """
+    ws = project_workspace(force)
+    plan(ws, resolve_app(ws, app), name, every=every, cron=cron, task=task)
+    ws.commit(dry_run=dry_run)

karni_cli/generators/seeder.py

@@ -0,0 +1,86 @@
+"""``karni make seeder <Model>`` — a ``Seeder`` in ``<app>/seeds.py`` for ``karni seed``.
+
+``karni seed`` already fills every model with values inferred from field
+names and types. A seeder steers one model: ``Meta.count`` pins its rows per
+run (``0`` skips it) and any class attribute overrides one field with a
+value or a factory-boy declaration; override ``seed()`` for full control.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from karni_cli.generators.core import (
+    APP_OPTION,
+    DRY_RUN_OPTION,
+    FORCE_OPTION,
+    App,
+    Workspace,
+    project_workspace,
+    resolve_app,
+)
+from karni_cli.generators.introspect import require_model
+from karni_cli.generators.naming import require_pascal
+from karni_cli.generators.pysource import Import, docstring, ensure_imports, replace_or_append
+from karni_cli.project import CliError
+
+NAME = "seeder"
+SUMMARY = "Add a Seeder to <app>/seeds.py: per-model rows and values for karni seed."
+
+
+def plan(ws: Workspace, app: App, model_name: str, *, count: int | None = None) -> str:
+    """Plan ``<Model>Seeder``; returns the class name."""
+    if count is not None and count < 0:
+        raise CliError("--count must be 0 or more (0 skips the model).", code="C106")
+    model = require_model(ws, app, require_pascal(model_name, "Model"))
+    path = model.app.file("seeds.py")
+    rel = ws.rel(path)
+    line = ws.line_length
+    text = ws.read(path)
+    if text is None:
+        text = docstring(f"{model.app.label} demo data for `karni seed`.", "", line) + "\n"
+    class_name = f"{model.name}Seeder"
+    meta = ["    class Meta:", f"        model = {model.name}"]
+    if count is not None:
+        meta.append(f"        count = {count}")
+    block = "\n".join(
+        [
+            f"class {class_name}(Seeder):",
+            docstring(
+                f"Demo rows for {model.name}; undeclared fields are inferred from their names.",
+                "    ",
+                line,
+            ),
+            "",
+            *meta,
+            "",
+            "    # Steer a field with a value or a factory-boy declaration, e.g.:",
+            '    # status = factory.Iterator(["published", "draft"])',
+        ]
+    )
+    text = ensure_imports(
+        ws, rel, text, [Import("karni.seeding", "Seeder"), Import(model.import_module, model.name)]
+    )
+    ws.write(path, replace_or_append(ws, rel, text, class_name, block))
+    ws.note(f"seeder: {model.app.module}.seeds.{class_name} — run: karni seed")
+    return class_name
+
+
+def command(
+    model: str = typer.Argument(..., help="Model class name (e.g. Event)."),
+    count: int | None = typer.Option(
+        None, "--count", help="Rows per `karni seed` run for this model (0 skips it)."
+    ),
+    app: str | None = APP_OPTION,
+    force: bool = FORCE_OPTION,
+    dry_run: bool = DRY_RUN_OPTION,
+) -> None:
+    """Add `<Model>Seeder(Seeder)` to APP/seeds.py, read by `karni seed`.
+
+    Only needed to steer a model's demo data: Meta.count pins its rows per
+    run, and a class attribute overrides a field (a value or a factory-boy
+    declaration); every other field stays inferred from its name and type.
+    """
+    ws = project_workspace(force)
+    plan(ws, resolve_app(ws, app), model, count=count)
+    ws.commit(dry_run=dry_run)

karni_cli/generators/serializer.py

@@ -0,0 +1,165 @@
+"""``karni make serializer <Model> --reason "..."`` — an explicit serializer, wired in.
+
+``BaseViewSet(model=X)`` already generates the serializer (K106), and
+``APIMeta`` steers its fields; an explicit one is the escape hatch for what
+neither covers. So ``--reason`` is mandatory: it becomes the
+``# karni: allow(redundant-serializer): <reason>`` marker above the class.
+The viewset's ``serializer_class`` is set in the same run.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+import typer
+
+from karni_cli.generators.core import (
+    APP_OPTION,
+    DRY_RUN_OPTION,
+    FORCE_OPTION,
+    App,
+    Workspace,
+    project_workspace,
+    resolve_app,
+)
+from karni_cli.generators.introspect import (
+    ModelInfo,
+    owned_paths,
+    require_model,
+    viewset_for,
+    viewsets_file,
+)
+from karni_cli.generators.naming import require_pascal
+from karni_cli.generators.pysource import (
+    Import,
+    ensure_imports,
+    pystr,
+    replace_or_append,
+    replace_span,
+    tuple_literal,
+)
+from karni_cli.project import CliError
+
+NAME = "serializer"
+SUMMARY = "Add an explicit serializer (--reason required) and set serializer_class."
+
+
+def _field_lists(model: ModelInfo, owners: list[str]) -> tuple[list[str], list[str]]:
+    bases = model.bases
+    head = ["id"]
+    tail: list[str] = []
+    if bases & {"BaseModel", "TimestampedModel"}:
+        tail += ["created_at", "updated_at"]
+    if bases & {"BaseModel", "AuditedModel"}:
+        tail += ["created_by", "updated_by"]
+    fields = [*head, *model.fields, *tail]
+    owned = dict.fromkeys(o for o in owners if o in model.fields)  # read + write may both name it
+    read_only = [*head, *tail, *owned]
+    return fields, read_only
+
+
+def plan(ws: Workspace, app: App, model_name: str, reason: str) -> str:
+    reason = " ".join(reason.split())
+    if not reason:
+        raise CliError(
+            "--reason is required: BaseViewSet already generates this serializer (K106) — say "
+            'why an explicit one is needed, e.g. --reason "computed display_name field".',
+            code="C109",
+        )
+    model = require_model(ws, app, model_name)
+    found = viewset_for(ws, app, model.name)
+    if found is None:
+        raise CliError(
+            f"No viewset for {model.name} in {ws.rel(viewsets_file(ws, app))} to wire the "
+            f"serializer into — karni make viewset {model.name} first.",
+            code="C105",
+        )
+    vs_path, viewset = found
+    class_name = f"{model.name}Serializer"
+    line = ws.line_length
+    fields, read_only = _field_lists(model, owned_paths(viewset))
+    block = "\n".join(
+        [
+            f"# karni: allow(redundant-serializer): {reason}",
+            f"class {class_name}(KarniModelSerializer):",
+            "    class Meta:",
+            f"        model = {model.name}",
+            tuple_literal("fields = ", [pystr(f) for f in fields], "        ", line),
+            tuple_literal("read_only_fields = ", [pystr(f) for f in read_only], "        ", line),
+        ]
+    )
+    path = app.file("serializers.py")
+    rel = ws.rel(path)
+    text = ensure_imports(
+        ws,
+        rel,
+        ws.read(path) or "",
+        [
+            Import("karni.api.serializers", "KarniModelSerializer"),
+            Import(model.import_module, model.name),
+        ],
+    )
+    ws.write(path, replace_or_append(ws, rel, text, class_name, block))
+    _wire(ws, vs_path, viewset, class_name, f"{app.module}.serializers")
+    ws.note(
+        f"note: BaseViewSet(model={model.name}) generates a serializer already; "
+        f"{class_name} replaces it. Prefer APIMeta for fields/read_only/write_only."
+    )
+    return class_name
+
+
+def _wire(ws: Workspace, path: Path, viewset: ast.ClassDef, class_name: str, module: str) -> None:
+    """Set ``serializer_class`` on the viewset: after its ``model = X`` line (AST-located)."""
+    rel = ws.rel(path)
+    text = ws.read(path) or ""
+    lines = text.splitlines()
+    indent = " " * viewset.body[0].col_offset
+    assignment = f"{indent}serializer_class = {class_name}"
+    existing = next(
+        (
+            stmt
+            for stmt in viewset.body
+            if isinstance(stmt, ast.Assign)
+            and any(isinstance(t, ast.Name) and t.id == "serializer_class" for t in stmt.targets)
+        ),
+        None,
+    )
+    if existing is not None:
+        ws.refuse_existing(f"{viewset.name}.serializer_class in {rel}")
+        text = replace_span(
+            text, existing.lineno, existing.end_lineno or existing.lineno, assignment
+        )
+    else:
+        anchor = next(
+            stmt
+            for stmt in viewset.body
+            if isinstance(stmt, ast.Assign)
+            and any(isinstance(t, ast.Name) and t.id == "model" for t in stmt.targets)
+        )
+        end = anchor.end_lineno or anchor.lineno
+        lines.insert(end, assignment)
+        text = "\n".join(lines) + "\n"
+    text = ensure_imports(ws, rel, text, [Import(module, class_name)])
+    ws.write(path, text)
+
+
+def command(
+    model: str = typer.Argument(..., help="Model class name (e.g. Event)."),
+    reason: str = typer.Option(
+        "", "--reason", help="Why the generated serializer is not enough (required)."
+    ),
+    app: str | None = APP_OPTION,
+    force: bool = FORCE_OPTION,
+    dry_run: bool = DRY_RUN_OPTION,
+) -> None:
+    """Add `<Model>Serializer` to APP/serializers.py and set the viewset's serializer_class.
+
+    BaseViewSet generates the serializer and APIMeta steers it, so an
+    explicit one needs --reason; it is recorded as the
+    `# karni: allow(redundant-serializer): <reason>` marker.
+    """
+    ws = project_workspace(force)
+    target = resolve_app(ws, app)
+    plan(ws, target, require_pascal(model.removesuffix("Serializer"), "Model"), reason)
+    ws.commit(dry_run=dry_run)

karni_cli/generators/service.py

@@ -0,0 +1,68 @@
+"""``karni make service <name>`` — a module under ``<app>/services/``.
+
+Services are where external calls live: rule K105 allows HTTP clients
+(``requests``, ``httpx``, ``urllib.request``) only under ``services/`` and
+``providers/``, so views, tasks and listeners call a service, never a client.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from karni_cli.generators.core import (
+    APP_OPTION,
+    DRY_RUN_OPTION,
+    FORCE_OPTION,
+    App,
+    Workspace,
+    project_workspace,
+    resolve_app,
+)
+from karni_cli.generators.naming import humanize, pascal, require_snake
+from karni_cli.generators.pysource import comment, docstring
+from karni_cli.project import CliError
+
+NAME = "service"
+SUMMARY = "Add a service module (<app>/services/<name>.py) — the home of HTTP clients."
+
+
+def plan(ws: Workspace, app: App, name: str) -> None:
+    require_snake(name, "Service name")
+    if ws.exists(app.file("services.py")):
+        raise CliError(
+            f"{ws.rel(app.file('services.py'))} exists — a services/ package would shadow it. "
+            "Move it to services/__init__.py first, then re-run.",
+            code="C107",
+        )
+    init = app.file("services", "__init__.py")
+    if not ws.exists(init):
+        ws.create(init, "")
+    line = ws.line_length
+    class_name = pascal(name) + ("" if name.endswith("service") else "Service")
+    body = comment(
+        "External calls (requests, httpx) belong here: rule K105 allows HTTP clients "
+        "only under services/ and providers/. Views, tasks and listeners call this "
+        "module, never a client directly.",
+        "",
+        line,
+        prefix="",
+    )
+    module_doc = f'"""{humanize(name)} service.\n\n{body}\n"""'
+    class_doc = docstring(f"{humanize(name)}: the calls this app makes to it.", "    ", line)
+    ws.create(
+        app.file("services", f"{name}.py"),
+        f"{module_doc}\n\n\nclass {class_name}:\n{class_doc}\n",
+    )
+    ws.note(f"import: from {app.module}.services.{name} import {class_name}")
+
+
+def command(
+    name: str = typer.Argument(..., help="Service module name, snake_case (e.g. stripe_client)."),
+    app: str | None = APP_OPTION,
+    force: bool = FORCE_OPTION,
+    dry_run: bool = DRY_RUN_OPTION,
+) -> None:
+    """Add APP/services/NAME.py — the one place HTTP clients are allowed (K105)."""
+    ws = project_workspace(force)
+    plan(ws, resolve_app(ws, app), name)
+    ws.commit(dry_run=dry_run)

karni_cli/generators/task.py

@@ -0,0 +1,84 @@
+"""``karni make task <name>`` — a Celery ``@shared_task`` in ``<app>/tasks.py``.
+
+Celery autodiscovers ``tasks`` modules (``karni.celery.create_celery_app``),
+so the task is registered as ``<app>.tasks.<name>`` with no wiring.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from karni_cli.generators.core import (
+    APP_OPTION,
+    DRY_RUN_OPTION,
+    FORCE_OPTION,
+    App,
+    Workspace,
+    project_workspace,
+    resolve_app,
+)
+from karni_cli.generators.naming import require_snake
+from karni_cli.generators.pysource import (
+    Import,
+    call,
+    docstring,
+    ensure_imports,
+    replace_or_append,
+)
+from karni_cli.project import CliError
+
+NAME = "task"
+SUMMARY = "Add a Celery task (@shared_task) to <app>/tasks.py; --retry N."
+
+
+def plan(
+    ws: Workspace, app: App, name: str, *, retry: int | None = None, announce: bool = True
+) -> str:
+    """Plan the task; returns its registered name (``<app>.tasks.<name>``)."""
+    require_snake(name, "Task name")
+    if retry is not None and retry < 1:
+        raise CliError("--retry must be 1 or more.", code="C106")
+    path = app.file("tasks.py")
+    rel = ws.rel(path)
+    line = ws.line_length
+    if retry is None:
+        decorator = "@shared_task"
+    else:
+        decorator = call(
+            "@shared_task",
+            ["autoretry_for=(Exception,)", "retry_backoff=True", f"max_retries={retry}"],
+            "",
+            line,
+        )
+    block = "\n".join(
+        [
+            decorator,
+            f"def {name}() -> None:",
+            docstring(f"Runs in a Celery worker: {name}.delay() queues it.", "    ", line),
+            "    # Off-request writes are audit-stamped only inside",
+            "    # karni.middleware.current_user(user).",
+        ]
+    )
+    text = ensure_imports(ws, rel, ws.read(path) or "", [Import("celery", "shared_task")])
+    ws.write(path, replace_or_append(ws, rel, text, name, block))
+    dotted = f"{app.module}.tasks.{name}"
+    if announce:
+        ws.note(f"task: {dotted} — schedule it with: karni make schedule {name} --every 1h")
+    else:
+        ws.note(f"task: {dotted}")
+    return dotted
+
+
+def command(
+    name: str = typer.Argument(..., help="Task function name, snake_case (e.g. send_digest)."),
+    retry: int | None = typer.Option(
+        None, "--retry", help="Retry up to N times on any exception (exponential backoff)."
+    ),
+    app: str | None = APP_OPTION,
+    force: bool = FORCE_OPTION,
+    dry_run: bool = DRY_RUN_OPTION,
+) -> None:
+    """Add a Celery task `NAME` to APP/tasks.py (registered as APP.tasks.NAME)."""
+    ws = project_workspace(force)
+    plan(ws, resolve_app(ws, app), name, retry=retry)
+    ws.commit(dry_run=dry_run)