Support `isinstance` constraints in inference #2846

zenlyj · 2025-10-04T15:35:06Z

Type of Changes

	Type
	🐛 Bug fix
✓	✨ New feature
	🔨 Refactoring
	📜 Docs

Description

These changes implements the constraint interface to add a new constraint - TypeConstraint to improve the accuracy of inference for objects used in type-narrowing guards.

Currently, the implementation only supports the isinstance pattern, but it should be relatively straightforward to extend it to support the negated case (not isinstance) in the future.

To determine whether an object is an instance of the given types, the implementation reuses existing inference mechanism for isinstance in brains.

Refs pylint-dev/pylint#1162
Refs pylint-dev/pylint#4635
Refs pylint-dev/pylint#10469

codecov · 2025-10-04T15:41:29Z

Codecov Report

❌ Patch coverage is 92.30769% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.37%. Comparing base (ab119c2) to head (010503c).

Files with missing lines	Patch %	Lines
astroid/helpers.py	83.33%	2 Missing ⚠️
astroid/constraint.py	96.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2846      +/-   ##
==========================================
+ Coverage   93.35%   93.37%   +0.02%     
==========================================
  Files          92       92              
  Lines       11190    11212      +22     
==========================================
+ Hits        10446    10469      +23     
+ Misses        744      743       -1

Flag	Coverage Δ
linux	`93.23% <92.30%> (+0.02%)`	⬆️
pypy	`93.37% <92.30%> (+0.02%)`	⬆️
windows	`93.35% <92.30%> (+0.02%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
astroid/brain/brain_builtin_inference.py	`92.68% <100.00%> (+0.65%)`	⬆️
astroid/constraint.py	`99.02% <96.00%> (-0.98%)`	⬇️
astroid/helpers.py	`94.44% <83.33%> (-0.89%)`	⬇️

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

zenlyj · 2025-10-04T15:48:41Z

Seems like test coverage is lacking. Shouldn't be an issue to get it up to 100%, but I would like a review first to see if this implementation makes sense.

jacobtylerwalls

Wonderful!

As we do more of these, it would be nice to add a CI step that installs pylint and runs the primer. I had an experiment (work in progress) at jacobtylerwalls#157 and
pylint-dev/pylint@main...jacobtylerwalls:pylint:run-with-custom-astroid. Something for later.

astroid/constraint.py

tests/test_constraint.py

DanielNoord

@jacobtylerwalls Should this be merged for 4.0.0 considering we already released a RC? Feels like a big change to include after a RC.

jacobtylerwalls · 2025-10-04T19:24:43Z

I wondered as well, happy to wait for 4.1. Let's release 4.0 final tomorrow in that case.

DanielNoord · 2025-10-04T19:26:37Z

I wondered as well, happy to wait for 4.1. Let's release 4.0 final tomorrow in that case.

Let's do so, especially as we haven't tested this with pylint yet. 4.0.0 has enough new features already :)

Pierre-Sassoulas

This is neat ! Glad to see that the constraint api is getting some love.

for more information, see https://pre-commit.ci

zenlyj · 2025-10-12T08:35:40Z

astroid/helpers.py

+    except StopIteration as e:
+        raise InferenceError(node=node, context=context) from e
+    # arg2 MUST be a type or a TUPLE of types
+    # for isinstance
+    if isinstance(node_infer, nodes.Tuple):
+        try:
+            class_container = [
+                next(node.infer(context=context)) for node in node_infer.elts
+            ]
+        except StopIteration as e:
+            raise InferenceError(node=node, context=context) from e


The StopIteration handlers are not covered by tests, wondering if it is reasonable to exclude them. From what I understand .infer() already throws InferenceError and we won't get to these blocks?

Isn't it possible for node.infer(context=context) to be inferable but an empty iterable ?

That was what I thought as well, but when we get an empty iterable, this decorator catches StopIteration and raises InferenceError? Not sure if there are cases where this decorator is not used.

astroid/astroid/decorators.py

Lines 75 to 96 in ab119c2

def raise_if_nothing_inferred(

func: Callable[_P, Generator[InferenceResult]],

) -> Callable[_P, Generator[InferenceResult]]:

def inner(*args: _P.args, **kwargs: _P.kwargs) -> Generator[InferenceResult]:

generator = func(*args, **kwargs)

try:

yield next(generator)

except StopIteration as error:

# generator is empty

if error.args:

raise InferenceError(**error.args[0]) from error

raise InferenceError(

"StopIteration raised without any error information."

) from error

except RecursionError as error:

raise InferenceError(

f"RecursionError raised with limit {sys.getrecursionlimit()}."

) from error

yield from generator

return inner

Not sure if there are cases where this decorator is not used.

That worries me also (plugins?)

A pragma to exclude coverage seems reasonable.

zenlyj · 2025-10-12T08:44:23Z

astroid/constraint.py

+            matches_checked_types = helpers.object_isinstance(inferred, types)
+
+            if matches_checked_types is util.Uninferable:
+                return True


This Uninferable check is not covered by tests, it should be unreachable in runtime. I am including it as a safe guard because helpers.object_isinstance() returns bool | Uninferable, but I am also fine with removing it. Thoughts?

Can you share more details about why this is unreachable? I see that we short-circuit if inferred is uninferable, but it wasn't apparent to me why inferring again wouldn't return uninferable.

zenlyj added Enhancement ✨ Improvement to a component inference labels Oct 4, 2025

jacobtylerwalls previously approved these changes Oct 4, 2025

View reviewed changes

astroid/constraint.py Outdated Show resolved Hide resolved

tests/test_constraint.py Show resolved Hide resolved

jacobtylerwalls added this to the 4.0.0 milestone Oct 4, 2025

DanielNoord reviewed Oct 4, 2025

View reviewed changes

Pierre-Sassoulas previously approved these changes Oct 5, 2025

View reviewed changes

Pierre-Sassoulas modified the milestones: 4.0.0, 4.1.0 Oct 5, 2025

Pierre-Sassoulas added the Blocked 🚧 A PR or issue blocked by another PR or issue label Oct 5, 2025

zenlyj and others added 5 commits October 12, 2025 16:19

Implement type constraint

ef43a90

Add tests

5dcb5fa

Add changelog

175bb43

[pre-commit.ci] auto fixes from pre-commit.com hooks

bbb1377

for more information, see https://pre-commit.ci

Use identity checks

8d3f554

zenlyj dismissed stale reviews from Pierre-Sassoulas and jacobtylerwalls via b3b9dd4 October 12, 2025 08:20

zenlyj force-pushed the constraint-type branch from e5217a2 to b3b9dd4 Compare October 12, 2025 08:20

zenlyj commented Oct 12, 2025

View reviewed changes

Add more tests

010503c

zenlyj force-pushed the constraint-type branch from b3b9dd4 to 010503c Compare October 12, 2025 09:37

	def raise_if_nothing_inferred(
	func: Callable[_P, Generator[InferenceResult]],
	) -> Callable[_P, Generator[InferenceResult]]:
	def inner(args: _P.args, *kwargs: _P.kwargs) -> Generator[InferenceResult]:
	generator = func(args, *kwargs)
	try:
	yield next(generator)
	except StopIteration as error:
	# generator is empty
	if error.args:
	raise InferenceError(**error.args[0]) from error
	raise InferenceError(
	"StopIteration raised without any error information."
	) from error
	except RecursionError as error:
	raise InferenceError(
	f"RecursionError raised with limit {sys.getrecursionlimit()}."
	) from error

	yield from generator

	return inner

Uh oh!

Support isinstance constraints in inference #2846

Are you sure you want to change the base?

Support isinstance constraints in inference #2846

Uh oh!

Conversation

zenlyj commented Oct 4, 2025

Type of Changes

Description

Uh oh!

codecov bot commented Oct 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

zenlyj commented Oct 4, 2025

Uh oh!

jacobtylerwalls left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

DanielNoord left a comment

Choose a reason for hiding this comment

Uh oh!

jacobtylerwalls commented Oct 4, 2025

Uh oh!

DanielNoord commented Oct 4, 2025

Uh oh!

Pierre-Sassoulas left a comment

Choose a reason for hiding this comment

Uh oh!

zenlyj Oct 12, 2025

Choose a reason for hiding this comment

Uh oh!

Pierre-Sassoulas Oct 12, 2025

Choose a reason for hiding this comment

Uh oh!

zenlyj Oct 12, 2025

Choose a reason for hiding this comment

Uh oh!

jacobtylerwalls Oct 12, 2025

Choose a reason for hiding this comment

Uh oh!

zenlyj Oct 12, 2025

Choose a reason for hiding this comment

Uh oh!

jacobtylerwalls Oct 12, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Support `isinstance` constraints in inference #2846

Support `isinstance` constraints in inference #2846

codecov bot commented Oct 4, 2025 •

edited

Loading