xtr-orm 1.5.0__py3-none-any.whl

xtr_orm/migrations/_revisions.py

@@ -0,0 +1,198 @@
+"""Reading the revision files: what exists, what is applied, and what a target means.
+
+Everything here works on a revision directory and a database's current
+revisions, and touches no database. The runner is handed the steps these
+functions return and applies them.
+"""
+
+from __future__ import annotations
+
+import re
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Final
+
+from alembic.runtime.migration import MigrationStep, RevisionStep
+from alembic.script.revision import ResolutionError, RevisionError
+from alembic.util import CommandError
+
+from xtr_orm.exception import MigrationError
+
+from .available_migration import AvailableMigration
+from .direction import Direction
+
+if TYPE_CHECKING:
+    from collections.abc import Generator, Iterable, Sequence
+
+    from alembic.script import Script, ScriptDirectory
+
+__all__ = [
+    "applied",
+    "available",
+    "known",
+    "mark_step",
+    "migration",
+    "parents",
+    "plan",
+    "refusing",
+    "resolve",
+    "revision_steps",
+    "step",
+]
+
+_ALIASES: Final[dict[str, tuple[str, Direction]]] = {
+    "latest": ("heads", Direction.UP),
+    "head": ("heads", Direction.UP),
+    "heads": ("heads", Direction.UP),
+    "next": ("+1", Direction.UP),
+    "first": ("base", Direction.DOWN),
+    "base": ("base", Direction.DOWN),
+    "prev": ("-1", Direction.DOWN),
+}
+"""Names a target may be given by, and the revision and direction each stands for."""
+
+_RELATIVE: Final = re.compile(r"^(?:.+?@)?\w*([+-])\d+$")
+"""``+2``, ``-1``, ``ae10+1``, ``branch@head-1``: a number of steps from somewhere."""
+
+
+def migration(script: Script) -> AvailableMigration:
+    """Describe ``script`` as the rest of the library sees a revision file."""
+    return AvailableMigration(
+        version=script.revision,
+        description=(script.doc or "").strip(),
+        down_versions=_as_tuple(script.down_revision),
+        path=script.path,
+        is_head=script.is_head,
+    )
+
+
+def available(directory: ScriptDirectory) -> tuple[Script, ...]:
+    """Return every revision in ``directory``, earliest first."""
+    with refusing():
+        return tuple(reversed(list(directory.walk_revisions())))
+
+
+def known(directory: ScriptDirectory, versions: Iterable[str]) -> tuple[str, ...]:
+    """Return the ``versions`` that have a revision file."""
+    found: list[str] = []
+    for version in versions:
+        try:
+            _ = directory.get_revision(version)
+        except (CommandError, ResolutionError, RevisionError):
+            continue
+        found.append(version)
+    return tuple(found)
+
+
+def applied(directory: ScriptDirectory, heads: Sequence[str]) -> set[str]:
+    """Return every revision ``heads`` stand for: themselves and all they follow.
+
+    A head without a file stands only for itself; what it followed cannot be
+    known.
+    """
+    present = known(directory, heads)
+    if not present:
+        return set()
+    with refusing():
+        return {each.revision for each in directory.iterate_revisions(present, "base")}
+
+
+def resolve(directory: ScriptDirectory, version: str) -> Script:
+    """Return the one revision ``version`` names — a full or partial id, or a label.
+
+    Raises:
+        MigrationError: When no revision, or more than one, answers to it.
+    """
+    try:
+        found = directory.get_revision(version)
+    except (CommandError, ResolutionError, RevisionError) as error:
+        raise MigrationError(f'Unknown version "{version}": {error}') from error
+    return found
+
+
+def parents(directory: ScriptDirectory, script: Script) -> tuple[str, ...]:
+    """Return the revisions ``script`` needs applied first: those it follows and depends on."""
+    dependencies = (resolve(directory, each).revision for each in _as_tuple(script.dependencies))
+    return (*_as_tuple(script.down_revision), *dependencies)
+
+
+def plan(
+    directory: ScriptDirectory, heads: tuple[str, ...], target: str
+) -> tuple[Direction, list[RevisionStep]]:
+    """Return which way reaching ``target`` from ``heads`` goes, and the steps it takes.
+
+    ``target`` is a revision, a relative one (``+1``, ``-2``, ``ae10+1``), or
+    one of ``latest``, ``first``, ``next``, ``prev`` and ``current``.
+
+    Raises:
+        MigrationError: When the target is unknown, or cannot be reached.
+    """
+    if target == "current":
+        return Direction.UP, []
+    destination, direction = _ALIASES.get(target, (target, Direction.UP))
+    if target not in _ALIASES:
+        relative = _RELATIVE.match(target)
+        if relative is not None:
+            direction = Direction.UP if relative.group(1) == "+" else Direction.DOWN
+        elif resolve(directory, target).revision in applied(directory, heads):
+            direction = Direction.DOWN
+    return direction, revision_steps(directory, heads, destination, direction)
+
+
+def revision_steps(
+    directory: ScriptDirectory, heads: tuple[str, ...], destination: str, direction: Direction
+) -> list[RevisionStep]:
+    """Return the steps from ``heads`` to ``destination``, going ``direction``.
+
+    Raises:
+        MigrationError: When the destination cannot be reached that way.
+    """
+    revision_map = directory.revision_map
+    with refusing():
+        if direction is Direction.UP:
+            scripts = reversed(
+                list(directory.iterate_revisions(destination, heads, implicit_base=True))
+            )
+            return [MigrationStep.upgrade_from_script(revision_map, each) for each in scripts]
+        scripts = directory.iterate_revisions(heads, destination, select_for_downgrade=True)
+        return [MigrationStep.downgrade_from_script(revision_map, each) for each in scripts]
+
+
+def step(directory: ScriptDirectory, script: Script, direction: Direction) -> RevisionStep:
+    """Return the step running ``script``'s upgrade or downgrade alone."""
+    if direction is Direction.UP:
+        return MigrationStep.upgrade_from_script(directory.revision_map, script)
+    return MigrationStep.downgrade_from_script(directory.revision_map, script)
+
+
+def mark_step(directory: ScriptDirectory, script: Script, direction: Direction) -> RevisionStep:
+    """Return a step that moves the version table over ``script`` without running it."""
+    marked = step(directory, script, direction)
+    marked.migration_fn = _nothing
+    return marked
+
+
+def _nothing(**_: object) -> None:
+    """Stand in for a revision's upgrade or downgrade when it is only marked."""
+
+
+def _as_tuple(value: str | Sequence[str] | None) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        return (value,)
+    return tuple(value)
+
+
+@contextmanager
+def refusing() -> Generator[None]:
+    """Turn the revision reader's own errors into :class:`MigrationError`."""
+    try:
+        yield
+    except (CommandError, ResolutionError, RevisionError) as error:
+        raise MigrationError(str(error)) from error
+    except KeyError as error:
+        # The reader indexes its map by the ids revisions name; one naming a
+        # revision that has no file surfaces as the missing key.
+        raise MigrationError(
+            f"A revision follows {error.args[0]!r}, which has no revision file.",
+        ) from error

xtr_orm/migrations/_schema.py

@@ -0,0 +1,66 @@
+"""Revisions written from table definitions rather than from a comparison.
+
+A dump of an existing database, or a diff "from an empty schema", both come
+down to one revision creating every table — and its downgrade dropping them
+again — written through the same renderer a compared diff uses.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from alembic.operations.ops import (
+    CreateIndexOp,
+    CreateTableOp,
+    DowngradeOps,
+    DropIndexOp,
+    DropTableOp,
+    UpgradeOps,
+)
+from sqlalchemy import MetaData
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
+    from sqlalchemy import Index, Table
+
+__all__ = ["creating", "matching", "tables_of"]
+
+
+def tables_of(metadata: MetaData | Sequence[MetaData] | None) -> list[Table]:
+    """Return every table ``metadata`` defines, each after the tables it refers to."""
+    if metadata is None:
+        return []
+    each = [metadata] if isinstance(metadata, MetaData) else metadata
+    return [table for one in each for table in one.sorted_tables]
+
+
+def matching(tables: Iterable[Table], patterns: Sequence[str]) -> list[Table]:
+    """Return the ``tables`` whose name one of ``patterns`` finds; all of them with none."""
+    if not patterns:
+        return list(tables)
+    compiled = [re.compile(pattern) for pattern in patterns]
+    return [table for table in tables if any(each.search(table.name) for each in compiled)]
+
+
+def creating(tables: Sequence[Table]) -> tuple[UpgradeOps, DowngradeOps]:
+    """Return operations creating ``tables`` with their indexes, and dropping them again."""
+    indexes = [index for table in tables for index in _indexes(table)]
+    upgrade = UpgradeOps(
+        [
+            *(CreateTableOp.from_table(table) for table in tables),
+            *(CreateIndexOp.from_index(index) for index in indexes),
+        ],
+    )
+    downgrade = DowngradeOps(
+        [
+            *(DropIndexOp.from_index(index) for index in reversed(indexes)),
+            *(DropTableOp.from_table(table) for table in reversed(tables)),
+        ],
+    )
+    return upgrade, downgrade
+
+
+def _indexes(table: Table) -> list[Index]:
+    return sorted(table.indexes, key=lambda index: str(index.name))

xtr_orm/migrations/available_migration.py

@@ -0,0 +1,27 @@
+"""A revision file, as it was found in the migrations directory."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["AvailableMigration"]
+
+
+@dataclass(frozen=True, slots=True)
+class AvailableMigration:
+    """A revision file, as it was found in the migrations directory.
+
+    Attributes:
+        version: The revision's identifier.
+        description: The first line of its message.
+        down_versions: The revisions it follows; empty for a first revision,
+            two or more for one merging branches.
+        path: Where its file is.
+        is_head: Whether no revision follows it.
+    """
+
+    version: str
+    description: str
+    down_versions: tuple[str, ...]
+    path: str
+    is_head: bool

xtr_orm/migrations/direction.py

@@ -0,0 +1,14 @@
+"""Which way a revision runs."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+__all__ = ["Direction"]
+
+
+class Direction(Enum):
+    """Which way a revision runs: its upgrade, or its downgrade."""
+
+    UP = "up"
+    DOWN = "down"

xtr_orm/migrations/executed_migration.py

@@ -0,0 +1,31 @@
+"""A revision the database counts as applied."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+__all__ = ["ExecutedMigration"]
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutedMigration:
+    """A revision the database counts as applied.
+
+    Applied means recorded in the version table, preceding a revision that
+    is, or recorded in the history table. When and how long come from the
+    history table: a revision applied before it existed has neither, and one
+    only marked as applied has no duration.
+
+    Attributes:
+        version: The revision's identifier.
+        executed_at: When it was applied, by the database's clock.
+        execution_time: How long it took, in seconds.
+    """
+
+    version: str
+    executed_at: datetime | None = None
+    execution_time: float | None = None

xtr_orm/migrations/execution_result.py

@@ -0,0 +1,26 @@
+"""One revision a migration ran, and how long it took."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .direction import Direction
+
+__all__ = ["ExecutionResult"]
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionResult:
+    """One revision a migration ran, and how long it took.
+
+    Attributes:
+        version: The revision's identifier.
+        direction: Whether its upgrade or its downgrade ran.
+        duration: How long it took, in seconds.
+    """
+
+    version: str
+    direction: Direction
+    duration: float

xtr_orm/migrations/migration_plan.py

@@ -0,0 +1,26 @@
+"""One revision a migration would run, and which way."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .direction import Direction
+
+__all__ = ["MigrationPlan"]
+
+
+@dataclass(frozen=True, slots=True)
+class MigrationPlan:
+    """One revision a migration would run, and which way.
+
+    Attributes:
+        version: The revision's identifier.
+        direction: Whether its upgrade or its downgrade runs.
+        description: The first line of its message.
+    """
+
+    version: str
+    direction: Direction
+    description: str

xtr_orm/migrations/migration_status.py

@@ -0,0 +1,48 @@
+"""Where a database stands against its revision files."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .available_migration import AvailableMigration
+    from .executed_migration import ExecutedMigration
+
+__all__ = ["MigrationStatus"]
+
+
+@dataclass(frozen=True, slots=True)
+class MigrationStatus:
+    """Where a database stands against its revision files, read in one go.
+
+    Attributes:
+        current: The revisions the version table holds; empty when nothing
+            is applied.
+        latest: The revisions no other follows.
+        previous: The revisions the current ones follow.
+        next: The revisions that could run next, their predecessors all
+            applied.
+        available: Every revision file, earliest first.
+        executed: Every revision counted as applied — those with a file,
+            earliest first, then those without. A revision is applied when
+            the version table holds it or one following it, or the history
+            table records it.
+        new: The revisions with a file that are not applied.
+        executed_unavailable: The revisions recorded as applied that have no
+            file.
+    """
+
+    current: tuple[str, ...]
+    latest: tuple[str, ...]
+    previous: tuple[str, ...]
+    next: tuple[str, ...]
+    available: tuple[AvailableMigration, ...]
+    executed: tuple[ExecutedMigration, ...]
+    new: tuple[AvailableMigration, ...]
+    executed_unavailable: tuple[ExecutedMigration, ...]
+
+    @property
+    def is_up_to_date(self) -> bool:
+        """Whether every revision with a file is applied."""
+        return not self.new

xtr_orm/migrations/migrations_config.py

@@ -0,0 +1,162 @@
+"""How one database's migrations are written, found and recorded."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Final, cast
+
+from xtr_orm.exception import InvalidArgumentError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping, Sequence
+
+__all__ = ["MigrationsConfig"]
+
+_FILE_TEMPLATE_FIELDS: Final = {
+    "rev": "%(rev)s",
+    "slug": "%(slug)s",
+    "epoch": "%(epoch)s",
+    "year": "%(year)d",
+    "month": "%(month).2d",
+    "day": "%(day).2d",
+    "hour": "%(hour).2d",
+    "minute": "%(minute).2d",
+    "second": "%(second).2d",
+}
+_FIELD: Final = re.compile(r"\{(\w+)\}")
+
+
+def _no_options() -> dict[str, object]:
+    return {}
+
+
+@dataclass(frozen=True, slots=True)
+class MigrationsConfig:
+    """Where a database's revisions live, how new ones are written, and how runs are recorded.
+
+    Revisions are ordinary migration files, one per change, in
+    :attr:`directory`. The database keeps its current revisions in
+    :attr:`version_table`, and a row per revision ever applied — when, and how
+    long it took — in :attr:`history_table`.
+
+    ```python
+    MigrationsConfig(
+        directory="%kernel.project_dir%/migrations",
+        version_table_schema="meta",
+        render_as_batch=True,  # SQLite cannot alter a table in place
+    )
+    ```
+
+    Attributes:
+        directory: Where revision files are read from and written to; created
+            when the first one is written.
+        version_table: The table holding the database's current revisions.
+        version_table_schema: The schema of both tables; the connection's
+            default when ``None``.
+        history_table: The table recording every revision applied, when it
+            ran and how long it took.
+        file_template: How a new revision's file is named. ``{rev}``,
+            ``{slug}``, ``{epoch}``, ``{year}``, ``{month}``, ``{day}``,
+            ``{hour}``, ``{minute}`` and ``{second}`` are filled in; the
+            default sorts files by the time they were written.
+        truncate_slug_length: The longest the message part of a file name
+            gets.
+        timezone: The time zone a revision's creation date is written in;
+            local time when ``None``.
+        template_directory: A directory holding a ``script.py.mako`` that new
+            revisions are rendered from; the package's own when ``None``.
+        recursive_version_locations: Read revisions from subdirectories of
+            :attr:`directory` too.
+        post_write_hooks: Programs run on every file written, such as a
+            formatter — each a mapping with a ``type`` (``"console_scripts"``,
+            ``"exec"`` or ``"module"``) and that type's options.
+        transaction_per_migration: Commit after each revision rather than
+            once after all of them.
+        transactional_ddl: Whether schema changes run inside the
+            transaction; the database's own answer when ``None``.
+        compare_type: Compare column types when generating a diff. Off by
+            default: a type the database stores as another — a UUID kept as
+            bytes on SQLite — would otherwise differ in every diff.
+        compare_server_default: Compare server defaults when generating a
+            diff.
+        render_as_batch: Write table changes as copy-and-move batches, which
+            SQLite needs for anything but adding a column.
+        include_schemas: Compare every schema when generating a diff, not
+            only the default one.
+        include_name: Decides, by name, which schemas and tables a diff
+            reads from the database.
+        include_object: Decides which tables, columns, indexes and
+            constraints a diff considers.
+        render_item: Renders a type or a construct a diff writes, before the
+            default rendering.
+        process_revision_directives: Adjusts a revision about to be written.
+        user_module_prefix: Written before a custom type's class name; the
+            type's own module — imported by the revision — when ``None``.
+        context_options: Any other migration context option, passed as it
+            is.
+    """
+
+    directory: str = "migrations"
+    version_table: str = "alembic_version"
+    version_table_schema: str | None = None
+    history_table: str = "alembic_version_history"
+    file_template: str = "{year}{month}{day}{hour}{minute}{second}_{rev}_{slug}"
+    truncate_slug_length: int = 40
+    timezone: str | None = None
+    template_directory: str | None = None
+    recursive_version_locations: bool = False
+    post_write_hooks: Sequence[Mapping[str, str]] = ()
+    transaction_per_migration: bool = False
+    transactional_ddl: bool | None = None
+    compare_type: bool = False
+    compare_server_default: bool = False
+    render_as_batch: bool = False
+    include_schemas: bool = False
+    include_name: Callable[..., bool] | None = None
+    include_object: Callable[..., bool] | None = None
+    render_item: Callable[..., str | bool] | None = None
+    process_revision_directives: Callable[..., None] | None = None
+    user_module_prefix: str | None = None
+    context_options: Mapping[str, object] = field(default_factory=_no_options)
+
+    def __post_init__(self) -> None:
+        """Refuse an empty directory or table name, or a file template naming nothing known.
+
+        Raises:
+            InvalidArgumentError: When the configuration cannot be used.
+        """
+        for name in ("directory", "version_table", "history_table"):
+            # Compared, not tested for truth: a value may be an environment
+            # placeholder, which refuses to decide anything before it is read.
+            if cast("str", getattr(self, name)) == "":
+                raise InvalidArgumentError(f'The migrations "{name}" must not be empty.')
+        if self.version_table == self.history_table:
+            raise InvalidArgumentError(
+                "The migrations version table and history table must differ, "
+                f'both are "{self.version_table}".',
+            )
+        unknown = [
+            name
+            for name in cast("list[str]", _FIELD.findall(self.file_template))
+            if name not in _FILE_TEMPLATE_FIELDS
+        ]
+        if unknown:
+            known = ", ".join(f"{{{name}}}" for name in _FILE_TEMPLATE_FIELDS)
+            raise InvalidArgumentError(
+                f'The migrations file template names "{{{unknown[0]}}}"; it may use {known}.',
+            )
+        if "{rev}" not in self.file_template and "{epoch}" not in self.file_template:
+            raise InvalidArgumentError(
+                "The migrations file template must hold {rev} or {epoch}, "
+                "or two revisions could be written to one file.",
+            )
+        if self.truncate_slug_length < 1:
+            raise InvalidArgumentError(
+                f"The migrations slug length must be at least 1, got {self.truncate_slug_length}.",
+            )
+
+    def alembic_file_template(self) -> str:
+        """Return :attr:`file_template` in the form the revision writer reads."""
+        escaped = self.file_template.replace("%", "%%")
+        return _FIELD.sub(lambda match: _FILE_TEMPLATE_FIELDS[match.group(1)], escaped)