karni-cli 0.3.1__py3-none-any.whl

karni_cli/generators/listener.py

@@ -0,0 +1,168 @@
+"""``karni make listener <name> --on Model.created|updated|deleted | <event>`` — a receiver.
+
+Writes to ``<app>/listeners.py``, which Karni autodiscovers at startup
+(:mod:`karni.events`) — no ``AppConfig.ready()`` wiring.
+
+* ``--on Event.created`` (``updated``/``deleted``; ``shop.Event.created``
+  for another app's model) → ``@on_created(Event)``; soft deletes count as
+  deleted. ``--queued`` → ``queued=True``: the work runs in a Celery worker
+  after the transaction commits.
+* ``--on order_shipped`` (or ``shop.events.order_shipped``) → a
+  ``@receiver`` for a custom event from ``events.py``. ``--queued`` creates
+  the task ``<app>.tasks.<name>`` and queues it on commit.
+"""
+
+from __future__ import annotations
+
+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 (
+    find_model,
+    models_in,
+    top_level_assignments,
+    top_level_functions,
+)
+from karni_cli.generators.naming import require_snake, snake
+from karni_cli.generators.pysource import Import, docstring, ensure_imports, replace_or_append
+from karni_cli.project import CliError
+
+NAME = "listener"
+SUMMARY = "Add a listener to <app>/listeners.py: --on Model.created|updated|deleted or an event."
+
+_LIFECYCLE = re.compile(
+    r"^(?:(?P<app>[a-z_]\w*)\.)?(?P<model>[A-Z]\w*)\.(?P<event>created|updated|deleted)$"
+)
+_EVENT = re.compile(r"^(?:(?P<module>[a-z_][\w.]*)\.events\.)?(?P<event>[a-z_]\w*)$")
+_ON_HELP = (
+    "Model.created|Model.updated|Model.deleted (app_label.Model.event for an installed "
+    "app's model, e.g. karni_payments.Payment.updated), or a custom event (order_shipped)"
+)
+#: The user model's label when no local app defines ``User`` (Karni's default).
+_USER_MODEL = "karni_accounts.User"
+
+
+def _local_app(ws: Workspace, label: str) -> App | None:
+    for other in local_apps(ws):
+        if label in (other.label, other.module):
+            return other
+    return None
+
+
+def _app_named(ws: Workspace, label: str) -> App:
+    found = _local_app(ws, label)
+    if found is None:
+        raise CliError(f"--on: no local app {label!r}.", code="C102")
+    return found
+
+
+def plan(ws: Workspace, app: App, name: str, *, on: str, queued: bool = False) -> None:
+    require_snake(name, "Listener name")
+    line = ws.line_length
+    lifecycle = _LIFECYCLE.match(on)
+    custom = None if lifecycle else _EVENT.match(on)
+    imports: list[Import] = []
+    if lifecycle:
+        label, model_name, event = lifecycle["app"], lifecycle["model"], lifecycle["event"]
+        owner = _local_app(ws, label) if label else app
+        model = None
+        if owner is not None:
+            model = (
+                models_in(ws, owner).get(model_name) if label else find_model(ws, owner, model_name)
+            )
+        # Not a local model: an installed app's (karni_payments.Payment) or the user
+        # model. karni.events takes the lazy "app_label.Model" string, so no import.
+        lazy = f"{label}.{model_name}" if label else (_USER_MODEL if model_name == "User" else "")
+        if model is None and not lazy:
+            raise CliError(
+                f"--on {on}: no model {model_name} — create it first: karni make model "
+                f"{model_name}, or name an installed app's model as app_label.{model_name}.{event}.",
+                code="C105",
+            )
+        target = model.name if model is not None else f'"{lazy}"'
+        annotation = model.name if model is not None else "Any"
+        decorator = f"@on_{event}({target}{', queued=True' if queued else ''})"
+        param = snake(model_name)
+        if param == name:
+            param = "instance"
+        where = (
+            "in a Celery worker, after commit" if queued else "inline, in the saving transaction"
+        )
+        lines = [
+            decorator,
+            f"def {name}({param}: {annotation}) -> None:",
+            docstring(f"Runs after {model_name} rows are {event} — {where}.", "    ", line),
+        ]
+        imports.append(Import("karni.events", f"on_{event}"))
+        imports.append(
+            Import(model.import_module, model.name)
+            if model is not None
+            else Import("typing", "Any")
+        )
+    elif custom:
+        source = _app_named(ws, custom["module"]) if custom["module"] else app
+        event = custom["event"]
+        events_path = source.file("events.py")
+        if event not in top_level_assignments(ws, events_path):
+            raise CliError(
+                f"--on {on}: no event {event} in {ws.rel(events_path)} — "
+                f"karni make event {event} --app {source.label}",
+                code="C105",
+            )
+        lines = [f"@receiver({event})", f"def {name}(sender: Any, **kwargs: Any) -> None:"]
+        imports += [
+            Import("typing", "Any"),
+            Import("django.dispatch", "receiver"),
+            Import(f"{source.module}.events", event),
+        ]
+        if queued:
+            if name not in top_level_functions(ws, app.file("tasks.py")):
+                task_gen.plan(ws, app, name, announce=False)
+            lines.append(
+                docstring(f"Queues tasks.{name} once the transaction commits.", "    ", line)
+            )
+            lines.append(f"    transaction.on_commit(tasks.{name}.delay)")
+            imports += [Import("django.db", "transaction"), Import(app.module, "tasks")]
+        else:
+            lines.append(
+                docstring(f"Runs when {event} is sent — inline, in the sender.", "    ", line)
+            )
+    else:
+        raise CliError(f"--on {on!r}: expected {_ON_HELP}.", code="C106")
+    path = app.file("listeners.py")
+    rel = ws.rel(path)
+    text = ensure_imports(ws, rel, ws.read(path) or "", imports)
+    ws.write(path, replace_or_append(ws, rel, text, name, "\n".join(lines)))
+    ws.note(f"listener: {app.module}.listeners.{name} on {on} (autodiscovered at startup)")
+
+
+def command(
+    name: str = typer.Argument(..., help="Listener function name, snake_case."),
+    on: str = typer.Option(..., "--on", help=_ON_HELP + "."),
+    queued: bool = typer.Option(
+        False, "--queued", help="Run the work in a Celery worker after the transaction commits."
+    ),
+    app: str | None = APP_OPTION,
+    force: bool = FORCE_OPTION,
+    dry_run: bool = DRY_RUN_OPTION,
+) -> None:
+    """Add a listener to APP/listeners.py (autodiscovered — no AppConfig.ready wiring).
+
+    --on Event.created|updated|deleted uses karni.events (soft deletes count
+    as deleted); --on order_shipped receives a custom event from events.py.
+    """
+    ws = project_workspace(force)
+    plan(ws, resolve_app(ws, app), name, on=on, queued=queued)
+    ws.commit(dry_run=dry_run)

karni_cli/generators/middleware.py

@@ -0,0 +1,95 @@
+"""``karni make middleware <Name>`` — a middleware class, wired into settings.
+
+The class goes to ``<app>/middleware.py``; its dotted path is added to the
+``# karni:middleware`` block of config/settings.py (``MIDDLEWARE += [...]``,
+so it runs after Karni's stack). A settings file without that block gets the
+exact line to add instead.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from karni_cli.generators.core import (
+    APP_OPTION,
+    DRY_RUN_OPTION,
+    FORCE_OPTION,
+    SETTINGS,
+    App,
+    Workspace,
+    project_workspace,
+    resolve_app,
+)
+from karni_cli.generators.naming import require_pascal
+from karni_cli.generators.pysource import Import, ensure_imports, replace_or_append
+from karni_cli.project import CliError
+from karni_cli.settings_edit import MIDDLEWARE_MARKER, add_entry
+
+NAME = "middleware"
+SUMMARY = "Add a middleware class to <app>/middleware.py, wired via # karni:middleware."
+
+
+def plan(ws: Workspace, app: App, name: str) -> str:
+    base = require_pascal(name, "Middleware name")
+    class_name = base if base.endswith("Middleware") else f"{base}Middleware"
+    path = app.file("middleware.py")
+    rel = ws.rel(path)
+    block = "\n".join(
+        [
+            f"class {class_name}:",
+            "    def __init__(self, get_response: Callable[[HttpRequest], HttpResponse]) -> None:",
+            "        self.get_response = get_response",
+            "",
+            "    def __call__(self, request: HttpRequest) -> HttpResponse:",
+            "        # Runs before the view (and the middleware after this one).",
+            "        response = self.get_response(request)",
+            "        # Runs after the view.",
+            "        return response",
+        ]
+    )
+    imports = [
+        Import("collections.abc", "Callable"),
+        Import("django.http", "HttpRequest"),
+        Import("django.http", "HttpResponse"),
+    ]
+    text = ensure_imports(ws, rel, ws.read(path) or "", imports)
+    ws.write(path, replace_or_append(ws, rel, text, class_name, block))
+    dotted = f"{app.module}.middleware.{class_name}"
+    settings = ws.read(SETTINGS)
+    try:
+        if settings is None:
+            raise CliError(f"{SETTINGS.as_posix()} not found", code="C001")
+        updated = add_entry(
+            settings,
+            dotted,
+            setting="MIDDLEWARE",
+            marker=MIDDLEWARE_MARKER,
+            filename=SETTINGS.as_posix(),
+        )
+    except CliError:
+        ws.note(
+            f"wire it yourself: add {dotted!r} to MIDDLEWARE in {SETTINGS.as_posix()} "
+            f"(projects scaffolded before `{MIDDLEWARE_MARKER}` have no marker block)."
+        )
+    else:
+        if updated is not None:
+            ws.write(SETTINGS, updated)
+        ws.note(f"middleware: {dotted} (last in MIDDLEWARE — move it if order matters)")
+    return dotted
+
+
+def command(
+    name: str = typer.Argument(..., help="Class name, PascalCase (Middleware suffix added)."),
+    app: str | None = APP_OPTION,
+    force: bool = FORCE_OPTION,
+    dry_run: bool = DRY_RUN_OPTION,
+) -> None:
+    """Add a middleware class to APP/middleware.py and wire it into MIDDLEWARE.
+
+    Wiring goes through the `# karni:middleware` block of config/settings.py
+    (appended after Karni's middleware); without that block the command
+    prints the line to add.
+    """
+    ws = project_workspace(force)
+    plan(ws, resolve_app(ws, app), name)
+    ws.commit(dry_run=dry_run)

karni_cli/generators/migration.py

@@ -0,0 +1,82 @@
+"""``karni make migration [name]`` — ``manage.py makemigrations`` through the project interpreter.
+
+The only generator that needs Django: it runs the project's own
+``makemigrations`` (``.venv``, else the running compose service — see
+:mod:`karni_cli.project`), streaming its output and exit code.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from karni_cli import project as project_mod
+from karni_cli.generators.core import APP_OPTION, DRY_RUN_OPTION, Workspace, resolve_app
+from karni_cli.project import require_project
+
+NAME = "migration"
+SUMMARY = "Create migrations: wraps manage.py makemigrations [app] [--name] [--empty]."
+
+
+def makemigrations_args(
+    app_label: str | None, name: str | None, *, empty: bool, dry_run: bool
+) -> list[str]:
+    args = ["makemigrations"]
+    if app_label:
+        args.append(app_label)
+    if name:
+        args += ["--name", name]
+    if empty:
+        args.append("--empty")
+    if dry_run:
+        args.append("--dry-run")
+    return args
+
+
+def run(
+    project: Path,
+    app_label: str | None,
+    name: str | None = None,
+    *,
+    empty: bool = False,
+    dry_run: bool = False,
+    docker: bool | None = None,
+    service: str = "django",
+) -> int:
+    """Run makemigrations in the project environment; returns its exit code."""
+    proc = project_mod.run_manage(
+        project,
+        makemigrations_args(app_label, name, empty=empty, dry_run=dry_run),
+        docker=docker,
+        service=service,
+        capture=False,
+    )
+    return proc.returncode
+
+
+def command(
+    name: str | None = typer.Argument(
+        None, help="Migration name (makemigrations --name), e.g. add_event_capacity."
+    ),
+    empty: bool = typer.Option(
+        False, "--empty", help="An empty migration to fill in (data migrations); needs one app."
+    ),
+    app: str | None = APP_OPTION,
+    dry_run: bool = DRY_RUN_OPTION,
+    docker: bool | None = typer.Option(None, "--docker/--no-docker"),
+    service: str = typer.Option("django", "--service", envvar="KARNI_COMPOSE_SERVICE"),
+) -> None:
+    """Create migrations — wraps `manage.py makemigrations [APP] [--name NAME] [--empty]`.
+
+    Without --app every app with model changes gets a migration; --empty
+    (a data migration) targets one app: --app, else the only local app.
+    --dry-run is makemigrations' own (prints, writes nothing).
+    """
+    project = require_project()
+    label = None
+    if app is not None or empty:
+        label = resolve_app(Workspace(project), app).label
+    raise typer.Exit(
+        run(project, label, name, empty=empty, dry_run=dry_run, docker=docker, service=service)
+    )

karni_cli/generators/model.py

@@ -0,0 +1,235 @@
+"""``karni make model <Name> [field:type ...]`` — a model on BaseModel.
+
+The field DSL is documented in :mod:`karni_cli.generators.fields`. ``--with
+viewset,page,test,factory,seeder`` chains the other generators in the same
+run: a viewset (``--access``/``--search`` apply), the list, detail and form
+pages for the resource (linked to each other), its API test, an explicit
+factory and a seeder. ``-a/--all`` chains viewset, page and test — factories
+and seeders are overrides of what Karni already generates, so they are only
+written when asked for.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from karni_cli.generators import apitest as test_gen
+from karni_cli.generators import factory as factory_gen
+from karni_cli.generators import migration as migration_gen
+from karni_cli.generators import page as page_gen
+from karni_cli.generators import seeder as seeder_gen
+from karni_cli.generators import viewset as viewset_gen
+from karni_cli.generators.core import (
+    APP_OPTION,
+    DRY_RUN_OPTION,
+    FORCE_OPTION,
+    App,
+    Workspace,
+    local_apps,
+    project_workspace,
+    resolve_app,
+    split_csv,
+)
+from karni_cli.generators.fields import (
+    FieldSpec,
+    RelationTarget,
+    is_user_target,
+    parse_fields,
+    relation_name,
+    render_model_body,
+)
+from karni_cli.generators.introspect import models_file, models_in
+from karni_cli.generators.naming import default_route, kebab, require_pascal
+from karni_cli.generators.pysource import Import, ensure_imports, pystr, replace_or_append
+from karni_cli.project import CliError
+
+NAME = "model"
+SUMMARY = "Add a model on BaseModel from a field DSL; --with viewset,page,test or -a chains them."
+
+#: What ``--with`` can chain, in run order.
+CHAINABLE = ("viewset", "page", "test", "factory", "seeder")
+#: What ``-a/--all`` chains: everything except the explicit overrides (factory, seeder).
+ALL = ("viewset", "page", "test")
+
+
+def _targets(
+    ws: Workspace, app: App, model: str, specs: list[FieldSpec]
+) -> dict[str, RelationTarget]:
+    resolved: dict[str, RelationTarget] = {}
+    own = models_in(ws, app)
+    for spec in specs:
+        if not spec.is_relation:
+            continue
+        raw = relation_name(spec)
+        if is_user_target(raw):
+            resolved[spec.name] = RelationTarget("settings.AUTH_USER_MODEL", True, "user")
+        elif raw in ("self", model):
+            resolved[spec.name] = RelationTarget(pystr("self"), False, "self")
+        elif "." in raw:
+            label, _, name = raw.partition(".")
+            for other in local_apps(ws):
+                if other.label == label and name not in models_in(ws, other):
+                    raise CliError(
+                        f"Field {spec.name}: app {label} has no model {name} — "
+                        f"karni make model {name} --app {label}",
+                        code="C104",
+                    )
+            resolved[spec.name] = RelationTarget(pystr(raw), False, raw.lower())
+        elif raw in own:
+            resolved[spec.name] = RelationTarget(pystr(raw), False, f"{app.label}.{raw}".lower())
+        else:
+            owners = [other for other in local_apps(ws) if raw in models_in(ws, other)]
+            if len(owners) != 1:
+                where = "several apps" if owners else "no local app"
+                raise CliError(
+                    f"Field {spec.name}: {where} defines a model {raw!r} — create it first "
+                    f"(karni make model {raw}) or write app.Model, e.g. "
+                    f"{spec.name}:{spec.kind}:shop.{raw}.",
+                    code="C104",
+                )
+            target = f"{owners[0].label}.{raw}"
+            resolved[spec.name] = RelationTarget(pystr(target), False, target.lower())
+    return resolved
+
+
+def plan(ws: Workspace, app: App, name: str, field_tokens: list[str]) -> str:
+    """Plan the model class in ``<app>/models.py``; returns the class name."""
+    model = require_pascal(name, "Model name")
+    specs = parse_fields(field_tokens)
+    path = models_file(ws, app)
+    rel = ws.rel(path)
+    body = render_model_body(
+        specs,
+        model=model,
+        app_label=app.label,
+        resolve=_targets(ws, app, model, specs),
+        line_length=ws.line_length,
+    )
+    lines = [f"class {model}(BaseModel):"]
+    if body.inner:
+        lines += [*body.inner, ""]
+    lines += body.lines
+    text_field = next((s.name for s in specs if s.is_text), None)
+    if text_field is not None:
+        lines += ["", "    def __str__(self) -> str:", f"        return self.{text_field}"]
+    if len(lines) == 1:
+        lines.append("    pass")
+    text = ws.read(path) or ""
+    text = ensure_imports(ws, rel, text, [Import("karni.models", "BaseModel"), *body.imports])
+    ws.write(path, replace_or_append(ws, rel, text, model, "\n".join(lines)))
+    for note in body.notes:
+        ws.note(note)
+    return model
+
+
+def plan_chain(
+    ws: Workspace,
+    app: App,
+    model: str,
+    chain: list[str],
+    *,
+    access: str | None,
+    search: list[str],
+    expand: list[str] | None = None,
+) -> None:
+    """The ``--with`` steps after the model, in :data:`CHAINABLE` order.
+
+    ``expand``: relation fields the detail page asks the API to expand, so it
+    shows the related rows' labels instead of raw ids.
+    """
+    if "viewset" in chain:
+        viewset_gen.plan(ws, app, model, access=access, search=search)
+    if "page" in chain:
+        resource = default_route(model)
+        singular = kebab(model)
+        specs = [
+            page_gen.spec_for(f"{singular}-form", resource=resource, kind="form", path=None),
+            page_gen.spec_for(
+                f"{singular}-detail", resource=resource, kind="detail", path=None, expand=expand
+            ),
+            page_gen.spec_for(resource, resource=resource, kind="list", path=None),
+        ]
+        planned = {path for spec in specs for path in spec.paths}
+        for spec in specs:
+            page_gen.plan(ws, spec, planned_routes=planned)
+    if "test" in chain:
+        test_gen.plan(ws, app, model)
+    if "factory" in chain:
+        factory_gen.plan(ws, app, model)
+    if "seeder" in chain:
+        seeder_gen.plan(ws, app, model)
+
+
+def resolve_chain(with_: list[str], all_: bool) -> list[str]:
+    chain = [*ALL, *split_csv(with_)] if all_ else split_csv(with_)
+    unknown = [item for item in chain if item not in CHAINABLE]
+    if unknown:
+        raise CliError(
+            f"--with {', '.join(unknown)}: unknown (available: {', '.join(CHAINABLE)}).",
+            code="C106",
+        )
+    return [item for item in CHAINABLE if item in chain]
+
+
+def command(
+    name: str = typer.Argument(..., help="Model class name, PascalCase (e.g. Event)."),
+    fields: list[str] | None = typer.Argument(
+        None,
+        help=(
+            "Fields as name:type[:arg][?] — str[:len] text int float decimal[:max:places] "
+            "bool date datetime email url slug json file image uuid choice:a|b fk:Model "
+            "m2m:Model o2o:Model; trailing ? = optional."
+        ),
+        show_default=False,
+    ),
+    with_: list[str] | None = typer.Option(
+        None,
+        "--with",
+        help="Also generate: viewset, page, test, factory, seeder (comma-separated or repeated).",
+    ),
+    all_: bool = typer.Option(
+        False, "--all", "-a", help="Also generate the viewset, the pages and the API test."
+    ),
+    access: str | None = typer.Option(
+        None, "--access", help=f"With viewset: {viewset_gen.ACCESS_CHOICES}."
+    ),
+    search: list[str] | None = typer.Option(
+        None, "--search", help="With viewset: search_fields (comma-separated)."
+    ),
+    migrate: bool = typer.Option(
+        False, "--migrate", help="Run `karni make migration` for the app afterwards."
+    ),
+    app: str | None = APP_OPTION,
+    force: bool = FORCE_OPTION,
+    dry_run: bool = DRY_RUN_OPTION,
+) -> None:
+    """Add `class NAME(BaseModel)` with FIELDS to APP/models.py.
+
+    Example: karni make model Event title:str:200 starts_at:datetime
+    "status:choice:draft|live" organizer:fk:User 'venue:fk:Venue?' -a
+    --access owned:organizer
+    """
+    ws = project_workspace(force)
+    chain = resolve_chain(with_ or [], all_)
+    if (access or search) and "viewset" not in chain:
+        raise CliError(
+            "--access/--search configure the viewset: add --with viewset (or -a).", code="C004"
+        )
+    target = resolve_app(ws, app)
+    if all_ and not ws.is_dir("frontend"):
+        chain = [item for item in chain if item != "page"]
+        ws.note("note: no frontend/ directory — pages skipped.")
+    model = plan(ws, target, name, fields or [])
+    expand = [
+        spec.name
+        for spec in parse_fields(fields or [])
+        if spec.is_relation and not is_user_target(relation_name(spec))
+    ]
+    plan_chain(ws, target, model, chain, access=access, search=split_csv(search), expand=expand)
+    if not migrate:
+        ws.note(f"next: karni make migration --app {target.label}")
+    ws.commit(dry_run=dry_run)
+    if migrate and not dry_run:
+        code = migration_gen.run(ws.root, target.label)
+        if code != 0:
+            raise typer.Exit(code)