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.
Files changed (64) hide show
  1. cypher_dsl/__init__.py +180 -0
  2. cypher_dsl/api.py +45 -0
  3. cypher_dsl/ast.py +113 -0
  4. cypher_dsl/clauses/__init__.py +1 -0
  5. cypher_dsl/clauses/base.py +23 -0
  6. cypher_dsl/clauses/call.py +217 -0
  7. cypher_dsl/clauses/match.py +137 -0
  8. cypher_dsl/clauses/projection.py +226 -0
  9. cypher_dsl/clauses/unwind.py +87 -0
  10. cypher_dsl/clauses/write.py +571 -0
  11. cypher_dsl/errors.py +35 -0
  12. cypher_dsl/expressions/__init__.py +1 -0
  13. cypher_dsl/expressions/base.py +339 -0
  14. cypher_dsl/expressions/collections.py +162 -0
  15. cypher_dsl/expressions/functions.py +190 -0
  16. cypher_dsl/expressions/operators.py +337 -0
  17. cypher_dsl/expressions/properties.py +63 -0
  18. cypher_dsl/expressions/values.py +445 -0
  19. cypher_dsl/features.py +27 -0
  20. cypher_dsl/patterns/__init__.py +1 -0
  21. cypher_dsl/patterns/nodes.py +377 -0
  22. cypher_dsl/patterns/relationships.py +309 -0
  23. cypher_dsl/py.typed +0 -0
  24. cypher_dsl/registry.py +39 -0
  25. cypher_dsl/render/__init__.py +1 -0
  26. cypher_dsl/render/bindings.py +71 -0
  27. cypher_dsl/render/calls.py +36 -0
  28. cypher_dsl/render/capabilities.py +189 -0
  29. cypher_dsl/render/configuration.py +68 -0
  30. cypher_dsl/render/context.py +20 -0
  31. cypher_dsl/render/expressions.py +176 -0
  32. cypher_dsl/render/filters.py +21 -0
  33. cypher_dsl/render/fragments.py +18 -0
  34. cypher_dsl/render/layout.py +68 -0
  35. cypher_dsl/render/literals.py +285 -0
  36. cypher_dsl/render/patterns.py +75 -0
  37. cypher_dsl/render/pretty.py +247 -0
  38. cypher_dsl/render/projections.py +54 -0
  39. cypher_dsl/render/renderer.py +131 -0
  40. cypher_dsl/render/rules.py +84 -0
  41. cypher_dsl/render/statements.py +67 -0
  42. cypher_dsl/render/targets.py +94 -0
  43. cypher_dsl/render/traversal.py +100 -0
  44. cypher_dsl/render/unwind.py +23 -0
  45. cypher_dsl/render/updates.py +80 -0
  46. cypher_dsl/statements/__init__.py +1 -0
  47. cypher_dsl/statements/analysis.py +155 -0
  48. cypher_dsl/statements/builder.py +695 -0
  49. cypher_dsl/statements/composition.py +123 -0
  50. cypher_dsl/statements/frames.py +161 -0
  51. cypher_dsl/statements/rules/__init__.py +68 -0
  52. cypher_dsl/statements/rules/base.py +199 -0
  53. cypher_dsl/statements/rules/call.py +144 -0
  54. cypher_dsl/statements/rules/flow.py +115 -0
  55. cypher_dsl/statements/rules/match.py +64 -0
  56. cypher_dsl/statements/rules/patterns.py +58 -0
  57. cypher_dsl/statements/rules/projection.py +280 -0
  58. cypher_dsl/statements/rules/writes.py +249 -0
  59. cypher_dsl/statements/validation.py +125 -0
  60. cypher_dsl-0.1.0a2.dist-info/METADATA +168 -0
  61. cypher_dsl-0.1.0a2.dist-info/RECORD +64 -0
  62. cypher_dsl-0.1.0a2.dist-info/WHEEL +4 -0
  63. cypher_dsl-0.1.0a2.dist-info/licenses/LICENSE +202 -0
  64. 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"]