snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/helpers/__init__.py

@@ -0,0 +1 @@
+"""Helpers: generic utility functions reused by 2+ domains. A neutral leaf, no cycles."""

snakeorm/helpers/annotations.py

@@ -0,0 +1,21 @@
+"""Utilities over type annotations, shared by two consumers that must not know about each other:
+the Model Compiler (which infers `nullable`) and `@snake_result` (the type to coerce an `X | None`
+with)."""
+
+from __future__ import annotations
+
+import types
+from typing import Any, Union, get_args, get_origin
+
+
+def unwrap_optional(annotation: Any) -> tuple[Any, bool]:
+    """If the type is `X | None`, returns `(X, True)`; otherwise `(type, False)`.
+
+    It recognises both syntaxes: `Optional[X]` / `Union[X, None]` and PEP 604's `X | None`.
+    """
+    if get_origin(annotation) in (Union, types.UnionType):
+        args = get_args(annotation)
+        non_none = tuple(arg for arg in args if arg is not type(None))
+        if len(non_none) != len(args):
+            return non_none[0], True
+    return annotation, False

snakeorm/helpers/inheritance.py

@@ -0,0 +1,41 @@
+"""Collecting descriptors along the MRO (inheritance from abstract models).
+
+A model inherits columns/relations from a base that is NOT a table; looking only at `vars(cls)`
+would lose whatever was inherited, so the compiler, the generated `__init__` and the linker walk the
+MRO with this helper.
+"""
+
+from __future__ import annotations
+
+from typing import TypeVar
+
+D = TypeVar("D")
+
+
+def collect_inherited(cls: type, descriptor_type: type[D]) -> dict[str, D]:
+    """Collects the descriptors of the given type across the whole MRO, from BASE to CHILD.
+
+    It walks `reversed(cls.__mro__)` so that two rules fall out: the parent's columns come BEFORE
+    the child's (DDL order), and if the child redefines an attribute its descriptor WINS (same key).
+    """
+    collected: dict[str, D] = {}
+    for klass in reversed(cls.__mro__):
+        for attr, value in vars(klass).items():
+            if isinstance(value, descriptor_type):
+                collected[attr] = value
+    return collected
+
+
+ABSTRACT_MARKER = "__snake_abstract__"
+"""The attribute `@snake_abstract` marks a base that contributes columns and is NOT a table with."""
+
+
+def is_abstract(cls: type) -> bool:
+    """Is this class marked as an abstract base?
+
+    It looks at the OWN dictionary (not `getattr`): the mark must not be inherited, or a
+    `@snake_model` child would still look abstract. It lives here (and not next to the decorator) to
+    avoid a cycle: `query.py` needs it and the decorators package drags in `view.py`, which imports
+    `snakeorm.query`.
+    """
+    return cls.__dict__.get(ABSTRACT_MARKER, False) is True

snakeorm/helpers/pyliteral.py

@@ -0,0 +1,52 @@
+"""Writing a string as a SAFE Python literal. One single place, two consumers (the migration
+renderer and the DB-first scaffolding), both generating `.py` that another process imports.
+
+A badly escaped string breaks the literal and whatever follows runs on import; in the scaffolding
+that is RCE, because the table/column names and comments come from the database.
+"""
+
+from __future__ import annotations
+
+_ESCAPES: dict[str, str] = {
+    "\\": "\\\\",
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+}
+"""Characters with a FIXED escape. The quote is not here because it depends on which one is used."""
+
+
+def _encode(value: str, quote: str) -> str:
+    """Escapes `value` as a string literal for the given quote (the way CPython/ruff do).
+
+    It escapes the quote, the control range and SURROGATES; everything else passes through. A lone
+    surrogate (`\\ud800`) is a valid `str` but is not encodable to UTF-8, so it is emitted as
+    `\\uXXXX` to make the escaper total over ANY `str` and keep the file writable.
+    """
+    out: list[str] = []
+    for char in value:
+        code = ord(char)
+        escaped = _ESCAPES.get(char)
+        if escaped is not None:
+            out.append(escaped)
+        elif char == quote:
+            out.append("\\" + quote)
+        elif code < 0x20 or code == 0x7F:
+            out.append(f"\\x{code:02x}")
+        elif 0xD800 <= code <= 0xDFFF:
+            # Lone surrogate: `\uXXXX`, the only way to fit it into an encodable literal.
+            out.append(f"\\u{code:04x}")
+        else:
+            out.append(char)
+    return f"{quote}{''.join(out)}{quote}"
+
+
+def str_lit(value: str) -> str:
+    """A string as a valid Python literal, double quotes unless single ones save escapes.
+
+    That is `ruff format`'s rule (the generated file passes `ruff check`); it ALWAYS returns a
+    closed, correct literal, whatever the content of `value`.
+    """
+    double = _encode(value, '"')
+    single = _encode(value, "'")
+    return single if single.count("\\") < double.count("\\") else double

snakeorm/helpers/pytype.py

@@ -0,0 +1,50 @@
+"""How a `python_type` off the compiled graph is SPELLED in generated Python source.
+
+Two generators write annotations from the same metadata — the DB-first scaffolder
+(`introspection/models.py`) and the DTO generator (`dto/`) — and they have to spell a type the same
+way or the mirror and the DTO of one column would disagree about what it is. That is why this lives
+here and not inside either of them: one question, one answer.
+"""
+
+from __future__ import annotations
+
+import snakeorm
+
+PARAMETERISED: dict[type, str] = {
+    dict: "dict[str, object]",
+    list: "list[object]",
+}
+"""How the generic builtins are SPELLED in generated code.
+
+`object` and not `Any`: the value really is unknown, and `object` says so while still making the
+checker ask for a narrowing before use. `Any` would say the opposite — that anything goes — which is
+what the bare form silently meant.
+"""
+
+FROM_SNAKEORM = "<snakeorm>"
+"""Marks "this symbol goes in the `from snakeorm import ...`", not in an `import` of its own."""
+
+
+def type_annotation(python_type: type) -> tuple[str, str | None]:
+    """The type's name exactly as it is written in the annotation, and its import if one is needed.
+
+    A type from the ORM ITSELF (`SnakeUtc`) is written bare and comes in through the
+    `from snakeorm import` the file already has: rendering it as `snakeorm.times.SnakeUtc` with its
+    own separate import would be exposing an internal path in a file people read, and tying it to
+    never moving again.
+    """
+    if python_type.__module__ == "builtins":
+        # `dict` and `list` are written PARAMETERISED. A bare `dict` is `dict[Any, Any]`, so every
+        # read through it comes back `Any` and the code this ORM generates would hand the user the
+        # one thing the project forbids — in a file it wrote itself. The decision lives here and not
+        # in the caller because this is the function that decides how a type is spelled.
+        parameterised = PARAMETERISED.get(python_type)
+        if parameterised is not None:
+            return parameterised, None
+        return python_type.__qualname__, None
+    if getattr(snakeorm, python_type.__qualname__, None) is python_type:
+        return python_type.__qualname__, FROM_SNAKEORM
+    return (
+        f"{python_type.__module__}.{python_type.__qualname__}",
+        python_type.__module__,
+    )

snakeorm/introspection/__init__.py

@@ -0,0 +1,13 @@
+"""Introspection: how a database's schema is READ (the third axis, alongside `dialects` and `drivers`).
+
+It returns the SAME graph as the Model Compiler: scaffolding and drift detection compare with no intermediate format.
+"""
+
+from snakeorm.introspection.mysql import MySQLIntrospector as MySQLIntrospector
+from snakeorm.introspection.base import SnakeIntrospector as SnakeIntrospector
+from snakeorm.introspection.drift import drift as drift
+from snakeorm.introspection.models import SnakeMirrorNames as SnakeMirrorNames
+from snakeorm.introspection.models import render_models as render_models
+from snakeorm.introspection.models import unrepresentable as unrepresentable
+from snakeorm.introspection.postgres import PostgresIntrospector as PostgresIntrospector
+from snakeorm.introspection.sqlite import SQLiteIntrospector as SQLiteIntrospector

snakeorm/introspection/base.py

@@ -0,0 +1,30 @@
+"""The INTROSPECTOR Protocol: how a database's schema is READ (the third axis, alongside Dialect and Driver).
+
+It returns the SAME graph (`SnakeTableInfo`) as the Model Compiler: scaffolding and the drift `check` compare with no translator. It is NOT bijective: `TEXT`/`VARCHAR(50)`/`CHAR(10)` all come back as `str`, so the round trip does not reproduce the original.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from snakeorm.core.placement import DEFAULT_SCHEMA
+from snakeorm.metadata import SnakeTableInfo
+
+
+@runtime_checkable
+class SnakeIntrospector(Protocol):
+    """Reads a database's REAL schema and returns it as a metadata graph."""
+
+    def tables(self, schema: str = DEFAULT_SCHEMA) -> list[SnakeTableInfo]:
+        """Every table in the schema with its columns, PK, uniqueness, indexes and comments.
+
+        The FKs come resolved in each `SnakeTableInfo` pointing at the NAME of the target table; whoever generates models translates them into class names.
+        """
+        ...
+
+    def unsupported(self, schema: str = DEFAULT_SCHEMA) -> list[str]:
+        """Objects the ORM does NOT know how to represent (triggers, exotic types, expression indexes), described so it can WARN.
+
+        Dropping them silently would make people believe the generated model covers the whole database.
+        """
+        ...

snakeorm/introspection/drift.py

@@ -0,0 +1,78 @@
+"""DRIFT detection: what the difference is between what the code says and what is in the database."""
+
+from __future__ import annotations
+
+from snakeorm.core.exceptions import SnakeDialectError
+from snakeorm.dialects import SnakeDialect
+from snakeorm.metadata import SnakeColumnInfo, SnakeTableInfo
+
+
+def drift(
+    code: list[SnakeTableInfo], database: list[SnakeTableInfo], dialect: SnakeDialect
+) -> list[str]:
+    """Differences between the compiled metadata and the REAL schema, as text (code vs database, not vs history like `makemigrations --check`).
+
+    It only compares what introspection reads reliably (existence of tables/columns, column type, nullability): defaults and constraints would give false positives that turn the tool into noise. Drift is about what YOU DECLARE: a table the ORM does not know about is not drift, it is somebody else's.
+
+    The `dialect` is not decoration and it is not optional. Comparing PYTHON types across this
+    boundary compares something only one side has: a `date` on SQLite is written as `TEXT`, and
+    reading `TEXT` back can only ever answer `str`. Both sides are right and they never match, so
+    drift used to report three differences against a database the ORM had just built out of the
+    very model it was comparing — noise from the one tool whose silence is the whole product.
+
+    The SQL type is what both sides genuinely share, so that is what is compared.
+    """
+    report: list[str] = []
+    in_code = {table.name: table for table in code}
+    in_database = {table.name: table for table in database}
+
+    for name in sorted(set(in_code) - set(in_database)):
+        report.append(f"table '{name}': is in the code and NOT in the database")
+
+    for name in sorted(set(in_code) & set(in_database)):
+        report.extend(_column_drift(name, in_code[name], in_database[name], dialect))
+    return report
+
+
+def _sql_type(column: SnakeColumnInfo, dialect: SnakeDialect) -> str:
+    """The SQL type this engine writes for the column, or the dialect's refusal to write one.
+
+    The STORAGE type feeds it, not the declared one: a `StrEnum` is stored as TEXT, so going
+    through `python_type` would flag every enum column as permanent drift.
+
+    A refusal is returned as text rather than raised: drift is a diagnostic, and a model this
+    engine cannot represent is exactly the kind of thing it exists to tell you about — not a
+    reason for the report to blow up half-written.
+    """
+    try:
+        return dialect.map_type(column.storage_type, params=column.type_params)
+    except SnakeDialectError as refusal:
+        return f"<not representable: {refusal}>"
+
+
+def _column_drift(
+    table: str, code: SnakeTableInfo, database: SnakeTableInfo, dialect: SnakeDialect
+) -> list[str]:
+    """Column differences for a table present on both sides."""
+    report: list[str] = []
+    in_code = {column.name: column for column in code.columns}
+    in_database = {column.name: column for column in database.columns}
+
+    for name in sorted(set(in_code) - set(in_database)):
+        report.append(f"{table}.{name}: is in the code and NOT in the database")
+    for name in sorted(set(in_database) - set(in_code)):
+        report.append(f"{table}.{name}: is in the database and NOT in the code")
+
+    for name in sorted(set(in_code) & set(in_database)):
+        expected, actual = in_code[name], in_database[name]
+        written, found = _sql_type(expected, dialect), _sql_type(actual, dialect)
+        if written != found:
+            report.append(
+                f"{table}.{name}: the code stores {written} and the database has {found}"
+            )
+        if expected.nullable != actual.nullable:
+            state = "accepts NULL" if actual.nullable else "does NOT accept NULL"
+            report.append(
+                f"{table}.{name}: the database {state} and the code says the opposite"
+            )
+    return report