forge-mvc-pivot 1.0.0b16__tar.gz

forge_mvc_pivot-1.0.0b16/LICENSE

@@ -0,0 +1,36 @@
+Forge — Licence propriétaire / source disponible
+
+Copyright (c) Roger Lequette.
+Tous droits réservés.
+
+Le code source de Forge est mis à disposition uniquement pour lecture, étude,
+évaluation et usage éducatif personnel.
+
+Sauf autorisation écrite préalable de Roger Lequette, il est interdit de :
+
+- utiliser Forge dans un cadre professionnel, commercial ou institutionnel ;
+- utiliser Forge pour une prestation client ;
+- intégrer Forge dans un produit, service, SaaS, application vendue ou solution
+  déployée pour un tiers ;
+- redistribuer Forge, modifié ou non ;
+- publier une version modifiée de Forge ;
+- vendre, louer, sous-licencier ou exploiter commercialement Forge ;
+- supprimer ou modifier les mentions de copyright et de licence.
+
+Les usages autorisés sans autorisation écrite préalable sont limités à :
+
+- lire le code ;
+- étudier son fonctionnement ;
+- tester Forge à titre personnel ;
+- l'utiliser dans un cadre éducatif personnel ou pédagogique non commercial ;
+- évaluer le framework avant une éventuelle demande d'autorisation.
+
+Toute utilisation non explicitement autorisée par cette licence nécessite une
+autorisation écrite préalable de Roger Lequette.
+
+Cette licence pourra évoluer ultérieurement. Toute version publiée de Forge
+reste soumise à la licence présente dans son dépôt au moment de sa récupération.
+
+LE LOGICIEL EST FOURNI « TEL QUEL », SANS GARANTIE D'AUCUNE SORTE, EXPRESSE OU
+IMPLICITE. EN AUCUN CAS LE DÉTENTEUR DU COPYRIGHT NE POURRA ÊTRE TENU
+RESPONSABLE DE TOUT DOMMAGE DÉCOULANT DE L'UTILISATION DE CE LOGICIEL.

forge_mvc_pivot-1.0.0b16/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: forge-mvc-pivot
+Version: 1.0.0b16
+Summary: Forge pivot — tables pivot enrichies (many_to_many avec attributs) et generateur make:pivot-crud.
+Author: Roger Lequette
+License-Expression: LicenseRef-Forge-Proprietary
+Project-URL: Homepage, https://github.com/caucrogeGit/Forge
+Project-URL: Repository, https://github.com/caucrogeGit/Forge
+Project-URL: Documentation, https://forgemvc.com/docs/forge/
+Keywords: python,mvc,forge,pivot,many-to-many
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: forge-mvc<2,>=1.0.0b16
+Dynamic: license-file
+
+# forge-mvc-pivot
+
+Opt-in Forge pour les **tables pivot enrichies** : associations `many_to_many`
+portant des attributs (par exemple `position`, `note`) sur la ligne de jointure.
+
+Extrait du core de Forge (ADR-021) : le core ne contient que les primitives
+générales ; le pivot avancé est une brique spécialisée, optionnelle.
+
+## Contenu
+
+- `PivotAdvancedService` : lecture et écriture d'associations pivot avec
+  attributs, contraintes déclaratives (`required`, `nullable`, `unique_pair`),
+  accès base injectables (`fetch_one`, `fetch_all`, `execute`, `insert_fn`).
+- `PivotFieldConstraint`, `PivotRow`, `PivotFormError`, `PivotConstraintError`,
+  `pivot_error_to_form_error` : contraintes, résultats et erreurs structurées.
+- Générateur `forge make:pivot-crud <EntitéSource> <nomRelation>` : échafaude un
+  sous-CRUD pivot à partir d'une relation `many_to_many` déclarée dans
+  `relations.json`.
+
+## Installation
+
+```bash
+pip install --pre forge-mvc-pivot
+```
+
+Le code généré importe `forge_mvc_pivot` : installez le paquet avant de lancer
+une application qui s'appuie sur un sous-CRUD pivot.

forge_mvc_pivot-1.0.0b16/README.md

@@ -0,0 +1,27 @@
+# forge-mvc-pivot
+
+Opt-in Forge pour les **tables pivot enrichies** : associations `many_to_many`
+portant des attributs (par exemple `position`, `note`) sur la ligne de jointure.
+
+Extrait du core de Forge (ADR-021) : le core ne contient que les primitives
+générales ; le pivot avancé est une brique spécialisée, optionnelle.
+
+## Contenu
+
+- `PivotAdvancedService` : lecture et écriture d'associations pivot avec
+  attributs, contraintes déclaratives (`required`, `nullable`, `unique_pair`),
+  accès base injectables (`fetch_one`, `fetch_all`, `execute`, `insert_fn`).
+- `PivotFieldConstraint`, `PivotRow`, `PivotFormError`, `PivotConstraintError`,
+  `pivot_error_to_form_error` : contraintes, résultats et erreurs structurées.
+- Générateur `forge make:pivot-crud <EntitéSource> <nomRelation>` : échafaude un
+  sous-CRUD pivot à partir d'une relation `many_to_many` déclarée dans
+  `relations.json`.
+
+## Installation
+
+```bash
+pip install --pre forge-mvc-pivot
+```
+
+Le code généré importe `forge_mvc_pivot` : installez le paquet avant de lancer
+une application qui s'appuie sur un sous-CRUD pivot.

forge_mvc_pivot-1.0.0b16/forge_mvc_pivot/__init__.py

@@ -0,0 +1,24 @@
+"""forge-mvc-pivot — Pivot advanced opt-in (extrait du core, ADR-021).
+
+Service de persistance pour tables pivot enrichies (associations many_to_many
+avec attributs) et générateur `forge make:pivot-crud`.
+"""
+from forge_mvc_pivot.service import (
+    PivotAdvancedService,
+    PivotConstraintError,
+    PivotFieldConstraint,
+    PivotFormError,
+    PivotRow,
+    pivot_error_to_form_error,
+)
+
+__all__ = [
+    "PivotAdvancedService",
+    "PivotConstraintError",
+    "PivotFieldConstraint",
+    "PivotFormError",
+    "PivotRow",
+    "pivot_error_to_form_error",
+]
+
+__version__ = "1.0.0b16"

forge_mvc_pivot-1.0.0b16/forge_mvc_pivot/make_pivot_crud.py

@@ -0,0 +1,489 @@
+"""forge_mvc_pivot/make_pivot_crud.py — Générateur de sous-CRUD Pivot advanced (opt-in).
+
+Commande : forge make:pivot-crud <EntitéSource> <nomRelation> [--dry-run]
+
+Analyse une relation many_to_many avec pivot.fields[] et génère une structure
+dédiée minimale sans modifier make:crud.
+
+Décision : PIVOT-ADVANCED-004.
+Service runtime : forge_mvc_pivot.PivotAdvancedService (PIVOT-ADVANCED-003).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field as dc_field
+from pathlib import Path
+
+import forge_cli.output as out
+
+_SNAKE_RE = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")
+
+
+def _to_snake(name: str) -> str:
+    return _SNAKE_RE.sub("_", name).lower()
+
+
+# ── Données de la relation résolue ────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class ResolvedPivotRelation:
+    from_entity: str
+    to_entity: str
+    relation_name: str
+    pivot_table: str
+    from_key: str
+    to_key: str
+    pivot_fields: tuple[str, ...]
+
+
+# ── Résultat ──────────────────────────────────────────────────────────────────
+
+@dataclass
+class MakePivotCrudResult:
+    created: list[Path] = dc_field(default_factory=list)
+    preserved: list[Path] = dc_field(default_factory=list)
+    dry_run: bool = False
+
+
+# ── Résolution de la relation ─────────────────────────────────────────────────
+
+def resolve_pivot_relation(
+    source_entity: str,
+    relation_name: str,
+    *,
+    relations_path: Path,
+) -> ResolvedPivotRelation:
+    """Charge relations.json et trouve la relation many_to_many cible.
+
+    Raises SystemExit avec message clair pour tous les cas d'erreur.
+    """
+    if not relations_path.exists():
+        print(out.error(
+            "mvc/entities/relations.json introuvable.\n"
+            "Créez d'abord vos relations avec forge make:relation."
+        ))
+        raise SystemExit(1)
+
+    try:
+        raw = json.loads(relations_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(out.error(f"relations.json invalide (JSON malformé) : {exc}"))
+        raise SystemExit(1)
+
+    if not isinstance(raw, dict) or raw.get("schema_version") != "1.0":
+        print(out.error('relations.json invalide : schema_version "1.0" attendu.'))
+        raise SystemExit(1)
+
+    relations = raw.get("relations")
+    if not isinstance(relations, list):
+        print(out.error("relations.json invalide : clé \"relations\" manquante ou invalide."))
+        raise SystemExit(1)
+
+    candidates = [
+        r for r in relations
+        if isinstance(r, dict)
+        and r.get("type") == "many_to_many"
+        and r.get("from") == source_entity
+        and r.get("name") == relation_name
+    ]
+
+    if not candidates:
+        # Distinguer les cas d'erreur
+        source_exists = any(
+            isinstance(r, dict) and r.get("from") == source_entity
+            for r in relations
+        )
+        if not source_exists:
+            print(out.error(f"Entité source inconnue : {source_entity!r} n'apparaît dans aucune relation."))
+        else:
+            print(out.error(
+                f"Relation introuvable : {source_entity}.{relation_name}.\n"
+                f"Vérifiez le nom de la relation (clé \"name\" dans relations.json)."
+            ))
+        raise SystemExit(1)
+
+    if len(candidates) > 1:
+        print(out.error(f"Relation ambiguë : plusieurs relations {source_entity}.{relation_name} trouvées."))
+        raise SystemExit(1)
+
+    rel = candidates[0]
+
+    if rel.get("type") != "many_to_many":
+        print(out.error(
+            f"Relation {source_entity}.{relation_name} n'est pas many_to_many.\n"
+            "make:pivot-crud est réservé aux relations many_to_many avec pivot.fields[]."
+        ))
+        raise SystemExit(1)
+
+    pivot = rel.get("pivot")
+    if not isinstance(pivot, dict):
+        print(out.error(
+            f"Relation {source_entity}.{relation_name} n'a pas de bloc pivot.\n"
+            "make:pivot-crud est réservé aux pivots avec attributs."
+        ))
+        raise SystemExit(1)
+
+    fields = pivot.get("fields")
+    if not isinstance(fields, list) or len(fields) == 0:
+        print(out.error(
+            f"Relation {source_entity}.{relation_name} : pivot.fields[] est absent ou vide.\n"
+            "make:pivot-crud est réservé aux pivots avec attributs.\n"
+            "Utilisez make:crud pour les pivots simples."
+        ))
+        raise SystemExit(1)
+
+    pivot_field_names = tuple(
+        f["name"] for f in fields
+        if isinstance(f, dict) and isinstance(f.get("name"), str)
+    )
+
+    return ResolvedPivotRelation(
+        from_entity=source_entity,
+        to_entity=rel.get("to", ""),
+        relation_name=relation_name,
+        pivot_table=pivot.get("table", ""),
+        from_key=pivot.get("from_key", ""),
+        to_key=pivot.get("to_key", ""),
+        pivot_fields=pivot_field_names,
+    )
+
+
+# ── Contenu généré ────────────────────────────────────────────────────────────
+
+def _build_controller(rel: ResolvedPivotRelation) -> str:
+    src_snake = _to_snake(rel.from_entity)
+    tgt_snake = _to_snake(rel.to_entity)
+    fields_repr = repr(list(rel.pivot_fields))
+
+    return f'''\
+"""mvc/controllers/pivot/{src_snake}_{rel.relation_name}_pivot_controller.py
+
+Sous-CRUD Pivot advanced pour {rel.from_entity}.{rel.relation_name}.
+Généré par forge make:pivot-crud {rel.from_entity} {rel.relation_name}.
+
+Ce contrôleur est opt-in — les routes (imbriquées sous la source) sont à
+déclarer manuellement dans mvc/routes.py. Noms de routes au format ADR-029
+(<contrôleur>-<méthode>) ; les identifiants sont lus depuis les paramètres
+de route « source_id » et « target_id ».
+
+Exemple de routes à ajouter :
+    with router.group("") as g:
+        g.add("GET",  "/{src_snake}s/{{source_id}}/{rel.relation_name}", controller.index, name="{src_snake}_{rel.relation_name}_pivot-index")
+        g.add("GET",  "/{src_snake}s/{{source_id}}/{rel.relation_name}/add", controller.add_form, name="{src_snake}_{rel.relation_name}_pivot-add_form")
+        g.add("POST", "/{src_snake}s/{{source_id}}/{rel.relation_name}/add", controller.add, name="{src_snake}_{rel.relation_name}_pivot-add")
+        g.add("GET",  "/{src_snake}s/{{source_id}}/{rel.relation_name}/{{target_id}}/edit", controller.edit_form, name="{src_snake}_{rel.relation_name}_pivot-edit_form")
+        g.add("POST", "/{src_snake}s/{{source_id}}/{rel.relation_name}/{{target_id}}/edit", controller.edit, name="{src_snake}_{rel.relation_name}_pivot-edit")
+        g.add("POST", "/{src_snake}s/{{source_id}}/{rel.relation_name}/{{target_id}}/remove", controller.remove, name="{src_snake}_{rel.relation_name}_pivot-remove")
+"""
+from __future__ import annotations
+
+from forge_mvc_pivot import PivotAdvancedService, PivotConstraintError, pivot_error_to_form_error
+from core.http.request import Request
+from core.http.response import Response
+from core.mvc.controller import BaseController
+
+_SERVICE = PivotAdvancedService(
+    table={rel.pivot_table!r},
+    source_key={rel.from_key!r},
+    target_key={rel.to_key!r},
+    pivot_fields={fields_repr},
+)
+
+_TEMPLATE_INDEX = "pivot/{src_snake}_{rel.relation_name}/index.html"
+_TEMPLATE_FORM  = "pivot/{src_snake}_{rel.relation_name}/form.html"
+
+
+class {rel.from_entity}{rel.relation_name.capitalize()}PivotController:
+
+    @staticmethod
+    def index(request: Request) -> Response:
+        """Liste les associations {rel.pivot_table}."""
+        {src_snake}_id = int(request.route("source_id"))
+        rows = _SERVICE.list_for_source({src_snake}_id)
+        return BaseController.render(_TEMPLATE_INDEX, context={{
+            "{src_snake}_id": {src_snake}_id,
+            "rows": rows,
+        }}, request=request)
+
+    @staticmethod
+    def add_form(request: Request) -> Response:
+        """Formulaire d'ajout d'une association."""
+        {src_snake}_id = int(request.route("source_id"))
+        return BaseController.render(_TEMPLATE_FORM, context={{
+            "{src_snake}_id": {src_snake}_id,
+            "row": None,
+            "action": f"/{src_snake}s/{{{src_snake}_id}}/{rel.relation_name}/add",
+            "error": None,
+        }}, request=request)
+
+    @staticmethod
+    def add(request: Request) -> Response:
+        """Crée une nouvelle association."""
+        {src_snake}_id = int(request.route("source_id"))
+        {tgt_snake}_id = int(request.form("{rel.to_key}"))
+        pivot_data = {{
+            field: request.form(field)
+            for field in {fields_repr}
+            if request.form(field) is not None
+        }}
+        try:
+            _SERVICE.attach({src_snake}_id, {tgt_snake}_id, pivot_data)
+            return BaseController.redirect(f"/{src_snake}s/{{{src_snake}_id}}/{rel.relation_name}", request=request)
+        except Exception as exc:
+            error = pivot_error_to_form_error(exc)
+            return BaseController.render(_TEMPLATE_FORM, context={{
+                "{src_snake}_id": {src_snake}_id,
+                "row": None,
+                "action": f"/{src_snake}s/{{{src_snake}_id}}/{rel.relation_name}/add",
+                "error": error,
+            }}, request=request)
+
+    @staticmethod
+    def edit_form(request: Request) -> Response:
+        """Formulaire de modification d'une association."""
+        {src_snake}_id = int(request.route("source_id"))
+        {tgt_snake}_id = int(request.route("target_id"))
+        row = _SERVICE.get({src_snake}_id, {tgt_snake}_id)
+        if row is None:
+            return BaseController.redirect(f"/{src_snake}s/{{{src_snake}_id}}/{rel.relation_name}", request=request)
+        return BaseController.render(_TEMPLATE_FORM, context={{
+            "{src_snake}_id": {src_snake}_id,
+            "row": row,
+            "action": f"/{src_snake}s/{{{src_snake}_id}}/{rel.relation_name}/{{{tgt_snake}_id}}/edit",
+            "error": None,
+        }}, request=request)
+
+    @staticmethod
+    def edit(request: Request) -> Response:
+        """Modifie les attributs pivot d'une association."""
+        {src_snake}_id = int(request.route("source_id"))
+        {tgt_snake}_id = int(request.route("target_id"))
+        pivot_data = {{
+            field: request.form(field)
+            for field in {fields_repr}
+            if request.form(field) is not None
+        }}
+        try:
+            _SERVICE.update({src_snake}_id, {tgt_snake}_id, pivot_data)
+            return BaseController.redirect(f"/{src_snake}s/{{{src_snake}_id}}/{rel.relation_name}", request=request)
+        except Exception as exc:
+            error = pivot_error_to_form_error(exc)
+            row = _SERVICE.get({src_snake}_id, {tgt_snake}_id)
+            return BaseController.render(_TEMPLATE_FORM, context={{
+                "{src_snake}_id": {src_snake}_id,
+                "row": row,
+                "action": f"/{src_snake}s/{{{src_snake}_id}}/{rel.relation_name}/{{{tgt_snake}_id}}/edit",
+                "error": error,
+            }}, request=request)
+
+    @staticmethod
+    def remove(request: Request) -> Response:
+        """Supprime une association."""
+        {src_snake}_id = int(request.route("source_id"))
+        {tgt_snake}_id = int(request.route("target_id"))
+        _SERVICE.detach({src_snake}_id, {tgt_snake}_id)
+        return BaseController.redirect(f"/{src_snake}s/{{{src_snake}_id}}/{rel.relation_name}", request=request)
+
+
+controller = {rel.from_entity}{rel.relation_name.capitalize()}PivotController()
+'''
+
+
+def _build_index_template(rel: ResolvedPivotRelation) -> str:
+    src_snake = _to_snake(rel.from_entity)
+    tgt_snake = _to_snake(rel.to_entity)
+    field_headers = "".join(f"        <th>{f}</th>\n" for f in rel.pivot_fields)
+    field_cells = "".join(
+        f"            <td>{{{{ row.pivot_data.get('{f}', '') }}}}</td>\n"
+        for f in rel.pivot_fields
+    )
+
+    return f"""\
+{{% extends "layouts/app.html" %}}
+{{% block content %}}
+<div class="flex justify-between items-center mb-6">
+    <h1 class="text-2xl font-bold text-gray-800">
+        {rel.from_entity} #{{{ src_snake}_id}} — {rel.relation_name}
+    </h1>
+    <a href="/{src_snake}s/{{{{ {src_snake}_id }}}}/{rel.relation_name}/add"
+       class="text-blue-600 hover:underline">Ajouter</a>
+</div>
+
+{{% if rows %}}
+<table class="w-full bg-white shadow rounded">
+    <thead>
+        <tr>
+        <th>{tgt_snake}</th>
+{field_headers}        <th>Actions</th>
+        </tr>
+    </thead>
+    <tbody>
+    {{% for row in rows %}}
+        <tr>
+            <td>{{{{ row.target_id }}}}</td>
+{field_cells}            <td>
+                <a href="/{src_snake}s/{{{{ {src_snake}_id }}}}/{rel.relation_name}/{{{{ row.target_id }}}}/edit">Modifier</a>
+                <form method="post" action="/{src_snake}s/{{{{ {src_snake}_id }}}}/{rel.relation_name}/{{{{ row.target_id }}}}/remove" style="display:inline">
+                    <input type="hidden" name="csrf_token" value="{{{{ csrf_token }}}}">
+                    <button type="submit">Retirer</button>
+                </form>
+            </td>
+        </tr>
+    {{% endfor %}}
+    </tbody>
+</table>
+{{% else %}}
+<p class="text-gray-500">Aucune association.</p>
+{{% endif %}}
+{{% endblock %}}
+"""
+
+
+def _build_form_template(rel: ResolvedPivotRelation) -> str:
+    src_snake = _to_snake(rel.from_entity)
+    tgt_snake = _to_snake(rel.to_entity)
+    field_inputs = "".join(
+        f"""<div>
+    <label>{f}</label>
+    <input type="text" name="{f}" value="{{{{ row.pivot_data.get('{f}', '') if row else '' }}}}">
+</div>
+"""
+        for f in rel.pivot_fields
+    )
+
+    return f"""\
+{{% extends "layouts/app.html" %}}
+{{% block content %}}
+<h1 class="text-2xl font-bold text-gray-800 mb-6">
+    {{{{ "Modifier" if row else "Ajouter" }}}} — {rel.from_entity}.{rel.relation_name}
+</h1>
+
+{{% if error %}}
+<div class="bg-red-50 border border-red-300 text-red-700 px-4 py-3 rounded mb-4">
+    {{{{ error.message }}}}
+</div>
+{{% endif %}}
+
+<form method="post" action="{{{{ action }}}}">
+    <input type="hidden" name="csrf_token" value="{{{{ csrf_token }}}}">
+
+    {{% if not row %}}
+    <div>
+        <label>{tgt_snake}</label>
+        <input type="number" name="{rel.to_key}" required>
+    </div>
+    {{% endif %}}
+
+{field_inputs}
+    <button type="submit">Enregistrer</button>
+    <a href="/{src_snake}s/{{{{ {src_snake}_id }}}}/{rel.relation_name}">Annuler</a>
+</form>
+{{% endblock %}}
+"""
+
+
+# ── Écriture fichier ──────────────────────────────────────────────────────────
+
+def _write_if_new(
+    path: Path,
+    content: str,
+    result: MakePivotCrudResult,
+    dry_run: bool,
+) -> None:
+    if path.exists():
+        result.preserved.append(path)
+    else:
+        if not dry_run:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+        result.created.append(path)
+
+
+# ── Entrée principale ─────────────────────────────────────────────────────────
+
+def make_pivot_crud(
+    source_entity: str,
+    relation_name: str,
+    *,
+    entities_root: Path,
+    output_root: Path,
+    dry_run: bool = False,
+) -> MakePivotCrudResult:
+    """Génère un sous-CRUD Pivot advanced pour une relation many_to_many."""
+    relations_path = entities_root / "relations.json"
+    rel = resolve_pivot_relation(
+        source_entity,
+        relation_name,
+        relations_path=relations_path,
+    )
+
+    src_snake = _to_snake(rel.from_entity)
+    controllers_dir = output_root / "mvc" / "controllers" / "pivot"
+    templates_dir = output_root / "mvc" / "templates" / "pivot" / f"{src_snake}_{rel.relation_name}"
+
+    controller_path = controllers_dir / f"{src_snake}_{rel.relation_name}_pivot_controller.py"
+    index_path = templates_dir / "index.html"
+    form_path = templates_dir / "form.html"
+
+    result = MakePivotCrudResult(dry_run=dry_run)
+
+    _write_if_new(controller_path, _build_controller(rel), result, dry_run)
+    _write_if_new(index_path, _build_index_template(rel), result, dry_run)
+    _write_if_new(form_path, _build_form_template(rel), result, dry_run)
+
+    return result
+
+
+def cmd_make_pivot_crud_main(args: list[str]) -> None:
+    if len(args) < 2 or args[0].startswith("-"):
+        print("Usage : forge make:pivot-crud EntitéSource nomRelation [--dry-run]")
+        raise SystemExit(1)
+
+    source_entity = args[0]
+    relation_name = args[1]
+    dry_run = "--dry-run" in args
+    unknown = [a for a in args[2:] if a != "--dry-run"]
+    if unknown:
+        print(out.error(f"Arguments inconnus : {' '.join(unknown)}"))
+        raise SystemExit(1)
+
+    result = make_pivot_crud(
+        source_entity,
+        relation_name,
+        entities_root=Path("mvc") / "entities",
+        output_root=Path("."),
+        dry_run=dry_run,
+    )
+
+    if dry_run:
+        print(out.dry_run("Aucun fichier créé."))
+        if result.created:
+            print("Fichiers qui seraient générés :")
+            for p in result.created:
+                print(f"  - {p.as_posix()}")
+    else:
+        for p in result.created:
+            print(out.created(p.as_posix()))
+        for p in result.preserved:
+            print(out.preserved(p.as_posix(), "← fichier existant, non touché"))
+
+        if result.created:
+            src_snake = _to_snake(source_entity)
+            print()
+            print(out.ok(f"Pivot advanced généré pour {source_entity}.{relation_name}"))
+            print()
+            ctrl_ref = f"{src_snake}_{relation_name}_ctrl"
+            name_prefix = f"{src_snake}_{relation_name}_pivot"
+            base = f"/{src_snake}s/{{source_id}}/{relation_name}"
+            print("Routes à ajouter dans mvc/routes.py :")
+            print(f'    # Pivot {source_entity}.{relation_name}')
+            print(f'    from mvc.controllers.pivot.{src_snake}_{relation_name}_pivot_controller import controller as {ctrl_ref}')
+            print('    with router.group("") as g:')
+            print(f'        g.add("GET",  "{base}", {ctrl_ref}.index, name="{name_prefix}-index")')
+            print(f'        g.add("GET",  "{base}/add", {ctrl_ref}.add_form, name="{name_prefix}-add_form")')
+            print(f'        g.add("POST", "{base}/add", {ctrl_ref}.add, name="{name_prefix}-add")')
+            print(f'        g.add("GET",  "{base}/{{target_id}}/edit", {ctrl_ref}.edit_form, name="{name_prefix}-edit_form")')
+            print(f'        g.add("POST", "{base}/{{target_id}}/edit", {ctrl_ref}.edit, name="{name_prefix}-edit")')
+            print(f'        g.add("POST", "{base}/{{target_id}}/remove", {ctrl_ref}.remove, name="{name_prefix}-remove")')

forge_mvc_pivot-1.0.0b16/forge_mvc_pivot/service.py

@@ -0,0 +1,363 @@
+"""forge_mvc_pivot/service.py — Service de persistance pour tables pivot avec attributs (opt-in extrait du core, ADR-021).
+
+Permet de gérer les associations many_to_many enrichies (pivot.fields[]) sans
+modifier make:crud. Utilise le même pattern d'injection que MariaDbSessionStore :
+fetch_one, fetch_all et execute sont injectables pour les tests.
+
+Décision : PIVOT-ADVANCED-001 / PIVOT-ADVANCED-003.
+Contraintes : PIVOT-ADVANCED-006.
+UX erreurs : PIVOT-ADVANCED-007.
+UX future : PIVOT-ADVANCED-004 (commande/générateur dédié).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field as dc_field
+from typing import Callable
+
+_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _safe_identifier(name: str, label: str) -> str:
+    """Valide qu'un nom de table ou de colonne ne contient pas de caractères dangereux."""
+    if not _IDENTIFIER_RE.match(name):
+        raise ValueError(
+            f"{label} invalide : {name!r}. "
+            "Seuls les caractères [A-Za-z0-9_] sont autorisés, le premier doit être une lettre ou _."
+        )
+    return name
+
+
+# ── Résultat ──────────────────────────────────────────────────────────────────
+
+@dataclass
+class PivotRow:
+    """Représente une ligne de table pivot avec ses attributs."""
+    source_id: int | str
+    target_id: int | str
+    pivot_data: dict = dc_field(default_factory=dict)
+
+
+# ── Erreur UX ─────────────────────────────────────────────────────────────────
+
+@dataclass
+class PivotFormError:
+    """Erreur pivot normalisée — affichable dans un formulaire de sous-CRUD pivot.
+
+    code    : identifiant stable du type d'erreur
+    message : message humain à afficher dans le formulaire
+    field   : champ concerné si applicable, None sinon
+    """
+    code: str
+    message: str
+    field: str | None = None
+
+
+class PivotConstraintError(ValueError):
+    """Levée quand une contrainte pivot est violée (required, nullable, unique_pair).
+
+    Porte un code stable et éventuellement le champ concerné pour
+    permettre un affichage structuré dans les formulaires pivot.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "invalid_pivot_data",
+        field: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.field = field
+
+
+# ── Contraintes ───────────────────────────────────────────────────────────────
+
+@dataclass
+class PivotFieldConstraint:
+    """Contrainte déclarative sur un champ pivot.
+
+    required=True  → le champ doit être présent dans pivot_data lors d'un attach.
+    nullable=False → la valeur None est refusée lors d'un attach ou update.
+    """
+    name: str
+    required: bool = False
+    nullable: bool = True
+
+
+# ── Helper UX ─────────────────────────────────────────────────────────────────
+
+def pivot_error_to_form_error(error: Exception) -> PivotFormError:
+    """Convertit une exception de PivotAdvancedService en PivotFormError affichable.
+
+    - PivotConstraintError → PivotFormError avec le code et le champ structurés.
+    - ValueError (hors PivotConstraintError) → code unknown_pivot_field.
+    - Autre exception → code invalid_pivot_data, message générique (pas de détail SQL).
+    """
+    if isinstance(error, PivotConstraintError):
+        return PivotFormError(
+            code=error.code,
+            message=str(error),
+            field=error.field,
+        )
+    if isinstance(error, ValueError):
+        return PivotFormError(
+            code="unknown_pivot_field",
+            message=str(error),
+        )
+    return PivotFormError(
+        code="invalid_pivot_data",
+        message="Une erreur est survenue lors de l'enregistrement.",
+    )
+
+
+# ── Accesseurs DB par défaut (lazy — pas de connexion à l'import) ─────────────
+
+def _default_fetch_one(sql: str, params: tuple) -> dict | None:
+    from core.database.db import fetch_one
+    return fetch_one(sql, params)
+
+
+def _default_fetch_all(sql: str, params: tuple) -> list[dict]:
+    from core.database.db import fetch_all
+    return fetch_all(sql, params) or []
+
+
+def _default_execute(sql: str, params: tuple) -> int:
+    from core.database.db import execute
+    return execute(sql, params)
+
+
+def _default_insert(sql: str, params: tuple) -> int:
+    from core.database.db import insert
+    return insert(sql, params)
+
+
+# ── Service ───────────────────────────────────────────────────────────────────
+
+class PivotAdvancedService:
+    """Service générique pour lire et modifier des associations pivot avec attributs.
+
+    Paramètres :
+        table             — nom de la table pivot (ex: "article_tag")
+        source_key        — colonne de clé source (ex: "article_id")
+        target_key        — colonne de clé cible (ex: "tag_id")
+        pivot_fields      — liste des noms de colonnes métier autorisés (ex: ["position", "note"])
+        pivot_constraints — liste de PivotFieldConstraint pour les contraintes avancées
+        unique_pair       — si True, vérifie l'unicité avant INSERT (default False)
+        id_field          — nom de la colonne id technique (ex: "id"), active get_by_id etc.
+
+    Les callables fetch_one, fetch_all, execute et insert_fn sont injectables pour les tests.
+    En production ils délèguent aux helpers core.database.db.
+
+    API pivot_fields (ancienne) et pivot_constraints (nouvelle) sont mutuellement exclusives.
+    Si pivot_constraints est fourni, il prend la priorité et définit la liste des champs autorisés.
+    """
+
+    def __init__(
+        self,
+        table: str,
+        source_key: str,
+        target_key: str,
+        pivot_fields: list[str] | None = None,
+        *,
+        pivot_constraints: list[PivotFieldConstraint] | None = None,
+        unique_pair: bool = False,
+        id_field: str | None = None,
+        fetch_one: Callable | None = None,
+        fetch_all: Callable | None = None,
+        execute: Callable | None = None,
+        insert_fn: Callable | None = None,
+    ) -> None:
+        self._table = _safe_identifier(table, "table")
+        self._source_key = _safe_identifier(source_key, "source_key")
+        self._target_key = _safe_identifier(target_key, "target_key")
+        self._unique_pair = unique_pair
+        self._id_field = _safe_identifier(id_field, "id_field") if id_field else None
+
+        if pivot_constraints is not None:
+            for c in pivot_constraints:
+                _safe_identifier(c.name, f"pivot_constraints[{c.name}].name")
+            self._pivot_fields: tuple[str, ...] = tuple(c.name for c in pivot_constraints)
+            self._constraints: dict[str, PivotFieldConstraint] = {c.name: c for c in pivot_constraints}
+        else:
+            self._pivot_fields = tuple(
+                _safe_identifier(f, f"pivot_fields[{i}]")
+                for i, f in enumerate(pivot_fields or [])
+            )
+            self._constraints = {}
+
+        self._fetch_one = fetch_one or _default_fetch_one
+        self._fetch_all = fetch_all or _default_fetch_all
+        self._execute = execute or _default_execute
+        self._insert_fn = insert_fn or _default_insert
+
+    # ── helpers internes ──────────────────────────────────────────────────────
+
+    def _check_pivot_data(self, pivot_data: dict) -> None:
+        """Lève ValueError si pivot_data contient des clés inconnues."""
+        unknown = set(pivot_data) - set(self._pivot_fields)
+        if unknown:
+            raise ValueError(
+                f"Champs pivot inconnus : {sorted(unknown)}. "
+                f"Champs autorisés : {sorted(self._pivot_fields)}."
+            )
+
+    def _enforce_attach_constraints(self, pivot_data: dict) -> None:
+        """Vérifie required et nullable lors d'un attach."""
+        for field_name, constraint in self._constraints.items():
+            if constraint.required and field_name not in pivot_data:
+                raise PivotConstraintError(
+                    f"Champ pivot requis absent : {field_name!r}.",
+                    code="required_field_missing",
+                    field=field_name,
+                )
+            if not constraint.nullable and field_name in pivot_data and pivot_data[field_name] is None:
+                raise PivotConstraintError(
+                    f"Champ pivot non nullable reçoit None : {field_name!r}.",
+                    code="nullable_field_rejected",
+                    field=field_name,
+                )
+
+    def _enforce_update_constraints(self, pivot_data: dict) -> None:
+        """Vérifie nullable lors d'un update (required non vérifié — mise à jour partielle)."""
+        for field_name, constraint in self._constraints.items():
+            if not constraint.nullable and field_name in pivot_data and pivot_data[field_name] is None:
+                raise PivotConstraintError(
+                    f"Champ pivot non nullable reçoit None : {field_name!r}.",
+                    code="nullable_field_rejected",
+                    field=field_name,
+                )
+
+    def _row_to_pivot_row(self, row: dict) -> PivotRow:
+        pivot_data = {k: v for k, v in row.items()
+                      if k not in (self._source_key, self._target_key)}
+        return PivotRow(
+            source_id=row[self._source_key],
+            target_id=row[self._target_key],
+            pivot_data=pivot_data,
+        )
+
+    # ── API publique ──────────────────────────────────────────────────────────
+
+    def list_for_source(self, source_id: int | str) -> list[PivotRow]:
+        """Retourne toutes les associations liées à source_id."""
+        sql = f"SELECT * FROM {self._table} WHERE {self._source_key} = ?"
+        rows = self._fetch_all(sql, (source_id,))
+        return [self._row_to_pivot_row(r) for r in rows]
+
+    def get(self, source_id: int | str, target_id: int | str) -> PivotRow | None:
+        """Retourne l'association (source_id, target_id), ou None si absente."""
+        sql = (
+            f"SELECT * FROM {self._table} "
+            f"WHERE {self._source_key} = ? AND {self._target_key} = ?"
+        )
+        row = self._fetch_one(sql, (source_id, target_id))
+        return self._row_to_pivot_row(row) if row else None
+
+    def attach(
+        self,
+        source_id: int | str,
+        target_id: int | str,
+        pivot_data: dict | None = None,
+    ) -> int:
+        """Crée une association. Retourne le lastrowid.
+
+        Seuls les champs déclarés dans pivot_fields / pivot_constraints sont acceptés.
+        Si unique_pair=True, lève PivotConstraintError si l'association existe déjà.
+        """
+        pivot_data = pivot_data or {}
+        self._check_pivot_data(pivot_data)
+        self._enforce_attach_constraints(pivot_data)
+
+        if self._unique_pair and self.get(source_id, target_id) is not None:
+            raise PivotConstraintError(
+                f"Association ({source_id}, {target_id}) déjà existante dans {self._table}.",
+                code="duplicate_pair",
+            )
+
+        columns = [self._source_key, self._target_key] + [
+            f for f in self._pivot_fields if f in pivot_data
+        ]
+        placeholders = ", ".join("?" for _ in columns)
+        col_list = ", ".join(columns)
+        values = (source_id, target_id) + tuple(
+            pivot_data[f] for f in self._pivot_fields if f in pivot_data
+        )
+
+        sql = f"INSERT INTO {self._table} ({col_list}) VALUES ({placeholders})"
+        return self._insert_fn(sql, values)
+
+    def update(
+        self,
+        source_id: int | str,
+        target_id: int | str,
+        pivot_data: dict,
+    ) -> int:
+        """Modifie les attributs pivot d'une association existante. Retourne rowcount.
+
+        Ne modifie pas source_key ni target_key.
+        Seuls les champs déclarés dans pivot_fields / pivot_constraints sont acceptés.
+        required n'est pas vérifié (mise à jour partielle autorisée).
+        """
+        self._check_pivot_data(pivot_data)
+        self._enforce_update_constraints(pivot_data)
+        if not pivot_data:
+            return 0
+
+        set_clause = ", ".join(f"{f} = ?" for f in pivot_data)
+        values = tuple(pivot_data[f] for f in pivot_data) + (source_id, target_id)
+        sql = (
+            f"UPDATE {self._table} SET {set_clause} "
+            f"WHERE {self._source_key} = ? AND {self._target_key} = ?"
+        )
+        return self._execute(sql, values)
+
+    def detach(self, source_id: int | str, target_id: int | str) -> int:
+        """Supprime l'association (source_id, target_id). Retourne rowcount."""
+        sql = (
+            f"DELETE FROM {self._table} "
+            f"WHERE {self._source_key} = ? AND {self._target_key} = ?"
+        )
+        return self._execute(sql, (source_id, target_id))
+
+    # ── Méthodes par id technique (requiert id_field) ─────────────────────────
+
+    def get_by_id(self, pivot_id: int | str) -> PivotRow | None:
+        """Retourne la ligne pivot par son id technique. Requiert id_field."""
+        if not self._id_field:
+            raise PivotConstraintError(
+                "get_by_id requiert id_field sur PivotAdvancedService.",
+                code="missing_id_field",
+            )
+        sql = f"SELECT * FROM {self._table} WHERE {self._id_field} = ?"
+        row = self._fetch_one(sql, (pivot_id,))
+        return self._row_to_pivot_row(row) if row else None
+
+    def update_by_id(self, pivot_id: int | str, pivot_data: dict) -> int:
+        """Modifie les attributs d'une ligne pivot par son id technique. Requiert id_field."""
+        if not self._id_field:
+            raise PivotConstraintError(
+                "update_by_id requiert id_field sur PivotAdvancedService.",
+                code="missing_id_field",
+            )
+        self._check_pivot_data(pivot_data)
+        self._enforce_update_constraints(pivot_data)
+        if not pivot_data:
+            return 0
+        set_clause = ", ".join(f"{f} = ?" for f in pivot_data)
+        values = tuple(pivot_data[f] for f in pivot_data) + (pivot_id,)
+        sql = f"UPDATE {self._table} SET {set_clause} WHERE {self._id_field} = ?"
+        return self._execute(sql, values)
+
+    def delete_by_id(self, pivot_id: int | str) -> int:
+        """Supprime une ligne pivot par son id technique. Requiert id_field."""
+        if not self._id_field:
+            raise PivotConstraintError(
+                "delete_by_id requiert id_field sur PivotAdvancedService.",
+                code="missing_id_field",
+            )
+        sql = f"DELETE FROM {self._table} WHERE {self._id_field} = ?"
+        return self._execute(sql, (pivot_id,))

forge_mvc_pivot-1.0.0b16/forge_mvc_pivot.egg-info/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: forge-mvc-pivot
+Version: 1.0.0b16
+Summary: Forge pivot — tables pivot enrichies (many_to_many avec attributs) et generateur make:pivot-crud.
+Author: Roger Lequette
+License-Expression: LicenseRef-Forge-Proprietary
+Project-URL: Homepage, https://github.com/caucrogeGit/Forge
+Project-URL: Repository, https://github.com/caucrogeGit/Forge
+Project-URL: Documentation, https://forgemvc.com/docs/forge/
+Keywords: python,mvc,forge,pivot,many-to-many
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: forge-mvc<2,>=1.0.0b16
+Dynamic: license-file
+
+# forge-mvc-pivot
+
+Opt-in Forge pour les **tables pivot enrichies** : associations `many_to_many`
+portant des attributs (par exemple `position`, `note`) sur la ligne de jointure.
+
+Extrait du core de Forge (ADR-021) : le core ne contient que les primitives
+générales ; le pivot avancé est une brique spécialisée, optionnelle.
+
+## Contenu
+
+- `PivotAdvancedService` : lecture et écriture d'associations pivot avec
+  attributs, contraintes déclaratives (`required`, `nullable`, `unique_pair`),
+  accès base injectables (`fetch_one`, `fetch_all`, `execute`, `insert_fn`).
+- `PivotFieldConstraint`, `PivotRow`, `PivotFormError`, `PivotConstraintError`,
+  `pivot_error_to_form_error` : contraintes, résultats et erreurs structurées.
+- Générateur `forge make:pivot-crud <EntitéSource> <nomRelation>` : échafaude un
+  sous-CRUD pivot à partir d'une relation `many_to_many` déclarée dans
+  `relations.json`.
+
+## Installation
+
+```bash
+pip install --pre forge-mvc-pivot
+```
+
+Le code généré importe `forge_mvc_pivot` : installez le paquet avant de lancer
+une application qui s'appuie sur un sous-CRUD pivot.

forge_mvc_pivot-1.0.0b16/forge_mvc_pivot.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+forge_mvc_pivot/__init__.py
+forge_mvc_pivot/make_pivot_crud.py
+forge_mvc_pivot/service.py
+forge_mvc_pivot.egg-info/PKG-INFO
+forge_mvc_pivot.egg-info/SOURCES.txt
+forge_mvc_pivot.egg-info/dependency_links.txt
+forge_mvc_pivot.egg-info/requires.txt
+forge_mvc_pivot.egg-info/top_level.txt

forge_mvc_pivot-1.0.0b16/forge_mvc_pivot.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

forge_mvc_pivot-1.0.0b16/forge_mvc_pivot.egg-info/requires.txt

@@ -0,0 +1 @@
+forge-mvc<2,>=1.0.0b16

forge_mvc_pivot-1.0.0b16/forge_mvc_pivot.egg-info/top_level.txt

@@ -0,0 +1 @@
+forge_mvc_pivot

forge_mvc_pivot-1.0.0b16/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "forge-mvc-pivot"
+version = "1.0.0b16"
+description = "Forge pivot — tables pivot enrichies (many_to_many avec attributs) et generateur make:pivot-crud."
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.12"
+authors = [
+    { name = "Roger Lequette" },
+]
+license = "LicenseRef-Forge-Proprietary"
+keywords = ["python", "mvc", "forge", "pivot", "many-to-many"]
+dependencies = [
+    "forge-mvc>=1.0.0b16,<2",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[project.urls]
+Homepage = "https://github.com/caucrogeGit/Forge"
+Repository = "https://github.com/caucrogeGit/Forge"
+Documentation = "https://forgemvc.com/docs/forge/"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["forge_mvc_pivot*"]

forge_mvc_pivot-1.0.0b16/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+