logging --- تسجيل الأحداث

توفر هذه الوحدة مجموعة فرعية خفيفة الوزن من حزمة logging القياسية في Python مُكيّفة لـ MicroPython. وهي تدعم التسجيل وفق المستويات من خلال كائنات Logger ذات أسماء هرمية، ومجموعة صغيرة من المعالِجات (StreamHandler وFileHandler)، والتنسيق بأسلوب printf عبر Formatter، إضافة إلى دوال مساعِدة على مستوى الوحدة تعادل تلك التي تعمل على المُسجِّل الجذر.

تتبع هذه الوحدة واجهة CPython المألوفة بدقة كافية بحيث ينبغي أن تعمل التطبيقات البسيطة المكتوبة للمكتبة القياسية دون أي تعديل. أما المُرشِّحات، وقفل تعدد العمليات، وصيغة ملف الإعداد، ومعظم أصناف المعالِجات فلا تُوفَّر.

ثوابت المستويات

logging.CRITICAL: int

القيمة العددية 50. تُستخدم للأخطاء غير القابلة للاسترداد.

logging.ERROR: int

القيمة العددية 40. تُستخدم للمشكلات الخطيرة.

logging.WARNING: int

القيمة العددية 30. المستوى الافتراضي لمُسجِّل جذر مُعَدّ حديثًا.

logging.INFO: int

القيمة العددية 20. تُستخدم لرسائل التأكيد.

logging.DEBUG: int

القيمة العددية 10. تُستخدم للمخرجات التشخيصية الدقيقة.

logging.NOTSET: int

القيمة العددية 0. تشير إلى مُسجِّل لم يُضبط له مستوى (يُورَّث المستوى الفعّال عندئذٍ من المُسجِّل الجذر أو من WARNING).

الدوال

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

تُرجِع Logger المسجَّل تحت الاسم name، وتُنشئه عند أول استخدام. إذا كان name يساوي None فيُرجَع المُسجِّل الجذر. ويستدعي أول نداء بـ name="root" (أو مع ترك name غير محدد) ضمنيًا الدالة basicConfig لإرفاق StreamHandler افتراضي يكتب إلى sys.stderr.

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

تُسجِّل رسالة عند المستوى level على المُسجِّل الجذر. تُدمَج args داخل msg باستخدام التنسيق بأسلوب printf عبر %؛ ويُستخدَم وسيط القاموس المفرد كخريطة.

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 ويُنسِّق إضافةً إلى ذلك أثر الاستثناء النشط عندما تكون exc_info صادقة. وإذا كانت exc_info نفسها كائن BaseException فيُستخدَم أثر ذلك الاستثناء؛ وإلا فيُرجَع إلى sys.exc_info() عند توافرها.

logging.shutdown() → None

تُغلق كل معالِج مُرفَق بكل مُسجِّل معروف وتنسى المُسجِّلات. يُسجَّل تلقائيًا عبر sys.atexit عند توافر ذلك الخطّاف.

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

تُعِدّ المُسجِّل الجذر بمعالِج واحد.

إذا قُدِّم filename فيُنشأ FileHandler باستخدام filemode وencoding؛ وإلا فيُستخدَم StreamHandler يكتب إلى stream (الافتراضي sys.stderr).

يُمرَّر format وdatefmt إلى Formatter جديد.

يضبط level مستوى المعالِج ومستوى المُسجِّل الجذر معًا.

إذا كان المُسجِّل الجذر يملك بالفعل معالِجات فلا تفعل هذه الدالة شيئًا، إلا إذا كان force يساوي True، وفي هذه الحالة تُغلق المعالِجات الموجودة وتُستبدل.

الأصناف

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

مُسجِّل ذو اسم. أنشئ المُسجِّلات عبر getLogger بدلًا من إنشائها مباشرةً، حتى تتمكن getLogger من إرجاع النسخة نفسها للاسم نفسه.

name: str

الاسم المنقَّط للمُسجِّل.

level: int

المستوى العددي المُعَدّ. القيمة 0 (NOTSET) تعني "وراثة".

handlers: list

قائمة نُسخ Handler المُرفَقة بهذا المُسجِّل. وعندما تكون فارغة، تُرسَل الرسائل إلى معالِجات المُسجِّل الجذر.

setLevel(level: int) → None

يضبط مستوى عتبة المُسجِّل.

isEnabledFor(level: int) → bool

تُرجِع True إذا كانت رسالة عند المستوى level ستُعالَج بواسطة هذا المُسجِّل.

getEffectiveLevel() → int

تُرجِع أول قيمة غير صفرية من بين: مستوى هذا المُسجِّل، أو مستوى المُسجِّل الجذر، أو WARNING.

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

تُسجِّل msg عند المستوى level. تُدمَج args داخل msg باستخدام عامل %؛ وإذا كان الوسيط الموضعي الأول قاموسًا فيُستخدَم كخريطة.

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 صادقة. وإذا كانت exc_info نسخة من BaseException فيُعرَض أثر ذلك الاستثناء؛ وإلا فيُرجَع إلى الاستثناء النشط عبر sys.exc_info().

addHandler(handler: Handler) → None

تُرفِق handler بهذا المُسجِّل.

hasHandlers() → bool

تُرجِع True إذا كان أي معالِج مُرفَقًا بهذا المُسجِّل.

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 باستخدام المُنسِّق المُعَدّ.

close() → None

يحرِّر الموارد التي يحتفظ بها المعالِج. تُستدعى من shutdown ومن FileHandler عند إغلاقه.

class logging.StreamHandler(stream=None)

معالِج يكتب السجلات المُنسَّقة، متبوعةً بـ self.terminator (وقيمته الافتراضية "\n")، إلى stream. القيمة الافتراضية لـ stream هي sys.stderr.

stream

كائن مجرى الوجهة.

terminator: str

سلسلة تُلحَق بعد كل سجل مُنسَّق. قيمتها الافتراضية "\n".

emit(record: LogRecord) → None

يكتب record إلى stream إذا كان مستواه يفي بعتبة المعالِج.

close() → None

يدفق المجرى الأساسي عندما يوفِّر دالة 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()؛ وتعيد تطبيقات المُسجِّل استخدام سجل واحد لكل مُسجِّل لتقليل التخصيصات.

name: str

اسم المُسجِّل المصدري.

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

تُهيّئ السجل بالقيم المُعطاة وتلتقط الوقت الحالي.