django-compose 0.1.0.dev1__py3-none-any.whl

django_compose/snapshot.py

@@ -0,0 +1,419 @@
+"""Immutable, pre-setup-safe composition inputs shared by builders and readers."""
+
+from __future__ import annotations
+
+import hashlib
+import importlib
+import json
+import os
+import sys
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any, Literal
+
+from django.apps import AppConfig
+from django.conf import global_settings
+from django.core.exceptions import ImproperlyConfigured
+from django.utils.module_loading import import_string
+
+from django_compose.autoreload import report_inputs, report_watch_paths
+from django_compose.sources import SourceResolver
+
+COMPILER = "django-compose:1"
+DEFAULT_EXCLUDES = ("**/__pycache__/**", "**/migrations/**", "**/tests/**")
+
+NON_INPUT_SETTINGS = frozenset(
+    {"COMPOSE_ROOTS", "COMPOSE_SNAPSHOT", "COMPOSE_CLOSURE", "COMPOSE_COMMAND_CONTEXT"}
+)
+STRUCTURAL_SETTINGS = frozenset(
+    {
+        "INSTALLED_APPS",
+        "MIGRATION_MODULES",
+        "DEFAULT_AUTO_FIELD",
+        "AUTH_USER_MODEL",
+        "COMPOSE_ADDON_GROUP",
+        "COMPOSE_OUTPUT_DIR",
+        "COMPOSE_OUTPUT_MODULE",
+        "COMPOSE_INTEGRATIONS",
+        "COMPOSE_TRANSITION_SOURCE",
+        "COMPOSE_EXTERNAL_ARTIFACT_ROOTS",
+        "COMPOSE_FINGERPRINT_GLOBS",
+        "COMPOSE_FINGERPRINT_SETTINGS",
+        "COMPOSE_FINGERPRINT_EXCLUDES",
+        "COMPOSE_ENV_PREFIXES",
+        "COMPOSE_WATCH_PATHS",
+    }
+)
+
+
+def structural_settings(namespace: Mapping[str, Any], *, settings_keys: Iterable[str] = ()) -> frozenset[str]:
+    """Name compiler inputs, including capability-declared fingerprint settings.
+
+    Configuration uses this same ownership boundary to refuse environment inputs.
+    Derived state and command execution context never participate in a snapshot.
+    """
+    declared = namespace.get("COMPOSE_FINGERPRINT_SETTINGS", ())
+    if isinstance(declared, str) or not isinstance(declared, Iterable):
+        raise ImproperlyConfigured("COMPOSE_FINGERPRINT_SETTINGS must contain setting names")
+    custom = (*settings_keys, *declared)
+    if any(not isinstance(key, str) or not key for key in custom):
+        raise ImproperlyConfigured("COMPOSE_FINGERPRINT_SETTINGS must contain setting names")
+    return (
+        STRUCTURAL_SETTINGS | {key for key in namespace if key.startswith("COMPOSE_")} | set(custom)
+    ) - NON_INPUT_SETTINGS
+
+
+def mode() -> Literal["write", "check"] | None:
+    value = os.environ.get("DJANGO_COMPOSE_MODE")
+    if value == "write":
+        return "write"
+    if value == "check":
+        return "check"
+    if value is not None:
+        raise ImproperlyConfigured("DJANGO_COMPOSE_MODE must be write or check, or absent for serving")
+    return None
+
+
+def _freeze(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return MappingProxyType({str(key): _freeze(item) for key, item in sorted(value.items())})
+    if isinstance(value, (tuple, list)):
+        return tuple(_freeze(item) for item in value)
+    if value is None or isinstance(value, (str, bool, int, float)):
+        return value
+    raise ImproperlyConfigured(f"Snapshot value is not a literal: {value!r}")
+
+
+def _plain(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {key: _plain(item) for key, item in value.items()}
+    if isinstance(value, tuple):
+        return [_plain(item) for item in value]
+    return value
+
+
+@dataclass(frozen=True)
+class Entry:
+    """A selected native app identity; entry preserves the authored spelling."""
+
+    name: str
+    label: str
+    config: str
+    path: str
+    entry: str
+
+    @classmethod
+    def from_config(cls, config: AppConfig, entry: str) -> Entry:
+        """Capture an already-selected native config without activating it again."""
+        return cls(
+            config.name,
+            config.label,
+            f"{type(config).__module__}.{type(config).__qualname__}",
+            config.path,
+            entry,
+        )
+
+
+@dataclass(frozen=True)
+class Snapshot:
+    """Frozen build inputs, retaining resolved direct dependencies by native app name."""
+
+    entries: tuple[Entry, ...]
+    files: tuple[tuple[str, str], ...]
+    integration_paths: tuple[str, ...]
+    transitions: tuple[tuple[str, str], ...]
+    transition_records: tuple[Mapping[str, str], ...]
+    authored_migration_modules: Mapping[str, str | None]
+    settings: Mapping[str, Any]
+    compiler: str = COMPILER
+    dependencies: Mapping[str, tuple[str, ...]] = field(
+        default_factory=lambda: MappingProxyType({}), kw_only=True
+    )
+    _process_mode: Literal["write", "check"] | None = field(default_factory=mode, repr=False, compare=False)
+
+    def check_mode(self) -> None:
+        if mode() != self._process_mode:
+            raise ImproperlyConfigured("DJANGO_COMPOSE_MODE changed after the settings snapshot")
+
+    def digest(self) -> str:
+        payload = {
+            "entries": [(e.name, e.label, e.config, e.entry) for e in self.entries],
+            "dependencies": self.dependencies,
+            "files": self.files,
+            "integrations": self.integration_paths,
+            "transitions": self.transitions,
+            "transition_records": self.transition_records,
+            "migrations": self.authored_migration_modules,
+            "settings": self.settings,
+            "compiler": self.compiler,
+        }
+        return hashlib.sha256(
+            json.dumps(_plain(payload), sort_keys=True, separators=(",", ":")).encode()
+        ).hexdigest()
+
+
+def app_entries(entries: Iterable[str | Entry]) -> tuple[Entry, ...]:
+    """Resolve native app identities without importing any app models."""
+    result = []
+    names: set[str] = set()
+    labels: set[str] = set()
+    for entry in entries:
+        if not isinstance(entry, Entry):
+            if not isinstance(entry, str):
+                raise ImproperlyConfigured(f"INSTALLED_APPS entry must be a string: {entry!r}")
+            config = AppConfig.create(entry)
+            entry = Entry.from_config(config, entry)
+        if entry.name == "django_compose":
+            continue
+        if entry.name in names or entry.label in labels:
+            raise ImproperlyConfigured(f"Duplicate app identity: {entry.entry!r}")
+        names.add(entry.name)
+        labels.add(entry.label)
+        result.append(entry)
+    return tuple(result)
+
+
+def transition_declarations(source: Any) -> tuple[Mapping[str, str], ...]:
+    """Normalize the explicit pre-setup transition declaration surface once."""
+    if isinstance(source, str):
+        module, separator, name = source.rpartition(".")
+        if not separator:
+            raise ImproperlyConfigured("COMPOSE_TRANSITION_SOURCE must name a callable")
+        source = getattr(importlib.import_module(module), name)()
+    declarations = []
+    origins: set[str] = set()
+    for declaration in source:
+        if not isinstance(declaration, Mapping) or set(declaration) != {
+            "declaring_app",
+            "name",
+            "app_label",
+            "module",
+        }:
+            raise ImproperlyConfigured(f"Invalid transition declaration: {declaration!r}")
+        if not all(isinstance(value, str) and value for value in declaration.values()):
+            raise ImproperlyConfigured(f"Invalid transition declaration: {declaration!r}")
+        origin = f"{declaration['declaring_app']}:{declaration['name']}"
+        name = declaration["name"]
+        if not ("_" + name).isidentifier() or name != name.lower() or name.startswith("_"):
+            raise ImproperlyConfigured(f"{origin}: name must be a lower-case migration name")
+        if origin in origins:
+            raise ImproperlyConfigured(f"Duplicate transition origin: {origin}")
+        origins.add(origin)
+        normalized = dict(declaration)
+        if not normalized["module"].startswith(normalized["declaring_app"] + "."):
+            normalized["module"] = normalized["declaring_app"] + "." + normalized["module"]
+        declarations.append(MappingProxyType(normalized))
+    return tuple(declarations)
+
+
+def _default_transitions(entries: tuple[Entry, ...]) -> tuple[Mapping[str, str], ...]:
+    records = []
+    for entry in entries:
+        directory = Path(entry.path) / "compose_migrations"
+        report_inputs(globs=[(directory, "*/*.py")])
+        for path in sorted(directory.glob("*/*.py")):
+            if path.name == "__init__.py" or not path.is_file():
+                continue
+            label = path.parent.name
+            if not label.isidentifier():
+                raise ImproperlyConfigured(f"Invalid default transition path: {path}")
+            records.append(
+                {
+                    "declaring_app": entry.name,
+                    "name": path.stem,
+                    "app_label": label,
+                    "module": f"{entry.name}.compose_migrations.{label}.{path.stem}",
+                }
+            )
+    return transition_declarations(records)
+
+
+def _fingerprints(
+    records: tuple[Mapping[str, str], ...], resolver: SourceResolver
+) -> tuple[tuple[str, str], ...]:
+    result = []
+    for declaration in records:
+        location = resolver.resolve(declaration["module"])
+        if location.path is not None:
+            report_inputs(files=[location.path])
+        if location.path is None or not location.path.is_file():
+            raise ImproperlyConfigured(f"Cannot fingerprint module {declaration['module']!r}")
+        result.append(
+            (
+                f"{declaration['declaring_app']}:{declaration['name']}",
+                hashlib.sha256(location.path.read_bytes()).hexdigest(),
+            )
+        )
+    return tuple(result)
+
+
+def transition_fingerprints(source: Any) -> tuple[tuple[str, str], ...]:
+    """Hash declared transition modules without executing their model imports."""
+    return _fingerprints(transition_declarations(source), SourceResolver())
+
+
+def _effective_sequence(
+    values: Mapping[str, Any], key: str, argument: Iterable[str] | None, default: Iterable[str] = ()
+) -> tuple[str, ...]:
+    explicit = tuple(argument) if argument is not None else None
+    value = tuple(values.get(key, default))
+    if explicit is not None and key in values and explicit != value:
+        raise ImproperlyConfigured(f"Conflicting snapshot argument and {key}")
+    result = value if explicit is None else explicit
+    if not all(isinstance(item, str) for item in result):
+        raise ImproperlyConfigured(f"{key} must contain strings")
+    return result
+
+
+def snapshot(
+    entries: Iterable[str | Entry],
+    *,
+    integration_paths: Iterable[str] | None = None,
+    fingerprint_globs: Iterable[str] | None = None,
+    fingerprint_excludes: Iterable[str] | None = None,
+    settings_keys: Iterable[str] = (),
+    namespace: Mapping[str, Any] | None = None,
+    transitions: Any = None,
+    authored_migration_modules: Mapping[str, str | None] | None = None,
+    dependencies: Mapping[str, tuple[str, ...]] | None = None,
+) -> Snapshot:
+    """Freeze effective compiler inputs once, without importing source models.
+
+    Explicit integration/glob/exclusion arguments and namespace declarations must
+    agree. Extra setting keys extend COMPOSE_FINGERPRINT_SETTINGS. An omitted
+    transition source discovers compose_migrations/<label>/<name>.py in app order.
+    Dependencies retain already-resolved native app-name edges; targets must
+    precede their dependants in entries. This function never resolves app edges.
+    """
+    normalized = app_entries(entries)
+    positions = {entry.name: index for index, entry in enumerate(normalized)}
+    edges = {} if dependencies is None else dependencies
+    for name, targets in edges.items():
+        if name not in positions:
+            raise ImproperlyConfigured(f"Snapshot dependency owner is not selected: {name!r}")
+        if isinstance(targets, str) or not isinstance(targets, (tuple, list)):
+            raise ImproperlyConfigured(f"Snapshot dependencies for {name!r} must be a sequence of app names")
+        for target in targets:
+            if not isinstance(target, str) or target not in positions:
+                raise ImproperlyConfigured(f"Snapshot dependency target is not selected: {target!r}")
+            if positions[target] >= positions[name]:
+                raise ImproperlyConfigured(f"Snapshot dependency {target!r} must precede {name!r}")
+    values = namespace if namespace is not None else {}
+    integrations = _effective_sequence(values, "COMPOSE_INTEGRATIONS", integration_paths)
+    globs = tuple(sorted(set(_effective_sequence(values, "COMPOSE_FINGERPRINT_GLOBS", fingerprint_globs))))
+    excludes = tuple(
+        sorted(
+            set(
+                _effective_sequence(
+                    values, "COMPOSE_FINGERPRINT_EXCLUDES", fingerprint_excludes, DEFAULT_EXCLUDES
+                )
+            )
+        )
+    )
+    resolver = SourceResolver(normalized)
+    if transitions is None and "COMPOSE_TRANSITION_SOURCE" not in values:
+        records = _default_transitions(normalized)
+    else:
+        records = transition_declarations(
+            values.get("COMPOSE_TRANSITION_SOURCE", ()) if transitions is None else transitions
+        )
+        if (
+            transitions is not None
+            and "COMPOSE_TRANSITION_SOURCE" in values
+            and transitions != values["COMPOSE_TRANSITION_SOURCE"]
+        ):
+            if records != transition_declarations(values["COMPOSE_TRANSITION_SOURCE"]):
+                raise ImproperlyConfigured("Conflicting snapshot argument and COMPOSE_TRANSITION_SOURCE")
+    authored = (
+        values.get("MIGRATION_MODULES", {})
+        if authored_migration_modules is None
+        else authored_migration_modules
+    )
+    if authored_migration_modules is not None and "MIGRATION_MODULES" in values:
+        if dict(authored_migration_modules) != dict(values["MIGRATION_MODULES"]):
+            raise ImproperlyConfigured("Conflicting snapshot argument and MIGRATION_MODULES")
+    effective_settings = {
+        key: value
+        for key, value in values.items()
+        if key.startswith("COMPOSE_") and key not in NON_INPUT_SETTINGS
+    }
+    output_dir = values.get("COMPOSE_OUTPUT_DIR")
+    effective_settings.update(
+        {
+            "COMPOSE_OUTPUT_DIR": Path(output_dir).as_posix() if output_dir is not None else None,
+            "COMPOSE_OUTPUT_MODULE": values.get("COMPOSE_OUTPUT_MODULE", "runtime"),
+            "COMPOSE_INTEGRATIONS": integrations,
+            "COMPOSE_FINGERPRINT_GLOBS": globs,
+            "COMPOSE_FINGERPRINT_EXCLUDES": excludes,
+            "COMPOSE_WATCH_PATHS": report_watch_paths(values.get("COMPOSE_WATCH_PATHS", ())),
+            "COMPOSE_TRANSITION_SOURCE": records,
+            "COMPOSE_EXTERNAL_ARTIFACT_ROOTS": tuple(
+                sorted(set(values.get("COMPOSE_EXTERNAL_ARTIFACT_ROOTS", ())))
+            ),
+            "DEFAULT_AUTO_FIELD": values.get("DEFAULT_AUTO_FIELD", global_settings.DEFAULT_AUTO_FIELD),
+            "AUTH_USER_MODEL": values.get("AUTH_USER_MODEL", global_settings.AUTH_USER_MODEL),
+        }
+    )
+    hook_settings = structural_settings(values, settings_keys=settings_keys)
+    hook_settings -= STRUCTURAL_SETTINGS
+    extras = hook_settings - set(effective_settings)
+    effective_settings["COMPOSE_FINGERPRINT_SETTINGS"] = tuple(sorted(extras))
+    for key in sorted(extras):
+        effective_settings[key] = values.get(key, getattr(global_settings, key, None))
+    files: dict[str, str] = {}
+    for entry in normalized:
+        root = Path(entry.path)
+        report_inputs(globs=[(root, "**/*.py"), *((root, pattern) for pattern in globs)])
+        paths = {
+            path
+            for path in root.rglob("*.py")
+            if not any(path.relative_to(root).full_match(pattern) for pattern in excludes)
+        }
+        for pattern in globs:
+            paths.update(root.glob(pattern))
+        for path in sorted(paths):
+            relative = path.relative_to(root)
+            if path.is_file():
+                files[f"{entry.name}/{relative.as_posix()}"] = hashlib.sha256(path.read_bytes()).hexdigest()
+    modules = {
+        f"integration:{dotted.rpartition('.')[0]}": dotted.rpartition(".")[0] for dotted in integrations
+    }
+    for entry in normalized:
+        config_class = import_string(entry.config)
+        if not isinstance(config_class, type) or not issubclass(config_class, AppConfig):
+            raise ImproperlyConfigured(f"Selected config must be an AppConfig class: {entry.config!r}")
+        for owner in config_class.__mro__:
+            if owner is not object:
+                modules[f"config:{owner.__module__}"] = owner.__module__
+    for key, module in sorted(modules.items()):
+        location = resolver.resolve(module)
+        if location.path is not None:
+            report_inputs(files=[location.path])
+        if location.kind in {"builtin", "frozen"}:
+            # The interpreter version owns implementations without a source file.
+            data = repr(
+                (
+                    module,
+                    location.kind,
+                    sys.implementation.name,
+                    tuple(sys.implementation.version),
+                    tuple(sys.version_info),
+                )
+            ).encode()
+        elif location.path is not None and location.path.is_file():
+            data = location.path.read_bytes()
+        else:
+            raise ImproperlyConfigured(f"Cannot fingerprint module {module!r}")
+        files[key] = hashlib.sha256(data).hexdigest()
+    return Snapshot(
+        normalized,
+        tuple(sorted(files.items())),
+        integrations,
+        _fingerprints(records, resolver),
+        records,
+        _freeze(authored),
+        _freeze(effective_settings),
+        dependencies=_freeze(edges),
+    )

django_compose/sources.py

@@ -0,0 +1,147 @@
+"""Import-free module locations and exact installed-distribution file ownership."""
+
+from __future__ import annotations
+
+import json
+import sys
+import sysconfig
+from collections.abc import Iterable
+from dataclasses import dataclass
+from importlib import metadata
+from importlib.machinery import BuiltinImporter, FrozenImporter, ModuleSpec, PathFinder
+from pathlib import Path
+from typing import Protocol
+from urllib.parse import unquote, urlsplit
+
+
+class AppSource(Protocol):
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def path(self) -> str: ...
+
+
+@dataclass(frozen=True)
+class ModuleSource:
+    module: str
+    path: Path | None
+    kind: str
+    distributions: tuple[str, ...] = ()
+    app: str | None = None
+    search_locations: tuple[Path, ...] = ()
+
+
+class SourceResolver:
+    """Resolve without executing packages; keep metadata indexing local to one audit."""
+
+    def __init__(
+        self,
+        entries: Iterable[AppSource] = (),
+        *,
+        distributions: Iterable[metadata.Distribution] | None = None,
+    ) -> None:
+        self.entries = tuple(sorted(entries, key=lambda entry: -len(entry.name)))
+        self._distributions = distributions
+        self._files: dict[Path, set[str]] | None = None
+        self._projects: list[tuple[Path, str]] = []
+
+    def distribution_names(self, path: Path) -> tuple[str, ...]:
+        """Match RECORD files or a PEP 610 local project directory, never package names."""
+        if self._files is None:
+            self._files = {}
+            distributions = self._distributions
+            for distribution in metadata.distributions() if distributions is None else distributions:
+                name = distribution.metadata["Name"]
+                if not name:
+                    continue
+                for file in distribution.files or ():
+                    location = Path(str(distribution.locate_file(file))).resolve()
+                    self._files.setdefault(location, set()).add(name)
+                direct = distribution.read_text("direct_url.json")
+                if direct:
+                    try:
+                        record = json.loads(direct)
+                        url = urlsplit(record.get("url", ""))
+                        if "dir_info" in record and url.scheme == "file" and url.netloc in ("", "localhost"):
+                            self._projects.append((Path(unquote(url.path)).resolve(), name))
+                    except ValueError, TypeError, AttributeError:
+                        continue
+        location = path.resolve()
+        names = self._files.get(location, set()).copy()
+        if location.is_dir():
+            names.update(
+                name
+                for file, owners in self._files.items()
+                if file.is_relative_to(location)
+                for name in owners
+            )
+        names.update(name for root, name in self._projects if location.is_relative_to(root))
+        return tuple(sorted(names))
+
+    @staticmethod
+    def _find(parts: list[str], locations: Iterable[str] | None = None) -> ModuleSpec | None:
+        search = list(locations) if locations is not None else None
+        for index, part in enumerate(parts):
+            spec = PathFinder.find_spec(part, search)
+            if spec is None:
+                return None
+            if index == len(parts) - 1:
+                return spec
+            if spec.submodule_search_locations is None:
+                return None
+            search = list(spec.submodule_search_locations)
+        return None
+
+    def resolve(self, module: str) -> ModuleSource:
+        if not module or not all(part and ("_" + part).isidentifier() for part in module.split(".")):
+            return ModuleSource(module, None, "unresolved")
+        for finder, kind in ((BuiltinImporter, "builtin"), (FrozenImporter, "frozen")):
+            if finder.find_spec(module) is not None:
+                return ModuleSource(module, None, kind)
+        spec = None
+        for entry in self.entries:
+            if module == entry.name:
+                spec = ModuleSpec(module, loader=None, is_package=True)
+                spec.submodule_search_locations = [entry.path]
+                candidate = Path(entry.path) / "__init__.py"
+                if candidate.is_file():
+                    spec.origin = str(candidate)
+            elif module.startswith(entry.name + "."):
+                spec = self._find(module[len(entry.name) + 1 :].split("."), (entry.path,))
+            if spec is not None:
+                break
+        if spec is None:
+            spec = self._find(module.split("."))
+        if spec is None:
+            return ModuleSource(module, None, "unresolved")
+        locations = tuple(Path(path).resolve() for path in spec.submodule_search_locations or ())
+        path = Path(spec.origin).resolve() if spec.origin else next(iter(locations), None)
+        if path is None:
+            return ModuleSource(module, None, "unresolved")
+        paths = sysconfig.get_paths()
+        site_roots = {Path(paths[key]).resolve() for key in ("purelib", "platlib")}
+        if (
+            module.partition(".")[0] in sys.stdlib_module_names
+            and path.is_relative_to(Path(paths["stdlib"]).resolve())
+            and not any(path.is_relative_to(root) for root in site_roots)
+        ):
+            return ModuleSource(module, path, "stdlib")
+        ownership_paths = (path,) if spec.origin else locations
+        names = tuple(
+            sorted({name for source in ownership_paths for name in self.distribution_names(source)})
+        )
+        app = next(
+            (entry.name for entry in self.entries if path.is_relative_to(Path(entry.path).resolve())), None
+        )
+        return ModuleSource(
+            module, path, "distribution" if names else "app" if app else "project", names, app, locations
+        )
+
+
+def resolve_module(module: str, entries: Iterable[AppSource] = ()) -> ModuleSource:
+    return SourceResolver(entries).resolve(module)
+
+
+def distribution_names(path: Path) -> tuple[str, ...]:
+    return SourceResolver().distribution_names(path)