prograph 1.3.3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (237) hide show
  1. prograph/__init__.py +36 -0
  2. prograph/__main__.py +5 -0
  3. prograph/_version.py +375 -0
  4. prograph/cli/__init__.py +1 -0
  5. prograph/cli/_iri_utils.py +124 -0
  6. prograph/cli/emit_genie_space.py +107 -0
  7. prograph/cli/generate_views.py +140 -0
  8. prograph/cli/main.py +420 -0
  9. prograph/cli/schema_inferrer.py +746 -0
  10. prograph/cli/ttl_loader.py +289 -0
  11. prograph/cli/upload_genie_space.py +84 -0
  12. prograph/config/__init__.py +27 -0
  13. prograph/config/yaml_config.py +848 -0
  14. prograph/demos/__init__.py +14 -0
  15. prograph/demos/turbofan/README.md +74 -0
  16. prograph/demos/turbofan/SCENARIO.md +209 -0
  17. prograph/demos/turbofan/__init__.py +75 -0
  18. prograph/demos/turbofan/create_tables.sql +206 -0
  19. prograph/demos/turbofan/data/engine-instances.ttl +1123 -0
  20. prograph/demos/turbofan/data/sensor-timeseries.csv +90 -0
  21. prograph/demos/turbofan/demo.py +162 -0
  22. prograph/demos/turbofan/genie_qa_notebook.py +434 -0
  23. prograph/demos/turbofan/graph.yaml +1098 -0
  24. prograph/demos/turbofan/instance_graph_demo.py +32 -0
  25. prograph/demos/turbofan/load.py +223 -0
  26. prograph/demos/turbofan/mapping.r2rml.ttl +991 -0
  27. prograph/demos/turbofan/ontology/engine-maintenance.ttl +606 -0
  28. prograph/demos/turbofan/payload-shapes.ttl +33 -0
  29. prograph/demos/turbofan/queries/example-queries.sparql +215 -0
  30. prograph/demos/turbofan/shapes.ttl +75 -0
  31. prograph/demos/turbofan/tables.py +106 -0
  32. prograph/demos/turbofan/turbofan_schema.py +393 -0
  33. prograph/demos/turbofan/validation_demo.py +153 -0
  34. prograph/describe.py +231 -0
  35. prograph/endpoint/__init__.py +12 -0
  36. prograph/endpoint/app.py +722 -0
  37. prograph/endpoint/cli.py +280 -0
  38. prograph/endpoint/credentials.py +240 -0
  39. prograph/endpoint/engines.py +418 -0
  40. prograph/endpoint/negotiate.py +101 -0
  41. prograph/endpoint/results.py +181 -0
  42. prograph/endpoint/service.py +31 -0
  43. prograph/engine.py +2718 -0
  44. prograph/execution.py +455 -0
  45. prograph/executors/__init__.py +6 -0
  46. prograph/executors/base.py +11 -0
  47. prograph/executors/databricks_sql_executor.py +51 -0
  48. prograph/executors/duckdb_executor.py +24 -0
  49. prograph/executors/mysql_executor.py +20 -0
  50. prograph/executors/oracle_executor.py +24 -0
  51. prograph/executors/pandas_executor.py +72 -0
  52. prograph/executors/postgresql_executor.py +35 -0
  53. prograph/executors/spark_executor.py +88 -0
  54. prograph/executors/sqlserver_executor.py +35 -0
  55. prograph/extras/__init__.py +1 -0
  56. prograph/extras/graphql/__init__.py +33 -0
  57. prograph/extras/graphql/execute.py +25 -0
  58. prograph/extras/graphql/schema.py +314 -0
  59. prograph/extras/instance_graph.py +559 -0
  60. prograph/genie/__init__.py +83 -0
  61. prograph/genie/databricks_uploader.py +306 -0
  62. prograph/genie/deploy.py +393 -0
  63. prograph/genie/formats.py +414 -0
  64. prograph/genie/instruction_generator.py +375 -0
  65. prograph/genie/sample_query_generator.py +256 -0
  66. prograph/genie/shacl_views.py +318 -0
  67. prograph/genie/space_emitter.py +329 -0
  68. prograph/genie/view_generator.py +628 -0
  69. prograph/genie/view_writer.py +172 -0
  70. prograph/graph/__init__.py +1 -0
  71. prograph/graph/ansi_session.py +348 -0
  72. prograph/graph/databricks_sql_graph.py +300 -0
  73. prograph/graph/drivers.py +143 -0
  74. prograph/graph/duckdb_graph.py +68 -0
  75. prograph/graph/mysql_graph.py +38 -0
  76. prograph/graph/oracle_graph.py +285 -0
  77. prograph/graph/pandas_graph.py +343 -0
  78. prograph/graph/postgresql_graph.py +644 -0
  79. prograph/graph/spark_graph.py +556 -0
  80. prograph/graph/sql_graph.py +83 -0
  81. prograph/graph/sqlserver_graph.py +72 -0
  82. prograph/hints.py +95 -0
  83. prograph/logging.py +550 -0
  84. prograph/mcp/__init__.py +29 -0
  85. prograph/mcp/__main__.py +180 -0
  86. prograph/mcp/bootstrap.py +98 -0
  87. prograph/mcp/server.py +601 -0
  88. prograph/mcp/sparql.py +397 -0
  89. prograph/mcp/tools.py +504 -0
  90. prograph/nlp/__init__.py +79 -0
  91. prograph/nlp/client.py +305 -0
  92. prograph/nlp/databricks_tools.py +369 -0
  93. prograph/nlp/graph_context.py +313 -0
  94. prograph/nlp/interface.py +652 -0
  95. prograph/nlp/prompts/__init__.py +19 -0
  96. prograph/nlp/prompts/examples.py +258 -0
  97. prograph/nlp/prompts/system.py +239 -0
  98. prograph/nlp/providers/__init__.py +14 -0
  99. prograph/nlp/providers/anthropic.py +274 -0
  100. prograph/nlp/providers/databricks.py +312 -0
  101. prograph/nlp/providers/openai.py +203 -0
  102. prograph/nlp/schema_context.py +78 -0
  103. prograph/ontology/__init__.py +53 -0
  104. prograph/ontology/alignment.py +542 -0
  105. prograph/ontology/hierarchy.py +310 -0
  106. prograph/ontology/imports.py +587 -0
  107. prograph/ontology/layer.py +991 -0
  108. prograph/ontology/skos.py +61 -0
  109. prograph/owl/__init__.py +27 -0
  110. prograph/owl/defined_classes.py +323 -0
  111. prograph/parameters.py +242 -0
  112. prograph/parser/__init__.py +1 -0
  113. prograph/parser/cypher/CypherLexer.py +836 -0
  114. prograph/parser/cypher/CypherListener.py +966 -0
  115. prograph/parser/cypher/CypherParser.py +10854 -0
  116. prograph/parser/cypher/CypherVisitor.py +543 -0
  117. prograph/parser/cypher/__init__.py +1 -0
  118. prograph/parser/sparql/SparqlLexer.py +801 -0
  119. prograph/parser/sparql/SparqlParser.py +10146 -0
  120. prograph/parser/sparql/SparqlParserListener.py +1056 -0
  121. prograph/parser/sparql/SparqlParserVisitor.py +593 -0
  122. prograph/parser/sparql/__init__.py +8 -0
  123. prograph/plan/__init__.py +3 -0
  124. prograph/plan/ir/__init__.py +1 -0
  125. prograph/plan/ir/casts.py +338 -0
  126. prograph/plan/ir/consistency.py +397 -0
  127. prograph/plan/ir/construct.py +90 -0
  128. prograph/plan/ir/cost.py +234 -0
  129. prograph/plan/ir/cypher_answer.py +1081 -0
  130. prograph/plan/ir/cypher_apoc.py +717 -0
  131. prograph/plan/ir/cypher_apoc_convert.py +505 -0
  132. prograph/plan/ir/cypher_apoc_date.py +845 -0
  133. prograph/plan/ir/cypher_apoc_map.py +496 -0
  134. prograph/plan/ir/cypher_apoc_meta.py +384 -0
  135. prograph/plan/ir/cypher_apoc_path.py +597 -0
  136. prograph/plan/ir/cypher_apoc_procedures.py +163 -0
  137. prograph/plan/ir/cypher_apoc_text.py +785 -0
  138. prograph/plan/ir/cypher_front.py +5474 -0
  139. prograph/plan/ir/cypher_functions.py +565 -0
  140. prograph/plan/ir/cypher_lists.py +935 -0
  141. prograph/plan/ir/cypher_maps.py +370 -0
  142. prograph/plan/ir/cypher_mixed.py +604 -0
  143. prograph/plan/ir/cypher_ontology.py +226 -0
  144. prograph/plan/ir/cypher_procedures.py +191 -0
  145. prograph/plan/ir/cypher_runtime_errors.py +107 -0
  146. prograph/plan/ir/cypher_temporal.py +1357 -0
  147. prograph/plan/ir/cypher_temporal_arith.py +339 -0
  148. prograph/plan/ir/cypher_values.py +546 -0
  149. prograph/plan/ir/cypher_write.py +612 -0
  150. prograph/plan/ir/dataset.py +643 -0
  151. prograph/plan/ir/dates.py +102 -0
  152. prograph/plan/ir/entry.py +992 -0
  153. prograph/plan/ir/expr.py +260 -0
  154. prograph/plan/ir/facts.py +1171 -0
  155. prograph/plan/ir/fresh.py +291 -0
  156. prograph/plan/ir/freshness.py +625 -0
  157. prograph/plan/ir/identity.py +797 -0
  158. prograph/plan/ir/java_datetime.py +265 -0
  159. prograph/plan/ir/java_regex.py +391 -0
  160. prograph/plan/ir/join_order.py +39 -0
  161. prograph/plan/ir/key_checks.py +433 -0
  162. prograph/plan/ir/keys.py +454 -0
  163. prograph/plan/ir/lower.py +5323 -0
  164. prograph/plan/ir/ops.py +619 -0
  165. prograph/plan/ir/owl_rl.py +1119 -0
  166. prograph/plan/ir/owl_rl_rules.py +725 -0
  167. prograph/plan/ir/profiles.py +694 -0
  168. prograph/plan/ir/ql.py +987 -0
  169. prograph/plan/ir/rdfs.py +342 -0
  170. prograph/plan/ir/rewrite.py +1782 -0
  171. prograph/plan/ir/saturate.py +339 -0
  172. prograph/plan/ir/semantics.py +103 -0
  173. prograph/plan/ir/slot.py +509 -0
  174. prograph/plan/ir/sparql_front.py +3418 -0
  175. prograph/plan/ir/strings.py +534 -0
  176. prograph/plan/ir/term_functions.py +274 -0
  177. prograph/plan/ir/terms.py +84 -0
  178. prograph/plan/ir/xpath_regex.py +264 -0
  179. prograph/plan/run_record.py +65 -0
  180. prograph/plan/sql/__init__.py +21 -0
  181. prograph/plan/sql/dialect.py +3726 -0
  182. prograph/plan/sql/mysql_serializer.py +103 -0
  183. prograph/plan/sql/names.py +65 -0
  184. prograph/plan/sql/oracle_serializer.py +306 -0
  185. prograph/plan/sql/pg_serializer.py +501 -0
  186. prograph/plan/sql/rel_algebra.py +781 -0
  187. prograph/plan/sql/sql_serializer.py +1419 -0
  188. prograph/plan/sql/sqlserver_serializer.py +603 -0
  189. prograph/provenance.py +222 -0
  190. prograph/r2rml/__init__.py +48 -0
  191. prograph/r2rml/catalog.py +259 -0
  192. prograph/r2rml/compile.py +372 -0
  193. prograph/r2rml/direct.py +140 -0
  194. prograph/r2rml/export.py +495 -0
  195. prograph/r2rml/model.py +180 -0
  196. prograph/r2rml/parser.py +546 -0
  197. prograph/r2rml/schema.py +120 -0
  198. prograph/read_only.py +122 -0
  199. prograph/results.py +157 -0
  200. prograph/rules/__init__.py +168 -0
  201. prograph/rules/__main__.py +32 -0
  202. prograph/schema/__init__.py +60 -0
  203. prograph/schema/change_set.py +50 -0
  204. prograph/schema/collations.py +198 -0
  205. prograph/schema/compile_schema.py +388 -0
  206. prograph/schema/context.py +845 -0
  207. prograph/schema/examples.py +234 -0
  208. prograph/schema/iri.py +817 -0
  209. prograph/schema/literals.py +94 -0
  210. prograph/schema/lpg_view.py +617 -0
  211. prograph/schema/mapping.py +1803 -0
  212. prograph/schema/maps_schema.py +40 -0
  213. prograph/schema/naming.py +77 -0
  214. prograph/schema/query_sources.py +59 -0
  215. prograph/schema/rows.py +215 -0
  216. prograph/schema/source_map.py +1103 -0
  217. prograph/schema/store_view.py +459 -0
  218. prograph/schema/types.py +569 -0
  219. prograph/schema/xsd.py +569 -0
  220. prograph/shacl/__init__.py +30 -0
  221. prograph/shacl/dqv.py +58 -0
  222. prograph/shacl/generate.py +255 -0
  223. prograph/shacl/report.py +138 -0
  224. prograph/shacl/validator.py +164 -0
  225. prograph/store.py +1737 -0
  226. prograph/utils/__init__.py +6 -0
  227. prograph/utils/exceptions.py +308 -0
  228. prograph/utils/helpers.py +126 -0
  229. prograph/warnings.py +46 -0
  230. prograph/writes.py +369 -0
  231. prograph-1.3.3.dist-info/METADATA +281 -0
  232. prograph-1.3.3.dist-info/RECORD +237 -0
  233. prograph-1.3.3.dist-info/WHEEL +5 -0
  234. prograph-1.3.3.dist-info/entry_points.txt +3 -0
  235. prograph-1.3.3.dist-info/licenses/LICENSE +201 -0
  236. prograph-1.3.3.dist-info/licenses/NOTICE +10 -0
  237. prograph-1.3.3.dist-info/top_level.txt +1 -0
prograph/schema/iri.py ADDED
@@ -0,0 +1,817 @@
1
+ """IRI resolution, the single place a mapping's RDF identity is decided.
2
+
3
+ Mapped data has an identity in two worlds: rows and columns in a table, and
4
+ IRIs in RDF. Several subsystems need the second one, R2RML (which imports and exports mappings), the SPARQL
5
+ front-end (whose results are RDF terms, not backend row objects), and the PROV-O
6
+ provenance export (whose entities must be the same nodes the SPARQL graph holds),
7
+ and they must agree, or the same thing acquires a different IRI depending on
8
+ which one you ask.
9
+
10
+ Two kinds of identity live here.
11
+
12
+ **Entity IRIs**, which node a row is:
13
+
14
+ 1. If the ``NodeMapping`` declares an ``iri_template``, that wins. Templates are
15
+ R2RML-style, with ``{column}`` placeholders resolved against the row:
16
+ ``http://example.org/person/{person_id}``.
17
+ 2. Otherwise the IRI is synthesized as ``{base_iri}{source_table}/{id}``, with
18
+ composite keys joined by ``/`` in ``id_columns`` order.
19
+
20
+ A template referencing a column that is missing or null yields no IRI (``None``)
21
+ rather than an IRI containing the string ``None``, the node simply has no
22
+ identity in RDF, which is what an unresolvable subject map means in R2RML.
23
+
24
+ A value placed in an IRI is made **IRI-safe** first (R2RML 7.3): every
25
+ character outside ``iunreserved`` is percent-encoded, so a key holding ``/``,
26
+ a space, ``#``, ``?`` or a quote cannot be read as IRI structure and the IRI
27
+ parses back to the key it was built from. The characters are one list,
28
+ :data:`IRI_SAFE_ENCODING`, which every builder reads (this module, the Spark
29
+ column form, the SPARQL term expression), because they must agree string for
30
+ string. A template that is one placeholder and no literal text is
31
+ column-valued (R2RML's ``rr:column``): the column holds the whole IRI, used
32
+ as it is.
33
+
34
+ **Vocabulary IRIs**, which class or predicate a label, property or relationship
35
+ type is. Same rule in the same shape: a declaration wins, otherwise the
36
+ convention applies.
37
+
38
+ 1. A ``NodeMapping.class_iri``, or a ``PredicateMapping`` naming the predicate,
39
+ is authoritative. That is how an externally-authored ontology binds to the
40
+ data, and the whole point of declaring one.
41
+ 2. Otherwise ``{vocab_iri}{Label}`` for a class, ``{vocab_iri}{property}`` for a
42
+ datatype predicate, and ``{vocab_iri}{camelCasedRelType}`` for an object
43
+ predicate.
44
+
45
+ The other direction, which element a query's IRI names, is the same IRIs
46
+ read back (:func:`labels_of_class`): an IRI names an element only when it
47
+ is the very IRI above, never by its local name in another namespace.
48
+
49
+ Relationship types are UPPER_SNAKE_CASE in ProGraph and camelCase in ontologies
50
+ (``WORKS_AT`` ↔ ``worksAt``), so the convention converts between them rather
51
+ than emitting a spelling no ontology would use. :func:`predicate_local_name` is
52
+ the inverse of ``prograph.schema.naming.rel_type_from_local_name``.
53
+ """
54
+
55
+ import re
56
+ from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
57
+ from prograph.schema.types import is_missing
58
+ from prograph.rules import home, module_home
59
+
60
+ module_home("node-iri-parsing", "Node and class IRIs",
61
+ terms=("IRI", "iri_template", "node IRI", "class IRI", "parse_node_iri", "template_values", "base IRI"))
62
+
63
+ # The default namespaces for synthesized IRIs.
64
+ DEFAULT_BASE_IRI = "http://example.org/data/"
65
+ DEFAULT_VOCAB_IRI = "http://example.org/ontology/"
66
+
67
+ _PLACEHOLDER = re.compile(r"\{([^{}]+)\}")
68
+
69
+ # R2RML 7.3, "IRI-safe": percent-encode every character that is not in
70
+ # iunreserved (ALPHA, DIGIT, "-", ".", "_", "~", and non-ASCII). Among
71
+ # printable ASCII that is the list below. '%' is first, so that a builder
72
+ # applying the pairs as replacements in order does not encode its own
73
+ # output. (character, its encoding), in the order to apply them.
74
+ IRI_SAFE_ENCODING: List[Tuple[str, str]] = [
75
+ (character, f"%{ord(character):02X}")
76
+ for character in "%" + " !\"#$&'()*+,/:;<=>?@[\\]^`{|}"
77
+ ]
78
+
79
+
80
+ # What else R2RML 7.3 percent-encodes (RFC 3987: iunreserved holds only ucschar of the non-ASCII
81
+ # characters), as code-point ranges: the ASCII controls and DEL, the C1 controls, private use
82
+ # (iprivate is no ucschar) and the noncharacters (U+FDD0 to U+FDEF, the last two of every plane).
83
+ IRI_UNSAFE_RANGES: List[Tuple[int, int]] = (
84
+ [(0x00, 0x1F), (0x7F, 0x9F), (0xE000, 0xF8FF), (0xFDD0, 0xFDEF), (0xFFFE, 0xFFFF)]
85
+ + [(p * 0x10000 + 0xFFFE, p * 0x10000 + 0xFFFF) for p in range(1, 15)]
86
+ + [(0xF0000, 0x10FFFF)])
87
+ # The same as an XPath character class of the characters themselves (NUL left out: no SQL text
88
+ # holds one), for the SQL guard (`plan.ir.lower.iri_safe`).
89
+ IRI_UNSAFE_CLASS = "[" + "".join(f"{chr(max(lo, 1))}-{chr(hi)}" for lo, hi in IRI_UNSAFE_RANGES) + "]"
90
+ # The same class written with escapes, per regex engine (`plan.ir.lower.iri_safe`), so the printed SQL holds
91
+ # no control or private-use character: Java's (Spark, Databricks) and RE2's (DuckDB) `\x{h..h}`, PostgreSQL's
92
+ # `\Uhhhhhhhh`. The database's string literal escapes the backslash where it needs to (`Dialect.literal`).
93
+ IRI_UNSAFE_ESCAPED = {
94
+ "java": "[" + "".join(f"\\x{{{max(lo, 1):X}}}-\\x{{{hi:X}}}" for lo, hi in IRI_UNSAFE_RANGES) + "]",
95
+ "re2": "[" + "".join(f"\\x{{{max(lo, 1):X}}}-\\x{{{hi:X}}}" for lo, hi in IRI_UNSAFE_RANGES) + "]",
96
+ "pg": "[" + "".join(f"\\U{max(lo, 1):08X}-\\U{hi:08X}" for lo, hi in IRI_UNSAFE_RANGES) + "]",
97
+ }
98
+ _UNSAFE = re.compile("[" + "".join(f"\\U{lo:08x}-\\U{hi:08x}" for lo, hi in IRI_UNSAFE_RANGES) + "]")
99
+
100
+
101
+ # The characters a template's own text alone can write into an IRI: `iri_safe` encodes them in every
102
+ # value (an integer's text is digits and '-'), so they cut a template's terms into runs
103
+ # (`source_map.one_term_per_values`, `source_map._iri_runs`). '%' starts a value's escape.
104
+ IRI_TEMPLATE_CUT = frozenset(c for c, _ in IRI_SAFE_ENCODING) - {"%"}
105
+
106
+
107
+ @home("iri-safe", "A value made IRI-safe for a template (R2RML 7.3)",
108
+ terms=("IRI-safe", "percent-encode", "iunreserved", "RFC 3987", "ucschar", "control character",
109
+ "private use", "noncharacter"))
110
+ def iri_safe(value: Any) -> str:
111
+ """`value` as text, IRI-safe (R2RML 7.3): fit to stand between two '/' of an IRI. Every
112
+ character outside RFC 3987's iunreserved is percent-encoded, its UTF-8 bytes as %XX: the
113
+ printable ASCII ones (`IRI_SAFE_ENCODING`), and the controls, private-use characters and
114
+ noncharacters (`IRI_UNSAFE_CLASS`), so an IRI template never errors (one-plan.md 8.2). The SQL form encodes the first and refuses the second (`plan.ir.lower.iri_safe`).
115
+ """
116
+ text = str(value)
117
+ for character, encoded in IRI_SAFE_ENCODING:
118
+ text = text.replace(character, encoded)
119
+ return _UNSAFE.sub(lambda m: "".join(f"%{b:02X}" for b in m.group(0).encode("utf-8")), text)
120
+
121
+
122
+ def iri_value(text: str) -> str:
123
+ """The value an IRI-safe piece of an IRI stands for: `iri_safe` undone."""
124
+ from urllib.parse import unquote
125
+ return unquote(text)
126
+
127
+
128
+ def template_values(parts: Sequence[Tuple[str, bool]], iri: str, *,
129
+ decode: Callable[[str], str] = iri_value, safe: bool = False,
130
+ every: bool = True) -> List[Tuple[str, ...]]:
131
+ """Every way the template `parts` (`template_parts` form) makes `iri`:
132
+ for each, the text of each placeholder in order, `decode`d (IRI-safe
133
+ undone, `iri_value`), a placeholder never empty and one column the
134
+ template reads twice the same text at both. The one parse of an IRI
135
+ back to a template's values (`parse_node_iri` reads it).
136
+
137
+ Several where a separator is a character a value may hold too
138
+ (`{a}-{b}` and `q-r-s`), the shortest first piece first; `every`
139
+ False stops at the first. With `safe`, each piece must be the form
140
+ `iri_safe` writes of its value (R2RML 7.3), so only IRIs a row's
141
+ values render are parsed."""
142
+ found: List[Tuple[str, ...]] = []
143
+ names = [text for text, is_column in parts if is_column]
144
+
145
+ def ends(at: int, i: int):
146
+ following = parts[i + 1] if i + 1 < len(parts) else None
147
+ if following is None:
148
+ return [len(iri)] if len(iri) > at else []
149
+ if following[1]:
150
+ return range(at + 1, len(iri) + 1)
151
+ out, end = [], iri.find(following[0], at + 1)
152
+ while end != -1:
153
+ out.append(end)
154
+ end = iri.find(following[0], end + 1)
155
+ return out
156
+
157
+ def match(at: int, i: int, pieces: Tuple[str, ...]) -> None:
158
+ if found and not every:
159
+ return
160
+ if i == len(parts):
161
+ if at == len(iri):
162
+ found.append(pieces)
163
+ return
164
+ text, is_column = parts[i]
165
+ if not is_column:
166
+ if iri.startswith(text, at):
167
+ match(at + len(text), i + 1, pieces)
168
+ return
169
+ earlier = names.index(text)
170
+ for end in ends(at, i):
171
+ piece = iri[at:end]
172
+ if earlier < len(pieces) and pieces[earlier] != piece:
173
+ continue
174
+ if safe and iri_safe(decode(piece)) != piece:
175
+ continue
176
+ match(end, i + 1, pieces + (piece,))
177
+
178
+ match(0, 0, ())
179
+ return [tuple(decode(piece) for piece in pieces) for pieces in found]
180
+
181
+
182
+ # An IRI's scheme (RFC 3987): an IRI that starts with one is absolute.
183
+ IRI_SCHEME = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*:")
184
+
185
+
186
+ def prepended_iri(text: str, base: Optional[str]) -> str:
187
+ """An R2RML IRI term map's IRI from its text (R2RML 7.3): the text where
188
+ it is an absolute IRI, else the base IRI prepended; ValueError where
189
+ it is relative and there is no base. The plan's lowering writes the
190
+ same rule in SQL, per row (`plan.ir.lower.absolute`)."""
191
+ if IRI_SCHEME.match(text):
192
+ return text
193
+ if not base:
194
+ raise ValueError(f"the relative IRI {text!r} and no base IRI")
195
+ return base + text
196
+
197
+
198
+ def is_column_valued(template: str) -> bool:
199
+ """Whether a template is one placeholder and nothing else, `{uri}`: the
200
+ column holds the whole IRI (R2RML's rr:column), so it is used as it is."""
201
+ parts = template_parts(template)
202
+ return len(parts) == 1 and parts[0][1]
203
+
204
+
205
+ def template_columns(template: str) -> List[str]:
206
+ """Return the column names a template references, in order of appearance."""
207
+ return _PLACEHOLDER.findall(template)
208
+
209
+
210
+ def template_parts(template: str, escapes: bool = False) -> List[Tuple[str, bool]]:
211
+ """Split a template into ``(text, is_column)`` pieces, in order.
212
+
213
+ ``"http://x/{a}/{b}"`` → ``[("http://x/", False), ("a", True), ("/", False),
214
+ ("b", True)]``. Empty literal runs are dropped.
215
+
216
+ Exists so that a renderer which cannot substitute values directly, the
217
+ Spark quad materializer builds a column *expression*, not a string, can
218
+ still be driven by this module's parse rather than its own.
219
+
220
+ With `escapes`, the template is an R2RML string template (R2RML 7.3):
221
+ a backslash escapes the character after it, so ``\\{``, ``\\}`` and
222
+ ``\\\\`` are literal text, and a ``{`` not escaped opens a placeholder
223
+ that the next ``}`` not escaped closes; a template not so formed raises
224
+ :class:`TemplateSyntaxError`. A ProGraph template has no escapes (a
225
+ backslash is text), so the default reads it as it always has.
226
+ """
227
+ if escapes:
228
+ return _escaped_template_parts(template)
229
+ parts: List[Tuple[str, bool]] = []
230
+ position = 0
231
+ for match in _PLACEHOLDER.finditer(template):
232
+ if match.start() > position:
233
+ parts.append((template[position:match.start()], False))
234
+ parts.append((match.group(1), True))
235
+ position = match.end()
236
+ if position < len(template):
237
+ parts.append((template[position:], False))
238
+ return parts
239
+
240
+
241
+ class TemplateSyntaxError(ValueError):
242
+ """An R2RML string template that is not well formed (R2RML 7.3): an
243
+ unclosed or empty placeholder, a brace not escaped where it opens or
244
+ closes nothing, or a backslash at its end."""
245
+
246
+
247
+ def _escaped_template_parts(template: str) -> List[Tuple[str, bool]]:
248
+ """`template_parts` of an R2RML string template (R2RML 7.3)."""
249
+ parts: List[Tuple[str, bool]] = []
250
+ text: List[str] = []
251
+ column: Optional[List[str]] = None
252
+ i, n = 0, len(template)
253
+ while i < n:
254
+ c = template[i]
255
+ if c == "\\":
256
+ if i + 1 >= n:
257
+ raise TemplateSyntaxError(f"template {template!r} ends in a backslash")
258
+ (column if column is not None else text).append(template[i + 1])
259
+ i += 2
260
+ continue
261
+ if c == "{":
262
+ if column is not None:
263
+ raise TemplateSyntaxError(f"template {template!r}: '{{' inside a placeholder")
264
+ if text:
265
+ parts.append(("".join(text), False))
266
+ text = []
267
+ column = []
268
+ elif c == "}":
269
+ if column is None:
270
+ raise TemplateSyntaxError(f"template {template!r}: '}}' that closes nothing")
271
+ if not column:
272
+ raise TemplateSyntaxError(f"template {template!r}: an empty placeholder")
273
+ parts.append(("".join(column), True))
274
+ column = None
275
+ else:
276
+ (column if column is not None else text).append(c)
277
+ i += 1
278
+ if column is not None:
279
+ raise TemplateSyntaxError(f"template {template!r}: a placeholder not closed")
280
+ if text:
281
+ parts.append(("".join(text), False))
282
+ return parts
283
+
284
+
285
+ def _is_missing(value: Any) -> bool:
286
+ """True for values that cannot form part of an IRI.
287
+
288
+ Pandas turns ``None`` in a numeric column into ``NaN``; a NaN is a missing
289
+ value here, not the float it claims to be (pyshacl's Decimal comparator
290
+ raises on one).
291
+ """
292
+ return is_missing(value)
293
+
294
+
295
+ def render_iri_template(template: str, values: Dict[str, Any]) -> Optional[str]:
296
+ """Substitute ``{column}`` placeholders in a template from a row's values.
297
+
298
+ Returns None if any referenced column is absent or null, so callers never
299
+ produce an IRI with a hole in it. Values are made IRI-safe, except in a
300
+ column-valued template, whose one value is the IRI.
301
+ """
302
+ missing = False
303
+ encode = (lambda value: str(value)) if is_column_valued(template) else iri_safe
304
+
305
+ def _substitute(match: "re.Match[str]") -> str:
306
+ nonlocal missing
307
+ column = match.group(1)
308
+ if column not in values or _is_missing(values[column]):
309
+ missing = True
310
+ return ""
311
+ return encode(values[column])
312
+
313
+ rendered = _PLACEHOLDER.sub(_substitute, template)
314
+ return None if missing else rendered
315
+
316
+
317
+ class IRITemplateError(ValueError):
318
+ """An `iri_template` whose IRIs cannot be read back: two placeholders
319
+ with nothing between them."""
320
+
321
+
322
+ class IdentityConflictError(ValueError):
323
+ """Two node mappings on one table whose keys differ, with nothing that
324
+ keeps their IRIs apart."""
325
+
326
+
327
+ from prograph.rules import home # noqa: E402
328
+
329
+
330
+ class UnstableIdentityError(ValueError):
331
+ """A node mapping whose `iri_template` reads columns other than its
332
+ key, where a call needs the IRI a key stands for."""
333
+
334
+
335
+ def _literal_prefix(template: str) -> str:
336
+ """A template's text before its first placeholder."""
337
+ parts = template_parts(template)
338
+ return parts[0][0] if parts and not parts[0][1] else ""
339
+
340
+
341
+ def _prefixes_overlap(first: str, second: str) -> bool:
342
+ return first.startswith(second) or second.startswith(first)
343
+
344
+
345
+ def check_identities(schema: Any) -> None:
346
+ """Refuse a schema whose node IRIs cannot name one node each.
347
+
348
+ - `{a}{b}`: with nothing between two placeholders, a=1, b=23 and a=12,
349
+ b=3 are the same IRI, and it parses back as one of them.
350
+ - Two mappings on one table with different keys give one row two
351
+ identities under the synthesized form. It is allowed when both
352
+ declare an `iri_template` and neither template's leading text starts
353
+ the other's, so no IRI can be both; a wide table holding two kinds
354
+ of entity is mapped so. Two labels on one table with the same key
355
+ are one entity and are not this.
356
+ """
357
+ mappings = list(getattr(schema, "node_mappings", []))
358
+ for mapping in mappings:
359
+ template = getattr(mapping, "iri_template", None)
360
+ if not template:
361
+ continue
362
+ parts = template_parts(template)
363
+ for (_, first), (_, second) in zip(parts, parts[1:]):
364
+ if first and second:
365
+ raise IRITemplateError(
366
+ f"iri_template {template!r} of {mapping.label} has two placeholders "
367
+ f"with nothing between them, so its IRIs cannot be read back; "
368
+ f"put a separator between them")
369
+ for index, mapping in enumerate(mappings):
370
+ for other in mappings[:index]:
371
+ if (other.qualified_source_table != mapping.qualified_source_table
372
+ or list(other.id_columns) == list(mapping.id_columns)):
373
+ continue
374
+ templates = [getattr(m, "iri_template", None) for m in (other, mapping)]
375
+ pair = (f"{other.label} (key {', '.join(other.id_columns)}) and "
376
+ f"{mapping.label} (key {', '.join(mapping.id_columns)}) "
377
+ f"on table {mapping.source_table}")
378
+ if not all(templates):
379
+ raise IdentityConflictError(
380
+ f"{pair} have different keys, so one row would have two node ids; "
381
+ f"give both an iri_template, or the same key")
382
+ if _prefixes_overlap(*(_literal_prefix(t) for t in templates)):
383
+ raise IdentityConflictError(
384
+ f"{pair} have different keys and iri_templates that can give "
385
+ f"the same node id ({templates[0]!r}, {templates[1]!r}); start them "
386
+ f"with different text")
387
+
388
+
389
+ def require_key_template(mapping: Any) -> None:
390
+ """Refuse a mapping whose IRI cannot be computed from its key: its
391
+ template reads another column. A call that turns a key
392
+ into an IRI, or an IRI into the row to write, needs that."""
393
+ template = getattr(mapping, "iri_template", None)
394
+ if not template:
395
+ return
396
+ other = [c for c in template_columns(template) if c not in mapping.id_columns]
397
+ if other:
398
+ raise UnstableIdentityError(
399
+ f"the iri_template of {mapping.label} reads {', '.join(other)}, which "
400
+ f"is not its key ({', '.join(mapping.id_columns)}): its IRI cannot be "
401
+ f"computed from a key")
402
+
403
+
404
+ def base_iri_of(schema_or_mapping: Any) -> str:
405
+ """The namespace synthesized instance IRIs start with: the schema's
406
+ `base_iri`, its one home. Given a mapping, its schema's; a mapping in
407
+ no schema has the default."""
408
+ schema = getattr(schema_or_mapping, "_schema", schema_or_mapping)
409
+ return getattr(schema, "base_iri", None) or DEFAULT_BASE_IRI
410
+
411
+
412
+ def default_node_iri(source_table: str, entity_id: Any, base_iri: str = DEFAULT_BASE_IRI) -> str:
413
+ """The synthesized IRI for a node with no declared template.
414
+
415
+ ``entity_id`` may be a tuple for a composite key, matching how composite node
416
+ ids are carried internally.
417
+ """
418
+ parts = entity_id if isinstance(entity_id, tuple) else (entity_id,)
419
+ key = "/".join(iri_safe(part) for part in parts)
420
+ return f"{base_iri}{source_table}/{key}"
421
+
422
+
423
+ def iri_segment(mapping: Any) -> str:
424
+ """The segment a mapping's synthesized IRIs carry after the base: its `iri_segment` where one is set
425
+ (a YAML source's name, kept whether `to_schema(by_table=True)` reads the source's qualified table or
426
+ not, so one source mints one IRI either way), else its `source_table`."""
427
+ return getattr(mapping, "iri_segment", None) or mapping.source_table
428
+
429
+
430
+ def node_iri_template(mapping: Any) -> str:
431
+ """The template a node mapping's IRIs are written by, with `{column}`
432
+ placeholders: its declared ``iri_template``, else the synthesized form
433
+ (`default_node_iri`), ``{base_iri}{source_table}/{key}``. What an agent
434
+ writes an individual's IRI from."""
435
+ template = getattr(mapping, "iri_template", None)
436
+ if template:
437
+ return template
438
+ key = "/".join("{" + column + "}" for column in mapping.id_columns)
439
+ shared = getattr(mapping, "identity", None)
440
+ if shared and shared not in ("global", "distinct"): # keywords, not a shared name
441
+ # A shared identity: maps of one name, over any tables, give one subject per key.
442
+ return f"{base_iri_of(mapping)}{shared}/{key}"
443
+ return f"{base_iri_of(mapping)}{iri_segment(mapping)}/{key}"
444
+
445
+
446
+ def node_iri(
447
+ mapping: Any,
448
+ values: Dict[str, Any],
449
+ ) -> Optional[str]:
450
+ """Resolve a node's IRI from its mapping and a row's column values.
451
+
452
+ Args:
453
+ mapping: The ``NodeMapping`` the node came from.
454
+ values: Column name -> value for the row. Must cover the mapping's id
455
+ columns, and any column the ``iri_template`` references.
456
+ Returns:
457
+ The IRI, or None when a referenced column is missing or null.
458
+ """
459
+ template = getattr(mapping, "iri_template", None)
460
+ if template:
461
+ return render_iri_template(template, values)
462
+
463
+ id_values = []
464
+ for column in mapping.id_columns:
465
+ value = values.get(column)
466
+ if _is_missing(value):
467
+ return None
468
+ id_values.append(value)
469
+
470
+ if not id_values:
471
+ return None
472
+
473
+ key = id_values[0] if len(id_values) == 1 else tuple(id_values)
474
+ return default_node_iri(iri_segment(mapping), key, base_iri_of(mapping))
475
+
476
+
477
+ def node_iri_from_id(
478
+ mapping: Any,
479
+ entity_id: Any,
480
+ ) -> Optional[str]:
481
+ """Resolve a node's IRI when only its id is in hand.
482
+
483
+ A declared ``iri_template`` that references non-id columns cannot be rendered
484
+ from an id alone; such a mapping returns None here and needs the row form
485
+ (:func:`node_iri`) instead.
486
+ """
487
+ template = getattr(mapping, "iri_template", None)
488
+ if template:
489
+ id_columns = mapping.id_columns
490
+ ids = entity_id if isinstance(entity_id, tuple) else (entity_id,)
491
+ if len(ids) != len(id_columns):
492
+ return None
493
+ values = dict(zip(id_columns, ids))
494
+ if any(column not in values for column in template_columns(template)):
495
+ return None
496
+ return render_iri_template(template, values)
497
+
498
+ if _is_missing(entity_id):
499
+ return None
500
+ return default_node_iri(iri_segment(mapping), entity_id, base_iri_of(mapping))
501
+
502
+
503
+ # ── Vocabulary IRIs ──────────────────────────────────────────────────────
504
+ #
505
+ # Classes and predicates, as opposed to the entity IRIs above. Same rule: a
506
+ # declaration wins, the convention is the fallback.
507
+
508
+
509
+ def parse_node_iri(schema: Any, iri: str) -> List[Tuple[Any, Dict[str, str]]]:
510
+ """The node mappings whose IRIs could be `iri`, each with the values (as
511
+ text) the IRI gives the columns that build it.
512
+
513
+ The inverse of :func:`node_iri`: a declared template matches with each
514
+ placeholder standing for text, and its columns are the template's,
515
+ which need not be the key (`{_uri}`); the synthesized form
516
+ matches ``{base_iri}{source_table}/{key}`` and gives the key columns.
517
+ Several mappings may match (labels on one table), and a match says only
518
+ what the IRI could name, not that the node exists;
519
+ :meth:`ProGraph.resolve_iri` checks that. A relationship's instance IRI
520
+ names no node: its segment after the table starts with ``@``.
521
+ """
522
+ matches: List[Tuple[Any, Dict[str, str]]] = []
523
+ for mapping in getattr(schema, "node_mappings", []):
524
+ id_columns = list(mapping.id_columns)
525
+ template = getattr(mapping, "iri_template", None)
526
+ if template:
527
+ parts = template_parts(template)
528
+ columns = list(dict.fromkeys(text for text, is_column in parts if is_column))
529
+ if not columns:
530
+ continue
531
+ decode = (lambda text: text) if is_column_valued(template) else iri_value
532
+ found = template_values(parts, iri, decode=decode, every=False)
533
+ if found:
534
+ placeholders = [text for text, is_column in parts if is_column]
535
+ matches.append((mapping, dict(zip(placeholders, found[0]))))
536
+ continue
537
+ prefix = f"{base_iri_of(schema)}{iri_segment(mapping)}/"
538
+ if not iri.startswith(prefix):
539
+ continue
540
+ key = iri[len(prefix):].split("/")
541
+ if key[0].startswith(RELATIONSHIP_MARK):
542
+ continue # a relationship's IRI; parse_relationship_iri reads those
543
+ if len(key) == len(id_columns) and all(key):
544
+ matches.append((mapping, dict(zip(id_columns, map(iri_value, key)))))
545
+ return matches
546
+
547
+
548
+ def predicate_local_name(rel_type: str) -> str:
549
+ """The predicate local name for a relationship type.
550
+
551
+ ProGraph stores relationship types UPPER_SNAKE_CASE (``IS_PART_OF``);
552
+ ontologies name the same predicate camelCase (``isPartOf``). The convention
553
+ converts, so a synthesized predicate looks like one an ontology would
554
+ declare. Inverse of ``prograph.schema.naming.rel_type_from_local_name``.
555
+ """
556
+ if "_" not in rel_type:
557
+ return rel_type.lower()
558
+ parts = rel_type.split("_")
559
+ return parts[0].lower() + "".join(part.capitalize() for part in parts[1:])
560
+
561
+
562
+ def default_class_iri(label: str, vocab_iri: str = DEFAULT_VOCAB_IRI) -> str:
563
+ """The synthesized class IRI for a label with no declared one."""
564
+ return f"{vocab_iri}{label}"
565
+
566
+
567
+ def default_property_iri(property_name: str, vocab_iri: str = DEFAULT_VOCAB_IRI) -> str:
568
+ """The synthesized predicate IRI for a datatype property."""
569
+ return f"{vocab_iri}{property_name}"
570
+
571
+
572
+ def default_relationship_iri(rel_type: str, vocab_iri: str = DEFAULT_VOCAB_IRI) -> str:
573
+ """The synthesized predicate IRI for a relationship type."""
574
+ return f"{vocab_iri}{predicate_local_name(rel_type)}"
575
+
576
+
577
+ def default_relation_class_iri(rel_type: str, vocab_iri: str = DEFAULT_VOCAB_IRI) -> str:
578
+ """The synthesized class IRI for a reified relationship.
579
+
580
+ An edge with properties needs a node to hang them on, and that node needs a
581
+ class for a shape to target. ``WORKS_AT`` becomes ``WorksAt``, the class
582
+ spelling, beside ``worksAt`` the predicate spelling, which is how an
583
+ ontology names the relation and the property it reifies.
584
+ """
585
+ return f"{vocab_iri}{''.join(part.capitalize() for part in rel_type.split('_'))}"
586
+
587
+
588
+ def relation_class_iri(mapping: Any, vocab_iri: str = DEFAULT_VOCAB_IRI) -> str:
589
+ """The class a reified relationship's statement node is typed with."""
590
+ declared = getattr(mapping, "relation_class_iri", None)
591
+ if declared:
592
+ return declared
593
+ return default_relation_class_iri(mapping.rel_type, vocab_iri)
594
+
595
+
596
+ def relationship_instance_iri(
597
+ mapping: Any,
598
+ source_id: Any,
599
+ target_id: Any,
600
+ ) -> Optional[str]:
601
+ """The IRI naming one relationship row, so something can be said *about* it.
602
+
603
+ An edge is a triple, and a triple is not a resource, to attach properties
604
+ (reification) or lineage (PROV-O) you first have to name it. Both do, and
605
+ they must produce the same name or a shape's violation cannot be joined to
606
+ the provenance of the very edge it flagged.
607
+
608
+ The form is ``{base}{table}/@{REL_TYPE}/{start key}/{end key}``, every
609
+ part of a composite key its own segment. It is derived only from the
610
+ mapping and the two ids, with no declarable template: every caller must
611
+ be able to compute it, and the provenance path holds a bare pair of ids,
612
+ not a row.
613
+
614
+ The ``@`` segment keeps it apart from every node IRI. A key part is
615
+ IRI-safe, so it never holds a bare ``@``; without the segment, a node
616
+ keyed ``(order, line)`` and an edge ``order -> part`` on the same table
617
+ were both ``{base}lineitem/1/5``. The type in it keeps two relationship
618
+ types mapped on one table apart.
619
+
620
+ The cost is that **parallel edges collide**, two rows of one type joining
621
+ the same pair in the same table are one statement in RDF, and their
622
+ properties merge onto it. Model a multigraph edge as a node if that
623
+ matters.
624
+ """
625
+ parts: List[Any] = []
626
+ for entity_id in (source_id, target_id):
627
+ # A composite key is a tuple; its parts join on '/', as a node's do.
628
+ for part in (entity_id if isinstance(entity_id, tuple) else (entity_id,)):
629
+ if _is_missing(part):
630
+ return None
631
+ parts.append(part)
632
+ return (relationship_iri_prefix(mapping)
633
+ + "/".join(iri_safe(part) for part in parts))
634
+
635
+
636
+ RELATIONSHIP_MARK = "@"
637
+
638
+
639
+ def relationship_iri_prefix(mapping: Any) -> str:
640
+ """What every instance IRI of a relationship mapping starts with, up to
641
+ and including the '/' before the start key."""
642
+ return (f"{base_iri_of(mapping)}{iri_segment(mapping)}/"
643
+ f"{RELATIONSHIP_MARK}{iri_safe(mapping.rel_type)}/")
644
+
645
+
646
+ def is_rdf_class(mapping: Any) -> bool:
647
+ """Whether a node mapping's rows are typed with a class (`rdf_class`): a mapping with no label gives none
648
+ unless it declares a `class_iri` (an unlabelled node has no rdf:type of its own)."""
649
+ if getattr(mapping, "label", None) is None and not getattr(mapping, "class_iri", None):
650
+ return False
651
+ return getattr(mapping, "rdf_class", True)
652
+
653
+
654
+ # A label as a constraint inside a query, for a label that is no class:
655
+ # never a term of the data, so never a result.
656
+ LABEL_IRI_PREFIX = "urn:prograph:label:"
657
+
658
+
659
+ def class_iri(mapping: Any, vocab_iri: str = DEFAULT_VOCAB_IRI) -> str:
660
+ """The class IRI a node mapping's rows are typed with.
661
+
662
+ A declared ``class_iri`` wins. That is how a mapping binds to an
663
+ externally-authored ontology's class rather than to an invented one.
664
+ """
665
+ declared = getattr(mapping, "class_iri", None)
666
+ if declared:
667
+ return declared
668
+ return default_class_iri(mapping.label, vocab_iri)
669
+
670
+
671
+ def property_iri(
672
+ schema: Any,
673
+ label: Optional[str],
674
+ property_name: str,
675
+ vocab_iri: str = DEFAULT_VOCAB_IRI,
676
+ ) -> str:
677
+ """The predicate IRI for a datatype property on a label.
678
+
679
+ Prefers a ``PredicateMapping`` declared for this (label, property), the
680
+ user's own vocabulary, and otherwise synthesizes one. Without this the
681
+ bridge would emit an invented predicate for a property the user had already
682
+ bound to ``foaf:name``, and a shape or axiom written against ``foaf:name``
683
+ would silently match nothing.
684
+ """
685
+ if schema is not None:
686
+ declared = schema.find_predicate_iri_for_property(label, property_name)
687
+ if declared:
688
+ return declared
689
+ return default_property_iri(property_name, vocab_iri)
690
+
691
+
692
+ def relationship_iri(
693
+ schema: Any,
694
+ rel_type: str,
695
+ vocab_iri: str = DEFAULT_VOCAB_IRI,
696
+ ) -> str:
697
+ """The predicate IRI for a relationship type, declaration first."""
698
+ if schema is not None:
699
+ declared = schema.find_predicate_iri_for_relationship(rel_type)
700
+ if declared:
701
+ return declared
702
+ return default_relationship_iri(rel_type, vocab_iri)
703
+
704
+
705
+ # The inverse direction: which class or predicate of the schema a query's IRI
706
+ # names. Two IRIs are equal only when they are the same string (RDF 1.1
707
+ # Concepts 3.2), and SPARQL matches a term by equality (SPARQL 1.1 18.3), so a
708
+ # query's IRI names a label, property or relationship type only when it is the
709
+ # IRI that element is published under: the declared one, else the default
710
+ # vocabulary's. A local name in another namespace names nothing.
711
+
712
+ def labels_of_class(schema: Any, iri: str) -> List[str]:
713
+ """The labels whose rows are typed with class `iri` (``class_iri``), in
714
+ mapping order; a label that is no RDF class is none."""
715
+ if schema is None:
716
+ return []
717
+ return list(dict.fromkeys(m.label for m in schema.node_mappings
718
+ if is_rdf_class(m) and class_iri(m) == iri))
719
+
720
+
721
+ class IdentityMeetWarning(UserWarning):
722
+ """Two YAML or Python maps over different rows whose authored IRI templates may give one IRI:
723
+ their subjects are one node where they meet (RDF: one IRI is one node), which a template copied
724
+ across tables does silently. One `identity:` on both says it is meant. Worded in mapping terms
725
+ (property-graph users need not know what an IRI is); the templates are in `detail`."""
726
+
727
+ def __init__(self, message: str, detail: str = ""):
728
+ super().__init__(message)
729
+ self.detail = detail
730
+
731
+
732
+ @home("identity-meetings", "Which maps' subjects may meet, and the refusal",
733
+ terms=("identity", "identity: global", "shared identity", "IdentityMeetWarning", "may meet",
734
+ "per-table IRI", "minted IRI"))
735
+ def check_meetings(schema: Any) -> None:
736
+ """keys-and-identity.md 4, one-plan 2.3 for 1.0, over the schema's source maps (a YAML file's
737
+ included R2RML among them). For two node maps over different rows (not of one subject
738
+ identity) whose subject templates may give one IRI (`TermMap.may_equal`):
739
+ - one minted by ProGraph (no iri_template: `{base_iri}{table}/{key}`, or a shared identity's
740
+ `{base_iri}{name}/{key}`) and the other not of that same minted identity: refused
741
+ (`IdentityConflictError`, naming both), since it would merge another's rows into
742
+ ProGraph's subjects;
743
+ - both authored YAML or Python templates: a warning (`IdentityMeetWarning`), unless both
744
+ declare one `identity:` name, or both `identity: global`;
745
+ - an R2RML template: global (R2RML 6), no warning."""
746
+ try:
747
+ maps = schema.source_maps()
748
+ except Exception: # noqa: BLE001 - a schema the one plan does not read is checked elsewhere
749
+ return
750
+ from prograph.schema.source_map import IRI, LEXICAL_R2RML, kept_apart
751
+ def declared(m):
752
+ # The map's own declaration (`NodeMap.identity`): no authoring object is read.
753
+ return m.identity if m.subject.lexical != LEXICAL_R2RML else None
754
+
755
+ nodes = [m for m in maps.nodes if m.subject.term_type == IRI and m.subject.constant is None]
756
+ import warnings
757
+ warned: set = set()
758
+ for i, a in enumerate(nodes):
759
+ for b in nodes[:i]:
760
+ if maps.subject_identity(a) == maps.subject_identity(b) or not a.subject.may_equal(b.subject) \
761
+ or kept_apart(a, b):
762
+ continue
763
+ ia, ib = declared(a), declared(b)
764
+ pair = f"{b.label or b.id} ({b.source.table}) and {a.label or a.id} ({a.source.table})"
765
+ minted = [m for m in (a, b) if m.subject.synthesized]
766
+ if minted:
767
+ if ia is not None and ia == ib and ia != "global":
768
+ continue # one shared identity, minted alike
769
+ whole = [m for m in (a, b) if not m.subject.synthesized and m.subject.column is not None]
770
+ if whole:
771
+ # A column holding whole IRIs (`{uri}`) may hold any IRI, ProGraph's minted ones
772
+ # too; its rows meet a minted subject only where the column holds that very IRI,
773
+ # the mapping's own choice: a warning, once per mapping (decided 2026-11-10).
774
+ w = whole[0]
775
+ if w.id not in warned:
776
+ warned.add(w.id)
777
+ other = a if w is b else b
778
+ warnings.warn(IdentityMeetWarning(
779
+ f"{pair} may describe the same nodes: a {w.source.table} row whose "
780
+ f"{w.subject.column} column holds one of {other.label or other.id}'s node ids is "
781
+ f"that node. If {w.label or w.id}'s nodes are never another mapping's, add "
782
+ f"identity: distinct to it",
783
+ detail=f"{w.subject.column} holds whole IRIs; {other.label or other.id}'s are "
784
+ f"{other.subject.text()}"), stacklevel=3)
785
+ continue
786
+ raise IdentityConflictError(
787
+ f"{pair} could give their rows the same node ids ({a.subject.text()} and "
788
+ f"{b.subject.text()}), which would merge their rows into one node. Give them one "
789
+ f"identity: <name> to make them one, or an iri_template that keeps them apart")
790
+ if LEXICAL_R2RML in (a.subject.lexical, b.subject.lexical):
791
+ continue # an R2RML template is global (R2RML 6)
792
+ if ia is not None and ia == ib:
793
+ continue # one identity declared: meant
794
+ warnings.warn(IdentityMeetWarning(
795
+ f"{pair} may describe the same nodes: where their iri_templates give one node id, their rows "
796
+ f"are one node. If that is meant, give both the same identity: <name> (or identity: global); "
797
+ f"if not, add identity: distinct to one, or keep the templates apart",
798
+ detail=f"{b.subject.text()} and {a.subject.text()}"), stacklevel=3)
799
+ # A relationship end whose label has node maps of different subjects ends at the node of its key in each
800
+ # (compile_schema: one edge map per pair of ends); a key two of them hold is two nodes, both its ends.
801
+ seen = set()
802
+ by_id = {n.id: n for n in maps.nodes}
803
+ for e in maps.edges:
804
+ if e.rel_type is None:
805
+ continue
806
+ for side, ref in (("start", e.start), ("end", e.end)):
807
+ branches = [x for x in maps.edges if (x.id == e.id or x.branch_of == e.id)]
808
+ refs = {getattr(x, side).map_id for x in branches}
809
+ if e.branch_of is not None or len(refs) < 2 or (e.rel_type, side) in seen:
810
+ continue
811
+ seen.add((e.rel_type, side))
812
+ tables = ", ".join(dict.fromkeys(by_id[r].source.table for r in refs if r in by_id))
813
+ warnings.warn(IdentityMeetWarning(
814
+ f"{e.rel_type}'s {side} label {ref.label} is given by node mappings over {tables} that are not "
815
+ f"one identity: a {side} key one of them holds is that node, and a key two of them hold may be "
816
+ f"two {ref.label} nodes, each an {side} of the relationship. If they describe the same entities, "
817
+ f"give them one identity: <name>"), stacklevel=3)