geneweb-py 0.1.0__py3-none-any.whl

geneweb_py/__init__.py

@@ -0,0 +1,23 @@
+"""
+geneweb-py : Librairie Python pour le format GeneWeb (.gw)
+
+Cette librairie permet de parser, manipuler et convertir les fichiers
+généalogiques au format GeneWeb (.gw).
+"""
+
+__version__ = "0.1.0"
+__author__ = "Guillaume Cayeux"
+__email__ = "guillaume.cayeux@relais4x100a2.fr"
+
+from .core.models import Date, Event, Family, Genealogy, Person
+from .core.parser import GeneWebParser, MultiPassParser
+
+__all__ = [
+    "Person",
+    "Family",
+    "Event",
+    "Date",
+    "Genealogy",
+    "GeneWebParser",
+    "MultiPassParser",
+]

geneweb_py/analytics/__init__.py

@@ -0,0 +1,5 @@
+"""Analyses prosopographiques (réseaux). Dépendances graphiques : extra analytics."""
+
+from .network import Network, NetworkEdge, NetworkNode, build_network
+
+__all__ = ["Network", "NetworkEdge", "NetworkNode", "build_network"]

geneweb_py/analytics/network.py

@@ -0,0 +1,261 @@
+"""Réseau prosopographique : personnes, organisations et événements.
+
+Remplace le script historique de ``Geneweb`` (V2, ``data_export/network.py``) qui
+reconstruisait le graphe depuis des CSV. Ici le graphe est construit directement depuis
+``Genealogy`` et ses ``Organization`` / ``OrganizationLink``.
+
+La construction (``build_network``) et l'export JSON (vis.js) n'ont aucune dépendance.
+``to_networkx``, GraphML, GEXF et Pyvis exigent l'extra ``analytics``.
+"""
+
+import importlib
+import json
+from dataclasses import dataclass, field
+from itertools import combinations
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..core.genealogy import Genealogy
+
+NODE_PERSON = "person"
+NODE_ORG = "organization"
+NODE_EVENT = "event"
+
+EDGE_MEMBER = "member"
+EDGE_PARTICIPANT = "participant"
+EDGE_ORGANIZATION = "organization"
+EDGE_WITNESS = "witness"
+EDGE_SPOUSE = "spouse"
+EDGE_PARENT = "parent"
+EDGE_CO_MEMBER = "co_member"
+
+PathLike = str | Path
+
+
+def _require(module: str) -> Any:
+    try:
+        return importlib.import_module(module)
+    except ImportError as exc:
+        raise ImportError(
+            f"'{module}' est requis pour cet export : "
+            "installer l'extra avec `uv sync --extra analytics`."
+        ) from exc
+
+
+@dataclass
+class NetworkNode:
+    id: str
+    label: str
+    kind: str
+    attrs: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class NetworkEdge:
+    source: str
+    target: str
+    kind: str
+    weight: int = 1
+
+
+@dataclass
+class Network:
+    """Graphe non orienté, indépendant de toute bibliothèque."""
+
+    nodes: list[NetworkNode] = field(default_factory=list)
+    edges: list[NetworkEdge] = field(default_factory=list)
+
+    def node(self, node_id: str) -> NetworkNode:
+        return next(n for n in self.nodes if n.id == node_id)
+
+    def edge(self, a: str, b: str) -> NetworkEdge:
+        """Arête entre ``a`` et ``b`` (dans un sens ou dans l'autre)."""
+        return next(e for e in self.edges if {e.source, e.target} == {a, b})
+
+    def co_membership(self) -> "Network":
+        """Projection sur les personnes : lien pondéré par le nombre d'organisations
+        partagées."""
+        members: dict[str, set[str]] = {}
+        for e in self.edges:
+            if e.kind == EDGE_MEMBER:
+                members.setdefault(e.target, set()).add(e.source)
+        shared: dict[tuple[str, str], int] = {}
+        for people in members.values():
+            for pair in combinations(sorted(people), 2):
+                shared[pair] = shared.get(pair, 0) + 1
+        used = {p for pair in shared for p in pair}
+        return Network(
+            nodes=[n for n in self.nodes if n.id in used],
+            edges=[
+                NetworkEdge(a, b, EDGE_CO_MEMBER, weight)
+                for (a, b), weight in shared.items()
+            ],
+        )
+
+    # -- Exports ----------------------------------------------------------
+    def export_json(self, path: PathLike) -> Path:
+        """JSON ``{"nodes": [...], "edges": [...]}`` directement lisible par vis.js."""
+        payload = {
+            "nodes": [
+                {"id": n.id, "label": n.label, "group": n.kind, **n.attrs}
+                for n in self.nodes
+            ],
+            "edges": [
+                {"from": e.source, "to": e.target, "value": e.weight, "title": e.kind}
+                for e in self.edges
+            ],
+        }
+        target = Path(path)
+        target.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+        )
+        return target
+
+    def to_networkx(self) -> Any:
+        """``networkx.Graph`` (attributs ``kind``, ``label``, ``weight``)."""
+        nx = _require("networkx")
+        graph = nx.Graph()
+        for n in self.nodes:
+            graph.add_node(n.id, label=n.label, kind=n.kind, **n.attrs)
+        for e in self.edges:
+            graph.add_edge(e.source, e.target, kind=e.kind, weight=e.weight)
+        return graph
+
+    def export_graphml(self, path: PathLike) -> Path:
+        nx = _require("networkx")
+        nx.write_graphml(self.to_networkx(), str(path), encoding="utf-8")
+        return Path(path)
+
+    def export_gexf(self, path: PathLike) -> Path:
+        nx = _require("networkx")
+        nx.write_gexf(self.to_networkx(), str(path), encoding="utf-8")
+        return Path(path)
+
+    def export_pyvis_html(self, path: PathLike, height: str = "750px") -> Path:
+        """Page HTML autonome (bibliothèque embarquée, aucun accès réseau)."""
+        pyvis_network = _require("pyvis.network")
+        vis = pyvis_network.Network(
+            height=height, width="100%", cdn_resources="in_line", notebook=False
+        )
+        for n in self.nodes:
+            vis.add_node(n.id, label=n.label, group=n.kind)
+        for e in self.edges:
+            vis.add_edge(e.source, e.target, value=e.weight, title=e.kind)
+        target = Path(path)
+        vis.write_html(str(target), notebook=False)
+        return target
+
+
+def _person_label(person: Any) -> str:
+    return f"{person.last_name} {person.first_name}".strip()
+
+
+def build_network(
+    genealogy: "Genealogy",
+    include_events: bool = False,
+    include_families: bool = False,
+) -> Network:
+    """Construit le réseau prosopographique d'une généalogie.
+
+    Nœuds ``person:<id>`` et ``org:<id>`` ; arête ``member`` personne -> organisation
+    pondérée par le nombre de ``OrganizationLink``.
+
+    Args:
+        include_events: ajoute un nœud par événement à l'origine d'un lien,
+            relié à son titulaire (``participant``), à l'organisation (``organization``)
+            et à ses témoins (``witness``).
+        include_families: ajoute les liens de parenté (``spouse``, ``parent``).
+    """
+    network = Network()
+    node_ids: set[str] = set()
+    weights: dict[tuple[str, str, str], int] = {}
+
+    def add_node(node: NetworkNode) -> None:
+        if node.id not in node_ids:
+            node_ids.add(node.id)
+            network.nodes.append(node)
+
+    def add_edge(source: str, target: str, kind: str) -> None:
+        weights[(source, target, kind)] = weights.get((source, target, kind), 0) + 1
+
+    for person_id, person in genealogy.persons.items():
+        add_node(NetworkNode(f"person:{person_id}", _person_label(person), NODE_PERSON))
+
+    for org in genealogy.organizations.values():
+        attrs = {
+            "type": org.type.value,
+            "place": org.place,
+            "confidence": org.confidence,
+            "needs_review": org.needs_review,
+        }
+        add_node(
+            NetworkNode(
+                f"org:{org.id}",
+                org.name,
+                NODE_ORG,
+                {k: v for k, v in attrs.items() if v is not None},
+            )
+        )
+
+    for link in genealogy.organization_links:
+        add_edge(f"person:{link.person_id}", f"org:{link.organization_id}", EDGE_MEMBER)
+
+    if include_events:
+        _add_events(genealogy, add_node, add_edge)
+
+    if include_families:
+        for family in genealogy.families.values():
+            if family.husband_id and family.wife_id:
+                add_edge(
+                    f"person:{family.husband_id}",
+                    f"person:{family.wife_id}",
+                    EDGE_SPOUSE,
+                )
+            for child in family.children:
+                for parent_id in (family.husband_id, family.wife_id):
+                    if parent_id:
+                        add_edge(
+                            f"person:{parent_id}",
+                            f"person:{child.person_id}",
+                            EDGE_PARENT,
+                        )
+
+    network.edges = [
+        NetworkEdge(source, target, kind, weight)
+        for (source, target, kind), weight in weights.items()
+        if source in node_ids and target in node_ids
+    ]
+    return network
+
+
+def _add_events(genealogy: "Genealogy", add_node: Any, add_edge: Any) -> None:
+    for person_id, person in genealogy.persons.items():
+        links = genealogy.get_organization_links(person_id=person_id)
+        for index, event in enumerate(person.events):
+            date = event.date.display_text if event.date else None
+            matching = [
+                link
+                for link in links
+                if link.source_event_type == event.event_type_raw
+                and (link.start_date.display_text if link.start_date else None) == date
+            ]
+            if not matching:
+                continue
+            event_id = f"event:{person_id}:{index}"
+            label = " ".join(p for p in (event.event_type_raw, date) if p)
+            add_node(
+                NetworkNode(
+                    event_id,
+                    label,
+                    NODE_EVENT,
+                    {"place": event.place} if event.place else {},
+                )
+            )
+            add_edge(f"person:{person_id}", event_id, EDGE_PARTICIPANT)
+            for link in matching:
+                add_edge(event_id, f"org:{link.organization_id}", EDGE_ORGANIZATION)
+            for witness in event.witnesses:
+                witness_id = witness.get("person_id")
+                if witness_id:
+                    add_edge(f"person:{witness_id}", event_id, EDGE_WITNESS)

geneweb_py/api/__init__.py

@@ -0,0 +1,11 @@
+"""
+Module API FastAPI pour geneweb-py.
+
+Ce module fournit une API REST moderne pour manipuler les données généalogiques
+au format GeneWeb (.gw) avec FastAPI.
+"""
+
+from .main import app, create_app
+from .services.genealogy_service import GenealogyService
+
+__all__ = ["app", "create_app", "GenealogyService"]

geneweb_py/api/dependencies.py

@@ -0,0 +1,75 @@
+"""Dépendances FastAPI pour l'API geneweb-py."""
+
+from fastapi import Depends, Header, HTTPException, Request, Response, status
+
+import geneweb_py.api.limits as _limits_mod
+
+from .services.genealogy_service import GenealogyService
+from .session_store import SessionStore
+
+
+def get_store(request: Request) -> SessionStore:
+    """Retourne le SessionStore stocké dans app.state."""
+    return request.app.state.session_store
+
+
+# Temps restant (secondes) renvoyé à chaque requête de session : le client recale son
+# compte à rebours sans dépendre de son horloge.
+SESSION_EXPIRES_IN_HEADER = "X-Session-Expires-In"
+
+
+def get_session_service(
+    response: Response,
+    x_session_token: str = Header(..., alias="X-Session-Token"),
+    store: SessionStore = Depends(get_store),
+) -> GenealogyService:
+    """Résout le token de session (et prolonge son TTL) ; retourne son GenealogyService.
+
+    Le service est conservé avec la session : ses caches (index des candidates,
+    témoins) et ses réglages (mots ignorés) survivent d'une requête à l'autre.
+    """
+    touched = store.service(x_session_token)
+    if touched is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Session inconnue ou expirée",
+        )
+    service, expires_at = touched
+    response.headers[SESSION_EXPIRES_IN_HEADER] = str(store.seconds_left(expires_at))
+    return service
+
+
+def require_write_mode() -> None:
+    """Lève 405 si l'API est en mode lecture seule (READ_ONLY=true)."""
+    if _limits_mod.READ_ONLY:
+        raise HTTPException(
+            status_code=status.HTTP_405_METHOD_NOT_ALLOWED,
+            detail="API en mode lecture seule",
+        )
+
+
+def get_pagination_params(
+    page: int = 1, size: int = 20, max_size: int = 100
+) -> tuple[int, int]:
+    """Valide et retourne les paramètres de pagination."""
+    if page < 1:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Le numéro de page doit être supérieur à 0",
+        )
+    if size < 1 or size > max_size:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"La taille de la page doit être entre 1 et {max_size}",
+        )
+    return page, size
+
+
+def get_search_limit(limit: int = 50, max_limit: int = 100) -> int:
+    """Valide et retourne la limite de recherche."""
+    if limit < 1 or limit > max_limit:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"La limite doit être entre 1 et {max_limit}",
+        )
+    return limit

geneweb_py/api/family_payload.py

@@ -0,0 +1,64 @@
+"""
+Construction des charges utiles Family pour les réponses API.
+"""
+
+from ..core.family import Family
+from .models.family import FamilyListSchema, FamilySchema
+from .serialization import child_to_schema, date_to_api_string, stable_event_id
+
+
+def _divorce_place_from_family(family: Family) -> str | None:
+    """Lieu de divorce si stocké en métadonnées du parseur."""
+    if not family.metadata:
+        return None
+    raw = family.metadata.get("divorce_place")
+    if raw is None:
+        return None
+    text = str(raw).strip()
+    return text or None
+
+
+def family_to_family_schema(family: Family) -> FamilySchema:
+    """Convertit une famille domaine en schéma API complet."""
+    src_list: list[str] = []
+    if family.family_source and str(family.family_source).strip():
+        src_list.append(str(family.family_source).strip())
+
+    event_ids: list[str] = []
+    for idx, ev in enumerate(family.events):
+        uid = getattr(ev, "unique_id", None)
+        if uid is not None:
+            event_ids.append(str(uid))
+        else:
+            event_ids.append(
+                stable_event_id(
+                    ev, scope="family", scope_key=family.family_id, index=idx
+                )
+            )
+
+    return FamilySchema(
+        id=family.family_id,
+        husband_id=family.husband_id,
+        wife_id=family.wife_id,
+        children=[child_to_schema(c) for c in family.children],
+        marriage_status=family.marriage_status,
+        notes=family.comments,
+        sources=src_list,
+        marriage_date=date_to_api_string(family.marriage_date),
+        marriage_place=family.marriage_place,
+        divorce_date=date_to_api_string(family.divorce_date),
+        divorce_place=_divorce_place_from_family(family),
+        events=event_ids,
+    )
+
+
+def family_to_list_schema(family: Family) -> FamilyListSchema:
+    """Schéma liste famille avec date de mariage."""
+    return FamilyListSchema(
+        id=family.family_id,
+        husband_id=family.husband_id,
+        wife_id=family.wife_id,
+        children_count=len(family.children),
+        marriage_date=date_to_api_string(family.marriage_date),
+        marriage_status=family.marriage_status,
+    )

geneweb_py/api/limits.py

@@ -0,0 +1,87 @@
+"""
+Limites et seuils de sécurité pour l'API HTTP.
+
+Les valeurs peuvent être surchargées via les variables d'environnement
+pour l'adaptation au déploiement.
+"""
+
+import os
+
+# Origines autorisées en développement / test local (frontends sur le port 3000).
+DEFAULT_DEV_CORS_ORIGINS: list[str] = [
+    "http://127.0.0.1:3000",
+    "http://localhost:3000",
+]
+
+
+def _parse_int_env(name: str, default: int) -> int:
+    """Lit une variable d'environnement entière avec repli sur défaut."""
+    raw = os.getenv(name)
+    if raw is None or raw.strip() == "":
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        return default
+
+
+def _split_csv_origins(raw: str) -> list[str]:
+    """Découpe une chaîne d'origines séparées par des virgules."""
+    return [item.strip() for item in raw.split(",") if item.strip()]
+
+
+def _get_api_env() -> str:
+    """Retourne le mode d'exécution API (dev, test, prod)."""
+    raw = os.getenv("GENEWEB_API_ENV", "dev")
+    return raw.strip().lower() or "dev"
+
+
+def get_cors_allow_origins() -> list[str]:
+    """
+    Retourne la liste des origines CORS autorisées selon l'environnement.
+
+    Priorité des variables d'environnement :
+        1. ``ALLOWED_ORIGINS`` (liste séparée par des virgules) ;
+        2. ``CORS_ORIGINS`` (rétrocompatibilité) ;
+        3. Si aucune n'est définie et que ``GENEWEB_API_ENV=prod`` : liste vide
+           (aucune origine cross-origin tant que l'opérateur ne configure pas
+           ``ALLOWED_ORIGINS``) ;
+        4. Sinon : ``DEFAULT_DEV_CORS_ORIGINS``.
+
+    En production, une origine ``*`` est ignorée (incompatible avec
+    ``allow_credentials=True`` et interdit par les critères de sécurité).
+
+    Returns:
+        Liste d'URL d'origine sans slash final parasite.
+    """
+    api_env = _get_api_env()
+    origins: list[str]
+
+    if "ALLOWED_ORIGINS" in os.environ:
+        raw = os.environ["ALLOWED_ORIGINS"]
+        if raw.strip() == "":
+            origins = []
+        else:
+            origins = _split_csv_origins(raw)
+    elif "CORS_ORIGINS" in os.environ:
+        raw = os.environ["CORS_ORIGINS"]
+        if raw.strip() == "":
+            origins = []
+        else:
+            origins = _split_csv_origins(raw)
+    elif api_env == "prod":
+        origins = []
+    else:
+        origins = list(DEFAULT_DEV_CORS_ORIGINS)
+
+    if api_env == "prod":
+        origins = [o for o in origins if o != "*"]
+
+    return origins
+
+
+MAX_UPLOAD_BYTES: int = _parse_int_env("GENEWEB_MAX_UPLOAD_BYTES", 50 * 1024 * 1024)
+
+SESSION_MAX_SESSIONS: int = _parse_int_env("SESSION_MAX_SESSIONS", 10)
+SESSION_TTL_SECONDS: int = _parse_int_env("SESSION_TTL_SECONDS", 3600)
+READ_ONLY: bool = os.getenv("READ_ONLY", "false").strip().lower() == "true"