s3dgraphy 1.6.0.dev7__tar.gz → 1.6.0.dev8__tar.gz

{s3dgraphy-1.6.0.dev7/src/s3dgraphy.egg-info → s3dgraphy-1.6.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev7
+Version: 1.6.0.dev8
 Summary: 3D Stratigraphic Graph Management Library for archaeological and heritage applications
 Author-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
 Maintainer-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
@@ -97,30 +97,47 @@ pip install s3dgraphy[full]          # All optional dependencies
 ## 🔧 Quick Start
 
 ```python
-import s3dgraphy
+from s3dgraphy import Graph
+from s3dgraphy.nodes import StratigraphicUnit, DocumentNode
 
-# Create a new stratigraphic graph
-graph = s3dgraphy.Graph()
+# Create a new stratigraphic graph (graph_id is required)
+graph = Graph("my_excavation")
 
-# Add stratigraphic units
-us1 = graph.add_node("US001", node_type="US", 
-                     properties={"period": "Roman", "material": "pottery"})
-us2 = graph.add_node("US002", node_type="US", 
-                     properties={"period": "Medieval", "material": "stone"})
+# Build node objects, then add them with add_node()
+wall = StratigraphicUnit("US001", name="US001", description="Stone wall foundation")
+floor = StratigraphicUnit("US002", name="US002", description="Mosaic floor")
+graph.add_node(wall)
+graph.add_node(floor)
 
-# Add stratigraphic relationships
-graph.add_edge(us1, us2, edge_type="ABOVE", 
-               properties={"certainty": "high"})
+# Add a stratigraphic relationship.
+# Canonical direction is recent -> ancient: the floor (US002) is more
+# recent than the wall (US001), so US002 is_after US001.
+graph.add_edge("e1", "US002", "US001", "is_after")
+
+# Attach documentation
+doc = DocumentNode("DOC001", name="DOC001", description="Field photo")
+graph.add_node(doc)
+graph.add_edge("e2", "US001", "DOC001", "has_documentation")
 
 # Query the graph
-print(f"Graph contains {len(graph.nodes)} stratigraphic units")
-print(f"Relationships: {len(graph.edges)}")
+print(f"Graph contains {len(graph.nodes)} nodes and {len(graph.edges)} edges")
+us_units = graph.get_nodes_by_type("US")
 
-# Export to different formats
-graph.export_graphml("stratigraphy.graphml")
-graph.export_json("stratigraphy.json")
+# Export to GraphML (yEd round-trip) — the exporter takes the graph directly
+from s3dgraphy.exporter.graphml import GraphMLExporter
+GraphMLExporter(graph).export("my_excavation.graphml")
 ```
 
+> **Note on the API.** Nodes are *objects* (`StratigraphicUnit`,
+> `DocumentNode`, …) created first and then added with `graph.add_node()`.
+> Edges are created with `graph.add_edge(edge_id, source_id, target_id,
+> edge_type)` using a **canonical** edge type from the connections
+> datamodel (e.g. `is_after`, `has_property`, `has_documentation`). Invalid
+> connections are downgraded to `generic_connection` with a warning rather
+> than silently accepted. See the
+> [API reference](https://docs.extendedmatrix.org/projects/s3dgraphy/) for
+> the full node and edge catalogs.
+
 ## 📚 Core Features
 
 ### 🏛️ Archaeological Stratigraphic Modeling
@@ -328,12 +345,12 @@ The GPL-3.0 license ensures that s3dgraphy remains free and open source, promoti
 If you use s3dgraphy in your research, please cite:
 
 ```bibtex
-@software{s3dgraphy2024,
+@software{s3dgraphy,
   title={s3dgraphy: 3D Stratigraphic Graph Management Library},
   author={Demetrescu, Emanuel},
-  year={2024},
+  year={2026},
   url={https://github.com/zalmoxes-laran/s3dgraphy},
-  version={0.1.1},
+  version={1.6.0},
   institution={CNR-ISPC (National Research Council - Institute of Heritage Science)}
 }
 ```

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8}/README.md

@@ -29,30 +29,47 @@ pip install s3dgraphy[full]          # All optional dependencies
 ## 🔧 Quick Start
 
 ```python
-import s3dgraphy
+from s3dgraphy import Graph
+from s3dgraphy.nodes import StratigraphicUnit, DocumentNode
 
-# Create a new stratigraphic graph
-graph = s3dgraphy.Graph()
+# Create a new stratigraphic graph (graph_id is required)
+graph = Graph("my_excavation")
 
-# Add stratigraphic units
-us1 = graph.add_node("US001", node_type="US", 
-                     properties={"period": "Roman", "material": "pottery"})
-us2 = graph.add_node("US002", node_type="US", 
-                     properties={"period": "Medieval", "material": "stone"})
+# Build node objects, then add them with add_node()
+wall = StratigraphicUnit("US001", name="US001", description="Stone wall foundation")
+floor = StratigraphicUnit("US002", name="US002", description="Mosaic floor")
+graph.add_node(wall)
+graph.add_node(floor)
 
-# Add stratigraphic relationships
-graph.add_edge(us1, us2, edge_type="ABOVE", 
-               properties={"certainty": "high"})
+# Add a stratigraphic relationship.
+# Canonical direction is recent -> ancient: the floor (US002) is more
+# recent than the wall (US001), so US002 is_after US001.
+graph.add_edge("e1", "US002", "US001", "is_after")
+
+# Attach documentation
+doc = DocumentNode("DOC001", name="DOC001", description="Field photo")
+graph.add_node(doc)
+graph.add_edge("e2", "US001", "DOC001", "has_documentation")
 
 # Query the graph
-print(f"Graph contains {len(graph.nodes)} stratigraphic units")
-print(f"Relationships: {len(graph.edges)}")
+print(f"Graph contains {len(graph.nodes)} nodes and {len(graph.edges)} edges")
+us_units = graph.get_nodes_by_type("US")
 
-# Export to different formats
-graph.export_graphml("stratigraphy.graphml")
-graph.export_json("stratigraphy.json")
+# Export to GraphML (yEd round-trip) — the exporter takes the graph directly
+from s3dgraphy.exporter.graphml import GraphMLExporter
+GraphMLExporter(graph).export("my_excavation.graphml")
 ```
 
+> **Note on the API.** Nodes are *objects* (`StratigraphicUnit`,
+> `DocumentNode`, …) created first and then added with `graph.add_node()`.
+> Edges are created with `graph.add_edge(edge_id, source_id, target_id,
+> edge_type)` using a **canonical** edge type from the connections
+> datamodel (e.g. `is_after`, `has_property`, `has_documentation`). Invalid
+> connections are downgraded to `generic_connection` with a warning rather
+> than silently accepted. See the
+> [API reference](https://docs.extendedmatrix.org/projects/s3dgraphy/) for
+> the full node and edge catalogs.
+
 ## 📚 Core Features
 
 ### 🏛️ Archaeological Stratigraphic Modeling
@@ -260,12 +277,12 @@ The GPL-3.0 license ensures that s3dgraphy remains free and open source, promoti
 If you use s3dgraphy in your research, please cite:
 
 ```bibtex
-@software{s3dgraphy2024,
+@software{s3dgraphy,
   title={s3dgraphy: 3D Stratigraphic Graph Management Library},
   author={Demetrescu, Emanuel},
-  year={2024},
+  year={2026},
   url={https://github.com/zalmoxes-laran/s3dgraphy},
-  version={0.1.1},
+  version={1.6.0},
   institution={CNR-ISPC (National Research Council - Institute of Heritage Science)}
 }
 ```

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "s3dgraphy"
-version = "1.6.0.dev7"
+version = "1.6.0.dev8"
 description = "3D Stratigraphic Graph Management Library for archaeological and heritage applications"
 readme = "README.md"
 requires-python = ">=3.9"

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8}/src/s3dgraphy/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.6.0.dev7"
+__version__ = "1.6.0.dev8"
 __datamodel_version__ = "1.5.5"  # s3Dgraphy connections datamodel version
 
 # s3Dgraphy/__init__.py

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8}/src/s3dgraphy/edges/edge.py

@@ -17,6 +17,12 @@ def _build_legacy_edge_types():
     return edge_types
 
 EDGE_TYPES = _build_legacy_edge_types()
+"""Legacy mapping ``edge_type -> {"label", "description"}``.
+
+Rebuilt from the connections datamodel for backward compatibility; new
+code should query :func:`s3dgraphy.edges.connections_loader.get_connections_datamodel`
+instead. ``Edge`` validates ``edge_type`` against the keys of this dict.
+"""
 
 class Edge:
     """

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8}/src/s3dgraphy/exporter/graphml/graphml_patcher.py

@@ -3,10 +3,11 @@ GraphML Patcher for s3dgraphy.
 
 Patches an existing GraphML file on disk with changes from an in-memory Graph.
 Supports:
-  - Updating existing nodes (description, name, EMID, URI)
-  - Adding new nodes that were created in-memory
-  - Adding new edges
-  - EMID validation and duplicate detection
+
+- Updating existing nodes (description, name, EMID, URI)
+- Adding new nodes that were created in-memory
+- Adding new edges
+- EMID validation and duplicate detection
 
 This is the "twin" of the importer: it uses the same dynamic key mapping
 and the same conventions to write back what the importer can read.
@@ -1429,11 +1430,13 @@ class GraphMLPatcher:
         Add new edges to the GraphML XML.
 
         For each edge in the graph that does NOT have an original_edge_id:
+
         - Generates a new edge ID
         - Creates <edge> XML with correct line style for the edge type
         - Resolves source/target using original_id or generated ID
 
         Skips:
+
         - Edges with original_edge_id (already in the XML)
         - Structural edges (represented by XML nesting, not <edge> elements)
         - Derived has_property edges where the target PropertyNode is inside

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8}/src/s3dgraphy/importer/import_graphml.py

@@ -2616,12 +2616,13 @@ class GraphMLImporter:
         """
         Verifica se un nodo è un nodo di continuità (BR).
         Usa una detection multi-segnale:
-          A) '_continuity' nel campo URL o description
-          B) ShapeNode con shape type 'diamond'
-          C) SVGNode il cui SVGContent refid punta alla risorsa
-             ``continuity.svg`` (refid risolto dinamicamente, vedi
-             build_svg_resource_map — yEd numera le Resource per ordine
-             di serializzazione, non c'è un id fisso)
+
+        A) '_continuity' nel campo URL o description
+        B) ShapeNode con shape type 'diamond'
+        C) SVGNode il cui SVGContent refid punta alla risorsa
+           ``continuity.svg`` (refid risolto dinamicamente, vedi
+           build_svg_resource_map — yEd numera le Resource per ordine
+           di serializzazione, non c'è un id fisso)
 
         Args:
             node_element: Elemento XML del nodo

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8}/src/s3dgraphy/nodes/hdt_node.py

@@ -9,12 +9,14 @@ formal propositions) about a heritage entity (HC1). HDTs are hierarchically
 composable — a city HDT contains district HDTs which contain monument HDTs.
 
 Granularity connectors (declared in s3Dgraphy_connections_datamodel.json):
-  * has_digital_twin              — Node → HDTNode  (HP1)
-  * has_digital_twin_component    — HDTNode → HDTNode (HP3 inverse, transitive)
-  * contains_proposition_set      — HDTNode → GraphNode (HP33)
-  * has_digital_object_part       — HDTNode → RepresentationModel* / LinkNode (HP29)
 
-Use case (the Colosseo example):
+* has_digital_twin              — Node → HDTNode  (HP1)
+* has_digital_twin_component    — HDTNode → HDTNode (HP3 inverse, transitive)
+* contains_proposition_set      — HDTNode → GraphNode (HP33)
+* has_digital_object_part       — HDTNode → RepresentationModel* / LinkNode (HP29)
+
+Use case (the Colosseo example)::
+
     colosseo_overall   = HDTNode("hdt_colosseo_overall", name="Colosseo HDT")
     colosseo_flavian   = HDTNode("hdt_colosseo_flavian", name="Colosseo Flavian phase")
     colosseo_medieval  = HDTNode("hdt_colosseo_medieval", name="Colosseo medieval fortress")

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8}/src/s3dgraphy/sync/graph_projector.py

@@ -578,6 +578,11 @@ class GraphProjector:
             except Exception:
                 period_datazione = {}
 
+        # Localized US/USM → canonical alias map (the single source in
+        # sync.rapporti) so non-Italian unita_tipo codes are recognised as
+        # stratigraphic units in the gating + node-class factory below.
+        from .rapporti import canonical_unita_tipo
+
         for (us_val, node_uuid, sito_v, area, unita_tipo,
              periodo_ini, fase_ini, rapporti_raw, d_strat,
              d_interp, attivita, struttura,
@@ -586,6 +591,13 @@ class GraphProjector:
             if not us_name:
                 continue
             ut_str = str(unita_tipo) if unita_tipo is not None else ""
+            # Canonical US/USM code for the structural decisions below
+            # (stratigraphic gating + node-class factory), so localized
+            # codes (SU/WSU/SE/…) are recognised as real stratigraphic
+            # units. attributes['unita_tipo'] keeps the ORIGINAL code
+            # (set further down) for round-trip + the language-aware
+            # rapporti dispatch.
+            ut_canon = canonical_unita_tipo(ut_str)
             node = None
             # Direct hit by composite key (paradata that the bridge
             # correctly classified OR a stratigraphic node already
@@ -602,14 +614,14 @@ class GraphProjector:
             # order (e.g. yEd document order interleaves US01 and
             # DOC.01 — DOC.01 might claim the bridge's '01' placeholder
             # before US01 row is iterated).
-            if node is None and ut_str in (
+            if node is None and ut_canon in (
                 "US", "USM", "USD", "USV", "USVs", "USVn", "USVc",
                 "SF", "VSF", "RSF",
             ):
                 node = nodes_by_key.pop((us_name, "__STRAT__"), None)
                 if node is None:
                     node = _create_stratigraphic_node_for_unita_tipo(
-                        ut_str, us_name, node_uuid or us_name,
+                        ut_canon, us_name, node_uuid or us_name,
                     )
                     if node is not None:
                         try:

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8}/src/s3dgraphy/sync/graphml_writer.py

@@ -1,7 +1,8 @@
 """Pure-Python wrapper over s3dgraphy.PyArchInitImporter +
 s3dgraphy.exporter.graphml.GraphMLExporter.
 
-Public API:
+Public API::
+
     export_graphml(db_path, mapping, output_path,
                    *, site_filter=None, persist_auxiliary=False) -> ExportResult
 

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8}/src/s3dgraphy/sync/group_projector.py

@@ -1,10 +1,10 @@
 """Pure-functional helpers for AI06 node grouping.
 
-build_groups_from_sql: scan us_table for the requested grouping
-    dimensions, emit one GroupSpec per (dim, value) pair.
-merge_adhoc_groups: append GroupSpec instances from a GroupStore.
-dimensions_with_data: return the subset of 7 grouping columns
-    that have at least one non-empty value in us_table for sito.
+- ``build_groups_from_sql``: scan us_table for the requested grouping
+  dimensions, emit one GroupSpec per (dim, value) pair.
+- ``merge_adhoc_groups``: append GroupSpec instances from a GroupStore.
+- ``dimensions_with_data``: return the subset of 7 grouping columns
+  that have at least one non-empty value in us_table for sito.
 
 UUID generation: deterministic UUID5 from (sito, group_kind, name)
 so re-export with the same SQL state produces identical UUIDs

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8}/src/s3dgraphy/sync/paradata_store.py

@@ -2,9 +2,10 @@
 
 AI05 Phase 2 closure. Manages the 3 node types without an SQL
 counterpart in pyarchinit:
-    - AuthorNode    (authorship metadata)
-    - LicenseNode   (rights / SPDX licence)
-    - EmbargoNode   (embargo dates)
+
+- AuthorNode    (authorship metadata)
+- LicenseNode   (rights / SPDX licence)
+- EmbargoNode   (embargo dates)
 
 File location: {db_path.parent}/paradata_{sito_slug}.graphml
 where sito_slug is `re.sub(r'\\W+', '_', sito).lower()`.

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8}/src/s3dgraphy/sync/rapporti.py

@@ -186,9 +186,41 @@ EDGE_TYPE_DIRECTION_FORWARD: dict[str, bool] = {
 # ---------------------------------------------------------------------------
 # Unit-type frozensets driving the verbose-vs-shorthand dispatch
 # ---------------------------------------------------------------------------
-#: Unit types where both endpoints get the verbose Italian dispatch
-#: ("Copre", "Coperto da", ...). Stratigraphic Harris atoms only.
-CANONICAL_UNIT_TYPES: frozenset[str] = frozenset({"US", "USM"})
+#: Localized US / USM ``unita_tipo`` code → canonical code. pyArchInit
+#: localizes ONLY the US / USM abbreviations per UI language (its
+#: ``pyarchinit_i18n_stratigraphic.UNIT_TYPE_ABBREV`` is the source of
+#: truth). This module is the pyArchInit↔canonical bridge, and the
+#: prefix-strip regex above already enumerates SU|SE|WSU|MSE|UE|…, so the
+#: gating set lives here too. The mapping doubles as the normalization
+#: source: any code path that needs the canonical form calls
+#: :func:`canonical_unita_tipo`. ``attributes['unita_tipo']`` is kept
+#: VERBATIM (original code) elsewhere so round-trip stays byte-identical;
+#: only the verbose/shorthand dispatch and the projector's stratigraphic
+#: gating read through this alias map.
+#:
+#:   US  → US (it/fr/ro) · SU (en/ar) · SE (de) · UE (es/ca/pt) · ΣΜ (el)
+#:   USM → USM (it/fr) · WSU (en/ar) · MSE (de) · UEM (es/ca/pt) ·
+#:         USZ (ro) · ΤΣΜ (el)
+UNITA_TIPO_CANONICAL: dict[str, str] = {
+    "US": "US", "SU": "US", "SE": "US", "UE": "US", "ΣΜ": "US",
+    "USM": "USM", "WSU": "USM", "MSE": "USM", "UEM": "USM",
+    "USZ": "USM", "ΤΣΜ": "USM",
+}
+
+
+def canonical_unita_tipo(unita_tipo) -> str:
+    """Map a (possibly localized) US/USM code to its canonical form.
+
+    Non-US/USM codes (USV*, SF, CON, DOC, …) and unknown values pass
+    through unchanged.
+    """
+    return UNITA_TIPO_CANONICAL.get(unita_tipo, unita_tipo)
+
+
+#: Unit types where both endpoints get the verbose dispatch ("Copre"/
+#: "Covers"/…, "Coperto da"/"Covered by"/…). All language variants of the
+#: Harris US/USM atoms, derived from the alias map so the two never drift.
+CANONICAL_UNIT_TYPES: frozenset[str] = frozenset(UNITA_TIPO_CANONICAL)
 
 
 #: Continuity unit type. Single-arrow shorthand ``>`` / ``<`` is
@@ -464,6 +496,49 @@ def _coerce_to_list(value):
     return []
 
 
+#: Arrow tokens emitted by :func:`select_rapporti_label` for
+#: non-canonical endpoints. When the dispatch returns one of these we do
+#: NOT override it with a verbose row term (virtual units keep ``>>`` /
+#: ``<<``, continuity keeps ``>`` / ``<``).
+_SHORTHAND_TOKENS: frozenset[str] = frozenset({">", "<", ">>", "<<"})
+
+
+def _source_rapporti_label(src_node, target_us: str, edge_type: str):
+    """Original pyArchInit ``rapporti`` term on *src_node* for *target_us*.
+
+    The d13 packed string is wire format that should byte-match the
+    originating ``us_table.rapporti``, so for a verbose relation we anchor
+    the label on the source row's own stored term (in the site's UI
+    language — "Covers" / "Couvre" / "Copre" / …) rather than the canonical
+    Italian. The label language can't be reconstructed from ``edge_type``
+    alone (e.g. "US" is shared by it / fr / ro), so the node's own term is
+    the only reliable source.
+
+    Returned in the canonical display casing (first letter upper, rest
+    lower — the form pyArchInit shows). Matching prefers the entry whose
+    label maps to the SAME canonical ``edge_type`` (disambiguates multiple
+    relations to one target), falling back to any verbose entry pointing at
+    ``target_us``. Returns ``None`` when the node carries no usable
+    ``rapporti`` attribute (e.g. a yEd-imported graph) — the caller then
+    keeps the canonical dispatch label.
+    """
+    attrs = getattr(src_node, "attributes", None) or {}
+    fallback = None
+    for entry in _coerce_to_list(attrs.get("rapporti")):
+        if not isinstance(entry, (list, tuple)) or len(entry) < 2:
+            continue
+        lbl = str(entry[0]).strip()
+        tgt = str(entry[1]).strip()
+        if tgt != str(target_us) or not lbl or lbl in _SHORTHAND_TOKENS:
+            continue
+        lbl = lbl.capitalize()
+        if RAPPORTI_TO_EDGE_TYPE.get(lbl.lower()) == edge_type:
+            return lbl
+        if fallback is None:
+            fallback = lbl
+    return fallback
+
+
 def serialize_rapporti_from_edges(graph, default_sito: str):
     """Walk *graph*'s edges and produce per-US rapporti lists ready
     for the pyarchinit ``us_table.rapporti`` column.
@@ -512,8 +587,6 @@ def serialize_rapporti_from_edges(graph, default_sito: str):
             continue
         src_unita_tipo = resolve_unita_tipo_for_dispatch(src_node)
         tgt_unita_tipo = resolve_unita_tipo_for_dispatch(tgt_node)
-        rapporti_label = select_rapporti_label(
-            et, src_unita_tipo, tgt_unita_tipo)
         tgt_attrs = getattr(tgt_node, "attributes", None) or {}
         tgt_us = tgt_attrs.get("us")
         if not tgt_us:
@@ -521,6 +594,18 @@ def serialize_rapporti_from_edges(graph, default_sito: str):
             if not tgt_name:
                 continue
             tgt_us = strip_us_prefix(str(tgt_name))
+        rapporti_label = select_rapporti_label(
+            et, src_unita_tipo, tgt_unita_tipo)
+        # For a verbose relation (both endpoints real US/USM, any language)
+        # anchor the term on the source row's own rapporti column so the
+        # packed string byte-matches the DB in the site's UI language;
+        # fall back to the canonical label when the source carries no
+        # rapporti attribute (e.g. yEd-imported graphs). Virtual units
+        # (``>>`` / ``<<``) and continuity (``>`` / ``<``) keep shorthand.
+        if rapporti_label not in _SHORTHAND_TOKENS:
+            original = _source_rapporti_label(src_node, str(tgt_us), et)
+            if original:
+                rapporti_label = original
         tgt_area = str(tgt_attrs.get("area") or "1")
         tgt_sito = default_sito
         rapporto = [rapporti_label, str(tgt_us), tgt_area, tgt_sito]
@@ -536,6 +621,8 @@ __all__ = [
     "EDGE_TYPE_TO_RAPPORTI_IT",
     "RAPPORTI_SHORTHAND",
     "EDGE_TYPE_DIRECTION_FORWARD",
+    "UNITA_TIPO_CANONICAL",
+    "canonical_unita_tipo",
     "CANONICAL_UNIT_TYPES",
     "CONTINUITY_UNIT_TYPES",
     "NON_RAPPORTI_EDGE_TYPES",

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8}/src/s3dgraphy/sync/yed_import_pipeline.py

@@ -6,12 +6,12 @@ SQLite and PostgreSQL backends through the `DbHandle` abstraction
 (Foundation 5.6.2-alpha) — all SQL is expressed as SQLAlchemy
 ``text()`` statements with named bind parameters.
 
-Public API:
+Public API::
 
     import_yed_raw(handle, graphml_path, sito, drafts, *,
                    policy=SKIP, dry_run=False) -> IngestResult
 
-Internal helpers (testable in isolation):
+Internal helpers (testable in isolation)::
 
     _classify_destination(classified)
     _flatten_members(folder, all_folders)

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8}/src/s3dgraphy/sync/yed_rapporti_policy.py

@@ -16,7 +16,7 @@ Self-loop folder edges (source == target) are filtered out of ALL
 policies before policy application — they arise from nested folder
 member edges authored in yEd and would otherwise produce noise.
 
-Public API:
+Public API::
 
     FolderEdgePolicy (StrEnum: skip / fan_out / representative / synthetic)
     FolderEdge      (dataclass: src, tgt, src_is_folder, tgt_is_folder, edge_type)
@@ -26,6 +26,7 @@ Public API:
     apply_policy(report, policy, *, all_folders, classified) -> ExpandedRapporti
 
 Implementation notes:
+
 * `analyze_edges` parses <edge> elements via lxml (falling back to
   stdlib `xml.etree.ElementTree`) and classifies each endpoint as a
   folder or a leaf based on the dataclass lookups passed in.

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8}/src/s3dgraphy/sync/yed_table_parser.py

@@ -3,11 +3,12 @@
 Reads the top-level <y:TableNode configuration="YED_TABLE_NODE"> of a
 yEd-raw graphml and extracts archaeological period candidates from
 its swimlane rows. Each row produces a PeriodCandidate with:
-  - auto_label from <y:NodeLabel> text
-  - auto_periodo from 1-based row ordinal
-  - auto_fase always 1 (yEd table rows don't encode phases)
-  - member_yed_ids from leaf nodes whose Y-coordinate falls in the
-    row's Y-range
+
+- auto_label from <y:NodeLabel> text
+- auto_periodo from 1-based row ordinal
+- auto_fase always 1 (yEd table rows don't encode phases)
+- member_yed_ids from leaf nodes whose Y-coordinate falls in the
+  row's Y-range
 
 datazione_iniziale / datazione_finale are NOT extracted (yEd doesn't
 encode dates on table rows) — user fills them later in the

{s3dgraphy-1.6.0.dev7 → s3dgraphy-1.6.0.dev8/src/s3dgraphy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev7
+Version: 1.6.0.dev8
 Summary: 3D Stratigraphic Graph Management Library for archaeological and heritage applications
 Author-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
 Maintainer-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
@@ -97,30 +97,47 @@ pip install s3dgraphy[full]          # All optional dependencies
 ## 🔧 Quick Start
 
 ```python
-import s3dgraphy
+from s3dgraphy import Graph
+from s3dgraphy.nodes import StratigraphicUnit, DocumentNode
 
-# Create a new stratigraphic graph
-graph = s3dgraphy.Graph()
+# Create a new stratigraphic graph (graph_id is required)
+graph = Graph("my_excavation")
 
-# Add stratigraphic units
-us1 = graph.add_node("US001", node_type="US", 
-                     properties={"period": "Roman", "material": "pottery"})
-us2 = graph.add_node("US002", node_type="US", 
-                     properties={"period": "Medieval", "material": "stone"})
+# Build node objects, then add them with add_node()
+wall = StratigraphicUnit("US001", name="US001", description="Stone wall foundation")
+floor = StratigraphicUnit("US002", name="US002", description="Mosaic floor")
+graph.add_node(wall)
+graph.add_node(floor)
 
-# Add stratigraphic relationships
-graph.add_edge(us1, us2, edge_type="ABOVE", 
-               properties={"certainty": "high"})
+# Add a stratigraphic relationship.
+# Canonical direction is recent -> ancient: the floor (US002) is more
+# recent than the wall (US001), so US002 is_after US001.
+graph.add_edge("e1", "US002", "US001", "is_after")
+
+# Attach documentation
+doc = DocumentNode("DOC001", name="DOC001", description="Field photo")
+graph.add_node(doc)
+graph.add_edge("e2", "US001", "DOC001", "has_documentation")
 
 # Query the graph
-print(f"Graph contains {len(graph.nodes)} stratigraphic units")
-print(f"Relationships: {len(graph.edges)}")
+print(f"Graph contains {len(graph.nodes)} nodes and {len(graph.edges)} edges")
+us_units = graph.get_nodes_by_type("US")
 
-# Export to different formats
-graph.export_graphml("stratigraphy.graphml")
-graph.export_json("stratigraphy.json")
+# Export to GraphML (yEd round-trip) — the exporter takes the graph directly
+from s3dgraphy.exporter.graphml import GraphMLExporter
+GraphMLExporter(graph).export("my_excavation.graphml")
 ```
 
+> **Note on the API.** Nodes are *objects* (`StratigraphicUnit`,
+> `DocumentNode`, …) created first and then added with `graph.add_node()`.
+> Edges are created with `graph.add_edge(edge_id, source_id, target_id,
+> edge_type)` using a **canonical** edge type from the connections
+> datamodel (e.g. `is_after`, `has_property`, `has_documentation`). Invalid
+> connections are downgraded to `generic_connection` with a warning rather
+> than silently accepted. See the
+> [API reference](https://docs.extendedmatrix.org/projects/s3dgraphy/) for
+> the full node and edge catalogs.
+
 ## 📚 Core Features
 
 ### 🏛️ Archaeological Stratigraphic Modeling
@@ -328,12 +345,12 @@ The GPL-3.0 license ensures that s3dgraphy remains free and open source, promoti
 If you use s3dgraphy in your research, please cite:
 
 ```bibtex
-@software{s3dgraphy2024,
+@software{s3dgraphy,
   title={s3dgraphy: 3D Stratigraphic Graph Management Library},
   author={Demetrescu, Emanuel},
-  year={2024},
+  year={2026},
   url={https://github.com/zalmoxes-laran/s3dgraphy},
-  version={0.1.1},
+  version={1.6.0},
   institution={CNR-ISPC (National Research Council - Institute of Heritage Science)}
 }
 ```