xtr-orm 1.5.0__py3-none-any.whl

xtr_orm/bundle/orm_config.py

@@ -0,0 +1,101 @@
+"""Configuration for :class:`~xtr_orm.bundle.orm_bundle.OrmBundle`."""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from xtr_orm.connection_registry import DEFAULT_CONNECTION
+from xtr_orm.exception import InvalidArgumentError
+from xtr_orm.migrations import MigrationsConfig
+
+from .connection_config import ConnectionConfig
+
+__all__ = ["OrmConfig"]
+
+_MIGRATIONS_DIRECTORY = "%kernel.project_dir%/migrations"
+
+
+def _one_connection() -> dict[str, ConnectionConfig]:
+    return {DEFAULT_CONNECTION: ConnectionConfig()}
+
+
+@dataclass(frozen=True, slots=True)
+class OrmConfig:
+    """Which databases the application uses, each by name.
+
+    With no configuration there is one connection, ``default``, reading its
+    URL from ``DATABASE_URL`` when first used, with its revisions in
+    ``migrations`` in the project directory.
+
+    ```python
+    OrmConfig(
+        connections={
+            "default": ConnectionConfig(url=env("DATABASE_URL")),
+            "reports": ConnectionConfig(url=env("REPORTS_URL"), bind_key="reports"),
+        },
+    )
+    ```
+
+    Attributes:
+        default_connection: The connection provided without a qualifier, and
+            used by every command not given ``--connection``.
+        connections: Every connection, by name — the default first once
+            built, each with its migrations settings decided.
+    """
+
+    default_connection: str = DEFAULT_CONNECTION
+    connections: Mapping[str, ConnectionConfig] = field(default_factory=_one_connection)
+
+    def __post_init__(self) -> None:
+        """Refuse no connection, an unnamed one, or a default that is not one of them.
+
+        Raises:
+            InvalidArgumentError: When the configuration cannot be used.
+        """
+        if not self.connections:
+            raise InvalidArgumentError("Configure at least one connection.")
+        for name, connection in self.connections.items():
+            if not isinstance(name, str) or not name:  # pyright: ignore[reportUnnecessaryIsInstance] -- configs are written by hand; the annotation is not enforced
+                raise InvalidArgumentError(f"A connection needs a non-empty name, got {name!r}.")
+            if not isinstance(connection, ConnectionConfig):  # pyright: ignore[reportUnnecessaryIsInstance] -- as above
+                raise InvalidArgumentError(
+                    f'The "{name}" connection must be a ConnectionConfig, got {connection!r}.',
+                )
+        if self.default_connection not in self.connections:
+            raise InvalidArgumentError(
+                f'The default connection "{self.default_connection}" is not configured.',
+            )
+        settled = _settled(self.default_connection, self.connections)
+        directories: dict[str, str] = {}
+        for name, connection in settled.items():
+            directory = connection.migrations.directory if connection.migrations else ""
+            if directory in directories:
+                raise InvalidArgumentError(
+                    f'The "{name}" and "{directories[directory]}" connections keep their '
+                    f'migrations in the same directory, "{directory}".',
+                )
+            directories[directory] = name
+        # Settled here, not when read, so the directory defaults take part in
+        # parameter resolution like any value the application wrote.
+        object.__setattr__(self, "connections", settled)
+
+
+def _settled(
+    default: str, connections: Mapping[str, ConnectionConfig]
+) -> dict[str, ConnectionConfig]:
+    """Return every connection, the default first, each with its migrations directory decided."""
+    ordered = [default, *(name for name in connections if name != default)]
+    settled: dict[str, ConnectionConfig] = {}
+    for name in ordered:
+        connection = connections[name]
+        if connection.migrations is None:
+            directory = (
+                _MIGRATIONS_DIRECTORY if name == default else f"{_MIGRATIONS_DIRECTORY}/{name}"
+            )
+            connection = dataclasses.replace(
+                connection, migrations=MigrationsConfig(directory=directory)
+            )
+        settled[name] = connection
+    return settled

xtr_orm/command/__init__.py

@@ -0,0 +1,56 @@
+"""The ``orm:*`` console commands.
+
+Importing this module declares them. With a container, the orm bundle loads
+it when the console bundle is active, and every command acts on the
+connections the bundle registered. Without one, give them connections with
+:func:`use_connections`:
+
+```python
+from xtr_orm import ConnectionRegistry
+from xtr_orm.command import use_connections
+
+registry = ConnectionRegistry()
+registry.register("default", engine=engine, migrator=migrator, database=database)
+use_connections(registry)
+```
+
+Needs the ``console`` extra: ``xtr-orm[console]``.
+"""
+
+from __future__ import annotations
+
+from .connections import use_connections
+from .database_create_command import DatabaseCreateCommand
+from .database_drop_command import DatabaseDropCommand
+from .migrations_current_command import MigrationsCurrentCommand
+from .migrations_diff_command import MigrationsDiffCommand
+from .migrations_dump_schema_command import MigrationsDumpSchemaCommand
+from .migrations_execute_command import MigrationsExecuteCommand
+from .migrations_generate_command import MigrationsGenerateCommand
+from .migrations_latest_command import MigrationsLatestCommand
+from .migrations_list_command import MigrationsListCommand
+from .migrations_migrate_command import MigrationsMigrateCommand
+from .migrations_rollup_command import MigrationsRollupCommand
+from .migrations_status_command import MigrationsStatusCommand
+from .migrations_up_to_date_command import MigrationsUpToDateCommand
+from .migrations_version_command import MigrationsVersionCommand
+from .run_sql_command import RunSqlCommand
+
+__all__ = [
+    "DatabaseCreateCommand",
+    "DatabaseDropCommand",
+    "MigrationsCurrentCommand",
+    "MigrationsDiffCommand",
+    "MigrationsDumpSchemaCommand",
+    "MigrationsExecuteCommand",
+    "MigrationsGenerateCommand",
+    "MigrationsLatestCommand",
+    "MigrationsListCommand",
+    "MigrationsMigrateCommand",
+    "MigrationsRollupCommand",
+    "MigrationsStatusCommand",
+    "MigrationsUpToDateCommand",
+    "MigrationsVersionCommand",
+    "RunSqlCommand",
+    "use_connections",
+]

xtr_orm/command/connection_command.py

@@ -0,0 +1,134 @@
+"""What every orm command shares: where the connections come from, and how it reports."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, ClassVar
+
+from xtr_console import ConsoleStyle, escape
+
+from xtr_orm.connection_registry import ConnectionRegistry
+from xtr_orm.exception import UnknownConnectionError
+
+from .connections import NO_CONNECTIONS, UNSET, resolve_connections
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from sqlalchemy.ext.asyncio import AsyncEngine
+
+    from xtr_orm.database import DatabaseManager
+    from xtr_orm.migrations import AvailableMigration, ExecutionResult, MigrationPlan, Migrator
+
+__all__ = ["ConnectionCommand"]
+
+
+class ConnectionCommand:
+    """An orm command, acting on the connections a container gives it, or ``use_connections()``.
+
+    A container builds each command with the connections its bundle
+    registered; without one, the console builds it bare, and it falls back to
+    the connections set with :func:`~xtr_orm.command.use_connections`.
+    """
+
+    __slots__: ClassVar[tuple[str, ...]] = ("_connections",)
+
+    _connections: ConnectionRegistry
+
+    def __init__(self, connections: ConnectionRegistry = UNSET) -> None:
+        """Act on ``connections``, or on those set with ``use_connections()`` when omitted."""
+        self._connections = connections
+
+    async def _migrator(self, io: ConsoleStyle, connection: str | None) -> Migrator | None:
+        """Return the migrator of ``connection``, or say on ``io`` why there is none."""
+        registry = self._registry(io, connection)
+        return None if registry is None else await registry.migrator(connection)
+
+    async def _database(self, io: ConsoleStyle, connection: str | None) -> DatabaseManager | None:
+        """Return the database manager of ``connection``, or say on ``io`` why there is none."""
+        registry = self._registry(io, connection)
+        return None if registry is None else await registry.database(connection)
+
+    async def _engine(self, io: ConsoleStyle, connection: str | None) -> AsyncEngine | None:
+        """Return the engine of ``connection``, or say on ``io`` why there is none."""
+        registry = self._registry(io, connection)
+        return None if registry is None else await registry.engine(connection)
+
+    def _name(self, connection: str | None) -> str:
+        """The name ``connection`` stands for: itself, or the default connection's."""
+        registry = resolve_connections(self._connections)
+        return connection or (registry.default if registry is not None else "default")
+
+    def _registry(self, io: ConsoleStyle, connection: str | None) -> ConnectionRegistry | None:
+        registry = resolve_connections(self._connections)
+        if registry is None:
+            io.error(NO_CONNECTIONS)
+            return None
+        if not registry.has(connection):
+            io.error(escape(str(UnknownConnectionError(self._name(connection), registry.names()))))
+            return None
+        return registry
+
+
+def confirm_changes(io: ConsoleStyle, migrator: Migrator) -> bool:
+    """Ask before a migration changes the database; a run asking nothing goes ahead."""
+    return io.confirm(
+        "WARNING! You are about to execute a migration on the "
+        f'"{escape(migrator.name)}" connection that could result in schema changes and data '
+        "loss. Are you sure you wish to continue?",
+        default=True,
+    )
+
+
+def report_plan(io: ConsoleStyle, plans: Sequence[MigrationPlan]) -> None:
+    """List what a dry run would do."""
+    for plan in plans:
+        verb = "++ migrating" if plan.direction.value == "up" else "-- reverting"
+        io.text(f"  {verb} {escape(format_version(plan.version, plan.description))}")
+
+
+def report_results(io: ConsoleStyle, results: Sequence[ExecutionResult]) -> None:
+    """List what a migration did, each revision with the time it took."""
+    for result in results:
+        verb = "++ migrated" if result.direction.value == "up" else "-- reverted"
+        io.text(f"  {verb} {escape(result.version)} ({result.duration:.3f}s)")
+
+
+def save_sql(io: ConsoleStyle, target: str, sql: str) -> None:
+    """Write ``sql`` to ``target`` — a file, or a directory to put a dated file in."""
+    path = Path(target)
+    if path.is_dir():
+        path /= f"migration_{datetime.now().astimezone():%Y%m%d%H%M%S}.sql"
+    _ = path.write_text(sql, encoding="utf-8")
+    io.success(f'Wrote the migration SQL to "{escape(str(path))}".')
+
+
+def report_written(
+    io: ConsoleStyle, what: str, written: AvailableMigration, connection: str | None
+) -> None:
+    """Say where a new revision went, and how to run it alone and revert it."""
+    option = f" --connection {escape(connection)}" if connection else ""
+    version = escape(written.version)
+    io.success(f'{what} "{escape(written.path)}"')
+    io.text(
+        "To run just this migration for testing purposes, you can use "
+        f"orm:migrations:execute --up {version}{option}",
+    )
+    io.text(f"To revert the migration you can use orm:migrations:execute --down {version}{option}")
+
+
+def report_count(io: ConsoleStyle, results: Sequence[ExecutionResult]) -> None:
+    """Close a run with how many revisions ran, and how long they took together."""
+    total = sum(result.duration for result in results)
+    plural = "" if len(results) == 1 else "s"
+    io.success(f"{len(results)} migration{plural} executed in {total:.3f}s.")
+
+
+def format_version(version: str, description: str | None) -> str:
+    """Render a version with its description, as the listing commands show it."""
+    return f"{version}{_described(description)}"
+
+
+def _described(description: str | None) -> str:
+    return f" - {description}" if description else ""

xtr_orm/command/connections.py

@@ -0,0 +1,37 @@
+"""Where the orm commands find the connections they act on."""
+
+from __future__ import annotations
+
+from typing import ClassVar, Final, final
+
+from xtr_orm.connection_registry import ConnectionRegistry
+
+__all__ = ["NO_CONNECTIONS", "UNSET", "resolve_connections", "use_connections"]
+
+UNSET: Final = ConnectionRegistry()
+"""The default of every command's ``connections`` parameter, meaning "no container gave one".
+
+Typed as what a container fills the parameter with, so the engine still
+matches it; ``ConnectionRegistry | None`` is a different type and never would be.
+"""
+
+NO_CONNECTIONS: Final = (
+    "No database connections: wire a container, or call xtr_orm.command.use_connections()."
+)
+
+
+@final
+class _Process:
+    """The connections commands use where no container supplies them."""
+
+    connections: ClassVar[ConnectionRegistry | None] = None
+
+
+def use_connections(connections: ConnectionRegistry | None) -> None:
+    """Have every orm command act on ``connections`` wherever no container supplies them."""
+    _Process.connections = connections
+
+
+def resolve_connections(given: ConnectionRegistry) -> ConnectionRegistry | None:
+    """Return the connections a command was given, or those set with :func:`use_connections`."""
+    return given if given is not UNSET else _Process.connections

xtr_orm/command/database_create_command.py

@@ -0,0 +1,53 @@
+"""``orm:database:create``: create a connection's database on its server."""
+
+from __future__ import annotations
+
+from typing import final
+
+from sqlalchemy.exc import SQLAlchemyError
+from xtr_console import ConsoleStyle, ExitCode, as_command, escape
+
+from xtr_orm.exception import UnsupportedDatabaseError
+
+from .connection_command import ConnectionCommand
+
+__all__ = ["DatabaseCreateCommand"]
+
+
+@as_command("orm:database:create")
+@final
+class DatabaseCreateCommand(ConnectionCommand):
+    """Creates the configured database."""
+
+    __slots__ = ()
+
+    async def __call__(
+        self,
+        io: ConsoleStyle,
+        *,
+        if_not_exists: bool = False,
+        connection: str | None = None,
+    ) -> int:
+        """Create the configured database.
+
+        Args:
+            io: Where the command writes.
+            if_not_exists: Do nothing, successfully, when the database exists.
+            connection: The connection whose database to create; the default
+                one when left out.
+        """
+        database = await self._database(io, connection)
+        if database is None:
+            return ExitCode.FAILURE
+        name = escape(database.database)
+        where = f'for connection named "{escape(self._name(connection))}"'
+        try:
+            created = await database.create(if_not_exists=if_not_exists)
+        except (SQLAlchemyError, OSError, UnsupportedDatabaseError) as error:
+            io.error(f'Could not create database "{name}" {where}: {escape(str(error))}')
+            return ExitCode.FAILURE
+        if not created:
+            io.text(f'Database "{name}" {where} already exists. Skipped.')
+            return ExitCode.SUCCESS
+        io.success(f'Created database "{name}" {where}.')
+        return ExitCode.SUCCESS

xtr_orm/command/database_drop_command.py

@@ -0,0 +1,65 @@
+"""``orm:database:drop``: drop a connection's database from its server."""
+
+from __future__ import annotations
+
+from typing import Annotated, final
+
+from sqlalchemy.exc import SQLAlchemyError
+from xtr_console import ConsoleStyle, ExitCode, Option, as_command, escape
+
+from xtr_orm.exception import UnsupportedDatabaseError
+
+from .connection_command import ConnectionCommand
+
+__all__ = ["DatabaseDropCommand"]
+
+
+@as_command("orm:database:drop")
+@final
+class DatabaseDropCommand(ConnectionCommand):
+    """Drops the configured database."""
+
+    __slots__ = ()
+
+    async def __call__(
+        self,
+        io: ConsoleStyle,
+        *,
+        if_exists: bool = False,
+        force: Annotated[bool, Option(alias="-f")] = False,
+        connection: str | None = None,
+    ) -> int:
+        """Drop the configured database, and every table and row in it.
+
+        Refused without --force, which is the confirmation that all of it may
+        be lost.
+
+        Args:
+            io: Where the command writes.
+            if_exists: Do nothing, successfully, when the database does not
+                exist.
+            force: Really drop it.
+            connection: The connection whose database to drop; the default one
+                when left out.
+        """
+        database = await self._database(io, connection)
+        if database is None:
+            return ExitCode.FAILURE
+        name = escape(database.database)
+        where = f'for connection named "{escape(self._name(connection))}"'
+        if not force:
+            io.error(
+                f'This would drop the database "{name}" {where}, and all its data would be '
+                "lost. Run the command again with --force to drop it.",
+            )
+            return ExitCode.INVALID
+        try:
+            dropped = await database.drop(if_exists=if_exists)
+        except (SQLAlchemyError, OSError, UnsupportedDatabaseError) as error:
+            io.error(f'Could not drop database "{name}" {where}: {escape(str(error))}')
+            return ExitCode.FAILURE
+        if not dropped:
+            io.text(f'Database "{name}" {where} does not exist. Skipped.')
+            return ExitCode.SUCCESS
+        io.success(f'Dropped database "{name}" {where}.')
+        return ExitCode.SUCCESS

xtr_orm/command/migrations_current_command.py

@@ -0,0 +1,44 @@
+"""``orm:migrations:current``: the revisions the database is at."""
+
+from __future__ import annotations
+
+from typing import final
+
+from xtr_console import ConsoleStyle, ExitCode, as_command, escape
+
+from xtr_orm.exception import MigrationError
+
+from .connection_command import ConnectionCommand, format_version
+
+__all__ = ["MigrationsCurrentCommand"]
+
+
+@as_command("orm:migrations:current")
+@final
+class MigrationsCurrentCommand(ConnectionCommand):
+    """Outputs the current version."""
+
+    __slots__ = ()
+
+    async def __call__(self, io: ConsoleStyle, *, connection: str | None = None) -> int:
+        """Print the revisions the database is at, one per line — base for none.
+
+        Args:
+            io: Where the command writes.
+            connection: The connection to read; the default one when left out.
+        """
+        migrator = await self._migrator(io, connection)
+        if migrator is None:
+            return ExitCode.FAILURE
+        try:
+            status = await migrator.status()
+        except MigrationError as error:
+            io.error(escape(error.reason))
+            return ExitCode.FAILURE
+        descriptions = {each.version: each.description for each in status.available}
+        if not status.current:
+            io.text("base")
+        for version in status.current:
+            description = descriptions.get(version, "(not available)")
+            io.text(escape(format_version(version, description)))
+        return ExitCode.SUCCESS

xtr_orm/command/migrations_diff_command.py

@@ -0,0 +1,60 @@
+"""``orm:migrations:diff``: write a revision from what the table definitions add."""
+
+from __future__ import annotations
+
+from typing import final
+
+from xtr_console import ConsoleStyle, ExitCode, as_command, escape
+
+from xtr_orm.exception import MigrationError
+
+from .connection_command import ConnectionCommand, report_written
+
+__all__ = ["MigrationsDiffCommand"]
+
+
+@as_command("orm:migrations:diff")
+@final
+class MigrationsDiffCommand(ConnectionCommand):
+    """Generate a migration by comparing your current database to your mapping information."""
+
+    __slots__ = ()
+
+    async def __call__(
+        self,
+        io: ConsoleStyle,
+        *,
+        message: str | None = None,
+        allow_empty_diff: bool = False,
+        from_empty_schema: bool = False,
+        connection: str | None = None,
+    ) -> int:
+        """Compare the database with the table definitions, and write what differs as a revision.
+
+        The database must be at the latest revisions, so the comparison sees
+        what they leave out rather than what is not applied yet.
+
+        Args:
+            io: Where the command writes.
+            message: What the revision does; it names the file too.
+            allow_empty_diff: Write a revision even when nothing differs.
+            from_empty_schema: Write every table, as if the database were
+                empty.
+            connection: The connection to compare; the default one when left
+                out.
+        """
+        migrator = await self._migrator(io, connection)
+        if migrator is None:
+            return ExitCode.FAILURE
+        try:
+            written = await migrator.diff(
+                message, allow_empty=allow_empty_diff, from_empty_schema=from_empty_schema
+            )
+        except MigrationError as error:
+            io.error(escape(error.reason))
+            return ExitCode.FAILURE
+        if written is None:
+            io.error("No changes detected in your mapping information.")
+            return ExitCode.FAILURE
+        report_written(io, "Generated new migration class to", written, connection)
+        return ExitCode.SUCCESS

xtr_orm/command/migrations_dump_schema_command.py

@@ -0,0 +1,56 @@
+"""``orm:migrations:dump-schema``: write a first revision from an existing database."""
+
+from __future__ import annotations
+
+from typing import final
+
+from xtr_console import ConsoleStyle, ExitCode, as_command, escape
+
+from xtr_orm.exception import MigrationError
+
+from .connection_command import ConnectionCommand, report_written
+
+__all__ = ["MigrationsDumpSchemaCommand"]
+
+
+@as_command("orm:migrations:dump-schema")
+@final
+class MigrationsDumpSchemaCommand(ConnectionCommand):
+    """Dump the schema for your database to a migration."""
+
+    __slots__ = ()
+
+    async def __call__(
+        self,
+        io: ConsoleStyle,
+        *,
+        message: str | None = None,
+        filter_tables: list[str] | None = None,
+        connection: str | None = None,
+    ) -> int:
+        """Write a first revision creating every table the database has.
+
+        For a database that predates its revisions, so there must be none
+        yet. The revision is written, not applied: record it as applied with
+        orm:migrations:rollup.
+
+        Args:
+            io: Where the command writes.
+            message: What the revision does; it names the file too.
+            filter_tables: A regular expression; only the tables whose name it
+                finds are dumped. Repeat for several.
+            connection: The connection whose database to dump; the default one
+                when left out.
+        """
+        migrator = await self._migrator(io, connection)
+        if migrator is None:
+            return ExitCode.FAILURE
+        try:
+            written = await migrator.dump_schema(message, table_filters=filter_tables or ())
+        except MigrationError as error:
+            io.error(escape(error.reason))
+            return ExitCode.FAILURE
+        report_written(io, "Dumped your schema to a new migration class at", written, connection)
+        option = f" --connection {escape(connection)}" if connection else ""
+        io.text(f"To use this as a rollup migration you can use orm:migrations:rollup{option}")
+        return ExitCode.SUCCESS