Debian Codegraph @

src/app_model/expressions/_expressions.py

raw
1 """Provides `Expr` and its subclasses."""
2
3 from __future__ import annotations
4
5 import ast
6 from typing import (
7 TYPE_CHECKING,
8 Any,
9 Generic,
10 SupportsIndex,
11 TypeVar,
12 Union,
13 cast,
14 overload,
15 )
16
17 ConstType = Union[None, str, bytes, bool, int, float]
18 PassedType = TypeVar(
19 "PassedType",
20 bound=Union[ast.cmpop, ast.operator, ast.boolop, ast.unaryop, ast.expr_context],
21 )
22 T = TypeVar("T")
23 T2 = TypeVar("T2", bound=Union[ConstType, "Expr"])
24 V = TypeVar("V", bound=ConstType)
25
26 if TYPE_CHECKING:
27 from collections.abc import Iterator, Mapping, Sequence
28 from types import CodeType
29
30 from pydantic.annotated_handlers import GetCoreSchemaHandler
31 from pydantic_core import core_schema
32 from typing_extensions import TypedDict, Unpack
33
34 from ._context_keys import ContextKey
35
36 # Used for node end positions in constructor keyword arguments
37 _EndPositionT = TypeVar("_EndPositionT", int, None)
38
39 # Corresponds to the names in the `_attributes`
40 # class variable which is non-empty in certain AST nodes
41 class _Attributes(TypedDict, Generic[_EndPositionT], total=False):
42 lineno: int
43 col_offset: int
44 end_lineno: _EndPositionT
45 end_col_offset: _EndPositionT
46
47
48 def parse_expression(expr: Expr | str) -> Expr:
49 """Parse string expression into an [`Expr`][app_model.expressions.Expr] instance.
50
51 Parameters
52 ----------
53 expr : Expr | str
54 Expression to parse. (If already an `Expr`, it is returned)
55
56 Returns
57 -------
58 Expr
59 Instance of `Expr`.
60
61 Raises
62 ------
63 SyntaxError
64 If the provided string is not an expression (e.g. it's a statement), or
65 if it uses any forbidden syntax components (e.g. Call, Attribute,
66 Containers, Indexing, Slicing, f-strings, named expression,
67 comprehensions.)
68 """
69 if isinstance(expr, Expr):
70 return expr
71 try:
72 # mode='eval' means the expr must consist of a single expression
73 tree = ast.parse(str(expr), mode="eval")
74 if not isinstance(tree, ast.Expression):
75 raise SyntaxError # pragma: no cover
76 return ExprTransformer().visit(tree.body)
77 except SyntaxError as e:
78 raise SyntaxError(f"{expr!r} is not a valid expression: ({e}).") from None
79
80
81 def safe_eval(expr: str | bool | Expr, context: Mapping | None = None) -> Any:
82 """Safely evaluate `expr` string given `context` dict.
83
84 This lets you evaluate a string expression with broader expression
85 support than `ast.literal_eval`, but much less support than `eval()`.
86 It also supports booleans (which are returned directly), and `Expr` instances,
87 which are evaluated in the given `context`.
88
89 Parameters
90 ----------
91 expr : str | bool | Expr
92 Expression to evaluate. If `expr` is a string, it is parsed into an
93 `Expr` instance. If a `bool`, it is returned directly.
94 context : Mapping | None
95 Context (mapping of names to objects) to evaluate the expression in.
96 """
97 if isinstance(expr, bool):
98 return expr
99 return parse_expression(expr).eval(context)
100
101
102 class Expr(ast.AST, Generic[T]):
103 """Base Expression class providing dunder and convenience methods.
104
105 This is a subclass of `ast.AST` that provides rich dunder methods that
106 facilitate joining and comparing typed expressions. It only implements a
107 subset of ast Expressions (for safety of evaluation), but provides more
108 than `ast.literal_eval`.
109
110 Expressions that are supported:
111
112 - Names: 'myvar' (these must be evaluated along with some context)
113 - Constants: '1'
114 - Comparisons: 'myvar > 1'
115 - Boolean Operators: 'myvar & yourvar' (bitwise `&` and `|` are overloaded
116 here to mean boolean `and` and `or`)
117 - Binary Operators: 'myvar + 42' (includes `//`, `@`, `^`)
118 - Unary Operators: 'not myvar'
119
120 Things that are *NOT* supported:
121
122 - attribute access: 'my.attr'
123 - calls: 'f(x)'
124 - containers (lists, tuples, sets, dicts)
125 - indexing or slicing
126 - joined strings (f-strings)
127 - named expressions (walrus operator)
128 - comprehensions (list, set, dict, generator)
129 - statements & assignments (e.g. 'a = b')
130
131 This class is not meant to be instantiated directly. Instead, use
132 [`parse_expression`][app_model.expressions._expressions.parse_expression], or the
133 [`Expr.parse`][app_model.expressions.Expr.parse] classmethod to create an expression
134 instance.
135
136 Once created, an expression can be joined with other expressions, or
137 constants.
138
139
140 Examples
141 --------
142 >>> expr = parse_expression("myvar > 5")
143
144 combine expressions with operators
145 >>> new_expr = expr & parse_expression("v2")
146
147 nice `repr`
148 >>> new_expr
149 BoolOp(
150 op=And(),
151 values=[
152 Compare(
153 left=Name(id='myvar', ctx=Load()),
154 ops=[
155 Gt()],
156 comparators=[
157 Constant(value=5)]),
158 Name(id='v2', ctx=Load())])
159
160 evaluate in some context
161 >>> new_expr.eval(dict(v2="hello!", myvar=8))
162 'hello!'
163
164 you can also use keyword arguments. This is *slightly* slower
165 >>> new_expr.eval(v2="hello!", myvar=4)
166
167 serialize
168 >>> str(new_expr)
169 'myvar > 5 and v2'
170
171 One reason you might want to use this object is to capture named expressions
172 that can be evaluated repeatedly as some underlying context changes.
173
174 ```python
175 light_is_green = Name[bool]("light_is_green")
176 count = Name[int]("count")
177 is_ready = light_is_green & count > 5
178
179 assert is_ready.eval({"count": 4, "light_is_green": True}) == False
180 assert is_ready.eval({"count": 7, "light_is_green": False}) == False
181 assert is_ready.eval({"count": 7, "light_is_green": True}) == True
182 ```
183
184 this will also preserve type information:
185 >>> reveal_type(is_ready()) # revealed type is `bool`
186 """
187
188 _names: set[str]
189 _code: CodeType
190
191 def __init__(self, *args: Any, **kwargs: Any) -> None:
192 if type(self).__name__ == "Expr":
193 raise RuntimeError("Don't instantiate Expr. Use `Expr.parse`")
194 super().__init__(*args, **kwargs)
195 self._recompile()
196
197 def _recompile(self) -> None:
198 ast.fix_missing_locations(self)
199 self._code = compile(ast.Expression(body=self), "<Expr>", "eval") # type: ignore [arg-type]
200 self._names = set(self._iter_names())
201
202 def eval(
203 self, context: Mapping[str, object] | None = None, **ctx_kwargs: object
204 ) -> T:
205 """Evaluate this expression with names in `context`."""
206 if context is None:
207 context = ctx_kwargs
208 elif ctx_kwargs:
209 context = {**context, **ctx_kwargs}
210 try:
211 return eval(self._code, {}, context) # type: ignore
212 except NameError as e:
213 miss = {k for k in self._names if k not in context}
214 raise NameError(
215 f"Names required to eval this expression are missing: {miss}"
216 ) from e
217
218 @classmethod
219 def parse(cls, expr: str) -> Expr:
220 """Parse string into Expr (classmethod).
221
222 see docstring of [`parse_expression`][app_model.expressions.parse_expression]
223 for details.
224 """
225 return parse_expression(expr)
226
227 def __str__(self) -> str:
228 """Serialize this expression to string form."""
229 return self._serialize()
230
231 def _serialize(self) -> str:
232 """Serialize this expression to string form."""
233 return str(_ExprSerializer(self))
234
235 def __repr__(self) -> str:
236 return f"Expr.parse({str(self)!r})"
237
238 @staticmethod
239 def _cast(obj: Any) -> Expr:
240 """Cast object into an Expression."""
241 return obj if isinstance(obj, Expr) else Constant(obj)
242
243 # boolean operators
244 # '&' and '|' are normally binary operators... but we use them here to
245 # combine expression objects meaning "and" and "or".
246 # if you want the binary operators, use Expr.bitand, and Expr.bitor
247
248 def __and__(
249 self, other: Expr[T2] | Expr[T] | ConstType | Compare
250 ) -> BoolOp[T | T2]:
251 return BoolOp(ast.And(), [self, other])
252
253 def __or__(self, other: Expr[T2] | Expr[T] | ConstType | Compare) -> BoolOp[T | T2]:
254 return BoolOp(ast.Or(), [self, other])
255
256 # comparisons
257
258 def __lt__(self, other: Any) -> Compare:
259 return Compare(self, [ast.Lt()], [other])
260
261 def __le__(self, other: Any) -> Compare:
262 return Compare(self, [ast.LtE()], [other])
263
264 def __eq__(self, other: Any) -> Compare: # type: ignore
265 return Compare(self, [ast.Eq()], [other])
266
267 def __ne__(self, other: Any) -> Compare: # type: ignore
268 return Compare(self, [ast.NotEq()], [other])
269
270 def __gt__(self, other: Any) -> Compare:
271 return Compare(self, [ast.Gt()], [other])
272
273 def __ge__(self, other: Any) -> Compare:
274 return Compare(self, [ast.GtE()], [other])
275
276 # using __contains__ always returns a bool... so we provide our own
277 # Expr.in_ and Expr.not_in methods
278
279 def in_(self, other: Any) -> Compare:
280 """Return a comparison for `self` in `other`."""
281 # not a dunder, use with Expr.in_(a, other)
282 return Compare(self, [ast.In()], [other])
283
284 def not_in(self, other: Any) -> Compare:
285 """Return a comparison for `self` no in `other`."""
286 return Compare(self, [ast.NotIn()], [other])
287
288 # binary operators
289 # (note that __and__ and __or__ are reserved for boolean operators.)
290
291 def __add__(self, other: T | Expr[T]) -> BinOp[T]:
292 return BinOp(self, ast.Add(), other)
293
294 def __sub__(self, other: T | Expr[T]) -> BinOp[T]:
295 return BinOp(self, ast.Sub(), other)
296
297 def __mul__(self, other: T | Expr[T]) -> BinOp[T]:
298 return BinOp(self, ast.Mult(), other)
299
300 def __truediv__(self, other: T | Expr[T]) -> BinOp[T]:
301 return BinOp(self, ast.Div(), other)
302
303 def __floordiv__(self, other: T | Expr[T]) -> BinOp[T]:
304 return BinOp(self, ast.FloorDiv(), other)
305
306 def __mod__(self, other: T | Expr[T]) -> BinOp[T]:
307 return BinOp(self, ast.Mod(), other)
308
309 def __matmul__(self, other: T | Expr[T]) -> BinOp[T]:
310 return BinOp(self, ast.MatMult(), other) # pragma: no cover
311
312 def __pow__(self, other: T | Expr[T]) -> BinOp[T]:
313 return BinOp(self, ast.Pow(), other)
314
315 def __xor__(self, other: T | Expr[T]) -> BinOp[T]:
316 return BinOp(self, ast.BitXor(), other)
317
318 def bitand(self, other: T | Expr[T]) -> BinOp[T]:
319 """Return bitwise self & other."""
320 return BinOp(self, ast.BitAnd(), other)
321
322 def bitor(self, other: T | Expr[T]) -> BinOp[T]:
323 """Return bitwise self | other."""
324 return BinOp(self, ast.BitOr(), other)
325
326 # unary operators
327
328 def __neg__(self) -> UnaryOp[T]:
329 return UnaryOp(ast.USub(), self)
330
331 def __pos__(self) -> UnaryOp[T]:
332 # usually a no-op
333 return UnaryOp(ast.UAdd(), self)
334
335 def __invert__(self) -> UnaryOp[T]:
336 # note: we're using the invert operator `~` to mean "not ___"
337 return UnaryOp(ast.Not(), self)
338
339 def __reduce_ex__(self, protocol: SupportsIndex) -> tuple[Any, ...]:
340 rv: list[Any] = list(super().__reduce_ex__(protocol))
341 rv[1] = tuple(getattr(self, f) for f in self._fields)
342 return tuple(rv)
343
344 @classmethod
345 def __get_pydantic_core_schema__(
346 cls, source: type, handler: GetCoreSchemaHandler
347 ) -> core_schema.CoreSchema:
348 # this will only be called by pydantic v2
349 from pydantic_core import core_schema
350
351 return core_schema.no_info_plain_validator_function(cls._validate)
352
353 @classmethod
354 def _validate(cls, v: Any) -> Expr:
355 """Validate v as an `Expr`. For use with Pydantic."""
356 return v if isinstance(v, Expr) else parse_expression(v)
357
358 def __hash__(self) -> int:
359 _hash = hash(self.__class__)
360 for f in self._fields:
361 field = getattr(self, f)
362 if isinstance(field, list):
363 field = tuple(field)
364 _hash += hash(field)
365 return _hash
366
367 def _iter_names(self) -> Iterator[str]:
368 yield from _iter_names(self)
369
370
371 LOAD = ast.Load()
372
373
374 class Name(Expr[T], ast.Name):
375 """A variable name.
376
377 Parameters
378 ----------
379 id : str
380 The name of the variable.
381 bound : Any | None
382 The type of the variable represented by this name (i.e. the type to which this
383 name evaluates to when used in an expression). This is used to provide type
384 hints when evaluating the expression. If `None`, the type is not known.
385 """
386
387 def __init__(
388 self,
389 id: str,
390 ctx: ast.expr_context = LOAD,
391 *,
392 bound: type[T] | None = None,
393 **kwargs: Unpack[_Attributes],
394 ) -> None:
395 super().__init__(id, ctx=ctx, **kwargs)
396 self.bound = bound
397
398
399 class Constant(Expr[V], ast.Constant):
400 """A constant value.
401
402 Parameters
403 ----------
404 value : V
405 the Python object this constant represents.
406 Types supported: NoneType, str, bytes, bool, int, float
407 kind : str | None
408 The kind of constant. This is used to provide type hints when
409 """
410
411 value: V # pyright: ignore[reportIncompatibleVariableOverride]
412
413 def __init__(
414 self, value: V, kind: str | None = None, **kwargs: Unpack[_Attributes]
415 ) -> None:
416 _valid_type = (type(None), str, bytes, bool, int, float)
417 if not isinstance(value, _valid_type):
418 raise TypeError(f"Constants must be type: {_valid_type!r}")
419 super().__init__(value, kind, **kwargs)
420
421
422 class Compare(Expr[bool], ast.Compare):
423 """A comparison of two or more values.
424
425 `left` is the first value in the comparison, `ops` the list of operators,
426 and `comparators` the list of values after the first element in the
427 comparison.
428 """
429
430 def __init__(
431 self,
432 left: Expr,
433 ops: Sequence[ast.cmpop],
434 comparators: Sequence[Expr],
435 **kwargs: Unpack[_Attributes],
436 ) -> None:
437 super().__init__(
438 Expr._cast(left), ops, [Expr._cast(c) for c in comparators], **kwargs
439 )
440
441
442 class BinOp(Expr[T], ast.BinOp):
443 """A binary operation (like addition or division).
444
445 `op` is the operator, and `left` and `right` are any expression nodes.
446 """
447
448 def __init__(
449 self,
450 left: T | Expr[T],
451 op: ast.operator,
452 right: T | Expr[T],
453 **kwargs: Unpack[_Attributes],
454 ) -> None:
455 super().__init__(Expr._cast(left), op, Expr._cast(right), **kwargs)
456
457
458 class BoolOp(Expr[T], ast.BoolOp):
459 """A boolean operation, 'or' or 'and'.
460
461 `op` is Or or And. `values` are the values involved. Consecutive operations
462 with the same operator, such as a or b or c, are collapsed into one node
463 with several values.
464
465 This doesn't include `not`, which is a `UnaryOp`.
466 """
467
468 def __init__(
469 self,
470 op: ast.boolop,
471 values: Sequence[ConstType | Expr],
472 **kwargs: Unpack[_Attributes],
473 ) -> None:
474 super().__init__(op, [Expr._cast(v) for v in values], **kwargs)
475
476
477 class UnaryOp(Expr[T], ast.UnaryOp):
478 """A unary operation.
479
480 `op` is the operator, and `operand` any expression node.
481 """
482
483 def __init__(
484 self, op: ast.unaryop, operand: Expr, **kwargs: Unpack[_Attributes]
485 ) -> None:
486 super().__init__(op, Expr._cast(operand), **kwargs)
487
488
489 class IfExp(Expr, ast.IfExp):
490 """An expression such as `'a if b else c'`.
491
492 `body` if `test` else `orelse`
493 """
494
495 def __init__(
496 self, test: Expr, body: Expr, orelse: Expr, **kwargs: Unpack[_Attributes]
497 ) -> None:
498 super().__init__(
499 Expr._cast(test), Expr._cast(body), Expr._cast(orelse), **kwargs
500 )
501
502
503 class Tuple(Expr, ast.Tuple):
504 """A tuple expression.
505
506 `elts` is a list of expressions.
507 """
508
509 def __init__(
510 self,
511 elts: Sequence[Expr],
512 ctx: ast.expr_context = LOAD,
513 **kwargs: Unpack[_Attributes],
514 ) -> None:
515 super().__init__(elts=[Expr._cast(e) for e in elts], ctx=ctx, **kwargs)
516
517
518 class List(Expr, ast.List):
519 """A tuple expression.
520
521 `elts` is a list of expressions.
522 """
523
524 def __init__(
525 self,
526 elts: Sequence[Expr],
527 ctx: ast.expr_context = LOAD,
528 **kwargs: Unpack[_Attributes],
529 ) -> None:
530 super().__init__(elts=[Expr._cast(e) for e in elts], ctx=ctx, **kwargs)
531
532
533 class Set(Expr, ast.Set):
534 """A tuple expression.
535
536 `elts` is a list of expressions.
537 """
538
539 def __init__(self, elts: Sequence[Expr], **kwargs: Unpack[_Attributes]) -> None:
540 super().__init__(elts=[Expr._cast(e) for e in elts], **kwargs)
541
542
543 class ExprTransformer(ast.NodeTransformer):
544 """Transformer that converts an ast.expr into an `Expr`.
545
546 Examples
547 --------
548 >>> tree = ast.parse("my_var > 11", mode="eval")
549 >>> tree = ExprTransformer().visit(tree) # transformed
550 """
551
552 _SUPPORTED_NODES = frozenset(
553 k for k, v in globals().items() if isinstance(v, type) and issubclass(v, Expr)
554 )
555
556 # fmt: off
557 @overload
558 def visit(self, node: ast.expr) -> Expr: ...
559 @overload
560 def visit(self, node: PassedType) -> PassedType: ...
561 # fmt: on
562 def visit(self, node: ast.AST) -> ast.AST | None:
563 """Visit a node in the tree, transforming into Expr."""
564 if isinstance(
565 node,
566 (
567 ast.cmpop,
568 ast.operator,
569 ast.boolop,
570 ast.unaryop,
571 ast.expr_context,
572 ),
573 ):
574 # all operation types just get passed through
575 return node
576
577 # filter here for supported expression node types
578 type_ = type(node).__name__
579
580 if type_ not in ExprTransformer._SUPPORTED_NODES:
581 raise SyntaxError(f"Type {type_!r} not supported")
582
583 # providing fake lineno and col_offset here rather than using
584 # ast.fill_missing_locations for typing purposes
585 kwargs: dict[str, Any] = {"lineno": 1, "col_offset": 0}
586
587 for name, field in ast.iter_fields(node):
588 if isinstance(field, ast.expr):
589 kwargs[name] = self.visit(field)
590 elif isinstance(field, list):
591 kwargs[name] = [self.visit(item) for item in field]
592 else:
593 kwargs[name] = field
594
595 # return instance of Expr from this module corresponding to the node type
596 return cast("Expr", globals()[type_](**kwargs))
597
598
599 class _ExprSerializer(ast.NodeVisitor):
600 """Serializes an `Expr` into a string.
601
602 Examples
603 --------
604 >>> expr = Expr.parse("a + b == c")
605 >>> print(expr)
606 'a + b == c'
607
608 or ... using this visitor directly:
609
610 >>> serializer = ExprSerializer()
611 >>> serializer.visit(expr)
612 >>> out = "".join(serializer.result)
613 """
614
615 def __init__(self, node: Expr | None = None) -> None:
616 self._result: list[str] = []
617
618 def write(*params: ast.AST | str) -> None:
619 for item in params:
620 if isinstance(item, ast.AST):
621 self.visit(item)
622 elif item:
623 self._result.append(item)
624
625 self.write = write
626
627 if node is not None:
628 self.visit(node)
629
630 def __str__(self) -> str:
631 return "".join(self._result)
632
633 def visit_Name(self, node: ast.Name) -> None:
634 self.write(node.id)
635
636 def visit_Tuple(self, node: ast.Tuple) -> None:
637 self.write(f"({', '.join(map(str, node.elts))})")
638
639 def visit_Set(self, node: ast.Set) -> None:
640 self.write("{" + ", ".join(map(str, node.elts)) + "}")
641
642 def visit_List(self, node: ast.List) -> None:
643 self.write(f"[{', '.join(map(str, node.elts))}]")
644
645 def visit_ContextKey(self, node: ContextKey) -> None:
646 return self.visit_Name(node)
647
648 def visit_Constant(self, node: ast.Constant) -> None:
649 self.write(repr(node.value))
650
651 def visit_BoolOp(self, node: ast.BoolOp) -> Any:
652 op = f" {_OPS[type(node.op)]} "
653 for idx, value in enumerate(node.values):
654 self.write((idx and op) or "", value)
655
656 def visit_Compare(self, node: ast.Compare) -> None:
657 self.visit(node.left)
658 for op, right in zip(node.ops, node.comparators):
659 self.write(f" {_OPS[type(op)]} ", right)
660
661 def visit_BinOp(self, node: ast.BinOp) -> None:
662 self.write(node.left, f" {_OPS[type(node.op)]} ", node.right)
663
664 def visit_UnaryOp(self, node: ast.UnaryOp) -> None:
665 sym = _OPS[type(node.op)]
666 self.write(sym, " " if sym.isalpha() else "", node.operand)
667
668 def visit_IfExp(self, node: ast.IfExp) -> Any:
669 self.write(node.body, " if ", node.test, " else ", node.orelse)
670
671
672 OpType = Union[type[ast.operator], type[ast.cmpop], type[ast.boolop], type[ast.unaryop]]
673 _OPS: dict[OpType, str] = {
674 # ast.boolop
675 ast.Or: "or",
676 ast.And: "and",
677 # ast.cmpop
678 ast.Eq: "==",
679 ast.Gt: ">",
680 ast.GtE: ">=",
681 ast.In: "in",
682 ast.Is: "is",
683 ast.NotEq: "!=",
684 ast.Lt: "<",
685 ast.LtE: "<=",
686 ast.NotIn: "not in",
687 ast.IsNot: "is not",
688 # ast.operator
689 ast.BitOr: "|",
690 ast.BitXor: "^",
691 ast.BitAnd: "&",
692 ast.LShift: "<<",
693 ast.RShift: ">>",
694 ast.Add: "+",
695 ast.Sub: "-",
696 ast.Mult: "*",
697 ast.Div: "/",
698 ast.Mod: "%",
699 ast.FloorDiv: "//",
700 ast.MatMult: "@",
701 ast.Pow: "**",
702 # ast.unaryop
703 ast.Not: "not",
704 ast.Invert: "~",
705 ast.UAdd: "+",
706 ast.USub: "-",
707 }
708
709
710 def _iter_names(expr: Expr) -> Iterator[str]:
711 """Iterate all (nested) names used in the expression.
712
713 Could be used to provide nicer error messages when eval() fails.
714 """
715 if isinstance(expr, Name):
716 yield expr.id
717 elif isinstance(expr, Expr):
718 for _, val in ast.iter_fields(expr):
719 val = val if isinstance(val, list) else [val]
720 for v in val:
721 yield from _iter_names(v)