چه زمانی از گزارش‌گیری استفاده کنیم¶

شما می‌توانید با ایجاد یک گزارش‌گیر از طریق logger = logging.getLogger(__name__) و سپس فراخوانی متدهای debug()، info()، warning()، error() و critical() آن، به قابلیت گزارش‌گیری دسترسی پیدا کنید. برای تشخیص اینکه چه زمانی از گزارش‌گیری استفاده کنید و ببینید چه زمانی از کدام متدهای گزارش‌گیر استفاده کنید، به جدول زیر مراجعه کنید. این جدول برای هر یک از مجموعه‌ای از وظایف رایج، بهترین ابزار برای استفاده در آن وظیفه را بیان می‌کند.

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

سطح پیش‌فرض WARNING است، یعنی فقط رویدادهای این شدت و بالاتر از آن پیگیری می‌شوند، مگر اینکه بسته‌ی logging به‌گونه‌ای دیگر پیکربندی شده باشد.

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

یک مثال ساده¶

یک مثال بسیار ساده:

import logging
logging.warning('Watch out!')  # will print a message to the console
logging.info('I told you so')  # will not print anything

اگر این سطرها را در یک اسکریپت وارد کنید و آن را اجرا کنید، خواهید دید:

WARNING:root:مراقب باشید!

در کنسول چاپ می‌شود. پیام INFO نمایش داده نمی‌شود زیرا سطح پیش‌فرض WARNING است. پیام چاپ‌شده شامل نشانگر سطح و شرح رویداد ارائه‌شده در فراخوانی logging است، یعنی 'Watch out!'. در صورت نیاز، می‌توان خروجی واقعی را با انعطاف‌پذیری بالایی قالب‌بندی کرد؛ گزینه‌های قالب‌بندی نیز بعداً توضیح داده خواهند شد.

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

گزارش‌گیری در یک پرونده¶

یک حالت بسیار رایج، ثبت رویدادهای گزارش در یک پرونده است، بنابراین در ادامه به بررسی آن می‌پردازیم. حتماً موارد زیر را در یک مفسر پایتون که به‌تازگی آغاز شده است آزمایش کنید و صرفاً از نشست توصیف‌شده در بالا ادامه ندهید:

import logging
logger = logging.getLogger(__name__)
logging.basicConfig(filename='example.log', encoding='utf-8', level=logging.DEBUG)
logger.debug('This message should go to the log file')
logger.info('So should this')
logger.warning('And this, too')
logger.error('And non-ASCII stuff, too, like Øresund and Malmö')

و اکنون اگر پرونده را باز کنیم و به آنچه داریم نگاه کنیم، باید پیام‌های گزارش را پیدا کنیم:

DEBUG:__main__:این پیام باید به پرونده گزارش برود
INFO:__main__:این پیام هم همین‌طور
WARNING:__main__:و این هم همین‌طور
ERROR:__main__:و موارد غیر اسکی (non-ASCII) نیز، مانند Øresund و Malmö

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

اگر می‌خواهید سطح گزارش را از طریق یک گزینه‌ی خط فرمان تنظیم کنید، مانند:

--log=INFO

و مقدار پارامتر داده‌شده برای --log را در متغیری به نام loglevel دارید، می‌توانید به این صورت استفاده کنید:

getattr(logging, loglevel.upper())

برای دریافت مقداری که آن را از طریق آرگومان level به basicConfig() می‌دهید. ممکن است بخواهید هر مقدار ورودی کاربر را از نظر خطا بررسی کنید، شاید مانند مثال زیر:

# assuming loglevel is bound to the string value obtained from the
# command line argument. Convert to upper case to allow the user to
# specify --log=DEBUG or --log=debug
numeric_level = getattr(logging, loglevel.upper(), None)
if not isinstance(numeric_level, int):
    raise ValueError('Invalid log level: %s' % loglevel)
logging.basicConfig(level=numeric_level, ...)

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

اگر اسکریپت بالا را چند بار اجرا کنید، پیام‌های اجراهای پیاپی به پرونده example.log افزوده می‌شوند. اگر می‌خواهید هر اجرا از نو آغاز شود و پیام‌های اجراهای پیشین را به خاطر نداشته باشد، می‌توانید با تغییر فراخوانی در مثال بالا به شکل زیر، آرگومان filemode را مشخص کنید:

logging.basicConfig(filename='example.log', filemode='w', level=logging.DEBUG)

خروجی مانند قبل خواهد بود، اما دیگر به پرونده گزارش الحاق نمی‌شود، بنابراین پیام‌های اجراهای پیشین از دست می‌روند.

ثبت داده‌های متغیر¶

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

import logging
logging.warning('%s before you %s', 'Look', 'leap!')

نمایش خواهد داد:

WARNING:root:پیش از اقدام، تأمل کنید!

همان‌طور که می‌بینید، ادغام داده‌های متغیر در پیام توصیف رویداد از سبک قدیمی قالب‌بندی رشته با %-style استفاده می‌کند. این برای سازگاری با نسخه‌های قدیمی است: بسته‌ی logging پیش از گزینه‌های قالب‌بندی جدیدتری مانند str.format() و string.Template وجود داشته است. این گزینه‌های قالب‌بندی جدیدتر پشتیبانی می‌شوند، اما بررسی آن‌ها خارج از محدوده این آموزش است: برای اطلاعات بیشتر استفاده از سبک‌های قالب‌بندی خاص در سراسر برنامه شما را ببینید.

تغییر قالب پیام‌های نمایش‌داده‌شده¶

برای تغییر قالبی که برای نمایش پیام‌ها استفاده می‌شود، باید قالبی را که می‌خواهید استفاده کنید، مشخص کنید:

import logging
logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.DEBUG)
logging.debug('This message should appear on the console')
logging.info('So should this')
logging.warning('And this, too')

که این را چاپ خواهد کرد:

DEBUG:این پیام باید در کنسول ظاهر شود
INFO:این پیام نیز همین‌طور
WARNING:و این پیام نیز همین‌طور

توجه داشته باشید که 'root' که در مثال‌های پیشین ظاهر شده بود، ناپدید شده است. برای مشاهده مجموعه کاملی از مواردی که می‌توانند در رشته‌های قالب ظاهر شوند، می‌توانید به مستندات ویژگی‌های LogRecord مراجعه کنید، اما برای استفاده ساده، فقط به levelname (شدت)، message (توصیف رویداد، شامل داده‌های متغیر) و احتمالاً به نمایش زمان وقوع رویداد نیاز دارید. این موضوع در بخش بعدی توضیح داده شده است.

نمایش تاریخ/زمان در پیام‌ها¶

برای نمایش تاریخ و زمان یک رویداد، '%(asctime)s' را در رشته قالب خود قرار می‌دهید:

import logging
logging.basicConfig(format='%(asctime)s %(message)s')
logging.warning('is when this event was logged.')

که باید چیزی شبیه به این چاپ کند:

2010-12-12 11:41:42,612 زمانی است که این رویداد ثبت شد.

قالب پیش‌فرض برای نمایش تاریخ/زمان (که در بالا نشان داده شد) مانند ISO8601 یا RFC 3339 است. اگر به کنترل بیشتری بر قالب‌بندی تاریخ/زمان نیاز دارید، یک آرگومان datefmt به basicConfig ارائه دهید، همان‌طور که در این مثال آمده است:

import logging
logging.basicConfig(format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %I:%M:%S %p')
logging.warning('is when this event was logged.')

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

این رویداد در ۱۲/۱۲/۲۰۱۰ ۱۱:۴۶:۳۶ ق.ظ ثبت شده است.

قالب آرگومان datefmt همان قالبی است که time.strftime() از آن پشتیبانی می‌کند.

گام‌های بعدی¶

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

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

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

جریان گزارش‌گیری¶

جریان اطلاعات رویداد گزارش در گزارش‌گیرها و هندلرها در نمودار زیر نشان داده شده است.

گزارش‌گیرها¶

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

پرکاربردترین متدهای اشیای گزارش‌گیر به دو دسته تقسیم می‌شوند: پیکربندی و ارسال پیام.

این‌ها رایج‌ترین متدهای پیکربندی هستند:

• Logger.setLevel() پایین‌ترین سطح شدت پیام گزارشی را مشخص می‌کند که یک گزارش‌گیر رسیدگی خواهد کرد، که در آن debug پایین‌ترین سطح شدت توکار و critical بالاترین شدت توکار است. برای مثال، اگر سطح شدت INFO باشد، گزارش‌گیر فقط پیام‌های INFO، WARNING، ERROR و CRITICAL را رسیدگی می‌کند و پیام‌های DEBUG را نادیده می‌گیرد.

• Logger.addHandler() و Logger.removeHandler() اشیای handler را به شیء logger اضافه و از آن حذف می‌کنند. handlerها با جزئیات بیشتر در هندلرها پوشش داده شده‌اند.

• Logger.addFilter() و Logger.removeFilter() اشیای فیلتر را به شیء گزارش‌گیر اضافه و از آن حذف می‌کنند. فیلترها با جزئیات بیشتر در اشیای فیلتر بررسی شده‌اند.

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

با پیکربندی شیء logger، متدهای زیر پیام‌های گزارش ایجاد می‌کنند:

• Logger.debug()، Logger.info()، Logger.warning()، Logger.error() و Logger.critical() همگی رکوردهای گزارش را ایجاد می‌کنند که دارای یک پیام و یک سطح هستند و سطح آن‌ها با نام متدهای مربوطه مطابقت دارد. پیام در واقع یک رشته‌ی قالب است که ممکن است حاوی سینتکس استاندارد جایگذاری رشته مانند %s، %d، %f و غیره باشد. سایر آرگومان‌های آن‌ها فهرستی از شیء‌ها است که با فیلدهای جایگذاری در پیام مطابقت دارند. در مورد **kwargs، متدهای گزارش تنها به کلیدواژه‌ای با نام exc_info توجه می‌کنند و از آن برای تعیین اینکه آیا اطلاعات استثنا در گزارش ثبت شود یا خیر استفاده می‌کنند.

• Logger.exception() یک پیام گزارش مشابه Logger.error() ایجاد می‌کند. تفاوت این است که Logger.exception() یک ردگیری پشته را نیز همراه آن خروجی می‌دهد. این متد را فقط از داخل یک هندلر استثنا فراخوانی کنید.

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

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

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

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

هندلرها¶

اشیاء Handler مسئول ارسال پیام‌های گزارش مناسب (بر اساس شدت پیام‌های گزارش) به مقصد مشخص‌شده‌ی handler هستند. اشیاء Logger می‌توانند با متد addHandler() صفر یا چند شیء handler را به خود اضافه کنند. به‌عنوان یک سناریوی نمونه، یک برنامه ممکن است بخواهد تمام پیام‌های گزارش را به یک پرونده گزارش، تمام پیام‌های گزارش با سطح خطا یا بالاتر را به stdout و تمام پیام‌های سطح بحرانی را به یک نشانی ایمیل ارسال کند. این سناریو به سه handler جداگانه نیاز دارد که هر handler مسئول ارسال پیام‌هایی با شدتی مشخص به مکانی مشخص است.

کتابخانه استاندارد شامل تعداد نسبتاً زیادی از انواع هندلر است (به هندلرهای مفید مراجعه کنید)؛ آموزش‌ها در مثال‌های خود عمدتاً از StreamHandler و FileHandler استفاده می‌کنند.

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

• متد setLevel()، همان‌طور که در اشیای logger نیز چنین است، کمترین سطح شدتی را که به مقصد مناسب ارسال خواهد شد مشخص می‌کند. چرا دو متد setLevel() وجود دارد؟ سطح تنظیم‌شده در logger تعیین می‌کند که پیام‌ها با چه شدتی به handlerهای آن منتقل شوند. سطح تنظیم‌شده در هر handler تعیین می‌کند که آن handler کدام پیام‌ها را ارسال کند.

• setFormatter() یک شیء Formatter را برای این هندلر انتخاب می‌کند تا از آن استفاده کند.

• addFilter() و removeFilter() به‌ترتیب اشیای فیلتر را بر روی Handlerها پیکربندی و از پیکربندی خارج می‌کنند.

کد برنامه نباید مستقیماً از Handler نمونه‌سازی کند و از نمونه‌های آن استفاده کند. در عوض، کلاس Handler یک کلاس پایه است که رابطی را تعریف می‌کند که همه‌ی handlerها باید داشته باشند و برخی رفتارهای پیش‌فرض را تعیین می‌کند که کلاس‌های فرزند می‌توانند از آن‌ها استفاده کنند (یا آن‌ها را بازنویسی کنند).

قالب‌بندها¶

اشیاء قالب‌بند (Formatter) ترتیب نهایی، ساختار و محتوای پیام گزارش را پیکربندی می‌کنند. برخلاف کلاس پایه‌ی logging.Handler، کد برنامه می‌تواند کلاس‌های قالب‌بند را نمونه‌سازی کند، هرچند اگر برنامه شما به رفتار خاصی نیاز داشته باشد، به احتمال زیاد می‌توانید یک زیرکلاس از قالب‌بند ایجاد کنید. سازنده سه آرگومان اختیاری دریافت می‌کند -- یک رشته‌ی قالب پیام، یک رشته‌ی قالب تاریخ و یک نشانگر سبک.

logging.Formatter.__init__(fmt=None, datefmt=None, style='%')¶

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

%Y-%m-%d %H:%M:%S

با میلی‌ثانیه‌هایی که در انتها اضافه شده‌اند. style یکی از '%'، '{' یا '$' است. اگر یکی از این موارد تعیین نشده باشد، از '%' استفاده خواهد شد.

اگر style برابر '%' باشد، رشته قالب پیام از جایگزینی رشته به‌سبک %(<dictionary key>)s استفاده می‌کند؛ کلیدهای ممکن در ویژگی‌های LogRecord مستند شده‌اند. اگر سبک برابر '{' باشد، فرض می‌شود رشته قالب پیام با str.format() (با استفاده از آرگومان‌های کلیدواژه‌ای) سازگار باشد، در حالی که اگر سبک برابر '$' باشد، رشته قالب پیام باید با آنچه string.Template.substitute() انتظار دارد مطابقت داشته باشد.

رشته‌ی قالب پیام زیر، زمان را در قالبی خوانا برای انسان، شدت پیام و محتوای پیام را به همین ترتیب ثبت می‌کند:

'%(asctime)s - %(levelname)s - %(message)s'

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

پیکربندی گزارش‌گیری¶

برنامه‌نویسان می‌توانند گزارش‌گیری را به سه روش پیکربندی کنند:

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

2. ایجاد یک پرونده‌ی پیکربندی گزارش‌گیری و خواندن آن با استفاده از تابع fileConfig().

3. ایجاد یک دیکشنری از اطلاعات پیکربندی و ارسال آن به تابع dictConfig().

برای مستندات مرجع در مورد دو گزینه‌ی آخر، به توابع پیکربندی مراجعه کنید. مثال زیر با استفاده از کد پایتون، یک گزارش‌گیر بسیار ساده، یک هندلر کنسول (console handler) و یک قالب‌بند (formatter) ساده را پیکربندی می‌کند:

import logging

# create logger
logger = logging.getLogger('simple_example')
logger.setLevel(logging.DEBUG)

# create console handler and set level to debug
ch = logging.StreamHandler()
ch.setLevel(logging.DEBUG)

# create formatter
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')

# add formatter to ch
ch.setFormatter(formatter)

# add ch to logger
logger.addHandler(ch)

# 'application' code
logger.debug('debug message')
logger.info('info message')
logger.warning('warn message')
logger.error('error message')
logger.critical('critical message')

اجرای این ماژول از خط فرمان، خروجی زیر را تولید می‌کند:

$ python simple_logging_module.py
2005-03-19 15:10:26,618 - simple_example - DEBUG - debug message
2005-03-19 15:10:26,620 - simple_example - INFO - info message
2005-03-19 15:10:26,695 - simple_example - WARNING - warn message
2005-03-19 15:10:26,697 - simple_example - ERROR - error message
2005-03-19 15:10:26,773 - simple_example - CRITICAL - critical message

ماژول پایتون زیر یک گزارش‌گیر، هندلر و قالب‌بند (formatter) تقریباً یکسان با موارد موجود در مثال ذکرشده در بالا ایجاد می‌کند، با این تفاوت که تنها نام اشیاء متفاوت است:

import logging
import logging.config

logging.config.fileConfig('logging.conf')

# create logger
logger = logging.getLogger('simpleExample')

# 'application' code
logger.debug('debug message')
logger.info('info message')
logger.warning('warn message')
logger.error('error message')
logger.critical('critical message')

در اینجا پرونده logging.conf آمده است:

[loggers]
keys=root,simpleExample

[handlers]
keys=consoleHandler

[formatters]
keys=simpleFormatter

[logger_root]
level=DEBUG
handlers=consoleHandler

[logger_simpleExample]
level=DEBUG
handlers=consoleHandler
qualname=simpleExample
propagate=0

[handler_consoleHandler]
class=StreamHandler
level=DEBUG
formatter=simpleFormatter
args=(sys.stdout,)

[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(message)s

خروجی تقریباً با خروجی مثال غیرمبتنی بر پرونده پیکربندی یکسان است:

$ python simple_logging_config.py
2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message
2005-03-19 15:38:55,979 - simpleExample - INFO - info message
2005-03-19 15:38:56,054 - simpleExample - WARNING - warn message
2005-03-19 15:38:56,055 - simpleExample - ERROR - error message
2005-03-19 15:38:56,130 - simpleExample - CRITICAL - critical message

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

توجه داشته باشید که نام کلاس‌های ارجاع‌شده در پرونده‌های پیکربندی باید یا نسبت به ماژول logging نسبی باشند، یا مقادیر مطلقی باشند که بتوان آن‌ها را با استفاده از سازوکارهای عادی ایمپورت حل کرد. بنابراین، می‌توانید از WatchedFileHandler (نسبت به ماژول logging) یا mypackage.mymodule.MyHandler (برای کلاسی که در بسته‌ی mypackage و ماژول mymodule تعریف شده باشد و mypackage در مسیر ایمپورت پایتون در دسترس باشد) استفاده کنید.

در پایتون 3.2، روش جدیدی برای پیکربندی گزارش‌گیری معرفی شده است که در آن از دیکشنری‌ها برای نگه‌داری اطلاعات پیکربندی استفاده می‌شود. این روش، ابرمجموعه‌ای از قابلیت‌های رویکرد مبتنی بر پرونده پیکربندیِ ذکرشده در بالا را فراهم می‌کند و روش پیکربندی توصیه‌شده برای برنامه‌ها و استقرارهای جدید است. از آنجا که از یک دیکشنری پایتون برای نگه‌داری اطلاعات پیکربندی استفاده می‌شود، و از آنجا که می‌توانید آن دیکشنری را با روش‌های مختلفی پر کنید، گزینه‌های بیشتری برای پیکربندی دارید. برای مثال، می‌توانید از یک پرونده پیکربندی در قالب JSON، یا در صورت دسترسی به قابلیت پردازش YAML، از یک پرونده در قالب YAML، برای پر کردن دیکشنری پیکربندی استفاده کنید. یا البته، می‌توانید دیکشنری را در کد پایتون بسازید، آن را به‌صورت pickled از طریق یک سوکت دریافت کنید، یا از هر رویکردی که برای برنامه شما مناسب است استفاده کنید.

در اینجا نمونه‌ای از همان پیکربندی بالا، در قالب YAML برای رویکرد جدید مبتنی بر دیکشنری آمده است:

version: 1
formatters:
  simple:
    format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
handlers:
  console:
    class: logging.StreamHandler
    level: DEBUG
    formatter: simple
    stream: ext://sys.stdout
loggers:
  simpleExample:
    level: DEBUG
    handlers: [console]
    propagate: no
root:
  level: DEBUG
  handlers: [console]

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

اگر هیچ پیکربندی ارائه نشود، چه اتفاقی می‌افتد¶

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

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

پیکربندی گزارش برای یک کتابخانه¶

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

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

یک هندلر بدون عملیات در بسته‌ی logging گنجانده شده است: NullHandler (از پایتون 3.1). می‌توان یک نمونه از این هندلر را به گزارش‌گیر سطح بالای فضای نام گزارش‌گیری مورد استفاده‌ی کتابخانه اضافه کرد (اگر بخواهید در نبود پیکربندی گزارش‌گیری، از نوشته شدن رویدادهای گزارش‌شده‌ی کتابخانه‌تان در sys.stderr جلوگیری کنید). اگر تمام گزارش‌گیری کتابخانه‌ی foo با استفاده از گزارش‌گیرهایی با نام‌های مطابق با 'foo.x'، 'foo.x.y' و غیره انجام شود، آنگاه کد:

import logging
logging.getLogger('foo').addHandler(logging.NullHandler())

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

سطوح سفارشی¶

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