logging --- การบันทึกเหตุการณ์

โมดูลนี้ให้ชุดย่อยที่มีน้ำหนักเบาของแพ็กเกจ logging มาตรฐานของ Python ที่ปรับแต่งสำหรับ MicroPython รองรับการบันทึกแบบมีระดับผ่านออบเจ็กต์ Logger ที่ตั้งชื่อตามลำดับชั้น ตัวจัดการขนาดเล็กจำนวนหนึ่ง (StreamHandler, FileHandler) การจัดรูปแบบสไตล์ printf ผ่าน Formatter และฟังก์ชันอำนวยความสะดวกระดับโมดูลที่เทียบเท่ากับฟังก์ชันที่ทำงานบน root logger

โมดูลนี้ปฏิบัติตาม API ของ CPython ที่คุ้นเคยอย่างใกล้ชิดพอที่แอปพลิเคชันอย่างง่ายที่เขียนสำหรับไลบรารีมาตรฐานควรทำงานได้โดยไม่ต้องเปลี่ยนแปลง ไม่มีการให้บริการ Filters การล็อกหลายกระบวนการ รูปแบบไฟล์การกำหนดค่า และคลาสตัวจัดการส่วนใหญ่

ค่าคงที่ระดับ

logging.CRITICAL: int

ค่าตัวเลข 50 ใช้สำหรับข้อผิดพลาดที่ไม่สามารถกู้คืนได้

logging.ERROR: int

ค่าตัวเลข 40 ใช้สำหรับปัญหาร้ายแรง

logging.WARNING: int

ค่าตัวเลข 30 ระดับเริ่มต้นสำหรับ root logger ที่เพิ่งกำหนดค่า

logging.INFO: int

ค่าตัวเลข 20 ใช้สำหรับข้อความยืนยัน

logging.DEBUG: int

ค่าตัวเลข 10 ใช้สำหรับผลลัพธ์การวิเคราะห์ปัญหาแบบละเอียด

logging.NOTSET: int

ค่าตัวเลข 0 ระบุว่า logger ไม่มีการกำหนดระดับ (จะสืบทอดระดับที่มีผลจาก root logger หรือ WARNING)

ฟังก์ชัน

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

คืนค่า Logger ที่ลงทะเบียนไว้ภายใต้ name โดยสร้างขึ้นในการใช้งานครั้งแรก หาก name เป็น None จะคืนค่า root logger การเรียกครั้งแรกด้วย name="root" (หรือโดยไม่ตั้ง name) จะเรียก basicConfig โดยอัตโนมัติเพื่อแนบ StreamHandler เริ่มต้นที่เขียนไปยัง sys.stderr

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

บันทึกข้อความที่ระดับ level บน root logger args จะถูกแทรกเข้าไปใน msg โดยใช้การจัดรูปแบบ % แบบ printf; อาร์กิวเมนต์ dict เดียวจะถูกใช้เป็น mapping

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

เทียบเท่ากับ getLogger().debug(msg, *args)

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

เทียบเท่ากับ getLogger().info(msg, *args)

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

เทียบเท่ากับ getLogger().warning(msg, *args)

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

เทียบเท่ากับ getLogger().error(msg, *args)

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

เทียบเท่ากับ getLogger().critical(msg, *args)

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

เทียบเท่ากับ getLogger().exception(msg, *args, exc_info=exc_info) บันทึกข้อความที่ ERROR และจัดรูปแบบ traceback ของข้อยกเว้นที่ใช้งานอยู่เพิ่มเติมเมื่อ exc_info มีค่าเป็นจริง หาก exc_info เป็นอินสแตนซ์ BaseException จะใช้ traceback ของข้อยกเว้นนั้น มิฉะนั้นจะอ้างอิง sys.exc_info() เมื่อใช้งานได้

logging.shutdown() → None

ปิด handler ทุกตัวที่แนบอยู่กับ logger ทุกตัวที่รู้จักและลืม logger เหล่านั้น ลงทะเบียนโดยอัตโนมัติผ่าน sys.atexit เมื่อมี hook นั้นพร้อมใช้งาน

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

เชื่อมโยง name ที่เป็นข้อความกับ level ที่เป็นตัวเลข เพื่อให้ Formatter แสดงผลผ่าน %(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

กำหนดค่า root logger ด้วย handler เดียว

หาก filename ถูกกำหนด จะสร้าง FileHandler โดยใช้ filemode และ encoding; มิฉะนั้นจะใช้ StreamHandler ที่เขียนไปยัง stream (ค่าเริ่มต้นคือ sys.stderr)

format และ datefmt จะถูกส่งผ่านไปยัง Formatter ใหม่

level กำหนดทั้งระดับของ handler และระดับของ root logger

หาก root logger มี handler อยู่แล้ว ฟังก์ชันนี้จะไม่ทำอะไร เว้นแต่ force จะเป็น True ซึ่งในกรณีนี้ handler ที่มีอยู่จะถูกปิดและแทนที่

คลาส

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

Logger ที่มีชื่อ สร้าง logger ผ่าน getLogger แทนที่จะสร้างโดยตรง เพื่อให้ getLogger สามารถคืนค่าอินสแตนซ์เดียวกันสำหรับชื่อเดียวกัน

name: str

ชื่อที่คั่นด้วยจุดของ logger

level: int

ระดับตัวเลขที่กำหนดค่าไว้ 0 (NOTSET) หมายถึง "สืบทอด"

handlers: list

รายการอินสแตนซ์ Handler ที่แนบอยู่กับ logger นี้ เมื่อว่างเปล่า ข้อความจะถูกส่งไปยัง handler ของ root logger

setLevel(level: int) → None

กำหนดระดับ threshold ของ logger

isEnabledFor(level: int) → bool

คืนค่า True หากข้อความที่มีระดับ level จะถูกประมวลผลโดย logger นี้

getEffectiveLevel() → int

คืนค่าแรกที่ไม่ใช่ศูนย์จาก: ระดับของ logger นี้, ระดับของ root logger หรือ WARNING

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

บันทึก msg ที่ระดับ level args จะถูกแทรกเข้าไปใน msg ด้วยตัวดำเนินการ %; หากอาร์กิวเมนต์ตำแหน่งแรกเป็น dict จะถูกใช้เป็น mapping

debug(msg: str, *args) → None

บันทึก msg ที่ DEBUG

info(msg: str, *args) → None

บันทึก msg ที่ INFO

warning(msg: str, *args) → None

บันทึก msg ที่ WARNING

error(msg: str, *args) → None

บันทึก msg ที่ ERROR

critical(msg: str, *args) → None

บันทึก msg ที่ CRITICAL

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

บันทึก msg ที่ ERROR และเมื่อ exc_info มีค่าเป็นจริง จะต่อท้าย traceback ที่จัดรูปแบบแล้ว หาก exc_info เป็นอินสแตนซ์ BaseException traceback ของข้อยกเว้นนั้นจะถูกแสดงผล มิฉะนั้นจะอ้างอิงข้อยกเว้นที่ใช้งานอยู่ผ่าน sys.exc_info()

addHandler(handler: Handler) → None

แนบ handler กับ logger นี้

hasHandlers() → bool

คืนค่า True หาก handler ใดถูกแนบอยู่กับ logger นี้

class logging.Handler(level: int = NOTSET)

คลาสฐานสำหรับ handler ทุกตัว คลาสย่อยต้องสร้าง emit()

level: int

ระดับ threshold ของ handler

formatter: 'Formatter | None'

Formatter ที่ใช้งานอยู่ หรือ None

setLevel(level: int) → None

กำหนดระดับ threshold ของ handler

setFormatter(formatter: Formatter) → None

แนบ formatter กับ handler นี้

format(record: LogRecord) → str

แสดงผล record โดยใช้ formatter ที่กำหนดค่าไว้

close() → None

ปลดปล่อยทรัพยากรที่ handler ถือครอง เรียกโดย shutdown และโดย FileHandler เมื่อถูกปิด

class logging.StreamHandler(stream=None)

Handler ที่เขียนระเบียนที่จัดรูปแบบแล้ว ตามด้วย self.terminator (ค่าเริ่มต้นคือ "\n") ไปยัง stream stream ค่าเริ่มต้นคือ sys.stderr

stream

ออบเจ็กต์ stream ปลายทาง

terminator: str

สตริงที่ต่อท้ายหลังจากระเบียนที่จัดรูปแบบแล้วทุกรายการ ค่าเริ่มต้นคือ "\n"

emit(record: LogRecord) → None

เขียน record ไปยัง stream หากระดับของมันตรงตามเกณฑ์ threshold ของ handler

close() → None

Flush stream ที่อยู่ด้านล่างเมื่อมันเปิดเผยเมธอด flush

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

คลาสย่อยของ StreamHandler ที่เปิด filename ด้วย mode และ encoding ที่กำหนดและเขียนระเบียนที่จัดรูปแบบแล้วลงไป ไฟล์ที่อยู่ด้านล่างจะถูกปิดเมื่อ close()

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

แสดงผลอินสแตนซ์ LogRecord เป็นสตริง

fmt คือเทมเพลตสไตล์ printf คีย์ที่รับรู้ได้คือ %(name)s, %(message)s, %(msecs)d, %(asctime)s และ %(levelname)s เมื่อไม่ได้กำหนดจะค่าเริ่มต้นเป็น "%(levelname)s:%(name)s:%(message)s"

datefmt คือเทมเพลต time.strftime ที่ใช้แสดงผล %(asctime)s ค่าเริ่มต้นคือ "%Y-%m-%d %H:%M:%S"

usesTime() → bool

คืนค่า True หากเทมเพลตรูปแบบอ้างอิงถึง asctime

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

จัดรูปแบบ record.ct โดยใช้ time.strftime และ datefmt คืนค่า None บนแพลตฟอร์มที่ time.strftime ไม่พร้อมใช้งาน

format(record: LogRecord) → str

แสดงผล record หากเทมเพลตใช้ asctime จะเรียก formatTime() ก่อนเพื่อเติมข้อมูลใน record.asctime

class logging.LogRecord

คอนเทนเนอร์สำหรับข้อมูลที่ส่งจาก Logger ไปยัง handler ของมัน อินสแตนซ์จะถูกเติมข้อมูลผ่าน set(); การสร้าง logger จะนำระเบียนเดียวกลับมาใช้ต่อ logger เพื่อลดการจัดสรรหน่วยความจำ

name: str

ชื่อของ logger ต้นทาง

levelno: int

ระดับตัวเลขของระเบียนนี้

levelname: str

ชื่อระดับที่เป็นข้อความ

message: str

ข้อความ log ที่จัดรูปแบบเต็มรูปแบบ

ct: float

เวลาที่สร้างตามที่คืนค่าโดย time.time()

msecs: int

ส่วนประกอบมิลลิวินาทีของ ct

asctime: str | None

timestamp ที่อ่านได้โดยมนุษย์ เติมข้อมูลแบบ lazy โดย Formatter

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

เริ่มต้นระเบียนด้วยค่าที่กำหนดและบันทึกเวลาปัจจุบัน