python-ddd-framework 0.3.1__py3-none-any.whl

python_ddd_framework/sqlalchemy/errors.py

@@ -0,0 +1,85 @@
+"""SQLAlchemy capability 的安全失败契约；任何消息都不得包含连接 URL。"""
+
+from __future__ import annotations
+
+from ..errors.base import FrameworkError
+
+
+class SqlAlchemyModelRegistrationError(FrameworkError):
+    def __init__(self, *, owner: str, reason: str) -> None:
+        self.owner = owner
+        self.reason = reason
+        super().__init__(f"Invalid SQLAlchemy model registration for {owner}: {reason}")
+
+
+class SqlAlchemyMetadataChangedError(FrameworkError):
+    def __init__(self, *, owner: str) -> None:
+        self.owner = owner
+        super().__init__(
+            f"SQLAlchemy MetaData owned by {owner} changed after its registration was declared"
+        )
+
+
+class SqlAlchemyConnectionError(FrameworkError):
+    def __init__(self, *, connection_name: str, operation: str, error_type: str) -> None:
+        self.connection_name = connection_name
+        self.operation = operation
+        self.error_type = error_type
+        super().__init__(
+            f"SQLAlchemy connection {connection_name!r} failed during {operation}: {error_type}"
+        )
+
+
+class UnknownSqlAlchemyConnectionError(FrameworkError, KeyError):
+    def __init__(self, connection_name: str) -> None:
+        self.connection_name = connection_name
+        super().__init__(f"SQLAlchemy connection {connection_name!r} is not configured")
+
+
+class SoftDeleteMigrationBlockedError(FrameworkError):
+    def __init__(self, affected_tables: tuple[tuple[str, int], ...]) -> None:
+        self.affected_tables = affected_tables
+        super().__init__(
+            f"Resolve historical soft-deleted rows before upgrading: {affected_tables}"
+        )
+
+
+class SqlAlchemyMigrationError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        operation: str,
+        failed_connection: str,
+        completed_connections: tuple[str, ...],
+        error_type: str,
+        cleanup_error_types: tuple[str, ...],
+        affected_tables: tuple[tuple[str, int], ...] = (),
+    ) -> None:
+        self.operation = operation
+        self.failed_connection = failed_connection
+        self.completed_connections = completed_connections
+        self.error_type = error_type
+        self.cleanup_error_types = cleanup_error_types
+        self.affected_tables = affected_tables
+        super().__init__(
+            f"SQLAlchemy migration {operation} failed for {failed_connection!r} after "
+            f"{len(completed_connections)} completed connection(s): {error_type}; "
+            f"cleanup failures: {len(cleanup_error_types)}; affected tables: {affected_tables}"
+        )
+
+
+class MigrationHeadsMismatchError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        connection_name: str,
+        current_heads: tuple[str, ...],
+        expected_heads: tuple[str, ...],
+    ) -> None:
+        self.connection_name = connection_name
+        self.current_heads = current_heads
+        self.expected_heads = expected_heads
+        super().__init__(
+            f"Connection {connection_name!r} is not at current Alembic heads: "
+            f"current={current_heads!r}, expected={expected_heads!r}"
+        )

python_ddd_framework/sqlalchemy/metadata.py

@@ -0,0 +1,576 @@
+"""Module-owned MetaData/migration declarations 与 Application-local aggregation。"""
+
+from __future__ import annotations
+
+import importlib.util
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TypeVar
+
+from sqlalchemy import Constraint, ForeignKey, MetaData, Table
+
+from ..modularity import AppModule, ModuleDescriptor, ModuleKey, ModuleRegistry
+from ..modularity.discovery import _import_package_modules
+from ..options import OptionsSnapshot
+from .errors import SqlAlchemyMetadataChangedError, SqlAlchemyModelRegistrationError
+from .options import _validate_connection_name
+
+_MODEL_REGISTRATIONS_ATTRIBUTE = "__python_ddd_framework_sqlalchemy_model_registrations__"
+_MIGRATION_REGISTRATIONS_ATTRIBUTE = "__python_ddd_framework_sqlalchemy_migration_registrations__"
+_TModule = TypeVar("_TModule", bound=type[AppModule])
+
+
+@dataclass(frozen=True, slots=True)
+class SqlAlchemyModelRegistration:
+    metadata: MetaData
+    migrations_package: str
+    branch_label: str
+    connection_name: str = "default"
+    _declared_fingerprint: tuple[object, ...] = field(init=False, repr=False, compare=False)
+
+    @classmethod
+    def from_package(
+        cls,
+        *,
+        models_package: str,
+        metadata: MetaData,
+        migrations_package: str,
+        branch_label: str,
+        connection_name: str = "default",
+    ) -> SqlAlchemyModelRegistration:
+        if not isinstance(models_package, str) or not models_package:
+            raise ValueError("models_package must be a non-empty import path")
+        if migrations_package == models_package or migrations_package.startswith(
+            models_package + "."
+        ):
+            raise ValueError("migrations_package must be outside models_package")
+        root = importlib.import_module(models_package)
+        if not hasattr(root, "__path__"):
+            raise ValueError("models_package must identify a package")
+        # Declarative class 导入会写入原生 MetaData，必须早于构造时的指纹冻结。
+        _import_package_modules(models_package)
+        return cls(metadata, migrations_package, branch_label, connection_name)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.metadata, MetaData):
+            raise TypeError("metadata must be sqlalchemy.MetaData")
+        if not isinstance(self.migrations_package, str) or not self.migrations_package.strip():
+            raise ValueError("migrations_package must be a non-empty import path")
+        if not isinstance(self.branch_label, str) or not self.branch_label.strip():
+            raise ValueError("branch_label must be a non-empty string")
+        if self.branch_label != self.branch_label.strip():
+            raise ValueError("branch_label must not contain surrounding whitespace")
+        _validate_connection_name(self.connection_name)
+        object.__setattr__(self, "_declared_fingerprint", _metadata_fingerprint(self.metadata))
+
+
+@dataclass(frozen=True, slots=True)
+class SqlAlchemyModelContribution:
+    owner: ModuleKey
+    registration: SqlAlchemyModelRegistration
+    migration_path: Path
+    declaration_index: int
+
+
+@dataclass(frozen=True, slots=True)
+class SqlAlchemyMigrationRegistration:
+    """不拥有 ORM metadata 的 external raw-SQL migration branch。"""
+
+    migrations_package: str
+    branch_label: str
+    owned_schemas: tuple[str, ...]
+    connection_name: str = "default"
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.migrations_package, str) or not self.migrations_package.strip():
+            raise ValueError("migrations_package must be a non-empty import path")
+        if (
+            not isinstance(self.branch_label, str)
+            or not self.branch_label
+            or self.branch_label != self.branch_label.strip()
+        ):
+            raise ValueError("branch_label must be a non-empty trimmed string")
+        _validate_connection_name(self.connection_name)
+        if (
+            not isinstance(self.owned_schemas, tuple)
+            or not self.owned_schemas
+            or any(not _is_postgres_identifier(item) for item in self.owned_schemas)
+        ):
+            raise ValueError("owned_schemas must be a non-empty tuple of PostgreSQL identifiers")
+        normalized = tuple(item.lower() for item in self.owned_schemas)
+        if len(set(normalized)) != len(normalized):
+            raise ValueError("owned_schemas cannot contain duplicates")
+        object.__setattr__(self, "owned_schemas", normalized)
+
+
+_MigrationDeclaration = (
+    SqlAlchemyMigrationRegistration | Callable[[OptionsSnapshot], SqlAlchemyMigrationRegistration]
+)
+
+
+@dataclass(frozen=True, slots=True)
+class SqlAlchemyMigrationContribution:
+    owner: ModuleKey
+    registration: SqlAlchemyMigrationRegistration
+    migration_path: Path
+    declaration_index: int
+
+
+@dataclass(frozen=True, slots=True)
+class _SqlAlchemyMigrationSource:
+    owner: ModuleKey
+    migrations_package: str
+    branch_label: str
+    migration_path: Path
+
+
+class SqlAlchemyModelCatalog:
+    __slots__ = ("_contributions", "_migration_contributions", "_migration_declarations")
+
+    def __init__(
+        self,
+        contributions: tuple[SqlAlchemyModelContribution, ...],
+        migration_contributions: tuple[SqlAlchemyMigrationContribution, ...],
+        migration_declarations: tuple[
+            tuple[type[AppModule], tuple[_MigrationDeclaration, ...]], ...
+        ],
+    ) -> None:
+        self._contributions = contributions
+        self._migration_contributions = migration_contributions
+        self._migration_declarations = migration_declarations
+
+    @property
+    def contributions(self) -> tuple[SqlAlchemyModelContribution, ...]:
+        return self._contributions
+
+    @property
+    def migration_contributions(self) -> tuple[SqlAlchemyMigrationContribution, ...]:
+        return self._migration_contributions
+
+    @property
+    def connection_names(self) -> tuple[str, ...]:
+        names = {item.registration.connection_name for item in self._contributions}
+        names.update(item.registration.connection_name for item in self._migration_contributions)
+        return tuple(name for name in ("default", *sorted(names - {"default"})) if name in names)
+
+    def for_connection(
+        self,
+        connection_name: str,
+    ) -> tuple[SqlAlchemyModelContribution, ...]:
+        return tuple(
+            item
+            for item in self._contributions
+            if item.registration.connection_name == connection_name
+        )
+
+    def migrations_for_connection(
+        self,
+        connection_name: str,
+    ) -> tuple[SqlAlchemyMigrationContribution, ...]:
+        return tuple(
+            item
+            for item in self._migration_contributions
+            if item.registration.connection_name == connection_name
+        )
+
+    def _migration_sources_for_connection(
+        self,
+        connection_name: str,
+    ) -> tuple[_SqlAlchemyMigrationSource, ...]:
+        model_sources = tuple(
+            _SqlAlchemyMigrationSource(
+                owner=item.owner,
+                migrations_package=item.registration.migrations_package,
+                branch_label=item.registration.branch_label,
+                migration_path=item.migration_path,
+            )
+            for item in self.for_connection(connection_name)
+        )
+        external_sources = tuple(
+            _SqlAlchemyMigrationSource(
+                owner=item.owner,
+                migrations_package=item.registration.migrations_package,
+                branch_label=item.registration.branch_label,
+                migration_path=item.migration_path,
+            )
+            for item in self.migrations_for_connection(connection_name)
+        )
+        return (*model_sources, *external_sources)
+
+    def _assert_unchanged(self) -> None:
+        for contribution in self._contributions:
+            registration = contribution.registration
+            if _metadata_fingerprint(registration.metadata) != registration._declared_fingerprint:
+                raise SqlAlchemyMetadataChangedError(owner=str(contribution.owner))
+        for module_type, declared in self._migration_declarations:
+            if module_type.__dict__.get(_MIGRATION_REGISTRATIONS_ATTRIBUTE, ()) is not declared:
+                raise SqlAlchemyMetadataChangedError(
+                    owner=f"{module_type.__module__}:{module_type.__qualname__}"
+                )
+
+
+def contributes_sqlalchemy_models(
+    *registrations: SqlAlchemyModelRegistration,
+) -> Callable[[_TModule], _TModule]:
+    declared = tuple(registrations)
+    if not declared or any(not isinstance(item, SqlAlchemyModelRegistration) for item in declared):
+        raise TypeError("contributes_sqlalchemy_models requires model registrations")
+
+    def decorate(module_type: _TModule) -> _TModule:
+        if not isinstance(module_type, type) or not issubclass(module_type, AppModule):
+            raise TypeError("contributes_sqlalchemy_models can only decorate AppModule classes")
+        if _MODEL_REGISTRATIONS_ATTRIBUTE in module_type.__dict__:
+            raise TypeError("SQLAlchemy model registrations may only be declared once per Module")
+        setattr(module_type, _MODEL_REGISTRATIONS_ATTRIBUTE, declared)
+        return module_type
+
+    return decorate
+
+
+def contributes_sqlalchemy_migrations(
+    *registrations: _MigrationDeclaration,
+) -> Callable[[_TModule], _TModule]:
+    declared = tuple(registrations)
+    if not declared or any(
+        not isinstance(item, SqlAlchemyMigrationRegistration) and not callable(item)
+        for item in declared
+    ):
+        raise TypeError("contributes_sqlalchemy_migrations requires migration registrations")
+
+    def decorate(module_type: _TModule) -> _TModule:
+        if not isinstance(module_type, type) or not issubclass(module_type, AppModule):
+            raise TypeError("contributes_sqlalchemy_migrations can only decorate AppModule classes")
+        if _MIGRATION_REGISTRATIONS_ATTRIBUTE in module_type.__dict__:
+            raise TypeError(
+                "SQLAlchemy migration registrations may only be declared once per Module"
+            )
+        setattr(module_type, _MIGRATION_REGISTRATIONS_ATTRIBUTE, declared)
+        return module_type
+
+    return decorate
+
+
+def _build_model_catalog(
+    registry: ModuleRegistry, options: OptionsSnapshot
+) -> SqlAlchemyModelCatalog:
+    builder = _SqlAlchemyModelCatalogBuilder(options)
+    for descriptor in registry.dependency_order:
+        builder.add_module(descriptor)
+    return builder.build()
+
+
+class _SqlAlchemyModelCatalogBuilder:
+    """拥有 model/raw-SQL migration arbitration 的 build-time mutable state。"""
+
+    __slots__ = (
+        "_branch_owners",
+        "_contributions",
+        "_migration_contributions",
+        "_migration_declarations",
+        "_options",
+        "_schema_owners",
+        "_table_owners",
+    )
+
+    def __init__(self, options: OptionsSnapshot) -> None:
+        self._options = options
+        self._contributions: list[SqlAlchemyModelContribution] = []
+        self._migration_contributions: list[SqlAlchemyMigrationContribution] = []
+        self._migration_declarations: list[
+            tuple[type[AppModule], tuple[_MigrationDeclaration, ...]]
+        ] = []
+        self._branch_owners: dict[str, ModuleKey] = {}
+        self._table_owners: dict[tuple[str, str], ModuleKey] = {}
+        self._schema_owners: dict[tuple[str, str], tuple[ModuleKey, str]] = {}
+
+    def add_module(self, descriptor: ModuleDescriptor) -> None:
+        self._add_model_declarations(descriptor)
+        self._add_migration_declarations(descriptor)
+
+    def build(self) -> SqlAlchemyModelCatalog:
+        return SqlAlchemyModelCatalog(
+            tuple(self._contributions),
+            tuple(self._migration_contributions),
+            tuple(self._migration_declarations),
+        )
+
+    def _add_model_declarations(self, descriptor: ModuleDescriptor) -> None:
+        declared = descriptor.module_type.__dict__.get(_MODEL_REGISTRATIONS_ATTRIBUTE, ())
+        if not isinstance(declared, tuple):
+            raise SqlAlchemyModelRegistrationError(
+                owner=str(descriptor.key),
+                reason="model registration metadata must be an immutable tuple",
+            )
+        for declaration_index, candidate in enumerate(declared):
+            self._add_model(candidate, descriptor.key, declaration_index)
+
+    def _add_model(
+        self,
+        candidate: object,
+        owner: ModuleKey,
+        declaration_index: int,
+    ) -> None:
+        if not isinstance(candidate, SqlAlchemyModelRegistration):
+            raise SqlAlchemyModelRegistrationError(
+                owner=str(owner),
+                reason="model registration metadata contains an invalid item",
+            )
+        registration = candidate
+        if _metadata_fingerprint(registration.metadata) != registration._declared_fingerprint:
+            raise SqlAlchemyMetadataChangedError(owner=str(owner))
+        self._claim_branch(registration.branch_label, owner)
+        migration_path = _migration_package_path(
+            registration.migrations_package,
+            owner=owner,
+        )
+        for table in registration.metadata.sorted_tables:
+            self._claim_table(registration, table, owner)
+        self._contributions.append(
+            SqlAlchemyModelContribution(
+                owner=owner,
+                registration=registration,
+                migration_path=migration_path,
+                declaration_index=declaration_index,
+            )
+        )
+
+    def _claim_table(
+        self,
+        registration: SqlAlchemyModelRegistration,
+        table: Table,
+        owner: ModuleKey,
+    ) -> None:
+        identity = (registration.connection_name, table.key)
+        previous_owner = self._table_owners.get(identity)
+        if previous_owner is not None:
+            raise SqlAlchemyModelRegistrationError(
+                owner=str(owner),
+                reason=(
+                    f"table {table.key!r} on connection {registration.connection_name!r} "
+                    f"is already owned by {previous_owner}"
+                ),
+            )
+        self._table_owners[identity] = owner
+        if table.schema is not None:
+            _claim_schema(
+                self._schema_owners,
+                connection_name=registration.connection_name,
+                schema=table.schema,
+                owner=owner,
+                kind="model",
+            )
+
+    def _add_migration_declarations(self, descriptor: ModuleDescriptor) -> None:
+        declared_migrations = descriptor.module_type.__dict__.get(
+            _MIGRATION_REGISTRATIONS_ATTRIBUTE,
+            (),
+        )
+        if not isinstance(declared_migrations, tuple):
+            raise SqlAlchemyModelRegistrationError(
+                owner=str(descriptor.key),
+                reason="migration registration metadata must be an immutable tuple",
+            )
+        self._migration_declarations.append((descriptor.module_type, declared_migrations))
+        for declaration_index, candidate in enumerate(declared_migrations):
+            # 解释结果只属于本 Application，不回写共享 Module class 的声明。
+            if callable(candidate):
+                candidate = candidate(self._options)
+            self._add_migration(candidate, descriptor.key, declaration_index)
+
+    def _add_migration(
+        self,
+        candidate: object,
+        owner: ModuleKey,
+        declaration_index: int,
+    ) -> None:
+        if not isinstance(candidate, SqlAlchemyMigrationRegistration):
+            raise SqlAlchemyModelRegistrationError(
+                owner=str(owner),
+                reason="migration registration metadata contains an invalid item",
+            )
+        registration = candidate
+        self._claim_branch(registration.branch_label, owner)
+        migration_path = _migration_package_path(
+            registration.migrations_package,
+            owner=owner,
+        )
+        for schema in registration.owned_schemas:
+            _claim_schema(
+                self._schema_owners,
+                connection_name=registration.connection_name,
+                schema=schema,
+                owner=owner,
+                kind="migration",
+            )
+        self._migration_contributions.append(
+            SqlAlchemyMigrationContribution(
+                owner=owner,
+                registration=registration,
+                migration_path=migration_path,
+                declaration_index=declaration_index,
+            )
+        )
+
+    def _claim_branch(self, branch_label: str, owner: ModuleKey) -> None:
+        previous_owner = self._branch_owners.get(branch_label)
+        if previous_owner is not None:
+            raise SqlAlchemyModelRegistrationError(
+                owner=str(owner),
+                reason=f"branch label {branch_label!r} is already owned by {previous_owner}",
+            )
+        self._branch_owners[branch_label] = owner
+
+
+def _claim_schema(
+    owners: dict[tuple[str, str], tuple[ModuleKey, str]],
+    *,
+    connection_name: str,
+    schema: str,
+    owner: ModuleKey,
+    kind: str,
+) -> None:
+    identity = (connection_name, schema.lower())
+    previous = owners.get(identity)
+    if previous is not None:
+        previous_owner, previous_kind = previous
+        if previous_owner == owner and previous_kind == kind == "model":
+            return
+        raise SqlAlchemyModelRegistrationError(
+            owner=str(owner),
+            reason=(
+                f"schema {schema!r} on connection {connection_name!r} is already owned by "
+                f"{previous_owner} ({previous_kind})"
+            ),
+        )
+    owners[identity] = (owner, kind)
+
+
+def _is_postgres_identifier(value: object) -> bool:
+    return (
+        isinstance(value, str)
+        and bool(value)
+        and (value[0].isalpha() or value[0] == "_")
+        and all(character.isalnum() or character == "_" for character in value)
+    )
+
+
+def _migration_package_path(package_name: str, *, owner: ModuleKey) -> Path:
+    try:
+        spec = importlib.util.find_spec(package_name)
+    except (ImportError, AttributeError, ValueError):
+        spec = None
+    locations = (
+        ()
+        if spec is None or spec.submodule_search_locations is None
+        else tuple(spec.submodule_search_locations)
+    )
+    if len(locations) != 1:
+        raise SqlAlchemyModelRegistrationError(
+            owner=str(owner),
+            reason=f"migration package {package_name!r} must resolve to one package directory",
+        )
+    return Path(locations[0]).resolve()
+
+
+def _metadata_fingerprint(metadata: MetaData) -> tuple[object, ...]:
+    return tuple(
+        _table_fingerprint(table)
+        for _, table in sorted(metadata.tables.items(), key=lambda item: item[0])
+    )
+
+
+def _table_fingerprint(table: Table) -> tuple[object, ...]:
+    return (
+        table.key,
+        table.comment,
+        tuple(
+            (
+                column.key,
+                column.name,
+                str(column.type),
+                column.nullable,
+                column.primary_key,
+                column.unique,
+                column.index,
+                column.autoincrement,
+                column.comment,
+                _schema_value_fingerprint(column.default),
+                _schema_value_fingerprint(column.server_default),
+                _schema_value_fingerprint(column.onupdate),
+                _schema_value_fingerprint(column.server_onupdate),
+                tuple(sorted(_foreign_key_fingerprint(item) for item in column.foreign_keys)),
+            )
+            for column in table.columns
+        ),
+        tuple(sorted(_constraint_fingerprint(constraint) for constraint in table.constraints)),
+        tuple(
+            sorted(
+                (
+                    index.name or "",
+                    index.unique,
+                    tuple(str(expression) for expression in index.expressions),
+                    tuple(
+                        sorted(
+                            (str(key), repr(value)) for key, value in index.dialect_kwargs.items()
+                        )
+                    ),
+                )
+                for index in table.indexes
+            )
+        ),
+    )
+
+
+def _constraint_fingerprint(constraint: Constraint) -> tuple[object, ...]:
+    return (
+        type(constraint).__module__,
+        type(constraint).__qualname__,
+        str(constraint.name or ""),
+        _ddl_value_fingerprint(getattr(constraint, "deferrable", None)),
+        _ddl_value_fingerprint(getattr(constraint, "initially", None)),
+        _ddl_value_fingerprint(getattr(constraint, "comment", None)),
+        _ddl_value_fingerprint(getattr(constraint, "onupdate", None)),
+        _ddl_value_fingerprint(getattr(constraint, "ondelete", None)),
+        _ddl_value_fingerprint(getattr(constraint, "use_alter", None)),
+        _ddl_value_fingerprint(getattr(constraint, "link_to_name", None)),
+        _ddl_value_fingerprint(getattr(constraint, "match", None)),
+        tuple(column.key for column in getattr(constraint, "columns", ())),
+        str(getattr(constraint, "sqltext", "")),
+        tuple(
+            sorted(
+                _foreign_key_fingerprint(element)
+                for element in getattr(constraint, "elements", ())
+                if isinstance(element, ForeignKey)
+            )
+        ),
+        tuple(sorted((str(key), repr(value)) for key, value in constraint.dialect_kwargs.items())),
+    )
+
+
+def _foreign_key_fingerprint(foreign_key: ForeignKey) -> tuple[object, ...]:
+    return (
+        str(foreign_key.target_fullname),
+        str(foreign_key.name or ""),
+        _ddl_value_fingerprint(foreign_key.onupdate),
+        _ddl_value_fingerprint(foreign_key.ondelete),
+        _ddl_value_fingerprint(foreign_key.deferrable),
+        _ddl_value_fingerprint(foreign_key.initially),
+        _ddl_value_fingerprint(foreign_key.use_alter),
+        _ddl_value_fingerprint(foreign_key.link_to_name),
+        _ddl_value_fingerprint(foreign_key.match),
+        _ddl_value_fingerprint(foreign_key.comment),
+        tuple(sorted((str(key), repr(value)) for key, value in foreign_key.dialect_kwargs.items())),
+    )
+
+
+def _ddl_value_fingerprint(value: object | None) -> tuple[str, str, str]:
+    # constraint fingerprints 需要排序；连 None 也编码为同形 tuple，避免显式值与 None 无法比较。
+    return type(value).__module__, type(value).__qualname__, repr(value)
+
+
+def _schema_value_fingerprint(value: object | None) -> tuple[str, str, str] | None:
+    if value is None:
+        return None
+    argument = getattr(value, "arg", value)
+    return type(value).__module__, type(value).__qualname__, str(argument)