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,226 @@
1
+ """What Cypher leaves out of an engine's ontology: it applies the class and property hierarchies (subclass, sub-property,
2
+ equivalent class and property) through the saturated maps (`saturate`), rdfs:domain and rdfs:range as labels of a
3
+ property's ends (`lpg_view.with_typing`), and under profile ql the inverse and symmetric properties through the
4
+ relationship types (`lpg_view.with_inverses`). The first Cypher query on an engine whose ontology states other
5
+ axioms warns once, naming them by kind (`CypherOntologyWarning`); SPARQL applies them."""
6
+
7
+ import threading
8
+ import warnings
9
+ from typing import Any, Dict, Iterable
10
+
11
+ from prograph.rules import module_home
12
+ from prograph.schema.xsd import XSD
13
+
14
+ module_home("cypher-ontology-axioms",
15
+ "The ontology axioms Cypher does not apply, named once per engine by `CypherOntologyWarning`",
16
+ terms=("CypherOntologyWarning", "ignored ontology axioms", "Cypher ontology", "class and property hierarchies only"))
17
+
18
+ RDFS = "http://www.w3.org/2000/01/rdf-schema#"
19
+ OWL = "http://www.w3.org/2002/07/owl#"
20
+ RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
21
+
22
+ DOMAIN_RANGE = "rdfs:domain/range"
23
+ INVERSE = "owl:inverseOf"
24
+ THING = "owl:Thing"
25
+ SYMMETRIC = "owl:SymmetricProperty"
26
+ REFLEXIVE = "owl:ReflexiveProperty"
27
+ EXISTENTIAL = "existential restrictions (owl:someValuesFrom)"
28
+ RL_FACTS = "RL-derived facts (profile rl)"
29
+ SAME_AS = "owl:sameAs"
30
+ INDIVIDUALS = "individual assertions held in the ontology (an ABox)"
31
+
32
+ # What SPARQL applies under profile rl besides the kinds above: the OWL 2 RL rules' property characteristics,
33
+ # chains, keys and class constructors. owl:disjointWith, owl:differentFrom, owl:complementOf,
34
+ # owl:propertyDisjointWith, owl:AsymmetricProperty and owl:IrreflexiveProperty only check consistency, so a
35
+ # derived fact never follows from them.
36
+ _RL_TYPES = frozenset(OWL + n for n in ("TransitiveProperty",))
37
+ _RL_PREDICATES = frozenset(OWL + n for n in (
38
+ "propertyChainAxiom", "hasKey", "allValuesFrom", "hasValue", "intersectionOf", "unionOf", "oneOf"))
39
+ # Axioms that only derive owl:sameAs under profile rl: named under the sameAs kind.
40
+ _SAME_AS_TYPES = frozenset(OWL + n for n in ("FunctionalProperty", "InverseFunctionalProperty"))
41
+ _SAME_AS_PREDICATES = frozenset(OWL + n for n in ("maxCardinality", "maxQualifiedCardinality"))
42
+
43
+ _lock = threading.Lock()
44
+ _VOCABULARIES = (RDFS, OWL, "http://www.w3.org/1999/02/22-rdf-syntax-ns#", XSD)
45
+ # Annotation vocabularies: a triple of one of these predicates is no assertion about an individual.
46
+ _ANNOTATIONS = ("http://purl.org/dc/elements/1.1/", "http://purl.org/dc/terms/",
47
+ "http://www.w3.org/2004/02/skos/core#")
48
+
49
+
50
+ def _is_schema_triple(s: str, p: str, o: str, annotation: frozenset = frozenset(),
51
+ header: frozenset = frozenset()) -> bool:
52
+ """Whether a triple is part of the ontology's schema (vocabulary of RDF, RDFS, OWL, a blank node's part of an
53
+ expression, an annotation, the ontology's header), not an assertion about an individual (`:ann a :Employee`,
54
+ `:ann :reportsto :cy`). `annotation` the predicates the graph declares `owl:AnnotationProperty`; `header`
55
+ the subjects it types `owl:Ontology`."""
56
+ if s.startswith("_:") or not s or not s.startswith(("http", "urn")):
57
+ return True # a blank node: part of a class or property expression
58
+ if s in header or p in annotation or p.startswith(_ANNOTATIONS):
59
+ return True
60
+ if p.startswith(_VOCABULARIES) and (p != RDF_TYPE or o.startswith(_VOCABULARIES)):
61
+ return True
62
+ return False
63
+
64
+
65
+ class CypherOntologyWarning(UserWarning):
66
+ """Cypher applies the ontology's class and property hierarchies, rdfs:domain and rdfs:range (and under profile ql
67
+ inverse and symmetric properties): the engine's ontology states axioms of
68
+ other kinds, which a Cypher query does not apply (the message names them by kind). SPARQL applies them."""
69
+
70
+
71
+ def ignored_kinds(graph: Any, profile: str, edge_predicates: Iterable[str] = ()) -> Dict[str, int]:
72
+ """Each kind of axiom `graph` (the ontology's rdflib graph) states that SPARQL applies under `profile` and
73
+ Cypher does not, with its count; `edge_predicates` the predicates of the mapped relationships (an
74
+ `owl:sameAs` link is data)."""
75
+ found: Dict[str, int] = {}
76
+
77
+ def add(kind: str) -> None:
78
+ found[kind] = found.get(kind, 0) + 1
79
+
80
+ rl, ql = profile == "rl", profile == "ql"
81
+ typed_as = {}
82
+ for s, p, o in graph:
83
+ if str(p) == RDF_TYPE and str(o) in (OWL + "AnnotationProperty", OWL + "Ontology"):
84
+ typed_as.setdefault(str(o), set()).add(str(s))
85
+ annotation = frozenset(typed_as.get(OWL + "AnnotationProperty", ()))
86
+ header = frozenset(typed_as.get(OWL + "Ontology", ()))
87
+ for s, p, o in graph:
88
+ p, o, s = str(p), str(o), str(s)
89
+ typed = p == RDF_TYPE
90
+ if p == RDFS + "domain" or p == RDFS + "range":
91
+ pass # applied: a label of the property's ends (`lpg_view.with_typing`)
92
+ elif p == OWL + "inverseOf":
93
+ pass # under ql read through the inverse types, under rl from the stored facts
94
+ elif p == OWL + "sameAs" and not rl: # under rl one node per component (`cypher_front.canonical`)
95
+ add(SAME_AS)
96
+ elif typed and o == OWL + "SymmetricProperty":
97
+ pass # as owl:inverseOf
98
+ elif typed and o == OWL + "ReflexiveProperty" and ql:
99
+ add(REFLEXIVE)
100
+ elif p == OWL + "someValuesFrom" and (ql or rl):
101
+ add(EXISTENTIAL)
102
+ if not _is_schema_triple(s, p, o, annotation, header):
103
+ add(INDIVIDUALS)
104
+ if OWL + "Thing" in (s, o) and not ql: # under ql every node's label (`lpg_view.with_everything`)
105
+ add(THING)
106
+ # RL's derived types and relationships are read from the stored facts (`lpg_view.with_derived`)
107
+ for predicate in edge_predicates:
108
+ if predicate == OWL + "sameAs" and not rl:
109
+ add(SAME_AS)
110
+ return found
111
+
112
+
113
+ def _caller():
114
+ """The file, line and module of the first frame outside ProGraph: where the query was run from."""
115
+ import os
116
+ import sys
117
+ root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
118
+ frame = sys._getframe(1)
119
+ while frame is not None and os.path.abspath(frame.f_code.co_filename).startswith(root + os.sep):
120
+ frame = frame.f_back
121
+ if frame is None:
122
+ return __file__, 1, __name__
123
+ return frame.f_code.co_filename, frame.f_lineno, frame.f_globals.get("__name__", "<unknown>")
124
+
125
+
126
+ def warn_once(engine: Any, graph: Any, edge_predicates: Iterable[str], typing_lost: Iterable[str] = (),
127
+ derived_values: Iterable[str] = ()) -> None:
128
+ """Warn, once per engine, of the axioms of the engine's ontology a Cypher query does not apply. The warning
129
+ is raised with `warn_explicit`, at the caller's file and line, with no registry, so the default filter's
130
+ once-per-location rule does not silence a second engine. An engine is marked warned only once its
131
+ ontology has been read."""
132
+ with _lock:
133
+ if engine.__dict__.get("_cypher_ontology_warned") or graph is None:
134
+ return
135
+ found = ignored_kinds(graph, getattr(engine, "_profile", None), edge_predicates)
136
+ for p in typing_lost: # a domain or range whose typed end no node mapping holds (`lpg_view.with_typing`)
137
+ found[f"rdfs:domain/range of <{p}> at an end no node mapping gives"] = 1
138
+ for p in derived_values: # a stored RL fact with a literal object Cypher reads as no property (`with_derived`)
139
+ found[f"stored OWL RL values of <{p}> (a literal of a datatype Cypher does not read, or a key another "
140
+ f"property holds)"] = 1
141
+ engine.__dict__["_cypher_ontology_warned"] = True
142
+ if found:
143
+ named = ", ".join(f"{kind} ({n})" for kind, n in found.items())
144
+ filename, lineno, module = _caller()
145
+ warnings.warn_explicit(
146
+ f"Cypher applies the ontology's class and property hierarchies only (subclass, sub-property, "
147
+ f"equivalent class and property, through the saturated maps), rdfs:domain and rdfs:range, and under "
148
+ f"profile ql inverse and symmetric properties; query in SPARQL for the rest. "
149
+ f"Ignored axioms: {named}", CypherOntologyWarning, filename, lineno, module=module, registry=None)
150
+
151
+
152
+ class StoredValues:
153
+ """An engine's warnings of the node properties stored OWL RL facts give (`cypher_front.stored_values`, rule
154
+ cypher-derived-labels), each given once per engine: a key whose values differ on some node (a mapped value and a
155
+ stored one, or two stored ones; compared as values, type-tolerantly, as `owl_rl.stage_disagreeing` compares
156
+ owl:sameAs records'), checked by one SPARQL query the first time a Cypher query reads the key; and a key read
157
+ from its maps alone (`warn`)."""
158
+
159
+ def __init__(self, engine: Any) -> None:
160
+ import weakref
161
+ self.engine = weakref.ref(engine)
162
+ self.said: set = set()
163
+
164
+ def warn(self, what: Any, text: str) -> None:
165
+ with _lock:
166
+ if what in self.said:
167
+ return
168
+ self.said.add(what)
169
+ filename, lineno, module = _caller()
170
+ warnings.warn_explicit(text, CypherOntologyWarning, filename, lineno, module=module, registry=None)
171
+
172
+ def check(self, label: Any, key: str, predicates: Iterable[str]) -> None:
173
+ """Warn, the first time a query reads `key` (given by `predicates`), where some node's values of it differ."""
174
+ with _lock:
175
+ if ("differ", key) in self.said:
176
+ return
177
+ self.said.add(("differ", key))
178
+ engine = self.engine()
179
+ if engine is None:
180
+ return
181
+ listed = " ".join(f"<{p}>" for p in sorted(set(predicates)))
182
+ query = (f"SELECT ?a WHERE {{ VALUES ?p {{ {listed} }} VALUES ?r {{ {listed} }} ?a ?p ?v . ?a ?r ?w "
183
+ f"FILTER(isLiteral(?v) && isLiteral(?w) && STR(?v) != STR(?w) && !COALESCE(?v = ?w, false)) }} LIMIT 1")
184
+ try:
185
+ with warnings.catch_warnings():
186
+ warnings.simplefilter("ignore")
187
+ found = engine.execute(query, language="sparql", return_type="list")
188
+ except Exception: # noqa: BLE001 - the check is a courtesy: the user's query has answered; no warning then
189
+ return
190
+ if found:
191
+ filename, lineno, module = _caller()
192
+ warnings.warn_explicit(
193
+ f"{label + '.' + key if label else 'A node property ' + key} has several values (mapped and OWL RL facts); the mapped one is shown, else "
194
+ f"the least; prograph.values(n, '{key}') lists all", CypherOntologyWarning, filename, lineno,
195
+ module=module, registry=None)
196
+
197
+
198
+ def covering(self, predicates: Iterable[str]) -> frozenset:
199
+ """The classes whose members an owl:hasValue axiom on one of `predicates` gives a value (C ⊑ R or C ≡ R, R a
200
+ restriction on the predicate with owl:hasValue): a node of such a class, or of a subclass, receives the
201
+ fact (`cypher_front._Translator.refuse_key`)."""
202
+ engine = self.engine()
203
+ layer = getattr(engine, "_ontology", None) if engine is not None else None
204
+ if layer is None:
205
+ return frozenset()
206
+ g = layer.rdf_graph() if callable(layer.rdf_graph) else layer.rdf_graph
207
+ from rdflib import URIRef
208
+ on, has = URIRef(OWL + "onProperty"), URIRef(OWL + "hasValue")
209
+ sub, eq = URIRef(RDFS + "subClassOf"), URIRef(OWL + "equivalentClass")
210
+ out = set()
211
+ for p in predicates:
212
+ for r in g.subjects(on, URIRef(p)):
213
+ if (r, has, None) not in g:
214
+ continue
215
+ out |= {str(c) for c in g.subjects(sub, r)} | {str(c) for c in g.subjects(eq, r)} | \
216
+ {str(c) for c in g.objects(r, eq)}
217
+ return frozenset(out)
218
+
219
+
220
+ def stored_values_of(engine: Any) -> StoredValues:
221
+ """The engine's `StoredValues`, made once."""
222
+ with _lock:
223
+ held = engine.__dict__.get("_cypher_stored_values")
224
+ if held is None:
225
+ held = engine.__dict__["_cypher_stored_values"] = StoredValues(engine)
226
+ return held
@@ -0,0 +1,191 @@
1
+ """Cypher procedure CALL over declared procedures (rule cypher-procedures; design 41-cypher-procedures):
2
+ a procedure is declared data, a signature and its rows (inputs, then outputs), never a callable. A call's
3
+ rows are the procedure's rows whose inputs are its arguments by value equivalence (null is null; an
4
+ INTEGER argument is a FLOAT or NUMBER parameter's number; a boolean is no number), each joined to the
5
+ query's row; a procedure of no outputs (void) leaves the rows as they are. Arguments are written in the
6
+ query (constants), so the matching rows are known at planning and become a `Values` relation. Errors are
7
+ refused at planning with openCypher's names (the TCK's).
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from dataclasses import dataclass, replace
13
+ from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple
14
+
15
+ from prograph.rules import module_home
16
+
17
+ module_home("cypher-procedures", "Cypher's procedure CALL, over declared procedures",
18
+ terms=("CALL", "YIELD", "procedure", "declare_procedure", "standalone CALL", "in-query CALL"))
19
+
20
+ TYPES = ("INTEGER", "FLOAT", "NUMBER", "STRING", "BOOLEAN", "ANY")
21
+
22
+
23
+ class ProcedureError(ValueError):
24
+ """A call the declared procedures refuse (openCypher's error name first: ProcedureNotFound,
25
+ InvalidNumberOfArguments, InvalidArgumentType, VariableAlreadyBound, UndefinedVariable,
26
+ UnexpectedSyntax)."""
27
+
28
+
29
+ @dataclass(frozen=True)
30
+ class Procedure:
31
+ """A declared procedure: its name (`ns.name`), its inputs and outputs as (name, type) pairs, and its
32
+ rows, each the inputs' values then the outputs'."""
33
+ name: str
34
+ inputs: Tuple[Tuple[str, str], ...]
35
+ outputs: Tuple[Tuple[str, str], ...]
36
+ rows: Tuple[Tuple[Any, ...], ...]
37
+ source: Optional[str] = None
38
+ columns: Tuple[Tuple[str, str], ...] = () # (input or output name, source column), where they differ
39
+
40
+ def __post_init__(self) -> None:
41
+ for _, t in self.inputs + self.outputs:
42
+ if t not in TYPES:
43
+ raise ValueError(f"a procedure type of {t!r} (one of {', '.join(TYPES)})")
44
+ names = [n for n, _ in self.inputs + self.outputs]
45
+ if len(set(names)) != len(names):
46
+ raise ValueError(f"{self.name} names an input or output twice")
47
+ width = len(self.inputs) + len(self.outputs)
48
+ if any(len(r) != width for r in self.rows):
49
+ raise ValueError(f"each row of {self.name} has its {width} inputs and outputs")
50
+ for row in self.rows:
51
+ for value, (n, t) in zip(row, self.inputs + self.outputs):
52
+ if not _of_type(value, t) or t == "INTEGER" and isinstance(value, float):
53
+ raise ValueError(f"{self.name}'s {n} is {t}; a row gives {value!r}")
54
+
55
+
56
+ def declare(name: str, inputs: Sequence[Tuple[str, str]], outputs: Sequence[Tuple[str, str]],
57
+ rows: Optional[Sequence[Sequence[Any]]] = None, source: Optional[str] = None,
58
+ columns: Optional[Dict[str, str]] = None) -> Procedure:
59
+ """The one loader: a procedure of literal `rows`, or of a `source` (a table or view the engine reads,
60
+ its columns named as the inputs then outputs, or as `columns` maps them). Exactly one of the two."""
61
+ if (rows is None) == (source is None):
62
+ raise ValueError(f"{name} is declared with rows or a source, one of the two")
63
+ ins = tuple((n, t.upper().rstrip("?")) for n, t in inputs)
64
+ outs = tuple((n, t.upper().rstrip("?")) for n, t in outputs)
65
+ if source is None:
66
+ if columns:
67
+ raise ValueError(f"{name} maps columns, which only a source has")
68
+ types = [t for _, t in ins + outs]
69
+ return Procedure(name, ins, outs, tuple(tuple(_cell(v, t) for v, t in zip(r, types)) if len(r) == len(types)
70
+ else tuple(r) for r in rows))
71
+ if not isinstance(source, str) or not source:
72
+ raise ValueError(f"{name}'s source is a table or view name")
73
+ if not ins and not outs:
74
+ raise ValueError(f"{name} has a source but no input or output to read from it")
75
+ unknown = set(columns or {}) - {n for n, _ in ins + outs}
76
+ if unknown:
77
+ raise ValueError(f"{name}'s columns name {', '.join(sorted(unknown))}, no input or output")
78
+ return Procedure(name, ins, outs, (), source, tuple(sorted((columns or {}).items())))
79
+
80
+
81
+ MAX_SOURCE_ROWS = 10_000
82
+
83
+
84
+ def _cell(value: Any, t: str, has_boolean: bool = True) -> Any:
85
+ """A value as its declared type holds it: a FLOAT an int gives is a float; a source's DECIMAL is a float
86
+ for FLOAT and NUMBER, an int for INTEGER when exact (else left, so the type error names it); a
87
+ BOOLEAN from an engine with no boolean type (0 or 1) is a boolean."""
88
+ from decimal import Decimal
89
+ if isinstance(value, Decimal):
90
+ if t == "INTEGER":
91
+ return int(value) if value == value.to_integral_value() else value
92
+ return float(value) if t in ("FLOAT", "NUMBER") else value
93
+ if t == "FLOAT" and isinstance(value, int) and not isinstance(value, bool):
94
+ return float(value)
95
+ if t == "BOOLEAN" and not has_boolean and value in (0, 1) and not isinstance(value, bool):
96
+ return bool(value)
97
+ return value
98
+
99
+
100
+ def resolved(proc: Procedure, read: Any, dialect: Any) -> Procedure:
101
+ """A source procedure with its rows read now: `read(sql)` gives the result's rows as sequences, `dialect`
102
+ names the table (rule source-table-names) and the columns. Each value is made its declared type and
103
+ checked as literal rows are; a source above MAX_SOURCE_ROWS is refused, since its rows enter the plan as
104
+ a VALUES list."""
105
+ if proc.source is None:
106
+ return proc
107
+ mapped = dict(proc.columns)
108
+ names = [mapped.get(n, n) for n, _ in proc.inputs + proc.outputs]
109
+ table = dialect.table_name(proc.source)
110
+ listed, cap = ", ".join(dialect.quote(c) for c in names), MAX_SOURCE_ROWS + 1
111
+ sql = (# SQL Server takes OFFSET ... FETCH only after an ORDER BY; Oracle takes both.
112
+ f"SELECT {listed} FROM {table} ORDER BY 1 OFFSET 0 ROWS FETCH NEXT {cap} ROWS ONLY"
113
+ if dialect.config.limit_style == "fetch" else
114
+ f"SELECT {listed} FROM {table} LIMIT {cap}") # the dialect's own row limit
115
+ try:
116
+ rows = [tuple(r) for r in read(sql)]
117
+ except Exception as e:
118
+ raise ProcedureError(f"{proc.name}'s source {proc.source} cannot be read: {e}") from e
119
+ if len(rows) > MAX_SOURCE_ROWS:
120
+ raise ProcedureError(f"{proc.name}'s source {proc.source} has more than {MAX_SOURCE_ROWS} rows, "
121
+ f"the most a procedure holds")
122
+ types = [t for _, t in proc.inputs + proc.outputs]
123
+ boolean = dialect.config.has_boolean_type
124
+ rows = [tuple(_cell(v, t, boolean) for v, t in zip(r, types)) for r in rows]
125
+ try:
126
+ return replace(proc, rows=tuple(rows))
127
+ except ValueError as e:
128
+ raise ValueError(f"{e} (source {proc.source})") from e
129
+
130
+
131
+ class Lazy(Mapping):
132
+ """The declared procedures by name, a source's rows read only when a call looks the procedure up (and
133
+ once): a name's presence is known without reading, so one unreadable source breaks only its callers."""
134
+
135
+ def __init__(self, declared: Dict[str, Procedure], read: Any, dialect: Any) -> None:
136
+ self._declared, self._read, self._dialect, self._done = declared, read, dialect, {}
137
+
138
+ def __getitem__(self, name: str) -> Procedure:
139
+ proc = self._declared[name]
140
+ if name not in self._done:
141
+ self._done[name] = resolved(proc, self._read, self._dialect)
142
+ return self._done[name]
143
+
144
+ def __contains__(self, name: object) -> bool:
145
+ return name in self._declared
146
+
147
+ def __iter__(self):
148
+ return iter(self._declared)
149
+
150
+ def __len__(self) -> int:
151
+ return len(self._declared)
152
+
153
+
154
+ def _of_type(value: Any, t: str) -> bool:
155
+ if value is None or t == "ANY":
156
+ return True
157
+ number = isinstance(value, (int, float)) and not isinstance(value, bool)
158
+ return {"INTEGER": isinstance(value, int) and not isinstance(value, bool),
159
+ "FLOAT": number, "NUMBER": number, "STRING": isinstance(value, str),
160
+ "BOOLEAN": isinstance(value, bool)}[t]
161
+
162
+
163
+ def _same(a: Any, b: Any) -> bool:
164
+ """Value equivalence: null is null, a boolean only a boolean, numbers by value."""
165
+ if a is None or b is None:
166
+ return a is None and b is None
167
+ if isinstance(a, bool) or isinstance(b, bool):
168
+ return isinstance(a, bool) and isinstance(b, bool) and a == b
169
+ return type(a) is type(b) and a == b or \
170
+ isinstance(a, (int, float)) and isinstance(b, (int, float)) and a == b
171
+
172
+
173
+ def matching(proc: Procedure, args: List[Any]) -> List[Tuple[Any, ...]]:
174
+ """The outputs of the procedure's rows for these arguments, in its declared order."""
175
+ if len(args) != len(proc.inputs):
176
+ raise ProcedureError(f"InvalidNumberOfArguments: {proc.name} takes {len(proc.inputs)} "
177
+ f"argument(s), given {len(args)}")
178
+ for value, (name, t) in zip(args, proc.inputs):
179
+ if not _of_type(value, t):
180
+ raise ProcedureError(f"InvalidArgumentType: {proc.name}'s {name} is {t}, given {value!r}")
181
+ coerced = [float(v) if t == "FLOAT" and isinstance(v, int) and not isinstance(v, bool) else v
182
+ for v, (_, t) in zip(args, proc.inputs)]
183
+ n = len(proc.inputs)
184
+ return [row[n:] for row in proc.rows if all(_same(v, a) for v, a in zip(row[:n], coerced))]
185
+
186
+
187
+ def find(procedures: Optional[Mapping[str, Procedure]], name: str) -> Procedure:
188
+ proc = procedures[name] if procedures is not None and name in procedures else None
189
+ if proc is None:
190
+ raise ProcedureError(f"ProcedureNotFound: no procedure {name} is declared")
191
+ return proc
@@ -0,0 +1,107 @@
1
+ """Cypher's run-time type errors, raised from SQL where a row evaluates the expression (rule
2
+ cypher-runtime-errors).
3
+
4
+ openCypher raises a TypeError (or ArgumentError) when a row's value is of the wrong kind for an operator or
5
+ function; a query whose rows never reach the expression answers without it. Where the translator knows the
6
+ kind (a literal, a typed column) and it is wrong, the slot code raises `RuntimeTypeError` instead of
7
+ refusing; the dispatchers (`cypher_values.cypher_slot` and `cypher_cell`) turn it into an expression that
8
+ raises the error on a row whose value is not null (a function of null is null). `entry._typed` reads the
9
+ raised text back into a `CypherExecutionError` whose message starts with the TCK's error type and name.
10
+ Where the kind is not known at planning, the refusal by name stays.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from dataclasses import replace
16
+ from typing import TYPE_CHECKING, Dict, Optional, Tuple
17
+
18
+ from prograph.plan.ir import expr as E
19
+ from prograph.plan.ir.facts import NotBuilt
20
+ from prograph.plan.ir.slot import Bound, Slot, value_slot
21
+ from prograph.rules import module_home
22
+ from prograph.schema import xsd
23
+
24
+ if TYPE_CHECKING:
25
+ from prograph.plan.ir import lower as L
26
+
27
+ module_home("cypher-runtime-errors", "A Cypher TypeError raised on a row, from SQL",
28
+ terms=("run time error", "runtime error", "TypeError", "ArgumentError", "InvalidArgumentType",
29
+ "InvalidArgumentValue", "MapElementAccessByNonString", "raise on a row", "wrong kind"))
30
+
31
+ # The text a raised statement carries, before the error's own text ("TypeError: InvalidArgumentType: ...").
32
+ RUNTIME_ERROR_MARK = "ProGraph Cypher run-time error: "
33
+ _SEP = "\x1f"
34
+
35
+ # The calls whose slot code may raise: the cell dispatcher asks only these (a slot worked out again is a cost).
36
+ CHECKED = frozenset({"INDEX", "IN", "RANGE", "FIELD", "KEYS", "SIZE", "REVERSE", "ALL", "ANY", "NONE", "SINGLE",
37
+ "COMPREHENSION", "+", "-", "*", "/", "%", "^", "NEG", "TOSTRING", "TOINTEGER", "TOFLOAT",
38
+ "TOBOOLEAN", "RUNTIME_ERROR"}) | frozenset({"SLICE", "SLICE_FROM", "SLICE_TO", "SLICE_FROM_TO"})
39
+
40
+
41
+ class RuntimeTypeError(NotBuilt):
42
+ """The argument `arg` of a call is of a kind its operator or function raises an error for, wherever a
43
+ row holds it non-null. Still a refusal by name where nothing turns it into the error."""
44
+
45
+ def __init__(self, arg: int, name: str, detail: str, kind: str = "TypeError") -> None:
46
+ self.arg, self.error = arg, f"{kind}: {name}: {detail}"
47
+ super().__init__(detail)
48
+
49
+
50
+ def known_kind(s: Slot) -> bool:
51
+ """The slot's values are of one known kind: a plain value of a known type, a list or a map."""
52
+ from prograph.plan.ir.slot import LIST, MAP, UNKNOWN, VALUE
53
+ if s.present is Bound.NEVER:
54
+ return False
55
+ if s.kinds in ({MAP}, {LIST}):
56
+ return True
57
+ if s.kinds != {VALUE} or UNKNOWN in s.datatypes:
58
+ return False
59
+ from prograph.plan.ir.cypher_answer import element_base
60
+ from prograph.plan.ir.cypher_temporal import TEMPORAL
61
+ # A node or relationship held as a value has keys and properties; a temporal has fields.
62
+ return all(element_base(d) is None and d not in TEMPORAL for d in s.datatypes)
63
+
64
+
65
+ def raising_slot(arg: int, error: str) -> Slot:
66
+ """The slot of a call that raises: a string that is never present, carrying its error in `reason` (the
67
+ cell dispatcher reads it back). Maybe null, so nothing folds the expression away as a constant."""
68
+ return replace(value_slot(xsd.STRING, Bound.MAYBE), reason=f"{RUNTIME_ERROR_MARK}{arg}{_SEP}{error}")
69
+
70
+
71
+ def error_of(slot: Slot) -> Optional[Tuple[int, str]]:
72
+ """(argument, error text) of a slot from `raising_slot`, else None."""
73
+ if not slot.reason or not slot.reason.startswith(RUNTIME_ERROR_MARK):
74
+ return None
75
+ arg, _, error = slot.reason[len(RUNTIME_ERROR_MARK):].partition(_SEP)
76
+ return int(arg), error
77
+
78
+
79
+ def raising_value(value: "object", present: Bound, error: str, L: "L") -> "object":
80
+ """The SQL of an error raised where `value` is not null; null where it is."""
81
+ raised = L.fn("CAST_STRING", L.fn("RAISE_ERROR", L.text(RUNTIME_ERROR_MARK + error)))
82
+ if present is Bound.ALWAYS:
83
+ return raised
84
+ return L.case(L.is_null(value), L.NULL_TEXT, raised)
85
+
86
+
87
+ def runtime_cell(e: E.Call, cells: Dict[str, "L.Cell"]) -> Optional["L.Cell"]:
88
+ """The cell of a call that raises its error on a row (None where the call is as well-kinded as its
89
+ slot says): the call's slot says it, or it is the front end's RUNTIME_ERROR (a literal known wrong)."""
90
+ from prograph.plan.ir import lower as L
91
+ from prograph.plan.ir.cypher_values import cypher_slot
92
+ if e.name not in CHECKED:
93
+ return None
94
+ slot = cypher_slot(e, {n: c.slot for n, c in cells.items()})
95
+ found = error_of(slot)
96
+ if found is None:
97
+ return None
98
+ arg, error = found
99
+ if arg >= len(e.args):
100
+ return None
101
+ cell = L.expr_cell(e.args[arg], cells)
102
+ return L.Cell(slot, raising_value(cell.value, cell.slot.present, error, L))
103
+
104
+
105
+ def runtime_error_call(err: RuntimeTypeError, arg: E.Expr) -> E.Call:
106
+ """The front end's call for a literal known wrong: RUNTIME_ERROR(error text, the argument)."""
107
+ return E.Call("RUNTIME_ERROR", (E.Const(err.error), arg), E.CYPHER)