autotyping

Autotyping uses heuristics to find annotations. Because it does not model full code flow through a function, it may miss implicit None returns.

Important: Always run a type checker (like mypy or pyright) after running autotyping to verify that the added annotations are correct.

To avoid listing many individual flags, use these shortcuts:

• --safe: Enables transformations that are considered safe: --none-return, --scalar-return, and --annotate-magics.
• --aggressive: Enables all --safe transformations plus riskier ones: --bool-param, --int-param, --float-param, --str-param, --bytes-param, and --annotate-imprecise-magics.

# Example of using the safe shortcut
python -m autotyping --safe /path/to/code

You can install autotyping via pip and run it directly against your codebase using the python -m autotyping command. By default, the tool does nothing unless you provide specific transformation flags. Use the following command structure:

pip install autotyping
python -m autotyping /path/to/my/code

Autotyping is built as a LibCST codemod. To run it via the libcst.tool interface:

1. Ensure you have a .libcst.codemod.yaml file in your project with 'autotyping' in the modules list.
2. Execute the command:

python -m libcst.tool codemod autotyping.AutotypeCommand /path/to/my/code

To automatically add type annotations during the commit process:

1. Install pre-commit:

   pip install pre-commit

2. Add the following configuration to your .pre-commit-config.yaml:

- repos:
  - repo: https://github.com/JelleZijlstra/autotyping
    rev: 24.9.0
    hooks:
      - id: autotyping
        stages: [pre-commit]
        types: [python]
        args: [--safe] # Use --safe, --aggressive, or specific flags

3. Install the hook in your repository:

   pre-commit install

When using --annotate-optional or --annotate-named-param, use the format name:type_path. The type_path can be a simple name or a fully qualified path.

• foo:int -> Annotates foo as int.
• foo:bar.Baz -> Annotates foo as bar.Baz (imports bar.Baz).
• foo:typing.Optional[int] -> Annotates foo with the specific type path.

You can provide a JSON report generated by pyanalyze to AutotypeCommand to apply high-fidelity type suggestions. The command parses the report and applies suggested_type and necessary imports to the corresponding code positions.

To use this, pass the path to the report via the --pyanalyze-report flag. If you want to avoid adding new imports to your files, use the --only-without-imports flag.

When running via python -m autotyping, the command accepts additional arguments defined by AutotypeCommand.add_args(parser). These arguments are passed directly to the AutotypeCommand constructor as keyword arguments.

Note: The positional path argument is handled separately and is used to identify the files to be processed (including stubs).

The AutotypeCommand is a LibCST VisitorBasedCodemodCommand designed to automatically add simple type annotations to Python code. It can infer types from default values, magic methods, return statements, and pyanalyze reports. It also supports manual configuration for specific parameter names and types.

from libcst.codemod import CodemodContext
from autotyping.autotyping import AutotypeCommand

# Assuming you have a CodemodContext and a target file
command = AutotypeCommand(
    context,
    annotate_optional=["foo:bar.Baz"],
    none_return=True,
    safe=True
)
# The command is then used within a LibCST codemod execution flow

You can run autotyping as a module using python -m autotyping. The tool accepts one or more paths as positional arguments and uses AutotypeCommand to perform type transformations.

It leverages LibCST's parallel_exec_transform_with_prettyprint to process files in parallel. The tool will output a summary of successes, skips, failures, and warnings to stderr upon completion.

python -m autotyping <path1> <path2> ...