Defines a flexible union type for data payloads that may be either a mapping or a sequence, commonly used in API request/response bodies.

Specifies the allowed shape of data that functions or methods can accept or return, enabling static type checking and clear API contracts.

When designing functions that accept flexible input such as JSON payloads, configuration objects, or lists of items, and you want to annotate the accepted types for static analysis.

Used in Python codebases that employ type hints, especially in web APIs, data processing pipelines, or configuration parsers where input can be either a dict or a list.

Payload = Union[Dict[str, Any], List[Any]]

Union of two generic container types: Dict with string keys and Any values, and List of Any elements.

Dict[str, Any] List[Any]

• Any Dict List Union typing payload data payloads

• Dict[Any
• Any] List[str] Tuple[Any
• ...] Any

Using bare 'dict' or 'list' without importing from typing (in Python <3.9) Using 'Dict[str, Any]' when keys are not necessarily strings Confusing Union with Optional

Optional[Union[Dict[str, Any], List[Any]]] Union[Dict[str, Any], List[Any], str] Tuple[Dict[str, Any], List[Any]]

Do not confuse with 'Any' alone; using 'Any' loses type safety. Ensure proper imports from typing module for Python <3.9.

• type-alias
• union-type
• generic-types
• typing-hints

The alias conveys intent that the data is a 'payload'—typically transient data sent over a wire or stored temporarily—rather than a generic dict/list.

Communicates to readers and type checkers that the function accepts flexible input shapes, promoting flexibility while retaining some type safety.

Think of a web API payload that can be either a JSON object or a JSON array.

In Python 3.9+, the built-in collections.abc types can be subscripted directly, allowing 'dict' and 'list' instead of 'Dict' and 'List'.

Consider using TypedDict or Pydantic models for more structured payload validation.