"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 ""

msgstr ""

msgid "Here is the auxiliary module::"

msgstr "در اینجا ماژول کمکی آمده است::"

msgid ""

msgstr ""

msgid "The output looks like this:"

msgstr "خروجی به این شکل است:"

msgid ""

msgstr ""

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 ""

msgstr ""

msgid "When run, the script should print something like the following:"

msgstr "هنگام اجرا، اسکریپت باید چیزی شبیه به مورد زیر چاپ کند:"

msgid ""

msgstr ""

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 ""

msgstr ""

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 ""

msgstr ""

msgid "When you run this, on the console you will see"

msgstr "هنگامی که این را اجرا می‌کنید، در کنسول خواهید دید"

msgid ""

msgstr ""

msgid "and in the file you will see something like"

msgstr "و در پرونده چیزی شبیه به این خواهید دید"

msgid ""

msgstr ""

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 ""

msgstr ""

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 ""

msgstr ""

msgid "and changing the section on the ``stdout`` handler to add it:"

msgstr "و تغییر بخش مربوط به هندلر ``stdout`` برای افزودن آن:"

msgid ""

msgstr ""

msgid "A filter is just a function, so we can define the ``filter_maker`` (a factory function) as follows:"

msgstr "یک فیلتر فقط یک تابع است، بنابراین می‌توانیم ``filter_maker`` (یک تابع کارخانه) را به‌صورت زیر تعریف کنیم:"

msgid ""

msgstr ""

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 ""

msgstr ""

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 ""

msgstr ""

msgid "Configuration server example"

msgstr "مثال سرور پیکربندی"

msgid "Here is an example of a module using the logging configuration server::"

msgstr "در اینجا نمونه‌ای از یک ماژول که از سرور پیکربندی گزارش‌گیری (logging configuration server) استفاده می‌کند، آمده است::"

msgid ""

msgstr ""

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 ""

msgstr ""

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 ""

msgstr ""

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 ""

msgstr ""

msgid "Sending and receiving logging events across a network"

msgstr "ارسال و دریافت رویدادهای گزارش در سراسر شبکه"