add-or-fix-type-checking

Add Or Fix Type Checking

Input

• <target>: module or directory to type-check (if known).
• Optional make typing or CI output showing typing failures.

Workflow

1. Identify scope from the failing run:

   • If you already have make typing or CI output, extract the failing file/module paths.
   • If not, run:

     make typing
     

   • Choose the narrowest target that covers the failures.

2. Run ty check for the target to get a focused baseline:

   ty check --respect-ignore-files --exclude '**/*_pb*' <target>
   

3. Triage errors by category before fixing anything:

   • Wrong/missing type annotations on signatures
   • Attribute access on union types (for example X | None)
   • Functions returning broad unions (for example str | list | BatchEncoding)
   • Mixin/protocol self-type issues
   • Dynamic attributes on objects or modules
   • Third-party stub gaps (missing kwargs, missing __version__, etc.)

4. 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. ty narrows through all of these patterns, including the negative forms:

   # Narrow X | None — use `if ...: raise`, never `assert`
   if x is None:
       raise ValueError("x must not be None")
   x.method()  # ty knows x is X here
   
   # Narrow str | UploadFile
   if isinstance(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)
   if isinstance(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 is None:
       raise RuntimeError("Manager not initialized")
   # Use `manager` (not `self.batching_manager`) in nested functions