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

django_compose/autoreload.py

@@ -0,0 +1,110 @@
+"""Compiler input evidence and adapters to Django's native reload backends."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from django.core.exceptions import ImproperlyConfigured
+from django.utils import autoreload
+
+
+class InputReport:
+    """Declared candidates survive failed reads and empty glob expansion."""
+
+    def __init__(self) -> None:
+        self.files: set[Path] = set()
+        self.globs: set[tuple[Path, str]] = set()
+
+    def add(self, *, files: Iterable[str | Path] = (), globs: Iterable[tuple[str | Path, str]] = ()) -> None:
+        self.files.update(Path(path).absolute() for path in files)
+        self.globs.update((Path(path).absolute(), pattern) for path, pattern in globs)
+
+    def payload(self) -> dict[str, Any]:
+        return {
+            "files": sorted(map(str, self.files)),
+            "globs": sorted((str(path), pattern) for path, pattern in self.globs),
+        }
+
+    def load(self, payload: dict[str, Any]) -> None:
+        self.add(files=payload["files"], globs=payload["globs"])
+
+    def state(self) -> tuple[dict[Path, bool], dict[tuple[Path, str], frozenset[Path]]]:
+        return (
+            {path: path.exists() for path in self.files},
+            {item: frozenset(item[0].glob(item[1])) for item in self.globs},
+        )
+
+    def attach(self, reloader: Any) -> None:
+        """Extend native tick polling, retaining native content-change detection."""
+        reloader.extra_files.update(self.files)
+        for directory, pattern in sorted(self.globs):
+            reloader.watch_dir(directory, pattern)
+        previous_files, previous_globs = self.state()
+        native_tick = reloader.tick
+
+        def tick() -> Any:
+            nonlocal previous_files, previous_globs
+            for result in native_tick():
+                current_files, current_globs = self.state()
+                changed = {
+                    path for path, exists in previous_files.items() if current_files.get(path) != exists
+                }
+                for item, members in previous_globs.items():
+                    changed.update(members ^ current_globs.get(item, frozenset()))
+                previous_files, previous_globs = current_files, current_globs
+                for path in sorted(changed):
+                    reloader.notify_file_changed(path)
+                yield result
+
+        reloader.tick = tick
+
+
+inputs = InputReport()
+
+
+def report_inputs(*, files: Iterable[str | Path] = (), globs: Iterable[tuple[str | Path, str]] = ()) -> None:
+    """Publish settings-reader candidates BEFORE reading, even when absent."""
+    inputs.add(files=files, globs=globs)
+
+
+def report_watch_paths(paths: Iterable[str | Path | tuple[str | Path, str]]) -> tuple[Any, ...]:
+    """Validate/report the mixed COMPOSE_WATCH_PATHS setting once at its owner."""
+    if isinstance(paths, (str, Path)):
+        raise ImproperlyConfigured(
+            "COMPOSE_WATCH_PATHS must be a sequence of files or (directory, glob) pairs"
+        )
+    normalized: list[Any] = []
+    for item in paths:
+        if isinstance(item, (str, Path)):
+            report_inputs(files=[item])
+            normalized.append(str(item))
+        elif (
+            isinstance(item, (tuple, list))
+            and len(item) == 2
+            and isinstance(item[0], (str, Path))
+            and isinstance(item[1], str)
+            and item[1]
+        ):
+            report_inputs(globs=[(item[0], item[1])])
+            normalized.append((str(item[0]), item[1]))
+        else:
+            raise ImproperlyConfigured("COMPOSE_WATCH_PATHS requires files or (directory, glob) pairs")
+    return tuple(normalized)
+
+
+def write_report(fd: int) -> None:
+    """Write a report to a caller-owned regular inherited descriptor."""
+    with os.fdopen(os.dup(fd), "w") as stream:
+        json.dump(inputs.payload(), stream)
+        stream.write("\n")
+
+
+def _started(sender: Any, **kwargs: Any) -> None:
+    inputs.attach(sender)
+
+
+autoreload.autoreload_started.connect(_started, weak=False, dispatch_uid="django_compose.inputs")

django_compose/build.py

@@ -0,0 +1,282 @@
+"""Compose-only model emission, concrete imports, artifacts and final publication."""
+
+from __future__ import annotations
+
+import importlib
+import os
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from django.apps import AppConfig, apps
+from django.apps.registry import Apps
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+
+from django_compose import serving
+from django_compose.artifacts import GeneratedTree, atomic_write, receipt_lock
+from django_compose.declarations import ArtifactHook, ModelDeclarationHook, ModelsView, model_declaration
+from django_compose.model_composition import ModelComposition
+from django_compose.rendering import render_models
+from django_compose.serving import Receipt, read_receipt, verify
+from django_compose.snapshot import Snapshot
+
+
+def discover(configs: Iterable[AppConfig]) -> ModelComposition:
+    return ModelComposition.discover(tuple(configs))
+
+
+@dataclass(frozen=True)
+class ConcreteModels:
+    composition: ModelComposition
+
+    def get_model(self, label: str, name: str) -> Any:
+        return apps.get_model(label, name, require_ready=False)
+
+
+class BuildPlan:
+    """One phase-2 build, retaining its writer lock until final publication."""
+
+    def __init__(
+        self,
+        snap: Snapshot,
+        configs: Iterable[AppConfig],
+        *,
+        mode: Literal["write", "check"],
+        integrations: tuple[object, ...],
+        transitions: Iterable[Any],
+        output_dir: Path,
+        output_module: str,
+    ) -> None:
+        if mode not in ("write", "check"):
+            raise ImproperlyConfigured("BuildPlan requires write or check mode")
+        if (
+            not all(part.isidentifier() for part in output_module.split("."))
+            or not output_dir.name.isidentifier()
+        ):
+            raise ImproperlyConfigured("Output package must have Python identifiers")
+        self.snapshot = snap
+        selected = {entry.name for entry in snap.entries}
+        self.configs = tuple(c for c in configs if c.name in selected)
+        self.mode = mode
+        self.integrations = integrations
+        self.transitions = tuple(transitions)
+        self.output_dir = output_dir
+        self.output_module = output_module
+        self.previous = read_receipt(output_dir)
+        self.sources: dict[Path, str | bytes] = {}
+        self._lock = receipt_lock(
+            output_dir,
+            write=mode == "write",
+            wait=float(os.environ["DJANGO_COMPOSE_WAIT"]) if "DJANGO_COMPOSE_WAIT" in os.environ else 5.0,
+        )
+        self._locked = False
+
+    @property
+    def labels(self) -> tuple[str, ...]:
+        return self.composition.labels
+
+    def _receipt(self, *, progress: bool, hashes: dict[str, str] | None = None) -> Receipt:
+        previous = self.previous
+        retired = previous.RETIRED_LABELS if previous else ()
+        history = set(previous.HISTORY_LABELS if previous else ())
+        history.update(getattr(self, "labels", ()))
+        history.update(path.parent.name for path in self.output_dir.glob("*/migrations") if path.is_dir())
+        history.update(transition["app_label"] for transition in self.transitions)
+        return Receipt(
+            tuple(sorted(history - set(retired))),
+            retired,
+            self.snapshot.digest(),
+            hashes if hashes is not None else (dict(previous.OWNED_FILES) if previous else {}),
+            self.snapshot.compiler,
+            tuple(getattr(self, "labels", ())),
+            progress,
+        )
+
+    def emit(self) -> BuildPlan:
+        self._lock.__enter__()
+        self._locked = True
+        try:
+            serving._register_build(self.close)
+            if self.mode == "check":
+                self.previous = verify(self.snapshot, self.output_module)
+            # Guard ownership before invalidation. A failed discovery remains invalid.
+            self.previous = GeneratedTree(self.output_dir, {})._validate()
+            if self.mode == "write":
+                receipt = self._receipt(progress=True)
+                if self.previous is None:
+                    self.sources.update({Path(label) / "__init__.py": "" for label in receipt.HISTORY_LABELS})
+                    receipt = self._receipt(
+                        progress=True, hashes=GeneratedTree(self.output_dir, self.sources).hashes()
+                    )
+                atomic_write(self.output_dir / "__init__.py", receipt.source().encode())
+            self.composition = discover(self.configs)
+            models = {model for config in self.configs for model in (config.models or {}).values()}
+            models.update(self.composition.ordered_models)
+            for source in self.composition.ordered_models:
+                models.update(self.composition.donors(source))
+            for model in sorted(models, key=lambda model: model._meta.label):
+                swappable = model._meta.swappable
+                if swappable and swappable not in self.snapshot.settings:
+                    raise ImproperlyConfigured(
+                        f"Swappable setting {swappable!r} for {model._meta.label} must be declared "
+                        "in COMPOSE_FINGERPRINT_SETTINGS"
+                    )
+            declarations = {
+                source: model_declaration(
+                    self.composition,
+                    source,
+                    tuple(h for h in self.integrations if isinstance(h, ModelDeclarationHook)),
+                )
+                for source in self.composition.ordered_models
+            }
+            history_labels = self._receipt(progress=True).HISTORY_LABELS
+            for label in history_labels:
+                self.sources[Path(label) / "__init__.py"] = ""
+                config = next((c for c in self.configs if c.label == label), None)
+                if config and label in self.labels:
+                    config_path = f"{type(config).__module__}.{type(config).__qualname__}"
+                    module, _, name = config_path.rpartition(".")
+                    model_module = f"{self.output_module}.{label}.models"
+                    body = (
+                        f"from {module} import {name} as SourceConfig\n\n"
+                        "class GeneratedConfig(SourceConfig):\n"
+                        f"    name = {config.name!r}\n    label = {label!r}\n\n"
+                        "    def import_models(self):\n"
+                        "        super().import_models()\n"
+                        "        from importlib import import_module\n"
+                        f"        self.models_module = import_module({model_module!r})\n"
+                    )
+                    self.sources[Path(label) / "apps.py"] = body
+                if label in self.labels:
+                    self.sources[Path(label) / "models.py"] = render_models(
+                        self.composition,
+                        label,
+                        runtime_module=self.output_module,
+                        declarations=declarations,
+                    )
+                migration_init = self.output_dir / label / "migrations" / "__init__.py"
+                effective = getattr(settings, "MIGRATION_MODULES", {}).get(
+                    label, f"{self.output_module}.{label}.migrations"
+                )
+                if effective == f"{self.output_module}.{label}.migrations" and not migration_init.exists():
+                    self.sources[Path(label) / "migrations" / "__init__.py"] = ""
+            if self.mode == "check":
+                changed = [
+                    p
+                    for p, value in self.sources.items()
+                    if not (self.output_dir / p).is_file()
+                    or (self.output_dir / p).read_bytes() != GeneratedTree._bytes(value)
+                ]
+                if changed:
+                    raise ImproperlyConfigured(f"Generated models are stale: {changed}; run compose")
+            else:
+                GeneratedTree(self.output_dir, self.sources).reconcile(prune=False)
+                provisional = dict(self.previous.OWNED_FILES) if self.previous else {}
+                provisional.update(GeneratedTree(self.output_dir, self.sources).hashes())
+                atomic_write(
+                    self.output_dir / "__init__.py",
+                    self._receipt(progress=True, hashes=provisional).source().encode(),
+                )
+            importlib.invalidate_caches()
+            for label in self.labels:
+                importlib.import_module(f"{self.output_module}.{label}.models")
+            return self
+        except BaseException:
+            self.close()
+            raise
+
+    def render_artifacts(self, models_view: ModelsView | Apps, hooks: Iterable[ArtifactHook]) -> None:
+        external = set(getattr(settings, "COMPOSE_EXTERNAL_ARTIFACT_ROOTS", ()))
+        receipt = self._receipt(progress=True)
+        reserved = {*receipt.MODEL_LABELS, *receipt.HISTORY_LABELS, *receipt.RETIRED_LABELS}
+        for hook in hooks:
+            root = Path(hook.external_root)
+            if (
+                root.is_absolute()
+                or len(root.parts) != 1
+                or root.name in {*reserved, "migrations", "__pycache__", ".."}
+                or root.as_posix() not in external
+            ):
+                raise ImproperlyConfigured(f"Undeclared artifact root: {hook.external_root!r}")
+            rendered = hook.render(self.composition, models_view)
+            GeneratedTree.validate_artifacts(self.output_dir, rendered)
+            for path, content in sorted(rendered.items()):
+                if (
+                    path in self.sources
+                    or len(path.parts) < 2
+                    or path.parts[0] != root.as_posix()
+                    or "migrations" in path.parts
+                ):
+                    raise ImproperlyConfigured(f"Competing or undeclared artifact: {path}")
+                if not isinstance(content, bytes):
+                    raise ImproperlyConfigured(f"ArtifactHook must render bytes: {path}")
+                self.sources[path] = content
+        tree = GeneratedTree(self.output_dir, self.sources)
+        tree._validate()
+        if self.mode == "check":
+            if any(
+                not (self.output_dir / path).is_file()
+                or (self.output_dir / path).read_bytes() != tree._bytes(value)
+                for path, value in self.sources.items()
+            ):
+                raise ImproperlyConfigured("Generated artifacts are stale; run compose")
+        else:
+            current = read_receipt(self.output_dir)
+            provisional = dict(current.OWNED_FILES) if current else {}
+            provisional.update(tree.hashes())
+            atomic_write(
+                self.output_dir / "__init__.py",
+                self._receipt(progress=True, hashes=provisional).source().encode(),
+            )
+            tree.reconcile(prune=False)
+        serving._publish_build_artifacts(
+            self.close, self.output_dir, self._receipt(progress=True, hashes=tree.hashes())
+        )
+
+    def finalize(self) -> Receipt:
+        try:
+            receipt = self._receipt(
+                progress=False, hashes=GeneratedTree(self.output_dir, self.sources).hashes()
+            )
+            tree = GeneratedTree(self.output_dir, self.sources)
+            if self.mode == "write":
+                tree.reconcile()
+                atomic_write(self.output_dir / "__init__.py", receipt.source().encode())
+            elif tree.drift() or self.previous != receipt:
+                raise ImproperlyConfigured("Generated receipt or artifacts are stale; run compose")
+            return receipt
+        finally:
+            self.close()
+
+    def close(self) -> None:
+        serving._clear_build(self.close)
+        if self._locked:
+            self._locked = False
+            self._lock.__exit__(None, None, None)
+
+
+def emit(
+    snap: Snapshot,
+    configs: Iterable[AppConfig],
+    *,
+    mode: Literal["write", "check"],
+    integrations: tuple[object, ...],
+    transitions: Iterable[Any],
+    output_dir: Path | str,
+    output_module: str,
+) -> BuildPlan:
+    return BuildPlan(
+        snap,
+        configs,
+        mode=mode,
+        integrations=integrations,
+        transitions=transitions,
+        output_dir=Path(output_dir),
+        output_module=output_module,
+    ).emit()
+
+
+def clean(output_dir: Path | str) -> tuple[Path, ...]:
+    return GeneratedTree(Path(output_dir), {}).clean()

django_compose/checks.py

@@ -0,0 +1,11 @@
+"""Bootstrap-safe registration of deferred native serving checks."""
+
+from django.core.checks import Error, Tags, register
+
+
+@register(Tags.urls)
+def check_url_collisions(**kwargs: object) -> list[Error]:
+    """Load URL policy only when native checks run after setup."""
+    from django_compose.urls import check_url_collisions as check
+
+    return check(**kwargs)

django_compose/cli.py

@@ -0,0 +1,12 @@
+"""The standalone launcher uses the same native management entrypoint."""
+
+from __future__ import annotations
+
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    from django_compose.management import execute
+
+    execute(["django-compose", *(sys.argv[1:] if argv is None else argv)])
+    return 0