ruff TC007
labelled unknown
Analysis Nemotron 3 Super
Flags PEP 613 explicit type aliases that reference symbols unavailable at runtime due to being imported only within TYPE_CHECKING blocks.
Fix: Wraps the right-hand side of the TypeAlias assignment in double quotes to create a forward reference string, preserving all whitespace and formatting except adding quotes around the expression.
12 hazards
- Changes runtime evaluation: quoted string is not evaluated as an expression, breaking code that inspects the alias via __annotations__ or typing.get_type_hints().
- Alters repr and str output: the alias now shows as a string literal instead of the evaluated type expression.
- Breaks isinstance or issubclass checks if the alias is used at runtime, as strings are not types.
- May cause misinterpretation by static tools expecting evaluated types, leading to false positives/negatives in type checking.
- If the RHS contains a comment, the fix may place quotes incorrectly relative to the comment, altering comment association.
- If the RHS is spread across multiple lines, quoting the entire expression may invalidate syntax if newlines are not handled correctly in string literals.
- If the alias is used in a generic base class like class C(A), quoting breaks class creation as string is not a type.
- If the RHS uses the | operator (Python 3.10+), quoting prevents union type formation at runtime, affecting structural pattern matching.
- If the RHS includes a forward reference already quoted, double-quoting may produce malformed nested quotes or escape issues.
- If the TYPE_CHECKING block is conditionally defined (e.g., inside a function), quoting may mismatch scope of the referenced symbol.
- If the module is executed with typing.TYPE_CHECKING=True at runtime (non-standard), the quoted alias will not resolve to the intended type.
- If the RHS contains a formatted string literal (f-string) or other expression relying on runtime values, quoting prevents its evaluation.
Programs
| id | result | title | hazard |
|---|---|---|---|
| r1-p001 | silent prediction off | keyword-only args + TYPE_CHECKING alias | Forward referencing via quoted alias changes evaluation timing/position of default expressions involving mutable objects; quoted strings delay evaluation until use, while unquoted evaluates at definit |
| r1-p002 | fired, no fix | generic base class with quoted alias breaking type creation | Quoting the RHS of a TypeAlias used as a base class turns it into a string, causing `class C(A)` to fail because strings are not valid types during class creation. |
| r1-p003 | fired, no fix | alias RHS with trailing comment misaligned by quote insertion | When the RHS contains a comment, wrapping it in quotes may place the quote after the comment, breaking syntax or misattributing the comment to the string literal. |
| r1-p004 | fired, no fix | context manager alias used in 'with' statement | If the aliased context manager is quoted, using it in a `with` statement fails because strings lack `__enter__`/`__exit__` methods, even if they have `write()` but not `close()`. |
| r1-p005 | fired, no fix | descriptor relying on unquoted alias for __get__ type resolution | Quoting a TypeAlias used in a descriptor's `__get__` annotation prevents proper type resolution at runtime, altering behavior when the descriptor accesses instance/class state. |
| r1-p006 | silent prediction off | docstring lost due to alias rewrite near commented block | When a TypeAlias is near a comment or docstring, the fix's whitespace preservation may incorrectly associate or detach comments, leading to lost documentation or misleading source structure. |
| r1-p007 | fired, no fix | repr of quoted alias shows string instead of type | The quoted alias appears as a string literal in `repr()` or `str()` output, breaking tools or debugging that rely on seeing the actual type expression rather than a quoted string. |
| r1-p008 | fired, no fix | shadowed built-in 'str' redefined after TYPE_CHECKING alias | If a name like `str` is imported under TYPE_CHECKING and aliased, then later redefined in the module, the quoted alias may refer to the wrong binding or become a stale string reference. |
| r2-p001 | fired, no fix | Multi-line RHS newline handling | If the RHS is spread across multiple lines, quoting the entire expression may invalidate syntax if newlines are not handled correctly in string literals. |
| r2-p002 | fired, no fix | isinstance check broken by string alias | Breaks isinstance or issubclass checks if the alias is used at runtime, as strings are not types. |
| r2-p003 | fired, no fix | Static tool misinterpretation of quoted alias | May cause misinterpretation by static tools expecting evaluated types, leading to false positives/negatives in type checking. |
| r2-p004 | fired, no fix | Interaction with set/dict hashing and equality | dict ordering, duplicate keys, __hash__/__eq__ overrides, sets |
| r2-p005 | fired, no fix | Conditional TYPE_CHECKING scope mismatch | If the TYPE_CHECKING block is conditionally defined (e.g., inside a function), quoting may mismatch scope of the referenced symbol. |
| r2-p006 | silent prediction off | Exception handling interference | exceptions raised inside the rewritten code, finally/else clauses, exception chaining |
| r2-p007 | fired, no fix | Context manager with non-file write()-like object | context managers that are not files, objects with write() but no close() |
| r2-p008 | silent prediction off | F-string RHS evaluation prevented by quoting | If the RHS contains a formatted string literal (f-string) or other expression relying on runtime values, quoting prevents its evaluation. |
Sources
r1-p001 · keyword-only args + TYPE_CHECKING alias
1from typing import TYPE_CHECKING, TypeAlias
2import sys
3if TYPE_CHECKING:
4 from collections import UserList
5class UserList(UserList):
6 pass
7DEFAULT_VAL: TypeAlias = UserList
8@no_type_check
9def func(a, *, b=DEFAULT_VAL()):
10 return len(b)
11try:
12 print(func(1))
13except Exception as e:
14 print(type(e).__name__, e)
15func.__defaults__ = (None,) # reset for second call
16print(func(2))
r1-p002 · generic base class with quoted alias breaking type creation
1from typing import TYPE_CHECKING, TypeAlias
2if TYPE_CHECKING:
3 class Base:
4 pass
5A: TypeAlias = Base
6try:
7 class C(A): # This line triggers TC007
8 pass
9 print('Success:', C.__bases__)
10except Exception as e:
11 print(type(e).__name__, e)
r1-p003 · alias RHS with trailing comment misaligned by quote insertion
1from typing import TYPE_CHECKING, TypeAlias
2if TYPE_CHECKING:
3 X = 42
4Y: TypeAlias = X # value from TYPE_CHECKING
5print('Y equals:', Y)
6# After fix: Y: TypeAlias = "X # value from TYPE_CHECKING" becomes invalid or misparsed
r1-p004 · context manager alias used in 'with' statement
1from typing import TYPE_CHECKING, TypeAlias
2import io
3if TYPE_CHECKING:
4 StringWriter = io.StringIO
5Log: TypeAlias = StringWriter
6try:
7 with Log() as f:
8 f.write('test')
9 print('written:', f.getvalue())
10except Exception as e:
11 print(type(e).__name__, e)
r1-p005 · descriptor relying on unquoted alias for __get__ type resolution
1from typing import TYPE_CHECKING, TypeAlias
2if TYPE_CHECKING:
3 IntVal = int
4Stored: TypeAlias = IntVal
5class IntDescriptor:
6 def __init__(self, value: Stored) -> None:
7 self.value = value
8 def __get__(self, instance, owner):
9 return self.value if instance is None else instance._val
10class A:
11 x = IntDescriptor(5)
12print('Descriptor value:', A().x)
r1-p006 · docstring lost due to alias rewrite near commented block
1from typing import TYPE_CHECKING, TypeAlias
2"""Module docstring."""
3if TYPE_CHECKING:
4 from math import pi
5 TWO_PI: TypeAlias = 2 * pi # constant
6print('Constant value:', TWO_PI)
7# After fix: the inline comment may be wrapped inside quotes, becoming part of the string
r1-p007 · repr of quoted alias shows string instead of type
1from typing import TYPE_CHECKING, TypeAlias
2if TYPE_CHECKING:
3 MyInt = int
4Number: TypeAlias = MyInt
5print('Alias repr:', repr(Number))
6print('Alias str:', str(Number))
7# Expected: <class 'int'> or similar; after fix: "MyInt"
r1-p008 · shadowed built-in 'str' redefined after TYPE_CHECKING alias
1from typing import TYPE_CHECKING, TypeAlias
2if TYPE_CHECKING:
3 from builtins import str as _str
4StrAlias: TypeAlias = _str
5str = lambda x: f'[{x}]' # shadow built-in
6print('StrAlias("hi"):', StrAlias('hi'))
7# After fix: StrAlias becomes "_str", which is not callable
r2-p001 · Multi-line RHS newline handling
1import sys
2from typing import TYPE_CHECKING, TypeAlias
3if TYPE_CHECKING:
4 from collections import deque
5MyAlias: TypeAlias = \
6 deque[int]
7def main():
8 try:
9 x = MyAlias() # This will fail after fix because MyAlias becomes string
10 print('success:', len(x))
11 except Exception as e:
12 print(type(e).__name__, ':', e)
13main()
r2-p002 · isinstance check broken by string alias
1from typing import TYPE_CHECKING, TypeAlias
2if TYPE_CHECKING:
3 class A: ...
4MyType: TypeAlias = A
5obj = object()
6print(isinstance(obj, MyType)) # Before: False, After: TypeError (str vs type)
r2-p003 · Static tool misinterpretation of quoted alias
1from typing import TYPE_CHECKING, TypeAlias
2if TYPE_CHECKING:
3 from typing import List
4AliasIntList: TypeAlias = List[int]
5x: AliasIntList = [1, 2]
6print(len(x)) # Should print 2; if misinterpreted, type checker may complain
r2-p004 · Interaction with set/dict hashing and equality
1from typing import TYPE_CHECKING, TypeAlias
2if TYPE_CHECKING:
3 class HashableObj:
4 def __init__(self, val): self.val = val
5 def __hash__(self): return hash(self.val)
6 def __eq__(self, other): return isinstance(other, HashableObj) and self.val == other.val
7MySetType: TypeAlias = HashableObj
8s = {MySetType(1), MySetType(1)} # Should have size 1
9print(len(s))
r2-p005 · Conditional TYPE_CHECKING scope mismatch
1from typing import TYPE_CHECKING, TypeAlias
2def outer():
3 if TYPE_CHECKING:
4 class Inner: ...
5 LocalAlias: TypeAlias = Inner # Rule should fire here
6 try:
7 x = LocalAlias() # Fails after fix: LocalAlias is string
8 print('created')
9 except Exception as e:
10 print(type(e).__name__, ':', e)
11outer()
r2-p006 · Exception handling interference
1from typing import TYPE_CHECKING, TypeAlias
2if TYPE_CHECKING:
3 def factory() -> int:
4 raise ValueError('bad')
5AliasFactory: TypeAlias = factory()
6try:
7 x = AliasFactory # After fix: x is string "factory()", no call → no exception
8 print('value:', x)
9except ValueError as e:
10 print('caught:', e)
11else:
12 print('no exception')
13finally:
14 print('finally')
r2-p007 · Context manager with non-file write()-like object
1from typing import TYPE_CHECKING, TypeAlias
2if TYPE_CHECKING:
3 class Logger:
4 def write(self, msg): print(f'LOG: {msg}')
5LoggerType: TypeAlias = Logger
6logger = LoggerType() # After fix: logger is string → AttributeError
7try:
8 logger.write('test')
9except AttributeError as e:
10 print(type(e).__name__, ':', e)
r2-p008 · F-string RHS evaluation prevented by quoting
1from typing import TYPE_CHECKING, TypeAlias
2if TYPE_CHECKING:
3 val = 42
4AliasFString: TypeAlias = f"value: {val}"
5print(AliasFString) # Before: 'value: 42', After: 'f"value: {val}"' (literal string)