Opcional, Unión y el Operador |

Las uniones expresan valores que pueden tomar múltiples tipos. La sintaxis X | Y (3.10+) reemplaza Union[X, Y]; los tipos anulables son uniones con None.

Receta

def parse_count(raw: str | None) -> int:
    if raw is None:
        return 0
    return int(raw)
 
def format_id(value: int | str) -> str:
    return str(value)

Cuándo usar esto:

• Al analizar variables de configuración y entorno opcionales
• Funciones que devuelven "valor o ausente"
• Al aceptar múltiples representaciones de entrada
• Al modelar éxito/fracaso sin excepciones

Ejemplo Funcional

from dataclasses import dataclass
 
@dataclass
class User:
    id: int
    email: str | None
 
def email_domain(user: User) -> str | None:
    if user.email is None:
        return None
    return user.email.split("@", 1)[1]
 
def describe(value: int | str | None) -> str:
    match value:
        case None:
            return "ausente"
        case int(n):
            return f"número {n}"
        case str(s):
            return f"texto {s}"
 
def coalesce(*values: str | None) -> str:
    for v in values:
        if v is not None:
            return v
    return ""
 
if __name__ == "__main__":
    print(describe(42))
    print(email_domain(User(1, None)))

Lo que esto demuestra:

• is None / is not None reduce los tipos opcionales para los verificadores
• match/case con patrones tipados refina las uniones
• str | None en argumentos variádicos para cadenas de respaldo
• Devolver None explícitamente en el tipo de retorno

Inmersión Profunda

Cómo Funciona

• Unión - El valor puede ser cualquier tipo miembro; el verificador requiere manejar todos los casos.
• Reducción de tipos (Narrowing) - Los refinamientos del flujo de control reducen la unión a un miembro específico.
• Alias Opcional - Optional[T] significa T | None - todavía válido, | es el estilo preferido.
• Exhaustividad - mypy --strict advierte sobre miembros de unión no manejados en match.
• TypeGuard - Funciones que reducen tipos para los llamadores (avanzado).

Herramientas de Reducción de Tipos

Notas de Python

from typing import TypeGuard
 
def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
    return all(isinstance(x, str) for x in val)

Trampas Comunes

• Comprobación de verdad vs None - if email: trata la cadena vacía como ausente de manera diferente a is None. Solución: Elegir explícitamente la semántica de None o de valor "falsy".
• Uso excesivo de Optional - Todo T | None oscurece los campos requeridos. Solución: Separar campos de modelo requeridos y opcionales.
• Orden de la unión - Generalmente irrelevante; los verificadores los tratan simétricamente.
• Devolver Any desde una rama de unión - Amplía el resultado. Solución: Tipo de retorno consistente por rama.
• null de JSON - Se mapea a None en Python - validar en el límite con Pydantic.

Alternativas

Preguntas Frecuentes

Relacionado

• Fundamentos de las Pistas de Tipo - fundamentos
• Literal, Final y Annotated - uniones precisas
• TypedDict y NamedTuple - claves opcionales
• Flujo de Control - reducción con match

Versiones de la Pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.