karni-cli 0.3.1__py3-none-any.whl

karni_cli/generators/fields.py

@@ -0,0 +1,343 @@
+"""The ``karni make model`` field DSL: ``name:type[:arg...][?]``.
+
+:data:`FIELD_DOCS` lists every type with the Django field it produces (it is
+also rendered into docs/cli.md). A trailing ``?`` makes the field optional:
+``null=True, blank=True``; string and file fields get ``blank=True`` only
+(Django stores ``""``, not ``NULL``); an optional FK/O2O uses
+``on_delete=models.SET_NULL``. Choice values are separated by ``|`` (quote
+the argument in a shell) or ``,``. Quote any field with ``?`` in zsh.
+"""
+
+from __future__ import annotations
+
+import keyword
+import re
+from dataclasses import dataclass, field
+
+from karni_cli.generators.naming import pascal, snake
+from karni_cli.generators.pysource import Import, call, pystr
+from karni_cli.project import CliError
+
+#: (syntax, what it generates) — the DSL reference, rendered into docs/cli.md.
+FIELD_DOCS: tuple[tuple[str, str], ...] = (
+    ("title:str[:len]", "CharField(max_length=len) — 255 when omitted"),
+    ("body:text", "TextField()"),
+    ("count:int", "IntegerField()"),
+    ("ratio:float", "FloatField()"),
+    ("price:decimal[:max:places]", "DecimalField(max_digits=max, decimal_places=places) — 10, 2"),
+    ("done:bool", "BooleanField(default=False)"),
+    ("day:date / at:datetime", "DateField() / DateTimeField()"),
+    (
+        "email:email / site:url / slug:slug",
+        "EmailField() / URLField() / SlugField() (:len optional)",
+    ),
+    ("meta:json", "JSONField(default=dict)"),
+    (
+        "doc:file / photo:image",
+        'FileField / ImageField(upload_to="<app>/<model>/") — image needs Pillow',
+    ),
+    ("ref:uuid", "UUIDField(default=uuid.uuid4)"),
+    ("status:choice:draft|live", "a TextChoices class + CharField(choices=..., default=first)"),
+    ("owner:fk:User", "ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)"),
+    ("venue:fk:Venue / fk:shop.Venue", 'ForeignKey("Venue") in the same app, or "app.Model"'),
+    ("tags:m2m:Tag / profile:o2o:User", "ManyToManyField / OneToOneField"),
+    ("name:type?", "optional: null=True, blank=True (strings and files: blank=True)"),
+)
+
+#: Fields BaseModel already declares, and names its methods/managers use.
+RESERVED = frozenset(
+    {
+        "id",
+        "pk",
+        "created_at",
+        "updated_at",
+        "deleted_at",
+        "created_by",
+        "updated_by",
+        "objects",
+        "all_objects",
+        "is_deleted",
+        "delete",
+        "hard_delete",
+        "restore",
+        "save",
+        "clean",
+    }
+)
+
+ALIASES = {
+    "string": "str",
+    "char": "str",
+    "integer": "int",
+    "boolean": "bool",
+    "choices": "choice",
+    "foreignkey": "fk",
+    "manytomany": "m2m",
+    "onetoone": "o2o",
+}
+
+TYPES = (
+    "str",
+    "text",
+    "int",
+    "float",
+    "decimal",
+    "bool",
+    "date",
+    "datetime",
+    "email",
+    "url",
+    "slug",
+    "json",
+    "file",
+    "image",
+    "uuid",
+    "choice",
+    "fk",
+    "m2m",
+    "o2o",
+)
+
+_STRINGISH = frozenset({"str", "text", "email", "url", "slug", "file", "image", "choice"})
+_RELATIONS = {"fk": "ForeignKey", "o2o": "OneToOneField", "m2m": "ManyToManyField"}
+_SIMPLE = {
+    "text": "TextField",
+    "int": "IntegerField",
+    "float": "FloatField",
+    "date": "DateField",
+    "datetime": "DateTimeField",
+}
+_USER_NAMES = frozenset({"user", "auth.user", "settings.auth_user_model"})
+_CHOICE_VALUE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
+
+
+@dataclass(frozen=True)
+class FieldSpec:
+    name: str
+    kind: str
+    args: tuple[str, ...]
+    optional: bool
+
+    @property
+    def is_relation(self) -> bool:
+        return self.kind in _RELATIONS
+
+    @property
+    def is_text(self) -> bool:
+        """A plain string column usable as ``__str__`` / search field."""
+        return self.kind in {"str", "slug", "email"}
+
+
+@dataclass
+class Rendered:
+    """A model body: inner classes, field lines and the imports they need."""
+
+    inner: list[str] = field(default_factory=list)
+    lines: list[str] = field(default_factory=list)
+    imports: list[Import] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+
+def parse_field(token: str) -> FieldSpec:
+    raw = token.strip()
+    optional = raw.endswith("?")
+    parts = raw.rstrip("?").split(":")
+    if len(parts) < 2 or not parts[0] or not parts[1]:
+        raise CliError(
+            f"Field {token!r}: expected name:type[:arg][?], e.g. title:str:200 or "
+            "starts_at:datetime? (types: " + ", ".join(TYPES) + ").",
+            code="C104",
+        )
+    name, kind, *args = parts
+    kind = ALIASES.get(kind.lower(), kind.lower())
+    if kind not in TYPES:
+        raise CliError(
+            f"Field {token!r}: unknown type {kind!r} (types: {', '.join(TYPES)}).", code="C104"
+        )
+    if not name.isidentifier() or keyword.iskeyword(name) or name != name.lower():
+        raise CliError(f"Field {token!r}: {name!r} must be a snake_case identifier.", code="C104")
+    if name.startswith("_") or "__" in name:
+        raise CliError(
+            f"Field {token!r}: names may not start with _ or contain __ (Django).", code="C104"
+        )
+    if name in RESERVED:
+        raise CliError(
+            f"Field {token!r}: {name!r} is reserved — BaseModel already provides it "
+            "(id, created_at, updated_at, deleted_at, created_by, updated_by) or uses the name.",
+            code="C104",
+        )
+    return FieldSpec(name, kind, tuple(args), optional)
+
+
+def parse_fields(tokens: list[str]) -> list[FieldSpec]:
+    specs = [parse_field(token) for token in tokens]
+    seen: set[str] = set()
+    for spec in specs:
+        if spec.name in seen:
+            raise CliError(f"Field {spec.name!r} is declared twice.", code="C104")
+        seen.add(spec.name)
+    return specs
+
+
+def _int_arg(spec: FieldSpec, index: int, default: int, what: str) -> int:
+    if len(spec.args) <= index or spec.args[index] == "":
+        return default
+    value = spec.args[index]
+    if not value.isdigit() or int(value) <= 0:
+        raise CliError(
+            f"Field {spec.name}: {what} must be a positive integer, got {value!r}.", code="C104"
+        )
+    return int(value)
+
+
+def _optional_kwargs(spec: FieldSpec) -> list[str]:
+    if not spec.optional:
+        return []
+    if spec.kind in _STRINGISH:
+        return ["blank=True"]
+    return ["null=True", "blank=True"]
+
+
+@dataclass(frozen=True)
+class RelationTarget:
+    """How a relation field refers to its target model."""
+
+    expr: str
+    is_user: bool
+    key: str
+
+
+def render_model_body(
+    specs: list[FieldSpec],
+    *,
+    model: str,
+    app_label: str,
+    resolve: dict[str, RelationTarget],
+    line_length: int,
+) -> Rendered:
+    """Field lines (indented four spaces) for ``model`` in ``app_label``.
+
+    :param resolve: relation target per field name (``spec.args[0]`` resolved
+        by the caller, which can see the project's models).
+    """
+    out = Rendered()
+    indent = "    "
+    targets = [resolve[s.name].key for s in specs if s.is_relation]
+    for spec in specs:
+        head = f"{spec.name} = models."
+        if spec.kind in {"str", "email", "url", "slug"}:
+            django = {"str": "CharField", "email": "EmailField", "url": "URLField"}.get(
+                spec.kind, "SlugField"
+            )
+            args: list[str] = []
+            if spec.kind == "str":
+                args.append(f"max_length={_int_arg(spec, 0, 255, 'max_length')}")
+            elif spec.args and spec.args[0]:
+                args.append(f"max_length={_int_arg(spec, 0, 1, 'max_length')}")
+            out.lines.append(
+                call(head + django, args + _optional_kwargs(spec), indent, line_length)
+            )
+        elif spec.kind in _SIMPLE:
+            out.lines.append(
+                call(head + _SIMPLE[spec.kind], _optional_kwargs(spec), indent, line_length)
+            )
+        elif spec.kind == "decimal":
+            digits = _int_arg(spec, 0, 10, "max_digits")
+            places = _int_arg(spec, 1, 2, "decimal_places")
+            if places > digits:
+                raise CliError(
+                    f"Field {spec.name}: decimal_places ({places}) > max_digits ({digits}).",
+                    code="C104",
+                )
+            args = [f"max_digits={digits}", f"decimal_places={places}", *_optional_kwargs(spec)]
+            out.lines.append(call(head + "DecimalField", args, indent, line_length))
+        elif spec.kind == "bool":
+            args = _optional_kwargs(spec) or ["default=False"]
+            out.lines.append(call(head + "BooleanField", args, indent, line_length))
+        elif spec.kind == "json":
+            args = _optional_kwargs(spec) or ["default=dict"]
+            out.lines.append(call(head + "JSONField", args, indent, line_length))
+        elif spec.kind == "uuid":
+            if spec.optional:
+                args = _optional_kwargs(spec)
+            else:
+                args = ["default=uuid.uuid4"]
+                out.imports.append(Import("uuid"))
+            out.lines.append(call(head + "UUIDField", args, indent, line_length))
+        elif spec.kind in {"file", "image"}:
+            django = "FileField" if spec.kind == "file" else "ImageField"
+            upload = pystr(f"{app_label}/{snake(model)}/")
+            args = [f"upload_to={upload}", *_optional_kwargs(spec)]
+            out.lines.append(call(head + django, args, indent, line_length))
+            if spec.kind == "image":
+                out.notes.append(
+                    f"note: {model}.{spec.name} is an ImageField — the project needs Pillow "
+                    "(pip install 'karni[images]')."
+                )
+        elif spec.kind == "choice":
+            _render_choice(spec, out, indent, line_length)
+        else:
+            target = resolve[spec.name]
+            args = [target.expr]
+            if spec.kind != "m2m":
+                if spec.optional:
+                    args += ["on_delete=models.SET_NULL", "null=True", "blank=True"]
+                else:
+                    args.append("on_delete=models.CASCADE")
+            elif spec.optional:
+                args.append("blank=True")
+            if targets.count(target.key) > 1:
+                args.append(f"related_name={pystr(snake(model) + '_' + spec.name + '_set')}")
+            out.lines.append(call(head + _RELATIONS[spec.kind], args, indent, line_length))
+            if target.is_user:
+                out.imports.append(Import("django.conf", "settings"))
+    if out.lines:
+        out.imports.append(Import("django.db", "models"))
+    return out
+
+
+def _render_choice(spec: FieldSpec, out: Rendered, indent: str, line_length: int) -> None:
+    raw = ":".join(spec.args)
+    values = [v.strip() for v in re.split(r"[|,]", raw) if v.strip()]
+    if not values:
+        raise CliError(
+            f"Field {spec.name}: choice needs values, e.g. '{spec.name}:choice:draft|published'.",
+            code="C104",
+        )
+    members: list[tuple[str, str]] = []
+    for value in values:
+        if not _CHOICE_VALUE.match(value):
+            raise CliError(
+                f"Field {spec.name}: choice value {value!r} may only use letters, digits, - and _.",
+                code="C104",
+            )
+        member = re.sub(r"[^A-Za-z0-9]", "_", value).upper()
+        if member[0].isdigit():
+            member = f"V_{member}"
+        if member in {m for m, _ in members}:
+            raise CliError(
+                f"Field {spec.name}: choice value {value!r} is listed twice.", code="C104"
+            )
+        members.append((member, value))
+    enum = pascal(spec.name)
+    out.inner.append(f"{indent}class {enum}(models.TextChoices):")
+    out.inner += [f"{indent}    {member} = {pystr(value)}" for member, value in members]
+    length = max(20, *(len(value) for _, value in members))
+    args = [f"max_length={length}", f"choices={enum}.choices"]
+    args += _optional_kwargs(spec) or [f"default={enum}.{members[0][0]}"]
+    out.lines.append(call(f"{spec.name} = models.CharField", args, indent, line_length))
+
+
+def relation_name(spec: FieldSpec) -> str:
+    """The raw target the user wrote for a relation field."""
+    if not spec.args or not spec.args[0]:
+        raise CliError(
+            f"Field {spec.name}: {spec.kind} needs a target model, e.g. "
+            f"'{spec.name}:{spec.kind}:User' or '{spec.name}:{spec.kind}:shop.Product'.",
+            code="C104",
+        )
+    return spec.args[0]
+
+
+def is_user_target(name: str) -> bool:
+    return name.lower() in _USER_NAMES

karni_cli/generators/introspect.py

@@ -0,0 +1,263 @@
+"""Static (AST) facts about a project's apps — what already exists, without Django."""
+
+from __future__ import annotations
+
+import ast
+import fnmatch
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from karni_cli.generators.core import SETTINGS, App, Workspace, local_apps
+from karni_cli.generators.pysource import parse
+from karni_cli.project import CliError
+
+#: karni.conf.base's default KARNI_ROLES, mirrored (the CLI runs without karni):
+#: staff holds everything, user and customer their own rows.
+SHIPPED_ROLES: dict[str, dict[str, Any]] = {
+    "staff": {"grants": {"*": "all"}},
+    "user": {"grants": {"*": "own"}},
+    "customer": {"grants": {"*": "own"}},
+}
+
+_RELATION_CALLS = frozenset({"ForeignKey", "OneToOneField", "ManyToManyField"})
+_AUDIT_BASES = frozenset({"BaseModel", "AuditedModel"})
+
+
+@dataclass(frozen=True)
+class ModelInfo:
+    app: App
+    name: str
+    path: Path
+    #: field name -> the called class name (``CharField``, ``ForeignKey`` …)
+    fields: dict[str, str]
+    bases: frozenset[str]
+
+    @property
+    def import_module(self) -> str:
+        return f"{self.app.module}.models"
+
+    def is_relation(self, name: str) -> bool:
+        if name in {"created_by", "updated_by"}:
+            return bool(self.bases & _AUDIT_BASES)
+        return self.fields.get(name) in _RELATION_CALLS
+
+    def has_field(self, name: str) -> bool:
+        if name in {"id", "pk", "created_at", "updated_at", "created_by", "updated_by"}:
+            return True
+        return name in self.fields
+
+
+def _call_name(node: ast.expr) -> str:
+    if isinstance(node, ast.Call):
+        func = node.func
+        if isinstance(func, ast.Attribute):
+            return func.attr
+        if isinstance(func, ast.Name):
+            return func.id
+    return ""
+
+
+def class_fields(cls: ast.ClassDef) -> dict[str, str]:
+    """``name = models.X(...)`` assignments in a class body → ``{name: "X"}``."""
+    found: dict[str, str] = {}
+    for stmt in cls.body:
+        if isinstance(stmt, ast.Assign) and len(stmt.targets) == 1:
+            target = stmt.targets[0]
+            called = _call_name(stmt.value)
+            if isinstance(target, ast.Name) and (
+                called.endswith("Field") or called in _RELATION_CALLS
+            ):
+                found[target.id] = called
+    return found
+
+
+def _bases(cls: ast.ClassDef) -> frozenset[str]:
+    names: set[str] = set()
+    for base in cls.bases:
+        if isinstance(base, ast.Name):
+            names.add(base.id)
+        elif isinstance(base, ast.Attribute):
+            names.add(base.attr)
+    return frozenset(names)
+
+
+def models_file(ws: Workspace, app: App) -> Path:
+    """``<app>/models.py``; a ``models/`` package is an unsupported layout."""
+    path = app.file("models.py")
+    if not ws.exists(path) and ws.is_dir(app.file("models")):
+        raise CliError(
+            f"{ws.rel(app.file('models'))}/ is a package — karni make writes "
+            f"{ws.rel(path)}. Add the class to the package yourself (and re-export it "
+            "from models/__init__.py).",
+            code="C107",
+        )
+    return path
+
+
+def models_in(ws: Workspace, app: App) -> dict[str, ModelInfo]:
+    path = models_file(ws, app)
+    text = ws.read(path)
+    if text is None:
+        return {}
+    tree = parse(ws, ws.rel(path), text)
+    found: dict[str, ModelInfo] = {}
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef):
+            found[node.name] = ModelInfo(app, node.name, path, class_fields(node), _bases(node))
+    return found
+
+
+def find_model(ws: Workspace, app: App, name: str) -> ModelInfo | None:
+    """``name`` in ``app``'s models, else in exactly one other local app."""
+    own = models_in(ws, app).get(name)
+    if own is not None:
+        return own
+    others = [
+        info
+        for other in local_apps(ws)
+        if other != app
+        for info in [models_in(ws, other).get(name)]
+        if info is not None
+    ]
+    return others[0] if len(others) == 1 else None
+
+
+def require_model(ws: Workspace, app: App, name: str) -> ModelInfo:
+    info = find_model(ws, app, name)
+    if info is None:
+        raise CliError(
+            f"No model {name} in {ws.rel(models_file(ws, app))} — create it first: "
+            f"karni make model {name} --app {app.label}",
+            code="C105",
+        )
+    return info
+
+
+def viewsets_file(ws: Workspace, app: App) -> Path:
+    """``<app>/viewsets.py``, or ``<app>/api/viewsets.py`` when only that exists."""
+    plain = app.file("viewsets.py")
+    nested = app.file("api", "viewsets.py")
+    if not ws.exists(plain) and ws.exists(nested):
+        return nested
+    return plain
+
+
+def viewset_for(ws: Workspace, app: App, model: str) -> tuple[Path, ast.ClassDef] | None:
+    """The class in the app's viewsets module whose body says ``model = <model>``."""
+    path = viewsets_file(ws, app)
+    text = ws.read(path)
+    if text is None:
+        return None
+    for node in parse(ws, ws.rel(path), text).body:
+        if not isinstance(node, ast.ClassDef):
+            continue
+        for stmt in node.body:
+            if (
+                isinstance(stmt, ast.Assign)
+                and any(isinstance(t, ast.Name) and t.id == "model" for t in stmt.targets)
+                and isinstance(stmt.value, ast.Name)
+                and stmt.value.id == model
+            ):
+                return path, node
+    return None
+
+
+def owned_paths(cls: ast.ClassDef) -> list[str]:
+    """String arguments of every ``Owned("...")`` call in the class body."""
+    found: list[str] = []
+    for node in ast.walk(cls):
+        if (
+            isinstance(node, ast.Call)
+            and _call_name(node) == "Owned"
+            and node.args
+            and isinstance(node.args[0], ast.Constant)
+            and isinstance(node.args[0].value, str)
+        ):
+            found.append(node.args[0].value)
+    return found
+
+
+def top_level_functions(ws: Workspace, path: Path) -> set[str]:
+    text = ws.read(path)
+    if text is None:
+        return set()
+    tree = parse(ws, ws.rel(path), text)
+    return {
+        node.name for node in tree.body if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef)
+    }
+
+
+def top_level_assignments(ws: Workspace, path: Path) -> set[str]:
+    text = ws.read(path)
+    if text is None:
+        return set()
+    names: set[str] = set()
+    for node in parse(ws, ws.rel(path), text).body:
+        if isinstance(node, ast.Assign):
+            names |= {t.id for t in node.targets if isinstance(t, ast.Name)}
+        elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            names.add(node.target.id)
+    return names
+
+
+def role_names(cls: ast.ClassDef) -> list[str]:
+    """String arguments of every ``HasRole("...")`` call in the class body, in order."""
+    found: list[str] = []
+    for node in ast.walk(cls):
+        if isinstance(node, ast.Call) and _call_name(node) == "HasRole":
+            for arg in node.args:
+                if (
+                    isinstance(arg, ast.Constant)
+                    and isinstance(arg.value, str)
+                    and arg.value not in found
+                ):
+                    found.append(arg.value)
+    return found
+
+
+def granted_reads(cls: ast.ClassDef) -> bool:
+    """Whether the class body calls ``Granted()`` — the roles' grants decide its rows."""
+    return any(
+        isinstance(node, ast.Call) and _call_name(node) == "Granted" for node in ast.walk(cls)
+    )
+
+
+def declared_roles(ws: Workspace) -> dict[str, dict[str, Any]]:
+    """``KARNI_ROLES`` from config/settings.py when it is a literal, else the shipped default."""
+    text = ws.read(SETTINGS)
+    if text is None:
+        return dict(SHIPPED_ROLES)
+    for node in parse(ws, ws.rel(SETTINGS), text).body:
+        if isinstance(node, ast.Assign) and any(
+            isinstance(target, ast.Name) and target.id == "KARNI_ROLES" for target in node.targets
+        ):
+            try:
+                value = ast.literal_eval(node.value)
+            except ValueError:
+                return {}  # computed at runtime: unknown here
+            return value if isinstance(value, dict) else {}
+    return dict(SHIPPED_ROLES)
+
+
+def grant_scopes(roles: dict[str, dict[str, Any]], key: str) -> dict[str, str]:
+    """Role slug → the scope its grants give ``key`` (``app.model:action``); later patterns win."""
+    found: dict[str, str] = {}
+    for slug, spec in roles.items():
+        grants = spec.get("grants") if isinstance(spec, dict) else None
+        if not isinstance(grants, dict):
+            continue
+        scope = None
+        for pattern, value in grants.items():
+            glob = "*:*" if pattern == "*" else str(pattern)
+            if fnmatch.fnmatchcase(key, glob):
+                scope = str(value)
+        if scope is not None:
+            found[slug] = scope
+    return found
+
+
+def viewset_module(ws: Workspace, app: App, path: Path) -> str:
+    """The dotted module of a viewsets file of ``app`` (``events.viewsets``)."""
+    rel = path.relative_to(app.path).with_suffix("")
+    return ".".join([app.module, *rel.parts])