logging-cookbook.po

# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001 Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
# Translators:
# Danial Behzadi <dani.behzi@ubuntu.com>, 2025
# Rafael Fontenelle <rffontenelle@gmail.com>, 2025
# Revisto <theRevisto@gmail.com>, 2025
# Sepehr Rasouli <sepehrrasouli06@gmail.com>, 2026
# arman mohebali <armanmohebali@outlook.com>, 2026
#
msgid ""
msgstr ""
"Project-Id-Version: Python 3.14\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-10-01 14:41+0330\n"
"PO-Revision-Date: 2026-10-06 20:24+0330\n"
"Last-Translator: Sepehr Rasouli <sepehrrasouli06@gmail.com>, 2026\n"
"Language-Team: Persian (https://github.com/python/python-docs-fa/)\n"
"Language: fa\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n > 1);\n"
"X-Generator: Poedit 3.6\n"

msgid "Logging Cookbook"
msgstr "کتاب آشپزی گزارش‌گیری (Logging Cookbook)"

msgid "This page contains a number of recipes related to logging, which have been found useful in the past. For links to tutorial and reference information, please see :ref:`cookbook-ref-links`."
msgstr "این صفحه حاوی تعدادی دستورالعمل مرتبط با گزارش‌کردن است که در گذشته مفید شناخته شده‌اند. برای پیوندهایی به اطلاعات آموزشی و مرجع، لطفاً :ref:`cookbook-ref-links` را ببینید."

msgid "Using logging in multiple modules"
msgstr "استفاده از گزارش‌گیری در ماژول‌های متعدد"

msgid "Multiple calls to ``logging.getLogger('someLogger')`` return a reference to the same logger object.  This is true not only within the same module, but also across modules as long as it is in the same Python interpreter process.  It is true for references to the same object; additionally, application code can define and configure a parent logger in one module and create (but not configure) a child logger in a separate module, and all logger calls to the child will pass up to the parent.  Here is a main module::"
msgstr "چندین فراخوانی ``logging.getLogger('someLogger')`` ارجاعی به همان شیء گزارش‌گیر برمی‌گردانند. این موضوع نه‌تنها در داخل همان ماژول، بلکه بین ماژول‌ها نیز تا زمانی که در یک فرآیند مفسر پایتون یکسان باشند، صادق است. این امر برای ارجاع‌ها به همان شیء نیز صادق است؛ علاوه بر این، کد برنامه می‌تواند یک گزارش‌گیر والد را در یک ماژول تعریف و پیکربندی کند و یک گزارش‌گیر فرزند را در ماژولی جداگانه ایجاد کند (اما آن را پیکربندی نکند)، و همه‌ی فراخوانی‌های گزارش‌گیر فرزند، به گزارش‌گیر والد منتقل خواهند شد. در ادامه یک ماژول اصلی آمده است::"

msgid ""
"import logging\n"
"import auxiliary_module\n"
"\n"
"# create logger with 'spam_application'\n"
"logger = logging.getLogger('spam_application')\n"
"logger.setLevel(logging.DEBUG)\n"
"# create file handler which logs even debug messages\n"
"fh = logging.FileHandler('spam.log')\n"
"fh.setLevel(logging.DEBUG)\n"
"# create console handler with a higher log level\n"
"ch = logging.StreamHandler()\n"
"ch.setLevel(logging.ERROR)\n"
"# create formatter and add it to the handlers\n"
"formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')\n"
"fh.setFormatter(formatter)\n"
"ch.setFormatter(formatter)\n"
"# add the handlers to the logger\n"
"logger.addHandler(fh)\n"
"logger.addHandler(ch)\n"
"\n"
"logger.info('creating an instance of auxiliary_module.Auxiliary')\n"
"a = auxiliary_module.Auxiliary()\n"
"logger.info('created an instance of auxiliary_module.Auxiliary')\n"
"logger.info('calling auxiliary_module.Auxiliary.do_something')\n"
"a.do_something()\n"
"logger.info('finished auxiliary_module.Auxiliary.do_something')\n"
"logger.info('calling auxiliary_module.some_function()')\n"
"auxiliary_module.some_function()\n"
"logger.info('done with auxiliary_module.some_function()')"
msgstr ""
"import logging\n"
"import auxiliary_module\n"
"\n"
"# create logger with 'spam_application'\n"
"logger = logging.getLogger('spam_application')\n"
"logger.setLevel(logging.DEBUG)\n"
"# create file handler which logs even debug messages\n"
"fh = logging.FileHandler('spam.log')\n"
"fh.setLevel(logging.DEBUG)\n"
"# create console handler with a higher log level\n"
"ch = logging.StreamHandler()\n"
"ch.setLevel(logging.ERROR)\n"
"# create formatter and add it to the handlers\n"
"formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')\n"
"fh.setFormatter(formatter)\n"
"ch.setFormatter(formatter)\n"
"# add the handlers to the logger\n"
"logger.addHandler(fh)\n"
"logger.addHandler(ch)\n"
"\n"
"logger.info('creating an instance of auxiliary_module.Auxiliary')\n"
"a = auxiliary_module.Auxiliary()\n"
"logger.info('created an instance of auxiliary_module.Auxiliary')\n"
"logger.info('calling auxiliary_module.Auxiliary.do_something')\n"
"a.do_something()\n"
"logger.info('finished auxiliary_module.Auxiliary.do_something')\n"
"logger.info('calling auxiliary_module.some_function()')\n"
"auxiliary_module.some_function()\n"
"logger.info('done with auxiliary_module.some_function()')"

msgid "Here is the auxiliary module::"
msgstr "در اینجا ماژول کمکی آمده است::"

msgid ""
"import logging\n"
"\n"
"# create logger\n"
"module_logger = logging.getLogger('spam_application.auxiliary')\n"
"\n"
"class Auxiliary:\n"
"    def __init__(self):\n"
"        self.logger = logging.getLogger('spam_application.auxiliary.Auxiliary')\n"
"        self.logger.info('creating an instance of Auxiliary')\n"
"\n"
"    def do_something(self):\n"
"        self.logger.info('doing something')\n"
"        a = 1 + 1\n"
"        self.logger.info('done doing something')\n"
"\n"
"def some_function():\n"
"    module_logger.info('received a call to \"some_function\"')"
msgstr ""
"import logging\n"
"\n"
"# create logger\n"
"module_logger = logging.getLogger('spam_application.auxiliary')\n"
"\n"
"class Auxiliary:\n"
"    def __init__(self):\n"
"        self.logger = logging.getLogger('spam_application.auxiliary.Auxiliary')\n"
"        self.logger.info('creating an instance of Auxiliary')\n"
"\n"
"    def do_something(self):\n"
"        self.logger.info('doing something')\n"
"        a = 1 + 1\n"
"        self.logger.info('done doing something')\n"
"\n"
"def some_function():\n"
"    module_logger.info('received a call to \"some_function\"')"

msgid "The output looks like this:"
msgstr "خروجی به این شکل است:"

msgid ""
"2005-03-23 23:47:11,663 - spam_application - INFO -\n"
"   creating an instance of auxiliary_module.Auxiliary\n"
"2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO -\n"
"   creating an instance of Auxiliary\n"
"2005-03-23 23:47:11,665 - spam_application - INFO -\n"
"   created an instance of auxiliary_module.Auxiliary\n"
"2005-03-23 23:47:11,668 - spam_application - INFO -\n"
"   calling auxiliary_module.Auxiliary.do_something\n"
"2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO -\n"
"   doing something\n"
"2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO -\n"
"   done doing something\n"
"2005-03-23 23:47:11,670 - spam_application - INFO -\n"
"   finished auxiliary_module.Auxiliary.do_something\n"
"2005-03-23 23:47:11,671 - spam_application - INFO -\n"
"   calling auxiliary_module.some_function()\n"
"2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO -\n"
"   received a call to 'some_function'\n"
"2005-03-23 23:47:11,673 - spam_application - INFO -\n"
"   done with auxiliary_module.some_function()"
msgstr ""
"2005-03-23 23:47:11,663 - spam_application - INFO -\n"
"   creating an instance of auxiliary_module.Auxiliary\n"
"2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO -\n"
"   creating an instance of Auxiliary\n"
"2005-03-23 23:47:11,665 - spam_application - INFO -\n"
"   created an instance of auxiliary_module.Auxiliary\n"
"2005-03-23 23:47:11,668 - spam_application - INFO -\n"
"   calling auxiliary_module.Auxiliary.do_something\n"
"2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO -\n"
"   doing something\n"
"2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO -\n"
"   done doing something\n"
"2005-03-23 23:47:11,670 - spam_application - INFO -\n"
"   finished auxiliary_module.Auxiliary.do_something\n"
"2005-03-23 23:47:11,671 - spam_application - INFO -\n"
"   calling auxiliary_module.some_function()\n"
"2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO -\n"
"   received a call to 'some_function'\n"
"2005-03-23 23:47:11,673 - spam_application - INFO -\n"
"   done with auxiliary_module.some_function()"

msgid "Logging from multiple threads"
msgstr "ثبت گزارش از چندین نخ"

msgid "Logging from multiple threads requires no special effort. The following example shows logging from the main (initial) thread and another thread::"
msgstr "گزارش‌گیری از چندین نخ نیازمند تلاش خاصی نیست. مثال زیر گزارش‌گیری از نخ اصلی (آغازین) و نخی دیگر را نشان می‌دهد::"

msgid ""
"import logging\n"
"import threading\n"
"import time\n"
"\n"
"def worker(arg):\n"
"    while not arg['stop']:\n"
"        logging.debug('Hi from myfunc')\n"
"        time.sleep(0.5)\n"
"\n"
"def main():\n"
"    logging.basicConfig(level=logging.DEBUG, format='%(relativeCreated)6d %(threadName)s %(message)s')\n"
"    info = {'stop': False}\n"
"    thread = threading.Thread(target=worker, args=(info,))\n"
"    thread.start()\n"
"    while True:\n"
"        try:\n"
"            logging.debug('Hello from main')\n"
"            time.sleep(0.75)\n"
"        except KeyboardInterrupt:\n"
"            info['stop'] = True\n"
"            break\n"
"    thread.join()\n"
"\n"
"if __name__ == '__main__':\n"
"    main()"
msgstr ""
"import logging\n"
"import threading\n"
"import time\n"
"\n"
"def worker(arg):\n"
"    while not arg['stop']:\n"
"        logging.debug('Hi from myfunc')\n"
"        time.sleep(0.5)\n"
"\n"
"def main():\n"
"    logging.basicConfig(level=logging.DEBUG, format='%(relativeCreated)6d %(threadName)s %(message)s')\n"
"    info = {'stop': False}\n"
"    thread = threading.Thread(target=worker, args=(info,))\n"
"    thread.start()\n"
"    while True:\n"
"        try:\n"
"            logging.debug('Hello from main')\n"
"            time.sleep(0.75)\n"
"        except KeyboardInterrupt:\n"
"            info['stop'] = True\n"
"            break\n"
"    thread.join()\n"
"\n"
"if __name__ == '__main__':\n"
"    main()"

msgid "When run, the script should print something like the following:"
msgstr "هنگام اجرا، اسکریپت باید چیزی شبیه به مورد زیر چاپ کند:"

msgid ""
"   0 Thread-1 Hi from myfunc\n"
"   3 MainThread Hello from main\n"
" 505 Thread-1 Hi from myfunc\n"
" 755 MainThread Hello from main\n"
"1007 Thread-1 Hi from myfunc\n"
"1507 MainThread Hello from main\n"
"1508 Thread-1 Hi from myfunc\n"
"2010 Thread-1 Hi from myfunc\n"
"2258 MainThread Hello from main\n"
"2512 Thread-1 Hi from myfunc\n"
"3009 MainThread Hello from main\n"
"3013 Thread-1 Hi from myfunc\n"
"3515 Thread-1 Hi from myfunc\n"
"3761 MainThread Hello from main\n"
"4017 Thread-1 Hi from myfunc\n"
"4513 MainThread Hello from main\n"
"4518 Thread-1 Hi from myfunc"
msgstr ""
"   0 Thread-1 Hi from myfunc\n"
"   3 MainThread Hello from main\n"
" 505 Thread-1 Hi from myfunc\n"
" 755 MainThread Hello from main\n"
"1007 Thread-1 Hi from myfunc\n"
"1507 MainThread Hello from main\n"
"1508 Thread-1 Hi from myfunc\n"
"2010 Thread-1 Hi from myfunc\n"
"2258 MainThread Hello from main\n"
"2512 Thread-1 Hi from myfunc\n"
"3009 MainThread Hello from main\n"
"3013 Thread-1 Hi from myfunc\n"
"3515 Thread-1 Hi from myfunc\n"
"3761 MainThread Hello from main\n"
"4017 Thread-1 Hi from myfunc\n"
"4513 MainThread Hello from main\n"
"4518 Thread-1 Hi from myfunc"

msgid "This shows the logging output interspersed as one might expect. This approach works for more threads than shown here, of course."
msgstr "این، خروجی گزارش‌گیری را به‌صورت درهم‌آمیخته، همان‌طور که انتظار می‌رود، نشان می‌دهد. البته این روش برای نخ‌های بیشتری نسبت به آنچه در اینجا نشان داده شده است نیز کار می‌کند."

msgid "Multiple handlers and formatters"
msgstr "هندلرها و قالب‌بندهای متعدد"

msgid "Loggers are plain Python objects.  The :meth:`~Logger.addHandler` method has no minimum or maximum quota for the number of handlers you may add.  Sometimes it will be beneficial for an application to log all messages of all severities to a text file while simultaneously logging errors or above to the console.  To set this up, simply configure the appropriate handlers.  The logging calls in the application code will remain unchanged.  Here is a slight modification to the previous simple module-based configuration example::"
msgstr "گزارش‌گیرها اشیای ساده پایتون هستند. متد :meth:`~Logger.addHandler` هیچ حداقل یا حداکثر سهمیه‌ای برای تعداد هندلرهایی که می‌توانید اضافه کنید، ندارد. گاهی اوقات برای یک برنامه کاربردی مفید خواهد بود که تمام پیام‌ها با تمام سطوح شدت را در یک پرونده متنی گزارش کند و همزمان خطاها یا سطوح بالاتر را در کنسول گزارش کند. برای تنظیم این حالت، کافی است هندلرهای مناسب را پیکربندی کنید. فراخوانی‌های گزارش در کد برنامه بدون تغییر باقی خواهند ماند. در ادامه تغییری جزئی در مثال پیکربندی ساده مبتنی بر ماژول قبلی آمده است::"

msgid ""
"import logging\n"
"\n"
"logger = logging.getLogger('simple_example')\n"
"logger.setLevel(logging.DEBUG)\n"
"# create file handler which logs even debug messages\n"
"fh = logging.FileHandler('spam.log')\n"
"fh.setLevel(logging.DEBUG)\n"
"# create console handler with a higher log level\n"
"ch = logging.StreamHandler()\n"
"ch.setLevel(logging.ERROR)\n"
"# create formatter and add it to the handlers\n"
"formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')\n"
"ch.setFormatter(formatter)\n"
"fh.setFormatter(formatter)\n"
"# add the handlers to logger\n"
"logger.addHandler(ch)\n"
"logger.addHandler(fh)\n"
"\n"
"# 'application' code\n"
"logger.debug('debug message')\n"
"logger.info('info message')\n"
"logger.warning('warn message')\n"
"logger.error('error message')\n"
"logger.critical('critical message')"
msgstr ""
"import logging\n"
"\n"
"logger = logging.getLogger('simple_example')\n"
"logger.setLevel(logging.DEBUG)\n"
"# create file handler which logs even debug messages\n"
"fh = logging.FileHandler('spam.log')\n"
"fh.setLevel(logging.DEBUG)\n"
"# create console handler with a higher log level\n"
"ch = logging.StreamHandler()\n"
"ch.setLevel(logging.ERROR)\n"
"# create formatter and add it to the handlers\n"
"formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')\n"
"ch.setFormatter(formatter)\n"
"fh.setFormatter(formatter)\n"
"# add the handlers to logger\n"
"logger.addHandler(ch)\n"
"logger.addHandler(fh)\n"
"\n"
"# 'application' code\n"
"logger.debug('debug message')\n"
"logger.info('info message')\n"
"logger.warning('warn message')\n"
"logger.error('error message')\n"
"logger.critical('critical message')"

msgid "Notice that the 'application' code does not care about multiple handlers.  All that changed was the addition and configuration of a new handler named *fh*."
msgstr "توجه داشته باشید که کد «برنامه» به چند هندلر اهمیتی نمی‌دهد. تنها چیزی که تغییر کرد، افزودن و پیکربندی یک هندلر جدید به نام *fh* بود."

msgid "The ability to create new handlers with higher- or lower-severity filters can be very helpful when writing and testing an application.  Instead of using many ``print`` statements for debugging, use ``logger.debug``: Unlike the print statements, which you will have to delete or comment out later, the logger.debug statements can remain intact in the source code and remain dormant until you need them again.  At that time, the only change that needs to happen is to modify the severity level of the logger and/or handler to debug."
msgstr "توانایی ایجاد هندلرهای جدید با فیلترهایی با شدت بالاتر یا پایین‌تر می‌تواند هنگام نوشتن و آزمایش یک برنامه کاربردی بسیار مفید باشد. به جای استفاده از دستورهای ``print`` زیاد برای اشکال‌زدایی، از ``logger.debug`` استفاده کنید: برخلاف دستورهای print که بعداً مجبور خواهید بود آن‌ها را حذف یا کامنت کنید، دستورهای logger.debug می‌توانند دست‌نخورده در کد منبع باقی بمانند و تا زمانی که دوباره به آن‌ها نیاز دارید، غیرفعال بمانند. در آن زمان، تنها تغییر لازم، تغییر سطح شدت logger و/یا هندلر به debug است."

msgid "Logging to multiple destinations"
msgstr "گزارش‌گیری در چندین مقصد"

msgid "Let's say you want to log to console and file with different message formats and in differing circumstances. Say you want to log messages with levels of DEBUG and higher to file, and those messages at level INFO and higher to the console. Let's also assume that the file should contain timestamps, but the console messages should not. Here's how you can achieve this::"
msgstr "فرض کنید می‌خواهید گزارش‌ها را با قالب‌های پیام متفاوت و در شرایط مختلف در کنسول و پرونده ثبت کنید. فرض کنید می‌خواهید پیام‌هایی با سطوح DEBUG و بالاتر را در پرونده و پیام‌هایی با سطح INFO و بالاتر را در کنسول ثبت کنید. همچنین فرض کنید پرونده باید شامل برچسب‌های زمانی باشد، اما پیام‌های کنسول نباید شامل برچسب‌های زمانی باشند. در ادامه، چگونگی دستیابی به این هدف آمده است::"

msgid ""
"import logging\n"
"\n"
"# set up logging to file - see previous section for more details\n"
"logging.basicConfig(level=logging.DEBUG,\n"
"                    format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',\n"
"                    datefmt='%m-%d %H:%M',\n"
"                    filename='/tmp/myapp.log',\n"
"                    filemode='w')\n"
"# define a Handler which writes INFO messages or higher to the sys.stderr\n"
"console = logging.StreamHandler()\n"
"console.setLevel(logging.INFO)\n"
"# set a format which is simpler for console use\n"
"formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')\n"
"# tell the handler to use this format\n"
"console.setFormatter(formatter)\n"
"# add the handler to the root logger\n"
"logging.getLogger().addHandler(console)\n"
"\n"
"# Now, we can log to the root logger, or any other logger. First the root...\n"
"logging.info('Jackdaws love my big sphinx of quartz.')\n"
"\n"
"# Now, define a couple of other loggers which might represent areas in your\n"
"# application:\n"
"\n"
"logger1 = logging.getLogger('myapp.area1')\n"
"logger2 = logging.getLogger('myapp.area2')\n"
"\n"
"logger1.debug('Quick zephyrs blow, vexing daft Jim.')\n"
"logger1.info('How quickly daft jumping zebras vex.')\n"
"logger2.warning('Jail zesty vixen who grabbed pay from quack.')\n"
"logger2.error('The five boxing wizards jump quickly.')"
msgstr ""
"import logging\n"
"\n"
"# set up logging to file - see previous section for more details\n"
"logging.basicConfig(level=logging.DEBUG,\n"
"                    format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',\n"
"                    datefmt='%m-%d %H:%M',\n"
"                    filename='/tmp/myapp.log',\n"
"                    filemode='w')\n"
"# define a Handler which writes INFO messages or higher to the sys.stderr\n"
"console = logging.StreamHandler()\n"
"console.setLevel(logging.INFO)\n"
"# set a format which is simpler for console use\n"
"formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')\n"
"# tell the handler to use this format\n"
"console.setFormatter(formatter)\n"
"# add the handler to the root logger\n"
"logging.getLogger().addHandler(console)\n"
"\n"
"# Now, we can log to the root logger, or any other logger. First the root...\n"
"logging.info('Jackdaws love my big sphinx of quartz.')\n"
"\n"
"# Now, define a couple of other loggers which might represent areas in your\n"
"# application:\n"
"\n"
"logger1 = logging.getLogger('myapp.area1')\n"
"logger2 = logging.getLogger('myapp.area2')\n"
"\n"
"logger1.debug('Quick zephyrs blow, vexing daft Jim.')\n"
"logger1.info('How quickly daft jumping zebras vex.')\n"
"logger2.warning('Jail zesty vixen who grabbed pay from quack.')\n"
"logger2.error('The five boxing wizards jump quickly.')"

msgid "When you run this, on the console you will see"
msgstr "هنگامی که این را اجرا می‌کنید، در کنسول خواهید دید"

msgid ""
"root        : INFO     Jackdaws love my big sphinx of quartz.\n"
"myapp.area1 : INFO     How quickly daft jumping zebras vex.\n"
"myapp.area2 : WARNING  Jail zesty vixen who grabbed pay from quack.\n"
"myapp.area2 : ERROR    The five boxing wizards jump quickly."
msgstr ""
"root        : INFO     Jackdaws love my big sphinx of quartz.\n"
"myapp.area1 : INFO     How quickly daft jumping zebras vex.\n"
"myapp.area2 : WARNING  Jail zesty vixen who grabbed pay from quack.\n"
"myapp.area2 : ERROR    The five boxing wizards jump quickly."

msgid "and in the file you will see something like"
msgstr "و در پرونده چیزی شبیه به این خواهید دید"

msgid ""
"10-22 22:19 root         INFO     Jackdaws love my big sphinx of quartz.\n"
"10-22 22:19 myapp.area1  DEBUG    Quick zephyrs blow, vexing daft Jim.\n"
"10-22 22:19 myapp.area1  INFO     How quickly daft jumping zebras vex.\n"
"10-22 22:19 myapp.area2  WARNING  Jail zesty vixen who grabbed pay from quack.\n"
"10-22 22:19 myapp.area2  ERROR    The five boxing wizards jump quickly."
msgstr ""
"10-22 22:19 root         INFO     Jackdaws love my big sphinx of quartz.\n"
"10-22 22:19 myapp.area1  DEBUG    Quick zephyrs blow, vexing daft Jim.\n"
"10-22 22:19 myapp.area1  INFO     How quickly daft jumping zebras vex.\n"
"10-22 22:19 myapp.area2  WARNING  Jail zesty vixen who grabbed pay from quack.\n"
"10-22 22:19 myapp.area2  ERROR    The five boxing wizards jump quickly."

msgid "As you can see, the DEBUG message only shows up in the file. The other messages are sent to both destinations."
msgstr "همان‌طور که می‌بینید، پیام DEBUG فقط در پرونده نمایش داده می‌شود. سایر پیام‌ها به هر دو مقصد ارسال می‌شوند."

msgid "This example uses console and file handlers, but you can use any number and combination of handlers you choose."
msgstr "این مثال از هندلرهای کنسول و پرونده استفاده می‌کند، اما شما می‌توانید از هر تعداد و ترکیبی از هندلرها که بخواهید استفاده کنید."

msgid "Note that the above choice of log filename ``/tmp/myapp.log`` implies use of a standard location for temporary files on POSIX systems. On Windows, you may need to choose a different directory name for the log - just ensure that the directory exists and that you have the permissions to create and update files in it."
msgstr "توجه داشته باشید که انتخاب نام پرونده گزارش ``/tmp/myapp.log`` در بالا، به معنای استفاده از یک مکان استاندارد برای پرونده‌های موقت در سیستم‌های POSIX است. در ویندوز، ممکن است لازم باشد نام پوشه متفاوتی را برای گزارش انتخاب کنید؛ فقط اطمینان حاصل کنید که پوشه وجود دارد و شما دسترسی لازم برای ایجاد و به‌روزرسانی پرونده‌ها در آن را دارید."

msgid "Custom handling of levels"
msgstr "مدیریت سفارشی سطح‌ها"

msgid "Sometimes, you might want to do something slightly different from the standard handling of levels in handlers, where all levels above a threshold get processed by a handler. To do this, you need to use filters. Let's look at a scenario where you want to arrange things as follows:"
msgstr "گاهی ممکن است بخواهید کاری کمی متفاوت از روش استاندارد پردازش سطوح در هندلرها انجام دهید، که در آن تمام سطوح بالاتر از یک آستانه توسط یک هندلر پردازش می‌شوند. برای این کار، باید از فیلترها استفاده کنید. بیایید سناریویی را بررسی کنیم که می‌خواهید موارد را به‌صورت زیر مرتب کنید:"

msgid "Send messages of severity ``INFO`` and ``WARNING`` to ``sys.stdout``"
msgstr "پیام‌هایی با شدت ``INFO`` و ``WARNING`` را به ``sys.stdout`` ارسال کنید"

msgid "Send messages of severity ``ERROR`` and above to ``sys.stderr``"
msgstr "پیام‌های با شدت ``ERROR`` و بالاتر را به ``sys.stderr`` ارسال کنید"

msgid "Send messages of severity ``DEBUG`` and above to file ``app.log``"
msgstr "پیام‌هایی با شدت ``DEBUG`` و بالاتر را به پرونده ``app.log`` ارسال کنید"

msgid "Suppose you configure logging with the following JSON:"
msgstr "فرض کنید گزارش‌گیری را با JSON زیر پیکربندی می‌کنید:"

msgid ""
"{\n"
"    \"version\": 1,\n"
"    \"disable_existing_loggers\": false,\n"
"    \"formatters\": {\n"
"        \"simple\": {\n"
"            \"format\": \"%(levelname)-8s - %(message)s\"\n"
"        }\n"
"    },\n"
"    \"handlers\": {\n"
"        \"stdout\": {\n"
"            \"class\": \"logging.StreamHandler\",\n"
"            \"level\": \"INFO\",\n"
"            \"formatter\": \"simple\",\n"
"            \"stream\": \"ext://sys.stdout\"\n"
"        },\n"
"        \"stderr\": {\n"
"            \"class\": \"logging.StreamHandler\",\n"
"            \"level\": \"ERROR\",\n"
"            \"formatter\": \"simple\",\n"
"            \"stream\": \"ext://sys.stderr\"\n"
"        },\n"
"        \"file\": {\n"
"            \"class\": \"logging.FileHandler\",\n"
"            \"formatter\": \"simple\",\n"
"            \"filename\": \"app.log\",\n"
"            \"mode\": \"w\"\n"
"        }\n"
"    },\n"
"    \"root\": {\n"
"        \"level\": \"DEBUG\",\n"
"        \"handlers\": [\n"
"            \"stderr\",\n"
"            \"stdout\",\n"
"            \"file\"\n"
"        ]\n"
"    }\n"
"}"
msgstr ""
"{\n"
"    \"version\": 1,\n"
"    \"disable_existing_loggers\": false,\n"
"    \"formatters\": {\n"
"        \"simple\": {\n"
"            \"format\": \"%(levelname)-8s - %(message)s\"\n"
"        }\n"
"    },\n"
"    \"handlers\": {\n"
"        \"stdout\": {\n"
"            \"class\": \"logging.StreamHandler\",\n"
"            \"level\": \"INFO\",\n"
"            \"formatter\": \"simple\",\n"
"            \"stream\": \"ext://sys.stdout\"\n"
"        },\n"
"        \"stderr\": {\n"
"            \"class\": \"logging.StreamHandler\",\n"
"            \"level\": \"ERROR\",\n"
"            \"formatter\": \"simple\",\n"
"            \"stream\": \"ext://sys.stderr\"\n"
"        },\n"
"        \"file\": {\n"
"            \"class\": \"logging.FileHandler\",\n"
"            \"formatter\": \"simple\",\n"
"            \"filename\": \"app.log\",\n"
"            \"mode\": \"w\"\n"
"        }\n"
"    },\n"
"    \"root\": {\n"
"        \"level\": \"DEBUG\",\n"
"        \"handlers\": [\n"
"            \"stderr\",\n"
"            \"stdout\",\n"
"            \"file\"\n"
"        ]\n"
"    }\n"
"}"

msgid "This configuration does *almost* what we want, except that ``sys.stdout`` would show messages of severity ``ERROR`` and only events of this severity and higher will be tracked as well as ``INFO`` and ``WARNING`` messages. To prevent this, we can set up a filter which excludes those messages and add it to the relevant handler. This can be configured by adding a ``filters`` section parallel to ``formatters`` and ``handlers``:"
msgstr "این پیکربندی *تقریباً* آنچه می‌خواهیم انجام می‌دهد، با این استثنا که ``sys.stdout`` پیام‌هایی با شدت ``ERROR`` را نشان می‌دهد و تنها رویدادهایی با این شدت و بالاتر، به‌همراه پیام‌های ``INFO`` و ``WARNING`` نیز پیگیری می‌شوند. برای جلوگیری از این موضوع، می‌توانیم فیلتری تنظیم کنیم که آن پیام‌ها را حذف کند و آن را به هندلر مربوطه اضافه کنیم. این کار را می‌توان با افزودن یک بخش ``filters`` هم‌سطح با ``formatters`` و ``handlers`` پیکربندی کرد:"

msgid ""
"{\n"
"    \"filters\": {\n"
"        \"warnings_and_below\": {\n"
"            \"()\" : \"__main__.filter_maker\",\n"
"            \"level\": \"WARNING\"\n"
"        }\n"
"    }\n"
"}"
msgstr ""
"{\n"
"    \"filters\": {\n"
"        \"warnings_and_below\": {\n"
"            \"()\" : \"__main__.filter_maker\",\n"
"            \"level\": \"WARNING\"\n"
"        }\n"
"    }\n"
"}"

msgid "and changing the section on the ``stdout`` handler to add it:"
msgstr "و تغییر بخش مربوط به هندلر ``stdout`` برای افزودن آن:"

msgid ""
"{\n"
"    \"stdout\": {\n"
"        \"class\": \"logging.StreamHandler\",\n"
"        \"level\": \"INFO\",\n"
"        \"formatter\": \"simple\",\n"
"        \"stream\": \"ext://sys.stdout\",\n"
"        \"filters\": [\"warnings_and_below\"]\n"
"    }\n"
"}"
msgstr ""
"{\n"
"    \"stdout\": {\n"
"        \"class\": \"logging.StreamHandler\",\n"
"        \"level\": \"INFO\",\n"
"        \"formatter\": \"simple\",\n"
"        \"stream\": \"ext://sys.stdout\",\n"
"        \"filters\": [\"warnings_and_below\"]\n"
"    }\n"
"}"

msgid "A filter is just a function, so we can define the ``filter_maker`` (a factory function) as follows:"
msgstr "یک فیلتر فقط یک تابع است، بنابراین می‌توانیم ``filter_maker`` (یک تابع کارخانه) را به‌صورت زیر تعریف کنیم:"

msgid ""
"def filter_maker(level):\n"
"    level = getattr(logging, level)\n"
"\n"
"    def filter(record):\n"
"        return record.levelno <= level\n"
"\n"
"    return filter"
msgstr ""
"def filter_maker(level):\n"
"    level = getattr(logging, level)\n"
"\n"
"    def filter(record):\n"
"        return record.levelno <= level\n"
"\n"
"    return filter"

msgid "This converts the string argument passed in to a numeric level, and returns a function which only returns ``True`` if the level of the passed in record is at or below the specified level. Note that in this example I have defined the ``filter_maker`` in a test script ``main.py`` that I run from the command line, so its module will be ``__main__`` - hence the ``__main__.filter_maker`` in the filter configuration. You will need to change that if you define it in a different module."
msgstr "این، آرگومان رشته‌ای داده‌شده را به یک سطح عددی تبدیل می‌کند و تابعی را برمی‌گرداند که فقط در صورتی ``True`` را برمی‌گرداند که سطح رکورد داده‌شده برابر با سطح مشخص‌شده یا پایین‌تر از آن باشد. توجه داشته باشید که در این مثال، ``filter_maker`` را در یک اسکریپت آزمایشی به نام ``main.py`` تعریف کرده‌ام که آن را از خط فرمان اجرا می‌کنم؛ بنابراین ماژول آن ``__main__`` خواهد بود؛ از این رو ``__main__.filter_maker`` در پیکربندی فیلتر آمده است. اگر آن را در ماژول دیگری تعریف کنید، باید آن را تغییر دهید."

msgid "With the filter added, we can run ``main.py``, which in full is:"
msgstr "با افزودن فیلتر، می‌توانیم ``main.py`` را اجرا کنیم، که به‌طور کامل به این صورت است:"

msgid ""
"import json\n"
"import logging\n"
"import logging.config\n"
"\n"
"CONFIG = '''\n"
"{\n"
"    \"version\": 1,\n"
"    \"disable_existing_loggers\": false,\n"
"    \"formatters\": {\n"
"        \"simple\": {\n"
"            \"format\": \"%(levelname)-8s - %(message)s\"\n"
"        }\n"
"    },\n"
"    \"filters\": {\n"
"        \"warnings_and_below\": {\n"
"            \"()\" : \"__main__.filter_maker\",\n"
"            \"level\": \"WARNING\"\n"
"        }\n"
"    },\n"
"    \"handlers\": {\n"
"        \"stdout\": {\n"
"            \"class\": \"logging.StreamHandler\",\n"
"            \"level\": \"INFO\",\n"
"            \"formatter\": \"simple\",\n"
"            \"stream\": \"ext://sys.stdout\",\n"
"            \"filters\": [\"warnings_and_below\"]\n"
"        },\n"
"        \"stderr\": {\n"
"            \"class\": \"logging.StreamHandler\",\n"
"            \"level\": \"ERROR\",\n"
"            \"formatter\": \"simple\",\n"
"            \"stream\": \"ext://sys.stderr\"\n"
"        },\n"
"        \"file\": {\n"
"            \"class\": \"logging.FileHandler\",\n"
"            \"formatter\": \"simple\",\n"
"            \"filename\": \"app.log\",\n"
"            \"mode\": \"w\"\n"
"        }\n"
"    },\n"
"    \"root\": {\n"
"        \"level\": \"DEBUG\",\n"
"        \"handlers\": [\n"
"            \"stderr\",\n"
"            \"stdout\",\n"
"            \"file\"\n"
"        ]\n"
"    }\n"
"}\n"
"'''\n"
"\n"
"def filter_maker(level):\n"
"    level = getattr(logging, level)\n"
"\n"
"    def filter(record):\n"
"        return record.levelno <= level\n"
"\n"
"    return filter\n"
"\n"
"logging.config.dictConfig(json.loads(CONFIG))\n"
"logging.debug('A DEBUG message')\n"
"logging.info('An INFO message')\n"
"logging.warning('A WARNING message')\n"
"logging.error('An ERROR message')\n"
"logging.critical('A CRITICAL message')"
msgstr ""
"import json\n"
"import logging\n"
"import logging.config\n"
"\n"
"CONFIG = '''\n"
"{\n"
"    \"version\": 1,\n"
"    \"disable_existing_loggers\": false,\n"
"    \"formatters\": {\n"
"        \"simple\": {\n"
"            \"format\": \"%(levelname)-8s - %(message)s\"\n"
"        }\n"
"    },\n"
"    \"filters\": {\n"
"        \"warnings_and_below\": {\n"
"            \"()\" : \"__main__.filter_maker\",\n"
"            \"level\": \"WARNING\"\n"
"        }\n"
"    },\n"
"    \"handlers\": {\n"
"        \"stdout\": {\n"
"            \"class\": \"logging.StreamHandler\",\n"
"            \"level\": \"INFO\",\n"
"            \"formatter\": \"simple\",\n"
"            \"stream\": \"ext://sys.stdout\",\n"
"            \"filters\": [\"warnings_and_below\"]\n"
"        },\n"
"        \"stderr\": {\n"
"            \"class\": \"logging.StreamHandler\",\n"
"            \"level\": \"ERROR\",\n"
"            \"formatter\": \"simple\",\n"
"            \"stream\": \"ext://sys.stderr\"\n"
"        },\n"
"        \"file\": {\n"
"            \"class\": \"logging.FileHandler\",\n"
"            \"formatter\": \"simple\",\n"
"            \"filename\": \"app.log\",\n"
"            \"mode\": \"w\"\n"
"        }\n"
"    },\n"
"    \"root\": {\n"
"        \"level\": \"DEBUG\",\n"
"        \"handlers\": [\n"
"            \"stderr\",\n"
"            \"stdout\",\n"
"            \"file\"\n"
"        ]\n"
"    }\n"
"}\n"
"'''\n"
"\n"
"def filter_maker(level):\n"
"    level = getattr(logging, level)\n"
"\n"
"    def filter(record):\n"
"        return record.levelno <= level\n"
"\n"
"    return filter\n"
"\n"
"logging.config.dictConfig(json.loads(CONFIG))\n"
"logging.debug('A DEBUG message')\n"
"logging.info('An INFO message')\n"
"logging.warning('A WARNING message')\n"
"logging.error('An ERROR message')\n"
"logging.critical('A CRITICAL message')"

msgid "And after running it like this:"
msgstr "و پس از اجرای آن به این صورت:"

msgid "python main.py 2>stderr.log >stdout.log"
msgstr "python main.py 2>stderr.log >stdout.log"

msgid "We can see the results are as expected:"
msgstr "می‌توانیم ببینیم که نتایج مطابق انتظار هستند:"

msgid ""
"$ more *.log\n"
"::::::::::::::\n"
"app.log\n"
"::::::::::::::\n"
"DEBUG    - A DEBUG message\n"
"INFO     - An INFO message\n"
"WARNING  - A WARNING message\n"
"ERROR    - An ERROR message\n"
"CRITICAL - A CRITICAL message\n"
"::::::::::::::\n"
"stderr.log\n"
"::::::::::::::\n"
"ERROR    - An ERROR message\n"
"CRITICAL - A CRITICAL message\n"
"::::::::::::::\n"
"stdout.log\n"
"::::::::::::::\n"
"INFO     - An INFO message\n"
"WARNING  - A WARNING message"
msgstr ""
"$ more *.log\n"
"::::::::::::::\n"
"app.log\n"
"::::::::::::::\n"
"DEBUG    - A DEBUG message\n"
"INFO     - An INFO message\n"
"WARNING  - A WARNING message\n"
"ERROR    - An ERROR message\n"
"CRITICAL - A CRITICAL message\n"
"::::::::::::::\n"
"stderr.log\n"
"::::::::::::::\n"
"ERROR    - An ERROR message\n"
"CRITICAL - A CRITICAL message\n"
"::::::::::::::\n"
"stdout.log\n"
"::::::::::::::\n"
"INFO     - An INFO message\n"
"WARNING  - A WARNING message"

msgid "Configuration server example"
msgstr "مثال سرور پیکربندی"

msgid "Here is an example of a module using the logging configuration server::"
msgstr "در اینجا نمونه‌ای از یک ماژول که از سرور پیکربندی گزارش‌گیری (logging configuration server) استفاده می‌کند، آمده است::"

msgid ""
"import logging\n"
"import logging.config\n"
"import time\n"
"import os\n"
"\n"
"# read initial config file\n"
"logging.config.fileConfig('logging.conf')\n"
"\n"
"# create and start listener on port 9999\n"
"t = logging.config.listen(9999)\n"
"t.start()\n"
"\n"
"logger = logging.getLogger('simpleExample')\n"
"\n"
"try:\n"
"    # loop through logging calls to see the difference\n"
"    # new configurations make, until Ctrl+C is pressed\n"
"    while True:\n"
"        logger.debug('debug message')\n"
"        logger.info('info message')\n"
"        logger.warning('warn message')\n"
"        logger.error('error message')\n"
"        logger.critical('critical message')\n"
"        time.sleep(5)\n"
"except KeyboardInterrupt:\n"
"    # cleanup\n"
"    logging.config.stopListening()\n"
"    t.join()"
msgstr ""
"import logging\n"
"import logging.config\n"
"import time\n"
"import os\n"
"\n"
"# read initial config file\n"
"logging.config.fileConfig('logging.conf')\n"
"\n"
"# create and start listener on port 9999\n"
"t = logging.config.listen(9999)\n"
"t.start()\n"
"\n"
"logger = logging.getLogger('simpleExample')\n"
"\n"
"try:\n"
"    # loop through logging calls to see the difference\n"
"    # new configurations make, until Ctrl+C is pressed\n"
"    while True:\n"
"        logger.debug('debug message')\n"
"        logger.info('info message')\n"
"        logger.warning('warn message')\n"
"        logger.error('error message')\n"
"        logger.critical('critical message')\n"
"        time.sleep(5)\n"
"except KeyboardInterrupt:\n"
"    # cleanup\n"
"    logging.config.stopListening()\n"
"    t.join()"

msgid "And here is a script that takes a filename and sends that file to the server, properly preceded with the binary-encoded length, as the new logging configuration::"
msgstr "و در اینجا اسکریپتی آمده است که یک نام پرونده می‌گیرد و آن پرونده را به‌عنوان پیکربندی جدید گزارش‌گیری، به‌همراه طول کدگذاری‌شده‌ی دودویی که به‌درستی پیش از آن قرار گرفته است، به سرور ارسال می‌کند::"

msgid ""
"#!/usr/bin/env python\n"
"import socket, sys, struct\n"
"\n"
"with open(sys.argv[1], 'rb') as f:\n"
"    data_to_send = f.read()\n"
"\n"
"HOST = 'localhost'\n"
"PORT = 9999\n"
"s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n"
"print('connecting...')\n"
"s.connect((HOST, PORT))\n"
"print('sending config...')\n"
"s.send(struct.pack('>L', len(data_to_send)))\n"
"s.send(data_to_send)\n"
"s.close()\n"
"print('complete')"
msgstr ""
"#!/usr/bin/env python\n"
"import socket, sys, struct\n"
"\n"
"with open(sys.argv[1], 'rb') as f:\n"
"    data_to_send = f.read()\n"
"\n"
"HOST = 'localhost'\n"
"PORT = 9999\n"
"s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n"
"print('connecting...')\n"
"s.connect((HOST, PORT))\n"
"print('sending config...')\n"
"s.send(struct.pack('>L', len(data_to_send)))\n"
"s.send(data_to_send)\n"
"s.close()\n"
"print('complete')"

msgid "Dealing with handlers that block"
msgstr "مدیریت هندلرهایی که مسدود می‌کنند"

msgid "Sometimes you have to get your logging handlers to do their work without blocking the thread you're logging from. This is common in web applications, though of course it also occurs in other scenarios."
msgstr "گاهی اوقات لازم است کاری کنید که هندلرهای گزارش‌گیری (logging handlers) کار خود را بدون مسدود کردن نخی که از آن گزارش‌گیری می‌کنید، انجام دهند. این حالت در برنامه‌های وب رایج است، هرچند البته در سناریوهای دیگر نیز رخ می‌دهد."

msgid "A common culprit which demonstrates sluggish behaviour is the :class:`SMTPHandler`: sending emails can take a long time, for a number of reasons outside the developer's control (for example, a poorly performing mail or network infrastructure). But almost any network-based handler can block: Even a :class:`SocketHandler` operation may do a DNS query under the hood which is too slow (and this query can be deep in the socket library code, below the Python layer, and outside your control)."
msgstr "یکی از عوامل رایج که رفتار کندی از خود نشان می‌دهد، :class:`SMTPHandler` است: ارسال ایمیل‌ها ممکن است به دلایل متعددی خارج از کنترل توسعه‌دهنده زمان زیادی ببرد (برای مثال، زیرساخت ایمیل یا شبکه با عملکرد ضعیف). اما تقریباً هر هندلر مبتنی بر شبکه‌ای می‌تواند مسدودکننده باشد: حتی یک عملیات :class:`SocketHandler` ممکن است در پشت صحنه یک پرس‌وجوی DNS انجام دهد که بیش از حد کند است (و این پرس‌وجو می‌تواند در عمق کد کتابخانه سوکت، پایین‌تر از لایه پایتون و خارج از کنترل شما باشد)."

msgid "One solution is to use a two-part approach. For the first part, attach only a :class:`QueueHandler` to those loggers which are accessed from performance-critical threads. They simply write to their queue, which can be sized to a large enough capacity or initialized with no upper bound to their size. The write to the queue will typically be accepted quickly, though you will probably need to catch the :exc:`queue.Full` exception as a precaution in your code. If you are a library developer who has performance-critical threads in their code, be sure to document this (together with a suggestion to attach only ``QueueHandlers`` to your loggers) for the benefit of other developers who will use your code."
msgstr "یک راه‌حل، استفاده از یک رویکرد دوبخشی است. برای بخش نخست، فقط یک :class:`QueueHandler` را به آن دسته از گزارش‌گیرها که از نخ‌های حساس به عملکرد به آن‌ها دسترسی می‌شود، متصل کنید. آن‌ها به‌سادگی در صف خود می‌نویسند؛ صفی که می‌توان آن را با ظرفیتی به‌اندازه کافی بزرگ تنظیم کرد یا بدون کران بالا برای اندازه‌اش مقداردهی اولیه کرد. نوشتن در صف معمولاً به‌سرعت پذیرفته می‌شود، هرچند احتمالاً لازم است استثنای :exc:`queue.Full` را به‌عنوان اقدام احتیاطی در کد خود مهار کنید. اگر توسعه‌دهنده کتابخانه هستید و نخ‌های حساس به عملکرد در کد خود دارید، حتماً این موضوع را (به‌همراه پیشنهادی مبنی بر اینکه فقط ``QueueHandlers`` را به گزارش‌گیرها شما متصل کنند) برای بهره‌مندی سایر توسعه‌دهندگانی که از کد شما استفاده خواهند کرد، مستند کنید."

msgid "The second part of the solution is :class:`QueueListener`, which has been designed as the counterpart to :class:`QueueHandler`.  A :class:`QueueListener` is very simple: it's passed a queue and some handlers, and it fires up an internal thread which listens to its queue for LogRecords sent from ``QueueHandlers`` (or any other source of ``LogRecords``, for that matter). The ``LogRecords`` are removed from the queue and passed to the handlers for processing."
msgstr "بخش دوم راه‌حل :class:`QueueListener` است که به‌عنوان همتای :class:`QueueHandler` طراحی شده است. یک :class:`QueueListener` بسیار ساده است: یک صف و چند هندلر به آن داده می‌شود و آن یک نخ داخلی راه‌اندازی می‌کند که به صف خود برای دریافت LogRecords ارسال‌شده از ``QueueHandlers`` (یا هر منبع دیگری از ``LogRecords``، در این خصوص) گوش می‌دهد. ``LogRecords`` از صف حذف می‌شوند و برای پردازش به هندلرها داده می‌شوند."

msgid "The advantage of having a separate :class:`QueueListener` class is that you can use the same instance to service multiple ``QueueHandlers``. This is more resource-friendly than, say, having threaded versions of the existing handler classes, which would eat up one thread per handler for no particular benefit."
msgstr "مزیت داشتن یک کلاس :class:`QueueListener` جداگانه این است که می‌توانید از یک نمونه‌ی واحد برای سرویس‌دهی به چندین ``QueueHandlers`` استفاده کنید. این کار از نظر مصرف منابع به‌صرفه‌تر از، مثلاً، داشتن نسخه‌های مبتنی بر نخ از کلاس‌های هندلر موجود است؛ نسخه‌هایی که به ازای هر handler یک نخ را بدون هیچ مزیت خاصی مصرف می‌کردند."

msgid "An example of using these two classes follows (imports omitted)::"
msgstr "در ادامه مثالی از استفاده از این دو کلاس آمده است (ایمپورت‌ها حذف شده‌اند)::"

msgid ""
"que = queue.Queue(-1)  # no limit on size\n"
"queue_handler = QueueHandler(que)\n"
"handler = logging.StreamHandler()\n"
"listener = QueueListener(que, handler)\n"
"root = logging.getLogger()\n"
"root.addHandler(queue_handler)\n"
"formatter = logging.Formatter('%(threadName)s: %(message)s')\n"
"handler.setFormatter(formatter)\n"
"listener.start()\n"
"# The log output will display the thread which generated\n"
"# the event (the main thread) rather than the internal\n"
"# thread which monitors the internal queue. This is what\n"
"# you want to happen.\n"
"root.warning('Look out!')\n"
"listener.stop()"
msgstr ""
"que = queue.Queue(-1)  # no limit on size\n"
"queue_handler = QueueHandler(que)\n"
"handler = logging.StreamHandler()\n"
"listener = QueueListener(que, handler)\n"
"root = logging.getLogger()\n"
"root.addHandler(queue_handler)\n"
"formatter = logging.Formatter('%(threadName)s: %(message)s')\n"
"handler.setFormatter(formatter)\n"
"listener.start()\n"
"# The log output will display the thread which generated\n"
"# the event (the main thread) rather than the internal\n"
"# thread which monitors the internal queue. This is what\n"
"# you want to happen.\n"
"root.warning('Look out!')\n"
"listener.stop()"

msgid "which, when run, will produce:"
msgstr "که با اجرای آن، خروجی زیر تولید می‌شود:"

msgid "MainThread: Look out!"
msgstr "MainThread: Look out!"

msgid "Although the earlier discussion wasn't specifically talking about async code, but rather about slow logging handlers, it should be noted that when logging from async code, network and even file handlers could lead to problems (blocking the event loop) because some logging is done from :mod:`asyncio` internals. It might be best, if any async code is used in an application, to use the above approach for logging, so that any blocking code runs only in the ``QueueListener`` thread."
msgstr "اگرچه بحث پیشین به‌طور مشخص درباره‌ی کد ناهمگام نبود، بلکه درباره‌ی هندلرهای کند گزارش‌گیری بود، باید توجه داشت که هنگام گزارش‌گیری از کد ناهمگام، هندلرهای شبکه و حتی پرونده می‌توانند به مشکلاتی منجر شوند (مسدود کردن حلقه‌ی رویداد)، زیرا بخشی از گزارش‌گیری از درونی :mod:`asyncio` انجام می‌شود. اگر در یک برنامه از هرگونه کد ناهمگام استفاده می‌شود، ممکن است بهتر باشد برای گزارش‌گیری از روش بالا استفاده کنید، تا هر کد مسدودکننده‌ای فقط در نخ ``QueueListener`` اجرا شود."

msgid "Prior to Python 3.5, the :class:`QueueListener` always passed every message received from the queue to every handler it was initialized with. (This was because it was assumed that level filtering was all done on the other side, where the queue is filled.) From 3.5 onwards, this behaviour can be changed by passing a keyword argument ``respect_handler_level=True`` to the listener's constructor. When this is done, the listener compares the level of each message with the handler's level, and only passes a message to a handler if it's appropriate to do so."
msgstr "پیش از پایتون 3.5، :class:`QueueListener` همیشه هر پیام دریافت‌شده از صف را به هر هندلر که شنونده با آن مقداردهی اولیه شده بود، ارسال می‌کرد. (این به این دلیل بود که فرض می‌شد تمام پالایش سطح در سمت دیگر، جایی که صف پر می‌شود، انجام می‌شود.) از 3.5 به بعد، می‌توان این رفتار را با ارسال یک آرگومان کلیدواژه‌ای ``respect_handler_level=True`` به سازنده‌ی شنونده تغییر داد. هنگامی که این کار انجام شود، شنونده سطح هر پیام را با سطح مدیر مقایسه می‌کند و تنها در صورتی یک پیام را به یک مدیر ارسال می‌کند که این کار مناسب باشد."

msgid "The :class:`QueueListener` can be started (and stopped) via the :keyword:`with` statement. For example:"
msgstr "می‌توان :class:`QueueListener` را از طریق دستور :keyword:`with` راه‌اندازی (و متوقف) کرد. برای مثال:"

msgid ""
"with QueueListener(que, handler) as listener:\n"
"    # The queue listener automatically starts\n"
"    # when the 'with' block is entered.\n"
"    pass\n"
"# The queue listener automatically stops once\n"
"# the 'with' block is exited."
msgstr ""
"with QueueListener(que, handler) as listener:\n"
"    # The queue listener automatically starts\n"
"    # when the 'with' block is entered.\n"
"    pass\n"
"# The queue listener automatically stops once\n"
"# the 'with' block is exited."

msgid "Sending and receiving logging events across a network"
msgstr "ارسال و دریافت رویدادهای گزارش در سراسر شبکه"