snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/introspection/models.py

@@ -0,0 +1,633 @@
+"""Generation of model CODE from an introspected graph (`scaffold`)."""
+
+from __future__ import annotations
+
+import keyword
+import os.path
+import re
+from dataclasses import dataclass, replace
+from collections.abc import Sequence
+
+from datetime import datetime
+from decimal import Decimal
+
+from snakeorm.metadata import (
+    SnakeColumnInfo,
+    SnakeIndexInfo,
+    SnakeIntSize,
+    SnakeJsonStorage,
+    SnakePrimaryKeyInfo,
+    SnakeRelationshipInfo,
+    SnakeRelationshipKind,
+    SnakeTableInfo,
+)
+from snakeorm.core.placement import DEFAULT_SCHEMA
+from snakeorm.helpers.pyliteral import str_lit
+from snakeorm.helpers.pytype import FROM_SNAKEORM, type_annotation
+
+_HEADER = '''"""Models generated by `snakeorm scaffold`. DO NOT EDIT BY HAND.
+
+This file TRANSLATES a live database into models. Point the scaffolder at any schema — one you own,
+one that belongs to another repository, one a serverless function has to talk to — and what comes
+out queries through the same typed API as a hand-written model, under Django, FastAPI or Flask, or
+under plain Python with no framework at all.
+
+It is a MIRROR, and `scaffold update` REGENERATES it whole: anything you write here is lost. Your
+own code goes in another file.
+
+There is no in-place adoption. Swapping `@snake_db_first` for `@snake_model` does NOT hand the
+table to migrations — the history has never seen it, so the autogenerated `CreateTable` meets the
+table that already exists and dies with `DuplicateTable`.
+
+And a mirror carries what the DATABASE holds, which is a lossy projection of code. Signals,
+`default_factory`, enum classes, methods, docstrings and domain constants live in a `.py`, and no
+row of the catalogue mentions them: they are not here, and they cannot be.
+"""
+
+from __future__ import annotations
+'''
+
+# `snakeorm` symbols the generated file ALWAYS imports. The knobs (SnakeIntSize, SnakeJsonStorage)
+# are only added when some column uses them, so as not to leave dead imports behind.
+_SNAKE_BASE = {"SnakeColumn", "SnakeModel", "snake_column", "snake_db_first"}
+
+
+def _mirrors(name: str) -> bool:
+    """Whether this database name can be COPIED into Python as it stands.
+
+    ASCII, a valid identifier, and not a keyword. Nothing else is asked and nothing is transformed:
+    the name that comes back is the name that went in.
+
+    ASCII on purpose, even though Python 3 accepts `商品` as an identifier. A class nobody can type
+    on the keyboard they read the traceback with is a mirror nobody can use — and where the line
+    falls is a judgement, so it is written here rather than left to the shape of a regex.
+    """
+    return name.isascii() and name.isidentifier() and not keyword.iskeyword(name)
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeMirrorNames:
+    """How a table becomes a class name. Both switches default ON."""
+
+    capwords: bool = True
+    """Split on `_` and capitalise each part: `project_requests` → `ProjectRequests`.
+
+    MECHANICAL and that is why it is the default: it knows no language and loses nothing. What it
+    deliberately does NOT do is remove a trailing `s` — that is a guess about English, and it turned
+    `status` into `Statu`, `analysis` into `Analysi` and `direcciones` into `Direccione`.
+
+    Off, the underscores stay and only the first letter is raised: `Project_requests`. It is the
+    spelling somebody grepping between the model and the table asks for. Neither setting ever LOWERS
+    a letter, so `ProductReQuests` keeps its capitals both ways.
+    """
+    include_schema: bool = True
+    """Prefix the schema, `public` INCLUDED: `public.orders` → `PublicOrders`.
+
+    No carve-out, and the missing exception is the feature. Two schemas holding a table of the same
+    name is ordinary —`sales.orders` beside `hr.orders`— and without the prefix they are ONE class:
+    the mirror keeps whichever came last and says nothing. Prefixing only when the schema is not
+    `public` would be a rule with a special case, and a special case is what somebody falls through.
+
+    Off for a database with one schema, where the prefix is noise. `unrepresentable` then reports
+    the collisions the prefix was preventing.
+    """
+    strip_id_suffix: bool = True
+    """Name a to-one after its LOCAL COLUMN with a trailing `_id` removed: `brand_id` → `brand`.
+
+    It is the convention the hand-written models keep, and the reason the name does not come from
+    the target TABLE: the introspector's own `name` field holds `brands`, which would give
+    `cars.brands` where a person writes `cars.brand`.
+
+    A composite key takes the prefix its columns SHARE —`stock_warehouse_id` + `stock_sku_id` → 
+    `stock`— because naming it after either column would be a coin toss.
+
+    Off, the relationship keeps the column's whole name and collides with the column itself. That
+    is not a bug in the switch: it is what a database whose FK columns carry no suffix does anyway,
+    and `unrepresentable` reports it either way rather than letting one attribute replace the other.
+    """
+
+
+def _relationship_name(
+    relationship: SnakeRelationshipInfo, names: SnakeMirrorNames
+) -> str:
+    """What to call a to-one: its local column(s) without the `_id`, or their shared prefix."""
+    locals_ = [pair[0] for pair in relationship.foreign_key.pairs]
+    if not names.strip_id_suffix:
+        return locals_[0]
+    stripped = [
+        column[: -len("_id")] if column.endswith("_id") else column
+        for column in locals_
+    ]
+    if len(stripped) == 1:
+        return stripped[0]
+    shared = os.path.commonprefix(stripped).rstrip("_")
+    return shared or stripped[0]
+
+
+@dataclass(frozen=True, slots=True)
+class _Collection:
+    """One `snake_to_many` on the parent: its attribute, the child class, the child's to-one."""
+
+    attribute: str
+    child_class: str
+    fk_name: str
+
+
+def _collections(
+    tables: Sequence[SnakeTableInfo], names: SnakeMirrorNames
+) -> tuple[dict[tuple[str, str], list[_Collection]], list[str]]:
+    """The inverse of every to-one that gets written, grouped by the table it hangs off.
+
+    Computed BEFORE anything is emitted because a collection lives on the PARENT while the key
+    lives on the CHILD, and the two are rendered in whatever order the table names sort in.
+
+    The attribute is the CHILD TABLE's name as it stands — see this module's own naming note. Its
+    only failure is a collision, and a collision is decidable by looking at one class body: it
+    can hit a column, a to-one, or another collection when two keys of the same child point at
+    the same parent. All three are reported, and none of the three is emitted.
+    """
+    present = {(table.schema, table.name) for table in tables}
+    rendered = [table for table in tables if _mirrors_as_class(table, names)]
+    proposed: dict[tuple[str, str], dict[str, list[_Collection]]] = {}
+    for table in rendered:
+        for attribute, relationship in _emitted_to_ones(table, names, present):
+            parent = (table.schema, relationship.foreign_key.target)
+            proposed.setdefault(parent, {}).setdefault(table.name, []).append(
+                _Collection(
+                    attribute=table.name,
+                    child_class=_class_name(table, names),
+                    fk_name=attribute,
+                )
+            )
+    by_parent: dict[tuple[str, str], list[_Collection]] = {}
+    complaints: list[str] = []
+    for table in rendered:
+        for child_name, candidates in proposed.get(
+            (table.schema, table.name), {}
+        ).items():
+            if len(candidates) > 1:
+                complaints.append(
+                    f"table {child_name!r} has two foreign keys pointing at "
+                    f"{table.name!r} ({', '.join(sorted(item.fk_name for item in candidates))}), "
+                    f"so both collections would be called {child_name!r}: nothing in the "
+                    f"database breaks the tie, and both are left out"
+                )
+                continue
+            collection = candidates[0]
+            taken = {_attribute(column.name) for column in table.columns} | {
+                attribute for attribute, _ in _emitted_to_ones(table, names, present)
+            }
+            if collection.attribute in taken:
+                complaints.append(
+                    f"the inverse of {child_name!r} on table {table.name!r} would be called "
+                    f"{collection.attribute!r}, which is already a column or a relationship: "
+                    f"the collection is left out"
+                )
+                continue
+            by_parent.setdefault((table.schema, table.name), []).append(collection)
+    return by_parent, complaints
+
+
+# What the generated file already has in scope. A mirror that derives one of these SHADOWS it, and
+# that is the failure of this family that compiles: the file imports clean, `snake_link()` runs, and
+# every class declared after the mirror inherits from the mirror instead of from the base.
+_TAKEN_BY_THE_FILE = frozenset(
+    {"SnakeModel", "SnakeColumn", "SnakeToOne", "SnakeToMany", "snakeorm"}
+)
+
+
+def _mirrors_as_class(table: SnakeTableInfo, names: SnakeMirrorNames) -> bool:
+    """Whether this table becomes a class at all: its name, its schema, and the name it DERIVES.
+
+    The third one was missing, and it is the one that bites. `_class_name` capitalises AFTER this
+    check ran, so `none` passed —`none` is not a keyword— and came out as `None`, and the generated
+    file did not parse while `unrepresentable()` reported nothing. That contradicts its own
+    docstring, whose entire reason to exist is that the file must not fail to parse in silence.
+
+    Measured, the family fails three ways: `none`/`true`/`false` derive keywords; `_` derives the
+    empty string and writes `class (SnakeModel):`; and `snake_model` derives `SnakeModel`, which
+    PARSES and shadows the import. That last one is the dangerous one, and the only one a
+    "does it compile?" check cannot see.
+
+    It is the same shape as `_to_one_refusal` below — validating what gets WRITTEN, not what came
+    in — which is the neighbour that had already solved this pattern.
+    """
+    if not _mirrors(table.name):
+        return False
+    if names.include_schema and not _mirrors(table.schema):
+        return False
+    derived = _class_name(table, names)
+    return _mirrors(derived) and derived not in _TAKEN_BY_THE_FILE
+
+
+def _to_one_refusal(
+    table: SnakeTableInfo,
+    relationship: SnakeRelationshipInfo,
+    names: SnakeMirrorNames,
+    present: set[tuple[str, str]],
+) -> str | None:
+    """WHY this to-one is not written, or `None` when it is. The single definition of that.
+
+    It used to be spelled four times — three complaints here and three `continue`s in the
+    renderer — and the inverse side turns that duplication from untidy into dangerous: a
+    `snake_to_many` naming a to-one the renderer skipped points at a relation nobody declared,
+    and `snake_link()` dies on import.
+    """
+    attribute = _relationship_name(relationship, names)
+    locals_ = [pair[0] for pair in relationship.foreign_key.pairs]
+    # A to-one whose name is already a column's would REPLACE it in the class body. Skipping it
+    # quietly is what the old `__` did with columns, and the mirror came back short.
+    if attribute in {_attribute(column.name) for column in table.columns}:
+        return (
+            f"foreign key of table {table.name!r} on {locals_} would be called "
+            f"{attribute!r}, which is already a column: the relationship is left out"
+        )
+    # A to-one whose TARGET is not in the batch would name a class nobody declares. The generator
+    # resolves nothing — it recomputes the target's name with the same rule — so there is no
+    # lookup to fail; the reference is simply written and the file does not import. `--schema` is
+    # the ordinary way in: one schema referencing another.
+    if (table.schema, relationship.foreign_key.target) not in present:
+        return (
+            f"foreign key of table {table.name!r} points at "
+            f"{relationship.foreign_key.target!r}, which is not in what is being generated "
+            f"(another schema, or filtered out): the relationship is left out"
+        )
+    # The name is DERIVED, so it can come out invalid where the column was fine: `class_id` is a
+    # perfectly good column and `class` is a keyword. Found by running the generator against a
+    # real database, which is the only place that column existed.
+    if not _mirrors(attribute):
+        return (
+            f"foreign key of table {table.name!r} on {locals_} would be called "
+            f"{attribute!r}, which Python will not take as an attribute name: the "
+            f"relationship is left out"
+        )
+    return None
+
+
+def _emitted_to_ones(
+    table: SnakeTableInfo, names: SnakeMirrorNames, present: set[tuple[str, str]]
+) -> list[tuple[str, SnakeRelationshipInfo]]:
+    """The to-ones the mirror actually writes, each paired with the attribute name it gets."""
+    return [
+        (_relationship_name(relationship, names), relationship)
+        for relationship in table.relationships
+        if relationship.kind is SnakeRelationshipKind.TO_ONE
+        and _to_one_refusal(table, relationship, names, present) is None
+    ]
+
+
+def _index_args(
+    table: SnakeTableInfo, index: SnakeIndexInfo, snake_symbols: set[str]
+) -> str:
+    """The `SnakeIndex(...)` arguments: its columns, and only the knobs that are not the default.
+
+    The NAME is emitted only when the database's differs from the one `resolved_name` would invent,
+    which is the same rule the schema follows: repeating the default is noise, and dropping a name
+    somebody chose makes a drift report demand an index that is already there.
+    """
+    parts = [_attribute(name) for name in index.columns]
+    if index.unique:
+        parts.append("unique=True")
+    if index.name is not None and index.name != replace(index, name=None).resolved_name(
+        table.name
+    ):
+        parts.append(f"name={str_lit(index.name)}")
+    if index.method is not None:
+        snake_symbols.add("SnakeIndexMethod")
+        parts.append(f"method=SnakeIndexMethod.{index.method.name}")
+    return ", ".join(parts)
+
+
+def _to_one_is_optional(
+    table: SnakeTableInfo, relationship: SnakeRelationshipInfo
+) -> bool:
+    """Whether the to-one can come back empty, which is the LINKER's rule and not a preference.
+
+    `_guard_nullability_parity` demands the relationship say the same thing as its key about
+    possibly not existing, in both directions, and one nullable member of a composite key is
+    enough. The generator never looked, so a mirror of any schema with a nullable FK did not even
+    import — and only `snake_link()` says so, which is why comparing strings never caught it.
+    """
+    by_name = {column.name: column for column in table.columns}
+    return any(
+        by_name[pair[0]].nullable
+        for pair in relationship.foreign_key.pairs
+        if pair[0] in by_name
+    )
+
+
+def _class_name(table: SnakeTableInfo, names: SnakeMirrorNames) -> str:
+    """The class name of a mirror, per the two switches above.
+
+    Reversibility does not ride on this. `@snake_db_first(table="...")` sits on the line above and
+    carries the SQL name exactly, so the class is free to read like Python.
+    """
+    raw = f"{table.schema}_{table.name}" if names.include_schema else table.name
+    if not names.capwords:
+        return raw[:1].upper() + raw[1:]
+    return "".join(part[:1].upper() + part[1:] for part in raw.split("_") if part)
+
+
+def unrepresentable(
+    tables: Sequence[SnakeTableInfo], names: SnakeMirrorNames | None = None
+) -> list[str]:
+    """What the scaffold cannot NAME, described so somebody can decide about it.
+
+    Same channel the introspector's own warnings travel on, and for the same reason: what the model
+    does not cover is said out loud, because silence reads as "all covered".
+
+    Measured before this existed, guessing failed three ways — a table named `商品` produced
+    `class (SnakeModel):` and the file did not parse; `Ürünler` became `RNler`, nonsense that
+    compiles; and a column named `商品` became `__`, so TWO of them collided into one attribute and
+    the rows came back short with nothing said. The last is the worst precisely because it runs.
+    """
+    names = names or SnakeMirrorNames()
+    complaints: list[str] = []
+    by_class: dict[str, list[str]] = {}
+    present = {(table.schema, table.name) for table in tables}
+    for table in tables:
+        if not _mirrors_as_class(table, names):
+            # The complaint distinguishes the two ways this fails, because the reader's next move
+            # differs: an unwritable name is obvious once pointed at, but `snake_model` derives
+            # `SnakeModel`, which looks perfectly fine — and is only wrong because the generated
+            # file already imports that name.
+            derived = _class_name(table, names)
+            reason = (
+                f"it would be written {derived!r}, which is what the generated file imports, "
+                f"so the mirror would shadow it and every class after it would inherit from "
+                f"the mirror"
+                if derived in _TAKEN_BY_THE_FILE
+                else "cannot be a Python class name as it stands (ASCII identifier, not a "
+                "keyword), before or after the capitalisation"
+            )
+            complaints.append(
+                f"table {table.name!r}: {reason}. Rename it, or mirror it by hand"
+            )
+            continue
+        by_class.setdefault(_class_name(table, names), []).append(
+            f"{table.schema}.{table.name}" if names.include_schema else table.name
+        )
+        complaints += [
+            f"column {column.name!r} of table {table.name!r}: cannot be a Python "
+            f"attribute name as it stands (ASCII identifier, not a keyword)"
+            for column in table.columns
+            if not _mirrors(column.name)
+        ]
+        complaints += [
+            refusal
+            for relationship in table.relationships
+            if relationship.kind is SnakeRelationshipKind.TO_ONE
+            and (refusal := _to_one_refusal(table, relationship, names, present))
+            is not None
+        ]
+        # A PARTIAL index is skipped, and skipping it QUIETLY is the sin this whole function
+        # exists to prevent: the reader would diff the mirror and be told to create an index that
+        # is already there. Its `where` is a condition, and rendering one back to source is an
+        # expression printer the generator does not have.
+        complaints += [
+            f"index {index.resolved_name(table.name)!r} of table {table.name!r} is PARTIAL "
+            f"(it has a WHERE): the mirror cannot write its condition back, so the index is "
+            f"left out"
+            for index in table.indexes
+            if index.where is not None
+        ]
+    # CapWords can COLLIDE where a literal copy could not: `product_requests` and `productRequests`
+    # both land on `ProductRequests`, and the second class would silently replace the first in the
+    # generated file. That is the price of reading like Python, and it is paid by saying so.
+    complaints += [
+        f"tables {sorted(sources)} all map to class {klass!r}: the mirror would keep only one of them"
+        for klass, sources in by_class.items()
+        if len(sources) > 1
+    ]
+    # The inverse side comes last because it is computed over the whole batch, not per table: a
+    # collection lives on the parent and the key that creates it on the child.
+    complaints += _collections(tables, names)[1]
+    return complaints
+
+
+def _attribute(name: str) -> str:
+    """A valid Python attribute name for a column."""
+    cleaned = re.sub(r"[^0-9a-zA-Z_]", "_", name)
+    return (
+        f"col_{cleaned}"
+        if not cleaned.isidentifier() or cleaned[0].isdigit()
+        else cleaned
+    )
+
+
+# How a type is SPELLED lives in `helpers/pytype` (`type_annotation`, `FROM_SNAKEORM`), shared with
+# the DTO generator: two generators writing annotations off the same metadata have to agree on the
+# spelling, and a second copy here would be the second answer to that one question.
+
+
+def render_models(
+    tables: list[SnakeTableInfo],
+    unsupported: list[str] | None = None,
+    names: SnakeMirrorNames | None = None,
+) -> str:
+    """Renders the introspected tables as `@snake_db_first` classes.
+
+    Whatever is NOT representable is written as a WARNING inside the file itself: whoever reads it later has to see what it does NOT cover.
+    """
+    imports: set[str] = set()
+    snake_symbols: set[str] = set(_SNAKE_BASE)
+    bodies: list[str] = []
+    names = names or SnakeMirrorNames()
+    refused = unrepresentable(tables, names)
+    linked = False
+    present = {(table.schema, table.name) for table in tables}
+    collections, _ = _collections(tables, names)
+    for table in sorted(tables, key=lambda item: item.name):
+        if not _mirrors_as_class(table, names):
+            continue
+        # `str_lit` on ALL text coming from the database: without it, quotes/newlines would escape
+        # the literal and become code executed when the generated `models.py` is imported (RCE for
+        # whoever controls the schema).
+        # The schema is emitted only when it is NOT the decorator's default, which is the same
+        # declaration with less noise. Leaving it out ALTOGETHER was the worst bug this generator
+        # had: `sales.orders` mirrored as `SalesOrders` over `table="orders"`, reading `public`.
+        placement = (
+            f", schema={str_lit(table.schema)}"
+            if table.schema != DEFAULT_SCHEMA
+            else ""
+        )
+        lines = [
+            f"@snake_db_first(table={str_lit(table.name)}{placement})",
+            f"class {_class_name(table, names)}(SnakeModel):",
+            f"    {str_lit(f'Mirror of table `{table.name}`.')}",
+            "",
+        ]
+        if table.db_comment is not None:
+            # The compiler reads `SnakeComment` off the class body, so no decorator parameter is
+            # needed. Often the only thing that says what a table inherited as `t_cst_rel_04` is
+            # FOR, and all three introspectors were already reading it.
+            lines.append(f"    SnakeComment = {str_lit(table.db_comment)}")
+            lines.append("")
+        for column in table.columns:
+            if not _mirrors(column.name):
+                continue
+            annotation, module = type_annotation(column.python_type)
+            if module == FROM_SNAKEORM:
+                snake_symbols.add(annotation)
+                module = None
+            if module is not None:
+                imports.add(f"import {module}")
+            optional = " | None" if column.nullable else ""
+            declarator = _declarator_for(table, column, snake_symbols)
+            lines.append(
+                f"    {_attribute(column.name)}: SnakeColumn[{annotation}{optional}] = "
+                f"{declarator}({_column_args(table, column.name, declarator, snake_symbols)})"
+            )
+        for attribute, relationship in _emitted_to_ones(table, names, present):
+            target = _class_name(
+                SnakeTableInfo(
+                    name=relationship.foreign_key.target,
+                    schema=table.schema,
+                    columns=(),
+                    primary_key=SnakePrimaryKeyInfo(columns=()),
+                ),
+                names,
+            )
+            columns = ", ".join(
+                _attribute(pair[0]) for pair in relationship.foreign_key.pairs
+            )
+            snake_symbols |= {"SnakeToOne", "snake_to_one"}
+            linked = True
+            optional = " | None" if _to_one_is_optional(table, relationship) else ""
+            lines.append(
+                f"    {attribute}: SnakeToOne[{target}{optional}] = snake_to_one({columns})"
+            )
+        for collection in collections.get((table.schema, table.name), []):
+            snake_symbols |= {"SnakeToMany", "snake_to_many"}
+            linked = True
+            lines.append(
+                f"    {collection.attribute}: SnakeToMany[{collection.child_class}] = "
+                f"snake_to_many({str_lit(collection.fk_name)})"
+            )
+        # LAST in the body, because `SnakeIndex(brand_id)` refers to the descriptors declared
+        # above: the names resolve at compile time, once `__set_name__` has run.
+        emitted = [index for index in table.indexes if index.where is None]
+        if emitted:
+            snake_symbols.add("SnakeIndex")
+            lines.append("")
+            lines.append("    SnakeIndexes = [")
+            lines += [
+                f"        SnakeIndex({_index_args(table, index, snake_symbols)}),"
+                for index in emitted
+            ]
+            lines.append("    ]")
+        bodies.append("\n".join(lines))
+
+    if linked:
+        # Added BEFORE the import line is built, which is the whole of a bug this had: appending it
+        # after meant `snake_link()` was emitted and never imported. The file PARSED — so `compile()`
+        # was happy — and raised `NameError` the moment anybody ran it.
+        snake_symbols.add("snake_link")
+    parts = [_HEADER]
+    parts.append(f"from snakeorm import {', '.join(sorted(snake_symbols))}")
+    if imports:
+        parts.append("\n".join(sorted(imports)) + "\n")
+    unsupported = [*(unsupported or []), *refused]
+    if unsupported:
+        # The warnings carry RAW names from the database: a `\n` would break the `#` comment and the
+        # next line would fall to module level (RCE on import). Collapsing the newlines is enough: a
+        # one-line comment cannot overflow.
+        warnings_ = "\n".join(
+            f"#   - {item.replace(chr(13), ' ').replace(chr(10), ' ')}"
+            for item in unsupported
+        )
+        parts.append(
+            "# INTROSPECTION WARNINGS: this EXISTS in the database and the model does NOT\n"
+            "# represent it. It is still there and still acting; it just cannot be seen from here.\n"
+            + warnings_
+            + "\n"
+        )
+    parts.extend(bodies)
+    if linked:
+        # Two-phase on purpose: the classes declare, `snake_link()` resolves. A generated file that
+        # skipped it would import cleanly and raise `SnakeUnlinkedRelationship` at the first query.
+        parts.append("snake_link()\n")
+    return "\n\n".join(parts).rstrip() + "\n"
+
+
+def _declarator_for(
+    table: SnakeTableInfo, column: SnakeColumnInfo, snake_symbols: set[str]
+) -> str:
+    """The declarator that matches the column's family.
+
+    Every family with parameters has its own (`snake_int(size=)`, `snake_str(max_length=)`...), and
+    `snake_column()` no longer accepts ANY of them: emitting it for everything produced a file that
+    does not even import. A date moreover has TWO, because `TIMESTAMP` and `TIMESTAMPTZ` are
+    different types and the mirror must reflect which one it is.
+    """
+    kind = column.python_type
+    if column.autoincrement:
+        # The database GENERATES the value, and `snake_auto` is the declarator that says so: it
+        # keeps the key out of `__init__`. Mirroring it as `snake_int(primary_key=True)` put the
+        # id back in the constructor, so the mirror asked the caller for a value only the sequence
+        # can produce — and the checker approved the call.
+        snake_symbols.add("snake_auto")
+        return "snake_auto"
+    if isinstance(kind, type) and issubclass(kind, datetime):
+        name = "snake_datetimetz" if column.with_timezone else "snake_datetime"
+        snake_symbols.add(name)
+        return name
+    if kind is Decimal and column.precision is None:
+        # An UNCONSTRAINED `NUMERIC` is legal on Postgres, and `snake_decimal()` demands
+        # `precision`: emitting it here produced a call missing a mandatory argument, and the file
+        # did not even import. `snake_column()` on a Decimal gives the bare NUMERIC, which is
+        # exactly what is in the database.
+        snake_symbols.add("snake_column")
+        return "snake_column"
+    name = {
+        int: "snake_int",
+        str: "snake_str",
+        Decimal: "snake_decimal",
+        dict: "snake_json",
+    }.get(kind, "snake_column")
+    snake_symbols.add(name)
+    return name
+
+
+def _column_args(
+    table: SnakeTableInfo, column_name: str, declarator: str, snake_symbols: set[str]
+) -> str:
+    """The declarator's arguments with ALL the knobs of the introspected column.
+
+    Emitting only pk/unique/db_comment widened things silently (`VARCHAR(20)`→`TEXT`, `INTEGER`→`BIGINT`): the mirror must reflect the real width, length, precision and default.
+
+    `snake_auto` takes a DIFFERENT set, which is why the declarator has to be passed in: it is the
+    primary key by construction, so it refuses `primary_key=`, and it spells the width `int_size=`
+    rather than `size=`. Emitting the common set produced a call the compiler rejects.
+    """
+    column = table.get_column(column_name)
+    assert column is not None
+    args: list[str] = []
+    if declarator == "snake_auto":
+        if column.int_size is not SnakeIntSize.BIGINT:
+            snake_symbols.add("SnakeIntSize")
+            args.append(f"int_size=SnakeIntSize.{column.int_size.name}")
+        if column.db_comment is not None:
+            args.append(f"db_comment={str_lit(column.db_comment)}")
+        return ", ".join(args)
+    if any(pk.name == column_name for pk in table.primary_key.columns):
+        args.append("primary_key=True")
+    if column.unique:
+        args.append("unique=True")
+    if column.max_length is not None:
+        args.append(f"max_length={column.max_length}")
+    if column.precision is not None:
+        args.append(f"precision={column.precision}")
+    if column.scale is not None:
+        args.append(f"scale={column.scale}")
+    if column.int_size is not SnakeIntSize.BIGINT:
+        snake_symbols.add("SnakeIntSize")
+        args.append(f"size=SnakeIntSize.{column.int_size.name}")
+    if column.json_storage is not SnakeJsonStorage.JSONB:
+        snake_symbols.add("SnakeJsonStorage")
+        args.append(f"storage=SnakeJsonStorage.{column.json_storage.name}")
+    if column.server_default_sql is not None:
+        args.append(f"server_default_sql={str_lit(column.server_default_sql)}")
+    if column.db_comment is not None:
+        args.append(f"db_comment={str_lit(column.db_comment)}")
+    return ", ".join(args)