xtr-orm 1.5.0__py3-none-any.whl

xtr_orm/command/run_sql_command.py

@@ -0,0 +1,77 @@
+"""``orm:run-sql``: run a statement and show what it returned."""
+
+from __future__ import annotations
+
+from typing import Any, cast, final
+
+from sqlalchemy import Row, text
+from sqlalchemy.exc import SQLAlchemyError
+from xtr_console import ConsoleStyle, ExitCode, as_command, escape
+
+from .connection_command import ConnectionCommand
+
+__all__ = ["RunSqlCommand"]
+
+
+@as_command("orm:run-sql")
+@final
+class RunSqlCommand(ConnectionCommand):
+    """Executes arbitrary SQL directly from the command line."""
+
+    __slots__ = ()
+
+    async def __call__(
+        self,
+        io: ConsoleStyle,
+        sql: str,
+        *,
+        force_fetch: bool = False,
+        connection: str | None = None,
+    ) -> int:
+        """Run the statement, committed, and show its rows or how many it changed.
+
+        Args:
+            io: Where the command writes.
+            sql: The statement to run.
+            force_fetch: Show the result as rows even when the statement
+                does not look like it returns any.
+            connection: The connection to run it on; the default one when
+                left out.
+        """
+        engine = await self._engine(io, connection)
+        if engine is None:
+            return ExitCode.FAILURE
+        columns: list[str] = []
+        rows: list[list[str]] = []
+        affected = 0
+        try:
+            async with engine.begin() as opened:
+                result = await opened.execute(text(sql))
+                if result.returns_rows:
+                    columns = [str(column) for column in result.keys()]  # noqa: SIM118 — a result's keys are its columns, not a dict's
+                    rows = [[_cell(value) for value in _values(row)] for row in result.all()]
+                else:
+                    affected = result.rowcount
+        except SQLAlchemyError as error:
+            io.error(escape(str(error)))
+            return ExitCode.FAILURE
+        if not columns and not force_fetch:
+            # A driver that cannot tell — after a schema change, say — reports -1.
+            if affected < 0:
+                io.success("The statement was executed.")
+            else:
+                io.success(f"{affected} row{'' if affected == 1 else 's'} affected.")
+            return ExitCode.SUCCESS
+        if not rows:
+            io.success("The query yielded an empty result set.")
+            return ExitCode.SUCCESS
+        io.table([escape(column) for column in columns], rows)
+        return ExitCode.SUCCESS
+
+
+def _values(row: Row[Any]) -> tuple[object, ...]:  # pyright: ignore[reportExplicitAny] -- a row of a text statement has no known column types
+    return tuple(cast("tuple[object, ...]", row))
+
+
+def _cell(value: object) -> str:
+    return "NULL" if value is None else escape(str(value))

xtr_orm/connection_registry.py

@@ -0,0 +1,192 @@
+"""Every configured connection by name, each piece built only when first asked for."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final, TypeVar, cast, final
+
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession
+
+from xtr_orm.database import DatabaseManager
+from xtr_orm.exception import (
+    InvalidArgumentError,
+    SessionUnavailableError,
+    UnknownConnectionError,
+)
+from xtr_orm.migrations import Migrator
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+__all__ = ["DEFAULT_CONNECTION", "ConnectionRegistry"]
+
+DEFAULT_CONNECTION: Final = "default"
+"""The name of the connection used when none is named."""
+
+_T = TypeVar("_T")
+
+
+@dataclass(frozen=True, slots=True)
+class _Connection:
+    engine: Callable[[], Awaitable[AsyncEngine]]
+    migrator: Callable[[], Awaitable[Migrator]]
+    database: Callable[[], Awaitable[DatabaseManager]]
+    session: Callable[[], Awaitable[AsyncSession]] | None
+    close: Callable[[], Awaitable[None]] | None
+
+
+@final
+class ConnectionRegistry:
+    """Every connection by name: its engine, its migrator and its database manager.
+
+    Each is given as the object itself, or as an async function building it —
+    called only when that piece is first asked for, so a command touching one
+    connection opens nothing of another's.
+
+    A connection may also say how to reach the session of the current unit
+    of work — the one every handler of a message shares — and how to close
+    it, releasing every connection it holds; the message bus middleware use
+    both.
+
+    ```python
+    registry = ConnectionRegistry()
+    registry.register(
+        "default",
+        engine=engine,
+        migrator=Migrator(engine, MigrationsConfig(directory="migrations")),
+        database=DatabaseManager(url),
+    )
+    ```
+    """
+
+    __slots__ = ("_connections", "_default")
+
+    _connections: dict[str, _Connection]
+    _default: str
+
+    def __init__(self, default: str = DEFAULT_CONNECTION) -> None:
+        """Hold connections, answering for ``default`` when none is named."""
+        self._connections = {}
+        self._default = default
+
+    @property
+    def default(self) -> str:
+        """The name of the connection used when none is named."""
+        return self._default
+
+    def register(  # noqa: PLR0913 — one keyword per piece of a connection
+        self,
+        name: str,
+        *,
+        engine: AsyncEngine | Callable[[], Awaitable[AsyncEngine]],
+        migrator: Migrator | Callable[[], Awaitable[Migrator]],
+        database: DatabaseManager | Callable[[], Awaitable[DatabaseManager]],
+        session: Callable[[], Awaitable[AsyncSession]] | None = None,
+        close: Callable[[], Awaitable[None]] | None = None,
+    ) -> None:
+        """Add the connection ``name``, or replace it.
+
+        Args:
+            name: What the connection is known by.
+            engine: Its engine, or what builds it.
+            migrator: Its migrator, or what builds it.
+            database: Its database manager, or what builds it.
+            session: What returns the session of the unit of work under way;
+                without it, :meth:`session` is refused.
+            close: What closes the connection; its engine is disposed when
+                left out.
+
+        Raises:
+            InvalidArgumentError: When ``name`` is empty.
+        """
+        if not name:
+            raise InvalidArgumentError("A connection needs a non-empty name.")
+        self._connections[name] = _Connection(
+            engine=_provider(engine, AsyncEngine),
+            migrator=_provider(migrator, Migrator),
+            database=_provider(database, DatabaseManager),
+            session=session,
+            close=close,
+        )
+
+    def names(self) -> tuple[str, ...]:
+        """Every connection's name, in the order registered."""
+        return tuple(self._connections)
+
+    def has(self, name: str | None = None) -> bool:
+        """Whether the connection ``name`` — the default one when ``None`` — exists."""
+        return (name or self._default) in self._connections
+
+    async def engine(self, name: str | None = None) -> AsyncEngine:
+        """Return the engine of the connection ``name``, the default one when ``None``.
+
+        Raises:
+            UnknownConnectionError: When no connection has that name.
+        """
+        return await self._get(name).engine()
+
+    async def migrator(self, name: str | None = None) -> Migrator:
+        """Return the migrator of the connection ``name``, the default one when ``None``.
+
+        Raises:
+            UnknownConnectionError: When no connection has that name.
+        """
+        return await self._get(name).migrator()
+
+    async def database(self, name: str | None = None) -> DatabaseManager:
+        """Return the database manager of the connection ``name``, the default one when ``None``.
+
+        Raises:
+            UnknownConnectionError: When no connection has that name.
+        """
+        return await self._get(name).database()
+
+    async def session(self, name: str | None = None) -> AsyncSession:
+        """Return the session of the current unit of work on the connection ``name``.
+
+        Raises:
+            UnknownConnectionError: When no connection has that name.
+            SessionUnavailableError: When the connection was registered
+                without a way to reach one.
+        """
+        wanted = name or self._default
+        provide = self._get(name).session
+        if provide is None:
+            raise SessionUnavailableError(wanted, "it was registered without a session")
+        return await provide()
+
+    async def close(self, name: str | None = None) -> None:
+        """Close the connection ``name``: release every database connection its pools hold.
+
+        The engine stays usable; its next use connects again.
+
+        Raises:
+            UnknownConnectionError: When no connection has that name.
+        """
+        connection = self._get(name)
+        if connection.close is not None:
+            await connection.close()
+            return
+        await (await connection.engine()).dispose()
+
+    def _get(self, name: str | None) -> _Connection:
+        wanted = name or self._default
+        found = self._connections.get(wanted)
+        if found is None:
+            raise UnknownConnectionError(wanted, self.names())
+        return found
+
+
+def _provider(
+    given: _T | Callable[[], Awaitable[_T]], kind: type[_T]
+) -> Callable[[], Awaitable[_T]]:
+    """Return an async function giving ``given``: itself when it is one, else wrapping it."""
+    if isinstance(given, kind):
+        instance = given
+
+        async def provide() -> _T:
+            return instance
+
+        return provide
+    # Anything not of the built kind is the function building it, as the signature says.
+    return cast("Callable[[], Awaitable[_T]]", given)

xtr_orm/database/__init__.py

@@ -0,0 +1,7 @@
+"""Creating and dropping the database a connection URL names."""
+
+from __future__ import annotations
+
+from .database_manager import DatabaseManager
+
+__all__ = ["DatabaseManager"]

xtr_orm/database/database_manager.py

@@ -0,0 +1,196 @@
+"""Creating and dropping the database a connection URL names."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Final, final
+
+from sqlalchemy import URL, make_url, text
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy.pool import NullPool
+
+from xtr_orm.exception import InvalidArgumentError, UnsupportedDatabaseError
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator, Mapping
+
+    from sqlalchemy.ext.asyncio import AsyncConnection
+
+__all__ = ["DatabaseManager"]
+
+_MEMORY: Final = frozenset({"", ":memory:"})
+
+
+@dataclass(frozen=True, slots=True)
+class _Server:
+    """How to reach a kind of server without its database, and ask it about one."""
+
+    maintenance_database: str | None
+    exists: str
+
+
+_SERVERS: Final[dict[str, _Server]] = {
+    "postgresql": _Server("postgres", "SELECT 1 FROM pg_database WHERE datname = :name"),
+    "mysql": _Server(None, "SELECT 1 FROM information_schema.schemata WHERE schema_name = :name"),
+    "mariadb": _Server(None, "SELECT 1 FROM information_schema.schemata WHERE schema_name = :name"),
+    "mssql": _Server("master", "SELECT 1 FROM sys.databases WHERE name = :name"),
+}
+
+
+@final
+class DatabaseManager:
+    """Creates and drops the database a connection URL names, on its server.
+
+    A database cannot be created from a connection to itself, so the server
+    is reached through its maintenance database — ``postgres`` on
+    PostgreSQL, ``master`` on SQL Server, none on MySQL and MariaDB — with
+    every statement committed as it runs. A SQLite database is its file.
+
+    ```python
+    manager = DatabaseManager("postgresql+asyncpg://app:secret@db/shop")
+    await manager.create(if_not_exists=True)
+    ```
+    """
+
+    __slots__ = ("_connect_args", "_url")
+
+    _url: URL
+    _connect_args: Mapping[str, object]
+
+    def __init__(self, url: str | URL, *, connect_args: Mapping[str, object] | None = None) -> None:
+        """Manage the database ``url`` names, connecting with ``connect_args``.
+
+        Raises:
+            InvalidArgumentError: When the URL names no database on a server.
+        """
+        self._url = make_url(url)
+        self._connect_args = connect_args or {}
+        if self.backend != "sqlite" and not self._url.database:
+            raise InvalidArgumentError(
+                f"The URL {self.safe_url} names no database to create or drop.",
+            )
+
+    @property
+    def backend(self) -> str:
+        """The kind of server, such as ``"postgresql"`` or ``"sqlite"``."""
+        return self._url.get_backend_name()
+
+    @property
+    def database(self) -> str:
+        """The database's name — for SQLite, its file."""
+        return self._url.database or ""
+
+    @property
+    def safe_url(self) -> str:
+        """The URL with its password hidden, fit for a message."""
+        return self._url.render_as_string(hide_password=True)
+
+    async def exists(self) -> bool:
+        """Whether the database exists.
+
+        Raises:
+            UnsupportedDatabaseError: For a server this library cannot ask.
+        """
+        if self.backend == "sqlite":
+            path = self._sqlite_path()
+            return path is None or path.exists()
+        server = self._server("check")
+        async with self._maintenance() as connection:
+            found = await connection.execute(text(server.exists), {"name": self.database})
+            return found.first() is not None
+
+    async def create(self, *, if_not_exists: bool = False) -> bool:
+        """Create the database; return whether it was created.
+
+        Args:
+            if_not_exists: Leave an existing database alone and return
+                ``False``, rather than let the server refuse.
+
+        Raises:
+            UnsupportedDatabaseError: For a server this library cannot ask.
+        """
+        if if_not_exists and await self.exists():
+            return False
+        if self.backend == "sqlite":
+            self._create_file()
+            return True
+        _ = self._server("create")
+        async with self._maintenance() as connection:
+            name = connection.dialect.identifier_preparer.quote(self.database)
+            _ = await connection.execute(text(f"CREATE DATABASE {name}"))
+        return True
+
+    async def drop(self, *, if_exists: bool = False) -> bool:
+        """Drop the database; return whether it was dropped.
+
+        Args:
+            if_exists: Do nothing for a database that does not exist and
+                return ``False``, rather than let the server refuse.
+
+        Raises:
+            UnsupportedDatabaseError: For a server this library cannot ask.
+        """
+        if if_exists and not await self.exists():
+            return False
+        if self.backend == "sqlite":
+            self._remove_file()
+            return True
+        _ = self._server("drop")
+        async with self._maintenance() as connection:
+            name = connection.dialect.identifier_preparer.quote(self.database)
+            _ = await connection.execute(text(f"DROP DATABASE {name}"))
+        return True
+
+    def _server(self, operation: str) -> _Server:
+        server = _SERVERS.get(self.backend)
+        if server is None:
+            raise UnsupportedDatabaseError(self.backend, operation)
+        return server
+
+    @asynccontextmanager
+    async def _maintenance(self) -> AsyncGenerator[AsyncConnection]:
+        """Connect to the server's maintenance database, committing every statement."""
+        server = _SERVERS[self.backend]
+        url = self._url
+        # ``set`` keeps a database it is given None for, so the URL is rebuilt.
+        maintenance = URL.create(
+            url.drivername,
+            username=url.username,
+            password=url.password,
+            host=url.host,
+            port=url.port,
+            database=server.maintenance_database,
+            query=url.query,
+        )
+        engine = create_async_engine(
+            maintenance,
+            poolclass=NullPool,
+            isolation_level="AUTOCOMMIT",
+            connect_args=dict(self._connect_args),
+        )
+        try:
+            async with engine.connect() as connection:
+                yield connection
+        finally:
+            await engine.dispose()
+
+    def _sqlite_path(self) -> Path | None:
+        """Return the SQLite file, or ``None`` for a database kept in memory."""
+        if self.database in _MEMORY or self.database.startswith("file::memory:"):
+            return None
+        return Path(self.database.removeprefix("file:").split("?", 1)[0])
+
+    def _create_file(self) -> None:
+        """Create the SQLite file, refusing one that exists; nothing for one in memory."""
+        path = self._sqlite_path()
+        if path is not None:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.touch(exist_ok=False)
+
+    def _remove_file(self) -> None:
+        """Remove the SQLite file; nothing for one in memory."""
+        path = self._sqlite_path()
+        if path is not None:
+            path.unlink()

xtr_orm/exception/__init__.py

@@ -0,0 +1,19 @@
+"""Every error this library raises, all deriving from :class:`OrmError`."""
+
+from __future__ import annotations
+
+from .invalid_argument_error import InvalidArgumentError
+from .migration_error import MigrationError
+from .orm_error import OrmError
+from .session_unavailable_error import SessionUnavailableError
+from .unknown_connection_error import UnknownConnectionError
+from .unsupported_database_error import UnsupportedDatabaseError
+
+__all__ = [
+    "InvalidArgumentError",
+    "MigrationError",
+    "OrmError",
+    "SessionUnavailableError",
+    "UnknownConnectionError",
+    "UnsupportedDatabaseError",
+]

xtr_orm/exception/invalid_argument_error.py

@@ -0,0 +1,28 @@
+"""A configuration or a call was given something the library cannot work with."""
+
+from __future__ import annotations
+
+from .orm_error import OrmError
+
+__all__ = ["InvalidArgumentError"]
+
+
+class InvalidArgumentError(OrmError, ValueError):
+    """A configuration or a call was given something the library cannot work with.
+
+    Raised where the value is given — a connection without a name, a version
+    table without a name — rather than when a database is first reached.
+
+    Also a :class:`ValueError`, so code that already guards its configuration
+    with ``except ValueError`` keeps working without learning a new exception.
+
+    Attributes:
+        reason: What is wrong with the value.
+    """
+
+    reason: str
+
+    def __init__(self, reason: str) -> None:
+        """Record what is wrong with the value."""
+        self.reason = reason
+        super().__init__(reason)

xtr_orm/exception/migration_error.py

@@ -0,0 +1,28 @@
+"""A migration operation was refused, or its revisions could not be read."""
+
+from __future__ import annotations
+
+from .orm_error import OrmError
+
+__all__ = ["MigrationError"]
+
+
+class MigrationError(OrmError):
+    """A migration operation was refused, or its revisions could not be read.
+
+    Raised before anything is changed whenever it can be decided up front: a
+    version that no revision answers to, a revision run out of order, a diff
+    against a database that is behind its revisions. Nothing is written when
+    it is raised from a check; a failing revision rolls back what the
+    database lets it.
+
+    Attributes:
+        reason: Why the operation was refused.
+    """
+
+    reason: str
+
+    def __init__(self, reason: str) -> None:
+        """Record why the operation was refused."""
+        self.reason = reason
+        super().__init__(reason)

xtr_orm/exception/orm_error.py

@@ -0,0 +1,14 @@
+"""The root every error in this library derives from."""
+
+from __future__ import annotations
+
+__all__ = ["OrmError"]
+
+
+class OrmError(Exception):
+    """Base class for every error raised by this library.
+
+    Catch this to handle anything the library can refuse; catch a subclass to
+    handle one cause. Every subclass carries the data a caller needs as typed
+    attributes and composes its own message from them.
+    """

xtr_orm/exception/session_unavailable_error.py

@@ -0,0 +1,29 @@
+"""The session of the current unit of work was asked for where there is none."""
+
+from __future__ import annotations
+
+from .orm_error import OrmError
+
+__all__ = ["SessionUnavailableError"]
+
+
+class SessionUnavailableError(OrmError):
+    """The session of the current unit of work was asked for where there is none.
+
+    A connection reaches the session everything in a unit of work shares —
+    a message's handlers, say — only inside one, and only when it was
+    registered with a way to.
+
+    Attributes:
+        connection: The connection the session was asked of.
+        reason: Why there is none.
+    """
+
+    connection: str
+    reason: str
+
+    def __init__(self, connection: str, reason: str) -> None:
+        """Record which connection was asked, and why it has no session to give."""
+        self.connection = connection
+        self.reason = reason
+        super().__init__(f'The "{connection}" connection has no session here: {reason}.')

xtr_orm/exception/unknown_connection_error.py

@@ -0,0 +1,28 @@
+"""A connection was asked for by a name nothing registered."""
+
+from __future__ import annotations
+
+from .orm_error import OrmError
+
+__all__ = ["UnknownConnectionError"]
+
+
+class UnknownConnectionError(OrmError, LookupError):
+    """A connection was asked for by a name nothing registered.
+
+    Also a :class:`LookupError`, as a missing key in any other mapping is.
+
+    Attributes:
+        name: The name asked for.
+        known: Every name that is registered.
+    """
+
+    name: str
+    known: tuple[str, ...]
+
+    def __init__(self, name: str, known: tuple[str, ...]) -> None:
+        """Record the name asked for and the ones that exist."""
+        self.name = name
+        self.known = known
+        names = ", ".join(f'"{each}"' for each in known) or "none"
+        super().__init__(f'Unknown connection "{name}"; the connections are: {names}.')

xtr_orm/exception/unsupported_database_error.py

@@ -0,0 +1,29 @@
+"""A database server was asked for something this library cannot do on it."""
+
+from __future__ import annotations
+
+from .orm_error import OrmError
+
+__all__ = ["UnsupportedDatabaseError"]
+
+
+class UnsupportedDatabaseError(OrmError):
+    """A database server was asked for something this library cannot do on it.
+
+    Creating or dropping a database takes a statement of the server's own;
+    a server whose statement is not known here is refused rather than sent a
+    guess.
+
+    Attributes:
+        backend: The kind of server the URL names, such as ``"oracle"``.
+        operation: What was asked, such as ``"create"``.
+    """
+
+    backend: str
+    operation: str
+
+    def __init__(self, backend: str, operation: str) -> None:
+        """Record which server was asked for what."""
+        self.backend = backend
+        self.operation = operation
+        super().__init__(f'Cannot {operation} a database on "{backend}": it is not supported.')

xtr_orm/messenger/__init__.py

@@ -0,0 +1,23 @@
+"""Message bus middleware for the connections: transactions, closing, and open transactions.
+
+Importing this module declares them by name — ``orm_transaction``,
+``orm_close_connection`` and ``orm_open_transaction_logger`` — for a bus
+configuration to list. With a container, the orm bundle loads it when the
+messenger bundle is active, and the messenger bundle registers each by that
+name. Without one, build them with a :class:`~xtr_orm.ConnectionRegistry`
+and put the instances in the configuration.
+
+Needs the ``messenger`` extra: ``xtr-orm[messenger]``.
+"""
+
+from __future__ import annotations
+
+from .close_connection_middleware import CloseConnectionMiddleware
+from .open_transaction_logger_middleware import OpenTransactionLoggerMiddleware
+from .transaction_middleware import TransactionMiddleware
+
+__all__ = [
+    "CloseConnectionMiddleware",
+    "OpenTransactionLoggerMiddleware",
+    "TransactionMiddleware",
+]