logging --- ghi nhật ký sự kiện

Mô-đun này cung cấp một tập hợp con nhẹ của gói logging chuẩn trong Python, được điều chỉnh cho MicroPython. Nó hỗ trợ ghi nhật ký theo cấp độ thông qua các đối tượng Logger được đặt tên theo phân cấp, một số lượng nhỏ các trình xử lý (StreamHandler, FileHandler), định dạng kiểu printf qua Formatter, và các hàm tiện lợi ở cấp mô-đun tương đương với các hàm hoạt động trên logger gốc.

Mô-đun này tuân theo API CPython quen thuộc đủ chặt chẽ để các ứng dụng đơn giản được viết cho thư viện chuẩn hoạt động mà không cần thay đổi. Bộ lọc, khóa đa tiến trình, định dạng tệp cấu hình và hầu hết các lớp trình xử lý không được cung cấp.

Hằng số cấp độ

logging.CRITICAL: int

Giá trị số 50. Dùng cho các lỗi không thể phục hồi.

logging.ERROR: int

Giá trị số 40. Dùng cho các vấn đề nghiêm trọng.

logging.WARNING: int

Giá trị số 30. Cấp độ mặc định cho logger gốc mới được cấu hình.

logging.INFO: int

Giá trị số 20. Dùng cho các thông báo xác nhận.

logging.DEBUG: int

Giá trị số 10. Dùng cho đầu ra chẩn đoán chi tiết.

logging.NOTSET: int

Giá trị số 0. Chỉ ra một logger không có cấp độ được cấu hình (khi đó cấp độ hiệu lực được kế thừa từ logger gốc hoặc WARNING).

Hàm

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

Trả về Logger đã đăng ký với tên name, tạo mới khi sử dụng lần đầu. Nếu name là None thì trả về logger gốc. Lần gọi đầu tiên với name="root" (hoặc với name không được đặt) sẽ ngầm gọi basicConfig để gắn StreamHandler mặc định ghi vào sys.stderr.

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

Ghi một thông báo ở level trên logger gốc. args được nội suy vào msg bằng định dạng printf kiểu %; một đối số dict đơn lẻ được dùng làm ánh xạ.

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

Tương đương với getLogger().debug(msg, *args).

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

Tương đương với getLogger().info(msg, *args).

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

Tương đương với getLogger().warning(msg, *args).

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

Tương đương với getLogger().error(msg, *args).

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

Tương đương với getLogger().critical(msg, *args).

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

Tương đương với getLogger().exception(msg, *args, exc_info=exc_info). Ghi thông báo ở ERROR và bổ sung định dạng traceback của ngoại lệ đang hoạt động khi exc_info có giá trị đúng. Nếu exc_info chính là một BaseException, traceback của ngoại lệ đó được sử dụng; ngược lại sys.exc_info() được tham khảo khi có sẵn.

logging.shutdown() → None

Đóng mọi trình xử lý gắn với mọi logger đã biết và xóa các logger đó. Được đăng ký tự động qua sys.atexit khi hook đó có sẵn.

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

Liên kết name dạng văn bản với level dạng số để Formatter có thể hiển thị nó qua %(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

Cấu hình logger gốc với một trình xử lý duy nhất.

Nếu filename được cung cấp, một FileHandler được tạo bằng filemode và encoding; ngược lại một StreamHandler ghi vào stream (mặc định là sys.stderr) được sử dụng.

format và datefmt được truyền đến một Formatter mới.

level đặt cả cấp độ của trình xử lý và cấp độ của logger gốc.

Nếu logger gốc đã có các trình xử lý, hàm này là no-op trừ khi force là True, trong trường hợp đó các trình xử lý hiện tại được đóng và thay thế.

Lớp

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

Một logger được đặt tên. Khởi tạo các logger qua getLogger thay vì trực tiếp, để getLogger có thể trả về cùng một thực thể cho cùng một tên.

name: str

Tên có dấu chấm của logger.

level: int

Cấp độ số được cấu hình. 0 (NOTSET) nghĩa là "kế thừa".

handlers: list

Danh sách các thực thể Handler gắn với logger này. Khi trống, thông báo được gửi đến các trình xử lý của logger gốc.

setLevel(level: int) → None

Đặt ngưỡng cấp độ của logger.

isEnabledFor(level: int) → bool

Trả về True nếu một thông báo ở level sẽ được xử lý bởi logger này.

getEffectiveLevel() → int

Trả về giá trị khác không đầu tiên trong số: cấp độ của logger này, cấp độ của logger gốc, hoặc WARNING.

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

Ghi msg ở level. args được nội suy vào msg bằng toán tử %; nếu đối số vị trí đầu tiên là dict thì nó được dùng làm ánh xạ.

debug(msg: str, *args) → None

Ghi msg ở DEBUG.

info(msg: str, *args) → None

Ghi msg ở INFO.

warning(msg: str, *args) → None

Ghi msg ở WARNING.

error(msg: str, *args) → None

Ghi msg ở ERROR.

critical(msg: str, *args) → None

Ghi msg ở CRITICAL.

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

Ghi msg ở ERROR và, khi exc_info có giá trị đúng, thêm vào traceback đã được định dạng. Nếu exc_info là một thực thể BaseException thì traceback của ngoại lệ đó được hiển thị; ngược lại ngoại lệ đang hoạt động được tham khảo qua sys.exc_info().

addHandler(handler: Handler) → None

Gắn handler vào logger này.

hasHandlers() → bool

Trả về True nếu có bất kỳ trình xử lý nào được gắn vào logger này.

class logging.Handler(level: int = NOTSET)

Lớp cơ sở cho tất cả các trình xử lý. Các lớp con triển khai emit().

level: int

Ngưỡng cấp độ của trình xử lý.

formatter: 'Formatter | None'

Formatter đang hoạt động, hoặc None.

setLevel(level: int) → None

Đặt ngưỡng cấp độ của trình xử lý.

setFormatter(formatter: Formatter) → None

Gắn formatter vào trình xử lý này.

format(record: LogRecord) → str

Hiển thị record bằng formatter đã cấu hình.

close() → None

Giải phóng tài nguyên do trình xử lý nắm giữ. Được gọi bởi shutdown và bởi FileHandler khi nó được đóng.

class logging.StreamHandler(stream=None)

Trình xử lý ghi các bản ghi đã định dạng, theo sau là self.terminator ("\n" theo mặc định), vào stream. stream mặc định là sys.stderr.

stream

Đối tượng luồng đích.

terminator: str

Chuỗi được thêm vào sau mỗi bản ghi đã định dạng. Mặc định là "\n".

emit(record: LogRecord) → None

Ghi record vào stream nếu cấp độ của nó đáp ứng ngưỡng của trình xử lý.

close() → None

Xả dữ liệu từ luồng bên dưới khi nó có phương thức flush.

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

Lớp con của StreamHandler mở filename với mode và encoding cho trước, và ghi các bản ghi đã định dạng vào đó. Tệp bên dưới được đóng khi gọi close().

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

Hiển thị các thực thể LogRecord thành chuỗi.

fmt là mẫu kiểu printf. Các khóa được nhận biết là %(name)s, %(message)s, %(msecs)d, %(asctime)s và %(levelname)s. Khi không được đặt, mặc định là "%(levelname)s:%(name)s:%(message)s".

datefmt là mẫu time.strftime dùng để hiển thị %(asctime)s. Mặc định là "%Y-%m-%d %H:%M:%S".

usesTime() → bool

Trả về True nếu mẫu định dạng tham chiếu đến asctime.

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

Định dạng record.ct bằng time.strftime và datefmt. Trả về None trên các nền tảng không có time.strftime.

format(record: LogRecord) → str

Hiển thị record. Nếu mẫu sử dụng asctime, formatTime() được gọi trước để điền record.asctime.

class logging.LogRecord

Container cho dữ liệu được truyền từ một Logger đến các trình xử lý của nó. Các thực thể được điền qua set(); các triển khai logger tái sử dụng một bản ghi duy nhất cho mỗi logger để giảm việc cấp phát bộ nhớ.

name: str

Tên của logger nguồn.

levelno: int

Cấp độ số của bản ghi này.

levelname: str

Tên cấp độ dạng văn bản.

message: str

Thông báo nhật ký đã được định dạng đầy đủ.

ct: float

Thời gian tạo như được trả về bởi time.time().

msecs: int

Thành phần mili giây của ct.

asctime: str | None

Dấu thời gian có thể đọc được; được điền chậm (lazy) bởi Formatter.

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

Khởi tạo bản ghi với các giá trị cho trước và ghi lại thời gian hiện tại.