Typing Stubs for typed-ast

Common errors

• ModuleNotFoundError: No module named 'types_typed_ast'

  cause Attempting to import the stub package directly at runtime.
  fix You should import from the actual library `typed_ast`, not the stub package `types_typed_ast`. Stubs are for type checkers, not runtime imports.

• error: Cannot find module named 'typed_ast' [attr-defined]

  cause The runtime library `typed-ast` is not installed, or the type checker (e.g., MyPy) cannot locate it.
  fix Install the runtime library: `pip install typed-ast`. Also, ensure `mypy` is installed if using it for type checking.

• error: Missing type annotations for 'parse' in module 'typed_ast.ast3' [no-untyped-def]

  cause MyPy or another type checker is not correctly picking up the `types-typed-ast` stubs, or they are missing/outdated for the specific `typed-ast` version.
  fix Verify `types-typed-ast` is installed: `pip show types-typed-ast`. Update both `typed-ast` and `types-typed-ast` to their latest compatible versions. Ensure MyPy is configured to check installed stubs (which it typically does by default).

Warnings

• gotcha Stub packages like `types-typed-ast` provide *only* type information and are not intended for direct import or runtime execution. Attempting to `import types_typed_ast` will result in a `ModuleNotFoundError`.
  Fix: Always import symbols from the *runtime library* (`typed-ast`), not the stub package. The stub package is consumed implicitly by type checkers like MyPy.
• gotcha For `types-typed-ast` to be effective, the actual runtime library `typed-ast` must also be installed. The stubs don't provide the implementation, only the type signatures.
  Fix: Ensure both `pip install typed-ast` and `pip install types-typed-ast` are executed. `typed-ast` for runtime, `types-typed-ast` for type checking.
• gotcha Version compatibility between stub packages and their corresponding runtime libraries can be an issue. Stubs are generated for specific versions of the runtime, and mismatches can lead to incorrect type checking results or missing definitions.
  Fix: When encountering unexpected type errors, ensure your `types-typed-ast` version is compatible with your `typed-ast` version. Consult the `typeshed` repository or `typed-ast` documentation for compatibility notes. Upgrading both packages might resolve the issue.

Install

• pip install types-typed-ast Install stubs
• pip install typed-ast mypy Install runtime + type checker

Imports

• AST
  wrong:

  from types_typed_ast import AST

  correct:

  from typed_ast.ast3 import AST

  Stub packages like `types-typed-ast` are not meant for runtime import. You import symbols from the *actual* library (`typed-ast`), and the type checker uses the stubs implicitly.
• parse
  wrong:

  import types_typed_ast; types_typed_ast.parse(...)

  correct:

  import typed_ast.ast3 as typed_ast; typed_ast.parse(...)

  Always import from the runtime library (`typed-ast`), not the stub package (`types-typed-ast`).

Quickstart

This example demonstrates how to use `typed-ast` (the runtime library) and how `types-typed-ast` (the stub package) provides type hints for it. The `mypy` command would use the installed stubs to verify type correctness of `analyze_node`'s arguments and return types without any explicit import of `types-typed-ast`.

import typed_ast.ast3 as typed_ast

def analyze_node(node: typed_ast.AST) -> str:
    """Analyzes an AST node and returns its type name."""
    if isinstance(node, typed_ast.Expr):
        return f"Expression node: {typed_ast.dump(node)}"
    return f"Generic node: {type(node).__name__}"

source_code = "def example_func(a: int, b: int) -> int: return a + b"
parsed_module = typed_ast.parse(source_code, mode='exec')

# This call is type-checked by MyPy using the stubs provided by types-typed-ast
result = analyze_node(parsed_module)
print(result)

# To run type checking, save this as 'my_script.py' and run:
# mypy my_script.py