int | Literal[5] and int | Literal[-5] are redundant for the same reason: int already includes both values.
But in flake8-pyi, a Flake8 plugin for Python type stubs, the Y051 rule used to flag the first expression and silently skip the second.
The problem wasn't with the type rule. It came from how Python represents negative numbers in its abstract syntax tree (AST).
A Warning That Went Missing
Y051 detects Literal types that are redundant in a union with a builtin type.
For example:
from typing import Literal
def example(value: int | Literal[5]) -> None: ...
Since 5 is already an int, Y051 reports:
Y051 "Literal[5]" is redundant in a union with "int"
The same reasoning applies to Literal[-5], but the original implementation didn't report it.
There was another symptom with multiple literal values:
int | Literal[-1, 5]
Before the fix, Y051 reported Literal[5] rather than Literal[-1], even though the negative value appeared first.
The issue affects flake8-pyi 26.5.0, the latest PyPI release as of November 20, 2026. The fix was merged on November 14 but has not yet been included in a published release.
How Python Represents -5
You can inspect the syntax tree using Python's built-in ast module:
import ast
for expression in ("5", "-5"):
node = ast.parse(expression, mode="eval").body
print(ast.dump(node))
On Python 3.13, this produces:
Constant(value=5)
UnaryOp(op=USub(), operand=Constant(value=5))
The positive integer is represented by an ast.Constant node. The negative expression is different: an ast.UnaryOp containing a unary minus (USub) applied to a positive integer constant.
In source code, -5 looks like a single negative integer value. In the AST, the minus sign is a separate operation.
This also applies inside Literal[-5]. The subscript expression is an ast.UnaryOp, not an ast.Constant.
Where Y051 Skipped the Negative Value
The Y051 implementation in flake8_pyi/visitor.py examines expressions collected from the Literal members of a union.
Originally, the relevant code was:
for literal in analysis.combined_literal_members:
if not isinstance(literal, ast.Constant):
continue
typ = type(literal.value)
For Literal[5], the check succeeds. The code extracts 5, identifies its type as int, and checks whether int is already present in the union.
For Literal[-5], the node is an ast.UnaryOp, so the loop skips it entirely.
That also explains the diagnostic for int | Literal[-1, 5]. The negative value is skipped, leaving 5 as the first recognized integer literal. Since Y051 reports only the first redundant literal for each builtin type in the union, the warning points to Literal[5].
The fix in PR #561 replaced the original check with structural pattern matching:
match literal:
case ast.Constant(value):
typ = type(value)
case ast.UnaryOp(
op=ast.USub(),
operand=ast.Constant(value=int()),
):
typ = int
case _:
continue
The first case preserves the existing behavior. The second recognizes a unary minus applied directly to an integer constant.
There is no need to evaluate the expression. The AST structure is enough to identify its type for this check.
With the new case, Y051 recognizes -1 before reaching 5, so the diagnostic for int | Literal[-1, 5] now identifies Literal[-1].
Testing the Diagnostic, Not Just the Warning
The upstream regression fixture in tests/union_duplicates.pyi covers several cases:
-
int | Literal[-1]— reportLiteral[-1]. -
Union[Literal[-5], builtins.int]— reportLiteral[-5]. -
int | Literal[-1, 5]— reportLiteral[-1], notLiteral[5]. -
str | Literal[-1]— no Y051 warning.
The first two check that negative integers are recognized with both union syntaxes.
The third is particularly useful. Before the fix, Y051 already reported a warning for that expression, but it identified the wrong literal. A test that checked only for the presence of Y051 would have missed the problem.
The last case makes sure the change doesn't flag every negative integer literal. Literal[-1] isn't redundant in a union with str.
The project's test runner reads the expected diagnostics from comments in its .pyi fixtures and compares them with Flake8's output. This checks both whether a warning appears and which literal it identifies.
Checking the AST Before Writing the Rule
The Y051 type rule didn't need to change. The implementation had simply assumed that every relevant literal would appear as an ast.Constant.
When working with Python's AST, expressions that look similar in source code don't always have similar node structures. It's worth checking those structures directly before deciding which node types a rule should handle.
Top comments (0)