Compatibility annotations
A codebase still supports older Python versions and uses the typing module’s generic collection syntax.
Python · Type Alias
List
typing.List[T] describes lists containing elements of type T and can be used in type aliases. It is deprecated in current Python documentation; use built-in list[T] for new code.
- Since
- 3.5
How it works
typing.List is the generic form of the built-in list, parameterized with an element type such as List[int]. In current Python, it is retained for compatibility but deprecated; new annotations should use list[int] instead. A type alias assigns that parameterized type to another name for static type checking.
Syntax
typing.List[T]Parameters
| Name | Type | Description |
|---|---|---|
T | type parameter | The single element type contained by the list. |
Returns
A parameterized type used for static annotations; it does not construct a list at runtime.
Key points
typing.List[T]parameterizes the built-in list concept with one element type.- It can describe functions that return lists, such as
List[int]. - A list annotation takes a single element type; use a union inside it when elements may have alternatives.
- Modern Python can define aliases with the
typestatement. - Aliases improve readability when a repeated list type expression is long or domain-specific.
Common mistakes
typing.Listis deprecated; prefer the built-in genericlistfor new annotations.- For function parameters, prefer
SequenceorIterablewhen mutation is not required.
Example: A legacy List alias
from typing import List
UserIds = List[int]
ids: UserIds = [101, 202, 303]
print(ids)Defines a reusable alias for a list of integers and uses it in an annotation.
When to use it
Readable type aliases
A domain-specific name makes a repeated list type easier to read.
List return annotations
A function’s result is specifically a list of one element type.
Interview questions
QWhat does typing.List[int] mean?
List[T] is the generic typing form of list, where T describes the element type. For example, List[int] annotates a list whose elements are integers.
Follow-up: What should modern Python code use instead? Use the built-in generic syntax list[int], because typing.List is deprecated.
QHow does a type alias work?
A type alias gives another name to a type expression, such as UserIds = List[int]. Static type checkers treat the alias as equivalent to the original type.
Follow-up: How can an alias be made explicit? Annotate the assignment with TypeAlias, although current Python documentation recommends the type statement instead.
QWhen should List be used for function arguments?
List is useful for describing list return values, but parameter annotations often benefit from abstract collection types. Sequence or Iterable can express that callers need only those operations rather than a concrete mutable list.
Follow-up: When is list[T] preferable for a parameter? Use it when the API specifically requires a list, especially when list-specific mutation or behavior is part of the contract.
Related
listSequenceIterableTypeAliasTypeAliasType