logging — registro de eventos

Este módulo proporciona un subconjunto ligero del paquete estándar de Python logging adaptado a MicroPython. Admite el registro por niveles a través de objetos Logger con nombres jerárquicos, un pequeño conjunto de manejadores (StreamHandler, FileHandler), formato al estilo printf mediante Formatter y funciones de conveniencia a nivel de módulo equivalentes a las que operan sobre el logger raíz.

El módulo sigue la conocida API de CPython lo bastante de cerca como para que las aplicaciones sencillas escritas para la biblioteca estándar funcionen sin cambios. No se proporcionan los filtros, el bloqueo entre múltiples procesos, el formato de archivo de configuración ni la mayoría de las clases de manejadores.

Constantes de nivel

logging.CRITICAL: int

Valor numérico 50. Se utiliza para errores irrecuperables.

logging.ERROR: int

Valor numérico 40. Se utiliza para problemas graves.

logging.WARNING: int

Valor numérico 30. Nivel predeterminado de un logger raíz recién configurado.

logging.INFO: int

Valor numérico 20. Se utiliza para mensajes de confirmación.

logging.DEBUG: int

Valor numérico 10. Se utiliza para salida de diagnóstico detallada.

logging.NOTSET: int

Valor numérico 0. Indica un logger sin nivel configurado (el nivel efectivo se hereda entonces del logger raíz o de WARNING).

Funciones

logging.getLogger(name: str | None = None) → Logger

Devuelve el Logger registrado bajo name, creándolo en el primer uso. Si name es None se devuelve el logger raíz. La primera llamada con name="root" (o con name sin establecer) invoca implícitamente basicConfig para adjuntar un StreamHandler predeterminado que escribe en sys.stderr.

logging.log(level: int, msg: str, *args) → None

Registra un mensaje en level sobre el logger raíz. Los args se interpolan en msg usando formato al estilo printf con %; un único argumento de tipo dict se usa como mapeo.

logging.debug(msg: str, *args) → None

Equivalente a getLogger().debug(msg, *args).

logging.info(msg: str, *args) → None

Equivalente a getLogger().info(msg, *args).

logging.warning(msg: str, *args) → None

Equivalente a getLogger().warning(msg, *args).

logging.error(msg: str, *args) → None

Equivalente a getLogger().error(msg, *args).

logging.critical(msg: str, *args) → None

Equivalente a getLogger().critical(msg, *args).

logging.exception(msg: str, *args, exc_info: bool | BaseException = True) → None

Equivalente a getLogger().exception(msg, *args, exc_info=exc_info). Registra el mensaje en ERROR y, además, formatea el rastreo (traceback) de la excepción activa cuando exc_info es verdadero. Si exc_info es en sí una BaseException, se utiliza el rastreo de esa excepción; en caso contrario se consulta sys.exc_info() cuando está disponible.

logging.shutdown() → None

Cierra todos los manejadores adjuntos a todos los loggers conocidos y olvida los loggers. Se registra automáticamente mediante sys.atexit cuando ese gancho está disponible.

logging.addLevelName(level: int, name: str) → None

Asocia el nombre textual name con el nivel numérico level para que Formatter pueda mostrarlo mediante %(levelname)s.

logging.basicConfig(filename: str | None = None, filemode: str = 'a', format: str | None = None, datefmt: str | None = None, level: int = WARNING, stream=None, encoding: str = 'UTF-8', force: bool = False) → None

Configura el logger raíz con un único manejador.

Si se proporciona filename se crea un FileHandler usando filemode y encoding; de lo contrario se usa un StreamHandler que escribe en stream (con valor predeterminado sys.stderr).

format y datefmt se pasan a un nuevo Formatter.

level establece tanto el nivel del manejador como el nivel del logger raíz.

Si el logger raíz ya tiene manejadores, esta función no hace nada a menos que force sea True, en cuyo caso los manejadores existentes se cierran y se reemplazan.

Clases

class logging.Logger(name: str, level: int = NOTSET)

Un logger con nombre. Construya los loggers mediante getLogger en lugar de directamente, de modo que getLogger pueda devolver la misma instancia para el mismo nombre.

name: str

El nombre con puntos del logger.

level: int

El nivel numérico configurado. 0 (NOTSET) significa «heredar».

handlers: list

La lista de instancias de Handler adjuntas a este logger. Cuando está vacía, los mensajes se despachan a los manejadores del logger raíz.

setLevel(level: int) → None

Establece el nivel de umbral del logger.

isEnabledFor(level: int) → bool

Devuelve True si un mensaje de level sería procesado por este logger.

getEffectiveLevel() → int

Devuelve el primero distinto de cero de: el nivel de este logger, el nivel del logger raíz o WARNING.

log(level: int, msg: str, *args) → None

Registra msg en level. Los args se interpolan en msg con el operador %; si el primer argumento posicional es un dict, se usa como mapeo.

debug(msg: str, *args) → None

Registra msg en DEBUG.

info(msg: str, *args) → None

Registra msg en INFO.

warning(msg: str, *args) → None

Registra msg en WARNING.

error(msg: str, *args) → None

Registra msg en ERROR.

critical(msg: str, *args) → None

Registra msg en CRITICAL.

exception(msg: str, *args, exc_info: bool | BaseException = True) → None

Registra msg en ERROR y, cuando exc_info es verdadero, añade el rastreo formateado. Si exc_info es una instancia de BaseException, se muestra el rastreo de esa excepción; en caso contrario se consulta la excepción activa mediante sys.exc_info().

addHandler(handler: Handler) → None

Adjunta handler a este logger.

hasHandlers() → bool

Devuelve True si hay algún manejador adjunto a este logger.

class logging.Handler(level: int = NOTSET)

Clase base para todos los manejadores. Las subclases implementan emit().

level: int

El nivel de umbral del manejador.

formatter: 'Formatter | None'

El Formatter activo, o None.

setLevel(level: int) → None

Establece el nivel de umbral del manejador.

setFormatter(formatter: Formatter) → None

Adjunta formatter a este manejador.

format(record: LogRecord) → str

Renderiza record usando el formateador configurado.

close() → None

Libera los recursos retenidos por el manejador. Lo llaman shutdown y FileHandler cuando se cierra.

class logging.StreamHandler(stream=None)

Manejador que escribe los registros formateados, seguidos de self.terminator ("\n" de forma predeterminada), en stream. stream toma como valor predeterminado sys.stderr.

stream

El objeto stream de destino.

terminator: str

Cadena añadida después de cada registro formateado. Su valor predeterminado es "\n".

emit(record: LogRecord) → None

Escribe record en stream si su nivel alcanza el umbral del manejador.

close() → None

Vacía el stream subyacente cuando este expone un método flush.

class logging.FileHandler(filename: str, mode: str = 'a', encoding: str = 'UTF-8')

Subclase de StreamHandler que abre filename con el mode y el encoding dados y escribe en él los registros formateados. El archivo subyacente se cierra en close().

class logging.Formatter(fmt: str | None = None, datefmt: str | None = None)

Renderiza instancias de LogRecord como cadenas.

fmt es una plantilla al estilo printf. Las claves reconocidas son %(name)s, %(message)s, %(msecs)d, %(asctime)s y %(levelname)s. Cuando no se establece, su valor predeterminado es "%(levelname)s:%(name)s:%(message)s".

datefmt es la plantilla de time.strftime usada para mostrar %(asctime)s. Su valor predeterminado es "%Y-%m-%d %H:%M:%S".

usesTime() → bool

Devuelve True si la plantilla de formato hace referencia a asctime.

formatTime(datefmt: str, record: LogRecord) → str | None

Formatea record.ct usando time.strftime y datefmt. Devuelve None en las plataformas donde time.strftime no está disponible.

format(record: LogRecord) → str

Renderiza record. Si la plantilla usa asctime, se invoca primero formatTime() para rellenar record.asctime.

class logging.LogRecord

Contenedor de los datos que un Logger pasa a sus manejadores. Las instancias se rellenan mediante set(); las implementaciones de logger reutilizan un único registro por logger para reducir las asignaciones de memoria.

name: str

El nombre del logger de origen.

levelno: int

Nivel numérico de este registro.

levelname: str

Nombre textual del nivel.

message: str

El mensaje de registro completamente formateado.

ct: float

Hora de creación tal como la devuelve time.time().

msecs: int

Componente de milisegundos de ct.

asctime: str | None

Marca de tiempo legible por humanos; la rellena de forma diferida Formatter.

set(name: str, level: int, message: str) → None

Inicializa el registro con los valores dados y captura la hora actual.