logging --- pencatatan peristiwa

Modul ini menyediakan subset ringan dari paket logging standar Python yang diadaptasi untuk MicroPython. Modul ini mendukung pencatatan bertingkat melalui objek Logger yang dinamai secara hierarkis, sejumlah kecil handler (StreamHandler, FileHandler), pemformatan gaya printf melalui Formatter, dan fungsi kemudahan tingkat modul yang setara dengan yang beroperasi pada logger akar.

Modul ini mengikuti API CPython yang familiar dengan cukup dekat sehingga aplikasi sederhana yang ditulis untuk pustaka standar seharusnya berfungsi tanpa perubahan. Filter, penguncian multi-proses, format file konfigurasi, dan sebagian besar kelas handler tidak disediakan.

Konstanta Level

logging.CRITICAL: int

Nilai numerik 50. Digunakan untuk kesalahan yang tidak dapat dipulihkan.

logging.ERROR: int

Nilai numerik 40. Digunakan untuk masalah serius.

logging.WARNING: int

Nilai numerik 30. Level default untuk logger akar yang baru dikonfigurasi.

logging.INFO: int

Nilai numerik 20. Digunakan untuk pesan konfirmasi.

logging.DEBUG: int

Nilai numerik 10. Digunakan untuk keluaran diagnostik terperinci.

logging.NOTSET: int

Nilai numerik 0. Menunjukkan logger tanpa level yang dikonfigurasi (level efektif kemudian diwarisi dari logger akar atau WARNING).

Fungsi

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

Kembalikan Logger yang terdaftar dengan nama name, buat pada penggunaan pertama. Jika name adalah None, logger akar dikembalikan. Panggilan pertama dengan name="root" (atau dengan name tidak diset) secara implisit memanggil basicConfig untuk melampirkan StreamHandler default yang menulis ke sys.stderr.

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

Catat pesan pada level di logger akar. args diinterpolasi ke dalam msg menggunakan pemformatan % gaya printf; satu argumen dict digunakan sebagai pemetaan.

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

Setara dengan getLogger().debug(msg, *args).

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

Setara dengan getLogger().info(msg, *args).

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

Setara dengan getLogger().warning(msg, *args).

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

Setara dengan getLogger().error(msg, *args).

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

Setara dengan getLogger().critical(msg, *args).

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

Setara dengan getLogger().exception(msg, *args, exc_info=exc_info). Mencatat pesan pada ERROR dan secara tambahan memformat traceback pengecualian aktif ketika exc_info bernilai truthy. Jika exc_info itu sendiri adalah BaseException, traceback pengecualian tersebut digunakan; jika tidak, sys.exc_info() dikonsultasikan bila tersedia.

logging.shutdown() → None

Tutup setiap handler yang dilampirkan ke setiap logger yang dikenal dan lupakan logger tersebut. Didaftarkan secara otomatis melalui sys.atexit ketika hook tersebut tersedia.

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

Kaitkan nama tekstual name dengan level numerik level sehingga Formatter dapat merendernya melalui %(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

Konfigurasikan logger akar dengan satu handler.

Jika filename diberikan, sebuah FileHandler dibuat menggunakan filemode dan encoding; jika tidak, sebuah StreamHandler yang menulis ke stream (default ke sys.stderr) digunakan.

format dan datefmt diteruskan ke Formatter baru.

level mengatur level handler dan level logger akar.

Jika logger akar sudah memiliki handler, fungsi ini adalah no-op kecuali jika force adalah True, dalam hal ini handler yang ada ditutup dan diganti.

Kelas

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

Logger bernama. Buat logger melalui getLogger daripada secara langsung, sehingga getLogger dapat mengembalikan instans yang sama untuk nama yang sama.

name: str

Nama bertitik logger.

level: int

Level numerik yang dikonfigurasi. 0 (NOTSET) berarti "warisi".

handlers: list

Daftar instans Handler yang dilampirkan ke logger ini. Bila kosong, pesan dikirimkan ke handler logger akar.

setLevel(level: int) → None

Tetapkan level ambang batas logger.

isEnabledFor(level: int) → bool

Kembalikan True jika pesan dengan level akan diproses oleh logger ini.

getEffectiveLevel() → int

Kembalikan nilai pertama yang bukan nol dari: level logger ini, level logger akar, atau WARNING.

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

Catat msg pada level. args diinterpolasi ke dalam msg dengan operator %; jika argumen posisional pertama adalah dict, maka digunakan sebagai pemetaan.

debug(msg: str, *args) → None

Catat msg pada DEBUG.

info(msg: str, *args) → None

Catat msg pada INFO.

warning(msg: str, *args) → None

Catat msg pada WARNING.

error(msg: str, *args) → None

Catat msg pada ERROR.

critical(msg: str, *args) → None

Catat msg pada CRITICAL.

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

Catat msg pada ERROR dan, ketika exc_info bernilai truthy, tambahkan traceback yang diformat. Jika exc_info adalah instans BaseException, traceback pengecualian tersebut dirender; jika tidak, pengecualian aktif dikonsultasikan melalui sys.exc_info().

addHandler(handler: Handler) → None

Lampirkan handler ke logger ini.

hasHandlers() → bool

Kembalikan True jika ada handler yang dilampirkan ke logger ini.

class logging.Handler(level: int = NOTSET)

Kelas dasar untuk semua handler. Sub-kelas mengimplementasikan emit().

level: int

Level ambang batas handler.

formatter: 'Formatter | None'

Formatter aktif, atau None.

setLevel(level: int) → None

Tetapkan level ambang batas handler.

setFormatter(formatter: Formatter) → None

Lampirkan formatter ke handler ini.

format(record: LogRecord) → str

Render record menggunakan formatter yang dikonfigurasi.

close() → None

Lepaskan sumber daya yang dipegang oleh handler. Dipanggil oleh shutdown dan oleh FileHandler ketika ditutup.

class logging.StreamHandler(stream=None)

Handler yang menulis rekaman terformat, diikuti oleh self.terminator ("\n" secara default), ke stream. stream default ke sys.stderr.

stream

Objek stream tujuan.

terminator: str

String yang ditambahkan setelah setiap rekaman terformat. Default ke "\n".

emit(record: LogRecord) → None

Tulis record ke stream jika levelnya memenuhi ambang batas handler.

close() → None

Siram stream yang mendasarinya ketika memaparkan metode flush.

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

Subkelas StreamHandler yang membuka filename dengan mode dan encoding yang diberikan dan menulis rekaman terformat ke dalamnya. File yang mendasarinya ditutup pada close().

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

Render instans LogRecord menjadi string.

fmt adalah template gaya printf. Kunci yang dikenali adalah %(name)s, %(message)s, %(msecs)d, %(asctime)s, dan %(levelname)s. Bila tidak diset, default ke "%(levelname)s:%(name)s:%(message)s".

datefmt adalah template time.strftime yang digunakan untuk merender %(asctime)s. Default ke "%Y-%m-%d %H:%M:%S".

usesTime() → bool

Kembalikan True jika template format merujuk ke asctime.

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

Format record.ct menggunakan time.strftime dan datefmt. Mengembalikan None pada platform di mana time.strftime tidak tersedia.

format(record: LogRecord) → str

Render record. Jika template menggunakan asctime, formatTime() dipanggil terlebih dahulu untuk mengisi record.asctime.

class logging.LogRecord

Wadah untuk data yang diteruskan dari Logger ke handler-nya. Instans diisi melalui set(); implementasi logger menggunakan kembali satu rekaman per logger untuk mengurangi alokasi.

name: str

Nama logger asal.

levelno: int

Level numerik rekaman ini.

levelname: str

Nama level tekstual.

message: str

Pesan log yang sepenuhnya diformat.

ct: float

Waktu pembuatan yang dikembalikan oleh time.time().

msecs: int

Komponen milidetik dari ct.

asctime: str | None

Timestamp yang dapat dibaca manusia; diisi secara malas oleh Formatter.

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

Inisialisasi rekaman dengan nilai yang diberikan dan ambil waktu saat ini.