logging.handlers --- هندلرهای گزارش‌گیری (Logging handlers)

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

هندلرهای مفید زیر در این بسته ارائه شده‌اند. توجه داشته باشید که سه مورد از هندلرها (StreamHandler، FileHandler و NullHandler) در واقع در خود ماژول logging تعریف شده‌اند، اما در اینجا همراه با سایر هندلرها مستند شده‌اند.

StreamHandler

کلاس StreamHandler، واقع در بسته‌ی اصلی logging، خروجی ثبت گزارش‌گیری را به جریان‌هایی مانند sys.stdout، sys.stderr یا هر شیء شبه‌پرونده (یا، دقیق‌تر، هر شیءای که از متدهای write() و flush() پشتیبانی می‌کند) ارسال می‌کند.

class logging.StreamHandler(stream=None)

یک نمونه جدید از کلاس StreamHandler برمی‌گرداند. اگر stream مشخص شده باشد، نمونه از آن برای خروجی گزارش استفاده می‌کند؛ در غیر این صورت، از sys.stderr استفاده می‌شود.

emit(record)

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

flush()

جریان را با فراخوانی متد flush() خود تخلیه می‌کند. توجه داشته باشید که متد close() از Handler به ارث برده شده است و بنابراین هیچ خروجی نمی‌دهد، از این رو گاهی ممکن است به یک فراخوانی صریح flush() نیاز باشد.

setStream(stream)

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

پارامترها:

stream -- جریانی که هندلر باید از آن استفاده کند.

بازگشت ها:

جریان قدیمی، اگر جریان تغییر کرده باشد، یا None اگر تغییر نکرده باشد.

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

terminator

رشته‌ای که به‌عنوان پایان‌بند هنگام نوشتن یک رکورد قالب‌بندی‌شده در یک جریان استفاده می‌شود. مقدار پیش‌فرض '\n' است.

اگر پایان‌دهی با خط جدید را نمی‌خواهید، می‌توانید ویژگی terminator نمونه‌ی هندلر را روی رشته‌ی خالی تنظیم کنید.

در نسخه‌های پیشین، پایان‌دهنده به‌صورت سخت‌کد '\n' بود.

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

FileHandler

کلاس FileHandler که در بسته‌ی اصلی logging قرار دارد، خروجی گزارش‌گیری را به یک پرونده روی دیسک ارسال می‌کند. این کلاس قابلیت خروجی را از StreamHandler به ارث می‌برد.

class logging.FileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

نمونه‌ای جدید از کلاس FileHandler برمی‌گرداند. پرونده مشخص‌شده باز می‌شود و به‌عنوان جریان گزارش‌گیری استفاده می‌شود. اگر mode مشخص‌نشده باشد، از 'a' استفاده می‌شود. اگر encoding برابر None نباشد، از آن برای باز کردن پرونده با همان کدگذاری استفاده می‌شود. اگر delay درست باشد، باز شدن پرونده تا اولین فراخوانی emit() به تعویق می‌افتد. به‌طور پیش‌فرض، پرونده به‌طور نامحدود بزرگ می‌شود. اگر errors مشخص‌شده باشد، از آن برای تعیین نحوه‌ی مدیریت خطاهای کدگذاری استفاده می‌شود.

تغییر یافته در نسخه‌ی 3.6: علاوه بر مقادیر رشته‌ای، اشیای Path نیز برای آرگومان filename پذیرفته می‌شوند.

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

close()

پرونده را می‌بندد.

emit(record)

رکورد را در پرونده خروجی می‌دهد.

توجه داشته باشید که اگر پرونده به دلیل خاموش‌سازی گزارش‌گیری در هنگام خروج بسته شده باشد و حالت پرونده 'w' باشد، رکورد منتشر نخواهد شد (به bpo-42378 مراجعه کنید).

NullHandler

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

کلاس NullHandler، واقع‌شده در بسته‌ی هسته‌ی logging، هیچ‌گونه قالب‌بندی یا خروجی انجام نمی‌دهد. این کلاس در اصل یک هندلر عملیات بی‌اثر (no-op) برای استفاده توسعه‌دهندگان کتابخانه است.

class logging.NullHandler

یک نمونه جدید از کلاس NullHandler برمی‌گرداند.

emit(record)

این متد هیچ کاری انجام نمی‌دهد.

handle(record)

این متد هیچ کاری انجام نمی‌دهد.

createLock()

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

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

WatchedFileHandler

کلاس WatchedFileHandler که در ماژول logging.handlers قرار دارد، یک FileHandler است که پرونده‌ای را که در آن گزارش می‌کند پایش می‌کند. اگر پرونده تغییر کند، بسته می‌شود و با استفاده از نام پرونده دوباره باز می‌شود.

ممکن است تغییری در یک پرونده به دلیل استفاده از برنامه‌هایی مانند newsyslog و logrotate، که چرخش پرونده‌های گزارش را انجام می‌دهند، رخ دهد. این هندلر، که برای استفاده در Unix/Linux در نظر گرفته شده است، پرونده را پایش می‌کند تا ببیند آیا از آخرین ارسال (emit) تغییر کرده است یا خیر. (اگر دستگاه یا آی‌نود پرونده تغییر کرده باشد، پرونده تغییر کرده تلقی می‌شود.) اگر پرونده تغییر کرده باشد، جریان پرونده قدیمی بسته می‌شود و پرونده برای دریافت یک جریان جدید باز می‌شود.

این هندلر برای استفاده در ویندوز مناسب نیست، زیرا در ویندوز پرونده‌های گزارش باز قابل جابه‌جایی یا تغییر نام نیستند — logging پرونده‌ها را با قفل‌های انحصاری باز می‌کند — و بنابراین نیازی به چنین هندلری نیست. علاوه بر این، ST_INO در ویندوز پشتیبانی نمی‌شود؛ stat() همیشه برای این مقدار ۰ برمی‌گرداند.

class logging.handlers.WatchedFileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

یک نمونه جدید از کلاس WatchedFileHandler برمی‌گرداند. پرونده مشخص‌شده باز می‌شود و به‌عنوان جریان برای ثبت گزارش استفاده می‌شود. اگر mode مشخص نباشد، از 'a' استفاده می‌شود. اگر encoding برابر None نباشد، از آن برای باز کردن پرونده با همان کدگذاری استفاده می‌شود. اگر delay درست باشد، باز شدن پرونده تا اولین فراخوانی emit() به تعویق می‌افتد. به‌طور پیش‌فرض، پرونده بدون محدودیت رشد می‌کند. اگر errors ارائه شده باشد، چگونگی مدیریت خطاهای کدگذاری را تعیین می‌کند.

تغییر یافته در نسخه‌ی 3.6: علاوه بر مقادیر رشته‌ای، اشیای Path نیز برای آرگومان filename پذیرفته می‌شوند.

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

reopenIfNeeded()

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

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

emit(record)

رکورد را در پرونده خروجی می‌دهد، اما ابتدا reopenIfNeeded() را فراخوانی می‌کند تا در صورت تغییر پرونده، آن را دوباره باز کند.

BaseRotatingHandler

کلاس BaseRotatingHandler، واقع در ماژول logging.handlers، کلاس پایه برای هندلرهای پرونده چرخشی (rotating file handlers)، RotatingFileHandler و TimedRotatingFileHandler است. شما نباید نیازی به نمونه‌سازی از این کلاس داشته باشید، اما این کلاس دارای ویژگی‌ها و متدهایی است که ممکن است نیاز داشته باشید آن‌ها را بازنویسی کنید.

class logging.handlers.BaseRotatingHandler(filename, mode, encoding=None, delay=False, errors=None)

پارامترها مانند FileHandler هستند. ویژگی‌ها عبارتند از:

namer

اگر این ویژگی روی یک شیء فراخوانی‌پذیر تنظیم شود، متد rotation_filename() به این callable واگذار می‌شود. پارامترهای ارسال‌شده به این callable، همان پارامترهایی هستند که به rotation_filename() ارسال شده‌اند.

توجه

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

همچنین لازم است توجه داشته باشید که هنگام استفاده از یک نام‌گذار (namer)، باید دقت کنید که برخی ویژگی‌های خاص در نام پرونده که در حین چرخش استفاده می‌شوند، حفظ شوند. برای مثال، RotatingFileHandler انتظار دارد مجموعه‌ای از پرونده‌های گزارش وجود داشته باشند که نام‌هایشان حاوی اعداد صحیح متوالی باشد، تا چرخش همان‌طور که انتظار می‌رود کار کند، و TimedRotatingFileHandler پرونده‌های گزارش قدیمی را (بر اساس پارامتر backupCount که به راه‌انداز handler ارسال می‌شود) با تعیین قدیمی‌ترین پرونده‌ها برای حذف، حذف می‌کند. برای این که این اتفاق بیفتد، نام‌های پرونده باید با استفاده از بخش تاریخ/ساعتِ نام پرونده قابل مرتب‌سازی باشند، و یک نام‌گذار باید این موضوع را رعایت کند. (اگر بخواهید از یک نام‌گذار استفاده کنید که این طرح‌واره را رعایت نمی‌کند، لازم است آن را در یک زیرکلاس از TimedRotatingFileHandler به کار ببرید که متد getFilesToDelete() را برای هماهنگی با طرح‌واره نام‌گذاری سفارشی بازنویسی می‌کند.)

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

rotator

اگر این ویژگی به یک شیء فراخوانی‌پذیر تنظیم شود، متد rotate() به این شیء فراخوانی‌پذیر واگذار می‌شود. پارامترهای ارسال‌شده به این شیء قابل فراخوانی، همان پارامترهای ارسال‌شده به rotate() هستند.

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

rotation_filename(default_name)

هنگام چرخش، نام یک پرونده گزارش را تغییر دهید.

این فراهم شده است تا بتوانید یک نام پرونده سفارشی ارائه دهید.

پیاده‌سازی پیش‌فرض، ویژگی 'namer' از هندلر را فراخوانی می‌کند، مشروط بر اینکه فراخوانی‌پذیر باشد، و نام پیش‌فرض را به آن می‌دهد. اگر این ویژگی فراخوانی‌پذیر نباشد (پیش‌فرض None است)، نام بدون تغییر بازگردانده می‌شود.

پارامترها:

default_name -- نام پیش‌فرض برای پرونده گزارش.

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

rotate(source, dest)

هنگام چرخش، گزارش فعلی را بچرخانید.

پیاده‌سازی پیش‌فرض، ویژگی 'rotator' هندلر را، در صورتی که قابل فراخوانی باشد، فراخوانی می‌کند و آرگومان‌های source و dest را به آن می‌دهد. اگر این ویژگی فراخوانی‌پذیر نباشد (مقدار پیش‌فرض None است)، source به‌سادگی به مقصد تغییر نام داده می‌شود.

پارامترها:

  • source -- نام پرونده منبع. این معمولاً نام پرونده پایه است، مثلاً 'test.log'.

  • dest -- نام پرونده مقصد. این معمولاً همان چیزی است که منبع به آن چرخش داده می‌شود، مثلاً 'test.log.1'.

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

دلیل وجود این ویژگی‌ها این است که شما را از نیاز به زیرکلاس‌سازی (subclass) بی‌نیاز کند؛ می‌توانید از همان فراخوانی‌پذیرها برای نمونه‌های RotatingFileHandler و TimedRotatingFileHandler استفاده کنید. اگر هر یک از فراخوانی‌پذیرهای namer یا rotator استثنایی را پرتاب کند، این استثنا به همان شیوه‌ای که هر استثنای دیگری در طول یک فراخوانی emit() مدیریت می‌شود، مدیریت خواهد شد، یعنی از طریق متد handleError() در هندلر .

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

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

RotatingFileHandler

کلاس RotatingFileHandler، که در ماژول logging.handlers قرار دارد، از چرخش پرونده‌های گزارش روی دیسک پشتیبانی می‌کند.

class logging.handlers.RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)

یک نمونه جدید از کلاس RotatingFileHandler برمی‌گرداند. پرونده مشخص‌شده باز می‌شود و به‌عنوان جریان برای گزارش‌کردن استفاده می‌شود. اگر mode مشخص‌نشده باشد، 'a' استفاده می‌شود. اگر encoding برابر None نباشد، از آن برای باز کردن پرونده با همان کدگذاری استفاده می‌شود. اگر delay درست باشد، باز کردن پرونده تا نخستین فراخوانی emit() به تعویق می‌افتد. به‌طور پیش‌فرض، پرونده به‌طور نامحدود رشد می‌کند. اگر errors ارائه‌شده باشد، چگونگی مدیریت خطاهای کدگذاری را تعیین می‌کند.

شما می‌توانید از مقدارهای maxBytes و backupCount استفاده کنید تا پرونده در اندازه‌ای از پیش تعیین‌شده چرخش <rollover> کند. هنگامی که اندازه‌ی پرونده در آستانه‌ی بیشتر شدن از این اندازه باشد، پرونده بسته می‌شود و پرونده جدیدی به‌صورت بی‌صدا برای خروجی باز می‌شود. چرخش هر زمان رخ می‌دهد که طول پرونده گزارش جاری نزدیک به maxBytes باشد؛ اما اگر هر یک از maxBytes یا backupCount صفر باشد، چرخش هرگز رخ نمی‌دهد، بنابراین معمولاً می‌خواهید backupCount را حداقل روی ۱ تنظیم کنید و maxBytes غیرصفر داشته باشید. هنگامی که backupCount غیرصفر باشد، سامانه فایل‌بندی‌های گزارش قدیمی را با افزودن پسوندهای '.1'، '.2' و غیره به نام پرونده ذخیره می‌کند. برای مثال، با backupCount برابر ۵ و نام پایه‌ی پرونده app.log، app.log، app.log.1، app.log.2 و به‌همین ترتیب تا app.log.5 را خواهید داشت. پرونده‌ای که در آن نوشته می‌شود همیشه app.log است. هنگامی که این پرونده پر شود، بسته می‌شود و به app.log.1 تغییر نام می‌یابد، و اگر پرونده‌های app.log.1، app.log.2 و غیره وجود داشته باشند، به‌ترتیب به app.log.2، app.log.3 و غیره تغییر نام می‌یابند.

تغییر یافته در نسخه‌ی 3.6: علاوه بر مقادیر رشته‌ای، اشیای Path نیز برای آرگومان filename پذیرفته می‌شوند.

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

doRollover()

یک چرخش انجام می‌دهد، همان‌طور که در بالا توضیح داده شد.

emit(record)

رکورد را در پرونده خروجی می‌دهد و چرخش را همان‌طور که پیش‌تر توضیح داده شد، مدیریت می‌کند.

shouldRollover(record)

بررسی کنید که آیا رکورد ارائه‌شده باعث می‌شود پرونده از محدودیت اندازه‌ی پیکربندی‌شده فراتر رود.

TimedRotatingFileHandler

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

class logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=None)

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

می‌توانید از when برای تعیین نوع interval استفاده کنید. فهرست مقادیر ممکن در زیر آمده است. توجه داشته باشید که آن‌ها به بزرگی و کوچکی حروف حساس نیستند.

مقدار

نوع بازه

اینکه آیا/چگونه از atTime استفاده می‌شود

'S'

ثانیه‌ها

نادیده گرفته می‌شود

'M'

دقیقه‌ها

نادیده گرفته می‌شود

'H'

ساعت‌ها

نادیده گرفته می‌شود

'D'

روزها

نادیده گرفته می‌شود

'W0'-'W6'

روز هفته (۰=دوشنبه)

برای محاسبه زمان چرخش اولیه استفاده می‌شود

'midnight'

اگر atTime مشخص نشده باشد، چرخش در نیمه‌شب انجام می‌شود، در غیر این صورت در زمان atTime انجام می‌شود

برای محاسبه زمان چرخش اولیه استفاده می‌شود

هنگام استفاده از چرخش مبتنی بر روز هفته، 'W0' را برای دوشنبه، 'W1' را برای سه‌شنبه، و به همین ترتیب تا 'W6' را برای یکشنبه مشخص کنید. در این حالت، مقدار ارسال‌شده برای interval استفاده نمی‌شود.

سامانه فایل‌بندی‌های گزارش قدیمی را با افزودن پسوندها به نام پرونده ذخیره می‌کند. این پسوندها مبتنی بر تاریخ و زمان هستند و بسته به بازه‌ی چرخش، از قالب strftime به‌صورت %Y-%m-%d_%H-%M-%S یا بخش ابتدایی آن استفاده می‌کنند.

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

اگر آرگومان utc درست باشد، از زمان‌های UTC استفاده می‌شود؛ در غیر این صورت از زمان محلی استفاده می‌شود.

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

اگر delay مقدار true داشته باشد، باز شدن پرونده تا نخستین فراخوانی emit() به تعویق می‌افتد.

اگر atTime برابر None نباشد، باید نمونه‌ای از datetime.time باشد که ساعتی از شبانه‌روز را که چرخش در آن رخ می‌دهد مشخص می‌کند، برای حالت‌هایی که چرخش برای وقوع در «نیمه‌شب» یا «یک روز خاص هفته» تنظیم شده است. توجه داشته باشید که در این حالت‌ها، مقدار atTime عملاً برای محاسبه‌ی چرخش اولیه استفاده می‌شود و چرخش‌های بعدی از طریق محاسبه‌ی بازه‌ی معمول محاسبه خواهند شد.

اگر errors مشخص شده باشد، از آن برای تعیین چگونگی مدیریت خطاهای کدگذاری استفاده می‌شود.

توجه

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

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

تغییر یافته در نسخه‌ی 3.6: علاوه بر مقادیر رشته‌ای، اشیای Path نیز برای آرگومان filename پذیرفته می‌شوند.

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

doRollover()

یک چرخش انجام می‌دهد، همان‌طور که در بالا توضیح داده شد.

emit(record)

رکورد را در پرونده می‌نویسد و چرخش را همان‌طور که در بالا توضیح داده شد، مدیریت می‌کند.

getFilesToDelete()

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

shouldRollover(record)

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

SocketHandler

کلاس SocketHandler، که در ماژول logging.handlers قرار دارد، خروجی گزارش‌دهی را به یک سوکت شبکه ارسال می‌کند. کلاس پایه از یک سوکت TCP استفاده می‌کند.

class logging.handlers.SocketHandler(host, port)

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

تغییر یافته در نسخه‌ی 3.4: اگر port به‌صورت None مشخص شود، یک سوکت دامنه‌ی Unix با استفاده از مقدار host ایجاد می‌شود؛ در غیر این صورت، یک سوکت TCP ایجاد می‌شود.

close()

سوکت را می‌بندد.

emit()

دیکشنری ویژگی‌های رکورد را پیکل می‌کند و آن را با قالب دودویی در سوکت می‌نویسد. اگر خطایی در سوکت رخ دهد، بسته را به‌صورت بی‌صدا دور می‌اندازد. اگر اتصال پیش‌تر قطع شده باشد، اتصال را دوباره برقرار می‌کند. برای پیکل‌گشایی (unpickle) رکورد در سمت دریافت‌کننده به یک LogRecord، از تابع makeLogRecord() استفاده کنید.

handleError()

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

makeSocket()

این یک متد کارخانه‌ای است که به زیرکلاس‌ها امکان می‌دهد نوع دقیق سوکت مورد نظر خود را تعریف کنند. پیاده‌سازی پیش‌فرض یک سوکت TCP ایجاد می‌کند (socket.SOCK_STREAM).

makePickle(record)

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

data = pickle.dumps(record_attr_dict, 1)
datalen = struct.pack('>L', len(data))
return datalen + data

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

send(packet)

یک بسته رشته بایتی پیکل‌شده را به سوکت ارسال کنید. قالب رشته بایتی ارسال‌شده همان‌گونه است که در مستندات makePickle() توضیح داده شده است.

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

createSocket()

تلاش می‌کند یک سوکت ایجاد کند؛ در صورت شکست، از یک الگوریتم پس‌روی نمایی (exponential back-off) استفاده می‌کند. در اولین شکست، هندلر پیامی را که سعی در ارسال آن داشت، رها می‌کند. هنگامی که پیام‌های بعدی توسط همان نمونه رسیدگی شوند، تا مدتی سپری نشده باشد، برای برقراری اتصال تلاش نمی‌کند. پارامترهای پیش‌فرض به‌گونه‌ای هستند که تأخیر اولیه ۱ ثانیه است و اگر پس از آن تأخیر نیز اتصال برقرار نشد، هندلر هر بار تأخیر را دو برابر می‌کند، تا حداکثر ۳۰ ثانیه.

این رفتار با ویژگی‌های زیرِ هندلر کنترل می‌شود:

  • retryStart (تأخیر اولیه، با مقدار پیش‌فرض ۱٫۰ ثانیه).

  • retryFactor (ضریب، با مقدار پیش‌فرض 2.0).

  • retryMax (حداکثر تأخیر، با مقدار پیش‌فرض ۳۰٫۰ ثانیه).

این بدان معناست که اگر شنونده راه دور (remote listener) پس از استفاده از هندلر راه‌اندازی شود، ممکن است پیام‌ها را از دست بدهید (زیرا مدیر تا زمانی که تأخیر سپری نشود، حتی برای برقراری اتصال تلاش نمی‌کند، بلکه در طول بازه تأخیر، فقط پیام‌ها را بی‌صدا دور می‌ریزد).

DatagramHandler

کلاس DatagramHandler، واقع در ماژول logging.handlers، از SocketHandler ارث می‌برد تا از ارسال پیام‌های گزارش بر روی سوکت‌های UDP پشتیبانی کند.

class logging.handlers.DatagramHandler(host, port)

یک نمونه جدید از کلاس DatagramHandler برمی‌گرداند که برای ارتباط با یک ماشین راه‌دور در نظر گرفته شده است و نشانی آن با host و port داده شده است.

توجه

از آن‌جا که UDP پروتکل جریانی نیست، هیچ اتصال پایداری بین نمونه‌ای از این هندلر و host وجود ندارد. به همین دلیل، هنگام استفاده از یک سوکت شبکه، ممکن است هر بار که رویدادی ثبت می‌شود، لازم باشد یک جستجوی DNS انجام شود؛ این موضوع می‌تواند مقداری تأخیر در سیستم ایجاد کند. اگر این مسئله بر شما تأثیر می‌گذارد، می‌توانید خودتان یک جستجو انجام دهید و این هندلر را به جای نام میزبان، با استفاده از آدرس IP حاصل از جستجو راه‌اندازی کنید.

تغییر یافته در نسخه‌ی 3.4: اگر port به‌صورت None تعیین شده باشد، یک سوکت دامنه‌ی یونیکس با استفاده از مقدار host ایجاد می‌شود؛ در غیر این صورت، یک سوکت UDP ایجاد می‌شود.

emit()

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

makeSocket()

در اینجا متد کارخانه‌ای (factory method) SocketHandler بازنویسی شده است تا یک سوکت UDP (socket.SOCK_DGRAM) ایجاد کند.

send(s)

یک رشته بایتی پیکل‌شده را به یک سوکت ارسال می‌کند. قالب رشته بایتی ارسال‌شده همان‌گونه است که در مستندات SocketHandler.makePickle() توضیح داده شده است.

SysLogHandler

کلاس SysLogHandler، واقع در ماژول logging.handlers، از ارسال پیام‌های گزارش‌دهی به syslog یونیکس دوردست یا محلی پشتیبانی می‌کند.

class logging.handlers.SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM, timeout=None)

یک نمونه‌ی جدید از کلاس SysLogHandler را برمی‌گرداند که برای ارتباط با یک ماشین یونیکسی راه‌دور در نظر گرفته شده است و نشانی آن از طریق address در قالب یک تاپل (host, port) داده شده است. اگر address مشخص نشده باشد، از ('localhost', 514) استفاده می‌شود. از این نشانی برای باز کردن یک سوکت استفاده می‌شود. جایگزینی برای ارائه یک تاپل (host, port)، ارائه یک نشانی به‌صورت یک رشته است، برای مثال '/dev/log'. در این حالت، از یک سوکت دامنه‌ی یونیکس برای ارسال پیام به syslog استفاده می‌شود. اگر facility مشخص نشده باشد، از LOG_USER استفاده می‌شود. نوع سوکتی که باز می‌شود به آرگومان socktype بستگی دارد، که مقدار پیش‌فرض آن socket.SOCK_DGRAM است و بنابراین یک سوکت UDP باز می‌شود. برای باز کردن یک سوکت TCP (برای استفاده با دیمن‌های syslog جدیدتر مانند rsyslog)، مقدار socket.SOCK_STREAM را مشخص کنید. اگر timeout مشخص شده باشد، یک مهلت (بر حسب ثانیه) برای عملیات سوکت تنظیم می‌شود. این کار می‌تواند به جلوگیری از آویزان شدن برنامه به‌طور نامحدود در صورت غیرقابل‌دسترس بودن سرور syslog کمک کند. به‌طور پیش‌فرض، timeout برابر None است، به این معنا که هیچ مهلتی اعمال نمی‌شود.

توجه داشته باشید که اگر سرور شما به پورت UDP ۵۱۴ گوش نمی‌دهد، SysLogHandler ممکن است به نظر برسد که کار نمی‌کند. در آن صورت، بررسی کنید که باید از چه نشانی‌ای برای سوکت دامنه (domain socket) استفاده کنید — این موضوع وابسته به سیستم است. برای مثال، در لینوکس این نشانی معمولاً '/dev/log' است، اما در OS/X برابر '/var/run/syslog' است. باید پلتفرم خود را بررسی کنید و از نشانی مناسب استفاده کنید (اگر برنامه شما باید روی چندین پلتفرم اجرا شود، ممکن است لازم باشد این بررسی را در ران‌تایم انجام دهید). در ویندوز، عملاً باید از گزینه UDP استفاده کنید.

توجه

در macOS 12.x (Monterey)، اپل رفتار syslog daemon خود را تغییر داده است؛ این سرویس دیگر روی یک سوکت دامنه (domain socket) گوش نمی‌دهد. بنابراین، نمی‌توانید انتظار داشته باشید که SysLogHandler روی این سیستم کار کند.

برای اطلاعات بیشتر gh-91070 را ببینید.

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

تغییر یافته در نسخه‌ی 3.14: timeout اضافه شد.

close()

سوکت به میزبان راه دور را می‌بندد.

createSocket()

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

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

emit(record)

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

تغییر یافته در نسخه‌ی 3.2.1: (نگاه کنید به bpo-12168.) در نسخه‌های پیشین، پیام ارسال‌شده به دِیمِن‌های syslog همیشه با یک بایت NUL ختم می‌شد، زیرا نسخه‌های اولیه این دِیمِن‌ها انتظار داشتند پیام با NUL ختم شود — هرچند این موضوع در مشخصات مربوطه (RFC 5424) وجود ندارد. نسخه‌های جدیدتر این دِیمِن‌ها انتظار بایت NUL را ندارند، اما اگر وجود داشته باشد آن را حذف می‌کنند، و دِیمِن‌های حتی جدیدتر (که RFC 5424 را دقیق‌تر رعایت می‌کنند) بایت NUL را به‌عنوان بخشی از پیام منتقل می‌کنند.

برای آسان‌تر کردن مدیریت پیام‌های syslog در برابر همه‌ی این رفتارهای متفاوت دِیمِن‌ها (daemon)، افزودن بایت NUL از طریق استفاده از یک ویژگی در سطح کلاس، append_nul، قابل‌پیکربندی شده است. این ویژگی به‌طور پیش‌فرض True است (با حفظ رفتار موجود) اما می‌توان آن را در یک نمونه SysLogHandler روی False تنظیم کرد تا آن نمونه پایان‌کننده‌ی NUL را اضافه نکند.

تغییر یافته در نسخه‌ی 3.3: (رجوع کنید: bpo-12419.) در نسخه‌های پیشین، امکانی برای پیشوند «ident» یا «tag» جهت شناسایی منبع پیام وجود نداشت. اکنون می‌توان این پیشوند را با استفاده از یک ویژگی سطح کلاس مشخص کرد، که به‌طور پیش‌فرض "" است تا رفتار موجود حفظ شود، اما می‌توان این ویژگی را در یک نمونه SysLogHandler بازنویسی کرد تا آن نمونه ident را به ابتدای هر پیام پردازش‌شده اضافه کند. توجه داشته باشید که ident ارائه‌شده باید متن باشد، نه بایت، و دقیقاً همان‌طور که هست به ابتدای پیام اضافه می‌شود.

encodePriority(facility, priority)

امکانات (facility) و اولویت (priority) را به‌صورت یک عدد صحیح کدگذاری می‌کند. شما می‌توانید رشته‌ها یا اعداد صحیح را ارسال کنید؛ اگر رشته‌ها ارسال شوند، از دیکشنری‌های نگاشت داخلی برای تبدیل آن‌ها به اعداد صحیح استفاده می‌شود.

مقادیر نمادین LOG_ در SysLogHandler تعریف شده‌اند و با مقادیر تعریف‌شده در پرونده‌ی سرآیند sys/syslog.h مطابقت دارند.

اولویت‌ها

نام (رشته)

مقدار نمادین

alert

LOG_ALERT

crit یا critical

LOG_CRIT

debug

LOG_DEBUG

emerg یا panic

LOG_EMERG

err یا error

LOG_ERR

info

LOG_INFO

notice

LOG_NOTICE

warn یا warning

LOG_WARNING

امکانات

نام (رشته)

مقدار نمادین

auth

LOG_AUTH

authpriv

LOG_AUTHPRIV

cron

LOG_CRON

daemon

LOG_DAEMON

ftp

LOG_FTP

kern

LOG_KERN

lpr

LOG_LPR

mail

LOG_MAIL

news

LOG_NEWS

syslog

LOG_SYSLOG

user

LOG_USER

uucp

LOG_UUCP

local0

LOG_LOCAL0

local1

LOG_LOCAL1

local2

LOG_LOCAL2

local3

LOG_LOCAL3

local4

LOG_LOCAL4

local5

LOG_LOCAL5

local6

LOG_LOCAL6

local7

LOG_LOCAL7
mapPriority(levelname)

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

NTEventLogHandler

کلاس NTEventLogHandler، واقع در ماژول logging.handlers، از ارسال پیام‌های گزارش به گزارش رویداد محلی Windows NT، Windows 2000 یا Windows XP پشتیبانی می‌کند. پیش از آنکه بتوانید از آن استفاده کنید، باید افزونه‌های Win32 Mark Hammond برای Python نصب شده باشند.

class logging.handlers.NTEventLogHandler(appname, dllname=None, logtype='Application')

یک نمونه جدید از کلاس NTEventLogHandler برمی‌گرداند. appname برای تعریف نام برنامه، آن‌گونه که در گزارش رویداد ظاهر می‌شود، استفاده می‌شود. یک ورودی رجیستری مناسب با استفاده از این نام ایجاد می‌شود. dllname باید مسیر کامل یک .dll یا .exeای باشد که حاوی تعریف پیام‌هایی است که در گزارش نگهداری می‌شوند (اگر مشخص نشود، 'win32service.pyd' استفاده می‌شود؛ این مورد همراه با افزونه‌های Win32 نصب می‌شود و حاوی چند تعریف پیام پایه‌ی جای‌نگهدار است. توجه داشته باشید که استفاده از این جای‌نگهدارها باعث بزرگ شدن گزارش‌های رویداد شما می‌شود، زیرا کل منبع پیام در گزارش نگهداری می‌شود. اگر گزارش‌های کم‌حجم‌تر می‌خواهید، باید نام .dll یا .exe خودتان را که حاوی تعریف پیام‌هایی است که می‌خواهید در گزارش رویداد استفاده کنید، ارسال کنید). logtype یکی از 'Application'، 'System' یا 'Security' است و مقدار پیش‌فرض آن 'Application' است.

close()

در این مرحله، می‌توانید نام برنامه را به‌عنوان منبع ورودی‌های گزارش رویداد از رجیستری حذف کنید. با این حال، اگر این کار را انجام دهید، نمی‌توانید رویدادها را آن‌گونه که قصد داشتید در نمایشگر Event Log ببینید — این نمایشگر باید بتواند برای دریافت نام .dll به رجیستری دسترسی داشته باشد. نسخه فعلی این کار را انجام نمی‌دهد.

emit(record)

شناسه‌ی پیام، دسته رویداد و نوع رویداد را تعیین می‌کند و سپس پیام را در گزارش رویداد NT ثبت می‌کند.

getEventCategory(record)

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

getEventType(record)

نوع رویداد را برای رکورد برمی‌گرداند. اگر می‌خواهید نوع‌های خودتان را مشخص کنید، این متد را بازنویسی کنید. این نسخه با استفاده از ویژگی typemap هندلر یک نگاشت انجام می‌دهد، که در __init__() به دیکشنری‌ای تنظیم می‌شود که شامل نگاشت‌هایی برای DEBUG، INFO، WARNING، ERROR و CRITICAL است. اگر از سطح‌های خودتان استفاده می‌کنید، یا باید این متد را بازنویسی کنید یا یک دیکشنری مناسب در ویژگی typemap هندلر قرار دهید.

getMessageID(record)

شناسه پیام رکورد را برمی‌گرداند. اگر از پیام‌های خودتان استفاده می‌کنید، می‌توانید این کار را به این صورت انجام دهید که msg ارسال‌شده به گزارش‌گیر یک شناسه باشد، نه یک رشته قالب. سپس، در اینجا می‌توانید از یک جستجو در دیکشنری برای دریافت شناسه پیام استفاده کنید. این نسخه ۱ را برمی‌گرداند که شناسه پیام پایه در win32service.pyd است.

SMTPHandler

کلاس SMTPHandler، که در ماژول logging.handlers قرار دارد، از ارسال پیام‌های گزارش به یک نشانی ایمیل از طریق SMTP پشتیبانی می‌کند.

class logging.handlers.SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)

یک نمونه جدید از کلاس SMTPHandler برمی‌گرداند. این نمونه با آدرس‌های فرستنده و گیرنده و خط موضوع ایمیل مقداردهی اولیه می‌شود. toaddrs باید فهرستی از رشته‌ها باشد. برای مشخص کردن یک پورت SMTP غیراستاندارد، از قالب تاپلبه‌شکل (host, port) برای آرگومان mailhost استفاده کنید. اگر از یک رشته استفاده کنید، از پورت استاندارد SMTP استفاده می‌شود. اگر سرور SMTP شما به احراز هویت نیاز دارد، می‌توانید یک تاپلبه‌شکل (username, password) برای آرگومان credentials مشخص کنید.

برای مشخص کردن استفاده از یک پروتکل امن (TLS)، یک تاپل را به آرگومان secure ارسال کنید. این مورد تنها زمانی استفاده می‌شود که اعتبارنامه‌های احراز هویت ارائه شده باشند. این تاپل باید یا تاپلی خالی باشد، یا تاپلی تک‌مقداری شامل نام پرونده کلید، یا تاپلی با ۲ مقدار شامل نام‌های پرونده کلید و پرونده گواهی باشد. (این تاپل به متد smtplib.SMTP.starttls() ارسال می‌شود.)

می‌توان برای ارتباط با سرور SMTP، یک مهلت زمانی را با استفاده از آرگومان timeout تعیین کرد.

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

emit(record)

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

getSubject(record)

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

MemoryHandler

کلاس MemoryHandler، که در ماژول logging.handlers قرار دارد، از بافر کردن رکوردهای گزارش در حافظه پشتیبانی می‌کند و آن‌ها را به‌صورت دوره‌ای به یک هندلر target تخلیه می‌کند. تخلیه هر زمان که بافر پر باشد، یا زمانی که رویدادی با شدت معین یا بیشتر مشاهده شود، رخ می‌دهد.

MemoryHandler زیرکلاسی از BufferingHandler است که کلاسی کلی‌تر و انتزاعی می‌باشد. این کلاس رکوردهای گزارش‌دهی را در حافظه بافر می‌کند. هر بار که رکوردی به بافر اضافه می‌شود، با فراخوانی shouldFlush() بررسی می‌شود که آیا بافر باید تخلیه شود یا خیر. اگر باید تخلیه شود، انتظار می‌رود flush() تخلیه را انجام دهد.

class logging.handlers.BufferingHandler(capacity)

هندلر را با بافری با ظرفیت مشخص، مقداردهی اولیه می‌کند. در اینجا، capacity به معنای تعداد رکوردهای گزارش (logging records) نگهداری‌شده در بافر است.

emit(record)

رکورد را به بافر اضافه کنید. اگر shouldFlush() مقدار true را برگرداند، برای پردازش بافر flush() را فراخوانی کنید.

flush()

برای یک نمونه از BufferingHandler، تخلیه به این معناست که بافر روی یک فهرست خالی تنظیم شود. می‌توان این متد را بازنویسی کرد تا رفتار تخلیه‌ی مفیدتری پیاده‌سازی شود.

shouldFlush(record)

اگر بافر به ظرفیت خود رسیده باشد، True را برمی‌گرداند. این متد می‌تواند برای پیاده‌سازی راهبردهای سفارشی تخلیه بازنویسی شود.

class logging.handlers.MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True)

نمونه‌ای جدید از کلاس MemoryHandler برمی‌گرداند. این نمونه با اندازه بافر capacity (تعداد رکوردهای نگهداری‌شده در بافر) مقداردهی اولیه می‌شود. اگر flushLevel مشخص نشده باشد، از ERROR استفاده می‌شود. اگر target مشخص نشده باشد، پیش از آنکه این هندلر کار مفیدی انجام دهد، باید هدف با استفاده از setTarget() تنظیم شود. اگر flushOnClose به‌صورت False مشخص شده باشد، آنگاه بافر هنگام بستن هندلر تخلیه نمی‌شود. اگر مشخص نشده باشد یا به‌صورت True مشخص شده باشد، رفتار پیشین یعنی تخلیه بافر هنگام بستن هندلر رخ خواهد داد.

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

close()

flush() را فراخوانی می‌کند، هدف را روی None تنظیم می‌کند و بافر را پاک می‌کند.

flush()

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

setTarget(target)

هندلر هدف را برای این هندلر تنظیم می‌کند.

shouldFlush(record)

پر بودن بافر یا وجود یک رکورد در flushLevel یا بالاتر را بررسی می‌کند.

HTTPHandler

کلاس HTTPHandler، که در ماژول logging.handlers قرار دارد، از ارسال پیام‌های گزارش به یک وب‌سرور با استفاده از معنای GET یا POST پشتیبانی می‌کند.

class logging.handlers.HTTPHandler(host, url, method='GET', secure=False, credentials=None, context=None)

یک نمونه جدید از کلاس HTTPHandler برمی‌گرداند. host می‌تواند به شکل host:port باشد، در صورتی که بخواهید از شماره پورت خاصی استفاده کنید. اگر method مشخص نشده باشد، GET استفاده می‌شود. اگر secure درست باشد، از اتصال HTTPS استفاده خواهد شد. پارامتر context می‌تواند به یک نمونه از ssl.SSLContext تنظیم شود تا تنظیمات SSL مورد استفاده برای اتصال HTTPS پیکربندی شود. اگر credentials مشخص شده باشد، باید یک تاپل دوتایی شامل شناسه کاربری و گذرواژه باشد که در سرآیند HTTP 'Authorization' با استفاده از احراز هویت Basic قرار می‌گیرد. اگر credentials را مشخص کنید، باید secure=True را نیز مشخص کنید تا شناسه کاربری و گذرواژه شما به‌صورت متن آشکار در شبکه ارسال نشوند.

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

mapLogRecord(record)

دیکشنری‌ای بر اساس record فراهم می‌کند که باید کدگذاری URL (URL-encoded) شود و به سرور وب فرستاده شود. پیاده‌سازی پیش‌فرض فقط record.__dict__ را برمی‌گرداند. این متد را می‌توان بازنویسی کرد، اگر برای مثال قرار باشد تنها زیرمجموعه‌ای از LogRecord به سرور وب فرستاده شود، یا اگر سفارشی‌سازی خاص‌تری برای آنچه به سرور فرستاده می‌شود لازم باشد.

emit(record)

رکورد را به‌عنوان یک دیکشنری کدگذاری‌شده به‌صورت URL به وب‌سرور ارسال می‌کند. از متد mapLogRecord() برای تبدیل رکورد به دیکشنری ارسالی استفاده می‌شود.

توجه

از آن‌جا که آماده‌سازی یک رکورد برای ارسال آن به یک وب‌سرور، با یک عملیات قالب‌بندی عام یکسان نیست، استفاده از setFormatter() برای تعیین یک Formatter برای HTTPHandler هیچ تأثیری ندارد. این هندلر به‌جای فراخوانی format()، ابتدا mapLogRecord() و سپس urllib.parse.urlencode() را فراخوانی می‌کند تا دیکشنری را به شکلی مناسب برای ارسال به یک وب‌سرور کدگذاری کند.

QueueHandler

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

کلاس QueueHandler، واقع در ماژول logging.handlers، از ارسال پیام‌های گزارش به یک صف پشتیبانی می‌کند، مانند آن‌هایی که در ماژول‌های queue یا multiprocessing پیاده‌سازی شده‌اند.

در کنار کلاس QueueListener، می‌توان از QueueHandler استفاده کرد تا هندلرها کار خود را روی نخ جداگانه‌ای از نخی که ثبت گزارش را انجام می‌دهد، انجام دهند. این موضوع در برنامه‌های وب و همچنین سایر برنامه‌های خدماتی اهمیت دارد؛ جایی که نخ‌های خدمات‌دهنده به کلاینت‌ها باید تا حد ممکن سریع پاسخ دهند، در حالی که هرگونه عملیات بالقوه کند (مانند ارسال ایمیل از طریق SMTPHandler) روی نخ جداگانه‌ای انجام می‌شود.

class logging.handlers.QueueHandler(queue)

یک نمونه جدید از کلاس QueueHandler برمی‌گرداند. این نمونه با صفی برای ارسال پیام‌ها به آن مقداردهی اولیه می‌شود. queue می‌تواند هر شیء صف‌مانند باشد؛ این شیء همان‌طور که هست توسط متد enqueue() استفاده می‌شود، که باید بداند چگونه پیام‌ها را به آن ارسال کند. داشتن API پیگیری وظیفه برای صف الزامی نیست، که به این معناست که می‌توانید از نمونه‌های SimpleQueue برای queue استفاده کنید.

توجه

اگر از multiprocessing استفاده می‌کنید، باید از به‌کارگیری SimpleQueue خودداری کنید و به‌جای آن از multiprocessing.Queue استفاده کنید.

هشدار

ماژول multiprocessing از یک گزارش‌گیر داخلی استفاده می‌کند که از طریق get_logger() ایجاد و به آن دسترسی پیدا می‌شود. multiprocessing.Queue هنگام قرار گرفتن آیتم‌ها در صف، پیام‌هایی در سطح DEBUG ثبت می‌کند. اگر آن پیام‌های گزارش توسط یک QueueHandler با استفاده از همان نمونه multiprocessing.Queue پردازش شوند، باعث بن‌بست یا بازگشت بی‌نهایت خواهد شد.

emit(record)

نتیجه‌ی آماده‌سازی LogRecord را در صف قرار می‌دهد. در صورت بروز استثنا (مثلاً به این دلیل که یک صف محدود پر شده باشد)، متد handleError() برای رسیدگی به خطا فراخوانی می‌شود. این می‌تواند منجر به حذف بی‌صدای رکورد (اگر logging.raiseExceptions برابر False باشد) یا چاپ یک پیام در sys.stderr (اگر logging.raiseExceptions برابر True باشد) شود.

prepare(record)

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

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

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

توجه

پیاده‌سازی پایه، پیام را با آرگومان‌ها قالب‌بندی می‌کند، ویژگی‌های message و msg را روی پیام قالب‌بندی‌شده تنظیم می‌کند و ویژگی‌های args و exc_text را روی None تنظیم می‌کند تا امکان پیکل‌کردن فراهم شود و از تلاش‌های بعدی برای قالب‌بندی جلوگیری شود. این بدان معناست که یک هندلر در سمت QueueListener اطلاعات لازم برای انجام قالب‌بندی سفارشی، برای مثال قالب‌بندی استثناها، را نخواهد داشت. ممکن است بخواهید یک زیرکلاس از QueueHandler بسازید و این متد را بازنویسی کنید تا برای مثال از تنظیم exc_text روی None خودداری کنید. توجه داشته باشید که تغییرات message / msg / args به اطمینان از قابل پیکل‌کردن (pickleable) بودن رکورد مربوط است و ممکن است بتوانید یا نتوانید از انجام آن خودداری کنید، بسته به اینکه args شما قابل پیکل‌کردن (pickleable) باشند یا خیر. (توجه داشته باشید که ممکن است لازم باشد نه‌تنها کد خودتان، بلکه کد موجود در هر کتابخانه‌ای که استفاده می‌کنید را نیز در نظر بگیرید.)

enqueue(record)

رکورد را با استفاده از put_nowait() در صف قرار می‌دهد؛ اگر بخواهید از رفتار مسدودکننده، مهلت زمانی یا پیاده‌سازی صف سفارشی استفاده کنید، ممکن است بخواهید این را بازنویسی کنید.

listener

هنگامی که از طریق پیکربندی با استفاده از dictConfig() ایجاد شود، این ویژگی شامل یک نمونه از QueueListener برای استفاده با این هندلر خواهد بود. در غیر این صورت، None خواهد بود.

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

QueueListener

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

کلاس QueueListener، که در ماژول logging.handlers قرار دارد، از دریافت پیام‌های گزارش از یک صف، مانند صف‌های پیاده‌سازی‌شده در ماژول‌های queue یا multiprocessing، پشتیبانی می‌کند. پیام‌ها از یک صف در یک نخ داخلی دریافت می‌شوند و در همان نخ، برای پردازش به یک یا چند هندلر ارسال می‌شوند. اگرچه QueueListener خود یک هندلر نیست، اما در اینجا مستند شده است زیرا با QueueHandler همکاری نزدیکی دارد.

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

class logging.handlers.QueueListener(queue, *handlers, respect_handler_level=False)

یک نمونه جدید از کلاس QueueListener برمی‌گرداند. این نمونه با صفی برای ارسال پیام‌ها به آن و فهرستی از هندلرها مقداردهی اولیه می‌شود که ورودی‌های قرار گرفته در صف را پردازش می‌کنند. صف می‌تواند هر شیء صف‌مانند باشد؛ این صف همان‌گونه که هست به متد dequeue() ارسال می‌شود و این متد باید بداند چگونه پیام‌ها را از آن دریافت کند. داشتن API پیگیری وظایف برای صف الزامی نیست (هرچند در صورت موجود بودن از آن استفاده می‌شود)، به این معنا که می‌توانید از نمونه‌های SimpleQueue برای queue استفاده کنید.

توجه

اگر از multiprocessing استفاده می‌کنید، باید از به‌کارگیری SimpleQueue خودداری کنید و به‌جای آن از multiprocessing.Queue استفاده کنید.

اگر respect_handler_level برابر True باشد، هنگام تصمیم‌گیری برای ارسال پیام‌ها به یک هندلر، سطح آن هندلر رعایت می‌شود (با سطح پیام مقایسه می‌شود)؛ در غیر این صورت، رفتار مانند نسخه‌های پیشین پایتون است — همیشه هر پیام به هر هندلر ارسال می‌شود.

تغییر یافته در نسخه‌ی 3.5: آرگومان respect_handler_level اضافه شد.

تغییر یافته در نسخه‌ی 3.14: اکنون می‌توان از QueueListener به‌عنوان یک مدیر زمینه از طریق with استفاده کرد. هنگام ورود به زمینه، شنونده آغاز می‌شود. هنگام خروج از زمینه، شنونده متوقف می‌شود. __enter__() شیء QueueListener را برمی‌گرداند.

dequeue(block)

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

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

prepare(record)

یک رکورد را برای پردازش آماده کنید.

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

handle(record)

یک رکورد را مدیریت کنید.

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

start()

شنونده را آغاز می‌کند.

این یک نخ پس‌زمینه را راه‌اندازی می‌کند تا صف را برای LogRecordهایی که باید پردازش شوند، پایش کند.

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

stop()

شنونده را متوقف می‌کند.

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

enqueue_sentinel()

یک نشانه (sentinel) را در صف می‌نویسد تا به شنونده بگوید که خارج شود. این پیاده‌سازی از put_nowait() استفاده می‌کند. اگر بخواهید از مهلت‌ها استفاده کنید یا با پیاده‌سازی‌های سفارشی صف کار کنید، ممکن است بخواهید این متد را بازنویسی کنید.

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

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

ماژول logging

مرجع API ماژول logging.

ماژول logging.config

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