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

264 statements  

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 

4 

5"""Classes representing different types of constraints on inference values.""" 

6 

7from __future__ import annotations 

8 

9from abc import ABC, abstractmethod 

10from collections.abc import Iterator 

11from typing import Self 

12 

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 

22 

23_NameNodes = nodes.AssignAttr | nodes.Attribute | nodes.AssignName | nodes.Name 

24 

25 

26class Constraint(ABC): 

27 """Represents a single constraint on a variable.""" 

28 

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".""" 

34 

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. 

42 

43 If negate is True, negate the constraint. 

44 """ 

45 

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.""" 

51 

52 

53class NoneConstraint(Constraint): 

54 """Represents an "is None" or "is not None" constraint.""" 

55 

56 CONST_NONE: nodes.Const = nodes.Const(None) 

57 

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. 

64 

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) 

75 

76 return None 

77 

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 

85 

86 # Return the XOR of self.negate and matches(inferred, self.CONST_NONE) 

87 return self.negate ^ _matches(inferred, self.CONST_NONE) 

88 

89 

90class BooleanConstraint(Constraint): 

91 """Represents an "x" or "not x" constraint.""" 

92 

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. 

98 

99 ``not x`` is matched by ``_match_constraint``, which flips negate. 

100 """ 

101 if _matches(expr, node): 

102 return cls(node=node, negate=negate) 

103 

104 return None 

105 

106 def satisfied_by( 

107 self, inferred: InferenceResult, context: InferenceContext 

108 ) -> bool: 

109 """Return True for uninferable results, or depending on negate flag: 

110 

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 

117 

118 return self.negate ^ inferred_booleaness 

119 

120 

121class TypeConstraint(Constraint): 

122 """Represents an "isinstance(x, y)" constraint.""" 

123 

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 

129 

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) 

146 

147 return None 

148 

149 def satisfied_by( 

150 self, inferred: InferenceResult, context: InferenceContext 

151 ) -> bool: 

152 """Return True for uninferable results, or depending on negate flag: 

153 

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 

159 

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) 

169 

170 if matches_checked_types is util.Uninferable: 

171 return True 

172 

173 return self.negate ^ matches_checked_types 

174 except (InferenceError, AstroidTypeError, MroError): 

175 return True 

176 

177 

178class CallableConstraint(Constraint): 

179 """Represents a "callable(x)" constraint.""" 

180 

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) 

197 

198 return None 

199 

200 def satisfied_by( 

201 self, inferred: InferenceResult, context: InferenceContext 

202 ) -> bool: 

203 """Return True for uninferable results, or depending on negate flag: 

204 

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 

210 

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 

216 

217 return self.negate ^ inferred.callable() 

218 

219 

220class EqualityConstraint(Constraint): 

221 """Represents a "==" or "!=" constraint.""" 

222 

223 def __init__(self, node: nodes.NodeNG, operand: nodes.NodeNG, negate: bool) -> None: 

224 super().__init__(node=node, negate=negate) 

225 self.operand = operand 

226 

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: 

232 

233 - "node == operand" or "operand == node": use given negate value 

234 - "node != operand" or "operand != node": flip negate value 

235 

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) 

242 

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) 

247 

248 return None 

249 

250 def satisfied_by( 

251 self, inferred: InferenceResult, context: InferenceContext 

252 ) -> bool: 

253 """Return True for uninferable/ambiguous results, or depending on negate flag: 

254 

255 - negate=False: satisfied when both operands are equal. 

256 - negate=True: satisfied when both operands are not equal. 

257 

258 Only comparisons between constants and callables are supported. 

259 """ 

260 if inferred is util.Uninferable: 

261 return True 

262 

263 operand_inferred = util.safe_infer(self.operand, context) 

264 if operand_inferred is util.Uninferable or operand_inferred is None: 

265 return True 

266 

267 if isinstance(inferred, nodes.Const) and isinstance( 

268 operand_inferred, nodes.Const 

269 ): 

270 return self.negate ^ (inferred.value == operand_inferred.value) 

271 

272 if inferred.callable() and operand_inferred.callable(): 

273 return self.negate ^ (inferred is operand_inferred) 

274 

275 return True 

276 

277 

278class _CompoundConstraint(Constraint): 

279 """Represents an "x and y" or "x or y" constraint.""" 

280 

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 

291 

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. 

298 

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 

304 

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) 

311 

312 return cls(node=node, op=expr.op, children=children, negate=negate) 

313 

314 def satisfied_by( 

315 self, inferred: InferenceResult, context: InferenceContext 

316 ) -> bool: 

317 """Return True for uninferable results, or depending on op and negate: 

318 

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 

324 

325 results = ( 

326 constraint.satisfied_by(inferred, context) for constraint in self.children 

327 ) 

328 

329 strict = (self.op == "and") ^ self.negate 

330 return all(results) if strict else any(results) 

331 

332 

333def get_constraints( 

334 expr: _NameNodes, frame: nodes.LocalsDictNodeNG 

335) -> dict[nodes.NodeNG, set[Constraint]]: 

336 """Returns the constraints for the given expression. 

337 

338 The returned dictionary maps the node where the constraint was generated to the 

339 corresponding constraint(s). 

340 

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 

360 

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) 

369 

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 

378 

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 

411 

412 return constraints_mapping 

413 

414 

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. 

420 

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 

436 

437 

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. 

443 

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) 

461 

462 

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. 

468 

469They do not depend on the constrained name, so they are computed once per block. 

470""" 

471 

472 

473def clear_preceding_guards_cache() -> None: 

474 """Clear the cache of the guard statements preceding each statement.""" 

475 _preceding_guards_cache.clear() 

476 

477 

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. 

484 

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 

494 

495 

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 

512 

513 

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] 

538 

539 

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 } 

546 

547 

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 

555 

556 

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 

567 

568 

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.""" 

579 

580 

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 

589 

590 return False 

591 

592 

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