pyoq-sql 1.0.2__py3-none-any.whl

pyoq/migrations/alembic.py

@@ -0,0 +1,106 @@
+"""Bringing PyOQ back in step around an Alembic migration.
+
+Alembic changes a database in `alembic upgrade`. It does not change one in
+`alembic revision`, and a post write hook runs there: Alembic hands each hook
+the revision file it has just written, while the database is still whatever it
+was. Recording the schema at that moment records the schema the migration is
+about to replace, and generates from it, which is why this is not a post write
+hook.
+
+The step belongs after the upgrade. Alembic offers two places for one.
+
+In `env.py`, which the project owns, once the migrations have run:
+
+    from pyoq.migrations import after_migration_at
+
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+        with context.begin_transaction():
+            context.run_migrations()
+    after_migration_at(PROJECT_ROOT)
+
+Or as a step of its own, after the upgrade has finished:
+
+    alembic upgrade head && pyoq-after-migration
+
+The command takes the project directory, or nothing and uses the working
+directory. Being handed a file is how a post write hook calls a command, so
+that is refused and says why rather than recording the schema a migration has
+not yet reached.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import IO, NoReturn
+
+from pyoq.errors import ConfigurationFileError, PyOQError
+from pyoq.migrations.hooks import after_migration_at
+
+_PYPROJECT = "pyproject.toml"
+
+
+def main(
+    arguments: list[str] | None = None,
+    *,
+    output: IO[str] | None = None,
+    error: IO[str] | None = None,
+) -> int:
+    """Bring the snapshot and the generated package back in step."""
+    written = sys.stdout if output is None else output
+    failed = sys.stderr if error is None else error
+    given = sys.argv[1:] if arguments is None else arguments
+    try:
+        root = _project_root(given)
+        outcome = after_migration_at(root)
+    except PyOQError as problem:
+        failed.write(f"pyoq: {problem}\n")
+        return 1
+    written.write(f"{outcome.describe()}\n")
+    return 0
+
+
+def run() -> NoReturn:
+    raise SystemExit(main())
+
+
+def _project_root(arguments: list[str]) -> Path:
+    """The project to bring back in step, named by a directory inside it."""
+    if not arguments:
+        return _declaring(Path.cwd())
+    given = Path(arguments[0]).resolve()
+    _require_directory(given)
+    return _declaring(given)
+
+
+def _require_directory(given: Path) -> None:
+    """A file is what a post write hook passes, and that is the wrong moment.
+
+    Alembic runs a post write hook inside `alembic revision`, handing it the
+    revision it has just written. The database has not been upgraded yet, so
+    recording it there records the schema this migration replaces.
+    """
+    if given.is_dir():
+        return
+    message = (
+        f"{given} is not a directory. This command takes the project to bring "
+        "back in step, and runs after a migration has been applied. Alembic "
+        "passes a written revision to a post write hook, which runs inside "
+        "`alembic revision` while the database is still what it was, so this "
+        "is not one. Run it after `alembic upgrade`, or call "
+        "`after_migration_at` from `env.py` once the migrations have run."
+    )
+    raise ConfigurationFileError(message)
+
+
+def _declaring(directory: Path) -> Path:
+    """The first directory at or above this one that a project declares itself in."""
+    for candidate in (directory, *directory.parents):
+        if (candidate / _PYPROJECT).is_file():
+            return candidate
+    message = f"no {_PYPROJECT} at or above {directory}"
+    raise ConfigurationFileError(message)
+
+
+__all__ = ("main", "run")

pyoq/migrations/hooks.py

@@ -0,0 +1,75 @@
+"""Bringing generated code back in step after a migration runs.
+
+A migration changes the schema, which makes the generated package stale and
+the recorded snapshot wrong. Every migration tool has somewhere to run a step
+after it writes or applies, and each of them needs the same two things done,
+so the work lives here once and the tools call it.
+
+Nothing here imports a migration tool. A hook is an ordinary callable a
+project wires up, so Alembic, Django, a shell script, or a CI job all reach
+the same code and none of them is a dependency.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pyoq.cli.services import CommandServices
+from pyoq.config import load_configuration
+from pyoq.generation import GenerationMode
+
+if TYPE_CHECKING:
+    from pyoq.config import Configuration
+
+
+@dataclass(frozen=True, slots=True)
+class MigrationOutcome:
+    """What the hook did, in the words each step reported."""
+
+    recorded: str
+    generated: str
+
+    def describe(self) -> str:
+        return f"{self.recorded}; {self.generated}"
+
+
+def after_migration(
+    configuration: Configuration,
+    /,
+    *,
+    services: CommandServices | None = None,
+) -> MigrationOutcome:
+    """Record the schema again and bring the generated package back in step.
+
+    Both, and in that order: the snapshot is what generation reads offline, so
+    a package regenerated before the snapshot is written would be generated
+    from the schema that has just been replaced.
+    """
+    running = services or CommandServices.defaults()
+    recorded = running.snapshot.execute(configuration)
+    generated = running.generation.execute(configuration, GenerationMode.WRITE)
+    return MigrationOutcome(recorded, generated)
+
+
+def after_migration_at(
+    project_root: Path | str,
+    /,
+    *,
+    selected_profile: str | None = None,
+    services: CommandServices | None = None,
+) -> MigrationOutcome:
+    """The same, for a caller that has a project directory and no configuration.
+
+    Migration tools know where the project is and nothing about PyOQ's
+    configuration, so this loads it the way the command line does.
+    """
+    configuration = load_configuration(
+        Path(project_root),
+        selected_profile=selected_profile,
+    )
+    return after_migration(configuration, services=services)
+
+
+__all__ = ("MigrationOutcome", "after_migration", "after_migration_at")

pyoq/naming.py

@@ -0,0 +1,261 @@
+"""Deterministic database-to-Python naming policy."""
+
+from __future__ import annotations
+
+import keyword
+import unicodedata
+from collections.abc import Iterable
+from dataclasses import dataclass
+from enum import StrEnum
+
+from pyoq.errors import NamingCollisionError, NamingValidationError
+from pyoq.schema import Identifier
+
+
+class PythonNameStyle(StrEnum):
+    SNAKE_CASE = "snake-case"
+    PASCAL_CASE = "pascal-case"
+    UPPER_SNAKE_CASE = "upper-snake-case"
+
+
+@dataclass(frozen=True, slots=True)
+class NameRequest:
+    key: str
+    source: Identifier
+
+    def __post_init__(self) -> None:
+        _require_text(self.key, "name request key")
+
+
+@dataclass(frozen=True, slots=True)
+class NamingScope:
+    name: str
+    style: PythonNameStyle
+    requests: tuple[NameRequest, ...]
+    reserved_names: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        _require_text(self.name, "naming scope")
+        _require_unique_request_keys(self.requests, self.name)
+        canonical_reserved_names = _canonical_reserved_names(self.reserved_names)
+        object.__setattr__(self, "reserved_names", canonical_reserved_names)
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class ResolvedName:
+    scope: str
+    key: str
+    source: Identifier
+    python_name: str
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class NameCollision:
+    scope: str
+    python_name: str
+    requests: tuple[NameRequest, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class NamingResult:
+    names: tuple[ResolvedName, ...]
+
+    def get(self, scope: str, key: str) -> str:
+        for resolved_name in self.names:
+            if resolved_name.scope == scope and resolved_name.key == key:
+                return resolved_name.python_name
+        message = f"no generated name exists for scope {scope!r} and key {key!r}"
+        raise KeyError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class NamingPolicy:
+    """Resolve complete naming scopes without retaining mutable state."""
+
+    def resolve(self, scopes: tuple[NamingScope, ...]) -> NamingResult:
+        _require_unique_scope_names(scopes)
+        resolved_names: list[ResolvedName] = []
+        collisions: list[NameCollision] = []
+        for scope in sorted(scopes, key=lambda candidate: candidate.name):
+            scope_names, scope_collisions = _resolve_scope(scope)
+            resolved_names.extend(scope_names)
+            collisions.extend(scope_collisions)
+        if collisions:
+            ordered_collisions = tuple(sorted(collisions))
+            raise NamingCollisionError(
+                _collision_message(ordered_collisions),
+                ordered_collisions,
+            )
+        return NamingResult(tuple(sorted(resolved_names)))
+
+
+def _resolve_scope(
+    scope: NamingScope,
+) -> tuple[list[ResolvedName], list[NameCollision]]:
+    grouped_requests: dict[str, list[NameRequest]] = {}
+    reserved_names = frozenset(scope.reserved_names)
+    for request in scope.requests:
+        python_name = _resolve_python_name(
+            request.source.value,
+            scope.style,
+            reserved_names,
+        )
+        grouped_requests.setdefault(python_name, []).append(request)
+    return _partition_scope_names(scope.name, grouped_requests)
+
+
+def _partition_scope_names(
+    scope_name: str,
+    grouped_requests: dict[str, list[NameRequest]],
+) -> tuple[list[ResolvedName], list[NameCollision]]:
+    resolved_names: list[ResolvedName] = []
+    collisions: list[NameCollision] = []
+    for python_name, requests in sorted(grouped_requests.items()):
+        ordered_requests = tuple(sorted(requests, key=lambda request: request.key))
+        if len(ordered_requests) > 1:
+            collisions.append(NameCollision(scope_name, python_name, ordered_requests))
+            continue
+        request = next(iter(ordered_requests))
+        resolved_names.append(
+            ResolvedName(scope_name, request.key, request.source, python_name)
+        )
+    return resolved_names, collisions
+
+
+def _resolve_python_name(
+    source: str,
+    style: PythonNameStyle,
+    reserved_names: frozenset[str],
+) -> str:
+    words = _identifier_words(source)
+    styled_name = _apply_style(words, style)
+    python_name = _prefix_leading_digit(styled_name)
+    while _is_reserved(python_name, reserved_names):
+        python_name += "_"
+    return python_name
+
+
+def _identifier_words(source: str) -> tuple[str, ...]:
+    normalized_source = unicodedata.normalize("NFKC", source)
+    words: list[str] = []
+    current_word: list[str] = []
+    for index, character in enumerate(normalized_source):
+        if not _is_word_character(character, bool(current_word)):
+            _finish_word(words, current_word)
+            continue
+        if current_word and _starts_word(normalized_source, index):
+            _finish_word(words, current_word)
+        current_word.append(character)
+    _finish_word(words, current_word)
+    return tuple(words) or ("unnamed",)
+
+
+def _is_word_character(character: str, word_started: bool) -> bool:
+    if character == "_":
+        return False
+    if word_started:
+        return f"a{character}".isidentifier()
+    return character.isidentifier() or character.isdecimal()
+
+
+def _starts_word(source: str, index: int) -> bool:
+    previous = source[index - 1]
+    current = source[index]
+    following = source[index + 1] if index + 1 < len(source) else ""
+    if previous.isdigit() != current.isdigit():
+        return True
+    if previous.islower() and current.isupper():
+        return True
+    return previous.isupper() and current.isupper() and following.islower()
+
+
+def _finish_word(words: list[str], current_word: list[str]) -> None:
+    if current_word:
+        words.append("".join(current_word))
+        current_word.clear()
+
+
+def _apply_style(words: tuple[str, ...], style: PythonNameStyle) -> str:
+    if style is PythonNameStyle.SNAKE_CASE:
+        return "_".join(word.lower() for word in words)
+    if style is PythonNameStyle.UPPER_SNAKE_CASE:
+        return "_".join(word.upper() for word in words)
+    return "".join(_capitalize_word(word) for word in words)
+
+
+def _capitalize_word(word: str) -> str:
+    return word[:1].upper() + word[1:].lower()
+
+
+def _prefix_leading_digit(name: str) -> str:
+    return f"_{name}" if name[0].isdigit() else name
+
+
+def _is_reserved(name: str, reserved_names: frozenset[str]) -> bool:
+    return (
+        keyword.iskeyword(name) or keyword.issoftkeyword(name) or name in reserved_names
+    )
+
+
+def _canonical_reserved_names(names: tuple[object, ...]) -> tuple[str, ...]:
+    valid_names: list[str] = []
+    for name in names:
+        if not isinstance(name, str) or not name.isidentifier():
+            message = f"reserved Python name must be a valid identifier: {name!r}"
+            raise NamingValidationError(message)
+        valid_names.append(name)
+    return tuple(sorted(set(valid_names)))
+
+
+def _require_unique_request_keys(requests: tuple[NameRequest, ...], scope: str) -> None:
+    duplicate_keys = _duplicate_values(request.key for request in requests)
+    if duplicate_keys:
+        message = (
+            f"naming scope {scope!r} contains duplicate request keys: "
+            f"{duplicate_keys!r}"
+        )
+        raise NamingValidationError(message)
+
+
+def _require_unique_scope_names(scopes: tuple[NamingScope, ...]) -> None:
+    duplicate_names = _duplicate_values(scope.name for scope in scopes)
+    if duplicate_names:
+        message = f"naming batch contains duplicate scopes: {duplicate_names!r}"
+        raise NamingValidationError(message)
+
+
+def _duplicate_values(values: Iterable[str]) -> list[str]:
+    seen: set[str] = set()
+    duplicates: set[str] = set()
+    for value in values:
+        if value in seen:
+            duplicates.add(value)
+        seen.add(value)
+    return sorted(duplicates)
+
+
+def _collision_message(collisions: tuple[NameCollision, ...]) -> str:
+    descriptions: list[str] = []
+    for collision in collisions:
+        request_keys = ", ".join(request.key for request in collision.requests)
+        descriptions.append(
+            f"{collision.scope!r}.{collision.python_name} from [{request_keys}]"
+        )
+    return "generated name collisions: " + "; ".join(descriptions)
+
+
+def _require_text(value: object, label: str) -> None:
+    if not isinstance(value, str) or not value:
+        message = f"{label} must be a non-empty string"
+        raise NamingValidationError(message)
+
+
+__all__ = (
+    "NameCollision",
+    "NameRequest",
+    "NamingPolicy",
+    "NamingResult",
+    "NamingScope",
+    "PythonNameStyle",
+    "ResolvedName",
+)

pyoq/policies/__init__.py

@@ -0,0 +1,47 @@
+"""Holding every statement to the rules a project set for it."""
+
+from pyoq.policies.bypass import (
+    AuditSink,
+    Bypass,
+    CollectingAudit,
+    administrative_bypass,
+    async_administrative_bypass,
+)
+from pyoq.policies.governed import (
+    AsyncGovernedOperations,
+    GovernedCompiler,
+    GovernedOperations,
+    async_governed,
+    governed,
+)
+from pyoq.policies.model import (
+    AllowedTables,
+    Policies,
+    Policy,
+    RowConstraint,
+    SoftDelete,
+    TableReference,
+    TenantScope,
+)
+from pyoq.policies.rewriting import govern
+
+__all__ = (
+    "AllowedTables",
+    "AsyncGovernedOperations",
+    "AuditSink",
+    "Bypass",
+    "CollectingAudit",
+    "GovernedCompiler",
+    "GovernedOperations",
+    "Policies",
+    "Policy",
+    "RowConstraint",
+    "SoftDelete",
+    "TableReference",
+    "TenantScope",
+    "administrative_bypass",
+    "async_administrative_bypass",
+    "async_governed",
+    "govern",
+    "governed",
+)

pyoq/policies/bypass.py

@@ -0,0 +1,122 @@
+"""Going around a policy on purpose, and saying so.
+
+A policy that can be set aside quietly is a policy nobody can rely on. Going
+around one asks for a reason and somewhere to record it, and hands back the
+ungoverned database only for as long as the block runs, so it cannot be kept.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol
+
+from pyoq.errors import PolicyViolationError
+from pyoq.policies.governed import AsyncGovernedOperations, GovernedOperations
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from pyoq.query.execution import QueryOperations
+    from pyoq.query.execution.aio import AsyncQueryOperations
+
+
+@dataclass(frozen=True, slots=True)
+class Bypass:
+    """One deliberate step around the policies a database was given."""
+
+    reason: str
+    policies: tuple[str, ...]
+    entered: bool = True
+
+
+class AuditSink(Protocol):
+    """Somewhere a bypass is written down."""
+
+    def record(self, bypass: Bypass, /) -> None: ...
+
+
+class CollectingAudit:
+    """Keeps what it is told, for a caller that wants to look afterwards."""
+
+    __slots__ = ("entries",)
+    entries: list[Bypass]
+
+    def __init__(self) -> None:
+        self.entries = []
+
+    def record(self, bypass: Bypass, /) -> None:
+        self.entries.append(bypass)
+
+
+@contextmanager
+def administrative_bypass(
+    database: GovernedOperations,
+    reason: str,
+    audit: AuditSink,
+    /,
+) -> Generator[QueryOperations]:
+    """The database without its policies, for as long as this block runs.
+
+    The ungoverned database is yielded rather than returned, so it belongs to
+    the block and cannot be kept past it.
+    """
+    _require_reason(reason)
+    audit.record(_entering(database, reason))
+    try:
+        yield database.released
+    finally:
+        audit.record(_leaving(database, reason))
+
+
+@contextmanager
+def async_administrative_bypass(
+    database: AsyncGovernedOperations,
+    reason: str,
+    audit: AuditSink,
+    /,
+) -> Generator[AsyncQueryOperations]:
+    """The same, for a database that is awaited."""
+    _require_reason(reason)
+    audit.record(_entering(database, reason))
+    try:
+        yield database.released
+    finally:
+        audit.record(_leaving(database, reason))
+
+
+def _entering(
+    database: GovernedOperations | AsyncGovernedOperations,
+    reason: str,
+) -> Bypass:
+    return Bypass(reason, _named(database), entered=True)
+
+
+def _leaving(
+    database: GovernedOperations | AsyncGovernedOperations,
+    reason: str,
+) -> Bypass:
+    return Bypass(reason, _named(database), entered=False)
+
+
+def _named(
+    database: GovernedOperations | AsyncGovernedOperations,
+) -> tuple[str, ...]:
+    return tuple(type(policy).__name__ for policy in database.policies.members)
+
+
+def _require_reason(reason: str) -> None:
+    """A bypass with nothing written against it is one nobody can review."""
+    if reason.strip():
+        return
+    message = "going around a policy needs a reason that says why"
+    raise PolicyViolationError(message)
+
+
+__all__ = (
+    "AuditSink",
+    "Bypass",
+    "CollectingAudit",
+    "administrative_bypass",
+    "async_administrative_bypass",
+)