Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/astroid/constraint.py: 33%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# Licensed under the LGPL: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html
2# For details: https://github.com/pylint-dev/astroid/blob/main/LICENSE
3# Copyright (c) https://github.com/pylint-dev/astroid/blob/main/CONTRIBUTORS.txt
5"""Classes representing different types of constraints on inference values."""
7from __future__ import annotations
9from abc import ABC, abstractmethod
10from collections.abc import Iterator
11from typing import Self
13from astroid import bases, helpers, nodes, util
14from astroid.context import InferenceContext
15from astroid.exceptions import (
16 AstroidError,
17 AstroidTypeError,
18 InferenceError,
19 MroError,
20)
21from astroid.typing import InferenceResult
23_NameNodes = nodes.AssignAttr | nodes.Attribute | nodes.AssignName | nodes.Name
26class Constraint(ABC):
27 """Represents a single constraint on a variable."""
29 def __init__(self, node: nodes.NodeNG, negate: bool) -> None:
30 self.node = node
31 """The node that this constraint applies to."""
32 self.negate = negate
33 """True if this constraint is negated. E.g., "is not" instead of "is"."""
35 @classmethod
36 @abstractmethod
37 def match(
38 cls, node: _NameNodes, expr: nodes.NodeNG, negate: bool = False
39 ) -> Self | None:
40 """Return a new constraint for node matched from expr, if expr matches
41 the constraint pattern.
43 If negate is True, negate the constraint.
44 """
46 @abstractmethod
47 def satisfied_by(
48 self, inferred: InferenceResult, context: InferenceContext
49 ) -> bool:
50 """Return True if this constraint is satisfied by the given inferred value."""
53class NoneConstraint(Constraint):
54 """Represents an "is None" or "is not None" constraint."""
56 CONST_NONE: nodes.Const = nodes.Const(None)
58 @classmethod
59 def match(
60 cls, node: _NameNodes, expr: nodes.NodeNG, negate: bool = False
61 ) -> Self | None:
62 """Return a new constraint for node matched from expr, if expr matches
63 the constraint pattern.
65 Negate the constraint based on the value of negate.
66 """
67 if isinstance(expr, nodes.Compare) and len(expr.ops) == 1:
68 left = expr.left
69 op, right = expr.ops[0]
70 if op in {"is", "is not"} and (
71 _matches(left, node) and _matches(right, cls.CONST_NONE)
72 ):
73 negate = (op == "is" and negate) or (op == "is not" and not negate)
74 return cls(node=node, negate=negate)
76 return None
78 def satisfied_by(
79 self, inferred: InferenceResult, context: InferenceContext
80 ) -> bool:
81 """Return True if this constraint is satisfied by the given inferred value."""
82 # Assume true if uninferable
83 if inferred is util.Uninferable:
84 return True
86 # Return the XOR of self.negate and matches(inferred, self.CONST_NONE)
87 return self.negate ^ _matches(inferred, self.CONST_NONE)
90class BooleanConstraint(Constraint):
91 """Represents an "x" or "not x" constraint."""
93 @classmethod
94 def match(
95 cls, node: _NameNodes, expr: nodes.NodeNG, negate: bool = False
96 ) -> Self | None:
97 """Return a new constraint for node if expr is node, else return None.
99 ``not x`` is matched by ``_match_constraint``, which flips negate.
100 """
101 if _matches(expr, node):
102 return cls(node=node, negate=negate)
104 return None
106 def satisfied_by(
107 self, inferred: InferenceResult, context: InferenceContext
108 ) -> bool:
109 """Return True for uninferable results, or depending on negate flag:
111 - negate=False: satisfied if boolean value is True
112 - negate=True: satisfied if boolean value is False
113 """
114 inferred_booleaness = inferred.bool_value()
115 if inferred is util.Uninferable or inferred_booleaness is util.Uninferable:
116 return True
118 return self.negate ^ inferred_booleaness
121class TypeConstraint(Constraint):
122 """Represents an "isinstance(x, y)" constraint."""
124 def __init__(
125 self, node: nodes.NodeNG, classinfo: nodes.NodeNG, negate: bool
126 ) -> None:
127 super().__init__(node=node, negate=negate)
128 self.classinfo = classinfo
130 @classmethod
131 def match(
132 cls, node: _NameNodes, expr: nodes.NodeNG, negate: bool = False
133 ) -> Self | None:
134 """Return a new constraint for node if expr matches the
135 "isinstance(x, y)" pattern. Else, return None.
136 """
137 is_instance_call = (
138 isinstance(expr, nodes.Call)
139 and isinstance(expr.func, nodes.Name)
140 and expr.func.name == "isinstance"
141 and not expr.keywords
142 and len(expr.args) == 2
143 )
144 if is_instance_call and _matches(expr.args[0], node):
145 return cls(node=node, classinfo=expr.args[1], negate=negate)
147 return None
149 def satisfied_by(
150 self, inferred: InferenceResult, context: InferenceContext
151 ) -> bool:
152 """Return True for uninferable results, or depending on negate flag:
154 - negate=False: satisfied when inferred is an instance of the checked types.
155 - negate=True: satisfied when inferred is not an instance of the checked types.
156 """
157 if inferred is util.Uninferable:
158 return True
160 # This method is called once per inferred value, with the same context.
161 # Use a clone: inferring the classinfo pushes it onto the context's
162 # inference path but only its first value is consumed, so nothing is
163 # cached and a reused context would make the classinfo uninferable
164 # from the second call on.
165 context = context.clone()
166 try:
167 types = helpers.class_or_tuple_to_container(self.classinfo, context)
168 matches_checked_types = helpers.object_isinstance(inferred, types, context)
170 if matches_checked_types is util.Uninferable:
171 return True
173 return self.negate ^ matches_checked_types
174 except (InferenceError, AstroidTypeError, MroError):
175 return True
178class CallableConstraint(Constraint):
179 """Represents a "callable(x)" constraint."""
181 @classmethod
182 def match(
183 cls, node: _NameNodes, expr: nodes.NodeNG, negate: bool = False
184 ) -> Self | None:
185 """Return a new constraint for node if expr matches the "callable(x)"
186 pattern. Else, return None.
187 """
188 is_callable_call = (
189 isinstance(expr, nodes.Call)
190 and isinstance(expr.func, nodes.Name)
191 and expr.func.name == "callable"
192 and not expr.keywords
193 and len(expr.args) == 1
194 )
195 if is_callable_call and _matches(expr.args[0], node):
196 return cls(node=node, negate=negate)
198 return None
200 def satisfied_by(
201 self, inferred: InferenceResult, context: InferenceContext
202 ) -> bool:
203 """Return True for uninferable results, or depending on negate flag:
205 - negate=False: satisfied when inferred is callable.
206 - negate=True: satisfied when inferred is not callable.
207 """
208 if inferred is util.Uninferable:
209 return True
211 # A base class that cannot be inferred may define __call__.
212 if isinstance(inferred, bases.Instance) and not helpers.has_known_bases(
213 inferred._proxied, context
214 ):
215 return True
217 return self.negate ^ inferred.callable()
220class EqualityConstraint(Constraint):
221 """Represents a "==" or "!=" constraint."""
223 def __init__(self, node: nodes.NodeNG, operand: nodes.NodeNG, negate: bool) -> None:
224 super().__init__(node=node, negate=negate)
225 self.operand = operand
227 @classmethod
228 def match(
229 cls, node: _NameNodes, expr: nodes.NodeNG, negate: bool = False
230 ) -> Self | None:
231 """Return a new constraint for node if expr matches one of these patterns:
233 - "node == operand" or "operand == node": use given negate value
234 - "node != operand" or "operand != node": flip negate value
236 Return None if no pattern matches.
237 """
238 if isinstance(expr, nodes.Compare) and len(expr.ops) == 1:
239 left = expr.left
240 op, right = expr.ops[0]
241 matches_left = _matches(left, node)
243 if op in {"==", "!="} and (matches_left or _matches(right, node)):
244 operand = right if matches_left else left
245 negate = (op == "==" and negate) or (op == "!=" and not negate)
246 return cls(node=node, operand=operand, negate=negate)
248 return None
250 def satisfied_by(
251 self, inferred: InferenceResult, context: InferenceContext
252 ) -> bool:
253 """Return True for uninferable/ambiguous results, or depending on negate flag:
255 - negate=False: satisfied when both operands are equal.
256 - negate=True: satisfied when both operands are not equal.
258 Only comparisons between constants and callables are supported.
259 """
260 if inferred is util.Uninferable:
261 return True
263 operand_inferred = util.safe_infer(self.operand, context)
264 if operand_inferred is util.Uninferable or operand_inferred is None:
265 return True
267 if isinstance(inferred, nodes.Const) and isinstance(
268 operand_inferred, nodes.Const
269 ):
270 return self.negate ^ (inferred.value == operand_inferred.value)
272 if inferred.callable() and operand_inferred.callable():
273 return self.negate ^ (inferred is operand_inferred)
275 return True
278class _CompoundConstraint(Constraint):
279 """Represents an "x and y" or "x or y" constraint."""
281 def __init__(
282 self,
283 node: nodes.NodeNG,
284 op: str,
285 children: list[Constraint],
286 negate: bool,
287 ) -> None:
288 super().__init__(node=node, negate=negate)
289 self.op = op
290 self.children = children
292 @classmethod
293 def match(
294 cls, node: _NameNodes, expr: nodes.NodeNG, negate: bool = False
295 ) -> Self | None:
296 """Return a new constraint for node if expr matches an "x and y" or
297 "x or y" pattern.
299 Return None if expr is not a supported boolean expression, or if any
300 operand does not match a constraint pattern.
301 """
302 if not (isinstance(expr, nodes.BoolOp) and expr.op in {"and", "or"}):
303 return None
305 children: list[Constraint] = []
306 for value in expr.values:
307 matches = list(_match_constraint(node, value, negate))
308 if not matches:
309 return None
310 children.extend(matches)
312 return cls(node=node, op=expr.op, children=children, negate=negate)
314 def satisfied_by(
315 self, inferred: InferenceResult, context: InferenceContext
316 ) -> bool:
317 """Return True for uninferable results, or depending on op and negate:
319 - negate=False: all children must be satisfied for "and", or any for "or".
320 - negate=True: any child must be satisfied for "and", or all for "or".
321 """
322 if inferred is util.Uninferable:
323 return True
325 results = (
326 constraint.satisfied_by(inferred, context) for constraint in self.children
327 )
329 strict = (self.op == "and") ^ self.negate
330 return all(results) if strict else any(results)
333def get_constraints(
334 expr: _NameNodes, frame: nodes.LocalsDictNodeNG
335) -> dict[nodes.NodeNG, set[Constraint]]:
336 """Returns the constraints for the given expression.
338 The returned dictionary maps the node where the constraint was generated to the
339 corresponding constraint(s).
341 Constraints are computed statically by analysing the code surrounding expr.
342 Currently this only supports constraints generated from if conditions,
343 comprehension conditions, preceding operands in boolean operations, and
344 preceding guard statements: asserts, ifs whose body ends with a return, raise,
345 continue or break, and ifs whose body assigns expr.
346 """
347 current_node: nodes.NodeNG | None = expr
348 constraints_mapping: dict[nodes.NodeNG, set[Constraint]] = {}
349 name = (
350 expr.attrname
351 if isinstance(expr, (nodes.Attribute, nodes.AssignAttr))
352 else expr.name
353 )
354 # Guards before a function, lambda, class or generator expression do not
355 # constrain its body: it may run later, after a reassignment.
356 collect_guards = True
357 while current_node is not None and current_node is not frame:
358 parent = current_node.parent
359 constraints: set[Constraint] | None = None
361 if isinstance(
362 current_node,
363 (nodes.FunctionDef, nodes.Lambda, nodes.ClassDef, nodes.GeneratorExp),
364 ):
365 collect_guards = False
366 elif collect_guards and current_node.is_statement:
367 if guards := _preceding_guards(current_node).get(name):
368 _add_guards_constraints(expr, guards, constraints_mapping)
370 if isinstance(parent, (nodes.If, nodes.IfExp)):
371 branch, _ = parent.locate_child(current_node)
372 if branch == "body":
373 constraints = set(_match_constraint(expr, parent.test))
374 elif branch == "orelse":
375 constraints = set(_match_constraint(expr, parent.test, invert=True))
376 if constraints:
377 constraints_mapping[parent] = constraints
379 elif isinstance(parent, nodes.BoolOp):
380 # Later operands are evaluated only if all preceding ones are
381 # truthy for "and", or all falsy for "or".
382 index = parent.values.index(current_node)
383 constraints = set()
384 for previous_value in parent.values[:index]:
385 constraints.update(
386 _match_constraint(expr, previous_value, invert=parent.op == "or")
387 )
388 if constraints:
389 constraints_mapping[parent] = constraints
390 elif isinstance(parent, nodes.Comprehension):
391 try:
392 index = parent.ifs.index(current_node)
393 except ValueError:
394 pass
395 else:
396 # Preceding conditions of the same generator guard this condition.
397 _add_ifs_constraints(expr, parent.ifs[:index], constraints_mapping)
398 elif isinstance(
399 parent, (nodes.ListComp, nodes.SetComp, nodes.DictComp, nodes.GeneratorExp)
400 ):
401 branch, _ = parent.locate_child(current_node)
402 if branch == "generators":
403 # Conditions guard the iterables of all later generators.
404 index = parent.generators.index(current_node)
405 generators = parent.generators[:index]
406 else: # elt, key or value: guarded by all conditions
407 generators = parent.generators
408 for comprehension in generators:
409 _add_ifs_constraints(expr, comprehension.ifs, constraints_mapping)
410 current_node = parent
412 return constraints_mapping
415def constraint_applies(
416 constraint_stmt: nodes.NodeNG, stmt: InferenceResult, expr: _NameNodes
417) -> bool:
418 """Return True if the constraints generated at constraint_stmt for expr apply
419 to the values assigned by stmt.
421 They do not apply to an assignment inside constraint_stmt, nor to one that can
422 run between constraint_stmt and expr, as in ``if x is None: return``, then
423 ``x = None``.
424 """
425 if constraint_stmt.parent_of(stmt):
426 return False
427 start = (constraint_stmt.end_lineno, constraint_stmt.end_col_offset)
428 position = (stmt.lineno, stmt.col_offset)
429 if None in start or None in position or position < start:
430 return True
431 # A position in another module says nothing about when the assignment runs.
432 if stmt.root() is not constraint_stmt.root():
433 return True
434 end = _unconstrained_range_end(constraint_stmt, expr)
435 return None in end or position > end
438def _unconstrained_range_end(
439 constraint_stmt: nodes.NodeNG, expr: _NameNodes
440) -> tuple[int | None, int | None]:
441 """Return the position up to which an assignment after constraint_stmt can
442 reach expr without running constraint_stmt again.
444 That is expr itself, or the end of the outermost loop containing expr but not
445 constraint_stmt: an assignment after expr in that loop reaches expr on the next
446 iteration.
447 """
448 end: nodes.NodeNG | None = None
449 node = expr.parent
450 while (
451 node is not None
452 and node is not constraint_stmt
453 and not node.parent_of(constraint_stmt)
454 ):
455 if isinstance(node, (nodes.For, nodes.While)):
456 end = node
457 node = node.parent
458 if end is None:
459 return (expr.lineno, expr.col_offset)
460 return (end.end_lineno, end.end_col_offset)
463_preceding_guards_cache: dict[
464 nodes.NodeNG, dict[str, tuple[nodes.If | nodes.Assert, ...]]
465] = {}
466"""The asserts and ifs preceding each statement in its block, by the names and
467attribute names their test reads.
469They do not depend on the constrained name, so they are computed once per block.
470"""
473def clear_preceding_guards_cache() -> None:
474 """Clear the cache of the guard statements preceding each statement."""
475 _preceding_guards_cache.clear()
478def _add_guards_constraints(
479 expr: _NameNodes,
480 guards: tuple[nodes.If | nodes.Assert, ...],
481 constraints_mapping: dict[nodes.NodeNG, set[Constraint]],
482) -> None:
483 """Add the constraints of guards for expr.
485 After an assert, its test holds. After an if, its test is false for a value
486 assigned before it, if its body cannot let that value through: the body exits,
487 or it assigns expr again.
488 """
489 for guard in guards:
490 is_if = isinstance(guard, nodes.If)
491 constraints = set(_match_constraint(expr, guard.test, invert=is_if))
492 if constraints and not (is_if and _lets_through(guard.body, expr)):
493 constraints_mapping[guard] = constraints
496def _lets_through(body: list[nodes.NodeNG], expr: _NameNodes) -> bool:
497 """Return True if a value of expr assigned before body can reach the code
498 after it.
499 """
500 if isinstance(body[-1], (nodes.Return, nodes.Raise, nodes.Continue, nodes.Break)):
501 return False
502 for stmt in body:
503 if isinstance(stmt, nodes.Assign):
504 targets = stmt.targets
505 elif isinstance(stmt, nodes.AnnAssign) and stmt.value is not None:
506 targets = [stmt.target]
507 else:
508 continue
509 if any(_same_target(target, expr) for target in targets):
510 return False
511 return True
514def _preceding_guards(
515 stmt: nodes.NodeNG,
516) -> dict[str, tuple[nodes.If | nodes.Assert, ...]]:
517 """Return the asserts and ifs preceding stmt in its block, by the names and
518 attribute names their test reads: a test that does not read a name cannot
519 constrain it.
520 """
521 if (cached := _preceding_guards_cache.get(stmt)) is not None:
522 return cached
523 try:
524 stmts = stmt.parent.child_sequence(stmt)
525 except AstroidError:
526 # A type comment annotation is not a child of its parent.
527 stmts = [stmt]
528 # Fill the cache for the whole block at once. Statements between two guards
529 # share the same mapping.
530 guards: dict[str, tuple[nodes.If | nodes.Assert, ...]] = {}
531 for sibling in stmts:
532 _preceding_guards_cache[sibling] = guards
533 if isinstance(sibling, (nodes.If, nodes.Assert)):
534 guards = guards.copy()
535 for name in _read_names(sibling.test):
536 guards[name] = (*guards.get(name, ()), sibling)
537 return _preceding_guards_cache[stmt]
540def _read_names(test: nodes.NodeNG) -> set[str]:
541 """Return the names and attribute names that test reads."""
542 return {
543 node.name if isinstance(node, nodes.Name) else node.attrname
544 for node in test.nodes_of_class((nodes.Name, nodes.Attribute))
545 }
548def _same_target(target: nodes.NodeNG, expr: _NameNodes) -> bool:
549 """Return True if target assigns the name or attribute that expr reads."""
550 if isinstance(target, nodes.AssignName) and isinstance(expr, nodes.Name):
551 return target.name == expr.name
552 if isinstance(target, nodes.AssignAttr) and isinstance(expr, nodes.Attribute):
553 return target.attrname == expr.attrname and _matches(target.expr, expr.expr)
554 return False
557def _add_ifs_constraints(
558 expr: _NameNodes,
559 ifs: list[nodes.NodeNG],
560 constraints_mapping: dict[nodes.NodeNG, set[Constraint]],
561) -> None:
562 """Add the constraints matching each comprehension condition in ifs."""
563 for if_expr in ifs:
564 constraints = set(_match_constraint(expr, if_expr))
565 if constraints:
566 constraints_mapping[if_expr] = constraints
569_CONSTRAINTS_BY_NODE_TYPE: dict[type[nodes.NodeNG], tuple[type[Constraint], ...]] = {
570 nodes.Attribute: (BooleanConstraint,),
571 nodes.BoolOp: (_CompoundConstraint,),
572 nodes.Call: (TypeConstraint, CallableConstraint),
573 nodes.Compare: (NoneConstraint, EqualityConstraint),
574 nodes.Name: (BooleanConstraint,),
575 # No nodes.UnaryOp entry: _match_constraint handles ``not`` itself, by matching
576 # the operand with the inversion flipped, so that any constraint can be negated.
577}
578"""Constraint types that can match each expression node type."""
581def _matches(node1: nodes.NodeNG | bases.Proxy, node2: nodes.NodeNG) -> bool:
582 """Returns True if the two nodes match."""
583 if isinstance(node1, nodes.Name) and isinstance(node2, nodes.Name):
584 return node1.name == node2.name
585 if isinstance(node1, nodes.Attribute) and isinstance(node2, nodes.Attribute):
586 return node1.attrname == node2.attrname and _matches(node1.expr, node2.expr)
587 if isinstance(node1, nodes.Const) and isinstance(node2, nodes.Const):
588 return node1.value == node2.value
590 return False
593def _match_constraint(
594 node: _NameNodes, expr: nodes.NodeNG, invert: bool = False
595) -> Iterator[Constraint]:
596 """Yields all constraint patterns for node that match."""
597 if isinstance(expr, nodes.UnaryOp) and expr.op == "not":
598 yield from _match_constraint(node, expr.operand, not invert)
599 return
600 for constraint_cls in _CONSTRAINTS_BY_NODE_TYPE.get(type(expr), ()):
601 constraint = constraint_cls.match(node, expr, invert)
602 if constraint:
603 yield constraint