csrd-utils 0.3.110__tar.gz → 0.4.0__tar.gz

{csrd_utils-0.3.110 → csrd_utils-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: csrd-utils
-Version: 0.3.110
+Version: 0.4.0
 Summary: CLI utilities for csrd service generation and feature augmentation
 Project-URL: Repository, https://github.com/csrd-api/fastapi-common
 Project-URL: Documentation, https://github.com/csrd-api/fastapi-common/tree/main/packages/utils

{csrd_utils-0.3.110 → csrd_utils-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "csrd-utils"
-version = "0.3.110"
+version = "0.4.0"
 description = "CLI utilities for csrd service generation and feature augmentation"
 license = { text = "MIT" }
 requires-python = ">=3.12"

{csrd_utils-0.3.110 → csrd_utils-0.4.0}/src/csrd_utils/v2/compose/augments.py

@@ -42,6 +42,10 @@ DynamicMigrationResolver = Callable[
     [ServiceAugment, ServiceNode, ComposeSpec], list[tuple[str, str]]
 ]
 
+#: Returns multiple variable dicts for multi-instance template rendering.
+#: Each dict is used to render the full template set once (e.g. per entity).
+MultiScaffoldResolver = Callable[[ServiceAugment, ServiceNode, ComposeSpec], list[dict[str, str]]]
+
 
 # ---------------------------------------------------------------------------
 # Role registry
@@ -297,6 +301,10 @@ class AugmentDescriptor:
     # Dynamic migration imports resolved from augment options
     resolve_dynamic_migrations: DynamicMigrationResolver | None = None
 
+    # Multi-instance scaffolding: when set, templates are rendered once
+    # per returned variable dict (e.g. one per discovered entity).
+    resolve_multi_scaffold_vars: MultiScaffoldResolver | None = None
+
 
 # ---------------------------------------------------------------------------
 # Resolver functions — dynamic wiring extracted from renderer/scaffolder
@@ -597,6 +605,126 @@ def _crud_scaffold_dynamic_migrations(
     return [(import_line, f"{snake}_migration")]
 
 
+# ── crud-proxy ───────────────────────────────────────────────────────────
+
+
+def _resolve_target_entities(
+    augment: ServiceAugment, svc: ServiceNode, spec: ComposeSpec
+) -> list[dict[str, str]]:
+    """Introspect target services' crud-scaffold augments to discover entities.
+
+    Returns a list of dicts with keys: target_name, target_port,
+    entity_name_snake, entity_name_pascal, entity_name_plural.
+    """
+    targets = augment.options.get("targets", [])
+    if isinstance(targets, str):
+        targets = [targets]
+
+    entities: list[dict[str, str]] = []
+    for target_name in targets:
+        target_svc = find_service_by_name(spec, target_name)
+        if target_svc is None:
+            continue
+        for target_aug in target_svc.augments:
+            if target_aug.name != "crud-scaffold":
+                continue
+            entity_raw = target_aug.options.get("entity_name", "item")
+            entity = entity_raw if isinstance(entity_raw, str) else entity_raw[0]
+            snake = entity.replace("-", "_").lower()
+            pascal = "".join(w.capitalize() for w in snake.split("_"))
+            plural_raw = target_aug.options.get("entity_name_plural", snake + "s")
+            plural = plural_raw if isinstance(plural_raw, str) else plural_raw[0]
+            entities.append(
+                {
+                    "target_name": target_name,
+                    "target_name_snake": target_name.replace("-", "_"),
+                    "target_port": str(target_svc.port),
+                    "entity_name_snake": snake,
+                    "entity_name_pascal": pascal,
+                    "entity_name_plural": plural,
+                }
+            )
+    return entities
+
+
+def _crud_proxy_compose_env(
+    augment: ServiceAugment, svc: ServiceNode, spec: ComposeSpec
+) -> dict[str, str]:
+    """Compose env vars: delegate URLs for each target service."""
+    return _delegate_compose_env(augment, svc, spec)
+
+
+def _crud_proxy_settings(
+    augment: ServiceAugment, svc: ServiceNode, spec: ComposeSpec
+) -> dict[str, str]:
+    """Settings fields: service URL for each target."""
+    return _delegate_settings(augment, svc, spec)
+
+
+def _crud_proxy_template_vars(
+    augment: ServiceAugment, svc: ServiceNode, spec: ComposeSpec
+) -> dict[str, str]:
+    """Template vars for rendering proxy files.
+
+    Passes target and entity info as comma-separated lists for template
+    iteration.  Individual entity templates use per-entity variables.
+    """
+    variables: dict[str, str] = {}
+    entities = _resolve_target_entities(augment, svc, spec)
+
+    # For multi-file scaffolding, each entity gets its own template render.
+    # Here we export the first entity's vars for the template (each entity
+    # file is scaffolded separately via resolve_dynamic_routers and the
+    # file-path substitution).
+    if entities:
+        for key, value in entities[0].items():
+            variables[key] = value
+
+    # Also pass delegate-config style target vars
+    variables.update(_delegate_template_vars(augment, svc, spec))
+
+    return variables
+
+
+def _crud_proxy_dynamic_routers(
+    augment: ServiceAugment, svc: ServiceNode, spec: ComposeSpec
+) -> list[tuple[str, str]]:
+    """Resolve dynamic router imports for each proxied entity."""
+    entities = _resolve_target_entities(augment, svc, spec)
+    result: list[tuple[str, str]] = []
+    for ent in entities:
+        snake = ent["entity_name_snake"]
+        alias = f"{snake}_proxy_router"
+        import_line = f"from .views.{snake}_proxy_view import router as {alias}"
+        result.append((import_line, alias))
+    return result
+
+
+def _crud_proxy_multi_scaffold_vars(
+    augment: ServiceAugment, svc: ServiceNode, spec: ComposeSpec
+) -> list[dict[str, str]]:
+    """Return one variable dict per discovered entity for multi-file scaffolding."""
+    svc_snake = svc.name.replace("-", "_")
+    base: dict[str, str] = {
+        "service_name": svc.name,
+        "service_name_snake": svc_snake,
+        "port": str(svc.port),
+    }
+    # Merge delegate-config style target vars
+    base.update(_delegate_template_vars(augment, svc, spec))
+
+    entities = _resolve_target_entities(augment, svc, spec)
+    if not entities:
+        return []
+
+    result: list[dict[str, str]] = []
+    for ent in entities:
+        variables = dict(base)
+        variables.update(ent)
+        result.append(variables)
+    return result
+
+
 # ── jwt-auth-provider ────────────────────────────────────────────────────
 
 
@@ -811,6 +939,20 @@ AUGMENT_REGISTRY: dict[str, AugmentDescriptor] = {
         resolve_dynamic_routers=_crud_scaffold_dynamic_routers,
         resolve_dynamic_migrations=_crud_scaffold_dynamic_migrations,
     ),
+    "crud-proxy": AugmentDescriptor(
+        name="crud-proxy",
+        scope="service",
+        description="Delegate-backed CRUD proxy endpoints mirroring another service's entities",
+        packages=["csrd-delegate", "csrd-models"],
+        template_dir="crud-proxy",
+        needs_target_selection=True,
+        routers=[],  # routers are dynamic per entity — wired via resolve_dynamic_routers
+        resolve_template_vars=_crud_proxy_template_vars,
+        resolve_dynamic_routers=_crud_proxy_dynamic_routers,
+        resolve_compose_env=_crud_proxy_compose_env,
+        resolve_settings_fields=_crud_proxy_settings,
+        resolve_multi_scaffold_vars=_crud_proxy_multi_scaffold_vars,
+    ),
 }
 
 

{csrd_utils-0.3.110 → csrd_utils-0.4.0}/src/csrd_utils/v2/compose/scaffolder.py

@@ -167,6 +167,10 @@ def scaffold_augment(
     Each file is rendered with ``string.Template`` substitution and copied
     into the service's source directory, preserving subdirectory structure.
 
+    When the descriptor provides ``resolve_multi_scaffold_vars``, templates
+    are rendered once per returned variable dict (e.g. one per discovered
+    entity).  Otherwise templates are rendered once with the standard vars.
+
     Files that already exist are **never overwritten** — they may contain
     user edits.  This makes the operation idempotent and safe to re-run.
     """
@@ -186,8 +190,23 @@ def scaffold_augment(
     if not svc_dest.exists():
         return
 
-    variables = _augment_template_vars(augment, service, spec)
-
+    # Multi-instance scaffolding (e.g. crud-proxy renders per entity)
+    if desc.resolve_multi_scaffold_vars is not None:
+        var_sets = desc.resolve_multi_scaffold_vars(augment, service, spec)
+        for variables in var_sets:
+            _render_template_set(template_dir, svc_dest, variables, augment.name)
+    else:
+        variables = _augment_template_vars(augment, service, spec)
+        _render_template_set(template_dir, svc_dest, variables, augment.name)
+
+
+def _render_template_set(
+    template_dir: Path,
+    svc_dest: Path,
+    variables: dict[str, str],
+    augment_name: str,
+) -> None:
+    """Render a set of template files with the given variables."""
     for template_file in sorted(template_dir.rglob("*")):
         if template_file.is_dir():
             continue
@@ -215,4 +234,4 @@ def scaffold_augment(
         rendered = Template(content).safe_substitute(variables)
         dest.write_text(rendered, encoding="utf-8")
 
-        logger.debug("Scaffolded %s for augment '%s'", dest, augment.name)
+        logger.debug("Scaffolded %s for augment '%s'", dest, augment_name)

csrd_utils-0.4.0/src/csrd_utils/v2/templates/augments/crud-proxy/delegates/${entity_name_snake}_delegate.py.template

@@ -0,0 +1,55 @@
+"""${entity_name_pascal} delegate — proxies CRUD operations to ${target_name}.
+
+This file is scaffolded once and never overwritten.
+"""
+
+from csrd.delegate import BaseDelegate
+
+from ..models.${entity_name_snake} import (
+    ${entity_name_pascal}ListResponse,
+    ${entity_name_pascal}Response,
+)
+
+
+class ${entity_name_pascal}Delegate(BaseDelegate):
+    """HTTP delegate for ${entity_name_plural} on ${target_name}."""
+
+    def __init__(self, base_url: str) -> None:
+        super().__init__(base_url)
+
+    async def list_all(self) -> ${entity_name_pascal}ListResponse:
+        """List all ${entity_name_plural}."""
+        return await self.get(
+            "/api/${entity_name_plural}",
+            response_model=${entity_name_pascal}ListResponse,
+        )
+
+    async def get_by_id(self, entity_id: str) -> ${entity_name_pascal}Response:
+        """Get a ${entity_name_snake} by ID."""
+        return await self.get(
+            f"/api/${entity_name_plural}/{entity_id}",
+            response_model=${entity_name_pascal}Response,
+        )
+
+    async def create(self, name: str) -> ${entity_name_pascal}Response:
+        """Create a new ${entity_name_snake}."""
+        return await self.post(
+            "/api/${entity_name_plural}",
+            json={"name": name},
+            response_model=${entity_name_pascal}Response,
+        )
+
+    async def update(self, entity_id: str, name: str) -> ${entity_name_pascal}Response:
+        """Update an existing ${entity_name_snake}."""
+        return await self.put(
+            f"/api/${entity_name_plural}/{entity_id}",
+            json={"name": name},
+            response_model=${entity_name_pascal}Response,
+        )
+
+    async def remove(self, entity_id: str) -> None:
+        """Delete a ${entity_name_snake}."""
+        await self.delete(f"/api/${entity_name_plural}/{entity_id}")
+
+
+__all__ = ("${entity_name_pascal}Delegate",)

csrd_utils-0.4.0/src/csrd_utils/v2/templates/augments/crud-proxy/dependencies/${entity_name_snake}_delegate.py.template

@@ -0,0 +1,21 @@
+"""${entity_name_pascal} delegate dependency.
+
+This file is scaffolded once and never overwritten.
+"""
+
+from typing import Annotated
+
+from fastapi import Depends
+
+from ..delegates.${entity_name_snake}_delegate import ${entity_name_pascal}Delegate
+from ..settings import settings
+
+
+def _${entity_name_snake}_delegate_factory() -> ${entity_name_pascal}Delegate:
+    """Create a ``${entity_name_pascal}Delegate`` bound to ${target_name}."""
+    return ${entity_name_pascal}Delegate(settings.${target_name_snake}_service_url)
+
+
+${entity_name_pascal}Del = Annotated[${entity_name_pascal}Delegate, Depends(_${entity_name_snake}_delegate_factory)]
+
+__all__ = ("${entity_name_pascal}Del",)

csrd_utils-0.4.0/src/csrd_utils/v2/templates/augments/crud-proxy/models/${entity_name_snake}.py.template

@@ -0,0 +1,31 @@
+"""${entity_name_pascal} models — mirrors target service's entity schema.
+
+This file is scaffolded once and never overwritten.
+"""
+
+from csrd.models import BaseModel
+
+
+class Create${entity_name_pascal}Request(BaseModel):
+    """Request body for creating a new ${entity_name_snake}."""
+
+    name: str
+
+
+class Update${entity_name_pascal}Request(BaseModel):
+    """Request body for updating an existing ${entity_name_snake}."""
+
+    name: str
+
+
+class ${entity_name_pascal}Response(BaseModel):
+    """Response model for a single ${entity_name_snake}."""
+
+    id: str
+    name: str
+
+
+class ${entity_name_pascal}ListResponse(BaseModel):
+    """Response model for a list of ${entity_name_plural}."""
+
+    items: list[${entity_name_pascal}Response]

csrd_utils-0.4.0/src/csrd_utils/v2/templates/augments/crud-proxy/views/${entity_name_snake}_proxy_view.py.template

@@ -0,0 +1,61 @@
+"""${entity_name_pascal} proxy endpoints — delegates to ${target_name}.
+
+This file is scaffolded once and never overwritten.
+"""
+
+from fastapi import APIRouter
+
+from ..dependencies.${entity_name_snake}_delegate import ${entity_name_pascal}Del
+from ..models.${entity_name_snake} import (
+    Create${entity_name_pascal}Request,
+    ${entity_name_pascal}ListResponse,
+    ${entity_name_pascal}Response,
+    Update${entity_name_pascal}Request,
+)
+
+router = APIRouter(prefix="/api/${entity_name_plural}", tags=["${entity_name_plural}"])
+
+
+@router.get("", response_model=${entity_name_pascal}ListResponse)
+async def list_${entity_name_plural}(
+    delegate: ${entity_name_pascal}Del,
+) -> ${entity_name_pascal}ListResponse:
+    """List all ${entity_name_plural} (proxied from ${target_name})."""
+    return await delegate.list_all()
+
+
+@router.get("/{entity_id}", response_model=${entity_name_pascal}Response)
+async def get_${entity_name_snake}(
+    entity_id: str,
+    delegate: ${entity_name_pascal}Del,
+) -> ${entity_name_pascal}Response:
+    """Get a ${entity_name_snake} by ID (proxied from ${target_name})."""
+    return await delegate.get_by_id(entity_id)
+
+
+@router.post("", status_code=201, response_model=${entity_name_pascal}Response)
+async def create_${entity_name_snake}(
+    body: Create${entity_name_pascal}Request,
+    delegate: ${entity_name_pascal}Del,
+) -> ${entity_name_pascal}Response:
+    """Create a new ${entity_name_snake} (proxied to ${target_name})."""
+    return await delegate.create(body.name)
+
+
+@router.put("/{entity_id}", response_model=${entity_name_pascal}Response)
+async def update_${entity_name_snake}(
+    entity_id: str,
+    body: Update${entity_name_pascal}Request,
+    delegate: ${entity_name_pascal}Del,
+) -> ${entity_name_pascal}Response:
+    """Update a ${entity_name_snake} (proxied to ${target_name})."""
+    return await delegate.update(entity_id, body.name)
+
+
+@router.delete("/{entity_id}", status_code=204)
+async def delete_${entity_name_snake}(
+    entity_id: str,
+    delegate: ${entity_name_pascal}Del,
+) -> None:
+    """Delete a ${entity_name_snake} (proxied to ${target_name})."""
+    await delegate.remove(entity_id)