isolating-extensions.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 13:04+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 "Isolating Extension Modules"
msgstr "جداسازی ماژول‌های توسعه"

msgid "Abstract"
msgstr "چکیده"

msgid "Traditionally, state belonging to Python extension modules was kept in C ``static`` variables, which have process-wide scope. This document describes problems of such per-process state and shows a safer way: per-module state."
msgstr "به‌طور سنتی، وضعیت متعلق به ماژول‌های توسعه‌ای پایتون در متغیرهای ``static`` زبان C نگهداری می‌شد که محدوده‌ای در سطح کل فرایند دارند. این سند مشکلات چنین وضعیت به‌ازای هر فرایند را توضیح می‌دهد و روش امن‌تری را نشان می‌دهد: وضعیت به‌ازای هر ماژول."

msgid "The document also describes how to switch to per-module state where possible. This transition involves allocating space for that state, potentially switching from static types to heap types, and—perhaps most importantly—accessing per-module state from code."
msgstr "این سند همچنین نحوه‌ی تغییر به وضعیت به‌ازای هر ماژول را در صورت امکان توصیف می‌کند. این گذار شامل تخصیص فضا برای آن وضعیت، احتمالاً تغییر از انواع ایستا به انواع heap، و—شاید مهم‌تر از همه—دسترسی به وضعیت به‌ازای هر ماژول از کد است."

msgid "Who should read this"
msgstr "چه کسانی باید این را بخوانند"

msgid "This guide is written for maintainers of :ref:`C-API <c-api-index>` extensions who would like to make that extension safer to use in applications where Python itself is used as a library."
msgstr "این راهنما برای نگهدارندگان افزونه‌های :ref:`C-API <c-api-index>` نوشته شده است که می‌خواهند استفاده از آن افزونه را در برنامه‌هایی که خود پایتون به‌عنوان کتابخانه استفاده می‌شود، ایمن‌تر کنند."

msgid "Background"
msgstr "پیش‌زمینه"

msgid "An *interpreter* is the context in which Python code runs. It contains configuration (e.g. the import path) and runtime state (e.g. the set of imported modules)."
msgstr "یک *مفسر* زمینه‌ای است که کد پایتون در آن اجرا می‌شود. این شامل پیکربندی (برای مثال مسیر ایمپورت) و وضعیت ران‌تایم (برای مثال مجموعه ماژول‌های ایمپورت‌شده) است."

msgid "Python supports running multiple interpreters in one process. There are two cases to think about—users may run interpreters:"
msgstr "پایتون از اجرای چندین مفسر در یک فرایند پشتیبانی می‌کند. دو حالت برای در نظر گرفتن وجود دارد—ممکن است کاربران مفسرها را اجرا کنند:"

msgid "in sequence, with several :c:func:`Py_InitializeEx`/:c:func:`Py_FinalizeEx` cycles, and"
msgstr "به‌صورت متوالی، با چندین چرخه‌ی :c:func:`Py_InitializeEx`/:c:func:`Py_FinalizeEx`، و"

msgid "in parallel, managing \"sub-interpreters\" using :c:func:`Py_NewInterpreter`/:c:func:`Py_EndInterpreter`."
msgstr "به‌صورت موازی، مدیریت «زیرمفسرها» با استفاده از :c:func:`Py_NewInterpreter`/:c:func:`Py_EndInterpreter`."

msgid "Both cases (and combinations of them) would be most useful when embedding Python within a library. Libraries generally shouldn't make assumptions about the application that uses them, which include assuming a process-wide \"main Python interpreter\"."
msgstr "هر دو حالت (و ترکیب‌های آن‌ها) بیشترین کاربرد را هنگام تعبیه پایتون در یک کتابخانه خواهند داشت. کتابخانه‌ها عموماً نباید درباره‌ی برنامه‌ای که از آن‌ها استفاده می‌کند فرض‌هایی داشته باشند؛ از جمله فرض وجود یک «مفسر اصلی پایتون» در سطح کل فرایند."

msgid "Historically, Python extension modules don't handle this use case well. Many extension modules (and even some stdlib modules) use *per-process* global state, because C ``static`` variables are extremely easy to use. Thus, data that should be specific to an interpreter ends up being shared between interpreters. Unless the extension developer is careful, it is very easy to introduce edge cases that lead to crashes when a module is loaded in more than one interpreter in the same process."
msgstr "از نظر تاریخی، ماژول‌های توسعه پایتون این مورد استفاده را به‌خوبی مدیریت نمی‌کنند. بسیاری از ماژول‌های توسعه (و حتی برخی ماژول‌های stdlib) از وضعیت سراسری *به‌ازای هر فرایند* استفاده می‌کنند، زیرا استفاده از متغیرهای ``static`` در C بسیار آسان است. در نتیجه، داده‌هایی که باید مختص به یک مفسر باشند، در نهایت بین مفسرها مشترک می‌شوند. مگر اینکه توسعه‌دهنده ماژول توسعه محتاط باشد، ایجاد حالت‌های مرزی که منجر به فروپاشی می‌شوند، هنگامی که یک ماژول در بیش از یک مفسر در همان فرایند بارگذاری می‌شود، بسیار آسان است."

msgid "Unfortunately, *per-interpreter* state is not easy to achieve. Extension authors tend to not keep multiple interpreters in mind when developing, and it is currently cumbersome to test the behavior."
msgstr "متأسفانه، وضعیت *به‌ازای هر مفسر* به‌آسانی قابل دستیابی نیست. نویسندگان افزونه‌ها معمولاً هنگام توسعه، چندین مفسر را در نظر نمی‌گیرند و آزمایش این رفتار در حال حاضر دشوار است."

msgid "Enter Per-Module State"
msgstr "ورود به وضعیت هر ماژول"

msgid "Instead of focusing on per-interpreter state, Python's C API is evolving to better support the more granular *per-module* state. This means that C-level data should be attached to a *module object*. Each interpreter creates its own module object, keeping the data separate. For testing the isolation, multiple module objects corresponding to a single extension can even be loaded in a single interpreter."
msgstr "به جای تمرکز بر وضعیت به‌ازای هر مفسر، C API پایتون در حال تکامل است تا از وضعیت ریزدانه‌ترِ *به‌ازای هر ماژول* بهتر پشتیبانی کند. این بدان معناست که داده‌های سطح C باید به یک *شیء ماژول* متصل شوند. هر مفسر شیء ماژول خود را ایجاد می‌کند و داده‌ها را جدا نگه می‌دارد. برای آزمایش جداسازی، حتی می‌توان چندین شیء ماژول متناظر با یک افزونه را در یک مفسر واحد بارگذاری کرد."

msgid "Per-module state provides an easy way to think about lifetime and resource ownership: the extension module will initialize when a module object is created, and clean up when it's freed. In this regard, a module is just like any other :c:expr:`PyObject *`; there are no \"on interpreter shutdown\" hooks to think—or forget—about."
msgstr "وضعیت به‌ازای هر ماژول، راه ساده‌ای برای فکر کردن درباره طول عمر و مالکیت منابع فراهم می‌کند: ماژول توسعه‌ای در زمان ایجاد یک شیء ماژول، مقداردهی اولیه می‌شود و در زمان آزاد شدن، پاک‌سازی می‌شود. از این نظر، یک ماژول دقیقاً مانند هر :c:expr:`PyObject *` دیگری است؛ هیچ قلابیبرای «خاموش شدن مفسر» وجود ندارد که بخواهید درباره آن فکر کنید—یا آن را فراموش کنید."

msgid "Note that there are use cases for different kinds of \"globals\": per-process, per-interpreter, per-thread or per-task state. With per-module state as the default, these are still possible, but you should treat them as exceptional cases: if you need them, you should give them additional care and testing. (Note that this guide does not cover them.)"
msgstr "توجه داشته باشید که برای انواع مختلف «سراسری‌ها» موارد استفاده وجود دارد: وضعیت به‌ازای هر فرایند، به‌ازای هر مفسر، به‌ازای هر نخ یا به‌ازای هر وظیفه . با وضعیت به‌ازای هر ماژول به‌عنوان پیش‌فرض، این موارد همچنان امکان‌پذیر هستند، اما باید با آن‌ها به‌عنوان موارد استثنایی رفتار کنید: اگر به آن‌ها نیاز دارید، باید مراقبت و آزمون بیشتری برای آن‌ها در نظر بگیرید. (توجه داشته باشید که این راهنما آن‌ها را پوشش نمی‌دهد.)"

msgid "Isolated Module Objects"
msgstr "اشیای ماژول جداشده"

msgid "The key point to keep in mind when developing an extension module is that several module objects can be created from a single shared library. For example:"
msgstr "نکته کلیدی که باید هنگام توسعه‌ی یک ماژول توسعه در نظر داشته باشید این است که می‌توان چندین شیء ماژول را از یک کتابخانه مشترک واحد ایجاد کرد. برای مثال:"

msgid ""
">>> import sys\n"
">>> import binascii\n"
">>> old_binascii = binascii\n"
">>> del sys.modules['binascii']\n"
">>> import binascii  # create a new module object\n"
">>> old_binascii == binascii\n"
"False"
msgstr ""
">>> import sys\n"
">>> import binascii\n"
">>> old_binascii = binascii\n"
">>> del sys.modules['binascii']\n"
">>> import binascii  # create a new module object\n"
">>> old_binascii == binascii\n"
"False"

msgid "As a rule of thumb, the two modules should be completely independent. All objects and state specific to the module should be encapsulated within the module object, not shared with other module objects, and cleaned up when the module object is deallocated. Since this just is a rule of thumb, exceptions are possible (see `Managing Global State`_), but they will need more thought and attention to edge cases."
msgstr "به‌عنوان یک قاعده سرانگشتی، این دو ماژول باید کاملاً مستقل باشند. تمام اشیاء و وضعیت خاص ماژول باید درون شیء ماژول کپسوله شوند، با دیگر اشیاء ماژول به‌اشتراک گذاشته نشوند و هنگام آزادسازی شیء ماژول پاک‌سازی شوند. از آنجا که این صرفاً یک قاعده سرانگشتی است، ممکن است استثناهایی وجود داشته باشد (به `Managing Global State`_ مراجعه کنید)، اما آن‌ها به تفکر و توجه بیشتری نسبت به حالت‌های مرزی نیاز دارند."

msgid "While some modules could do with less stringent restrictions, isolated modules make it easier to set clear expectations and guidelines that work across a variety of use cases."
msgstr "در حالی که برخی ماژول‌ها ممکن است با محدودیت‌های کمتر سخت‌گیرانه نیز کار کنند، ماژول‌های ایزوله تعیین انتظارات و دستورالعمل‌های مشخصی را که در طیف متنوعی از موارد استفاده کاربرد دارند، آسان‌تر می‌کنند."

msgid "Surprising Edge Cases"
msgstr "حالت‌های مرزی غافلگیرکننده"

msgid "Note that isolated modules do create some surprising edge cases. Most notably, each module object will typically not share its classes and exceptions with other similar modules. Continuing from the `example above <Isolated Module Objects_>`__, note that ``old_binascii.Error`` and ``binascii.Error`` are separate objects. In the following code, the exception is *not* caught:"
msgstr "توجه داشته باشید که ماژول‌های ایزوله برخی حالت‌های مرزی غافلگیرکننده ایجاد می‌کنند. به‌ویژه، هر شیء ماژول به‌طور معمول کلاس‌ها و استثناهای خود را با سایر ماژول‌های مشابه به اشتراک نمی‌گذارد. در ادامه‌ی `مثال بالا <Isolated Module Objects_>`__، توجه داشته باشید که ``old_binascii.Error`` و ``binascii.Error`` اشیاء جداگانه‌ای هستند. در کد زیر، استثنا گرفته *نمی‌شود*:"

msgid ""
">>> old_binascii.Error == binascii.Error\n"
"False\n"
">>> try:\n"
"...     old_binascii.unhexlify(b'qwertyuiop')\n"
"... except binascii.Error:\n"
"...     print('boo')\n"
"...\n"
"Traceback (most recent call last):\n"
"  File \"<stdin>\", line 2, in <module>\n"
"binascii.Error: Non-hexadecimal digit found"
msgstr ""
">>> old_binascii.Error == binascii.Error\n"
"False\n"
">>> try:\n"
"...     old_binascii.unhexlify(b'qwertyuiop')\n"
"... except binascii.Error:\n"
"...     print('boo')\n"
"...\n"
"Traceback (most recent call last):\n"
"  File \"<stdin>\", line 2, in <module>\n"
"binascii.Error: Non-hexadecimal digit found"

msgid "This is expected. Notice that pure-Python modules behave the same way: it is a part of how Python works."
msgstr "این مورد انتظار است. توجه داشته باشید که ماژول‌های پایتون خالص نیز به همین شکل رفتار می‌کنند: این بخشی از نحوه‌ی کار پایتون است."

msgid "The goal is to make extension modules safe at the C level, not to make hacks behave intuitively. Mutating ``sys.modules`` \"manually\" counts as a hack."
msgstr "هدف این است که ماژول‌های توسعه در سطح C امن باشند، نه اینکه هک‌ها رفتاری شهودی داشته باشند. تغییر ``sys.modules`` به‌صورت «دستی» یک هک محسوب می‌شود."

msgid "Making Modules Safe with Multiple Interpreters"
msgstr "ایمن‌سازی ماژول‌ها با چند مفسر"

msgid "Managing Global State"
msgstr "مدیریت وضعیت سراسری"

msgid "Sometimes, the state associated with a Python module is not specific to that module, but to the entire process (or something else \"more global\" than a module). For example:"
msgstr "گاهی اوقات، وضعیت مرتبط با یک ماژول پایتون مختص به آن ماژول نیست، بلکه به کل فرایند (یا چیزی «سراسری‌تر» از یک ماژول) مربوط می‌شود. برای مثال:"

msgid "The ``readline`` module manages *the* terminal."
msgstr "ماژول ``readline`` *پایانه* را مدیریت می‌کند."

msgid "A module running on a circuit board wants to control *the* on-board LED."
msgstr "ماژولی که روی یک برد مدار اجرا می‌شود، می‌خواهد *همان* LED روی برد را کنترل کند."

msgid "In these cases, the Python module should provide *access* to the global state, rather than *own* it. If possible, write the module so that multiple copies of it can access the state independently (along with other libraries, whether for Python or other languages). If that is not possible, consider explicit locking."
msgstr "در این موارد، ماژول پایتون باید به‌جای *مالکیت* وضعیت سراسری، *دسترسی* به آن را فراهم کند. در صورت امکان، ماژول را به‌گونه‌ای بنویسید که چندین نسخه از آن بتوانند مستقل از یکدیگر به وضعیت دسترسی داشته باشند (در کنار سایر کتابخانه‌ها، چه برای پایتون و چه برای زبان‌های دیگر). اگر این ممکن نیست، قفل صریح را در نظر بگیرید."

msgid "If it is necessary to use process-global state, the simplest way to avoid issues with multiple interpreters is to explicitly prevent a module from being loaded more than once per process—see :ref:`isolating-extensions-optout`."
msgstr "اگر استفاده از وضعیت سراسری در سطح فرایند ضروری است، ساده‌ترین راه برای اجتناب از مشکلات مربوط به چندین مفسر، جلوگیری صریح از بارگذاری یک ماژول بیش از یک بار در هر فرایند است—:ref:`isolating-extensions-optout` را ببینید."

msgid "Managing Per-Module State"
msgstr "مدیریت وضعیت هر ماژول"

msgid "To use per-module state, use :ref:`multi-phase extension module initialization <multi-phase-initialization>`. This signals that your module supports multiple interpreters correctly."
msgstr "برای استفاده از وضعیت به‌ازای هر ماژول، از :ref:`multi-phase extension module initialization <multi-phase-initialization>` استفاده کنید. این نشان می‌دهد که ماژول شما به‌درستی از چندین مفسر پشتیبانی می‌کند."

msgid "Set ``PyModuleDef.m_size`` to a positive number to request that many bytes of storage local to the module. Usually, this will be set to the size of some module-specific ``struct``, which can store all of the module's C-level state. In particular, it is where you should put pointers to classes (including exceptions, but excluding static types) and settings (e.g. ``csv``'s :py:data:`~csv.field_size_limit`) which the C code needs to function."
msgstr "``PyModuleDef.m_size`` را روی یک عدد مثبت تنظیم کنید تا آن تعداد بایت حافظه‌ی محلی ماژول درخواست شود. معمولاً، این مقدار روی اندازه‌ی یک ``struct`` اختصاصی برای ماژول تنظیم می‌شود که می‌تواند تمام وضعیت ماژول در سطح C را ذخیره کند. به‌طور خاص، این جایی است که باید اشاره‌گرهایی به کلاس‌ها (شامل استثناها، اما به‌جز انواع ایستا) و تنظیماتی (مانند :py:data:`~csv.field_size_limit` در ``csv``) را قرار دهید که کد C برای کار کردن به آن‌ها نیاز دارد."

msgid "Another option is to store state in the module's ``__dict__``, but you must avoid crashing when users modify ``__dict__`` from Python code. This usually means error- and type-checking at the C level, which is easy to get wrong and hard to test sufficiently."
msgstr "گزینه دیگر این است که وضعیت را در ``__dict__`` ماژول ذخیره کنید، اما باید هنگامی که کاربران ``__dict__`` را از کد پایتون تغییر می‌دهند، از فروپاشی جلوگیری کنید. این معمولاً به معنای بررسی خطاها و نوع‌ها در سطح C است، که پیاده‌سازی نادرست آن آسان و آزمایش کافی آن دشوار است."

msgid "However, if module state is not needed in C code, storing it in ``__dict__`` only is a good idea."
msgstr "با این حال، اگر وضعیت ماژول در کد C مورد نیاز نیست، ذخیره آن فقط در ``__dict__`` ایده خوبی است."

msgid "If the module state includes ``PyObject`` pointers, the module object must hold references to those objects and implement the module-level hooks ``m_traverse``, ``m_clear`` and ``m_free``. These work like ``tp_traverse``, ``tp_clear`` and ``tp_free`` of a class. Adding them will require some work and make the code longer; this is the price for modules which can be unloaded cleanly."
msgstr "اگر وضعیت ماژول شامل اشاره‌گرهای ``PyObject`` باشد، شیء ماژول باید ارجاع‌ها به آن اشیاء را حفظ کند و قلاب‌های سطح ماژول ``m_traverse``، ``m_clear`` و ``m_free`` را پیاده‌سازی کند. این‌ها مانند ``tp_traverse``، ``tp_clear`` و ``tp_free`` در یک کلاس کار می‌کنند. افزودن آن‌ها نیازمند کمی کار است و کد را طولانی‌تر می‌کند؛ این بهای ماژول‌هایی است که می‌توانند به‌تمیزی باربرداری شوند."

msgid "An example of a module with per-module state is currently available as `xxlimited <https://github.com/python/cpython/blob/master/Modules/xxlimited.c>`__; example module initialization shown at the bottom of the file."
msgstr "نمونه‌ای از یک ماژول با وضعیت به‌ازای هر ماژول، در حال حاضر به‌عنوان `xxlimited <https://github.com/python/cpython/blob/master/Modules/xxlimited.c>`__ در دسترس است؛ مقداردهی اولیه ماژول نمونه در پایان پرونده نشان داده شده است."

msgid "Opt-Out: Limiting to One Module Object per Process"
msgstr "انصراف: محدود کردن به یک شیء ماژول در هر فرایند"

msgid "A non-negative ``PyModuleDef.m_size`` signals that a module supports multiple interpreters correctly. If this is not yet the case for your module, you can explicitly make your module loadable only once per process. For example::"
msgstr "مقدار غیرمنفی ``PyModuleDef.m_size`` نشان می‌دهد که ماژول به‌درستی از چند مفسر پشتیبانی می‌کند. اگر این وضعیت هنوز برای ماژول شما برقرار نیست، می‌توانید به‌صراحت ماژول خود را فقط یک‌بار در هر فرایند قابل بارگذاری کنید. برای مثال::"

msgid ""
"// A process-wide flag\n"
"static int loaded = 0;\n"
"\n"
"// Mutex to provide thread safety (only needed for free-threaded Python)\n"
"static PyMutex modinit_mutex = {0};\n"
"\n"
"static int\n"
"exec_module(PyObject* module)\n"
"{\n"
"    PyMutex_Lock(&modinit_mutex);\n"
"    if (loaded) {\n"
"        PyMutex_Unlock(&modinit_mutex);\n"
"        PyErr_SetString(PyExc_ImportError,\n"
"                        \"cannot load module more than once per process\");\n"
"        return -1;\n"
"    }\n"
"    loaded = 1;\n"
"    PyMutex_Unlock(&modinit_mutex);\n"
"    // ... rest of initialization\n"
"}"
msgstr ""
"// A process-wide flag\n"
"static int loaded = 0;\n"
"\n"
"// Mutex to provide thread safety (only needed for free-threaded Python)\n"
"static PyMutex modinit_mutex = {0};\n"
"\n"
"static int\n"
"exec_module(PyObject* module)\n"
"{\n"
"    PyMutex_Lock(&modinit_mutex);\n"
"    if (loaded) {\n"
"        PyMutex_Unlock(&modinit_mutex);\n"
"        PyErr_SetString(PyExc_ImportError,\n"
"                        \"cannot load module more than once per process\");\n"
"        return -1;\n"
"    }\n"
"    loaded = 1;\n"
"    PyMutex_Unlock(&modinit_mutex);\n"
"    // ... rest of initialization\n"
"}"

msgid "If your module's :c:member:`PyModuleDef.m_clear` function is able to prepare for future re-initialization, it should clear the ``loaded`` flag. In this case, your module won't support multiple instances existing *concurrently*, but it will, for example, support being loaded after Python runtime shutdown (:c:func:`Py_FinalizeEx`) and re-initialization (:c:func:`Py_Initialize`)."
msgstr "اگر تابع :c:member:`PyModuleDef.m_clear` ماژول شما قادر است برای مقداردهی اولیه مجدد در آینده آماده شود، باید پرچم ``loaded`` را پاک کند. در این صورت، ماژول شما از وجود *همزمان* چندین نمونه پشتیبانی نخواهد کرد، اما برای مثال، از بارگذاری شدن پس از خاموش شدن ران‌تایم پایتون (:c:func:`Py_FinalizeEx`) و مقداردهی اولیه مجدد (:c:func:`Py_Initialize`) پشتیبانی خواهد کرد."

msgid "Module State Access from Functions"
msgstr "دسترسی به وضعیت ماژول از توابع"

msgid "Accessing the state from module-level functions is straightforward. Functions get the module object as their first argument; for extracting the state, you can use ``PyModule_GetState``::"
msgstr "دسترسی به وضعیت از توابع سطح ماژول ساده است. توابع شیء ماژول را به‌عنوان نخستین آرگومان خود دریافت می‌کنند؛ برای استخراج وضعیت، می‌توانید از ``PyModule_GetState`` استفاده کنید::"

msgid ""
"static PyObject *\n"
"func(PyObject *module, PyObject *args)\n"
"{\n"
"    my_struct *state = (my_struct*)PyModule_GetState(module);\n"
"    if (state == NULL) {\n"
"        return NULL;\n"
"    }\n"
"    // ... rest of logic\n"
"}"
msgstr ""
"static PyObject *\n"
"func(PyObject *module, PyObject *args)\n"
"{\n"
"    my_struct *state = (my_struct*)PyModule_GetState(module);\n"
"    if (state == NULL) {\n"
"        return NULL;\n"
"    }\n"
"    // ... rest of logic\n"
"}"

msgid "``PyModule_GetState`` may return ``NULL`` without setting an exception if there is no module state, i.e. ``PyModuleDef.m_size`` was zero. In your own module, you're in control of ``m_size``, so this is easy to prevent."
msgstr "``PyModule_GetState`` ممکن است در صورتی که وضعیت ماژول وجود نداشته باشد، یعنی ``PyModuleDef.m_size`` صفر بوده است، ``NULL`` را بدون اینکه استثنایی تنظیم کند برگرداند. در ماژول خودتان، شما بر ``m_size`` کنترل دارید، بنابراین جلوگیری از این موضوع آسان است."

msgid "Heap Types"
msgstr "انواع Heap"

msgid "Traditionally, types defined in C code are *static*; that is, ``static PyTypeObject`` structures defined directly in code and initialized using ``PyType_Ready()``."
msgstr "به‌طور سنتی، نوع‌های تعریف‌شده در کد C *ایستا* هستند؛ یعنی ساختارهای ``static PyTypeObject`` که مستقیماً در کد تعریف شده‌اند و با استفاده از ``PyType_Ready()`` مقداردهی اولیه می‌شوند."

msgid "Such types are necessarily shared across the process. Sharing them between module objects requires paying attention to any state they own or access. To limit the possible issues, static types are immutable at the Python level: for example, you can't set ``str.myattribute = 123``."
msgstr "چنین نوع‌هایی لزوماً در سراسر فرایند به‌اشتراک گذاشته می‌شوند. به‌اشتراک گذاشتن آن‌ها بین اشیای ماژول نیازمند توجه به هر وضعیتی است که مالک آن هستند یا به آن دسترسی دارند. برای محدود کردن مسائل احتمالی، نوع‌های ایستا در سطح پایتون تغییرناپذیر هستند: برای مثال، نمی‌توانید ``str.myattribute = 123`` را انتساب دهید."

msgid "Sharing truly immutable objects between interpreters is fine, as long as they don't provide access to mutable objects. However, in CPython, every Python object has a mutable implementation detail: the reference count. Changes to the refcount are guarded by the GIL. Thus, code that shares any Python objects across interpreters implicitly depends on CPython's current, process-wide GIL."
msgstr "اشتراک‌گذاری اشیاء واقعاً تغییرناپذیر میان مفسرها مشکلی ندارد، تا زمانی که آن‌ها دسترسی به اشیاء تغییرپذیر فراهم نکنند. با این حال، در CPython، هر شیء پایتون یک جزئیات پیاده‌سازی تغییرپذیر دارد: شمار ارجاع. تغییرات شمار ارجاع توسط GIL محافظت می‌شود. بنابراین، کدی که هر شیء پایتون را میان مفسرها به اشتراک می‌گذارد، به‌طور ضمنی به GIL فعلی CPython در سطح فرآیند وابسته است."

msgid "Because they are immutable and process-global, static types cannot access \"their\" module state. If any method of such a type requires access to module state, the type must be converted to a *heap-allocated type*, or *heap type* for short. These correspond more closely to classes created by Python's ``class`` statement."
msgstr "از آن‌جا که انواع ایستا تغییرناپذیر و سراسری در سطح فرایند هستند، امکان دسترسی به وضعیت ماژول «خود» را ندارند. اگر هر متدی از چنین نوعی نیازمند دسترسی به وضعیت ماژول باشد، آن نوع باید به یک *نوع تخصیص‌یافته در heap* (heap-allocated type)، یا به‌اختصار *نوع heap* (heap type) تبدیل شود. این موارد بیشتر با کلاس‌های ایجادشده با دستور ``class`` پایتون مطابقت دارند."

msgid "For new modules, using heap types by default is a good rule of thumb."
msgstr "برای ماژول‌های جدید، استفاده از انواع heap (heap types) به‌صورت پیش‌فرض، قاعده سرانگشتی خوبی است."

msgid "Changing Static Types to Heap Types"
msgstr "تغییر نوع‌های ایستا به نوع‌های Heap"

msgid "Static types can be converted to heap types, but note that the heap type API was not designed for \"lossless\" conversion from static types—that is, creating a type that works exactly like a given static type. So, when rewriting the class definition in a new API, you are likely to unintentionally change a few details (e.g. pickleability or inherited slots). Always test the details that are important to you."
msgstr "می‌توان انواع ایستا را به انواع heap (heap types) تبدیل کرد، اما توجه داشته باشید که API نوع heap برای تبدیل «بدون اتلاف» انواع ایستا طراحی نشده است—یعنی ایجاد نوعی که دقیقاً مانند یک نوع ایستای مشخص رفتار کند. بنابراین، هنگام بازنویسی تعریف کلاس در یک API جدید، احتمال دارد به‌طور ناخواسته چند جزئیات را تغییر دهید (مثلاً قابلیت pickle یا جایگاه‌های ارثی). همیشه جزئیاتی را که برای شما مهم هستند آزمایش کنید."

msgid "Watch out for the following two points in particular (but note that this is not a comprehensive list):"
msgstr "به‌ویژه به دو نکته‌ی زیر توجه داشته باشید (اما توجه داشته باشید که این یک فهرست جامع نیست):"

msgid "Unlike static types, heap type objects are mutable by default. Use the :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` flag to prevent mutability."
msgstr "برخلاف انواع ایستا، اشیای نوع heap به‌طور پیش‌فرض تغییرپذیر هستند. برای جلوگیری از تغییرپذیری، از پرچم :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` استفاده کنید."

msgid "Heap types inherit :c:member:`~PyTypeObject.tp_new` by default, so it may become possible to instantiate them from Python code. You can prevent this with the :c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag."
msgstr "انواع Heap به‌طور پیش‌فرض :c:member:`~PyTypeObject.tp_new` را به ارث می‌برند، بنابراین ممکن است امکان نمونه‌سازی آن‌ها از کد پایتون فراهم شود. می‌توانید با پرچم :c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` از این موضوع جلوگیری کنید."

msgid "Defining Heap Types"
msgstr "تعریف انواع هیپ"

msgid "Heap types can be created by filling a :c:struct:`PyType_Spec` structure, a description or \"blueprint\" of a class, and calling :c:func:`PyType_FromModuleAndSpec` to construct a new class object."
msgstr "انواع Heap را می‌توان با پر کردن یک ساختار :c:struct:`PyType_Spec`، یک توصیف یا «نقشه» از یک کلاس، و فراخوانی :c:func:`PyType_FromModuleAndSpec` برای ساخت یک شیء کلاس جدید ایجاد کرد."

msgid "Other functions, like :c:func:`PyType_FromSpec`, can also create heap types, but :c:func:`PyType_FromModuleAndSpec` associates the module with the class, allowing access to the module state from methods."
msgstr "توابع دیگر، مانند :c:func:`PyType_FromSpec`، نیز می‌توانند نوع‌های heap (heap types) را ایجاد کنند، اما :c:func:`PyType_FromModuleAndSpec` ماژول را به کلاس مرتبط می‌کند و امکان دسترسی به وضعیت ماژول را از طریق متدها فراهم می‌کند."

msgid "The class should generally be stored in *both* the module state (for safe access from C) and the module's ``__dict__`` (for access from Python code)."
msgstr "این کلاس عموماً باید در *هر دو* وضعیت ماژول (برای دسترسی ایمن از C) و ``__dict__`` ماژول (برای دسترسی از کد پایتون) ذخیره شود."

msgid "Garbage-Collection Protocol"
msgstr "پروتکل زباله‌روبی"

msgid "Instances of heap types hold a reference to their type. This ensures that the type isn't destroyed before all its instances are, but may result in reference cycles that need to be broken by the garbage collector."
msgstr "نمونه‌های انواع heap، ارجاعی به نوع خود نگه می‌دارند. این امر تضمین می‌کند که نوع پیش از آنکه همه‌ی نمونه‌هایش نابود شوند، از بین نرود، اما ممکن است به چرخه‌های ارجاعی منجر شود که باید توسط زباله‌رو شکسته شوند."

msgid "To avoid memory leaks, instances of heap types must implement the garbage collection protocol. That is, heap types should:"
msgstr "برای جلوگیری از نشت حافظه، نمونه‌های انواع heap (heap types) باید پروتکل زباله‌روبی را پیاده‌سازی کنند. یعنی، انواع heap باید:"

msgid "Have the :c:macro:`Py_TPFLAGS_HAVE_GC` flag."
msgstr "پرچم :c:macro:`Py_TPFLAGS_HAVE_GC` را داشته باشد."

msgid "Define a traverse function using :c:data:`Py_tp_traverse`, which visits the type (e.g. using ``Py_VISIT(Py_TYPE(self))``)."
msgstr "یک تابع پیمایش با استفاده از :c:data:`Py_tp_traverse` تعریف کنید، که از نوع بازدید می‌کند (برای مثال با استفاده از ``Py_VISIT(Py_TYPE(self))``)."

msgid "Please refer to the documentation of :c:macro:`Py_TPFLAGS_HAVE_GC` and :c:member:`~PyTypeObject.tp_traverse` for additional considerations."
msgstr "برای ملاحظات بیشتر، لطفاً به مستندات :c:macro:`Py_TPFLAGS_HAVE_GC` و :c:member:`~PyTypeObject.tp_traverse` مراجعه کنید."

msgid "The API for defining heap types grew organically, leaving it somewhat awkward to use in its current state. The following sections will guide you through common issues."
msgstr "API برای تعریف انواع heap به‌صورت طبیعی رشد کرده است، به‌طوری که استفاده از آن در وضعیت کنونی تا حدی دشوار است. بخش‌های زیر شما را درباره‌ی مشکلات رایج راهنمایی می‌کنند."

msgid "``tp_traverse`` in Python 3.8 and lower"
msgstr "``tp_traverse`` در پایتون 3.8 و پایین‌تر"

msgid "The requirement to visit the type from ``tp_traverse`` was added in Python 3.9. If you support Python 3.8 and lower, the traverse function must *not* visit the type, so it must be more complicated::"
msgstr "الزام به بازدید از نوع از ``tp_traverse`` در Python 3.9 افزوده شد. اگر از Python 3.8 و پایین‌تر پشتیبانی می‌کنید، تابع پیمایش *نباید* از نوع بازدید کند، بنابراین باید پیچیده‌تر باشد::"

msgid ""
"static int my_traverse(PyObject *self, visitproc visit, void *arg)\n"
"{\n"
"    if (Py_Version >= 0x03090000) {\n"
"        Py_VISIT(Py_TYPE(self));\n"
"    }\n"
"    return 0;\n"
"}"
msgstr ""
"static int my_traverse(PyObject *self, visitproc visit, void *arg)\n"
"{\n"
"    if (Py_Version >= 0x03090000) {\n"
"        Py_VISIT(Py_TYPE(self));\n"
"    }\n"
"    return 0;\n"
"}"

msgid "Unfortunately, :c:data:`Py_Version` was only added in Python 3.11. As a replacement, use:"
msgstr "متأسفانه، :c:data:`Py_Version` تنها در پایتون 3.11 اضافه شده است. به‌عنوان جایگزین، از این استفاده کنید:"

msgid ":c:macro:`PY_VERSION_HEX`, if not using the stable ABI, or"
msgstr ":c:macro:`PY_VERSION_HEX`، در صورت عدم استفاده از ABI پایدار، یا"

msgid ":py:data:`sys.version_info` (via :c:func:`PySys_GetObject` and :c:func:`PyArg_ParseTuple`)."
msgstr ":py:data:`sys.version_info` (از طریق :c:func:`PySys_GetObject` و :c:func:`PyArg_ParseTuple`)."

msgid "Delegating ``tp_traverse``"
msgstr "واگذاری ``tp_traverse``"

msgid "If your traverse function delegates to the :c:member:`~PyTypeObject.tp_traverse` of its base class (or another type), ensure that ``Py_TYPE(self)`` is visited only once. Note that only heap type are expected to visit the type in ``tp_traverse``."
msgstr "اگر تابع پیمایش شما به :c:member:`~PyTypeObject.tp_traverse` کلاس پایه خود (یا نوع دیگری) واگذار می‌کند، اطمینان حاصل کنید که ``Py_TYPE(self)`` تنها یک بار بازدید می‌شود. توجه داشته باشید که فقط انواع heap (heap type) انتظار می‌رود که نوع را در ``tp_traverse`` بازدید کنند."

msgid "For example, if your traverse function includes::"
msgstr "برای مثال، اگر تابع پیمایش شما شامل موارد زیر باشد::"

msgid "base->tp_traverse(self, visit, arg)"
msgstr "base->tp_traverse(self, visit, arg)"

msgid "...and ``base`` may be a static type, then it should also include::"
msgstr "... و ``base`` ممکن است یک نوع ایستا باشد، در این صورت باید شامل موارد زیر نیز باشد::"

msgid ""
"if (base->tp_flags & Py_TPFLAGS_HEAPTYPE) {\n"
"    // a heap type's tp_traverse already visited Py_TYPE(self)\n"
"} else {\n"
"    if (Py_Version >= 0x03090000) {\n"
"        Py_VISIT(Py_TYPE(self));\n"
"    }\n"
"}"
msgstr ""
"if (base->tp_flags & Py_TPFLAGS_HEAPTYPE) {\n"
"    // a heap type's tp_traverse already visited Py_TYPE(self)\n"
"} else {\n"
"    if (Py_Version >= 0x03090000) {\n"
"        Py_VISIT(Py_TYPE(self));\n"
"    }\n"
"}"

msgid "It is not necessary to handle the type's reference count in :c:member:`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject.tp_clear`."
msgstr "لازم نیست شمار ارجاعِ نوع در :c:member:`~PyTypeObject.tp_new` و :c:member:`~PyTypeObject.tp_clear` مدیریت شود."

msgid "Defining ``tp_dealloc``"
msgstr "تعریف ``tp_dealloc``"

msgid "If your type has a custom :c:member:`~PyTypeObject.tp_dealloc` function, it needs to:"
msgstr "اگر نوع شما تابع :c:member:`~PyTypeObject.tp_dealloc` سفارشی دارد، باید:"

msgid "call :c:func:`PyObject_GC_UnTrack` before any fields are invalidated, and"
msgstr ":c:func:`PyObject_GC_UnTrack` را پیش از آنکه فیلدها بی‌اعتبار شوند فراخوانی کنید، و"

msgid "decrement the reference count of the type."
msgstr "شمار ارجاع‌های نوع را کاهش دهید."

msgid "To keep the type valid while ``tp_free`` is called, the type's refcount needs to be decremented *after* the instance is deallocated. For example::"
msgstr "برای معتبر نگه‌داشتن نوع در حین فراخوانی ``tp_free``، شمارنده ارجاع (refcount) نوع باید *پس از* آزادسازی نمونه کاهش یابد. برای مثال::"

msgid ""
"static void my_dealloc(PyObject *self)\n"
"{\n"
"    PyObject_GC_UnTrack(self);\n"
"    ...\n"
"    PyTypeObject *type = Py_TYPE(self);\n"
"    type->tp_free(self);\n"
"    Py_DECREF(type);\n"
"}"
msgstr ""
"static void my_dealloc(PyObject *self)\n"
"{\n"
"    PyObject_GC_UnTrack(self);\n"
"    ...\n"
"    PyTypeObject *type = Py_TYPE(self);\n"
"    type->tp_free(self);\n"
"    Py_DECREF(type);\n"
"}"

msgid "The default ``tp_dealloc`` function does this, so if your type does *not* override ``tp_dealloc`` you don't need to add it."
msgstr "تابع پیش‌فرض ``tp_dealloc`` این کار را انجام می‌دهد، بنابراین اگر نوع شما ``tp_dealloc`` را بازنویسی *نمی‌کند*، نیازی نیست آن را اضافه کنید."

msgid "Not overriding ``tp_free``"
msgstr "عدم بازنویسی ``tp_free``"

msgid "The :c:member:`~PyTypeObject.tp_free` slot of a heap type must be set to :c:func:`PyObject_GC_Del`. This is the default; do not override it."
msgstr "جایگاه :c:member:`~PyTypeObject.tp_free` در یک نوع heap باید روی :c:func:`PyObject_GC_Del` تنظیم شود. این پیش‌فرض است؛ آن را بازنویسی نکنید."

msgid "Avoiding ``PyObject_New``"
msgstr "پرهیز از ``PyObject_New``"

msgid "GC-tracked objects need to be allocated using GC-aware functions."
msgstr "اشیای پیگیری‌شده توسط زباله‌روبی باید با استفاده از توابع آگاه از زباله‌روبی تخصیص داده شوند."

msgid "If you use :c:func:`PyObject_New` or :c:func:`PyObject_NewVar`:"
msgstr "اگر از :c:func:`PyObject_New` یا :c:func:`PyObject_NewVar` استفاده می‌کنید:"

msgid "Get and call type's :c:member:`~PyTypeObject.tp_alloc` slot, if possible. That is, replace ``TYPE *o = PyObject_New(TYPE, typeobj)`` with::"
msgstr "در صورت امکان، جایگاه :c:member:`~PyTypeObject.tp_alloc` نوع را دریافت کرده و فراخوانی کنید. یعنی ``TYPE *o = PyObject_New(TYPE, typeobj)`` را با این جایگزین کنید::"

msgid "TYPE *o = typeobj->tp_alloc(typeobj, 0);"
msgstr "TYPE *o = typeobj->tp_alloc(typeobj, 0);"

msgid "Replace ``o = PyObject_NewVar(TYPE, typeobj, size)`` with the same, but use size instead of the 0."
msgstr "``o = PyObject_NewVar(TYPE, typeobj, size)`` را با همان جایگزین کنید، اما به‌جای 0 از size استفاده کنید."

msgid "If the above is not possible (e.g. inside a custom ``tp_alloc``), call :c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`::"
msgstr "اگر مورد بالا ممکن نیست (برای مثال داخل یک ``tp_alloc`` سفارشی)، :c:func:`PyObject_GC_New` یا :c:func:`PyObject_GC_NewVar` را فراخوانی کنید::"

msgid ""
"TYPE *o = PyObject_GC_New(TYPE, typeobj);\n"
"\n"
"TYPE *o = PyObject_GC_NewVar(TYPE, typeobj, size);"
msgstr ""
"TYPE *o = PyObject_GC_New(TYPE, typeobj);\n"
"\n"
"TYPE *o = PyObject_GC_NewVar(TYPE, typeobj, size);"

msgid "Module State Access from Classes"
msgstr "دسترسی به وضعیت ماژول از کلاس‌ها"

msgid "If you have a type object defined with :c:func:`PyType_FromModuleAndSpec`, you can call :c:func:`PyType_GetModule` to get the associated module, and then :c:func:`PyModule_GetState` to get the module's state."
msgstr "اگر یک شیء نوع تعریف‌شده با :c:func:`PyType_FromModuleAndSpec` دارید، می‌توانید :c:func:`PyType_GetModule` را فراخوانی کنید تا ماژول مرتبط را دریافت کنید، و سپس :c:func:`PyModule_GetState` را فراخوانی کنید تا وضعیت ماژول را دریافت کنید."

msgid "To save a some tedious error-handling boilerplate code, you can combine these two steps with :c:func:`PyType_GetModuleState`, resulting in::"
msgstr "برای پرهیز از برخی کدهای پیش‌ساخته ملال‌آور مدیریت خطا، می‌توانید این دو مرحله را با :c:func:`PyType_GetModuleState` ترکیب کنید، که نتیجه به این صورت است::"

msgid ""
"my_struct *state = (my_struct*)PyType_GetModuleState(type);\n"
"if (state == NULL) {\n"
"    return NULL;\n"
"}"
msgstr ""
"my_struct *state = (my_struct*)PyType_GetModuleState(type);\n"
"if (state == NULL) {\n"
"    return NULL;\n"
"}"

msgid "Module State Access from Regular Methods"
msgstr "دسترسی به وضعیت ماژول از متدهای معمولی"

msgid "Accessing the module-level state from methods of a class is somewhat more complicated, but is possible thanks to API introduced in Python 3.9. To get the state, you need to first get the *defining class*, and then get the module state from it."
msgstr "دسترسی به وضعیت سطح ماژول از متدهای یک کلاس تا حدی پیچیده‌تر است، اما به‌لطف API معرفی‌شده در پایتون 3.9 امکان‌پذیر است. برای دریافت وضعیت، باید ابتدا *کلاس تعریف‌کننده* را دریافت کنید و سپس وضعیت ماژول را از آن بگیرید."

msgid "The largest roadblock is getting *the class a method was defined in*, or that method's \"defining class\" for short. The defining class can have a reference to the module it is part of."
msgstr "بزرگ‌ترین مانع، به دست آوردن *کلاسی که یک متد در آن تعریف شده است*، یا به‌اختصار «کلاس تعریف‌کننده»ی آن متد است. کلاس تعریف‌کننده می‌تواند ارجاعی به ماژولی داشته باشد که بخشی از آن است."

msgid "Do not confuse the defining class with ``Py_TYPE(self)``. If the method is called on a *subclass* of your type, ``Py_TYPE(self)`` will refer to that subclass, which may be defined in different module than yours."
msgstr "کلاس تعریف‌کننده را با ``Py_TYPE(self)`` اشتباه نگیرید. اگر متد بر روی یک *زیرکلاس* از نوع شما فراخوانی شود، ``Py_TYPE(self)`` به آن زیرکلاس ارجاع خواهد داشت، که ممکن است در ماژولی متفاوت از ماژول شما تعریف شده باشد."

msgid "The following Python code can illustrate the concept. ``Base.get_defining_class`` returns ``Base`` even if ``type(self) == Sub``:"
msgstr "کد پایتون زیر می‌تواند این مفهوم را نشان دهد. ``Base.get_defining_class`` حتی اگر ``type(self) == Sub`` باشد، ``Base`` را برمی‌گرداند:"

msgid ""
"class Base:\n"
"    def get_type_of_self(self):\n"
"        return type(self)\n"
"\n"
"    def get_defining_class(self):\n"
"        return __class__\n"
"\n"
"class Sub(Base):\n"
"    pass"
msgstr ""
"class Base:\n"
"    def get_type_of_self(self):\n"
"        return type(self)\n"
"\n"
"    def get_defining_class(self):\n"
"        return __class__\n"
"\n"
"class Sub(Base):\n"
"    pass"

msgid "For a method to get its \"defining class\", it must use the :ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS <METH_METHOD-METH_FASTCALL-METH_KEYWORDS>` :c:type:`calling convention <PyMethodDef>` and the corresponding :c:type:`PyCMethod` signature::"
msgstr "برای اینکه یک متد «کلاس تعریف‌کننده» خود را دریافت کند، باید از :ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS <METH_METHOD-METH_FASTCALL-METH_KEYWORDS>` :c:type:`قرارداد فراخوانی <PyMethodDef>` و امضای متناظر :c:type:`PyCMethod` استفاده کند::"

msgid ""
"PyObject *PyCMethod(\n"
"    PyObject *self,               // object the method was called on\n"
"    PyTypeObject *defining_class, // defining class\n"
"    PyObject *const *args,        // C array of arguments\n"
"    Py_ssize_t nargs,             // length of \"args\"\n"
"    PyObject *kwnames)            // NULL, or dict of keyword arguments"
msgstr ""
"PyObject *PyCMethod(\n"
"    PyObject *self,               // object the method was called on\n"
"    PyTypeObject *defining_class, // defining class\n"
"    PyObject *const *args,        // C array of arguments\n"
"    Py_ssize_t nargs,             // length of \"args\"\n"
"    PyObject *kwnames)            // NULL, or dict of keyword arguments"

msgid "Once you have the defining class, call :c:func:`PyType_GetModuleState` to get the state of its associated module."
msgstr "پس از اینکه کلاس تعریف‌کننده را در اختیار داشتید، برای دریافت وضعیت ماژول مرتبط با آن، :c:func:`PyType_GetModuleState` را فراخوانی کنید."

msgid "For example::"
msgstr "برای مثال::"

msgid ""
"static PyObject *\n"
"example_method(PyObject *self,\n"
"        PyTypeObject *defining_class,\n"
"        PyObject *const *args,\n"
"        Py_ssize_t nargs,\n"
"        PyObject *kwnames)\n"
"{\n"
"    my_struct *state = (my_struct*)PyType_GetModuleState(defining_class);\n"
"    if (state == NULL) {\n"
"        return NULL;\n"
"    }\n"
"    ... // rest of logic\n"
"}\n"
"\n"
"PyDoc_STRVAR(example_method_doc, \"...\");\n"
"\n"
"static PyMethodDef my_methods[] = {\n"
"    {\"example_method\",\n"
"      (PyCFunction)(void(*)(void))example_method,\n"
"      METH_METHOD|METH_FASTCALL|METH_KEYWORDS,\n"
"      example_method_doc}\n"
"    {NULL},\n"
"}"
msgstr ""
"static PyObject *\n"
"example_method(PyObject *self,\n"
"        PyTypeObject *defining_class,\n"
"        PyObject *const *args,\n"
"        Py_ssize_t nargs,\n"
"        PyObject *kwnames)\n"
"{\n"
"    my_struct *state = (my_struct*)PyType_GetModuleState(defining_class);\n"
"    if (state == NULL) {\n"
"        return NULL;\n"
"    }\n"
"    ... // rest of logic\n"
"}\n"
"\n"
"PyDoc_STRVAR(example_method_doc, \"...\");\n"
"\n"
"static PyMethodDef my_methods[] = {\n"
"    {\"example_method\",\n"
"      (PyCFunction)(void(*)(void))example_method,\n"
"      METH_METHOD|METH_FASTCALL|METH_KEYWORDS,\n"
"      example_method_doc}\n"
"    {NULL},\n"
"}"

msgid "Module State Access from Slot Methods, Getters and Setters"
msgstr "دسترسی به وضعیت ماژول از متدهای جایگاه، getters و setters"

msgid "This is new in Python 3.11."
msgstr "این مورد در پایتون 3.11 جدید است."

msgid "Slot methods—the fast C equivalents for special methods, such as :c:member:`~PyNumberMethods.nb_add` for :py:attr:`~object.__add__` or :c:member:`~PyTypeObject.tp_new` for initialization—have a very simple API that doesn't allow passing in the defining class, unlike with :c:type:`PyCMethod`. The same goes for getters and setters defined with :c:type:`PyGetSetDef`."
msgstr "متدهای جایگاه (slot methods)—معادل‌های سریع C برای متدهای ویژه، مانند :c:member:`~PyNumberMethods.nb_add` برای :py:attr:`~object.__add__` یا :c:member:`~PyTypeObject.tp_new` برای مقداردهی اولیه—دارای API بسیار ساده‌ای هستند که برخلاف :c:type:`PyCMethod` اجازه‌ی ارسال کلاس تعریف‌کننده را نمی‌دهد. همین موضوع برای setters و getters که با :c:type:`PyGetSetDef` تعریف‌شده‌اند نیز صدق می‌کند."

msgid "To access the module state in these cases, use the :c:func:`PyType_GetModuleByDef` function, and pass in the module definition. Once you have the module, call :c:func:`PyModule_GetState` to get the state::"
msgstr "برای دسترسی به وضعیت ماژول در این موارد، از تابع :c:func:`PyType_GetModuleByDef` استفاده کنید و تعریف ماژول را به آن ارسال کنید. هنگامی که ماژول را دریافت کردید، برای دریافت وضعیت، :c:func:`PyModule_GetState` را فراخوانی کنید::"

msgid ""
"PyObject *module = PyType_GetModuleByDef(Py_TYPE(self), &module_def);\n"
"my_struct *state = (my_struct*)PyModule_GetState(module);\n"
"if (state == NULL) {\n"
"    return NULL;\n"
"}"
msgstr ""
"PyObject *module = PyType_GetModuleByDef(Py_TYPE(self), &module_def);\n"
"my_struct *state = (my_struct*)PyModule_GetState(module);\n"
"if (state == NULL) {\n"
"    return NULL;\n"
"}"

msgid ":c:func:`!PyType_GetModuleByDef` works by searching the :term:`method resolution order` (i.e. all superclasses) for the first superclass that has a corresponding module."
msgstr ":c:func:`!PyType_GetModuleByDef` با جست‌وجو در :term:`method resolution order` (یعنی همه‌ی ابرکلاس‌ها) برای نخستین ابرکلاسی که ماژول متناظر دارد، کار می‌کند."

msgid "In very exotic cases (inheritance chains spanning multiple modules created from the same definition), :c:func:`!PyType_GetModuleByDef` might not return the module of the true defining class. However, it will always return a module with the same definition, ensuring a compatible C memory layout."
msgstr "در موارد بسیار خاص (زنجیره‌های وراثتی که چندین ماژول ایجادشده از یک تعریف را در بر می‌گیرند)، ممکن است :c:func:`!PyType_GetModuleByDef` ماژولِ کلاس تعریف‌کننده واقعی را برنگرداند. با این حال، همیشه ماژولی با همان تعریف را برمی‌گرداند و چیدمان حافظه‌ای سازگار در C را تضمین می‌کند."

msgid "Lifetime of the Module State"
msgstr "طول عمر وضعیت ماژول"

msgid "When a module object is garbage-collected, its module state is freed. For each pointer to (a part of) the module state, you must hold a reference to the module object."
msgstr "وقتی یک شیء ماژول زباله‌روبی می‌شود، وضعیت ماژول آن آزاد می‌شود. برای هر اشاره‌گر به (بخشی از) وضعیت ماژول، باید یک ارجاع به شیء ماژول نگه دارید."

msgid "Usually this is not an issue, because types created with :c:func:`PyType_FromModuleAndSpec`, and their instances, hold a reference to the module. However, you must be careful in reference counting when you reference module state from other places, such as callbacks for external libraries."
msgstr "معمولاً این مسئله مشکلی نیست، زیرا انواع ساخته‌شده با :c:func:`PyType_FromModuleAndSpec` و نمونه‌هایشان، یک ارجاع به ماژول نگه می‌دارند. با این حال، وقتی از جاهای دیگر، مانند کال‌بک‌هایی برای کتابخانه‌های خارجی، به وضعیت ماژول ارجاع می‌دهید، باید در شمارش ارجاع دقت کنید."

msgid "Open Issues"
msgstr "مسائل باز"

msgid "Several issues around per-module state and heap types are still open."
msgstr "چندین مسئله پیرامون وضعیت به‌ازای هر ماژول و انواع heap (heap types) هنوز باز هستند."

msgid "Discussions about improving the situation are best held on the `discuss forum under c-api tag <https://discuss.python.org/c/core-dev/c-api/30>`__."
msgstr "بهتر است بحث‌های مربوط به بهبود وضعیت در `انجمن discuss ذیل برچسب c-api <https://discuss.python.org/c/core-dev/c-api/30>`__ انجام شوند."

msgid "Per-Class Scope"
msgstr "محدوده به‌ازای هر کلاس"

msgid "It is currently (as of Python 3.11) not possible to attach state to individual *types* without relying on CPython implementation details (which may change in the future—perhaps, ironically, to allow a proper solution for per-class scope)."
msgstr "در حال حاضر (در پایتون 3.11) امکان الصاق وضعیت به *انواع* منفرد بدون تکیه بر جزئیات پیاده‌سازی CPython وجود ندارد (که ممکن است در آینده تغییر کنند—شاید، از سر طعنه، تا راه‌حل مناسبی برای محدوده به‌ازای هر کلاس فراهم شود)."

msgid "Lossless Conversion to Heap Types"
msgstr "تبدیل بدون اتلاف به نوع‌های Heap"

msgid "The heap type API was not designed for \"lossless\" conversion from static types; that is, creating a type that works exactly like a given static type."
msgstr "API نوع heap برای تبدیل «بدون اتلاف» از انواع ایستا طراحی نشده است؛ یعنی ایجاد نوعی که دقیقاً مانند یک نوع ایستای معین کار کند."