logging — רישום אירועים

מודול זה מספק תת-קבוצה קלת-משקל של חבילת ה-logging הסטנדרטית של Python, מותאמת ל-MicroPython. הוא תומך ברישום לפי רמות באמצעות אובייקטי Logger בעלי שמות היררכיים, אוסף קטן של מטפלים (StreamHandler, FileHandler), עיצוב בסגנון printf באמצעות Formatter, ופונקציות נוחות ברמת המודול המקבילות לאלו הפועלות על ה-logger השורשי.

המודול עוקב אחר ה-API המוכר של CPython בצורה קרובה מספיק כך שיישומים פשוטים שנכתבו עבור הספרייה הסטנדרטית אמורים לעבוד ללא שינוי. מסננים, נעילה רב-תהליכית, פורמט קובץ התצורה ורוב מחלקות המטפלים אינם מסופקים.

קבועי רמות

logging.CRITICAL: int

ערך מספרי 50. משמש לשגיאות בלתי ניתנות לשחזור.

logging.ERROR: int

ערך מספרי 40. משמש לבעיות חמורות.

logging.WARNING: int

ערך מספרי 30. רמת ברירת המחדל עבור logger שורשי שזה עתה הוגדר.

logging.INFO: int

ערך מספרי 20. משמש להודעות אישור.

logging.DEBUG: int

ערך מספרי 10. משמש לפלט אבחון מפורט.

logging.NOTSET: int

ערך מספרי 0. מציין logger ללא רמה מוגדרת (הרמה האפקטיבית נורשת אז מה-logger השורשי או WARNING).

פונקציות

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

מחזירה את ה-Logger הרשום תחת name, ויוצרת אותו בשימוש הראשון. אם name הוא None מוחזר ה-logger השורשי. הקריאה הראשונה עם name="root" (או עם name שאינו מוגדר) מפעילה באופן מרומז את basicConfig כדי לצרף StreamHandler ברירת מחדל הכותב אל sys.stderr.

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

רושמת הודעה ברמה level על ה-logger השורשי. args משולבים לתוך msg באמצעות עיצוב % בסגנון printf; ארגומנט dict בודד משמש כמיפוי.

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

סוגרת כל מטפל המצורף לכל logger ידוע ומשכיחה את ה-loggers. נרשמת אוטומטית באמצעות 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

מגדירה את ה-logger השורשי עם מטפל יחיד.

אם filename מסופק נוצר FileHandler תוך שימוש ב-filemode וב-encoding; אחרת נעשה שימוש ב-StreamHandler הכותב אל stream (ברירת המחדל היא sys.stderr).

format ו-datefmt מועברים ל-Formatter חדש.

level קובע הן את רמת המטפל והן את רמת ה-logger השורשי.

אם ל-logger השורשי כבר יש מטפלים, פונקציה זו אינה עושה דבר אלא אם force הוא True, ובמקרה זה המטפלים הקיימים נסגרים ומוחלפים.

מחלקות

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

logger בעל שם. בנו loggers באמצעות getLogger ולא ישירות, כך ש-getLogger יוכל להחזיר את אותה מופע עבור אותו שם.

name: str

השם המנוקד של ה-logger.

level: int

הרמה המספרית המוגדרת. 0 (NOTSET) משמעו ”לרשת“.

handlers: list

רשימת מופעי ה-Handler המצורפים ל-logger זה. כאשר היא ריקה, הודעות נשלחות למטפלים של ה-logger השורשי.

setLevel(level: int) → None

מגדירה את רמת הסף של ה-logger.

isEnabledFor(level: int) → bool

מחזירה True אם הודעה ברמה level תעובד על ידי logger זה.

getEffectiveLevel() → int

מחזירה את הראשון שאינו אפס מבין: רמת ה-logger הזה, רמת ה-logger השורשי, או WARNING.

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

רושמת msg ברמה level. args משולבים לתוך msg באמצעות אופרטור ה-%; אם הארגומנט המיקומי הראשון הוא dict הוא משמש כמיפוי.

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 אם מצורפים ל-logger זה מטפלים כלשהם.

class logging.Handler(level: int = NOTSET)

מחלקת בסיס לכל המטפלים. תת-מחלקות מממשות את emit().

level: int

רמת הסף של המטפל.

formatter: 'Formatter | None'

ה-Formatter הפעיל, או None.

setLevel(level: int) → None

מגדירה את רמת הסף של המטפל.

setFormatter(formatter: Formatter) → None

מצרפת את formatter למטפל זה.

format(record: LogRecord) → str

מציגה את record באמצעות ה-formatter המוגדר.

close() → None

משחררת משאבים המוחזקים על ידי המטפל. נקראת על ידי shutdown ועל ידי FileHandler כאשר הוא נסגר.

class logging.StreamHandler(stream=None)

מטפל הכותב רשומות מעוצבות, ואחריהן self.terminator ("\n" כברירת מחדל), אל stream. ברירת המחדל של stream היא sys.stderr.

stream

אובייקט ה-stream של היעד.

terminator: str

מחרוזת המצורפת אחרי כל רשומה מעוצבת. ברירת המחדל היא "\n".

emit(record: LogRecord) → None

כותבת את record אל stream אם רמתו עומדת בסף המטפל.

close() → None

מרוקנת את ה-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 למטפלים שלו. מופעים מאוכלסים באמצעות set(); מימושי logger משתמשים מחדש ברשומה יחידה לכל logger כדי להפחית הקצאות.

name: str

שם ה-logger שממנו מקורה הרשומה.

levelno: int

הרמה המספרית של רשומה זו.

levelname: str

שם הרמה הטקסטואלי.

message: str

הודעת היומן המעוצבת במלואה.

ct: float

זמן היצירה כפי שמוחזר על ידי time.time().

msecs: int

רכיב המילישניות של ct.

asctime: str | None

חותמת זמן קריאה לאדם; מאוכלסת באופן עצל על ידי Formatter.

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

מאתחלת את הרשומה עם הערכים הנתונים ולוכדת את הזמן הנוכחי.