arango-query-core 0.2.5__tar.gz → 0.2.6__tar.gz

{arango_query_core-0.2.5 → arango_query_core-0.2.6}/CHANGELOG.md

@@ -6,6 +6,19 @@ exact versions (contextual-data-fabric CC-9) and re-run their golden /
 eval suites on every bump — pre-1.0, **minor** bumps may break the API
 and this file must say so explicitly.
 
+## [0.2.6] - 2026-10-29
+
+### Added
+
+- **Temporal property encodings.** A property may declare how its temporal
+  values are stored, `"encoding": "epoch_ms"` (integer milliseconds since the
+  epoch) or `"iso8601"` (an ISO-8601 string), read into
+  `PropertyInfo.encoding` (empty when not declared) and carried by
+  `schema_summary()`. Any other value is refused with `INVALID_MAPPING`.
+  The vocabulary is `TEMPORAL_ENCODINGS`. It is a physical detail, like
+  `field`, so OWL/Turtle does not carry it. arango-cypher-py lowers temporal
+  accessors, functions and arithmetic from it (LDBC WP-41).
+
 ## [0.2.5] - 2026-10-26
 
 ### Added

{arango_query_core-0.2.5 → arango_query_core-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: arango-query-core
-Version: 0.2.5
+Version: 0.2.6
 Summary: Shared conceptual-model and NL substrate for ArangoDB query transpilers (arango-cypher-py, arango-sparql-py)
 Project-URL: Repository, https://github.com/ArthurKeen/arango-query-core
 Project-URL: Changelog, https://github.com/ArthurKeen/arango-query-core/blob/main/CHANGELOG.md

{arango_query_core-0.2.5 → arango_query_core-0.2.6}/arango_query_core/__init__.py

@@ -5,6 +5,7 @@ from .extensions import ExtensionPolicy, ExtensionRegistry
 from .mapping import (
     COLLECTION_NAME_RE,
     SUPERTYPE_STYLES,
+    TEMPORAL_ENCODINGS,
     IndexInfo,
     MappingBundle,
     MappingResolver,
@@ -25,6 +26,7 @@ except ImportError:
 __all__ = [
     "COLLECTION_NAME_RE",
     "SUPERTYPE_STYLES",
+    "TEMPORAL_ENCODINGS",
     "AqlExecutor",
     "AqlFragment",
     "AqlQuery",

{arango_query_core-0.2.5 → arango_query_core-0.2.6}/arango_query_core/mapping.py

@@ -163,6 +163,14 @@ class IndexInfo:
     traversal_safe: bool = True
 
 
+#: Storage encodings of temporal property values.
+#:
+#: * ``epoch_ms`` — an integer, milliseconds since 1970-01-01T00:00:00Z.
+#: * ``iso8601`` — an ISO-8601 string (``2010-01-03T15:10:31.499+00:00``,
+#:   or ``2010-01-03`` for a date).
+TEMPORAL_ENCODINGS = frozenset({"epoch_ms", "iso8601"})
+
+
 @dataclass(frozen=True)
 class PropertyInfo:
     """Metadata for a single property/attribute on an entity or relationship.
@@ -187,6 +195,25 @@ class PropertyInfo:
     # / numeric / free_text / boolean / other), inferred by the schema analyzer.
     # Consumers choose a matching strategy from this rather than field names.
     role: str = ""
+    # How a temporal value (``type`` date / datetime / …) is stored: one of
+    # ``TEMPORAL_ENCODINGS``, or empty when the mapping does not say.
+    # Consumers must not guess an encoding: comparisons, components
+    # (``.year``) and arithmetic differ between the two.
+    encoding: str = ""
+
+
+def _property_encoding(owner: str, name: str, raw: Any) -> str:
+    """A property's declared ``encoding``, checked against ``TEMPORAL_ENCODINGS``."""
+    if raw in (None, ""):
+        return ""
+    encoding = str(raw)
+    if encoding not in TEMPORAL_ENCODINGS:
+        raise CoreError(
+            f"Property {owner}.{name} declares encoding {encoding!r}; expected one of "
+            f"{', '.join(sorted(TEMPORAL_ENCODINGS))}",
+            code="INVALID_MAPPING",
+        )
+    return encoding
 
 
 @dataclass(frozen=True)
@@ -438,6 +465,7 @@ class MappingResolver:
                     numeric_like=bool(meta.get("numericLike") or meta.get("numeric_like")),
                     sample_values=tuple(str(s) for s in samples) if samples else (),
                     role=str(meta.get("role") or ""),
+                    encoding=_property_encoding(label_or_type, name, meta.get("encoding")),
                 )
             elif isinstance(meta, str):
                 result[name] = PropertyInfo(field=name, type=meta)
@@ -797,6 +825,7 @@ class MappingResolver:
                         **({"numericLike": True} if p.numeric_like else {}),
                         **({"sampleValues": list(p.sample_values)} if p.sample_values else {}),
                         **({"role": p.role} if p.role else {}),
+                        **({"encoding": p.encoding} if p.encoding else {}),
                     }
                     for name, p in props.items()
                 },
@@ -831,6 +860,7 @@ class MappingResolver:
                         **({"numericLike": True} if p.numeric_like else {}),
                         **({"sampleValues": list(p.sample_values)} if p.sample_values else {}),
                         **({"role": p.role} if p.role else {}),
+                        **({"encoding": p.encoding} if p.encoding else {}),
                     }
                     for name, p in props.items()
                 },

{arango_query_core-0.2.5 → arango_query_core-0.2.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arango-query-core"
-version = "0.2.5"
+version = "0.2.6"
 description = "Shared conceptual-model and NL substrate for ArangoDB query transpilers (arango-cypher-py, arango-sparql-py)"
 readme = "README.md"
 license = { file = "LICENSE" }

arango_query_core-0.2.6/tests/test_mapping_property_encoding.py

@@ -0,0 +1,74 @@
+"""Temporal property encodings: ``PropertyInfo.encoding``."""
+
+from __future__ import annotations
+
+import pytest
+
+from arango_query_core import TEMPORAL_ENCODINGS, CoreError, MappingBundle, MappingResolver
+
+
+def _resolver(properties: dict, rel_properties: dict | None = None) -> MappingResolver:
+    return MappingResolver(
+        MappingBundle(
+            conceptual_schema={"entities": [], "relationships": []},
+            physical_mapping={
+                "entities": {
+                    "Post": {"collectionName": "post", "style": "COLLECTION", "properties": properties},
+                    "Person": {"collectionName": "person", "style": "COLLECTION", "properties": {}},
+                },
+                "relationships": {
+                    "KNOWS": {
+                        "edgeCollectionName": "knows",
+                        "style": "DEDICATED_COLLECTION",
+                        "domain": "Person",
+                        "range": "Person",
+                        "properties": rel_properties or {},
+                    }
+                },
+            },
+            metadata={},
+        )
+    )
+
+
+def test_the_vocabulary() -> None:
+    assert frozenset({"epoch_ms", "iso8601"}) == TEMPORAL_ENCODINGS
+
+
+def test_a_declared_encoding_is_read_for_entities_and_relationships() -> None:
+    resolver = _resolver(
+        {"creationDate": {"type": "datetime", "encoding": "epoch_ms"}},
+        {"creationDate": {"type": "datetime", "encoding": "iso8601"}},
+    )
+    assert resolver.resolve_properties("Post")["creationDate"].encoding == "epoch_ms"
+    assert resolver.resolve_properties("KNOWS")["creationDate"].encoding == "iso8601"
+
+
+def test_no_declaration_means_unknown() -> None:
+    props = _resolver({"creationDate": {"type": "datetime"}, "title": "string", "id": None})
+    infos = props.resolve_properties("Post")
+    assert {name: info.encoding for name, info in infos.items()} == {
+        "creationDate": "",
+        "title": "",
+        "id": "",
+    }
+
+
+@pytest.mark.parametrize("bad", ["epochMillis", "ISO8601", "seconds", 13])
+def test_an_unknown_encoding_is_an_invalid_mapping(bad: object) -> None:
+    resolver = _resolver({"creationDate": {"type": "datetime", "encoding": bad}})
+    with pytest.raises(CoreError, match="Post.creationDate declares encoding") as err:
+        resolver.resolve_properties("Post")
+    assert err.value.code == "INVALID_MAPPING"
+
+
+def test_the_schema_summary_carries_the_encoding_when_declared() -> None:
+    summary = _resolver(
+        {"creationDate": {"type": "datetime", "encoding": "iso8601"}, "title": {"type": "string"}},
+        {"creationDate": {"type": "datetime", "encoding": "epoch_ms"}},
+    ).schema_summary()
+    post = next(e for e in summary["entities"] if e["label"] == "Post")
+    assert post["properties"]["creationDate"]["encoding"] == "iso8601"
+    assert "encoding" not in post["properties"]["title"]
+    knows = next(r for r in summary["relationships"] if r["type"] == "KNOWS")
+    assert knows["properties"]["creationDate"]["encoding"] == "epoch_ms"