s3dgraphy 1.6.0.dev45__tar.gz → 1.6.0.dev46__tar.gz

{s3dgraphy-1.6.0.dev45/src/s3dgraphy.egg-info → s3dgraphy-1.6.0.dev46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev45
+Version: 1.6.0.dev46
 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>

{s3dgraphy-1.6.0.dev45 → s3dgraphy-1.6.0.dev46}/pyproject.toml

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

{s3dgraphy-1.6.0.dev45 → s3dgraphy-1.6.0.dev46}/src/s3dgraphy/__init__.py

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

{s3dgraphy-1.6.0.dev45 → s3dgraphy-1.6.0.dev46}/src/s3dgraphy/api.py

@@ -322,6 +322,15 @@ def is_spatiotemporal(node) -> bool:
     return _is(node)
 
 
+def entity_epoch(graph: Graph, node_id: str) -> Optional[str]:
+    """The epoch an entity stands in: the narrowest holding its own date (start,
+    else end), else its ``has_first_epoch``, else the nearest to its date
+    (MICRO autori nel tempo, 11 Oct 2026). See
+    :func:`s3dgraphy.spatiotemporal.entity_epoch`."""
+    from .spatiotemporal import entity_epoch as _epoch
+    return _epoch(graph, node_id)
+
+
 def view_instances(graph: Graph, group_id: str) -> List[Dict[str, Any]]:
     """The instances a client draws inside the paradata group ``group_id``:
     every master (document or property) outside the group that a reader of the

{s3dgraphy-1.6.0.dev45 → s3dgraphy-1.6.0.dev46}/src/s3dgraphy/paradata_view.py

@@ -18,8 +18,9 @@ The rule, for a ``ParadataNodeGroup`` G:
   property, or the document an annotation region is on — that is NOT itself a
   member of G is drawn as an instance inside G;
 * the instance carries the badge of where the master comes from: the unit that
-  owns the property (its original owner), the epoch where the document is born
-  (``has_first_epoch``).
+  owns the property (its original owner), the epoch where the document or the
+  author stands — the one of its own date, else its ``has_first_epoch``
+  (:func:`s3dgraphy.spatiotemporal.entity_epoch`, 11 Oct 2026).
 
 A unit read as a source (connections 1.6.24) is not a master of this rule: a
 unit is drawn in the matrix, not in a group. Removed nodes (a CRDT tombstone, a
@@ -77,6 +78,12 @@ def _badge(graph, master, spec: Dict[str, Any]) -> Optional[str]:
     if via == "has_property":
         from .ownership import original_owner
         return original_owner(graph, master.node_id)
+    if via == "has_first_epoch":
+        # MICRO autori nel tempo (E.D., 11 Oct 2026): the epoch a document or an
+        # author stands in is the one of its own date, else its has_first_epoch
+        # (spatiotemporal.entity_epoch, the lane every client draws it in)
+        from .spatiotemporal import entity_epoch
+        return entity_epoch(graph, master.node_id)
     if via:
         for e in graph.edges:
             if e.edge_source == master.node_id and e.edge_type == via and _live(e):

{s3dgraphy-1.6.0.dev45 → s3dgraphy-1.6.0.dev46}/src/s3dgraphy/spatiotemporal.py

@@ -99,6 +99,88 @@ def spatiotemporal_profile(graph: Any, node_id: str, *,
     }
 
 
+def _year(value: Any) -> Optional[float]:
+    """The year a written value says: a number, or the leading year of a date
+    («2021-09-28» → 2021); ``None`` when it says none."""
+    if value is None or value == "":
+        return None
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value)
+    import re
+    m = re.match(r"\s*(-?\d+(?:\.\d+)?)", str(value))
+    return float(m.group(1)) if m else None
+
+
+def own_year(graph: Any, node: Any) -> Tuple[Optional[float], Optional[str]]:
+    """The year an entity's OWN date says, and which one: its
+    ``absolute_time_start`` (the property — value, else description — else the
+    node's own ``absolute_time_start`` field), else its ``absolute_time_end``
+    the same way. ``(None, None)`` when it has no date of its own."""
+    attrs = getattr(node, "attributes", None) or {}
+    data = getattr(node, "data", None) or {}
+    for quale in ("absolute_time_start", "absolute_time_end"):
+        for e in graph.edges:
+            if e.edge_source != node.node_id or e.edge_type != "has_property":
+                continue
+            p = graph.find_node_by_id(e.edge_target)
+            if p is None or getattr(p, "node_type", None) != "property":
+                continue
+            if getattr(p, "property_type", None) != quale and getattr(p, "name", None) != quale:
+                continue
+            y = _year(getattr(p, "value", None))
+            if y is None:
+                y = _year(getattr(p, "description", None))
+            if y is None:
+                y = _year((getattr(p, "attributes", None) or {}).get("value"))
+            if y is not None:
+                return y, quale
+        for holder in (attrs, data):
+            y = _year(holder.get(quale)) if isinstance(holder, dict) else None
+            if y is not None:
+                return y, quale
+        y = _year(getattr(node, quale, None))
+        if y is not None:
+            return y, quale
+    return None, None
+
+
+def entity_epoch(graph: Any, node_id: str) -> Optional[str]:
+    """The epoch an entity stands in (MICRO autori nel tempo, E.D. 11 Oct 2026:
+    «il master sta nell'epoca della sua data»), the rule every client draws the
+    lanes with (EMStudio's em-core ``layout.rs``):
+
+    1. its own date (:func:`own_year`: the start, else the end) in the
+       NARROWEST epoch whose bounds hold it;
+    2. else its ``has_first_epoch``;
+    3. else, when it has a date outside every epoch, the NEAREST epoch to it
+       (Alexandru Diaconescu, scomparso nel 2021, with «XX sec» ending in 2013).
+
+    ``None`` for an unknown id, an epoch, or an entity with neither a date nor
+    a declared epoch."""
+    node = graph.find_node_by_id(node_id)
+    if node is None or getattr(node, "node_type", None) in ("EpochNode", "epoch"):
+        return None
+    bounds = []
+    for n in graph.nodes:
+        if getattr(n, "node_type", None) not in ("EpochNode", "epoch"):
+            continue
+        a, b = _year(getattr(n, "start_time", None)), _year(getattr(n, "end_time", None))
+        if a is None or b is None:
+            continue
+        bounds.append((n.node_id, min(a, b), max(a, b)))
+    year, _ = own_year(graph, node)
+    if year is not None:
+        holding = [b for b in bounds if b[1] <= year <= b[2]]
+        if holding:
+            return min(holding, key=lambda b: b[2] - b[1])[0]
+    for e in graph.edges:
+        if e.edge_source == node_id and e.edge_type == "has_first_epoch":
+            return e.edge_target
+    if year is not None and bounds:
+        return min(bounds, key=lambda b: (min(abs(year - b[1]), abs(year - b[2])), b[2] - b[1]))[0]
+    return None
+
+
 def time_label(quale_id: str, owner: Any, lang: str = "en") -> Optional[str]:
     """The label of ``absolute_time_start`` / ``absolute_time_end`` (or any
     quale) on this owner: «Data di scomparsa» for an author's end, «Data di

{s3dgraphy-1.6.0.dev45 → s3dgraphy-1.6.0.dev46/src/s3dgraphy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev45
+Version: 1.6.0.dev46
 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>

{s3dgraphy-1.6.0.dev45 → s3dgraphy-1.6.0.dev46}/tests/test_spatiotemporal_entities.py

@@ -241,6 +241,68 @@ def test_the_instance_writes_nothing():
     assert (len(g.nodes), len(g.edges)) == before
 
 
+# ── 5b · the master in the epoch of its date (E.D., 11 Oct 2026) ──────────────
+# «Un autore ha un master che sta nell'epoca della sua data: absolute_time_start
+# se c'è, altrimenti absolute_time_end, altrimenti has_first_epoch.»
+
+def _diaconescu(start=None, end="2021", declared=None):
+    g = Graph(graph_id="tm")
+    g.add_node(EpochNode("EP_ROM", "II A.D.", start_time=100, end_time=199))
+    g.add_node(EpochNode("EP_POST", "Post antiquity", start_time=200, end_time=1800))
+    g.add_node(EpochNode("EP_XX", "XX sec", start_time=1801, end_time=2013))
+    g.add_node(AuthorNode("AD", name="Alexandru Diaconescu", first_name="Alexandru",
+                          surname="Diaconescu"))
+    for pid, ptype, value in (("P_S", "absolute_time_start", start),
+                              ("P_E", "absolute_time_end", end)):
+        if value is None:
+            continue
+        g.add_node(PropertyNode(node_id=pid, name=ptype, property_type=ptype,
+                                value=value, description=""))
+        g.add_edge(f"hp_{pid}", "AD", pid, "has_property")
+    if declared:
+        g.add_edge("ep", "AD", declared, "has_first_epoch")
+    return g
+
+
+def test_the_start_decides_the_epoch():
+    assert api.entity_epoch(_diaconescu(start="1950"), "AD") == "EP_XX"
+
+
+def test_without_a_start_the_end_decides():
+    assert api.entity_epoch(_diaconescu(end="1700"), "AD") == "EP_POST"
+
+
+def test_a_date_beats_the_declared_epoch():
+    assert api.entity_epoch(_diaconescu(start="150", declared="EP_XX"), "AD") == "EP_ROM"
+
+
+def test_a_date_out_of_every_epoch_keeps_the_declared_one():
+    assert api.entity_epoch(_diaconescu(end="2021", declared="EP_POST"), "AD") == "EP_POST"
+
+
+def test_a_date_out_of_every_epoch_without_one_goes_to_the_nearest():
+    """Templu Mare: Diaconescu passed away in 2021, «XX sec» ends in 2013."""
+    assert api.entity_epoch(_diaconescu(end="2021-09-28"), "AD") == "EP_XX"
+
+
+def test_no_date_and_no_epoch_is_nowhere():
+    assert api.entity_epoch(_diaconescu(end=None), "AD") is None
+    assert api.entity_epoch(_diaconescu(end=None, declared="EP_ROM"), "AD") == "EP_ROM"
+    assert api.entity_epoch(_diaconescu(), "EP_XX") is None
+    assert api.entity_epoch(_diaconescu(), "nope") is None
+
+
+def test_the_instance_badge_is_the_epoch_of_the_date():
+    g = _diaconescu(end="2021")
+    g.add_node(ParadataNodeGroup("PD", "USV104_PD"))
+    g.add_node(ExtractorNode("X1", "D.05.05", description="modulo di 15 piedi"))
+    g.add_edge("x2", "X1", "AD", "has_author")
+    g.add_edge("m1", "X1", "PD", "is_in_paradata_nodegroup")
+    (a,) = api.view_instances(g, "PD")
+    assert (a["kind"], a["owner"], a["owner_kind"], a["owner_name"]) == \
+        ("author", "EP_XX", "epoch", "XX sec")
+
+
 # ── 6 · the round trip ───────────────────────────────────────────────────────
 
 def test_an_author_with_a_life_survives_em_json(tmp_path):