fix-future-annotations

A CLI and pre-commit hook to upgrade the typing annotations syntax to PEP 585 and PEP 604.

Upgrade Details

PEP 585 – Type Hinting Generics In Standard Collections

Old	New
typing.Dict[str, int] List[str]	dict[str, int] list[str]

PEP 604 – Allow writing union types as X | Y

Old	New
typing.Union[str, int] Optional[str]	str | int str | None

PEP 563 – Postponed Evaluation of Annotations

Old	New
def create() -> "Foo": pass	def create() -> Foo: pass

Import aliases handling

Old	New
import typing as t from typing import Tuple as MyTuple def foo() -> MyTuple[str, t.Optional[int]]: pass	from __future__ import annotations import typing as t def foo() -> tuple[str, int | None]: pass

Full example

Old	New
from typing import Union, Dict, Optional, Tuple # non-annotation usage will be preserved MyType = Union[str, int] def foo() -> Tuple[Dict[str, int], Optional[str]]: ...	from __future__ import annotations from typing import Union # non-annotation usage will be preserved MyType = Union[str, int] def foo() -> tuple[dict[str, int], str | None]: ...

Unused import names will be removed, and if from __future__ import annotations is not found in the script, it will be automatically added if the new syntax is being used.

Use as a command line tool

python3 -m pip install -U fix-future-annotations

fix-future-annotations my_script.py

Use as pre-commit hook

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

repos:
  - repo: https://github.com/frostming/fix-future-annotations
    rev: 0.5.0  # a released version tag
    hooks:
      - id: fix-future-annotations

Configurations

fix-future-annotations can be configured via pyproject.toml. Here is an example:

[tool.fix_future_annotations]
exclude_files = [  # regex patterns to exclude files
    'tests/.*',
    'docs/.*',
]

exclude_lines = [  # regex patterns to exclude lines
    '# ffa: ignore',   # if a line ends with this comment, the whole *block* will be excluded
    'class .+\(BaseModel\):'  # classes that inherit from `BaseModel` will be excluded
]

License

This work is distributed under MIT license.