logging — registro de eventos

Este módulo fornece um subconjunto leve do pacote logging padrão do Python adaptado para o MicroPython. Ele suporta registro por níveis através de objetos Logger nomeados hierarquicamente, um pequeno conjunto de handlers (StreamHandler, FileHandler), formatação no estilo printf via Formatter e funções de conveniência em nível de módulo equivalentes àquelas que operam sobre o logger raiz.

O módulo segue a API familiar do CPython de forma próxima o suficiente para que aplicações simples escritas para a biblioteca padrão funcionem sem alterações. Filtros, travamento entre múltiplos processos, o formato de arquivo de configuração e a maioria das classes de handler não são fornecidos.

Constantes de Nível

logging.CRITICAL: int

Valor numérico 50. Usado para erros irrecuperáveis.

logging.ERROR: int

Valor numérico 40. Usado para problemas sérios.

logging.WARNING: int

Valor numérico 30. Nível padrão para um logger raiz recém-configurado.

logging.INFO: int

Valor numérico 20. Usado para mensagens de confirmação.

logging.DEBUG: int

Valor numérico 10. Usado para saída de diagnóstico detalhada.

logging.NOTSET: int

Valor numérico 0. Indica um logger sem nível configurado (o nível efetivo é então herdado do logger raiz ou WARNING).

Funções

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

Retorna o Logger registrado sob name, criando-o no primeiro uso. Se name for None o logger raiz é retornado. A primeira chamada com name="root" (ou com name não definido) invoca implicitamente basicConfig para anexar um StreamHandler padrão que escreve em sys.stderr.

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

Registra uma mensagem no nível level no logger raiz. Os args são interpolados em msg usando formatação no estilo printf com %; um único argumento do tipo dict é usado como o mapeamento.

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 a mensagem em ERROR e, adicionalmente, formata o traceback da exceção ativa quando exc_info é verdadeiro. Se exc_info for ele próprio um BaseException, o traceback dessa exceção é usado; caso contrário, sys.exc_info() é consultado quando disponível.

logging.shutdown() → None

Fecha todos os handlers anexados a todos os loggers conhecidos e esquece os loggers. Registrado automaticamente através de sys.atexit quando esse hook está disponível.

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

Associa o name textual ao level numérico para que o Formatter possa renderizá-lo via %(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 o logger raiz com um único handler.

Se filename for fornecido, um FileHandler é criado usando filemode e encoding; caso contrário, é usado um StreamHandler que escreve em stream (cujo padrão é sys.stderr).

format e datefmt são repassados a um novo Formatter.

level define tanto o nível do handler quanto o nível do logger raiz.

Se o logger raiz já possuir handlers, esta função é uma operação nula, a menos que force seja True, caso em que os handlers existentes são fechados e substituídos.

Classes

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

Um logger nomeado. Construa loggers através de getLogger em vez de diretamente, para que getLogger possa retornar a mesma instância para o mesmo nome.

name: str

O nome pontuado do logger.

level: int

O nível numérico configurado. 0 (NOTSET) significa “herdar”.

handlers: list

A lista de instâncias de Handler anexadas a este logger. Quando vazia, as mensagens são despachadas para os handlers do logger raiz.

setLevel(level: int) → None

Define o nível de limiar do logger.

isEnabledFor(level: int) → bool

Retorna True se uma mensagem de level seria processada por este logger.

getEffectiveLevel() → int

Retorna o primeiro valor diferente de zero entre: o nível deste logger, o nível do logger raiz, ou WARNING.

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

Registra msg no nível level. Os args são interpolados em msg com o operador %; se o primeiro argumento posicional for um dict, ele é usado como um mapeamento.

debug(msg: str, *args) → None

Registra msg em DEBUG.

info(msg: str, *args) → None

Registra msg em INFO.

warning(msg: str, *args) → None

Registra msg em WARNING.

error(msg: str, *args) → None

Registra msg em ERROR.

critical(msg: str, *args) → None

Registra msg em CRITICAL.

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

Registra msg em ERROR e, quando exc_info é verdadeiro, anexa o traceback formatado. Se exc_info for uma instância de BaseException, o traceback dessa exceção é renderizado; caso contrário, a exceção ativa é consultada via sys.exc_info().

addHandler(handler: Handler) → None

Anexa handler a este logger.

hasHandlers() → bool

Retorna True se houver algum handler anexado a este logger.

class logging.Handler(level: int = NOTSET)

Classe base para todos os handlers. As subclasses implementam emit().

level: int

O nível de limiar do handler.

formatter: 'Formatter | None'

O Formatter ativo, ou None.

setLevel(level: int) → None

Define o nível de limiar do handler.

setFormatter(formatter: Formatter) → None

Anexa formatter a este handler.

format(record: LogRecord) → str

Renderiza record usando o formatter configurado.

close() → None

Libera os recursos mantidos pelo handler. Chamado por shutdown e por FileHandler quando ele é fechado.

class logging.StreamHandler(stream=None)

Handler que escreve registros formatados, seguidos por self.terminator ("\n" por padrão), em stream. O padrão de stream é sys.stderr.

stream

O objeto de stream de destino.

terminator: str

String anexada após cada registro formatado. O padrão é "\n".

emit(record: LogRecord) → None

Escreve record em stream se seu nível atender ao limiar do handler.

close() → None

Faz o flush do stream subjacente quando ele expõe um método flush.

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

Subclasse de StreamHandler que abre filename com o mode e o encoding fornecidos e escreve registros formatados nele. O arquivo subjacente é fechado em close().

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

Renderiza instâncias de LogRecord em strings.

fmt é um template no estilo printf. As chaves reconhecidas são %(name)s, %(message)s, %(msecs)d, %(asctime)s e %(levelname)s. Quando não definido, o padrão é "%(levelname)s:%(name)s:%(message)s".

datefmt é o template de time.strftime usado para renderizar %(asctime)s. O padrão é "%Y-%m-%d %H:%M:%S".

usesTime() → bool

Retorna True se o template de formato referenciar asctime.

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

Formata record.ct usando time.strftime e datefmt. Retorna None em plataformas onde time.strftime não está disponível.

format(record: LogRecord) → str

Renderiza record. Se o template usar asctime, formatTime() é invocado primeiro para preencher record.asctime.

class logging.LogRecord

Contêiner para os dados passados de um Logger para seus handlers. As instâncias são preenchidas através de set(); as implementações de logger reutilizam um único registro por logger para reduzir alocações.

name: str

O nome do logger de origem.

levelno: int

Nível numérico deste registro.

levelname: str

Nome textual do nível.

message: str

A mensagem de log totalmente formatada.

ct: float

Horário de criação conforme retornado por time.time().

msecs: int

Componente em milissegundos de ct.

asctime: str | None

Timestamp legível por humanos; preenchido de forma preguiçosa pelo Formatter.

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

Inicializa o registro com os valores fornecidos e captura o horário atual.