logging — registo de eventos

Este módulo fornece um subconjunto leve do pacote logging padrão do Python, adaptado para MicroPython. Suporta registo por níveis através de objetos Logger com nomes hierárquicos, um pequeno conjunto de handlers (StreamHandler, FileHandler), formatação no estilo printf via Formatter, e funções de conveniência a nível de módulo equivalentes às que operam sobre o logger raiz.

O módulo segue a API familiar do CPython de forma suficientemente próxima para que aplicações simples escritas para a biblioteca padrão funcionem sem alterações. Filtros, bloqueio para múltiplos processos, o formato de ficheiro de configuração e a maioria das classes de handlers não estão disponíveis.

Constantes de Nível

logging.CRITICAL: int

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

logging.ERROR: int

Valor numérico 40. Utilizado para problemas graves.

logging.WARNING: int

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

logging.INFO: int

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

logging.DEBUG: int

Valor numérico 10. Utilizado 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 de WARNING).

Funções

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

Devolve o Logger registado com o nome name, criando-o na primeira utilização. Se name for None, é devolvido o logger raiz. A primeira chamada com name="root" (ou sem name definido) invoca implicitamente basicConfig para associar um StreamHandler predefinido que escreve em sys.stderr.

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

Regista uma mensagem no level indicado no logger raiz. Os args são interpolados em msg utilizando a formatação % no estilo printf; um único argumento dict é utilizado como 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). Regista a mensagem em ERROR e, adicionalmente, formata o traceback da exceção ativa quando exc_info for verdadeiro. Se exc_info for em si uma instância de BaseException, é utilizado o traceback dessa exceção; caso contrário, é consultado sys.exc_info() quando disponível.

logging.shutdown() → None

Fecha todos os handlers associados a todos os loggers conhecidos e esquece os loggers. Registado automaticamente via 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 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, é criado um FileHandler utilizando filemode e encoding; caso contrário, é utilizado um StreamHandler que escreve em stream (por omissão sys.stderr).

format e datefmt são passados diretamente a um novo Formatter.

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

Se o logger raiz já tiver handlers, esta função não tem efeito, exceto se force for True, caso em que os handlers existentes são fechados e substituídos.

Classes

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

Um logger com nome. Construa loggers via getLogger em vez de diretamente, para que getLogger possa devolver a mesma instância para o mesmo nome.

name: str

O nome pontilhado do logger.

level: int

O nível numérico configurado. 0 (NOTSET) significa «herdar».

handlers: list

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

setLevel(level: int) → None

Define o nível limiar do logger.

isEnabledFor(level: int) → bool

Devolve True se uma mensagem de level fosse processada por este logger.

getEffectiveLevel() → int

Devolve o primeiro valor não nulo entre: o nível deste logger, o nível do logger raiz, ou WARNING.

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

Regista msg em level. Os args são interpolados em msg com o operador %; se o primeiro argumento posicional for um dict, é utilizado como mapeamento.

debug(msg: str, *args) → None

Regista msg em DEBUG.

info(msg: str, *args) → None

Regista msg em INFO.

warning(msg: str, *args) → None

Regista msg em WARNING.

error(msg: str, *args) → None

Regista msg em ERROR.

critical(msg: str, *args) → None

Regista msg em CRITICAL.

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

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

addHandler(handler: Handler) → None

Associa handler a este logger.

hasHandlers() → bool

Devolve True se existirem handlers associados a este logger.

class logging.Handler(level: int = NOTSET)

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

level: int

O nível limiar do handler.

formatter: 'Formatter | None'

O Formatter ativo, ou None.

setLevel(level: int) → None

Define o nível limiar do handler.

setFormatter(formatter: Formatter) → None

Associa formatter a este handler.

format(record: LogRecord) → str

Renderiza record utilizando o formatter configurado.

close() → None

Liberta os recursos detidos pelo handler. Chamado por shutdown e por FileHandler quando é fechado.

class logging.StreamHandler(stream=None)

Handler que escreve registos formatados, seguidos de self.terminator ("\n" por omissão), em stream. stream tem como valor predefinido sys.stderr.

stream

O objeto stream de destino.

terminator: str

Cadeia acrescentada após cada registo formatado. Por omissão é "\n".

emit(record: LogRecord) → None

Escreve record em stream se o seu nível satisfizer o limiar do handler.

close() → None

Liberta o stream subjacente quando este 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 encoding indicados e escreve registos formatados. O ficheiro subjacente é fechado em close().

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

Renderiza instâncias de LogRecord como cadeias de caracteres.

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

datefmt é o modelo time.strftime utilizado para renderizar %(asctime)s. Por omissão é "%Y-%m-%d %H:%M:%S".

usesTime() → bool

Devolve True se o modelo de formato referenciar asctime.

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

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

format(record: LogRecord) → str

Renderiza record. Se o modelo utilizar asctime, formatTime() é invocado primeiro para preencher record.asctime.

class logging.LogRecord

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

name: str

O nome do logger de origem.

levelno: int

Nível numérico deste registo.

levelname: str

Nome textual do nível.

message: str

A mensagem de registo completamente formatada.

ct: float

Tempo de criação tal como devolvido por time.time().

msecs: int

Componente em milissegundos de ct.

asctime: str | None

Timestamp legível por humanos; preenchido de forma lazy por Formatter.

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

Inicializa o registo com os valores fornecidos e captura o tempo atual.