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
@@ -0,0 +1,546 @@
1
+ """R2RML parser, reads R2RML Turtle documents into the R2RML data model.
2
+
3
+ Uses rdflib to parse RDF and extract R2RML constructs per the W3C R2RML
4
+ specification (https://www.w3.org/TR/r2rml/).
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import re
10
+ from contextlib import contextmanager
11
+ from pathlib import Path
12
+ from typing import Dict, List, Optional, Set, Tuple
13
+
14
+ try:
15
+ import rdflib
16
+ from rdflib import Graph, Namespace, RDF, URIRef, Literal, BNode
17
+ from rdflib.term import Node
18
+ RDFLIB_AVAILABLE = True
19
+ except ImportError:
20
+ RDFLIB_AVAILABLE = False
21
+
22
+ from prograph.r2rml.model import (
23
+ R2RMLMapping, TriplesMap, LogicalTable, SubjectMap,
24
+ PredicateObjectMap, PredicateMap, ObjectMap, GraphMap,
25
+ JoinCondition,
26
+ )
27
+
28
+
29
+ # Without rdflib the R2RML package still imports (a YAML or Python schema's queries reach it for
30
+ # `with_included`); parsing a document is what needs rdflib.
31
+ RR = Namespace("http://www.w3.org/ns/r2rml#") if RDFLIB_AVAILABLE else None
32
+
33
+
34
+ @contextmanager
35
+ def literals_as_written():
36
+ """rdflib reads a typed literal as written while inside: by default it rewrites the lexical
37
+ form from the value (`"3.0E1"^^xsd:double` as `30.0`, `"007"^^xsd:integer` as `7`), and an
38
+ rr:constant is the term as written (R2RML 7.2; RDF 1.1 Concepts 3.3: a literal is its lexical
39
+ form). Restored on leaving."""
40
+ import rdflib
41
+ before, rdflib.NORMALIZE_LITERALS = rdflib.NORMALIZE_LITERALS, False
42
+ try:
43
+ yield
44
+ finally:
45
+ rdflib.NORMALIZE_LITERALS = before
46
+
47
+
48
+ def sql_identifier(text: Optional[str]) -> Optional[str]:
49
+ """The name an R2RML SQL identifier denotes (R2RML 5: rr:tableName,
50
+ rr:column, a template's column and a join condition's are SQL
51
+ identifiers): a delimited identifier, "Name", is the name between its
52
+ quotes with each doubled quote one quote, exactly as written; an
53
+ undelimited one is left as it is. A qualified name ("s"."t") is read
54
+ part by part. Kept with its quotes, "\"Name\"" was taken for a
55
+ column called "Name" with the quotes and written quoted again,
56
+ s.\"\"\"Name\"\"\", which no database binds (A3, the W3C cases)."""
57
+ if text is None or '"' not in text:
58
+ return text
59
+ parts, i, n = [], 0, len(text)
60
+ while i < n:
61
+ if text[i] == '"':
62
+ j, name = i + 1, []
63
+ while j < n:
64
+ if text[j] == '"':
65
+ if j + 1 < n and text[j + 1] == '"':
66
+ name.append('"'); j += 2; continue
67
+ break
68
+ name.append(text[j]); j += 1
69
+ if j >= n:
70
+ return text # no closing quote: not a delimited identifier
71
+ parts.append("".join(name)); i = j + 1
72
+ else:
73
+ j = text.find(".", i)
74
+ j = n if j < 0 else j
75
+ parts.append(text[i:j]); i = j
76
+ if i < n:
77
+ if text[i] != ".":
78
+ return text
79
+ i += 1
80
+ return ".".join(parts)
81
+
82
+
83
+ _DELIMITED_PLACEHOLDER = re.compile(r'(?<!\\)\{("(?:[^"]|"")*")\}')
84
+
85
+
86
+ def template_identifiers(template: Optional[str]) -> Optional[str]:
87
+ """A template with each delimited column placeholder, {"ID"}, written as
88
+ the column it names, {ID} (R2RML 7.3: a placeholder is a column name, an
89
+ SQL identifier). ProGraph's template placeholders are bare names."""
90
+ if template is None or '{"' not in template:
91
+ return template
92
+ return _DELIMITED_PLACEHOLDER.sub(lambda m: "{" + sql_identifier(m.group(1)) + "}", template)
93
+
94
+
95
+ def undelimited(text: Optional[str]) -> bool:
96
+ """`text`, an R2RML SQL identifier as written, is undelimited (a regular identifier, which
97
+ the database folds; `Dialect.fold_identifier`)."""
98
+ return text is not None and '"' not in text
99
+
100
+
101
+ def undelimited_placeholders(template: Optional[str]) -> Set[str]:
102
+ """The columns a template as written names undelimited, `{ID}` (not `{"ID"}`)."""
103
+ if template is None:
104
+ return set()
105
+ from prograph.schema.iri import template_parts
106
+ try:
107
+ parts = template_parts(template, escapes=True)
108
+ except Exception: # noqa: BLE001 - a malformed template is refused where it is compiled
109
+ return set()
110
+ return {text for text, is_column in parts if is_column and undelimited(text)}
111
+
112
+
113
+ class R2RMLParseError(Exception):
114
+ """Raised when an R2RML document cannot be parsed."""
115
+
116
+
117
+ def _document_graph() -> Graph:
118
+ """A graph holding only the prefixes the parsed document declares: a
119
+ plain `Graph()` binds rdflib's well-known namespaces too (brick, csvw,
120
+ dcat and some 25 more), and the schema handed every one of them to a
121
+ model as PREFIX lines it should write."""
122
+ return Graph(bind_namespaces="none")
123
+
124
+
125
+ def _parse_turtle(g: Graph, text: str, base: str, turtle: bool = True) -> Optional[str]:
126
+ """Parse a Turtle (or N3) document into `g` as rdflib's own parser
127
+ does, and give the base IRI the document declares first (@base or
128
+ BASE, wherever it stands in the text, as the parse reads it), or None."""
129
+ from rdflib.plugins.parsers.notation3 import RDFSink, SinkParser
130
+
131
+ class _Parser(SinkParser):
132
+ declared: Optional[str] = None
133
+
134
+ def directiveOrStatement(self, argstr: str, h: int) -> int:
135
+ before = self._baseURI
136
+ j = super().directiveOrStatement(argstr, h)
137
+ if self.declared is None and self._baseURI != before:
138
+ self.declared = self._baseURI
139
+ return j
140
+
141
+ parser = _Parser(RDFSink(g), baseURI=base, turtle=turtle)
142
+ parser.loadBuf(text.encode('utf-8'))
143
+ for prefix, namespace in parser._bindings.items():
144
+ g.bind(prefix, namespace)
145
+ return None if parser.declared is None else str(parser.declared)
146
+
147
+
148
+ class R2RMLParser:
149
+ """Parse R2RML Turtle documents into :class:`R2RMLMapping` instances.
150
+
151
+ Example::
152
+
153
+ parser = R2RMLParser()
154
+ mapping = parser.parse_file("mapping.ttl")
155
+ for tm in mapping.triples_maps:
156
+ print(tm.uri, tm.logical_table.table_name)
157
+ """
158
+
159
+ def __init__(self):
160
+ self._regular: Set[str] = set() # the triples map under way's undelimited columns
161
+ if not RDFLIB_AVAILABLE:
162
+ raise ImportError(
163
+ "rdflib is required for R2RML parsing; it is a dependency of prograph, so "
164
+ "reinstall prograph in this environment"
165
+ )
166
+
167
+ def parse(self, source: str, format: str = 'turtle') -> R2RMLMapping:
168
+ """Parse an R2RML mapping from a string.
169
+
170
+ Args:
171
+ source: R2RML document content
172
+ format: RDF serialization format (default: turtle)
173
+
174
+ Returns:
175
+ Parsed R2RMLMapping
176
+ """
177
+ g = _document_graph()
178
+ base = None
179
+ with literals_as_written():
180
+ if format in ('turtle', 'n3'):
181
+ base = _parse_turtle(g, source, g.absolutize(''), turtle=format == 'turtle')
182
+ else:
183
+ g.parse(data=source, format=format)
184
+ mapping = self._extract_mapping(g)
185
+ mapping.base = base
186
+ return mapping
187
+
188
+ def parse_file(self, path: str) -> R2RMLMapping:
189
+ """Parse an R2RML mapping from a file.
190
+
191
+ Args:
192
+ path: Path to R2RML file
193
+
194
+ Returns:
195
+ Parsed R2RMLMapping
196
+
197
+ Raises:
198
+ FileNotFoundError: If the file does not exist
199
+ """
200
+ p = Path(path)
201
+ if not p.exists():
202
+ raise FileNotFoundError(f"R2RML file not found: {path}")
203
+
204
+ format_map = {
205
+ '.ttl': 'turtle',
206
+ '.n3': 'n3',
207
+ '.rdf': 'xml',
208
+ '.owl': 'xml',
209
+ '.jsonld': 'json-ld',
210
+ '.nt': 'nt',
211
+ }
212
+ fmt = format_map.get(p.suffix.lower(), 'turtle')
213
+
214
+ g = _document_graph()
215
+ base = None
216
+ with literals_as_written():
217
+ if fmt in ('turtle', 'n3'):
218
+ base = _parse_turtle(g, p.read_bytes().decode('utf-8'), p.resolve().as_uri(),
219
+ turtle=fmt == 'turtle')
220
+ else:
221
+ g.parse(str(p), format=fmt)
222
+ mapping = self._extract_mapping(g)
223
+ mapping.base = base
224
+ return mapping
225
+
226
+ # ------------------------------------------------------------------
227
+ # Internal extraction
228
+ # ------------------------------------------------------------------
229
+
230
+ def _extract_mapping(self, g: Graph) -> R2RMLMapping:
231
+ prefixes = {str(prefix): str(ns) for prefix, ns in g.namespaces() if prefix}
232
+ triples_maps = []
233
+
234
+ # Find all TriplesMap subjects. They have rr:logicalTable
235
+ for tm_uri in g.subjects(RR.logicalTable, None):
236
+ triples_maps.append(self._extract_triples_map(g, tm_uri))
237
+
238
+ return R2RMLMapping(triples_maps=triples_maps, prefixes=prefixes)
239
+
240
+ def _extract_triples_map(self, g: Graph, tm_uri: Node) -> TriplesMap:
241
+ uri_str = self._map_id(g, tm_uri)
242
+ self._regular: Set[str] = set()
243
+ logical_table = self._extract_logical_table(g, tm_uri)
244
+ subject_map = self._extract_subject_map(g, tm_uri)
245
+ po_maps = self._extract_predicate_object_maps(g, tm_uri)
246
+ graph_maps = self._extract_graph_maps(g, tm_uri)
247
+
248
+ return TriplesMap(
249
+ uri=uri_str,
250
+ logical_table=logical_table,
251
+ subject_map=subject_map,
252
+ predicate_object_maps=po_maps,
253
+ graph_maps=graph_maps,
254
+ subject_map_count=(len(set(g.objects(tm_uri, RR.subjectMap)))
255
+ + len(set(g.objects(tm_uri, RR.subject)))),
256
+ regular_columns=frozenset(self._regular),
257
+ )
258
+
259
+ @staticmethod
260
+ def _map_id(g: Graph, node: Node) -> str:
261
+ """A triples map's identifier: its IRI, or for a blank node one
262
+ that is the same on every load of the document, `_:map_<hash>`,
263
+ the hash of its own triples with their blank nodes canonical
264
+ (rdflib.compare, RDF dataset canonicalization). rdflib names a blank
265
+ node afresh on each parse, and the bridge names labels and sources
266
+ after the map: a blank-node map's label changed from load to load. A link to another triples map is written as
267
+ that map's name, not followed."""
268
+ if not isinstance(node, BNode):
269
+ return str(node)
270
+ cached = getattr(g, '_prograph_map_ids', None)
271
+ if cached is None:
272
+ cached = {}
273
+ g._prograph_map_ids = cached
274
+ if node in cached:
275
+ return cached[node]
276
+ import hashlib
277
+ from rdflib.compare import to_canonical_graph
278
+ maps = set(g.subjects(RR.logicalTable, None))
279
+ own = Graph()
280
+ stack, seen = [node], {node}
281
+ while stack:
282
+ s = stack.pop()
283
+ for p, o in g.predicate_objects(s):
284
+ if o in maps and o != node:
285
+ # Another triples map: by its IRI, or a placeholder for
286
+ # a blank one (its own triples name it).
287
+ o = o if not isinstance(o, BNode) else Literal("triples map")
288
+ elif isinstance(o, BNode) and o not in seen:
289
+ seen.add(o)
290
+ stack.append(o)
291
+ own.add((s, p, o))
292
+ text = "\n".join(sorted(" ".join(term.n3() for term in triple)
293
+ for triple in to_canonical_graph(own)))
294
+ cached[node] = "_:map_" + hashlib.sha1(text.encode("utf-8")).hexdigest()[:12]
295
+ return cached[node]
296
+
297
+ def _extract_logical_table(self, g: Graph, tm_uri: Node) -> LogicalTable:
298
+ lt_node = self._single_object(g, tm_uri, RR.logicalTable)
299
+ if lt_node is None:
300
+ raise R2RMLParseError(f"TriplesMap {tm_uri} missing rr:logicalTable")
301
+
302
+ written = self._literal_value(g, lt_node, RR.tableName)
303
+ table_name = sql_identifier(written)
304
+ sql_query = self._literal_value(g, lt_node, RR.sqlQuery)
305
+ if sql_query is not None:
306
+ # A query is read as a derived table: a statement terminator
307
+ # after it is no part of the query (R2RML 5.2 allows one).
308
+ sql_query = sql_query.strip().rstrip(";").rstrip()
309
+
310
+ if table_name is None and sql_query is None:
311
+ raise R2RMLParseError(
312
+ f"LogicalTable for {tm_uri} must have rr:tableName or rr:sqlQuery"
313
+ )
314
+
315
+ return LogicalTable(table_name=table_name, sql_query=sql_query,
316
+ sql_versions=sorted(str(v) for v in g.objects(lt_node, RR.sqlVersion)),
317
+ written=written.strip() if written is not None and '"' in written else None)
318
+
319
+ def _extract_subject_map(self, g: Graph, tm_uri: Node) -> SubjectMap:
320
+ # Check for shortcut rr:subject first
321
+ subject_shortcut = self._single_object(g, tm_uri, RR.subject)
322
+ if subject_shortcut is not None:
323
+ classes = [str(c) for c in g.objects(tm_uri, RR['class'])]
324
+ return SubjectMap(constant=str(subject_shortcut), classes=classes)
325
+
326
+ sm_node = self._single_object(g, tm_uri, RR.subjectMap)
327
+ if sm_node is None:
328
+ return SubjectMap()
329
+
330
+ template, column, constant = self._extract_term_map_value(g, sm_node)
331
+
332
+ # Term type
333
+ term_type_obj = self._single_object(g, sm_node, RR.termType)
334
+ term_type = 'IRI'
335
+ if term_type_obj is not None:
336
+ tt_str = str(term_type_obj)
337
+ if tt_str.endswith('BlankNode'):
338
+ term_type = 'BlankNode'
339
+ elif tt_str.endswith('Literal'):
340
+ # Kept so that the compile refuses it (R2RML 7.4: a subject
341
+ # is an IRI or a blank node); the bridge reads no subject's
342
+ # term type.
343
+ term_type = 'Literal'
344
+
345
+ # Classes (rr:class), multiple allowed
346
+ classes = [str(c) for c in g.objects(sm_node, RR['class'])]
347
+
348
+ # Graph maps on subject
349
+ graph_maps = self._extract_graph_maps(g, sm_node)
350
+
351
+ return SubjectMap(
352
+ template=template,
353
+ column=column,
354
+ constant=constant,
355
+ term_type=term_type,
356
+ classes=classes,
357
+ graph_maps=graph_maps,
358
+ )
359
+
360
+ def _extract_predicate_object_maps(
361
+ self, g: Graph, tm_uri: Node
362
+ ) -> List[PredicateObjectMap]:
363
+ result = []
364
+ for po_node in g.objects(tm_uri, RR.predicateObjectMap):
365
+ predicate_maps = self._extract_predicate_maps(g, po_node)
366
+ object_maps = self._extract_object_maps(g, po_node)
367
+ graph_maps = self._extract_graph_maps(g, po_node)
368
+ result.append(PredicateObjectMap(
369
+ predicate_maps=predicate_maps,
370
+ object_maps=object_maps,
371
+ graph_maps=graph_maps,
372
+ ))
373
+ return result
374
+
375
+ def _extract_predicate_maps(self, g: Graph, po_node: Node) -> List[PredicateMap]:
376
+ maps = []
377
+
378
+ # Shortcut: rr:predicate
379
+ for pred in g.objects(po_node, RR.predicate):
380
+ maps.append(PredicateMap(constant=str(pred)))
381
+
382
+ # Full form: rr:predicateMap
383
+ for pm_node in g.objects(po_node, RR.predicateMap):
384
+ template, column, constant = self._extract_term_map_value(g, pm_node)
385
+ maps.append(PredicateMap(
386
+ constant=str(constant) if constant else None,
387
+ column=column,
388
+ template=template,
389
+ ))
390
+
391
+ return maps
392
+
393
+ def _extract_object_maps(self, g: Graph, po_node: Node) -> List[ObjectMap]:
394
+ maps = []
395
+
396
+ # Shortcut: rr:object
397
+ for obj in g.objects(po_node, RR.object):
398
+ val = str(obj)
399
+ if isinstance(obj, Literal):
400
+ maps.append(ObjectMap(constant=val, term_type='Literal',
401
+ **self._constant_literal(obj)))
402
+ else:
403
+ maps.append(ObjectMap(constant=val, term_type='IRI'))
404
+
405
+ # Full form: rr:objectMap
406
+ for om_node in g.objects(po_node, RR.objectMap):
407
+ maps.append(self._extract_object_map(g, om_node))
408
+
409
+ return maps
410
+
411
+ def _extract_object_map(self, g: Graph, om_node: Node) -> ObjectMap:
412
+ template, column, constant = self._extract_term_map_value(g, om_node)
413
+
414
+ # Parent triples map (referencing object map)
415
+ parent_tm = self._single_object(g, om_node, RR.parentTriplesMap)
416
+ parent_tm_str = self._map_id(g, parent_tm) if parent_tm else None
417
+
418
+ # Join conditions
419
+ join_conditions = []
420
+ for jc_node in g.objects(om_node, RR.joinCondition):
421
+ child_written = self._literal_value(g, jc_node, RR.child)
422
+ parent_written = self._literal_value(g, jc_node, RR.parent)
423
+ child, parent = sql_identifier(child_written), sql_identifier(parent_written)
424
+ if child and parent:
425
+ if undelimited(child_written):
426
+ self._regular.add(child)
427
+ join_conditions.append(JoinCondition(child=child, parent=parent,
428
+ parent_regular=undelimited(parent_written)))
429
+
430
+ # Term type
431
+ term_type_obj = self._single_object(g, om_node, RR.termType)
432
+ if term_type_obj is not None:
433
+ tt_str = str(term_type_obj)
434
+ if tt_str.endswith('IRI'):
435
+ term_type = 'IRI'
436
+ elif tt_str.endswith('BlankNode'):
437
+ term_type = 'BlankNode'
438
+ else:
439
+ term_type = 'Literal'
440
+ elif parent_tm_str:
441
+ term_type = 'IRI'
442
+ elif constant is not None:
443
+ # R2RML 7.4: a constant-valued term map's term type is its
444
+ # constant's.
445
+ constant_node = self._single_object(g, om_node, RR.constant)
446
+ term_type = 'Literal' if isinstance(constant_node, Literal) else 'IRI'
447
+ elif template and not (self._single_object(g, om_node, RR.datatype)
448
+ or self._single_object(g, om_node, RR.language)):
449
+ # R2RML 7.4: an object map's term type is rr:Literal when it is
450
+ # column-valued or has rr:datatype or rr:language; rr:IRI
451
+ # otherwise.
452
+ term_type = 'IRI'
453
+ else:
454
+ term_type = 'Literal'
455
+
456
+ # Datatype and language
457
+ datatype_obj = self._single_object(g, om_node, RR.datatype)
458
+ datatype = str(datatype_obj) if datatype_obj else None
459
+
460
+ language_obj = self._single_object(g, om_node, RR.language)
461
+ language = str(language_obj) if language_obj else None
462
+ constant_node = self._single_object(g, om_node, RR.constant)
463
+ if isinstance(constant_node, Literal):
464
+ # A constant literal is that literal: its own datatype or tag.
465
+ said = self._constant_literal(constant_node)
466
+ datatype, language = said['datatype'], said['language']
467
+
468
+ return ObjectMap(
469
+ template=template,
470
+ column=column,
471
+ constant=constant,
472
+ parent_triples_map=parent_tm_str,
473
+ join_conditions=join_conditions,
474
+ term_type=term_type,
475
+ datatype=datatype,
476
+ language=language,
477
+ )
478
+
479
+ def _extract_graph_maps(self, g: Graph, subject: Node) -> List[GraphMap]:
480
+ maps = []
481
+
482
+ # Shortcut: rr:graph
483
+ for graph_uri in g.objects(subject, RR.graph):
484
+ maps.append(GraphMap(constant=str(graph_uri)))
485
+
486
+ # Full form: rr:graphMap
487
+ for gm_node in g.objects(subject, RR.graphMap):
488
+ template, column, constant = self._extract_term_map_value(g, gm_node)
489
+ term_type_obj = self._single_object(g, gm_node, RR.termType)
490
+ term_type = 'IRI'
491
+ if term_type_obj is not None:
492
+ tt_str = str(term_type_obj)
493
+ term_type = ('BlankNode' if tt_str.endswith('BlankNode')
494
+ else 'Literal' if tt_str.endswith('Literal') else 'IRI')
495
+ maps.append(GraphMap(
496
+ template=template,
497
+ column=column,
498
+ constant=str(constant) if constant else None,
499
+ term_type=term_type,
500
+ ))
501
+
502
+ return maps
503
+
504
+ # ------------------------------------------------------------------
505
+ # Helpers
506
+ # ------------------------------------------------------------------
507
+
508
+ def _extract_term_map_value(
509
+ self, g: Graph, node: Node
510
+ ) -> Tuple[Optional[str], Optional[str], Optional[str]]:
511
+ """Extract (template, column, constant) from a term map node."""
512
+ template_written = self._literal_value(g, node, RR.template)
513
+ column_written = self._literal_value(g, node, RR.column)
514
+ template = template_identifiers(template_written)
515
+ column = sql_identifier(column_written)
516
+ self._regular.update(undelimited_placeholders(template_written))
517
+ if undelimited(column_written):
518
+ self._regular.add(column)
519
+ constant_node = self._single_object(g, node, RR.constant)
520
+ constant = str(constant_node) if constant_node is not None else None
521
+ return template, column, constant
522
+
523
+ @staticmethod
524
+ def _constant_literal(lit: Literal) -> Dict[str, Optional[str]]:
525
+ """The datatype and language tag of a constant literal (R2RML 7.1:
526
+ the term map's value is that literal); an xsd:string is a simple
527
+ literal's datatype, and says none."""
528
+ from prograph.schema import xsd
529
+ datatype = str(lit.datatype) if lit.datatype is not None else None
530
+ if datatype == xsd.STRING:
531
+ datatype = None
532
+ return {"datatype": datatype,
533
+ "language": lit.language.lower() if lit.language else None}
534
+
535
+ def _single_object(self, g: Graph, s: Node, p: Node) -> Optional[Node]:
536
+ """Get a single object for (s, p, ?) or None."""
537
+ for o in g.objects(s, p):
538
+ return o
539
+ return None
540
+
541
+ def _literal_value(self, g: Graph, s: Node, p: Node) -> Optional[str]:
542
+ """Get a literal string value for (s, p, ?) or None."""
543
+ obj = self._single_object(g, s, p)
544
+ if obj is not None:
545
+ return str(obj)
546
+ return None
@@ -0,0 +1,120 @@
1
+ """An R2RML mapping as the engine holds it (docs/architecture/r2rml-without-the-bridge.md):
2
+ its source maps, compiled straight from the document (`compile.compile_r2rml`), and the engine-side
3
+ state a `GraphSchema` carries (column types, constraints, table stats, defaults, prefixes, the base
4
+ IRI). It has no property-graph view: an API that reads node or relationship mappings gets
5
+ `PropertyGraphViewError`, naming a YAML mapping as the way out."""
6
+
7
+ from __future__ import annotations
8
+
9
+ from typing import Any, Dict, Optional
10
+
11
+ from prograph.schema.mapping import GraphSchema
12
+
13
+
14
+ class PropertyGraphViewError(NotImplementedError):
15
+ """An R2RML mapping has no property-graph view in ProGraph 1.0 (node and relationship mappings,
16
+ labels): Cypher, OWL RL, SHACL validation, GraphQL and `set_properties` read
17
+ one (`require_property_graph`)."""
18
+
19
+ def __init__(self, what: str = "node and relationship mappings") -> None: # noqa: D107
20
+ super().__init__(
21
+ f"{what} needs a YAML mapping (an R2RML mapping has no property-graph view): query it with "
22
+ f"SPARQL, or map the tables in YAML")
23
+
24
+
25
+ class PrefixClashWarning(UserWarning):
26
+ """An included R2RML document binds a prefix the YAML binds to another namespace."""
27
+
28
+
29
+ class R2RMLSchema(GraphSchema):
30
+ """An R2RML mapping's schema: `source_maps()` from the document, no property-graph view."""
31
+
32
+ def __init__(self, r2rml: Any, base_iri: Optional[str] = None,
33
+ prefix_map: Optional[Dict[str, str]] = None, **kwargs: Any) -> None:
34
+ super().__init__(**kwargs)
35
+ base = r2rml.base or base_iri or self.base_iri
36
+ # What the one plan compiles (`entry.source_maps`): the document and its base IRI (R2RML 7.3).
37
+ self.__dict__["r2rml_source"] = (r2rml, base)
38
+ prefixes = dict(r2rml.prefixes)
39
+ prefixes.update(prefix_map or {})
40
+ for prefix, ns in prefixes.items():
41
+ self.add_prefix(prefix, ns)
42
+
43
+ # No property-graph view: the node and relationship mappings stay empty, so GraphSchema's own
44
+ # helpers see none, and an API that needs them refuses (`require_property_graph`).
45
+ property_graph = False
46
+
47
+ def source_maps(self):
48
+ from prograph.plan.ir.entry import source_maps
49
+ return source_maps(self)
50
+
51
+
52
+ def include(schema: Any, r2rml: Any) -> None:
53
+ """A YAML or Python schema that includes an R2RML document (`rdf.r2rml`): its
54
+ triples maps join the schema's source maps (`with_included`), with no property-graph labels;
55
+ the document's prefixes are the schema's too."""
56
+ schema.__dict__["included_r2rml"] = (r2rml, r2rml.base or schema.base_iri)
57
+ import warnings
58
+ held = dict(schema.prefixes or {})
59
+ for prefix, ns in r2rml.prefixes.items():
60
+ if prefix not in held:
61
+ schema.add_prefix(prefix, ns)
62
+ elif held[prefix] != ns:
63
+ warnings.warn(f"the included R2RML document binds {prefix}: to <{ns}>, the YAML to <{held[prefix]}>: "
64
+ f"the YAML's is kept", PrefixClashWarning, stacklevel=2)
65
+
66
+
67
+ def with_included(schema: Any, maps: Any) -> Any:
68
+ """`maps` (the schema's own), its included R2RML document's, and its owned store's generated maps
69
+ (`prograph.store.Store.attach`), one set: each after the ones before, so a mapping's position is its
70
+ map's. A map id two of them name is refused; maps may share subjects, as triples maps of one
71
+ document do (R2RML 6), each giving its triples."""
72
+ from prograph.r2rml.compile import R2RMLMappingError, compile_r2rml
73
+ from prograph.schema.source_map import with_decimal_text
74
+ setting = getattr(schema, "decimal_text", None)
75
+ maps = with_decimal_text(maps, setting) # the schema's `decimal_text`, for every map it holds
76
+ included = schema.__dict__.get("included_r2rml")
77
+ store = schema.__dict__.get("owned_store")
78
+ own: frozenset = frozenset()
79
+ for name, extra in (("the included R2RML document",
80
+ with_decimal_text(compile_r2rml(*included), setting) if included else None),
81
+ ("the owned store", store.source_maps() if store is not None else None)):
82
+ if extra is None:
83
+ continue
84
+ clash = {m.id for m in maps.nodes + maps.edges} & {m.id for m in extra.nodes + extra.edges}
85
+ if clash:
86
+ raise R2RMLMappingError(f"{name} and the schema both name {sorted(clash)}")
87
+ maps = maps.joined(extra)
88
+ if store is not None and name == "the owned store":
89
+ own = frozenset(m.id for m in extra.nodes + extra.edges)
90
+ # The store's columns are its own (text, `Store._create`): its query sources are typed here,
91
+ # since they appear after the engine read its tables' types.
92
+ from prograph.schema import types as T
93
+ for source in extra.tables():
94
+ schema.column_types.setdefault(source.table, {
95
+ c: T.of_sql_type("VARCHAR") for c in ("graph", "subject", "o_text")})
96
+ if store is not None:
97
+ # The property-graph view reads the store through its generic maps (`lpg_view.build`), not these.
98
+ if not own:
99
+ from dataclasses import replace
100
+ maps = replace(maps) # a copy to mark: the schema's own maps stay unmarked
101
+ maps.__dict__["owned_store"] = (store, schema.column_types, own)
102
+ return maps
103
+
104
+
105
+ def store_version(schema: Any) -> Any:
106
+ """The attached owned store's version, for a cache of the joined maps (`with_included`)."""
107
+ store = schema.__dict__.get("owned_store")
108
+ return None if store is None else (id(store), store.version, store.view_key)
109
+
110
+
111
+ def require_property_graph(schema: Any, what: str) -> None:
112
+ """Refuse `what` over a schema with no property-graph view (an R2RML mapping)."""
113
+ if getattr(schema, "property_graph", True) is False:
114
+ raise PropertyGraphViewError(what)
115
+
116
+
117
+ def load(text: str, base_iri: Optional[str] = None, format: str = "turtle", **kwargs: Any) -> R2RMLSchema:
118
+ """An R2RML document's text (`format` as rdflib reads it) as the engine's schema."""
119
+ from prograph.r2rml.parser import R2RMLParser
120
+ return R2RMLSchema(R2RMLParser().parse(text, format=format), base_iri, **kwargs)