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,274 @@
1
+ """The functions on RDF terms (SPARQL 1.1 17.4.2): STR, LANG, DATATYPE and
2
+ isNUMERIC, over the plan's cells (m2-functions.md 12).
3
+
4
+ - STR (17.4.2.5): an IRI's text, a literal's lexical form, as a simple
5
+ literal; a blank node is an error (unbound).
6
+ - LANG (17.4.2.6): a literal's language tag, "" where it has none, as a
7
+ simple literal; any other term is an error.
8
+ - DATATYPE (17.4.2.7): a literal's datatype IRI, xsd:string for a simple
9
+ literal and rdf:langString for a tagged one (RDF 1.1, as the SPARQL 1.2
10
+ draft has it); any other term is an error.
11
+ - isNUMERIC (17.4.2.4): true for a literal of a numeric datatype whose
12
+ lexical form is valid, false for any other term.
13
+ - IRI (17.4.2.8): an IRI as it is; a simple literal or xsd:string resolved
14
+ against the query's base; another term, or text that is no valid IRI, an
15
+ error (unbound).
16
+ - STRDT (17.4.2.11), STRLANG (17.4.2.12): a simple literal's lexical form
17
+ with the datatype IRI, or the language tag, given as a constant; another
18
+ term, or a tag that is not one (BCP 47's shape), an error.
19
+
20
+ Where the slot fixes the term's kind, datatype and tag the answer is decided
21
+ at planning; where rows differ it reads the cells' parts (`lower.part`).
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ import re
27
+ from typing import Mapping
28
+
29
+ from prograph.plan.ir import expr as E
30
+ from prograph.plan.ir.facts import NotBuilt, expr_slot
31
+ from prograph.plan.ir.slot import BOOLEAN, NOTHING, UNKNOWN, Bound, Slot, literal_slot
32
+ from prograph.rules import module_home
33
+ from prograph.schema import xsd
34
+ from prograph.schema.source_map import BLANK, IRI, LITERAL
35
+
36
+ module_home("term-functions", "SPARQL's functions on terms: STR, LANG, DATATYPE, isNUMERIC",
37
+ terms=("STR", "LANG", "DATATYPE", "isNUMERIC", "17.4.2"))
38
+
39
+ TERM_CALLS = frozenset({"STR", "LANG", "DATATYPE", "isNUMERIC", "IRI", "STRDT", "STRLANG"})
40
+ # A language tag's shape (BCP 47, as RDF 1.1 3.3 and Turtle's LANGTAG read it).
41
+ _LANGTAG = re.compile(r"[a-zA-Z]+(-[a-zA-Z0-9]+)*")
42
+ _NUMBERS = frozenset(xsd.INTEGER_DATATYPES | {xsd.INTEGER, xsd.DECIMAL, xsd.FLOAT, xsd.DOUBLE})
43
+
44
+
45
+ def term_slot(e: E.Call, slots: Mapping[str, Slot]) -> Slot:
46
+ """The slot of a term function over rows of `slots`."""
47
+ if len(e.args) != (2 if e.name in ("IRI", "STRDT", "STRLANG") else 1):
48
+ raise NotBuilt(f"{e.name} with {len(e.args)} arguments")
49
+ arg = expr_slot(e.args[0], slots)
50
+ if e.name in ("STRDT", "STRLANG"):
51
+ return _built_literal_slot(e, arg)
52
+ if e.name == "IRI":
53
+ if arg.present is Bound.NEVER or not arg.terms:
54
+ return NOTHING
55
+ if IRI not in arg.kinds and not (LITERAL in arg.kinds and xsd.STRING in arg.datatypes):
56
+ return NOTHING
57
+ return Slot(kinds=frozenset({IRI}), bound=Bound.MAYBE)
58
+ if e.name == "isNUMERIC":
59
+ return BOOLEAN
60
+ if arg.present is Bound.NEVER:
61
+ return NOTHING
62
+ if not arg.terms:
63
+ raise NotBuilt(f"{e.name} over a {'/'.join(sorted(arg.kinds))} value")
64
+ takes = {IRI, LITERAL} if e.name == "STR" else {LITERAL}
65
+ if not arg.kinds & takes:
66
+ return NOTHING # every row's term is an error
67
+ always = arg.present is Bound.ALWAYS and arg.kinds <= takes
68
+ bound = Bound.ALWAYS if always else Bound.MAYBE
69
+ if e.name == "DATATYPE":
70
+ return Slot(kinds=frozenset({IRI}), bound=bound)
71
+ return literal_slot(xsd.STRING, bound, native=True)
72
+
73
+
74
+ def _second(e: E.Call):
75
+ """STRDT's datatype IRI or STRLANG's tag, a constant of the query; None otherwise."""
76
+ from prograph.plan.ir.terms import IRITerm, LiteralTerm
77
+ x = e.args[1]
78
+ value = getattr(x, "value", None)
79
+ if e.name == "STRDT":
80
+ return value.text if isinstance(value, IRITerm) else None
81
+ if isinstance(value, LiteralTerm) and value.language is None and value.datatype in (None, xsd.STRING):
82
+ return value.lexical
83
+ return None
84
+
85
+
86
+ def _built_literal_slot(e: E.Call, arg: Slot) -> Slot:
87
+ """STRDT's or STRLANG's slot: a literal of the given datatype or tag, present where the argument
88
+ is a simple literal."""
89
+ second = _second(e)
90
+ if second is None:
91
+ if isinstance(e.args[1], E.Const):
92
+ return NOTHING # a tag that is no simple literal, or a datatype that is no IRI: an error
93
+ raise NotBuilt(f"{e.name} with a datatype or tag that is not a constant")
94
+ if e.name == "STRLANG" and not _LANGTAG.fullmatch(second):
95
+ return NOTHING
96
+ if arg.present is Bound.NEVER or not arg.terms or LITERAL not in arg.kinds or xsd.STRING not in arg.datatypes:
97
+ return NOTHING
98
+ simple = arg.kinds == {LITERAL} and arg.datatypes == {xsd.STRING} and arg.language is None
99
+ bound = Bound.ALWAYS if simple and arg.present is Bound.ALWAYS else Bound.MAYBE
100
+ if e.name == "STRLANG":
101
+ return literal_slot(xsd.RDF_LANGSTRING, bound, language=second.lower())
102
+ return literal_slot(second, bound, native=second == xsd.STRING)
103
+
104
+
105
+ def term_cell(e: E.Call, cells):
106
+ """The cell of STR, LANG, DATATYPE, IRI, STRDT or STRLANG."""
107
+ from prograph.plan.ir import lower as L
108
+ arg = L.expr_cell(e.args[0], cells)
109
+ slot = term_slot(e, {k: c.slot for k, c in cells.items()})
110
+ if slot.present is Bound.NEVER:
111
+ return L.Cell(slot, L.NULL)
112
+ if e.name in ("STRDT", "STRLANG"):
113
+ # The argument's text where it is a simple literal (a literal of xsd:string), else an error.
114
+ s = arg.slot
115
+ tests = []
116
+ if s.kind_varies:
117
+ tests.append(L.eq(L.part(arg, L.KIND), L.text(LITERAL)))
118
+ if s.datatype_varies:
119
+ tests.append(L.eq(L.fn("COALESCE", L.part(arg, L.DT), L.text(xsd.STRING)), L.text(xsd.STRING)))
120
+ value = L.lexical(arg)
121
+ return L.Cell(slot, L.case(L.all_of(tests), value) if tests else value)
122
+ is_literal = L.eq(L.part(arg, L.KIND), L.text(LITERAL)) if arg.slot.kind_varies else None
123
+ if e.name == "IRI":
124
+ return L.Cell(slot, _iri(arg, e.args[1].value.lexical, L))
125
+ if e.name == "STR":
126
+ value = L.lexical(arg)
127
+ if BLANK in arg.slot.kinds:
128
+ value = L.case(L.R.NotExpr(child=L.eq(L.part(arg, L.KIND), L.text(BLANK))), value)
129
+ return L.Cell(slot, value)
130
+ if e.name == "LANG":
131
+ value = L.fn("COALESCE", L.part(arg, L.LANG), L.text(""))
132
+ else: # DATATYPE: a simple literal's is xsd:string
133
+ value = L.fn("COALESCE", L.part(arg, L.DT), L.text(xsd.STRING))
134
+ if arg.slot.present is not Bound.ALWAYS:
135
+ value = L.case(L.is_null(arg.value, negated=True), value)
136
+ if is_literal is not None:
137
+ value = L.case(is_literal, value)
138
+ return L.Cell(slot, value)
139
+
140
+
141
+ def is_numeric(e: E.Call, cells):
142
+ """isNUMERIC as SQL: a native numeric column's value is valid; a term
143
+ of another kind or datatype is not numeric; text held in a column of a
144
+ numeric datatype may be ill-typed, so it is not built."""
145
+ from prograph.plan.ir import lower as L
146
+ arg = L.expr_cell(e.args[0], cells)
147
+ s = arg.slot
148
+ if s.present is Bound.NEVER:
149
+ return L.NULL
150
+ if not s.terms:
151
+ raise NotBuilt(f"isNUMERIC over a {'/'.join(sorted(s.kinds))} value")
152
+ numeric = s.datatypes & _NUMBERS if LITERAL in s.kinds else frozenset()
153
+ if not numeric:
154
+ result = L.FALSE
155
+ elif s.kinds == {LITERAL} and s.datatypes <= _NUMBERS and s.native is not None:
156
+ result = L.TRUE
157
+ elif s.kinds == {LITERAL} and len(s.datatypes) == 1 and L._valid_constants(s):
158
+ result = L.TRUE
159
+ elif UNKNOWN in s.datatypes or s.held_as is not None:
160
+ raise NotBuilt("isNUMERIC over a value of no recorded datatype")
161
+ else:
162
+ # Rows differ, or numbers are text a column holds: a literal of a numeric datatype whose
163
+ # lexical form is valid (`lower.valid_lexical`), per row.
164
+ dt = L.fn("COALESCE", L.part(arg, L.DT), L.text(xsd.STRING))
165
+ result = L.valid_lexical(L.lexical(arg), dt, numeric)
166
+ if s.kind_varies:
167
+ result = L.case(L.eq(L.part(arg, L.KIND), L.text(LITERAL)), result, L.FALSE)
168
+ elif s.kinds != {LITERAL}:
169
+ result = L.FALSE
170
+ return L.case(L.is_null(arg.value, negated=True), result) if s.present is not Bound.ALWAYS else result
171
+
172
+
173
+ def _iri(arg, base: str, L):
174
+ """IRI(arg)'s text: an IRI's, a simple literal's or xsd:string's resolved
175
+ against `base` where it has no scheme; NULL (an error) for another term
176
+ or a result that is no valid IRI (`lower._IRI_SHAPE`)."""
177
+ from prograph.plan.sql import rel_algebra as R
178
+ s = arg.slot
179
+ text = L.lexical(arg)
180
+ takes = []
181
+ if s.kind_varies:
182
+ kind = L.part(arg, L.KIND)
183
+ takes.append(L.eq(kind, L.text(IRI)))
184
+ literal = L.eq(kind, L.text(LITERAL))
185
+ else:
186
+ literal = L.TRUE if s.kinds == {LITERAL} else L.FALSE
187
+ if LITERAL in s.kinds:
188
+ simple = literal
189
+ if s.datatype_varies:
190
+ simple = L.all_of([literal, L.eq(L.fn("COALESCE", L.part(arg, L.DT), L.text(xsd.STRING)),
191
+ L.text(xsd.STRING))])
192
+ elif s.datatype != xsd.STRING:
193
+ simple = L.FALSE
194
+ takes.append(simple)
195
+ if IRI in s.kinds and not s.kind_varies:
196
+ takes = [L.TRUE]
197
+ scheme = R.CompareExpr(left=text, op="RLIKE", right=L.text("^[A-Za-z][A-Za-z0-9+.-]*:"))
198
+ resolved = L.case(scheme, text, L.fn("STR_CONCAT", L.text(base), text)) if base else text
199
+ valid = R.CompareExpr(left=resolved, op="RLIKE", right=L.text(L._IRI_SHAPE))
200
+ return L.case(L.all_of([L.any_of(takes), valid]), resolved)
201
+
202
+
203
+ # -- numeric functions (17.4.4) ----------------------------------------------------------
204
+
205
+ NUMERIC_CALLS = frozenset({"ABS", "CEIL", "FLOOR", "ROUND"})
206
+
207
+
208
+ def numeric_slot(e: E.Call, slots: Mapping[str, Slot]) -> Slot:
209
+ """ABS, CEIL, FLOOR, ROUND (17.4.4, XPath fn:abs ... fn:round): the
210
+ argument's datatype; another term an error (unbound)."""
211
+ from dataclasses import replace
212
+ if len(e.args) != 1:
213
+ raise NotBuilt(f"{e.name} with {len(e.args)} arguments")
214
+ arg = expr_slot(e.args[0], slots)
215
+ if arg.present is Bound.NEVER or not arg.terms or not (LITERAL in arg.kinds and arg.datatypes & _NUMBERS):
216
+ return NOTHING
217
+ if arg.kinds != {LITERAL} or len(arg.datatypes) != 1 or arg.native is None:
218
+ raise NotBuilt(f"{e.name} over a column of several kinds or datatypes, or numbers held as text")
219
+ digits = arg.digits
220
+ if arg.native == xsd.DECIMAL and digits is not None and e.name != "ABS":
221
+ from prograph.plan.ir.facts import rounded_digits
222
+ digits = rounded_digits(digits)
223
+ return replace(arg, provenance=None, held_as=None, digits=digits)
224
+
225
+
226
+ def decimal_round(v, L):
227
+ """A decimal rounded to the nearest integral value, a tie toward positive infinity (fn:round, and
228
+ Cypher's round() as Java's Math.round), by its fraction, exact and never wider than v: t, v truncated
229
+ toward zero (FLOOR of a non-negative, CEIL of a negative: neither grows the magnitude), then t + 1
230
+ where v - t >= 0.5 and t - 1 where v - t < -0.5. A double's 0.5 kept only 15 of a large decimal's
231
+ digits (12345678901234567.49 rounded to ...600, ...568 on DuckDB), and v + 0.5 or
232
+ FLOOR(-99999999999999999999.5) needs a digit more than a DECIMAL(38, s) holds."""
233
+ half = L.R.LitExpr(value=0.5, sql="0.5")
234
+ zero = L.R.LitExpr(value=0, sql="0")
235
+ nonneg = L.R.CompareExpr(left=v, op=">=", right=zero)
236
+ t = L.case(nonneg, L.fn("FLOOR", v), L.fn("CEIL", v))
237
+ exact = L.fn("DECIMAL_SIZED", half, L.integer(2), L.integer(1))
238
+ frac = L.fn("-", v, t)
239
+ up = L.R.CompareExpr(left=frac, op=">=", right=exact)
240
+ minus_half = L.fn("DECIMAL_SIZED", L.R.LitExpr(value=-0.5, sql="-0.5"), L.integer(2), L.integer(1))
241
+ down = L.R.CompareExpr(left=frac, op="<", right=minus_half)
242
+ return L.case(nonneg, L.case(up, L.fn("+", t, L.integer(1)), t),
243
+ L.case(down, L.fn("-", t, L.integer(1)), t))
244
+
245
+
246
+ def numeric_cell(e: E.Call, cells):
247
+ from prograph.plan.ir import lower as L
248
+ arg = L.expr_cell(e.args[0], cells)
249
+ slot = numeric_slot(e, {k: c.slot for k, c in cells.items()})
250
+ if slot.present is Bound.NEVER:
251
+ return L.Cell(slot, L.NULL)
252
+ v = arg.value
253
+ if slot.native in xsd.INTEGER_DATATYPES | {xsd.INTEGER} and e.name != "ABS":
254
+ return L.Cell(slot, v) # an integer is its own ceiling, floor and rounding
255
+ if e.name == "ROUND":
256
+ # fn:round: the nearest integral value, a tie toward positive infinity.
257
+ half = L.R.LitExpr(value=0.5, sql="0.5")
258
+ if slot.native == xsd.DECIMAL:
259
+ value = decimal_round(v, L)
260
+ else:
261
+ value = L.fn("FLOOR", L.fn("+", v, half))
262
+ if slot.native in (xsd.DOUBLE, xsd.FLOAT):
263
+ # A double in [-0.5, 0] rounds to a zero of its sign (F&O fn:round: round(-0.5) is -0;
264
+ # long fuzz): v * 0.0 is that zero.
265
+ near = L.all_of([L.R.CompareExpr(left=v, op=">=", right=L.R.LitExpr(value=-0.5, sql="-0.5")),
266
+ L.R.CompareExpr(left=v, op="<=", right=L.R.LitExpr(value=0, sql="0"))])
267
+ value = L.case(near, L.fn("*", v, L.R.LitExpr(value=0.0, sql="0.0")), value)
268
+ else:
269
+ value = L.fn(e.name, v)
270
+ if slot.native == xsd.DECIMAL and slot.digits is not None:
271
+ value = L.fn("DECIMAL_SIZED", value, L.integer(slot.digits[0]), L.integer(slot.digits[1]))
272
+ elif slot.native in (xsd.DOUBLE, xsd.FLOAT) and e.name != "ABS":
273
+ value = L.fn("CAST_DOUBLE", value) # Spark's CEIL and FLOOR of a double are a BIGINT
274
+ return L.Cell(slot, value)
@@ -0,0 +1,84 @@
1
+ """RDF terms as the one plan holds them, written as the query wrote them.
2
+
3
+ A constant of a plan (`Const`) and a cell of a `Values` table hold an RDF
4
+ term (RDF 1.1 Concepts 3) as one of the three classes here, or a Cypher
5
+ value as Python holds it (None for null, a bool, an int, a float, a str, a
6
+ tuple for a list, a `CypherMap` for a map). Two terms are one term exactly
7
+ where they are equal objects (SPARQL's sameTerm, RDF 1.1 3.4 and 3.3): a
8
+ literal keeps its lexical form as written, so `"01"^^xsd:integer` and
9
+ `"1"^^xsd:integer` are two terms of one value.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ from dataclasses import dataclass
15
+ from typing import Any, Optional, Tuple
16
+
17
+ from prograph.schema import xsd
18
+ from prograph.schema.source_map import RR_DEFAULT_GRAPH
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class IRITerm:
23
+ """An IRI, by its text."""
24
+ text: str
25
+
26
+ def __repr__(self) -> str:
27
+ return f"<{self.text}>"
28
+
29
+
30
+ @dataclass(frozen=True)
31
+ class BlankTerm:
32
+ """A blank node, by its label (without `_:`)."""
33
+ label: str
34
+
35
+ def __repr__(self) -> str:
36
+ return f"_:{self.label}"
37
+
38
+
39
+ @dataclass(frozen=True)
40
+ class LiteralTerm:
41
+ """A literal: its lexical form as written, its datatype IRI and its
42
+ language tag (lower case). A tagged literal's datatype is
43
+ rdf:langString and an untagged one's with none given xsd:string (RDF
44
+ 1.1 3.3), so that equal terms are equal objects."""
45
+ lexical: str
46
+ datatype: Optional[str] = None
47
+ language: Optional[str] = None
48
+
49
+ def __post_init__(self) -> None:
50
+ if self.language is not None:
51
+ object.__setattr__(self, "language", self.language.lower())
52
+ object.__setattr__(self, "datatype", xsd.RDF_LANGSTRING)
53
+ elif self.datatype is None:
54
+ object.__setattr__(self, "datatype", xsd.STRING)
55
+ elif self.datatype == xsd.RDF_LANGSTRING:
56
+ raise ValueError("rdf:langString needs a language tag")
57
+
58
+ def __repr__(self) -> str:
59
+ if self.language:
60
+ return f'"{self.lexical}"@{self.language}'
61
+ return f'"{self.lexical}"^^<{self.datatype}>'
62
+
63
+
64
+ @dataclass(frozen=True)
65
+ class CypherMap:
66
+ """A Cypher map value, its entries sorted by key so that equal maps are
67
+ equal objects."""
68
+ entries: Tuple[Tuple[str, Any], ...]
69
+
70
+
71
+ @dataclass(frozen=True)
72
+ class CypherPath:
73
+ """A Cypher path value: its nodes and the relationships between them,
74
+ one more node than relationships."""
75
+ nodes: Tuple[Any, ...]
76
+ relationships: Tuple[Any, ...]
77
+
78
+
79
+ # The graph a map's triple is in where it names none: the default graph, as
80
+ # R2RML spells it (R2RML 6.4). A quad scan's graph column holds it.
81
+ DEFAULT_GRAPH = IRITerm(RR_DEFAULT_GRAPH)
82
+
83
+ TERM_CLASSES = (IRITerm, BlankTerm, LiteralTerm)
84
+
@@ -0,0 +1,264 @@
1
+ """An XPath regular expression, rewritten for each engine (SPARQL 1.1 17.4.3.14 -> XPath F&O 5.6).
2
+
3
+ REGEX's pattern is XPath's (XML Schema regex with `^` and `$` added); no engine reads it as it is:
4
+ DuckDB uses RE2, Spark and Databricks Java's regex, PostgreSQL its ARE. A constant pattern is
5
+ parsed here against the subset all of them read alike, and written again once for each:
6
+
7
+ - literal characters, their metacharacters escaped; `.`, `*`, `+`, `?` (each also reluctant),
8
+ `{n}`, `{n,}`, `{n,m}`, `|`, `( )`, `^`, `$`, and bracket classes of literal characters and
9
+ ranges (negated or not);
10
+ - `.` is `[^\\n]` (F&O 2E's `.` misses only the newline; PostgreSQL's matches it, Java's misses
11
+ U+0085, U+2028 and U+2029 as well);
12
+ - `$` is the end of the string (`\\z` in RE2 and Java, where `$` also matches before a final
13
+ newline; PostgreSQL's `$` is the end already);
14
+ - flags: `i` (`(?i)`, with `u` in Java so case folding is Unicode's) and `s` (`.` matches every
15
+ character, the newline too: `(?s)` in Java and RE2; PostgreSQL's `.` does already).
16
+
17
+ A pattern outside the subset is `NotBuilt`, naming the construct (a class escape such as `\\d`,
18
+ `\\p{..}`, a back-reference, class subtraction, `(?`, the flags `m x q`); a pattern that is no
19
+ XPath regex is `InvalidPattern`, which the standard calls an error (17.4.3.14), here found at
20
+ planning. Matching is a search (fn:matches), as each engine's operator is.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ from dataclasses import dataclass
26
+ from typing import List, Optional, Tuple
27
+
28
+ from prograph.plan.ir.facts import NotBuilt
29
+ from prograph.rules import home
30
+
31
+
32
+ class InvalidPattern(ValueError):
33
+ """The pattern is no XPath regular expression (an error, 17.4.3.14)."""
34
+
35
+
36
+ @dataclass(frozen=True)
37
+ class Translated:
38
+ """One pattern as each engine reads it: Java (Spark, Databricks), RE2
39
+ (DuckDB) and PostgreSQL's ARE."""
40
+ java: str
41
+ re2: str
42
+ pg: str
43
+
44
+
45
+ _END = None # a piece that is the end of the string; written per engine
46
+ _DOT = object() # `.`: [^\n] without the s flag, any character with it; written per engine
47
+ _META = set("\\|.-^?*+{}()[]$")
48
+ _SINGLE = {"n": "\\n", "r": "\\r", "t": "\\t"}
49
+ _CLASS_ESCAPES = set("sSiIcCdDwWpP")
50
+ _MAX_REPEAT = 1000 # RE2's limit on a repeat count
51
+
52
+
53
+ @home("xpath-regex", "An XPath regular expression for each engine",
54
+ terms=("REGEX", "pattern", "XPath regex", "RE2", "ARE", "regex flags", "fn:matches"))
55
+ def translate(pattern: str, flags: str = "") -> Translated:
56
+ """`pattern` with `flags` for each engine. Raises `InvalidPattern` for
57
+ a pattern that is no XPath regex and `NotBuilt` for one outside the
58
+ subset (see the module's text)."""
59
+ for f in flags:
60
+ if f in "mxq":
61
+ raise NotBuilt(f"the REGEX flag {f!r} (only i and s are built)")
62
+ if f not in "is":
63
+ raise InvalidPattern(f"no REGEX flag {f!r}")
64
+ pieces, i = _alternation(pattern, 0, top=True)
65
+ if i != len(pattern):
66
+ raise InvalidPattern("an unmatched ')'")
67
+ parts = _flatten(pieces)
68
+
69
+ s_on = "s" in flags
70
+ dot = "." if s_on else "[^\\n]"
71
+
72
+ def write(end: str, prefix: str) -> str:
73
+ return prefix + "".join(end if p is _END else dot if p is _DOT else p for p in parts)
74
+
75
+ def opts(*names: str) -> str:
76
+ on = "".join(n for n in names if n)
77
+ return f"(?{on})" if on else ""
78
+ i_on = "i" in flags
79
+ return Translated(write("\\z", opts("i" if i_on else "", "s" if s_on else "", "u" if i_on else "")),
80
+ write("\\z", opts("i" if i_on else "", "s" if s_on else "")),
81
+ write("$", opts("i" if i_on else "")))
82
+
83
+
84
+ def _flatten(pieces) -> List[Optional[str]]:
85
+ out: List[Optional[str]] = []
86
+ for p in pieces:
87
+ if isinstance(p, list):
88
+ out.extend(_flatten(p))
89
+ else:
90
+ out.append(p)
91
+ return out
92
+
93
+
94
+ def _alternation(s: str, i: int, top: bool = False):
95
+ """regExp ::= branch ('|' branch)*, from `i`, to a ')' or the end."""
96
+ out: list = []
97
+ while True:
98
+ branch, i = _branch(s, i)
99
+ out.append(branch)
100
+ if i < len(s) and s[i] == "|":
101
+ out.append("|")
102
+ i += 1
103
+ continue
104
+ return out, i
105
+
106
+
107
+ def _branch(s: str, i: int):
108
+ out: list = []
109
+ while i < len(s) and s[i] not in "|)":
110
+ piece, i = _piece(s, i)
111
+ out.append(piece)
112
+ return out, i
113
+
114
+
115
+ def _piece(s: str, i: int):
116
+ atom, i, anchor = _atom(s, i)
117
+ quantifier, i = _quantifier(s, i)
118
+ if quantifier and anchor:
119
+ raise NotBuilt("a quantifier on ^ or $")
120
+ return [atom, quantifier] if quantifier else atom, i
121
+
122
+
123
+ def _quantifier(s: str, i: int) -> Tuple[str, int]:
124
+ if i >= len(s):
125
+ return "", i
126
+ c = s[i]
127
+ if c in "*+?":
128
+ q, i = c, i + 1
129
+ elif c == "{":
130
+ j = s.find("}", i)
131
+ if j < 0:
132
+ raise InvalidPattern("a '{' with no '}'")
133
+ body = s[i + 1:j]
134
+ lo, comma, hi = body.partition(",")
135
+ if not lo.isascii() or not lo.isdigit() or (comma and hi and not (hi.isascii() and hi.isdigit())):
136
+ raise InvalidPattern(f"the quantifier {{{body}}}")
137
+ if hi and int(hi) < int(lo):
138
+ raise InvalidPattern(f"the quantifier {{{body}}}: the upper bound is below the lower")
139
+ if int(lo) > _MAX_REPEAT or (hi and int(hi) > _MAX_REPEAT):
140
+ raise NotBuilt(f"a repeat count past {_MAX_REPEAT}")
141
+ q, i = "{" + body + "}", j + 1
142
+ else:
143
+ return "", i
144
+ if i < len(s) and s[i] == "?":
145
+ q, i = q + "?", i + 1
146
+ if i < len(s) and s[i] in "*+?{":
147
+ raise InvalidPattern("a quantifier on a quantifier")
148
+ return q, i
149
+
150
+
151
+ def _atom(s: str, i: int):
152
+ """An atom, the next index, and whether it is an anchor."""
153
+ c = s[i]
154
+ if c == ".":
155
+ # F&O 2nd edition 7.6.1.1, which SPARQL 1.1 cites: without the s flag
156
+ # `.` misses only the newline (F&O 3.1 and XML Schema miss \r too;
157
+ # Oxigraph follows 2E, Jena's Java regex departs).
158
+ return _DOT, i + 1, False
159
+ if c == "^":
160
+ return "^", i + 1, True
161
+ if c == "$":
162
+ return _END, i + 1, True
163
+ if c == "(":
164
+ if s.startswith("(?", i):
165
+ raise NotBuilt("a group opened with '(?' (non-capturing, lookahead or flags)")
166
+ inner, j = _alternation(s, i + 1)
167
+ if j >= len(s) or s[j] != ")":
168
+ raise InvalidPattern("a '(' with no ')'")
169
+ return ["(", inner, ")"], j + 1, False
170
+ if c == "[":
171
+ return _class(s, i)
172
+ if c in "*+?":
173
+ raise InvalidPattern(f"a quantifier {c!r} with nothing before it")
174
+ if c == "{":
175
+ raise InvalidPattern("a '{' with nothing before it")
176
+ if c in "]}":
177
+ raise NotBuilt(f"an unescaped {c!r} (Java reads it as itself, XPath's grammar refuses it)")
178
+ if c == "\\":
179
+ return _escape(s, i, in_class=False)
180
+ return _literal(c), i + 1, False
181
+
182
+
183
+ def _literal(c: str) -> str:
184
+ if c in _META:
185
+ return "\\" + c
186
+ if c in "\n\r\t":
187
+ return {"\n": "\\n", "\r": "\\r", "\t": "\\t"}[c]
188
+ return c
189
+
190
+
191
+ def _escape(s: str, i: int, in_class: bool):
192
+ if i + 1 >= len(s):
193
+ raise InvalidPattern("a '\\' at the end")
194
+ c = s[i + 1]
195
+ if c in _SINGLE:
196
+ return _SINGLE[c], i + 2, False
197
+ if c in _META:
198
+ return "\\" + c, i + 2, False
199
+ if c in _CLASS_ESCAPES:
200
+ what = {"p": "\\p{..}", "P": "\\P{..}"}.get(c, "\\" + c)
201
+ raise NotBuilt(f"the class escape {what} (Unicode classes are not the engines' alike)")
202
+ if c.isdigit() and c != "0":
203
+ raise NotBuilt("a back-reference")
204
+ # Outside XML Schema's escapes (F.1.1 [24], F&O adding `$`): the grammar
205
+ # refuses it. Before punctuation (`\%`) Jena and Oxigraph both read it as
206
+ # the character, so a refusal rather than an error until that departure
207
+ # is settled; before a letter (`\q`) Java refuses it too: an error.
208
+ if not c.isalnum():
209
+ raise NotBuilt(f"the escape \\{c} (no XPath escape; Jena and Oxigraph read it as {c!r})")
210
+ raise InvalidPattern(f"the escape \\{c}")
211
+
212
+
213
+ def _class(s: str, i: int):
214
+ """charClassExpr ::= '[' '^'? (char | range)+ ']'; subtraction is not built."""
215
+ j = i + 1
216
+ out = ["["]
217
+ if j < len(s) and s[j] == "^":
218
+ out.append("^")
219
+ j += 1
220
+ items = 0
221
+ while True:
222
+ if j >= len(s):
223
+ raise InvalidPattern("a '[' with no ']'")
224
+ c = s[j]
225
+ if c == "]" and items:
226
+ return "".join(out) + "]", j + 1, False
227
+ if c == "[":
228
+ raise NotBuilt("a '[' inside a class (subtraction or a nested class)")
229
+ lo, j = _class_char(s, j, first=not items)
230
+ items += 1
231
+ # a range lo-hi, unless the '-' is last (a literal) or opens a subtraction
232
+ if j + 1 < len(s) and s[j] == "-" and s[j + 1] != "]":
233
+ if s[j + 1] == "[":
234
+ raise NotBuilt("class subtraction")
235
+ hi, j2 = _class_char(s, j + 1, first=False)
236
+ if ord(_unescape(hi)) < ord(_unescape(lo)):
237
+ raise InvalidPattern(f"the range {lo}-{hi} runs backwards")
238
+ out.append(lo + "-" + hi)
239
+ j = j2
240
+ else:
241
+ out.append(lo)
242
+
243
+
244
+ def _class_char(s: str, j: int, first: bool) -> Tuple[str, int]:
245
+ c = s[j]
246
+ if c == "\\":
247
+ text, j, _ = _escape(s, j, in_class=True)
248
+ return text, j
249
+ if c == "-" and not first and j + 1 < len(s) and s[j + 1] == "[":
250
+ raise NotBuilt("class subtraction")
251
+ if c == "-" and not first and not (j + 1 < len(s) and s[j + 1] == "]"):
252
+ raise NotBuilt("a '-' in a class that is neither a range nor first or last")
253
+ if c == "-":
254
+ return "\\-", j + 1
255
+ if c == "^" or c == "&":
256
+ return "\\" + c, j + 1
257
+ return _literal(c) if c in "\n\r\t" else c, j + 1
258
+
259
+
260
+ def _unescape(written: str) -> str:
261
+ """The character a class character was written for."""
262
+ if written.startswith("\\") and len(written) == 2:
263
+ return {"n": "\n", "r": "\r", "t": "\t"}.get(written[1], written[1])
264
+ return written
@@ -0,0 +1,65 @@
1
+ """How one `ProGraph.execute` call ran: the SQL statements the database
2
+ was sent.
3
+
4
+ The query path logs each statement it sends (`compositional_backend_executed`)
5
+ and a statement the database rejected (`sql_runtime_error`). `observe()`
6
+ captures those events for the calls inside its block
7
+ (`prograph.logging.capture_events`, context-local), and `Run` is read from
8
+ them; nothing is added to the result path. The MCP tools return it with
9
+ the rows: the SQL that ran, never a guess.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import contextlib
15
+ from dataclasses import dataclass, field
16
+ from typing import Iterator, List, Optional
17
+ from prograph.rules import module_home
18
+
19
+ module_home("run-record", "The SQL a call ran",
20
+ terms=("observe", "what ran", "SQL sent", "run record", "compositional_backend_executed"))
21
+
22
+ _EXECUTED = "compositional_backend_executed"
23
+
24
+
25
+ @dataclass
26
+ class Run:
27
+ """`ran_in` is 'sql' once a statement ran, else None. `statements` are
28
+ the SQL texts the database was sent, in order, `sql` the last that ran;
29
+ `failed` is one it rejected, with `error`."""
30
+ ran_in: Optional[str] = None
31
+ reason: Optional[str] = None
32
+ statements: List[str] = field(default_factory=list)
33
+ sql: Optional[str] = None
34
+ failed: Optional[str] = None
35
+ error: Optional[str] = None
36
+
37
+
38
+ def read(events: List[dict]) -> Run:
39
+ """The run the events of one call tell."""
40
+ run = Run()
41
+ for event in events:
42
+ name = event.get("event")
43
+ if name == _EXECUTED and event.get("sql"):
44
+ run.statements.append(event["sql"])
45
+ run.ran_in, run.sql = "sql", event["sql"]
46
+ elif name == "sql_runtime_error":
47
+ run.failed, run.error = event.get("sql"), event.get("error")
48
+ return run
49
+
50
+
51
+ @contextlib.contextmanager
52
+ def observe() -> Iterator["_Observed"]:
53
+ """The run of the calls made inside the block: `.run` after it."""
54
+ from prograph.logging import capture_events
55
+ observed = _Observed()
56
+ with capture_events() as captured:
57
+ yield observed
58
+ observed.run = read(captured.events)
59
+
60
+
61
+ class _Observed:
62
+ run: Optional[Run] = None
63
+
64
+
65
+ __all__ = ["Run", "read", "observe"]