"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-09-15 10:51+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 "Defining Extension Types: Assorted Topics"

msgstr "تعریف نوع‌های توسعه‌ای: موضوعات گوناگون"

msgid "This section aims to give a quick fly-by on the various type methods you can implement and what they do."

msgstr "هدف این بخش، ارائه‌ی مروری سریع و گذرا بر متدهای مختلف نوع است؛ متدهایی که می‌توانید پیاده‌سازی کنید و اینکه هر یک چه کاری انجام می‌دهند."

msgid "Here is the definition of :c:type:`PyTypeObject`, with some fields only used in :ref:`debug builds <debug-build>` omitted:"

msgstr "در ادامه، تعریف :c:type:`PyTypeObject` آمده است؛ برخی از فیلدهایی که تنها در :ref:`ساخت‌های اشکال‌زدایی <debug-build>` استفاده می‌شوند، از آن حذف شده‌اند:"

msgid ""

msgstr ""

msgid "Now that's a *lot* of methods. Don't worry too much though -- if you have a type you want to define, the chances are very good that you will only implement a handful of these."

msgstr "خب، این *تعداد زیادی* متد است. البته زیاد نگران نباشید -- اگر نوعی دارید که می‌خواهید تعریف کنید، به احتمال بسیار زیاد فقط چند مورد از آن‌ها را پیاده‌سازی خواهید کرد."

msgid "As you probably expect by now, we're going to go over this and give more information about the various handlers. We won't go in the order they are defined in the structure, because there is a lot of historical baggage that impacts the ordering of the fields. It's often easiest to find an example that includes the fields you need and then change the values to suit your new type. ::"

msgstr "همان‌طور که احتمالاً تاکنون انتظار دارید، می‌خواهیم این موارد را مرور کنیم و اطلاعات بیشتری درباره هندلرهای گوناگون ارائه دهیم. به ترتیبی که در ساختار تعریف شده‌اند پیش نمی‌رویم، زیرا میراث تاریخی فراوانی وجود دارد که بر ترتیب فیلدها تأثیر می‌گذارد. اغلب ساده‌ترین راه این است که مثالی بیابید که فیلدهای مورد نیازتان را در بر داشته باشد و سپس مقادیر را متناسب با نوع جدید خود تغییر دهید. ::"

msgid "const char *tp_name; /* For printing */"

msgstr "const char *tp_name; /* برای چاپ */"

msgid "The name of the type -- as mentioned in the previous chapter, this will appear in various places, almost entirely for diagnostic purposes. Try to choose something that will be helpful in such a situation! ::"

msgstr "نام نوع — همان‌طور که در فصل پیشین ذکر شد، این نام در مکان‌های مختلف ظاهر خواهد شد، تقریباً به‌طور کامل برای اهداف تشخیصی. سعی کنید چیزی را برگزینید که در چنین موقعیتی سودمند باشد! ::"

msgid "Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */"

msgstr "Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */"

msgid "These fields tell the runtime how much memory to allocate when new objects of this type are created. Python has some built-in support for variable length structures (think: strings, tuples) which is where the :c:member:`~PyTypeObject.tp_itemsize` field comes in. This will be dealt with later. ::"

msgstr "این فیلدها به ران‌تایم می‌گویند که هنگام ایجاد اشیاء جدید از این نوع، چه مقدار حافظه تخصیص دهد. پایتون پشتیبانی توکاری برای ساختارهای با طول متغیر دارد (مثلاً: رشته‌ها، تاپل‌ها) و این همان جایی است که فیلد :c:member:`~PyTypeObject.tp_itemsize` به کار می‌آید. این موضوع بعداً بررسی خواهد شد. ::"

msgid "const char *tp_doc;"

msgstr "const char *tp_doc;"

msgid "Here you can put a string (or its address) that you want returned when the Python script references ``obj.__doc__`` to retrieve the doc string."

msgstr "در اینجا می‌توانید رشته‌ای (یا آدرس آن) را قرار دهید که می‌خواهید هنگامی که اسکریپت پایتون برای بازیابی رشته مستند به ``obj.__doc__`` ارجاع می‌دهد، بازگردانده شود."

msgid "Now we come to the basic type methods -- the ones most extension types will implement."

msgstr "اکنون به متدهای پایه‌ی نوع می‌رسیم -- همان‌هایی که بیشتر نوع‌های توسعه‌ای آن‌ها را پیاده‌سازی خواهند کرد."

msgid "Finalization and De-allocation"

msgstr "نهایی‌سازی و آزادسازی"

msgid "destructor tp_dealloc;"

msgstr "destructor tp_dealloc;"

msgid "This function is called when the reference count of the instance of your type is reduced to zero and the Python interpreter wants to reclaim it. If your type has memory to free or other clean-up to perform, you can put it here. The object itself needs to be freed here as well. Here is an example of this function::"

msgstr "این تابع زمانی فراخوانی می‌شود که شمارش ارجاع نمونه‌ی نوع شما به صفر کاهش یابد و مفسر پایتون بخواهد آن را بازپس‌گیری کند. اگر نوع شما حافظه‌ای برای آزاد کردن یا پاک‌سازی دیگری برای انجام دارد، می‌توانید آن را اینجا قرار دهید. خود شیء نیز باید در اینجا آزاد شود. در ادامه مثالی از این تابع آمده است::"

msgid ""

msgstr ""

msgid "If your type supports garbage collection, the destructor should call :c:func:`PyObject_GC_UnTrack` before clearing any member fields::"

msgstr "اگر نوع شما از زباله‌روبی پشتیبانی کند، مخرب باید پیش از پاک کردن هر یک از فیلدهای عضو، :c:func:`PyObject_GC_UnTrack` را فراخوانی کند::"

msgid ""

msgstr ""

msgid "One important requirement of the deallocator function is that it leaves any pending exceptions alone. This is important since deallocators are frequently called as the interpreter unwinds the Python stack; when the stack is unwound due to an exception (rather than normal returns), nothing is done to protect the deallocators from seeing that an exception has already been set. Any actions which a deallocator performs which may cause additional Python code to be executed may detect that an exception has been set. This can lead to misleading errors from the interpreter. The proper way to protect against this is to save a pending exception before performing the unsafe action, and restoring it when done. This can be done using the :c:func:`PyErr_Fetch` and :c:func:`PyErr_Restore` functions::"

msgstr "یکی از الزامات مهم تابع آزادساز حافظه این است که هرگونه استثنای در انتظار را دست‌نخورده بگذارد. این موضوع اهمیت دارد، زیرا آزادسازهای حافظه اغلب هنگام باز شدن پشته پایتون توسط مفسر فراخوانی می‌شوند؛ وقتی پشته به دلیل یک استثنا (و نه بازگشت‌های عادی) باز می‌شود، هیچ کنشی انجام نمی‌شود تا از آزادسازهای حافظه در برابر دیدن این موضوع که از پیش استثنایی تنظیم شده است محافظت شود. هر کنشی که آزادساز حافظه انجام می‌دهد و ممکن است باعث اجرای کد پایتون دیگری شود، ممکن است تشخیص دهد که استثنایی تنظیم شده است. این می‌تواند به خطاهای گمراه‌کننده از سوی مفسر منجر شود. راه درست برای محافظت در برابر این موضوع، ذخیره کردن استثنای در انتظار پیش از انجام کنش نا‌ایمن و بازگردانی آن پس از اتمام کار است. این کار را می‌توان با استفاده از توابع :c:func:`PyErr_Fetch` و :c:func:`PyErr_Restore` انجام داد::"

msgid ""

msgstr ""

msgid "There are limitations to what you can safely do in a deallocator function. First, if your type supports garbage collection (using :c:member:`~PyTypeObject.tp_traverse` and/or :c:member:`~PyTypeObject.tp_clear`), some of the object's members can have been cleared or finalized by the time :c:member:`~PyTypeObject.tp_dealloc` is called. Second, in :c:member:`~PyTypeObject.tp_dealloc`, your object is in an unstable state: its reference count is equal to zero. Any call to a non-trivial object or API (as in the example above) might end up calling :c:member:`~PyTypeObject.tp_dealloc` again, causing a double free and a crash."

msgstr "کارهایی که می‌توانید به‌طور ایمن در یک تابع آزادساز حافظه انجام دهید، محدودیت‌هایی دارد. نخست، اگر نوع شما از زباله‌روبی پشتیبانی کند (با استفاده از :c:member:`~PyTypeObject.tp_traverse` و/یا :c:member:`~PyTypeObject.tp_clear`)، ممکن است برخی از اعضای شیء تا زمانی که :c:member:`~PyTypeObject.tp_dealloc` فراخوانی می‌شود، پاک‌سازی یا نهایی‌سازی شده باشند. دوم، در :c:member:`~PyTypeObject.tp_dealloc`، شیء شما در وضعیتی ناپایدار قرار دارد: شمارش ارجاع آن برابر با صفر است. هر فراخوانی شیء یا API غیربدیهی (مانند مثال بالا) ممکن است در نهایت :c:member:`~PyTypeObject.tp_dealloc` را دوباره فراخوانی کند و موجب آزادسازی دوباره (double free) و فروپاشی شود."

msgid "Starting with Python 3.4, it is recommended not to put any complex finalization code in :c:member:`~PyTypeObject.tp_dealloc`, and instead use the new :c:member:`~PyTypeObject.tp_finalize` type method."

msgstr "از پایتون 3.4 به بعد، توصیه می‌شود هیچ کد نهایی‌سازی پیچیده‌ای در :c:member:`~PyTypeObject.tp_dealloc` قرار ندهید و در عوض از متد نوع جدید :c:member:`~PyTypeObject.tp_finalize` استفاده کنید."

msgid ":pep:`442` explains the new finalization scheme."

msgstr ":pep:`442` طرح جدید نهایی‌سازی را توضیح می‌دهد."

msgid "Object Presentation"

msgstr "نمایش شیء"

msgid "In Python, there are two ways to generate a textual representation of an object: the :func:`repr` function, and the :func:`str` function. (The :func:`print` function just calls :func:`str`.) These handlers are both optional."

msgstr "در پایتون، دو راه برای تولید نمایش متنی یک شیء وجود دارد: تابع :func:`repr` و تابع :func:`str`. (تابع :func:`print` فقط :func:`str` را فراخوانی می‌کند.) این هندلرها هر دو اختیاری هستند."

msgid ""

msgstr ""

msgid "The :c:member:`~PyTypeObject.tp_repr` handler should return a string object containing a representation of the instance for which it is called. Here is a simple example::"

msgstr "هندلر :c:member:`~PyTypeObject.tp_repr` باید یک شیء رشته را برگرداند که حاوی نمایشی از نمونه‌ای باشد که برای آن فراخوانی می‌شود. در اینجا یک مثال ساده آمده است::"

msgid ""

msgstr ""

msgid "If no :c:member:`~PyTypeObject.tp_repr` handler is specified, the interpreter will supply a representation that uses the type's :c:member:`~PyTypeObject.tp_name` and a uniquely identifying value for the object."

msgstr "اگر هیچ هندلر :c:member:`~PyTypeObject.tp_repr` تعیین نشده باشد، مفسر بازنمایی‌ای را فراهم می‌کند که از :c:member:`~PyTypeObject.tp_name` نوع و مقداری که به‌طور یکتا شیء را شناسایی می‌کند، به کار می‌گیرد."

msgid "The :c:member:`~PyTypeObject.tp_str` handler is to :func:`str` what the :c:member:`~PyTypeObject.tp_repr` handler described above is to :func:`repr`; that is, it is called when Python code calls :func:`str` on an instance of your object. Its implementation is very similar to the :c:member:`~PyTypeObject.tp_repr` function, but the resulting string is intended for human consumption. If :c:member:`~PyTypeObject.tp_str` is not specified, the :c:member:`~PyTypeObject.tp_repr` handler is used instead."

msgstr "هندلر :c:member:`~PyTypeObject.tp_str` برای :func:`str` همان است که هندلر :c:member:`~PyTypeObject.tp_repr` که در بالا توضیح داده شد برای :func:`repr` است؛ یعنی زمانی فراخوانی می‌شود که کد پایتون :func:`str` را روی نمونه‌ای از شیء شما فراخوانی کند. پیاده‌سازی آن بسیار شبیه تابع :c:member:`~PyTypeObject.tp_repr` است، اما رشته‌ی حاصل برای خواندن توسط انسان در نظر گرفته شده است. اگر :c:member:`~PyTypeObject.tp_str` مشخص نشده باشد، از هندلر :c:member:`~PyTypeObject.tp_repr` استفاده می‌شود."

msgid "Here is a simple example::"

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

msgid ""

msgstr ""

msgid "Attribute Management"

msgstr "مدیریت ویژگی"

msgid "For every object which can support attributes, the corresponding type must provide the functions that control how the attributes are resolved. There needs to be a function which can retrieve attributes (if any are defined), and another to set attributes (if setting attributes is allowed). Removing an attribute is a special case, for which the new value passed to the handler is ``NULL``."

msgstr "برای هر شیء که می‌تواند از ویژگی‌ها پشتیبانی کند، نوع متناظر باید توابعی را فراهم کند که کنترل می‌کنند ویژگی‌ها چگونه حل می‌شوند. باید تابعی وجود داشته باشد که بتواند ویژگی‌ها را بازیابی کند (در صورتی که ویژگی‌ای تعریف‌شده باشد)، و تابع دیگری برای تنظیم ویژگی‌ها (در صورتی که تنظیم ویژگی‌ها مجاز باشد). حذف یک ویژگی حالت خاصی است که در آن مقدار جدیدِ منتقل‌شده به هندلر ``NULL`` است."

msgid "Python supports two pairs of attribute handlers; a type that supports attributes only needs to implement the functions for one pair. The difference is that one pair takes the name of the attribute as a :c:expr:`char\\*`, while the other accepts a :c:expr:`PyObject*`. Each type can use whichever pair makes more sense for the implementation's convenience. ::"

msgstr "پایتون از دو جفت هندلر ویژگی پشتیبانی می‌کند؛ نوعی که از ویژگی‌ها پشتیبانی می‌کند، تنها باید توابع یکی از این جفت‌ها را پیاده‌سازی کند. تفاوت این است که یک جفت، نام ویژگی را به‌صورت :c:expr:`char\\*` می‌گیرد، در حالی که جفت دیگر :c:expr:`PyObject*` را می‌پذیرد. هر نوع می‌تواند از هر جفتی که برای راحتی پیاده‌سازی منطقی‌تر باشد استفاده کند. ::"

msgid ""

msgstr ""

msgid "If accessing attributes of an object is always a simple operation (this will be explained shortly), there are generic implementations which can be used to provide the :c:expr:`PyObject*` version of the attribute management functions. The actual need for type-specific attribute handlers almost completely disappeared starting with Python 2.2, though there are many examples which have not been updated to use some of the new generic mechanism that is available."

msgstr "اگر دسترسی به ویژگی‌های یک شیء همیشه یک عملیات ساده باشد (این موضوع در ادامه توضیح داده خواهد شد)، پیاده‌سازی‌های عامی وجود دارند که می‌توان از آن‌ها برای ارائه نسخه‌ی :c:expr:`PyObject*` از توابع مدیریت ویژگی استفاده کرد. نیاز واقعی به هندلرهای ویژگی مخصوص نوع، از پایتون 2.2 به بعد تقریباً به‌طور کامل از بین رفت، هرچند مثال‌های زیادی برای استفاده از برخی از سازوکارهای عام جدیدِ موجود به‌روزرسانی نشده‌اند."

msgid "Generic Attribute Management"

msgstr "مدیریت عام ویژگی"

msgid "Most extension types only use *simple* attributes. So, what makes the attributes simple? There are only a couple of conditions that must be met:"

msgstr "بیشتر نوع‌های توسعه‌ای تنها از ویژگی‌های *ساده* استفاده می‌کنند. پس، چه چیزی ویژگی‌ها را ساده می‌کند؟ تنها چند شرط وجود دارد که باید برآورده شوند:"

msgid "The name of the attributes must be known when :c:func:`PyType_Ready` is called."

msgstr "نام ویژگی‌ها باید هنگامی که :c:func:`PyType_Ready` فراخوانی می‌شود، مشخص باشد."

msgid "No special processing is needed to record that an attribute was looked up or set, nor do actions need to be taken based on the value."

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

msgid "Note that this list does not place any restrictions on the values of the attributes, when the values are computed, or how relevant data is stored."

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

msgid "When :c:func:`PyType_Ready` is called, it uses three tables referenced by the type object to create :term:`descriptor`\\s which are placed in the dictionary of the type object. Each descriptor controls access to one attribute of the instance object. Each of the tables is optional; if all three are ``NULL``, instances of the type will only have attributes that are inherited from their base type, and should leave the :c:member:`~PyTypeObject.tp_getattro` and :c:member:`~PyTypeObject.tp_setattro` fields ``NULL`` as well, allowing the base type to handle attributes."

msgstr "وقتی :c:func:`PyType_Ready` فراخوانی می‌شود، از سه جدولی که شیء نوع به آن‌ها ارجاع می‌دهد برای ایجاد :term:`توصیف‌گر <descriptor>`\\هایی که در دیکشنری شیء نوع قرار می‌گیرند استفاده می‌کند. هر توصیف‌گر دسترسی به یک ویژگی از شیء نمونه را کنترل می‌کند. هر یک از این جدول‌ها اختیاری است؛ اگر هر سه ``NULL`` باشند، نمونه‌های این نوع فقط ویژگی‌هایی را خواهند داشت که از نوع پایه خود به ارث برده‌اند، و فیلدهای :c:member:`~PyTypeObject.tp_getattro` و :c:member:`~PyTypeObject.tp_setattro` نیز باید ``NULL`` باقی بمانند تا نوع پایه بتواند ویژگی‌ها را مدیریت کند."

msgid "The tables are declared as three fields of the type object::"

msgstr "جدول‌ها به‌عنوان سه فیلد از شیء نوع اعلان می‌شوند::"

msgid ""

msgstr ""

msgid "If :c:member:`~PyTypeObject.tp_methods` is not ``NULL``, it must refer to an array of :c:type:`PyMethodDef` structures. Each entry in the table is an instance of this structure::"

msgstr "اگر :c:member:`~PyTypeObject.tp_methods` برابر ``NULL`` نباشد، باید به آرایه‌ای از ساختارهای :c:type:`PyMethodDef` اشاره کند. هر ورودی جدول نمونه‌ای از این ساختار است::"

msgid ""

msgstr ""

msgid "One entry should be defined for each method provided by the type; no entries are needed for methods inherited from a base type. One additional entry is needed at the end; it is a sentinel that marks the end of the array. The :c:member:`~PyMethodDef.ml_name` field of the sentinel must be ``NULL``."

msgstr "برای هر متدی که توسط نوع ارائه می‌شود، باید یک ورودی تعریف شود؛ برای متدهایی که از یک نوع پایه به ارث رسیده‌اند، نیازی به ورودی نیست. در انتها، به یک ورودی اضافی نیاز است؛ این ورودی یک نشانگر است که پایان آرایه را مشخص می‌کند. فیلد :c:member:`~PyMethodDef.ml_name` نشانگر باید ``NULL`` باشد."

msgid "The second table is used to define attributes which map directly to data stored in the instance. A variety of primitive C types are supported, and access may be read-only or read-write. The structures in the table are defined as::"

msgstr "از جدول دوم برای تعریف ویژگی‌هایی استفاده می‌شود که مستقیماً به داده‌های ذخیره‌شده در نمونه نگاشت می‌شوند. انواع مختلفی از نوع‌های اولیه‌ی C پشتیبانی می‌شوند و دسترسی می‌تواند فقط‌خواندنی یا خواندنی-نوشتنی باشد. ساختارهای موجود در جدول به صورت زیر تعریف می‌شوند::"

msgid ""

msgstr ""

msgid "For each entry in the table, a :term:`descriptor` will be constructed and added to the type which will be able to extract a value from the instance structure. The :c:member:`~PyMemberDef.type` field should contain a type code like :c:macro:`Py_T_INT` or :c:macro:`Py_T_DOUBLE`; the value will be used to determine how to convert Python values to and from C values. The :c:member:`~PyMemberDef.flags` field is used to store flags which control how the attribute can be accessed: you can set it to :c:macro:`Py_READONLY` to prevent Python code from setting it."

msgstr "برای هر ورودی در جدول، یک :term:`توصیف‌گر <descriptor>` ساخته و به نوع اضافه می‌شود که قادر خواهد بود مقداری را از ساختار نمونه استخراج کند. فیلد :c:member:`~PyMemberDef.type` باید حاوی کد نوعی مانند :c:macro:`Py_T_INT` یا :c:macro:`Py_T_DOUBLE` باشد؛ این مقدار برای تعیین نحوه‌ی تبدیل مقادیر پایتون به مقادیر C و بالعکس استفاده خواهد شد. فیلد :c:member:`~PyMemberDef.flags` برای ذخیره‌ی پرچم‌هایی استفاده می‌شود که نحوه‌ی دسترسی به ویژگی را کنترل می‌کنند: می‌توانید آن را روی :c:macro:`Py_READONLY` تنظیم کنید تا کد پایتون نتواند آن را مقداردهی کند."

msgid "An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` table to build descriptors that are used at runtime is that any attribute defined this way can have an associated doc string simply by providing the text in the table. An application can use the introspection API to retrieve the descriptor from the class object, and get the doc string using its :attr:`~type.__doc__` attribute."

msgstr "مزیت جالب استفاده از جدول :c:member:`~PyTypeObject.tp_members` برای ساخت توصیف‌گرهایی که در ران‌تایم استفاده می‌شوند این است که هر ویژگی که به این روش تعریف شود، می‌تواند صرفاً با ارائه‌ی متن در جدول، یک رشته مستند مرتبط داشته باشد. یک برنامه می‌تواند از API درون‌نگری برای بازیابی توصیف‌گر از شیء کلاس استفاده کند و رشته مستند را با استفاده از ویژگی :attr:`~type.__doc__` آن به دست آورد."

msgid "As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :c:member:`~PyMethodDef.ml_name` value of ``NULL`` is required."

msgstr "مانند جدول :c:member:`~PyTypeObject.tp_methods`، یک ورودی نشانگر که مقدار :c:member:`~PyMethodDef.ml_name` آن ``NULL`` است، لازم است."

msgid "Type-specific Attribute Management"

msgstr "مدیریت ویژگی‌های مخصوص به نوع"

msgid "For simplicity, only the :c:expr:`char\\*` version will be demonstrated here; the type of the name parameter is the only difference between the :c:expr:`char\\*` and :c:expr:`PyObject*` flavors of the interface. This example effectively does the same thing as the generic example above, but does not use the generic support added in Python 2.2. It explains how the handler functions are called, so that if you do need to extend their functionality, you'll understand what needs to be done."

msgstr "برای سادگی، در اینجا فقط نسخه‌ی :c:expr:`char\\*` نمایش داده خواهد شد؛ نوع پارامتر name تنها تفاوت بین گونه‌های :c:expr:`char\\*` و :c:expr:`PyObject*` رابط است. این مثال عملاً همان کاری را انجام می‌دهد که مثال عام بالا انجام می‌دهد، اما از پشتیبانی عام افزوده‌شده در Python 2.2 استفاده نمی‌کند. این مثال توضیح می‌دهد که توابع هندلر چگونه فراخوانی می‌شوند، تا اگر به‌راستی نیاز به گسترش قابلیت‌های آن‌ها داشته باشید، بفهمید چه کاری باید انجام شود."

msgid "The :c:member:`~PyTypeObject.tp_getattr` handler is called when the object requires an attribute look-up. It is called in the same situations where the :meth:`~object.__getattr__` method of a class would be called."

msgstr "هندلر :c:member:`~PyTypeObject.tp_getattr` زمانی فراخوانی می‌شود که شیء به جست‌وجوی ویژگی نیاز داشته باشد. این هندلر در همان موقعیت‌هایی فراخوانی می‌شود که متد :meth:`~object.__getattr__` یک کلاس فراخوانی می‌شود."

msgid "Here is an example::"

msgstr "در ادامه یک مثال آمده است::"

msgid ""

msgstr ""

msgid "The :c:member:`~PyTypeObject.tp_setattr` handler is called when the :meth:`~object.__setattr__` or :meth:`~object.__delattr__` method of a class instance would be called. When an attribute should be deleted, the third parameter will be ``NULL``. Here is an example that simply raises an exception; if this were really all you wanted, the :c:member:`~PyTypeObject.tp_setattr` handler should be set to ``NULL``. ::"

msgstr "هندلر :c:member:`~PyTypeObject.tp_setattr` زمانی فراخوانی می‌شود که قرار باشد متد :meth:`~object.__setattr__` یا :meth:`~object.__delattr__` یک نمونه‌ی کلاس فراخوانی شود. وقتی ویژگی‌ای باید حذف شود، پارامتر سوم ``NULL`` خواهد بود. در ادامه مثالی آمده است که صرفاً یک استثنا ایجاد می‌کند؛ اگر واقعاً همین تمام چیزی بود که می‌خواستید، هندلر :c:member:`~PyTypeObject.tp_setattr` باید روی ``NULL`` تنظیم شود. ::"

msgid ""

msgstr ""

msgid "Object Comparison"

msgstr "مقایسه‌ی شیء"

msgid "richcmpfunc tp_richcompare;"

msgstr "richcmpfunc tp_richcompare;"

msgid "The :c:member:`~PyTypeObject.tp_richcompare` handler is called when comparisons are needed. It is analogous to the :ref:`rich comparison methods <richcmpfuncs>`, like :meth:`!__lt__`, and also called by :c:func:`PyObject_RichCompare` and :c:func:`PyObject_RichCompareBool`."

msgstr "هندلر :c:member:`~PyTypeObject.tp_richcompare` زمانی فراخوانی می‌شود که به مقایسه نیاز باشد. این هندلر مشابه :ref:`متدهای مقایسه‌ی غنی (rich comparison) <richcmpfuncs>` مانند :meth:`!__lt__` است و همچنین توسط :c:func:`PyObject_RichCompare` و :c:func:`PyObject_RichCompareBool` فراخوانی می‌شود."

msgid "This function is called with two Python objects and the operator as arguments, where the operator is one of ``Py_EQ``, ``Py_NE``, ``Py_LE``, ``Py_GE``, ``Py_LT`` or ``Py_GT``. It should compare the two objects with respect to the specified operator and return ``Py_True`` or ``Py_False`` if the comparison is successful, ``Py_NotImplemented`` to indicate that comparison is not implemented and the other object's comparison method should be tried, or ``NULL`` if an exception was set."

msgstr "این تابع با دو شیء پایتون و عملگر به‌عنوان آرگومان فراخوانی می‌شود، که در آن عملگر یکی از ``Py_EQ``، ``Py_NE``، ``Py_LE``، ``Py_GE``، ``Py_LT`` یا ``Py_GT`` است. این تابع باید دو شیء را با توجه به عملگر مشخص‌شده مقایسه کند و در صورت موفقیت مقایسه، ``Py_True`` یا ``Py_False`` را برگرداند، ``Py_NotImplemented`` را برای نشان دادن این‌که مقایسه پیاده‌سازی نشده و باید متد مقایسه شیء دیگر امتحان شود، یا ``NULL`` را در صورتی که استثنایی تنظیم شده باشد."

msgid "Here is a sample implementation, for a datatype that is considered equal if the size of an internal pointer is equal::"

msgstr "در اینجا یک پیاده‌سازی نمونه برای یک نوع داده آمده است که در صورتی برابر در نظر گرفته می‌شود که اندازه‌ی اشاره‌گر داخلی‌اش برابر باشد::"

msgid ""

msgstr ""

msgid "Abstract Protocol Support"

msgstr "پشتیبانی از پروتکل انتزاعی"

msgid "Python supports a variety of *abstract* 'protocols;' the specific interfaces provided to use these interfaces are documented in :ref:`abstract`."

msgstr "پایتون انواع مختلفی از «پروتکل‌های *انتزاعی*» را پشتیبانی می‌کند؛ رابط‌های مشخصی که برای استفاده از این رابط‌ها فراهم شده‌اند، در :ref:`abstract` مستند شده‌اند."

msgid "A number of these abstract interfaces were defined early in the development of the Python implementation. In particular, the number, mapping, and sequence protocols have been part of Python since the beginning. Other protocols have been added over time. For protocols which depend on several handler routines from the type implementation, the older protocols have been defined as optional blocks of handlers referenced by the type object. For newer protocols there are additional slots in the main type object, with a flag bit being set to indicate that the slots are present and should be checked by the interpreter. (The flag bit does not indicate that the slot values are non-``NULL``. The flag may be set to indicate the presence of a slot, but a slot may still be unfilled.) ::"

msgstr "تعدادی از این رابط‌های انتزاعی در اوایل توسعه‌ی پیاده‌سازی پایتون تعریف شدند. به‌طور خاص، پروتکل‌های عدد، نگاشت و دنباله از همان ابتدا بخشی از پایتون بوده‌اند. پروتکل‌های دیگر به مرور زمان اضافه شده‌اند. برای پروتکل‌هایی که به چند روال هندلر از پیاده‌سازی نوع وابسته‌اند، پروتکل‌های قدیمی‌تر به‌صورت بلوک‌های اختیاری از هندلرها تعریف شده‌اند که شیء نوع به آن‌ها ارجاع می‌دهد. برای پروتکل‌های جدیدتر، جایگاه‌های اضافی در شیء نوع اصلی وجود دارند و یک بیت پرچم تنظیم می‌شود تا نشان دهد که این جایگاه‌ها موجودند و باید توسط مفسر بررسی شوند. (بیت پرچم نشان نمی‌دهد که مقادیر جایگاه‌ها غیر ``NULL`` هستند. ممکن است پرچم برای نشان دادن وجود یک جایگاه تنظیم شده باشد، اما جایگاه همچنان پرنشده باشد.) ::"

msgid ""

msgstr ""

msgid "If you wish your object to be able to act like a number, a sequence, or a mapping object, then you place the address of a structure that implements the C type :c:type:`PyNumberMethods`, :c:type:`PySequenceMethods`, or :c:type:`PyMappingMethods`, respectively. It is up to you to fill in this structure with appropriate values. You can find examples of the use of each of these in the :file:`Objects` directory of the Python source distribution. ::"

msgstr "اگر می‌خواهید شیء شما بتواند مانند یک عدد، یک دنباله یا یک شیء نگاشت رفتار کند، آدرس ساختاری را که به‌ترتیب نوع C :c:type:`PyNumberMethods`، :c:type:`PySequenceMethods` یا :c:type:`PyMappingMethods` را پیاده‌سازی می‌کند، قرار می‌دهید. پر کردن این ساختار با مقدارهای مناسب بر عهده شماست. می‌توانید نمونه‌هایی از استفاده از هر یک از این‌ها را در پوشه :file:`Objects` توزیع کد منبع پایتون بیابید. ::"

msgid "hashfunc tp_hash;"

msgstr "hashfunc tp_hash;"

msgid "This function, if you choose to provide it, should return a hash number for an instance of your data type. Here is a simple example::"

msgstr "این تابع، اگر بخواهید آن را ارائه کنید، باید یک عدد هش برای نمونه‌ای از نوع داده‌ی شما بازگرداند. در اینجا یک مثال ساده آمده است::"

msgid ""

msgstr ""

msgid ":c:type:`Py_hash_t` is a signed integer type with a platform-varying width. Returning ``-1`` from :c:member:`~PyTypeObject.tp_hash` indicates an error, which is why you should be careful to avoid returning it when hash computation is successful, as seen above."

msgstr ":c:type:`Py_hash_t` یک نوع عدد صحیح علامت‌دار با پهنای متغیر بر اساس پلتفرم است. برگرداندن ``-1`` از :c:member:`~PyTypeObject.tp_hash` نشان‌دهنده‌ی خطا است؛ به همین دلیل باید مراقب باشید تا در صورت موفقیت‌آمیز بودن محاسبه‌ی هش، آن را برنگردانید، همان‌طور که در بالا مشاهده کردید."

msgid "ternaryfunc tp_call;"

msgstr "ternaryfunc tp_call;"

msgid "This function is called when an instance of your data type is \"called\", for example, if ``obj1`` is an instance of your data type and the Python script contains ``obj1('hello')``, the :c:member:`~PyTypeObject.tp_call` handler is invoked."

msgstr "این تابع زمانی فراخوانی می‌شود که نمونه‌ای از نوع داده شما «فراخوانی» شود؛ برای مثال، اگر ``obj1`` نمونه‌ای از نوع داده شما باشد و اسکریپت پایتون شامل ``obj1('hello')`` باشد، هندلر :c:member:`~PyTypeObject.tp_call` فراخوانی می‌شود."

msgid "This function takes three arguments:"

msgstr "این تابع سه آرگومان می‌گیرد:"

msgid "*self* is the instance of the data type which is the subject of the call. If the call is ``obj1('hello')``, then *self* is ``obj1``."

msgstr "*self* نمونه‌ای از نوع داده است که موضوع فراخوانی است. اگر فراخوانی ``obj1('hello')`` باشد، آنگاه *self* همان ``obj1`` است."

msgid "*args* is a tuple containing the arguments to the call. You can use :c:func:`PyArg_ParseTuple` to extract the arguments."

msgstr "*args* تاپلی است که آرگومان‌های فراخوانی را در بر دارد. می‌توانید از :c:func:`PyArg_ParseTuple` برای استخراج آرگومان‌ها استفاده کنید."

msgid "*kwds* is a dictionary of keyword arguments that were passed. If this is non-``NULL`` and you support keyword arguments, use :c:func:`PyArg_ParseTupleAndKeywords` to extract the arguments. If you do not want to support keyword arguments and this is non-``NULL``, raise a :exc:`TypeError` with a message saying that keyword arguments are not supported."

msgstr "*kwds* یک دیکشنری از آرگومان‌های کلیدواژه‌ای است که ارسال شده‌اند. اگر این مقدار غیر ``NULL`` باشد و شما از آرگومان‌های کلیدواژه‌ای پشتیبانی می‌کنید، برای استخراج آرگومان‌ها از :c:func:`PyArg_ParseTupleAndKeywords` استفاده کنید. اگر نمی‌خواهید از آرگومان‌های کلیدواژه‌ای پشتیبانی کنید و این مقدار غیر ``NULL`` باشد، یک :exc:`TypeError` با پیامی که می‌گوید آرگومان‌های کلیدواژه‌ای پشتیبانی نمی‌شوند ایجاد کنید."

msgid "Here is a toy ``tp_call`` implementation::"

msgstr "در ادامه، یک پیاده‌سازی ساده از ``tp_call`` آمده است::"

msgid ""

msgstr ""

msgid ""

msgstr ""

msgid "These functions provide support for the iterator protocol. Both handlers take exactly one parameter, the instance for which they are being called, and return a new reference. In the case of an error, they should set an exception and return ``NULL``. :c:member:`~PyTypeObject.tp_iter` corresponds to the Python :meth:`~object.__iter__` method, while :c:member:`~PyTypeObject.tp_iternext` corresponds to the Python :meth:`~iterator.__next__` method."

msgstr "این توابع از پروتکل پیمایش‌گر پشتیبانی می‌کنند. هر دو هندلر دقیقاً یک پارامتر می‌گیرند — نمونه‌ای که برای آن فراخوانی می‌شوند — و یک ارجاع جدید برمی‌گردانند. در صورت خطا، باید یک استثنا تنظیم کنند و ``NULL`` را برگردانند. :c:member:`~PyTypeObject.tp_iter` با متد :meth:`~object.__iter__` پایتون متناظر است، در حالی که :c:member:`~PyTypeObject.tp_iternext` با متد :meth:`~iterator.__next__` پایتون متناظر است."

msgid "Any :term:`iterable` object must implement the :c:member:`~PyTypeObject.tp_iter` handler, which must return an :term:`iterator` object. Here the same guidelines apply as for Python classes:"

msgstr "هر شیء :term:`iterable` باید هندلر :c:member:`~PyTypeObject.tp_iter` را پیاده‌سازی کند که باید یک شیء :term:`iterator` را برگرداند. در اینجا همان دستورالعمل‌های مربوط به کلاس‌های پایتون اعمال می‌شود:"

msgid "For collections (such as lists and tuples) which can support multiple independent iterators, a new iterator should be created and returned by each call to :c:member:`~PyTypeObject.tp_iter`."

msgstr "برای کلکسیون‌هایی (مانند فهرست‌ها و تاپل‌ها) که می‌توانند از چندین پیمایش‌گر مستقل پشتیبانی کنند، باید با هر فراخوانی :c:member:`~PyTypeObject.tp_iter` یک پیمایش‌گر جدید ایجاد و برگردانده شود."

msgid "Objects which can only be iterated over once (usually due to side effects of iteration, such as file objects) can implement :c:member:`~PyTypeObject.tp_iter` by returning a new reference to themselves -- and should also therefore implement the :c:member:`~PyTypeObject.tp_iternext` handler."

msgstr "اشیایی که تنها یک بار می‌توان آن‌ها را پیمایش کرد (معمولاً به دلیل اثرات جانبی پیمایش، مانند اشیای پرونده) می‌توانند :c:member:`~PyTypeObject.tp_iter` را با بازگرداندن یک ارجاع جدید به خودشان پیاده‌سازی کنند -- و بنابراین باید هندلر :c:member:`~PyTypeObject.tp_iternext` را نیز پیاده‌سازی کنند."

msgid "Any :term:`iterator` object should implement both :c:member:`~PyTypeObject.tp_iter` and :c:member:`~PyTypeObject.tp_iternext`. An iterator's :c:member:`~PyTypeObject.tp_iter` handler should return a new reference to the iterator. Its :c:member:`~PyTypeObject.tp_iternext` handler should return a new reference to the next object in the iteration, if there is one. If the iteration has reached the end, :c:member:`~PyTypeObject.tp_iternext` may return ``NULL`` without setting an exception, or it may set :exc:`StopIteration` *in addition* to returning ``NULL``; avoiding the exception can yield slightly better performance. If an actual error occurs, :c:member:`~PyTypeObject.tp_iternext` should always set an exception and return ``NULL``."

msgstr "هر شیء :term:`iterator` باید هم :c:member:`~PyTypeObject.tp_iter` و هم :c:member:`~PyTypeObject.tp_iternext` را پیاده‌سازی کند. هندلر :c:member:`~PyTypeObject.tp_iter` در یک پیمایش‌گر باید ارجاع جدیدی به پیمایش‌گر برگرداند. هندلر :c:member:`~PyTypeObject.tp_iternext` آن باید در صورت وجود، ارجاع جدیدی به شیء بعدی در پیمایش برگرداند. اگر پیمایش به پایان رسیده باشد، :c:member:`~PyTypeObject.tp_iternext` می‌تواند بدون تنظیم استثنا ``NULL`` برگرداند، یا *علاوه بر* برگرداندن ``NULL``، :exc:`StopIteration` را تنظیم کند؛ پرهیز از استثنا می‌تواند به کارایی کمی بهتر منجر شود. اگر خطای واقعی رخ دهد، :c:member:`~PyTypeObject.tp_iternext` باید همیشه یک استثنا تنظیم کند و ``NULL`` برگرداند."

msgid "Weak Reference Support"

msgstr "پشتیبانی از ارجاع ضعیف"

msgid "One of the goals of Python's weak reference implementation is to allow any type to participate in the weak reference mechanism without incurring the overhead on performance-critical objects (such as numbers)."

msgstr "یکی از اهداف پیاده‌سازی ارجاع ضعیف در پایتون این است که به هر نوعی اجازه دهد در سازوکار ارجاع ضعیف شرکت کند، بدون آنکه سرباری بر شیءهای حساس به کارایی (مانند اعداد) تحمیل شود."

msgid "Documentation for the :mod:`weakref` module."

msgstr "مستندات ماژول :mod:`weakref`."

msgid "For an object to be weakly referenceable, the extension type must set the ``Py_TPFLAGS_MANAGED_WEAKREF`` bit of the :c:member:`~PyTypeObject.tp_flags` field. The legacy :c:member:`~PyTypeObject.tp_weaklistoffset` field should be left as zero."

msgstr "برای اینکه بتوان به یک شیء ارجاع ضعیف داد، نوع توسعه‌ای باید بیت ``Py_TPFLAGS_MANAGED_WEAKREF`` را در فیلد :c:member:`~PyTypeObject.tp_flags` تنظیم کند. فیلد قدیمی :c:member:`~PyTypeObject.tp_weaklistoffset` باید صفر باقی بماند."

msgid "If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` should also be set."

msgstr "اگر این پرچم تنظیم شده باشد، :c:macro:`Py_TPFLAGS_HAVE_GC` نیز باید تنظیم شود."

msgid "Concretely, here is how the statically declared type object would look::"

msgstr "به‌طور مشخص، شیء نوعِ به‌صورت ایستا اعلان‌شده به این شکل خواهد بود::"

msgid ""

msgstr ""

msgid "The only further addition is that ``tp_dealloc`` needs to clear any weak references (by calling :c:func:`PyObject_ClearWeakRefs`)::"

msgstr "تنها مورد دیگری که باید اضافه شود این است که ``tp_dealloc`` باید هر ارجاع ضعیفی را پاک کند (با فراخوانی :c:func:`PyObject_ClearWeakRefs`)::"

msgid ""

msgstr ""

msgid "More Suggestions"

msgstr "پیشنهادهای بیشتر"

msgid "In order to learn how to implement any specific method for your new data type, get the :term:`CPython` source code. Go to the :file:`Objects` directory, then search the C source files for ``tp_`` plus the function you want (for example, ``tp_richcompare``). You will find examples of the function you want to implement."

msgstr "برای یادگیری نحوه‌ی پیاده‌سازی هر متد ویژه برای نوع داده‌ی جدید خود، کد منبع :term:`CPython` را دریافت کنید. به پوشه‌ی :file:`Objects` بروید، سپس در پرونده‌های منبع C به دنبال ``tp_`` به‌علاوه‌ی تابعی که می‌خواهید بگردید (برای مثال، ``tp_richcompare``). نمونه‌هایی از تابعی که می‌خواهید پیاده‌سازی کنید را خواهید یافت."

msgid "When you need to verify that an object is a concrete instance of the type you are implementing, use the :c:func:`PyObject_TypeCheck` function. A sample of its use might be something like the following::"

msgstr "هنگامی که نیاز دارید بررسی کنید که یک شیء، نمونه‌ی عینی نوعی است که پیاده‌سازی می‌کنید، از تابع :c:func:`PyObject_TypeCheck` استفاده کنید. نمونه‌ای از کاربرد آن می‌تواند چیزی شبیه به موارد زیر باشد::"

msgid ""

msgstr ""

msgid "Download CPython source releases."

msgstr "دانلود نسخه‌های کد منبع سی‌پایتون."

msgid "https://www.python.org/downloads/source/"

msgstr "https://www.python.org/downloads/source/"

msgid "The CPython project on GitHub, where the CPython source code is developed."

msgstr "پروژه‌ی سی‌پایتون در GitHub، جایی که کد منبع سی‌پایتون در آن توسعه داده می‌شود."

msgid "https://github.com/python/cpython"

msgstr "https://github.com/python/cpython"

msgid "object"

msgstr "شیء"

msgid "deallocation"

msgstr "آزادسازی"

msgid "deallocation, object"

msgstr "آزادسازی، شیء"

msgid "finalization"

msgstr "نهایی‌سازی"

msgid "finalization, of objects"

msgstr "نهایی‌سازی، از اشیاء"

msgid "PyErr_Fetch (C function)"

msgstr "PyErr_Fetch (تابع C)"

msgid "PyErr_Restore (C function)"

msgstr "PyErr_Restore (تابع C)"

msgid "string"

msgstr "رشته"

msgid "object representation"

msgstr "نمایش شیء"

msgid "built-in function"

msgstr "تابع توکار"

msgid "repr"

msgstr "repr"