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,1357 @@
1
+ """Cypher's temporal values on the one plan (rule cypher-temporal; design 41-cypher-temporal.md,
2
+ decision B, 2026-11-12). This piece: `date`, held as one BIGINT, the days since 1970-01-01, answered as
3
+ ISO 8601 text. A constructor of literal arguments (a map of literals, an ISO string, another literal
4
+ date) is worked out at planning, in the proleptic Gregorian calendar; so is `date()`, the statement's
5
+ clock, one instant per statement. Years 1 to 9999 here; others, and constructors over columns, are not
6
+ built yet. localtime, time, localdatetime, datetime and duration come next.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import datetime as _dt
12
+ import re
13
+ from dataclasses import dataclass
14
+ from typing import TYPE_CHECKING, Any, Dict, List, Mapping, Optional
15
+
16
+ from prograph.plan.ir import expr as E
17
+ from prograph.plan.ir.facts import NotBuilt
18
+ from prograph.rules import home, module_home
19
+
20
+ if TYPE_CHECKING:
21
+ from prograph.plan.ir import lower as L
22
+ from prograph.plan.sql import rel_algebra as R
23
+
24
+ module_home("cypher-temporal", "Cypher's temporal values, in SQL",
25
+ terms=("date", "datetime", "localtime", "duration", "temporal", "ISO 8601", "Cypher temporal"))
26
+
27
+ CYPHER_DATE = "urn:prograph:cypher:date" # the slot datatype of a Cypher date (days since 1970-01-01)
28
+ CYPHER_LOCALTIME = "urn:prograph:cypher:localtime" # a local time: nanoseconds of the day
29
+ CYPHER_LOCALDATETIME = "urn:prograph:cypher:localdatetime" # nanoseconds since 1970-01-01T00:00, DECIMAL(38,0)
30
+ TEMPORAL = frozenset({CYPHER_DATE, CYPHER_LOCALTIME, CYPHER_LOCALDATETIME})
31
+ _DAY = 86_400_000_000_000
32
+ _NS = {"hour": 3_600_000_000_000, "minute": 60_000_000_000, "second": 1_000_000_000}
33
+ _EPOCH = _dt.date(1970, 1, 1)
34
+
35
+
36
+ class TemporalError(ValueError):
37
+ """A temporal value openCypher refuses (a field out of range, a string of no ISO form)."""
38
+
39
+
40
+ @dataclass(frozen=True)
41
+ class CypherDate:
42
+ """A Cypher date written in the query, as its days since 1970-01-01."""
43
+ days: int
44
+
45
+ @property
46
+ def date(self) -> _dt.date:
47
+ return _EPOCH + _dt.timedelta(days=self.days)
48
+
49
+
50
+ def _of(d: _dt.date) -> CypherDate:
51
+ return CypherDate((d - _EPOCH).days)
52
+
53
+
54
+ def date_part(v: Any) -> Optional[CypherDate]:
55
+ """The date of a temporal that has one, as a base for another constructor (openCypher: a date, a local
56
+ date-time's date, a date-time's local date); None for any other value."""
57
+ if isinstance(v, CypherDate):
58
+ return v
59
+ if isinstance(v, CypherLocalDateTime):
60
+ return CypherDate(v.nanos // _DAY)
61
+ if isinstance(v, CypherDateTime):
62
+ return CypherDate((v.instant + v.offset * 1_000_000_000) // _DAY)
63
+ return None
64
+
65
+
66
+ def time_part(v: Any) -> Optional["CypherLocalTime"]:
67
+ """The local time of a temporal that has one: a local time, a time's local time, a local date-time's,
68
+ a date-time's local time; None for any other value."""
69
+ if isinstance(v, CypherLocalTime):
70
+ return v
71
+ if isinstance(v, CypherTime):
72
+ return CypherLocalTime(v.nanos)
73
+ if isinstance(v, CypherLocalDateTime):
74
+ return CypherLocalTime(v.nanos % _DAY)
75
+ if isinstance(v, CypherDateTime):
76
+ return CypherLocalTime((v.instant + v.offset * 1_000_000_000) % _DAY)
77
+ return None
78
+
79
+
80
+ def _int(value: Any, key: str) -> int:
81
+ if isinstance(value, bool) or not isinstance(value, int):
82
+ raise TemporalError(f"date field {key} is not an integer")
83
+ return value
84
+
85
+
86
+ @home("cypher-date-literal", "A Cypher date of literal arguments, at planning",
87
+ terms=("date({...})", "date('...')", "week date", "ordinal date", "quarter date"))
88
+ def date_of(arg: Any) -> CypherDate:
89
+ """openCypher's date(arg) for a literal arg: a map (calendar {year, month, day}, week {year, week,
90
+ dayOfWeek}, ordinal {year, ordinalDay}, quarter {year, quarter, dayOfQuarter}; a `date` key a date
91
+ whose fields fill the ones not given), an ISO 8601 date string, or a date."""
92
+ if date_part(arg) is not None:
93
+ return date_part(arg)
94
+ if isinstance(arg, str):
95
+ return _parse(arg)
96
+ if not isinstance(arg, dict):
97
+ raise NotBuilt("date() of a value that is not a map, a string or a date")
98
+ base: Optional[_dt.date] = None
99
+ if "date" in arg:
100
+ if date_part(arg["date"]) is None:
101
+ raise NotBuilt("date({date: ...}) of a value that is not a date")
102
+ base = date_part(arg["date"]).date
103
+ known = {"year", "month", "day", "week", "dayOfWeek", "ordinalDay", "quarter", "dayOfQuarter", "date"}
104
+ if set(arg) - known:
105
+ raise NotBuilt(f"date() of the fields {sorted(set(arg) - known)}")
106
+ m = {k: _int(v, k) for k, v in arg.items() if k != "date"}
107
+ # openCypher's combinations: one of calendar, week, ordinal or quarter fields; no later field without
108
+ # the one before it (day without month); errors otherwise.
109
+ forms = [bool({"month", "day"} & set(m)), bool({"week"} & set(m)) or ("dayOfWeek" in m),
110
+ "ordinalDay" in m, bool({"quarter", "dayOfQuarter"} & set(m))]
111
+ if sum(forms) > 1 or ("day" in m and "month" not in m and base is None) or \
112
+ ("dayOfQuarter" in m and "quarter" not in m and base is None) or \
113
+ ("dayOfWeek" in m and "week" not in m and base is None):
114
+ raise NotBuilt("date fields of two forms, or a field without the one before it (an error)")
115
+ try:
116
+ if "week" in m or ("dayOfWeek" in m and base is not None):
117
+ iso = base.isocalendar() if base is not None else None
118
+ year = m.get("year", iso[0] if iso else None)
119
+ dow = m.get("dayOfWeek", iso[2] if iso else 1)
120
+ if year is None:
121
+ raise TemporalError("a week date without a year")
122
+ return _of(_dt.date.fromisocalendar(year, m.get("week", iso[1] if iso else 1), dow))
123
+ year = m.get("year", base.year if base is not None else None)
124
+ if year is None:
125
+ raise TemporalError("a date without a year")
126
+ if "ordinalDay" in m:
127
+ if not 1 <= m["ordinalDay"] <= (366 if _dt.date(year, 12, 31).timetuple().tm_yday == 366 else 365):
128
+ raise NotBuilt("an ordinal day out of range (an error)")
129
+ return _of(_dt.date(year, 1, 1) + _dt.timedelta(days=m["ordinalDay"] - 1))
130
+ if "quarter" in m or ("dayOfQuarter" in m and base is not None):
131
+ if "quarter" not in m:
132
+ m["quarter"] = (base.month - 1) // 3 + 1
133
+ first = _dt.date(year, 3 * (m["quarter"] - 1) + 1, 1)
134
+ if base is not None and "dayOfQuarter" not in m:
135
+ bq = _dt.date(base.year, 3 * ((base.month - 1) // 3) + 1, 1)
136
+ doq = (base - bq).days + 1
137
+ else:
138
+ doq = m.get("dayOfQuarter", 1)
139
+ end = _dt.date(year + (m["quarter"] == 4), (3 * m["quarter"]) % 12 + 1, 1)
140
+ if not 1 <= m["quarter"] <= 4 or not 1 <= doq <= (end - first).days:
141
+ raise NotBuilt("a quarter or day of quarter out of range (an error)")
142
+ return _of(first + _dt.timedelta(days=doq - 1))
143
+ month = m.get("month", base.month if base is not None else 1)
144
+ day = m.get("day", base.day if base is not None else 1)
145
+ return _of(_dt.date(year, month, day))
146
+ except (ValueError, OverflowError) as e:
147
+ raise NotBuilt(f"a date outside the range the engines hold (ProGraph reads years 1 to 9999; Spark's DATE "
148
+ f"stops near year -290308, so no engine holds years like -999999999), or an invalid one ({e})")
149
+
150
+
151
+ _FORMS = [
152
+ (re.compile(r"(\d{4})-(\d{2})-(\d{2})"), "calendar"), (re.compile(r"(\d{4})(\d{2})(\d{2})"), "calendar"),
153
+ (re.compile(r"(\d{4})-(\d{2})"), "month"), (re.compile(r"(\d{4})(\d{2})"), "month"),
154
+ (re.compile(r"(\d{4})-W(\d{2})-(\d)"), "week"), (re.compile(r"(\d{4})W(\d{2})(\d)"), "week"),
155
+ (re.compile(r"(\d{4})-W(\d{2})"), "week"), (re.compile(r"(\d{4})W(\d{2})"), "week"),
156
+ (re.compile(r"(\d{4})-Q(\d)-(\d{2})"), "quarter"), (re.compile(r"(\d{4})Q(\d)(\d{2})"), "quarter"),
157
+ (re.compile(r"(\d{4})-(\d{3})"), "ordinal"), (re.compile(r"(\d{4})(\d{3})"), "ordinal"),
158
+ (re.compile(r"(\d{4})"), "year"),
159
+ ]
160
+
161
+
162
+ def _parse(text: str) -> CypherDate:
163
+ """An ISO 8601 date string, in the forms openCypher reads."""
164
+ for pattern, form in _FORMS:
165
+ m = pattern.fullmatch(text)
166
+ if m is None:
167
+ continue
168
+ g = [int(x) for x in m.groups()]
169
+ if form == "calendar":
170
+ return date_of({"year": g[0], "month": g[1], "day": g[2]})
171
+ if form == "month":
172
+ return date_of({"year": g[0], "month": g[1]})
173
+ if form == "week":
174
+ return date_of({"year": g[0], "week": g[1], "dayOfWeek": g[2] if len(g) > 2 else 1})
175
+ if form == "quarter":
176
+ return date_of({"year": g[0], "quarter": g[1], "dayOfQuarter": g[2]})
177
+ if form == "ordinal":
178
+ return date_of({"year": g[0], "ordinalDay": g[1]})
179
+ return date_of({"year": g[0]})
180
+ if re.match(r"[+-]\d{5,}-", text):
181
+ raise NotBuilt(f"date() of {text!r}: a date outside the range the engines hold (ProGraph reads years 1 to "
182
+ f"9999; Spark's DATE stops near year -290308, so no engine holds years like -999999999)")
183
+ raise NotBuilt(f"date() of the string {text!r} (an ISO 8601 form not built, or none)")
184
+
185
+
186
+ _FIELDS = {
187
+ "year": lambda d: d.year, "month": lambda d: d.month, "day": lambda d: d.day,
188
+ "quarter": lambda d: (d.month - 1) // 3 + 1,
189
+ "week": lambda d: d.isocalendar()[1], "weekYear": lambda d: d.isocalendar()[0],
190
+ "dayOfWeek": lambda d: d.isocalendar()[2], "weekDay": lambda d: d.isocalendar()[2],
191
+ "ordinalDay": lambda d: d.timetuple().tm_yday,
192
+ "dayOfQuarter": lambda d: (d - _dt.date(d.year, 3 * ((d.month - 1) // 3) + 1, 1)).days + 1,
193
+ }
194
+
195
+
196
+ def field_of(value: Any, key: str) -> Optional[int]:
197
+ """A literal temporal's field (`d.year`, `t.hour`, ...); None for a key it has none of."""
198
+ if isinstance(value, (CypherTime, CypherDateTime, CypherDuration)):
199
+ return struct_field(value, key)
200
+ if isinstance(value, CypherLocalTime):
201
+ f = _TIME_FIELDS.get(key)
202
+ if f is None:
203
+ raise NotBuilt(f"a local time has no field {key} (an error)")
204
+ return f(value.nanos)
205
+ if isinstance(value, CypherLocalDateTime):
206
+ if key in _TIME_FIELDS:
207
+ return _TIME_FIELDS[key](value.nanos % _DAY)
208
+ f = _FIELDS.get(key)
209
+ if f is None:
210
+ raise NotBuilt(f"a local date-time has no field {key} (an error)")
211
+ return f(CypherDate(value.nanos // _DAY).date)
212
+ f = _FIELDS.get(key)
213
+ if f is None:
214
+ raise NotBuilt(f"a date has no field {key} (an error)")
215
+ return f(value.date)
216
+
217
+
218
+ def text(datatype: str, value: "R.Expr", L) -> "R.Expr":
219
+ """A temporal SQL value as its ISO 8601 text (the answer's form)."""
220
+ if datatype == CYPHER_DATE:
221
+ return L.fn("CYPHER_DATE_TEXT", value)
222
+ if datatype == CYPHER_LOCALTIME:
223
+ return L.fn("CYPHER_LOCALTIME_TEXT", value)
224
+ if datatype in STRUCTS:
225
+ return struct_text(datatype, value, L)
226
+ if datatype == CYPHER_LOCALDATETIME:
227
+ days, nod = L.fn("CYPHER_NS_DAYS", value), L.fn("CYPHER_NS_OF_DAY", value)
228
+ return L.fn("STR_CONCAT", L.fn("STR_CONCAT", L.fn("CYPHER_DATE_TEXT", days), L.text("T")),
229
+ L.fn("CYPHER_LOCALTIME_TEXT", nod))
230
+ raise NotBuilt(f"the text of {datatype}")
231
+
232
+
233
+ def innermost(datatype: Optional[str]) -> Optional[str]:
234
+ """The element type at the bottom of a list type (`cypher_lists.list_type`, nested to any depth)."""
235
+ from prograph.plan.ir.cypher_lists import element_of, nested
236
+ while nested(datatype):
237
+ datatype = element_of(datatype)
238
+ return datatype
239
+
240
+
241
+ def list_text(element: str, value: "R.Expr", L, depth: int = 0) -> "R.Expr":
242
+ """A list of temporals (`element` its element type, itself a list of them to any depth) as the list of
243
+ their ISO 8601 texts, each level transformed (the answer's form: never the values' SQL encoding)."""
244
+ from prograph.plan.ir.cypher_lists import element_of, nested
245
+ from prograph.plan.sql import rel_algebra as R
246
+ var = R.LitExpr(value=f"_tv{depth or ''}", sql=f"_tv{depth or ''}")
247
+ inner = list_text(element_of(element), var, L, depth + 1) if nested(element) else text(element, var, L)
248
+ return L.case(L.is_null(value), L.NULL, L.fn("LIST_TRANSFORM", value, var, inner))
249
+
250
+
251
+ def iso_text(value: Any) -> str:
252
+ """A literal temporal's ISO 8601 text, the form `text` writes in SQL (one text for the answer and for
253
+ toString): a date `YYYY-MM-DD`; a local time HH:MM, then :SS where the seconds or their fraction are
254
+ not zero, then the fraction without its trailing zeros; a local date-time `<date>T<time>`; a time its
255
+ local time and offset (Z for zero); a date-time its local value, offset and [zone]; a duration its
256
+ own text."""
257
+ if isinstance(value, CypherDuration):
258
+ return value.text
259
+ if isinstance(value, CypherDate):
260
+ d = value.date
261
+ return f"{d.year:04d}-{d.month:02d}-{d.day:02d}"
262
+ if isinstance(value, CypherLocalTime):
263
+ n = value.nanos
264
+ out = f"{n // _NS['hour']:02d}:{n // _NS['minute'] % 60:02d}"
265
+ if n % _NS["minute"]:
266
+ out += f":{n // _NS['second'] % 60:02d}"
267
+ if n % _NS["second"]:
268
+ out += "." + f"{n % _NS['second']:09d}".rstrip("0")
269
+ return out
270
+ if isinstance(value, CypherLocalDateTime):
271
+ return iso_text(CypherDate(value.nanos // _DAY)) + "T" + iso_text(CypherLocalTime(value.nanos % _DAY))
272
+ if isinstance(value, CypherTime):
273
+ return iso_text(CypherLocalTime(value.nanos)) + _offset_text(value.offset)
274
+ if isinstance(value, CypherDateTime):
275
+ local = iso_text(CypherLocalDateTime(value.instant + value.offset * 1_000_000_000))
276
+ return local + _offset_text(value.offset) + (f"[{value.zone}]" if value.zone else "")
277
+ raise NotBuilt(f"the text of a {type(value).__name__}")
278
+
279
+
280
+ _SQL_FIELDS = {"year": "CYPHER_DATE_YEAR", "month": "CYPHER_DATE_MONTH", "day": "CYPHER_DATE_DAY"}
281
+ _TIME_SQL = {"hour": (_NS["hour"], 24), "minute": (_NS["minute"], 60), "second": (_NS["second"], 60),
282
+ "millisecond": (1_000_000, 1000), "microsecond": (1000, 1_000_000), "nanosecond": (1, 1_000_000_000)}
283
+
284
+
285
+ def field_cell(key: str, cell: "L.Cell") -> "L.Cell":
286
+ """A temporal column's field: a date's year, month, day by the engine's calendar; a local time's by
287
+ integer division of its nanoseconds."""
288
+ from prograph.plan.ir import lower as L
289
+ from prograph.plan.ir.slot import Bound, value_slot
290
+ from prograph.schema import xsd
291
+ if cell.slot.datatype == CYPHER_DURATION:
292
+ return L.Cell(value_slot(xsd.INTEGER, Bound.MAYBE), _duration_field(key, cell.value, L))
293
+ if cell.slot.datatype in (CYPHER_TIME, CYPHER_DATETIME) and key in _OFFSET_FIELDS:
294
+ return _offset_field(key, cell, L)
295
+ if cell.slot.datatype == CYPHER_DATETIME: # its local date-time's fields
296
+ return field_cell(key, L.Cell(value_slot(CYPHER_LOCALDATETIME, Bound.MAYBE), _local_ns(cell.value, L)))
297
+ if cell.slot.datatype == CYPHER_TIME: # its local time's fields
298
+ if key not in _TIME_SQL:
299
+ raise NotBuilt(f"the field {key} of a time column")
300
+ inner = L.Cell(value_slot(CYPHER_LOCALTIME, Bound.MAYBE), L.fn("CYPHER_FIELD_LONG", cell.value, L.text("n")))
301
+ return field_cell(key, inner)
302
+ if cell.slot.datatype == CYPHER_LOCALDATETIME:
303
+ part = "CYPHER_NS_OF_DAY" if key in _TIME_SQL else "CYPHER_NS_DAYS"
304
+ inner = L.Cell(value_slot(CYPHER_LOCALTIME if key in _TIME_SQL else CYPHER_DATE, Bound.MAYBE),
305
+ L.fn(part, cell.value))
306
+ return field_cell(key, inner)
307
+ if cell.slot.datatype == CYPHER_LOCALTIME:
308
+ if key not in _TIME_SQL:
309
+ raise NotBuilt(f"the field {key} of a local time column")
310
+ unit, modulus = _TIME_SQL[key]
311
+ value = L.fn("INT_MOD", L.fn("INT_DIV", cell.value, L.fn("CAST_LONG", L.integer(unit))), L.integer(modulus))
312
+ return L.Cell(value_slot(xsd.INTEGER, Bound.MAYBE), value)
313
+ if key in _CALENDAR_FIELDS:
314
+ return L.Cell(value_slot(xsd.INTEGER, Bound.MAYBE), _calendar_field(key, cell.value, L))
315
+ if key not in _SQL_FIELDS:
316
+ raise NotBuilt(f"the field {key} of a date column")
317
+ return L.Cell(value_slot(xsd.INTEGER, Bound.MAYBE), L.fn(_SQL_FIELDS[key], cell.value))
318
+
319
+
320
+ def _local_ns(value: "R.Expr", L) -> "R.Expr":
321
+ """A date-time's local date-time (nanoseconds, DECIMAL): its instant plus its offset. Read from the
322
+ struct's own arguments where the value is one written here (a literal, a source column's, under its
323
+ null test), so a field's arithmetic reads the parts once, not the whole struct twice."""
324
+ inner, null = value, None
325
+ if getattr(inner, "name", None) == "CASE" and len(inner.args) == 3 and inner.args[1] is L.NULL:
326
+ null, inner = inner.args[0], inner.args[2]
327
+ fields = {getattr(k, "value", None): v for k, v in zip(inner.args[0::2], inner.args[1::2])} \
328
+ if getattr(inner, "name", None) == "NAMED_STRUCT" else {}
329
+ if not {"i", "o"} <= set(fields):
330
+ null, fields = None, {"i": L.fn("CYPHER_FIELD_DECIMAL", value, L.text("i")),
331
+ "o": L.fn("CYPHER_FIELD_LONG", value, L.text("o"))}
332
+ o_ns = L.fn("*", L.fn("CYPHER_XINT", fields["o"]), L.fn("CYPHER_XINT", L.integer(1_000_000_000)))
333
+ local = L.fn("CYPHER_XINT", L.fn("+", fields["i"], o_ns))
334
+ if null is None or repr(null) == repr(_null_parts(L, fields["i"], fields["o"])):
335
+ return local # null exactly where i or o is: the sum is null there itself
336
+ return L.case(null, L.NULL, local)
337
+
338
+
339
+ _OFFSET_FIELDS = ("offsetSeconds", "offsetMinutes", "offset", "timezone", "epochSeconds", "epochMillis")
340
+
341
+
342
+ def _offset_field(key: str, cell: "L.Cell", L) -> "L.Cell":
343
+ """A time's or date-time's offset fields (`struct_field` for a literal): its offset in seconds, in
344
+ minutes (truncated toward zero, as Java's), as text (Z for zero); its zone's name, else the offset's
345
+ text; a date-time's instant in milliseconds (floored) and seconds (`_epoch_seconds`)."""
346
+ from prograph.plan.ir.slot import Bound, value_slot
347
+ from prograph.schema import xsd
348
+ o = L.fn("CYPHER_FIELD_LONG", cell.value, L.text("o"))
349
+ integer, string = value_slot(xsd.INTEGER, Bound.MAYBE), value_slot(xsd.STRING, Bound.MAYBE)
350
+ if key == "offsetSeconds":
351
+ return L.Cell(integer, o)
352
+ if key == "offsetMinutes":
353
+ return L.Cell(integer, L.fn("INT_QUOTIENT", o, L.fn("CAST_LONG", L.integer(60))))
354
+ text = L.fn("CYPHER_OFFSET_TEXT", o)
355
+ if key == "offset" or key == "timezone" and cell.slot.datatype == CYPHER_TIME:
356
+ return L.Cell(string, text)
357
+ if key == "timezone":
358
+ return L.Cell(string, L.fn("COALESCE", L.fn("CYPHER_FIELD_STRING", cell.value, L.text("z")), text))
359
+ if cell.slot.datatype != CYPHER_DATETIME:
360
+ raise NotBuilt(f"a time has no field {key} (an error)")
361
+ instant = L.fn("CYPHER_FIELD_DECIMAL", cell.value, L.text("i"))
362
+ unit = L.fn("CYPHER_XINT", L.integer(1_000_000))
363
+ below = L.fn("CYPHER_XMOD", L.fn("+", L.fn("CYPHER_XMOD", instant, unit), unit), unit) # floored
364
+ millis = L.fn("CYPHER_XTDIV", L.fn("-", instant, below), unit)
365
+ if key == "epochSeconds": # the floored milliseconds over 1000, truncated toward zero (`_epoch_seconds`)
366
+ millis = L.fn("CYPHER_XTDIV", millis, L.fn("CYPHER_XINT", L.integer(1000)))
367
+ return L.Cell(integer, L.fn("CAST_LONG", millis))
368
+
369
+
370
+ def _duration_field(key: str, value: "R.Expr", L) -> "R.Expr":
371
+ """A duration column's field, as `_DURATION_FIELDS` has it for a literal: quotients and remainders
372
+ truncated toward zero, the time fields of its seconds and nanoseconds as one total."""
373
+ if key not in _DURATION_FIELDS:
374
+ raise NotBuilt(f"a duration has no field {key} (an error)")
375
+ m, d, s, n = (L.fn("CYPHER_XINT", L.fn("CYPHER_FIELD_LONG", value, L.text(k))) for k in "mdsn")
376
+
377
+ def x(k: int) -> "R.Expr":
378
+ return L.fn("CYPHER_XINT", L.integer(k))
379
+
380
+ def div(a, k):
381
+ return L.fn("CYPHER_XTDIV", a, x(k))
382
+
383
+ def rem(a, k):
384
+ return L.fn("CYPHER_XMOD", a, x(k))
385
+ total = L.fn("+", L.fn("*", s, x(1_000_000_000)), n)
386
+ out = {"years": lambda: div(m, 12), "quarters": lambda: div(m, 3), "months": lambda: m,
387
+ "weeks": lambda: div(d, 7), "days": lambda: d, "hours": lambda: div(total, 3_600_000_000_000),
388
+ "minutes": lambda: div(total, 60_000_000_000), "seconds": lambda: s,
389
+ "milliseconds": lambda: L.fn("+", L.fn("*", s, x(1000)), div(n, 1_000_000)),
390
+ "microseconds": lambda: L.fn("+", L.fn("*", s, x(1_000_000)), div(n, 1000)), "nanoseconds": lambda: total,
391
+ "monthsOfYear": lambda: rem(m, 12), "quartersOfYear": lambda: rem(div(m, 3), 4),
392
+ "monthsOfQuarter": lambda: rem(m, 3), "daysOfWeek": lambda: rem(d, 7),
393
+ "minutesOfHour": lambda: rem(div(total, 60_000_000_000), 60), "secondsOfMinute": lambda: rem(s, 60),
394
+ "nanosecondsOfSecond": lambda: n, "millisecondsOfSecond": lambda: div(n, 1_000_000),
395
+ "microsecondsOfSecond": lambda: div(n, 1000)}[key]()
396
+ return L.fn("CAST_LONG", out)
397
+
398
+
399
+ _CALENDAR_FIELDS = ("quarter", "weekDay", "dayOfWeek", "ordinalDay", "dayOfQuarter", "week", "weekYear")
400
+
401
+
402
+ def _calendar_field(key: str, days: "R.Expr", L) -> "R.Expr":
403
+ """A date's (days since 1970-01-01) quarter, ISO day of the week (Monday 1), day of the year, day of the
404
+ quarter, ISO week and week-based year, by integer arithmetic over its year, month and day (every
405
+ engine's): 1970-01-01 a Thursday; a month's first day the days before it in the year (`before`, a leap
406
+ year's February 29 among them); the ISO week the week of the Thursday of the date's week, in that
407
+ Thursday's year (ISO 8601: week 1 holds the year's first Thursday)."""
408
+ from prograph.plan.sql import rel_algebra as R
409
+
410
+ def long(n: int) -> "R.Expr":
411
+ return L.fn("CAST_LONG", L.integer(n))
412
+
413
+ def floor_mod(a: "R.Expr", n: int) -> "R.Expr":
414
+ r = L.fn("INT_REMAINDER", a, long(n))
415
+ return L.case(R.CompareExpr(left=r, op="<", right=long(0)), L.fn("+", r, long(n)), r)
416
+
417
+ def quotient(a: "R.Expr", n: int) -> "R.Expr": # a never negative here
418
+ return L.fn("INT_QUOTIENT", a, long(n))
419
+
420
+ def leap(y: "R.Expr") -> "R.Expr":
421
+ is_leap = L.any_of([L.all_of([L.eq(floor_mod(y, 4), long(0)),
422
+ R.NotExpr(child=L.eq(floor_mod(y, 100), long(0)))]),
423
+ L.eq(floor_mod(y, 400), long(0))])
424
+ return L.case(is_leap, long(1), long(0))
425
+
426
+ def before(m: "R.Expr", y: "R.Expr") -> "R.Expr":
427
+ """The days of the year before month m's first day."""
428
+ return L.case(R.CompareExpr(left=m, op="<=", right=long(2)), L.fn("*", long(31), L.fn("-", m, long(1))),
429
+ L.fn("+", L.fn("+", quotient(L.fn("+", L.fn("*", long(153), L.fn("-", m, long(3))), long(2)), 5),
430
+ long(59)), leap(y)))
431
+
432
+ def ordinal(d: "R.Expr") -> "R.Expr":
433
+ return L.fn("+", before(L.fn("CYPHER_DATE_MONTH", d), L.fn("CYPHER_DATE_YEAR", d)), L.fn("CYPHER_DATE_DAY", d))
434
+
435
+ def quarter(d: "R.Expr") -> "R.Expr":
436
+ return L.fn("+", quotient(L.fn("-", L.fn("CYPHER_DATE_MONTH", d), long(1)), 3), long(1))
437
+
438
+ weekday = L.fn("+", floor_mod(L.fn("+", L.fn("CAST_LONG", days), long(3)), 7), long(1))
439
+ thursday = L.fn("+", L.fn("-", L.fn("CAST_LONG", days), weekday), long(4))
440
+ if key == "quarter":
441
+ return quarter(days)
442
+ if key in ("weekDay", "dayOfWeek"):
443
+ return weekday
444
+ if key == "ordinalDay":
445
+ return ordinal(days)
446
+ if key == "dayOfQuarter":
447
+ first = L.fn("+", L.fn("*", long(3), L.fn("-", quarter(days), long(1))), long(1))
448
+ return L.fn("-", ordinal(days), before(first, L.fn("CYPHER_DATE_YEAR", days)))
449
+ if key == "weekYear":
450
+ return L.fn("CYPHER_DATE_YEAR", thursday)
451
+ return L.fn("+", quotient(L.fn("-", ordinal(thursday), long(1)), 7), long(1)) # week
452
+
453
+
454
+ @dataclass(frozen=True)
455
+ class CypherLocalTime:
456
+ """A Cypher local time written in the query, as its nanoseconds of the day."""
457
+ nanos: int
458
+
459
+
460
+ _TIME_FIELDS = {
461
+ "hour": lambda n: n // _NS["hour"], "minute": lambda n: n // _NS["minute"] % 60,
462
+ "second": lambda n: n // _NS["second"] % 60, "millisecond": lambda n: n // 1_000_000 % 1000,
463
+ "microsecond": lambda n: n // 1000 % 1_000_000, "nanosecond": lambda n: n % 1_000_000_000,
464
+ }
465
+
466
+
467
+ def _time_fields(m: Dict[str, int], base: Optional[int], hour_required: bool = True) -> int:
468
+ """Nanoseconds of the day from {hour, minute, second, millisecond, microsecond, nanosecond}: a field
469
+ not given is the base's (or 0, the hour required without a base); the sub-second fields add up."""
470
+ if base is None and "hour" not in m and hour_required:
471
+ raise NotBuilt("a time without an hour")
472
+ if base is None and (("second" in m and "minute" not in m) or ("minute" in m and "hour" not in m) or
473
+ (any(k in m for k in ("millisecond", "microsecond", "nanosecond")) and "second" not in m)):
474
+ raise NotBuilt("a time field without the one before it (an error)")
475
+ parts = {k: f(base) if base is not None else 0 for k, f in _TIME_FIELDS.items()}
476
+ sub = any(k in m for k in ("millisecond", "microsecond", "nanosecond"))
477
+ for k in ("hour", "minute", "second"):
478
+ if k in m:
479
+ parts[k] = m[k]
480
+ if not (0 <= parts["hour"] < 24 and 0 <= parts["minute"] < 60 and 0 <= parts["second"] < 60):
481
+ raise NotBuilt("a time field out of range (an error in openCypher)")
482
+ if not sub:
483
+ frac = parts["nanosecond"]
484
+ elif base is None:
485
+ frac = m.get("millisecond", 0) * 1_000_000 + m.get("microsecond", 0) * 1000 + m.get("nanosecond", 0)
486
+ else:
487
+ # Over a base each sub-second field sets its own part of the base's fraction (truncate('millisecond',
488
+ # ...) with {nanosecond: 2} keeps the milliseconds); a nanosecond of 1000 or more is the whole fraction.
489
+ base_frac = parts["nanosecond"]
490
+ ms, us, ns = base_frac // 1_000_000, base_frac // 1000 % 1000, base_frac % 1000
491
+ if "nanosecond" in m and m["nanosecond"] >= 1000 and "millisecond" not in m and "microsecond" not in m:
492
+ ms, us, ns = 0, 0, m["nanosecond"]
493
+ else:
494
+ ms, us, ns = m.get("millisecond", ms), m.get("microsecond", us), m.get("nanosecond", ns)
495
+ frac = ms * 1_000_000 + us * 1000 + ns
496
+ if not 0 <= frac < 1_000_000_000:
497
+ raise NotBuilt("a time's sub-second fields out of range (an error in openCypher)")
498
+ return parts["hour"] * _NS["hour"] + parts["minute"] * _NS["minute"] + parts["second"] * _NS["second"] + frac
499
+
500
+
501
+ _TIME_FORM = re.compile(r"(\d{2})(?::?(\d{2})(?::?(\d{2})(?:[.,](\d{1,9}))?)?)?")
502
+
503
+
504
+ @home("cypher-localtime-literal", "A Cypher local time of literal arguments, at planning",
505
+ terms=("localtime({...})", "localtime('...')"))
506
+ def localtime_of(arg: Any) -> CypherLocalTime:
507
+ """openCypher's localtime(arg) for a literal arg: a map of time fields (a `time` key a local time
508
+ whose fields fill the ones not given), an ISO 8601 time string (HH:MM:SS.fffffffff and its shorter and
509
+ basic forms), or a local time."""
510
+ if time_part(arg) is not None:
511
+ return time_part(arg)
512
+ if isinstance(arg, str):
513
+ m = _TIME_FORM.fullmatch(arg)
514
+ if m is None or (":" in arg) != (arg[2:3] == ":"):
515
+ raise NotBuilt(f"localtime() of the string {arg!r} (an ISO 8601 form not built, or none)")
516
+ h, mi, se, fr = m.groups()
517
+ fields = {"hour": int(h), "minute": int(mi or 0), "second": int(se or 0),
518
+ "nanosecond": int((fr or "0").ljust(9, "0"))}
519
+ return CypherLocalTime(_time_fields(fields, None))
520
+ if not isinstance(arg, dict):
521
+ raise NotBuilt("localtime() of a value that is not a map, a string or a local time")
522
+ base = None
523
+ if "time" in arg:
524
+ if time_part(arg["time"]) is None:
525
+ raise NotBuilt("localtime({time: ...}) of a value that is not a local time")
526
+ base = time_part(arg["time"]).nanos
527
+ known = {"hour", "minute", "second", "millisecond", "microsecond", "nanosecond", "time"}
528
+ if set(arg) - known:
529
+ raise NotBuilt(f"localtime() of the fields {sorted(set(arg) - known)}")
530
+ return CypherLocalTime(_time_fields({k: _int(v, k) for k, v in arg.items() if k != "time"}, base))
531
+
532
+
533
+ @dataclass(frozen=True)
534
+ class CypherLocalDateTime:
535
+ """A Cypher local date-time written in the query, as its nanoseconds since 1970-01-01T00:00."""
536
+ nanos: int
537
+
538
+
539
+ _DATE_KEYS = {"year", "month", "day", "week", "dayOfWeek", "ordinalDay", "quarter", "dayOfQuarter"}
540
+ _TIME_KEYS = {"hour", "minute", "second", "millisecond", "microsecond", "nanosecond"}
541
+
542
+
543
+ @home("cypher-localdatetime-literal", "A Cypher local date-time of literal arguments, at planning",
544
+ terms=("localdatetime({...})", "localdatetime('...')"))
545
+ def localdatetime_of(arg: Any) -> CypherLocalDateTime:
546
+ """openCypher's localdatetime(arg) for a literal arg: a map of date fields and time fields (the time
547
+ 00:00 where none is given; `date`, `time` or `datetime` keys whose fields fill the ones not given),
548
+ an ISO 8601 string `<date>T<time>`, or a local date-time."""
549
+ if isinstance(arg, CypherLocalDateTime):
550
+ return arg
551
+ if isinstance(arg, CypherDateTime):
552
+ return CypherLocalDateTime(arg.instant + arg.offset * 1_000_000_000)
553
+ if isinstance(arg, str):
554
+ d, t = (arg.split("T", 1) + [None])[:2]
555
+ days = _parse(d).days
556
+ nod = localtime_of(t).nanos if t else 0
557
+ return CypherLocalDateTime(days * _DAY + nod)
558
+ if not isinstance(arg, dict):
559
+ raise NotBuilt("localdatetime() of a value that is not a map, a string or a local date-time")
560
+ known = _DATE_KEYS | _TIME_KEYS | {"date", "time", "datetime"}
561
+ if set(arg) - known:
562
+ raise NotBuilt(f"localdatetime() of the fields {sorted(set(arg) - known)}")
563
+ base_date, base_time = arg.get("date"), arg.get("time")
564
+ if "datetime" in arg:
565
+ both = arg["datetime"]
566
+ if not isinstance(both, (CypherLocalDateTime, CypherDateTime)):
567
+ raise NotBuilt("localdatetime({datetime: ...}) of a value that is not a date-time")
568
+ base_date = base_date if base_date is not None else both
569
+ base_time = base_time if base_time is not None else both
570
+ base_date = date_part(base_date) if base_date is not None else None
571
+ base_time = time_part(base_time) if base_time is not None else None
572
+ if (arg.get("date") is not None and base_date is None) or (arg.get("time") is not None and base_time is None):
573
+ raise NotBuilt("localdatetime() of a base that is not a date or a local time")
574
+ date_map = {k: v for k, v in arg.items() if k in _DATE_KEYS}
575
+ if base_date is not None:
576
+ date_map["date"] = base_date
577
+ days = date_of(date_map).days
578
+ tm = {k: _int(v, k) for k, v in arg.items() if k in _TIME_KEYS}
579
+ nod = _time_fields(tm, base_time.nanos if base_time is not None else None, hour_required=False)
580
+ return CypherLocalDateTime(days * _DAY + nod)
581
+
582
+
583
+ # -- time and datetime: one struct each, compared and ordered by `struct_keys` -------
584
+
585
+ CYPHER_TIME = "urn:prograph:cypher:time" # {n: nanoseconds of the day (local), o: offset seconds}
586
+ CYPHER_DATETIME = "urn:prograph:cypher:datetime" # {i: UTC nanoseconds since 1970, DECIMAL(38,0), o: offset, z: zone}
587
+ STRUCTS = frozenset({CYPHER_TIME, CYPHER_DATETIME})
588
+
589
+
590
+ @dataclass(frozen=True)
591
+ class CypherTime:
592
+ """A Cypher time (with an offset) written in the query."""
593
+ nanos: int # of the day, local
594
+ offset: int # seconds east of UTC
595
+
596
+
597
+ @dataclass(frozen=True)
598
+ class CypherDateTime:
599
+ """A Cypher date-time written in the query: an instant, its offset and its zone's name (None for an
600
+ offset alone)."""
601
+ instant: int # UTC nanoseconds since 1970-01-01T00:00
602
+ offset: int
603
+ zone: Optional[str] = None
604
+
605
+
606
+ _OFFSET = re.compile(r"([+-])(\d{2}):?(\d{2})?(?::?(\d{2}))?")
607
+
608
+
609
+ def _zone(text: str):
610
+ """(offset seconds, None) for an offset or Z; (None, zone name) for a named zone."""
611
+ if text == "Z":
612
+ return 0, None
613
+ m = _OFFSET.fullmatch(text)
614
+ if m is not None:
615
+ sign, h, mi, se = m.groups()
616
+ seconds = int(h) * 3600 + int(mi or 0) * 60 + int(se or 0)
617
+ if seconds > 18 * 3600:
618
+ raise NotBuilt(f"an offset past 18 hours ({text})")
619
+ return (-seconds if sign == "-" else seconds), None
620
+ try:
621
+ import zoneinfo
622
+ zoneinfo.ZoneInfo(text)
623
+ except Exception:
624
+ raise NotBuilt(f"the time zone {text!r} (no such zone in this tz database)")
625
+ return None, text
626
+
627
+
628
+ def _offset_at(zone: str, local_ns: int) -> int:
629
+ """A named zone's offset at a local date-time (planning's tz database; the earlier offset in an
630
+ overlap)."""
631
+ import zoneinfo
632
+ days, nod = divmod(local_ns, _DAY)
633
+ d = CypherDate(days).date
634
+ t = _dt.datetime(d.year, d.month, d.day, nod // _NS["hour"], nod // _NS["minute"] % 60,
635
+ nod // _NS["second"] % 60, tzinfo=zoneinfo.ZoneInfo(zone))
636
+ offset = int(t.utcoffset().total_seconds())
637
+ if offset % 60:
638
+ # Local mean time, before the zone's standard time: tz databases disagree there (Europe/Stockholm
639
+ # in 1818 is +01:12:12 in one and Berlin's +00:53:28 in another), so no one answer.
640
+ raise NotBuilt(f"a date-time in {zone}'s local mean time, an offset with seconds (before standard time tz "
641
+ f"databases give different offsets, the TCK's +00:53:28 among them); write a fixed offset "
642
+ f"(+01:00) or a date-time after the zone's standard time")
643
+ return offset
644
+
645
+
646
+ def _offset_of_instant(zone: str, instant_ns: int) -> int:
647
+ import zoneinfo
648
+ seconds = instant_ns // 1_000_000_000
649
+ t = _dt.datetime(1970, 1, 1, tzinfo=_dt.timezone.utc) + _dt.timedelta(seconds=seconds)
650
+ return int(t.astimezone(zoneinfo.ZoneInfo(zone)).utcoffset().total_seconds())
651
+
652
+
653
+ @home("cypher-time-literal", "A Cypher time and date-time of literal arguments, at planning",
654
+ terms=("time({...})", "datetime({...})", "datetime('...')", "timezone", "datetime.fromepoch"))
655
+ def time_of(arg: Any) -> CypherTime:
656
+ """openCypher's time(arg): time fields and a `timezone` (an offset or Z; default Z), a `time` key
657
+ filling the fields not given; an ISO 8601 time with an offset; a time."""
658
+ if isinstance(arg, CypherTime):
659
+ return arg
660
+ if isinstance(arg, CypherDateTime):
661
+ return CypherTime((arg.instant + arg.offset * 1_000_000_000) % _DAY, arg.offset)
662
+ if isinstance(arg, (CypherLocalTime, CypherLocalDateTime)):
663
+ return CypherTime(time_part(arg).nanos, 0)
664
+ if isinstance(arg, str):
665
+ m = re.fullmatch(r"([^+\-Z]+)(Z|[+-].+)?", arg)
666
+ if m is None:
667
+ raise NotBuilt(f"time() of the string {arg!r}")
668
+ offset, zone = _zone(m.group(2) or "Z")
669
+ if zone is not None:
670
+ raise NotBuilt("time() with a named zone")
671
+ return CypherTime(localtime_of(m.group(1)).nanos, offset)
672
+ if not isinstance(arg, dict):
673
+ raise NotBuilt("time() of a value that is not a map, a string or a time")
674
+ base = arg.get("time")
675
+ known = _TIME_KEYS | {"time", "timezone"}
676
+ if set(arg) - known:
677
+ raise NotBuilt(f"time() of the fields {sorted(set(arg) - known)}")
678
+ if base is not None and time_part(base) is None:
679
+ raise NotBuilt("time({time: ...}) of a value that is not a time")
680
+ if isinstance(base, CypherDateTime): # its local time, at its offset
681
+ base = CypherTime(time_part(base).nanos, base.offset)
682
+ elif base is not None and not isinstance(base, CypherTime):
683
+ base = time_part(base) # a local time or a local date-time's: no offset, so Z
684
+ offset = base.offset if isinstance(base, CypherTime) else 0
685
+ if "timezone" in arg:
686
+ new, zone = _zone(arg["timezone"])
687
+ if zone is not None:
688
+ raise NotBuilt("time() with a named zone")
689
+ if isinstance(base, CypherTime): # the same instant at the new offset, then the fields set
690
+ base = CypherTime((base.nanos + (new - base.offset) * 1_000_000_000) % _DAY, new)
691
+ offset = new
692
+ tm = {k: _int(v, k) for k, v in arg.items() if k in _TIME_KEYS}
693
+ return CypherTime(_time_fields(tm, base.nanos if base is not None else None), offset)
694
+
695
+
696
+ def datetime_of(arg: Any) -> CypherDateTime:
697
+ """openCypher's datetime(arg): date and time fields and a `timezone` (an offset, Z or a named zone;
698
+ default Z), `date`/`time`/`datetime` keys filling the fields not given; an ISO 8601 date-time with an
699
+ offset and/or a [zone]; a date-time; a local date-time at Z."""
700
+ if isinstance(arg, CypherDateTime):
701
+ return arg
702
+ if isinstance(arg, CypherLocalDateTime): # its fields at the default zone, Z (TCK Temporal3 [11])
703
+ return datetime_of({"datetime": arg})
704
+ if isinstance(arg, str):
705
+ m = re.fullmatch(r"([^T]+)(?:T([^+\-Z\[]+))?(Z|[+-][\d:]+)?(?:\[([^\]]+)\])?", arg)
706
+ if m is None:
707
+ raise NotBuilt(f"datetime() of the string {arg!r}")
708
+ d, t, off, zone = m.groups()
709
+ local = _parse(d).days * _DAY + (localtime_of(t).nanos if t else 0)
710
+ offset = _zone(off)[0] if off else None
711
+ if zone is not None:
712
+ _zone(zone)
713
+ resolved = _in_zone(local, zone)
714
+ if offset is not None and offset != resolved.offset:
715
+ if _offset_of_instant(zone, local - offset * 1_000_000_000) != offset:
716
+ raise NotBuilt(f"a date-time string whose offset {off} is not {zone}'s (an error)")
717
+ return CypherDateTime(local - offset * 1_000_000_000, offset, zone) # the other offset of an overlap
718
+ return resolved
719
+ return CypherDateTime(local - (offset or 0) * 1_000_000_000, offset or 0, zone)
720
+ if not isinstance(arg, dict):
721
+ raise NotBuilt("datetime() of a value that is not a map, a string, a date-time or a local date-time")
722
+ known = _DATE_KEYS | _TIME_KEYS | {"date", "time", "datetime", "timezone"}
723
+ if set(arg) - known:
724
+ raise NotBuilt(f"datetime() of the fields {sorted(set(arg) - known)}")
725
+ local_arg = {k: v for k, v in arg.items() if k != "timezone"}
726
+ zone, offset = None, 0
727
+ if "timezone" in arg:
728
+ # A base with an offset: the same instant in the new zone, then the fields set (openCypher).
729
+ new, new_zone = _zone(arg["timezone"])
730
+ b = local_arg.get("datetime")
731
+ t = local_arg.get("time")
732
+ instant = None
733
+ if isinstance(b, CypherDateTime) and not isinstance(t, (CypherTime, CypherLocalTime)):
734
+ instant = b.instant
735
+ elif isinstance(t, (CypherTime, CypherDateTime)):
736
+ time_zone = t.zone if isinstance(t, CypherDateTime) else None
737
+ if isinstance(t, CypherDateTime):
738
+ t = CypherTime((t.instant + t.offset * 1_000_000_000) % _DAY, t.offset)
739
+ day_source = {k: v for k, v in local_arg.items() if k in _DATE_KEYS or k in ("date", "datetime")}
740
+ if "datetime" in day_source and isinstance(day_source["datetime"], CypherDateTime):
741
+ d = day_source.pop("datetime")
742
+ day_source["date"] = CypherDate((d.instant + d.offset * 1_000_000_000) // _DAY)
743
+ if isinstance(day_source.get("datetime"), CypherLocalDateTime):
744
+ day_source["date"] = CypherDate(day_source.pop("datetime").nanos // _DAY)
745
+ days = date_of({k: v for k, v in day_source.items() if k != "datetime"}).days
746
+ if time_zone is not None:
747
+ # A time of a zoned date-time is read in its zone as the result's date has it (Neo4j: the
748
+ # zone's rules at that date, not at the base's), then moved to the new zone.
749
+ t = CypherTime(t.nanos, _offset_at(time_zone, days * _DAY + t.nanos))
750
+ instant = days * _DAY + t.nanos - t.offset * 1_000_000_000
751
+ for k in list(local_arg):
752
+ if k in _DATE_KEYS or k in ("date", "datetime", "time"):
753
+ del local_arg[k]
754
+ if instant is not None:
755
+ off = _offset_of_instant(new_zone, instant) if new_zone is not None else new
756
+ local_arg["datetime"] = CypherLocalDateTime(instant + off * 1_000_000_000)
757
+ for key in ("datetime", "time"):
758
+ b = local_arg.get(key)
759
+ if isinstance(b, CypherDateTime):
760
+ zone, offset = b.zone, b.offset
761
+ local_arg[key] = CypherLocalDateTime(b.instant + b.offset * 1_000_000_000)
762
+ if isinstance(b, CypherTime):
763
+ offset = b.offset
764
+ local_arg[key] = CypherLocalTime(b.nanos)
765
+ local = localdatetime_of(local_arg).nanos
766
+ if "timezone" in arg:
767
+ offset, zone = _zone(arg["timezone"])
768
+ if zone is not None:
769
+ return _in_zone(local, zone)
770
+ return CypherDateTime(local - offset * 1_000_000_000, offset, zone)
771
+
772
+
773
+ def _in_zone(local: int, zone: str) -> CypherDateTime:
774
+ """A local date-time in a named zone, as Java resolves it: in an overlap the earlier offset; in a gap
775
+ the time moved later by the gap (02:30 in a spring-forward hour is 03:30 at the later offset)."""
776
+ before = _offset_at(zone, local)
777
+ instant = local - before * 1_000_000_000
778
+ return CypherDateTime(instant, _offset_of_instant(zone, instant), zone)
779
+
780
+
781
+ def datetime_from_epoch(seconds: int, nanos: int = 0) -> CypherDateTime:
782
+ return CypherDateTime(seconds * 1_000_000_000 + nanos, 0, None)
783
+
784
+
785
+ def struct_value(value: Any, L) -> "R.Expr":
786
+ """A literal time, date-time or duration as its struct (see the slot datatypes above)."""
787
+ from prograph.plan.sql import rel_algebra as R
788
+ if isinstance(value, CypherDuration):
789
+ return L.fn("NAMED_STRUCT", L.text("m"), L.fn("CAST_LONG", L.integer(value.months)),
790
+ L.text("d"), L.fn("CAST_LONG", L.integer(value.days)),
791
+ L.text("s"), L.fn("CAST_LONG", L.integer(value.seconds)),
792
+ L.text("n"), L.fn("CAST_LONG", L.integer(value.nanos)))
793
+ if isinstance(value, CypherTime):
794
+ return L.fn("NAMED_STRUCT", L.text("n"), L.fn("CAST_LONG", L.integer(value.nanos)),
795
+ L.text("o"), L.fn("CAST_LONG", L.integer(value.offset)))
796
+ return L.fn("NAMED_STRUCT", L.text("i"), R.LitExpr(value=value.instant, sql=f"CAST({value.instant} AS DECIMAL(38,0))"),
797
+ L.text("o"), L.fn("CAST_LONG", L.integer(value.offset)),
798
+ L.text("z"), L.text(value.zone) if value.zone else L.fn("CAST_STRING", L.NULL))
799
+
800
+
801
+ @home("cypher-source-temporal", "A source table's DATE, TIME and TIMESTAMP columns as Cypher temporal values",
802
+ terms=("DATE column", "TIME column", "TIMESTAMP column", "TIMESTAMPTZ", "source temporal", "date property",
803
+ "temporal struct", "struct of parts"))
804
+ def source_type(slot: "Slot", kind: Any = None) -> Optional[str]:
805
+ """The Cypher temporal type a source column's values are (design 41-cypher-temporal, "source
806
+ columns"): a DATE a date, a TIME a local time, a TIME WITH TIME ZONE a time (its local time and
807
+ offset), a TIMESTAMP a local date-time, a TIMESTAMPTZ (an instant) a date-time at offset 0, a struct
808
+ of the integers months, days, seconds and nanoseconds a duration; None for any other column. So a property read from a DATE column
809
+ equals `date('2020-01-01')` and orders with it."""
810
+ from prograph.plan.ir.slot import LOCAL, VALUE, ZONED
811
+ from prograph.schema import xsd
812
+ if getattr(kind, "kind", None) == "time":
813
+ return CYPHER_TIME if getattr(kind, "zoned", False) else CYPHER_LOCALTIME
814
+ structs = {"duration": CYPHER_DURATION, "datetime_struct": CYPHER_DATETIME,
815
+ "localdatetime_struct": CYPHER_LOCALDATETIME, "time_struct": CYPHER_TIME,
816
+ "localtime_struct": CYPHER_LOCALTIME}
817
+ if getattr(kind, "kind", None) in structs:
818
+ return structs[kind.kind]
819
+ if slot.kinds != {VALUE} or len(slot.datatypes) != 1:
820
+ return None
821
+ if slot.datatype == xsd.DATE:
822
+ return CYPHER_DATE
823
+ if slot.datatype == xsd.DATETIME:
824
+ if slot.zone == LOCAL:
825
+ return CYPHER_LOCALDATETIME
826
+ if slot.zone == ZONED:
827
+ return CYPHER_DATETIME
828
+ raise NotBuilt("a date-time column whose rows are zoned in some maps and local in others")
829
+ return None
830
+
831
+
832
+ _STRUCT_PARTS = {"datetime_struct": ("epoch_seconds", "nanoseconds", "offset_seconds"),
833
+ "localdatetime_struct": ("local_seconds", "nanoseconds"),
834
+ "time_struct": ("nanoseconds_of_day", "offset_seconds"),
835
+ "localtime_struct": ("nanoseconds_of_day",)}
836
+
837
+
838
+ def _struct_cell(kind: str, target: str, cell: "L.Cell", L) -> "L.Cell":
839
+ """A struct column of a temporal's integer parts (`types.temporal_struct`) as the Cypher type `target`
840
+ holds it: null where the struct or a part is (a date-time's zone may be null: an offset alone); a
841
+ date-time's or local date-time's seconds and nanoseconds as one exact total (nanoseconds outside
842
+ [0, 10^9) carried). The parts are taken as the source holds them: a time of day within the day, an
843
+ offset within -18:00 to +18:00 and a date within years 1 to 9999 are the source's to keep."""
844
+ from prograph.plan.ir.slot import value_slot
845
+ v = cell.value
846
+ part = {k: L.fn("CYPHER_FIELD_LONG", v, L.text(k)) for k in _STRUCT_PARTS[kind]}
847
+
848
+ def total(seconds):
849
+ ns = L.fn("*", L.fn("CYPHER_XINT", seconds), L.fn("CYPHER_XINT", L.integer(1_000_000_000)))
850
+ return L.fn("CYPHER_XINT", L.fn("+", ns, L.fn("CYPHER_XINT", part["nanoseconds"])))
851
+ if kind == "localdatetime_struct": # null where a part is, as its arithmetic is
852
+ out = total(part["local_seconds"])
853
+ elif kind == "localtime_struct":
854
+ out = part["nanoseconds_of_day"]
855
+ elif kind == "time_struct":
856
+ n, o = part["nanoseconds_of_day"], part["offset_seconds"]
857
+ out = L.case(_null_parts(L, n, o), L.NULL, L.fn("NAMED_STRUCT", L.text("n"), n, L.text("o"), o))
858
+ else:
859
+ i, o = total(part["epoch_seconds"]), part["offset_seconds"]
860
+ out = L.case(_null_parts(L, i, o), L.NULL, L.fn("NAMED_STRUCT", L.text("i"), i, L.text("o"), o, L.text("z"),
861
+ L.fn("CYPHER_FIELD_STRING", v, L.text("zone"))))
862
+ return L.Cell(value_slot(target, cell.slot.null), out)
863
+
864
+
865
+ def _null_parts(L, a: "R.Expr", b: "R.Expr") -> "R.Expr":
866
+ """Whether either of a struct's two parts is null: the struct is then null (`_local_ns` reads this
867
+ test as the parts' own arithmetic, null where either is)."""
868
+ return L.any_of([L.is_null(a), L.is_null(b)])
869
+
870
+
871
+ def source_cell(target: str, cell: "L.Cell", L, struct: Optional[str] = None) -> "L.Cell":
872
+ """A source temporal column's value as the Cypher type `target` holds it (`source_type`); `struct` the
873
+ kind of struct of a temporal's parts the column is (`types.temporal_struct`), None for an engine type."""
874
+ from prograph.plan.ir.slot import value_slot
875
+ if struct in _STRUCT_PARTS:
876
+ return _struct_cell(struct, target, cell, L)
877
+ v = cell.value
878
+ if target == CYPHER_DATE:
879
+ out = L.fn("CYPHER_SOURCE_DAYS", v)
880
+ elif target == CYPHER_LOCALTIME:
881
+ out = L.fn("CYPHER_SOURCE_TIME_NS", v)
882
+ elif target == CYPHER_LOCALDATETIME:
883
+ out = L.fn("CYPHER_SOURCE_LOCAL_NS", v)
884
+ elif target == CYPHER_TIME: # its local time of day and its offset
885
+ out = L.case(L.is_null(v), L.NULL, L.fn("NAMED_STRUCT", L.text("n"), L.fn("CYPHER_SOURCE_TIME_NS", v),
886
+ L.text("o"), L.fn("CYPHER_SOURCE_OFFSET", v)))
887
+ elif target == CYPHER_DURATION: # its parts, the nanoseconds carried into the seconds ([0, 10^9) left)
888
+ months, days, seconds, nanos = (L.fn("CYPHER_FIELD_LONG", v, L.text(k))
889
+ for k in ("months", "days", "seconds", "nanoseconds"))
890
+ out = L.case(L.is_null(v), L.NULL, L.fn(
891
+ "NAMED_STRUCT", L.text("m"), months, L.text("d"), days,
892
+ L.text("s"), L.fn("+", seconds, L.fn("CYPHER_FLOOR_DIV", nanos, L.integer(1_000_000_000))),
893
+ L.text("n"), L.fn("CYPHER_FLOOR_MOD", nanos, L.integer(1_000_000_000))))
894
+ else: # an instant: its nanoseconds at offset 0, no zone name
895
+ out = L.case(L.is_null(v), L.NULL, L.fn("NAMED_STRUCT", L.text("i"), L.fn("CYPHER_SOURCE_INSTANT_NS", v),
896
+ L.text("o"), L.fn("CAST_LONG", L.integer(0)),
897
+ L.text("z"), L.fn("CAST_STRING", L.NULL)))
898
+ return L.Cell(value_slot(target, cell.slot.null), out)
899
+
900
+
901
+ def stored_kind(datatype: Optional[str]) -> Optional[Any]:
902
+ """The source type (`prograph.schema.types`) the owned store holds a Cypher temporal of slot datatype
903
+ `datatype` as, read back by `source_cell` as a mapped column of that type is: a date a DATE (its ISO
904
+ 8601 text), a duration a struct of its four parts, any other temporal the struct of its integer parts
905
+ `types.temporal_struct` names; None for a value of no temporal type."""
906
+ from prograph.schema import types as T
907
+ return {CYPHER_DATE: T.DATE, CYPHER_LOCALTIME: T.LOCALTIME_STRUCT, CYPHER_TIME: T.TIME_STRUCT,
908
+ CYPHER_LOCALDATETIME: T.LOCALDATETIME_STRUCT, CYPHER_DATETIME: T.DATETIME_STRUCT,
909
+ CYPHER_DURATION: T.DURATION}.get(datatype)
910
+
911
+
912
+ def stored_text(datatype: str, value: "R.Expr", L) -> "R.Expr":
913
+ """A Cypher temporal's SQL value as the text the owned store holds it in, the source value `stored_kind`
914
+ names (`source_cell`'s inverse): a date its ISO 8601 text; any other a JSON object of its integer parts
915
+ (`types.temporal_struct_fields`), one form on every engine: the fields in that order, no spaces, each
916
+ integer in decimal digits, a date-time's zone a JSON string or `null` for an offset alone (built by
917
+ concatenation, never by an engine's JSON writer, whose key order, spacing and nulls differ). A date-time's
918
+ or local date-time's nanoseconds are split exactly into whole seconds (floored) and the nanoseconds of
919
+ the second. A zone name is an IANA name or an offset, which holds no character JSON escapes."""
920
+ from prograph.schema import types as T
921
+ if datatype == CYPHER_DATE:
922
+ return text(CYPHER_DATE, value, L)
923
+ billion = L.integer(1_000_000_000)
924
+
925
+ def split(ns): # exact whole seconds (floored) and the nanoseconds of the second
926
+ nanos = L.fn("CYPHER_FLOOR_MOD", L.fn("CYPHER_XINT", ns), billion)
927
+ seconds = L.fn("CAST_LONG", L.fn("CYPHER_XTDIV", L.fn("-", L.fn("CYPHER_XINT", ns), nanos), billion))
928
+ return [seconds, nanos]
929
+
930
+ def long(k):
931
+ return L.fn("CYPHER_FIELD_LONG", value, L.text(k))
932
+ parts = {CYPHER_LOCALTIME: lambda: [value],
933
+ CYPHER_TIME: lambda: [long("n"), long("o")],
934
+ CYPHER_LOCALDATETIME: lambda: split(value),
935
+ CYPHER_DATETIME: lambda: split(L.fn("CYPHER_FIELD_DECIMAL", value, L.text("i"))) + [long("o")],
936
+ CYPHER_DURATION: lambda: [long(k) for k in "mdsn"]}.get(datatype)
937
+ if parts is None:
938
+ raise NotBuilt(f"the stored form of {datatype}")
939
+ fields = T.temporal_struct_fields(stored_kind(datatype))
940
+ pieces = []
941
+ for i, (name, part) in enumerate(zip(fields, parts())):
942
+ pieces += [L.text(("{" if i == 0 else ",") + f'"{name}":'), L.fn("CAST_STRING", part)]
943
+ if datatype == CYPHER_DATETIME:
944
+ zone = L.fn("CYPHER_FIELD_STRING", value, L.text("z"))
945
+ pieces += [L.text(',"zone":'), L.fn("COALESCE", L.concat([L.text('"'), zone, L.text('"')]), L.text("null"))]
946
+ return L.case(L.is_null(value), L.NULL, L.concat(pieces + [L.text("}")]))
947
+
948
+
949
+ def duration_equal(op: str, a: "R.Expr", b: "R.Expr", L) -> "R.Expr":
950
+ """= and <> of two durations: by their four parts; <, > not defined (null)."""
951
+ from prograph.plan.sql import rel_algebra as R
952
+ if op not in ("=", "<>"):
953
+ return L.NULL_BOOLEAN
954
+ eq = L.all_of([R.CompareExpr(left=L.fn("CYPHER_FIELD_LONG", a, L.text(k)), op="=",
955
+ right=L.fn("CYPHER_FIELD_LONG", b, L.text(k))) for k in "mdsn"])
956
+ return eq if op == "=" else R.NotExpr(child=eq)
957
+
958
+
959
+ def struct_keys(datatype: str, value: "R.Expr", L) -> List["R.Expr"]:
960
+ """The values a time or date-time is compared, ordered and told apart by, most significant first
961
+ (the temporal CIP's equality of the value with its offset and zone; Neo4j 5's order as the field
962
+ reference): a date-time its instant, then its offset (at one instant the later local time), then its
963
+ zone's name ('' for an offset alone, before every name; by code point where compared); a time its
964
+ instant of the day at UTC (local nanoseconds minus the offset, not wrapped at midnight: 00:30+01:00 before 23:00Z), then its offset. Two values are equal only where every key is: one instant
965
+ at two offsets or zones is two values (`=` false, DISTINCT and grouping keep both, ordered by these
966
+ keys). A duration has none: durations are not ordered."""
967
+ if datatype == CYPHER_DURATION:
968
+ raise NotBuilt("ORDER BY a duration (durations are not ordered)")
969
+ o = L.fn("CYPHER_FIELD_LONG", value, L.text("o"))
970
+ if datatype == CYPHER_DATETIME:
971
+ return [L.fn("CYPHER_FIELD_DECIMAL", value, L.text("i")), o,
972
+ L.fn("COALESCE", L.fn("CYPHER_FIELD_STRING", value, L.text("z")), L.text(""))]
973
+ n = L.fn("CYPHER_FIELD_LONG", value, L.text("n"))
974
+ return [L.fn("-", n, L.fn("*", o, L.fn("CAST_LONG", L.integer(1_000_000_000)))), o]
975
+
976
+
977
+ def key_parts(datatypes) -> int:
978
+ """How many `struct_keys` a column of these Cypher types is ordered by (0 for none of the structs)."""
979
+ return 3 if CYPHER_DATETIME in datatypes else 2 if CYPHER_TIME in datatypes else 0
980
+
981
+
982
+ def struct_compare(op: str, datatype: str, a: "R.Expr", b: "R.Expr", L) -> "R.Expr":
983
+ """`a op b` (SQL's =, <>, <, <=, >, >=) of two times or two date-times, by `struct_keys`, lexicographic;
984
+ the caller makes it null where either is null."""
985
+ from prograph.plan.sql import rel_algebra as R
986
+ pairs = list(zip(struct_keys(datatype, a, L), struct_keys(datatype, b, L)))
987
+ if datatype == CYPHER_DATETIME:
988
+ pairs[-1] = (L.codepoint(pairs[-1][0]), L.codepoint(pairs[-1][1]))
989
+ if op in ("=", "<>"):
990
+ eq = L.all_of([R.CompareExpr(left=x, op="=", right=y) for x, y in pairs])
991
+ return eq if op == "=" else R.NotExpr(child=eq)
992
+ strict = op[0]
993
+ out = R.CompareExpr(left=pairs[-1][0], op=op, right=pairs[-1][1])
994
+ for x, y in reversed(pairs[:-1]):
995
+ out = L.any_of([R.CompareExpr(left=x, op=strict, right=y),
996
+ L.all_of([R.CompareExpr(left=x, op="=", right=y), out])])
997
+ return out
998
+
999
+
1000
+ def struct_text(datatype: str, value: "R.Expr", L) -> "R.Expr":
1001
+ """A time or date-time as ISO 8601 text: its local value, its offset (Z for zero), its [zone]."""
1002
+ if datatype == CYPHER_DURATION:
1003
+ return L.fn("CYPHER_DURATION_TEXT", *(L.fn("CYPHER_FIELD_LONG", value, L.text(k)) for k in "mdsn"))
1004
+ o = L.fn("CYPHER_FIELD_LONG", value, L.text("o"))
1005
+ if datatype == CYPHER_TIME:
1006
+ local = L.fn("CYPHER_LOCALTIME_TEXT", L.fn("CYPHER_FIELD_LONG", value, L.text("n")))
1007
+ return L.fn("STR_CONCAT", local, L.fn("CYPHER_OFFSET_TEXT", o))
1008
+ instant = L.fn("CYPHER_FIELD_DECIMAL", value, L.text("i"))
1009
+ local_ns = L.fn("+", instant, L.fn("*", o, L.fn("CAST_LONG", L.integer(1_000_000_000))))
1010
+ local = text(CYPHER_LOCALDATETIME, local_ns, L)
1011
+ zone = L.fn("CYPHER_FIELD_STRING", value, L.text("z"))
1012
+ tail = L.fn("COALESCE", L.fn("STR_CONCAT", L.fn("STR_CONCAT", L.text("["), zone), L.text("]")), L.text(""))
1013
+ return L.fn("STR_CONCAT", L.fn("STR_CONCAT", local, L.fn("CYPHER_OFFSET_TEXT", o)), tail)
1014
+
1015
+
1016
+ def struct_field(value: Any, key: str) -> Any:
1017
+ """A literal time's, date-time's or duration's field."""
1018
+ if isinstance(value, CypherDuration):
1019
+ f = _DURATION_FIELDS.get(key)
1020
+ if f is None:
1021
+ raise NotBuilt(f"a duration has no field {key} (an error)")
1022
+ return f(value)
1023
+ text_offset = _offset_text(value.offset)
1024
+ minutes = int(value.offset / 60) # toward zero, as Java's
1025
+ if isinstance(value, CypherTime):
1026
+ if key in _TIME_FIELDS:
1027
+ return _TIME_FIELDS[key](value.nanos)
1028
+ extra = {"offsetSeconds": value.offset, "offsetMinutes": minutes, "offset": text_offset,
1029
+ "timezone": text_offset}
1030
+ if key not in extra:
1031
+ raise NotBuilt(f"a time has no field {key} (an error)")
1032
+ return extra[key]
1033
+ local = CypherLocalDateTime(value.instant + value.offset * 1_000_000_000)
1034
+ extra = {"offsetSeconds": value.offset, "offsetMinutes": minutes, "offset": text_offset,
1035
+ "timezone": value.zone or text_offset,
1036
+ "epochSeconds": _epoch_seconds(value.instant), "epochMillis": value.instant // 1_000_000}
1037
+ if key in extra:
1038
+ return extra[key]
1039
+ return field_of(local, key)
1040
+
1041
+
1042
+ def _epoch_seconds(instant: int) -> int:
1043
+ """A date-time's epochSeconds as Neo4j 5 gives it (openCypher leaves it unsaid): its milliseconds since
1044
+ the epoch, floored, then divided by 1000 truncated toward zero, so an instant half a second before the
1045
+ epoch is 0 and 1969-12-31T23:59:58.999Z is -1."""
1046
+ millis = instant // 1_000_000
1047
+ return -(-millis // 1000) if millis < 0 else millis // 1000
1048
+
1049
+
1050
+ def _offset_text(seconds: int) -> str:
1051
+ if seconds == 0:
1052
+ return "Z"
1053
+ sign, a = ("-" if seconds < 0 else "+"), abs(seconds)
1054
+ h, m, s = a // 3600, a // 60 % 60, a % 60
1055
+ return f"{sign}{h:02d}:{m:02d}" + (f":{s:02d}" if s else "")
1056
+
1057
+
1058
+ TEMPORAL = TEMPORAL | STRUCTS
1059
+
1060
+
1061
+ # -- duration: one struct, equal by its four parts, not ordered --------------------------------------------
1062
+
1063
+ CYPHER_DURATION = "urn:prograph:cypher:duration" # {m: months, d: days, s: seconds, n: nanoseconds}
1064
+ STRUCTS = STRUCTS | {CYPHER_DURATION}
1065
+ TEMPORAL = TEMPORAL | {CYPHER_DURATION}
1066
+ _MONTH_SECONDS = 2_629_746 # an average Gregorian month (openCypher, as Neo4j)
1067
+
1068
+
1069
+ @dataclass(frozen=True)
1070
+ class CypherDuration:
1071
+ """A Cypher duration written in the query: months, days, seconds and nanoseconds kept apart (P1M is
1072
+ no 30 days), the nanoseconds in [0, 10^9)."""
1073
+ months: int
1074
+ days: int
1075
+ seconds: int
1076
+ nanos: int
1077
+
1078
+ @property
1079
+ def text(self) -> str:
1080
+ """ISO 8601, as openCypher prints a duration (each part with its sign; PT0S for none)."""
1081
+ out = "P"
1082
+ y, m = int(self.months / 12), self.months - int(self.months / 12) * 12
1083
+ out += f"{y}Y" if y else ""
1084
+ out += f"{m}M" if m else ""
1085
+ out += f"{self.days}D" if self.days else ""
1086
+ total = self.seconds * 1_000_000_000 + self.nanos
1087
+ if total:
1088
+ sign = "-" if total < 0 else ""
1089
+ a = abs(total)
1090
+ h, rest = divmod(a, 3_600_000_000_000)
1091
+ mi, rest = divmod(rest, 60_000_000_000)
1092
+ s, ns = divmod(rest, 1_000_000_000)
1093
+ out += "T" + (f"{sign}{h}H" if h else "") + (f"{sign}{mi}M" if mi else "")
1094
+ if s or ns:
1095
+ frac = f".{ns:09d}".rstrip("0") if ns else ""
1096
+ out += f"{sign}{s}{frac}S"
1097
+ return out if out != "P" else "PT0S"
1098
+
1099
+
1100
+ def _duration(months: Any = 0, days: Any = 0, seconds: Any = 0, nanos: Any = 0) -> CypherDuration:
1101
+ """Normalised as openCypher does: a fraction of a month to days and seconds (an average month), of a
1102
+ day to seconds, of a second to nanoseconds."""
1103
+ from fractions import Fraction as F
1104
+ months, days, seconds, nanos = F(months), F(days), F(seconds), F(nanos)
1105
+ whole_months = int(months)
1106
+ # A fraction of a month: an average month's seconds, its whole days counted as days.
1107
+ month_seconds = (months - whole_months) * _MONTH_SECONDS
1108
+ month_days = int(month_seconds / 86400)
1109
+ days += month_days
1110
+ seconds += month_seconds - month_days * 86400
1111
+ whole_days = int(days)
1112
+ seconds += (days - whole_days) * 86400
1113
+ total = seconds * 1_000_000_000 + nanos
1114
+ total_ns = int(round(total)) if total.denominator != 1 else int(total)
1115
+ s, n = divmod(total_ns, 1_000_000_000)
1116
+ # a whole number of days in the seconds stays seconds (openCypher keeps days and seconds apart)
1117
+ return CypherDuration(whole_months, whole_days, s, n)
1118
+
1119
+
1120
+ _UNITS = {"years": ("m", 12), "quarters": ("m", 3), "months": ("m", 1), "weeks": ("d", 7), "days": ("d", 1),
1121
+ "hours": ("s", 3600), "minutes": ("s", 60), "seconds": ("s", 1), "milliseconds": ("n", 1_000_000),
1122
+ "microseconds": ("n", 1000), "nanoseconds": ("n", 1)}
1123
+
1124
+
1125
+ @home("cypher-duration-literal", "A Cypher duration of literal arguments, at planning",
1126
+ terms=("duration({...})", "duration('P...')", "ISO 8601 duration"))
1127
+ def duration_of(arg: Any) -> CypherDuration:
1128
+ """openCypher's duration(arg) for a literal arg: a map of units (years, quarters, months, weeks, days,
1129
+ hours, minutes, seconds, milli-, micro-, nanoseconds; fractions allowed and carried down), or an ISO
1130
+ 8601 duration string (PnYnMnWnDTnHnMnS, fractions allowed; or the alternative PYYYY-MM-DDThh:mm:ss)."""
1131
+ from fractions import Fraction as F
1132
+ if isinstance(arg, CypherDuration):
1133
+ return arg
1134
+ if isinstance(arg, str) and re.fullmatch(r"P\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[.,]\d{1,9})?", arg):
1135
+ # ISO 8601's alternative form, PYYYY-MM-DDThh:mm:ss[.f] (TCK Temporal2 [7]): each field its unit.
1136
+ y, mo, d, h, mi, sec = re.split(r"[-T:]", arg[1:])
1137
+ if int(mo) > 12 or int(d) > 31 or int(h) > 23 or int(mi) > 59 or int(sec[:2]) > 59:
1138
+ # ISO 8601 bounds the alternative form's fields by their carry-over points; engines differ past them.
1139
+ raise NotBuilt(f"duration() of the string {arg!r} (a field past its carry-over point)")
1140
+ arg = {"years": int(y), "months": int(mo), "days": int(d), "hours": int(h), "minutes": int(mi),
1141
+ "seconds": F(sec.replace(",", "."))}
1142
+ if isinstance(arg, str):
1143
+ m = re.fullmatch(r"(-)?P(?:([-\d.]+)Y)?(?:([-\d.]+)M)?(?:([-\d.]+)W)?(?:([-\d.]+)D)?"
1144
+ r"(?:T(?:([-\d.]+)H)?(?:([-\d.]+)M)?(?:([-\d.]+)S)?)?", arg)
1145
+ if m is None or arg in ("P", "PT"):
1146
+ raise NotBuilt(f"duration() of the string {arg!r} (a form not built, or none)")
1147
+ neg, *parts = m.groups()
1148
+ keys = ("years", "months", "weeks", "days", "hours", "minutes", "seconds")
1149
+ arg = {k: (-1 if neg else 1) * F(v) for k, v in zip(keys, parts) if v is not None}
1150
+ if not isinstance(arg, dict):
1151
+ raise NotBuilt("duration() of a value that is not a map or a string")
1152
+ if set(arg) - set(_UNITS):
1153
+ raise NotBuilt(f"duration() of the fields {sorted(set(arg) - set(_UNITS))}")
1154
+ acc = {"m": F(0), "d": F(0), "s": F(0), "n": F(0)}
1155
+ for k, v in arg.items():
1156
+ if isinstance(v, bool) or not isinstance(v, (int, float, F)):
1157
+ raise NotBuilt(f"duration field {k} that is not a number")
1158
+ part, factor = _UNITS[k]
1159
+ acc[part] += F(v) * factor
1160
+ return _duration(acc["m"], acc["d"], acc["s"], acc["n"])
1161
+
1162
+
1163
+ _DURATION_FIELDS = {
1164
+ "years": lambda d: int(d.months / 12), "quarters": lambda d: int(d.months / 3), "months": lambda d: d.months,
1165
+ "weeks": lambda d: int(d.days / 7), "days": lambda d: d.days,
1166
+ "hours": lambda d: int((d.seconds * 1_000_000_000 + d.nanos) / 3_600_000_000_000),
1167
+ "minutes": lambda d: int((d.seconds * 1_000_000_000 + d.nanos) / 60_000_000_000),
1168
+ "seconds": lambda d: d.seconds, "milliseconds": lambda d: d.seconds * 1000 + d.nanos // 1_000_000,
1169
+ "microseconds": lambda d: d.seconds * 1_000_000 + d.nanos // 1000,
1170
+ "nanoseconds": lambda d: d.seconds * 1_000_000_000 + d.nanos,
1171
+ "monthsOfYear": lambda d: d.months - int(d.months / 12) * 12,
1172
+ "quartersOfYear": lambda d: int(d.months / 3) - int(d.months / 12) * 4,
1173
+ "monthsOfQuarter": lambda d: d.months - int(d.months / 3) * 3,
1174
+ "daysOfWeek": lambda d: d.days - int(d.days / 7) * 7,
1175
+ "minutesOfHour": lambda d: int((d.seconds * 1_000_000_000 + d.nanos) / 60_000_000_000) % 60 if d.seconds >= 0
1176
+ else -(int(-(d.seconds * 1_000_000_000 + d.nanos) / 60_000_000_000) % 60),
1177
+ "secondsOfMinute": lambda d: d.seconds % 60 if d.seconds >= 0 else -((-d.seconds) % 60),
1178
+ "nanosecondsOfSecond": lambda d: d.nanos, "millisecondsOfSecond": lambda d: d.nanos // 1_000_000,
1179
+ "microsecondsOfSecond": lambda d: d.nanos // 1000,
1180
+ }
1181
+
1182
+
1183
+
1184
+ # -- truncate ---------------------------------------------------------------------------------------------
1185
+
1186
+ _DATE_UNITS = ("millennium", "century", "decade", "year", "weekYear", "quarter", "month", "week", "day")
1187
+ _TIME_UNITS = {"hour": _NS["hour"], "minute": _NS["minute"], "second": _NS["second"], "millisecond": 1_000_000,
1188
+ "microsecond": 1000}
1189
+
1190
+
1191
+ def _truncate_days(unit: str, days: int) -> int:
1192
+ d = CypherDate(days).date
1193
+ if unit in ("millennium", "century", "decade"):
1194
+ size = {"millennium": 1000, "century": 100, "decade": 10}[unit]
1195
+ if d.year // size * size < 1:
1196
+ raise NotBuilt(f"truncate to the {unit} of a year before {size} (year 0, outside 1 to 9999)")
1197
+ return _of(_dt.date(d.year // size * size, 1, 1)).days
1198
+ if unit == "year":
1199
+ return _of(_dt.date(d.year, 1, 1)).days
1200
+ if unit == "weekYear":
1201
+ return _of(_dt.date.fromisocalendar(d.isocalendar()[0], 1, 1)).days
1202
+ if unit == "quarter":
1203
+ return _of(_dt.date(d.year, 3 * ((d.month - 1) // 3) + 1, 1)).days
1204
+ if unit == "month":
1205
+ return _of(_dt.date(d.year, d.month, 1)).days
1206
+ if unit == "week":
1207
+ return days - (d.isocalendar()[2] - 1)
1208
+ return days # day
1209
+
1210
+
1211
+ @home("cypher-truncate", "A Cypher temporal truncated to a unit, at planning",
1212
+ terms=("truncate", "date.truncate", "datetime.truncate", "localtime.truncate"))
1213
+ def truncate(kind: str, unit: str, value: Any, fields: Optional[dict] = None) -> Any:
1214
+ """`<kind>.truncate(unit, value, fields)` for literal arguments (openCypher): the value cut to the
1215
+ unit (millennium .. day, hour .. microsecond), as `kind`, then `fields` set as a constructor sets
1216
+ them over it; a date-time keeps the value's zone or offset (Z for a local value)."""
1217
+ fields = dict(fields or {})
1218
+ if not isinstance(unit, str) or unit not in _DATE_UNITS and unit not in _TIME_UNITS:
1219
+ raise NotBuilt(f"truncate to the unit {unit!r}")
1220
+ zone, offset = None, 0
1221
+ if isinstance(value, CypherDate):
1222
+ local, has_date = value.days * _DAY, True
1223
+ elif isinstance(value, CypherLocalDateTime):
1224
+ local, has_date = value.nanos, True
1225
+ elif isinstance(value, CypherDateTime):
1226
+ local, has_date, zone, offset = value.instant + value.offset * 1_000_000_000, True, value.zone, value.offset
1227
+ elif isinstance(value, CypherLocalTime):
1228
+ local, has_date = value.nanos, False
1229
+ elif isinstance(value, CypherTime):
1230
+ local, has_date, offset = value.nanos, False, value.offset
1231
+ else:
1232
+ raise NotBuilt("truncate of a value that is not a temporal literal")
1233
+ if unit in _DATE_UNITS:
1234
+ if not has_date:
1235
+ raise NotBuilt(f"truncate a time to {unit} (an error in openCypher)")
1236
+ local = _truncate_days(unit, local // _DAY) * _DAY
1237
+ else:
1238
+ if kind == "date":
1239
+ raise NotBuilt(f"date.truncate to {unit} (an error in openCypher)")
1240
+ day, nod = divmod(local, _DAY) if has_date else (0, local)
1241
+ nod = nod // _TIME_UNITS[unit] * _TIME_UNITS[unit]
1242
+ local = day * _DAY + nod if has_date else nod
1243
+ if kind == "date":
1244
+ return date_of({"date": CypherDate(local // _DAY), **fields})
1245
+ if kind == "localdatetime":
1246
+ return localdatetime_of({"datetime": CypherLocalDateTime(local), **fields})
1247
+ if kind == "localtime":
1248
+ return localtime_of({"time": CypherLocalTime(local % _DAY), **fields})
1249
+ if kind == "time":
1250
+ if "timezone" in fields: # the truncated local time at that offset (no conversion)
1251
+ new, zone = _zone(fields["timezone"])
1252
+ if zone is not None:
1253
+ raise NotBuilt("time.truncate with a named zone")
1254
+ offset = new
1255
+ return time_of({"time": CypherTime(local % _DAY, offset), **{k: v for k, v in fields.items() if k != "timezone"}})
1256
+ # datetime: the value's zone (its offset at the new local time) or offset
1257
+ if "timezone" in fields: # the truncated local value in that zone (no conversion)
1258
+ return datetime_of({"datetime": CypherLocalDateTime(local), **fields})
1259
+ base = _in_zone(local, zone) if zone is not None else CypherDateTime(local - offset * 1_000_000_000, offset)
1260
+ return datetime_of({"datetime": base, **fields})
1261
+
1262
+
1263
+ # -- duration.between and its in<unit> forms ------------------------------------------------------------
1264
+
1265
+ def _parts(v: Any):
1266
+ """(local nanoseconds, has a date, offset seconds or None, zone or None) of a literal temporal."""
1267
+ if isinstance(v, CypherDate):
1268
+ return v.days * _DAY, True, None, None
1269
+ if isinstance(v, CypherLocalDateTime):
1270
+ return v.nanos, True, None, None
1271
+ if isinstance(v, CypherDateTime):
1272
+ return v.instant + v.offset * 1_000_000_000, True, v.offset, v.zone
1273
+ if isinstance(v, CypherLocalTime):
1274
+ return v.nanos, False, None, None
1275
+ if isinstance(v, CypherTime):
1276
+ return v.nanos, False, v.offset, None
1277
+ raise NotBuilt("duration.between of a value that is not a temporal literal")
1278
+
1279
+
1280
+ def _add_months(local: int, months: int) -> int:
1281
+ days, nod = divmod(local, _DAY)
1282
+ d = CypherDate(days).date
1283
+ total = d.year * 12 + d.month - 1 + months
1284
+ y, m = divmod(total, 12)
1285
+ import calendar
1286
+ day = min(d.day, calendar.monthrange(y, m + 1)[1])
1287
+ return _of(_dt.date(y, m + 1, day)).days * _DAY + nod
1288
+
1289
+
1290
+ def _months_until(a: int, b: int) -> int:
1291
+ """Java's LocalDateTime.until(b, MONTHS): the end date moved a day back (forward) where it is after
1292
+ (before) the start and its time earlier (later); then LocalDate.until's whole months, from the packed
1293
+ month * 32 + day, truncated toward zero."""
1294
+ da, db = CypherDate(a // _DAY).date, CypherDate(b // _DAY).date
1295
+ if db > da and b % _DAY < a % _DAY:
1296
+ db = db - _dt.timedelta(days=1)
1297
+ elif db < da and b % _DAY > a % _DAY:
1298
+ db = db + _dt.timedelta(days=1)
1299
+ pa = (da.year * 12 + da.month - 1) * 32 + da.day
1300
+ pb = (db.year * 12 + db.month - 1) * 32 + db.day
1301
+ return int((pb - pa) / 32)
1302
+
1303
+
1304
+ def _days_until(a: int, b: int) -> int:
1305
+ days = b // _DAY - a // _DAY
1306
+ if days > 0 and b % _DAY < a % _DAY:
1307
+ days -= 1
1308
+ elif days < 0 and b % _DAY > a % _DAY:
1309
+ days += 1
1310
+ return days
1311
+
1312
+
1313
+ @home("cypher-duration-between", "A Cypher duration between two temporals, at planning",
1314
+ terms=("duration.between", "duration.inMonths", "duration.inDays", "duration.inSeconds"))
1315
+ def between(unit: Optional[str], a: Any, b: Any) -> CypherDuration:
1316
+ """duration.between(a, b) and duration.in{Months,Days,Seconds}(a, b) of literal temporals
1317
+ (openCypher, as Java's until): where either has no date, the difference of the times of day (at UTC
1318
+ where both have offsets); else, where both have offsets, b in a's zone, whole months then whole days
1319
+ counted on local date-times and the rest by instant (local where either has none)."""
1320
+ la, da, oa, za = _parts(a)
1321
+ lb, db, ob, zb = _parts(b)
1322
+ if not da and not db: # two times of day: their difference, at UTC where both have offsets
1323
+ ta, tb = la, lb
1324
+ if oa is not None and ob is not None:
1325
+ ta, tb = ta - oa * 1_000_000_000, tb - ob * 1_000_000_000
1326
+ return _duration(nanos=tb - ta) if unit in (None, "seconds") else _duration()
1327
+ # A side with no date takes the other's; a local side is read in the other's zone or offset.
1328
+ if not da:
1329
+ la = lb // _DAY * _DAY + la
1330
+ if not db:
1331
+ lb = la // _DAY * _DAY + lb
1332
+ if oa is not None and ob is None:
1333
+ ob, zb = (_in_zone(lb, za).offset, za) if za else (oa, None)
1334
+ elif ob is not None and oa is None:
1335
+ oa, za = (_in_zone(la, zb).offset, zb) if zb else (ob, None)
1336
+ zoned = oa is not None
1337
+
1338
+ def instant(local: int, zone: Optional[str], offset: Optional[int]) -> int:
1339
+ return _in_zone(local, zone).instant if zone else local - offset * 1_000_000_000
1340
+
1341
+ if zoned:
1342
+ ia, ib = la - oa * 1_000_000_000, lb - ob * 1_000_000_000
1343
+ lb = ib + (_offset_of_instant(za, ib) if za else oa) * 1_000_000_000 # b in a's zone
1344
+ if unit == "seconds":
1345
+ return _duration(nanos=ib - ia)
1346
+ elif unit == "seconds":
1347
+ return _duration(nanos=lb - la)
1348
+ if unit == "days":
1349
+ return _duration(days=_days_until(la, lb))
1350
+ months = _months_until(la, lb)
1351
+ if unit == "months":
1352
+ return _duration(months=months)
1353
+ a1 = _add_months(la, months)
1354
+ days = _days_until(a1, lb)
1355
+ a2 = a1 + days * _DAY
1356
+ rest = (ib - instant(a2, za, oa)) if zoned else lb - a2
1357
+ return _duration(months=months, days=days, nanos=rest)