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.
- prograph/__init__.py +36 -0
- prograph/__main__.py +5 -0
- prograph/_version.py +375 -0
- prograph/cli/__init__.py +1 -0
- prograph/cli/_iri_utils.py +124 -0
- prograph/cli/emit_genie_space.py +107 -0
- prograph/cli/generate_views.py +140 -0
- prograph/cli/main.py +420 -0
- prograph/cli/schema_inferrer.py +746 -0
- prograph/cli/ttl_loader.py +289 -0
- prograph/cli/upload_genie_space.py +84 -0
- prograph/config/__init__.py +27 -0
- prograph/config/yaml_config.py +848 -0
- prograph/demos/__init__.py +14 -0
- prograph/demos/turbofan/README.md +74 -0
- prograph/demos/turbofan/SCENARIO.md +209 -0
- prograph/demos/turbofan/__init__.py +75 -0
- prograph/demos/turbofan/create_tables.sql +206 -0
- prograph/demos/turbofan/data/engine-instances.ttl +1123 -0
- prograph/demos/turbofan/data/sensor-timeseries.csv +90 -0
- prograph/demos/turbofan/demo.py +162 -0
- prograph/demos/turbofan/genie_qa_notebook.py +434 -0
- prograph/demos/turbofan/graph.yaml +1098 -0
- prograph/demos/turbofan/instance_graph_demo.py +32 -0
- prograph/demos/turbofan/load.py +223 -0
- prograph/demos/turbofan/mapping.r2rml.ttl +991 -0
- prograph/demos/turbofan/ontology/engine-maintenance.ttl +606 -0
- prograph/demos/turbofan/payload-shapes.ttl +33 -0
- prograph/demos/turbofan/queries/example-queries.sparql +215 -0
- prograph/demos/turbofan/shapes.ttl +75 -0
- prograph/demos/turbofan/tables.py +106 -0
- prograph/demos/turbofan/turbofan_schema.py +393 -0
- prograph/demos/turbofan/validation_demo.py +153 -0
- prograph/describe.py +231 -0
- prograph/endpoint/__init__.py +12 -0
- prograph/endpoint/app.py +722 -0
- prograph/endpoint/cli.py +280 -0
- prograph/endpoint/credentials.py +240 -0
- prograph/endpoint/engines.py +418 -0
- prograph/endpoint/negotiate.py +101 -0
- prograph/endpoint/results.py +181 -0
- prograph/endpoint/service.py +31 -0
- prograph/engine.py +2718 -0
- prograph/execution.py +455 -0
- prograph/executors/__init__.py +6 -0
- prograph/executors/base.py +11 -0
- prograph/executors/databricks_sql_executor.py +51 -0
- prograph/executors/duckdb_executor.py +24 -0
- prograph/executors/mysql_executor.py +20 -0
- prograph/executors/oracle_executor.py +24 -0
- prograph/executors/pandas_executor.py +72 -0
- prograph/executors/postgresql_executor.py +35 -0
- prograph/executors/spark_executor.py +88 -0
- prograph/executors/sqlserver_executor.py +35 -0
- prograph/extras/__init__.py +1 -0
- prograph/extras/graphql/__init__.py +33 -0
- prograph/extras/graphql/execute.py +25 -0
- prograph/extras/graphql/schema.py +314 -0
- prograph/extras/instance_graph.py +559 -0
- prograph/genie/__init__.py +83 -0
- prograph/genie/databricks_uploader.py +306 -0
- prograph/genie/deploy.py +393 -0
- prograph/genie/formats.py +414 -0
- prograph/genie/instruction_generator.py +375 -0
- prograph/genie/sample_query_generator.py +256 -0
- prograph/genie/shacl_views.py +318 -0
- prograph/genie/space_emitter.py +329 -0
- prograph/genie/view_generator.py +628 -0
- prograph/genie/view_writer.py +172 -0
- prograph/graph/__init__.py +1 -0
- prograph/graph/ansi_session.py +348 -0
- prograph/graph/databricks_sql_graph.py +300 -0
- prograph/graph/drivers.py +143 -0
- prograph/graph/duckdb_graph.py +68 -0
- prograph/graph/mysql_graph.py +38 -0
- prograph/graph/oracle_graph.py +285 -0
- prograph/graph/pandas_graph.py +343 -0
- prograph/graph/postgresql_graph.py +644 -0
- prograph/graph/spark_graph.py +556 -0
- prograph/graph/sql_graph.py +83 -0
- prograph/graph/sqlserver_graph.py +72 -0
- prograph/hints.py +95 -0
- prograph/logging.py +550 -0
- prograph/mcp/__init__.py +29 -0
- prograph/mcp/__main__.py +180 -0
- prograph/mcp/bootstrap.py +98 -0
- prograph/mcp/server.py +601 -0
- prograph/mcp/sparql.py +397 -0
- prograph/mcp/tools.py +504 -0
- prograph/nlp/__init__.py +79 -0
- prograph/nlp/client.py +305 -0
- prograph/nlp/databricks_tools.py +369 -0
- prograph/nlp/graph_context.py +313 -0
- prograph/nlp/interface.py +652 -0
- prograph/nlp/prompts/__init__.py +19 -0
- prograph/nlp/prompts/examples.py +258 -0
- prograph/nlp/prompts/system.py +239 -0
- prograph/nlp/providers/__init__.py +14 -0
- prograph/nlp/providers/anthropic.py +274 -0
- prograph/nlp/providers/databricks.py +312 -0
- prograph/nlp/providers/openai.py +203 -0
- prograph/nlp/schema_context.py +78 -0
- prograph/ontology/__init__.py +53 -0
- prograph/ontology/alignment.py +542 -0
- prograph/ontology/hierarchy.py +310 -0
- prograph/ontology/imports.py +587 -0
- prograph/ontology/layer.py +991 -0
- prograph/ontology/skos.py +61 -0
- prograph/owl/__init__.py +27 -0
- prograph/owl/defined_classes.py +323 -0
- prograph/parameters.py +242 -0
- prograph/parser/__init__.py +1 -0
- prograph/parser/cypher/CypherLexer.py +836 -0
- prograph/parser/cypher/CypherListener.py +966 -0
- prograph/parser/cypher/CypherParser.py +10854 -0
- prograph/parser/cypher/CypherVisitor.py +543 -0
- prograph/parser/cypher/__init__.py +1 -0
- prograph/parser/sparql/SparqlLexer.py +801 -0
- prograph/parser/sparql/SparqlParser.py +10146 -0
- prograph/parser/sparql/SparqlParserListener.py +1056 -0
- prograph/parser/sparql/SparqlParserVisitor.py +593 -0
- prograph/parser/sparql/__init__.py +8 -0
- prograph/plan/__init__.py +3 -0
- prograph/plan/ir/__init__.py +1 -0
- prograph/plan/ir/casts.py +338 -0
- prograph/plan/ir/consistency.py +397 -0
- prograph/plan/ir/construct.py +90 -0
- prograph/plan/ir/cost.py +234 -0
- prograph/plan/ir/cypher_answer.py +1081 -0
- prograph/plan/ir/cypher_apoc.py +717 -0
- prograph/plan/ir/cypher_apoc_convert.py +505 -0
- prograph/plan/ir/cypher_apoc_date.py +845 -0
- prograph/plan/ir/cypher_apoc_map.py +496 -0
- prograph/plan/ir/cypher_apoc_meta.py +384 -0
- prograph/plan/ir/cypher_apoc_path.py +597 -0
- prograph/plan/ir/cypher_apoc_procedures.py +163 -0
- prograph/plan/ir/cypher_apoc_text.py +785 -0
- prograph/plan/ir/cypher_front.py +5474 -0
- prograph/plan/ir/cypher_functions.py +565 -0
- prograph/plan/ir/cypher_lists.py +935 -0
- prograph/plan/ir/cypher_maps.py +370 -0
- prograph/plan/ir/cypher_mixed.py +604 -0
- prograph/plan/ir/cypher_ontology.py +226 -0
- prograph/plan/ir/cypher_procedures.py +191 -0
- prograph/plan/ir/cypher_runtime_errors.py +107 -0
- prograph/plan/ir/cypher_temporal.py +1357 -0
- prograph/plan/ir/cypher_temporal_arith.py +339 -0
- prograph/plan/ir/cypher_values.py +546 -0
- prograph/plan/ir/cypher_write.py +612 -0
- prograph/plan/ir/dataset.py +643 -0
- prograph/plan/ir/dates.py +102 -0
- prograph/plan/ir/entry.py +992 -0
- prograph/plan/ir/expr.py +260 -0
- prograph/plan/ir/facts.py +1171 -0
- prograph/plan/ir/fresh.py +291 -0
- prograph/plan/ir/freshness.py +625 -0
- prograph/plan/ir/identity.py +797 -0
- prograph/plan/ir/java_datetime.py +265 -0
- prograph/plan/ir/java_regex.py +391 -0
- prograph/plan/ir/join_order.py +39 -0
- prograph/plan/ir/key_checks.py +433 -0
- prograph/plan/ir/keys.py +454 -0
- prograph/plan/ir/lower.py +5323 -0
- prograph/plan/ir/ops.py +619 -0
- prograph/plan/ir/owl_rl.py +1119 -0
- prograph/plan/ir/owl_rl_rules.py +725 -0
- prograph/plan/ir/profiles.py +694 -0
- prograph/plan/ir/ql.py +987 -0
- prograph/plan/ir/rdfs.py +342 -0
- prograph/plan/ir/rewrite.py +1782 -0
- prograph/plan/ir/saturate.py +339 -0
- prograph/plan/ir/semantics.py +103 -0
- prograph/plan/ir/slot.py +509 -0
- prograph/plan/ir/sparql_front.py +3418 -0
- prograph/plan/ir/strings.py +534 -0
- prograph/plan/ir/term_functions.py +274 -0
- prograph/plan/ir/terms.py +84 -0
- prograph/plan/ir/xpath_regex.py +264 -0
- prograph/plan/run_record.py +65 -0
- prograph/plan/sql/__init__.py +21 -0
- prograph/plan/sql/dialect.py +3726 -0
- prograph/plan/sql/mysql_serializer.py +103 -0
- prograph/plan/sql/names.py +65 -0
- prograph/plan/sql/oracle_serializer.py +306 -0
- prograph/plan/sql/pg_serializer.py +501 -0
- prograph/plan/sql/rel_algebra.py +781 -0
- prograph/plan/sql/sql_serializer.py +1419 -0
- prograph/plan/sql/sqlserver_serializer.py +603 -0
- prograph/provenance.py +222 -0
- prograph/r2rml/__init__.py +48 -0
- prograph/r2rml/catalog.py +259 -0
- prograph/r2rml/compile.py +372 -0
- prograph/r2rml/direct.py +140 -0
- prograph/r2rml/export.py +495 -0
- prograph/r2rml/model.py +180 -0
- prograph/r2rml/parser.py +546 -0
- prograph/r2rml/schema.py +120 -0
- prograph/read_only.py +122 -0
- prograph/results.py +157 -0
- prograph/rules/__init__.py +168 -0
- prograph/rules/__main__.py +32 -0
- prograph/schema/__init__.py +60 -0
- prograph/schema/change_set.py +50 -0
- prograph/schema/collations.py +198 -0
- prograph/schema/compile_schema.py +388 -0
- prograph/schema/context.py +845 -0
- prograph/schema/examples.py +234 -0
- prograph/schema/iri.py +817 -0
- prograph/schema/literals.py +94 -0
- prograph/schema/lpg_view.py +617 -0
- prograph/schema/mapping.py +1803 -0
- prograph/schema/maps_schema.py +40 -0
- prograph/schema/naming.py +77 -0
- prograph/schema/query_sources.py +59 -0
- prograph/schema/rows.py +215 -0
- prograph/schema/source_map.py +1103 -0
- prograph/schema/store_view.py +459 -0
- prograph/schema/types.py +569 -0
- prograph/schema/xsd.py +569 -0
- prograph/shacl/__init__.py +30 -0
- prograph/shacl/dqv.py +58 -0
- prograph/shacl/generate.py +255 -0
- prograph/shacl/report.py +138 -0
- prograph/shacl/validator.py +164 -0
- prograph/store.py +1737 -0
- prograph/utils/__init__.py +6 -0
- prograph/utils/exceptions.py +308 -0
- prograph/utils/helpers.py +126 -0
- prograph/warnings.py +46 -0
- prograph/writes.py +369 -0
- prograph-1.3.3.dist-info/METADATA +281 -0
- prograph-1.3.3.dist-info/RECORD +237 -0
- prograph-1.3.3.dist-info/WHEEL +5 -0
- prograph-1.3.3.dist-info/entry_points.txt +3 -0
- prograph-1.3.3.dist-info/licenses/LICENSE +201 -0
- prograph-1.3.3.dist-info/licenses/NOTICE +10 -0
- 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)
|