cypher-dsl 0.1.0a2__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.
- cypher_dsl/__init__.py +180 -0
- cypher_dsl/api.py +45 -0
- cypher_dsl/ast.py +113 -0
- cypher_dsl/clauses/__init__.py +1 -0
- cypher_dsl/clauses/base.py +23 -0
- cypher_dsl/clauses/call.py +217 -0
- cypher_dsl/clauses/match.py +137 -0
- cypher_dsl/clauses/projection.py +226 -0
- cypher_dsl/clauses/unwind.py +87 -0
- cypher_dsl/clauses/write.py +571 -0
- cypher_dsl/errors.py +35 -0
- cypher_dsl/expressions/__init__.py +1 -0
- cypher_dsl/expressions/base.py +339 -0
- cypher_dsl/expressions/collections.py +162 -0
- cypher_dsl/expressions/functions.py +190 -0
- cypher_dsl/expressions/operators.py +337 -0
- cypher_dsl/expressions/properties.py +63 -0
- cypher_dsl/expressions/values.py +445 -0
- cypher_dsl/features.py +27 -0
- cypher_dsl/patterns/__init__.py +1 -0
- cypher_dsl/patterns/nodes.py +377 -0
- cypher_dsl/patterns/relationships.py +309 -0
- cypher_dsl/py.typed +0 -0
- cypher_dsl/registry.py +39 -0
- cypher_dsl/render/__init__.py +1 -0
- cypher_dsl/render/bindings.py +71 -0
- cypher_dsl/render/calls.py +36 -0
- cypher_dsl/render/capabilities.py +189 -0
- cypher_dsl/render/configuration.py +68 -0
- cypher_dsl/render/context.py +20 -0
- cypher_dsl/render/expressions.py +176 -0
- cypher_dsl/render/filters.py +21 -0
- cypher_dsl/render/fragments.py +18 -0
- cypher_dsl/render/layout.py +68 -0
- cypher_dsl/render/literals.py +285 -0
- cypher_dsl/render/patterns.py +75 -0
- cypher_dsl/render/pretty.py +247 -0
- cypher_dsl/render/projections.py +54 -0
- cypher_dsl/render/renderer.py +131 -0
- cypher_dsl/render/rules.py +84 -0
- cypher_dsl/render/statements.py +67 -0
- cypher_dsl/render/targets.py +94 -0
- cypher_dsl/render/traversal.py +100 -0
- cypher_dsl/render/unwind.py +23 -0
- cypher_dsl/render/updates.py +80 -0
- cypher_dsl/statements/__init__.py +1 -0
- cypher_dsl/statements/analysis.py +155 -0
- cypher_dsl/statements/builder.py +695 -0
- cypher_dsl/statements/composition.py +123 -0
- cypher_dsl/statements/frames.py +161 -0
- cypher_dsl/statements/rules/__init__.py +68 -0
- cypher_dsl/statements/rules/base.py +199 -0
- cypher_dsl/statements/rules/call.py +144 -0
- cypher_dsl/statements/rules/flow.py +115 -0
- cypher_dsl/statements/rules/match.py +64 -0
- cypher_dsl/statements/rules/patterns.py +58 -0
- cypher_dsl/statements/rules/projection.py +280 -0
- cypher_dsl/statements/rules/writes.py +249 -0
- cypher_dsl/statements/validation.py +125 -0
- cypher_dsl-0.1.0a2.dist-info/METADATA +168 -0
- cypher_dsl-0.1.0a2.dist-info/RECORD +64 -0
- cypher_dsl-0.1.0a2.dist-info/WHEEL +4 -0
- cypher_dsl-0.1.0a2.dist-info/licenses/LICENSE +202 -0
- cypher_dsl-0.1.0a2.dist-info/licenses/NOTICE +60 -0
cypher_dsl/__init__.py
ADDED
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Construct and render Cypher queries from Python syntax objects.
|
|
3
|
+
|
|
4
|
+
Every exported name is listed in ``__all__`` so that the facade is explicit and a missing
|
|
5
|
+
export fails at import time in a test rather than later as a missing attribute.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from cypher_dsl.api import (
|
|
9
|
+
asc,
|
|
10
|
+
assign,
|
|
11
|
+
asterisk,
|
|
12
|
+
boolean_operation,
|
|
13
|
+
call,
|
|
14
|
+
condition,
|
|
15
|
+
count,
|
|
16
|
+
create,
|
|
17
|
+
desc,
|
|
18
|
+
element_id,
|
|
19
|
+
fn,
|
|
20
|
+
in_,
|
|
21
|
+
list_,
|
|
22
|
+
lit,
|
|
23
|
+
map_,
|
|
24
|
+
match,
|
|
25
|
+
merge,
|
|
26
|
+
name,
|
|
27
|
+
node,
|
|
28
|
+
optional_call,
|
|
29
|
+
optional_match,
|
|
30
|
+
param,
|
|
31
|
+
raw,
|
|
32
|
+
returning,
|
|
33
|
+
set_labels,
|
|
34
|
+
union,
|
|
35
|
+
unwind,
|
|
36
|
+
update_properties,
|
|
37
|
+
with_,
|
|
38
|
+
)
|
|
39
|
+
from cypher_dsl.ast import AstNode, structurally_equal
|
|
40
|
+
from cypher_dsl.clauses.base import Clause
|
|
41
|
+
from cypher_dsl.clauses.call import SubqueryCallClause
|
|
42
|
+
from cypher_dsl.clauses.match import MatchClause, Where
|
|
43
|
+
from cypher_dsl.clauses.projection import ReturnClause, WithClause
|
|
44
|
+
from cypher_dsl.clauses.unwind import UnwindClause
|
|
45
|
+
from cypher_dsl.clauses.write import (
|
|
46
|
+
Assignment,
|
|
47
|
+
CreateClause,
|
|
48
|
+
DeleteClause,
|
|
49
|
+
LabelUpdate,
|
|
50
|
+
MergeAction,
|
|
51
|
+
MergeClause,
|
|
52
|
+
RemoveClause,
|
|
53
|
+
SetClause,
|
|
54
|
+
UpdateKind,
|
|
55
|
+
)
|
|
56
|
+
from cypher_dsl.expressions.base import (
|
|
57
|
+
Expression,
|
|
58
|
+
ExpressionInput,
|
|
59
|
+
LiteralInput,
|
|
60
|
+
NamedExpression,
|
|
61
|
+
ProjectionInput,
|
|
62
|
+
)
|
|
63
|
+
from cypher_dsl.expressions.collections import ListExpression, MapExpression
|
|
64
|
+
from cypher_dsl.expressions.functions import Asterisk, ElementId, FunctionInvocation, RawExpression
|
|
65
|
+
from cypher_dsl.expressions.operators import BinaryOperation, Comparison, Condition, UnaryOperation
|
|
66
|
+
from cypher_dsl.expressions.properties import Property, SubscriptExpression
|
|
67
|
+
from cypher_dsl.expressions.values import (
|
|
68
|
+
UNBOUND,
|
|
69
|
+
AliasedExpression,
|
|
70
|
+
FrozenValue,
|
|
71
|
+
Literal,
|
|
72
|
+
Parameter,
|
|
73
|
+
SortItem,
|
|
74
|
+
SortOrder,
|
|
75
|
+
SymbolicName,
|
|
76
|
+
Variable,
|
|
77
|
+
freeze_value,
|
|
78
|
+
same_binding,
|
|
79
|
+
thaw_value,
|
|
80
|
+
)
|
|
81
|
+
from cypher_dsl.features import Language
|
|
82
|
+
from cypher_dsl.patterns.nodes import NodePattern, PatternElement, PatternProperties
|
|
83
|
+
from cypher_dsl.patterns.relationships import Relationship, RelationshipDirection, RelationshipPattern
|
|
84
|
+
from cypher_dsl.render.configuration import Configuration
|
|
85
|
+
from cypher_dsl.render.renderer import Rendered, Renderer, RenderInput
|
|
86
|
+
from cypher_dsl.statements.builder import StatementBuilder
|
|
87
|
+
from cypher_dsl.statements.composition import Statement, UnionStatement
|
|
88
|
+
|
|
89
|
+
__all__ = [
|
|
90
|
+
"UNBOUND",
|
|
91
|
+
"AliasedExpression",
|
|
92
|
+
"Assignment",
|
|
93
|
+
"AstNode",
|
|
94
|
+
"Asterisk",
|
|
95
|
+
"BinaryOperation",
|
|
96
|
+
"Clause",
|
|
97
|
+
"Comparison",
|
|
98
|
+
"Condition",
|
|
99
|
+
"Configuration",
|
|
100
|
+
"CreateClause",
|
|
101
|
+
"DeleteClause",
|
|
102
|
+
"ElementId",
|
|
103
|
+
"Expression",
|
|
104
|
+
"ExpressionInput",
|
|
105
|
+
"FrozenValue",
|
|
106
|
+
"FunctionInvocation",
|
|
107
|
+
"LabelUpdate",
|
|
108
|
+
"Language",
|
|
109
|
+
"ListExpression",
|
|
110
|
+
"Literal",
|
|
111
|
+
"LiteralInput",
|
|
112
|
+
"MapExpression",
|
|
113
|
+
"MatchClause",
|
|
114
|
+
"MergeAction",
|
|
115
|
+
"MergeClause",
|
|
116
|
+
"NamedExpression",
|
|
117
|
+
"NodePattern",
|
|
118
|
+
"Parameter",
|
|
119
|
+
"PatternElement",
|
|
120
|
+
"PatternProperties",
|
|
121
|
+
"ProjectionInput",
|
|
122
|
+
"Property",
|
|
123
|
+
"RawExpression",
|
|
124
|
+
"Relationship",
|
|
125
|
+
"RelationshipDirection",
|
|
126
|
+
"RelationshipPattern",
|
|
127
|
+
"RemoveClause",
|
|
128
|
+
"RenderInput",
|
|
129
|
+
"Rendered",
|
|
130
|
+
"Renderer",
|
|
131
|
+
"ReturnClause",
|
|
132
|
+
"SetClause",
|
|
133
|
+
"SortItem",
|
|
134
|
+
"SortOrder",
|
|
135
|
+
"Statement",
|
|
136
|
+
"StatementBuilder",
|
|
137
|
+
"SubqueryCallClause",
|
|
138
|
+
"SubscriptExpression",
|
|
139
|
+
"SymbolicName",
|
|
140
|
+
"UnaryOperation",
|
|
141
|
+
"UnionStatement",
|
|
142
|
+
"UnwindClause",
|
|
143
|
+
"UpdateKind",
|
|
144
|
+
"Variable",
|
|
145
|
+
"Where",
|
|
146
|
+
"WithClause",
|
|
147
|
+
"asc",
|
|
148
|
+
"assign",
|
|
149
|
+
"asterisk",
|
|
150
|
+
"boolean_operation",
|
|
151
|
+
"call",
|
|
152
|
+
"condition",
|
|
153
|
+
"count",
|
|
154
|
+
"create",
|
|
155
|
+
"desc",
|
|
156
|
+
"element_id",
|
|
157
|
+
"fn",
|
|
158
|
+
"freeze_value",
|
|
159
|
+
"in_",
|
|
160
|
+
"list_",
|
|
161
|
+
"lit",
|
|
162
|
+
"map_",
|
|
163
|
+
"match",
|
|
164
|
+
"merge",
|
|
165
|
+
"name",
|
|
166
|
+
"node",
|
|
167
|
+
"optional_call",
|
|
168
|
+
"optional_match",
|
|
169
|
+
"param",
|
|
170
|
+
"raw",
|
|
171
|
+
"returning",
|
|
172
|
+
"same_binding",
|
|
173
|
+
"set_labels",
|
|
174
|
+
"structurally_equal",
|
|
175
|
+
"thaw_value",
|
|
176
|
+
"union",
|
|
177
|
+
"unwind",
|
|
178
|
+
"update_properties",
|
|
179
|
+
"with_",
|
|
180
|
+
]
|
cypher_dsl/api.py
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
"""Construction functions for the public API."""
|
|
2
|
+
|
|
3
|
+
from cypher_dsl.clauses.call import call, optional_call
|
|
4
|
+
from cypher_dsl.clauses.match import match, optional_match
|
|
5
|
+
from cypher_dsl.clauses.unwind import unwind
|
|
6
|
+
from cypher_dsl.clauses.write import assign, create, merge, set_labels, update_properties
|
|
7
|
+
from cypher_dsl.expressions.collections import list_, map_
|
|
8
|
+
from cypher_dsl.expressions.functions import asterisk, count, element_id, fn, raw
|
|
9
|
+
from cypher_dsl.expressions.operators import boolean_operation, condition, in_
|
|
10
|
+
from cypher_dsl.expressions.values import asc, desc, lit, name, param
|
|
11
|
+
from cypher_dsl.patterns.nodes import node
|
|
12
|
+
from cypher_dsl.statements.builder import returning, with_
|
|
13
|
+
from cypher_dsl.statements.composition import union
|
|
14
|
+
|
|
15
|
+
__all__ = [
|
|
16
|
+
"asc",
|
|
17
|
+
"assign",
|
|
18
|
+
"asterisk",
|
|
19
|
+
"boolean_operation",
|
|
20
|
+
"call",
|
|
21
|
+
"condition",
|
|
22
|
+
"count",
|
|
23
|
+
"create",
|
|
24
|
+
"desc",
|
|
25
|
+
"element_id",
|
|
26
|
+
"fn",
|
|
27
|
+
"in_",
|
|
28
|
+
"list_",
|
|
29
|
+
"lit",
|
|
30
|
+
"map_",
|
|
31
|
+
"match",
|
|
32
|
+
"merge",
|
|
33
|
+
"name",
|
|
34
|
+
"node",
|
|
35
|
+
"optional_call",
|
|
36
|
+
"optional_match",
|
|
37
|
+
"param",
|
|
38
|
+
"raw",
|
|
39
|
+
"returning",
|
|
40
|
+
"set_labels",
|
|
41
|
+
"union",
|
|
42
|
+
"unwind",
|
|
43
|
+
"update_properties",
|
|
44
|
+
"with_",
|
|
45
|
+
]
|
cypher_dsl/ast.py
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Shared contracts for abstract syntax tree nodes: child order, bound names and structural comparison.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from collections.abc import Mapping
|
|
8
|
+
from dataclasses import fields, is_dataclass
|
|
9
|
+
from typing import TypeAlias
|
|
10
|
+
|
|
11
|
+
from cypher_dsl.errors import DslError
|
|
12
|
+
|
|
13
|
+
OccurrencePath: TypeAlias = tuple[int, ...]
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class OccurrenceFacts:
|
|
17
|
+
"""Base for read-only semantic facts attached to one AST occurrence."""
|
|
18
|
+
|
|
19
|
+
__slots__ = ()
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def _require_tuple(value: object, field: str) -> None:
|
|
23
|
+
"""Reject mutable syntax containers before a frozen node can retain them."""
|
|
24
|
+
if not isinstance(value, tuple):
|
|
25
|
+
raise DslError(f"{field} must be a tuple, not {type(value).__name__}.")
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class _Visitor:
|
|
29
|
+
"""Receive node-entry and node-exit callbacks with no-op defaults."""
|
|
30
|
+
|
|
31
|
+
__slots__ = ()
|
|
32
|
+
|
|
33
|
+
def enter(self, node: AstNode) -> None:
|
|
34
|
+
"""Ignore a node entry."""
|
|
35
|
+
|
|
36
|
+
def leave(self, node: AstNode) -> None:
|
|
37
|
+
"""Ignore a node exit."""
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class AstNode:
|
|
41
|
+
"""
|
|
42
|
+
Base for every syntax node.
|
|
43
|
+
|
|
44
|
+
Subclasses declare their children in documented syntax order by overriding
|
|
45
|
+
``children``. They must not override ``accept``: keeping traversal in one place is
|
|
46
|
+
what makes every visitor see the same order.
|
|
47
|
+
|
|
48
|
+
Nodes are expected to be frozen dataclasses. The base class carries no state, so a
|
|
49
|
+
leaf node needs neither an instance dictionary nor a custom initialiser.
|
|
50
|
+
"""
|
|
51
|
+
|
|
52
|
+
__slots__ = ()
|
|
53
|
+
|
|
54
|
+
def children(self) -> tuple[AstNode, ...]:
|
|
55
|
+
"""Return the child nodes in documented syntax order."""
|
|
56
|
+
return ()
|
|
57
|
+
|
|
58
|
+
def local_names(self) -> tuple[str, ...]:
|
|
59
|
+
"""
|
|
60
|
+
Return the names this node binds for its own subtree, empty for ordinary nodes.
|
|
61
|
+
|
|
62
|
+
Clause and statement bindings live in scope frames. This hook covers bindings
|
|
63
|
+
an expression introduces inside itself, such as a comprehension variable, so
|
|
64
|
+
reference checking does not mistake them for references to an outer name.
|
|
65
|
+
"""
|
|
66
|
+
return ()
|
|
67
|
+
|
|
68
|
+
def accept(self, visitor: _Visitor) -> None:
|
|
69
|
+
"""Walk this node and its descendants, calling enter and leave in order."""
|
|
70
|
+
visitor.enter(self)
|
|
71
|
+
for child in self.children():
|
|
72
|
+
child.accept(visitor)
|
|
73
|
+
visitor.leave(self)
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def structurally_equal(left: AstNode, right: AstNode) -> bool:
|
|
77
|
+
"""
|
|
78
|
+
Compare two syntax trees by node type and named field values.
|
|
79
|
+
|
|
80
|
+
Expression equality is reserved for building predicates, so it cannot also answer
|
|
81
|
+
"are these trees the same". This function walks node types, dataclass fields,
|
|
82
|
+
tuples, lists and mappings explicitly. Value objects such as ``SymbolicName`` and
|
|
83
|
+
frozen literal records compare through their own equality, which is defined on
|
|
84
|
+
values rather than on node identity.
|
|
85
|
+
|
|
86
|
+
Args:
|
|
87
|
+
left: First tree to compare.
|
|
88
|
+
right: Second tree to compare.
|
|
89
|
+
|
|
90
|
+
Returns:
|
|
91
|
+
True when both trees have the same shape and equal field values.
|
|
92
|
+
"""
|
|
93
|
+
return _structurally_equal(left, right)
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def _structurally_equal(left: object, right: object) -> bool:
|
|
97
|
+
if left is right:
|
|
98
|
+
return True
|
|
99
|
+
if type(left) is not type(right):
|
|
100
|
+
return False
|
|
101
|
+
if isinstance(left, AstNode):
|
|
102
|
+
if not is_dataclass(left):
|
|
103
|
+
return True
|
|
104
|
+
return all(_structurally_equal(getattr(left, field.name), getattr(right, field.name)) for field in fields(left))
|
|
105
|
+
if isinstance(left, (tuple, list)) and isinstance(right, (tuple, list)):
|
|
106
|
+
return len(left) == len(right) and all(
|
|
107
|
+
_structurally_equal(left_item, right_item) for left_item, right_item in zip(left, right, strict=True)
|
|
108
|
+
)
|
|
109
|
+
if isinstance(left, Mapping) and isinstance(right, Mapping):
|
|
110
|
+
return len(left) == len(right) and all(
|
|
111
|
+
key in right and _structurally_equal(value, right[key]) for key, value in left.items()
|
|
112
|
+
)
|
|
113
|
+
return left == right
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Clause syntax, including the grammar options owned by each clause."""
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Clause base type.
|
|
3
|
+
|
|
4
|
+
A clause is a syntax node with a fixed position in a statement.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from cypher_dsl.ast import AstNode
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class Clause(AstNode):
|
|
13
|
+
"""
|
|
14
|
+
Base for a clause that occupies one position in an ordered statement.
|
|
15
|
+
|
|
16
|
+
Subclasses hold their own contents as frozen fields and expose those contents as
|
|
17
|
+
children in rendered order.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
__slots__ = ()
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
__all__ = ["Clause"]
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
"""
|
|
2
|
+
The ``CALL`` subquery clause.
|
|
3
|
+
|
|
4
|
+
A subquery call runs a finalised statement once per incoming row in its own scope. The
|
|
5
|
+
outer variables enter the body only through the variable scope clause the call renders,
|
|
6
|
+
and the names the body's final ``RETURN`` projects become available to the clauses after
|
|
7
|
+
the call. The clause stores names, not rendered text, so identifier quoting stays a
|
|
8
|
+
rendering decision.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
from dataclasses import dataclass
|
|
14
|
+
from typing import TYPE_CHECKING
|
|
15
|
+
|
|
16
|
+
from cypher_dsl.ast import AstNode, _require_tuple
|
|
17
|
+
from cypher_dsl.clauses.base import Clause
|
|
18
|
+
from cypher_dsl.errors import DslError
|
|
19
|
+
from cypher_dsl.expressions.base import Expression, ExpressionInput, require_operand
|
|
20
|
+
from cypher_dsl.expressions.values import Literal, SymbolicName, Variable, validate_name
|
|
21
|
+
from cypher_dsl.statements.composition import Statement, UnionStatement
|
|
22
|
+
|
|
23
|
+
if TYPE_CHECKING:
|
|
24
|
+
from cypher_dsl.statements.builder import StatementBuilder
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
@dataclass(frozen=True, eq=False, weakref_slot=True, slots=True)
|
|
28
|
+
class SubqueryCallClause(Clause):
|
|
29
|
+
"""
|
|
30
|
+
Run a finalised statement once per incoming row in its own scope.
|
|
31
|
+
|
|
32
|
+
The scope clause states the outer variables the body receives. The names the body's
|
|
33
|
+
final ``RETURN`` projects become available to the clauses after the call. A body
|
|
34
|
+
without a ``RETURN`` is a unit subquery: it changes the graph without changing the
|
|
35
|
+
number of rows.
|
|
36
|
+
|
|
37
|
+
Attributes:
|
|
38
|
+
subquery: The finalised statement or union the call runs.
|
|
39
|
+
imports: Variables the scope clause passes from the outer query into the body.
|
|
40
|
+
They are declarations, so they are not children.
|
|
41
|
+
import_all: Render ``(*)`` and treat every outer variable as imported.
|
|
42
|
+
optional: Render ``OPTIONAL CALL`` so rows without subquery output survive with
|
|
43
|
+
``null`` bindings.
|
|
44
|
+
in_transactions: Run the body in separate inner transactions.
|
|
45
|
+
of_rows: Input rows per inner transaction, rendered as ``OF ... ROWS``. It
|
|
46
|
+
requires ``in_transactions``.
|
|
47
|
+
"""
|
|
48
|
+
|
|
49
|
+
subquery: Statement | UnionStatement
|
|
50
|
+
imports: tuple[Variable, ...] = ()
|
|
51
|
+
import_all: bool = False
|
|
52
|
+
optional: bool = False
|
|
53
|
+
in_transactions: bool = False
|
|
54
|
+
of_rows: Expression | None = None
|
|
55
|
+
|
|
56
|
+
def __post_init__(self) -> None:
|
|
57
|
+
"""
|
|
58
|
+
Reject a body, an import list or a transaction modifier the clause cannot hold.
|
|
59
|
+
|
|
60
|
+
Raises:
|
|
61
|
+
DslError: If the body is not a finalised statement or union, a collection is
|
|
62
|
+
not a tuple, an import is not a variable, named imports are combined
|
|
63
|
+
with ``import_all``, a flag is not a boolean, or the row count is not an
|
|
64
|
+
expression that can denote a positive integer.
|
|
65
|
+
InvalidIdentifierError: If an import name cannot be an identifier.
|
|
66
|
+
"""
|
|
67
|
+
if not isinstance(self.subquery, (Statement, UnionStatement)):
|
|
68
|
+
raise DslError(f"CALL needs a finalised statement or union, not {type(self.subquery).__name__}.")
|
|
69
|
+
_require_tuple(self.imports, "CALL imports")
|
|
70
|
+
for field in ("import_all", "optional", "in_transactions"):
|
|
71
|
+
if not isinstance(getattr(self, field), bool):
|
|
72
|
+
raise DslError(f"{field} is a boolean choice, not {type(getattr(self, field)).__name__}.")
|
|
73
|
+
if self.import_all and self.imports:
|
|
74
|
+
raise DslError("CALL takes either named imports or (*), not both.")
|
|
75
|
+
for variable in self.imports:
|
|
76
|
+
if not isinstance(variable, Variable):
|
|
77
|
+
raise DslError(f"CALL imports need variables, not {type(variable).__name__}.")
|
|
78
|
+
validate_name(variable.symbol.value)
|
|
79
|
+
self._validate_of_rows()
|
|
80
|
+
|
|
81
|
+
def _validate_of_rows(self) -> None:
|
|
82
|
+
"""Reject a row count that cannot denote a positive integer."""
|
|
83
|
+
if self.of_rows is None:
|
|
84
|
+
return
|
|
85
|
+
if not self.in_transactions:
|
|
86
|
+
raise DslError("OF ... ROWS belongs to IN TRANSACTIONS. Pass in_transactions=True with of_rows.")
|
|
87
|
+
if not isinstance(self.of_rows, Expression):
|
|
88
|
+
raise DslError(f"OF ... ROWS needs an expression, not {type(self.of_rows).__name__}.")
|
|
89
|
+
require_operand(self.of_rows)
|
|
90
|
+
if not isinstance(self.of_rows, Literal):
|
|
91
|
+
return
|
|
92
|
+
rows = self.of_rows.value
|
|
93
|
+
if isinstance(rows, bool) or not isinstance(rows, int) or rows < 1:
|
|
94
|
+
raise DslError(
|
|
95
|
+
f"OF ... ROWS requires a positive integer literal, not {rows!r}. Bind a runtime value with param()."
|
|
96
|
+
)
|
|
97
|
+
|
|
98
|
+
def children(self) -> tuple[AstNode, ...]:
|
|
99
|
+
"""Expose the body and the row-count expression in rendered order."""
|
|
100
|
+
return (self.subquery,) if self.of_rows is None else (self.subquery, self.of_rows)
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def _coerce_import(item: object) -> Variable:
|
|
104
|
+
"""
|
|
105
|
+
Turn one import input into a variable.
|
|
106
|
+
|
|
107
|
+
Args:
|
|
108
|
+
item: A variable or a bare variable name.
|
|
109
|
+
|
|
110
|
+
Returns:
|
|
111
|
+
The variable the scope clause renders.
|
|
112
|
+
|
|
113
|
+
Raises:
|
|
114
|
+
DslError: If the input is neither a variable nor a string.
|
|
115
|
+
InvalidIdentifierError: If a string cannot be an identifier.
|
|
116
|
+
"""
|
|
117
|
+
if isinstance(item, Variable):
|
|
118
|
+
return item
|
|
119
|
+
if isinstance(item, str):
|
|
120
|
+
validate_name(item)
|
|
121
|
+
return Variable(SymbolicName(item))
|
|
122
|
+
raise DslError(f"CALL imports need a variable or a variable name, not {type(item).__name__}.")
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def _finalise_subquery(value: object) -> Statement | UnionStatement:
|
|
126
|
+
"""
|
|
127
|
+
Finalise one subquery input.
|
|
128
|
+
|
|
129
|
+
Args:
|
|
130
|
+
value: A statement, a union or a statement builder.
|
|
131
|
+
|
|
132
|
+
Returns:
|
|
133
|
+
The finalised body the clause can hold.
|
|
134
|
+
|
|
135
|
+
Raises:
|
|
136
|
+
DslError: If the input is none of the accepted kinds.
|
|
137
|
+
"""
|
|
138
|
+
from cypher_dsl.statements.builder import StatementBuilder
|
|
139
|
+
|
|
140
|
+
if isinstance(value, StatementBuilder):
|
|
141
|
+
return value.build()
|
|
142
|
+
if isinstance(value, (Statement, UnionStatement)):
|
|
143
|
+
return value
|
|
144
|
+
raise DslError(f"CALL accepts statements, unions and statement builders, not {type(value).__name__}.")
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
def call(
|
|
148
|
+
subquery: Statement | UnionStatement | StatementBuilder,
|
|
149
|
+
imports: tuple[str | Variable, ...] = (),
|
|
150
|
+
import_all: bool = False,
|
|
151
|
+
in_transactions: bool | ExpressionInput = False,
|
|
152
|
+
) -> StatementBuilder:
|
|
153
|
+
"""
|
|
154
|
+
Start a statement whose only clause calls a subquery.
|
|
155
|
+
|
|
156
|
+
The call renders the 5.23+ variable scope clause, so a body sees outer variables
|
|
157
|
+
only through ``imports`` or ``import_all``. A body that ends in ``RETURN`` makes its
|
|
158
|
+
returned names available to the clauses after the call.
|
|
159
|
+
|
|
160
|
+
Args:
|
|
161
|
+
subquery: Finalised statement, union or builder. A builder is finalised through
|
|
162
|
+
``build``, so an incomplete body cannot reach a renderer.
|
|
163
|
+
imports: Outer variables the scope clause passes into the body. A bare string is
|
|
164
|
+
a variable name.
|
|
165
|
+
import_all: Render ``(*)`` and pass every outer variable into the body.
|
|
166
|
+
in_transactions: Run the body in separate inner transactions. ``True`` renders
|
|
167
|
+
the bare modifier. A positive integer literal, parameter or expression
|
|
168
|
+
renders ``OF ... ROWS``.
|
|
169
|
+
|
|
170
|
+
Returns:
|
|
171
|
+
A new builder whose only clause is the ``CALL``.
|
|
172
|
+
|
|
173
|
+
Raises:
|
|
174
|
+
DslError: If the body is not finalisable, an import is not a variable name,
|
|
175
|
+
named imports and ``import_all`` are combined, or the row count is invalid.
|
|
176
|
+
"""
|
|
177
|
+
from cypher_dsl.statements.builder import StatementBuilder
|
|
178
|
+
|
|
179
|
+
return StatementBuilder().call(subquery, imports=imports, import_all=import_all, in_transactions=in_transactions)
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
def optional_call(
|
|
183
|
+
subquery: Statement | UnionStatement | StatementBuilder,
|
|
184
|
+
imports: tuple[str | Variable, ...] = (),
|
|
185
|
+
import_all: bool = False,
|
|
186
|
+
in_transactions: bool | ExpressionInput = False,
|
|
187
|
+
) -> StatementBuilder:
|
|
188
|
+
"""
|
|
189
|
+
Start a statement whose only clause optionally calls a subquery.
|
|
190
|
+
|
|
191
|
+
``OPTIONAL CALL`` keeps an outer row alive with ``null`` bindings when the body
|
|
192
|
+
produces no rows for it, the same way ``OPTIONAL MATCH`` does.
|
|
193
|
+
|
|
194
|
+
Args:
|
|
195
|
+
subquery: Finalised statement, union or builder. A builder is finalised through
|
|
196
|
+
``build``.
|
|
197
|
+
imports: Outer variables the scope clause passes into the body.
|
|
198
|
+
import_all: Render ``(*)`` and pass every outer variable into the body.
|
|
199
|
+
in_transactions: Run the body in separate inner transactions. ``True`` renders
|
|
200
|
+
the bare modifier. A positive integer literal, parameter or expression
|
|
201
|
+
renders ``OF ... ROWS``.
|
|
202
|
+
|
|
203
|
+
Returns:
|
|
204
|
+
A new builder whose only clause is the ``OPTIONAL CALL``.
|
|
205
|
+
|
|
206
|
+
Raises:
|
|
207
|
+
DslError: If the body is not finalisable, an import is not a variable name,
|
|
208
|
+
named imports and ``import_all`` are combined, or the row count is invalid.
|
|
209
|
+
"""
|
|
210
|
+
from cypher_dsl.statements.builder import StatementBuilder
|
|
211
|
+
|
|
212
|
+
return StatementBuilder().optional_call(
|
|
213
|
+
subquery, imports=imports, import_all=import_all, in_transactions=in_transactions
|
|
214
|
+
)
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
__all__ = ["SubqueryCallClause", "call", "optional_call"]
|