logging.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:
# Alireza Shabani (Revisto) <theRevisto@gmail.com>, 2025
# Danial Behzadi <dani.behzi@ubuntu.com>, 2025
# Rafael Fontenelle <rffontenelle@gmail.com>, 2025
# Sepehr Rasouli <sepehrrasouli06@gmail.com>, 2026
#
msgid ""
msgstr ""
"Project-Id-Version: Python 3.14\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-09-16 12:56+0000\n"
"PO-Revision-Date: 2026-09-14 10:26+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 HOWTO"
msgstr "راهنمای گزارش‌گیری"

msgid "Author"
msgstr "نویسنده"

msgid "Vinay Sajip <vinay_sajip at red-dove dot com>"
msgstr "Vinay Sajip <vinay_sajip at red-dove dot com>"

msgid "This page contains tutorial information. For links to reference information and a logging cookbook, please see :ref:`tutorial-ref-links`."
msgstr "این صفحه شامل اطلاعات آموزشی است. برای پیوندهایی به اطلاعات مرجع و یک کتابچه‌ی آشپزی برای گزارش‌گیری (logging cookbook)، لطفاً :ref:`tutorial-ref-links` را ببینید."

msgid "Basic Logging Tutorial"
msgstr "آموزش مقدماتی گزارش‌گیری"

msgid "Logging is a means of tracking events that happen when some software runs. The software's developer adds logging calls to their code to indicate that certain events have occurred. An event is described by a descriptive message which can optionally contain variable data (i.e. data that is potentially different for each occurrence of the event). Events also have an importance which the developer ascribes to the event; the importance can also be called the *level* or *severity*."
msgstr "ثبت رویداد راهی برای پیگیری رویدادهایی است که هنگام اجرای یک نرم‌افزار رخ می‌دهند. توسعه‌دهنده‌ی نرم‌افزار فراخوانی‌های ثبت رویداد را به کد خود اضافه می‌کند تا نشان دهد رویدادهای خاصی رخ داده‌اند. یک رویداد با یک پیام توصیفی توصیف می‌شود که می‌تواند به‌صورت اختیاری حاوی داده‌های متغیر باشد (یعنی داده‌هایی که ممکن است برای هر وقوع رویداد متفاوت باشند). رویدادها همچنین دارای اهمیتی هستند که توسعه‌دهنده به رویداد نسبت می‌دهد؛ این اهمیت را می‌توان *سطح* یا *شدت* نیز نامید."

msgid "When to use logging"
msgstr "چه زمانی از گزارش‌گیری استفاده کنیم"

msgid "You can access logging functionality by creating a logger via ``logger = logging.getLogger(__name__)``, and then calling the logger's :meth:`~Logger.debug`, :meth:`~Logger.info`, :meth:`~Logger.warning`, :meth:`~Logger.error` and :meth:`~Logger.critical` methods. To determine when to use logging, and to see which logger methods to use when, see the table below. It states, for each of a set of common tasks, the best tool to use for that task."
msgstr "شما می‌توانید با ایجاد یک گزارش‌گیر از طریق ``logger = logging.getLogger(__name__)`` و سپس فراخوانی متدهای :meth:`~Logger.debug`، :meth:`~Logger.info`، :meth:`~Logger.warning`، :meth:`~Logger.error` و :meth:`~Logger.critical` آن، به قابلیت گزارش‌گیری دسترسی پیدا کنید. برای تشخیص اینکه چه زمانی از گزارش‌گیری استفاده کنید و ببینید چه زمانی از کدام متدهای گزارش‌گیر استفاده کنید، به جدول زیر مراجعه کنید. این جدول برای هر یک از مجموعه‌ای از وظایف رایج، بهترین ابزار برای استفاده در آن وظیفه را بیان می‌کند."

msgid "Task you want to perform"
msgstr "کاری که می‌خواهید انجام دهید"

msgid "The best tool for the task"
msgstr "بهترین ابزار برای این کار"

msgid "Display console output for ordinary usage of a command line script or program"
msgstr "نمایش خروجی کنسول برای استفاده معمول از یک اسکریپت یا برنامه خط فرمان"

msgid ":func:`print`"
msgstr ":func:`print`"

msgid "Report events that occur during normal operation of a program (e.g. for status monitoring or fault investigation)"
msgstr "گزارش رویدادهایی که در حین عملکرد عادی یک برنامه رخ می‌دهند (برای مثال برای پایش وضعیت یا بررسی خطا)"

msgid "A logger's :meth:`~Logger.info` (or :meth:`~Logger.debug` method for very detailed output for diagnostic purposes)"
msgstr "متد :meth:`~Logger.info` یک گزارش‌گیر (یا متد :meth:`~Logger.debug` برای خروجی با جزئیات بسیار برای اهداف تشخیصی)"

msgid "Issue a warning regarding a particular runtime event"
msgstr "صدور یک هشدار در مورد یک رویداد ران‌تایم خاص"

msgid ":func:`warnings.warn` in library code if the issue is avoidable and the client application should be modified to eliminate the warning"
msgstr ":func:`warnings.warn` در کد کتابخانه‌ای، اگر مشکل قابل‌اجتناب است و برنامه‌ی کلاینت باید برای حذف هشدار اصلاح شود"

msgid "A logger's :meth:`~Logger.warning` method if there is nothing the client application can do about the situation, but the event should still be noted"
msgstr "متد :meth:`~Logger.warning` گزارش‌گیر، اگر برنامه کلاینت نتواند هیچ کاری درباره آن موقعیت انجام دهد، اما رویداد همچنان باید ثبت شود"

msgid "Report an error regarding a particular runtime event"
msgstr "گزارش یک خطا در مورد یک رویداد ران‌تایم خاص"

msgid "Raise an exception"
msgstr "پرتاب یک استثنا"

msgid "Report suppression of an error without raising an exception (e.g. error handler in a long-running server process)"
msgstr "گزارش فرونشانی یک خطا بدون پرتاب استثنا (مثلاً هندلر خطا در یک فرآیند سرور طولانی‌مدت)"

msgid "A logger's :meth:`~Logger.error`, :meth:`~Logger.exception` or :meth:`~Logger.critical` method as appropriate for the specific error and application domain"
msgstr "متد :meth:`~Logger.error`، :meth:`~Logger.exception` یا :meth:`~Logger.critical` یک گزارش‌گیر، متناسب با خطای مشخص و حوزه‌ی کاربرد"

msgid "The logger methods are named after the level or severity of the events they are used to track. The standard levels and their applicability are described below (in increasing order of severity):"
msgstr "متدهای گزارش‌گیر بر اساس سطح یا شدت رویدادهایی که برای پیگیری آن‌ها استفاده می‌شوند، نام‌گذاری شده‌اند. سطح‌های استاندارد و موارد کاربرد آن‌ها در زیر شرح داده شده‌اند (به‌ترتیب افزایشی شدت):"

msgid "Level"
msgstr "سطح"

msgid "When it's used"
msgstr "هنگامی که استفاده می‌شود"

msgid "``DEBUG``"
msgstr "``DEBUG``"

msgid "Detailed information, typically of interest only when diagnosing problems."
msgstr "اطلاعات دقیق، معمولاً فقط هنگام اشکال‌زدایی مشکلات مورد توجه است."

msgid "``INFO``"
msgstr "``INFO``"

msgid "Confirmation that things are working as expected."
msgstr "تأیید اینکه همه‌چیز مطابق انتظار کار می‌کند."

msgid "``WARNING``"
msgstr "``WARNING``"

msgid "An indication that something unexpected happened, or indicative of some problem in the near future (e.g. 'disk space low'). The software is still working as expected."
msgstr "نشانه‌ای از اینکه اتفاق غیرمنتظره‌ای رخ داده است، یا نشان‌دهنده‌ی مشکلی در آینده‌ی نزدیک (مثلاً «فضای دیسک کم است»). نرم‌افزار همچنان مطابق انتظار کار می‌کند."

msgid "``ERROR``"
msgstr "``ERROR``"

msgid "Due to a more serious problem, the software has not been able to perform some function."
msgstr "به دلیل مشکلی جدی‌تر، نرم‌افزار نتوانسته است برخی عملکردها را انجام دهد."

msgid "``CRITICAL``"
msgstr "``CRITICAL``"

msgid "A serious error, indicating that the program itself may be unable to continue running."
msgstr "یک خطای جدی، که نشان می‌دهد خود برنامه ممکن است نتواند به اجرا ادامه دهد."

msgid "The default level is ``WARNING``, which means that only events of this severity and higher will be tracked, unless the logging package is configured to do otherwise."
msgstr "سطح پیش‌فرض ``WARNING`` است، یعنی فقط رویدادهای این شدت و بالاتر از آن پیگیری می‌شوند، مگر اینکه بسته‌ی logging به‌گونه‌ای دیگر پیکربندی شده باشد."

msgid "Events that are tracked can be handled in different ways. The simplest way of handling tracked events is to print them to the console. Another common way is to write them to a disk file."
msgstr "رویدادهایی که پیگیری می‌شوند را می‌توان به روش‌های مختلفی مدیریت کرد. ساده‌ترین روش برای مدیریت رویدادهای پیگیری‌شده، چاپ آن‌ها در کنسول است. یک روش رایج دیگر، نوشتن آن‌ها در یک پرونده روی دیسک است."

msgid "A simple example"
msgstr "یک مثال ساده"

msgid "A very simple example is::"
msgstr "یک مثال بسیار ساده::"

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

msgid "If you type these lines into a script and run it, you'll see:"
msgstr "اگر این سطرها را در یک اسکریپت وارد کنید و آن را اجرا کنید، خواهید دید:"

msgid "WARNING:root:Watch out!"
msgstr "WARNING:root:مراقب باشید!"

msgid "printed out on the console. The ``INFO`` message doesn't appear because the default level is ``WARNING``. The printed message includes the indication of the level and the description of the event provided in the logging call, i.e. 'Watch out!'. The actual output can be formatted quite flexibly if you need that; formatting options will also be explained later."
msgstr "در کنسول چاپ می‌شود. پیام ``INFO`` نمایش داده نمی‌شود زیرا سطح پیش‌فرض ``WARNING`` است. پیام چاپ‌شده شامل نشانگر سطح و شرح رویداد ارائه‌شده در فراخوانی logging است، یعنی 'Watch out!'. در صورت نیاز، می‌توان خروجی واقعی را با انعطاف‌پذیری بالایی قالب‌بندی کرد؛ گزینه‌های قالب‌بندی نیز بعداً توضیح داده خواهند شد."

msgid "Notice that in this example, we use functions directly on the ``logging`` module, like ``logging.debug``, rather than creating a logger and calling functions on it. These functions operate on the root logger, but can be useful as they will call :func:`~logging.basicConfig` for you if it has not been called yet, like in this example.  In larger programs you'll usually want to control the logging configuration explicitly however - so for that reason as well as others, it's better to create loggers and call their methods."
msgstr "توجه داشته باشید که در این مثال، به‌جای ایجاد یک گزارش‌گیر و فراخوانی توابع آن، مستقیماً از توابع ماژول ``logging``، مانند ``logging.debug``، استفاده می‌کنیم. این توابع بر روی گزارش‌گیر ریشه عمل می‌کنند، اما می‌توانند مفید باشند، زیرا اگر :func:`~logging.basicConfig` هنوز فراخوانی نشده باشد، آن را برای شما فراخوانی می‌کنند، همان‌طور که در این مثال دیده می‌شود. با این حال، در برنامه‌های بزرگ‌تر معمولاً می‌خواهید پیکربندی گزارش‌گیری را به‌صراحت کنترل کنید؛ بنابراین به همین دلیل و دلایل دیگر، بهتر است گزارش‌گیرها را ایجاد کنید و متدهای آن‌ها را فراخوانی کنید."

msgid "Logging to a file"
msgstr "گزارش‌گیری در یک پرونده"

msgid "A very common situation is that of recording logging events in a file, so let's look at that next. Be sure to try the following in a newly started Python interpreter, and don't just continue from the session described above::"
msgstr "یک حالت بسیار رایج، ثبت رویدادهای گزارش در یک پرونده است، بنابراین در ادامه به بررسی آن می‌پردازیم. حتماً موارد زیر را در یک مفسر پایتون که به‌تازگی آغاز شده است آزمایش کنید و صرفاً از نشست توصیف‌شده در بالا ادامه ندهید::"

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

msgid "The *encoding* argument was added. In earlier Python versions, or if not specified, the encoding used is the default value used by :func:`open`. While not shown in the above example, an *errors* argument can also now be passed, which determines how encoding errors are handled. For available values and the default, see the documentation for :func:`open`."
msgstr "آرگومان *encoding* افزوده شد. در نسخه‌های پیشین پایتون، یا اگر مشخص نشده باشد، کدگذاری استفاده‌شده مقدار پیش‌فرضی است که توسط :func:`open` استفاده می‌شود. اگرچه در مثال بالا نشان داده نشده است، اکنون می‌توان آرگومان *errors* را نیز ارسال کرد که تعیین می‌کند خطاهای کدگذاری چگونه مدیریت شوند. برای مقادیر موجود و مقدار پیش‌فرض، مستندات :func:`open` را ببینید."

msgid "And now if we open the file and look at what we have, we should find the log messages:"
msgstr "و اکنون اگر پرونده را باز کنیم و به آنچه داریم نگاه کنیم، باید پیام‌های گزارش را پیدا کنیم:"

msgid ""
"DEBUG:__main__:This message should go to the log file\n"
"INFO:__main__:So should this\n"
"WARNING:__main__:And this, too\n"
"ERROR:__main__:And non-ASCII stuff, too, like Øresund and Malmö"
msgstr ""
"DEBUG:__main__:این پیام باید به پرونده گزارش برود\n"
"INFO:__main__:این پیام هم همین‌طور\n"
"WARNING:__main__:و این هم همین‌طور\n"
"ERROR:__main__:و موارد غیر اسکی (non-ASCII) نیز، مانند Øresund و Malmö"

msgid "This example also shows how you can set the logging level which acts as the threshold for tracking. In this case, because we set the threshold to ``DEBUG``, all of the messages were printed."
msgstr "این مثال همچنین نشان می‌دهد که چگونه می‌توانید سطح گزارش‌گیری را تنظیم کنید که به‌عنوان آستانه‌ای برای پیگیری عمل می‌کند. در این مورد، چون آستانه را روی ``DEBUG`` تنظیم کردیم، تمام پیام‌ها چاپ شدند."

msgid "If you want to set the logging level from a command-line option such as:"
msgstr "اگر می‌خواهید سطح گزارش را از طریق یک گزینه‌ی خط فرمان تنظیم کنید، مانند:"

msgid "--log=INFO"
msgstr "--log=INFO"

msgid "and you have the value of the parameter passed for ``--log`` in some variable *loglevel*, you can use::"
msgstr "و مقدار پارامتر داده‌شده برای ``--log`` را در متغیری به نام *loglevel* دارید، می‌توانید به این صورت استفاده کنید::"

msgid "getattr(logging, loglevel.upper())"
msgstr "getattr(logging, loglevel.upper())"

msgid "to get the value which you'll pass to :func:`basicConfig` via the *level* argument. You may want to error check any user input value, perhaps as in the following example::"
msgstr "برای دریافت مقداری که آن را از طریق آرگومان *level* به :func:`basicConfig` می‌دهید. ممکن است بخواهید هر مقدار ورودی کاربر را از نظر خطا بررسی کنید، شاید مانند مثال زیر::"

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

msgid "The call to :func:`basicConfig` should come *before* any calls to a logger's methods such as :meth:`~Logger.debug`, :meth:`~Logger.info`, etc. Otherwise, that logging event may not be handled in the desired manner."
msgstr "فراخوانی :func:`basicConfig` باید *پیش از* هر فراخوانی از متدهای گزارش‌گیر مانند :meth:`~Logger.debug`، :meth:`~Logger.info` و غیره انجام شود. در غیر این صورت، ممکن است آن رویداد گزارش به روش دلخواه مدیریت نشود."

msgid "If you run the above script several times, the messages from successive runs are appended to the file *example.log*. If you want each run to start afresh, not remembering the messages from earlier runs, you can specify the *filemode* argument, by changing the call in the above example to::"
msgstr "اگر اسکریپت بالا را چند بار اجرا کنید، پیام‌های اجراهای پیاپی به پرونده *example.log* افزوده می‌شوند. اگر می‌خواهید هر اجرا از نو آغاز شود و پیام‌های اجراهای پیشین را به خاطر نداشته باشد، می‌توانید با تغییر فراخوانی در مثال بالا به شکل زیر، آرگومان *filemode* را مشخص کنید::"

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

msgid "The output will be the same as before, but the log file is no longer appended to, so the messages from earlier runs are lost."
msgstr "خروجی مانند قبل خواهد بود، اما دیگر به پرونده گزارش الحاق نمی‌شود، بنابراین پیام‌های اجراهای پیشین از دست می‌روند."

msgid "Logging variable data"
msgstr "ثبت داده‌های متغیر"

msgid "To log variable data, use a format string for the event description message and append the variable data as arguments. For example::"
msgstr "برای ثبت داده‌های متغیر، از یک رشته قالب برای پیام توصیف رویداد استفاده کنید و داده‌های متغیر را به‌عنوان آرگومان اضافه کنید. برای مثال::"

msgid ""
"import logging\n"
"logging.warning('%s before you %s', 'Look', 'leap!')"
msgstr ""
"import logging\n"
"logging.warning('%s before you %s', 'Look', 'leap!')"

msgid "will display:"
msgstr "نمایش خواهد داد:"

msgid "WARNING:root:Look before you leap!"
msgstr "WARNING:root:پیش از اقدام، تأمل کنید!"

msgid "As you can see, merging of variable data into the event description message uses the old, %-style of string formatting. This is for backwards compatibility: the logging package pre-dates newer formatting options such as :meth:`str.format` and :class:`string.Template`. These newer formatting options *are* supported, but exploring them is outside the scope of this tutorial: see :ref:`formatting-styles` for more information."
msgstr "همان‌طور که می‌بینید، ادغام داده‌های متغیر در پیام توصیف رویداد از سبک قدیمی قالب‌بندی رشته با %-style استفاده می‌کند. این برای سازگاری با نسخه‌های قدیمی است: بسته‌ی logging پیش از گزینه‌های قالب‌بندی جدیدتری مانند :meth:`str.format` و :class:`string.Template` وجود داشته است. این گزینه‌های قالب‌بندی جدیدتر *پشتیبانی می‌شوند*، اما بررسی آن‌ها خارج از محدوده این آموزش است: برای اطلاعات بیشتر :ref:`formatting-styles` را ببینید."

msgid "Changing the format of displayed messages"
msgstr "تغییر قالب پیام‌های نمایش‌داده‌شده"

msgid "To change the format which is used to display messages, you need to specify the format you want to use::"
msgstr "برای تغییر قالبی که برای نمایش پیام‌ها استفاده می‌شود، باید قالبی را که می‌خواهید استفاده کنید، مشخص کنید::"

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

msgid "which would print:"
msgstr "که این را چاپ خواهد کرد:"

msgid ""
"DEBUG:This message should appear on the console\n"
"INFO:So should this\n"
"WARNING:And this, too"
msgstr ""
"DEBUG:این پیام باید در کنسول ظاهر شود\n"
"INFO:این پیام نیز همین‌طور\n"
"WARNING:و این پیام نیز همین‌طور"

msgid "Notice that the 'root' which appeared in earlier examples has disappeared. For a full set of things that can appear in format strings, you can refer to the documentation for :ref:`logrecord-attributes`, but for simple usage, you just need the *levelname* (severity), *message* (event description, including variable data) and perhaps to display when the event occurred. This is described in the next section."
msgstr "توجه داشته باشید که 'root' که در مثال‌های پیشین ظاهر شده بود، ناپدید شده است. برای مشاهده مجموعه کاملی از مواردی که می‌توانند در رشته‌های قالب ظاهر شوند، می‌توانید به مستندات :ref:`logrecord-attributes` مراجعه کنید، اما برای استفاده ساده، فقط به *levelname* (شدت)، *message* (توصیف رویداد، شامل داده‌های متغیر) و احتمالاً به نمایش زمان وقوع رویداد نیاز دارید. این موضوع در بخش بعدی توضیح داده شده است."

msgid "Displaying the date/time in messages"
msgstr "نمایش تاریخ/زمان در پیام‌ها"

msgid "To display the date and time of an event, you would place '%(asctime)s' in your format string::"
msgstr "برای نمایش تاریخ و زمان یک رویداد، '%(asctime)s' را در رشته قالب خود قرار می‌دهید::"

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

msgid "which should print something like this:"
msgstr "که باید چیزی شبیه به این چاپ کند:"

msgid "2010-12-12 11:41:42,612 is when this event was logged."
msgstr "2010-12-12 11:41:42,612 زمانی است که این رویداد ثبت شد."

msgid "The default format for date/time display (shown above) is like ISO8601 or :rfc:`3339`. If you need more control over the formatting of the date/time, provide a *datefmt* argument to ``basicConfig``, as in this example::"
msgstr "قالب پیش‌فرض برای نمایش تاریخ/زمان (که در بالا نشان داده شد) مانند ISO8601 یا :rfc:`3339` است. اگر به کنترل بیشتری بر قالب‌بندی تاریخ/زمان نیاز دارید، یک آرگومان *datefmt* به ``basicConfig`` ارائه دهید، همان‌طور که در این مثال آمده است::"

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

msgid "which would display something like this:"
msgstr "که چیزی شبیه به این را نمایش می‌دهد:"

msgid "12/12/2010 11:46:36 AM is when this event was logged."
msgstr "این رویداد در ۱۲/۱۲/۲۰۱۰ ۱۱:۴۶:۳۶ ق.ظ ثبت شده است."

msgid "The format of the *datefmt* argument is the same as supported by :func:`time.strftime`."
msgstr "قالب آرگومان *datefmt* همان قالبی است که :func:`time.strftime` از آن پشتیبانی می‌کند."

msgid "Next Steps"
msgstr "گام‌های بعدی"

msgid "That concludes the basic tutorial. It should be enough to get you up and running with logging. There's a lot more that the logging package offers, but to get the best out of it, you'll need to invest a little more of your time in reading the following sections. If you're ready for that, grab some of your favourite beverage and carry on."
msgstr "این آموزش مقدماتی به پایان رسید. این باید برای شروع کار شما با logging کافی باشد. بسته‌ی logging امکانات بسیار بیشتری ارائه می‌دهد، اما برای بهره‌مندی هرچه بهتر از آن، لازم است کمی بیشتر زمان خود را صرف خواندن بخش‌های بعدی کنید. اگر برای این کار آماده‌اید، نوشیدنی دلخواه‌تان را بردارید و ادامه دهید."

msgid "If your logging needs are simple, then use the above examples to incorporate logging into your own scripts, and if you run into problems or don't understand something, please post a question in the Help category of the `Python discussion forum <https://discuss.python.org/c/help/7>`_ and you should receive help before too long."
msgstr "اگر نیازهای شما به گزارش ساده هستند، از مثال‌های بالا برای گنجاندن گزارش در اسکریپت‌های خود استفاده کنید و اگر با مشکلی مواجه شدید یا چیزی را متوجه نشدید، لطفاً پرسش خود را در دسته‌ی Help در `انجمن گفتگوی پایتون <https://discuss.python.org/c/help/7>`_ ارسال کنید؛ باید به‌زودی کمک دریافت کنید."

msgid "Still here? You can carry on reading the next few sections, which provide a slightly more advanced/in-depth tutorial than the basic one above. After that, you can take a look at the :ref:`logging-cookbook`."
msgstr "هنوز اینجا هستید؟ می‌توانید به خواندن چند بخش بعدی ادامه دهید، که آموزشی کمی پیشرفته‌تر/عمیق‌تر از آموزش پایه‌ی بالا ارائه می‌دهند. پس از آن، می‌توانید نگاهی به :ref:`logging-cookbook` بیندازید."

msgid "Advanced Logging Tutorial"
msgstr "آموزش پیشرفته گزارش‌گیری"

msgid "The logging library takes a modular approach and offers several categories of components: loggers, handlers, filters, and formatters."
msgstr "کتابخانه‌ی logging رویکردی ماژولار دارد و چندین دسته از کامپوننت‌ها را ارائه می‌دهد: گزارش‌گیرها، هندلرها، فیلترها و قالب‌بندها (formatters)."

msgid "Loggers expose the interface that application code directly uses."
msgstr "گزارش‌گیرها رابطی را که کد برنامه به‌طور مستقیم از آن استفاده می‌کند، در دسترس قرار می‌دهند."

msgid "Handlers send the log records (created by loggers) to the appropriate destination."
msgstr "هندلرها رکوردهای گزارش را که توسط گزارش‌گیرها  ایجاد شده‌اند، به مقصد مناسب ارسال می‌کنند."

msgid "Filters provide a finer grained facility for determining which log records to output."
msgstr "فیلترها امکان دقیق‌تری را برای تعیین اینکه کدام رکوردهای گزارش باید خروجی داده شوند، فراهم می‌کنند."

msgid "Formatters specify the layout of log records in the final output."
msgstr "قالب‌بندها چیدمان رکوردهای گزارش را در خروجی نهایی مشخص می‌کنند."

msgid "Log event information is passed between loggers, handlers, filters and formatters in a :class:`LogRecord` instance."
msgstr "اطلاعات رویداد گزارش بین گزارش‌گیرها، هندلرها، فیلترها و قالب‌بندها در یک نمونه از :class:`LogRecord` منتقل می‌شود."

msgid "Logging is performed by calling methods on instances of the :class:`Logger` class (hereafter called :dfn:`loggers`). Each instance has a name, and they are conceptually arranged in a namespace hierarchy using dots (periods) as separators. For example, a logger named 'scan' is the parent of loggers 'scan.text', 'scan.html' and 'scan.pdf'. Logger names can be anything you want, and indicate the area of an application in which a logged message originates."
msgstr "گزارش کردن با فراخوانی متدهای نمونه‌هایی از کلاس :class:`Logger` (که از این پس :dfn:`loggers` نامیده می‌شوند) انجام می‌شود. هر نمونه یک نام دارد، و آن‌ها به‌صورت مفهومی در یک سلسله‌مراتب فضای نام با استفاده از نقطه‌ها (periods) به‌عنوان جداکننده چیده شده‌اند. برای مثال، یک گزارش‌گیر با نام 'scan' والد گزارش‌گیرهای 'scan.text'، 'scan.html' و 'scan.pdf' است. نام‌های گزارش‌گیر می‌توانند هر چیزی باشند که شما بخواهید، و بخشی از یک برنامه را که یک پیام گزارش‌شده از آن سرچشمه می‌گیرد، نشان می‌دهند."

msgid "A good convention to use when naming loggers is to use a module-level logger, in each module which uses logging, named as follows::"
msgstr "یک قرارداد خوب هنگام نام‌گذاری گزارش‌گیرها این است که در هر ماژولی که از گزارش‌گیری  استفاده می‌کند، از یک گزارش‌گیر سطح ماژول با نام زیر استفاده کنید::"

msgid "logger = logging.getLogger(__name__)"
msgstr "logger = logging.getLogger(__name__)"

msgid "This means that logger names track the package/module hierarchy, and it's intuitively obvious where events are logged just from the logger name."
msgstr "این بدان معناست که نام‌های گزارش‌گیر سلسله‌مراتب بسته/ماژول را پیگیری می‌کنند، و تنها از روی نام گزارش‌گیر به‌طور شهودی آشکار است که رویدادها کجا ثبت می‌شوند."

msgid "The root of the hierarchy of loggers is called the root logger. That's the logger used by the functions :func:`debug`, :func:`info`, :func:`warning`, :func:`error` and :func:`critical`, which just call the same-named method of the root logger. The functions and the methods have the same signatures. The root logger's name is printed as 'root' in the logged output."
msgstr "ریشه‌ی سلسله‌مراتب گزارش‌گیرها، گزارش‌گیر ریشه نامیده می‌شود. این همان گزارش‌گیری است که توابع :func:`debug`، :func:`info`، :func:`warning`، :func:`error` و :func:`critical` از آن استفاده می‌کنند و صرفاً متد هم‌نام گزارش‌گیر ریشه را فراخوانی می‌کنند. این توابع و متدها امضاهای یکسانی دارند. نام گزارش‌گیر ریشه در خروجی گزارش‌شده به‌صورت 'root' چاپ می‌شود."

msgid "It is, of course, possible to log messages to different destinations. Support is included in the package for writing log messages to files, HTTP GET/POST locations, email via SMTP, generic sockets, queues, or OS-specific logging mechanisms such as syslog or the Windows NT event log. Destinations are served by :dfn:`handler` classes. You can create your own log destination class if you have special requirements not met by any of the built-in handler classes."
msgstr "البته، امکان ثبت پیام‌های گزارش در مقصدهای مختلف وجود دارد. پشتیبانی برای نوشتن پیام‌های گزارش در پرونده‌ها، مکان‌های HTTP GET/POST، ایمیل از طریق SMTP، سوکت‌های عام، صف‌ها، یا سازوکارهای گزارش مختص سیستم‌عامل مانند syslog یا گزارش رویداد ویندوز NT در این بسته گنجانده شده است. مقصدها توسط کلاس‌های :dfn:`handler` سرویس‌دهی می‌شوند. اگر نیازهای خاصی دارید که توسط هیچ‌یک از کلاس‌های handler توکار برآورده نمی‌شوند، می‌توانید کلاس مقصد گزارش خود را بسازید."

msgid "By default, no destination is set for any logging messages. You can specify a destination (such as console or file) by using :func:`basicConfig` as in the tutorial examples. If you call the functions  :func:`debug`, :func:`info`, :func:`warning`, :func:`error` and :func:`critical`, they will check to see if no destination is set; and if one is not set, they will set a destination of the console (``sys.stderr``) and a default format for the displayed message before delegating to the root logger to do the actual message output."
msgstr "به‌طور پیش‌فرض، هیچ مقصدی برای پیام‌های گزارش تنظیم نشده است. می‌توانید با استفاده از :func:`basicConfig` همان‌طور که در مثال‌های آموزش آمده است، یک مقصد (مانند کنسول یا پرونده) را مشخص کنید. اگر توابع :func:`debug`، :func:`info`، :func:`warning`، :func:`error` و :func:`critical` را فراخوانی کنید، آن‌ها بررسی می‌کنند که آیا هیچ مقصدی تنظیم نشده است؛ و اگر مقصدی تنظیم نشده باشد، پیش از واگذاری خروجی واقعی پیام به گزارش‌گیر ریشه، یک مقصد از نوع کنسول (``sys.stderr``) و یک قالب پیش‌فرض برای پیام نمایش‌داده‌شده تنظیم می‌کنند."

msgid "The default format set by :func:`basicConfig` for messages is:"
msgstr "قالب پیش‌فرضی که :func:`basicConfig` برای پیام‌ها تنظیم می‌کند، عبارت است از:"

msgid "severity:logger name:message"
msgstr "severity:logger name:message"

msgid "You can change this by passing a format string to :func:`basicConfig` with the *format* keyword argument. For all options regarding how a format string is constructed, see :ref:`formatter-objects`."
msgstr "شما می‌توانید این را با فرستادن یک رشته‌ی قالب به :func:`basicConfig` از طریق آرگومان کلیدواژه‌ای *format* تغییر دهید. برای همه‌ی گزینه‌های مربوط به نحوه‌ی ساخت یک رشته‌ی قالب، :ref:`formatter-objects` را ببینید."

msgid "Logging Flow"
msgstr "جریان گزارش‌گیری"

msgid "The flow of log event information in loggers and handlers is illustrated in the following diagram."
msgstr "جریان اطلاعات رویداد گزارش در گزارش‌گیرها و هندلرها در نمودار زیر نشان داده شده است."

msgid "Loggers"
msgstr "گزارش‌گیرها"

msgid ":class:`Logger` objects have a threefold job.  First, they expose several methods to application code so that applications can log messages at runtime. Second, logger objects determine which log messages to act upon based upon severity (the default filtering facility) or filter objects.  Third, logger objects pass along relevant log messages to all interested log handlers."
msgstr "اشیای :class:`Logger` وظیفه‌ای سه‌گانه دارند. نخست، آن‌ها چندین متد را در اختیار کد برنامه قرار می‌دهند تا برنامه‌ها بتوانند پیام‌های گزارش را در ران‌تایم ثبت کنند. دوم، اشیای گزارش‌گیر بر اساس شدت (سازوکار فیلتر پیش‌فرض) یا اشیای فیلتر، تعیین می‌کنند که کدام پیام‌های گزارش پردازش شوند. سوم، اشیای گزارش‌گیر پیام‌های گزارش مرتبط را به تمام هندلرهای گزارش علاقه‌مند منتقل می‌کنند."

msgid "The most widely used methods on logger objects fall into two categories: configuration and message sending."
msgstr "پرکاربردترین متدهای اشیای گزارش‌گیر به دو دسته تقسیم می‌شوند: پیکربندی و ارسال پیام."

msgid "These are the most common configuration methods:"
msgstr "این‌ها رایج‌ترین متدهای پیکربندی هستند:"

msgid ":meth:`Logger.setLevel` specifies the lowest-severity log message a logger will handle, where debug is the lowest built-in severity level and critical is the highest built-in severity.  For example, if the severity level is INFO, the logger will handle only INFO, WARNING, ERROR, and CRITICAL messages and will ignore DEBUG messages."
msgstr ":meth:`Logger.setLevel` پایین‌ترین سطح شدت پیام گزارشی را مشخص می‌کند که یک گزارش‌گیر رسیدگی خواهد کرد، که در آن debug پایین‌ترین سطح شدت توکار و critical بالاترین شدت توکار است. برای مثال، اگر سطح شدت INFO باشد، گزارش‌گیر فقط پیام‌های INFO، WARNING، ERROR و CRITICAL را رسیدگی می‌کند و پیام‌های DEBUG را نادیده می‌گیرد."

msgid ":meth:`Logger.addHandler` and :meth:`Logger.removeHandler` add and remove handler objects from the logger object.  Handlers are covered in more detail in :ref:`handler-basic`."
msgstr ":meth:`Logger.addHandler` و :meth:`Logger.removeHandler` اشیای handler را به شیء logger اضافه و از آن حذف می‌کنند. handlerها با جزئیات بیشتر در :ref:`handler-basic` پوشش داده شده‌اند."

msgid ":meth:`Logger.addFilter` and :meth:`Logger.removeFilter` add and remove filter objects from the logger object.  Filters are covered in more detail in :ref:`filter`."
msgstr ":meth:`Logger.addFilter` و :meth:`Logger.removeFilter` اشیای فیلتر را به شیء گزارش‌گیر اضافه و از آن حذف می‌کنند. فیلترها با جزئیات بیشتر در :ref:`filter` بررسی شده‌اند."

msgid "You don't need to always call these methods on every logger you create. See the last two paragraphs in this section."
msgstr "نیازی نیست همیشه این متدها را روی هر گزارش‌گیر که ایجاد می‌کنید فراخوانی کنید. دو پاراگراف آخر این بخش را ببینید."

msgid "With the logger object configured, the following methods create log messages:"
msgstr "با پیکربندی شیء logger، متدهای زیر پیام‌های گزارش ایجاد می‌کنند:"

msgid ":meth:`Logger.debug`, :meth:`Logger.info`, :meth:`Logger.warning`, :meth:`Logger.error`, and :meth:`Logger.critical` all create log records with a message and a level that corresponds to their respective method names. The message is actually a format string, which may contain the standard string substitution syntax of ``%s``, ``%d``, ``%f``, and so on.  The rest of their arguments is a list of objects that correspond with the substitution fields in the message.  With regard to ``**kwargs``, the logging methods care only about a keyword of ``exc_info`` and use it to determine whether to log exception information."
msgstr ":meth:`Logger.debug`، :meth:`Logger.info`، :meth:`Logger.warning`، :meth:`Logger.error` و :meth:`Logger.critical` همگی رکوردهای گزارش را ایجاد می‌کنند که دارای یک پیام و یک سطح هستند و سطح آن‌ها با نام متدهای مربوطه مطابقت دارد. پیام در واقع یک رشته‌ی قالب است که ممکن است حاوی سینتکس استاندارد جایگذاری رشته مانند ``%s``، ``%d``، ``%f`` و غیره باشد. سایر آرگومان‌های آن‌ها فهرستی از شیء‌ها است که با فیلدهای جایگذاری در پیام مطابقت دارند. در مورد ``**kwargs``، متدهای گزارش تنها به کلیدواژه‌ای با نام ``exc_info`` توجه می‌کنند و از آن برای تعیین اینکه آیا اطلاعات استثنا در گزارش ثبت شود یا خیر استفاده می‌کنند."

msgid ":meth:`Logger.exception` creates a log message similar to :meth:`Logger.error`.  The difference is that :meth:`Logger.exception` dumps a stack trace along with it.  Call this method only from an exception handler."
msgstr ":meth:`Logger.exception` یک پیام گزارش مشابه :meth:`Logger.error` ایجاد می‌کند. تفاوت این است که :meth:`Logger.exception` یک ردگیری پشته را نیز همراه آن خروجی می‌دهد. این متد را فقط از داخل یک هندلر استثنا فراخوانی کنید."

msgid ":meth:`Logger.log` takes a log level as an explicit argument.  This is a little more verbose for logging messages than using the log level convenience methods listed above, but this is how to log at custom log levels."
msgstr ":meth:`Logger.log` یک سطح گزارش را به‌عنوان آرگومان صریح دریافت می‌کند. این روش برای گزارش کردن پیام‌ها کمی طولانی‌تر از استفاده از متدهای سهولت‌بخش سطح گزارش فهرست‌شده در بالا است، اما روش گزارش کردن در سطح‌های گزارش سفارشی همین است."

msgid ":func:`getLogger` returns a reference to a logger instance with the specified name if it is provided, or ``root`` if not.  The names are period-separated hierarchical structures.  Multiple calls to :func:`getLogger` with the same name will return a reference to the same logger object.  Loggers that are further down in the hierarchical list are children of loggers higher up in the list. For example, given a logger with a name of ``foo``, loggers with names of ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all descendants of ``foo``."
msgstr ":func:`getLogger` در صورت ارائه شدن نام مشخص‌شده، ارجاعی به یک نمونه گزارش‌گیر با آن نام را برمی‌گرداند، و در غیر این صورت ``root`` را برمی‌گرداند. نام‌ها ساختارهای سلسله‌مراتبی هستند که با نقطه از هم جدا شده‌اند. فراخوانی‌های متعدد :func:`getLogger` با نام یکسان، ارجاعی به همان شیء گزارش‌گیر را برمی‌گرداند. گزارش‌گیرهای پایین‌تر در فهرست سلسله‌مراتبی، فرزندان گزارش‌گیرهای بالاتر در فهرست هستند. برای مثال، با فرض یک گزارش‌گیر با نام ``foo``، گزارش‌گیرهای دارای نام‌های ``foo.bar``، ``foo.bar.baz`` و ``foo.bam`` همگی از نوادگان ``foo`` هستند."

msgid "Loggers have a concept of *effective level*. If a level is not explicitly set on a logger, the level of its parent is used instead as its effective level. If the parent has no explicit level set, *its* parent is examined, and so on - all ancestors are searched until an explicitly set level is found. The root logger always has an explicit level set (``WARNING`` by default). When deciding whether to process an event, the effective level of the logger is used to determine whether the event is passed to the logger's handlers."
msgstr "گزارش‌گیرها مفهومی به نام *سطح مؤثر* دارند. اگر سطحی به‌صراحت روی یک گزارش‌گیر تنظیم نشده باشد، در عوض سطح والد آن به‌عنوان سطح مؤثر آن استفاده می‌شود. اگر والد سطح صریحی تنظیم‌شده نداشته باشد، والد *آن* بررسی می‌شود، و به همین ترتیب — تمام نیاکان جستجو می‌شوند تا سطحی که به‌صراحت تنظیم شده باشد پیدا شود. گزارش‌گیر ریشه همیشه سطح صریحی تنظیم‌شده دارد (به‌طور پیش‌فرض ``WARNING``). هنگام تصمیم‌گیری برای پردازش یک رویداد، از سطح مؤثر گزارش‌گیر برای تعیین اینکه آیا رویداد به هندلرهای گزارش‌گیر ارسال می‌شود یا خیر استفاده می‌شود."

msgid "Child loggers propagate messages up to the handlers associated with their ancestor loggers. Because of this, it is unnecessary to define and configure handlers for all the loggers an application uses. It is sufficient to configure handlers for a top-level logger and create child loggers as needed. (You can, however, turn off propagation by setting the *propagate* attribute of a logger to ``False``.)"
msgstr "گزارش‌گیرهای فرزند پیام‌ها را به هندلرهای مرتبط با گزارش‌گیرهای اجدادی خود منتشر می‌کنند. به همین دلیل، نیازی به تعریف و پیکربندی هندلرها برای تمام گزارش‌گیرهایی که یک برنامه از آن‌ها استفاده می‌کند، نیست. کافی است هندلرها را برای یک گزارش‌گیر سطح بالا پیکربندی کنید و گزارش‌گیرهای فرزند را در صورت نیاز ایجاد کنید. (با این حال، می‌توانید با تنظیم ویژگی *propagate* یک گزارش‌گیر روی ``False``، انتشار را غیرفعال کنید.)"

msgid "Handlers"
msgstr "هندلرها"

msgid ":class:`~logging.Handler` objects are responsible for dispatching the appropriate log messages (based on the log messages' severity) to the handler's specified destination.  :class:`Logger` objects can add zero or more handler objects to themselves with an :meth:`~Logger.addHandler` method.  As an example scenario, an application may want to send all log messages to a log file, all log messages of error or higher to stdout, and all messages of critical to an email address. This scenario requires three individual handlers where each handler is responsible for sending messages of a specific severity to a specific location."
msgstr "اشیاء :class:`~logging.Handler` مسئول ارسال پیام‌های گزارش مناسب (بر اساس شدت پیام‌های گزارش) به مقصد مشخص‌شده‌ی handler هستند. اشیاء :class:`Logger` می‌توانند با متد :meth:`~Logger.addHandler` صفر یا چند شیء handler را به خود اضافه کنند. به‌عنوان یک سناریوی نمونه، یک برنامه ممکن است بخواهد تمام پیام‌های گزارش را به یک پرونده گزارش، تمام پیام‌های گزارش با سطح خطا یا بالاتر را به stdout و تمام پیام‌های سطح بحرانی را به یک نشانی ایمیل ارسال کند. این سناریو به سه handler جداگانه نیاز دارد که هر handler مسئول ارسال پیام‌هایی با شدتی مشخص به مکانی مشخص است."

msgid "The standard library includes quite a few handler types (see :ref:`useful-handlers`); the tutorials use mainly :class:`StreamHandler` and :class:`FileHandler` in its examples."
msgstr "کتابخانه استاندارد شامل تعداد نسبتاً زیادی از انواع هندلر است (به :ref:`useful-handlers` مراجعه کنید)؛ آموزش‌ها در مثال‌های خود عمدتاً از :class:`StreamHandler` و :class:`FileHandler` استفاده می‌کنند."

msgid "There are very few methods in a handler for application developers to concern themselves with.  The only handler methods that seem relevant for application developers who are using the built-in handler objects (that is, not creating custom handlers) are the following configuration methods:"
msgstr "در یک هندلر، متدهای بسیار کمی وجود دارد که توسعه‌دهندگان برنامه باید به آن‌ها بپردازند. تنها متدهای هندلر که به نظر می‌رسد برای توسعه‌دهندگان برنامه‌ای که از اشیای هندلر توکار استفاده می‌کنند (یعنی هندلرهای سفارشی ایجاد نمی‌کنند) مرتبط باشند، متدهای پیکربندی زیر هستند:"

msgid "The :meth:`~Handler.setLevel` method, just as in logger objects, specifies the lowest severity that will be dispatched to the appropriate destination.  Why are there two :meth:`~Handler.setLevel` methods?  The level set in the logger determines which severity of messages it will pass to its handlers.  The level set in each handler determines which messages that handler will send on."
msgstr "متد :meth:`~Handler.setLevel`، همان‌طور که در اشیای logger نیز چنین است، کمترین سطح شدتی را که به مقصد مناسب ارسال خواهد شد مشخص می‌کند. چرا دو متد :meth:`~Handler.setLevel` وجود دارد؟ سطح تنظیم‌شده در logger تعیین می‌کند که پیام‌ها با چه شدتی به handlerهای آن منتقل شوند. سطح تنظیم‌شده در هر handler تعیین می‌کند که آن handler کدام پیام‌ها را ارسال کند."

msgid ":meth:`~Handler.setFormatter` selects a Formatter object for this handler to use."
msgstr ":meth:`~Handler.setFormatter` یک شیء Formatter را برای این هندلر  انتخاب می‌کند تا از آن استفاده کند."

msgid ":meth:`~Handler.addFilter` and :meth:`~Handler.removeFilter` respectively configure and deconfigure filter objects on handlers."
msgstr ":meth:`~Handler.addFilter` و :meth:`~Handler.removeFilter` به‌ترتیب اشیای فیلتر را بر روی Handlerها پیکربندی و از پیکربندی خارج می‌کنند."

msgid "Application code should not directly instantiate and use instances of :class:`Handler`.  Instead, the :class:`Handler` class is a base class that defines the interface that all handlers should have and establishes some default behavior that child classes can use (or override)."
msgstr "کد برنامه نباید مستقیماً از :class:`Handler` نمونه‌سازی کند و از نمونه‌های آن استفاده کند. در عوض، کلاس :class:`Handler` یک کلاس پایه است که رابطی را تعریف می‌کند که همه‌ی handlerها باید داشته باشند و برخی رفتارهای پیش‌فرض را تعیین می‌کند که کلاس‌های فرزند می‌توانند از آن‌ها استفاده کنند (یا آن‌ها را بازنویسی کنند)."

msgid "Formatters"
msgstr "قالب‌بندها"

msgid "Formatter objects configure the final order, structure, and contents of the log message.  Unlike the base :class:`logging.Handler` class, application code may instantiate formatter classes, although you could likely subclass the formatter if your application needs special behavior.  The constructor takes three optional arguments -- a message format string, a date format string and a style indicator."
msgstr "اشیاء قالب‌بند (Formatter) ترتیب نهایی، ساختار و محتوای پیام گزارش را پیکربندی می‌کنند. برخلاف کلاس پایه‌ی :class:`logging.Handler`، کد برنامه می‌تواند کلاس‌های قالب‌بند را نمونه‌سازی کند، هرچند اگر برنامه شما به رفتار خاصی نیاز داشته باشد، به احتمال زیاد می‌توانید یک زیرکلاس از قالب‌بند ایجاد کنید. سازنده سه آرگومان اختیاری دریافت می‌کند -- یک رشته‌ی قالب پیام، یک رشته‌ی قالب تاریخ و یک نشانگر سبک."

msgid "If there is no message format string, the default is to use the raw message.  If there is no date format string, the default date format is:"
msgstr "اگر رشته‌ی قالب پیام وجود نداشته باشد، به‌طور پیش‌فرض از پیام خام استفاده می‌شود. اگر رشته‌ی قالب تاریخ وجود نداشته باشد، قالب تاریخ پیش‌فرض عبارت است از:"

msgid "%Y-%m-%d %H:%M:%S"
msgstr "%Y-%m-%d %H:%M:%S"

msgid "with the milliseconds tacked on at the end. The ``style`` is one of ``'%'``, ``'{'``, or ``'$'``. If one of these is not specified, then ``'%'`` will be used."
msgstr "با میلی‌ثانیه‌هایی که در انتها اضافه شده‌اند. ``style`` یکی از ``'%'``، ``'{'`` یا ``'$'`` است. اگر یکی از این موارد تعیین نشده باشد، از ``'%'`` استفاده خواهد شد."

msgid "If the ``style`` is ``'%'``, the message format string uses ``%(<dictionary key>)s`` styled string substitution; the possible keys are documented in :ref:`logrecord-attributes`. If the style is ``'{'``, the message format string is assumed to be compatible with :meth:`str.format` (using keyword arguments), while if the style is ``'$'`` then the message format string should conform to what is expected by :meth:`string.Template.substitute`."
msgstr "اگر ``style`` برابر ``'%'`` باشد، رشته قالب پیام از جایگزینی رشته به‌سبک ``%(<dictionary key>)s`` استفاده می‌کند؛ کلیدهای ممکن در :ref:`logrecord-attributes` مستند شده‌اند. اگر سبک برابر ``'{'`` باشد، فرض می‌شود رشته قالب پیام با :meth:`str.format` (با استفاده از آرگومان‌های کلیدواژه‌ای) سازگار باشد، در حالی که اگر سبک برابر ``'$'`` باشد، رشته قالب پیام باید با آنچه :meth:`string.Template.substitute` انتظار دارد مطابقت داشته باشد."

msgid "Added the ``style`` parameter."
msgstr "پارامتر ``style`` اضافه شد."

msgid "The following message format string will log the time in a human-readable format, the severity of the message, and the contents of the message, in that order::"
msgstr "رشته‌ی قالب پیام زیر، زمان را در قالبی خوانا برای انسان، شدت پیام و محتوای پیام را به همین ترتیب ثبت می‌کند::"

msgid "'%(asctime)s - %(levelname)s - %(message)s'"
msgstr "'%(asctime)s - %(levelname)s - %(message)s'"

msgid "Formatters use a user-configurable function to convert the creation time of a record to a tuple. By default, :func:`time.localtime` is used; to change this for a particular formatter instance, set the ``converter`` attribute of the instance to a function with the same signature as :func:`time.localtime` or :func:`time.gmtime`. To change it for all formatters, for example if you want all logging times to be shown in GMT, set the ``converter`` attribute in the Formatter class (to ``time.gmtime`` for GMT display)."
msgstr "قالب‌بندکننده‌ها از یک تابع قابل‌پیکربندی توسط کاربر برای تبدیل زمان ایجاد یک رکورد به یک تاپل استفاده می‌کنند. به‌طور پیش‌فرض، از :func:`time.localtime` استفاده می‌شود؛ برای تغییر این موضوع برای یک نمونه‌ی خاص از قالب‌بندکننده، ویژگی ``converter`` آن نمونه را روی تابعی با همان امضای :func:`time.localtime` یا :func:`time.gmtime` تنظیم کنید. برای تغییر آن برای همه‌ی قالب‌بندکننده‌ها، برای مثال اگر می‌خواهید همه‌ی زمان‌های گزارش‌گیری به‌صورت GMT نمایش داده شوند، ویژگی ``converter`` را در کلاس Formatter تنظیم کنید (برای نمایش GMT، روی ``time.gmtime``)."

msgid "Configuring Logging"
msgstr "پیکربندی گزارش‌گیری"

msgid "Programmers can configure logging in three ways:"
msgstr "برنامه‌نویسان می‌توانند گزارش‌گیری را به سه روش پیکربندی کنند:"

msgid "Creating loggers, handlers, and formatters explicitly using Python code that calls the configuration methods listed above."
msgstr "ایجاد ثبت‌کننده‌ها، هندلرها و قالب‌بندها به‌صورت صریح با استفاده از کد پایتونی که متدهای پیکربندی فهرست‌شده در بالا را فراخوانی می‌کند."

msgid "Creating a logging config file and reading it using the :func:`fileConfig` function."
msgstr "ایجاد یک پرونده‌ی پیکربندی گزارش‌گیری و خواندن آن با استفاده از تابع :func:`fileConfig`."

msgid "Creating a dictionary of configuration information and passing it to the :func:`dictConfig` function."
msgstr "ایجاد یک دیکشنری از اطلاعات پیکربندی و ارسال آن به تابع :func:`dictConfig`."

msgid "For the reference documentation on the last two options, see :ref:`logging-config-api`.  The following example configures a very simple logger, a console handler, and a simple formatter using Python code::"
msgstr "برای مستندات مرجع در مورد دو گزینه‌ی آخر، به :ref:`logging-config-api` مراجعه کنید. مثال زیر با استفاده از کد پایتون، یک گزارش‌گیر بسیار ساده، یک هندلر کنسول (console handler) و یک قالب‌بند (formatter) ساده را پیکربندی می‌کند::"

msgid ""
"import logging\n"
"\n"
"# create logger\n"
"logger = logging.getLogger('simple_example')\n"
"logger.setLevel(logging.DEBUG)\n"
"\n"
"# create console handler and set level to debug\n"
"ch = logging.StreamHandler()\n"
"ch.setLevel(logging.DEBUG)\n"
"\n"
"# create formatter\n"
"formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')\n"
"\n"
"# add formatter to ch\n"
"ch.setFormatter(formatter)\n"
"\n"
"# add ch to logger\n"
"logger.addHandler(ch)\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"
"# create logger\n"
"logger = logging.getLogger('simple_example')\n"
"logger.setLevel(logging.DEBUG)\n"
"\n"
"# create console handler and set level to debug\n"
"ch = logging.StreamHandler()\n"
"ch.setLevel(logging.DEBUG)\n"
"\n"
"# create formatter\n"
"formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')\n"
"\n"
"# add formatter to ch\n"
"ch.setFormatter(formatter)\n"
"\n"
"# add ch to logger\n"
"logger.addHandler(ch)\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 "Running this module from the command line produces the following output:"
msgstr "اجرای این ماژول از خط فرمان، خروجی زیر را تولید می‌کند:"

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

msgid "The following Python module creates a logger, handler, and formatter nearly identical to those in the example listed above, with the only difference being the names of the objects::"
msgstr "ماژول پایتون زیر یک گزارش‌گیر، هندلر و قالب‌بند (formatter) تقریباً یکسان با موارد موجود در مثال ذکرشده در بالا ایجاد می‌کند، با این تفاوت که تنها نام اشیاء متفاوت است::"

msgid ""
"import logging\n"
"import logging.config\n"
"\n"
"logging.config.fileConfig('logging.conf')\n"
"\n"
"# create logger\n"
"logger = logging.getLogger('simpleExample')\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"
"import logging.config\n"
"\n"
"logging.config.fileConfig('logging.conf')\n"
"\n"
"# create logger\n"
"logger = logging.getLogger('simpleExample')\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 "Here is the logging.conf file:"
msgstr "در اینجا پرونده logging.conf آمده است:"

msgid ""
"[loggers]\n"
"keys=root,simpleExample\n"
"\n"
"[handlers]\n"
"keys=consoleHandler\n"
"\n"
"[formatters]\n"
"keys=simpleFormatter\n"
"\n"
"[logger_root]\n"
"level=DEBUG\n"
"handlers=consoleHandler\n"
"\n"
"[logger_simpleExample]\n"
"level=DEBUG\n"
"handlers=consoleHandler\n"
"qualname=simpleExample\n"
"propagate=0\n"
"\n"
"[handler_consoleHandler]\n"
"class=StreamHandler\n"
"level=DEBUG\n"
"formatter=simpleFormatter\n"
"args=(sys.stdout,)\n"
"\n"
"[formatter_simpleFormatter]\n"
"format=%(asctime)s - %(name)s - %(levelname)s - %(message)s"
msgstr ""
"[loggers]\n"
"keys=root,simpleExample\n"
"\n"
"[handlers]\n"
"keys=consoleHandler\n"
"\n"
"[formatters]\n"
"keys=simpleFormatter\n"
"\n"
"[logger_root]\n"
"level=DEBUG\n"
"handlers=consoleHandler\n"
"\n"
"[logger_simpleExample]\n"
"level=DEBUG\n"
"handlers=consoleHandler\n"
"qualname=simpleExample\n"
"propagate=0\n"
"\n"
"[handler_consoleHandler]\n"
"class=StreamHandler\n"
"level=DEBUG\n"
"formatter=simpleFormatter\n"
"args=(sys.stdout,)\n"
"\n"
"[formatter_simpleFormatter]\n"
"format=%(asctime)s - %(name)s - %(levelname)s - %(message)s"

msgid "The output is nearly identical to that of the non-config-file-based example:"
msgstr "خروجی تقریباً با خروجی مثال غیرمبتنی بر پرونده پیکربندی یکسان است:"

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

msgid "You can see that the config file approach has a few advantages over the Python code approach, mainly separation of configuration and code and the ability of noncoders to easily modify the logging properties."
msgstr "می‌توانید ببینید که روش پرونده پیکربندی چند مزیت نسبت به روش کد پایتون دارد، عمدتاً جداسازی پیکربندی و کد و توانایی افراد غیربرنامه‌نویس برای تغییر آسان ویژگی‌های گزارش‌گیری."

msgid "The :func:`fileConfig` function takes a default parameter, ``disable_existing_loggers``, which defaults to ``True`` for reasons of backward compatibility. This may or may not be what you want, since it will cause any non-root loggers existing before the :func:`fileConfig` call to be disabled unless they (or an ancestor) are explicitly named in the configuration. Please refer to the reference documentation for more information, and specify ``False`` for this parameter if you wish."
msgstr "تابع :func:`fileConfig` یک پارامتر پیش‌فرض به نام ``disable_existing_loggers`` دارد که به دلایل سازگاری با نسخه‌های قبلی، مقدار پیش‌فرض آن ``True`` است. این ممکن است مطابق خواسته شما باشد یا نباشد، زیرا باعث می‌شود هر گزارش‌گیر غیرریشه‌ای که پیش از فراخوانی :func:`fileConfig` وجود دارد، غیرفعال شود؛ مگر آنکه آن گزارش‌گیر (یا والد آن) به‌صراحت در پیکربندی نام برده شود. لطفاً برای اطلاعات بیشتر به مستندات مرجع مراجعه کنید و در صورت تمایل، مقدار ``False`` را برای این پارامتر مشخص کنید."

msgid "The dictionary passed to :func:`dictConfig` can also specify a Boolean value with key ``disable_existing_loggers``, which if not specified explicitly in the dictionary also defaults to being interpreted as ``True``. This leads to the logger-disabling behaviour described above, which may not be what you want - in which case, provide the key explicitly with a value of ``False``."
msgstr "دیکشنری داده‌شده به :func:`dictConfig` همچنین می‌تواند یک مقدار بولی با کلید ``disable_existing_loggers`` را مشخص کند، که اگر به‌طور صریح در دیکشنری مشخص نشده باشد، به‌صورت پیش‌فرض نیز به‌عنوان ``True`` تفسیر می‌شود. این امر به رفتار غیرفعال‌سازی گزارش‌گیرها که در بالا توضیح داده شد منجر می‌شود، که ممکن است آنچه شما می‌خواهید نباشد؛ در این صورت، کلید را به‌طور صریح با مقدار ``False`` ارائه دهید."

msgid "Note that the class names referenced in config files need to be either relative to the logging module, or absolute values which can be resolved using normal import mechanisms. Thus, you could use either :class:`~logging.handlers.WatchedFileHandler` (relative to the logging module) or ``mypackage.mymodule.MyHandler`` (for a class defined in package ``mypackage`` and module ``mymodule``, where ``mypackage`` is available on the Python import path)."
msgstr "توجه داشته باشید که نام کلاس‌های ارجاع‌شده در پرونده‌های پیکربندی باید یا نسبت به ماژول logging نسبی باشند، یا مقادیر مطلقی باشند که بتوان آن‌ها را با استفاده از سازوکارهای عادی ایمپورت حل کرد. بنابراین، می‌توانید از :class:`~logging.handlers.WatchedFileHandler` (نسبت به ماژول logging) یا ``mypackage.mymodule.MyHandler`` (برای کلاسی که در بسته‌ی ``mypackage`` و ماژول ``mymodule`` تعریف شده باشد و ``mypackage`` در مسیر ایمپورت پایتون در دسترس باشد) استفاده کنید."

msgid "In Python 3.2, a new means of configuring logging has been introduced, using dictionaries to hold configuration information. This provides a superset of the functionality of the config-file-based approach outlined above, and is the recommended configuration method for new applications and deployments. Because a Python dictionary is used to hold configuration information, and since you can populate that dictionary using different means, you have more options for configuration. For example, you can use a configuration file in JSON format, or, if you have access to YAML processing functionality, a file in YAML format, to populate the configuration dictionary. Or, of course, you can construct the dictionary in Python code, receive it in pickled form over a socket, or use whatever approach makes sense for your application."
msgstr "در پایتون 3.2، روش جدیدی برای پیکربندی گزارش‌گیری معرفی شده است که در آن از دیکشنری‌ها برای نگه‌داری اطلاعات پیکربندی استفاده می‌شود. این روش، ابرمجموعه‌ای از قابلیت‌های رویکرد مبتنی بر پرونده پیکربندیِ ذکرشده در بالا را فراهم می‌کند و روش پیکربندی توصیه‌شده برای برنامه‌ها و استقرارهای جدید است. از آنجا که از یک دیکشنری پایتون برای نگه‌داری اطلاعات پیکربندی استفاده می‌شود، و از آنجا که می‌توانید آن دیکشنری را با روش‌های مختلفی پر کنید، گزینه‌های بیشتری برای پیکربندی دارید. برای مثال، می‌توانید از یک پرونده پیکربندی در قالب JSON، یا در صورت دسترسی به قابلیت پردازش YAML، از یک پرونده در قالب YAML، برای پر کردن دیکشنری پیکربندی استفاده کنید. یا البته، می‌توانید دیکشنری را در کد پایتون بسازید، آن را به‌صورت pickled از طریق یک سوکت دریافت کنید، یا از هر رویکردی که برای برنامه شما مناسب است استفاده کنید."

msgid "Here's an example of the same configuration as above, in YAML format for the new dictionary-based approach:"
msgstr "در اینجا نمونه‌ای از همان پیکربندی بالا، در قالب YAML برای رویکرد جدید مبتنی بر دیکشنری آمده است:"

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

msgid "For more information about logging using a dictionary, see :ref:`logging-config-api`."
msgstr "برای اطلاعات بیشتر درباره‌ی گزارش‌کردن با استفاده از یک دیکشنری، :ref:`logging-config-api` را ببینید."

msgid "What happens if no configuration is provided"
msgstr "اگر هیچ پیکربندی ارائه نشود، چه اتفاقی می‌افتد"

msgid "If no logging configuration is provided, it is possible to have a situation where a logging event needs to be output, but no handlers can be found to output the event."
msgstr "اگر هیچ پیکربندی گزارش‌گیری ارائه نشده باشد، ممکن است موقعیتی پیش بیاید که یک رویداد گزارش‌گیری نیاز به خروجی داشته باشد، اما هیچ هندلری برای خروجی آن رویداد نتوان یافت."

msgid "The event is output using a 'handler of last resort', stored in :data:`lastResort`. This internal handler is not associated with any logger, and acts like a :class:`~logging.StreamHandler` which writes the event description message to the current value of ``sys.stderr`` (therefore respecting any redirections which may be in effect). No formatting is done on the message - just the bare event description message is printed. The handler's level is set to ``WARNING``, so all events at this and greater severities will be output."
msgstr "این رویداد با استفاده از یک «هندلر آخرین چاره» (handler of last resort) که در :data:`lastResort` ذخیره شده است، خروجی داده می‌شود. این هندلر داخلی به هیچ گزارش‌گیری مرتبط نیست و مانند یک :class:`~logging.StreamHandler` عمل می‌کند که پیام شرح رویداد را در مقدار فعلی ``sys.stderr`` می‌نویسد (بنابراین هرگونه تغییرمسیری را که ممکن است فعال باشد رعایت می‌کند). هیچ قالب‌بندی روی پیام انجام نمی‌شود؛ فقط پیام شرح رویداد به‌صورت خام چاپ می‌شود. سطح این هندلر روی ``WARNING`` تنظیم شده است، بنابراین همه رویدادها با این شدت و شدت‌های بیشتر خروجی داده خواهند شد."

msgid "For versions of Python prior to 3.2, the behaviour is as follows:"
msgstr "در نسخه‌های پایتون پیش از 3.2، رفتار به شرح زیر است:"

msgid "If :data:`raiseExceptions` is ``False`` (production mode), the event is silently dropped."
msgstr "اگر :data:`raiseExceptions` برابر ``False`` باشد (حالت تولید)، رویداد به‌صورت بی‌صدا حذف می‌شود."

msgid "If :data:`raiseExceptions` is ``True`` (development mode), a message 'No handlers could be found for logger X.Y.Z' is printed once."
msgstr "اگر :data:`raiseExceptions` برابر ``True`` باشد (حالت توسعه)، پیام 'No handlers could be found for logger X.Y.Z' یک بار چاپ می‌شود."

msgid "To obtain the pre-3.2 behaviour, :data:`lastResort` can be set to ``None``."
msgstr "برای به دست آوردن رفتار پیش از 3.2، می‌توان :data:`lastResort` را روی ``None`` تنظیم کرد."

msgid "Configuring Logging for a Library"
msgstr "پیکربندی گزارش برای یک کتابخانه"

msgid "When developing a library which uses logging, you should take care to document how the library uses logging - for example, the names of loggers used. Some consideration also needs to be given to its logging configuration. If the using application does not use logging, and library code makes logging calls, then (as described in the previous section) events of severity ``WARNING`` and greater will be printed to ``sys.stderr``. This is regarded as the best default behaviour."
msgstr "هنگام توسعه‌ی کتابخانه‌ای که از گزارش‌گیری استفاده می‌کند، باید دقت کنید که نحوه‌ی استفاده‌ی کتابخانه از گزارش‌گیری را مستند کنید، برای مثال، نام گزارش‌گیرهای استفاده‌شده. همچنین باید به پیکربندی گزارش‌گیری آن نیز توجه شود. اگر برنامه‌ی استفاده‌کننده از گزارش‌گیری استفاده نکند و کد کتابخانه فراخوانی‌های گزارش‌گیری انجام دهد، آنگاه (همان‌طور که در بخش قبلی توضیح داده شد) رویدادهایی با شدت ``WARNING`` و بالاتر در ``sys.stderr`` چاپ خواهند شد. این رفتار به‌عنوان بهترین رفتار پیش‌فرض در نظر گرفته می‌شود."

msgid "If for some reason you *don't* want these messages printed in the absence of any logging configuration, you can attach a do-nothing handler to the top-level logger for your library. This avoids the message being printed, since a handler will always be found for the library's events: it just doesn't produce any output. If the library user configures logging for application use, presumably that configuration will add some handlers, and if levels are suitably configured then logging calls made in library code will send output to those handlers, as normal."
msgstr "اگر به هر دلیلی *نمی‌خواهید* این پیام‌ها در نبود هرگونه پیکربندی گزارش چاپ شوند، می‌توانید یک هندلر بی‌عمل را به گزارش‌گیر سطح بالای کتابخانه‌ی خود متصل کنید. این کار از چاپ پیام جلوگیری می‌کند، زیرا همیشه برای رویدادهای کتابخانه یک هندلر پیدا خواهد شد: فقط هیچ خروجی‌ای تولید نمی‌کند. اگر کاربر کتابخانه گزارش را برای استفاده‌ی برنامه پیکربندی کند، احتمالاً آن پیکربندی چند هندلر اضافه خواهد کرد، و اگر سطوح به‌طور مناسبی پیکربندی شده باشند، فراخوانی‌های گزارش انجام‌شده در کد کتابخانه، خروجی را مانند حالت عادی به آن هندلرها ارسال خواهند کرد."

msgid "A do-nothing handler is included in the logging package: :class:`~logging.NullHandler` (since Python 3.1). An instance of this handler could be added to the top-level logger of the logging namespace used by the library (*if* you want to prevent your library's logged events being output to ``sys.stderr`` in the absence of logging configuration). If all logging by a library *foo* is done using loggers with names matching 'foo.x', 'foo.x.y', etc. then the code::"
msgstr "یک هندلر بدون عملیات در بسته‌ی logging گنجانده شده است: :class:`~logging.NullHandler` (از پایتون 3.1). می‌توان یک نمونه از این هندلر را به گزارش‌گیر سطح بالای فضای نام گزارش‌گیری مورد استفاده‌ی کتابخانه اضافه کرد (*اگر* بخواهید در نبود پیکربندی گزارش‌گیری، از نوشته شدن رویدادهای گزارش‌شده‌ی کتابخانه‌تان در ``sys.stderr`` جلوگیری کنید). اگر تمام گزارش‌گیری کتابخانه‌ی *foo* با استفاده از گزارش‌گیرهایی با نام‌های مطابق با 'foo.x'، 'foo.x.y' و غیره انجام شود، آنگاه کد::"

msgid ""
"import logging\n"
"logging.getLogger('foo').addHandler(logging.NullHandler())"
msgstr ""
"import logging\n"
"logging.getLogger('foo').addHandler(logging.NullHandler())"

msgid "should have the desired effect. If an organisation produces a number of libraries, then the logger name specified can be 'orgname.foo' rather than just 'foo'."
msgstr "باید اثر مطلوب را داشته باشد. اگر سازمانی تعدادی کتابخانه تولید کند، آنگاه نام گزارش‌گیر مشخص‌شده می‌تواند به‌جای فقط 'foo'، 'orgname.foo' باشد."

msgid "It is strongly advised that you *do not log to the root logger* in your library. Instead, use a logger with a unique and easily identifiable name, such as the ``__name__`` for your library's top-level package or module. Logging to the root logger will make it difficult or impossible for the application developer to configure the logging verbosity or handlers of your library as they wish."
msgstr "اکیداً توصیه می‌شود که در کتابخانه‌ی خود *به گزارش‌گیر ریشه گزارش نکنید*. در عوض، از گزارش‌گیری با نام یکتا و به‌راحتی قابل‌تشخیص استفاده کنید، مانند ``__name__`` برای بسته یا ماژول سطح بالای کتابخانه‌ی خود. گزارش کردن به گزارش‌گیر ریشه، پیکربندی سطح جزئیات گزارش یا handlerهای کتابخانه‌ی شما را برای توسعه‌دهنده‌ی برنامه، آن‌گونه که بخواهد دشوار یا غیرممکن می‌سازد."

msgid "It is strongly advised that you *do not add any handlers other than* :class:`~logging.NullHandler` *to your library's loggers*. This is because the configuration of handlers is the prerogative of the application developer who uses your library. The application developer knows their target audience and what handlers are most appropriate for their application: if you add handlers 'under the hood', you might well interfere with their ability to carry out unit tests and deliver logs which suit their requirements."
msgstr "اکیداً توصیه می‌شود که *هیچ هندلری به‌جز* :class:`~logging.NullHandler` *به گزارش‌گیرهای کتابخانه خود اضافه نکنید*. دلیل این امر آن است که پیکربندی هندلرها در اختیار توسعه‌دهنده‌ی برنامه‌ای است که از کتابخانه شما استفاده می‌کند. توسعه‌دهنده‌ی برنامه مخاطبان هدف و مناسب‌ترین هندلرها برای برنامه‌اش را می‌داند: اگر «در پشت صحنه» هندلرهایی اضافه کنید، ممکن است در توانایی او برای اجرای آزمون واحد‌ها و ارائه گزارش‌هایی که نیازهایش را برآورده می‌کنند، اختلال ایجاد کنید."

msgid "Logging Levels"
msgstr "سطوح گزارش"

msgid "The numeric values of logging levels are given in the following table. These are primarily of interest if you want to define your own levels, and need them to have specific values relative to the predefined levels. If you define a level with the same numeric value, it overwrites the predefined value; the predefined name is lost."
msgstr "مقادیر عددی سطوح گزارش‌گیری در جدول زیر آمده است. این مقادیر عمدتاً زمانی اهمیت دارند که بخواهید سطوح خودتان را تعریف کنید و لازم باشد که آن‌ها مقادیر مشخصی نسبت به سطوح از پیش تعریف‌شده داشته باشند. اگر سطحی با همان مقدار عددی تعریف کنید، مقدار از پیش تعریف‌شده را بازنویسی می‌کند؛ نام از پیش تعریف‌شده از بین می‌رود."

msgid "Numeric value"
msgstr "مقدار عددی"

msgid "50"
msgstr "50"

msgid "40"
msgstr "40"

msgid "30"
msgstr "30"

msgid "20"
msgstr "20"

msgid "10"
msgstr "10"

msgid "``NOTSET``"
msgstr "``NOTSET``"

msgid "0"
msgstr "0"

msgid "Levels can also be associated with loggers, being set either by the developer or through loading a saved logging configuration. When a logging method is called on a logger, the logger compares its own level with the level associated with the method call. If the logger's level is higher than the method call's, no logging message is actually generated. This is the basic mechanism controlling the verbosity of logging output."
msgstr "سطح‌ها می‌توانند به گزارش‌گیرها نیز مرتبط باشند و توسط توسعه‌دهنده یا از طریق بارگذاری یک پیکربندی گزارش‌گیری ذخیره‌شده تنظیم شوند. هنگامی که یک متد گزارش‌گیری روی یک گزارش‌گیر فراخوانی می‌شود، گزارش‌گیر سطح خود را با سطح مرتبط با فراخوانی متد مقایسه می‌کند. اگر سطح گزارش‌گیر بالاتر از سطح فراخوانی متد باشد، در عمل هیچ پیام گزارش‌گیریی تولید نمی‌شود. این مکانیزم اساسی کنترل پرگویی خروجی گزارش‌گیری است."

msgid "Logging messages are encoded as instances of the :class:`~logging.LogRecord` class. When a logger decides to actually log an event, a :class:`~logging.LogRecord` instance is created from the logging message."
msgstr "پیام‌های ثبت رویداد به‌صورت نمونه‌هایی از کلاس :class:`~logging.LogRecord` کدگذاری می‌شوند. هنگامی که یک گزارش‌گیر تصمیم می‌گیرد واقعاً رویدادی را ثبت کند، نمونه‌ای از :class:`~logging.LogRecord` بر اساس پیام ثبت رویداد ایجاد می‌شود."

msgid "Logging messages are subjected to a dispatch mechanism through the use of :dfn:`handlers`, which are instances of subclasses of the :class:`Handler` class. Handlers are responsible for ensuring that a logged message (in the form of a :class:`LogRecord`) ends up in a particular location (or set of locations) which is useful for the target audience for that message (such as end users, support desk staff, system administrators, developers). Handlers are passed :class:`LogRecord` instances intended for particular destinations. Each logger can have zero, one or more handlers associated with it (via the :meth:`~Logger.addHandler` method of :class:`Logger`). In addition to any handlers directly associated with a logger, *all handlers associated with all ancestors of the logger* are called to dispatch the message (unless the *propagate* flag for a logger is set to a false value, at which point the passing to ancestor handlers stops)."
msgstr "پیام‌های گزارش با استفاده از :dfn:`handlers` تحت یک سازوکار توزیع قرار می‌گیرند؛ هندلرها نمونه‌هایی از زیرکلاس‌های کلاس :class:`Handler` هستند. هندلرها مسئول اطمینان از این هستند که پیام گزارش‌شده (در قالب :class:`LogRecord`) در مکان خاصی (یا مجموعه‌ای از مکان‌ها) قرار گیرد که برای مخاطبان هدف آن پیام مفید باشد (مانند کاربران نهایی، کارکنان میز پشتیبانی، مدیران سیستم، توسعه‌دهندگان). نمونه‌های :class:`LogRecord` که برای مقاصد خاصی در نظر گرفته شده‌اند، به هندلرها ارسال می‌شوند. هر گزارش‌گیر می‌تواند صفر، یک یا چند هندلر مرتبط با خود داشته باشد (از طریق متد :meth:`~Logger.addHandler` کلاس :class:`Logger`). علاوه بر هر هندلری که مستقیماً با یک گزارش‌گیر مرتبط است، *تمام هندلرهای مرتبط با تمام اجداد آن گزارش‌گیر* برای توزیع پیام فراخوانی می‌شوند (مگر اینکه پرچم *propagate* برای یک گزارش‌گیر روی مقدار نادرست تنظیم شده باشد، که در آن حالت، ارسال به هندلرهای اجداد متوقف می‌شود)."

msgid "Just as for loggers, handlers can have levels associated with them. A handler's level acts as a filter in the same way as a logger's level does. If a handler decides to actually dispatch an event, the :meth:`~Handler.emit` method is used to send the message to its destination. Most user-defined subclasses of :class:`Handler` will need to override this :meth:`~Handler.emit`."
msgstr "همانند گزارش‌گیرها، هندلرها نیز می‌توانند سطح‌هایی مرتبط با خود داشته باشند. سطح یک هندلر نیز همانند سطح یک گزارش‌گیر به‌عنوان یک فیلتر عمل می‌کند. اگر یک هندلر تصمیم بگیرد واقعاً رویدادی را ارسال کند، از متد :meth:`~Handler.emit` برای فرستادن پیام به مقصد آن استفاده می‌شود. بیشتر زیرکلاس‌های :class:`Handler` که توسط کاربر تعریف شده‌اند، نیاز خواهند داشت که این متد :meth:`~Handler.emit` را بازنویسی کنند."

msgid "Custom Levels"
msgstr "سطوح سفارشی"

msgid "Defining your own levels is possible, but should not be necessary, as the existing levels have been chosen on the basis of practical experience. However, if you are convinced that you need custom levels, great care should be exercised when doing this, and it is possibly *a very bad idea to define custom levels if you are developing a library*. That's because if multiple library authors all define their own custom levels, there is a chance that the logging output from such multiple libraries used together will be difficult for the using developer to control and/or interpret, because a given numeric value might mean different things for different libraries."
msgstr "تعریف سطوح خودتان ممکن است، اما نباید ضروری باشد، زیرا سطوح موجود بر اساس تجربه عملی انتخاب شده‌اند. با این حال، اگر متقاعد شده‌اید که به سطوح سفارشی نیاز دارید، باید هنگام انجام این کار بسیار احتیاط کنید، و ممکن است *تعریف سطوح سفارشی در صورتی که در حال توسعه‌ی یک کتابخانه هستید، ایده بسیار بدی باشد*. این به آن دلیل است که اگر چندین نویسنده کتابخانه همگی سطوح سفارشی خود را تعریف کنند، این احتمال وجود دارد که کنترل و/یا تفسیر خروجی گزارش‌گیری  چنین کتابخانه‌هایی که با هم استفاده می‌شوند، برای توسعه‌دهنده استفاده‌کننده دشوار باشد، زیرا یک مقدار عددی معین ممکن است برای کتابخانه‌های مختلف معانی متفاوتی داشته باشد."

msgid "Useful Handlers"
msgstr "هندلرهای مفید"

msgid "In addition to the base :class:`Handler` class, many useful subclasses are provided:"
msgstr "علاوه بر کلاس پایه :class:`Handler`، زیرکلاس‌های مفید زیادی ارائه شده‌اند:"

msgid ":class:`StreamHandler` instances send messages to streams (file-like objects)."
msgstr "نمونه‌های :class:`StreamHandler` پیام‌ها را به جریان‌ها (اشیاء شبه‌پرونده) ارسال می‌کنند."

msgid ":class:`FileHandler` instances send messages to disk files."
msgstr "نمونه‌های :class:`FileHandler` پیام‌ها را به پرونده‌های دیسک ارسال می‌کنند."

msgid ":class:`~handlers.BaseRotatingHandler` is the base class for handlers that rotate log files at a certain point. It is not meant to be  instantiated directly. Instead, use :class:`~handlers.RotatingFileHandler` or :class:`~handlers.TimedRotatingFileHandler`."
msgstr ":class:`~handlers.BaseRotatingHandler` کلاس پایه برای هندلرهایی است که پرونده‌های گزارش را در نقطه‌ای معین می‌چرخانند. این کلاس برای نمونه‌سازی مستقیم در نظر گرفته نشده است. در عوض، از :class:`~handlers.RotatingFileHandler` یا :class:`~handlers.TimedRotatingFileHandler` استفاده کنید."

msgid ":class:`~handlers.RotatingFileHandler` instances send messages to disk files, with support for maximum log file sizes and log file rotation."
msgstr "نمونه‌های :class:`~handlers.RotatingFileHandler` پیام‌ها را به پرونده‌های دیسک ارسال می‌کنند و از حداکثر اندازه پرونده‌های گزارش و چرخش پرونده گزارش پشتیبانی می‌کنند."

msgid ":class:`~handlers.TimedRotatingFileHandler` instances send messages to disk files, rotating the log file at certain timed intervals."
msgstr "نمونه‌های :class:`~handlers.TimedRotatingFileHandler` پیام‌ها را به پرونده‌های دیسک ارسال می‌کنند و پرونده گزارش را در بازه‌های زمانی مشخصی می‌چرخانند."

msgid ":class:`~handlers.SocketHandler` instances send messages to TCP/IP sockets. Since 3.4, Unix domain sockets are also supported."
msgstr "نمونه‌های :class:`~handlers.SocketHandler` پیام‌ها را به سوکت‌های TCP/IP ارسال می‌کنند. از نسخه 3.4، از سوکت‌های دامنه یونیکس (Unix domain sockets) نیز پشتیبانی می‌شود."

msgid ":class:`~handlers.DatagramHandler` instances send messages to UDP sockets. Since 3.4, Unix domain sockets are also supported."
msgstr "نمونه‌های :class:`~handlers.DatagramHandler` پیام‌ها را به سوکت‌های UDP ارسال می‌کنند. از 3.4، سوکت‌های دامنه یونیکس نیز پشتیبانی می‌شوند."

msgid ":class:`~handlers.SMTPHandler` instances send messages to a designated email address."
msgstr "نمونه‌های :class:`~handlers.SMTPHandler` پیام‌ها را به یک نشانی ایمیل تعیین‌شده ارسال می‌کنند."

msgid ":class:`~handlers.SysLogHandler` instances send messages to a Unix syslog daemon, possibly on a remote machine."
msgstr "نمونه‌های :class:`~handlers.SysLogHandler` پیام‌ها را به یک دیمون syslog در یونیکس ارسال می‌کنند، احتمالاً روی یک ماشین راه دور."

msgid ":class:`~handlers.NTEventLogHandler` instances send messages to a Windows NT/2000/XP event log."
msgstr "نمونه‌های :class:`~handlers.NTEventLogHandler` پیام‌ها را به گزارش رویداد ویندوز NT/2000/XP ارسال می‌کنند."

msgid ":class:`~handlers.MemoryHandler` instances send messages to a buffer in memory, which is flushed whenever specific criteria are met."
msgstr "نمونه‌های :class:`~handlers.MemoryHandler` پیام‌ها را به بافری در حافظه ارسال می‌کنند که هر زمان معیارهای خاصی برآورده شوند، تخلیه می‌شود."

msgid ":class:`~handlers.HTTPHandler` instances send messages to an HTTP server using either ``GET`` or ``POST`` semantics."
msgstr "نمونه‌های :class:`~handlers.HTTPHandler` پیام‌ها را با استفاده از معنای ``GET`` یا ``POST`` به یک سرور HTTP ارسال می‌کنند."

msgid ":class:`~handlers.WatchedFileHandler` instances watch the file they are logging to. If the file changes, it is closed and reopened using the file name. This handler is only useful on Unix-like systems; Windows does not support the underlying mechanism used."
msgstr "نمونه‌های :class:`~handlers.WatchedFileHandler` پرونده‌ای را که در آن گزارش می‌کنند، پایش می‌کنند. اگر پرونده تغییر کند، بسته می‌شود و با استفاده از نام پرونده دوباره باز می‌شود. این هندلر فقط در سیستم‌های شبه‌یونیکس مفید است؛ ویندوز از سازوکار زیربنایی مورد استفاده پشتیبانی نمی‌کند."

msgid ":class:`~handlers.QueueHandler` instances send messages to a queue, such as those implemented in the :mod:`queue` or :mod:`multiprocessing` modules."
msgstr "نمونه‌های :class:`~handlers.QueueHandler` پیام‌ها را به یک صف ارسال می‌کنند، مانند صف‌هایی که در ماژول‌های :mod:`queue` یا :mod:`multiprocessing` پیاده‌سازی شده‌اند."

msgid ":class:`NullHandler` instances do nothing with error messages. They are used by library developers who want to use logging, but want to avoid the 'No handlers could be found for logger *XXX*' message which can be displayed if the library user has not configured logging. See :ref:`library-config` for more information."
msgstr "نمونه‌های :class:`NullHandler` هیچ کاری با پیام‌های خطا انجام نمی‌دهند. توسعه‌دهندگان کتابخانه‌ها که می‌خواهند از گزارش‌گیری استفاده کنند، اما می‌خواهند از پیام «No handlers could be found for logger *XXX*» اجتناب کنند، از این نمونه‌ها استفاده می‌کنند؛ پیامی که ممکن است در صورتی که کاربر کتابخانه گزارش‌گیری را پیکربندی نکرده باشد، نمایش داده شود. برای اطلاعات بیشتر :ref:`library-config` را ببینید."

msgid "The :class:`NullHandler` class."
msgstr "کلاس :class:`NullHandler`."

msgid "The :class:`~handlers.QueueHandler` class."
msgstr "کلاس :class:`~handlers.QueueHandler`."

msgid "The :class:`NullHandler`, :class:`StreamHandler` and :class:`FileHandler` classes are defined in the core logging package. The other handlers are defined in a sub-module, :mod:`logging.handlers`. (There is also another sub-module, :mod:`logging.config`, for configuration functionality.)"
msgstr "کلاس‌های :class:`NullHandler`، :class:`StreamHandler` و :class:`FileHandler` در بسته‌ی اصلی logging تعریف شده‌اند. سایر هندلرها در یک زیرماژول، :mod:`logging.handlers` تعریف شده‌اند. (همچنین زیرماژول دیگری، :mod:`logging.config`، برای قابلیت پیکربندی وجود دارد.)"

msgid "Logged messages are formatted for presentation through instances of the :class:`Formatter` class. They are initialized with a format string suitable for use with the % operator and a dictionary."
msgstr "پیام‌های ثبت‌شده برای نمایش از طریق نمونه‌هایی از کلاس :class:`Formatter` قالب‌بندی می‌شوند. آن‌ها با یک رشته قالب مناسب برای استفاده با عملگر % و یک دیکشنری مقداردهی اولیه می‌شوند."

msgid "For formatting multiple messages in a batch, instances of :class:`BufferingFormatter` can be used. In addition to the format string (which is applied to each message in the batch), there is provision for header and trailer format strings."
msgstr "برای قالب‌بندی چندین پیام در یک دسته، می‌توان از نمونه‌های :class:`BufferingFormatter` استفاده کرد. علاوه بر رشته‌ی قالب (که به هر پیام در دسته اعمال می‌شود)، امکانی برای رشته‌های قالب سرآیند و پایانی وجود دارد."

msgid "When filtering based on logger level and/or handler level is not enough, instances of :class:`Filter` can be added to both :class:`Logger` and :class:`Handler` instances (through their :meth:`~Handler.addFilter` method). Before deciding to process a message further, both loggers and handlers consult all their filters for permission. If any filter returns a false value, the message is not processed further."
msgstr "هنگامی که فیلتر کردن بر اساس سطح logger و/یا سطح handler کافی نباشد، می‌توان نمونه‌هایی از :class:`Filter` را به هر دو نمونه‌ی :class:`Logger` و :class:`Handler` اضافه کرد (از طریق متد :meth:`~Handler.addFilter` آن‌ها). پیش از تصمیم به ادامه‌ی پردازش یک پیام، logger و handler هر دو برای کسب اجازه تمام فیلترهای خود را بررسی می‌کنند. اگر هر یک از فیلترها مقدار نادرستی برگرداند، پیام بیش از این پردازش نمی‌شود."

msgid "The basic :class:`Filter` functionality allows filtering by specific logger name. If this feature is used, messages sent to the named logger and its children are allowed through the filter, and all others dropped."
msgstr "قابلیت پایه‌ای :class:`Filter` امکان فیلتر کردن بر اساس نام گزارش‌گیر مشخص را فراهم می‌کند. اگر از این قابلیت استفاده شود، پیام‌های ارسال‌شده به گزارش‌گیر نام‌برده و فرزندان آن از فیلتر عبور داده می‌شوند و تمام پیام‌های دیگر حذف می‌شوند."

msgid "Exceptions raised during logging"
msgstr "استثناهای پرتاب‌شده هنگام گزارش کردن"

msgid "The logging package is designed to swallow exceptions which occur while logging in production. This is so that errors which occur while handling logging events - such as logging misconfiguration, network or other similar errors - do not cause the application using logging to terminate prematurely."
msgstr "بسته‌ی گزارش‌گیری به‌گونه‌ای طراحی شده است که استثناهایی را که هنگام گزارش‌گیری در محیط عملیاتی رخ می‌دهند، ببلعد. این برای آن است که خطاهایی که هنگام مدیریت رویدادهای گزارش‌گیری رخ می‌دهند — مانند پیکربندی نادرست گزارش‌گیری، خطاهای شبکه یا دیگر خطاهای مشابه — باعث خاتمه‌ی زودهنگام برنامه‌ی کاربردی‌ای که از گزارش‌گیری استفاده می‌کند، نشوند."

msgid ":class:`SystemExit` and :class:`KeyboardInterrupt` exceptions are never swallowed. Other exceptions which occur during the :meth:`~Handler.emit` method of a :class:`Handler` subclass are passed to its :meth:`~Handler.handleError` method."
msgstr "استثناهای :class:`SystemExit` و :class:`KeyboardInterrupt` هرگز نادیده گرفته نمی‌شوند. سایر استثناهایی که در حین اجرای متد :meth:`~Handler.emit` یک کلاس فرعی از :class:`Handler` رخ می‌دهند، به متد :meth:`~Handler.handleError` آن ارسال می‌شوند."

msgid "The default implementation of :meth:`~Handler.handleError` in :class:`Handler` checks to see if a module-level variable, :data:`raiseExceptions`, is set. If set, a traceback is printed to :data:`sys.stderr`. If not set, the exception is swallowed."
msgstr "پیاده‌سازی پیش‌فرض :meth:`~Handler.handleError` در :class:`Handler` بررسی می‌کند که آیا یک متغیر سطح ماژول به نام :data:`raiseExceptions` تنظیم شده است یا خیر. اگر تنظیم شده باشد، یک ردگیری پشته در :data:`sys.stderr` چاپ می‌شود. اگر تنظیم نشده باشد، استثنا نادیده گرفته می‌شود."

msgid "The default value of :data:`raiseExceptions` is ``True``. This is because during development, you typically want to be notified of any exceptions that occur. It's advised that you set :data:`raiseExceptions` to ``False`` for production usage."
msgstr "مقدار پیش‌فرض :data:`raiseExceptions` برابر ``True`` است. این به این دلیل است که در طول توسعه، معمولاً می‌خواهید از هر استثنایی که رخ می‌دهد مطلع شوید. توصیه می‌شود برای استفاده در محیط عملیاتی، :data:`raiseExceptions` را روی ``False`` تنظیم کنید."

msgid "Using arbitrary objects as messages"
msgstr "استفاده از اشیاء دلخواه به‌عنوان پیام"

msgid "In the preceding sections and examples, it has been assumed that the message passed when logging the event is a string. However, this is not the only possibility. You can pass an arbitrary object as a message, and its :meth:`~object.__str__` method will be called when the logging system needs to convert it to a string representation. In fact, if you want to, you can avoid computing a string representation altogether - for example, the :class:`~handlers.SocketHandler` emits an event by pickling it and sending it over the wire."
msgstr "در بخش‌ها و مثال‌های پیشین، فرض بر این بوده است که پیامی که هنگام ثبت رویداد ارسال می‌شود، یک رشته است. با این حال، این تنها حالت ممکن نیست. شما می‌توانید یک شیء دلخواه را به‌عنوان پیام ارسال کنید، و هنگامی که سیستم ثبت رویداد نیاز داشته باشد آن را به یک بازنمایی رشته‌ای تبدیل کند، متد :meth:`~object.__str__` آن فراخوانی خواهد شد. در واقع، اگر بخواهید، می‌توانید به‌طور کامل از محاسبه‌ی بازنمایی رشته‌ای اجتناب کنید — برای مثال، :class:`~handlers.SocketHandler` یک رویداد را با پیکل‌کردن آن و ارسال آن از طریق شبکه منتشر می‌کند."

msgid "Optimization"
msgstr "بهینه‌سازی"

msgid "Formatting of message arguments is deferred until it cannot be avoided. However, computing the arguments passed to the logging method can also be expensive, and you may want to avoid doing it if the logger will just throw away your event. To decide what to do, you can call the :meth:`~Logger.isEnabledFor` method which takes a level argument and returns true if the event would be created by the Logger for that level of call. You can write code like this::"
msgstr "قالب‌بندی آرگومان‌های پیام تا زمانی که نتوان از آن اجتناب کرد، به تعویق می‌افتد. با این حال، محاسبه آرگومان‌هایی که به متد گزارش‌کردن ارسال می‌شوند نیز می‌تواند پرهزینه باشد، و ممکن است بخواهید از انجام آن اجتناب کنید اگر گزارش‌گیر قرار باشد صرفاً رویداد شما را دور بیندازد. برای تصمیم‌گیری درباره اینکه چه کاری انجام دهید، می‌توانید متد :meth:`~Logger.isEnabledFor` را فراخوانی کنید که یک آرگومان سطح می‌گیرد و در صورتی مقدار true را برمی‌گرداند که رویداد برای آن سطح از فراخوانی توسط Logger ایجاد شود. می‌توانید کدی مانند زیر بنویسید::"

msgid ""
"if logger.isEnabledFor(logging.DEBUG):\n"
"    logger.debug('Message with %s, %s', expensive_func1(),\n"
"                                        expensive_func2())"
msgstr ""
"if logger.isEnabledFor(logging.DEBUG):\n"
"    logger.debug('Message with %s, %s', expensive_func1(),\n"
"                                        expensive_func2())"

msgid "so that if the logger's threshold is set above ``DEBUG``, the calls to ``expensive_func1`` and ``expensive_func2`` are never made."
msgstr "به‌گونه‌ای که اگر آستانه‌ی گزارش‌گیر بالاتر از ``DEBUG`` تنظیم شده باشد، فراخوانی‌های ``expensive_func1`` و ``expensive_func2`` هرگز انجام نمی‌شوند."

msgid "In some cases, :meth:`~Logger.isEnabledFor` can itself be more expensive than you'd like (e.g. for deeply nested loggers where an explicit level is only set high up in the logger hierarchy). In such cases (or if you want to avoid calling a method in tight loops), you can cache the result of a call to :meth:`~Logger.isEnabledFor` in a local or instance variable, and use that instead of calling the method each time. Such a cached value would only need to be recomputed when the logging configuration changes dynamically while the application is running (which is not all that common)."
msgstr "در برخی موارد، خود :meth:`~Logger.isEnabledFor` می‌تواند پرهزینه‌تر از آن باشد که مایلید (برای مثال، برای گزارش‌گیرهای عمیقاً تودرتو که در آن‌ها یک سطح صریح فقط در سطوح بالای سلسله‌مراتب گزارش‌گیرها تنظیم شده است). در چنین مواردی (یا اگر می‌خواهید از فراخوانی یک متد در حلقه‌های فشرده اجتناب کنید)، می‌توانید نتیجه‌ی فراخوانی :meth:`~Logger.isEnabledFor` را در یک متغیر محلی یا نمونه به‌عنوان نهانگاه ذخیره کنید و به‌جای فراخوانی متد در هر بار، از آن استفاده کنید. چنین مقدار نهان‌شده‌ای تنها زمانی نیاز به بازمحاسبه دارد که پیکربندی گزارش‌گیری در حین اجرای برنامه به‌صورت پویا تغییر کند (که چندان رایج نیست)."

msgid "There are other optimizations which can be made for specific applications which need more precise control over what logging information is collected. Here's a list of things you can do to avoid processing during logging which you don't need:"
msgstr "برای برنامه‌های کاربردی خاصی که به کنترل دقیق‌تری بر اطلاعات گزارش جمع‌آوری‌شده نیاز دارند، می‌توان بهینه‌سازی‌های دیگری نیز انجام داد. در اینجا فهرستی از کارهایی آمده است که می‌توانید برای اجتناب از پردازش‌هایی که در حین گزارش کردن به آن‌ها نیاز ندارید، انجام دهید:"

msgid "What you don't want to collect"
msgstr "آنچه نمی‌خواهید جمع‌آوری شود"

msgid "How to avoid collecting it"
msgstr "چگونه از زباله‌روبی آن اجتناب کنیم"

msgid "Information about where calls were made from."
msgstr "اطلاعات درباره‌ی این که فراخوانی‌ها از کجا انجام شده‌اند."

msgid "Set ``logging._srcfile`` to ``None``. This avoids calling :func:`sys._getframe`, which may help to speed up your code in environments like PyPy (which can't speed up code that uses :func:`sys._getframe`)."
msgstr "``logging._srcfile`` را روی ``None`` تنظیم کنید. این کار از فراخوانی :func:`sys._getframe` جلوگیری می‌کند، که ممکن است به افزایش سرعت کد شما در محیط‌هایی مانند PyPy کمک کند (که نمی‌تواند سرعت کدی را که از :func:`sys._getframe` استفاده می‌کند افزایش دهد)."

msgid "Threading information."
msgstr "اطلاعات نخ‌بندی."

msgid "Set ``logging.logThreads`` to ``False``."
msgstr "``logging.logThreads`` را روی ``False`` تنظیم کنید."

msgid "Current process ID (:func:`os.getpid`)"
msgstr "شناسه فرایند جاری (:func:`os.getpid`)"

msgid "Set ``logging.logProcesses`` to ``False``."
msgstr "``logging.logProcesses`` را روی ``False`` تنظیم کنید."

msgid "Current process name when using ``multiprocessing`` to manage multiple processes."
msgstr "نام فرایند فعلی هنگام استفاده از ``multiprocessing`` برای مدیریت چندین فرایند."

msgid "Set ``logging.logMultiprocessing`` to ``False``."
msgstr "``logging.logMultiprocessing`` را روی ``False`` تنظیم کنید."

msgid "Current :class:`asyncio.Task` name when using ``asyncio``."
msgstr "نام فعلی :class:`asyncio.Task` هنگام استفاده از ``asyncio``."

msgid "Set ``logging.logAsyncioTasks`` to ``False``."
msgstr "``logging.logAsyncioTasks`` را روی ``False`` تنظیم کنید."

msgid "Also note that the core logging module only includes the basic handlers. If you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't take up any memory."
msgstr "همچنین توجه داشته باشید که ماژول اصلی logging فقط شامل هندلرهای پایه  است. اگر :mod:`logging.handlers` و :mod:`logging.config` را ایمپورت نکنید، آن‌ها هیچ حافظه‌ای را اشغال نخواهند کرد."

msgid "Other resources"
msgstr "منابع دیگر"

msgid "Module :mod:`logging`"
msgstr "ماژول :mod:`logging`"

msgid "API reference for the logging module."
msgstr "مرجع API برای ماژول logging."

msgid "Module :mod:`logging.config`"
msgstr "ماژول :mod:`logging.config`"

msgid "Configuration API for the logging module."
msgstr "API پیکربندی برای ماژول logging."

msgid "Module :mod:`logging.handlers`"
msgstr "ماژول :mod:`logging.handlers`"

msgid "Useful handlers included with the logging module."
msgstr "هندلرهای مفید موجود در ماژول logging."

msgid ":ref:`A logging cookbook <logging-cookbook>`"
msgstr ":ref:`کتابچه آشپزی ثبت رویداد <logging-cookbook>`"