pyoq-sql 1.0.0__py3-none-any.whl

pyoq/config/loader.py

@@ -0,0 +1,204 @@
+"""Strict project configuration loading."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import cast
+
+from pyoq.config import (
+    Configuration,
+    DatabaseDialect,
+    DatabaseProfile,
+    EnvironmentReference,
+)
+from pyoq.errors import (
+    ConfigurationFileError,
+    ConfigurationValidationError,
+    PathContainmentError,
+    UnknownConfigurationSettingError,
+)
+
+_DEFAULT_CODEGEN_DIRECTORY = "pyoq_generated"
+_DEFAULT_CODEGEN_PACKAGE = "pyoq_generated"
+_DEFAULT_PROFILE = "default"
+_ROOT_SETTINGS = frozenset(
+    {
+        "codegen-directory",
+        "codegen-package",
+        "profiles",
+        "schema-snapshot",
+        "selected-profile",
+    }
+)
+_PROFILE_SETTINGS = frozenset({"database-path", "dialect", "dsn-environment"})
+
+RawTable = dict[str, object]
+
+
+def load_configuration(
+    project_root: Path,
+    *,
+    explicit: Configuration | None = None,
+    pyproject_path: Path | None = None,
+    selected_profile: str | None = None,
+) -> Configuration:
+    if explicit is not None:
+        return (
+            explicit
+            if selected_profile is None
+            else explicit.select_profile(selected_profile)
+        )
+
+    root = project_root.resolve()
+    source_path = _resolve_config_path(root, pyproject_path)
+    document = _read_toml(source_path)
+    table = _pyoq_table(document)
+    configuration = _parse_configuration(root, table)
+    return (
+        configuration
+        if selected_profile is None
+        else configuration.select_profile(selected_profile)
+    )
+
+
+def _read_toml(path: Path) -> RawTable:
+    try:
+        with path.open("rb") as stream:
+            document = tomllib.load(stream)
+    except (OSError, tomllib.TOMLDecodeError) as error:
+        message = f"unable to read configuration: {path}"
+        raise ConfigurationFileError(message) from error
+    return cast(RawTable, document)
+
+
+def _pyoq_table(document: RawTable) -> RawTable:
+    tool = _require_table(document.get("tool"), "tool")
+    return _require_table(tool.get("pyoq"), "tool.pyoq")
+
+
+def _parse_configuration(root: Path, table: RawTable) -> Configuration:
+    _reject_unknown(table, _ROOT_SETTINGS, "tool.pyoq")
+    profiles = _parse_profiles(table.get("profiles"))
+    return Configuration(
+        project_root=root,
+        codegen_directory=Path(
+            _string_setting(
+                table,
+                "codegen-directory",
+                _DEFAULT_CODEGEN_DIRECTORY,
+                "tool.pyoq",
+            )
+        ),
+        codegen_package=_string_setting(
+            table,
+            "codegen-package",
+            _DEFAULT_CODEGEN_PACKAGE,
+            "tool.pyoq",
+        ),
+        selected_profile=_string_setting(
+            table,
+            "selected-profile",
+            _DEFAULT_PROFILE,
+            "tool.pyoq",
+        ),
+        profiles=profiles,
+        schema_snapshot=_optional_path_setting(table, "schema-snapshot"),
+    )
+
+
+def _optional_path_setting(table: RawTable, key: str) -> Path | None:
+    """A path a project may leave unset, which most projects do."""
+    written = table.get(key)
+    if written is None:
+        return None
+    if not isinstance(written, str) or not written:
+        message = f"tool.pyoq.{key} must be a non-empty string"
+        raise ConfigurationValidationError(message)
+    return Path(written)
+
+
+def _parse_profiles(value: object) -> tuple[DatabaseProfile, ...]:
+    table = _require_table(value, "tool.pyoq.profiles")
+    if not table:
+        message = "tool.pyoq.profiles must contain at least one profile"
+        raise ConfigurationValidationError(message)
+    return tuple(_parse_profile(name, settings) for name, settings in table.items())
+
+
+def _parse_profile(name: str, value: object) -> DatabaseProfile:
+    location = f"tool.pyoq.profiles.{name}"
+    table = _require_table(value, location)
+    _reject_unknown(table, _PROFILE_SETTINGS, location)
+    dialect_name = _required_string(table, "dialect", location)
+    try:
+        dialect = DatabaseDialect(dialect_name)
+    except ValueError as error:
+        supported = ", ".join(dialect.value for dialect in DatabaseDialect)
+        message = f"{location}.dialect must be one of: {supported}"
+        raise ConfigurationValidationError(message) from error
+    dsn_name = _optional_string(table, "dsn-environment", location)
+    dsn_environment = None if dsn_name is None else EnvironmentReference(dsn_name)
+    database_name = _optional_string(table, "database-path", location)
+    return DatabaseProfile(
+        name=name,
+        dialect=dialect,
+        dsn_environment=dsn_environment,
+        database_path=None if database_name is None else Path(database_name),
+    )
+
+
+def _resolve_config_path(root: Path, configured: Path | None) -> Path:
+    path = root / "pyproject.toml" if configured is None else configured
+    candidate = path if path.is_absolute() else root / path
+    resolved = candidate.resolve()
+    if not resolved.is_relative_to(root):
+        message = f"configuration path escapes project root: {path}"
+        raise PathContainmentError(message)
+    return resolved
+
+
+def _require_table(value: object, location: str) -> RawTable:
+    if not isinstance(value, dict):
+        message = f"{location} must be a table"
+        raise ConfigurationValidationError(message)
+    return cast(RawTable, value)
+
+
+def _reject_unknown(table: RawTable, allowed: frozenset[str], location: str) -> None:
+    unknown = sorted(table.keys() - allowed)
+    if unknown:
+        names = ", ".join(unknown)
+        message = f"unknown settings in {location}: {names}"
+        raise UnknownConfigurationSettingError(message)
+
+
+def _required_string(table: RawTable, key: str, location: str) -> str:
+    value = table.get(key)
+    if not isinstance(value, str) or not value:
+        message = f"{location}.{key} must be a non-empty string"
+        raise ConfigurationValidationError(message)
+    return value
+
+
+def _string_setting(
+    table: RawTable,
+    key: str,
+    default: str,
+    location: str,
+) -> str:
+    value = table.get(key, default)
+    if not isinstance(value, str) or not value:
+        message = f"{location}.{key} must be a non-empty string"
+        raise ConfigurationValidationError(message)
+    return value
+
+
+def _optional_string(table: RawTable, key: str, location: str) -> str | None:
+    value = table.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value:
+        message = f"{location}.{key} must be a non-empty string"
+        raise ConfigurationValidationError(message)
+    return value

pyoq/config/models.py

@@ -0,0 +1,243 @@
+"""Immutable configuration contracts."""
+
+from __future__ import annotations
+
+import keyword
+import os
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from enum import StrEnum
+from pathlib import Path
+
+from pyoq.errors import (
+    ConfigurationValidationError,
+    PathContainmentError,
+    SecretResolutionError,
+)
+
+_ENVIRONMENT_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+_PROFILE_NAME = re.compile(r"[A-Za-z][A-Za-z0-9_-]*")
+
+
+class DatabaseDialect(StrEnum):
+    POSTGRES = "postgres"
+    MYSQL = "mysql"
+    SQLITE = "sqlite"
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class SecretValue:
+    _value: str
+
+    def __post_init__(self) -> None:
+        if not self._value:
+            message = "secret values cannot be empty"
+            raise ConfigurationValidationError(message)
+
+    def reveal(self) -> str:
+        return self._value
+
+    def __repr__(self) -> str:
+        return "SecretValue('[REDACTED]')"
+
+    def __str__(self) -> str:
+        return "[REDACTED]"
+
+
+@dataclass(frozen=True, slots=True)
+class EnvironmentReference:
+    name: str
+
+    def __post_init__(self) -> None:
+        if not _ENVIRONMENT_NAME.fullmatch(self.name):
+            message = f"invalid environment variable name: {self.name!r}"
+            raise ConfigurationValidationError(message)
+
+    def resolve(self, environment: Mapping[str, str] | None = None) -> SecretValue:
+        values = os.environ if environment is None else environment
+        value = values.get(self.name)
+        if not value:
+            message = f"required environment variable is unavailable: {self.name}"
+            raise SecretResolutionError(message)
+        return SecretValue(value)
+
+
+@dataclass(frozen=True, slots=True)
+class DatabaseProfile:
+    name: str
+    dialect: DatabaseDialect
+    dsn_environment: EnvironmentReference | None = None
+    database_path: Path | None = None
+
+    def __post_init__(self) -> None:
+        if not _PROFILE_NAME.fullmatch(self.name):
+            message = f"invalid profile name: {self.name!r}"
+            raise ConfigurationValidationError(message)
+        if (
+            self.database_path is not None
+            and self.dialect is not DatabaseDialect.SQLITE
+        ):
+            message = "database-path is only valid for SQLite profiles"
+            raise ConfigurationValidationError(message)
+        if self.database_path is not None and self.dsn_environment is not None:
+            message = "database-path and dsn-environment are mutually exclusive"
+            raise ConfigurationValidationError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class Configuration:
+    project_root: Path
+    codegen_directory: Path
+    codegen_package: str
+    selected_profile: str
+    profiles: tuple[DatabaseProfile, ...]
+    schema_snapshot: Path | None = None
+    """Where the recorded schema is kept, relative to the project root.
+
+    Generation reads it instead of a database when it is set, which is what
+    lets a check run where there are no credentials to connect with.
+    """
+
+    def __post_init__(self) -> None:
+        root = self.project_root.resolve()
+        object.__setattr__(self, "project_root", root)
+        codegen_directory = _canonical_codegen_directory(
+            root,
+            self.codegen_directory,
+        )
+        object.__setattr__(self, "codegen_directory", codegen_directory)
+        object.__setattr__(
+            self,
+            "schema_snapshot",
+            _canonical_snapshot(root, self.schema_snapshot),
+        )
+        _validate_package_name(self.codegen_package)
+        _validate_profiles(self.profiles, self.selected_profile)
+        _validate_database_paths(root, self.profiles)
+
+    @property
+    def generated_path(self) -> Path:
+        return (self.project_root / self.codegen_directory).resolve()
+
+    @property
+    def schema_snapshot_path(self) -> Path | None:
+        """The recorded schema, as an absolute path, where one is configured."""
+        if self.schema_snapshot is None:
+            return None
+        return (self.project_root / self.schema_snapshot).resolve()
+
+    @property
+    def active_profile(self) -> DatabaseProfile:
+        return _find_profile(self.profiles, self.selected_profile)
+
+    @property
+    def active_database_path(self) -> Path | None:
+        configured = self.active_profile.database_path
+        if configured is None:
+            return None
+        return (self.project_root / configured).resolve()
+
+    def select_profile(self, name: str) -> Configuration:
+        _find_profile(self.profiles, name)
+        return replace(self, selected_profile=name)
+
+
+def load_configuration(
+    project_root: Path,
+    *,
+    explicit: Configuration | None = None,
+    pyproject_path: Path | None = None,
+    selected_profile: str | None = None,
+) -> Configuration:
+    from pyoq.config.loader import load_configuration as load_from_toml
+
+    return load_from_toml(
+        project_root,
+        explicit=explicit,
+        pyproject_path=pyproject_path,
+        selected_profile=selected_profile,
+    )
+
+
+def _contained(root: Path, configured: Path, label: str) -> Path:
+    """Where a configured path lands, refused if that is outside the project.
+
+    One policy for every path a project configures. It is written once because
+    three of them need it, and the one that had its own copy is the one that
+    escaped. Resolving first is what catches a symbolic link that points out
+    of the project as surely as a `..` does.
+    """
+    if configured.is_absolute():
+        message = f"{label} must be relative to the project root"
+        raise PathContainmentError(message)
+    resolved = (root / configured).resolve()
+    if resolved == root or not resolved.is_relative_to(root):
+        message = f"{label} escapes project root: {configured}"
+        raise PathContainmentError(message)
+    return resolved
+
+
+def _canonical_codegen_directory(root: Path, configured: Path) -> Path:
+    return _contained(root, configured, "codegen-directory").relative_to(root)
+
+
+def _canonical_snapshot(root: Path, configured: Path | None) -> Path | None:
+    """The recorded schema is written and replaced, so it stays in the project."""
+    if configured is None:
+        return None
+    return _contained(root, configured, "schema-snapshot").relative_to(root)
+
+
+def _validate_package_name(name: str) -> None:
+    parts = name.split(".")
+    invalid = any(not part.isidentifier() or keyword.iskeyword(part) for part in parts)
+    if invalid:
+        message = f"codegen-package is not a valid dotted package name: {name!r}"
+        raise ConfigurationValidationError(message)
+
+
+def _validate_profiles(
+    profiles: tuple[DatabaseProfile, ...],
+    selected_profile: str,
+) -> None:
+    if not profiles:
+        message = "configuration must contain at least one profile"
+        raise ConfigurationValidationError(message)
+    names = tuple(profile.name for profile in profiles)
+    if len(set(names)) != len(names):
+        message = "configuration profile names must be unique"
+        raise ConfigurationValidationError(message)
+    _find_profile(profiles, selected_profile)
+
+
+def _validate_database_paths(
+    root: Path,
+    profiles: tuple[DatabaseProfile, ...],
+) -> None:
+    for profile in profiles:
+        configured = profile.database_path
+        if configured is None:
+            continue
+        _contained(root, configured, "database-path")
+
+
+def _find_profile(
+    profiles: tuple[DatabaseProfile, ...],
+    name: str,
+) -> DatabaseProfile:
+    for profile in profiles:
+        if profile.name == name:
+            return profile
+    message = f"selected profile does not exist: {name!r}"
+    raise ConfigurationValidationError(message)
+
+
+__all__ = (
+    "Configuration",
+    "DatabaseDialect",
+    "DatabaseProfile",
+    "EnvironmentReference",
+    "SecretValue",
+    "load_configuration",
+)

pyoq/descriptors.py

@@ -0,0 +1,165 @@
+"""Runtime contracts used by generated database types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import ClassVar, Generic, TypeAlias, TypeVar
+
+from pyoq.query import Expression, FieldNode, ScalarFamily
+from pyoq.relations import RelationCardinality, RelationDirection
+from pyoq.schema import JsonScalar as SchemaJsonScalar
+from pyoq.schema import JsonValue as SchemaJsonValue
+from pyoq.schema import KeyKind, ReferentialAction
+from pyoq.unset import UNSET, UnsetType
+
+Value = TypeVar("Value")
+Row = TypeVar("Row", covariant=True)
+Insert = TypeVar("Insert", covariant=True)
+Update = TypeVar("Update", covariant=True)
+SourceRow = TypeVar("SourceRow", covariant=True)
+TargetRow = TypeVar("TargetRow", covariant=True)
+JsonScalar: TypeAlias = SchemaJsonScalar
+JsonValue: TypeAlias = SchemaJsonValue
+
+
+class Missing:
+    __slots__ = ()
+
+
+class Present:
+    __slots__ = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ColumnDescriptor(Expression[Value], Generic[Value]):
+    database_name: str
+    nullable: bool
+    writable: bool
+    has_default: bool
+    generated: bool
+    scalar_family: ScalarFamily = ScalarFamily.OTHER
+    table_name: str | None = None
+    schema_name: str | None = None
+    catalog_name: str | None = None
+    field_name: str | None = None
+    value_type: type[object] | None = None
+
+    def __post_init__(self) -> None:
+        _require_name(self.database_name, "column")
+        self._initialize_expression(
+            FieldNode(
+                self.database_name,
+                self.table_name,
+                self.schema_name,
+                self.catalog_name,
+                self.scalar_family,
+                self.value_type,
+                self.nullable,
+            ),
+            self.scalar_family,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class TableDescriptor(Generic[Row, Insert, Update]):
+    COLUMNS: ClassVar[tuple[object, ...]] = ()
+    """Every column this table has, in the order the table declares them.
+
+    Generation fills this in. A table written by hand names no columns, and
+    so cannot be selected from without saying which.
+    """
+
+    database_name: str
+    schema_name: str | None = None
+    catalog_name: str | None = None
+    row_type: type[Row] | None = None
+    """The class one row of this table reads back as.
+
+    Generation fills this in, so a table constant carries the type of what it
+    holds as well as its name. A table written by hand names no row class, and
+    so a row of it can only be read as the values it came back with.
+    """
+
+    def __post_init__(self) -> None:
+        _require_name(self.database_name, "table")
+
+
+@dataclass(frozen=True, slots=True)
+class KeyDescriptor(Generic[Value]):
+    kind: KeyKind
+    column_names: tuple[str, ...]
+    database_name: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.column_names:
+            message = "key descriptor requires at least one column"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class RelationshipDescriptor(Generic[SourceRow, TargetRow]):
+    source_table: str
+    source_columns: tuple[str, ...]
+    target_table: str
+    target_columns: tuple[str, ...]
+    source_schema: str | None = None
+    source_catalog: str | None = None
+    target_schema: str | None = None
+    target_catalog: str | None = None
+    """Where each side lives, because a table name alone names more than one.
+
+    Two schemas may each hold a `parent` and a `child` joined on the same
+    columns. Without these, a constant generated for one of them describes
+    both, and reading through it answers with whichever was found first.
+    """
+
+    database_name: str | None = None
+    on_update: ReferentialAction = ReferentialAction.NO_ACTION
+    on_delete: ReferentialAction = ReferentialAction.NO_ACTION
+    direction: RelationDirection = RelationDirection.FORWARD
+    cardinality: RelationCardinality = RelationCardinality.TO_ONE
+    optional: bool = False
+    target_row_type: type[TargetRow] | None = None
+    """The class one row of the table this reaches reads back as.
+
+    The same fact as a table constant's own, carried here so that following a
+    relation says what it arrives at without the caller naming it again.
+    """
+
+    def __post_init__(self) -> None:
+        _require_name(self.source_table, "relationship source table")
+        _require_name(self.target_table, "relationship target table")
+        if not self.source_columns or len(self.source_columns) != len(
+            self.target_columns
+        ):
+            message = "relationship descriptor columns must be non-empty and aligned"
+            raise ValueError(message)
+        if self.cardinality is RelationCardinality.TO_MANY and self.optional:
+            message = "a to-many relationship cannot be optional"
+            raise ValueError(message)
+
+    @property
+    def to_one(self) -> bool:
+        return self.cardinality is RelationCardinality.TO_ONE
+
+
+def _require_name(value: str, label: str) -> None:
+    if not value:
+        message = f"{label} name cannot be empty"
+        raise ValueError(message)
+
+
+__all__ = (
+    "UNSET",
+    "ColumnDescriptor",
+    "JsonScalar",
+    "JsonValue",
+    "KeyDescriptor",
+    "Missing",
+    "Present",
+    "RelationCardinality",
+    "RelationDirection",
+    "RelationshipDescriptor",
+    "TableDescriptor",
+    "UnsetType",
+)

pyoq/diagnostics/__init__.py

@@ -0,0 +1,68 @@
+"""Seeing what a scope asked a database to do."""
+
+from pyoq.diagnostics.budget import QueryBudget, QueryScope
+from pyoq.diagnostics.events import (
+    CollectingSink,
+    EventPolicy,
+    EventSink,
+    StatementEvent,
+    StatementFailed,
+    StatementFinished,
+    StatementStarted,
+    reportable_values,
+)
+from pyoq.diagnostics.fingerprint import (
+    CacheMetrics,
+    QueryShape,
+    forget_shapes,
+    normalize_sql,
+    query_shape,
+    shape_cache_metrics,
+)
+from pyoq.diagnostics.instrumented import (
+    AsyncInstrumentedOperations,
+    InstrumentedOperations,
+)
+from pyoq.diagnostics.metrics import DatabaseMetrics, metrics_of
+from pyoq.diagnostics.observation import (
+    DEFAULT_REPEAT_THRESHOLD,
+    DEFAULT_SHAPE_LIMIT,
+    DEFAULT_SITE_LIMIT,
+    CallSite,
+    QueryObserver,
+    RepeatedQuery,
+    calling_site,
+)
+from pyoq.diagnostics.scoped import AsyncScopedOperations, ScopedOperations
+
+__all__ = (
+    "DEFAULT_REPEAT_THRESHOLD",
+    "DEFAULT_SHAPE_LIMIT",
+    "DEFAULT_SITE_LIMIT",
+    "AsyncInstrumentedOperations",
+    "AsyncScopedOperations",
+    "CacheMetrics",
+    "CallSite",
+    "CollectingSink",
+    "DatabaseMetrics",
+    "EventPolicy",
+    "EventSink",
+    "InstrumentedOperations",
+    "QueryBudget",
+    "QueryObserver",
+    "QueryScope",
+    "QueryShape",
+    "RepeatedQuery",
+    "ScopedOperations",
+    "StatementEvent",
+    "StatementFailed",
+    "StatementFinished",
+    "StatementStarted",
+    "calling_site",
+    "forget_shapes",
+    "metrics_of",
+    "normalize_sql",
+    "query_shape",
+    "reportable_values",
+    "shape_cache_metrics",
+)