hare-orm 0.9.0__py3-none-any.whl

hare/inspectdb/generation/many_to_many_tables.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+from hare.fields.relations.fields.many_to_many_field import ManyToManyField
+from hare.inspectdb.generation.model_naming import ModelNaming
+
+if TYPE_CHECKING:
+    from hare.fields.field import Field
+    from hare.inspectdb.introspection.table_info import TableInfo
+
+
+class ManyToManyTables:
+    """The through tables of many-to-many relations among the tables of one inspectdb run - each
+    rebuilt as a ``ManyToManyField`` on the model of its first side, ``through=`` naming the table, so
+    the generated module drifts clean; the table itself gets a note instead of a class."""
+
+    def __init__(self, table_infos: list[TableInfo], class_references: dict[str, str]) -> None:
+        """
+        Args:
+            table_infos: The tables of the run.
+            class_references: The ``"<app>.<Class>"`` of each table's model, by table name.
+        """
+        #: The many-to-many fields each table's model gets, by table name: preferred attribute name
+        #: and field.
+        self.fields_by_table: dict[str, list[tuple[str, Field[Any]]]] = {}
+        #: The note of each through table rebuilt so, by table name.
+        self.notes_by_table: dict[str, str] = {}
+        tables_by_name = {table_info.name: table_info for table_info in table_infos}
+        for table_info in table_infos:
+            sides = self.get_sides(table_info, tables_by_name)
+            if sides is None:
+                continue
+            (owner_column, owner_table), (other_column, other_table) = sides
+            # hare names a through table <owner table>_<field> - the field's name is the rest.
+            field_name = table_info.name.removeprefix(f"{owner_table}_")
+            attribute_name = ModelNaming.get_field_name(
+                field_name if field_name and field_name != table_info.name else other_table
+            )
+            # A pair is linked once only where a unique index over both columns says so.
+            unique = any(
+                index.is_unique and set(index.columns) == {owner_column, other_column} for index in table_info.indexes
+            )
+            field = cast(
+                "Field[Any]",
+                ManyToManyField(
+                    class_references[other_table],
+                    through=table_info.name,
+                    forward_key=other_column,
+                    backward_key=owner_column,
+                    related_name=ModelNaming.get_field_name(f"{table_info.name}_set"),
+                    unique=unique,
+                ),
+            )
+            self.fields_by_table.setdefault(owner_table, []).append((attribute_name, field))
+            owner_class_name = class_references[owner_table].rpartition(".")[2]
+            self.notes_by_table[table_info.name] = (
+                f"# NOTE: table {table_info.name!r} is the through table of the ManyToManyField "
+                f"{owner_class_name}.{attribute_name}."
+            )
+
+    @staticmethod
+    def get_sides(
+        table_info: TableInfo, tables_by_name: dict[str, TableInfo]
+    ) -> tuple[tuple[str, str], tuple[str, str]] | None:
+        """The two sides of a through table - two single-column foreign keys to the primary keys of
+        tables of the run, and no other column.
+
+        Args:
+            table_info: The table.
+            tables_by_name: The tables of the run.
+
+        Returns:
+            The column and the target table of each side, in the order of the columns; None for a
+            table of any other shape.
+        """
+        if not table_info.is_many_to_many_junction_shape or table_info.composite_foreign_keys:
+            return None
+        if len(table_info.foreign_keys) != 2 or len(table_info.columns) != 2:
+            return None
+        sides = []
+        for column in table_info.columns:
+            foreign_key = table_info.foreign_keys.get(column.name)
+            if (
+                foreign_key is None
+                or foreign_key.to_field is not None
+                or foreign_key.target_table not in tables_by_name
+            ):
+                return None
+            sides.append((column.name, foreign_key.target_table))
+        return sides[0], sides[1]

hare/inspectdb/generation/model_factory.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from copy import copy
+from typing import TYPE_CHECKING, Any, cast
+
+from hare.fields.composite_primary_key import CompositePrimaryKey
+from hare.inspectdb.constants import FACTORY_MODEL_MODULE_NAME
+from hare.inspectdb.generation.declarations import ModelGenerationOptions
+from hare.inspectdb.generation.inspected_model_builder import InspectedModelBuilder
+from hare.models import Model
+from hare.models.enums import ModelOption
+
+if TYPE_CHECKING:
+    from hare.inspectdb.generation.inspected_model import InspectedModel
+    from hare.inspectdb.introspection.table_info import TableInfo
+    from hare.migrations.state.model_state import ModelState
+from hare.exceptions import ConfigurationError
+from hare.inspectdb.exceptions import ManyToManyThroughTableSkippedError
+
+
+class ModelFactory:
+    """Builds Model classes from introspected tables."""
+
+    @staticmethod
+    def from_table_info(
+        table_info: TableInfo,
+        dialect: str,
+        *,
+        app_label: str,
+        foreign_key_target_overrides: dict[str, str] | None = None,
+        skip_many_to_many_through_tables: bool = True,
+    ) -> type[Model]:
+        """Builds an unregistered Model class for one table.
+
+        Args:
+            table_info: The introspected table.
+            dialect: The backend dialect, for type mapping.
+            app_label: App label FK/composite-FK target references are qualified with
+                (``"<app_label>.<TargetClass>"``) - normally the label the model is then
+                registered under.
+            foreign_key_target_overrides: Per-target-table override of the whole ``"<app_label>.
+                <TargetClass>"`` reference, keyed by the target's raw table name - for pointing an
+                FK at an already-registered model.
+            skip_many_to_many_through_tables: Whether a table shaped exactly like a ManyToManyField through
+                table is refused (the default) instead of built.
+
+        Returns:
+            The new model class, not yet registered anywhere.
+
+        Raises:
+            ManyToManyThroughTableSkippedError: The table is a ManyToManyField through table and
+                ``skip_many_to_many_through_tables`` is True.
+            ConfigurationError: No model can be declared for the table.
+        """
+        inspected = InspectedModelBuilder(
+            table_info,
+            ModelGenerationOptions(dialect, app_label, foreign_key_target_overrides, skip_many_to_many_through_tables),
+        ).build()
+        if inspected.unmodelable_reason is not None:
+            raise ConfigurationError(f"inspectdb: {inspected.unmodelable_reason}")
+        if inspected.state is None:
+            raise ManyToManyThroughTableSkippedError(table_info.name)
+        return ModelFactory.build_model_class(inspected)
+
+    @staticmethod
+    def build_model_class(inspected: InspectedModel) -> type[Model]:
+        """Builds the class of an inspected model.
+
+        Args:
+            inspected: The inspected model - with a state.
+
+        Returns:
+            The new model class.
+        """
+        # Only a model with a state reaches here - a skipped through table has none.
+        state = cast("ModelState", inspected.state)
+        attributes: dict[str, Any] = {"__module__": FACTORY_MODEL_MODULE_NAME, "__qualname__": inspected.class_name}
+        attributes.update({name: copy(field) for name, field in state.fields.items()})
+        if isinstance(state.pk_field_name, tuple):
+            attributes["pk"] = CompositePrimaryKey(
+                *state.pk_field_name, without_overlaps=state.options.get(ModelOption.PK_WITHOUT_OVERLAPS, False)
+            )
+        meta_options = {
+            str(entry): state.options[entry] for entry in inspected.meta_layout if isinstance(entry, ModelOption)
+        }
+        if meta_options:
+            attributes["Meta"] = type("Meta", (), meta_options)
+        return cast("type[Model]", type(inspected.class_name, (Model,), attributes))

hare/inspectdb/generation/model_naming.py

@@ -0,0 +1,75 @@
+"""The database-name-to-identifier mangling SchemaIntrospector and ModelSourceBuilder share - the
+introspector predicts the attribute names the generator gives.
+"""
+
+from __future__ import annotations
+
+import keyword
+import unicodedata
+
+from hare.inspectdb.constants import ENUM_MEMBER_NAME_PATTERN, UNDERSCORE_RUN_PATTERN
+
+
+class ModelNaming:
+    """Python names of the models and fields inspectdb generates."""
+
+    @staticmethod
+    def get_safe_identifier(name: str, *, digit_prefix: str) -> str:
+        """``name`` made a usable identifier: an illegal character becomes an underscore (letters of
+        any script stay), a leading digit gets ``digit_prefix``, a keyword gets a trailing
+        underscore. The caller keeps the real name (``source_field=``) and the results unique.
+        """
+        normalized = unicodedata.normalize("NFKC", name)
+        safe = "".join(char if f"a{char}".isidentifier() else "_" for char in normalized)
+        if not safe or not safe.isidentifier():
+            safe = f"{digit_prefix}{safe}"
+        return f"{safe}_" if keyword.iskeyword(safe) else safe
+
+    @staticmethod
+    def get_field_name(name: str) -> str:
+        """A field's name for a column: ``get_safe_identifier()``'s, a run of underscores made one -
+        ``__`` separates the names of a lookup path -, none at its end - a lookup path would read it as
+        part of the separator -, and a keyword followed by ``_field``. The caller keeps the real name
+        (``source_field=``) and the results unique.
+
+        Args:
+            name: The column's name.
+
+        Returns:
+            The field's name.
+        """
+        safe = ModelNaming.get_safe_identifier(name, digit_prefix="field_")
+        if keyword.iskeyword(safe.removesuffix("_")) and safe.endswith("_"):
+            safe = f"{safe.removesuffix('_')}_field"
+        return UNDERSCORE_RUN_PATTERN.sub("_", safe).rstrip("_") or "field"
+
+    @staticmethod
+    def get_class_name(table_name: str) -> str:
+        """Derives the Python class name inspectdb generates for a given DB table name - the single
+        source of truth every caller that needs to name or reference a generated model class relies
+        on, so they can never disagree about what name a given table maps to."""
+        return ModelNaming.get_safe_identifier(
+            "".join(part.capitalize() for part in table_name.split("_")), digit_prefix="T"
+        )
+
+    @staticmethod
+    def get_enum_member_names(labels: list[str]) -> dict[str, str]:
+        """The member names of an enum of labels - each label uppercased, a run of characters no name
+        holds made an underscore, a number appended to a repeated name.
+
+        Args:
+            labels: The labels.
+
+        Returns:
+            The labels by member name.
+        """
+        member_names: dict[str, str] = {}
+        for label in labels:
+            member_name = ENUM_MEMBER_NAME_PATTERN.sub("_", label).strip("_").upper() or "VALUE"
+            if not member_name[0].isalpha():
+                member_name = f"VALUE_{member_name}"
+            unique_member_name, number = member_name, 2
+            while unique_member_name in member_names:
+                unique_member_name, number = f"{member_name}_{number}", number + 1
+            member_names[unique_member_name] = label
+        return member_names

hare/inspectdb/generation/model_source_builder.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+from hare.inspectdb.generation.declarations import ModelGenerationOptions
+from hare.inspectdb.generation.inspected_model_builder import InspectedModelBuilder
+from hare.migrations.writer.import_manager import ImportManager
+from hare.migrations.writer.migration_writer import MigrationWriter
+from hare.models.enums import ModelOption
+
+if TYPE_CHECKING:
+    from hare.fields.field import Field
+    from hare.inspectdb.generation.inspected_model import InspectedModel
+    from hare.inspectdb.introspection.table_info import TableInfo
+    from hare.migrations.state.model_state import ModelState
+
+
+class ModelSourceBuilder:
+    """Renders one table's ``InspectedModel`` as Python model source - each field, index and
+    constraint written as the call building it, the way a migration file writes it.
+
+    Args:
+        table: The table.
+        options: How the table is turned into a model.
+        imports: The imports of the module the model is written into, shared by its models - an enum
+            declared for one takes a name no other's declaration has. None for a model of its own.
+    """
+
+    def __init__(
+        self, table: TableInfo, options: ModelGenerationOptions, imports: ImportManager | None = None
+    ) -> None:
+        self.table = table
+        self.options = options
+        self.model_builder = self.get_model_builder(frozenset())
+        self.shares_imports = imports is not None
+        self.imports = imports if imports is not None else ImportManager()
+        #: Whether the last build rendered a class, not a skipped table's note.
+        self.has_class = False
+
+    def get_model_builder(self, extra_reserved_attribute_names: frozenset[str]) -> InspectedModelBuilder:
+        """The builder of the table's inspected model, reserving ``extra_reserved_attribute_names``."""
+        return InspectedModelBuilder(self.table, self.options, extra_reserved_attribute_names)
+
+    @property
+    def bound_names(self) -> set[str]:
+        """Module-level names the rendered source binds through its imports."""
+        return {"Model", *self.imports.bound_names()}
+
+    def build(self) -> str:
+        """The model's source with its imports.
+
+        Returns:
+            The source, or the note a skipped table gets instead.
+        """
+        body = self.build_body()
+        if not self.has_class:
+            return body
+        return "\n".join([*self.get_import_lines(self.imports), "", "", body])
+
+    def build_body(self) -> str:
+        """The model's class source without its imports - which ``self.imports`` holds then.
+
+        Returns:
+            The class source, or the note a skipped table gets instead.
+        """
+        inspected = self.model_builder.build()
+        self.has_class = inspected.state is not None
+        if inspected.state is None:
+            return inspected.skipped_note or ""
+        source = self.render(inspected)
+        # A class-body attribute named like an import (a column "fields", "OnDelete", ...) would
+        # shadow that import for every later line of the class body - rebuilt with those names
+        # reserved. Renaming attributes never changes which imports are needed.
+        if not self.bound_names & set(inspected.state.fields):
+            return source
+        self.model_builder = self.get_model_builder(frozenset(self.bound_names))
+        if not self.shares_imports:
+            self.imports = ImportManager()
+        return self.render(self.model_builder.build())
+
+    @staticmethod
+    def get_import_lines(imports: ImportManager) -> list[str]:
+        """The import lines of a module of models.
+
+        Args:
+            imports: What the models import.
+
+        Returns:
+            The lines.
+        """
+        lines = ["from hare.models import Model", *imports.render()]
+        # An enum class no module defines (the labels of a PostgreSQL ENUM type) is declared after
+        # the imports.
+        if imports.enum_declarations:
+            lines.extend(["", *imports.enum_declarations])
+        return lines
+
+    def render_field(self, field: Field[Any]) -> str:
+        """A field as the call building it. A relation indexed by default is written as a model
+        declares it: without ``db_index=True`` (a migration file writes it, since a replayed
+        relation isn't indexed by default), and with ``db_index=False`` when it has no index."""
+        path, args, kwargs = field.deconstruct()
+        if getattr(type(field), "indexed_by_default", False):
+            if kwargs.get("db_index") is True:
+                del kwargs["db_index"]
+            elif not field.index and not field.pk:
+                kwargs["db_index"] = False
+        return MigrationWriter.render_call(path, args, kwargs, self.imports)
+
+    def render(self, inspected: InspectedModel) -> str:
+        """The class source of an inspected model.
+
+        Args:
+            inspected: The inspected model - with a state.
+
+        Returns:
+            The source.
+        """
+        # Only a model with a state reaches here - a skipped through table has none.
+        state = cast("ModelState", inspected.state)
+        lines = [f"class {inspected.class_name}(Model):"]
+        for attribute_name, field in state.fields.items():
+            todo_reason = inspected.todo_reasons.get(attribute_name)
+            todo = f"  # TODO: {todo_reason}" if todo_reason else ""
+            lines.append(f"    {attribute_name} = {self.render_field(field)}{todo}")
+        if isinstance(state.pk_field_name, tuple):
+            composite_pk = MigrationWriter.render_call(
+                "hare.fields.CompositePrimaryKey",
+                list(state.pk_field_name),
+                {"without_overlaps": True} if state.options.get(ModelOption.PK_WITHOUT_OVERLAPS) else {},
+                self.imports,
+            )
+            lines.append("")
+            lines.append(f"    pk = {composite_pk}")
+        if inspected.meta_layout:
+            lines.append("")
+            lines.append("    class Meta:")
+            # A Meta body made only of comment lines would be a SyntaxError.
+            if not any(isinstance(entry, ModelOption) for entry in inspected.meta_layout):
+                lines.append("        pass")
+            for entry in inspected.meta_layout:
+                if isinstance(entry, ModelOption):
+                    lines.append(
+                        f"        {entry} = {MigrationWriter.render_value(state.options[entry], self.imports)}"
+                    )
+                else:
+                    lines.append(f"        {entry}")
+        return "\n".join(lines)

hare/inspectdb/introspection/__init__.py

@@ -0,0 +1,28 @@
+"""Reads an existing database's schema into plain dataclasses (TableInfo/ColumnInfo/...) - the
+intermediate representation ModelSourceBuilder renders back out as hare-orm model source. Each
+dialect reads its own catalog through its ``SchemaIntrospector`` subclass (``Dialect.introspector_class``).
+"""
+
+from __future__ import annotations
+
+from hare.inspectdb.exceptions import SchemaNotFoundError, TableNotFoundError, UnsupportedDialectError
+from hare.inspectdb.introspection.column_info import ColumnInfo
+from hare.inspectdb.introspection.composite_foreign_key_info import CompositeForeignKeyInfo
+from hare.inspectdb.introspection.database_catalog import DatabaseCatalog
+from hare.inspectdb.introspection.foreign_key_info import ForeignKeyInfo
+from hare.inspectdb.introspection.index_info import IndexInfo
+from hare.inspectdb.introspection.schema_introspector import SchemaIntrospector
+from hare.inspectdb.introspection.table_info import TableInfo
+
+__all__ = [
+    "DatabaseCatalog",
+    "ColumnInfo",
+    "CompositeForeignKeyInfo",
+    "ForeignKeyInfo",
+    "IndexInfo",
+    "SchemaIntrospector",
+    "TableInfo",
+    "UnsupportedDialectError",
+    "SchemaNotFoundError",
+    "TableNotFoundError",
+]

hare/inspectdb/introspection/column_info.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class ColumnInfo:
+    name: str
+    db_type: str
+    nullable: bool
+    is_pk: bool
+    is_unique: bool
+    #: The column's 1-based position in the PRIMARY KEY, None outside it - the key's order can
+    #: differ from the table's.
+    pk_position: int | None = None
+    #: A plain (non-unique) single-column index exists on this column - reconstructed as
+    #: db_index=True. Independent of is_unique (a UNIQUE constraint already implies indexing at
+    #: the DB level, so this only matters for a genuinely separate, non-unique index).
+    has_index: bool = False
+    #: character_maximum_length (Postgres) / parsed out of the declared type string (SQLite,
+    #: e.g. "VARCHAR(255)") - overrides the generic max_length=255 fallback when known.
+    max_length: int | None = None
+    #: Precision and scale of a column mapped to a DecimalField - Postgres reports them for integers
+    #: too.
+    numeric_precision: int | None = None
+    numeric_scale: int | None = None
+    #: The parsed default (SchemaIntrospector.parse_db_default()). None: no default, a sequence
+    #: default or a NULL default.
+    db_default: Any = None
+    #: The column's comment, where the database keeps column comments.
+    description: str | None = None
+    #: information_schema.columns.udt_name (Postgres): the element type of an ARRAY ("_int4"), the
+    #: real type of a USER-DEFINED column.
+    udt_name: str | None = None
+    #: A generated column's expression, as the database's catalog gives it (SQLite: parsed from the
+    #: CREATE TABLE text). A generated column whose expression can't be parsed is left out of the columns.
+    generated_expression: str | None = None
+    #: True for a STORED generated column, False for VIRTUAL - only meaningful when
+    #: generated_expression is set.
+    generated_stored: bool = True
+    #: A ``vector(N)`` column's dimensions, parsed from format_type() (Postgres).
+    vector_dimensions: int | None = None
+    #: A ``numeric(p,s)[]`` column's element precision and scale, parsed from format_type()
+    #: (Postgres).
+    array_element_numeric_precision_scale: tuple[int, int] | None = None
+    #: varchar[]/char[]'s own element length (Postgres only) - same reasoning as
+    #: array_element_numeric_precision_scale above, parsed out of format_type()'s own
+    #: "character varying(N)[]"/"character(N)[]" text.
+    array_element_max_length: int | None = None
+    #: "ALWAYS" or "BY DEFAULT" for a Postgres identity column (``GENERATED ... AS IDENTITY``),
+    #: None otherwise - the database assigns its value on INSERT.
+    identity_generation: str | None = None
+    #: The column's full type as the database prints it - ``character varying(50)``, ``numeric(10,2)``,
+    #: ``integer[]``; None where the introspector reads no such text.
+    full_type: str | None = None
+    #: The labels of the column's ``ENUM`` type in their order - of its elements' type for an array;
+    #: None for a column of no enum type (Postgres only).
+    enum_labels: tuple[str, ...] | None = None
+    #: The schema of the column's ``ENUM`` type when it isn't the connection's default one; None otherwise
+    #: (Postgres only).
+    enum_type_schema: str | None = None
+    #: Whether the database gives the column a value an INSERT leaves out - a sequence, an identity, a
+    #: row id. Read for an integer primary key; True where it can't be told.
+    generates_key: bool = True
+    #: Why the column's field can't be the column as it is - written as a TODO; None when it can.
+    todo_reason: str | None = None

hare/inspectdb/introspection/composite_foreign_key_info.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from hare.fields.enums import OnDelete
+from hare.inspectdb.constants import FOREIGN_KEY_NO_ACTION
+
+
+@dataclass
+class CompositeForeignKeyInfo:
+    """A composite FOREIGN KEY referencing the target's whole primary key under the key column naming
+    of a relation - rendered as one ``ForeignKeyField``.
+    """
+
+    #: Python attribute name for the generated ForeignKeyField - chosen so that
+    #: ``f"{field_name}_{target_pk_component}"`` reproduces every entry in ``columns`` exactly.
+    field_name: str
+    #: This table's own local columns, reordered to match the target's declared primary key
+    #: column order (not necessarily the FK constraint's own written order).
+    columns: tuple[str, ...]
+    target_table: str
+    on_delete: OnDelete = OnDelete.CASCADE
+    #: The ON UPDATE action, as the database spells it.
+    on_update: str = FOREIGN_KEY_NO_ACTION
+    #: ``DEFERRABLE INITIALLY IMMEDIATE``/``DEFERRABLE INITIALLY DEFERRED``, ``""`` for a constraint
+    #: checked at once - None where the database doesn't tell (SQLite).
+    deferral: str | None = None