Rules

byte-string-type-annotation

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

What it does

Checks for byte-strings in type annotation positions.

Why is this bad?

Static analysis tools like ty can't analyze type annotations that use byte-string notation.

Examples

def test(): -> b"int":
    ...

Use instead:

def test(): -> "int":
    ...

call-non-callable

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

conflicting-argument-forms

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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_singleton

if flag:
    f = repr  # Expects a value
else:
    f = is_singleton  # Expects a type form

f(int)  # error

conflicting-declarations

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

conflicting-metaclass

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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): ...

cyclic-class-definition

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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): ...

cyclic-type-alias-definition

Default level: error · Preview (since 1.0.0) · Related issues · View source

What it does

Checks for type alias definitions that (directly or mutually) refer to themselves.

Why is it bad?

Although it is permitted to define a recursive type alias, it is not meaningful to have a type alias whose expansion can only result in itself, and is therefore not allowed.

Examples

type Itself = Itself

type A = B
type B = A

duplicate-base

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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): ...

duplicate-kw-only

Default level: error · Added in 0.0.1-alpha.12 · Related issues · View source

What it does

Checks for dataclass definitions with more than one field annotated with KW_ONLY.

Why is this bad?

dataclasses.KW_ONLY is a special marker used to emulate the * syntax in normal signatures. It can only be used once per dataclass.

Attempting to annotate two different fields with it will lead to a runtime error.

Examples

from dataclasses import dataclass, KW_ONLY

@dataclass
class A:  # Crash at runtime
    b: int
    _1: KW_ONLY
    c: str
    _2: KW_ONLY
    d: bytes

escape-character-in-forward-annotation

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

TODO #14889

fstring-type-annotation

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

What it does

Checks for f-strings in type annotation positions.

Why is this bad?

Static analysis tools like ty can't analyze type annotations that use f-string notation.

Examples

def test(): -> f"int":
    ...

Use instead:

def test(): -> "int":
    ...

implicit-concatenated-string-type-annotation

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

What it does

Checks for implicit concatenated strings in type annotation positions.

Why is this bad?

Static analysis tools like ty can't analyze type annotations that use implicit concatenated strings.

Examples

def test(): -> "Literal[" "5" "]":
    ...

Use instead:

def test(): -> "Literal[5]":
    ...

inconsistent-mro

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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): ...

index-out-of-bounds

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

instance-layout-conflict

Default level: error · Added in 0.0.1-alpha.12 · Related issues · View source

What it does

Checks for classes definitions which will fail at runtime due to "instance memory layout conflicts".

This error is usually caused by attempting to combine multiple classes that define non-empty __slots__ in a class's Method Resolution Order (MRO), or by attempting to combine multiple builtin classes in a class's MRO.

Why is this bad?

Inheriting from bases with conflicting instance memory layouts will lead to a TypeError at runtime.

An instance memory layout conflict occurs when CPython cannot determine the memory layout instances of a class should have, because the instance memory layout of one of its bases conflicts with the instance memory layout of one or more of its other bases.

For example, if a Python class defines non-empty __slots__, this will impact the memory layout of instances of that class. 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): ...

An instance layout conflict can also be caused by attempting to use multiple inheritance with two builtin classes, due to the way that these classes are implemented in a CPython C extension:

class A(int, float): ...  # TypeError: multiple bases have instance lay-out conflict

Note that pure-Python classes with no __slots__, or pure-Python classes with empty __slots__, are always compatible:

class A: ...
class B:
    __slots__ = ()
class C:
    __slots__ = ("a", "b")

# fine
class D(A, B, C): ...

Known problems

Classes that have "dynamic" definitions of __slots__ (definitions do not consist of string literals, or tuples of string literals) are not currently considered disjoint bases by ty.

Additionally, this check is not exhaustive: many C extensions (including several in the standard library) define classes that use extended memory layouts and thus cannot coexist in a single MRO. Since it is currently not possible to represent this fact in stub files, having a full knowledge of these classes is also impossible. When it comes to classes that do not define __slots__ at the Python level, therefore, ty, currently only hard-codes a number of cases where it knows that a class will produce instances with an atypical memory layout.

Further reading

• CPython documentation: __slots__
• CPython documentation: Method Resolution Order

invalid-argument-type

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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]

invalid-assignment

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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 = ''

invalid-attribute-access

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

invalid-await

Default level: error · Added in 0.0.1-alpha.19 · Related issues · View source

What it does

Checks for await being used with types that are not Awaitable.

Why is this bad?

Such expressions will lead to TypeError being raised at runtime.

Examples

import asyncio

class InvalidAwait:
    def __await__(self) -> int:
        return 5

async def main() -> None:
    await InvalidAwait()  # error: [invalid-await]
    await 42  # error: [invalid-await]

asyncio.run(main())

invalid-base

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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]

invalid-context-manager

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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)

invalid-declaration

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

invalid-exception-caught

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

• Python documentation: except clause
• Python documentation: Built-in Exceptions

Ruff rule

This rule corresponds to Ruff's except-with-non-exception-classes (B030)

invalid-explicit-override

Default level: error · Added in 0.0.1-alpha.28 · Related issues · View source

What it does

Checks for methods that are decorated with @override but do not override any method in a superclass.

Why is this bad?

Decorating a method with @override declares to the type checker that the intention is that it should override a method from a superclass.

Example

from typing import override

class A:
    @override
    def foo(self): ...  # Error raised here

class B(A):
    @override
    def ffooo(self): ...  # Error raised here

class C:
    @override
    def __repr__(self): ...  # fine: overrides `object.__repr__`

class D(A):
    @override
    def foo(self): ...  # fine: overrides `A.foo`

invalid-generic-class

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

• Typing spec: Generics

invalid-key

Default level: error · Added in 0.0.1-alpha.17 · Related issues · View source

What it does

Checks for subscript accesses with invalid keys and TypedDict construction with an unknown key.

Why is this bad?

Subscripting with an invalid key will raise a KeyError at runtime.

Creating a TypedDict with an unknown key is likely a mistake; if the TypedDict is closed=true it also violates the expectations of the type.

Examples

from typing import TypedDict

class Person(TypedDict):
    name: str
    age: int

alice = Person(name="Alice", age=30)
alice["height"]  # KeyError: 'height'

bob: Person = { "name": "Bob", "age": 30 }  # typo!

carol = Person(name="Carol", age=25)  # typo!

invalid-legacy-type-variable

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

• Typing spec: Generics

invalid-metaclass

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

• Python documentation: Metaclasses

invalid-method-override

Default level: error · Added in 0.0.1-alpha.20 · Related issues · View source

What it does

Detects method overrides that violate the Liskov Substitution Principle ("LSP").

The LSP states that an instance of a subtype should be substitutable for an instance of its supertype. Applied to Python, this means: 1. All argument combinations a superclass method accepts must also be accepted by an overriding subclass method. 2. The return type of an overriding subclass method must be a subtype of the return type of the superclass method.

Why is this bad?

Violating the Liskov Substitution Principle will lead to many of ty's assumptions and inferences being incorrect, which will mean that it will fail to catch many possible type errors in your code.

Example

class Super:
    def method(self, x) -> int:
        return 42

class Sub(Super):
    # Liskov violation: `str` is not a subtype of `int`,
    # but the supertype method promises to return an `int`.
    def method(self, x) -> str:  # error: [invalid-override]
        return "foo"

def accepts_super(s: Super) -> int:
    return s.method(x=42)

accepts_super(Sub())  # The result of this call is a string, but ty will infer
                      # it to be an `int` due to the violation of the Liskov Substitution Principle.

class Sub2(Super):
    # Liskov violation: the superclass method can be called with a `x=`
    # keyword argument, but the subclass method does not accept it.
    def method(self, y) -> int:  # error: [invalid-override]
       return 42

accepts_super(Sub2())  # TypeError at runtime: method() got an unexpected keyword argument 'x'
                       # ty cannot catch this error due to the violation of the Liskov Substitution Principle.

Common issues

Why does ty complain about my __eq__ method?

__eq__ and __ne__ methods in Python are generally expected to accept arbitrary objects as their second argument, for example:

class A:
    x: int

    def __eq__(self, other: object) -> bool:
        # gracefully handle an object of an unexpected type
        # without raising an exception
        if not isinstance(other, A):
            return False
        return self.x == other.x

If A.__eq__ here were annotated as only accepting A instances for its second argument, it would imply that you wouldn't be able to use == between instances of A and instances of unrelated classes without an exception possibly being raised. While some classes in Python do indeed behave this way, the strongly held convention is that it should be avoided wherever possible. As part of this check, therefore, ty enforces that __eq__ and __ne__ methods accept object as their second argument.

Why does ty disagree with Ruff about how to write my method?

Ruff has several rules that will encourage you to rename a parameter, or change its type signature, if it thinks you're falling into a certain anti-pattern. For example, Ruff's ARG002 rule recommends that an unused parameter should either be removed or renamed to start with _. Applying either of these suggestions can cause ty to start reporting an invalid-method-override error if the function in question is a method on a subclass that overrides a method on a superclass, and the change would cause the subclass method to no longer accept all argument combinations that the superclass method accepts.

This can usually be resolved by adding @typing.override to your method definition. Ruff knows that a method decorated with @typing.override is intended to override a method by the same name on a superclass, and avoids reporting rules like ARG002 for such methods; it knows that the changes recommended by ARG002 would violate the Liskov Substitution Principle.

Correct use of @override is enforced by ty's invalid-explicit-override rule.

invalid-named-tuple

Default level: error · Added in 0.0.1-alpha.19 · Related issues · View source

What it does

Checks for invalidly defined NamedTuple classes.

Why is this bad?

An invalidly defined NamedTuple class may lead to the type checker drawing incorrect conclusions. It may also lead to TypeErrors at runtime.

Examples

A class definition cannot combine NamedTuple with other base classes in multiple inheritance; doing so raises a TypeError at runtime. The sole exception to this rule is Generic[], which can be used alongside NamedTuple in a class's bases list.

>>> from typing import NamedTuple
>>> class Foo(NamedTuple, object): ...
TypeError: can only inherit from a NamedTuple type and Generic

invalid-newtype

Default level: error · Preview (since 1.0.0) · Related issues · View source

What it does

Checks for the creation of invalid NewTypes

Why is this bad?

There are several requirements that you must follow when creating a NewType.

Examples

from typing import NewType

def get_name() -> str: ...

Foo = NewType("Foo", int)        # okay
Bar = NewType(get_name(), int)   # error: The first argument to `NewType` must be a string literal
Baz = NewType("Baz", int | str)  # error: invalid base for `typing.NewType`

invalid-overload

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

• Python documentation: @overload

invalid-parameter-default

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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 = ''): ...

invalid-paramspec

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

What it does

Checks for the creation of invalid ParamSpecs

Why is this bad?

There are several requirements that you must follow when creating a ParamSpec.

Examples

from typing import ParamSpec

P1 = ParamSpec("P1")  # okay
P2 = ParamSpec("S2")  # error: ParamSpec name must match the variable it's assigned to

References

• Typing spec: ParamSpec

invalid-protocol

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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'>

invalid-raise

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

• Python documentation: The raise statement
• Python documentation: Built-in Exceptions

invalid-return-type

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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]

invalid-super-argument

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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) is True - issubclass(obj, type) is True

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

• Python documentation: super()

invalid-syntax-in-forward-annotation

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

TODO #14889

invalid-type-alias-type

Default level: error · Added in 0.0.1-alpha.6 · Related issues · View source

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

invalid-type-arguments

Default level: error · Added in 0.0.1-alpha.29 · Related issues · View source

What it does

Checks for invalid type arguments in explicit type specialization.

Why is this bad?

Providing the wrong number of type arguments or type arguments that don't satisfy the type variable's bounds or constraints will lead to incorrect type inference and may indicate a misunderstanding of the generic type's interface.

Examples

Using legacy type variables:

from typing import Generic, TypeVar

T1 = TypeVar('T1', int, str)
T2 = TypeVar('T2', bound=int)

class Foo1(Generic[T1]): ...
class Foo2(Generic[T2]): ...

Foo1[bytes]  # error: bytes does not satisfy T1's constraints
Foo2[str]  # error: str does not satisfy T2's bound

Using PEP 695 type variables:

class Foo[T]: ...
class Bar[T, U]: ...

Foo[int, str]  # error: too many arguments
Bar[int]  # error: too few arguments

invalid-type-checking-constant

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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 = ''

invalid-type-form

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

invalid-type-guard-call

Default level: error · Added in 0.0.1-alpha.11 · Related issues · View source

What it does

Checks for type guard function calls without a valid target.

Why is this bad?

The first non-keyword non-variadic argument to a type guard function is its target and must map to a symbol.

Starred (is_str(*a)), literal (is_str(42)) and other non-symbol-like expressions are invalid as narrowing targets.

Examples

from typing import TypeIs

def f(v: object) -> TypeIs[int]: ...

f()  # Error
f(*a)  # Error
f(10)  # Error

invalid-type-guard-definition

Default level: error · Added in 0.0.1-alpha.11 · Related issues · View source

What it does

Checks for type guard functions without a first non-self-like non-keyword-only non-variadic parameter.

Why is this bad?

Type narrowing functions must accept at least one positional argument (non-static methods must accept another in addition to self/cls).

Extra parameters/arguments are allowed but do not affect narrowing.

Examples

from typing import TypeIs

def f() -> TypeIs[int]: ...  # Error, no parameter
def f(*, v: object) -> TypeIs[int]: ...  # Error, no positional arguments allowed
def f(*args: object) -> TypeIs[int]: ... # Error, expect variadic arguments
class C:
    def f(self) -> TypeIs[int]: ...  # Error, only positional argument expected is `self`

invalid-type-variable-constraints

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

missing-argument

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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'

missing-typed-dict-key

Default level: error · Added in 0.0.1-alpha.20 · Related issues · View source

What it does

Detects missing required keys in TypedDict constructor calls.

Why is this bad?

TypedDict requires all non-optional keys to be provided during construction. Missing items can lead to a KeyError at runtime.

Example

from typing import TypedDict

class Person(TypedDict):
    name: str
    age: int

alice: Person = {"name": "Alice"}  # missing required key 'age'

alice["age"]  # KeyError

no-matching-overload

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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]

non-subscriptable

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

not-iterable

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

override-of-final-method

Default level: error · Added in 0.0.1-alpha.29 · Related issues · View source

What it does

Checks for methods on subclasses that override superclass methods decorated with @final.

Why is this bad?

Decorating a method with @final declares to the type checker that it should not be overridden on any subclass.

Example

from typing import final

class A:
    @final
    def foo(self): ...

class B(A):
    def foo(self): ...  # Error raised here

parameter-already-assigned

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

positional-only-parameter-as-kwarg

Default level: error · Added in 0.0.1-alpha.22 · Related issues · View source

What it does

Checks for keyword arguments in calls that match positional-only parameters of the callable.

Why is this bad?

Providing a positional-only parameter as a keyword argument will raise TypeError at runtime.

Example

def f(x: int, /) -> int: ...

f(x=1)  # Error raised here

raw-string-type-annotation

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

What it does

Checks for raw-strings in type annotation positions.

Why is this bad?

Static analysis tools like ty can't analyze type annotations that use raw-string notation.

Examples

def test(): -> r"int":
    ...

Use instead:

def test(): -> "int":
    ...

static-assert-error

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

subclass-of-final-class

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

too-many-positional-arguments

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

type-assertion-failure

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

unavailable-implicit-super-arguments

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

• Python documentation: super()

unknown-argument

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

unresolved-attribute

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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'

unresolved-import

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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'

unresolved-reference

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

unsupported-bool-conversion

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

unsupported-operator

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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'

zero-stepsize-in-slice

Default level: error · Added in 0.0.1-alpha.1 · Related issues · View source

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

ambiguous-protocol-member

Default level: warn · Added in 0.0.1-alpha.20 · Related issues · View source

What it does

Checks for protocol classes with members that will lead to ambiguous interfaces.

Why is this bad?

Assigning to an undeclared variable in a protocol class leads to an ambiguous interface which may lead to the type checker inferring unexpected things. It's recommended to ensure that all members of a protocol class are explicitly declared.

Examples

from typing import Protocol

class BaseProto(Protocol):
    a: int                               # fine (explicitly declared as `int`)
    def method_member(self) -> int: ...  # fine: a method definition using `def` is considered a declaration
    c = "some variable"                  # error: no explicit declaration, leading to ambiguity
    b = method_member                    # error: no explicit declaration, leading to ambiguity

    # error: this creates implicit assignments of `d` and `e` in the protocol class body.
    # Were they really meant to be considered protocol members?
    for d, e in enumerate(range(42)):
        pass

class SubProto(BaseProto, Protocol):
    a = 42  # fine (declared in superclass)

deprecated

Default level: warn · Added in 0.0.1-alpha.16 · Related issues · View source

What it does

Checks for uses of deprecated items

Why is this bad?

Deprecated items should no longer be used.

Examples

@warnings.deprecated("use new_func instead")
def old_func(): ...

old_func()  # emits [deprecated] diagnostic

ignore-comment-unknown-rule

Default level: warn · Added in 0.0.1-alpha.1 · Related issues · View source

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]

invalid-ignore-comment

Default level: warn · Added in 0.0.1-alpha.1 · Related issues · View source

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

possibly-missing-attribute

Default level: warn · Added in 0.0.1-alpha.22 · Related issues · View source

What it does

Checks for possibly missing attributes.

Why is this bad?

Attempting to access a missing attribute will raise an AttributeError at runtime.

Examples

class A:
    if b:
        c = 0

A.c  # AttributeError: type object 'A' has no attribute 'c'

possibly-missing-implicit-call

Default level: warn · Added in 0.0.1-alpha.22 · Related issues · View source

What it does

Checks for implicit calls to possibly missing methods.

Why is this bad?

Expressions such as x[y] and x * y call methods under the hood (__getitem__ and __mul__ respectively). Calling a missing 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

possibly-missing-import

Default level: warn · Added in 0.0.1-alpha.22 · Related issues · View source

What it does

Checks for imports of symbols that may be missing.

Why is this bad?

Importing a missing 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'

redundant-cast

Default level: warn · Added in 0.0.1-alpha.1 · Related issues · View source

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

undefined-reveal

Default level: warn · Added in 0.0.1-alpha.1 · Related issues · View source

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

unresolved-global

Default level: warn · Added in 0.0.1-alpha.15 · Related issues · View source

What it does

Detects variables declared as global in an inner scope that have no explicit bindings or declarations in the global scope.

Why is this bad?

Function bodies with global statements can run in any order (or not at all), which makes it hard for static analysis tools to infer the types of globals without explicit definitions or declarations.

Example

def f():
    global x  # unresolved global
    x = 42

def g():
    print(x)  # unresolved reference

Use instead:

x: int

def f():
    global x
    x = 42

def g():
    print(x)

Or:

x: int | None = None

def f():
    global x
    x = 42

def g():
    print(x)

unsupported-base

Default level: warn · Added in 0.0.1-alpha.7 · Related issues · View source

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]

useless-overload-body

Default level: warn · Added in 0.0.1-alpha.22 · Related issues · View source

What it does

Checks for various @overload-decorated functions that have non-stub bodies.

Why is this bad?

Functions decorated with @overload are ignored at runtime; they are overridden by the implementation function that follows the series of overloads. While it is not illegal to provide a body for an @overload-decorated function, it may indicate a misunderstanding of how the @overload decorator works.

Example

from typing import overload

@overload
def foo(x: int) -> int:
    return x + 1  # will never be executed

@overload
def foo(x: str) -> str:
    return "Oh no, got a string"  # will never be executed

def foo(x: int | str) -> int | str:
    raise Exception("unexpected type encountered")

Use instead:

from typing import assert_never, overload

@overload
def foo(x: int) -> int: ...

@overload
def foo(x: str) -> str: ...

def foo(x: int | str) -> int | str:
    if isinstance(x, int):
        return x + 1
    elif isinstance(x, str):
        return "Oh no, got a string"
    else:
        assert_never(x)

References

• Python documentation: @overload

division-by-zero

Default level: ignore · Preview (since 0.0.1-alpha.1) · Related issues · View source

What it does

It detects division by zero.

Why is this bad?

Dividing by zero raises a ZeroDivisionError at runtime.

Examples

5 / 0

possibly-unresolved-reference

Default level: ignore · Added in 0.0.1-alpha.1 · Related issues · View source

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

unused-ignore-comment

Default level: ignore · Added in 0.0.1-alpha.1 · Related issues · View source

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