El módulo reprlib produce representaciones abreviadas de objetos Python. En lugar de imprimir una lista con millones de elementos, un string enorme o una estructura profundamente anidada, limita longitud, cantidad de items y profundidad. Es útil en logs, consoles, debuggers, mensajes de error, herramientas de inspección e interfaces administrativas.
Una representación corta no es serialización. Está destinada a personas y diagnóstico, no a reconstruir el objeto. También puede revelar datos sensibles si el repr() del objeto los expone. Los límites reducen volumen, pero no sustituyen redaction, control de acceso o una política de logging.
repr y reprlib
La función built-in repr() intenta crear una representación inequívoca y útil para desarrolladores.
datos = list(range(1000))
print(repr(datos))
En objetos grandes, el resultado consume memoria, inunda logs y dificulta encontrar lo importante. reprlib.repr() utiliza una instancia predeterminada de Repr.
import reprlib
print(reprlib.repr(datos))
Tipos soportados
La implementación conoce strings, bytes, listas, tuplas, sets, frozensets, diccionarios, arrays y objetos genéricos. En containers limita items y en texto limita caracteres.
Los objetos personalizados siguen dependiendo de su __repr__() salvo que crees una política especializada.
Crea una instancia Repr
La clase Repr expone atributos para controlar límites.
from reprlib import Repr
resumen = Repr()
resumen.maxlist = 5
resumen.maxstring = 40
resumen.maxdict = 4
print(resumen.repr(datos))
Usa una instancia por política. Un console interactivo puede mostrar más detalles que un log de producción.
Límite de listas
maxlist define cuántos elementos aparecen. El módulo selecciona una cantidad limitada e inserta puntos suspensivos para indicar omisión.
La representación no siempre indica cuántos items fueron ocultados. Registra len(lista) por separado cuando importe el tamaño total.
Tuplas
maxtuple controla tuplas. Una tupla de un elemento conserva la coma necesaria.
resumen.maxtuple = 3
print(resumen.repr(tuple(range(20))))
No analices la salida con eval(). Las reticencias y truncamientos significan que el texto puede no ser una expresión completa.
Sets y frozensets
maxset y maxfrozenset limitan conjuntos. Los sets no tienen orden semántico estable, por lo que la muestra visible puede variar.
No uses este output como snapshot determinístico entre entornos. En tests, normaliza una colección derivada cuando los elementos puedan ordenarse.
Diccionarios
maxdict limita pares clave-valor.
resumen.maxdict = 3
config = {f"clave_{i}": i for i in range(20)}
print(resumen.repr(config))
Una clave sensible puede aparecer incluso en una muestra pequeña. Redacta o filtra el mapping antes de representarlo.
Strings
maxstring controla la longitud.
resumen.maxstring = 30
print(resumen.repr("a" * 500))
La abreviación suele preservar partes del inicio y del final. Es útil para rutas e IDs, pero puede revelar prefijos y sufijos secretos.
Salida larga de objetos propios
Otros límites, como maxlong, influyen en determinados caminos. El comportamiento exacto depende del tipo y de la versión.
Prueba los objetos reales. Un solo atributo no limita automáticamente todo __repr__() personalizado.
Bytes y binarios
Los límites de texto también afectan varias representaciones de bytes. Los payloads pueden contener tokens, datos personales o caracteres de control.
Para diagnóstico, prefiere tamaño, digest y una muestra sanitizada explícitamente.
Otros containers
Atributos como maxarray, maxdeque y maxother controlan otras categorías. Consulta la versión de Python del proyecto.
Valores demasiado altos eliminan la protección contra explosión de logs.
Profundidad con maxlevel
maxlevel limita el recorrido anidado.
resumen.maxlevel = 2
anidado = {"a": {"b": {"c": {"d": 1}}}}
print(resumen.repr(anidado))
Así una operación de diagnóstico no recorre un árbol enorme.
Objetos recursivos
Un container puede referirse a sí mismo.
items = []
items.append(items)
print(repr(items))
El sistema de representación detecta varios ciclos. reprlib añade límites, pero un __repr__() personalizado todavía puede entrar en recursión.
recursive_repr
El decorator recursive_repr() protege un __repr__() propio.
from reprlib import recursive_repr
class Nodo:
def __init__(self, valor):
self.valor = valor
self.siguiente = None
@recursive_repr(fillvalue="...")
def __repr__(self):
return f"Nodo({self.valor!r}, siguiente={self.siguiente!r})"
Cuando el mismo objeto aparece otra vez en la misma representación, el decorator devuelve el marcador.
Elección de fillvalue
fillvalue define el indicador de recursión. Mantén un valor corto y claramente artificial.
No uses texto que pueda confundirse con datos reales.
Subclase de Repr
Una subclase puede personalizar tipos de la aplicación.
from reprlib import Repr
class ReprAplicacion(Repr):
def repr_Usuario(self, obj, level):
return f"Usuario(id={obj.id!r})"
Prueba el dispatch porque herencia, clases dinámicas y nombres cualificados pueden requerir otra estrategia.
Redacta antes de formatear
Los objetos con contraseñas, tokens, claves y datos personales deben sanitizarse.
def sanitizar(config):
ocultas = {"password", "token", "secret"}
return {
clave: "***" if clave.lower() in ocultas else valor
for clave, valor in config.items()
}
Aplica reprlib a la estructura sanitizada. Truncar no equivale a proteger secretos.
Logging estructurado
En logging JSON, campos separados como tipo, tamaño, cantidad y muestra son mejores que una sola string.
reprlib puede generar la muestra mientras los metadatos permanecen buscables.
Mensajes de error
Una excepción puede incluir un resumen limitado.
valor_corto = resumen.repr(valor)
raise ValueError(f"valor inválido: {valor_corto}")
Escapa entrada no confiable cuando el mensaje será mostrado en HTML, terminal con estilos u otro contexto interpretado.
Caracteres de control
Los strings pueden contener controles de terminal. repr() escapa muchos, pero la superficie de salida aún requiere tratamiento.
No escribas binarios arbitrarios directamente en un terminal humano.
Rendimiento
Limitar el texto final reduce volumen, pero todavía se llama __repr__() en objetos seleccionados. Un método personalizado puede ser lento, acceder a red o provocar side effects, lo cual es un mal diseño.
__repr__() debería ser rápido, seguro y sin efectos observables.
Objetos lazy
No materialices generators o iterators solo para representarlos. Puedes consumir el stream y cambiar el comportamiento.
Registra tipo, estado conocido e identificador. El diagnóstico seguro no debe forzar cálculo caro.
Dataclasses
Las dataclasses generan __repr__() automáticamente. Los campos sensibles pueden usar repr=False.
from dataclasses import dataclass, field
@dataclass
class Credencial:
usuario: str
password: str = field(repr=False)
Combina esto con redaction porque objetos anidados pueden revelar información.
Estabilidad del formato
El repr de tipos internos puede cambiar entre versiones de Python. No lo uses como protocolo, clave de cache, firma o formato persistente.
Para persistencia, usa JSON, base de datos u otro formato versionado.
Snapshots de tests
Los snapshots basados en repr son frágiles por orden de sets, direcciones de memoria y cambios de versión. Normaliza los datos y elimina valores inestables.
Prueba por debajo, exactamente en el límite y por encima.
Diseño de __repr__
Un buen __repr__() incluye tipo y campos que identifican el estado, pero omite secretos y colecciones enormes.
def __repr__(self):
return f"Job(id={self.id!r}, status={self.status!r})"
Usa una instancia Repr dedicada si un campo variable puede crecer.
Errores comunes
Los fallos frecuentes son tratar repr como serialización, asumir que truncar protege secretos, configurar límites demasiado altos, materializar iterators, crear un __repr__() lento, depender del orden de sets, hacer parse de la salida y mantener snapshots inestables.
Conclusión
reprlib mantiene representaciones legibles y limitadas en logs, consoles y diagnósticos. Configura una instancia Repr por contexto, limita profundidad y containers, usa recursive_repr en ciclos y sanitiza antes de formatear.
Consulta la documentación oficial de reprlib y ast en Python para inspección estructural.
