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,265 @@
1
+ """A Java date pattern (SimpleDateFormat for apoc.date, DateTimeFormatter for apoc.temporal) for each engine:
2
+ one translation table from each pattern letter to what ProGraph writes for it.
3
+
4
+ A pattern is read into literal text and letter runs (`'...'` quotes text, `''` is a quote). Each run is
5
+ looked up in `TABLE` by style ("simple": java.text.SimpleDateFormat; "formatter":
6
+ java.time.format.DateTimeFormatter) and letter, and becomes a `Field`: what it shows (a year, a month's name,
7
+ an offset ...) and its width. Formatting writes each field from the value's parts in SQL (the same on every
8
+ engine; names in English, APOC's locale). Parsing writes each field's token in the engine's own format
9
+ string (DuckDB's strptime, Spark's and Databricks' datetime patterns), for the fields the table gives one.
10
+ A letter the table has no row for, or a width it does not build, raises `NotBuilt` naming the letter: never
11
+ a near miss.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ from dataclasses import dataclass
17
+ from typing import Callable, Dict, List, Optional, Tuple, Union
18
+
19
+ from prograph.plan.ir.facts import NotBuilt
20
+ from prograph.rules import home
21
+
22
+ SIMPLE, FORMATTER = "simple", "formatter"
23
+
24
+ DATE_KINDS = frozenset({"era", "era_long", "year", "year2", "month", "month_short", "month_long", "day", "doy", "dow_short",
25
+ "dow_long", "isoyear", "isoweek", "isodow"})
26
+ TIME_KINDS = frozenset({"hour", "hour12", "minute", "second", "millis", "fraction", "nano", "ampm"})
27
+ ZONE_KINDS = frozenset({"offset_hhmm", "offset_x1", "offset_x2", "offset_x3", "offset_dx1", "offset_dx2",
28
+ "offset_dx3", "offset_lx1", "offset_lx2", "offset_lx3", "zone_short", "zone_long", "zone_id",
29
+ "offset_gmt", "zone_bracket"})
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class Field:
34
+ """One letter run: what it shows and its width (the least number of digits, a name's length class)."""
35
+ kind: str
36
+ width: int
37
+ letter: str
38
+
39
+
40
+ Piece = Union[str, Field]
41
+
42
+
43
+ def _numeric(kind: str, most: Optional[int] = None) -> Callable[[str, int], Field]:
44
+ def make(letter: str, n: int) -> Field:
45
+ if most is not None and n > most:
46
+ raise NotBuilt(f"the pattern letter {letter!r} {n} times (at most {most})")
47
+ return Field(kind, n, letter)
48
+ return make
49
+
50
+
51
+ def _text_or_number(number: str, short: str, long: str, narrow_refused: bool = True):
52
+ def make(letter: str, n: int) -> Field:
53
+ if n <= 2:
54
+ return Field(number, n, letter)
55
+ if n == 3:
56
+ return Field(short, n, letter)
57
+ if n == 4 or (n > 4 and not narrow_refused):
58
+ return Field(long, n, letter)
59
+ raise NotBuilt(f"the pattern letter {letter!r} {n} times (a narrow name)")
60
+ return make
61
+
62
+
63
+ def _names(short: str, long: str, longest: Optional[int] = None):
64
+ def make(letter: str, n: int) -> Field:
65
+ if longest is not None and n > longest:
66
+ raise NotBuilt(f"the pattern letter {letter!r} {n} times (a narrow name)")
67
+ return Field(short if n <= 3 else long, n, letter)
68
+ return make
69
+
70
+
71
+ def _year(letter: str, n: int) -> Field:
72
+ return Field("year2" if n == 2 else "year", n, letter)
73
+
74
+
75
+ def _fixed(kind: str):
76
+ return lambda letter, n: Field(kind, n, letter)
77
+
78
+
79
+ def _simple_x(letter: str, n: int) -> Field:
80
+ if n > 3:
81
+ raise NotBuilt("the pattern letter 'X' 4 times (an error in Java)")
82
+ return Field(f"offset_x{n}", n, letter)
83
+
84
+
85
+ def _formatter_offset(lower: bool):
86
+ def make(letter: str, n: int) -> Field:
87
+ if n > 3:
88
+ raise NotBuilt(f"the pattern letter {letter!r} {n} times (seconds of an offset)")
89
+ return Field(f"offset_{'l' if lower else 'd'}x{n}", n, letter)
90
+ return make
91
+
92
+
93
+ def _formatter_z(letter: str, n: int) -> Field:
94
+ if n <= 3:
95
+ return Field("offset_hhmm", n, letter)
96
+ if n == 4:
97
+ return Field("offset_gmt", n, letter)
98
+ return Field("offset_dx3", n, letter)
99
+
100
+
101
+ def _zone_id(letter: str, n: int) -> Field:
102
+ if n != 2:
103
+ raise NotBuilt(f"the pattern letter 'V' {n} times (only VV, the zone's id)")
104
+ return Field("zone_id", n, letter)
105
+
106
+
107
+ def _formatter_fraction(letter: str, n: int) -> Field:
108
+ if n > 9:
109
+ raise NotBuilt("a fraction of more than 9 digits")
110
+ return Field("fraction", n, letter)
111
+
112
+
113
+ TABLE: Dict[str, Dict[str, Callable[[str, int], Field]]] = {
114
+ SIMPLE: {
115
+ "G": _fixed("era"), "y": _year, "M": _text_or_number("month", "month_short", "month_long", False),
116
+ "d": _numeric("day"), "H": _numeric("hour"), "h": _numeric("hour12"), "m": _numeric("minute"),
117
+ "s": _numeric("second"), "S": _numeric("millis"), "E": _names("dow_short", "dow_long"),
118
+ "a": _fixed("ampm"), "D": _numeric("doy"), "Z": _fixed("offset_hhmm"), "X": _simple_x,
119
+ "z": lambda letter, n: Field("zone_short" if n < 4 else "zone_long", n, letter),
120
+ },
121
+ FORMATTER: {
122
+ "G": lambda letter, n: Field("era_long" if n == 4 else "era", n, letter) if n <= 4 else
123
+ (_ for _ in ()).throw(NotBuilt("the pattern letter 'G' 5 times (a narrow name)")),
124
+ "u": _year, "y": _year, "M": _text_or_number("month", "month_short", "month_long"),
125
+ "L": _text_or_number("month", "month_short", "month_long"), "d": _numeric("day", 2),
126
+ "D": _numeric("doy", 3), "H": _numeric("hour", 2), "h": _numeric("hour12", 2), "m": _numeric("minute", 2),
127
+ "s": _numeric("second", 2), "S": _formatter_fraction, "n": _numeric("nano"),
128
+ "E": _names("dow_short", "dow_long", 4), "a": lambda letter, n: Field("ampm", n, letter) if n == 1 else
129
+ (_ for _ in ()).throw(NotBuilt("the pattern letter 'a' more than once (an error in Java)")),
130
+ "X": _formatter_offset(False), "x": _formatter_offset(True), "Z": _formatter_z, "VV": _zone_id,
131
+ "V": _zone_id,
132
+ },
133
+ }
134
+ """Each style's letters: a function of the letter and its count to its `Field`. Letters with no row
135
+ (SimpleDateFormat's Y w W F u k K L; DateTimeFormatter's Y w W e c Q q k K z O and the reserved [ ] { } #) are
136
+ refused by name."""
137
+
138
+ _RESERVED = set("[]{}#")
139
+
140
+
141
+ @home("java-datetime-pattern", "A Java date pattern (APOC's) for each engine",
142
+ terms=("SimpleDateFormat", "DateTimeFormatter", "date pattern", "pattern letter", "strftime", "date_format",
143
+ "strptime", "apoc.date.format", "apoc.temporal.format"))
144
+ def compile_pattern(pattern: str, style: str) -> List[Piece]:
145
+ """`pattern` as literal text and `Field`s, by `TABLE` (see the module's text); `NotBuilt` naming a
146
+ letter, or a width, the table has no row for."""
147
+ out: List[Piece] = []
148
+ i, text = 0, ""
149
+ while i < len(pattern):
150
+ c = pattern[i]
151
+ if c == "'":
152
+ j = pattern.find("'", i + 1)
153
+ while j >= 0 and j + 1 < len(pattern) and pattern[j + 1] == "'":
154
+ j = pattern.find("'", j + 2)
155
+ if j < 0:
156
+ raise NotBuilt("an unclosed quote in the pattern (an error in Java)")
157
+ if j == i + 1:
158
+ text += "'"
159
+ else:
160
+ text += pattern[i + 1:j].replace("''", "'")
161
+ i = j + 1
162
+ continue
163
+ if ("a" <= c <= "z") or ("A" <= c <= "Z"):
164
+ j = i
165
+ while j < len(pattern) and pattern[j] == c:
166
+ j += 1
167
+ n = j - i
168
+ row = TABLE[style].get("VV" if style == FORMATTER and c == "V" else c)
169
+ if row is None:
170
+ raise NotBuilt(f"the pattern letter {c!r} (not built: "
171
+ f"{'a week-based or locale field' if c in 'YwWeckFuKLQq' else 'no row in the table'})")
172
+ if text:
173
+ out.append(text)
174
+ text = ""
175
+ out.append(row(c, n))
176
+ i = j
177
+ continue
178
+ if style == FORMATTER and c in _RESERVED:
179
+ raise NotBuilt(f"the pattern character {c!r} (an optional section or a reserved character)")
180
+ text += c
181
+ i += 1
182
+ if text:
183
+ out.append(text)
184
+ return out
185
+
186
+
187
+ # DateTimeFormatter's named formats APOC reads (DateFormatUtil.getOrCreate): the ISO formatters as patterns
188
+ # where one pattern writes them, and the Elasticsearch names as APOC maps them.
189
+ NAMED = {
190
+ "basic_iso_date": "yyyyMMdd", "iso_date": "yyyy-MM-dd", "iso_local_date": "yyyy-MM-dd",
191
+ "iso_local_time": None, "iso_local_date_time": None, "iso_date_time": None, "iso_time": None,
192
+ "iso_week_date": None, "iso_ordinal_date": "yyyy-DDD", "iso_instant": None, "iso_offset_date": None,
193
+ "iso_offset_date_time": None, "iso_offset_time": None, "iso_zoned_date_time": None, "rfc_1123_date_time": None,
194
+ "basic_date": "yyyyMMdd", "date": "yyyy-MM-dd", "date_hour": "yyyy-MM-dd'T'HH",
195
+ "date_hour_minute": "yyyy-MM-dd'T'HH:mm", "date_hour_minute_second": "yyyy-MM-dd'T'HH:mm:ss",
196
+ "date_hour_minute_second_fraction": "yyyy-MM-dd'T'HH:mm:ss.SSS",
197
+ "date_hour_minute_second_millis": "yyyy-MM-dd'T'HH:mm:ss.SSS", "hour": "HH", "hour_minute": "HH:mm",
198
+ "hour_minute_second": "HH:mm:ss", "hour_minute_second_fraction": "HH:mm:ss.SSS",
199
+ "hour_minute_second_millis": "HH:mm:ss.SSS", "ordinal_date": "yyyy-DDD", "year": "yyyy",
200
+ "year_month": "yyyy-MM", "year_month_day": "yyyy-MM-dd",
201
+ }
202
+ """A named format's pattern; None where no one pattern writes it (ProGraph writes those itself, or refuses)."""
203
+
204
+
205
+ # Parsing: each field's token in the engine's format string (DuckDB strptime, Spark datetime pattern).
206
+ _PARSE = {
207
+ ("year", 4): ("%Y", "yyyy"), ("month", 2): ("%m", "MM"), ("month", 1): ("%m", "M"),
208
+ ("month_short", 3): ("%b", "MMM"), ("month_long", 4): ("%B", "MMMM"), ("day", 2): ("%d", "dd"),
209
+ ("day", 1): ("%d", "d"), ("hour", 2): ("%H", "HH"), ("hour", 1): ("%H", "H"), ("hour12", 2): ("%I", "hh"),
210
+ ("hour12", 1): ("%I", "h"), ("minute", 2): ("%M", "mm"), ("minute", 1): ("%M", "m"),
211
+ ("second", 2): ("%S", "ss"), ("second", 1): ("%S", "s"), ("millis", 3): ("%g", "SSS"),
212
+ ("dow_short", 3): ("%a", None), ("dow_long", 4): ("%A", None), ("ampm", 1): ("%p", "a"),
213
+ }
214
+
215
+
216
+ def parse_formats(pieces: List[Piece]) -> Tuple[str, Optional[str]]:
217
+ """The pieces as DuckDB's strptime format and Spark's datetime pattern (None where Spark's parser reads a
218
+ field no pattern of its gives: a day-of-week name); `NotBuilt` naming a letter no engine parses alike (a
219
+ two-digit year, which Java reads in a window around today, among them)."""
220
+ duck, spark = "", ""
221
+ if any(isinstance(p, Field) and p.kind == "hour12" for p in pieces) and \
222
+ not any(isinstance(p, Field) and p.kind == "ampm" for p in pieces):
223
+ raise NotBuilt("parsing the pattern letter 'h' with no 'a' (Java reads the hour as AM, DuckDB's parser "
224
+ "as it is)")
225
+ for p in pieces:
226
+ if isinstance(p, str):
227
+ duck += p.replace("%", "%%")
228
+ # Spark's pattern takes punctuation, digits and spaces as they are; a letter or a quote would need
229
+ # the pattern's quotes, which a SQL literal cannot carry to every engine alike.
230
+ if any(c.isalpha() or c in "'[]{}#" for c in p):
231
+ raise NotBuilt(f"parsing a pattern with the literal text {p!r} (letters or quotes in it)")
232
+ spark = None if spark is None else spark + p
233
+ continue
234
+ token = _PARSE.get((p.kind, p.width))
235
+ if token is None:
236
+ raise NotBuilt(f"parsing the pattern letter {p.letter!r} {p.width} times")
237
+ duck += token[0]
238
+ if token[1] is None or spark is None: # Spark's parser reads no day-of-week name
239
+ spark = None
240
+ else:
241
+ spark += token[1]
242
+ return duck, spark
243
+
244
+
245
+ def kinds(pieces: List[Piece]) -> set:
246
+ return {p.kind for p in pieces if isinstance(p, Field)}
247
+
248
+
249
+ _SHAPES = {"year": "[0-9]+", "month": "[0-9]{1,2}", "day": "[0-9]{1,2}", "hour": "[0-9]{1,2}",
250
+ "hour12": "[0-9]{1,2}", "minute": "[0-9]{1,2}", "second": "[0-9]{1,2}", "millis": "[0-9]{3}",
251
+ "month_short": "[A-Za-z]+", "month_long": "[A-Za-z]+", "dow_short": "[A-Za-z]+",
252
+ "dow_long": "[A-Za-z]+", "ampm": "[AaPp][Mm]"}
253
+
254
+
255
+ def millis_shape(pieces: List[Piece]) -> Optional[str]:
256
+ """Where the pattern parses milliseconds (SSS), a regex of text whose milliseconds are exactly three
257
+ digits: SimpleDateFormat reads `.5` as 5 ms, the engines' parsers as 500, so other text must raise. None
258
+ for a pattern with no milliseconds."""
259
+ import re
260
+ if not any(isinstance(p, Field) and p.kind == "millis" for p in pieces):
261
+ return None
262
+ out = "^"
263
+ for p in pieces:
264
+ out += re.escape(p) if isinstance(p, str) else _SHAPES[p.kind]
265
+ return out + "$"
@@ -0,0 +1,391 @@
1
+ """A Java regular expression (java.util.regex, as APOC's text functions read one) for each engine.
2
+
3
+ Spark and Databricks read Java's patterns themselves (their regex functions are java.util.regex), so a pattern
4
+ goes to them as it is written, its replacement string too. DuckDB reads RE2: a constant pattern is parsed here
5
+ against the constructs both read alike and written again for RE2, and anything else is refused by name
6
+ (`NotBuilt`), never translated to a near miss:
7
+
8
+ - literal characters (RE2's metacharacters escaped), `|`, groups `( )` and `(?: )`, `*`, `+`, `?` and
9
+ `{n}`, `{n,}`, `{n,m}` (each also reluctant), `^` and `\\A`, `\\z`;
10
+ - `.`: Java's misses every line terminator (`\\n`, `\\r`, U+0085, U+2028, U+2029), RE2's only `\\n`, so it is
11
+ written as that class;
12
+ - `$` and `\\Z`: Java's also match before a line terminator ending the text, which RE2 cannot say; written as
13
+ `\\z`, with `ends_anchor` set so that the caller raises for a text that ends with a line terminator;
14
+ - `\\d \\D \\w \\W` (ASCII in both), `\\s \\S` (written as Java's ASCII class, which has \\x0B where RE2's has
15
+ not), `\\p{..}`/`\\P{..}` of a Unicode general category (`L`, `Lu`, `IsL` ...);
16
+ - escapes `\\t \\n \\r \\f \\a \\e`, `\\xhh`, `\\x{h..h}`, `\\uhhhh`, `\\0ooo`, and `\\` before punctuation;
17
+ - classes `[...]` and `[^...]` of characters, ranges and the class escapes above.
18
+
19
+ Refused by name: lookaround, named and atomic groups, inline flags (`(?i)`: Java folds ASCII only, RE2
20
+ Unicode), possessive quantifiers, back-references, `\\b`/`\\B` (Java's word boundary is Unicode-aware, RE2's
21
+ ASCII), `\\G`, `\\R`, `\\X`, `\\h`, `\\v`, `\\Q..\\E`, `\\c`, POSIX, script and block properties, class union
22
+ and intersection. A pattern that is no Java regex is `InvalidJavaPattern` (Neo4j raises for it).
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ from dataclasses import dataclass
28
+ from typing import List, Optional, Tuple
29
+
30
+ from prograph.plan.ir.facts import NotBuilt
31
+ from prograph.rules import home
32
+
33
+
34
+ class InvalidJavaPattern(ValueError):
35
+ """The text is no Java regular expression (java.util.regex raises PatternSyntaxException)."""
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class JavaRegex:
40
+ """A Java pattern as RE2 reads it: `re2`, its capturing groups, and whether it uses `$` or `\\Z` (then a
41
+ text ending with a line terminator must raise, see the module's text)."""
42
+ re2: str
43
+ groups: int
44
+ ends_anchor: bool
45
+ matches_empty: bool = False # it can match the empty string ...
46
+ matches_text: bool = True # ... and a non-empty one: then RE2 and Java find different empty matches
47
+
48
+
49
+ _RE2_META = set("\\.+*?()|[]{}^$")
50
+ _DOT = "[^\\n\\r\\x{85}\\x{2028}\\x{2029}]"
51
+ _SPACE = "\\t\\n\\x0B\\f\\r "
52
+ _CATEGORIES = {"L", "Lu", "Ll", "Lt", "Lm", "Lo", "M", "Mn", "Mc", "Me", "N", "Nd", "Nl", "No", "P", "Pc", "Pd",
53
+ "Ps", "Pe", "Pi", "Pf", "Po", "S", "Sm", "Sc", "Sk", "So", "Z", "Zs", "Zl", "Zp", "C", "Cc", "Cf",
54
+ "Co", "Cs", "Cn"}
55
+ _REFUSED_ESCAPES = {"b": "\\b (Java's word boundary is Unicode-aware, RE2's ASCII)", "B": "\\B (as \\b)",
56
+ "G": "\\G", "R": "\\R", "X": "\\X", "h": "\\h", "H": "\\H", "v": "\\v", "V": "\\V",
57
+ "Q": "\\Q..\\E quoting", "E": "\\E", "c": "a control escape \\c", "k": "a named back-reference"}
58
+
59
+
60
+ @home("java-regex", "A Java regular expression (APOC's) for each engine",
61
+ terms=("Java regex", "java.util.regex", "PatternSyntaxException", "RE2", "apoc.text.replace", "split"))
62
+ def to_re2(pattern: str) -> JavaRegex:
63
+ """`pattern`, a Java regex, as RE2 reads it (see the module's text): `NotBuilt` naming a construct RE2
64
+ reads otherwise, `InvalidJavaPattern` for no Java regex."""
65
+ p = _Parser(pattern)
66
+ out = p.alternation()
67
+ if p.i != len(pattern):
68
+ raise InvalidJavaPattern("an unmatched ')'")
69
+ empty, text = p.last
70
+ return JavaRegex(out, p.groups, p.ends_anchor, empty, text)
71
+
72
+
73
+ def empty_matches_differ(t: JavaRegex) -> bool:
74
+ """Whether RE2 and Java find different matches of the pattern in some text: a pattern that can match
75
+ both the empty string and a non-empty one (`x*`, `a|`, `\\s*`). RE2 skips an empty match right after a
76
+ non-empty one; Java does not (`replace('abc', 'b*', '-')` is -a--c- in Java, -a-c- in RE2)."""
77
+ return t.matches_empty and t.matches_text
78
+
79
+
80
+ class _Parser:
81
+ def __init__(self, s: str) -> None:
82
+ self.s, self.i, self.groups, self.ends_anchor = s, 0, 0, False
83
+ # (whether it can match the empty string, whether it can match a non-empty one) of the last
84
+ # alternation parsed, and of the last atom
85
+ self.last, self.atom_info = (True, False), (False, True)
86
+
87
+ def peek(self, k: int = 0) -> str:
88
+ return self.s[self.i + k] if self.i + k < len(self.s) else ""
89
+
90
+ def alternation(self) -> str:
91
+ out, infos = [self.branch()], [self.last]
92
+ while self.peek() == "|":
93
+ self.i += 1
94
+ out.append(self.branch())
95
+ infos.append(self.last)
96
+ self.last = (any(e for e, _ in infos), any(t for _, t in infos))
97
+ return "|".join(out)
98
+
99
+ def branch(self) -> str:
100
+ out, empty, text = [], True, False
101
+ while self.i < len(self.s) and self.peek() not in "|)":
102
+ self.atom_info = (False, True)
103
+ atom, quantifiable = self.atom()
104
+ a_empty, a_text = self.atom_info
105
+ q = self.quantifier() if quantifiable else self._no_quantifier()
106
+ if q:
107
+ lo, hi = _bounds(q)
108
+ a_empty, a_text = a_empty or lo == 0, a_text and hi != 0
109
+ empty, text = empty and a_empty, text or a_text
110
+ out.append(atom + q)
111
+ self.last = (empty, text)
112
+ return "".join(out)
113
+
114
+ def _no_quantifier(self) -> str:
115
+ if self.peek() and self.peek() in "*+?":
116
+ raise NotBuilt("a quantifier on an anchor")
117
+ return ""
118
+
119
+ def quantifier(self) -> str:
120
+ c = self.peek()
121
+ if c in ("*", "+", "?"):
122
+ q = c
123
+ self.i += 1
124
+ elif c == "{":
125
+ j = self.s.find("}", self.i)
126
+ body = self.s[self.i + 1:j] if j > 0 else ""
127
+ lo, comma, hi = body.partition(",")
128
+ if j < 0 or not lo.isascii() or not lo.isdigit() or (hi and not (hi.isascii() and hi.isdigit())):
129
+ raise InvalidJavaPattern("an illegal repetition '{'")
130
+ if hi and int(hi) < int(lo):
131
+ raise InvalidJavaPattern("a repetition whose upper bound is below its lower")
132
+ if int(lo) > 1000 or (hi and int(hi) > 1000):
133
+ raise NotBuilt("a repeat count past 1000 (RE2's limit)")
134
+ q = "{" + body + "}"
135
+ self.i = j + 1
136
+ else:
137
+ return ""
138
+ if self.peek() == "?":
139
+ q += "?"
140
+ self.i += 1
141
+ elif self.peek() == "+":
142
+ raise NotBuilt("a possessive quantifier")
143
+ if self.peek() and self.peek() in "*+?":
144
+ raise InvalidJavaPattern("a dangling quantifier")
145
+ return q
146
+
147
+ def atom(self) -> Tuple[str, bool]:
148
+ c = self.peek()
149
+ if c == ".":
150
+ self.i += 1
151
+ return _DOT, True
152
+ if c == "^":
153
+ self.i += 1
154
+ self.atom_info = (True, False)
155
+ return "^", False
156
+ if c == "$":
157
+ self.i += 1
158
+ self.ends_anchor = True
159
+ self.atom_info = (True, False)
160
+ return "\\z", False
161
+ if c == "(":
162
+ text = self.group()
163
+ self.atom_info = self.last
164
+ return text, True
165
+ if c == "[":
166
+ return self.cls(), True
167
+ if c == "\\":
168
+ return self.escape(in_class=False)
169
+ if c in "*+?":
170
+ raise InvalidJavaPattern(f"a dangling {c!r}")
171
+ if c == "{":
172
+ raise InvalidJavaPattern("an illegal repetition '{'")
173
+ self.i += 1
174
+ return _lit(c), True
175
+
176
+ def group(self) -> str:
177
+ s, i = self.s, self.i
178
+ if s.startswith("(?", i):
179
+ for prefix, what in (("(?:", None), ("(?=", "a lookahead"), ("(?!", "a negative lookahead"),
180
+ ("(?<=", "a lookbehind"), ("(?<!", "a negative lookbehind"),
181
+ ("(?<", "a named group"), ("(?>", "an atomic group")):
182
+ if s.startswith(prefix, i):
183
+ if what is not None:
184
+ raise NotBuilt(f"{what} (RE2 has none)")
185
+ self.i = i + 3
186
+ inner = self.alternation()
187
+ self._close()
188
+ return "(?:" + inner + ")"
189
+ raise NotBuilt("inline flags such as (?i) (Java folds case in ASCII only, RE2 in Unicode)")
190
+ self.i += 1
191
+ self.groups += 1
192
+ inner = self.alternation()
193
+ self._close()
194
+ return "(" + inner + ")"
195
+
196
+ def _close(self) -> None:
197
+ if self.peek() != ")":
198
+ raise InvalidJavaPattern("an unclosed group")
199
+ self.i += 1
200
+
201
+ def escape(self, in_class: bool) -> Tuple[str, bool]:
202
+ s, i = self.s, self.i
203
+ if i + 1 >= len(s):
204
+ raise InvalidJavaPattern("a '\\' at the end")
205
+ c = s[i + 1]
206
+ self.i = i + 2
207
+ if c in "dDwW":
208
+ return "\\" + c, True # ASCII digits and word characters in both
209
+ if c == "s":
210
+ return (_SPACE if in_class else f"[{_SPACE}]"), True
211
+ if c == "S":
212
+ if in_class:
213
+ raise NotBuilt("\\S inside a class")
214
+ return f"[^{_SPACE}]", True
215
+ if c in "pP":
216
+ return self.property(c), True
217
+ if c in "tnrf":
218
+ return "\\" + c, True
219
+ if c == "a":
220
+ return "\\x07", True
221
+ if c == "e":
222
+ return "\\x1B", True
223
+ if c == "x":
224
+ if self.peek() == "{":
225
+ j = s.find("}", self.i)
226
+ digits = s[self.i + 1:j] if j > 0 else ""
227
+ self.i = j + 1
228
+ else:
229
+ digits = s[self.i:self.i + 2]
230
+ self.i += 2
231
+ return _code(digits, 16), True
232
+ if c == "u":
233
+ digits = s[self.i:self.i + 4]
234
+ self.i += 4
235
+ return _code(digits, 16), True
236
+ if c == "0": # \\0n, \\0nn, \\0mnn: a third digit only where the first is 0 to 3
237
+ j = self.i
238
+ most = 3 if self.peek() and self.peek() in "0123" else 2
239
+ while j < len(s) and j < self.i + most and s[j] in "01234567":
240
+ j += 1
241
+ digits = s[self.i:j]
242
+ self.i = j
243
+ return _code(digits, 8), True
244
+ if c == "N" and self.peek() == "{": # Java 9+'s \\N{NAME}: the character so named
245
+ import unicodedata
246
+ j = s.find("}", self.i)
247
+ name = s[self.i + 1:j] if j > 0 else ""
248
+ self.i = j + 1
249
+ try:
250
+ return _code(f"{ord(unicodedata.lookup(name)):x}", 16), True
251
+ except KeyError:
252
+ raise InvalidJavaPattern(f"no character named {name}") from None
253
+ if c in "AzZ" and not in_class:
254
+ self.atom_info = (True, False)
255
+ self.ends_anchor = self.ends_anchor or c == "Z"
256
+ return ("\\A" if c == "A" else "\\z"), False
257
+ if c.isdigit():
258
+ raise NotBuilt("a back-reference (RE2 has none)")
259
+ if c in _REFUSED_ESCAPES:
260
+ raise NotBuilt(f"the escape {_REFUSED_ESCAPES[c]}")
261
+ if c.isalpha():
262
+ raise InvalidJavaPattern(f"the escape \\{c}")
263
+ return _lit(c, in_class), True
264
+
265
+ def property(self, c: str) -> str:
266
+ s = self.s
267
+ if self.peek() == "{":
268
+ j = s.find("}", self.i)
269
+ if j < 0:
270
+ raise InvalidJavaPattern("an unclosed \\p{")
271
+ name = s[self.i + 1:j]
272
+ self.i = j + 1
273
+ else:
274
+ name = self.peek()
275
+ self.i += 1
276
+ category = name[2:] if name.startswith("Is") and name[2:] in _CATEGORIES else \
277
+ name[3:] if name.startswith("gc=") else name
278
+ if category not in _CATEGORIES:
279
+ raise NotBuilt(f"the property \\{c}{{{name}}} (only Unicode general categories are built)")
280
+ return f"\\{c}{{{category}}}"
281
+
282
+ def cls(self) -> str:
283
+ s = self.s
284
+ self.i += 1
285
+ out = "["
286
+ if self.peek() == "^":
287
+ out += "^"
288
+ self.i += 1
289
+ if self.peek() == "]":
290
+ raise NotBuilt("a ']' first in a class")
291
+ items: List[str] = []
292
+ while True:
293
+ c = self.peek()
294
+ if not c:
295
+ raise InvalidJavaPattern("an unclosed class")
296
+ if c == "]":
297
+ self.i += 1
298
+ if not items:
299
+ raise InvalidJavaPattern("an empty class")
300
+ return out + "".join(items) + "]"
301
+ if c == "[" or s.startswith("&&", self.i):
302
+ raise NotBuilt("a class union or intersection")
303
+ lo, single = self.class_char(first=not items)
304
+ if single and self.peek() == "-" and self.peek(1) not in ("]", ""):
305
+ self.i += 1
306
+ if self.peek() == "[":
307
+ raise NotBuilt("a class union or intersection")
308
+ hi, single_hi = self.class_char(first=False)
309
+ if not single_hi:
310
+ raise InvalidJavaPattern("a range ending in a class")
311
+ items.append(lo + "-" + hi)
312
+ else:
313
+ items.append(lo)
314
+
315
+ def class_char(self, first: bool) -> Tuple[str, bool]:
316
+ c = self.peek()
317
+ if c == "\\":
318
+ before = self.i
319
+ text, _ = self.escape(in_class=True)
320
+ single = self.s[before + 1] not in "dDwWsSpP"
321
+ return text, single
322
+ self.i += 1
323
+ if c == "-" and not first and self.peek() != "]":
324
+ raise NotBuilt("a '-' in a class that is neither a range nor first or last")
325
+ return _lit(c, in_class=True), True
326
+
327
+
328
+ def _bounds(q: str) -> Tuple[int, Optional[int]]:
329
+ """A quantifier's least and most repetitions (None: no most)."""
330
+ if len(q) > 1 and q.endswith("?"): # reluctant
331
+ q = q[:-1]
332
+ if q in ("*", "+", "?"):
333
+ return {"*": (0, None), "+": (1, None), "?": (0, 1)}[q]
334
+ lo, comma, hi = q[1:-1].partition(",")
335
+ return int(lo), (int(hi) if hi else None) if comma else int(lo)
336
+
337
+
338
+ def _lit(c: str, in_class: bool = False) -> str:
339
+ if in_class:
340
+ return "\\" + c if c in "\\]^-[" else _control(c)
341
+ return "\\" + c if c in _RE2_META else _control(c)
342
+
343
+
344
+ def _control(c: str) -> str:
345
+ return f"\\x{{{ord(c):x}}}" if ord(c) < 0x20 or ord(c) == 0x7F else c
346
+
347
+
348
+ def _code(digits: str, base: int) -> str:
349
+ try:
350
+ n = int(digits, base)
351
+ except ValueError:
352
+ raise InvalidJavaPattern(f"the escape digits {digits!r}") from None
353
+ if n > 0x10FFFF:
354
+ raise InvalidJavaPattern("a code point past U+10FFFF")
355
+ return f"\\x{{{n:x}}}"
356
+
357
+
358
+ def replacement_to_re2(replacement: str, groups: int) -> str:
359
+ """A Java replacement string (Matcher.appendReplacement: `$n` a group, the longest number of groups the
360
+ pattern has; `\\x` the character x) as DuckDB's regexp_replace reads one (`\\n` a group, `\\\\` a
361
+ backslash). `InvalidJavaPattern` where Java raises (a `$` naming no group, a trailing `\\`); `NotBuilt` for
362
+ `${name}` and a group past 9."""
363
+ out, i = [], 0
364
+ while i < len(replacement):
365
+ c = replacement[i]
366
+ if c == "\\":
367
+ if i + 1 >= len(replacement):
368
+ raise InvalidJavaPattern("a character to be escaped is missing")
369
+ nxt = replacement[i + 1]
370
+ out.append("\\\\" if nxt == "\\" else nxt)
371
+ i += 2
372
+ elif c == "$":
373
+ if i + 1 >= len(replacement):
374
+ raise InvalidJavaPattern("an illegal group reference: group index is missing")
375
+ if replacement[i + 1] == "{":
376
+ raise NotBuilt("a named group reference ${name}")
377
+ if not replacement[i + 1].isdigit():
378
+ raise InvalidJavaPattern("an illegal group reference")
379
+ n, j = int(replacement[i + 1]), i + 2
380
+ if n > groups:
381
+ raise InvalidJavaPattern(f"no group {n}")
382
+ while j < len(replacement) and replacement[j].isdigit() and n * 10 + int(replacement[j]) <= groups:
383
+ n, j = n * 10 + int(replacement[j]), j + 1
384
+ if n > 9:
385
+ raise NotBuilt("a group past 9 (DuckDB's regexp_replace names \\0 to \\9)")
386
+ out.append(f"\\{n}")
387
+ i = j
388
+ else:
389
+ out.append(c)
390
+ i += 1
391
+ return "".join(out)