django-angular3 0.1.0__py3-none-any.whl

django_angular3/cli.py

@@ -0,0 +1,313 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from .angular import (
+    AngularCommandError,
+    execute_invocations,
+    format_invocations,
+    resolve_angular_command,
+)
+from .build import create_build_plan, write_build_plan
+from .config import ConfigError, load_project_config
+from .validation import validate_openapi_file, validate_project_config, validate_ui_file
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="django-angular3")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    validate_openapi = subparsers.add_parser(
+        "validate-openapi", help="Validate an OpenAPI source document."
+    )
+    validate_openapi.add_argument("path", help="Path to the OpenAPI document.")
+
+    validate_ui = subparsers.add_parser(
+        "validate-ui", help="Validate a UI definition document."
+    )
+    validate_ui.add_argument("path", help="Path to the UI definition document.")
+
+    validate_project = subparsers.add_parser(
+        "validate-project", help="Validate a django-angular3 project configuration."
+    )
+    validate_project.add_argument(
+        "path",
+        nargs="?",
+        default="django-angular3.json",
+        help="Path to the project config.",
+    )
+
+    build = subparsers.add_parser(
+        "build", help="Validate a project and emit a deterministic build plan."
+    )
+    build.add_argument(
+        "path", nargs="?", default="django-angular3.json", help="Path to the config."
+    )
+    build.add_argument(
+        "--output",
+        default="build",
+        help="Directory where the build plan should be written.",
+    )
+    build.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the build plan instead of writing it to disk.",
+    )
+
+    ng_new = subparsers.add_parser("ng_new", help="Create an empty Angular workspace.")
+    ng_new.add_argument(
+        "path", nargs="?", default=None, help="Path to the project config."
+    )
+    ng_new.add_argument(
+        "--dry-run",
+        action="store_true",
+        help=(
+            "Print the resolved Angular subprocess call list instead of "
+            "invoking Angular tooling."
+        ),
+    )
+
+    ng_workspace = subparsers.add_parser(
+        "ng_workspace",
+        help="Bootstrap the configured Angular workspace with angular-django2.",
+    )
+    ng_workspace.add_argument(
+        "path", nargs="?", default=None, help="Path to the project config."
+    )
+    ng_workspace.add_argument(
+        "--dry-run",
+        action="store_true",
+        help=(
+            "Print the resolved Angular subprocess call list instead of "
+            "invoking Angular tooling."
+        ),
+    )
+
+    ng_config = subparsers.add_parser(
+        "ng_config", help="Configure Angular workspace defaults."
+    )
+    ng_config.add_argument(
+        "path", nargs="?", default=None, help="Path to the project config."
+    )
+    ng_config.add_argument(
+        "--dry-run",
+        action="store_true",
+        help=(
+            "Print the resolved Angular subprocess call list instead of "
+            "invoking Angular tooling."
+        ),
+    )
+
+    ng_build = subparsers.add_parser(
+        "ng_build", help="Build the configured Angular application."
+    )
+    ng_build.add_argument(
+        "path", nargs="?", default=None, help="Path to the project config."
+    )
+    ng_build.add_argument(
+        "--dry-run",
+        action="store_true",
+        help=(
+            "Print the resolved Angular subprocess call list instead of "
+            "invoking Angular tooling."
+        ),
+    )
+
+    ng_gen_app = subparsers.add_parser(
+        "ng_gen_app",
+        help="Generate an Angular application in the configured workspace.",
+    )
+    ng_gen_app.add_argument(
+        "path", nargs="?", default=None, help="Path to the project config."
+    )
+    ng_gen_app.add_argument(
+        "--app-name", default=None, help="Optional Angular application name."
+    )
+    ng_gen_app.add_argument(
+        "--dry-run",
+        action="store_true",
+        help=(
+            "Print the resolved Angular subprocess call list instead of "
+            "invoking Angular tooling."
+        ),
+    )
+
+    ng_openapi_gen = subparsers.add_parser(
+        "ng_openapi_gen", help="Run ng-openapi-gen for the configured OpenAPI source."
+    )
+    ng_openapi_gen.add_argument(
+        "path", nargs="?", default=None, help="Path to the project config."
+    )
+    ng_openapi_gen.add_argument(
+        "--dry-run",
+        action="store_true",
+        help=(
+            "Print the resolved Angular subprocess call list instead of "
+            "invoking Angular tooling."
+        ),
+    )
+
+    ng_add = subparsers.add_parser("ng_add", help="Run ng add for an Angular package.")
+    ng_add.add_argument(
+        "path", nargs="?", default=None, help="Path to the project config."
+    )
+    ng_add.add_argument(
+        "--package",
+        default=None,
+        help="Package to add (defaults to setting: ng_add_package).",
+    )
+    ng_add.add_argument(
+        "--dry-run",
+        action="store_true",
+        help=(
+            "Print the resolved Angular subprocess call list instead of "
+            "invoking Angular tooling."
+        ),
+    )
+
+    install_tutorial = subparsers.add_parser(
+        "install-tutorial",
+        help="Install the simple_crm tutorial project to a local directory.",
+    )
+    install_tutorial.add_argument(
+        "dest",
+        nargs="?",
+        default="simple_crm",
+        help="Destination directory (default: simple_crm).",
+    )
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "validate-openapi":
+        return _run_validation(
+            validate_openapi_file(args.path), f"OpenAPI document {args.path}"
+        )
+
+    if args.command == "validate-ui":
+        return _run_validation(validate_ui_file(args.path), f"UI document {args.path}")
+
+    if args.command == "validate-project":
+        try:
+            config = load_project_config(args.path)
+        except ConfigError as exc:
+            print(f"Configuration error: {exc}", file=sys.stderr)
+            return 1
+        return _run_validation(
+            validate_project_config(config), f"Project configuration {Path(args.path)}"
+        )
+
+    if args.command == "build":
+        try:
+            config = load_project_config(args.path)
+        except ConfigError as exc:
+            print(f"Configuration error: {exc}", file=sys.stderr)
+            return 1
+
+        errors = validate_project_config(config)
+        if errors:
+            return _run_validation(errors, f"Project configuration {Path(args.path)}")
+
+        plan = create_build_plan(config)
+        if args.dry_run:
+            print(json.dumps(plan.to_dict(), indent=2))
+            return 0
+
+        plan_path = write_build_plan(plan, args.output)
+        print(f"Wrote build plan to {plan_path}")
+        return 0
+
+    if args.command == "install-tutorial":
+        return _run_install_tutorial(args.dest)
+
+    if args.command in {
+        "ng_new",
+        "ng_workspace",
+        "ng_config",
+        "ng_build",
+        "ng_gen_app",
+        "ng_openapi_gen",
+        "ng_add",
+    }:
+        plan_options = {}
+        if args.command == "ng_gen_app":
+            plan_options["app_name"] = args.app_name
+        if args.command == "ng_add":
+            plan_options["package"] = args.package
+        return _run_angular_command(
+            args.command, args.path, dry_run=args.dry_run, **plan_options
+        )
+
+    parser.error("Unknown command")
+    return 2
+
+
+def _run_validation(errors: list[str], label: str) -> int:
+    if errors:
+        print(f"{label} is invalid.", file=sys.stderr)
+        for error in errors:
+            print(f"  - {error}", file=sys.stderr)
+        return 1
+
+    print(f"{label} is valid.")
+    return 0
+
+
+def _run_angular_command(
+    command_name: str, path: str | Path | None, *, dry_run: bool, **options: str | None
+) -> int:
+    try:
+        invocations = resolve_angular_command(command_name, path, **options)
+    except (AngularCommandError, ConfigError, TypeError, ValueError) as exc:
+        print(exc, file=sys.stderr)
+        return 1
+
+    if dry_run:
+        print(format_invocations(invocations))
+        return 0
+
+    try:
+        execute_invocations(invocations)
+    except AngularCommandError as exc:
+        print(exc, file=sys.stderr)
+        return 1
+
+    print(f"Executed {len(invocations)} command(s).")
+    return 0
+
+
+def _run_install_tutorial(dest: str) -> int:
+    import shutil
+
+    src = Path(__file__).parent / "examples" / "01_simple_crm"
+    dest_path = Path(dest)
+
+    if dest_path.exists():
+        print(f"Error: destination '{dest_path}' already exists.", file=sys.stderr)
+        return 1
+
+    shutil.copytree(
+        src,
+        dest_path,
+        ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo"),
+    )
+    print(f"Tutorial project installed to '{dest_path}'.")
+    print()
+    print("Next steps:")
+    print(f"  cd {dest_path}")
+    print("  python manage.py migrate")
+    print("  python manage.py createsuperuser")
+    print("  python manage.py runserver")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

django_angular3/config.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .documents import DocumentError, load_document
+
+
+class ConfigError(ValueError):
+    """Raised when the project configuration is invalid."""
+
+
+@dataclass(frozen=True)
+class ProjectConfig:
+    config_path: Path
+    project_name: str
+    openapi_source: Path
+    ui_source: Path
+    angular_output: Path
+    openapi_generator_config: Path | None = None
+    ng_openapi_gen_config: Path | None = None
+
+
+def load_project_config(path: str | Path) -> ProjectConfig:
+    config_path = Path(path).resolve()
+    try:
+        document: dict[str, Any] | None = load_document(config_path)
+    except DocumentError as exc:
+        raise ConfigError(str(exc)) from exc
+
+    if not isinstance(document, dict):
+        raise ConfigError("Project configuration must be a mapping.")
+
+    project: dict[str, Any] = _require_mapping(document, "project")
+    openapi: dict[str, Any] = _require_mapping(document, "openapi")
+    ui: dict[str, Any] = _require_mapping(document, "ui")
+    angular: dict[str, Any] = _require_mapping(document, "angular")
+
+    root = config_path.parent
+    project_name = _require_string(project, "name", section="project")
+    openapi_source = _resolve_path(
+        root, _require_string(openapi, "source", section="openapi")
+    )
+    ui_source = _resolve_path(root, _require_string(ui, "source", section="ui"))
+    angular_output_value = angular.get("output", angular.get("package"))
+    if not isinstance(angular_output_value, str) or not angular_output_value.strip():
+        raise ConfigError(
+            "Configuration value 'angular.output' must be a non-empty string."
+        )
+    angular_output = _resolve_path(root, angular_output_value)
+
+    openapi_generator_config = _optional_path(
+        root, openapi.get("openapiGeneratorConfig"), "openapi.openapiGeneratorConfig"
+    )
+    ng_openapi_gen_config = _optional_path(
+        root, openapi.get("ngOpenApiGenConfig"), "openapi.ngOpenApiGenConfig"
+    )
+
+    return ProjectConfig(
+        config_path=config_path,
+        project_name=project_name,
+        openapi_source=openapi_source,
+        ui_source=ui_source,
+        angular_output=angular_output,
+        openapi_generator_config=openapi_generator_config,
+        ng_openapi_gen_config=ng_openapi_gen_config,
+    )
+
+
+def _require_mapping(document: dict[str, Any], key: str) -> dict[str, Any]:
+    value: dict[str, Any] | None = document.get(key)
+    if not isinstance(value, dict):
+        raise ConfigError(f"Configuration section '{key}' must be a mapping.")
+    return value
+
+
+def _require_string(document: dict[str, Any], key: str, *, section: str) -> str:
+    value = document.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigError(
+            f"Configuration value '{section}.{key}' must be a non-empty string."
+        )
+    return value
+
+
+def _resolve_path(root: Path, raw_path: str) -> Path:
+    return (root / raw_path).resolve()
+
+
+def _optional_path(root: Path, value: Any, label: str) -> Path | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigError(f"Configuration value '{label}' must be a non-empty string.")
+    return (root / value).resolve()
+
+
+def get_previous_schema_path(source: Path) -> Path:
+    """Return the conventional path for the previous schema artifact.
+
+    The previous schema is stored alongside the current schema with
+    ``.previous`` inserted before the file extension.  For example::
+
+        spec/openapi/source/api.json  →  spec/openapi/source/api.previous.json
+
+    This path is written by ``export_schema`` before the current schema is
+    overwritten, and consumed by ``build_app`` for change detection.
+    """
+    return source.parent / (source.stem + ".previous" + source.suffix)

django_angular3/documents.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import json
+import tomllib
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml  # type: ignore
+except ImportError:  # pragma: no cover - exercised when optional dep absent
+    yaml = None
+
+
+class DocumentError(ValueError):
+    """Raised when a structured input document cannot be loaded."""
+
+
+def load_document(path: str | Path) -> Any:
+    file_path = Path(path)
+    if not file_path.exists():
+        raise DocumentError(f"Document does not exist: {file_path}")
+
+    suffix = file_path.suffix.lower()
+    text = file_path.read_text(encoding="utf-8")
+
+    if suffix == ".json":
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise DocumentError(f"Invalid JSON in {file_path}: {exc}") from exc
+
+    if suffix == ".toml":
+        try:
+            return tomllib.loads(text)
+        except tomllib.TOMLDecodeError as exc:
+            raise DocumentError(f"Invalid TOML in {file_path}: {exc}") from exc
+
+    if suffix in {".yaml", ".yml"}:
+        if yaml is None:
+            raise DocumentError(
+                "YAML support requires the optional 'yaml' extra. "
+                "Install with `pip install -e .[yaml]` or use JSON/TOML."
+            )
+        try:
+            return yaml.safe_load(text)
+        except yaml.YAMLError as exc:
+            raise DocumentError(f"Invalid YAML in {file_path}: {exc}") from exc
+
+    raise DocumentError(
+        f"Unsupported document format for {file_path}. "
+        "Use .json, .toml, .yaml, or .yml."
+    )

django_angular3/examples/01_simple_crm/django-angular3.json

@@ -0,0 +1,10 @@
+{
+  "project": { "name": "simple_crm" },
+  "app": { "name": "shop" },
+  "openapi": { "source": "schema.yaml" },
+  "ui": { "source": "ui.json" },
+  "angular": {
+    "output": "build/angular",
+    "workspace": { "packageManager": "pnpm", "style": "scss", "routing": true }
+  }
+}

django_angular3/examples/01_simple_crm/manage.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python
+"""Django's command-line utility for administrative tasks."""
+
+import os
+import sys
+
+
+def main():
+    """Run administrative tasks."""
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "simple_crm.settings")
+    try:
+        from django.core.management import execute_from_command_line
+    except ImportError as exc:
+        raise ImportError(
+            "Couldn't import Django. Are you sure it's installed and "
+            "available on your PYTHONPATH environment variable? Did you "
+            "forget to activate a virtual environment?"
+        ) from exc
+    execute_from_command_line(sys.argv)
+
+
+if __name__ == "__main__":
+    main()

django_angular3/examples/01_simple_crm/shop/admin.py

@@ -0,0 +1,17 @@
+from django.contrib import admin
+
+from .models import Customer, Product
+
+
+class CustomerAdmin(admin.ModelAdmin):
+    list_display = ["id", "name", "email", "active"]
+    list_editable = ["name", "email", "active"]
+
+
+class ProductAdmin(admin.ModelAdmin):
+    list_display = ["id", "name", "price", "sku"]
+    list_editable = ["name", "price"]
+
+
+admin.site.register(Customer, CustomerAdmin)
+admin.site.register(Product, ProductAdmin)

django_angular3/examples/01_simple_crm/shop/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class ShopConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "shop"

django_angular3/examples/01_simple_crm/shop/models.py

@@ -0,0 +1,20 @@
+from django.db import models
+
+
+class Customer(models.Model):
+    name = models.CharField(max_length=120)
+    email = models.EmailField()
+    phone = models.CharField(max_length=50, blank=True)
+    active = models.BooleanField(default=True)
+
+    class Meta:
+        ordering = ["id"]
+
+
+class Product(models.Model):
+    name = models.CharField(max_length=200)
+    price = models.FloatField()
+    sku = models.CharField(max_length=100, blank=True)
+
+    class Meta:
+        ordering = ["id"]

django_angular3/examples/01_simple_crm/shop/serializers.py

@@ -0,0 +1,15 @@
+from rest_framework import serializers
+
+from .models import Customer, Product
+
+
+class CustomerSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Customer
+        fields = ["id", "name", "email", "phone", "active"]
+
+
+class ProductSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Product
+        fields = ["id", "name", "price", "sku"]

django_angular3/examples/01_simple_crm/shop/tests.py

@@ -0,0 +1 @@
+# Create your tests here.

django_angular3/examples/01_simple_crm/shop/views.py

@@ -0,0 +1,24 @@
+from rest_framework import mixins, permissions, viewsets
+
+from .models import Customer, Product
+from .serializers import CustomerSerializer, ProductSerializer
+
+
+class CustomerViewSet(
+    mixins.ListModelMixin,
+    mixins.CreateModelMixin,
+    mixins.RetrieveModelMixin,
+    mixins.UpdateModelMixin,
+    mixins.DestroyModelMixin,
+    viewsets.GenericViewSet,
+):
+    queryset = Customer.objects.all()
+    serializer_class = CustomerSerializer
+    permission_classes = [permissions.AllowAny]
+    http_method_names = ["get", "post", "patch", "delete", "head", "options"]
+
+
+class ProductViewSet(mixins.ListModelMixin, viewsets.GenericViewSet):
+    queryset = Product.objects.all()
+    serializer_class = ProductSerializer
+    permission_classes = [permissions.AllowAny]

django_angular3/examples/01_simple_crm/simple_crm/asgi.py

@@ -0,0 +1,7 @@
+import os
+
+from django.core.asgi import get_asgi_application
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "simple_crm.settings")
+
+application = get_asgi_application()