Python Source Code Type Hint Style Guide

[krzywon]

Type hinting style guide

Preamble

Python is a dynamically typed programming language, so variables passed to and used in modules and classes may be of any value type at run-time. To minimize issues related to type mismatch, a base type-hinting structure is proposed.

Proposal

Adding type hints

• All new Python is highly recommended to have type hints that match this proposal.
• As existing code is modified, whether a bug is fixed, or a module refactored, the developer making changes should make every effort to ensure that code matches this proposal.

Type hint structure

• In general, all type hints should follow the latest python typing scheme outlined in https://docs.python.org/3/library/typing.html.
• In general, all type hints should be as explicit as necessary to ensure developers can replicate the type(s) allowed by the module.
• Built in types should be used to minimize imports from the typing module, e.g. list instead of from typing import List.
• Types with multiple options should be separated by |, e.g. str | float | int instead of importing Union from the typing module.
• Variables that could be None should include | None as an option instead of using Optional from the typing module.
• User-defined type hints should be after all imports, but before any function, module variable, or class definitions.
• User-defined type hint variable names should be in PascalCase.
• Variables passed to functions and methods should use annotated type hints, e.g. def add(value1: float, value2: float) -> float.
• Return types should always be explicitly defined. In cases where no value is returned, use -> None
• Class variables should be annotated as the variable is defined in the __init__() method, e.g. self.var1: float = 0.0
• Top-level module variables should include type hints of the same style as class variables
• Lists, tuples, dictionaries and other iterable types should use [] to define the object type(s) held within.
  • list[str] suggests a list of strings
  • tuple[int] suggests a tuple of any length, with all elements integers
  • tuple[str, int] suggests a tuple of two items, the first a string and the second an integer
  • dict[str, str | float] suggests a dictionary with all keys as strings and values either a string or a float
• Object types should use the first of the following annotation methods that is applicable:
  • Objects with their own typing scheme should use these typing elements, e.g. numpy.typing.NDArray instead of numpy.ndarray
  • Objects already imported or defined within the module should directly use the Object as the type, e.g. pathlib.Path
  • Objects not imported into the module, or objects that would cause a circular import exception, should be imported within an if typing.TYPE_CHECKING: block and type hints should have the class name surround with quotation marks, e.g. data: "Data1D"

Type hint review process

• During a pull request review, if type hints are missing, the reviewer should add a comment to one line without type hints with a suggested code block on proper type hinting. The lack of type hints should not prevent a pull request that is otherwise ready from being merged.

---

Revision Acceptance Date: February 10, 2026
Revision Number: 1
Original Suggestion: https://github.com/orgs/SasView/discussions/3170