Type Hints for Python (Backport)

Warnings

• gotcha Installing the `typing` PyPI package on Python 3.5 or later has *no effect* because the standard library `typing` module takes precedence. In some scenarios (e.g., `pip install -t . typing`), it can even cause `AttributeError` by shadowing the standard library module.
  Fix: For Python 3.5+, do not install the `typing` PyPI package. Rely on the built-in `typing` module. For libraries supporting older Pythons, use conditional installation (`pip install "typing; python_version < '3.5'"`).
• deprecated For built-in generic types like `list`, `dict`, `set`, and `tuple`, using their `typing` module counterparts (e.g., `typing.List`, `typing.Dict`) is deprecated since Python 3.9.
  Fix: Use the built-in generics directly, e.g., `list[str]` instead of `typing.List[str]`, and `dict[str, int]` instead of `typing.Dict[str, int]`.
• gotcha Type hints are primarily for static analysis tools (type checkers like MyPy, IDEs) and are *not* enforced by the Python runtime by default. Incorrect type hints will not cause runtime errors but will be flagged by static analyzers.
  Fix: Integrate a static type checker into your development workflow (e.g., MyPy, Pyright) to leverage the benefits of type hints.
• deprecated `typing.Callable` is deprecated for runtime type checking in some contexts. While still commonly used for type annotations, `collections.abc.Callable` may be preferred for runtime checks where strict compatibility is desired, or when working with `isinstance` checks.
  Fix: Consider using `collections.abc.Callable` for runtime checks. For annotations, `typing.Callable` remains broadly understood but be aware of the shift.
• breaking `typing.NewType` changed from a function to a class in Python 3.10, which introduced a slight runtime overhead. This change was reverted in Python 3.11, restoring performance to Python 3.9 levels. Code relying on the exact type or performance of `NewType` instantiation in 3.10 could be affected.
  Fix: Upgrade to Python 3.11+ if `NewType` performance or its class-based nature in 3.10 is an issue.
• gotcha Relying on internal `typing` module attributes (e.g., `__union_params__`) prior to Python 3.8 was risky due to the module's provisional status and led to breaking changes. Public APIs like `get_args()` were introduced to provide stable access.
  Fix: Avoid using undocumented internal attributes of the `typing` module. Use stable public APIs like `typing.get_args()` and `typing.get_origin()` when inspecting types at runtime.

Install

• pip install typing Install for Python < 3.5
• pip install "typing; python_version < '3.5'" Conditional install (recommended for library authors)

Imports

• List

  from typing import List

  While built-in generics (list[int]) are preferred in Python 3.9+, using `typing.List` is correct for broader compatibility (Python 3.5-3.8 and the backport package). `collections.abc.List` is a runtime type, not typically used for type hints directly.
• Dict

  from typing import Dict

  Same reasoning as List.
• Optional

  from typing import Optional

• Union

  from typing import Union

• Callable

  from typing import Callable

  For type hints, `typing.Callable` is standard. `collections.abc.Callable` is for runtime checks, but `typing.Callable` itself is deprecated in favor of `collections.abc.Callable` in some contexts for runtime checking if strict runtime compatibility is needed. However, for type hint *annotations*, `typing.Callable` is typically what's imported.
• Any

  from typing import Any

Quickstart

This quickstart demonstrates basic type hinting using common constructs from the `typing` module, including type annotations for variables, function parameters, and return values. It also shows the use of `List`, `Optional`, and `Union` types for more complex scenarios. The `from __future__ import annotations` import is recommended for broader compatibility and allows for 'postponed evaluation' of type annotations.

from __future__ import annotations # For Python < 3.9, enables future syntax for type hints
from typing import List, Union, Optional

def greet(name: str) -> str:
    return f"Hello, {name}!"

def get_item(items: List[str], index: int) -> Optional[str]:
    if 0 <= index < len(items):
        return items[index]
    return None

def process_value(value: Union[int, str]) -> str:
    if isinstance(value, int):
        return f"Received an integer: {value}"
    return f"Received a string: {value}"

print(greet("Alice"))
print(get_item(["apple", "banana"], 0))
print(get_item(["apple", "banana"], 2))
print(process_value(123))
print(process_value("hello"))