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

django_compose/management/__init__.py

@@ -0,0 +1,221 @@
+"""Native Django dispatch with composition and post-setup execution contexts."""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import subprocess
+import sys
+import tempfile
+from contextlib import ExitStack
+from types import MappingProxyType
+from typing import Any
+
+from django.apps import apps
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from django.core.management import ManagementUtility
+from django.core.management.base import CommandError, handle_default_options
+from django.utils import autoreload
+from django.utils.module_loading import import_string
+
+from django_compose.autoreload import inputs, report_inputs, write_report
+
+MIGRATION_COMMANDS = frozenset(
+    {"makemigrations", "migrate", "check_migrations", "retire_history", "reset_migration_history"}
+)
+
+
+def require_serving_mode() -> None:
+    """Migration commands require a process populated from verified serving apps."""
+    if "DJANGO_COMPOSE_MODE" in os.environ:
+        raise CommandError("Migration commands require serving mode; unset DJANGO_COMPOSE_MODE")
+
+
+class _Dispatch:
+    def __init__(self, command: Any) -> None:
+        self.command = command
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.command, name)
+
+    def run_from_argv(self, argv: list[str]) -> Any:
+        """Adapt native execute after parsing, retaining the winning argv dispatcher.
+
+        Custom run_from_argv implementations must call self.execute to participate.
+        Factories receive command, original argv and read-only shallow-copied options.
+        The native dispatcher continues to own parsing, errors and connection cleanup.
+        """
+        original_execute = self.command.execute
+        missing = object()
+        previous = vars(self.command).get("execute", missing)
+        original_argv = tuple(argv)
+
+        def execute(*args: Any, **options: Any) -> Any:
+            with ExitStack() as stack:
+                # runserver recovery fabricates ready flags, but not ready_event.
+                if apps.ready_event.is_set():
+                    parsed_options = MappingProxyType(options.copy())
+                    for dotted in getattr(settings, "COMPOSE_COMMAND_CONTEXT", ()):
+                        stack.enter_context(
+                            import_string(dotted)(original_argv[1], original_argv, parsed_options)
+                        )
+                return original_execute(*args, **options)
+
+        self.command.execute = execute
+        try:
+            return self.command.run_from_argv(argv)
+        finally:
+            if previous is missing:
+                del self.command.execute
+            else:
+                self.command.execute = previous
+
+
+class _Utility(ManagementUtility):
+    def fetch_command(self, subcommand: str) -> Any:
+        return _Dispatch(super().fetch_command(subcommand))
+
+
+def _default_options(arguments: list[str]) -> Any:
+    from django_compose.management.commands.compose import Command
+
+    parser = Command().create_parser(arguments[0], "compose")
+    options, _ = parser.parse_known_args(arguments[2:])
+    handle_default_options(options)
+    return options
+
+
+def _fallback_inputs() -> None:
+    module = os.environ.get("DJANGO_SETTINGS_MODULE")
+    if module:
+        from django_compose.sources import SourceResolver
+
+        try:
+            location = SourceResolver(()).resolve(module)
+            if location.path is not None:
+                report_inputs(files=[location.path])
+        except ImportError, ImproperlyConfigured, ValueError:
+            pass
+    exception = sys.exc_info()[1]
+    filename = getattr(exception, "filename", None)
+    if filename:
+        report_inputs(files=[filename])
+    if exception is not None:
+        traceback = exception.__traceback__
+        while traceback is not None:
+            report_inputs(files=[traceback.tb_frame.f_code.co_filename])
+            traceback = traceback.tb_next
+
+
+def _parent(arguments: list[str]) -> None:
+    """Compose before each native reloader child, without populating the parent."""
+    options = _default_options(arguments)
+    signal.signal(signal.SIGTERM, lambda *args: sys.exit(0))
+    environment = {**os.environ, autoreload.DJANGO_AUTORELOAD_ENV: "true"}
+    child_arguments = autoreload.get_child_arguments()
+    # The compose subprocess uses this launcher, independent of manage.py imports.
+    bootstrap = "from django_compose.management import execute; import sys; execute(sys.argv[1:])"
+    defaults = [f"--pythonpath={options.pythonpath}"] if options.pythonpath else []
+    for name in ("DJANGO_SETTINGS_MODULE",):
+        if name in os.environ:
+            environment[name] = os.environ[name]
+    while True:
+        with tempfile.TemporaryFile(mode="w+") as report:
+            command = [
+                sys.executable,
+                "-c",
+                bootstrap,
+                arguments[0],
+                "compose",
+                "--if-stale",
+                "--report-inputs",
+                str(report.fileno()),
+                *defaults,
+            ]
+            result = subprocess.run(command, env=os.environ.copy(), pass_fds=(report.fileno(),))
+            report.seek(0)
+            payload = report.read()
+            if payload:
+                inputs.load(json.loads(payload))
+        if result.returncode:
+            reloader = autoreload.get_reloader()
+            inputs.attach(reloader)
+            print("Composition failed; waiting for input changes.", file=sys.stderr, flush=True)
+            try:
+                reloader.run_loop()
+            except SystemExit as exc:
+                if exc.code != 3:
+                    raise
+            continue
+        code = subprocess.run(child_arguments, env=environment, close_fds=False).returncode
+        if code != 3:
+            raise SystemExit(code)
+
+
+def execute(argv: list[str] | None = None) -> None:
+    """Drop-in management entrypoint retaining Django's native setup policy."""
+    arguments = list(sys.argv if argv is None else argv)
+    command = arguments[1] if len(arguments) > 1 else "help"
+    if command in MIGRATION_COMMANDS:
+        require_serving_mode()
+    if (
+        command == "runserver"
+        and "--noreload" not in arguments
+        and not any(arg in {"--help", "-h", "--version"} for arg in arguments)
+        and os.environ.get(autoreload.DJANGO_AUTORELOAD_ENV) != "true"
+    ):
+        try:
+            _parent(arguments)
+        except KeyboardInterrupt:
+            pass
+        return
+    report_fd = None
+    old_wait = os.environ.get("DJANGO_COMPOSE_WAIT")
+    from django_compose.serving import _close_build, _close_startup_verification
+
+    try:
+        if command == "compose":
+            from django_compose.management.commands.compose import Command
+
+            if "--help" in arguments[2:] or "-h" in arguments[2:]:
+                Command().create_parser(arguments[0], "compose").print_help()
+                return
+            options = _default_options(arguments)
+            report_fd = options.report_inputs
+            if settings.configured:
+                raise ImproperlyConfigured("Select compose mode before Django settings load")
+            expected = "check" if options.check else "write"
+            existing = os.environ.get("DJANGO_COMPOSE_MODE")
+            if existing is not None and existing != expected:
+                raise ImproperlyConfigured("DJANGO_COMPOSE_MODE conflicts with compose arguments")
+            os.environ["DJANGO_COMPOSE_MODE"] = expected
+            os.environ["DJANGO_COMPOSE_WAIT"] = str(options.wait)
+            sys.dont_write_bytecode = True
+            if options.if_stale:
+                from django_compose.serving import verify
+
+                # Settings computes the immutable snapshot; no native setup occurs here.
+                snap = settings.COMPOSE_SNAPSHOT
+                try:
+                    verify(snap, settings.COMPOSE_OUTPUT_MODULE)
+                except ImproperlyConfigured:
+                    pass
+                else:
+                    print(f"Composition lock: {settings.COMPOSE_OUTPUT_DIR}/.compose.lock")
+                    print("Composition is current.")
+                    return
+        _Utility(arguments).execute()
+    finally:
+        try:
+            _fallback_inputs()
+            if report_fd is not None:
+                write_report(report_fd)
+        finally:
+            _close_build()
+            _close_startup_verification()
+            if old_wait is None:
+                os.environ.pop("DJANGO_COMPOSE_WAIT", None)
+            else:
+                os.environ["DJANGO_COMPOSE_WAIT"] = old_wait

django_compose/management/commands/__init__.py

@@ -0,0 +1 @@
+"""Django command discovery package."""

django_compose/management/commands/check_migrations.py

@@ -0,0 +1,57 @@
+"""Check native history or audit its retained Python import providers."""
+
+from typing import Any
+
+from django.apps import apps
+from django.core.management.base import BaseCommand, CommandError, CommandParser
+from django.db.migrations.loader import MigrationLoader
+
+from django_compose.management import require_serving_mode
+from django_compose.management.commands.makemigrations import history_labels
+from django_compose.migration_imports import MigrationImportReport
+from django_compose.migrations import TransitionBinding
+
+
+class Command(BaseCommand):
+    help = "Check native history and pending transitions, or audit retained Python imports."
+    requires_system_checks: list[str] = []
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        parser.add_argument("--imports", action="store_true", help="Audit imports without database access.")
+        parser.add_argument("--removing", nargs="+", metavar="DIST", help="Prove named providers removable.")
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        require_serving_mode()
+        if options.get("removing") and not options.get("imports"):
+            raise CommandError("--removing requires --imports")
+        if options.get("imports"):
+            report = MigrationImportReport()
+            items = report.collect()
+            for item in items:
+                providers = ", ".join(item.distributions)
+                detail = ": ".join(value for value in (item.kind, providers, item.detail) if value)
+                self.stdout.write(f"{item.path}: {item.module}: {detail}")
+            loader_error = None
+            if any(item.kind == "unsupported" for item in items):
+                # In particular, never execute opaque compiled migrations merely
+                # to obtain loader diagnostics for a static import report.
+                loader_error = "Native migration loader skipped: report has unsupported sources or imports"
+                self.stdout.write(loader_error)
+            else:
+                try:
+                    MigrationLoader(None, ignore_no_migrations=True)
+                except Exception as error:
+                    loader_error = f"Native migration loader: {type(error).__name__}: {error}"
+                    self.stdout.write(loader_error)
+            if options.get("removing"):
+                refusals = list(report.removal_refusals(options["removing"]))
+                if loader_error:
+                    refusals.append(loader_error)
+                if refusals:
+                    raise CommandError("Cannot remove distributions:\n" + "\n".join(refusals))
+                self.stdout.write("No retained history or enabled app requires the named distributions.")
+            return
+        try:
+            TransitionBinding(labels=history_labels()).check_native_history(apps)
+        except RuntimeError as error:
+            raise CommandError(str(error)) from error

django_compose/management/commands/compose.py

@@ -0,0 +1,42 @@
+"""Report the composition performed by native phase-2 population."""
+
+import math
+from argparse import ArgumentParser, ArgumentTypeError
+from pathlib import Path
+from typing import Any
+
+from django.apps import apps
+from django.conf import settings
+from django.core.management.base import BaseCommand, CommandError
+
+from django_compose.serving import mode
+
+
+def _wait(value: str) -> float:
+    seconds = float(value)
+    if not math.isfinite(seconds) or seconds < 0:
+        raise ArgumentTypeError("wait must be finite and nonnegative")
+    return seconds
+
+
+class Command(BaseCommand):
+    help = "Compose concrete models and capability artifacts."
+    requires_system_checks = []
+
+    def add_arguments(self, parser: ArgumentParser) -> None:
+        parser.add_argument("--check", action="store_true", help="Compare output without writing files")
+        parser.add_argument("--if-stale", action="store_true", help="Skip setup when already current")
+        parser.add_argument("--report-inputs", type=int, metavar="FD", help="Write input JSON to descriptor")
+        parser.add_argument("--wait", type=_wait, default=5.0, metavar="SECONDS", help="Writer lock timeout")
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        expected = "check" if options["check"] else "write"
+        config = apps.get_app_config("django_compose")
+        if mode() != expected or getattr(config, "compose_mode", None) != expected:
+            raise CommandError(
+                "Set DJANGO_COMPOSE_MODE before settings load or use "
+                "django_compose.management.execute; direct django-admin compose requires the mode variable"
+            )
+
+        self.stdout.write(f"Composition lock: {Path(settings.COMPOSE_OUTPUT_DIR) / '.compose.lock'}")
+        self.stdout.write("Composition is current." if options["check"] else "Composition generated.")

django_compose/management/commands/makemigrations.py

@@ -0,0 +1,136 @@
+"""Author initial schema, bind transitions, then reconcile native model changes."""
+
+from __future__ import annotations
+
+import importlib
+from pathlib import Path
+from typing import Any
+
+from django.apps import apps
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from django.core.management.base import CommandError
+from django.core.management.commands.makemigrations import Command as NativeCommand
+from django.db.migrations import Migration
+from django.db.migrations.loader import MigrationLoader
+from django.db.migrations.writer import MigrationWriter
+from django.utils.module_loading import module_dir
+
+from django_compose.management import require_serving_mode
+from django_compose.migrations import (
+    DropGuardAutodetector,
+    TransitionBinding,
+    _metadata,
+)
+from django_compose.serving import read_receipt
+
+
+def history_labels() -> tuple[str, ...]:
+    """Read the compiler receipt without invoking composition."""
+    receipt = read_receipt(Path(settings.COMPOSE_OUTPUT_DIR))
+    if receipt is None:
+        raise CommandError("Migration authoring requires a receipt; run compose first")
+    return tuple(receipt.HISTORY_LABELS)
+
+
+class Command(NativeCommand):
+    """Keep native authoring and add immutable reusable origin binding."""
+
+    autodetector = DropGuardAutodetector
+    _initial_history: frozenset[str] | None = None
+
+    def handle(self, *app_labels: str, **options: Any) -> str | None:
+        require_serving_mode()
+        name = options.get("name")
+        if name and not name.isidentifier():
+            return super().handle(*app_labels, **options)
+        for label in app_labels:
+            try:
+                apps.get_app_config(label)
+            except LookupError:
+                return super().handle(*app_labels, **options)
+        labels = history_labels()
+        loader = MigrationLoader(None, ignore_no_migrations=True)
+        initialized = frozenset(label for label, _ in loader.disk_migrations)
+        initial = {
+            label
+            for label in labels
+            if label not in initialized
+            and (not app_labels or label in app_labels)
+            and MigrationLoader.migrations_module(label)[0] is not None
+            and any(apps.get_app_config(label).get_models())
+        }
+        selected = set(app_labels) if app_labels else None
+        if initial:
+            for flag in ("merge", "empty", "update"):
+                if options.get(flag):
+                    raise CommandError(f"--{flag} is not applicable before initial schema authoring")
+            self._initial_history = initialized
+            try:
+                super().handle(*sorted(initial), **options)
+            finally:
+                self._initial_history = None
+            if options.get("dry_run") or options.get("check_changes"):
+                return None
+            if selected is not None:
+                # Native dependency expansion can initialize other fresh apps.
+                current = MigrationLoader(None, ignore_no_migrations=True)
+                selected.update(label for label, _ in current.disk_migrations if label not in initialized)
+        if options.get("merge"):
+            return super().handle(*app_labels, **options)
+        authored = TransitionBinding(labels=labels)
+        try:
+            if options.get("dry_run") or options.get("check_changes"):
+                authored.check(app_labels=selected)
+            else:
+                authored.materialize(apps, app_labels=selected)
+        except (RuntimeError, ImproperlyConfigured) as error:
+            raise CommandError(str(error)) from error
+        return super().handle(*app_labels, **options)
+
+    def write_migration_files(
+        self,
+        changes: dict[str, list[Migration]],
+        update_previous_migration_paths: dict[str, str] | None = None,
+    ) -> None:
+        """Preflight every destination before handing serialization to Django."""
+        if self._initial_history is not None:
+            existing = sorted(set(changes) & self._initial_history)
+            if existing:
+                raise CommandError(
+                    "Initial schema depends on changes to existing apps; "
+                    "author their transitions first: " + ", ".join(existing)
+                )
+        destinations = set()
+        paths = set()
+        for label, migrations in changes.items():
+            for migration in migrations:
+                if update_previous_migration_paths and _metadata(migration, "origin") is not None:
+                    raise CommandError(
+                        "Cannot update immutable authored migration; create a follow-up migration"
+                    )
+                package, _ = MigrationLoader.migrations_module(label)
+                if package is None:
+                    raise CommandError(f"Migrations are disabled for app {label!r}")
+                writer = MigrationWriter(migration, self.include_header)
+                key = package, writer.filename
+                if key in destinations:
+                    raise CommandError(f"Multiple migrations target {key!r}")
+                destinations.add(key)
+                try:
+                    directory = Path(module_dir(importlib.import_module(package)))
+                except ModuleNotFoundError as error:
+                    if error.name is None or not (
+                        package == error.name or package.startswith(error.name + ".")
+                    ):
+                        raise
+                    if self.dry_run:
+                        raise CommandError(
+                            f"Read-only authoring cannot create missing migration package {package!r}"
+                        ) from error
+                    continue
+                path = (directory / writer.filename).resolve()
+                if path in paths or path.exists():
+                    raise CommandError(f"Refusing to overwrite existing migration {path}")
+                paths.add(path)
+        return super().write_migration_files(changes, update_previous_migration_paths)

django_compose/management/commands/migrate.py

@@ -0,0 +1,18 @@
+"""Share native makemigrations' autodetector, as required by commands.E001."""
+
+from typing import Any
+
+from django.core.management.commands.migrate import Command as NativeCommand
+
+from django_compose.management import require_serving_mode
+from django_compose.migrations import DropGuardAutodetector
+
+
+class Command(NativeCommand):
+    """Apply native migrations with the shared model-change notice guard."""
+
+    autodetector = DropGuardAutodetector
+
+    def handle(self, *args: Any, **options: Any) -> Any:
+        require_serving_mode()
+        return super().handle(*args, **options)

django_compose/management/commands/reset_migration_history.py

@@ -0,0 +1,34 @@
+"""Explicitly retire fully applied, model-clean native migration history."""
+
+from typing import Any
+
+from django.core.management.base import BaseCommand, CommandError, CommandParser
+from django.db import DEFAULT_DB_ALIAS, connections
+
+from django_compose.management import require_serving_mode
+from django_compose.management.commands.makemigrations import history_labels
+from django_compose.migrations import reset_migration_history
+
+
+class Command(BaseCommand):
+    """Dispatch the separately guarded maintenance operation."""
+
+    help = "Replace selected fully applied migration histories with fresh initials."
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        parser.add_argument("app_labels", nargs="*")
+        parser.add_argument("--database", default=DEFAULT_DB_ALIAS, choices=tuple(connections))
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        require_serving_mode()
+        allowed = set(history_labels())
+        selected = set(options["app_labels"]) or allowed
+        if unknown := selected - allowed:
+            raise CommandError(f"Unknown composed apps: {', '.join(sorted(unknown))}")
+        try:
+            labels, removed, recorded = reset_migration_history(selected, database=options["database"])
+        except RuntimeError as error:
+            raise CommandError(str(error)) from error
+        self.stdout.write(
+            f"labels: {', '.join(labels)}; files removed: {removed}; migrations recorded: {recorded}"
+        )

django_compose/management/commands/retire_history.py

@@ -0,0 +1,24 @@
+"""Explicit retirement of disabled native migration history."""
+
+from typing import Any
+
+from django.core.management.base import BaseCommand, CommandError, CommandParser
+
+from django_compose.management import require_serving_mode
+from django_compose.migrations import retire_history
+
+
+class Command(BaseCommand):
+    help = "Retire history-only labels after routed database and dependency checks."
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        parser.add_argument("label")
+        parser.add_argument("--purge", action="store_true")
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        require_serving_mode()
+        try:
+            retire_history(options["label"], purge=options["purge"])
+        except RuntimeError as error:
+            raise CommandError(str(error)) from error
+        self.stdout.write(f"Retired history: {options['label']}")