Repository navigation
PYI002: Confusing/Unclear error message #27324
Description
Summary
Given a simple stub file, e.g., test.pyi with the following content
import numpy as np
x: object
if np.ma.is_mask(x): ...will result in the following output when running ruff check test.pyi with the new default rules
PYI002 `if` test must be a simple comparison against `sys.platform` or `sys.version_info`
--> test.pyi:4:4
|
3 | x: object
4 | if np.ma.is_mask(x): ...
| ^^^^^^^^^^^^^^^^
|
Found 1 error.
This does not look quite right 😄
Version
ruff 0.16.0
Activity
ntBre commentedon Jul 30, 2026
The diagnostic does seem a bit misleading, but I think the rule is acting as intended. Is this the kind of code that caused the diagnostic in a real project? The rule is just pointing out that type checkers only recognize certain kinds of simple conditionals in stub files, and this is not one of them.
wangenau commentedon Jul 30, 2026
Yes, the code is adapted from https://github.com/numpy/numpy/blob/main/numpy/typing/tests/data/reveal/ma.pyi#L370.
The rule is not activated in their repo, I was just playing around with it.
And now I understand the reasoning of the message.
The error message is indeed confusing, since no
sys.platformorsys.version_infoare in the actual code.But then it might be a false positive from my side 😄
ntBre commentedon Jul 30, 2026
I'm not a typing expert, but it seems pretty unusual to have a full function definition in a stub file since they aren't evaluated at runtime. If you end up activating
PYI002in numpy, this file would likely be a good use for per-file-ignores or another ignore mechanism.Regardless, I wouldn't be opposed to trying to improve the diagnostic. It feels like it's missing some kind of explanatory note about type checkers or at least mentioning stub files.
Avasam commentedon Aug 12, 2026
AFAICT,
if np.ma.is_mask(x): ...does nothing for any type checker, and I don't see why it would (outside of a really, really weird custom mypy plugin).The error message could mention "in stubs".
A helper message could be added to direct the user to simply remove the statement, if no
sys.platformorsys.version_info(or adjacent) is detected at all.unrecognized-version-info-check (PYI003) already handles validating that a version check is supported / in spec.
The same "it's a version check, but an unsupported one" detection could be leveraged to not guide the user to remove the statement in PYI002 if but rather to simplify it.
Or keep it simple with a conditional prose:
jonathandung commentedon Aug 13, 2026
The title should be changed.
[-]`PYI002`: False positive[/-][+]`PYI002`: Confusing/Unclear error message[/+][`flake8-pyi`] Mention stubs in the diagnostic message (`PYI002`) (#2…