Tipado en Python · DacaCode

Tipado en Python: Estructuras de datos

Dacadev — Tue, 13 Aug 2024 00:00:00 -0500

Tabla de Contenido

Cuando una función recibe datos de un producto, un usuario o una respuesta de una API, el problema no suele ser solamente el tipo de cada valor, sino la forma completa del objeto. Las estructuras de datos tipadas en Python nos permiten documentar y validar mejor esa forma: qué claves existen, cuáles son opcionales y cuándo conviene pasar de un diccionario a una estructura con comportamiento propio.

Note

Este artículo es parte de una serie que explica el tipado en Python. A continuación, puedes ver la recopilación de todos los posts de la serie.

Ver serie

En artículos anteriores vimos cómo agregar tipos a variables, colecciones y funciones. Ahora vamos a llevar esa idea a estructuras que representan datos con significado dentro de una aplicación: productos, órdenes, usuarios, configuraciones o payloads de entrada/salida.

Diccionarios tipados en Python

Los diccionarios son una de las formas más comunes de representar datos en Python. Nos permiten asociar llaves con valores, y esas llaves deben ser objetos hashables, normalmente str, int o tuplas inmutables.

Para agregar tipado a un diccionario podemos usar dict[<tipo_llave>, <tipo_valor>]:

product: dict[str, str | int] = {
 "name": "Camisa",
 "price": 20,
}

En este ejemplo estamos indicando que las llaves son str y que los valores pueden ser str o int. Esto ayuda a evitar errores como usar una llave de tipo incorrecto o asignar un valor fuera del rango esperado.

Sin embargo, esta aproximación tiene una limitación importante: no transmite qué claves se esperan dentro del diccionario. El analizador estático sabe que puede existir cualquier llave str, pero no sabe que esperamos exactamente name y price.

product: dict[str, str | int] = {
 "name": "Camisa",
 "price": 20,
}

product["name"] # ✅ válido
product["category"] # ✅ también parece válido para el type checker

El segundo acceso puede fallar en tiempo de ejecución con un KeyError, pero el tipo dict[str, str | int] no expresa que category no hace parte del contrato de esa estructura.

Info

Un diccionario tipado con dict[str, ...] es útil cuando trabajas con pares clave-valor homogéneos o dinámicos. Cuando necesitas describir una forma específica de datos, conviene usar TypedDict.

TypedDict: diccionarios con forma definida

TypedDict, disponible desde el módulo typing, nos permite definir un diccionario con claves conocidas y valores tipados. Es especialmente útil para payloads JSON, respuestas de APIs o datos que siguen siendo diccionarios, pero tienen una estructura clara.

from typing import TypedDict


class Product(TypedDict):
 name: str
 price: int
 tags: list[str]
 active: bool


product: Product = {
 "name": "Camisa",
 "price": 20,
 "tags": ["ropa"],
 "active": True,
}

Con esta definición, el type checker entiende que Product debe tener las claves name, price, tags y active, y que cada una espera un tipo específico.

Es importante recordar que TypedDict no cambia el comportamiento del diccionario en tiempo de ejecución. Seguimos trabajando con un dict, no con una clase tradicional.

product["name"] # ✅ funciona
product.name # ❌ no funciona

TypedDict mejora la información disponible para herramientas como editores, linters y analizadores estáticos. Pero el acceso sigue siendo por llave, igual que en cualquier diccionario.

Warning

No uses TypedDict esperando validación automática en tiempo de ejecución. Su objetivo principal es mejorar el tipado estático y la documentación del contrato de datos.

Llaves opcionales con NotRequired

En muchos casos una estructura tiene campos obligatorios y campos opcionales. Por ejemplo, un producto puede requerir name, price y active, pero permitir que tags no exista.

Para ese caso podemos usar NotRequired:

from typing import NotRequired, TypedDict


class Product(TypedDict):
 name: str
 price: int
 tags: NotRequired[list[str]]
 active: bool


product_without_tags: Product = {
 "name": "Camisa",
 "price": 20,
 "active": True,
}

La clave tags ahora puede omitirse. Esto es diferente a decir que tags puede ser None. Con NotRequired[list[str]], la llave completa puede no existir.

class Product(TypedDict):
 name: str
 tags: NotRequired[list[str]]


product: Product = {"name": "Camisa"}

product.get("tags") # ✅ acceso seguro si la llave puede no existir
product["tags"] # ⚠️ puede lanzar KeyError en tiempo de ejecución

Tip

Si una llave es opcional, usa get() o valida su existencia antes de acceder con []. El tipado te ayuda a diseñar el contrato, pero no elimina los errores de acceso en tiempo de ejecución.

Enfoque inverso: total=False y Required

También podemos definir el caso contrario: que todas las llaves sean opcionales por defecto y marcar únicamente algunas como obligatorias. Para ello usamos total=False junto con Required.

from typing import Required, TypedDict


class Product(TypedDict, total=False):
 name: Required[str]
 price: Required[int]
 tags: list[str]
 active: bool


product: Product = {
 "name": "Camisa",
 "price": 20,
}

Aquí name y price son obligatorias, mientras que tags y active pueden omitirse. Este enfoque es útil cuando la mayoría de campos son opcionales y solo necesitas destacar unos pocos como requeridos.

La decisión entre NotRequired y total=False + Required depende de la forma dominante de tu estructura:

Usa NotRequired cuando la mayoría de campos son obligatorios.
Usa total=False + Required cuando la mayoría de campos son opcionales.

Dataclass: estructuras de datos con atributos

Una dataclass es una clase diseñada para almacenar datos con menos código repetitivo. Python agregó este decorador en la versión 3.7, y desde entonces se convirtió en una herramienta muy práctica para modelar objetos de datos.

from dataclasses import dataclass


@dataclass
class Product:
 name: str
 price: int
 active: bool
 tags: list[str]


product = Product(name="Camisa", price=20, active=True, tags=["ropa"])

print(product.name)
print(product.price)

A diferencia de TypedDict, aquí sí accedemos a los datos como atributos: product.name, product.price, product.tags. Además, dataclass genera automáticamente métodos como __init__, __repr__ y __eq__, lo que reduce la cantidad de código necesario.

product_1 = Product(name="Camisa", price=20, active=True, tags=["ropa"])
product_2 = Product(name="Camisa", price=20, active=True, tags=["ropa"])

print(product_1 == product_2) # True
print(product_1) # Product(name='Camisa', price=20, active=True, tags=['ropa'])

Info

dataclass sigue siendo una clase de Python. El decorador solo genera código común por ti, sin impedir que agregues métodos, validaciones o comportamiento adicional cuando lo necesites.

Dataclass vs class tradicional

Podemos escribir una clase tradicional para representar el mismo producto:

class Product:
 def __init__(
 self,
 name: str,
 price: int,
 active: bool,
 tags: list[str],
 ) -> None:
 self.name = name
 self.price = price
 self.active = active
 self.tags = tags

El código funciona, pero gran parte de la implementación es repetitiva. Solo estamos recibiendo argumentos y asignándolos como atributos. Con dataclass, expresamos la misma estructura de forma más directa:

from dataclasses import dataclass


@dataclass
class Product:
 name: str
 price: int
 active: bool
 tags: list[str]

La diferencia no es solamente estética. dataclass comunica intención: esta clase existe principalmente para alojar datos. Además, mantiene una buena integración con type hints y reduce el riesgo de inconsistencias entre los argumentos de __init__ y los atributos reales.

También puedes agregar comportamiento cuando haga falta:

from dataclasses import dataclass


@dataclass
class Product:
 name: str
 price: int
 active: bool
 tags: list[str]

 def has_tag(self, tag: str) -> bool:
 return tag in self.tags


product = Product(name="Camisa", price=20, active=True, tags=["ropa"])

print(product.has_tag("ropa")) # True

Tip

Si tu clase solo define __init__, __repr__ o comparaciones básicas para alojar datos, probablemente una dataclass expresa mejor la intención.

Cuándo usar cada estructura de datos

No existe una única estructura correcta para todos los casos. La decisión depende de si estás modelando datos dinámicos, contratos de intercambio o entidades con comportamiento.

flowchart TD
 A[Necesitas representar datos con estructura] --> B{¿Debe seguir siendo un dict?}
 B -- Sí --> C{¿Conoces las claves esperadas?}
 C -- No --> D["Usa dict[str, tipo]"]
 C -- Sí --> E[Usa TypedDict]
 B -- No --> F{¿Principalmente almacena datos?}
 F -- Sí --> G[Usa dataclass]
 F -- No --> H[Usa class tradicional]

Como regla práctica:

dict[str, tipo]: úsalo cuando las claves son dinámicas o la estructura es homogénea. Por ejemplo, contadores, mapas de configuración simples o agrupaciones donde todas las llaves comparten el mismo tipo de valor.
TypedDict: úsalo cuando necesitas conservar el comportamiento de diccionario, pero quieres describir claves específicas. Es una buena opción para JSON, payloads de APIs y datos serializables.
dataclass: úsala cuando quieres representar datos con atributos, comparación automática y una intención clara de modelo de datos. Funciona muy bien para capas internas de dominio o estructuras intermedias.
class tradicional: úsala cuando el objeto necesita controlar invariantes complejas, encapsular estado mutable o exponer comportamiento más importante que los datos que almacena.

La frontera entre dataclass y class tradicional no es rígida. Una dataclass puede tener métodos, y una clase tradicional puede almacenar datos. La clave está en comunicar intención y evitar código accidentalmente complejo.

Warning

No conviertas todo diccionario en dataclass ni todo objeto en TypedDict. Elige la estructura según el contrato que quieres expresar y el comportamiento que necesitas en el sistema.

Cierre

Las estructuras de datos tipadas en Python nos ayudan a hacer explícitos los contratos que antes quedaban implícitos en diccionarios o clases repetitivas. dict[str, ...] funciona para casos homogéneos, TypedDict describe diccionarios con forma específica, NotRequired y Required permiten modelar campos opcionales, y dataclass reduce el código necesario para representar datos con atributos.

Lo importante es usar el tipado como una herramienta de diseño. Cuando la estructura comunica intención, el código se vuelve más fácil de leer, refactorizar y validar antes de llegar a producción.

Note

Esta es la pieza final de la serie hasta el momento. Puedes volver a la recopilación completa para repasar los conceptos anteriores sobre tipado en Python.

Ver serie

Tipado en Python: Tipado de clases

Dacadev — Mon, 12 Aug 2024 00:00:00 -0500

Tabla de Contenido

Cuando un proyecto empieza a tener modelos de dominio, servicios y objetos que se pasan entre capas, el tipado de clases en Python se vuelve una herramienta clave para mantener contratos claros. Ya no se trata solo de saber si una variable es str o int; también necesitamos expresar que un método recibe un User, que un atributo guarda un datetime, o que una operación entre contadores devuelve otro contador compatible.

Note

Este artículo es parte de una serie que explica el tipado en Python. A continuación, puedes ver la recopilación de todos los posts de la serie.

Ver serie

En esta entrega nos concentraremos en clases: cómo usarlas como tipos, cómo declarar atributos de instancia, cuándo aplicar ClassVar, y cómo resolver referencias hacia la propia clase con strings, from __future__ import annotations y typing.Self.

Usar clases como tipos en Python

En Python, una clase también puede usarse como anotación de tipo. Esto aplica tanto para clases que tú defines como para clases de la librería estándar. Por ejemplo, el módulo datetime define tipos como date, datetime y timedelta, mientras que uuid define UUID.

import datetime
import uuid

birth_date: datetime.date = datetime.date(2020, 2, 7)
timestamp: datetime.datetime = datetime.datetime(2020, 2, 7, 10, 0)
duration: datetime.timedelta = datetime.timedelta(hours=1)

uid1: uuid.UUID = uuid.uuid1()
uid4: uuid.UUID = uuid.uuid4()

Este código no cambia el comportamiento en tiempo de ejecución. Su valor está en la señal que le entregamos al IDE, al analizador estático y a otros desarrolladores que lean el código.

import datetime

created_at: datetime.datetime = datetime.datetime.now() # ✅
created_at = "2024-08-12" # ❌ el contrato dejó de ser datetime.datetime

Info

Las anotaciones no reemplazan la validación de datos externos. Si recibes JSON, entrada de usuario o información desde una API, sigue siendo necesario validar en los bordes del sistema.

Tipar atributos de instancia en la clase

Cuando trabajamos con clases propias, podemos declarar los atributos esperados directamente en el cuerpo de la clase. Esto ayuda a que el analizador entienda qué atributos existen en cada instancia, incluso si se asignan dentro de __init__.

class Counter:
 n: int

 def __init__(self, start: int = 0) -> None:
 self.n = start

 def __repr__(self) -> str:
 return str(self.n)

En este ejemplo, n: int describe un atributo de instancia. Cada objeto Counter tendrá su propio valor de n, asignado en el constructor.

counter = Counter(start=10)
print(counter.n) # ✅ 10
print(repr(counter)) # ✅ "10"

counter.n = "10" # ❌ rompe el contrato declarado para la instancia

La anotación en el cuerpo de la clase no inicializa el atributo por sí sola. Si declaras n: int, pero nunca asignas self.n, la instancia no tendrá ese atributo disponible en tiempo de ejecución.

Warning

Anotar un atributo no es lo mismo que crearlo. La anotación describe el contrato; la asignación en __init__ crea el estado real de la instancia.

ClassVar para variables de clase

No todos los atributos declarados en una clase pertenecen a cada instancia. Algunas variables funcionan como configuración compartida para todas las instancias. Para estos casos existe ClassVar, disponible desde typing.

from typing import ClassVar

class Counter:
 STEP: ClassVar[int] = 1
 n: int

 def __init__(self, start: int = 0) -> None:
 self.n = start

 def __repr__(self) -> str:
 return str(self.n)

 def increment(self) -> None:
 self.n += self.STEP

STEP representa una variable de clase. El valor vive en la clase Counter, no como parte del estado individual de cada objeto.

Counter.STEP = 2 # ✅ configuración compartida
counter = Counter(10)
counter.increment()
print(counter.n) # 12

counter.STEP = 5 # ❌ puede ocultar la variable de clase en esa instancia

Técnicamente Python permite asignar counter.STEP = 5, pero eso crea o modifica un atributo en la instancia, lo cual puede generar confusión. ClassVar permite que herramientas como mypy o Pyright detecten este uso como una señal de diseño incorrecta.

Tip

Usa ClassVar cuando el atributo describe configuración, constantes o metadatos compartidos por todas las instancias de una clase.

Referencias hacia la propia clase con strings

Un caso común aparece cuando un método recibe o devuelve otra instancia de la misma clase. Por ejemplo, podemos definir la suma de dos contadores con __add__.

from typing import ClassVar

class Counter:
 STEP: ClassVar[int] = 1
 n: int

 def __init__(self, start: int = 0) -> None:
 self.n = start

 def __repr__(self) -> str:
 return str(self.n)

 def __add__(self, other: "Counter") -> "Counter":
 return Counter(start=self.n + other.n)

La anotación "Counter" es una referencia adelantada o forward reference. Se escribe como string porque, mientras Python está evaluando el cuerpo de la clase, el nombre Counter todavía no terminó de definirse.

first = Counter(2)
second = Counter(3)

result = first + second
print(result) # 5

El siguiente diagrama resume el contrato principal de la clase:

classDiagram
 class Counter {
 +int n
 +ClassVar~int~ STEP
 +__init__(int start) None
 +__repr__() str
 +__add__(Counter other) Counter
 }

Esta forma es compatible con versiones antiguas de Python y sigue siendo frecuente en bases de código que necesitan soportar varios entornos.

Evaluación diferida con `from future import annotations`

Desde Python 3.7 podemos activar la evaluación diferida de anotaciones usando from __future__ import annotations. Con esto, las anotaciones no se resuelven inmediatamente al definir la clase, lo que permite escribir Counter sin comillas.

from __future__ import annotations

from typing import ClassVar

class Counter:
 STEP: ClassVar[int] = 1
 n: int

 def __init__(self, start: int = 0) -> None:
 self.n = start

 def __repr__(self) -> str:
 return str(self.n)

 def __add__(self, other: Counter) -> Counter:
 return Counter(start=self.n + other.n)

La ventaja principal es legibilidad. El código se ve más cercano a una anotación normal y reduce el ruido de comillas en modelos con muchas referencias cruzadas.

# ✅ con evaluación diferida
from __future__ import annotations

class Node:
 parent: Node | None

 def __init__(self, parent: Node | None = None) -> None:
 self.parent = parent

Info

from __future__ import annotations debe aparecer al inicio del archivo, antes de otros imports normales. Es una decisión por módulo, no por clase.

`typing.Self` para métodos que devuelven la misma clase

Python 3.11 incorporó typing.Self para expresar que un método devuelve una instancia del mismo tipo concreto que lo invoca. Esto es especialmente útil en métodos fluidos, constructores alternativos y operaciones que deberían preservar el subtipo.

from typing import Self

class Counter:
 n: int

 def __init__(self, start: int = 0) -> None:
 self.n = start

 def __repr__(self) -> str:
 return str(self.n)

 def __add__(self, other: Self) -> Self:
 return type(self)(start=self.n + other.n)

Aquí usamos type(self)(...) en lugar de Counter(...) para respetar el tipo concreto de la instancia. Si más adelante existe una subclase de Counter, el método tiene mejores posibilidades de devolver esa misma subclase.

Warning

Si anotas un método con Self, procura que la implementación realmente devuelva el mismo tipo concreto. Anotar Self pero retornar siempre Counter(...) puede engañar al analizador estático.

Herencia: cuando la clase base no es suficiente

El beneficio de Self se ve más claro con herencia. Consideremos una clase base A y una subclase B. Si el método me se anota devolviendo A, el tipo estático del resultado será siempre A, incluso cuando el objeto real sea B.

from __future__ import annotations

class A:
 def me(self) -> A:
 return self

class B(A):
 pass

b = B()
result = b.me() # tipo estático: A

Ese contrato es correcto, pero pierde información. El método devuelve self, así que cuando lo invoca una instancia de B, el resultado debería conservar el tipo B.

from typing import Self

class A:
 def me(self) -> Self:
 return self

class B(A):
 pass

b = B()
result = b.me() # tipo estático: B

La diferencia es importante cuando encadenas métodos o cuando la subclase agrega comportamiento adicional.

from typing import Self

class A:
 def me(self) -> Self:
 return self

class B(A):
 def only_b(self) -> str:
 return "B"

b = B()
print(b.me().only_b()) # ✅ el analizador conserva que b.me() es B

Sin Self, el analizador puede asumir que b.me() es A, y por tanto marcar only_b() como un método inexistente.

class A:
 def me(self) -> "A":
 return self

class B(A):
 def only_b(self) -> str:
 return "B"

b = B()
b.me().only_b() # ❌ para el analizador, me() devuelve A

Tip

Usa Self cuando el contrato del método sea “devuelvo el mismo tipo concreto que recibió la llamada”. Usa el nombre de la clase cuando el método debe devolver explícitamente una instancia de esa clase base.

Cierre

El tipado de clases permite expresar contratos más precisos entre objetos. Puedes usar clases estándar como datetime.datetime o uuid.UUID, declarar atributos de instancia, diferenciar variables compartidas con ClassVar, y manejar referencias hacia la propia clase con strings o evaluación diferida.

Para jerarquías de herencia, typing.Self mejora la precisión del análisis estático porque conserva el tipo concreto de la instancia. Esta diferencia se vuelve relevante cuando diseñas APIs orientadas a objetos, métodos encadenables o modelos que se especializan mediante subclases.

Note

En el próximo artículo veremos cómo aplicar tipado a estructuras de datos para modelar colecciones más expresivas y mantenibles.

Estructuras de datos

Tipado en Python: Tipado de funciones

Dacadev — Sun, 11 Aug 2024 00:00:00 -0500

Tabla de Contenido

Cuando un módulo crece y varias funciones empiezan a pasar datos entre capas, el contrato entre parámetros y retorno se vuelve crítico. El tipado de funciones en Python nos permite documentar ese contrato directamente en el código, mejorar la autocompletación del IDE y detectar inconsistencias antes de ejecutar el flujo completo en producción.

Note

Este artículo es parte de una serie que explica el tipado en Python. A continuación, puedes ver la recopilación de todos los posts de la serie.

Ver serie

En la entrega anterior vimos cómo anotar variables y colecciones. Ahora aplicaremos esa misma idea en funciones: parámetros, retornos, valores por defecto, argumentos dinámicos y objetos que se pueden invocar como funciones.

Info

Las anotaciones de tipo no cambian el comportamiento de Python en tiempo de ejecución. Su valor principal está en herramientas de análisis estático como mypy, pyright, IDEs y revisiones de código.

Sintaxis general para tipar funciones

La sintaxis base para agregar tipos a una función consiste en anotar cada argumento después de : y declarar el tipo de retorno después de ->.

def my_function(arg1: type, arg2: type) -> return_type:
 ...

Esta estructura expresa dos cosas importantes:

arg1: type: el argumento arg1 debería recibir valores compatibles con type.
-> return_type: la función debería devolver un valor compatible con return_type.

Por ejemplo, una función que recibe dos enteros y retorna otro entero se puede escribir así:

def add(a: int, b: int) -> int:
 return a + b

Si la función no retorna un valor útil, se usa None como tipo de retorno:

def log_message(message: str) -> None:
 print(message)

Tip

Anotar el retorno es tan importante como anotar los argumentos. Muchas inconsistencias aparecen cuando una función empieza devolviendo int, luego en una rama retorna None y el consumidor asume que siempre puede operar con números.

Ejemplo con `Counter`

Supongamos que tenemos una lista de elementos y cada elemento contiene una lista de etiquetas. Queremos contar cuántas veces aparece cada etiqueta.

from collections import Counter


def counter_tags(items: list[dict[str, list[str]]]) -> Counter[str]:
 return Counter(tag for item in items for tag in item["tags"])

La firma de counter_tags nos dice que items debe ser una lista de diccionarios. Cada diccionario usa llaves de tipo str y valores de tipo list[str]. La función retorna un Counter[str], es decir, un contador cuyas llaves son cadenas.

counter_tags([{"tags": ["python", "typing"]}, {"tags": ["python"]}]) # ✅
counter_tags([{"tags": ["python", 1]}, {"tags": ["typing"]}]) # ❌

La segunda llamada es problemática porque la lista de tags mezcla str con int. Python puede ejecutarla, pero un analizador estático marcará que 1 no coincide con list[str].

Warning

El tipado describe la forma esperada de los datos, pero no reemplaza validaciones de entrada cuando los datos vienen de usuarios, APIs externas, archivos o mensajes de una cola.

Valores por defecto tipados

Cuando una función tiene valores por defecto, también conviene anotar esos parámetros. El valor asignado debe ser compatible con el tipo declarado.

def sum_numbers(numbers: list[int], start: int = 0) -> int:
 total = start

 for n in numbers:
 total += n

 return total


sum_numbers([1, 2, 3, 4], start=100) # ✅
sum_numbers([1, 2, 3, 4]) # ✅
sum_numbers([1, 2, "A"]) # ❌
sum_numbers([1, 2, 3, 4], start="B") # ❌

En este caso numbers debe ser una lista de enteros y start también debe ser un entero. Si no se pasa start, Python usa 0, que cumple con la anotación int.

Este patrón es útil en funciones acumuladoras, paginadores, transformaciones de datos y cualquier API interna donde un valor opcional modifica el cálculo sin cambiar el tipo esperado.

`*args` tipados

Python permite recibir una cantidad variable de argumentos posicionales con *args. Para tiparlos, se anota el tipo de cada elemento recibido, no el tipo de la tupla completa.

def sum_args(*args: int) -> int:
 total = 0

 for n in args:
 total += n

 return total


sum_args(1, 2, 3, 4, 5) # ✅
sum_args(1, "A") # ❌

La anotación *args: int significa que cada argumento posicional adicional debe ser int. Internamente, Python sigue recibiendo una tupla, pero desde el punto de vista del contrato de la función, cada elemento debe respetar el tipo indicado.

Info

Si necesitas aceptar varios tipos en *args, puedes combinar tipos con |, por ejemplo *args: int | float. Esto mantiene el contrato explícito sin convertir la función en una entrada completamente abierta.

`*args` con parámetros keyword-only

También podemos combinar argumentos dinámicos con parámetros que solo se reciben por nombre. En Python, todo parámetro declarado después de *args se vuelve keyword-only.

def sum_args(*args: int, start: int = 0) -> int:
 total = start

 for n in args:
 total += n

 return total


sum_args(1, 2, 3, 4) # ✅
sum_args(1, 2, 3, start=100) # ✅
sum_args(1, 2, 3, start="x") # ❌
sum_args(1, 2, "3") # ❌

Aquí start no puede pasarse como otro argumento posicional más; debe enviarse usando su nombre. Esto mejora la legibilidad cuando el parámetro tiene un rol especial dentro del cálculo.

Este estilo es recomendable cuando una función acepta una secuencia flexible de valores, pero también necesita opciones de configuración con nombres claros.

Funciones de primer orden y `Callable`

En Python podemos pasar funciones como argumentos de otras funciones. Para anotar este tipo de contrato usamos Callable, disponible en collections.abc.

import time
from collections.abc import Callable


def work(send_notification: Callable[[str], None]) -> None:
 for i in range(3):
 time.sleep(1)

 send_notification(f"Finished {i + 1} rounds of work!")

La anotación Callable[[str], None] indica que send_notification debe ser invocable, recibir un str y no retornar un valor útil.

def notify(message: str) -> None:
 print(message)


def bad_notify(message: int) -> None:
 print(message)


work(notify) # ✅
work(bad_notify) # ❌

En Callable, el primer bloque define la lista de argumentos y el segundo define el retorno:

Callable[[str], None]
Callable[[str, int], bool]
Callable[[bytes], str]

flowchart LR
 A["Callable[[str, int], bool]"] --> B[Entrada 1: str]
 A --> C[Entrada 2: int]
 B --> D[Función compatible]
 C --> D
 D --> E[Salida: bool]

Tip

Usa Callable cuando la función consumidora solo necesita ejecutar un comportamiento. Esto reduce acoplamiento porque no obliga a depender de una implementación concreta.

`Callable` con clases y `call`

Callable no se limita a funciones definidas con def. Una instancia de clase también puede ser invocable si implementa el método especial __call__.

class Notifier:
 def __call__(self, message: str) -> None:
 print(f"Notifier sends: '{message}'")


notifier = Notifier()
work(notifier) # ✅

En este ejemplo, notifier se comporta como una función porque Notifier define __call__. Para el contrato de work, lo importante es que el objeto pueda invocarse con un str y retornar None.

Este patrón aparece con frecuencia cuando necesitas combinar estado interno con una interfaz funcional. Por ejemplo, un notificador podría guardar credenciales, configuración del canal o métricas, pero seguir exponiendo una firma simple para el consumidor.

Warning

No confundas Callable con una clase específica. Callable[[str], None] describe una capacidad de invocación; no exige que el objeto sea una función tradicional ni una instancia de una clase concreta.

Conclusión

El tipado de funciones en Python permite hacer explícitos los contratos entre piezas de código: qué argumentos acepta una función, qué retorna y qué forma deben tener los callables que recibe como dependencias.

En código de aplicación, estas anotaciones mejoran la navegación, reducen errores de integración y facilitan refactors. En librerías o módulos compartidos, además funcionan como documentación ejecutable para otros desarrolladores y herramientas.

Note

En el siguiente artículo continuaremos con el tipado aplicado a clases, atributos y métodos.

Tipado en clases

Tipado básico en Python

Dacadev — Sat, 10 Aug 2024 00:00:00 -0500

Tabla de Contenido

Note

Este artículo es parte de una serie que explica el tipado en Python. A continuación, puedes ver la recopilación de todos los posts de la serie.

Ver serie

Agregar tipos en Python es muy sencillo y tiene una sintaxis similar a otros lenguajes como Typescript. No es obligatorio aplicar tipado en cada pieza de código, lo que permite agregarlo de manera gradual. Además, agregar o no tipos no afectará el comportamiento del código.

Info

La posibilidad de agregar tipado en Python está disponible desde la versión 3.5. Desde entonces, se han añadido nuevas características y mejoras.

Tipos Buitl-in in Python

Los tipos built-in son aquellos que vienen por defecto en Python, como str, int, float, bool, bytes, None, list, dict, tuple, set, entre otros.

Para agregar tipado a una variable, simplemente añade : después del nombre de la variable y luego especifica el tipo de dato. La sintaxis es:

<variable>: <type> = <value>

Ejemplo:

n: int = 1
f: float = 10.0
c: complex = 1 + 2j
b: bool = True
s: bytes = b'bytes'
t: str = "hello world"
v: None = None

En el anterior ejemplo estamos definiendo que cada una de las variables solo van a manejar un tipo de datos a lo largo de vida en el programa.

Note

Recuerda que el agregar el tipo de dato no afecta el comportamiento del código, es solo una ayuda para el programador, analizadores de código estáticos e IDEs.

Tipado en colecciones

Para colecciones como list, dict, tuple, set, la sintaxis es similar a la de las variables simples. salvo que podemos definir o nor el tipo de variable que cada variable va a contener. es decir que tenemos dos tipos de sintaxis que podemos utilizar.

<variable>: <collection> = <value>
<variable>: <collection>[<type>...] = <value>

En la primera opción estamos definiendo que la variable va a ser de tipo list, dict, tuple, set y en la segunda opción estamos definiendo que la variable va a ser de tipo list, dict, tuple, set y que va a contener un tipo de dato especifico. Veamos como se aplica esto en algunos ejemplos, para ello es importante tener en cuenta la versión de Python que estás utilizando.

Python 3.5 a 3.8: Es necesario importar los tipos de la librería typing:

from typing import List, Set, Tuple, Dict

l: List = [1, 2, 3, 4]
s: Set[str] = {"hello", "world"}
t: Tuple[int, str, bool] = (10, "Python", True)
d: Dict[str, bool] = {"active": True, "admin": False}

Python 3.9 y posteriores: Puedes utilizar la sintaxis estándar sin importar typing:

l: list = [1, 2, 3, 4]
s: set[str] = {"hello", "world"}
t: tuple[int, str, bool] = (10, "Python", True)
d: dict[str, bool] = {"active": True, "admin": False}

En los ejemplos anteriores podemos observar que estamos definiendo un tipo de colección diferente por cada varibale y cabe destacar que en el caso de las colecciones podemos definir el tipo de dato que va a contener cada una de las variables, debes tener en cuenta que:

para list y set se utiliza el tipo de dato que va a contener entre corchetes [].
para tuple se define el tipo de dato y la posición dentro de la tupla entre corchetes [], es decir que en el ejemplo se espera que sea una tupla de tres elementos que estaran en el siguiente orden int, str, bool.
para dict se define el tipo de dato que va a contener la llave y el valor entre corchetes [], es decir que en el ejemplo se espera que sea un diccionario con llaves de tipo str y valores de tipo bool.

Combinación de Tipos en Python

En algunos casos, es necesario que las variables puedan contener más de un tipo de dato o incluso que puedan ser opcionales. Para ello se han definido diversas estrategias para alcanzar esta funcionalidad

Definir Más de un Tipo

Utiliza el carácter | para definir más de un tipo de dato en una variable, este carácter actúa como un OR lógico:

a: int | str = 1
b: int | str = "one"

Para versiones anteriores a Python 3.9, importa Union de typing:

from typing import Union

a: Union[int, str] = 1
b: Union[int, str] = "one"

Valores Opcionales o `None`

Para definir que un valor es opcional, añade None como parte de los tipos posibles:

a: int | None = 1
b: int | None = None

Para versiones anteriores a Python 3.9, utiliza Optional o Union:

# Opción 1
from typing import Optional

a: Optional[int] = 1

# Opción 2
from typing import Union

a: Union[int, None] = None

Definir Valores Fijos

Si deseas restringir los valores que puede tomar una variable, usa Literal de typing:

from typing import Literal

cards: Literal["clubs", "diamonds", "hearts", "spades"]
cards = "clubs"

Definir Tipos Personalizados

EN Python asi como con las variables es posible definir tipos personalizados, para simplificar la lectura del código o incluso para darle un mejor entendimiento al código. en la siguiente pieza de código podemos ver esta funcionalidad.

from typing import Literal

UserType = Literal["admin", "user"]
ID = int | str
PersonalData = dict[str, str | bool| float | None]

User = tuple[ID, PersonalData, UserType]
UserUgly = tuple[int | str, dict[str, str | bool| float | None], Literal["admin", "user"]]

Como podemos observa en el ejemplo anterior estamos separando nuestra definición de tipos en otros tipos para facilitar la lectura de nuestro código, en el caso de User y UserUgly estamos definiendo un tipo de dato que va a ser una tupla que va a contener un ID, PersonalData y UserType y en el caso de UserUgly estamos definiendo el mismo tipo de dato pero de una manera menos legible.

si escribieramos el mismo código para versiones anteriores a Python 3.9, el código se vería de la siguiente manera:

from typing import Literal, Union, Optional

UserType = Literal["admin", "user"]
ID = Union[int, str]
PersonalData = dict[str, Optional[str, bool, float]]

User = tuple[ID, PersonalData, UserType]

Datos IO en Python

Cuando trabajes con datos de entrada/salida, como la lectura de archivos, usa el tipo IO de typing:

from typing import IO

text_file: IO[str] # text, json, xml, html...
bin_file: IO[bytes] # jpeg, png, pdf, mp3...

El tipo IO es un tipo genérico que se utiliza para representar objetos que son streams de entrada o salida, como archivos y sockets, y solo admite tipos de datos str y bytes.

Info

En este artículo, hemos cubierto las nociones básicas sobre cómo agregar tipos a tus variables en Python. En el próximo artículo, exploraremos cómo agregar tipos a funciones.

Tipado de funciones

Tipado en Python: Introducción

Dacadev — Fri, 09 Aug 2024 00:00:00 -0500

Tabla de Contenido

Note

Este artículo hace parte de una serie que explicará el tipado en Python, a continuación puedes ver la recopilación de todos los posts de la serie.

Ver serie

¿Por qué es importante el tipado?

Antes de ahondar en el uso de tipos en python, debemos hacer un pequeño énfasis de porque nace la necesidad de implementar “tipado” y análisis estático de código en Python

Info

Escribo tipado entre comillas porque realmente no implementamos tipado en python, sino que simulamos tener tipos en Python, esto lo veremos vas adelante, pero es importante tenerlo en cuenta.

Python, al ser un lenguaje interpretado, significa que el código es leído y ejecutado solamente cuando el interprete pasa por la línea de código, por lo que el error, si existe, solo aparecerá cuando ejecutamos dicha línea de código. Por el contrario en un lenguaje compilado como Go o Java, el código debe primero construido (compilado) y después usado, pero es en el proceso de compilación en donde se realizan validaciones de tipos dentro del código y estas validaciones permiten capturar errores tempranos.

Tipos de errores

En este punto vale la pena agrupar los errores en dos grupos:

Errores de excepción: Son errores que se generan cuando un programa falla al ejecutar una acción determinada, como por ejemplo abrir un archivo que no existe.
Errores de lógica: Son errores que no generan excepción sino que generan un resultado errado al esperado.

Warning

Los errores de lógica son los mas peligrosos ya que al no levantar una excepción normalmente permiten que el flujo de trabajo continue con los errores.

En ese orden de ideas nos centraremos en los errores de lógica ya que son los errores que podemos “capturar” gracias a los tipos, por ejemplo con ayuda de tipos podemos capturar errores tempranos como:

validar el uso de los tipos de datos dentro de nuestro código, por ejemplo si estamos usando un string en un lugar donde deberíamos de usar un entero
validar que los métodos que estamos llamando existan en el objeto que estamos usando
validar que los atributos que estamos usando en un objeto existan
validar que los argumentos que estamos pasando a una función sean los correctos

Veamos la forma tradicional de validar y capturar errores de tipos en Python. Para ello debemos de implementar una serie sentencias en nuestro código para asegurarnos que estamos usando los tipos correctos. esto puede afectar la legibilidad del código y la productividad, e incluso el rendimiento de nuestros programas en algunos casos.

def clean_text(a):
 assert isinstance(a, str), "Input must be a string"
 # process a

def calculate_sum(*nums):
 sum = 0

 for num in nums:
 if not isinstance(num, (int, float)):
 raise ValueError("Input must be a number")

 sum += num

 return sum

En el caso de clean_text estamos validando que el argumento a sea un string, en caso de que no sea un string, levantamos una excepción. En el caso de calculate_sum estamos validando que los argumentos que estamos pasando sean int o float, en caso de que no sea alguno de estos, levantamos una excepción.

Info

En el caso clean_text estamos usando assert para validar el tipo de dato, sin embargo assert no es recomendado para validar tipos de datos, ya que se puede desactivar en tiempo de ejecución, por lo que no es una buena práctica usarlo como captura de errores en código, sin embargo es probable que lo encuentres en tu día a día como desarrollador.

Si miramos a profundidad el código no esta mal, sino que estamos agregando lógica adicional que esta afectando la legibilidad del código, y un de los principales objetivos que tenemos como programadores es escribir código limpio y legible. para los demás o tu yo del futuro. Imagina si hicieramos esto en códigos mas complejos y extensos.

Note

La siguiente entrega de esta seria aborda el tema de como implementar tipado en Python, y como podemos mejorar la legibilidad del código y la productividad. para verla da click en el siguiente botón.

Tipado básico en Python

Tipado en Python: Serie de DacaDev

Dacadev — Thu, 08 Aug 2024 00:00:00 -0500

Python, al ser un lenguaje interpretado y dinámicamente tipado, no incluye de forma nativa la gestión y manejo de tipos. Esta característica es extremadamente útil y práctica, especialmente para quienes están comenzando en el mundo del desarrollo de software.

Sin embargo, a medida que los proyectos crecen, esta ventaja inicial puede convertirse en un desafío. La ausencia de un sistema de tipos explícito puede complicar la lectura del código, dificultar la depuración de errores y limitar la escalabilidad del proyecto.

Por esta razón, ha surgido la iniciativa de implementar tipado en Python. Con esta herramienta, los desarrolladores pueden tener un mayor control sobre los tipos de datos en su código, lo que permite capturar errores tempranos y mejorar la calidad del software desde las primeras etapas del desarrollo.

En DacaDev, hemos creado una serie de artículos que explican de manera detallada el tipado en Python. A continuación, puedes acceder a cada uno de los artículos de la serie:

Tipado en Python · DacaCode

Tipado en Python: Estructuras de datos

Diccionarios tipados en Python

TypedDict: diccionarios con forma definida

Llaves opcionales con NotRequired

Enfoque inverso: total=False y Required

Dataclass: estructuras de datos con atributos

Dataclass vs class tradicional

Cuándo usar cada estructura de datos

Cierre

Tipado en Python: Tipado de clases

Usar clases como tipos en Python

Tipar atributos de instancia en la clase

ClassVar para variables de clase

Referencias hacia la propia clase con strings

Evaluación diferida con from __future__ import annotations

typing.Self para métodos que devuelven la misma clase

Herencia: cuando la clase base no es suficiente

Cierre

Tipado en Python: Tipado de funciones

Sintaxis general para tipar funciones

Ejemplo con Counter

Valores por defecto tipados

*args tipados

*args con parámetros keyword-only

Funciones de primer orden y Callable

Callable con clases y __call__

Conclusión

Tipado básico en Python

Tipos Buitl-in in Python

Tipado en colecciones

Combinación de Tipos en Python

Definir Más de un Tipo

Valores Opcionales o None

Definir Valores Fijos

Definir Tipos Personalizados

Datos IO en Python

Tipado en Python: Introducción

¿Por qué es importante el tipado?

Tipos de errores

Tipado en Python: Serie de DacaDev

Evaluación diferida con `from future import annotations`

`typing.Self` para métodos que devuelven la misma clase

Ejemplo con `Counter`

`*args` tipados

`*args` con parámetros keyword-only

Funciones de primer orden y `Callable`

`Callable` con clases y `call`

Valores Opcionales o `None`