django-angular3 0.1.0__py3-none-any.whl

django_angular3/management/commands/export_schema.py

@@ -0,0 +1,106 @@
+"""Management command: export_schema
+
+Export the OpenAPI schema from DRF using drf-spectacular and persist it as a
+durable, versioned artifact at the path configured in ``openapi.source``.
+
+Before writing, the command rotates the existing schema to its ``.previous``
+counterpart (e.g. ``api.json`` → ``api.previous.json``) so that ``build_app``
+can compare the two versions for change detection without requiring the caller
+to manage file paths explicitly.
+
+Usage::
+
+    django-admin export_schema django-angular3.json
+    django-admin export_schema django-angular3.json --format yaml
+    django-admin export_schema django-angular3.json --dry-run
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from django.core.management.base import BaseCommand, CommandError
+
+from ...config import ConfigError, get_previous_schema_path, load_project_config
+
+
+class Command(BaseCommand):
+    help = (
+        "Export the OpenAPI schema from DRF (via drf-spectacular) and persist "
+        "it as a versioned artifact. The previous schema is archived alongside "
+        "the current one for use by build_app change detection."
+    )
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "config",
+            help="Path to the django-angular3.json project config file.",
+        )
+        parser.add_argument(
+            "--format",
+            dest="format",
+            choices=["json", "yaml"],
+            default="json",
+            help="Serialization format for the exported schema (default: json).",
+        )
+        parser.add_argument(
+            "--dry-run",
+            action="store_true",
+            help=(
+                "Generate the schema and display the artifact paths that would be "
+                "written, but do not modify any files on disk."
+            ),
+        )
+
+    def handle(self, *args, **options) -> None:
+        try:
+            config = load_project_config(options["config"])
+        except ConfigError as exc:
+            raise CommandError(str(exc)) from exc
+
+        destination = config.openapi_source
+        previous_path = get_previous_schema_path(destination)
+
+        if options["dry_run"]:
+            self.stdout.write("--- DRY RUN: export_schema ---")
+            self.stdout.write(f"  destination : {destination}")
+            if destination.exists():
+                self.stdout.write(
+                    f"  previous    : {previous_path}  (would archive current)"
+                )
+            self.stdout.write("  (no files written)")
+            return
+
+        # Generate the schema via drf-spectacular.
+        try:
+            from drf_spectacular.generators import (
+                SchemaGenerator,  # type: ignore[import-untyped]
+            )
+            from drf_spectacular.renderers import (  # type: ignore[import-untyped]
+                OpenApiJsonRenderer,
+                OpenApiYamlRenderer,
+            )
+        except ImportError as exc:  # pragma: no cover
+            raise CommandError(
+                "drf-spectacular is required for schema export. "
+                "Install it with: pip install drf-spectacular"
+            ) from exc
+
+        generator = SchemaGenerator()
+        schema = generator.get_schema(request=None, public=True)
+
+        renderer = (
+            OpenApiYamlRenderer()
+            if options["format"] == "yaml"
+            else OpenApiJsonRenderer()
+        )
+        schema_bytes: bytes = renderer.render(schema, renderer_context={})
+
+        # Rotate current → previous before writing the new schema.
+        if destination.exists():
+            destination.replace(previous_path)
+            self.stdout.write(f"Previous schema archived to: {previous_path}")
+
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_bytes(schema_bytes)
+        self.stdout.write(self.style.SUCCESS(f"Schema exported to: {destination}"))

django_angular3/management/commands/ng_add.py

@@ -0,0 +1,19 @@
+import argparse
+
+from ._base import AngularBaseCommand
+
+
+class Command(AngularBaseCommand):
+    angular_command_name = "ng_add"
+    help = "Run ng add for an Angular package in the configured workspace."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        super().add_arguments(parser)
+        parser.add_argument(
+            "--package",
+            default=None,
+            help="Package to add (defaults to setting: ng_add_package).",
+        )
+
+    def get_invocation_options(self, options: dict[str, object]) -> dict[str, object]:
+        return {"package": options.get("package")}

django_angular3/management/commands/ng_build.py

@@ -0,0 +1,6 @@
+from ._base import AngularBaseCommand
+
+
+class Command(AngularBaseCommand):
+    angular_command_name = "ng_build"
+    help = "Build the configured Angular application."

django_angular3/management/commands/ng_config.py

@@ -0,0 +1,6 @@
+from ._base import AngularBaseCommand
+
+
+class Command(AngularBaseCommand):
+    angular_command_name = "ng_config"
+    help = "Apply django-angular3 Angular workspace defaults."

django_angular3/management/commands/ng_gen_app.py

@@ -0,0 +1,22 @@
+import argparse
+
+from ._base import AngularBaseCommand
+
+
+class Command(AngularBaseCommand):
+    angular_command_name = "ng_gen_app"
+    help = "Generate an Angular application inside the configured workspace."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        super().add_arguments(parser)
+        parser.add_argument(
+            "--app-name",
+            default=None,
+            help=(
+                "Optional Angular application name. Defaults to "
+                "project.name from config."
+            ),
+        )
+
+    def get_invocation_options(self, options: dict[str, object]) -> dict[str, object]:
+        return {"app_name": options.get("app_name")}

django_angular3/management/commands/ng_new.py

@@ -0,0 +1,6 @@
+from ._base import AngularBaseCommand
+
+
+class Command(AngularBaseCommand):
+    angular_command_name = "ng_new"
+    help = "Create an empty Angular workspace for django-angular3."

django_angular3/management/commands/ng_openapi_gen.py

@@ -0,0 +1,6 @@
+from ._base import AngularBaseCommand
+
+
+class Command(AngularBaseCommand):
+    angular_command_name = "ng_openapi_gen"
+    help = "Run ng-openapi-gen for the configured OpenAPI source."

django_angular3/management/commands/ng_workspace.py

@@ -0,0 +1,6 @@
+from ._base import AngularBaseCommand
+
+
+class Command(AngularBaseCommand):
+    angular_command_name = "ng_workspace"
+    help = "Create and bootstrap an Angular workspace with angular-django2."

django_angular3/management/commands/ng_workspace_delete.py

@@ -0,0 +1,6 @@
+from ._base import AngularBaseCommand
+
+
+class Command(AngularBaseCommand):
+    angular_command_name = "ng_workspace_delete"
+    help = "Delete the generated Angular workspace entirely."

django_angular3/management/commands/ng_workspace_modify.py

@@ -0,0 +1,6 @@
+from ._base import AngularBaseCommand
+
+
+class Command(AngularBaseCommand):
+    angular_command_name = "ng_workspace_modify"
+    help = "Reapply angular-django2 workspace bootstrap and django-angular3 defaults."

django_angular3/migrations/__init__.py

@@ -0,0 +1,2 @@
+# This Django app does not currently define any models,
+# so there are no migrations to apply.

django_angular3/models.py

@@ -0,0 +1,2 @@
+# This Django app does not currently define any models.
+# Models may be added in the future if database-backed features are needed.

django_angular3/settings.py

@@ -0,0 +1,123 @@
+import os
+from collections.abc import Mapping, Sequence
+from types import SimpleNamespace
+from typing import Any
+
+
+class AngularCommandError(RuntimeError):
+    """Raised when an Angular command cannot be resolved or executed."""
+
+
+_is_win = os.name == "nt"
+
+DEFAULT_ANGULAR_SETTINGS: dict[str, Any] = {
+    "config_path": "django-angular3.json",
+    "node_executable": "node.exe" if _is_win else "node",
+    "pnpm_executable": "pnpm.cmd" if _is_win else "pnpm",
+    "ng_executable": "ng.cmd" if _is_win else "ng",
+    "command_allowlist": ("ng_openapi_gen",),
+    "package_manager": "pnpm",
+    "build_configuration": "production",
+    "style": "scss",
+    "routing": True,
+    "ng_add_package": "angular-django2",
+}
+
+
+class AngularSettings(SimpleNamespace):
+    """Configuration values used to resolve and run Angular-related commands.
+
+    Attributes:
+        config_path (str): Default project config path.
+        node_executable (str): Node executable name or path.
+        pnpm_executable (str): pnpm executable name or path.
+        ng_executable (str): Angular CLI executable name or path.
+        command_allowlist (tuple[str, ...]): Allowed resolved
+            django-angular3 command names.
+        package_manager (str): Angular package manager setting.
+        build_configuration (str): Angular build configuration name.
+        style (str): Default Angular stylesheet format.
+        routing (bool): Whether generated applications enable routing.
+        ng_add_package (str): The default package name or path to install for ng_add.
+    """
+
+
+def load_angular_settings(
+    overrides: Mapping[str, object] | None = None,
+) -> AngularSettings:
+    data = DEFAULT_ANGULAR_SETTINGS.copy()
+    data.update(_normalize_legacy_settings(_load_django_settings()))
+    if overrides:
+        data.update(_normalize_legacy_settings(overrides))
+    data["command_allowlist"] = _normalize_command_allowlist(
+        data.get("command_allowlist")
+    )
+    return AngularSettings(**data)
+
+
+def _load_django_settings() -> dict[str, object]:
+    try:
+        from django.conf import settings as django_settings
+        from django.core.exceptions import ImproperlyConfigured
+    except ImportError:
+        return {}
+
+    try:
+        if not getattr(django_settings, "configured", False):
+            return {}
+
+        value = getattr(django_settings, "DJANGO_ANGULAR3", {})
+    except ImproperlyConfigured:
+        return {}
+
+    if not isinstance(value, Mapping):
+        raise AngularCommandError(
+            "DJANGO_ANGULAR3 must be a dictionary-like mapping, got "
+            f"{type(value).__name__}."
+        )
+
+    return dict(value)
+
+
+def _normalize_legacy_settings(data: Mapping[str, object]) -> dict[str, object]:
+    normalized = dict(data)
+    if "pnpm_executable" not in normalized:
+        for legacy_key in ("npx_executable", "npm_executable"):
+            if legacy_key in normalized:
+                normalized["pnpm_executable"] = normalized[legacy_key]
+                break
+
+    normalized.pop("npm_executable", None)
+    normalized.pop("npx_executable", None)
+    return normalized
+
+
+def _normalize_command_allowlist(value: object) -> tuple[str, ...]:
+    if isinstance(value, str):
+        commands = (value,)
+    elif isinstance(value, Sequence):
+        commands = tuple(value)
+    else:
+        raise AngularCommandError(
+            "DJANGO_ANGULAR3['command_allowlist'] must be a string "
+            "or a sequence of strings."
+        )
+
+    normalized_commands: list[str] = []
+    for command in commands:
+        if not isinstance(command, str):
+            raise AngularCommandError(
+                "DJANGO_ANGULAR3['command_allowlist'] must only contain strings."
+            )
+
+        normalized_command = command.strip().lower()
+        if not normalized_command:
+            raise AngularCommandError(
+                "DJANGO_ANGULAR3['command_allowlist'] cannot contain "
+                "empty command names."
+            )
+
+        if normalized_command not in normalized_commands:
+            normalized_commands.append(normalized_command)
+
+    return tuple(normalized_commands)

django_angular3/tools.py

@@ -0,0 +1,134 @@
+import json
+import os
+import platform
+import tarfile
+import urllib.request
+import zipfile
+from pathlib import Path
+
+# Base directory for storing downloaded tools relative to this package
+PKG_DIR = Path(__file__).resolve().parent
+BIN_DIR = PKG_DIR / ".bin"
+
+
+def get_system_info():
+    """Returns normalized OS and architecture strings."""
+    os_name = platform.system().lower()
+    if os_name == "darwin":
+        os_name = "macos"
+
+    arch = platform.machine().lower()
+    if arch in ["x86_64", "amd64"]:
+        arch = "amd64"
+    elif arch in ["arm64", "aarch64"]:
+        arch = "arm64"
+    elif arch in ["i386", "i686", "x86"]:
+        arch = "386"
+
+    return os_name, arch
+
+
+def get_latest_oasdiff_release():
+    """Fetches the latest release info from oasdiff GitHub repository."""
+    url = "https://api.github.com/repos/Tufin/oasdiff/releases/latest"
+    req = urllib.request.Request(url, headers={"User-Agent": "django-angular3"})
+    try:
+        with urllib.request.urlopen(req) as response:
+            data = json.loads(response.read().decode("utf-8"))
+            return data
+    except Exception as e:
+        raise RuntimeError(f"Failed to fetch latest oasdiff version: {e}")
+
+
+def get_download_url(release_data, os_name, arch):
+    """Finds the correct asset URL for the current OS and architecture."""
+    # oasdiff release naming pattern: oasdiff_<version>_<os>_<arch>.tar.gz/zip
+    # e.g., oasdiff_1.21.3_linux_amd64.tar.gz
+    # e.g., oasdiff_1.21.3_windows_amd64.zip
+
+    # Map our normalized OS name to oasdiff's naming conventions
+    # sometimes they use darwin, sometimes macos.
+    search_os = "darwin" if os_name == "macos" else os_name
+
+    # In recent versions, windows is windows, linux is linux.
+
+    for asset in release_data.get("assets", []):
+        name = asset["name"].lower()
+        if search_os in name and arch in name:
+            if name.endswith(".tar.gz") or name.endswith(".zip"):
+                return asset["browser_download_url"], asset["name"]
+
+    raise RuntimeError(
+        f"Could not find a suitable oasdiff binary for {os_name} {arch}."
+    )
+
+
+def extract_archive(archive_path, extract_to):
+    """Extracts a .zip or .tar.gz archive."""
+    if archive_path.name.endswith(".zip"):
+        with zipfile.ZipFile(archive_path, "r") as zip_ref:
+            zip_ref.extractall(extract_to)
+    elif archive_path.name.endswith(".tar.gz"):
+        with tarfile.open(archive_path, "r:gz") as tar_ref:
+            if hasattr(tarfile, "data_filter"):
+                tar_ref.extractall(extract_to, filter="data")
+            else:
+                tar_ref.extractall(extract_to)
+    else:
+        raise ValueError(f"Unsupported archive format: {archive_path.name}")
+
+
+def ensure_oasdiff():
+    """
+    Ensures oasdiff is installed and available.
+    Returns the absolute path to the oasdiff executable.
+    """
+    BIN_DIR.mkdir(parents=True, exist_ok=True)
+
+    exe_name = "oasdiff.exe" if platform.system().lower() == "windows" else "oasdiff"
+    oasdiff_path = BIN_DIR / exe_name
+
+    if oasdiff_path.exists():
+        # Check if it's executable
+        if not os.access(oasdiff_path, os.X_OK):
+            oasdiff_path.chmod(0o755)
+        return str(oasdiff_path)
+
+    print(f"oasdiff not found. Downloading to {BIN_DIR}...")
+
+    try:
+        os_name, arch = get_system_info()
+        release_data = get_latest_oasdiff_release()
+        url, asset_name = get_download_url(release_data, os_name, arch)
+
+        archive_path = BIN_DIR / asset_name
+
+        print(f"Downloading from {url}...")
+        urllib.request.urlretrieve(url, archive_path)
+
+        print("Extracting...")
+        extract_archive(archive_path, BIN_DIR)
+
+        # Clean up archive
+        archive_path.unlink()
+
+        # Verify it was extracted properly
+        if not oasdiff_path.exists():
+            raise RuntimeError(
+                f"Extraction completed, but {exe_name} was not found in {BIN_DIR}."
+            )
+
+        if os_name != "windows":
+            oasdiff_path.chmod(0o755)
+
+        print("oasdiff downloaded and ready.")
+        return str(oasdiff_path)
+
+    except Exception as e:
+        raise RuntimeError(f"Failed to install oasdiff: {e}")
+
+
+if __name__ == "__main__":
+    # Test the downloader
+    path = ensure_oasdiff()
+    print(f"oasdiff is located at: {path}")

django_angular3/urls.py

@@ -0,0 +1,6 @@
+# This Django app does not currently define any URL patterns.
+# URL patterns may be added in the future if web endpoints are needed.
+
+
+app_name = "django_angular3"
+urlpatterns = []

django_angular3/validation.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .config import ProjectConfig
+from .documents import DocumentError, load_document
+
+
+class ValidationError(ValueError):
+    """Raised when validation cannot continue."""
+
+
+def validate_openapi_document(document: Any) -> list[str]:
+    errors: list[str] = []
+    if not isinstance(document, dict):
+        return ["OpenAPI document must be a mapping."]
+
+    if not any(key in document for key in ("openapi", "swagger")):
+        errors.append("OpenAPI document must declare either 'openapi' or 'swagger'.")
+
+    paths = document.get("paths")
+    if not isinstance(paths, dict):
+        errors.append("OpenAPI document must contain a 'paths' mapping.")
+        return errors
+
+    if not paths:
+        errors.append("OpenAPI document must define at least one path.")
+        return errors
+
+    allowed_methods = {
+        "get",
+        "put",
+        "post",
+        "delete",
+        "options",
+        "head",
+        "patch",
+        "trace",
+    }
+
+    for path_name, path_item in paths.items():
+        if not isinstance(path_name, str) or not path_name.startswith("/"):
+            errors.append(
+                f"OpenAPI path '{path_name}' must be a string starting with '/'."
+            )
+            continue
+        if not isinstance(path_item, dict):
+            errors.append(f"OpenAPI path '{path_name}' must map to an object.")
+            continue
+
+        operations = [name for name in path_item if name in allowed_methods]
+        if not operations:
+            errors.append(
+                f"OpenAPI path '{path_name}' must define at least one HTTP operation."
+            )
+            continue
+
+        for operation_name in operations:
+            operation = path_item[operation_name]
+            if not isinstance(operation, dict):
+                errors.append(
+                    f"Operation '{operation_name}' on path "
+                    f"'{path_name}' must be an object."
+                )
+
+    return errors
+
+
+def validate_ui_document(document: Any) -> list[str]:
+    errors: list[str] = []
+    if not isinstance(document, dict):
+        return ["UI definition document must be a mapping."]
+
+    pages = document.get("pages", [])
+    forms = document.get("forms", [])
+
+    if not isinstance(pages, list):
+        errors.append("'pages' must be a list when provided.")
+    else:
+        for index, page in enumerate(pages):
+            if not isinstance(page, dict):
+                errors.append(f"pages[{index}] must be an object.")
+                continue
+            route = page.get("route")
+            kind = page.get("kind")
+            if not isinstance(route, str) or not route.startswith("/"):
+                errors.append(
+                    f"pages[{index}].route must be a string starting with '/'."
+                )
+            if not isinstance(kind, str) or not kind.strip():
+                errors.append(f"pages[{index}].kind must be a non-empty string.")
+
+    if not isinstance(forms, list):
+        errors.append("'forms' must be a list when provided.")
+    else:
+        for index, form in enumerate(forms):
+            if not isinstance(form, dict):
+                errors.append(f"forms[{index}] must be an object.")
+                continue
+            form_id = form.get("id")
+            mode = form.get("mode")
+            submit = form.get("submit")
+            if not isinstance(form_id, str) or not form_id.strip():
+                errors.append(f"forms[{index}].id must be a non-empty string.")
+            if not isinstance(mode, str) or not mode.strip():
+                errors.append(f"forms[{index}].mode must be a non-empty string.")
+            if submit is not None:
+                if not isinstance(submit, dict):
+                    errors.append(
+                        f"forms[{index}].submit must be an object when provided."
+                    )
+                else:
+                    action = submit.get("action")
+                    if not isinstance(action, str) or not action.strip():
+                        errors.append(
+                            f"forms[{index}].submit.action must be a non-empty string."
+                        )
+
+    return errors
+
+
+def validate_openapi_file(path: str | Path) -> list[str]:
+    try:
+        document = load_document(path)
+    except DocumentError as exc:
+        return [str(exc)]
+    return validate_openapi_document(document)
+
+
+def validate_ui_file(path: str | Path) -> list[str]:
+    try:
+        document = load_document(path)
+    except DocumentError as exc:
+        return [str(exc)]
+    return validate_ui_document(document)
+
+
+def validate_project_config(config: ProjectConfig) -> list[str]:
+    errors: list[str] = []
+
+    if not config.openapi_source.exists():
+        errors.append(f"OpenAPI source does not exist: {config.openapi_source}")
+    else:
+        errors.extend(validate_openapi_file(config.openapi_source))
+
+    if not config.ui_source.exists():
+        errors.append(f"UI source does not exist: {config.ui_source}")
+    else:
+        errors.extend(validate_ui_file(config.ui_source))
+
+    if config.angular_output.exists() and not config.angular_output.is_dir():
+        errors.append(
+            "Angular output path must be a directory when it exists: "
+            f"{config.angular_output}"
+        )
+
+    if config.openapi_generator_config and not config.openapi_generator_config.exists():
+        errors.append(
+            "OpenAPI Generator config does not exist: "
+            f"{config.openapi_generator_config}"
+        )
+
+    if config.ng_openapi_gen_config and not config.ng_openapi_gen_config.exists():
+        errors.append(
+            f"ng-openapi-gen config does not exist: {config.ng_openapi_gen_config}"
+        )
+
+    return errors

django_angular3/views.py

@@ -0,0 +1,2 @@
+# This Django app does not currently define any views.
+# Views may be added in the future if web endpoints are needed.