pyoq-sql 1.0.2__py3-none-any.whl

pyoq/config/loader.py

@@ -0,0 +1,289 @@
+"""Strict project configuration loading."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import cast
+
+from pyoq.config import (
+    Configuration,
+    ConnectionConfiguration,
+    DatabaseDialect,
+    DatabaseProfile,
+    DataSourceName,
+    EnvironmentReference,
+    PoolConfiguration,
+    SettingValue,
+)
+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",
+    }
+)
+_CONNECTION_SETTINGS = frozenset({"database", "host", "password", "port", "username"})
+_POOL_SETTINGS = frozenset(
+    {"maximum-pool-size", "minimum-pool-size", "pool-checkout-timeout"}
+)
+_PROFILE_SETTINGS = (
+    frozenset({"database-path", "dialect", "dsn", "dsn-environment"})
+    | _CONNECTION_SETTINGS
+    | _POOL_SETTINGS
+)
+
+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)
+    dsn_value = _optional_string(table, "dsn", location)
+    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),
+        dsn=None if dsn_value is None else DataSourceName(dsn_value),
+        connection=_connection_configuration(table, location),
+        pool=_pool_configuration(table, location),
+    )
+
+
+def _connection_configuration(
+    table: RawTable,
+    location: str,
+) -> ConnectionConfiguration | None:
+    if not any(key in table for key in _CONNECTION_SETTINGS):
+        return None
+    return ConnectionConfiguration(
+        database=_required_setting_value(table, "database", location),
+        username=_required_setting_value(table, "username", location),
+        host=_optional_setting_value(table, "host", location),
+        port=_optional_setting_value(table, "port", location, allow_number=True),
+        password=_optional_setting_value(table, "password", location),
+    )
+
+
+def _pool_configuration(table: RawTable, location: str) -> PoolConfiguration:
+    return PoolConfiguration(
+        minimum_size=_optional_setting_value(
+            table,
+            "minimum-pool-size",
+            location,
+            allow_number=True,
+        ),
+        maximum_size=_optional_setting_value(
+            table,
+            "maximum-pool-size",
+            location,
+            allow_number=True,
+        ),
+        checkout_timeout=_optional_setting_value(
+            table,
+            "pool-checkout-timeout",
+            location,
+            allow_number=True,
+        ),
+    )
+
+
+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
+
+
+def _required_setting_value(
+    table: RawTable,
+    key: str,
+    location: str,
+) -> SettingValue:
+    value = _optional_setting_value(table, key, location)
+    if value is None:
+        message = f"{location}.{key} is required with structured connection fields"
+        raise ConfigurationValidationError(message)
+    return value
+
+
+def _optional_setting_value(
+    table: RawTable,
+    key: str,
+    location: str,
+    *,
+    allow_number: bool = False,
+) -> SettingValue | None:
+    value = table.get(key)
+    if value is None:
+        return None
+    if isinstance(value, str) and value:
+        return SettingValue(value)
+    if allow_number and not isinstance(value, bool) and isinstance(value, int | float):
+        return SettingValue(str(value))
+    expected = "a value or environment reference" if allow_number else "a string"
+    message = f"{location}.{key} must be {expected}"
+    raise ConfigurationValidationError(message)

pyoq/config/models.py

@@ -0,0 +1,245 @@
+"""Immutable configuration contracts."""
+
+from __future__ import annotations
+
+import keyword
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+
+from pyoq.config.connection import (
+    ConnectionConfiguration,
+    PoolConfiguration,
+    ResolvedPoolConfiguration,
+)
+from pyoq.config.values import (
+    DatabaseDialect,
+    DataSourceName,
+    Dialect,
+    EnvironmentReference,
+    SecretValue,
+    SettingValue,
+)
+from pyoq.errors import (
+    ConfigurationValidationError,
+    PathContainmentError,
+)
+
+_PROFILE_NAME = re.compile(r"[A-Za-z][A-Za-z0-9_-]*")
+
+
+@dataclass(frozen=True, slots=True)
+class DatabaseProfile:
+    name: str
+    dialect: DatabaseDialect
+    dsn_environment: EnvironmentReference | None = None
+    database_path: Path | None = None
+    dsn: DataSourceName | None = None
+    connection: ConnectionConfiguration | None = None
+    pool: PoolConfiguration = field(default_factory=PoolConfiguration)
+
+    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.dsn is not None and self.dsn_environment is not None:
+            message = "dsn and dsn-environment are mutually exclusive"
+            raise ConfigurationValidationError(message)
+        if self.database_path is not None and self._has_dsn():
+            message = "database-path and dsn settings are mutually exclusive"
+            raise ConfigurationValidationError(message)
+        if self.connection is not None and self._has_connection_target():
+            message = "structured connection fields cannot be combined with a dsn"
+            raise ConfigurationValidationError(message)
+        if self.connection is not None and self.dialect is DatabaseDialect.SQLITE:
+            message = "structured connection fields are not valid for SQLite profiles"
+            raise ConfigurationValidationError(message)
+
+    def resolve_dsn(
+        self,
+        environment: Mapping[str, str] | None = None,
+    ) -> SecretValue | None:
+        if self.dsn is not None:
+            return self.dsn.resolve(environment)
+        if self.dsn_environment is not None:
+            return self.dsn_environment.resolve(environment)
+        if self.connection is not None:
+            return self.connection.resolve_dsn(self.dialect, environment)
+        return None
+
+    def _has_dsn(self) -> bool:
+        return self.dsn is not None or self.dsn_environment is not None
+
+    def _has_connection_target(self) -> bool:
+        return self.database_path is not None or self._has_dsn()
+
+
+@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",
+    "ConnectionConfiguration",
+    "DataSourceName",
+    "DatabaseDialect",
+    "DatabaseProfile",
+    "Dialect",
+    "EnvironmentReference",
+    "PoolConfiguration",
+    "ResolvedPoolConfiguration",
+    "SecretValue",
+    "SettingValue",
+    "load_configuration",
+)

pyoq/config/values.py

@@ -0,0 +1,142 @@
+"""Typed scalar values used by project configuration."""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+
+from pyoq.errors import ConfigurationValidationError, SecretResolutionError
+
+_ENVIRONMENT_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+_ENVIRONMENT_REFERENCE = re.compile(r"\$\{(?P<name>[A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+class DatabaseDialect(StrEnum):
+    POSTGRES = "postgres"
+    MYSQL = "mysql"
+    SQLITE = "sqlite"
+
+
+Dialect = DatabaseDialect
+
+
+@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):
+            # The value is not repeated back. Whatever was written here is
+            # frequently a connection string, and a connection string carries
+            # a password: saying it aloud would put the password in a
+            # traceback, a log, and whatever collects them.
+            message = (
+                "dsn-environment names an environment variable, such as "
+                "DATABASE_URL, and what was given is not a variable name. "
+                "A connection string itself belongs in dsn."
+            )
+            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, repr=False)
+class DataSourceName:
+    _value: str
+
+    def __post_init__(self) -> None:
+        _validate_value(self._value, "dsn")
+
+    def resolve(self, environment: Mapping[str, str] | None = None) -> SecretValue:
+        return _resolve_value(self._value, environment)
+
+    def __repr__(self) -> str:
+        return "DataSourceName('[REDACTED]')"
+
+    def __str__(self) -> str:
+        return "[REDACTED]"
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class SettingValue:
+    """One profile scalar, either literal or a complete environment reference."""
+
+    _value: str
+
+    def __post_init__(self) -> None:
+        _validate_value(self._value, "profile setting")
+
+    def resolve(self, environment: Mapping[str, str] | None = None) -> SecretValue:
+        return _resolve_value(self._value, environment)
+
+    def __repr__(self) -> str:
+        return "SettingValue('[REDACTED]')"
+
+    def __str__(self) -> str:
+        return "[REDACTED]"
+
+
+def _validate_value(value: str, label: str) -> None:
+    if not value:
+        message = f"{label} values cannot be empty"
+        raise ConfigurationValidationError(message)
+    if "${" in value and not _ENVIRONMENT_REFERENCE.fullmatch(value):
+        # Anywhere in the string, not only at the start. A value is a whole
+        # reference or none of one, and something half written is a mistake
+        # rather than a literal: read as a literal it would be used as typed,
+        # and the first anyone knew of it would be the server refusing it.
+        # The value is not repeated back here either, for the same reason.
+        message = (
+            f"{label} is a literal or a whole ${{VARIABLE_NAME}} reference, "
+            f"and what was given is neither. A value that has to contain "
+            f"'${{' belongs in the environment, referenced whole."
+        )
+        raise ConfigurationValidationError(message)
+
+
+def _resolve_value(
+    value: str,
+    environment: Mapping[str, str] | None,
+) -> SecretValue:
+    match = _ENVIRONMENT_REFERENCE.fullmatch(value)
+    if match is None:
+        return SecretValue(value)
+    return EnvironmentReference(match.group("name")).resolve(environment)
+
+
+__all__ = (
+    "DataSourceName",
+    "DatabaseDialect",
+    "Dialect",
+    "EnvironmentReference",
+    "SecretValue",
+    "SettingValue",
+)