52 KiB
Generated
Rules
byte-string-type-annotation
Default level: error
detects byte strings in type annotation positions
What it does
Checks for byte-strings in type annotation positions.
Why is this bad?
Static analysis tools like ty can't analyse type annotations that use byte-string notation.
Examples
def test(): -> b"int":
...
Use instead:
def test(): -> "int":
...
Links
call-non-callable
Default level: error
detects calls to non-callable objects
What it does
Checks for calls to non-callable objects.
Why is this bad?
Calling a non-callable object will raise a TypeError at runtime.
Examples
4() # TypeError: 'int' object is not callable
Links
conflicting-argument-forms
Default level: error
detects when an argument is used as both a value and a type form in a call
What it does
Checks whether an argument is used as both a value and a type form in a call.
Why is this bad?
Such calls have confusing semantics and often indicate a logic error.
Examples
from typing import reveal_type
from ty_extensions import is_fully_static
if flag:
f = repr # Expects a value
else:
f = is_fully_static # Expects a type form
f(int) # error
Links
conflicting-declarations
Default level: error
detects conflicting declarations
What it does
Checks whether a variable has been declared as two conflicting types.
Why is this bad
A variable with two conflicting declarations likely indicates a mistake. Moreover, it could lead to incorrect or ill-defined type inference for other code that relies on these variables.
Examples
if b:
a: int
else:
a: str
a = 1
Links
conflicting-metaclass
Default level: error
detects conflicting metaclasses
What it does
Checks for class definitions where the metaclass of the class being created would not be a subclass of the metaclasses of all the class's bases.
Why is it bad?
Such a class definition raises a TypeError at runtime.
Examples
class M1(type): ...
class M2(type): ...
class A(metaclass=M1): ...
class B(metaclass=M2): ...
## TypeError: metaclass conflict
class C(A, B): ...
Links
cyclic-class-definition
Default level: error
detects cyclic class definitions
What it does
Checks for class definitions in stub files that inherit (directly or indirectly) from themselves.
Why is it bad?
Although forward references are natively supported in stub files, inheritance cycles are still disallowed, as it is impossible to resolve a consistent method resolution order for a class that inherits from itself.
Examples
## foo.pyi
class A(B): ...
class B(A): ...
Links
duplicate-base
Default level: error
detects class definitions with duplicate bases
What it does
Checks for class definitions with duplicate bases.
Why is this bad?
Class definitions with duplicate bases raise TypeError at runtime.
Examples
class A: ...
## TypeError: duplicate base class
class B(A, A): ...
Links
escape-character-in-forward-annotation
Default level: error
detects forward type annotations with escape characters
TODO #14889
Links
fstring-type-annotation
Default level: error
detects F-strings in type annotation positions
What it does
Checks for f-strings in type annotation positions.
Why is this bad?
Static analysis tools like ty can't analyse type annotations that use f-string notation.
Examples
def test(): -> f"int":
...
Use instead:
def test(): -> "int":
...
Links
implicit-concatenated-string-type-annotation
Default level: error
detects implicit concatenated strings in type annotations
What it does
Checks for implicit concatenated strings in type annotation positions.
Why is this bad?
Static analysis tools like ty can't analyse type annotations that use implicit concatenated strings.
Examples
def test(): -> "Literal[" "5" "]":
...
Use instead:
def test(): -> "Literal[5]":
...
Links
incompatible-slots
Default level: error
detects class definitions whose MRO has conflicting __slots__
What it does
Checks for classes whose bases define incompatible __slots__.
Why is this bad?
Inheriting from bases with incompatible __slots__s
will lead to a TypeError at runtime.
Classes with no or empty __slots__ are always compatible:
class A: ...
class B:
__slots__ = ()
class C:
__slots__ = ("a", "b")
## fine
class D(A, B, C): ...
Multiple inheritance from more than one different class
defining non-empty __slots__ is not allowed:
class A:
__slots__ = ("a", "b")
class B:
__slots__ = ("a", "b") # Even if the values are the same
## TypeError: multiple bases have instance lay-out conflict
class C(A, B): ...
Known problems
Dynamic (not tuple or string literal) __slots__ are not checked.
Additionally, classes inheriting from built-in classes with implicit layouts
like str or int are also not checked.
>>> hasattr(int, "__slots__")
False
>>> hasattr(str, "__slots__")
False
>>> class A(int, str): ...
Traceback (most recent call last):
File "<python-input-0>", line 1, in <module>
class A(int, str): ...
TypeError: multiple bases have instance lay-out conflict
Links
inconsistent-mro
Default level: error
detects class definitions with an inconsistent MRO
What it does
Checks for classes with an inconsistent method resolution order (MRO).
Why is this bad?
Classes with an inconsistent MRO will raise a TypeError at runtime.
Examples
class A: ...
class B(A): ...
## TypeError: Cannot create a consistent method resolution order
class C(A, B): ...
Links
index-out-of-bounds
Default level: error
detects index out of bounds errors
What it does
Checks for attempts to use an out of bounds index to get an item from a container.
Why is this bad?
Using an out of bounds index will raise an IndexError at runtime.
Examples
t = (0, 1, 2)
t[3] # IndexError: tuple index out of range
Links
invalid-argument-type
Default level: error
detects call arguments whose type is not assignable to the corresponding typed parameter
What it does
Detects call arguments whose type is not assignable to the corresponding typed parameter.
Why is this bad?
Passing an argument of a type the function (or callable object) does not accept violates the expectations of the function author and may cause unexpected runtime errors within the body of the function.
Examples
def func(x: int): ...
func("foo") # error: [invalid-argument-type]
Links
invalid-assignment
Default level: error
detects invalid assignments
What it does
Checks for assignments where the type of the value is not assignable to the type of the assignee.
Why is this bad?
Such assignments break the rules of the type system and weaken a type checker's ability to accurately reason about your code.
Examples
a: int = ''
Links
invalid-attribute-access
Default level: error
Invalid attribute access
What it does
Checks for assignments to class variables from instances and assignments to instance variables from its class.
Why is this bad?
Incorrect assignments break the rules of the type system and weaken a type checker's ability to accurately reason about your code.
Examples
class C:
class_var: ClassVar[int] = 1
instance_var: int
C.class_var = 3 # okay
C().class_var = 3 # error: Cannot assign to class variable
C().instance_var = 3 # okay
C.instance_var = 3 # error: Cannot assign to instance variable
Links
invalid-base
Default level: error
detects class bases that will cause the class definition to raise an exception at runtime
What it does
Checks for class definitions that have bases which are not instances of type.
Why is this bad?
Class definitions with bases like this will lead to TypeError being raised at runtime.
Examples
class A(42): ... # error: [invalid-base]
Links
invalid-context-manager
Default level: error
detects expressions used in with statements that don't implement the context manager protocol
What it does
Checks for expressions used in with statements
that do not implement the context manager protocol.
Why is this bad?
Such a statement will raise TypeError at runtime.
Examples
## TypeError: 'int' object does not support the context manager protocol
with 1:
print(2)
Links
invalid-declaration
Default level: error
detects invalid declarations
What it does
Checks for declarations where the inferred type of an existing symbol is not assignable to its post-hoc declared type.
Why is this bad?
Such declarations break the rules of the type system and weaken a type checker's ability to accurately reason about your code.
Examples
a = 1
a: str
Links
invalid-exception-caught
Default level: error
detects exception handlers that catch classes that do not inherit from BaseException
What it does
Checks for exception handlers that catch non-exception classes.
Why is this bad?
Catching classes that do not inherit from BaseException will raise a TypeError at runtime.
Example
try:
1 / 0
except 1:
...
Use instead:
try:
1 / 0
except ZeroDivisionError:
...
References
Ruff rule
This rule corresponds to Ruff's except-with-non-exception-classes (B030)
Links
invalid-generic-class
Default level: error
detects invalid generic classes
What it does
Checks for the creation of invalid generic classes
Why is this bad?
There are several requirements that you must follow when defining a generic class.
Examples
from typing import Generic, TypeVar
T = TypeVar("T") # okay
## error: class uses both PEP-695 syntax and legacy syntax
class C[U](Generic[T]): ...
References
Links
invalid-legacy-type-variable
Default level: error
detects invalid legacy type variables
What it does
Checks for the creation of invalid legacy TypeVars
Why is this bad?
There are several requirements that you must follow when creating a legacy TypeVar.
Examples
from typing import TypeVar
T = TypeVar("T") # okay
Q = TypeVar("S") # error: TypeVar name must match the variable it's assigned to
T = TypeVar("T") # error: TypeVars should not be redefined
## error: TypeVar must be immediately assigned to a variable
def f(t: TypeVar("U")): ...
References
Links
invalid-metaclass
Default level: error
detects invalid metaclass= arguments
What it does
Checks for arguments to metaclass= that are invalid.
Why is this bad?
Python allows arbitrary expressions to be used as the argument to metaclass=.
These expressions, however, need to be callable and accept the same arguments
as type.__new__.
Example
def f(): ...
## TypeError: f() takes 0 positional arguments but 3 were given
class B(metaclass=f): ...
References
Links
invalid-overload
Default level: error
detects invalid @overload usages
What it does
Checks for various invalid @overload usages.
Why is this bad?
The @overload decorator is used to define functions and methods that accepts different
combinations of arguments and return different types based on the arguments passed. This is
mainly beneficial for type checkers. But, if the @overload usage is invalid, the type
checker may not be able to provide correct type information.
Example
Defining only one overload:
from typing import overload
@overload
def foo(x: int) -> int: ...
def foo(x: int | None) -> int | None:
return x
Or, not providing an implementation for the overloaded definition:
from typing import overload
@overload
def foo() -> None: ...
@overload
def foo(x: int) -> int: ...
References
Links
invalid-parameter-default
Default level: error
detects default values that can't be assigned to the parameter's annotated type
What it does
Checks for default values that can't be assigned to the parameter's annotated type.
Why is this bad?
This breaks the rules of the type system and weakens a type checker's ability to accurately reason about your code.
Examples
def f(a: int = ''): ...
Links
invalid-protocol
Default level: error
detects invalid protocol class definitions
What it does
Checks for protocol classes that will raise TypeError at runtime.
Why is this bad?
An invalidly defined protocol class may lead to the type checker inferring
unexpected things. It may also lead to TypeErrors at runtime.
Examples
A Protocol class cannot inherit from a non-Protocol class;
this raises a TypeError at runtime:
>>> from typing import Protocol
>>> class Foo(int, Protocol): ...
...
Traceback (most recent call last):
File "<python-input-1>", line 1, in <module>
class Foo(int, Protocol): ...
TypeError: Protocols can only inherit from other protocols, got <class 'int'>
Links
invalid-raise
Default level: error
detects raise statements that raise invalid exceptions or use invalid causes
Checks for raise statements that raise non-exceptions or use invalid
causes for their raised exceptions.
Why is this bad?
Only subclasses or instances of BaseException can be raised.
For an exception's cause, the same rules apply, except that None is also
permitted. Violating these rules results in a TypeError at runtime.
Examples
def f():
try:
something()
except NameError:
raise "oops!" from f
def g():
raise NotImplemented from 42
Use instead:
def f():
try:
something()
except NameError as e:
raise RuntimeError("oops!") from e
def g():
raise NotImplementedError from None
References
Links
invalid-return-type
Default level: error
detects returned values that can't be assigned to the function's annotated return type
What it does
Detects returned values that can't be assigned to the function's annotated return type.
Why is this bad?
Returning an object of a type incompatible with the annotated return type may cause confusion to the user calling the function.
Examples
def func() -> int:
return "a" # error: [invalid-return-type]
Links
invalid-super-argument
Default level: error
detects invalid arguments for super()
What it does
Detects super() calls where:
- the first argument is not a valid class literal, or
- the second argument is not an instance or subclass of the first argument.
Why is this bad?
super(type, obj) expects:
- the first argument to be a class,
- and the second argument to satisfy one of the following:
isinstance(obj, type)isTrueissubclass(obj, type)isTrue
Violating this relationship will raise a TypeError at runtime.
Examples
class A:
...
class B(A):
...
super(A, B()) # it's okay! `A` satisfies `isinstance(B(), A)`
super(A(), B()) # error: `A()` is not a class
super(B, A()) # error: `A()` does not satisfy `isinstance(A(), B)`
super(B, A) # error: `A` does not satisfy `issubclass(A, B)`
References
Links
invalid-syntax-in-forward-annotation
Default level: error
invalid-type-alias-type
Default level: error
detects invalid TypeAliasType definitions
What it does
Checks for the creation of invalid TypeAliasTypes
Why is this bad?
There are several requirements that you must follow when creating a TypeAliasType.
Examples
from typing import TypeAliasType
IntOrStr = TypeAliasType("IntOrStr", int | str) # okay
NewAlias = TypeAliasType(get_name(), int) # error: TypeAliasType name must be a string literal
Links
invalid-type-checking-constant
Default level: error
detects invalid TYPE_CHECKING constant assignments
What it does
Checks for a value other than False assigned to the TYPE_CHECKING variable, or an
annotation not assignable from bool.
Why is this bad?
The name TYPE_CHECKING is reserved for a flag that can be used to provide conditional
code seen only by the type checker, and not at runtime. Normally this flag is imported from
typing or typing_extensions, but it can also be defined locally. If defined locally, it
must be assigned the value False at runtime; the type checker will consider its value to
be True. If annotated, it must be annotated as a type that can accept bool values.
Examples
TYPE_CHECKING: str
TYPE_CHECKING = ''
Links
invalid-type-form
Default level: error
detects invalid type forms
What it does
Checks for expressions that are used as type expressions but cannot validly be interpreted as such.
Why is this bad?
Such expressions cannot be understood by ty. In some cases, they might raise errors at runtime.
Examples
from typing import Annotated
a: type[1] # `1` is not a type
b: Annotated[int] # `Annotated` expects at least two arguments
Links
invalid-type-variable-constraints
Default level: error
detects invalid type variable constraints
What it does
Checks for constrained type variables with only one constraint.
Why is this bad?
A constrained type variable must have at least two constraints.
Examples
from typing import TypeVar
T = TypeVar('T', str) # invalid constrained TypeVar
Use instead:
T = TypeVar('T', str, int) # valid constrained TypeVar
## or
T = TypeVar('T', bound=str) # valid bound TypeVar
Links
missing-argument
Default level: error
detects missing required arguments in a call
What it does
Checks for missing required arguments in a call.
Why is this bad?
Failing to provide a required argument will raise a TypeError at runtime.
Examples
def func(x: int): ...
func() # TypeError: func() missing 1 required positional argument: 'x'
Links
no-matching-overload
Default level: error
detects calls that do not match any overload
What it does
Checks for calls to an overloaded function that do not match any of the overloads.
Why is this bad?
Failing to provide the correct arguments to one of the overloads will raise a TypeError
at runtime.
Examples
@overload
def func(x: int): ...
@overload
def func(x: bool): ...
func("string") # error: [no-matching-overload]
Links
non-subscriptable
Default level: error
detects subscripting objects that do not support subscripting
What it does
Checks for subscripting objects that do not support subscripting.
Why is this bad?
Subscripting an object that does not support it will raise a TypeError at runtime.
Examples
4[1] # TypeError: 'int' object is not subscriptable
Links
not-iterable
Default level: error
detects iteration over an object that is not iterable
What it does
Checks for objects that are not iterable but are used in a context that requires them to be.
Why is this bad?
Iterating over an object that is not iterable will raise a TypeError at runtime.
Examples
for i in 34: # TypeError: 'int' object is not iterable
pass
Links
parameter-already-assigned
Default level: error
detects multiple arguments for the same parameter
What it does
Checks for calls which provide more than one argument for a single parameter.
Why is this bad?
Providing multiple values for a single parameter will raise a TypeError at runtime.
Examples
def f(x: int) -> int: ...
f(1, x=2) # Error raised here
Links
raw-string-type-annotation
Default level: error
detects raw strings in type annotation positions
What it does
Checks for raw-strings in type annotation positions.
Why is this bad?
Static analysis tools like ty can't analyse type annotations that use raw-string notation.
Examples
def test(): -> r"int":
...
Use instead:
def test(): -> "int":
...
Links
static-assert-error
Default level: error
Failed static assertion
What it does
Makes sure that the argument of static_assert is statically known to be true.
Why is this bad?
A static_assert call represents an explicit request from the user
for the type checker to emit an error if the argument cannot be verified
to evaluate to True in a boolean context.
Examples
from ty_extensions import static_assert
static_assert(1 + 1 == 3) # error: evaluates to `False`
static_assert(int(2.0 * 3.0) == 6) # error: does not have a statically known truthiness
Links
subclass-of-final-class
Default level: error
detects subclasses of final classes
What it does
Checks for classes that subclass final classes.
Why is this bad?
Decorating a class with @final declares to the type checker that it should not be subclassed.
Example
from typing import final
@final
class A: ...
class B(A): ... # Error raised here
Links
too-many-positional-arguments
Default level: error
detects calls passing too many positional arguments
What it does
Checks for calls that pass more positional arguments than the callable can accept.
Why is this bad?
Passing too many positional arguments will raise TypeError at runtime.
Example
def f(): ...
f("foo") # Error raised here
Links
type-assertion-failure
Default level: error
detects failed type assertions
What it does
Checks for assert_type() and assert_never() calls where the actual type
is not the same as the asserted type.
Why is this bad?
assert_type() allows confirming the inferred type of a certain value.
Example
def _(x: int):
assert_type(x, int) # fine
assert_type(x, str) # error: Actual type does not match asserted type
Links
unavailable-implicit-super-arguments
Default level: error
detects invalid super() calls where implicit arguments are unavailable.
What it does
Detects invalid super() calls where implicit arguments like the enclosing class or first method argument are unavailable.
Why is this bad?
When super() is used without arguments, Python tries to find two things:
the nearest enclosing class and the first argument of the immediately enclosing function (typically self or cls).
If either of these is missing, the call will fail at runtime with a RuntimeError.
Examples
super() # error: no enclosing class or function found
def func():
super() # error: no enclosing class or first argument exists
class A:
f = super() # error: no enclosing function to provide the first argument
def method(self):
def nested():
super() # error: first argument does not exist in this nested function
lambda: super() # error: first argument does not exist in this lambda
(super() for _ in range(10)) # error: argument is not available in generator expression
super() # okay! both enclosing class and first argument are available
References
Links
unknown-argument
Default level: error
detects unknown keyword arguments in calls
What it does
Checks for keyword arguments in calls that don't match any parameter of the callable.
Why is this bad?
Providing an unknown keyword argument will raise TypeError at runtime.
Example
def f(x: int) -> int: ...
f(x=1, y=2) # Error raised here
Links
unresolved-attribute
Default level: error
detects references to unresolved attributes
What it does
Checks for unresolved attributes.
Why is this bad?
Accessing an unbound attribute will raise an AttributeError at runtime.
An unresolved attribute is not guaranteed to exist from the type alone,
so this could also indicate that the object is not of the type that the user expects.
Examples
class A: ...
A().foo # AttributeError: 'A' object has no attribute 'foo'
Links
unresolved-import
Default level: error
detects unresolved imports
What it does
Checks for import statements for which the module cannot be resolved.
Why is this bad?
Importing a module that cannot be resolved will raise a ModuleNotFoundError
at runtime.
Examples
import foo # ModuleNotFoundError: No module named 'foo'
Links
unresolved-reference
Default level: error
detects references to names that are not defined
What it does
Checks for references to names that are not defined.
Why is this bad?
Using an undefined variable will raise a NameError at runtime.
Example
print(x) # NameError: name 'x' is not defined
Links
unsupported-bool-conversion
Default level: error
detects boolean conversion where the object incorrectly implements __bool__
What it does
Checks for bool conversions where the object doesn't correctly implement __bool__.
Why is this bad?
If an exception is raised when you attempt to evaluate the truthiness of an object, using the object in a boolean context will fail at runtime.
Examples
class NotBoolable:
__bool__ = None
b1 = NotBoolable()
b2 = NotBoolable()
if b1: # exception raised here
pass
b1 and b2 # exception raised here
not b1 # exception raised here
b1 < b2 < b1 # exception raised here
Links
unsupported-operator
Default level: error
detects binary, unary, or comparison expressions where the operands don't support the operator
What it does
Checks for binary expressions, comparisons, and unary expressions where the operands don't support the operator.
Why is this bad?
Attempting to use an unsupported operator will raise a TypeError at
runtime.
Examples
class A: ...
A() + A() # TypeError: unsupported operand type(s) for +: 'A' and 'A'
Links
zero-stepsize-in-slice
Default level: error
detects a slice step size of zero
What it does
Checks for step size 0 in slices.
Why is this bad?
A slice with a step size of zero will raise a ValueError at runtime.
Examples
l = list(range(10))
l[1:10:0] # ValueError: slice step cannot be zero
Links
invalid-ignore-comment
Default level: warn
detects ignore comments that use invalid syntax
What it does
Checks for type: ignore and ty: ignore comments that are syntactically incorrect.
Why is this bad?
A syntactically incorrect ignore comment is probably a mistake and is useless.
Examples
a = 20 / 0 # type: ignoree
Use instead:
a = 20 / 0 # type: ignore
Links
possibly-unbound-attribute
Default level: warn
detects references to possibly unbound attributes
What it does
Checks for possibly unbound attributes.
Why is this bad?
Attempting to access an unbound attribute will raise an AttributeError at runtime.
Examples
class A:
if b:
c = 0
A.c # AttributeError: type object 'A' has no attribute 'c'
Links
possibly-unbound-implicit-call
Default level: warn
detects implicit calls to possibly unbound methods
What it does
Checks for implicit calls to possibly unbound methods.
Why is this bad?
Expressions such as x[y] and x * y call methods
under the hood (__getitem__ and __mul__ respectively).
Calling an unbound method will raise an AttributeError at runtime.
Examples
import datetime
class A:
if datetime.date.today().weekday() != 6:
def __getitem__(self, v): ...
A()[0] # TypeError: 'A' object is not subscriptable
Links
possibly-unbound-import
Default level: warn
detects possibly unbound imports
What it does
Checks for imports of symbols that may be unbound.
Why is this bad?
Importing an unbound module or name will raise a ModuleNotFoundError
or ImportError at runtime.
Examples
## module.py
import datetime
if datetime.date.today().weekday() != 6:
a = 1
## main.py
from module import a # ImportError: cannot import name 'a' from 'module'
Links
redundant-cast
Default level: warn
detects redundant cast calls
What it does
Detects redundant cast calls where the value already has the target type.
Why is this bad?
These casts have no effect and can be removed.
Example
def f() -> int:
return 10
cast(int, f()) # Redundant
Links
undefined-reveal
Default level: warn
detects usages of reveal_type without importing it
What it does
Checks for calls to reveal_type without importing it.
Why is this bad?
Using reveal_type without importing it will raise a NameError at runtime.
Examples
reveal_type(1) # NameError: name 'reveal_type' is not defined
Links
unknown-rule
Default level: warn
detects ty: ignore comments that reference unknown rules
What it does
Checks for ty: ignore[code] where code isn't a known lint rule.
Why is this bad?
A ty: ignore[code] directive with a code that doesn't match
any known rule will not suppress any type errors, and is probably a mistake.
Examples
a = 20 / 0 # ty: ignore[division-by-zer]
Use instead:
a = 20 / 0 # ty: ignore[division-by-zero]
Links
unsupported-base
Default level: warn
detects class bases that are unsupported as ty could not feasibly calculate the class's MRO
What it does
Checks for class definitions that have bases which are unsupported by ty.
Why is this bad?
If a class has a base that is an instance of a complex type such as a union type, ty will not be able to resolve the method resolution order (MRO) for the class. This will lead to an inferior understanding of your codebase and unpredictable type-checking behavior.
Examples
import datetime
class A: ...
class B: ...
if datetime.date.today().weekday() != 6:
C = A
else:
C = B
class D(C): ... # error: [unsupported-base]
Links
division-by-zero
Default level: ignore
detects division by zero
What it does
It detects division by zero.
Why is this bad?
Dividing by zero raises a ZeroDivisionError at runtime.
Examples
5 / 0
Links
possibly-unresolved-reference
Default level: ignore
detects references to possibly undefined names
What it does
Checks for references to names that are possibly not defined.
Why is this bad?
Using an undefined variable will raise a NameError at runtime.
Example
for i in range(0):
x = i
print(x) # NameError: name 'x' is not defined
Links
unused-ignore-comment
Default level: ignore
detects unused type: ignore comments
What it does
Checks for type: ignore or ty: ignore directives that are no longer applicable.
Why is this bad?
A type: ignore directive that no longer matches any diagnostic violations is likely
included by mistake, and should be removed to avoid confusion.
Examples
a = 20 / 2 # ty: ignore[division-by-zero]
Use instead:
a = 20 / 2