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,1103 @@
1
+ """Source maps: which rows give which RDF terms.
2
+
3
+ The one home of that rule (docs/architecture/rules.md, "Which rows give
4
+ which RDF terms"). A source map says, for one source (a table, or a query,
5
+ and a row filter), how each row becomes RDF terms: its subject, its
6
+ classes, the literal or IRI objects of its predicates (a node map), or the
7
+ one triple each row of a relationship source gives (an edge map, whose
8
+ rows have no key: each row is one edge). The shapes follow R2RML's
9
+ triples maps (R2RML 6 and 7, "term maps"), so that an R2RML mapping can be
10
+ compiled to them directly (`prograph.r2rml.compile.compile_r2rml`) as a YAML or Python schema
11
+ is (`prograph.schema.compile_schema`).
12
+
13
+ Everything here is frozen and holds no reference to the schema or its
14
+ mappings: a `SourceMaps` is a snapshot of one schema version
15
+ (`GraphSchema.source_maps`), so a later change to a mapping cannot change
16
+ maps already compiled; the schema compiles new ones.
17
+
18
+ Statistics and column types stay on the schema (`get_table_stats`,
19
+ `column_type`).
20
+
21
+ The SPARQL compiler reads node identity
22
+ (`subject_identity_of`), the subjects two maps may share (`SourceMaps.
23
+ partners`) and an edge's triple identity (`SourceMaps.triple_identity`)
24
+ here.
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ import functools
30
+ import re
31
+ from dataclasses import dataclass, field, replace
32
+ from typing import Any, Dict, List, NamedTuple, Optional, Sequence, Set, Tuple, Union
33
+ from prograph.rules import home, module_home
34
+
35
+ module_home("source-maps", "Which rows give which RDF terms (source maps)",
36
+ terms=("source map", "TermMap", "NodeMap", "EdgeMap", "subject identity", "term map", "R2RML mapping"))
37
+
38
+ module_home("subject-grouped-by-iri", "A subject grouped by its IRI (SPARQL)",
39
+ terms=("GROUP BY", "COUNT(DISTINCT)", "iri_valued", "subject IRI", "aggregate"))
40
+
41
+ # A term map's term type (R2RML 7.4, rr:termType).
42
+ IRI = "iri"
43
+ BLANK = "blank"
44
+ LITERAL = "literal"
45
+ _TERM_TYPES = (IRI, BLANK, LITERAL)
46
+
47
+ # R2RML 6.4: a graph map whose constant is rr:defaultGraph puts its triples
48
+ # in the default graph.
49
+ RR_DEFAULT_GRAPH = "http://www.w3.org/ns/r2rml#defaultGraph"
50
+
51
+ # How a column's value becomes the text of a term: ProGraph's (# the value's str(), IRI-safe in a template) or R2RML's natural RDF lexical
52
+ # form (R2RML 10.2), for maps compiled from R2RML in step 2.
53
+ LEXICAL_PROGRAPH = "prograph"
54
+ LEXICAL_R2RML = "r2rml"
55
+
56
+ # How a DECIMAL column's value is written into a term, a literal's text or an IRI's (the schema's
57
+ # `decimal_text`, sparql-choices.md D3): XML Schema 1.1's canonical form (`1`, `1.5`), the default;
58
+ # or the database's own text (`1.0`, `1.50`), as Ontop writes it.
59
+ DECIMAL_CANONICAL = "canonical"
60
+ DECIMAL_DATABASE = "database"
61
+ DECIMAL_TEXTS = (DECIMAL_CANONICAL, DECIMAL_DATABASE)
62
+ # The reader (a dialect function) a DECIMAL column is read through under `decimal_text: database`.
63
+ DATABASE_DECIMAL_TEXT = "DATABASE_DECIMAL_TEXT"
64
+ # The readers of a uuid column (rule uuid-text): its text, lower case or (SQL Server) upper case. A string
65
+ # read so still compares as its bytes, on the native column (`lower.eq`).
66
+ UUID_READERS = ("UUID_TEXT", "UUID_TEXT_UPPER")
67
+
68
+
69
+ def decimal_text_setting(value: Any) -> str:
70
+ """A schema's `decimal_text`, checked: `canonical` (None too) or `database`."""
71
+ if value is None:
72
+ return DECIMAL_CANONICAL
73
+ if value not in DECIMAL_TEXTS:
74
+ raise ValueError(f"decimal_text must be one of {DECIMAL_TEXTS}; got {value!r}")
75
+ return value
76
+
77
+ # A run of a template: (text, is_column), as `prograph.schema.iri.template_parts`.
78
+ TemplateParts = Tuple[Tuple[str, bool], ...]
79
+ # Name -> value pairs in their authored order, a dict made immutable.
80
+ Pairs = Tuple[Tuple[Any, Any], ...]
81
+
82
+
83
+ def _sorted_filter(pairs: Optional[Pairs]) -> Pairs:
84
+ """A row filter in a form two equal filters share, whatever their
85
+ authored order: the key every identity reads it by."""
86
+ return tuple(sorted(pairs or (), key=str))
87
+
88
+
89
+ @dataclass(frozen=True)
90
+ class TermMap:
91
+ """How a row gives one RDF term (R2RML 7, "term maps"; the term constructors of the source-map design).
92
+
93
+ Exactly one of `template`, `column` and `constant` is set. In a map
94
+ compiled from a YAML or Python schema, a template of one placeholder
95
+ and no literal text is column-valued (R2RML's rr:column;
96
+ `prograph.schema.iri.is_column_valued`): it is held as `column`, the
97
+ column holding the whole term. A map compiled from R2RML keeps such a
98
+ template a template (`lexical` `LEXICAL_R2RML`): R2RML 7.3 makes a
99
+ template's value IRI-safe and a column's not, so `{Name}` and
100
+ rr:column "Name" give different IRIs from one value.
101
+
102
+ Attributes:
103
+ term_type: `IRI`, `BLANK` or `LITERAL`.
104
+ template: The template's runs, `template_parts` form.
105
+ column: The column whose value is the term (rr:column).
106
+ constant: The term itself (rr:constant).
107
+ datatype: A literal's datatype IRI, when declared.
108
+ language: A literal's fixed language tag.
109
+ language_column: The column a literal's per-row language tag is
110
+ read from (ProGraph's own; R2RML has none).
111
+ synthesized: A YAML or Python node with no `iri_template`, whose
112
+ subject is `{base_iri}{source_table}/{k1}/{k2}`. It mints the
113
+ same terms as the template it is held as; it says that the
114
+ schema wrote none (the round trip, `compile_schema.project`),
115
+ and, for now, that its subject's
116
+ identity is its key (`subject_identity_of`).
117
+ lexical: How a value becomes text (`LEXICAL_PROGRAPH`, or
118
+ `LEXICAL_R2RML`, R2RML 10.2: the value's natural RDF lexical
119
+ form, IRI-safe in an IRI template's placeholder, a relative IRI
120
+ resolved against the mapping's base IRI, `Settings.base_iri`).
121
+ """
122
+ term_type: str
123
+ template: Optional[TemplateParts] = None
124
+ column: Optional[str] = None
125
+ constant: Optional[str] = None
126
+ datatype: Optional[str] = None
127
+ language: Optional[str] = None
128
+ language_column: Optional[str] = None
129
+ synthesized: bool = False
130
+ lexical: str = LEXICAL_PROGRAPH
131
+
132
+ def __post_init__(self) -> None:
133
+ if self.term_type not in _TERM_TYPES:
134
+ raise ValueError(f"term_type must be one of {_TERM_TYPES}; got {self.term_type!r}")
135
+ given = [x is not None for x in (self.template, self.column, self.constant)]
136
+ if sum(given) != 1:
137
+ raise ValueError("a term map has exactly one of a template, a column and a constant")
138
+ if self.term_type != LITERAL and (self.datatype or self.language or self.language_column):
139
+ raise ValueError("only a literal term map has a datatype or a language")
140
+
141
+ def columns(self) -> Tuple[str, ...]:
142
+ """The columns the term is built from, in order of appearance."""
143
+ if self.template is not None:
144
+ return tuple(text for text, is_column in self.template if is_column)
145
+ if self.column is not None:
146
+ return (self.column,)
147
+ return ()
148
+
149
+ def shape(self) -> Tuple[Optional[str], ...]:
150
+ """The term's literal runs, None at each placeholder: two term maps
151
+ of one shape write their terms the same way around their values."""
152
+ if self.template is not None:
153
+ return tuple(None if is_column else text for text, is_column in self.template)
154
+ if self.column is not None:
155
+ return (None,)
156
+ return (self.constant,)
157
+
158
+ def prefix(self) -> str:
159
+ """The text every term of the map starts with: the template's
160
+ before its first placeholder, a constant whole, a column's none."""
161
+ if self.constant is not None:
162
+ return self.constant
163
+ if self.template and not self.template[0][1]:
164
+ return self.template[0][0]
165
+ return ""
166
+
167
+ def mints(self) -> Tuple[Any, ...]:
168
+ """What decides the terms the map gives a row: everything but
169
+ `synthesized`, which records only how the schema spelled it."""
170
+ return (self.term_type, self.template, self.column, self.constant, self.datatype,
171
+ self.language, self.language_column, self.lexical)
172
+
173
+ def may_equal(self, other: "TermMap") -> bool:
174
+ """Whether a term of this map and one of `other` can be one term:
175
+ of one term type (RDF 1.1 Concepts 3.4: a blank node is never an
176
+ IRI, and neither is a literal), with neither prefix ruling the other
177
+ out, and, for two IRI templates (or constants) that write text around their values, with
178
+ their runs of text able to line up (`_iri_runs_meet`: values are IRI-safe, so a character
179
+ `IRI_SAFE_ENCODING` encodes stands in no value and cuts a term into runs)."""
180
+ if self.term_type != other.term_type:
181
+ return False
182
+ if self.relative_iri() or other.relative_iri():
183
+ # A relative R2RML IRI is resolved against the base only when
184
+ # lowered: its prefix says nothing yet (fresh review, 2026-11-09).
185
+ return True
186
+ first, second = self.prefix(), other.prefix()
187
+ if not (first.startswith(second) or second.startswith(first)):
188
+ return False
189
+ return _iri_runs_meet(self, other)
190
+
191
+ def relative_iri(self) -> bool:
192
+ """An R2RML IRI map whose fixed prefix has no scheme: its terms are
193
+ resolved against the base IRI (R2RML 7.3) when lowered."""
194
+ if self.term_type != IRI or self.lexical != LEXICAL_R2RML or self.constant is not None:
195
+ return False
196
+ from prograph.schema.iri import IRI_SCHEME
197
+ return not IRI_SCHEME.match(self.prefix())
198
+
199
+ def one_term_per_values(self, integer_values: bool = False) -> bool:
200
+ """Whether the map is injective: two different tuples of values of
201
+ its columns (`columns`) never give one term, so a term names its
202
+ values and a key of those values is a key of the terms.
203
+
204
+ A constant reads no column and a column-valued map its one column
205
+ as the whole term. A template of one placeholder adds fixed text
206
+ around one value. A template of several placeholders is injective
207
+ only where each value can be cut out of the term: an IRI template
208
+ whose values are IRI-safe (R2RML 7.3, `prograph.schema.iri.
209
+ iri_safe`, which leaves only `iunreserved` characters and `%`
210
+ escapes) and where each pair of placeholders is kept apart by text
211
+ holding a character no IRI-safe value holds (`http://x/{a}/{b}`;
212
+ not `{a}{b}`, nor `{a}-{b}`, '-' being `iunreserved`). A literal or
213
+ blank-node template puts values in as they are (R2RML 7.3), so it
214
+ is injective with one placeholder only. Assumes, as every rule
215
+ over a column does, that a column's values have one type, whose
216
+ texts differ where the values do.
217
+
218
+ An R2RML IRI map whose rows may be absolute or relative IRIs is not injective: a relative
219
+ value is prepended the base IRI (R2RML 7.3, `plan.ir.lower.absolute`), so `x` and
220
+ `http://base/x` are one IRI (M2 review R1).
221
+
222
+ With `integer_values` (every placeholder reads an integer column, `slot.held_as_values`): an
223
+ integer's text is an optional `-` and digits, ended by its first non-digit, so text between
224
+ placeholders that starts with a non-digit cuts the values apart (`{a}_{b}`, `{a}-{b}`)."""
225
+ if self.term_type == IRI and self.lexical == LEXICAL_R2RML and self.constant is None:
226
+ import re
227
+ from prograph.schema.iri import IRI_SCHEME
228
+ prefix = self.prefix()
229
+ if not IRI_SCHEME.match(prefix) and (not prefix or re.fullmatch(r"[A-Za-z][A-Za-z0-9+.-]*", prefix)):
230
+ return False # each row tested for a scheme: two values may meet
231
+ if self.template is None:
232
+ return True
233
+ if sum(1 for _, is_column in self.template if is_column) <= 1:
234
+ return True
235
+ if self.term_type != IRI:
236
+ return False
237
+ from prograph.schema.iri import IRI_TEMPLATE_CUT as cut
238
+ between: Optional[str] = None
239
+ for text, is_column in self.template:
240
+ if is_column:
241
+ if between is not None and integer_values:
242
+ if not between or between[0] in "0123456789":
243
+ return False
244
+ elif between is not None and not (set(between) & cut):
245
+ return False
246
+ between = ""
247
+ elif between is not None:
248
+ between += text
249
+ return True
250
+
251
+ def text(self) -> Optional[str]:
252
+ """The template text the map was written as (`{column}` at each
253
+ placeholder), a column's `{column}`; None for a constant."""
254
+ if self.template is not None:
255
+ return "".join("{" + text + "}" if is_column else text
256
+ for text, is_column in self.template)
257
+ if self.column is not None:
258
+ return "{" + self.column + "}"
259
+ return None
260
+
261
+
262
+
263
+ def _iri_runs(m: "TermMap") -> Optional[Tuple[Tuple[str, ...], ...]]:
264
+ """An IRI map's terms cut at every character an IRI-safe value cannot hold (`IRI_SAFE_ENCODING`
265
+ but '%', which an escape starts): one list per run, holding the text between its placeholders
266
+ (one string for a run with none). None where the cut is not known: a map not of a constant or
267
+ of a template with text around its values (a column holds a whole IRI as it is, R2RML 6.3)."""
268
+ if m.term_type != IRI:
269
+ return None
270
+ if m.constant is not None:
271
+ parts: Sequence[Tuple[str, bool]] = ((m.constant, False),)
272
+ elif m.template is not None and any(not is_column for _, is_column in m.template):
273
+ parts = tuple(m.template)
274
+ else:
275
+ return None
276
+ return _runs_of(tuple(parts))
277
+
278
+
279
+ @functools.lru_cache(maxsize=8192)
280
+ def _runs_of(parts: Tuple[Tuple[str, bool], ...]) -> Tuple[Tuple[str, ...], ...]:
281
+ """`_iri_runs` of a template's parts (or a constant's one part), kept: a map's runs are read for
282
+ every pair of maps a plan compares."""
283
+ from prograph.schema.iri import IRI_TEMPLATE_CUT as cut
284
+ runs: List[List[str]] = [[""]]
285
+ for text, is_column in parts:
286
+ if is_column:
287
+ runs[-1].append("")
288
+ continue
289
+ for ch in text:
290
+ if ch in cut:
291
+ runs[-1][-1] += ch # the cut character ends the run, as its last text
292
+ runs.append([""])
293
+ else:
294
+ runs[-1][-1] += ch
295
+ return tuple(tuple(r) for r in runs)
296
+
297
+
298
+ def _iri_runs_meet(a: "TermMap", b: "TermMap") -> bool:
299
+ """Whether the runs of two IRI maps (`_iri_runs`) can line up into one term. Each cut
300
+ character is written by the template's own text, never by a value, so two terms are one only
301
+ with as many runs, each pair compatible: two runs of plain text equal; plain text against a run
302
+ with values starting and ending as that text does, long enough for both; two runs with values
303
+ starting alike (one's first text a prefix of the other's) and ending alike. True where unknown."""
304
+ ra, rb = _iri_runs(a), _iri_runs(b)
305
+ if ra is None or rb is None:
306
+ return True
307
+ if len(ra) != len(rb):
308
+ return False
309
+ for x, y in zip(ra, rb):
310
+ if len(x) == 1 and len(y) == 1:
311
+ if x[0] != y[0]:
312
+ return False
313
+ elif len(x) == 1 or len(y) == 1:
314
+ plain, mixed = (x[0], y) if len(x) == 1 else (y[0], x)
315
+ if not (plain.startswith(mixed[0]) and plain.endswith(mixed[-1])
316
+ and len(plain) >= len(mixed[0]) + len(mixed[-1])):
317
+ return False
318
+ else:
319
+ if not (x[0].startswith(y[0]) or y[0].startswith(x[0])):
320
+ return False
321
+ if not (x[-1].endswith(y[-1]) or y[-1].endswith(x[-1])):
322
+ return False
323
+ return True
324
+
325
+
326
+ def graphs_of(graph_maps: Tuple["TermMap", ...], graph: Optional[str]) -> Tuple["TermMap", ...]:
327
+ """The graph maps a triple is in (R2RML 11.1): an R2RML triple's `graph_maps`, or a YAML or
328
+ Python schema's `graph` (its `graph_iri`) as one constant IRI map; () for the default graph
329
+ alone."""
330
+ return (TermMap(IRI, constant=graph),) if graph else tuple(graph_maps)
331
+
332
+ @dataclass(frozen=True)
333
+ class Source:
334
+ """The rows a map reads: a table or a query, and a row filter.
335
+
336
+ Attributes:
337
+ table: The source table's name as authored (`source_table`); for a
338
+ query, its name, the key of its frame on a DataFrame backend.
339
+ qualified: The name SQL reads it by, through the schema's settings
340
+ (`TableMapping.qualified_source_table`), at the version the
341
+ maps were compiled from.
342
+ query: A SQL query whose result is the source (an R2RML view,
343
+ rr:sqlQuery), or None.
344
+ filter: The row filter's (column, value) pairs in authored order; a
345
+ value of None is the rows with no value there. None where the
346
+ schema gave no filter; `()` for an empty one.
347
+ """
348
+ table: str
349
+ qualified: str
350
+ query: Optional[str] = None
351
+ filter: Optional[Pairs] = None
352
+ regular_columns: frozenset = frozenset()
353
+ """The columns an R2RML mapping names undelimited, which the database folds
354
+ (`Dialect.fold_identifier`); every other name is exact (YAML's all are)."""
355
+
356
+ def filter_key(self) -> Pairs:
357
+ return _sorted_filter(self.filter)
358
+
359
+ @home("source-rows-within", "Every row one source reads is a row another reads",
360
+ terms=("rows within", "same table", "row filter", "filter within", "one source row", "SAME_TABLE",
361
+ "sqlQuery rows", "equal query text", "simple select"))
362
+ def rows_within(self, other: "Source", folds: bool = True) -> bool:
363
+ """Whether every row this source reads is a row `other` reads. A
364
+ table against a table: the same qualified name (both folding the
365
+ same columns) and `other`'s row filter, a conjunction of (column,
366
+ value) equalities, among this one's; a source is within itself. A
367
+ query against a query: only the same text (R2RML 8: one text, one
368
+ effective query), the same columns folded and `other`'s filter among
369
+ this one's; two texts are never compared. A query against a table:
370
+ where the query is a plain select of that one table (`simple_select`:
371
+ its WHERE only drops rows, so its rows are rows of the table, the
372
+ table's columns the query's projection); never a table within a
373
+ query. `mapping.rows_within` is the authoring mappings' question of
374
+ one node, which adds the key and the IRI. The columns folded must be
375
+ the same (`folds`), unless the caller compares the columns it reads
376
+ (`rewrite._one_source`: the maps of one query text name only theirs)."""
377
+ if folds and self.regular_columns != other.regular_columns:
378
+ return False
379
+ if self.query is None and other.query is None:
380
+ if self.qualified != other.qualified:
381
+ return False
382
+ elif self.query is not None and other.query is not None:
383
+ if self.query != other.query:
384
+ return False
385
+ elif self.query is not None:
386
+ shape = simple_select(self.query)
387
+ if shape is None or other.filter_key() or not same_table_name(shape.table, other.qualified):
388
+ return False
389
+ else:
390
+ return False
391
+ return set(other.filter_key()) <= set(self.filter_key())
392
+
393
+
394
+ class SimpleSelect(NamedTuple):
395
+ """A query that is one table's rows, some dropped: `table` as written
396
+ (dotted, parts in their quotes), the `columns` it projects (None: all
397
+ of the table's, `*` or `t.*`)."""
398
+ table: str
399
+ columns: Optional[Tuple[str, ...]]
400
+
401
+
402
+ _SELECT_WORD = re.compile(r"[A-Za-z_][A-Za-z_0-9$]*")
403
+ # Words that make a query not a row filter of one table: another table, a regrouping, a
404
+ # row count, a set operation, a window, a sample, or a value that changes between two reads.
405
+ _NOT_A_FILTER = frozenset(
406
+ "JOIN GROUP HAVING WINDOW QUALIFY LIMIT OFFSET FETCH TOP UNION INTERSECT EXCEPT MINUS ORDER OVER "
407
+ "INTO DISTINCT ALL LATERAL PIVOT UNPIVOT TABLESAMPLE SAMPLE RANDOM RAND UUID NEWID GEN_RANDOM_UUID "
408
+ "SYSDATE CONNECT START WITH RETURNING FOR".split())
409
+
410
+
411
+ def _select_tokens(text: str) -> Optional[List[Tuple[str, str, int]]]:
412
+ """`text` as (kind, token, depth) with kind 'w' (a bare word), 'q' (a quoted name, its text without the
413
+ quotes), 's' (a string or number), 'p' (one punctuation mark); None where a comment, a `;`, a quote that
414
+ never closes or parentheses that do not balance make it not worth reading."""
415
+ out: List[Tuple[str, str, int]] = []
416
+ i, depth, n = 0, 0, len(text)
417
+ while i < n:
418
+ c = text[i]
419
+ if c.isspace():
420
+ i += 1
421
+ elif c in "\"`":
422
+ j = i + 1
423
+ while True:
424
+ j = text.find(c, j)
425
+ if j < 0:
426
+ return None
427
+ if text[j + 1:j + 2] == c:
428
+ j += 2
429
+ continue
430
+ break
431
+ out.append(("q", text[i + 1:j].replace(c + c, c), depth))
432
+ i = j + 1
433
+ elif c == "'":
434
+ j = i + 1
435
+ while True:
436
+ j = text.find("'", j)
437
+ if j < 0:
438
+ return None
439
+ if text[j + 1:j + 2] == "'":
440
+ j += 2
441
+ continue
442
+ break
443
+ out.append(("s", text[i:j + 1], depth))
444
+ i = j + 1
445
+ elif c == "[":
446
+ return None # a bracket-quoted name or an array: not read
447
+ elif c.isalpha() or c == "_":
448
+ m = _SELECT_WORD.match(text, i)
449
+ out.append(("w", m.group(0), depth))
450
+ i = m.end()
451
+ elif c.isdigit():
452
+ m = re.compile(r"[0-9][0-9A-Za-z_.]*").match(text, i)
453
+ out.append(("s", m.group(0), depth))
454
+ i = m.end()
455
+ else:
456
+ if c in ";\\" or text.startswith("--", i) or text.startswith("/*", i):
457
+ return None
458
+ if c == "(":
459
+ depth += 1
460
+ elif c == ")":
461
+ depth -= 1
462
+ if depth < 0:
463
+ return None
464
+ out.append(("p", c, depth if c != "(" else depth - 1))
465
+ i += 1
466
+ return out if depth == 0 else None
467
+
468
+
469
+ def simple_select(query: str) -> Optional[SimpleSelect]:
470
+ """`query` as `SELECT <* | t.* | plain columns> FROM <table> [AS] [alias] [WHERE ...]` and nothing else,
471
+ or None. The WHERE may hold subqueries (EXISTS, IN): it only drops rows, so the rows are the table's own,
472
+ each once, and a key of the table holds on them where the projection keeps its columns. Any join, grouping,
473
+ DISTINCT, window, LIMIT, ORDER BY, set operation, expression or renamed column, or a function whose value
474
+ differs between reads (anywhere, subqueries too), is None."""
475
+ toks = _select_tokens(query)
476
+ if not toks or any(k == "w" and t.upper() in _NOT_A_FILTER for k, t, _ in toks):
477
+ return None
478
+ top = [(k, t) for k, t, d in toks if d == 0]
479
+ if len(top) < 4 or top[0] != ("w", top[0][1]) or top[0][1].upper() != "SELECT":
480
+ return None
481
+ try:
482
+ at = next(i for i, (k, t) in enumerate(top) if k == "w" and t.upper() == "FROM")
483
+ except StopIteration:
484
+ return None
485
+ columns: Optional[List[str]] = []
486
+ items: List[List[Tuple[str, str]]] = [[]]
487
+ for kt in top[1:at]:
488
+ if kt == ("p", ","):
489
+ items.append([])
490
+ else:
491
+ items[-1].append(kt)
492
+ for item in items:
493
+ if item and item[-1] == ("p", "*") and (len(item) == 1 or (len(item) == 3 and item[1] == ("p", ".")
494
+ and item[0][0] in "wq")):
495
+ columns = None
496
+ elif item and item[-1][0] in "wq" and (len(item) == 1 or (len(item) == 3 and item[1] == ("p", ".")
497
+ and item[0][0] in "wq")) \
498
+ and not (item[-1][0] == "w" and item[-1][1].upper() in ("AS", "CASE", "NULL", "NOT")):
499
+ if columns is not None:
500
+ columns.append(item[-1][1])
501
+ else:
502
+ return None
503
+ rest = top[at + 1:]
504
+ parts: List[str] = []
505
+ j = 0
506
+ while j < len(rest) and rest[j][0] in "wq":
507
+ parts.append(rest[j][1] if rest[j][0] == "w" else '"' + rest[j][1].replace('"', '""') + '"')
508
+ j += 1
509
+ if j < len(rest) and rest[j] == ("p", ".") and j + 1 < len(rest) and rest[j + 1][0] in "wq":
510
+ j += 1
511
+ continue
512
+ break
513
+ if not parts or len(parts) > 3:
514
+ return None
515
+ if j < len(rest) and rest[j][0] == "w" and rest[j][1].upper() == "AS":
516
+ j += 1
517
+ if j >= len(rest) or rest[j][0] not in "wq":
518
+ return None
519
+ j += 1
520
+ elif j < len(rest) and rest[j][0] in "wq" and not (rest[j][0] == "w" and rest[j][1].upper() == "WHERE"):
521
+ j += 1
522
+ if j < len(rest) and not (rest[j][0] == "w" and rest[j][1].upper() == "WHERE"):
523
+ return None
524
+ return SimpleSelect(".".join(parts), None if columns is None else tuple(columns))
525
+
526
+
527
+ def same_table_name(written: str, qualified: str) -> bool:
528
+ """Whether a table written in a query (`simple_select`) and a source's qualified name are one table: the
529
+ same parts, a part compared as written or, where one is bare and the other quoted, only as lower-case text
530
+ (a bare name the database folds to lower case: DuckDB, PostgreSQL, Databricks; one that folds to upper
531
+ case makes the two names two tables, which the mapping's author must not write)."""
532
+ def parts(name: str) -> List[Tuple[str, bool]]:
533
+ out = []
534
+ for m in re.finditer(r'"((?:[^"]|"")*)"|`((?:[^`]|``)*)`|([^.\s"`]+)', name):
535
+ q1, q2, bare = m.groups()
536
+ out.append(((q1 or "").replace('""', '"') if q1 is not None else
537
+ (q2 or "").replace("``", "`") if q2 is not None else bare, bare is None))
538
+ return out
539
+ a, b = parts(written), parts(qualified)
540
+ if len(a) != len(b) or not a:
541
+ return False
542
+ for (x, qx), (y, qy) in zip(a, b):
543
+ if x != y or (qx != qy and x != x.lower()):
544
+ return False
545
+ return True
546
+
547
+
548
+ def constant_term(term_type: str, text: str, datatype: Optional[str] = None,
549
+ language: Optional[str] = None) -> TermMap:
550
+ """A term written in a query (an IRI, a blank node's label, a literal's
551
+ lexical form) as the constant term map that gives it: how the one plan
552
+ states where a constant's term comes from (`TermSlot.provenance`), so
553
+ that `TermMap.may_equal` compares it with a map's terms."""
554
+ return TermMap(term_type=term_type, constant=text,
555
+ datatype=datatype if term_type == LITERAL else None,
556
+ language=language if term_type == LITERAL else None)
557
+
558
+
559
+ def identity_table(source: "Source") -> str:
560
+ """The table part of an element's identity (elementId()): the name a
561
+ table is written by as authored, for a query its mapping's name (not
562
+ its whole text); otherwise the name SQL reads it by."""
563
+ return source.table if source.query else source.qualified
564
+
565
+
566
+ @dataclass(frozen=True)
567
+ class Key:
568
+ """A node source's key: the columns that name one row.
569
+
570
+ Attributes:
571
+ columns: The key's columns, a composite key whole (never cut to its
572
+ first column).
573
+ stated: Whether the key is a stated key, one row per node, which an
574
+ optimization may rely on (`NodeMapping.key_stated`; False for an
575
+ R2RML subject template's columns, which state identity, not
576
+ uniqueness: rules.md "Keys an optimization relies on").
577
+ listed: Whether the schema wrote the key as a list (`id_column=['a']`)
578
+ rather than a column name: the authored spelling, for the round
579
+ trip only.
580
+ trust: Whether a plan may rely on the key (`NodeMapping.keys`):
581
+ 'trusted', 'check', or None (`prograph.node_keys.trusted_keys`).
582
+ on_duplicate: What a Cypher statement does with a key the data
583
+ breaks (`NodeMapping.on_duplicate`, `prograph.node_keys`); None
584
+ is the engine's default.
585
+ """
586
+ columns: Tuple[str, ...]
587
+ stated: bool = True
588
+ listed: bool = False
589
+ on_duplicate: Optional[str] = None
590
+ trust: Optional[str] = None
591
+
592
+
593
+ @dataclass(frozen=True)
594
+ class PredicateObject:
595
+ """One predicate a node map's rows give, and its literal object (R2RML
596
+ 6.3). From R2RML, an IRI or blank-node object is an edge map's end
597
+ (`EdgeMap`, its end's `EndRef.exists` False): a triple between two
598
+ terms, as a relationship's is.
599
+
600
+ Not `prograph.r2rml.model.PredicateObjectMap`, the parsed R2RML
601
+ construct, which pairs several predicate maps with several object maps:
602
+ a compiled one is one predicate and one object.
603
+
604
+ Attributes:
605
+ predicate: The predicate IRI; None where it is made from the row
606
+ (`predicate_map`).
607
+ object: The object's term map: a literal column, template or
608
+ constant (from a YAML or Python schema, a literal column).
609
+ property_name: The property-graph name the object is read under;
610
+ None for a map compiled from R2RML.
611
+ graph: The named graph the triple is in; None for the default graph.
612
+ A YAML or Python schema's (`graph_iri`); None from R2RML, whose
613
+ graphs are `graph_maps`.
614
+ predicate_map: A predicate made from the row (an R2RML predicate map
615
+ of rr:column or rr:template, R2RML 6.3), with `predicate` None.
616
+ graph_maps: The graph maps of an R2RML triple (R2RML 11.1: the
617
+ subject map's and the predicate-object map's together): a triple
618
+ in each graph they give, the constant `RR_DEFAULT_GRAPH` being
619
+ the default graph; () for the default graph alone.
620
+ """
621
+ predicate: Optional[str]
622
+ object: TermMap
623
+ property_name: Optional[str] = None
624
+ graph: Optional[str] = None
625
+ predicate_map: Optional[TermMap] = None
626
+ graph_maps: Tuple[TermMap, ...] = ()
627
+
628
+
629
+ @dataclass(frozen=True)
630
+ class EndRef:
631
+ """One end of an edge map.
632
+
633
+ Attributes:
634
+ map_id: The end's node map; None where the edge's end names no map
635
+ (a label no node mapping has, an R2RML IRI or blank-node object with no parent triples
636
+ map).
637
+ label: The end's label as the schema wrote it (`start_node_label`);
638
+ None for a map compiled from R2RML.
639
+ columns: The edge source's columns that hold the end's key, in the
640
+ end map's key order (an R2RML object's: its term's columns).
641
+ listed: Whether the schema wrote `columns` as a list: the authored
642
+ spelling, for the round trip only.
643
+ term: The end's term built from the edge's row: the end map's
644
+ subject over `columns` in place of its key (an R2RML object's
645
+ own term map). None where it cannot be (no end map, or a subject
646
+ that reads a column beyond the key, which the edge's row does
647
+ not hold). With `parent_columns`, built from the parent's row.
648
+ exists: Whether the end's row must exist for the edge to be a
649
+ triple (a YAML edge, rr:parentTriplesMap: a join); False for an
650
+ R2RML IRI or blank-node object with no parent triples map, whose
651
+ term stands by itself.
652
+ parent_columns: The end of an R2RML referencing object map whose
653
+ edge has a join (`EdgeMap.join`, R2RML 8): the parent's columns
654
+ `term` is built from, read from the parent row the join matches,
655
+ the parent subject's columns. `columns` are then the edge
656
+ source's columns the join equates with them, in that order, or
657
+ () where it does not equate each. Equal by SQL equality is not
658
+ one text (an INTEGER 1 and a VARCHAR '01' are equal on some
659
+ databases), so the term is the parent's.
660
+ () where `term` is built from the edge source's own row.
661
+ peers: The other node maps of the end's label whose subject gives
662
+ `term` too (one `identity:`, or one authored template): the end
663
+ exists where any of them, or `map_id`'s, has the key's row.
664
+ identity: The identity an end is given by instead of a label
665
+ (`RelationshipMapping.end_node_identity`): its maps are those
666
+ declaring it; None for an end given by a label.
667
+ """
668
+ map_id: Optional[str]
669
+ label: Optional[str]
670
+ columns: Tuple[str, ...]
671
+ listed: bool
672
+ term: Optional[TermMap]
673
+ exists: bool = True
674
+ parent_columns: Tuple[str, ...] = ()
675
+ peers: Tuple[str, ...] = ()
676
+ identity: Optional[str] = None
677
+
678
+
679
+ @dataclass(frozen=True)
680
+ class JointQuery:
681
+ """The joint SQL query of an R2RML referencing object map (R2RML 8),
682
+ held as a join, never as SQL text: each row of the
683
+ child's source with each row of the parent's where every condition
684
+ holds, `child.c = parent.p` by SQL equality (a NULL matches nothing).
685
+ A referencing object map with no condition between two different
686
+ logical tables is no valid mapping (R2RML 8), which `compile_r2rml`
687
+ refuses; with one logical table and no condition there is no join, the
688
+ parent's subject being made from the child's row (`EdgeMap.join` None).
689
+
690
+ Attributes:
691
+ child: The child triples map's source, the edge's own
692
+ (`EdgeMap.source`).
693
+ parent: The parent triples map's source.
694
+ conditions: (child column, parent column) pairs, as authored.
695
+ """
696
+ child: Source
697
+ parent: Source
698
+ conditions: Tuple[Tuple[str, str], ...] = ()
699
+
700
+
701
+ @dataclass(frozen=True)
702
+ class NodeMap:
703
+ """A source map over a node source: a subject per
704
+ row, its classes and its predicate-object maps.
705
+
706
+ Attributes:
707
+ id: Unique within the maps: the label, `Label#2` for the second map
708
+ of one label, `Label#3` and on; the
709
+ triples map's IRI for a map compiled from R2RML.
710
+ order: The map's position among the node maps, from 0.
711
+ source: The rows it reads.
712
+ key: Its key.
713
+ subject: The subject term map.
714
+ classes: Every class IRI its subjects are typed with; () for a
715
+ label that is no RDF class.
716
+ predicate_objects: Its predicate-object maps, in declaration order.
717
+ graph: The named graph its triples are in, or None.
718
+ label: The property-graph label; None from R2RML.
719
+ rdf_class: Whether the label is an RDF class (`NodeMapping.rdf_class`).
720
+ declared_class: The class IRI the schema declared (`class_iri`),
721
+ None where the class is the default vocabulary's: the authored
722
+ spelling, for the round trip.
723
+ property_columns: (property name, column) in declaration order.
724
+ mutable: As authored (`NodeMapping.mutable`: set_properties and
725
+ OWL RL may write its table).
726
+ graph_maps: An R2RML subject map's graph maps (R2RML 6.1, 11.1):
727
+ the graphs its class triples are in (`RR_DEFAULT_GRAPH` the
728
+ default graph); () for the default graph alone.
729
+ identity: The identity the map declares (YAML `identity: <name>` or
730
+ `global`; a generated mapping's own scope), None where it
731
+ declares none: what `iri.check_meetings` reads, so it needs no
732
+ authoring object.
733
+ key_properties: Whether each key column is also a property of the
734
+ node in the property-graph view, under its column name, where
735
+ the map gives no property of that name (a YAML or Python node
736
+ mapping's `id_column`: `lpg_view.with_key_properties`). False for a
737
+ map from R2RML or a generated map.
738
+ """
739
+ id: str
740
+ order: int
741
+ source: Source
742
+ key: Key
743
+ subject: TermMap
744
+ classes: Tuple[str, ...]
745
+ predicate_objects: Tuple[PredicateObject, ...]
746
+ graph: Optional[str] = None
747
+ label: Optional[str] = None
748
+ rdf_class: bool = True
749
+ declared_class: Optional[str] = None
750
+ property_columns: Pairs = ()
751
+ mutable: bool = False
752
+ graph_maps: Tuple[TermMap, ...] = ()
753
+ identity: Optional[str] = None
754
+ # A YAML source's name its synthesized IRIs carry (`iri.iri_segment`), where it is not the table.
755
+ iri_segment: Optional[str] = None
756
+ key_properties: bool = False
757
+
758
+
759
+ @dataclass(frozen=True)
760
+ class EdgeMap:
761
+ """A source map over a relationship source: each row one edge, one
762
+ triple from its start's term to its end's, with no key.
763
+
764
+ From R2RML, each IRI or blank-node object of a triples map is one (its
765
+ start the map's subject, its end the object's own term, `exists`
766
+ False), and so is each referencing object map (its end the parent's
767
+ subject, over the joint query, `join`).
768
+
769
+ Attributes:
770
+ id: Unique within the maps: the relationship type, `TYPE#2` for its
771
+ second mapping, and on; from R2RML, the triples map's IRI and
772
+ the object's place in it, `<map>#po<i>.<j>.<k>`.
773
+ order: The map's position among the edge maps, from 0.
774
+ predicate: The triple's predicate IRI; None where it is made from
775
+ the row (`predicate_map`).
776
+ rel_type: The property-graph relationship type; None from R2RML.
777
+ property_columns: (property name, column) in declaration order.
778
+ reify: As authored (`RelationshipMapping.reify`: None is auto).
779
+ relation_class_iri: As authored.
780
+ referential_integrity: As authored.
781
+ trust: Whether a plan may rely on no two rows holding one start and
782
+ end (`RelationshipMapping.keys`): 'trusted', 'check' or None.
783
+ graph: The named graph its triples are in, or None.
784
+ mutable: As authored (`RelationshipMapping.mutable`: OWL RL may
785
+ write inferred edges into its table).
786
+ join: The joint query of an R2RML referencing object map whose
787
+ parent's logical table is not the child's, or that has join
788
+ conditions (R2RML 8); None where each edge is one row of
789
+ `source`.
790
+ predicate_map: As `PredicateObject.predicate_map`.
791
+ graph_maps: As `PredicateObject.graph_maps`, read from the edge's
792
+ (the child's) row.
793
+ row_key: The columns that name one row, one relationship (a Cypher
794
+ pattern tells two relationships apart by them,
795
+ `lpg_view.relationship_identity`); None where no source says.
796
+ branch_of: Where a relationship mapping's end label has node maps
797
+ of different subjects, it compiles to one edge map per pair of
798
+ its ends' subjects (`compile_schema`), each end checked in its
799
+ own maps: the first branch's id on the others, None on the
800
+ first and on an edge map of one branch.
801
+ split: Whether the relationship mapping compiled to several such
802
+ branches (each end checked in its own maps, so
803
+ `referential_integrity`, as authored, drops no check).
804
+ """
805
+ id: str
806
+ order: int
807
+ source: Source
808
+ predicate: Optional[str]
809
+ rel_type: Optional[str]
810
+ start: EndRef
811
+ end: EndRef
812
+ property_columns: Pairs = ()
813
+ reify: Optional[bool] = None
814
+ relation_class_iri: Optional[str] = None
815
+ referential_integrity: bool = False
816
+ graph: Optional[str] = None
817
+ mutable: bool = False
818
+ join: Optional[JointQuery] = None
819
+ trust: Optional[str] = None
820
+ predicate_map: Optional[TermMap] = None
821
+ graph_maps: Tuple[TermMap, ...] = ()
822
+ row_key: Optional[Tuple[str, ...]] = None
823
+ branch_of: Optional[str] = None
824
+ split: bool = False
825
+ iri_segment: Optional[str] = None
826
+
827
+
828
+ @dataclass(frozen=True)
829
+ class PredicateDeclaration:
830
+ """A `PredicateMapping` as the schema declared it, for the round trip:
831
+ a node map's predicate-object maps and an edge map's predicate are
832
+ already resolved through it."""
833
+ predicate_iri: str
834
+ kind: str # 'datatype' | 'object', PredicateKind's values
835
+ node_label: Optional[str] = None
836
+ property_name: Optional[str] = None
837
+ relationship_type: Optional[str] = None
838
+ datatype: Optional[str] = None
839
+ language: Optional[str] = None
840
+ language_column: Optional[str] = None
841
+
842
+
843
+ @dataclass(frozen=True)
844
+ class Settings:
845
+ """The schema-level settings a map's terms and names are read through."""
846
+ name: Optional[str]
847
+ base_iri: str
848
+ default_catalog: Optional[str]
849
+ default_schema: Optional[str]
850
+ table_qualifications: Pairs
851
+ prefixes: Pairs
852
+ decimal_text: str = DECIMAL_CANONICAL
853
+
854
+
855
+ DISTINCT = "distinct"
856
+ """The identity a map declares (`identity: distinct`) to say its subjects are never another map's: trusted
857
+ as `keys: trusted` is, so its subjects meet no other map's however their templates read (design
858
+ 41-identity-scopes). Data that holds one IRI in both is the declaration broken, as a repeated trusted key."""
859
+
860
+
861
+ def with_decimal_text(maps: "SourceMaps", setting: str) -> "SourceMaps":
862
+ """`maps` under the schema's `decimal_text` (`Settings.decimal_text`), which the SPARQL
863
+ translator reads (`sparql_front.held_under`); `maps` itself under the default."""
864
+ setting = decimal_text_setting(setting)
865
+ if setting == maps.settings.decimal_text:
866
+ return maps
867
+ return replace(maps, settings=replace(maps.settings, decimal_text=setting))
868
+
869
+
870
+ def kept_apart(a: "NodeMap", b: "NodeMap") -> bool:
871
+ """Whether a declaration keeps two node maps' subjects apart (`identity: distinct` on either)."""
872
+ return DISTINCT in (a.identity, b.identity)
873
+
874
+
875
+ def subject_identity_of(source: Source, key: Key, subject: TermMap) -> Tuple[Any, ...]:
876
+ """What makes two node maps' subjects one subject by their rows: the
877
+ same rows (qualified source and query) and the same subject term map
878
+ (`TermMap.mints`). The row filter is left out: two filtered maps of one
879
+ identity give a row passing both one subject. The one home of node
880
+ identity on the SPARQL path (docs/architecture/rules.md, "Which rows
881
+ give which RDF terms").
882
+
883
+ A synthesized subject (no iri_template) is identified by its key
884
+ instead of its text, and so is never one identity with a declared
885
+ template, even one that writes the synthesized form out. That keeps,
886
+ on every schema `prograph.schema.iri.check_identities` admits, the
887
+ partition the key-based identity it replaced gave (table, key and
888
+ declared iri_template), the one the
889
+ property graph's row test still reads (`prograph.schema.mapping.
890
+ rows_within`, which compares the iri_template's text): where the two
891
+ rules differ, the planner read one identity as two branches of
892
+ different labels, and `GROUP BY ?s` split each subject in two.
893
+ Increment 4 moves the SPARQL readers of `rows_within` and row sharing
894
+ to source maps; it must then drop this key in favour of the subject's
895
+ terms (`subject.mints()` alone), which is RDF's answer (RDF 1.1
896
+ Concepts 3.2: a node is its IRI) for two cases: the synthesized form
897
+ written out beside the synthesized form on one table and key (one
898
+ subject, two here), and one table spelled two ways that
899
+ `table_qualifications` qualify alike (two subjects, their synthesized
900
+ IRIs differing by the spelling; one here).
901
+
902
+ Beyond the key-based identity, the source query is read: two maps of
903
+ one source name and different queries are two identities (the R2RML
904
+ bridge names each query source by its triples map, so none differ).
905
+ """
906
+ if subject.synthesized:
907
+ return (source.qualified, source.query, ("synthesized",) + tuple(key.columns))
908
+ return (source.qualified, source.query, subject.mints())
909
+
910
+
911
+ def key_property(column: str) -> PredicateObject:
912
+ """A node map's key column read as a property-graph property under its column name
913
+ (`NodeMap.key_properties`): a literal of the column, with no predicate, so no triple."""
914
+ return PredicateObject(predicate=None, object=TermMap(LITERAL, column=column), property_name=column)
915
+
916
+
917
+ def names_one_key(key: Key, subject: TermMap) -> bool:
918
+ """Whether a subject is written from every column of its map's key
919
+ (`SourceMaps.subject_names_one_key`)."""
920
+ return set(key.columns) <= set(subject.columns())
921
+
922
+
923
+ class Giver(NamedTuple):
924
+ """A map that gives a predicate's triples: a node map with the
925
+ predicate-object map, or an edge map with None."""
926
+ map: Union[NodeMap, EdgeMap]
927
+ predicate_object: Optional[PredicateObject]
928
+
929
+
930
+ @dataclass(frozen=True)
931
+ class SourceMaps:
932
+ """Every source map of one schema version, and their indexes.
933
+
934
+ Attributes:
935
+ settings: The schema's settings.
936
+ nodes: The node maps, in declaration order.
937
+ edges: The edge maps, in declaration order.
938
+ predicate_declarations: Each predicate IRI's declarations, in the
939
+ schema's order (IRI first seen, then declaration), for the
940
+ round trip.
941
+ representatives: The IRIs in `GraphSchema.predicate_mappings`
942
+ order, each with the position of its representative among its
943
+ declarations.
944
+ property_predicates: The schema's (label, property) -> IRI
945
+ resolutions, first declaration first, as it holds them.
946
+ relationship_predicates: Its relationship type -> IRI resolutions.
947
+ """
948
+ settings: Settings
949
+ nodes: Tuple[NodeMap, ...]
950
+ edges: Tuple[EdgeMap, ...]
951
+ predicate_declarations: Tuple[Tuple[str, Tuple[PredicateDeclaration, ...]], ...] = ()
952
+ representatives: Tuple[Tuple[str, int], ...] = ()
953
+ property_predicates: Tuple[Tuple[Tuple[Optional[str], str], str], ...] = ()
954
+ relationship_predicates: Tuple[Tuple[str, str], ...] = ()
955
+ # Indexes, worked out once per version.
956
+ by_id: Dict[str, Union[NodeMap, EdgeMap]] = field(default_factory=dict, compare=False,
957
+ repr=False)
958
+ by_class: Dict[str, List[NodeMap]] = field(default_factory=dict, compare=False, repr=False)
959
+ by_predicate: Dict[str, List[Giver]] = field(default_factory=dict, compare=False,
960
+ repr=False)
961
+ # The givers whose predicate is made from the row (an R2RML predicate
962
+ # map of rr:column or rr:template): any predicate may be theirs.
963
+ open_predicates: List[Giver] = field(default_factory=list, compare=False, repr=False)
964
+
965
+ def __post_init__(self) -> None:
966
+ by_id: Dict[str, Union[NodeMap, EdgeMap]] = {}
967
+ for m in self.nodes + self.edges:
968
+ if m.id in by_id:
969
+ raise ValueError(f"two source maps have the id {m.id!r}")
970
+ by_id[m.id] = m
971
+ by_class: Dict[str, List[NodeMap]] = {}
972
+ by_predicate: Dict[str, List[Giver]] = {}
973
+ open_predicates: List[Giver] = []
974
+ for node in self.nodes:
975
+ for iri in node.classes:
976
+ by_class.setdefault(iri, []).append(node)
977
+ for pom in node.predicate_objects:
978
+ giver = Giver(node, pom)
979
+ if pom.predicate is None:
980
+ open_predicates.append(giver)
981
+ else:
982
+ by_predicate.setdefault(pom.predicate, []).append(giver)
983
+ for edge in self.edges:
984
+ if edge.predicate is None:
985
+ open_predicates.append(Giver(edge, None))
986
+ else:
987
+ by_predicate.setdefault(edge.predicate, []).append(Giver(edge, None))
988
+ # Frozen: the indexes are set past the dataclass's guard, once.
989
+ object.__setattr__(self, "by_id", by_id)
990
+ object.__setattr__(self, "by_class", by_class)
991
+ object.__setattr__(self, "by_predicate", by_predicate)
992
+ object.__setattr__(self, "open_predicates", open_predicates)
993
+ object.__setattr__(self, "_partners", None)
994
+
995
+ def joined(self, other: "SourceMaps") -> "SourceMaps":
996
+ """These maps and `other`'s, one set (a YAML schema's and its included R2RML document's): `other`'s after these, renumbered, so a mapping's position is its map's; these
997
+ maps' settings and predicate indexes. Two maps of one id are refused (`__post_init__`)."""
998
+ n, e = len(self.nodes), len(self.edges)
999
+ return SourceMaps(
1000
+ settings=self.settings,
1001
+ nodes=self.nodes + tuple(replace(m, order=n + i) for i, m in enumerate(other.nodes)),
1002
+ edges=self.edges + tuple(replace(m, order=e + i) for i, m in enumerate(other.edges)),
1003
+ predicate_declarations=self.predicate_declarations, representatives=self.representatives,
1004
+ property_predicates=self.property_predicates,
1005
+ relationship_predicates=self.relationship_predicates)
1006
+
1007
+ def tables(self) -> Tuple[Source, ...]:
1008
+ """Every logical table the maps read, once each by its name (`Source.table`), in
1009
+ declaration order: each map's source and a joint query's parent (R2RML 8). The tables
1010
+ an engine loads and types are these, the ones the plan reads."""
1011
+ out: Dict[str, Source] = {}
1012
+ for m in self.nodes + self.edges:
1013
+ sources = [m.source]
1014
+ join = getattr(m, "join", None)
1015
+ if join is not None:
1016
+ sources += [join.child, join.parent]
1017
+ for s in sources:
1018
+ out.setdefault(s.table, s)
1019
+ return tuple(out.values())
1020
+
1021
+ def node(self, map_id: str) -> Optional[NodeMap]:
1022
+ found = self.by_id.get(map_id)
1023
+ return found if isinstance(found, NodeMap) else None
1024
+
1025
+ def subject_identity(self, m: NodeMap) -> Tuple[Any, ...]:
1026
+ """What makes two node maps' subjects one subject by their rows
1027
+ (`subject_identity_of`)."""
1028
+ return subject_identity_of(m.source, m.key, m.subject)
1029
+
1030
+ def partners(self) -> Dict[str, Set[str]]:
1031
+ """Map id -> the ids of the node maps of other subject identities
1032
+ whose subjects may be its subjects (`TermMap.may_equal`), every pair
1033
+ at once: each map's prefix read once and sorted, so that only the
1034
+ maps a prefix starts are compared. Worked out once
1035
+ per version. Pair by pair, NPD's 1,588 maps took 1.26 million tests
1036
+ and ten seconds of every SPARQL planning."""
1037
+ cached = getattr(self, "_partners")
1038
+ if cached is not None:
1039
+ return cached
1040
+ # Each identity as a number, so that the sweep compares numbers.
1041
+ numbers: Dict[Tuple[Any, ...], int] = {}
1042
+ read = sorted(((m.subject.prefix(), m.subject.term_type,
1043
+ numbers.setdefault(self.subject_identity(m), len(numbers)), m.id, m.identity == DISTINCT)
1044
+ for m in self.nodes), key=lambda r: r[0])
1045
+ partners: Dict[str, Set[str]] = {}
1046
+ for i, (prefix, term_type, identity, map_id, apart) in enumerate(read):
1047
+ for other_prefix, other_type, other_identity, other, other_apart in read[i + 1:]:
1048
+ if not other_prefix.startswith(prefix):
1049
+ break
1050
+ if other_type == term_type and other_identity != identity and not (apart or other_apart):
1051
+ partners.setdefault(map_id, set()).add(other)
1052
+ partners.setdefault(other, set()).add(map_id)
1053
+ object.__setattr__(self, "_partners", partners)
1054
+ return partners
1055
+
1056
+ @staticmethod
1057
+ def subject_names_one_key(m: NodeMap) -> bool:
1058
+ """Whether each subject of `m` is written from every key column, so
1059
+ that two rows of different keys never give one subject: the
1060
+ synthesized form, or a template holding the whole key. A template
1061
+ that leaves a key column out (`{_uri}` on a table keyed by row id, a
1062
+ value table's form) can give several rows one subject, and those
1063
+ rows are one RDF node (RDF 1.1 Concepts 3.2)."""
1064
+ return names_one_key(m.key, m.subject)
1065
+
1066
+ def column_value(column: str) -> TermMap:
1067
+ """A literal term map of a column's value as it is (its natural literal, R2RML 10.2): what a
1068
+ lookup reads a key back through (`entry.node_keys`)."""
1069
+ return TermMap(term_type=LITERAL, column=column)
1070
+
1071
+
1072
+ def iri_column(column: str) -> TermMap:
1073
+ """An IRI term map of a column whose values are whole IRIs, as they are (no base resolved)."""
1074
+ return TermMap(term_type=IRI, column=column)
1075
+
1076
+
1077
+ def side_table_map(map_id: str, query: str, subject_column: str) -> "NodeMap":
1078
+ """A node map over a query of ProGraph's own side tables (the owl:sameAs alias rows,
1079
+ `plan.ir.identity`), its subject the IRI column `subject_column`: scanned by a plan, never one of the
1080
+ mapping's maps (it gives no triple)."""
1081
+ import hashlib
1082
+ table = "__prograph_side_" + hashlib.sha1(query.encode("utf-8")).hexdigest()[:12]
1083
+ return NodeMap(id=map_id, order=0, source=Source(table=table, qualified=table, query=query),
1084
+ key=Key((subject_column,), stated=False), subject=iri_column(subject_column), classes=(),
1085
+ predicate_objects=())
1086
+
1087
+
1088
+ def triple_identity_term(start: TermMap, predicate: str, end: TermMap) -> TermMap:
1089
+ """An IRI naming one triple by its start IRI, predicate and end IRI as their templates write them
1090
+ (`urn:prograph:triple:<start> <p> <end>`): one triple two maps give is one term (an R2RML
1091
+ relationship's identity, `lpg_view.relationship_identity`). Both ends are IRI templates."""
1092
+ return TermMap(IRI, template=((("urn:prograph:triple:", False),) + tuple(start.template)
1093
+ + ((f" <{predicate}> ", False),) + tuple(end.template)))
1094
+
1095
+
1096
+ def row_identity_term(tag: str, columns: Sequence[str]) -> TermMap:
1097
+ """An IRI naming one row by `columns` under `tag` (`urn:prograph:<tag>/<v1>/<v2>...`): terms of two
1098
+ tags never meet. For an identity no mapping states as a term (a relationship's,
1099
+ `lpg_view.relationship_identity`)."""
1100
+ runs: List[Tuple[str, bool]] = [(f"urn:prograph:{tag}", False)]
1101
+ for c in columns:
1102
+ runs += [("/", False), (c, True)]
1103
+ return TermMap(IRI, template=tuple(runs))