Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Apply fixes using this priority order (simplest first):
a. Narrow unions with isinstance() / if x is None / hasattr().
This is the primary tool for resolving union-type errors. narrows
through all of these patterns, including the negative forms:
ty
# Narrow X | None โ use `if ...: raise`, never `assert`if x isNone:
raise ValueError("x must not be None")
x.method() # ty knows x is X here# Narrow str | UploadFileifisinstance(field, str):
raise TypeError("Expected file upload, got string")
await field.read() # ty knows field is UploadFile here# Narrow broad union parameters early in a function body# (common for methods accepting e.g. list | dict | BatchEncoding)ifisinstance(encoded_inputs, (list, tuple)):
raise TypeError("Expected a mapping, got sequence")
encoded_inputs.keys() # ty sees only the dict/mapping types now
b. Use local variables to help ty track narrowing across closures.
When self.x is X | None and you need to pass it to nested functions
or closures, ty cannot track that self.x stays non-None. Copy to a
local variable and narrow the local:
manager = self.batching_manager
if manager isNone:
raise RuntimeError("Manager not initialized")
# Use `manager` (not `self.batching_manager`) in nested functions
c. Split chained calls when the intermediate type is a broad union.
If func().method() fails because func() returns a union, split it:
# BAD: ty can't narrow through chained calls
result = func(return_dict=True).to(device)["input_ids"]
# GOOD: split, narrow, then chain
result = func(return_dict=True)
ifnothasattr(result, "to"):
raise TypeError("Expected dict-like result")
inputs = result.to(device)["input_ids"]
d. Fix incorrect type hints at the source. If a parameter is typed X | None
but can never be None when actually called, remove None from the hint.
e. Annotate untyped attributes. Add type annotations to instance variables
set in __init__ or elsewhere (for example self.foo: list[int] = []).
Declare class-level attributes that are set dynamically later
(for example _cache: Cache, _token_tensor: torch.Tensor | None).
f. Use @overload for methods with input-dependent return types.
When a method returns different types based on the input type (e.g.
__getitem__ with str vs int keys), use @overload to declare each
signature separately:
This eliminates cast() calls at usage sites by giving the checker
precise return types for each call pattern.
g. Make container classes generic to propagate value types.
When a class like UserDict holds values whose type changes after
transformation (e.g. lists โ tensors after .to()), make the class
generic so methods can return narrowed types:
from typing importGeneric, overload
from typing_extensions import TypeVar
_V = TypeVar("_V", default=Any) # default=Any keeps existing code workingclassMyDict(UserDict, Generic[_V]):
@overloaddef__getitem__(self, item: str) -> _V: ...
# ...defto(self, device) -> MyDict[torch.Tensor]:
# after .to(), values are tensors
...
returnself# type: ignore[return-value]
The default=Any (from typing_extensions) means unparameterized usage
like MyDict() stays MyDict[Any] โ no existing code needs to change.
Only methods that narrow the value type (like .to()) declare a specific
return type. This eliminates cast() at all call sites.
h. Use self: "ProtocolType" for mixins. When a mixin accesses attributes
from its host class, define a Protocol in src/transformers/_typing.py and
annotate self on methods that need it. Apply this consistently to all methods
in the mixin. Import under TYPE_CHECKING to avoid circular imports.
i. Use TypeGuard functions for dynamic module attributes (for example
torch.npu, torch.xpu, torch.compiler). Instead of getattr(torch, "npu")
or hasattr(torch, "npu") and torch.npu.is_available(), define a type guard
function in src/transformers/_typing.py:
defhas_torch_npu(mod: ModuleType) -> TypeGuard[Any]:
returnhasattr(mod, "npu") and mod.npu.is_available()
Then use it as a narrowing check: if has_torch_npu(torch): torch.npu.device_count().
After the guard, ty treats the module as Any, allowing attribute access without
getattr() or cast(). See existing guards in _typing.py for all device backends.
Key rules for type guards:
Use TypeGuard[Any] (not a Protocol) โ this is the simplest form that works
with ty and avoids losing the original module's known attributes.
The guard function must be called directly in an if condition for narrowing
to work. ty does NOT narrow through and conditions or if not guard: return.
Import guards with from .._typing import has_torch_xxx (not via module
attribute _typing.has_torch_xxx) โ ty only resolves TypeGuard from
direct imports.
j. Use getattr() / setattr() for dynamic model/config attributes.
For runtime-injected fields (for example config/model flags), use
getattr(obj, "field", default) for reads and setattr(obj, "field", value)
for writes. Also use getattr() for third-party packages missing type stubs
(for example getattr(safetensors, "__version__", "unknown")).
Avoid getattr(torch, "npu") style โ use type guards instead (see above).
k. Use cast() as a last resort before # type: ignore.
Use when you've structurally validated the type but the checker can't see it:
pattern-matched AST nodes, known-typed dict values, or validated API responses.
# After structural validation confirms the type:
stmt = cast(cst.Assign, node.body[0])
annotations = cast(list[Annotation], [])
Do not use cast() for module attribute narrowing โ use type guards.
Do not use cast() when @overload or generics can solve it at the source.
l. Use # type: ignore only for third-party stub defects. This means
cases where the third-party package's type stubs are wrong or incomplete
and there is no way to narrow or cast around it. Examples:
A kwarg that exists at runtime but is missing from the stubs
A method that exists but isn't declared in the stubs
Always add the specific error code: # type: ignore[call-arg], not bare
# type: ignore.
Things to never do:
Never use assert for type narrowing. Asserts are stripped by python -O
and must not be relied on for correctness. Use if ...: raise instead.
Never use # type: ignore as a first resort. Exhaust all approaches above first.
Do not use getattr(torch, "backend") to access dynamic device backends
(npu, xpu, hpu, musa, mlu, neuron, compiler) โ use type guards
Do not use cast() for module attribute narrowing โ use type guards
Do not use cast() when @overload or generics can eliminate it at the source
Do not add helper methods or abstractions just to satisfy the type checker
(especially for only 1-2 occurrences)
Do not pollute base classes with domain-specific fields; use Protocols
Do not add if x is not None guards for values guaranteed non-None
by the call chain; fix the annotation instead
Do not use conditional inheritance patterns; annotate self instead
Organization:
Keep shared Protocols and type aliases in src/transformers/_typing.py
Import type-only symbols under if TYPE_CHECKING: to avoid circular deps
Use from __future__ import annotations for PEP 604 syntax (X | Y)
Verify and close the PR loop:
Re-run ty check on the same <target>
Re-run make typing to confirm the type/model-rules step passes
If working toward merge readiness, run make check-repo
Ensure runtime behavior did not change and run relevant tests
Update CI coverage when adding new typed areas:
Update ty_check_dirs in Makefile to include newly type-checked directories.
