Introducción a Tipos en Python

🌐 Traducción por IA y humanos

Esta traducción fue hecha por IA guiada por humanos. 🤝

Podría tener errores al interpretar el significado original, o sonar poco natural, etc. 🤖

Puedes mejorar esta traducción ayudándonos a guiar mejor al LLM de IA.

Versión en inglés

Python tiene soporte para "anotaciones de tipos" opcionales (también llamadas "type hints").

Estas "anotaciones de tipos" o type hints son una sintaxis especial que permite declarar el tipo de una variable.

Al declarar tipos para tus variables, los editores y herramientas te pueden proporcionar un mejor soporte.

Este es solo un tutorial rápido / recordatorio sobre las anotaciones de tipos en Python. Cubre solo lo mínimo necesario para usarlas con FastAPI... que en realidad es muy poco.

FastAPI se basa completamente en estas anotaciones de tipos, dándole muchas ventajas y beneficios.

Pero incluso si nunca usas FastAPI, te beneficiaría aprender un poco sobre ellas.

Nota

Si eres un experto en Python, y ya sabes todo sobre las anotaciones de tipos, salta al siguiente capítulo.

Motivación

Comencemos con un ejemplo simple:

Python 3.10+

def get_full_name(first_name, last_name):
    full_name = first_name.title() + " " + last_name.title()
    return full_name


print(get_full_name("john", "doe"))

Llamar a este programa genera:

John Doe

La función hace lo siguiente:

• Toma un first_name y last_name.
• Convierte la primera letra de cada uno a mayúsculas con title().
• Concatena ambos con un espacio en el medio.

Python 3.10+

def get_full_name(first_name, last_name):
    full_name = first_name.title() + " " + last_name.title()
    return full_name


print(get_full_name("john", "doe"))

Edítalo

Es un programa muy simple.

Pero ahora imagina que lo escribieras desde cero.

En algún momento habrías empezado la definición de la función, tenías los parámetros listos...

Pero luego tienes que llamar "ese método que convierte la primera letra a mayúscula".

¿Era upper? ¿Era uppercase? first_uppercase? capitalize?

Entonces, pruebas con el amigo del viejo programador, el autocompletado del editor.

Escribes el primer parámetro de la función, first_name, luego un punto (.) y luego presionas Ctrl+Espacio para activar el autocompletado.

Pero, tristemente, no obtienes nada útil:

Añadir tipos

Modifiquemos una sola línea de la versión anterior.

Cambiaremos exactamente este fragmento, los parámetros de la función, de:

    first_name, last_name

a:

    first_name: str, last_name: str

Eso es todo.

Esas son las "anotaciones de tipos":

Python 3.10+

def get_full_name(first_name: str, last_name: str):
    full_name = first_name.title() + " " + last_name.title()
    return full_name


print(get_full_name("john", "doe"))

Eso no es lo mismo que declarar valores predeterminados como sería con:

    first_name="john", last_name="doe"

Es una cosa diferente.

Estamos usando dos puntos (:), no igualdades (=).

Y agregar anotaciones de tipos normalmente no cambia lo que sucede de lo que ocurriría sin ellas.

Pero ahora, imagina que nuevamente estás en medio de la creación de esa función, pero con anotaciones de tipos.

En el mismo punto, intentas activar el autocompletado con Ctrl+Espacio y ves:

Con eso, puedes desplazarte, viendo las opciones, hasta que encuentres la que "te suene":

Más motivación

Revisa esta función, ya tiene anotaciones de tipos:

Python 3.10+

def get_name_with_age(name: str, age: int):
    name_with_age = name + " is this old: " + age
    return name_with_age

Porque el editor conoce los tipos de las variables, no solo obtienes autocompletado, también obtienes chequeo de errores:

Ahora sabes que debes corregirlo, convertir age a un string con str(age):

Python 3.10+

def get_name_with_age(name: str, age: int):
    name_with_age = name + " is this old: " + str(age)
    return name_with_age

Declaración de tipos

Acabas de ver el lugar principal para declarar anotaciones de tipos. Como parámetros de función.

Este también es el lugar principal donde los utilizarías con FastAPI.

Tipos simples

Puedes declarar todos los tipos estándar de Python, no solo str.

Puedes usar, por ejemplo:

• int
• float
• bool
• bytes

Python 3.10+

def get_items(item_a: str, item_b: int, item_c: float, item_d: bool, item_e: bytes):
    return item_a, item_b, item_c, item_d, item_e

Módulo typing

Para algunos casos adicionales, podrías necesitar importar algunas cosas del módulo typing de la standard library, por ejemplo cuando quieres declarar que algo tiene "cualquier tipo", puedes usar Any de typing:

from typing import Any


def some_function(data: Any):
    print(data)

Tipos genéricos

Algunos tipos pueden tomar "parámetros de tipo" entre corchetes, para definir sus tipos internos, por ejemplo una "lista de strings" se declararía list[str].

Estos tipos que pueden tomar parámetros de tipo se llaman Tipos Genéricos o Genéricos.

Puedes usar los mismos tipos integrados como genéricos (con corchetes y tipos dentro):

• list
• tuple
• set
• dict

Lista

Por ejemplo, vamos a definir una variable para ser una list de str.

Declara la variable, con la misma sintaxis de dos puntos (:).

Como tipo, pon list.

Como la lista es un tipo que contiene algunos tipos internos, los pones entre corchetes:

Python 3.10+

def process_items(items: list[str]):
    for item in items:
        print(item)

Información

Esos tipos internos en los corchetes se denominan "parámetros de tipo".

En este caso, str es el parámetro de tipo pasado a list.

Eso significa: "la variable items es una list, y cada uno de los ítems en esta lista es un str".

Al hacer eso, tu editor puede proporcionar soporte incluso mientras procesa elementos de la lista:

Sin tipos, eso es casi imposible de lograr.

Nota que la variable item es uno de los elementos en la lista items.

Y aún así, el editor sabe que es un str y proporciona soporte para eso.

Tuple y Set

Harías lo mismo para declarar tuples y sets:

Python 3.10+

def process_items(items_t: tuple[int, int, str], items_s: set[bytes]):
    return items_t, items_s

Esto significa:

• La variable items_t es un tuple con 3 ítems, un int, otro int, y un str.
• La variable items_s es un set, y cada uno de sus ítems es del tipo bytes.

Dict

Para definir un dict, pasas 2 parámetros de tipo, separados por comas.

El primer parámetro de tipo es para las claves del dict.

El segundo parámetro de tipo es para los valores del dict:

Python 3.10+

def process_items(prices: dict[str, float]):
    for item_name, item_price in prices.items():
        print(item_name)
        print(item_price)

Esto significa:

• La variable prices es un dict:
  • Las claves de este dict son del tipo str (digamos, el nombre de cada ítem).
  • Los valores de este dict son del tipo float (digamos, el precio de cada ítem).

Union

Puedes declarar que una variable puede ser cualquiera de varios tipos, por ejemplo, un int o un str.

Para definirlo usas la barra vertical (|) para separar ambos tipos.

Esto se llama una "unión", porque la variable puede ser cualquiera en la unión de esos dos conjuntos de tipos.

def process_item(item: int | str):
    print(item)

Esto significa que item podría ser un int o un str.

Posiblemente None

Puedes declarar que un valor podría tener un tipo, como str, pero que también podría ser None.

Python 3.10+

def say_hi(name: str | None = None):
    if name is not None:
        print(f"Hey {name}!")
    else:
        print("Hello World")

Usar str | None en lugar de solo str te permitirá al editor ayudarte a detectar errores donde podrías estar asumiendo que un valor siempre es un str, cuando en realidad también podría ser None.

Clases como tipos

También puedes declarar una clase como el tipo de una variable.

Digamos que tienes una clase Person, con un nombre:

Python 3.10+

class Person:
    def __init__(self, name: str):
        self.name = name


def get_person_name(one_person: Person):
    return one_person.name

Luego puedes declarar una variable para que sea de tipo Person:

Python 3.10+

class Person:
    def __init__(self, name: str):
        self.name = name


def get_person_name(one_person: Person):
    return one_person.name

Y luego, nuevamente, obtienes todo el soporte del editor:

Nota que esto significa "one_person es una instance de la clase Person".

No significa "one_person es la clase llamada Person".

Modelos Pydantic

Pydantic es un paquete de Python para realizar la validación de datos.

Declaras la "forma" de los datos como clases con atributos.

Y cada atributo tiene un tipo.

Entonces creas un instance de esa clase con algunos valores y validará los valores, los convertirá al tipo adecuado (si es el caso) y te dará un objeto con todos los datos.

Y obtienes todo el soporte del editor con ese objeto resultante.

Un ejemplo de la documentación oficial de Pydantic:

Python 3.10+

from datetime import datetime

from pydantic import BaseModel


class User(BaseModel):
    id: int
    name: str = "John Doe"
    signup_ts: datetime | None = None
    friends: list[int] = []


external_data = {
    "id": "123",
    "signup_ts": "2017-06-01 12:22",
    "friends": [1, "2", b"3"],
}
user = User(**external_data)
print(user)
# > User id=123 name='John Doe' signup_ts=datetime.datetime(2017, 6, 1, 12, 22) friends=[1, 2, 3]
print(user.id)
# > 123

Información

Para saber más sobre Pydantic, revisa su documentación.

FastAPI está completamente basado en Pydantic.

Verás mucho más de todo esto en práctica en el Tutorial - Guía del Usuario.

Anotaciones de tipos con metadata

Python también tiene una funcionalidad que permite poner metadata adicional en estas anotaciones de tipos usando Annotated.

Puedes importar Annotated desde typing.

Python 3.10+

from typing import Annotated


def say_hello(name: Annotated[str, "this is just metadata"]) -> str:
    return f"Hello {name}"

Python en sí no hace nada con este Annotated. Y para los editores y otras herramientas, el tipo sigue siendo str.

Pero puedes usar este espacio en Annotated para proporcionar a FastAPI metadata adicional sobre cómo quieres que se comporte tu aplicación.

Lo importante a recordar es que el primer parámetro de tipo que pasas a Annotated es el tipo real. El resto es solo metadata para otras herramientas.

Por ahora, solo necesitas saber que Annotated existe, y que es Python estándar. 😎

Luego verás lo poderoso que puede ser.

Consejo

El hecho de que esto sea Python estándar significa que seguirás obteniendo la mejor experiencia de desarrollador posible en tu editor, con las herramientas que usas para analizar y refactorizar tu código, etc. ✨

Y también que tu código será muy compatible con muchas otras herramientas y paquetes de Python. 🚀

Anotaciones de tipos en FastAPI

FastAPI aprovecha estas anotaciones de tipos para hacer varias cosas.

Con FastAPI declaras parámetros con anotaciones de tipos y obtienes:

• Soporte del editor.
• Chequeo de tipos.

...y FastAPI usa las mismas declaraciones para:

• Definir requerimientos: de parámetros de path de la request, parámetros de query, headers, bodies, dependencias, etc.
• Convertir datos: de la request al tipo requerido.
• Validar datos: provenientes de cada request:
  • Generando errores automáticos devueltos al cliente cuando los datos son inválidos.
• Documentar la API usando OpenAPI:
  • Que luego es usada por las interfaces de documentación interactiva automática.

Todo esto puede sonar abstracto. No te preocupes. Verás todo esto en acción en el Tutorial - Guía del Usuario.

Lo importante es que al usar tipos estándar de Python, en un solo lugar (en lugar de agregar más clases, decoradores, etc.), FastAPI hará gran parte del trabajo por ti.

Información

Si ya revisaste todo el tutorial y volviste para ver más sobre tipos, un buen recurso es la "cheat sheet" de mypy.