pyoq-sql 1.0.2__py3-none-any.whl

pyoq/__init__.py

@@ -0,0 +1,10 @@
+"""Public package interface for PyOQ."""
+
+from importlib.metadata import version
+
+from pyoq.config import Dialect
+from pyoq.serving import Database, connect
+
+__version__ = version("pyoq-sql")
+
+__all__ = ("Database", "Dialect", "__version__", "connect")

pyoq/__main__.py

@@ -0,0 +1,5 @@
+"""Module command entry point."""
+
+from pyoq.cli import run
+
+run()

pyoq/_native.pyi

@@ -0,0 +1,5 @@
+from collections.abc import Sequence
+
+def fingerprint_fragments(fragments: Sequence[bytes]) -> int: ...
+def group_integer_keys(keys: Sequence[int | None]) -> list[tuple[int, int]]: ...
+def runtime_marker() -> str: ...

pyoq/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Public command-line interface."""
+
+from pyoq.cli.commands import ExitCode, main, run
+
+__all__ = ("ExitCode", "main", "run")

pyoq/cli/commands.py

@@ -0,0 +1,270 @@
+"""Stable command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass
+from enum import IntEnum, StrEnum
+from pathlib import Path
+from typing import IO, NoReturn, cast
+
+from pyoq import __version__
+from pyoq.cli.services import CommandServices, GenerationMode
+from pyoq.config import Configuration, load_configuration
+from pyoq.errors import (
+    CommandError,
+    ConfigurationError,
+    OperationUnavailableError,
+    PyOQError,
+)
+
+
+class ExitCode(IntEnum):
+    SUCCESS = 0
+    COMMAND_FAILED = 1
+    USAGE = 2
+    CONFIGURATION = 3
+    UNAVAILABLE = 4
+
+
+class CommandName(StrEnum):
+    GENERATE = "generate"
+    INSPECT = "inspect"
+    SNAPSHOT = "snapshot"
+    DRIFT = "drift"
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigurationSource:
+    project_root: Path
+    pyproject_path: Path | None
+    selected_profile: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class GenerateCommand:
+    source: ConfigurationSource
+    mode: GenerationMode
+
+
+@dataclass(frozen=True, slots=True)
+class InspectCommand:
+    source: ConfigurationSource
+
+
+@dataclass(frozen=True, slots=True)
+class SnapshotCommand:
+    source: ConfigurationSource
+
+
+@dataclass(frozen=True, slots=True)
+class DriftCommand:
+    source: ConfigurationSource
+
+
+ParsedCommand = GenerateCommand | InspectCommand | SnapshotCommand | DriftCommand
+
+
+class ParserExitError(Exception):
+    def __init__(self, status: int, message: str | None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+
+
+class CommandParser(argparse.ArgumentParser):
+    _output: IO[str]
+
+    def set_output(self, output: IO[str]) -> None:
+        self._output = output
+
+    def _print_message(self, message: str, file: object | None = None) -> None:
+        self._output.write(message or "")
+
+    def exit(self, status: int = 0, message: str | None = None) -> NoReturn:
+        raise ParserExitError(status, message)
+
+    def error(self, message: str) -> NoReturn:
+        formatted = f"{self.format_usage()}{self.prog}: error: {message}\n"
+        raise ParserExitError(ExitCode.USAGE, formatted)
+
+
+def create_parser(output: IO[str] | None = None) -> CommandParser:
+    command_output = sys.stdout if output is None else output
+    parser = CommandParser(prog="pyoq", description="Typed database tooling")
+    parser.set_output(command_output)
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    generate = subparsers.add_parser(
+        CommandName.GENERATE,
+        help="generate typed database code",
+    )
+    generate.set_output(command_output)
+    _add_configuration_arguments(generate)
+    modes = generate.add_mutually_exclusive_group()
+    modes.add_argument(
+        "--check",
+        action="store_true",
+        help="fail when generated files are not current",
+    )
+    modes.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="show planned changes without writing files",
+    )
+
+    inspect = subparsers.add_parser(
+        CommandName.INSPECT,
+        help="inspect configured database metadata",
+    )
+    inspect.set_output(command_output)
+    _add_configuration_arguments(inspect)
+
+    snapshot = subparsers.add_parser(
+        CommandName.SNAPSHOT,
+        help="record the database schema in the configured snapshot file",
+    )
+    snapshot.set_output(command_output)
+    _add_configuration_arguments(snapshot)
+
+    drift = subparsers.add_parser(
+        CommandName.DRIFT,
+        help="compare the recorded schema against the database",
+    )
+    drift.set_output(command_output)
+    _add_configuration_arguments(drift)
+    return parser
+
+
+def main(
+    arguments: Sequence[str] | None = None,
+    *,
+    services: CommandServices | None = None,
+    output: IO[str] | None = None,
+    error: IO[str] | None = None,
+) -> int:
+    standard_output = sys.stdout if output is None else output
+    standard_error = sys.stderr if error is None else error
+    parser = create_parser(standard_output)
+    try:
+        namespace = parser.parse_args(arguments)
+        command = _parsed_command(namespace)
+        selected_services = (
+            services if services is not None else CommandServices.defaults()
+        )
+        _execute(command, selected_services, standard_output)
+    except ParserExitError as parser_exit:
+        return _handle_parser_exit(parser_exit, standard_output, standard_error)
+    except ConfigurationError as configuration_error:
+        _write_error(standard_error, "configuration error", configuration_error)
+        return ExitCode.CONFIGURATION
+    except OperationUnavailableError as unavailable_error:
+        _write_error(standard_error, "unavailable", unavailable_error)
+        return ExitCode.UNAVAILABLE
+    except CommandError as command_error:
+        _write_error(standard_error, "command failed", command_error)
+        return ExitCode.COMMAND_FAILED
+    except PyOQError as failure:
+        # Everything PyOQ raises is deliberate, so a command reports it rather
+        # than letting a traceback stand in for a message.
+        _write_error(standard_error, "command failed", failure)
+        return ExitCode.COMMAND_FAILED
+    return ExitCode.SUCCESS
+
+
+def run(arguments: Sequence[str] | None = None) -> NoReturn:
+    raise SystemExit(main(arguments))
+
+
+def _add_configuration_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--project-root",
+        type=Path,
+        default=Path.cwd(),
+        help="project root containing pyproject.toml",
+    )
+    parser.add_argument(
+        "--config",
+        type=Path,
+        dest="pyproject_path",
+        help="configuration file relative to the project root",
+    )
+    parser.add_argument(
+        "--profile",
+        dest="selected_profile",
+        help="configuration profile to select",
+    )
+
+
+def _parsed_command(namespace: argparse.Namespace) -> ParsedCommand:
+    source = ConfigurationSource(
+        project_root=cast(Path, namespace.project_root),
+        pyproject_path=cast(Path | None, namespace.pyproject_path),
+        selected_profile=cast(str | None, namespace.selected_profile),
+    )
+    command = CommandName(cast(str, namespace.command))
+    if command is CommandName.GENERATE:
+        return GenerateCommand(source, _generation_mode(namespace))
+    if command is CommandName.SNAPSHOT:
+        return SnapshotCommand(source)
+    if command is CommandName.DRIFT:
+        return DriftCommand(source)
+    return InspectCommand(source)
+
+
+def _generation_mode(namespace: argparse.Namespace) -> GenerationMode:
+    if cast(bool, namespace.check):
+        return GenerationMode.CHECK
+    if cast(bool, namespace.dry_run):
+        return GenerationMode.DRY_RUN
+    return GenerationMode.WRITE
+
+
+def _execute(
+    command: ParsedCommand,
+    services: CommandServices,
+    output: IO[str],
+) -> None:
+    configuration = _load_source(command.source)
+    if isinstance(command, GenerateCommand):
+        message = services.generation.execute(configuration, command.mode)
+    elif isinstance(command, SnapshotCommand):
+        message = services.snapshot.execute(configuration)
+    elif isinstance(command, DriftCommand):
+        message = services.drift.execute(configuration)
+    else:
+        message = services.inspection.execute(configuration)
+    output.write(f"{message}\n")
+
+
+def _load_source(source: ConfigurationSource) -> Configuration:
+    return load_configuration(
+        source.project_root,
+        pyproject_path=source.pyproject_path,
+        selected_profile=source.selected_profile,
+    )
+
+
+def _handle_parser_exit(
+    parser_exit: ParserExitError,
+    output: IO[str],
+    error: IO[str],
+) -> int:
+    if parser_exit.message:
+        destination = output if parser_exit.status == ExitCode.SUCCESS else error
+        destination.write(parser_exit.message)
+    return parser_exit.status
+
+
+def _write_error(output: IO[str], prefix: str, error: Exception) -> None:
+    output.write(f"{prefix}: {error}\n")
+
+
+__all__ = ("ExitCode", "main", "run")

pyoq/cli/defaults.py

@@ -0,0 +1,98 @@
+"""Default database command service assembly."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from pyoq.config import Configuration
+from pyoq.errors import ConfigurationValidationError, SchemaDriftError
+from pyoq.generation import (
+    AtomicGenerationWriter,
+    DirectoryProjectLock,
+    FileDriftChecker,
+    GeneratedTypesRenderer,
+    GenerationPipeline,
+    GenerationPlanner,
+    JsonManifestStore,
+    ManifestOwnedCleanup,
+    PythonSyntaxValidator,
+)
+from pyoq.schema import SchemaSource
+from pyoq.snapshots import compare_snapshots, read_snapshot, write_snapshot
+
+
+@dataclass(frozen=True, slots=True)
+class SchemaInspectionService:
+    source: SchemaSource
+
+    def execute(self, configuration: Configuration) -> str:
+        snapshot = self.source.load(configuration)
+        table_count = sum(
+            len(schema.tables)
+            for catalog in snapshot.catalogs
+            for schema in catalog.schemas
+        )
+        view_count = sum(
+            len(schema.views)
+            for catalog in snapshot.catalogs
+            for schema in catalog.schemas
+        )
+        return f"inspected tables: {table_count}; views: {view_count}"
+
+
+def default_generation_pipeline(source: SchemaSource) -> GenerationPipeline:
+    manifests = JsonManifestStore()
+    return GenerationPipeline(
+        schema_source=source,
+        planner=GenerationPlanner((GeneratedTypesRenderer(),)),
+        validator=PythonSyntaxValidator(),
+        manifest_store=manifests,
+        drift_checker=FileDriftChecker(),
+        writer=AtomicGenerationWriter(manifests, ManifestOwnedCleanup()),
+        project_lock=DirectoryProjectLock(),
+    )
+
+
+__all__ = ("SchemaInspectionService", "default_generation_pipeline")
+
+
+@dataclass(frozen=True, slots=True)
+class SnapshotRecordingService:
+    """Writing what the database holds to the file a project reviews."""
+
+    source: SchemaSource
+
+    def execute(self, configuration: Configuration) -> str:
+        destination = _required_snapshot_path(configuration)
+        snapshot = self.source.load(configuration)
+        write_snapshot(snapshot, destination)
+        return f"recorded the schema in {destination}"
+
+
+@dataclass(frozen=True, slots=True)
+class SchemaDriftService:
+    """Comparing the recorded schema against what the database now holds."""
+
+    source: SchemaSource
+
+    def execute(self, configuration: Configuration) -> str:
+        recorded_path = _required_snapshot_path(configuration)
+        recorded = read_snapshot(recorded_path)
+        observed = self.source.load(configuration)
+        report = compare_snapshots(recorded, observed)
+        if report.is_current:
+            return report.summary()
+        raise SchemaDriftError(report.summary())
+
+
+def _required_snapshot_path(configuration: Configuration) -> Path:
+    """Where the schema is recorded, which a project has to have chosen."""
+    destination = configuration.schema_snapshot_path
+    if destination is None:
+        message = (
+            "no schema snapshot is configured; set tool.pyoq.schema-snapshot "
+            "to the file the schema is recorded in"
+        )
+        raise ConfigurationValidationError(message)
+    return destination

pyoq/cli/services.py

@@ -0,0 +1,97 @@
+"""Command service boundaries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from pyoq.config import Configuration
+from pyoq.errors import OperationUnavailableError
+from pyoq.generation import GenerationMode
+
+
+class GenerationService(Protocol):
+    def execute(self, configuration: Configuration, mode: GenerationMode) -> str: ...
+
+
+class InspectionService(Protocol):
+    def execute(self, configuration: Configuration) -> str: ...
+
+
+class SnapshotService(Protocol):
+    def execute(self, configuration: Configuration) -> str: ...
+
+
+class DriftService(Protocol):
+    def execute(self, configuration: Configuration) -> str: ...
+
+
+class UnavailableGenerationService:
+    def execute(self, configuration: Configuration, mode: GenerationMode) -> str:
+        message = "schema generation is not available"
+        raise OperationUnavailableError(message)
+
+
+class UnavailableInspectionService:
+    def execute(self, configuration: Configuration) -> str:
+        message = "schema inspection is not available"
+        raise OperationUnavailableError(message)
+
+
+class UnavailableSnapshotService:
+    def execute(self, configuration: Configuration) -> str:
+        message = "recording a schema snapshot is not available"
+        raise OperationUnavailableError(message)
+
+
+class UnavailableDriftService:
+    def execute(self, configuration: Configuration) -> str:
+        message = "schema drift comparison is not available"
+        raise OperationUnavailableError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class CommandServices:
+    generation: GenerationService
+    inspection: InspectionService
+    snapshot: SnapshotService
+    drift: DriftService
+
+    @classmethod
+    def unavailable(cls) -> CommandServices:
+        return cls(
+            generation=UnavailableGenerationService(),
+            inspection=UnavailableInspectionService(),
+            snapshot=UnavailableSnapshotService(),
+            drift=UnavailableDriftService(),
+        )
+
+    @classmethod
+    def defaults(cls) -> CommandServices:
+        from pyoq.cli.defaults import (
+            SchemaDriftService,
+            SchemaInspectionService,
+            SnapshotRecordingService,
+            default_generation_pipeline,
+        )
+        from pyoq.schema import DialectRoutingSchemaSource
+        from pyoq.snapshots.routing import ConfiguredSchemaSource
+
+        configured = ConfiguredSchemaSource()
+        live = DialectRoutingSchemaSource()
+        return cls(
+            generation=default_generation_pipeline(configured),
+            inspection=SchemaInspectionService(configured),
+            snapshot=SnapshotRecordingService(live),
+            drift=SchemaDriftService(live),
+        )
+
+
+__all__ = (
+    "CommandServices",
+    "DriftService",
+    "GenerationMode",
+    "GenerationService",
+    "InspectionService",
+    "SnapshotService",
+)

pyoq/config/__init__.py

@@ -0,0 +1,31 @@
+"""Public configuration interface."""
+
+from pyoq.config.connection import (
+    ConnectionConfiguration,
+    PoolConfiguration,
+    ResolvedPoolConfiguration,
+)
+from pyoq.config.models import Configuration, DatabaseProfile, load_configuration
+from pyoq.config.values import (
+    DatabaseDialect,
+    DataSourceName,
+    Dialect,
+    EnvironmentReference,
+    SecretValue,
+    SettingValue,
+)
+
+__all__ = (
+    "Configuration",
+    "ConnectionConfiguration",
+    "DataSourceName",
+    "DatabaseDialect",
+    "DatabaseProfile",
+    "Dialect",
+    "EnvironmentReference",
+    "PoolConfiguration",
+    "ResolvedPoolConfiguration",
+    "SecretValue",
+    "SettingValue",
+    "load_configuration",
+)

pyoq/config/connection.py

@@ -0,0 +1,161 @@
+"""Structured server connection and pool configuration."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from urllib.parse import quote, urlunsplit
+
+from pyoq.config.values import DatabaseDialect, SecretValue, SettingValue
+from pyoq.errors import ConfigurationValidationError
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectionConfiguration:
+    database: SettingValue
+    username: SettingValue
+    host: SettingValue | None = None
+    port: SettingValue | None = None
+    password: SettingValue | None = None
+
+    def resolve_dsn(
+        self,
+        dialect: DatabaseDialect,
+        environment: Mapping[str, str] | None = None,
+    ) -> SecretValue:
+        scheme, default_port = _server_defaults(dialect)
+        host = _resolved_host(self.host, environment)
+        port = _resolved_port(self.port, default_port, environment)
+        username = self.username.resolve(environment).reveal()
+        password = _resolved_password(self.password, environment)
+        database = self.database.resolve(environment).reveal()
+        authority = _connection_authority(host, port, username, password)
+        return SecretValue(
+            urlunsplit((scheme, authority, f"/{quote(database, safe='')}", "", ""))
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedPoolConfiguration:
+    minimum_size: int | None
+    maximum_size: int | None
+    checkout_timeout: float | None
+
+
+@dataclass(frozen=True, slots=True)
+class PoolConfiguration:
+    minimum_size: SettingValue | None = None
+    maximum_size: SettingValue | None = None
+    checkout_timeout: SettingValue | None = None
+
+    def resolve(
+        self,
+        environment: Mapping[str, str] | None = None,
+    ) -> ResolvedPoolConfiguration:
+        return ResolvedPoolConfiguration(
+            _resolved_integer(self.minimum_size, "minimum-pool-size", environment),
+            _resolved_integer(self.maximum_size, "maximum-pool-size", environment),
+            _resolved_float(
+                self.checkout_timeout,
+                "pool-checkout-timeout",
+                environment,
+            ),
+        )
+
+
+def _server_defaults(dialect: DatabaseDialect) -> tuple[str, int]:
+    if dialect is DatabaseDialect.MYSQL:
+        return "mysql", 3306
+    if dialect is DatabaseDialect.POSTGRES:
+        return "postgresql", 5432
+    message = "structured connection fields require a server database dialect"
+    raise ConfigurationValidationError(message)
+
+
+def _resolved_host(
+    configured: SettingValue | None,
+    environment: Mapping[str, str] | None,
+) -> str:
+    host = (
+        "localhost" if configured is None else configured.resolve(environment).reveal()
+    )
+    if any(character.isspace() or character in "/@?#[]" for character in host):
+        message = f"invalid database host: {host!r}"
+        raise ConfigurationValidationError(message)
+    return host
+
+
+def _resolved_port(
+    configured: SettingValue | None,
+    default: int,
+    environment: Mapping[str, str] | None,
+) -> int:
+    if configured is None:
+        return default
+    written = configured.resolve(environment).reveal()
+    try:
+        port = int(written)
+    except ValueError as error:
+        message = f"database port must be an integer: {written!r}"
+        raise ConfigurationValidationError(message) from error
+    if not 1 <= port <= 65535:
+        message = "database port must be between 1 and 65535"
+        raise ConfigurationValidationError(message)
+    return port
+
+
+def _resolved_password(
+    configured: SettingValue | None,
+    environment: Mapping[str, str] | None,
+) -> str:
+    return "" if configured is None else configured.resolve(environment).reveal()
+
+
+def _connection_authority(
+    host: str,
+    port: int,
+    username: str,
+    password: str,
+) -> str:
+    credentials = quote(username, safe="")
+    if password:
+        credentials = f"{credentials}:{quote(password, safe='')}"
+    address = f"[{host}]" if ":" in host else host
+    return f"{credentials}@{address}:{port}"
+
+
+def _resolved_integer(
+    configured: SettingValue | None,
+    label: str,
+    environment: Mapping[str, str] | None,
+) -> int | None:
+    if configured is None:
+        return None
+    written = configured.resolve(environment).reveal()
+    try:
+        return int(written)
+    except ValueError as error:
+        message = f"{label} must be an integer: {written!r}"
+        raise ConfigurationValidationError(message) from error
+
+
+def _resolved_float(
+    configured: SettingValue | None,
+    label: str,
+    environment: Mapping[str, str] | None,
+) -> float | None:
+    if configured is None:
+        return None
+    written = configured.resolve(environment).reveal()
+    try:
+        return float(written)
+    except ValueError as error:
+        message = f"{label} must be numeric: {written!r}"
+        raise ConfigurationValidationError(message) from error
+
+
+__all__ = (
+    "ConnectionConfiguration",
+    "PoolConfiguration",
+    "ResolvedPoolConfiguration",
+)