snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/dto/read.py

@@ -0,0 +1,231 @@
+"""Reading the declarations out of a DTO file with `ast`, without importing or running it.
+
+The declarations live under `if TYPE_CHECKING:`, so there is nothing to run: the interpreter never
+reaches them and only a checker looks. That is not an obstacle this module works around, it is the
+arrangement that makes the whole thing safe — a tool that rewrites your file does not execute your
+file, and the check mode in particular touches nothing of yours at all.
+
+The ONLY thing imported is the models module the file names, because the compiled metadata is where
+the types, the nullability and the relationships live. The AST gives names; `SnakeTableInfo` gives
+the truth.
+
+Reading also sees something evaluating cannot. The source says which name a path is ROOTED at, and
+the evaluated descriptor has forgotten: `Post.author.username` and `Author.username` both come out
+as a `SnakeExpr` that knows its own steps and not whose they are. So a spec over `Post` that selects
+`Author.id` — which type-checks, because `Author.id` is a perfectly good expression — is a refusal
+here and was invisible before.
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib
+
+from snakeorm.core.exceptions import SnakeDtoError
+from snakeorm.dto.spec import SnakeDtoPick, SnakeDtoSpec, build_spec
+
+_SNAKE_DTO = "snakeorm.dto.snake_dto"
+"""The dotted path the declaration function is imported from.
+
+Matched through the file's IMPORTS rather than by the literal text `snake_dto`, so an alias reads
+and somebody else's function of the same name does not.
+"""
+
+
+def specs_in_source(source: str, *, path: str = "<source>") -> tuple[SnakeDtoSpec, ...]:
+    """Every `snake_dto(...)` declaration in this source, in the order it was written.
+
+    Model modules are imported as they are named — that is what compiles the metadata — but the file
+    being read never is.
+    """
+    try:
+        tree = ast.parse(source, filename=path)
+    except SyntaxError as error:
+        raise SnakeDtoError(
+            f"{path} is not valid Python, so there are no declarations to read: {error}"
+        ) from error
+    statements = _reachable(tree)
+    imports = _imported_paths(statements)
+    callers = {local for local, dotted in imports.items() if dotted == _SNAKE_DTO}
+    return tuple(
+        _spec_of(call, imports, path)
+        for statement in statements
+        if isinstance(statement, ast.Expr)
+        and isinstance(statement.value, ast.Call)
+        and _called_name(statement.value) in callers
+        for call in [statement.value]
+    )
+
+
+def _reachable(tree: ast.Module) -> list[ast.stmt]:
+    """The module's own statements, plus the bodies of its `if TYPE_CHECKING:` blocks.
+
+    Both spellings of the guard count, the bare name and the attribute. Recognising only one would
+    reject a file that is correct, which is the same fail-in-the-open shape as identifying a
+    TypedDict by the text of its base class.
+    """
+    statements: list[ast.stmt] = []
+    for statement in tree.body:
+        if isinstance(statement, ast.If) and _is_type_checking(statement.test):
+            statements.extend(statement.body)
+        else:
+            statements.append(statement)
+    return statements
+
+
+def _is_type_checking(test: ast.expr) -> bool:
+    """Whether an `if` guards a type-checking-only block, written either way round."""
+    if isinstance(test, ast.Name):
+        return test.id == "TYPE_CHECKING"
+    return isinstance(test, ast.Attribute) and test.attr == "TYPE_CHECKING"
+
+
+def _imported_paths(statements: list[ast.stmt]) -> dict[str, str]:
+    """Every name the file binds by importing, mapped to the dotted path it came from.
+
+    Only `from x import Y`, because that is what binds a CLASS. A plain `import x.y` binds a module,
+    and a module is neither a model nor the declaration function. A relative import is left out: it
+    gives no absolute path to import back, and guessing the package from the file would be guessing.
+    """
+    paths: dict[str, str] = {}
+    for statement in statements:
+        if not isinstance(statement, ast.ImportFrom) or statement.module is None:
+            continue
+        if statement.level:
+            continue
+        for alias in statement.names:
+            paths[alias.asname or alias.name] = f"{statement.module}.{alias.name}"
+    return paths
+
+
+def _called_name(call: ast.Call) -> str:
+    """The bare name a call is made through, or `""` for anything more complicated."""
+    return call.func.id if isinstance(call.func, ast.Name) else ""
+
+
+def _spec_of(call: ast.Call, imports: dict[str, str], path: str) -> SnakeDtoSpec:
+    """One `snake_dto(...)` call turned into a spec, with its model imported for real."""
+    where = f"{path}:{call.lineno}"
+    if len(call.args) != 1 or not isinstance(call.args[0], ast.Name):
+        raise SnakeDtoError(
+            f"{where}: snake_dto() takes the MODEL CLASS as its only positional argument, written "
+            f"as the name the file imports it under."
+        )
+    root = call.args[0].id
+    model = _model(root, imports, where)
+    name = _name(call, where)
+    fields = _list(call, "fields")
+    excluded = _list(call, "exclude")
+    return build_spec(
+        model=model,
+        name=name,
+        fields=None
+        if fields is None
+        else tuple(_pick(item, root, name, where) for item in fields),
+        exclude=None
+        if excluded is None
+        else tuple(_pick(item, root, name, where).path for item in excluded),
+        where=where,
+    )
+
+
+def _model(root: str, imports: dict[str, str], where: str) -> type:
+    """The model class, resolved through the file's own import of it and then imported for real.
+
+    Through the import and never through a registry index keyed by class name: two applications can
+    each declare a `Customer`, and that index is kept by whichever registered last. The dotted path
+    the user already wrote IS an identity, so the module is imported and the attribute read off it.
+    """
+    dotted = imports.get(root)
+    if dotted is None:
+        raise SnakeDtoError(
+            f"{where}: {root!r} is not imported in this file, so there is no telling which model "
+            f"it is. Add it under `if TYPE_CHECKING:` next to the declaration."
+        )
+    module_name, _, attribute = dotted.rpartition(".")
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as error:
+        raise SnakeDtoError(
+            f"{where}: {root!r} comes from {module_name!r}, which cannot be imported: {error}."
+        ) from error
+    found = getattr(module, attribute, None)
+    if not isinstance(found, type):
+        raise SnakeDtoError(
+            f"{where}: {module_name!r} has no class called {attribute!r}."
+        )
+    return found
+
+
+def _name(call: ast.Call, where: str) -> str:
+    """The `name=` keyword, which has to be a plain string literal to be readable without running."""
+    for keyword in call.keywords:
+        if keyword.arg == "name":
+            value = keyword.value
+            if isinstance(value, ast.Constant) and isinstance(value.value, str):
+                return value.value
+            raise SnakeDtoError(
+                f"{where}: name= has to be a plain string literal. It is read out of the source "
+                f"without running it, so an expression cannot be resolved."
+            )
+    raise SnakeDtoError(
+        f"{where}: this declaration has no name=, and that is what the generated class is called."
+    )
+
+
+def _list(call: ast.Call, keyword: str) -> list[ast.expr] | None:
+    """One of the two switches as a list of expressions, or `None` when it was not given."""
+    for item in call.keywords:
+        if item.arg == keyword:
+            if not isinstance(item.value, ast.List):
+                raise SnakeDtoError(
+                    f"{keyword}= has to be written as a list literal, so it can be read without "
+                    f"running the file."
+                )
+            return list(item.value.elts)
+    return None
+
+
+def _pick(entry: ast.expr, root: str, dto: str, where: str) -> SnakeDtoPick:
+    """One selected entry: the path it names, and the DTO it was disambiguated with if any."""
+    if isinstance(entry, ast.Tuple):
+        if len(entry.elts) != 2 or not isinstance(entry.elts[1], ast.Constant):
+            raise SnakeDtoError(
+                f'{where}: a paired entry of {dto} is written `(Model.relation, "DtoName")`, '
+                f"with the name as a plain string."
+            )
+        named = entry.elts[1].value
+        if not isinstance(named, str):
+            raise SnakeDtoError(
+                f"{where}: the DTO name paired with an entry of {dto} has to be a string."
+            )
+        return SnakeDtoPick(path=_chain(entry.elts[0], root, dto, where), dto=named)
+    return SnakeDtoPick(path=_chain(entry, root, dto, where))
+
+
+def _chain(entry: ast.expr, root: str, dto: str, where: str) -> tuple[str, ...]:
+    """The attribute chain an entry is written as, checked to start at the model being described.
+
+    The ROOT check is the one that only reading can do. `snake_dto(Post, fields=[Author.id])`
+    type-checks — `Author.id` is a valid expression — and the value it produces has forgotten it
+    came from `Author`. `Post` has an `id` too, so resolving the evaluated path lands on the wrong
+    column and says nothing.
+    """
+    steps: list[str] = []
+    node = entry
+    while isinstance(node, ast.Attribute):
+        steps.append(node.attr)
+        node = node.value
+    if not isinstance(node, ast.Name) or not steps:
+        raise SnakeDtoError(
+            f"{where}: {dto} selects something that is not class access on a model. An entry is "
+            f"written `Model.column`, `Model.relation.column` or `Model.relation`, so that the "
+            f"type checker validates it where you wrote it."
+        )
+    if node.id != root:
+        written = ".".join([node.id, *reversed(steps)])
+        raise SnakeDtoError(
+            f"{where}: {dto} describes {root} and selects {written}, which starts somewhere else. "
+            f"Every entry has to be rooted at the model the declaration names."
+        )
+    return tuple(reversed(steps))

snakeorm/dto/region.py

@@ -0,0 +1,326 @@
+"""The marked region: the only part of a DTO file this generator owns, and the only part it writes.
+
+A DTO file has two owners with a visible line between them. Above, the specs, which are the user's
+and are never edited. Between the markers, the classes, which are the generator's and are rewritten
+whole on every run. Nothing outside the two marker lines is ever touched — that is a property of the
+splice, not of care taken while writing it.
+
+A marker EARNS its place here in a way it would not have in somebody's own class body. These classes
+were never typed by a person: without the boundary there is no way to tell a generated class from a
+hand-written one, and a tool that cannot tell would eventually overwrite the wrong thing.
+
+The region is regenerated rather than patched, which is what makes idempotence structural: the same
+specs and the same models render the same bytes, so a second run has nothing to write. What is
+DIFFED, field by field, is the old region against the new one — and because the region is this
+module's own output, it can be read strictly instead of being guessed at.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Sequence
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+from snakeorm.core.exceptions import SnakeDtoError
+from snakeorm.dto.read import specs_in_source
+from snakeorm.dto.resolve import SnakeDtoShape, resolve_all
+from snakeorm.helpers.pytype import FROM_SNAKEORM
+
+BEGIN = "# snakeorm-dto: begin generated block"
+"""First line of the region. Matched as a PREFIX so the explanation after it can be reworded."""
+
+END = "# snakeorm-dto: end generated block"
+"""Last line of the region."""
+
+_HEADER = f"{BEGIN} — written by `snakeorm dto --sync`, edit the specs above"
+_FOOTER = END
+
+
+class SnakeDtoChangeKind(Enum):
+    """What happened to one field. Three kinds, because they are three different risks."""
+
+    ADDED = "added"
+    REMOVED = "removed"
+    RETYPED = "retyped"
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeDtoChange:
+    """One field this run added, dropped or retyped, with the text on both sides."""
+
+    dto: str
+    field: str
+    kind: SnakeDtoChangeKind
+    before: str = ""
+    after: str = ""
+
+    def describe(self) -> str:
+        """The change as ONE line, which is what the command prints.
+
+        Every change is printed, always. A generator that writes into your file and reports only
+        failures is a generator you have to `git diff` to trust.
+        """
+        if self.kind is SnakeDtoChangeKind.ADDED:
+            return f"{self.dto}: added `{self.after}`"
+        if self.kind is SnakeDtoChangeKind.REMOVED:
+            return f"{self.dto}: removed `{self.before}`"
+        return f"{self.dto}: retyped `{self.before}` -> `{self.after}`"
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeDtoSyncResult:
+    """The source as it should be, and every field that moved to get there."""
+
+    source: str
+    changes: tuple[SnakeDtoChange, ...]
+
+    @property
+    def changed(self) -> bool:
+        """Whether anything moved at all. `False` is what a second run has to say."""
+        return bool(self.changes)
+
+
+def sync_source(source: str, *, path: str = "<source>") -> SnakeDtoSyncResult:
+    """The file with its generated region brought in line with its specs, and what that took.
+
+    Nothing is written here — this returns text — so a refusal halfway through cannot leave a file
+    half rewritten. And nothing of the user's is ever EXECUTED: the specs are read out of the source
+    with `ast`, and the only thing imported is the models module they name.
+    """
+    specs = specs_in_source(source, path=path)
+    lines = source.splitlines(keepends=True)
+    start, stop = _locate(lines, path)
+    if not specs:
+        return SnakeDtoSyncResult(source=source, changes=())
+    shapes = resolve_all(specs)
+    _check_scope(shapes, source, path)
+    newline = _newline_of(lines)
+    rendered = _render(shapes, newline)
+    existing = lines[start:stop] if start is not None and stop is not None else []
+    changes = _diff(_parse_region(existing), shapes)
+    if existing == rendered:
+        return SnakeDtoSyncResult(source=source, changes=())
+    if start is None or stop is None:
+        # No region yet: it goes at the END of the file, always, so where it lands is a rule and
+        # not a judgement about somebody's layout.
+        head = (
+            lines
+            if not lines or lines[-1].endswith(("\n", "\r"))
+            else [*lines[:-1], lines[-1] + newline]
+        )
+        return SnakeDtoSyncResult(
+            source="".join([*head, newline, newline, *rendered]), changes=changes
+        )
+    return SnakeDtoSyncResult(
+        source="".join([*lines[:start], *rendered, *lines[stop:]]), changes=changes
+    )
+
+
+def sync_file(path: Path, *, write: bool) -> SnakeDtoSyncResult:
+    """Same over a file on disk. With `write=False` it reports and touches nothing.
+
+    Written only when something actually moved, so a clean run does not restamp the modification
+    time and set half the build tooling off.
+    """
+    result = sync_source(path.read_text(encoding="utf-8"), path=str(path))
+    if write and result.changed:
+        path.write_text(result.source, encoding="utf-8")
+    return result
+
+
+def _locate(lines: list[str], path: str) -> tuple[int | None, int | None]:
+    """Where the region starts and ends, as line indices, or `(None, None)` when there is none.
+
+    Every way of being malformed is an error rather than a repair: an unterminated region has no end
+    to write up to, and two regions have no rule saying which is the real one. Guessing either way
+    is how a generator eats the half of the file it did not understand.
+    """
+    starts = [index for index, line in enumerate(lines) if line.startswith(BEGIN)]
+    ends = [index for index, line in enumerate(lines) if line.startswith(END)]
+    if not starts and not ends:
+        return None, None
+    if len(starts) > 1 or len(ends) > 1:
+        raise SnakeDtoError(
+            f"{path} holds more than one generated region, and there is no rule saying which is the "
+            f"real one. Nothing was written: delete the extra `{BEGIN}` block."
+        )
+    if not starts:
+        raise SnakeDtoError(
+            f"{path} has a `{END}` with no beginning. Nothing was written."
+        )
+    if not ends:
+        raise SnakeDtoError(
+            f"{path} opens a generated region at line {starts[0] + 1} and never closes it with "
+            f"`{END}`. There is no end to write up to, so nothing was written."
+        )
+    if ends[0] < starts[0]:
+        raise SnakeDtoError(
+            f"{path} closes its generated region before it opens it. Nothing was written."
+        )
+    return starts[0], ends[0] + 1
+
+
+def _render(shapes: Sequence[SnakeDtoShape], newline: str) -> list[str]:
+    """The whole region as lines, markers included. Deterministic, which is where idempotence lives."""
+    out = [_HEADER + newline]
+    for index, shape in enumerate(shapes):
+        if index:
+            out.extend([newline, newline])
+        out.append(f"class {shape.name}(TypedDict):{newline}")
+        for field in shape.fields:
+            out.append(f"    {field.name}: {field.annotation}{newline}")
+        if not shape.fields:
+            # A class body cannot be empty, and a spec CAN legitimately select nothing.
+            out.append(f"    pass{newline}")
+    out.append(_FOOTER + newline)
+    return out
+
+
+def _parse_region(lines: list[str]) -> dict[str, dict[str, str]]:
+    """`{class: {field: annotation}}` for the region as it stands on disk.
+
+    Read with `ast` and not with a regular expression, because this is the generator's own output
+    and the shape of it is known exactly. Anything unparseable comes back empty, which reports every
+    field as added — loud, and correct: a region that is not what this tool writes IS out of date.
+    """
+    try:
+        tree = ast.parse("".join(line for line in lines if not line.startswith("#")))
+    except SyntaxError:
+        return {}
+    found: dict[str, dict[str, str]] = {}
+    for node in tree.body:
+        if not isinstance(node, ast.ClassDef):
+            continue
+        found[node.name] = {
+            statement.target.id: ast.unparse(statement.annotation)
+            for statement in node.body
+            if isinstance(statement, ast.AnnAssign)
+            and isinstance(statement.target, ast.Name)
+        }
+    return found
+
+
+def _diff(
+    before: dict[str, dict[str, str]], shapes: Sequence[SnakeDtoShape]
+) -> tuple[SnakeDtoChange, ...]:
+    """Every field that moved between the region on disk and the one about to be written.
+
+    A whole class appearing reports as its fields being added, and a class disappearing as its
+    fields being removed. One vocabulary instead of two: what a reader wants to know is which keys
+    the response gained or lost, and a class is only how they are grouped.
+    """
+    changes: list[SnakeDtoChange] = []
+    wanted = {shape.name: shape for shape in shapes}
+    for shape in shapes:
+        old = before.get(shape.name, {})
+        for field in shape.fields:
+            written = f"{field.name}: {field.annotation}"
+            if field.name not in old:
+                changes.append(
+                    SnakeDtoChange(
+                        dto=shape.name,
+                        field=field.name,
+                        kind=SnakeDtoChangeKind.ADDED,
+                        after=written,
+                    )
+                )
+            elif old[field.name] != field.annotation:
+                changes.append(
+                    SnakeDtoChange(
+                        dto=shape.name,
+                        field=field.name,
+                        kind=SnakeDtoChangeKind.RETYPED,
+                        before=f"{field.name}: {old[field.name]}",
+                        after=written,
+                    )
+                )
+        current = {field.name for field in shape.fields}
+        for name, annotation in old.items():
+            if name not in current:
+                changes.append(
+                    SnakeDtoChange(
+                        dto=shape.name,
+                        field=name,
+                        kind=SnakeDtoChangeKind.REMOVED,
+                        before=f"{name}: {annotation}",
+                    )
+                )
+    for name, old in before.items():
+        if name in wanted:
+            continue
+        for field_name, annotation in old.items():
+            changes.append(
+                SnakeDtoChange(
+                    dto=name,
+                    field=field_name,
+                    kind=SnakeDtoChangeKind.REMOVED,
+                    before=f"{field_name}: {annotation}",
+                )
+            )
+    return tuple(changes)
+
+
+def _check_scope(shapes: Sequence[SnakeDtoShape], source: str, path: str) -> None:
+    """Refuses anything whose name the file does not already have in scope, and writes no imports.
+
+    `TypedDict` is included, and it is the one people forget: the generator writes
+    `class X(TypedDict)` and cannot make that resolve on its own. Editing somebody's import block on
+    a guess is a much bigger claim on their file than filling a region they marked out; getting it
+    wrong means the file stops importing, so the generator would have broken the build to fix a
+    type. Saying which line to add costs the reader one line and cannot go wrong.
+    """
+    in_scope = _names_in_scope(source, path)
+    if "TypedDict" not in in_scope:
+        raise SnakeDtoError(
+            f"{path} does not have `TypedDict` in scope, and every generated class is written "
+            f"`class X(TypedDict)`. Add `from typing import TypedDict` yourself — or from "
+            f"`typing_extensions` if these shapes are read by pydantic or FastAPI on Python 3.11, "
+            f"where the one in `typing` does not carry what pydantic needs and it refuses. This "
+            f"command writes classes, never imports."
+        )
+    for shape in shapes:
+        for field in shape.fields:
+            if field.requires is None:
+                continue
+            if field.requires == FROM_SNAKEORM:
+                symbol = field.annotation.split(" ")[0]
+                needed, line = symbol, f"from snakeorm import {symbol}"
+            else:
+                needed = field.requires.split(".")[0]
+                line = f"import {field.requires}"
+            if needed not in in_scope:
+                raise SnakeDtoError(
+                    f"{shape.name} needs `{field.name}: {field.annotation}` and {path} does not "
+                    f"have `{needed}` in scope. Add `{line}` yourself and run this again: this "
+                    f"command writes classes, never imports."
+                )
+
+
+def _names_in_scope(source: str, path: str) -> set[str]:
+    """Every name the file's imports bind, wherever in the file they are written.
+
+    The whole tree, so an import parked under `if TYPE_CHECKING:` counts — which is exactly where a
+    name used only in annotations belongs, and where these specs live. Being generous here can only
+    let a class THROUGH; the checker reads the same file and has the last word.
+    """
+    bound: set[str] = set()
+    for node in ast.walk(ast.parse(source, filename=path)):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                bound.add(alias.asname or alias.name.split(".")[0])
+        elif isinstance(node, ast.ImportFrom):
+            for alias in node.names:
+                bound.add(alias.asname or alias.name)
+    return bound
+
+
+def _newline_of(lines: list[str]) -> str:
+    """The file's line ending, so what gets inserted matches what is already there."""
+    for line in lines:
+        if line.endswith("\r\n"):
+            return "\r\n"
+        if line.endswith("\n"):
+            return "\n"
+    return "\n"