logging --- امکان ثبت رویدادها برای پایتون

کد منبع: Lib/logging/__init__.py

Important

این صفحه شامل اطلاعات مرجع API است. برای اطلاعات آموزشی و بحث در مورد موضوعات پیشرفته‌تر، ببینید

• آموزش مقدماتی

• آموزش پیشرفته

• کتابچه‌ی گزارش‌گیری (Logging Cookbook)

---

این ماژول توابع و کلاس‌هایی را تعریف می‌کند که یک سیستم ثبت رویداد انعطاف‌پذیر برای برنامه‌ها و کتابخانه‌ها را پیاده‌سازی می‌کنند.

مزیت اصلی ارائه شدن API گزارش‌گیری توسط یک ماژول از کتابخانه استاندارد این است که تمام ماژول‌های پایتون می‌توانند در گزارش‌گیری مشارکت کنند، بنابراین گزارش برنامه شما می‌تواند شامل پیام‌های خودتان، یکپارچه‌شده با پیام‌های ماژول‌های شخص ثالث، باشد.

در اینجا مثالی ساده از کاربرد رایج آمده است:

# myapp.py
import logging
import mylib
logger = logging.getLogger(__name__)

def main():
    logging.basicConfig(filename='myapp.log', level=logging.INFO)
    logger.info('Started')
    mylib.do_something()
    logger.info('Finished')

if __name__ == '__main__':
    main()

# mylib.py
import logging
logger = logging.getLogger(__name__)

def do_something():
    logger.info('Doing something')

اگر myapp.py را اجرا کنید، باید این را در myapp.log ببینید:

INFO:__main__:Started
INFO:mylib:Doing something
INFO:__main__:Finished

ویژگی کلیدی این کاربرد متعارف این است که بیشتر کد صرفاً یک گزارش‌گیر سطح ماژول با getLogger(__name__) ایجاد می‌کند و برای هرگونه گزارش‌گیری مورد نیاز از همان گزارش‌گیر استفاده می‌کند. این روش مختصر است و در صورت نیاز، کنترل ریزدانه‌ای را در اختیار کد پایین‌دستی قرار می‌دهد. پیام‌های گزارش‌شده در گزارش‌گیر سطح ماژول به هندلرهای گزارش‌گیرها در ماژول‌های سطح بالاتر ارسال می‌شوند، تا گزارش‌گیر بالاترین سطح که به‌عنوان گزارش‌گیر ریشه شناخته می‌شود؛ این رویکرد گزارش‌گیری سلسله‌مراتبی نامیده می‌شود.

برای اینکه گزارش‌گیری مفید باشد، باید پیکربندی شود: تنظیم سطوح و مقصدها برای هر گزارش‌گیر، احتمالاً تغییر نحوه‌ی گزارش کردن ماژول‌های خاص، که اغلب بر اساس آرگومان‌های خط فرمان یا پیکربندی برنامه انجام می‌شود. در بیشتر موارد، مانند مورد بالا، فقط گزارش‌گیر ریشه نیاز به چنین پیکربندی دارد، زیرا همه‌ی گزارش‌گیرهای سطح پایین‌تر در سطح ماژول در نهایت پیام‌های خود را به هندلرهای آن ارسال می‌کنند. basicConfig() راهی سریع برای پیکربندی گزارش‌گیر ریشه فراهم می‌کند که بسیاری از موارد استفاده را پوشش می‌دهد.

این ماژول قابلیت‌ها و انعطاف‌پذیری زیادی ارائه می‌دهد. اگر با گزارش‌گیری آشنایی ندارید، بهترین راه برای تسلط بر آن، مشاهده‌ی آموزش‌ها است (به پیوندهای بالا و سمت راست مراجعه کنید).

کلاس‌های پایه‌ای که توسط ماژول تعریف شده‌اند، به‌همراه ویژگی‌ها و متدهای آن‌ها، در بخش‌های زیر فهرست شده‌اند.

• گزارش‌گیرها رابطی را که کد برنامه به‌طور مستقیم از آن استفاده می‌کند، در دسترس قرار می‌دهند.

• هندلرها رکوردهای گزارش را که توسط گزارش‌گیرها ایجاد شده‌اند، به مقصد مناسب ارسال می‌کنند.

• فیلترها امکان دقیق‌تری برای تعیین اینکه کدام رکوردهای گزارش خروجی داده شوند، فراهم می‌کنند.

• قالب‌بندها چیدمان رکوردهای گزارش را در خروجی نهایی تعیین می‌کنند.

اشیای Logger

گزارش‌گیرها ویژگی‌ها و متدهای زیر را دارند. توجه داشته باشید که گزارش‌گیرها هرگز نباید مستقیماً نمونه‌سازی شوند، بلکه همیشه باید از طریق تابع در سطح ماژول logging.getLogger(name) ایجاد شوند. فراخوانی‌های مکرر getLogger() با نام یکسان، همیشه ارجاعی به همان شیء گزارش‌گیر را برمی‌گردانند.

name ممکن است یک مقدار سلسله‌مراتبی جداشده با نقطه، مانند foo.bar.baz باشد (اگرچه برای مثال می‌تواند فقط foo ساده باشد). گزارش‌گیرهایی که در فهرست سلسله‌مراتبی پایین‌تر هستند، فرزندان گزارش‌گیرهای بالاتر در فهرست هستند. برای مثال، اگر گزارش‌گیری با نام foo داشته باشیم، گزارش‌گیرهایی با نام‌های foo.bar، foo.bar.baz و foo.bam همگی نوادگان foo هستند. علاوه بر این، همه‌ی گزارش‌گیرها نوادگان گزارش‌گیر ریشه هستند. سلسله‌مراتب نام گزارش‌گیرها مشابه سلسله‌مراتب بسته‌های پایتون است و در صورتی که گزارش‌گیرهای خود را به‌ازای هر ماژول با استفاده از ساختار توصیه‌شده logging.getLogger(__name__) سازمان‌دهی کنید، با آن یکسان است. زیرا در یک ماژول، __name__ نام ماژول در فضای نام بسته‌ی پایتون است.

class logging.Logger

name

این نام گزارش‌گیر است و مقداری است که برای دریافت گزارش‌گیر به getLogger() پاس داده شده است.

توجه

این ویژگی باید به‌عنوان فقط‌خواندنی در نظر گرفته شود.

level

آستانه این گزارش‌گیر، که با متد setLevel() تنظیم شده است.

توجه

این ویژگی را مستقیماً تنظیم نکنید - همیشه از setLevel() استفاده کنید، که سطح ارسال‌شده به آن را بررسی می‌کند.

parent

گزارش‌گیر والد این گزارش‌گیر. ممکن است بر اساس نمونه‌سازی بعدی گزارش‌گیرهایی که در سلسله‌مراتب فضای نام بالاتر قرار دارند، تغییر کند.

توجه

این مقدار باید به‌عنوان فقط‌خواندنی در نظر گرفته شود.

propagate

اگر این ویژگی به مقدار درست ارزیابی شود، رویدادهای ثبت‌شده در این گزارش‌گیر، علاوه بر هر هندلری که به این گزارش‌گیر متصل باشد، به هندلرهای گزارش‌گیرهای سطح بالاتر (اجدادی) نیز ارسال می‌شوند. پیام‌ها مستقیماً به هندلرهای گزارش‌گیرهای اجدادی ارسال می‌شوند؛ نه سطح و نه فیلترهای گزارش‌گیرهای اجدادی مورد نظر در نظر گرفته نمی‌شوند.

اگر این مقدار نادرست ارزیابی شود، پیام‌های گزارش به هندلرهای گزارش‌گیرهای اجدادی (ancestor loggers) منتقل نمی‌شوند.

برای بیان صریح آن با یک مثال: اگر ویژگی propagate گزارش‌گیر به نام A.B.C به مقدار true ارزیابی شود، هر رویدادی که از طریق فراخوانی متدی مانند logging.getLogger('A.B.C').error(...) در A.B.C ثبت شود، [منوط به عبور از تنظیمات سطح و فیلتر آن گزارش‌گیر] به‌نوبه خود به هر یک از هندلرهای متصل به گزارش‌گیرهایی به نام‌های A.B، A و گزارش‌گیر ریشه ارسال می‌شود، پس از آنکه ابتدا به هر یک از هندلرهای متصل به A.B.C ارسال شده باشد. اگر ویژگی propagate هر گزارش‌گیر در زنجیره‌ی A.B.C، A.B، A روی false تنظیم شده باشد، آن گزارش‌گیر آخرین گزارش‌گیر است که رویداد برای مدیریت به هندلرهای آن ارائه می‌شود، و انتشار در آن نقطه متوقف می‌شود.

سازنده این ویژگی را روی True تنظیم می‌کند.

توجه

اگر یک هندلر را به یک گزارش‌گیر و یک یا چند مورد از اجداد آن متصل کنید، ممکن است همان رکورد چندین بار منتشر شود. به‌طور کلی، نباید نیازی به اتصال یک هندلر به بیش از یک گزارش‌گیر داشته باشید؛ اگر آن را فقط به گزارش‌گیر مناسبی که بالاترین جایگاه را در سلسله‌مراتب گزارش‌گیرها دارد متصل کنید، آن هندلر تمام رویدادهای ثبت‌شده توسط همه گزارش‌گیرهای پایین‌دست را مشاهده خواهد کرد، مشروط بر اینکه تنظیم انتشار (propagate) آن‌ها روی True باقی مانده باشد. یک سناریوی رایج این است که هندلرها فقط به گزارش‌گیر ریشه متصل شوند و اجازه دهید انتشار (propagation) بقیه موارد را مدیریت کند.

handlers

فهرستی از هندلرها که مستقیماً به این نمونه‌ی گزارش‌گیر متصل شده‌اند.

توجه

این ویژگی باید به‌عنوان فقط‌خواندنی در نظر گرفته شود؛ معمولاً از طریق متدهای addHandler() و removeHandler() تغییر می‌یابد، که از قفل‌ها برای اطمینان از عملکرد ایمن برای نخ‌ها استفاده می‌کنند.

disabled

این ویژگی مدیریت هر رویدادی را غیرفعال می‌کند. این ویژگی در مقداردهی اولیه روی False تنظیم می‌شود و فقط توسط کد پیکربندی گزارش‌گیری تغییر می‌کند.

توجه

این ویژگی باید به‌عنوان فقط‌خواندنی در نظر گرفته شود.

setLevel(level)

آستانه این گزارش‌گیر را روی level تنظیم می‌کند. پیام‌های گزارش که شدت کمتری از level دارند نادیده گرفته می‌شوند؛ پیام‌های گزارشی که شدت level یا بالاتر دارند، توسط هر هندلر یا هندلرهایی که به این گزارش‌گیر سرویس می‌دهند منتشر می‌شوند، مگر آنکه سطح یک هندلر روی سطح شدت بالاتری از level تنظیم شده باشد.

هنگامی که یک گزارش‌گیر ایجاد می‌شود، سطح آن بر روی NOTSET تنظیم می‌شود (که باعث می‌شود وقتی گزارش‌گیر، گزارش‌گیر ریشه است، تمام پیام‌ها پردازش شوند، یا وقتی گزارش‌گیر، گزارش‌گیر غیرریشه است، پیام‌ها به والد واگذار شوند). توجه داشته باشید که گزارش‌گیر ریشه با سطح WARNING ایجاد می‌شود.

اصطلاح «واگذاری به والد» به این معناست که اگر سطح یک گزارش‌گیر NOTSET باشد، زنجیره‌ی گزارش‌گیرهای والد آن پیمایش می‌شود تا یا یک گزارش‌گیر والد با سطحی غیر از NOTSET پیدا شود، یا به ریشه برسیم.

اگر نیایی با سطحی غیر از NOTSET یافت شود، سطح آن نیا به‌عنوان سطح مؤثر گزارش‌گیری که جست‌وجوی نیاکان در آن آغاز شده است در نظر گرفته می‌شود و برای تعیین چگونگی مدیریت یک رویداد گزارش استفاده می‌شود.

اگر به ریشه رسیده شود و سطح آن NOTSET باشد، تمام پیام‌ها پردازش خواهند شد. در غیر این صورت، سطح ریشه به‌عنوان سطح مؤثر استفاده خواهد شد.

برای مشاهده‌ی فهرستی از سطح‌ها، سطوح گزارش‌گیری را ببینید.

تغییر یافته در نسخه‌ی 3.2: پارامتر level اکنون نمایش رشته‌ای سطح مانند 'INFO' را به‌عنوان جایگزینی برای ثابت‌های عدد صحیح مانند INFO می‌پذیرد. با این حال، توجه داشته باشید که سطح‌ها به‌صورت داخلی به‌عنوان اعداد صحیح ذخیره می‌شوند و متدهایی مانند getEffectiveLevel() و isEnabledFor() اعداد صحیح را برمی‌گردانند/انتظار دارند که اعداد صحیح به آن‌ها ارسال شود.

isEnabledFor(level)

نشان می‌دهد که آیا پیامی با سطح شدت level توسط این گزارش‌گیر پردازش می‌شود یا خیر. این متد ابتدا سطح ماژول تنظیم‌شده توسط logging.disable(level) و سپس سطح مؤثر گزارش‌گیر را که توسط getEffectiveLevel() تعیین می‌شود، بررسی می‌کند.

getEffectiveLevel()

سطح مؤثر این گزارش‌گیر را نشان می‌دهد. اگر مقداری غیر از NOTSET با استفاده از setLevel() تنظیم شده باشد، آن مقدار برگردانده می‌شود. در غیر این صورت، سلسله‌مراتب به سمت ریشه پیمایش می‌شود تا مقداری غیر از NOTSET پیدا شود و آن مقدار برگردانده می‌شود. مقدار برگردانده‌شده یک عدد صحیح است، معمولاً یکی از logging.DEBUG، logging.INFO و غیره.

getChild(suffix)

یک گزارش‌گیر برمی‌گرداند که، همان‌طور که به‌وسیله‌ی پسوند تعیین می‌شود، از زیرمجموعه‌های این گزارش‌گیر است. بنابراین، logging.getLogger('abc').getChild('def.ghi') همان گزارش‌گیری را برمی‌گرداند که logging.getLogger('abc.def.ghi') برمی‌گرداند. این یک متد سهولت‌بخش است و زمانی مفید است که گزارش‌گیر والد به‌جای یک رشته‌ی لفظی، با استفاده از مثلاً __name__ نام‌گذاری شده باشد.

اضافه شده در نسخه‌ی 3.2.

getChildren()

مجموعه‌ای از گزارش‌گیرها را برمی‌گرداند که فرزندان مستقیم این گزارش‌گیر هستند. بنابراین برای مثال logging.getLogger().getChildren() ممکن است مجموعه‌ای حاوی گزارش‌گیرهایی با نام‌های foo و bar برگرداند، اما گزارش‌گیری با نام foo.bar در این مجموعه گنجانده نمی‌شود. به‌همین‌ترتیب، logging.getLogger('foo').getChildren() ممکن است مجموعه‌ای شامل گزارش‌گیری با نام foo.bar برگرداند، اما شامل گزارش‌گیری با نام foo.bar.baz نمی‌شود.

اضافه شده در نسخه‌ی 3.12.

debug(msg, *args, **kwargs)

پیامی را با سطح DEBUG در این گزارش‌گیر ثبت می‌کند. msg رشته‌ی قالب پیام است و args آرگومان‌هایی هستند که با استفاده از عملگر قالب‌بندی رشته، در msg ادغام می‌شوند. (توجه داشته باشید که این بدان معناست که می‌توانید از کلیدواژه‌ها در رشته‌ی قالب، به‌همراه یک آرگومان دیکشنری واحد استفاده کنید.) هنگامی که args ارائه نشود، هیچ عملیات قالب‌بندی با % روی msg انجام نمی‌شود.

چهار آرگومان کلیدواژه‌ای در kwargs وجود دارد که بررسی می‌شوند: exc_info، stack_info، stacklevel و extra.

اگر exc_info به‌صورت نادرست ارزیابی نشود، باعث می‌شود اطلاعات استثنا به پیام گزارش افزوده شود. اگر یک تاپل استثنا (در قالبی که توسط sys.exc_info() برگردانده می‌شود) یا یک نمونه استثنا ارائه شده باشد، از آن استفاده می‌شود؛ در غیر این صورت، sys.exc_info() فراخوانی می‌شود تا اطلاعات استثنا دریافت شود.

دومین آرگومان کلیدواژه‌ای اختیاری stack_info است که مقدار پیش‌فرض آن False است. اگر true باشد، اطلاعات پشته به پیام گزارش اضافه می‌شود، از جمله فراخوانی واقعی گزارش. توجه داشته باشید که این اطلاعات پشته همان اطلاعات پشته‌ای نیست که از طریق تعیین exc_info نمایش داده می‌شود: اولی فریم‌های پشته از انتهای پشته تا فراخوانی گزارش در نخ جاری است، در حالی که دومی اطلاعاتی در مورد فریم‌های پشته‌ای است که به‌دنبال یک استثنا، در حین جست‌وجو برای هندلرهای استثنا، باز شده‌اند.

شما می‌توانید stack_info را مستقل از exc_info تعیین کنید، برای مثال صرفاً برای اینکه نشان دهید چگونه به نقطه‌ای مشخص در کد خود رسیده‌اید، حتی زمانی که هیچ استثنایی پرتاب نشده باشد. فریم‌های پشته پس از یک خط سرآیند چاپ می‌شوند که می‌گوید:

پشته (آخرین فراخوانی در انتها):

این Traceback (most recent call last): را شبیه‌سازی می‌کند که هنگام نمایش فریم‌های استثنا استفاده می‌شود.

سومین آرگومان کلیدواژه‌ای اختیاری stacklevel است که مقدار پیش‌فرض آن 1 است. اگر بزرگ‌تر از ۱ باشد، تعداد متناظری از فریم‌های پشته هنگام محاسبه شماره خط و نام تابعی که در LogRecord ایجادشده برای رویداد گزارش‌گیری تنظیم می‌شوند، نادیده گرفته می‌شوند. می‌توان از این در توابع کمکی گزارش‌گیری استفاده کرد تا نام تابع، نام پرونده و شماره خط ثبت‌شده، اطلاعات مربوط به تابع/متد کمکی نباشد، بلکه اطلاعات مربوط به فراخواننده آن باشد. نام این پارامتر مشابه نام معادل آن در ماژول warnings است.

چهارمین آرگومان کلیدواژه‌ای extra است که می‌توان از آن برای ارسال یک دیکشنری استفاده کرد؛ این دیکشنری برای پر کردن __dict__ در LogRecord ایجادشده برای رویداد گزارش با ویژگی‌های تعریف‌شده توسط کاربر استفاده می‌شود. سپس می‌توانید از این ویژگی‌های سفارشی به دلخواه خود استفاده کنید. برای مثال، می‌توان آن‌ها را در پیام‌های گزارش‌شده گنجاند. برای مثال:

FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logger = logging.getLogger('tcpserver')
logger.warning('Protocol problem: %s', 'connection reset', extra=d)

چیزی شبیه به این را چاپ می‌کند

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

کلیدهای موجود در دیکشنری ارسال‌شده در extra نباید با کلیدهای استفاده‌شده توسط سیستم گزارش‌گیری تداخل داشته باشند. (برای اطلاعات بیشتر در مورد کلیدهایی که توسط سیستم گزارش‌گیری استفاده می‌شوند، بخش ویژگی‌های LogRecord را ببینید.)

اگر بخواهید از این ویژگی‌ها در پیام‌های ثبت‌شده استفاده کنید، باید کمی دقت به خرج دهید. برای مثال، در مثال بالا، Formatter با یک رشته‌ی قالب پیکربندی شده است که انتظار دارد 'clientip' و 'user' در دیکشنری ویژگی‌های LogRecord وجود داشته باشند. اگر این موارد وجود نداشته باشند، پیام ثبت نخواهد شد، زیرا یک استثنای قالب‌بندی رشته رخ خواهد داد. بنابراین در این حالت، همیشه باید دیکشنری extra را با این کلیدها ارسال کنید.

اگرچه ممکن است این موضوع آزاردهنده باشد، این قابلیت برای استفاده در شرایط خاص در نظر گرفته شده است، مانند سرورهای چندنخی که در آن‌ها کد یکسانی در زمینه‌های بسیاری اجرا می‌شود و شرایط جالب‌توجهی که پیش می‌آیند به این زمینه وابسته‌اند (مانند نشانی IP کلاینت دوردست و نام کاربری احراز هویت‌شده، در مثال بالا). در چنین شرایطی، احتمال دارد که Formatters اختصاصی با Handlers خاصی استفاده شوند.

اگر هیچ هندلری به این گزارش‌گیر یا هیچ‌یک از نیاکان آن متصل نشده باشد (با در نظر گرفتن ویژگی‌های مرتبط با Logger.propagate)، پیام به هندلر تنظیم‌شده در lastResort ارسال خواهد شد.

تغییر یافته در نسخه‌ی 3.2: پارامتر stack_info افزوده شد.

تغییر یافته در نسخه‌ی 3.5: پارامتر exc_info اکنون می‌تواند نمونه‌های استثنا را بپذیرد.

تغییر یافته در نسخه‌ی 3.8: پارامتر stacklevel افزوده شد.

info(msg, *args, **kwargs)

پیامی را با سطح INFO در این گزارش‌گیر ثبت می‌کند. آرگومان‌ها همانند debug() تفسیر می‌شوند.

warning(msg, *args, **kwargs)

پیامی را با سطح WARNING در این گزارش‌گیر ثبت می‌کند. آرگومان‌ها همانند debug() تفسیر می‌شوند.

توجه

یک متد منسوخ warn وجود دارد که از نظر عملکردی کاملاً با warning یکسان است. از آن‌جا که warn منسوخ است، لطفاً از آن استفاده نکنید و در عوض از warning استفاده کنید.

error(msg, *args, **kwargs)

پیامی را با سطح ERROR در این گزارش‌گیر ثبت می‌کند. آرگومان‌ها مانند debug() تفسیر می‌شوند.

critical(msg, *args, **kwargs)

پیامی را با سطح CRITICAL در این گزارش‌گیر ثبت می‌کند. آرگومان‌ها همانند debug() تفسیر می‌شوند.

log(level, msg, *args, **kwargs)

پیامی را با سطح level از نوع عدد صحیح در این گزارش‌گیر ثبت می‌کند. سایر آرگومان‌ها مانند آرگومان‌های debug() تفسیر می‌شوند.

exception(msg, *args, **kwargs)

پیامی را با سطح ERROR در این گزارش‌گیر ثبت می‌کند. آرگومان‌ها همان‌گونه که برای debug() تفسیر می‌شوند، تفسیر می‌شوند. اطلاعات استثنا به پیام گزارش اضافه می‌شود. این متد باید فقط از یک هندلر استثنا فراخوانی شود.

addFilter(filter)

فیلتر مشخص‌شده filter را به این گزارش‌گیر اضافه می‌کند.

removeFilter(filter)

فیلتر مشخص‌شده filter را از این گزارش‌گیر حذف می‌کند.

filter(record)

فیلترهای این گزارش‌گیر را روی رکورد اعمال می‌کند و در صورتی که رکورد قرار باشد پردازش شود، True را برمی‌گرداند. فیلترها به‌ترتیب بررسی می‌شوند، تا یکی از آن‌ها مقدار نادرست برگرداند. اگر هیچ‌کدام مقدار نادرست برنگردانند، رکورد پردازش خواهد شد (به هندلرها پاس داده می‌شود). اگر یکی مقدار نادرست برگرداند، هیچ پردازش بیشتری روی رکورد انجام نمی‌شود.

addHandler(hdlr)

هندلر مشخص‌شده hdlr را به این گزارش‌گیر اضافه می‌کند.

removeHandler(hdlr)

هندلر مشخص‌شده hdlr را از این گزارش‌گیر حذف می‌کند.

findCaller(stack_info=False, stacklevel=1)

نام پرونده منبع و شماره‌ی خط فراخواننده را پیدا می‌کند. نام پرونده، شماره‌ی خط، نام تابع و اطلاعات پشته را به‌صورت یک تاپل ۴ عنصری برمی‌گرداند. اطلاعات پشته به‌صورت None برگردانده می‌شود، مگر اینکه stack_info برابر True باشد.

پارامتر stacklevel از کدی که debug() و سایر APIها را فراخوانی می‌کند، ارسال می‌شود. اگر بزرگ‌تر از ۱ باشد، مقدار مازاد برای پرش از فریم‌های پشته (stack frames) پیش از تعیین مقادیری که باید برگردانده شوند استفاده می‌شود. این کار عموماً هنگام فراخوانی APIهای ثبت رویداد از کد کمکی/پوششی مفید است، به‌گونه‌ای که اطلاعات موجود در گزارش رویداد نه به کد کمکی/پوششی، بلکه به کدی که آن را فراخوانی می‌کند اشاره کند.

handle(record)

یک رکورد را با ارسال آن به تمام هندلرهای مرتبط با این گزارش‌گیر و نیاکان آن مدیریت می‌کند (تا زمانی که یک مقدار false برای propagate یافت شود). این متد برای رکوردهای از پیکل خارج‌شده دریافت‌شده از یک سوکت، و همچنین رکوردهایی که به‌صورت محلی ایجادشده‌اند، استفاده می‌شود. فیلتر در سطح گزارش‌گیر با استفاده از filter() اعمال می‌شود.

makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)

این یک متد کارخانه‌ای است که می‌توان آن را در زیرکلاس‌ها بازنویسی کرد تا نمونه‌های تخصصی LogRecord ایجاد شوند.

hasHandlers()

بررسی می‌کند که آیا این گزارش‌گیر هیچ هندلر پیکربندی‌شده‌ای دارد یا خیر. این کار با جست‌وجوی هندلرها در این گزارش‌گیر و والدین آن در سلسله‌مراتب گزارش‌گیر انجام می‌شود. اگر یک هندلر پیدا شود، True را برمی‌گرداند، در غیر این صورت False را برمی‌گرداند. این متد هر زمان که گزارش‌گیری پیدا شود که ویژگی 'propagate' آن روی false تنظیم شده باشد، جست‌وجو در سلسله‌مراتب به سمت بالا را متوقف می‌کند — آن گزارش‌گیر آخرین گزارش‌گیری خواهد بود که وجود هندلرها در آن بررسی می‌شود.

اضافه شده در نسخه‌ی 3.2.

تغییر یافته در نسخه‌ی 3.7: گزارش‌گیرها اکنون می‌توانند پیکل و پیکل‌گشایی (unpickle) شوند.

سطوح گزارش‌گیری

مقادیر عددی سطح‌های گزارش‌گیری در جدول زیر آمده است. این مقادیر عمدتاً زمانی مورد توجه هستند که بخواهید سطح‌های خودتان را تعریف کنید و نیاز داشته باشید آن‌ها مقادیر مشخصی نسبت به سطح‌های از پیش تعریف‌شده داشته باشند. اگر سطحی با همان مقدار عددی تعریف کنید، آن سطح مقدار از پیش تعریف‌شده را بازنویسی می‌کند؛ نام از پیش تعریف‌شده از بین می‌رود.

سطح	مقدار عددی	معنای آن / زمان استفاده از آن
logging.NOTSET	0	هنگام تنظیم روی یک گزارش‌گیر، نشان می‌دهد که برای تعیین سطح مؤثر باید به گزارش‌گیرهای اجدادی مراجعه شود. اگر باز هم به NOTSET برسد، آنگاه همه رویدادها ثبت می‌شوند. هنگام تنظیم روی یک هندلر، همه رویدادها پردازش می‌شوند.
logging.DEBUG	۱۰	اطلاعات تفصیلی، که معمولاً فقط برای توسعه‌دهنده‌ای که سعی در اشکال‌زدایی یک مشکل دارد، اهمیت دارد.
logging.INFO	۲۰	تأیید اینکه همه‌چیز مطابق انتظار کار می‌کند.
logging.WARNING	۳۰	نشانه‌ای از اینکه اتفاق غیرمنتظره‌ای رخ داده است، یا ممکن است مشکلی در آینده نزدیک پیش بیاید (برای مثال «فضای دیسک کم است»). نرم‌افزار همچنان مطابق انتظار کار می‌کند.
logging.ERROR	40	به دلیل مشکلی جدی‌تر، نرم‌افزار نتوانسته است تابعی را انجام دهد.
logging.CRITICAL	۵۰	خطای جدی، که نشان می‌دهد خود برنامه ممکن است نتواند به اجرا ادامه دهد.

اشیاء هندلر

هندلرها دارای ویژگی‌ها و متدهای زیر هستند. توجه داشته باشید که Handler هرگز به‌طور مستقیم نمونه‌سازی نمی‌شود؛ این کلاس به‌عنوان پایه‌ای برای زیرکلاس‌های مفیدتر عمل می‌کند. با این حال، متد __init__() در زیرکلاس‌ها باید Handler.__init__() را فراخوانی کند.

class logging.Handler

__init__(level=NOTSET)

نمونه‌ی Handler را با تنظیم سطح آن، تنظیم فهرست فیلترها به فهرست خالی و ایجاد یک قفل (با استفاده از createLock()) برای سریال‌سازی دسترسی به یک سازوکار ورودی/خروجی، مقداردهی اولیه می‌کند.

createLock()

یک قفل نخ را مقداردهی اولیه می‌کند که می‌توان از آن برای سریال‌سازی دسترسی به عملکرد I/O زیرین که ممکن است نخ‌ایمن نباشد، استفاده کرد.

acquire()

قفل نخ ایجادشده با createLock() را به دست می‌آورد.

release()

قفل نخِ به‌دست‌آمده با acquire() را آزاد می‌کند.

setLevel(level)

آستانه این هندلر را روی level تنظیم می‌کند. پیام‌های گزارش که کم‌اهمیت‌تر از level باشند، نادیده گرفته می‌شوند. هنگامی که یک هندلر ایجاد می‌شود، سطح روی NOTSET تنظیم می‌شود (که باعث می‌شود همه پیام‌ها پردازش شوند).

برای مشاهده‌ی فهرستی از سطح‌ها، سطوح گزارش‌گیری را ببینید.

تغییر یافته در نسخه‌ی 3.2: پارامتر level اکنون نمایش رشته‌ای از سطح مانند 'INFO' را به‌عنوان جایگزینی برای ثابت‌های عدد صحیح مانند INFO می‌پذیرد.

setFormatter(fmt)

قالب‌بند را برای این هندلر روی fmt تنظیم می‌کند. آرگومان fmt باید نمونه‌ای از Formatter یا None باشد.

addFilter(filter)

فیلتر مشخص‌شده filter را به این هندلر می‌افزاید.

removeFilter(filter)

فیلتر مشخص‌شده filter را از این هندلر حذف می‌کند.

filter(record)

فیلترهای این هندلر را روی رکورد اعمال می‌کند و اگر رکورد قرار باشد پردازش شود، True را برمی‌گرداند. فیلترها به‌ترتیب بررسی می‌شوند تا یکی از آن‌ها مقدار نادرست برگرداند. اگر هیچ‌کدام از آن‌ها مقدار نادرست برنگردانند، رکورد منتشر خواهد شد. اگر یکی مقدار نادرست برگرداند، هندلر رکورد را منتشر نخواهد کرد.

flush()

اطمینان حاصل کنید که تمام خروجی گزارش‌گیری تخلیه شده باشد. این نسخه هیچ کاری انجام نمی‌دهد و برای پیاده‌سازی توسط زیرکلاس‌ها در نظر گرفته شده است.

close()

هرگونه منبع مورد استفاده توسط هندلر را پاک‌سازی کنید. این نسخه هیچ خروجی تولید نمی‌کند، اما هندلر را از یک نگاشت داخلی از هندلرها حذف می‌کند که برای جست‌وجوی هندلر بر اساس نام استفاده می‌شود.

زیرکلاس‌ها باید اطمینان حاصل کنند که این از متدهای close() بازنویسی‌شده فراخوانی می‌شود.

handle(record)

به‌صورت مشروط، رکورد گزارش مشخص‌شده را بسته به فیلترهایی که ممکن است به هندلر افزوده شده باشند، منتشر می‌کند. انتشار واقعی رکورد را با اکتساب/آزادسازی قفل نخ ورودی/خروجی می‌پوشاند.

handleError(record)

این متد باید توسط هندلرها هنگامی فراخوانی شود که در حین فراخوانی emit() با استثنایی مواجه می‌شوند. اگر ویژگی سطح ماژول raiseExceptions برابر False باشد، استثناها به‌صورت بی‌صدا نادیده گرفته می‌شوند. این همان چیزی است که معمولاً برای یک سامانه‌ی گزارش مطلوب است—بیشتر کاربران به خطاهای سامانه‌ی گزارش اهمیتی نمی‌دهند، بیشتر به خطاهای برنامه علاقه‌مندند. با این حال، در صورت تمایل می‌توانید این را با یک هندلر سفارشی جایگزین کنید. رکورد مشخص‌شده همان رکوردی است که هنگام وقوع استثنا در حال پردازش بود. (مقدار پیش‌فرض raiseExceptions برابر True است، زیرا این امر در حین توسعه مفیدتر است).

format(record)

قالب‌بندی یک رکورد را انجام دهید؛ اگر یک قالب‌بند (formatter) تنظیم‌شده باشد، از آن استفاده کنید. در غیر این صورت، از قالب‌بند پیش‌فرض برای ماژول استفاده کنید.

emit(record)

هر کاری که برای ثبت واقعی رکورد گزارش مشخص‌شده لازم است انجام دهید. این نسخه برای پیاده‌سازی توسط زیرکلاس‌ها در نظر گرفته شده است و بنابراین یک NotImplementedError پرتاب می‌کند.

هشدار

این متد پس از کسب یک قفل در سطح هندلر فراخوانی می‌شود؛ قفلی که پس از بازگشت این متد آزاد می‌شود. هنگامی که این متد را بازنویسی می‌کنید، توجه داشته باشید که باید هنگام فراخوانی هر چیزی که بخش‌های دیگری از API گزارش‌گیری را فراخوانی کند و ممکن است قفل‌گذاری انجام دهد، احتیاط کنید، زیرا ممکن است این کار به بن‌بست منجر شود. به‌طور مشخص:

• APIهای پیکربندی گزارش‌گیری، قفل سطح ماژول را کسب می‌کنند و سپس قفل‌های جداگانه‌ی سطح هندلر را همزمان با پیکربندی آن هندلرها کسب می‌کنند.

• بسیاری از APIهای گزارش‌گیری، قفل سطح ماژول را قفل می‌کنند. اگر چنین APIای از این متد فراخوانی شود، در صورتی که یک فراخوانی پیکربندی در یک نخ دیگر انجام شود، ممکن است باعث بن‌بست شود؛ زیرا آن نخ تلاش خواهد کرد قفل سطح ماژول را پیش از قفل سطح هندلر به دست آورد، در حالی که این نخ تلاش می‌کند قفل سطح ماژول را پس از قفل سطح هندلر به دست آورد (زیرا در این متد، قفل سطح هندلر از قبل به دست آمده است).

برای مشاهده‌ی فهرستی از هندلرها که به‌صورت استاندارد گنجانده شده‌اند، logging.handlers را ببینید.

اشیای قالب‌بند (Formatter)

class logging.Formatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

مسئول تبدیل یک LogRecord به یک رشته خروجی است که توسط انسان یا سیستم خارجی تفسیر می‌شود.

پارامترها:

• fmt (str) -- یک رشته قالب با style داده‌شده برای کل خروجی ثبت‌شده. کلیدهای نگاشت ممکن از ویژگی‌های LogRecord شیء LogRecord گرفته می‌شوند. اگر مشخص نشده باشد، از '%(message)s' استفاده می‌شود که فقط پیام ثبت‌شده است.

• datefmt (str) -- یک رشته قالب برای بخش تاریخ/زمان خروجی گزارش‌شده. اگر مشخص نشده باشد، از پیش‌فرض توصیف‌شده در formatTime() استفاده می‌شود.

• style (str) -- می‌تواند یکی از '%'، '{' یا '$' باشد و تعیین می‌کند که رشته قالب چگونه با داده‌های آن ادغام شود: با استفاده از یکی از printf-style String Formatting (%)، str.format() ({) یا string.Template ($). این موضوع فقط در مورد fmt صدق می‌کند (برای مثال '%(message)s' در مقابل '{message}')، نه در مورد پیام‌های گزارش واقعی که به متدهای گزارش‌گیری ارسال می‌شوند. با این حال، راه‌های دیگری برای استفاده از قالب‌بندی { و $ برای پیام‌های گزارش وجود دارد.

• validate (bool) -- اگر True (پیش‌فرض) باشد، fmt و style نادرست یا ناهماهنگ باعث پرتاب ValueError می‌شود؛ برای مثال، logging.Formatter('%(asctime)s - %(message)s', style='{').

• defaults (dict[str, Any]) -- یک دیکشنری حاوی مقادیر پیش‌فرض برای استفاده در فیلدهای سفارشی. برای مثال، logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})

تغییر یافته در نسخه‌ی 3.2: پارامتر style اضافه شد.

تغییر یافته در نسخه‌ی 3.8: پارامتر validate اضافه شد.

تغییر یافته در نسخه‌ی 3.10: پارامتر defaults اضافه شد.

format(record)

دیکشنری ویژگی‌های رکورد به‌عنوان عملوند یک عملیات قالب‌بندی رشته استفاده می‌شود. رشته حاصل را برمی‌گرداند. پیش از قالب‌بندی دیکشنری، چند مرحله مقدماتی انجام می‌شود. ویژگی message رکورد با استفاده از msg % args محاسبه می‌شود. اگر رشته قالب‌بندی شامل '(asctime)' باشد، formatTime() برای قالب‌بندی زمان رویداد فراخوانی می‌شود. اگر اطلاعات استثنا وجود داشته باشد، با استفاده از formatException() قالب‌بندی می‌شود و به پیام اضافه می‌شود. توجه داشته باشید که اطلاعات استثنای قالب‌بندی‌شده در ویژگی exc_text به‌عنوان نهانگاه ذخیره می‌شود. این مفید است، زیرا می‌توان اطلاعات استثنا را پیکل کرد و از طریق شبکه ارسال کرد، اما اگر بیش از یک زیرکلاس از Formatter دارید که قالب‌بندی اطلاعات استثنا را سفارشی می‌کند، باید مراقب باشید. در این حالت، باید مقدار نهان‌شده را (با تنظیم ویژگی exc_text روی None) پس از آنکه قالب‌بند قالب‌بندی خود را انجام داد، پاک کنید تا قالب‌بند بعدی که رویداد را مدیریت می‌کند، از مقدار نهان‌شده استفاده نکند، بلکه آن را از نو محاسبه کند.

اگر اطلاعات پشته در دسترس باشد، پس از اطلاعات استثنا افزوده می‌شود و در صورت لزوم با استفاده از formatStack() تبدیل می‌شود.

formatTime(record, datefmt=None)

این متد باید توسط یک قالب‌بند که می‌خواهد از یک زمان قالب‌بندی‌شده استفاده کند، از format() فراخوانی شود. این متد می‌تواند در قالب‌بندها بازنویسی شود تا هر نیاز خاصی را برآورده کند، اما رفتار پایه به شرح زیر است: اگر datefmt (یک رشته) مشخص شده باشد، از آن به همراه time.strftime() برای قالب‌بندی زمان ایجاد رکورد استفاده می‌شود. در غیر این صورت، از قالب '%Y-%m-%d %H:%M:%S,uuu' استفاده می‌شود، که در آن بخش uuu یک مقدار میلی‌ثانیه است و سایر حروف مطابق مستندات time.strftime() هستند. یک نمونه زمان در این قالب 2003-01-23 00:29:50,411 است. رشته حاصل برگردانده می‌شود.

این تابع از یک تابع قابل پیکربندی توسط کاربر برای تبدیل زمان ایجاد به یک تاپل استفاده می‌کند. به‌طور پیش‌فرض، از time.localtime() استفاده می‌شود؛ برای تغییر این موضوع برای یک نمونه خاص از قالب‌بند، ویژگی converter را به تابعی با همان امضای time.localtime() یا time.gmtime() تنظیم کنید. برای تغییر آن برای تمام قالب‌بندها، برای مثال اگر می‌خواهید تمام زمان‌های گزارش به‌صورت GMT نمایش داده شوند، ویژگی converter را در کلاس Formatter تنظیم کنید.

تغییر یافته در نسخه‌ی 3.3: پیش‌تر، قالب پیش‌فرض به‌صورت سخت‌کدشده مطابق این مثال بود: 2010-09-06 22:38:15,292 که در آن بخش پیش از کاما توسط یک رشته‌ی قالب strptime ('%Y-%m-%d %H:%M:%S') پردازش می‌شود و بخش پس از کاما یک مقدار میلی‌ثانیه‌ای است. از آن‌جا که strptime قالب جای‌نگهدار برای میلی‌ثانیه‌ها ندارد، مقدار میلی‌ثانیه‌ای با استفاده از رشته‌ی قالب دیگری، یعنی '%s,%03d' افزوده می‌شود --- و هر دوی این رشته‌های قالب در این متد سخت‌کد شده بودند. با این تغییر، این رشته‌ها به‌عنوان ویژگی‌های سطح کلاس تعریف می‌شوند که در صورت نیاز می‌توانند در سطح نمونه بازنویسی شوند. نام ویژگی‌ها default_time_format (برای رشته‌ی قالب strptime) و default_msec_format (برای افزودن مقدار میلی‌ثانیه‌ای) است.

تغییر یافته در نسخه‌ی 3.9: default_msec_format می‌تواند None باشد.

formatException(exc_info)

اطلاعات استثنای مشخص‌شده (یک تاپل استثنای استاندارد که توسط sys.exc_info() برگردانده می‌شود) را به‌صورت یک رشته قالب‌بندی می‌کند. این پیاده‌سازی پیش‌فرض فقط از traceback.print_exception() استفاده می‌کند. رشته حاصل برگردانده می‌شود.

formatStack(stack_info)

اطلاعات پشته‌ی مشخص‌شده را به‌صورت یک رشته قالب‌بندی می‌کند (رشته‌ای که توسط traceback.print_stack() برگردانده می‌شود، اما با حذف آخرین نویسه‌ی خط جدید). این پیاده‌سازی پیش‌فرض تنها مقدار ورودی را برمی‌گرداند.

class logging.BufferingFormatter(linefmt=None)

یک کلاس قالب‌بند پایه مناسب برای زیرکلاس‌سازی هنگامی که می‌خواهید تعدادی رکورد را فرمت‌دهی کنید. شما می‌توانید یک نمونه از Formatter را که می‌خواهید از آن برای فرمت‌دهی هر خط (که متناظر با یک رکورد واحد است) استفاده کنید، ارسال کنید. اگر مشخص نشده باشد، قالب‌بند پیش‌فرض (که فقط پیام رویداد را خروجی می‌دهد) به‌عنوان قالب‌بند خط استفاده می‌شود.

formatHeader(records)

یک سرآیند برای فهرستی از رکوردها برمی‌گرداند. پیاده‌سازی پایه فقط رشته‌ی خالی را برمی‌گرداند. اگر رفتار خاصی مدنظرتان باشد، باید این متد را بازنویسی کنید، مثلاً برای نمایش تعداد رکوردها، یک عنوان یا یک خط جداکننده.

formatFooter(records)

پابرگی برای فهرستی از رکوردها برمی‌گرداند. پیاده‌سازی پایه فقط رشته خالی را برمی‌گرداند. اگر رفتار خاصی بخواهید، لازم است این متد را بازنویسی کنید، مثلاً برای نمایش تعداد رکوردها یا یک خط جداکننده.

format(records)

متن قالب‌بندی‌شده برای فهرستی از رکوردها را برمی‌گرداند. پیاده‌سازی پایه، در صورتی که هیچ رکوردی وجود نداشته باشد، فقط رشته خالی را برمی‌گرداند؛ در غیر این صورت، رشته حاصل از الحاق سرآیند، هر رکورد قالب‌بندی‌شده با قالب‌بند خط، و پابرگ را برمی‌گرداند.

اشیای فیلتر

از Filters می‌توان توسط Handlers و Loggers برای فیلتر کردن پیشرفته‌تر از آنچه توسط سطح‌ها فراهم می‌شود استفاده کرد. کلاس فیلتر پایه فقط رویدادهایی را مجاز می‌داند که زیر یک نقطه مشخص در سلسله‌مراتب گزارش‌گیر قرار دارند. برای مثال، فیلتری که با 'A.B' مقداردهی اولیه شده باشد، رویدادهای ثبت‌شده توسط گزارش‌گیرهای 'A.B'، 'A.B.C'، 'A.B.C.D'، 'A.B.D' و غیره را مجاز می‌داند، اما رویدادهای ثبت‌شده توسط گزارش‌گیرهای 'A.BB'، 'B.A.B' و غیره را مجاز نمی‌داند. اگر با رشته تهی مقداردهی اولیه شود، همه‌ی رویدادها عبور داده می‌شوند.

class logging.Filter(name='')

نمونه‌ای از کلاس Filter برمی‌گرداند. اگر name مشخص شده باشد، نام گزارش‌گیری را مشخص می‌کند که رویدادهای آن، به همراه رویدادهای فرزندان آن، اجازه عبور از فیلتر را خواهند داشت. اگر name رشته خالی باشد، همه رویدادها اجازه عبور خواهند داشت.

filter(record)

آیا رکورد مشخص‌شده باید گزارش شود؟ برای خیر false و برای بله true برمی‌گرداند. فیلترها می‌توانند رکوردهای گزارش را به‌صورت درجا اصلاح کنند یا یک نمونه رکورد کاملاً متفاوت برگردانند که در هرگونه پردازش بعدی رویداد، جایگزین رکورد گزارش اصلی خواهد شد.

توجه داشته باشید که فیلترهای متصل به هندلرها پیش از آنکه هندلر رویدادی را منتشر کند، بررسی می‌شوند، در حالی که فیلترهای متصل به گزارش‌گیرها هر زمان که رویدادی ثبت شود (با استفاده از debug()، info() و غیره)، پیش از ارسال رویداد به هندلرها بررسی می‌شوند. این بدان معناست که تنظیمات فیلتر یک گزارش‌گیر، رویدادهایی را که گزارش‌گیرهای زیرمجموعه تولید کرده‌اند، فیلتر نخواهد کرد، مگر آنکه فیلتر به آن گزارش‌گیرهای زیرمجموعه نیز اعمال شده باشد.

شما در واقع نیازی به ساخت زیرکلاس از Filter ندارید: می‌توانید هر نمونه‌ای را که متد filter با همان معانی دارد، ارسال کنید.

تغییر یافته در نسخه‌ی 3.2: نیازی نیست کلاس‌های Filter تخصصی ایجاد کنید، یا از کلاس‌های دیگر دارای متد filter استفاده کنید: می‌توانید از یک تابع (یا شیء فراخوانی‌پذیر دیگر) به عنوان فیلتر استفاده کنید. منطق فیلتر بررسی می‌کند که آیا شیء فیلتر دارای ویژگی filter است یا خیر: اگر داشته باشد، فرض می‌شود که یک Filter است و متد filter() آن فراخوانی می‌شود. در غیر این صورت، فرض می‌شود که یک شیء فراخوانی‌پذیر است و با رکورد به عنوان تنها پارامتر فراخوانی می‌شود. مقدار بازگشتی باید با مقداری که توسط filter() بازگردانده می‌شود مطابقت داشته باشد.

تغییر یافته در نسخه‌ی 3.12: اکنون می‌توانید یک نمونه‌ی LogRecord را از فیلترها برگردانید تا رکورد گزارش را جایگزین کند، به‌جای این‌که آن را به‌صورت درجا تغییر دهید. این امر به فیلترهای متصل به یک Handler اجازه می‌دهد رکورد گزارش را پیش از انتشار تغییر دهند، بدون این‌که عوارض جانبی روی سایر handlerها داشته باشند.

اگرچه فیلترها عمدتاً برای فیلتر کردن رکوردها بر اساس معیارهای پیچیده‌تر از سطوح استفاده می‌شوند، اما هر رکورد پردازش‌شده توسط هندلر یا گزارش‌گیری که این فیلترها به آن متصل شده‌اند را مشاهده می‌کنند: این موضوع زمانی می‌تواند مفید باشد که بخواهید کارهایی مانند شمارش تعداد رکوردهای پردازش‌شده توسط یک گزارش‌گیر یا هندلر خاص، یا افزودن، تغییر یا حذف ویژگی‌های LogRecord در حال پردازش را انجام دهید. بدیهی است که تغییر LogRecord باید با کمی دقت انجام شود، اما این کار امکان تزریق اطلاعات زمینه‌ای به گزارش‌ها را فراهم می‌کند (به استفاده از فیلترها برای انتقال اطلاعات زمینه‌ای مراجعه کنید).

اشیای LogRecord

نمونه‌های LogRecord هر بار که چیزی ثبت می‌شود، به‌طور خودکار توسط Logger ایجاد می‌شوند و می‌توان آن‌ها را به‌صورت دستی از طریق makeLogRecord() ایجاد کرد (برای مثال، از یک رویداد pickleشده دریافت‌شده از شبکه).

class logging.LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None)

شامل تمام اطلاعات مربوط به رویدادی است که ثبت می‌شود.

اطلاعات اصلی در msg و args منتقل می‌شود، که با استفاده از msg % args ترکیب می‌شوند تا ویژگی message رکورد را ایجاد کنند.

پارامترها:

• name (str) -- نام گزارش‌گیر استفاده‌شده برای ثبت رویدادی که این LogRecord آن را نشان می‌دهد. توجه داشته باشید که نام گزارش‌گیر در LogRecord همیشه همین مقدار را خواهد داشت، حتی اگر توسط یک هندلر متصل به یک گزارش‌گیر متفاوت (بالادستی) ارسال شده باشد.

• level (int) -- سطح عددی رویداد گزارش (مانند 10 برای DEBUG، 20 برای INFO و غیره). توجه داشته باشید که این به دو ویژگی از LogRecord تبدیل می‌شود: levelno برای مقدار عددی و levelname برای نام سطح متناظر.

• pathname (str) -- مسیر کامل به‌صورت رشته برای پرونده منبعی که فراخوانی logging در آن انجام شده‌است.

• lineno (int) -- شماره‌ی خط در پرونده منبعی که فراخوانی گزارش در آن انجام شده است.

• msg (Any) -- پیام توصیف رویداد، که می‌تواند یک رشته‌ی %-format با جانگهدارهایی برای داده‌های متغیر، یا یک شیء دلخواه باشد (ببینید استفاده از اشیاء دلخواه به‌عنوان پیام).

• args (tuple | dict[str, Any]) -- داده‌های متغیر برای ادغام در آرگومان msg جهت به دست آوردن توضیح رویداد.

• exc_info (tuple[type[BaseException], BaseException, types.TracebackType] | None) -- یک تاپل استثنا حاوی اطلاعات استثنای جاری، همان‌طور که از sys.exc_info() بازگردانده می‌شود، یا None اگر اطلاعات استثنا در دسترس نباشد.

• func (str | None) -- نام تابع یا متدی که فراخوانی گزارش‌گیری از آن انجام شده است.

• sinfo (str | None) -- یک رشته متنی که اطلاعات پشته را از کف پشته در نخ جاری تا فراخوانی گزارش‌گیری نشان می‌دهد.

getMessage()

پیام این نمونه LogRecord را پس از ادغام آرگومان‌های ارائه‌شده توسط کاربر با پیام بازمی‌گرداند. اگر آرگومان پیام ارائه‌شده توسط کاربر در فراخوانی گزارش، رشته نباشد، str() روی آن فراخوانی می‌شود تا به رشته تبدیل شود. این امکان استفاده از کلاس‌های تعریف‌شده توسط کاربر به‌عنوان پیام را فراهم می‌کند، که متد __str__ آن‌ها می‌تواند رشته قالب واقعی مورد استفاده را برگرداند.

تغییر یافته در نسخه‌ی 3.2: ایجاد یک LogRecord با فراهم کردن کارخانه‌ای که برای ایجاد رکورد استفاده می‌شود، قابل پیکربندی‌تر شده است. کارخانه را می‌توان با استفاده از getLogRecordFactory() و setLogRecordFactory() تنظیم کرد (برای امضای کارخانه این را ببینید).

از این قابلیت می‌توانید برای تزریق مقادیر خودتان به یک LogRecord در زمان ایجاد استفاده کنید. می‌توانید از الگوی زیر استفاده کنید:

old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    return record

logging.setLogRecordFactory(record_factory)

با این الگو، می‌توان چندین کارخانه را به‌صورت زنجیره‌ای به هم متصل کرد، و تا زمانی که آن‌ها ویژگی‌های یکدیگر را بازنویسی نکنند یا ویژگی‌های استاندارد فهرست‌شده در بالا را به‌طور غیرعمد بازنویسی نکنند، نباید مورد غیرمنتظره‌ای پیش بیاید.

ویژگی‌های LogRecord

LogRecord تعدادی ویژگی دارد که بیشتر آن‌ها از پارامترهای سازنده مشتق می‌شوند. (توجه داشته باشید که نام‌ها همیشه دقیقاً میان پارامترهای سازنده LogRecord و ویژگی‌های LogRecord مطابقت ندارند.) می‌توان از این ویژگی‌ها برای ادغام داده‌های رکورد در رشته قالب استفاده کرد. جدول زیر (به‌ترتیب الفبایی) نام ویژگی‌ها، معانی آن‌ها و جای‌نگهدار متناظر در یک رشته قالب به سبک % را فهرست می‌کند.

اگر از قالب‌بندی {} (str.format()) استفاده می‌کنید، می‌توانید از {attrname} به‌عنوان جای‌نگهدار در رشته قالب استفاده کنید. اگر از قالب‌بندی $ (string.Template) استفاده می‌کنید، از شکل ${attrname} استفاده کنید. در هر دو حالت، البته attrname را با نام ویژگی واقعی که می‌خواهید استفاده کنید، جایگزین کنید.

در مورد قالب‌بندی {}، می‌توانید پرچم‌های قالب‌بندی را با قرار دادن آن‌ها پس از نام ویژگی و جدا کردن آن‌ها از آن با دونقطه مشخص کنید. برای مثال: یک جای‌نگهدار به‌صورت {msecs:03.0f} مقدار میلی‌ثانیه‌ی 4 را به‌صورت 004 قالب‌بندی می‌کند. برای جزئیات کامل درباره گزینه‌های در دسترس شما، به مستندات str.format() مراجعه کنید.

نام ویژگی	قالب	توضیح
args	شما نباید نیاز داشته باشید که این مورد را خودتان قالب‌بندی کنید.	تاپل آرگومان‌هایی که در msg ادغام می‌شوند تا message تولید شود، یا دیکشنری که مقادیر آن برای ادغام استفاده می‌شوند (هنگامی که تنها یک آرگومان وجود دارد و آن یک دیکشنری است).
asctime	%(asctime)s	زمان قابل‌خواندن برای انسان هنگام ایجاد LogRecord. به‌طور پیش‌فرض این مقدار به شکل '2003-07-08 16:49:45,896' است (اعداد پس از ویرگول، بخش میلی‌ثانیه‌ای زمان هستند).
created	%(created)f	زمان ایجاد LogRecord (به‌صورت مقدار برگردانده‌شده توسط time.time_ns() / 1e9).
exc_info	شما نباید نیاز داشته باشید که این مورد را خودتان قالب‌بندی کنید.	تاپل استثنا (مانند sys.exc_info) یا اگر استثنایی رخ نداده باشد، None.
exc_text	شما نباید نیاز داشته باشید که این مورد را خودتان قالب‌بندی کنید.	اطلاعات استثنا که به‌صورت یک رشته قالب‌بندی شده است. این مقدار زمانی تنظیم می‌شود که Formatter.format() فراخوانی شود، یا اگر استثنایی رخ نداده باشد None خواهد بود.
filename	%(filename)s	بخش نام پرونده از pathname.
funcName	%(funcName)s	نام تابعی که شامل فراخوانی گزارش است.
levelname	%(levelname)s	سطح گزارش‌گیری متنی برای پیام ('DEBUG'، 'INFO'، 'WARNING'، 'ERROR'، 'CRITICAL').
levelno	%(levelno)s	سطح گزارش‌دهی عددی برای پیام (DEBUG، INFO، WARNING، ERROR، CRITICAL).
lineno	%(lineno)d	شماره‌ی خط منبعی که فراخوانی گزارش‌گیری در آن انجام شده است (در صورت موجود بودن).
پیام	%(message)s	پیام ثبت‌شده، که به‌صورت msg % args محاسبه می‌شود. این مقدار زمانی تنظیم می‌شود که Formatter.format() فراخوانی شود.
ماژول	%(module)s	ماژول (بخش نام از filename).
msecs	%(msecs)d	بخش میلی‌ثانیه‌ای از زمانی که LogRecord ایجاد شده است.
msg	شما نباید نیاز داشته باشید که این مورد را خودتان قالب‌بندی کنید.	رشته قالب ارسال‌شده در فراخوانی اصلی logging. با args ترکیب می‌شود تا message تولید شود، یا یک شیء دلخواه (ببینید استفاده از اشیاء دلخواه به‌عنوان پیام).
نام	%(name)s	نام گزارش‌گیر استفاده‌شده برای ثبت فراخوانی.
نام مسیر	%(pathname)s	مسیر کامل پرونده منبعی که فراخوانی گزارش‌گیری در آن صادر شده است (در صورت موجود بودن).
فرایند	%(process)d	شناسه‌ی فرایند (در صورت موجود بودن).
processName	%(processName)s	نام فرایند (در صورت موجود بودن).
relativeCreated	%(relativeCreated)d	زمان ایجاد LogRecord بر حسب میلی‌ثانیه، نسبت به زمان بارگذاری ماژول logging.
stack_info	شما نباید نیاز داشته باشید که این مورد را خودتان قالب‌بندی کنید.	اطلاعات فریم پشته، در صورت موجود بودن، از انتهای پشته در نخ جاری، تا و شامل فریم پشته‌ی فراخوانی logging که منجر به ایجاد این رکورد شد.
نخ	%(thread)d	شناسه نخ (در صورت موجود بودن).
threadName	%(threadName)s	نام نخ (در صورت موجود بودن).
taskName	%(taskName)s	نام asyncio.Task (در صورت موجود بودن).

تغییر یافته در نسخه‌ی 3.1: processName افزوده شد.

تغییر یافته در نسخه‌ی 3.12: taskName افزوده شد.

اشیای LoggerAdapter

نمونه‌های LoggerAdapter برای ارسال آسان اطلاعات زمینه‌ای به فراخوانی‌های گزارش استفاده می‌شوند. برای دیدن نمونه‌ای از کاربرد، بخش افزودن اطلاعات زمینه‌ای به خروجی گزارش شما را ببینید.

class logging.LoggerAdapter(logger, extra=None, merge_extra=False)

نمونه‌ای از LoggerAdapter را برمی‌گرداند که با یک نمونه‌ی Logger زیربنایی، یک شیء دیکشنری‌مانند اختیاری (extra)، و یک بولی اختیاری (merge_extra) مقداردهی اولیه شده است؛ این بولی نشان می‌دهد که آیا آرگومان extra فراخوانی‌های گزارش منفرد باید با extra مربوط به LoggerAdapter ادغام شود یا خیر. رفتار پیش‌فرض این است که از آرگومان extra فراخوانی‌های گزارش منفرد چشم‌پوشی شود و فقط از extra مربوط به نمونه‌ی LoggerAdapter استفاده شود

process(msg, kwargs)

پیام و/یا آرگومان‌های کلیدواژه‌ای ارسال‌شده به یک فراخوانی گزارش‌گیری را تغییر می‌دهد تا اطلاعات زمینه‌ای را درج کند. این پیاده‌سازی، شیء ارسال‌شده به‌عنوان extra به سازنده را دریافت می‌کند و آن را با استفاده از کلید 'extra' به kwargs اضافه می‌کند. مقدار بازگشتی یک تاپل (msg, kwargs) است که شامل نسخه‌های (احتمالاً تغییرکرده) آرگومان‌های ارسال‌شده است.

manager

به manager زیربنایی در logger واگذار می‌شود.

_log

به متد زیربنایی _log() در logger واگذار می‌کند.

علاوه بر موارد بالا، LoggerAdapter از متدهای زیرِ Logger پشتیبانی می‌کند: debug()، info()، warning()، error()، exception()، critical()، log()، isEnabledFor()، getEffectiveLevel()، setLevel() و hasHandlers(). این متدها امضاهای یکسانی با همتایان خود در Logger دارند، بنابراین می‌توانید از نمونه‌های این دو نوع به‌جای یکدیگر استفاده کنید.

تغییر یافته در نسخه‌ی 3.2: متدهای isEnabledFor()، getEffectiveLevel()، setLevel() و hasHandlers() به LoggerAdapter افزوده شدند. این متدها به گزارش‌گیر زیرین محول می‌شوند.

تغییر یافته در نسخه‌ی 3.6: ویژگی manager و متد _log() افزوده شدند؛ این موارد به گزارش‌گیر زیرین ارجاع می‌دهند و امکان تودرتو شدن آداپتورها را فراهم می‌کنند.

تغییر یافته در نسخه‌ی 3.10: آرگومان extra اکنون اختیاری است.

تغییر یافته در نسخه‌ی 3.13: پارامتر merge_extra افزوده شد.

ایمنی نخ (Thread Safety)

ماژول logging به‌گونه‌ای طراحی شده است که بدون نیاز به انجام هیچ کار خاصی از سوی کلاینت‌های آن، نخ‌ایمن (thread-safe) باشد. این ماژول این امر را با استفاده از قفل‌های threading محقق می‌کند؛ یک قفل برای سریال‌سازی دسترسی به داده‌های مشترک ماژول وجود دارد و هر هندلر نیز یک قفل برای سریال‌سازی دسترسی به I/O زیربنایی خود ایجاد می‌کند.

اگر با استفاده از ماژول signal در حال پیاده‌سازی هندلرهای سیگنال ناهمگام هستید، ممکن است نتوانید از درون چنین هندلرهایی از گزارش‌گیری استفاده کنید. دلیل این امر آن است که پیاده‌سازی‌های قفل در ماژول threading همیشه قابل ورود مجدد (re-entrant) نیستند و بنابراین نمی‌توان آن‌ها را از چنین هندلرهای سیگنالی فراخوانی کرد.

توابع سطح ماژول

علاوه بر کلاس‌های توصیف‌شده در بالا، تعدادی تابع در سطح ماژول نیز وجود دارد.

logging.getLogger(name=None)

یک گزارش‌گیر با نام مشخص‌شده بازمی‌گرداند یا اگر نام None باشد، گزارش‌گیر ریشه‌ی سلسله‌مراتب را بازمی‌گرداند. اگر مشخص شده باشد، نام معمولاً یک نام سلسله‌مراتبی جداشده با نقطه مانند 'a'، 'a.b' یا 'a.b.c.d' است. انتخاب این نام‌ها کاملاً بر عهده‌ی توسعه‌دهنده‌ای است که از logging استفاده می‌کند، هرچند توصیه می‌شود از __name__ استفاده شود، مگر اینکه دلیل خاصی برای انجام ندادن آن داشته باشید، همان‌طور که در اشیای Logger ذکر شده است.

تمام فراخوانی‌های این تابع با یک نام مشخص، همان نمونه‌ی گزارش‌گیر را برمی‌گردانند. این بدان معناست که هرگز نیازی نیست نمونه‌های گزارش‌گیر بین بخش‌های مختلف یک برنامه منتقل شوند.

logging.getLoggerClass()

کلاس استاندارد Logger یا آخرین کلاس ارسال‌شده به setLoggerClass() را برمی‌گرداند. این تابع ممکن است از درون تعریف یک کلاس جدید فراخوانی شود، تا اطمینان حاصل شود که نصب یک کلاس Logger سفارشی‌سازی‌شده، سفارشی‌سازی‌هایی را که پیش‌تر توسط سایر کدها اعمال شده‌اند واگرد نمی‌کند. برای مثال:

class MyLogger(logging.getLoggerClass()):
    # ... override behaviour here

logging.getLogRecordFactory()

یک شیء فراخوانی‌پذیر برمی‌گرداند که برای ایجاد یک LogRecord استفاده می‌شود.

اضافه شده در نسخه‌ی 3.2: این تابع، همراه با setLogRecordFactory()، فراهم شده است تا توسعه‌دهندگان کنترل بیشتری بر چگونگی ساخت LogRecord که نشان‌دهنده‌ی یک رویداد گزارش است، داشته باشند.

برای اطلاعات بیشتر درباره چگونگی فراخوانی کارخانه، setLogRecordFactory() را ببینید.

logging.debug(msg, *args, **kwargs)

این یک تابع سهولت‌بخش است که Logger.debug() را روی گزارش‌گیر ریشه فراخوانی می‌کند. مدیریت آرگومان‌ها از هر جهت همان چیزی است که در آن متد توضیح داده‌شده است.

تنها تفاوت این است که اگر گزارش‌گیر ریشه هیچ هندلری نداشته باشد، basicConfig() پیش از فراخوانی debug روی گزارش‌گیر ریشه فراخوانی می‌شود.

برای اسکریپت‌های بسیار کوتاه یا نمایش‌های سریع امکانات logging، استفاده از debug و سایر توابع سطح ماژول ممکن است مناسب باشد. با این حال، بیشتر برنامه‌ها نیاز دارند پیکربندی گزارش‌گیری را به‌دقت و به‌صراحت کنترل کنند، بنابراین باید ایجاد یک گزارش‌گیر سطح ماژول و فراخوانی Logger.debug() (یا سایر متدهای مختص سطح) روی آن را ترجیح دهند، همان‌طور که در ابتدای این مستندات توضیح داده شده است.

logging.info(msg, *args, **kwargs)

پیامی را با سطح INFO در گزارش‌گیر ریشه ثبت می‌کند. در بقیه موارد، آرگومان‌ها و رفتار همانند debug() است.

logging.warning(msg, *args, **kwargs)

پیامی را با سطح WARNING در گزارش‌گیر ریشه ثبت می‌کند. در بقیه موارد، آرگومان‌ها و رفتار همانند debug() است.

توجه

تابع منسوخی به نام warn وجود دارد که از نظر عملکردی با warning یکسان است. از آن‌جا که warn منسوخ است، لطفاً از آن استفاده نکنید؛ به‌جای آن از warning استفاده کنید.

logging.error(msg, *args, **kwargs)

پیامی را با سطح ERROR در گزارش‌گیر ریشه ثبت می‌کند. در بقیه موارد، آرگومان‌ها و رفتار همانند debug() است.

logging.critical(msg, *args, **kwargs)

پیامی را با سطح CRITICAL در گزارش‌گیر ریشه ثبت می‌کند. آرگومان‌ها و رفتار آن در بقیه موارد همانند debug() است.

logging.exception(msg, *args, **kwargs)

پیامی را با سطح ERROR در گزارش‌گیر ریشه ثبت می‌کند. آرگومان‌ها و رفتار آن در سایر موارد مانند debug() است. اطلاعات استثنا به پیام گزارش افزوده می‌شود. این تابع فقط باید از یک مدیر استثنا فراخوانی شود.

logging.log(level, msg, *args, **kwargs)

پیامی را با سطح level در گزارش‌گیر ریشه ثبت می‌کند. در سایر موارد، آرگومان‌ها و رفتار آن همانند debug() است.

logging.disable(level=CRITICAL)

یک سطح غالب level برای همه گزارش‌گیرها فراهم می‌کند که بر سطح خود گزارش‌گیر اولویت دارد. هنگامی که نیاز باشد خروجی گزارش به‌طور موقت در سراسر برنامه کاهش یابد، این تابع می‌تواند مفید باشد. اثر آن غیرفعال کردن همه فراخوانی‌های گزارش با شدت level و پایین‌تر است؛ به‌طوری‌که اگر آن را با مقدار INFO فراخوانی کنید، همه رویدادهای INFO و DEBUG دور ریخته می‌شوند، در حالی که رویدادهای با شدت WARNING و بالاتر بر اساس سطح مؤثر گزارش‌گیر پردازش می‌شوند. اگر logging.disable(logging.NOTSET) فراخوانی شود، این سطح غالب به‌طور مؤثر حذف می‌شود، به‌طوری‌که خروجی گزارش بار دیگر به سطوح مؤثر گزارش‌گیرهای جداگانه بستگی دارد.

توجه داشته باشید که اگر هر سطح گزارش‌گیری سفارشی‌ای بالاتر از CRITICAL تعریف کرده باشید (این کار توصیه نمی‌شود)، نمی‌توانید به مقدار پیش‌فرض پارامتر level اتکا کنید، بلکه باید به‌صراحت مقدار مناسبی را ارائه دهید.

تغییر یافته در نسخه‌ی 3.7: پارامتر level به‌طور پیش‌فرض روی سطح CRITICAL تنظیم شد. برای اطلاعات بیشتر درباره این تغییر، bpo-28524 را ببینید.

logging.addLevelName(level, levelName)

سطح level را با متن levelName در یک دیکشنری داخلی مرتبط می‌کند؛ این دیکشنری برای نگاشت سطوح عددی به یک نمایش متنی به کار می‌رود، برای مثال هنگامی که یک Formatter یک پیام را قالب‌بندی می‌کند. همچنین می‌توانید از این تابع برای تعریف سطوح خودتان استفاده کنید. تنها محدودیت‌ها این است که تمام سطوح مورد استفاده باید با استفاده از این تابع ثبت شوند، سطوح باید اعداد صحیح مثبت باشند و باید به ترتیب افزایش شدت، افزایش یابند.

توجه

اگر قصد تعریف سطح‌های خود را دارید، لطفاً به بخش سطوح سفارشی مراجعه کنید.

logging.getLevelNamesMapping()

نگاشتی از نام سطوح به سطوح گزارش‌کردن متناظر آن‌ها برمی‌گرداند. برای مثال، رشته "CRITICAL" به CRITICAL نگاشت می‌شود. نگاشت بازگشتی در هر فراخوانی این تابع از یک نگاشت داخلی کپی می‌شود.

اضافه شده در نسخه‌ی 3.11.

logging.getLevelName(level)

بازنمایی متنی یا عددی سطح گزارش‌دهی level را بازمی‌گرداند.

اگر level یکی از سطح‌های از پیش تعریف‌شده CRITICAL، ERROR، WARNING، INFO یا DEBUG باشد، رشته متناظر را دریافت می‌کنید. اگر با استفاده از addLevelName() سطح‌ها را به نام‌ها مرتبط کرده باشید، نامی که به level مرتبط کرده‌اید برگردانده می‌شود. اگر مقدار عددی متناظر با یکی از سطح‌های تعریف‌شده ارسال شود، نمایش رشته‌ای متناظر برگردانده می‌شود.

پارامتر level همچنین نمایش رشته‌ای از سطح مانند 'INFO' را می‌پذیرد. در چنین مواردی، این تابع مقدار عددی متناظر سطح را برمی‌گرداند.

اگر هیچ مقدار عددی یا رشته‌ای متناظری ارسال نشود، رشته 'Level %s' % level برگردانده می‌شود.

توجه

سطح‌ها به‌صورت داخلی اعداد صحیح هستند (زیرا باید در منطق گزارش‌گیری مقایسه شوند). این تابع برای تبدیل میان یک سطح عدد صحیح و نام سطحی استفاده می‌شود که در خروجی گزارش قالب‌بندی‌شده به‌وسیله‌ی مشخص‌کننده‌ی قالب %(levelname)s نمایش داده می‌شود (به ویژگی‌های LogRecord مراجعه کنید)، و برعکس.

تغییر یافته در نسخه‌ی 3.4: در نسخه‌های پیش از 3.4 پایتون، این تابع همچنین می‌توانست یک سطح متنی را بپذیرد و مقدار عددی متناظر آن سطح را برمی‌گرداند. این رفتار بدون مستند، یک اشتباه تلقی می‌شد و در پایتون 3.4 حذف شد، اما در 3.4.2 برای حفظ سازگاری با نسخه‌های پیشین بازگردانده شد.

logging.getHandlerByName(name)

یک هندلر با name مشخص‌شده برمی‌گرداند، یا اگر هندلری با آن نام وجود نداشته باشد None برمی‌گرداند.

اضافه شده در نسخه‌ی 3.12.

logging.getHandlerNames()

یک مجموعه تغییرناپذیر از تمام نام‌های شناخته‌شده‌ی هندلرها را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.12.

logging.makeLogRecord(attrdict)

یک نمونه جدید از LogRecord را ایجاد می‌کند و برمی‌گرداند که ویژگی‌های آن توسط attrdict تعریف شده‌اند. این تابع برای گرفتن یک دیکشنری ویژگی‌های LogRecord که پیکل‌شده و از طریق یک سوکت ارسال شده است، و بازسازی آن به‌عنوان یک نمونه از LogRecord در سمت گیرنده مفید است.

logging.basicConfig(**kwargs)

پیکربندی پایه‌ی سیستم گزارش‌گیری را با ایجاد یک StreamHandler با یک Formatter پیش‌فرض و افزودن آن به گزارش‌گیر ریشه انجام می‌دهد. توابع debug()، info()، warning()، error() و critical() اگر هیچ هندلری برای گزارش‌گیر ریشه تعریف نشده باشد، به‌طور خودکار basicConfig() را فراخوانی می‌کنند.

اگر گزارش‌گیر ریشه از قبل هندلرهایی پیکربندی‌شده داشته باشد، این تابع کاری انجام نمی‌دهد، مگر اینکه آرگومان کلیدواژه‌ای force بر روی True تنظیم شده باشد.

توجه

این تابع باید از نخ اصلی پیش از آغاز سایر نخ‌ها فراخوانی شود. در نسخه‌های پیش از 2.7.1 و 3.2 پایتون، اگر این تابع از چندین نخ فراخوانی شود، ممکن است (در شرایط نادر) یک هندلر بیش از یک بار به گزارش‌گیر ریشه اضافه شود و به نتایج غیرمنتظره‌ای مانند تکراری شدن پیام‌ها در گزارش منجر شود.

از آرگومان‌های کلیدواژه‌ای زیر پشتیبانی می‌شود.

قالب	توضیح
filename	مشخص می‌کند که به‌جای StreamHandler، یک FileHandler با استفاده از نام پرونده مشخص‌شده ایجاد شود.
filemode	اگر filename مشخص شده باشد، پرونده در این حالت باز می‌شود. پیش‌فرض 'a' است.
format	از رشته‌ی قالب مشخص‌شده برای هندلر استفاده کنید. به‌طور پیش‌فرض، شامل ویژگی‌های levelname، name و message است که با دونقطه از هم جدا شده‌اند.
datefmt	از قالب تاریخ/زمان مشخص‌شده استفاده کنید، همان‌طور که time.strftime() می‌پذیرد.
style	اگر format مشخص شده باشد، از این سبک برای رشته قالب استفاده می‌شود. یکی از '%'، '{' یا '$' به‌ترتیب برای printf-style، str.format() یا string.Template است. مقدار پیش‌فرض '%' است.
level	سطح گزارش‌گیر ریشه را روی سطح تعیین‌شده تنظیم کنید.
stream	برای راه‌اندازی StreamHandler از جریان مشخص‌شده استفاده کنید. توجه داشته باشید که این آرگومان با filename ناسازگار است؛ اگر هر دو وجود داشته باشند، یک ValueError پرتاب می‌شود.
handlers	اگر مشخص شده باشد، این باید پیمایش‌پذیری از هندلرهای از پیش ساخته‌شده برای افزودن به گزارش‌گیر ریشه باشد. به هر هندلری که از پیش قالب‌بندی (formatter) برایش تنظیم نشده باشد، قالب‌بندٔ پیش‌فرضی که در این تابع ساخته می‌شود اختصاص داده خواهد شد. توجه داشته باشید که این آرگومان با filename یا stream ناسازگار است؛ اگر هر دو وجود داشته باشند، یک ValueError پرتاب می‌شود.
force	اگر این آرگومان کلیدواژه‌ای با مقدار درست مشخص شود، پیش از اجرای پیکربندی مطابق با سایر آرگومان‌ها، هر هندلر موجود متصل به گزارش‌گیر ریشه حذف و بسته می‌شود.
encoding	اگر این آرگومان کلیدواژه‌ای همراه با filename مشخص شود، هنگام ایجاد FileHandler از مقدار آن استفاده می‌شود و بنابراین هنگام باز کردن پرونده خروجی نیز از آن استفاده می‌شود.
errors	اگر این آرگومان کلیدواژه‌ای به همراه filename مشخص شده باشد، مقدار آن در زمان ایجاد FileHandler استفاده می‌شود و بنابراین در زمان باز کردن پرونده خروجی نیز استفاده می‌شود. اگر مشخص نشده باشد، مقدار 'backslashreplace' استفاده می‌شود. توجه داشته باشید که اگر None مشخص شود، به همان صورت به open() ارسال می‌شود، به این معنا که همانند ارسال 'errors' با آن رفتار خواهد شد.

تغییر یافته در نسخه‌ی 3.2: آرگومان style افزوده شد.

تغییر یافته در نسخه‌ی 3.3: آرگومان handlers افزوده شد. بررسی‌های بیشتری برای شناسایی موقعیت‌هایی که در آن‌ها آرگومان‌های ناسازگار مشخص شده‌اند، افزوده شدند (برای مثال handlers همراه با stream یا filename، یا stream همراه با filename).

تغییر یافته در نسخه‌ی 3.8: آرگومان force افزوده شد.

تغییر یافته در نسخه‌ی 3.9: آرگومان‌های encoding و errors افزوده شدند.

logging.shutdown()

به سیستم گزارش‌گیری اطلاع می‌دهد تا با تخلیه و بستن همه‌ی هندلرها، یک خاموش‌سازی منظم را انجام دهد. این باید در زمان خروج برنامه فراخوانی شود و پس از این فراخوانی، نباید هیچ استفاده‌ی دیگری از سیستم گزارش‌گیری صورت گیرد.

هنگامی که ماژول logging ایمپورت می‌شود، این تابع را به‌عنوان یک مدیر خروج (exit handler) ثبت می‌کند (به atexit مراجعه کنید)، بنابراین معمولاً نیازی به انجام این کار به‌صورت دستی نیست.

logging.setLoggerClass(klass)

به سیستم گزارش‌گیری می‌گوید که هنگام نمونه‌سازی یک گزارش‌گیر از کلاس klass استفاده کند. این کلاس باید __init__() را به‌گونه‌ای تعریف کند که تنها یک آرگومان name مورد نیاز باشد، و __init__() باید Logger.__init__() را فراخوانی کند. این تابع معمولاً پیش از نمونه‌سازی هر گزارش‌گیر توسط برنامه‌هایی که نیاز به استفاده از رفتار سفارشی گزارش‌گیر دارند، فراخوانی می‌شود. پس از این فراخوانی، همان‌گونه که در هر زمان دیگری نیز هست، گزارش‌گیرها را مستقیماً با استفاده از زیرکلاس نمونه‌سازی نکنید: برای دریافت گزارش‌گیرهای خود همچنان از API logging.getLogger() استفاده کنید.

logging.setLogRecordFactory(factory)

یک شیء فراخوانی‌پذیر را تنظیم کنید که برای ایجاد یک LogRecord استفاده می‌شود.

پارامترها:

factory -- فراخوانی‌پذیر کارخانه‌ای که برای نمونه‌سازی یک رکورد گزارش استفاده می‌شود.

اضافه شده در نسخه‌ی 3.2: این تابع، به همراه getLogRecordFactory()، فراهم شده است تا توسعه‌دهندگان کنترل بیشتری بر چگونگی ایجاد LogRecord که نشان‌دهنده‌ی یک رویداد گزارش‌دهی است، داشته باشند.

این کارخانه دارای امضای زیر است:

factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

نام:

نام گزارش‌گیر .

level:

سطح گزارش (عددی).

fn:

مسیر کامل پرونده‌ای که فراخوانی گزارش در آن انجام شده است.

lno:

شماره خط در پرونده‌ای که فراخوانی گزارش در آن انجام شده است.

msg:

پیام گزارش .

args:

آرگومان‌های پیام گزارش‌گیری.

exc_info:

یک تاپل استثنا، یا None.

func:

نام تابع یا متدی که فراخوانی گزارش‌گیری را انجام داده است.

sinfo:

ردگیری پشته‌ای مانند آنچه توسط traceback.print_stack() ارائه می‌شود، که سلسله‌مراتب فراخوانی را نشان می‌دهد.

kwargs:

آرگومان‌های کلیدواژه‌ای اضافی.

ویژگی‌های سطح ماژول

logging.lastResort

یک «هندلری آخرین چاره (handler of last resort)» از طریق این ویژگی در دسترس است. این یک StreamHandler است که در sys.stderr با سطح WARNING می‌نویسد و برای رسیدگی به رویدادهای گزارش‌گیری در نبود هرگونه پیکربندی گزارش‌گیری استفاده می‌شود. نتیجه نهایی فقط چاپ پیام در sys.stderr است. این جایگزین پیام خطای پیشین می‌شود که می‌گفت «هیچ هندلری برای logger XYZ پیدا نشد». اگر به هر دلیلی به رفتار پیشین نیاز دارید، می‌توان lastResort را روی None تنظیم کرد.

اضافه شده در نسخه‌ی 3.2.

logging.raiseExceptions

برای بررسی اینکه آیا استثناهای حین مدیریت باید انتشار یابند، استفاده می‌شود.

پیش‌فرض: True.

اگر raiseExceptions برابر False باشد، استثناها به‌صورت خاموش نادیده گرفته می‌شوند. این معمولاً همان چیزی است که برای یک سامانه‌ی گزارش خواسته می‌شود؛ بیشتر کاربران به خطاهای سامانه‌ی گزارش اهمیتی نمی‌دهند، بلکه بیشتر به خطاهای برنامه علاقه‌مند هستند.

یکپارچگی با ماژول warnings

می‌توان از تابع captureWarnings() برای یکپارچه‌سازی logging با ماژول warnings استفاده کرد.

logging.captureWarnings(capture)

این تابع برای فعال و غیرفعال کردن ضبط هشدارها به‌وسیله‌ی گزارش‌گیری استفاده می‌شود.

اگر capture برابر True باشد، هشدارهای صادر شده از ماژول warnings به سامانه‌ی گزارش‌گیری هدایت می‌شوند. به‌طور مشخص، یک هشدار با استفاده از warnings.formatwarning() قالب‌بندی می‌شود و رشته‌ی حاصل در یک گزارش‌گیر به نام 'py.warnings' با شدت WARNING ثبت می‌شود.

اگر capture برابر False باشد، تغییر مسیر هشدارها به سامانه‌ی گزارش‌گیری متوقف می‌شود و هشدارها به مقصدهای اصلی خود (یعنی آن‌هایی که پیش از فراخوانی captureWarnings(True) فعال بودند) تغییر مسیر داده می‌شوند.

همچنین ملاحظه نمائید

ماژول logging.config

API پیکربندی ماژول logging.

ماژول logging.handlers

هندلرهای مفید ارائه‌شده همراه با ماژول logging.

PEP 282 - یک سیستم گزارش‌گیری

پیشنهادی که این قابلیت را برای گنجاندن در کتابخانه‌ی استاندارد پایتون توصیف کرد.

بسته‌ی گزارش‌گیری اصلی پایتون

این کد منبع اصلی بسته‌ی logging است. نسخه‌ی این بسته که از این سایت در دسترس است، برای استفاده با پایتون 1.5.2، 2.1.x و 2.2.x مناسب است؛ این نسخه‌های پایتون بسته‌ی logging را در کتابخانه‌ی استاندارد شامل نمی‌شوند.