annotationlib.po

# Persian translations for Python package.
# Copyright (C) 2001 Python Software Foundation
# This file is distributed under the same license as the Python package.
# Automatically generated, 2026.
#
# Translators:
# 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-21 11:59+0000\n"
"PO-Revision-Date: 2026-09-13 16:52+0330\n"
"Last-Translator: Sepehr Rasouli <sepehrrasouli06@gmail.com>, 2026\n"
"Language-Team: none\n"
"Language: fa\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"X-Generator: Poedit 3.6\n"

msgid ":mod:`!annotationlib` --- Functionality for introspecting annotations"
msgstr ":mod:`!annotationlib` --- امکاناتی برای درون‌نگری حاشیه‌نویسی‌ها"

msgid "**Source code:** :source:`Lib/annotationlib.py`"
msgstr "**کد منبع:** :source:`Lib/annotationlib.py`"

msgid "The :mod:`!annotationlib` module provides tools for introspecting :term:`annotations <annotation>` on modules, classes, and functions."
msgstr "ماژول :mod:`!annotationlib` ابزارهایی را برای درون‌نگری :term:`حاشیه‌نویسی‌ها <annotation>` بر روی ماژول‌ها، کلاس‌ها و توابع فراهم می‌کند."

msgid "Annotations are :ref:`lazily evaluated <lazy-evaluation>` and often contain forward references to objects that are not yet defined when the annotation is created. This module provides a set of low-level tools that can be used to retrieve annotations in a reliable way, even in the presence of forward references and other edge cases."
msgstr "حاشیه‌گذاری‌ها  :ref:`به‌صورت تنبل ارزیابی می‌شوند <lazy-evaluation>` و اغلب شامل ارجاع پیشرو به اشیایی هستند که هنوز در زمان ایجاد حاشیه‌گذاری تعریف نشده‌اند. این ماژول مجموعه‌ای از ابزارهای سطح پایین را فراهم می‌کند که می‌توان از آن‌ها برای بازیابی حاشیه‌گذاری‌ها به‌صورت قابل‌اعتماد استفاده کرد، حتی در صورت وجود ارجاع‌های پیشرو و سایر موارد مرزی."

msgid "This module supports retrieving annotations in three main formats (see :class:`Format`), each of which works best for different use cases:"
msgstr "این ماژول از بازیابی حاشیه‌نویسی‌ها در ۳ قالب اصلی پشتیبانی می‌کند (به :class:`Format` مراجعه کنید)، که هر کدام برای موارد استفاده‌ی متفاوتی مناسب‌تر است:"

msgid ":attr:`~Format.VALUE` evaluates the annotations and returns their value. This is most straightforward to work with, but it may raise errors, for example if the annotations contain references to undefined names."
msgstr ":attr:`~Format.VALUE` حاشیه‌نویسی‌ها را ارزیابی می‌کند و مقدار آن‌ها را برمی‌گرداند. کار با این گزینه از همه ساده‌تر است، اما ممکن است خطاها را پرتاب کند، برای مثال اگر حاشیه‌نویسی‌ها شامل ارجاع به نام‌های تعریف‌نشده باشند."

msgid ":attr:`~Format.FORWARDREF` returns :class:`ForwardRef` objects for annotations that cannot be resolved, allowing you to inspect the annotations without evaluating them. This is useful when you need to work with annotations that may contain unresolved forward references."
msgstr ":attr:`~Format.FORWARDREF` برای حاشیه‌نویسی‌هاییکه قابل حل نیستند، اشیای :class:`ForwardRef` را برمی‌گرداند و به شما امکان می‌دهد حاشیه‌نویسی‌ها را بدون ارزیابی بررسی کنید. این حالت زمانی مفید است که نیاز داشته باشید با حاشیه‌نویسی‌هایی کار کنید که ممکن است حاوی ارجاع‌های پیشروی حل‌نشده باشند."

msgid ":attr:`~Format.STRING` returns the annotations as a string, similar to how it would appear in the source file. This is useful for documentation generators that want to display annotations in a readable way."
msgstr ":attr:`~Format.STRING` حاشیه‌نویسی‌ها را به‌صورت یک رشته برمی‌گرداند، شبیه به آنچه در پرونده منبع ظاهر می‌شود. این برای مستندسازهایی که می‌خواهند حاشیه‌نویسی‌ها را به‌شکلی خوانا نمایش دهند، مفید است."

msgid "The :func:`get_annotations` function is the main entry point for retrieving annotations. Given a function, class, or module, it returns an annotations dictionary in the requested format. This module also provides functionality for working directly with the :term:`annotate function` that is used to evaluate annotations, such as :func:`get_annotate_from_class_namespace` and :func:`call_annotate_function`, as well as the :func:`call_evaluate_function` function for working with :term:`evaluate functions <evaluate function>`."
msgstr "تابع :func:`get_annotations` نقطه ورود اصلی برای بازیابی حاشیه‌گذاری‌ها  است. این تابع با دریافت یک تابع، کلاس یا ماژول، دیکشنری حاشیه‌گذاری‌ها را در قالب درخواستی بازمی‌گرداند. این ماژول همچنین برای کار مستقیم با :term:`annotate function` که برای ارزیابی حاشیه‌گذاری‌ها استفاده می‌شود، قابلیت‌هایی فراهم می‌کند؛ مانند :func:`get_annotate_from_class_namespace` و :func:`call_annotate_function`، و همچنین تابع :func:`call_evaluate_function` برای کار با :term:`evaluate functions <evaluate function>`."

msgid "Most functionality in this module can execute arbitrary code; see :ref:`the security section <annotationlib-security>` for more information."
msgstr "بیشتر قابلیت‌های این ماژول می‌توانند کد دلخواه را اجرا کنند؛ برای اطلاعات بیشتر :ref:`بخش امنیت <annotationlib-security>` را ببینید."

msgid ":pep:`649` proposed the current model for how annotations work in Python."
msgstr ":pep:`649` مدل کنونی برای چگونگی کارکرد حاشیه‌نویسی‌هادر پایتون را پیشنهاد داد."

msgid ":pep:`749` expanded on various aspects of :pep:`649` and introduced the :mod:`!annotationlib` module."
msgstr ":pep:`749` به تشریح جنبه‌های مختلفی از :pep:`649` پرداخت و ماژول :mod:`!annotationlib` را معرفی کرد."

msgid ":ref:`annotations-howto` provides best practices for working with annotations."
msgstr ":ref:`annotations-howto` بهترین شیوه‌ها را برای کار با حاشیه‌نویسی‌ها  ارائه می‌دهد."

msgid ":pypi:`typing-extensions` provides a backport of :func:`get_annotations` that works on earlier versions of Python."
msgstr ":pypi:`typing-extensions` یک بک‌پورت از :func:`get_annotations` فراهم می‌کند که در نسخه‌های پیشین پایتون کار می‌کند."

msgid "Annotation semantics"
msgstr "معناشناسی حاشیه‌نویسی"

msgid "The way annotations are evaluated has changed over the history of Python 3, and currently still depends on a :ref:`future import <future>`. There have been execution models for annotations:"
msgstr "روش ارزیابی حاشیه‌نویسی‌ها در طول تاریخ پایتون ۳ تغییر کرده است و در حال حاضر همچنان به یک :ref:`future import <future>` وابسته است. مدل‌های اجرایی برای حاشیه‌نویسی‌ها وجود داشته‌اند:"

msgid "*Stock semantics* (default in Python 3.0 through 3.13; see :pep:`3107` and :pep:`526`): Annotations are evaluated eagerly, as they are encountered in the source code."
msgstr "*معناشناسی استاندارد* (پیش‌فرض در پایتون 3.0 تا 3.13؛ :pep:`3107` و :pep:`526` را ببینید): حاشیه‌نویسی‌هابه‌صورت فوری، به‌محض مواجهه در کد منبع ارزیابی می‌شوند."

msgid "*Stringified annotations* (used with ``from __future__ import annotations`` in Python 3.7 and newer; see :pep:`563`): Annotations are stored as strings only."
msgstr "*حاشیه‌نویسی‌های رشته‌ای* (با ``from __future__ import annotations`` در پایتون 3.7 و جدیدتر استفاده می‌شود؛ به :pep:`563` مراجعه کنید): حاشیه‌نویسی‌ها فقط به‌صورت رشته ذخیره می‌شوند."

msgid "*Deferred evaluation* (default in Python 3.14 and newer; see :pep:`649` and :pep:`749`): Annotations are evaluated lazily, only when they are accessed."
msgstr "*ارزیابی به‌تعویق‌افتاده* (پیش‌فرض در پایتون 3.14 و نسخه‌های جدیدتر؛ :pep:`649` و :pep:`749` را ببینید): حاشیه‌گذاری‌ها به‌صورت تنبل ارزیابی می‌شوند، تنها زمانی که به آن‌ها دسترسی پیدا شود."

msgid "As an example, consider the following program::"
msgstr "به‌عنوان مثال، برنامه زیر را در نظر بگیرید::"

msgid ""
"def func(a: Cls) -> None:\n"
"    print(a)\n"
"\n"
"class Cls: pass\n"
"\n"
"print(func.__annotations__)"
msgstr ""
"def func(a: Cls) -> None:\n"
"    print(a)\n"
"\n"
"class Cls: pass\n"
"\n"
"print(func.__annotations__)"

msgid "This will behave as follows:"
msgstr "این به‌صورت زیر رفتار خواهد کرد:"

msgid "Under stock semantics (Python 3.13 and earlier), it will throw a :exc:`NameError` at the line where ``func`` is defined, because ``Cls`` is an undefined name at that point."
msgstr "طبق معناشناسی استاندارد (پایتون 3.13 و نسخه‌های پیشین)، یک :exc:`NameError` در سطری که ``func`` تعریف شده است پرتاب می‌شود، زیرا ``Cls`` در آن نقطه یک نام تعریف‌نشده است."

msgid "Under stringified annotations (if ``from __future__ import annotations`` is used), it will print ``{'a': 'Cls', 'return': 'None'}``."
msgstr "در حالت حاشیه‌نویسی‌های رشته‌ای‌شده (اگر از ``from __future__ import annotations`` استفاده شود)، ``{'a': 'Cls', 'return': 'None'}`` چاپ خواهد شد."

msgid "Under deferred evaluation (Python 3.14 and later), it will print ``{'a': <class 'Cls'>, 'return': None}``."
msgstr "در ارزیابی معوق (پایتون 3.14 و نسخه‌های بعد)، ``{'a': <class 'Cls'>, 'return': None}`` چاپ خواهد شد."

msgid "Stock semantics were used when function annotations were first introduced in Python 3.0 (by :pep:`3107`) because this was the simplest, most obvious way to implement annotations. The same execution model was used when variable annotations were introduced in Python 3.6 (by :pep:`526`). However, stock semantics caused problems when using annotations as type hints, such as a need to refer to names that are not yet defined when the annotation is encountered. In addition, there were performance problems with executing annotations at module import time. Therefore, in Python 3.7, :pep:`563` introduced the ability to store annotations as strings using the ``from __future__ import annotations`` syntax. The plan at the time was to eventually make this behavior the default, but a problem appeared: stringified annotations are more difficult to process for those who introspect annotations at runtime. An alternative proposal, :pep:`649`, introduced the third execution model, deferred evaluation, and was implemented in Python 3.14. Stringified annotations are still used if ``from __future__ import annotations`` is present, but this behavior will eventually be removed."
msgstr "هنگامی که حاشیه‌نویسی‌های تابع برای نخستین بار در پایتون 3.0 (توسط :pep:`3107`) معرفی شدند، از معناشناسی پیش‌فرض استفاده شد، زیرا این ساده‌ترین و آشکارترین روش برای پیاده‌سازی حاشیه‌نویسی‌ها بود. هنگامی که حاشیه‌نویسی‌های متغیر در پایتون 3.6 (توسط :pep:`526`) معرفی شدند، از همان مدل اجرایی استفاده شد. با این حال، معناشناسی پیش‌فرض هنگام استفاده از حاشیه‌نویسی‌ها به‌عنوان راهنمایی‌های نوع مشکلاتی ایجاد می‌کرد، مانند نیاز به ارجاع به نام‌هایی که در زمان مواجهه با حاشیه‌نویسی هنوز تعریف‌نشده‌اند. علاوه بر این، مشکلات عملکردی در اجرای حاشیه‌نویسی‌ها در زمان ایمپورت ماژول وجود داشت. بنابراین، در پایتون 3.7، :pep:`563` توانایی ذخیره کردن حاشیه‌نویسی‌ها به‌صورت رشته با استفاده از سینتکس ``from __future__ import annotations`` را معرفی کرد. برنامه در آن زمان این بود که در نهایت این رفتار به پیش‌فرض تبدیل شود، اما مشکلی پدیدار شد: پردازش حاشیه‌نویسی‌های رشته‌ای برای کسانی که حاشیه‌نویسی‌ها را در ران‌تایم درون‌نگری می‌کنند، دشوارتر است. یک پیشنهاد جایگزین، :pep:`649`، سومین مدل اجرایی، یعنی ارزیابی به‌تعویق‌افتاده را معرفی کرد و در پایتون 3.14 پیاده‌سازی شد. در صورت وجود ``from __future__ import annotations``، همچنان از حاشیه‌نویسی‌های رشته‌ای استفاده می‌شود، اما این رفتار در نهایت حذف خواهد شد."

msgid "Classes"
msgstr "کلاس‌ها"

msgid "An :class:`~enum.IntEnum` describing the formats in which annotations can be returned. Members of the enum, or their equivalent integer values, can be passed to :func:`get_annotations` and other functions in this module, as well as to :attr:`~object.__annotate__` functions."
msgstr "یک :class:`~enum.IntEnum` که قالب‌هایی را توصیف می‌کند که حاشیه‌نویسی‌ها می‌توانند در آن‌ها برگردانده شوند. اعضای enum، یا مقادیر صحیح معادل آن‌ها، می‌توانند به :func:`get_annotations` و سایر توابع این ماژول، و همچنین به توابع :attr:`~object.__annotate__` ارسال شوند."

msgid "Values are the result of evaluating the annotation expressions."
msgstr "مقادیر، نتیجه‌ی ارزیابی عبارت‌های حاشیه‌نویسی هستند."

msgid "Special value used to signal that an annotate function is being evaluated in a special environment with fake globals. When passed this value, annotate functions should either return the same value as for the :attr:`Format.VALUE` format, or raise :exc:`NotImplementedError` to signal that they do not support execution in this environment. This format is only used internally and should not be passed to the functions in this module."
msgstr "مقدار ویژه‌ای که برای اعلام اینکه یک تابع annotate در یک محیط ویژه با متغیرهای سراسری جعلی ارزیابی می‌شود، به‌کار می‌رود. هنگامی که این مقدار به آن‌ها داده شود، توابع annotate باید یا همان مقداری را که برای قالب :attr:`Format.VALUE` برمی‌گردانند، برگردانند، یا :exc:`NotImplementedError` را پرتاب کنند تا نشان دهند که از اجرا در این محیط پشتیبانی نمی‌کنند. این قالب فقط به‌صورت داخلی استفاده می‌شود و نباید به توابع این ماژول داده شود."

msgid "Values are real annotation values (as per :attr:`Format.VALUE` format) for defined values, and :class:`ForwardRef` proxies for undefined values. Real objects may contain references to :class:`ForwardRef` proxy objects."
msgstr "مقادیر، برای مقادیر تعریف‌شده، مقادیر واقعی حاشیه‌نویسی (بر اساس قالب :attr:`Format.VALUE`) هستند و برای مقادیر تعریف‌نشده، پراکسی‌های :class:`ForwardRef` هستند. اشیاء واقعی ممکن است شامل ارجاع‌هایی به اشیاء پراکسی :class:`ForwardRef` باشند."

msgid "Values are the text string of the annotation as it appears in the source code, up to modifications including, but not restricted to, whitespace normalizations and constant values optimizations."
msgstr "مقادیر، رشته‌ی متنی حاشیه‌نویسیهستند، به همان شکلی که در کد منبع ظاهر می‌شود، با در نظر گرفتن تغییراتی شامل، اما نه محدود به، نرمال‌سازی‌های فضای سفید و بهینه‌سازی‌های مقادیر ثابت."

msgid "The exact values of these strings may change in future versions of Python."
msgstr "مقادیر دقیق این رشته‌ها ممکن است در نسخه‌های آینده پایتون تغییر کند."

msgid "A proxy object for forward references in annotations."
msgstr "یک شیء پراکسی برای ارجاع‌های پیش‌رو در حاشیه‌نویسی‌ها."

msgid "Instances of this class are returned when the :attr:`~Format.FORWARDREF` format is used and annotations contain a name that cannot be resolved. This can happen when a forward reference is used in an annotation, such as when a class is referenced before it is defined."
msgstr "نمونه‌هایی از این کلاس زمانی برگردانده می‌شوند که از قالب :attr:`~Format.FORWARDREF` استفاده شود و حاشیه‌نویسی‌ها شامل نامی باشند که نمی‌توان آن را حل کرد. این حالت ممکن است زمانی رخ دهد که از یک ارجاع به جلو در یک حاشیه‌نویسی استفاده شود، مانند زمانی که یک کلاس پیش از تعریف شدن، به آن ارجاع داده شود."

msgid "A string containing the code that was evaluated to produce the :class:`~ForwardRef`. The string may not be exactly equivalent to the original source."
msgstr "رشته‌ای حاوی کدی که برای تولید :class:`~ForwardRef` ارزیابی‌شده است. این رشته ممکن است دقیقاً معادل کد منبع اصلی نباشد."

msgid "Evaluate the forward reference, returning its value."
msgstr "ارجاع پیشرو را ارزیابی می‌کند و مقدار آن را برمی‌گرداند."

msgid "If the *format* argument is :attr:`~Format.VALUE` (the default), this method may throw an exception, such as :exc:`NameError`, if the forward reference refers to a name that cannot be resolved. The arguments to this method can be used to provide bindings for names that would otherwise be undefined. If the *format* argument is :attr:`~Format.FORWARDREF`, the method will never throw an exception, but may return a :class:`~ForwardRef` instance. For example, if the forward reference object contains the code ``list[undefined]``, where ``undefined`` is a name that is not defined, evaluating it with the :attr:`~Format.FORWARDREF` format will return ``list[ForwardRef('undefined')]``. If the *format* argument is :attr:`~Format.STRING`, the method will return :attr:`~ForwardRef.__forward_arg__`."
msgstr "اگر آرگومان *format* برابر :attr:`~Format.VALUE` باشد (پیش‌فرض)، این متد ممکن است در صورتی استثنایی مانند :exc:`NameError` پرتاب کند که ارجاع پیشرو به نامی اشاره کند که نمی‌توان آن را حل کرد. می‌توان از آرگومان‌های این متد برای فراهم کردن پیوندها برای نام‌هایی استفاده کرد که در غیر این صورت تعریف‌نشده خواهند بود. اگر آرگومان *format* برابر :attr:`~Format.FORWARDREF` باشد، این متد هرگز استثنا پرتاب نخواهد کرد، اما ممکن است نمونه‌ای از :class:`~ForwardRef` بازگشت دهد. برای مثال، اگر شیء ارجاع پیشرو حاوی کد ``list[undefined]`` باشد، که در آن ``undefined`` نامی است که تعریف‌نشده است، ارزیابی آن با قالب :attr:`~Format.FORWARDREF` ``list[ForwardRef('undefined')]`` را بازگشت خواهد داد. اگر آرگومان *format* برابر :attr:`~Format.STRING` باشد، این متد :attr:`~ForwardRef.__forward_arg__` را بازگشت خواهد داد."

msgid "The *owner* parameter provides the preferred mechanism for passing scope information to this method. The owner of a :class:`~ForwardRef` is the object that contains the annotation from which the :class:`~ForwardRef` derives, such as a module object, type object, or function object."
msgstr "پارامتر *owner* سازوکار ترجیحی برای انتقال اطلاعات محدوده به این متد را فراهم می‌کند. مالک یک :class:`~ForwardRef` آن شیء است که حاوی حاشیه‌نویسی ای است که :class:`~ForwardRef` از آن مشتق می‌شود، مانند شیء ماژول، شیء نوع، یا شیء تابع."

msgid "The *globals*, *locals*, and *type_params* parameters provide a more precise mechanism for influencing the names that are available when the :class:`~ForwardRef` is evaluated. *globals* and *locals* are passed to :func:`eval`, representing the global and local namespaces in which the name is evaluated. The *type_params* parameter is relevant for objects created using the native syntax for :ref:`generic classes <generic-classes>` and :ref:`functions <generic-functions>`. It is a tuple of :ref:`type parameters <type-params>` that are in scope while the forward reference is being evaluated. For example, if evaluating a :class:`~ForwardRef` retrieved from an annotation found in the class namespace of a generic class ``C``, *type_params* should be set to ``C.__type_params__``."
msgstr "پارامترهای *globals*، *locals* و *type_params* سازوکار دقیق‌تری را برای تأثیرگذاری بر نام‌هایی که هنگام ارزیابی :class:`~ForwardRef` در دسترس هستند، فراهم می‌کنند. *globals* و *locals* به :func:`eval` ارسال می‌شوند و نشان‌دهنده‌ی فضای نام های سراسری و محلی هستند که نام در آن‌ها ارزیابی می‌شود. پارامتر *type_params* برای اشیایی که با استفاده از سینتکس بومی برای :ref:`کلاس‌های عام <generic-classes>` و :ref:`توابع عام <generic-functions>` ایجاد شده‌اند، مرتبط است. این، تاپلی از :ref:`پارامترهای نوع <type-params>` است که در حین ارزیابی ارجاع پیشرو، در محدوده قرار دارند. برای مثال، اگر در حال ارزیابی یک :class:`~ForwardRef` هستید که از یک حاشیه‌نویسی یافت‌شده در فضای نام کلاسِ یک کلاس عام ``C`` بازیابی شده است، *type_params* باید روی ``C.__type_params__`` تنظیم شود."

msgid ":class:`~ForwardRef` instances returned by :func:`get_annotations` retain references to information about the scope they originated from, so calling this method with no further arguments may be sufficient to evaluate such objects. :class:`~ForwardRef` instances created by other means may not have any information about their scope, so passing arguments to this method may be necessary to evaluate them successfully."
msgstr "نمونه‌های :class:`~ForwardRef` که توسط :func:`get_annotations` بازگردانده می‌شوند، ارجاع‌هایی به اطلاعات مربوط به محدوده‌ای که از آن منشأ گرفته‌اند را حفظ می‌کنند، بنابراین فراخوانی این متد بدون آرگومان‌های بیشتر ممکن است برای ارزیابی چنین اشیایی کافی باشد. نمونه‌های :class:`~ForwardRef` که به روش‌های دیگر ایجاد شده‌اند ممکن است هیچ اطلاعاتی درباره محدوده خود نداشته باشند، بنابراین ارسال آرگومان‌ها به این متد ممکن است برای ارزیابی موفقیت‌آمیز آن‌ها ضروری باشد."

msgid "If no *owner*, *globals*, *locals*, or *type_params* are provided and the :class:`~ForwardRef` does not contain information about its origin, empty globals and locals dictionaries are used."
msgstr "اگر هیچ‌کدام از *owner*، *globals*، *locals* یا *type_params* ارائه نشده باشند و :class:`~ForwardRef` حاوی اطلاعاتی درباره خاستگاه خود نباشد، از دیکشنری‌های خالی *globals* و *locals* استفاده می‌شود."

msgid "Functions"
msgstr "توابع"

msgid "Convert an annotations dict containing runtime values to a dict containing only strings. If the values are not already strings, they are converted using :func:`type_repr`. This is meant as a helper for user-provided annotate functions that support the :attr:`~Format.STRING` format but do not have access to the code creating the annotations."
msgstr "یک دیکشنری حاشیه‌نویسی‌ها را که حاوی مقادیر ران‌تایم است، به دیکشنری‌ای تبدیل می‌کند که فقط شامل رشته‌ها است. اگر مقادیر از قبل رشته نباشند، با استفاده از :func:`type_repr` تبدیل می‌شوند. این به‌عنوان یک کمک‌کننده برای توابع حاشیه‌نویسی ارائه‌شده توسط کاربر در نظر گرفته شده است که از قالب :attr:`~Format.STRING` پشتیبانی می‌کنند اما به کدی که حاشیه‌نویسی‌ها را ایجاد می‌کند دسترسی ندارند."

msgid "For example, this is used to implement the :attr:`~Format.STRING` format for :class:`typing.TypedDict` classes created through the functional syntax:"
msgstr "برای مثال، این برای پیاده‌سازی فرمت :attr:`~Format.STRING` برای کلاس‌های :class:`typing.TypedDict` که از طریق سینتکس تابعی ایجاد شده‌اند استفاده می‌شود:"

msgid ""
">>> from typing import TypedDict\n"
">>> Movie = TypedDict(\"movie\", {\"name\": str, \"year\": int})\n"
">>> get_annotations(Movie, format=Format.STRING)\n"
"{'name': 'str', 'year': 'int'}"
msgstr ""
">>> from typing import TypedDict\n"
">>> Movie = TypedDict(\"movie\", {\"name\": str, \"year\": int})\n"
">>> get_annotations(Movie, format=Format.STRING)\n"
"{'name': 'str', 'year': 'int'}"

msgid "Call the :term:`annotate function` *annotate* with the given *format*, a member of the :class:`Format` enum, and return the annotations dictionary produced by the function."
msgstr ":term:`annotate function` *annotate* را با *format* داده‌شده، عضوی از شمارشی (enum) :class:`Format`، فراخوانی کنید و دیکشنری حاشیه‌نویسی‌ها  تولیدشده توسط تابع را برگردانید."

msgid "This helper function is required because annotate functions generated by the compiler for functions, classes, and modules only support the :attr:`~Format.VALUE` format when called directly. To support other formats, this function calls the annotate function in a special environment that allows it to produce annotations in the other formats. This is a useful building block when implementing functionality that needs to partially evaluate annotations while a class is being constructed."
msgstr "این تابع کمکی مورد نیاز است، زیرا توابع annotate (annotate functions) تولیدشده توسط کامپایلر برای توابع، کلاس‌ها و ماژول‌ها، هنگام فراخوانی مستقیم تنها از قالب :attr:`~Format.VALUE` پشتیبانی می‌کنند. برای پشتیبانی از سایر قالب‌ها، این تابع، تابع annotate (annotate function) را در محیط ویژه‌ای فراخوانی می‌کند که به آن امکان می‌دهد حاشیه‌نویسی‌هارا در سایر قالب‌ها تولید کند. این یک جزء سازنده‌ی مفید در پیاده‌سازی قابلیتی است که نیاز دارد حاشیه‌نویسی‌ها را در حالی که یک کلاس در حال ساخته‌شدن است به‌طور جزئی ارزیابی کند."

msgid "*owner* is the object that owns the annotation function, usually a function, class, or module. If provided, it is used in the :attr:`~Format.FORWARDREF` format to produce a :class:`ForwardRef` object that carries more information."
msgstr "*owner* شیءای است که تابع حاشیه‌نویسی‌ها به آن تعلق دارد و معمولاً یک تابع، کلاس یا ماژول است. در صورت ارائه، از آن در قالب :attr:`~Format.FORWARDREF` برای ایجاد یک شیء :class:`ForwardRef` حاوی اطلاعات بیشتر استفاده می‌شود."

msgid ":PEP:`PEP 649 <649#the-stringizer-and-the-fake-globals-environment>` contains an explanation of the implementation technique used by this function."
msgstr ":PEP:`PEP 649 <649#the-stringizer-and-the-fake-globals-environment>` شامل توضیحی درباره‌ی روش پیاده‌سازی به‌کاررفته در این تابع است."

msgid "Call the :term:`evaluate function` *evaluate* with the given *format*, a member of the :class:`Format` enum, and return the value produced by the function. This is similar to :func:`call_annotate_function`, but the latter always returns a dictionary mapping strings to annotations, while this function returns a single value."
msgstr ":term:`evaluate function` یعنی *evaluate* را با *format* داده‌شده، که عضوی از enum :class:`Format` است، فراخوانی می‌کند و مقدار تولیدشده توسط تابع را برمی‌گرداند. این تابع مشابه :func:`call_annotate_function` است، اما آن تابع همیشه دیکشنری‌ای را برمی‌گرداند که رشته‌ها را به annotationها نگاشت می‌کند، در حالی که این تابع یک مقدار واحد را برمی‌گرداند."

msgid "This is intended for use with the evaluate functions generated for lazily evaluated elements related to type aliases and type parameters:"
msgstr "این برای استفاده با توابع ارزیابی تولیدشده برای عناصری که با تأخیر ارزیابی می‌شوند و به نام‌های مستعار نوع و پارامترهای نوع مربوط هستند، در نظر گرفته شده است:"

msgid ":meth:`typing.TypeAliasType.evaluate_value`, the value of type aliases"
msgstr ":meth:`typing.TypeAliasType.evaluate_value`، مقدار نام‌های مستعار نوع"

msgid ":meth:`typing.TypeVar.evaluate_bound`, the bound of type variables"
msgstr ":meth:`typing.TypeVar.evaluate_bound`، کران متغیرهای نوع"

msgid ":meth:`typing.TypeVar.evaluate_constraints`, the constraints of type variables"
msgstr ":meth:`typing.TypeVar.evaluate_constraints`، محدودیت‌های متغیرهای نوع"

msgid ":meth:`typing.TypeVar.evaluate_default`, the default value of type variables"
msgstr ":meth:`typing.TypeVar.evaluate_default`، مقدار پیش‌فرض متغیرهای نوع"

msgid ":meth:`typing.ParamSpec.evaluate_default`, the default value of parameter specifications"
msgstr ":meth:`typing.ParamSpec.evaluate_default`، مقدار پیش‌فرض مشخصات پارامتر"

msgid ":meth:`typing.TypeVarTuple.evaluate_default`, the default value of type variable tuples"
msgstr ":meth:`typing.TypeVarTuple.evaluate_default`، مقدار پیش‌فرض تاپل‌های متغیر نوع"

msgid "*owner* is the object that owns the evaluate function, such as the type alias or type variable object."
msgstr "*owner* شیءای است که تابع evaluate به آن تعلق دارد، مانند شیء نام مستعار نوع یا شیء متغیر نوع."

msgid "*format* can be used to control the format in which the value is returned:"
msgstr "*format* می‌تواند برای کنترل قالبی که مقدار در آن برگردانده می‌شود، استفاده شود:"

msgid ""
">>> type Alias = undefined\n"
">>> call_evaluate_function(Alias.evaluate_value, Format.VALUE)\n"
"Traceback (most recent call last):\n"
"...\n"
"NameError: name 'undefined' is not defined\n"
">>> call_evaluate_function(Alias.evaluate_value, Format.FORWARDREF)\n"
"ForwardRef('undefined')\n"
">>> call_evaluate_function(Alias.evaluate_value, Format.STRING)\n"
"'undefined'"
msgstr ""
">>> type Alias = undefined\n"
">>> call_evaluate_function(Alias.evaluate_value, Format.VALUE)\n"
"Traceback (most recent call last):\n"
"...\n"
"NameError: name 'undefined' is not defined\n"
">>> call_evaluate_function(Alias.evaluate_value, Format.FORWARDREF)\n"
"ForwardRef('undefined')\n"
">>> call_evaluate_function(Alias.evaluate_value, Format.STRING)\n"
"'undefined'"

msgid "Retrieve the :term:`annotate function` from a class namespace dictionary *namespace*. Return :const:`!None` if the namespace does not contain an annotate function. This is primarily useful before the class has been fully created (e.g., in a metaclass); after the class exists, the annotate function can be retrieved with ``cls.__annotate__``. See :ref:`below <annotationlib-metaclass>` for an example using this function in a metaclass."
msgstr ":term:`annotate function` را از دیکشنری فضای نام کلاس *namespace* بازیابی می‌کند. اگر فضای نام شامل تابع annotate نباشد، :const:`!None` را بازمی‌گرداند. این موضوع عمدتاً پیش از آنکه کلاس به‌طور کامل ایجاد شده باشد (مثلاً در یک فراکلاس) مفید است؛ پس از ایجاد کلاس، می‌توان تابع annotate را با ``cls.__annotate__`` بازیابی کرد. برای نمونه‌ای از استفاده از این تابع در فراکلاس، :ref:`زیر <annotationlib-metaclass>` را ببینید."

msgid "Compute the annotations dict for an object."
msgstr "دیکشنری حاشیه‌نویسی‌های یک شیء را محاسبه کنید."

msgid "*obj* may be a callable, class, module, or other object with :attr:`~object.__annotate__` or :attr:`~object.__annotations__` attributes. Passing any other object raises :exc:`TypeError`."
msgstr "*obj* می‌تواند یک شیء فراخوانی‌پذیر، کلاس، ماژول، یا شیء دیگری دارای ویژگی‌های :attr:`~object.__annotate__` یا :attr:`~object.__annotations__` باشد. اگر هر شیء دیگری داده شود، :exc:`TypeError` پرتاب می‌شود."

msgid "The *format* parameter controls the format in which annotations are returned, and must be a member of the :class:`Format` enum or its integer equivalent. The different formats work as follows:"
msgstr "پارامتر *format* قالبی را که حاشیه‌نویسی‌ها در آن بازگردانده می‌شوند کنترل می‌کند، و باید عضوی از enum :class:`Format` یا معادل عدد صحیح آن باشد. قالب‌های مختلف به‌صورت زیر عمل می‌کنند:"

msgid "VALUE: :attr:`!object.__annotations__` is tried first; if that does not exist, the :attr:`!object.__annotate__` function is called if it exists."
msgstr "VALUE: ابتدا :attr:`!object.__annotations__` امتحان می‌شود؛ اگر وجود نداشته باشد، در صورت وجود داشتن تابع :attr:`!object.__annotate__` فراخوانی می‌شود."

msgid "FORWARDREF: If :attr:`!object.__annotations__` exists and can be evaluated successfully, it is used; otherwise, the :attr:`!object.__annotate__` function is called. If it does not exist either, :attr:`!object.__annotations__` is tried again and any error from accessing it is re-raised."
msgstr "FORWARDREF: اگر :attr:`!object.__annotations__` وجود داشته باشد و بتوان آن را با موفقیت ارزیابی کرد، از آن استفاده می‌شود؛ در غیر این صورت، تابع :attr:`!object.__annotate__` فراخوانی می‌شود. اگر این نیز وجود نداشته باشد، بار دیگر برای :attr:`!object.__annotations__` تلاش می‌شود و هر خطایی که از دسترسی به آن حاصل شود، دوباره پرتاب می‌شود."

msgid "When calling :attr:`!object.__annotate__` it is first called with :attr:`~Format.FORWARDREF`. If this is not implemented, it will then check if :attr:`~Format.VALUE_WITH_FAKE_GLOBALS` is supported and use that in the fake globals environment. If neither of these formats are supported, it will fall back to using :attr:`~Format.VALUE`. If :attr:`~Format.VALUE` fails, the error from this call will be raised."
msgstr "هنگام فراخوانی :attr:`!object.__annotate__`، ابتدا با :attr:`~Format.FORWARDREF` فراخوانی می‌شود. اگر این قالب پیاده‌سازی نشده باشد، سپس بررسی می‌شود که آیا :attr:`~Format.VALUE_WITH_FAKE_GLOBALS` پشتیبانی می‌شود یا خیر و در صورت پشتیبانی، از آن در محیط سراسری جعلی استفاده می‌شود. اگر هیچ‌کدام از این قالب‌ها پشتیبانی نشود، به استفاده از :attr:`~Format.VALUE` بازمی‌گردد. اگر :attr:`~Format.VALUE` با شکست مواجه شود، خطای حاصل از این فراخوانی پرتاب می‌شود."

msgid "STRING: If :attr:`!object.__annotate__` exists, it is called first; otherwise, :attr:`!object.__annotations__` is used and stringified using :func:`annotations_to_string`."
msgstr "STRING: اگر :attr:`!object.__annotate__` وجود داشته باشد، ابتدا فراخوانی می‌شود؛ در غیر این صورت، از :attr:`!object.__annotations__` استفاده می‌شود و با استفاده از :func:`annotations_to_string` به رشته تبدیل می‌شود."

msgid "When calling :attr:`!object.__annotate__` it is first called with :attr:`~Format.STRING`. If this is not implemented, it will then check if :attr:`~Format.VALUE_WITH_FAKE_GLOBALS` is supported and use that in the fake globals environment. If neither of these formats are supported, it will fall back to using :attr:`~Format.VALUE` with the result converted using :func:`annotations_to_string`. If :attr:`~Format.VALUE` fails, the error from this call will be raised."
msgstr "هنگام فراخوانی :attr:`!object.__annotate__`، ابتدا با :attr:`~Format.STRING` فراخوانی می‌شود. اگر این قالب پیاده‌سازی نشده باشد، سپس بررسی می‌شود که آیا :attr:`~Format.VALUE_WITH_FAKE_GLOBALS` پشتیبانی می‌شود یا خیر و در صورت پشتیبانی، از آن در محیط سراسری جعلی استفاده می‌شود. اگر هیچ‌کدام از این قالب‌ها پشتیبانی نشوند، به استفاده از :attr:`~Format.VALUE` بازمی‌گردد و نتیجه با استفاده از :func:`annotations_to_string` تبدیل می‌شود. اگر :attr:`~Format.VALUE` با شکست مواجه شود، خطای حاصل از این فراخوانی پرتاب می‌شود."

msgid "Returns a dict. :func:`!get_annotations` returns a new dict every time it's called; calling it twice on the same object will return two different but equivalent dicts."
msgstr "یک دیکشنری بازمی‌گرداند. :func:`!get_annotations` هر بار که فراخوانی می‌شود یک دیکشنری جدید بازمی‌گرداند؛ دو بار فراخوانی آن روی یک شیء، دو دیکشنری متفاوت اما معادل بازمی‌گرداند."

msgid "This function handles several details for you:"
msgstr "این تابع چندین جزئیات را برای شما مدیریت می‌کند:"

msgid "If *eval_str* is true, values of type :class:`!str` will be un-stringized using :func:`eval`. This is intended for use with stringized annotations (``from __future__ import annotations``). It is an error to set *eval_str* to true with formats other than :attr:`Format.VALUE`."
msgstr "اگر *eval_str* برابر true باشد، مقادیر از نوع :class:`!str` با استفاده از :func:`eval` از حالت رشته‌ای خارج می‌شوند. این قابلیت برای استفاده با حاشیه‌نویسی‌های رشته‌ای‌شده (``from __future__ import annotations``) در نظر گرفته شده است. تنظیم *eval_str* روی true در قالب‌هایی غیر از :attr:`Format.VALUE` خطا است."

msgid "If *obj* doesn't have an annotations dict, returns an empty dict. (Functions and methods always have an annotations dict; classes, modules, and other types of callables may not.)"
msgstr "اگر *obj* دیکشنری annotations نداشته باشد، یک دیکشنری خالی برمی‌گرداند. (توابع و متدها همیشه دیکشنری annotations دارند؛ کلاس‌ها، ماژول‌ها و سایر انواع فراخوانی‌پذیر ممکن است نداشته باشند.)"

msgid "Ignores inherited annotations on classes, as well as annotations on metaclasses. If a class doesn't have its own annotations dict, returns an empty dict."
msgstr "حاشیه‌نویسی‌های موروثی کلاس‌هاو همچنین حاشیه‌نویسی‌های فراکلاس‌ها را نادیده می‌گیرد. اگر کلاسی دیکشنری حاشیه‌نویسی‌های خود را نداشته باشد، یک دیکشنری خالی برمی‌گرداند."

msgid "All accesses to object members and dict values are done using ``getattr()`` and ``dict.get()`` for safety."
msgstr "تمام دسترسی‌ها به اعضای شیء و مقادیر دیکشنری برای ایمنی با استفاده از ``getattr()`` و ``dict.get()`` انجام می‌شوند."

msgid "*eval_str* controls whether or not values of type :class:`!str` are replaced with the result of calling :func:`eval` on those values:"
msgstr "*eval_str* تعیین می‌کند که آیا مقادیر از نوع :class:`!str` با نتیجه‌ی فراخوانی :func:`eval` روی آن مقادیر جایگزین می‌شوند یا خیر:"

msgid "If eval_str is true, :func:`eval` is called on values of type :class:`!str`. (Note that :func:`!get_annotations` doesn't catch exceptions; if :func:`eval` raises an exception, it will unwind the stack past the :func:`!get_annotations` call.)"
msgstr "اگر eval_str درست باشد، :func:`eval` روی مقادیری از نوع :class:`!str` فراخوانی می‌شود. (توجه داشته باشید که :func:`!get_annotations` استثناها را مهار نمی‌کند؛ اگر :func:`eval` استثنایی پرتاب کند، باعث باز شدن پشته تا پس از فراخوانی :func:`!get_annotations` خواهد شد.)"

msgid "If *eval_str* is false (the default), values of type :class:`!str` are unchanged."
msgstr "اگر *eval_str* نادرست باشد (پیش‌فرض)، مقادیر از نوع :class:`!str` بدون تغییر می‌مانند."

msgid "*globals* and *locals* are passed in to :func:`eval`; see the documentation for :func:`eval` for more information. If *globals* or *locals* is :const:`!None`, this function may replace that value with a context-specific default, contingent on ``type(obj)``:"
msgstr "*globals* و *locals* به :func:`eval` ارسال می‌شوند؛ برای اطلاعات بیشتر، مستندات :func:`eval` را ببینید. اگر *globals* یا *locals* برابر :const:`!None` باشد، این تابع ممکن است، بسته به ``type(obj)``، آن مقدار را با یک پیش‌فرض وابسته به زمینه جایگزین کند:"

msgid "If *obj* is a module, *globals* defaults to ``obj.__dict__``."
msgstr "اگر *obj* یک ماژول باشد، *globals* به‌طور پیش‌فرض برابر با ``obj.__dict__`` است."

msgid "If *obj* is a class, *globals* defaults to ``sys.modules[obj.__module__].__dict__`` and *locals* defaults to the *obj* class namespace."
msgstr "اگر *obj* یک کلاس باشد، *globals* به‌طور پیش‌فرض ``sys.modules[obj.__module__].__dict__`` است و *locals* به‌طور پیش‌فرض فضای نام کلاس *obj* است."

msgid "If *obj* is a callable, *globals* defaults to :attr:`obj.__globals__ <function.__globals__>`, although if *obj* is a wrapped function (using :func:`functools.update_wrapper`) or a :class:`functools.partial` object, it is unwrapped until a non-wrapped function is found."
msgstr "اگر *obj* فراخوانی‌پذیر باشد، مقدار پیش‌فرض *globals* برابر با :attr:`obj.__globals__ <function.__globals__>` است، هرچند اگر *obj* یک تابع پوشیده‌شده (با استفاده از :func:`functools.update_wrapper`) یا یک شیء :class:`functools.partial` باشد، تا زمانی که یک تابع بدون پوشش پیدا شود، پوشش آن برداشته می‌شود."

msgid "Calling :func:`!get_annotations` is best practice for accessing the annotations dict of any object. See :ref:`annotations-howto` for more information on annotations best practices."
msgstr "فراخوانی :func:`!get_annotations` بهترین روش برای دسترسی به دیکشنری حاشیه‌نویسی‌های هر شیء است. برای اطلاعات بیشتر درباره بهترین روش‌های حاشیه‌نویسی، :ref:`annotations-howto` را ببینید."

msgid ""
">>> def f(a: int, b: str) -> float:\n"
"...     pass\n"
">>> get_annotations(f)\n"
"{'a': <class 'int'>, 'b': <class 'str'>, 'return': <class 'float'>}"
msgstr ""
">>> def f(a: int, b: str) -> float:\n"
"...     pass\n"
">>> get_annotations(f)\n"
"{'a': <class 'int'>, 'b': <class 'str'>, 'return': <class 'float'>}"

msgid "Convert an arbitrary Python value to a format suitable for use by the :attr:`~Format.STRING` format. This calls :func:`repr` for most objects, but has special handling for some objects, such as type objects."
msgstr "یک مقدار دلخواه پایتون را به قالبی مناسب برای استفاده توسط قالب :attr:`~Format.STRING` تبدیل می‌کند. این تابع برای بیشتر اشیاء، :func:`repr` را فراخوانی می‌کند، اما برای برخی اشیاء، مانند اشیاء نوع، مدیریت ویژه‌ای دارد."

msgid "This is meant as a helper for user-provided annotate functions that support the :attr:`~Format.STRING` format but do not have access to the code creating the annotations. It can also be used to provide a user-friendly string representation for other objects that contain values that are commonly encountered in annotations."
msgstr "این به‌عنوان یک ابزار کمکی برای توابع حاشیه‌نویسی ارائه‌شده توسط کاربر در نظر گرفته شده است که از قالب :attr:`~Format.STRING` پشتیبانی می‌کنند، اما به کدی که حاشیه‌نویسی‌هارا ایجاد می‌کند دسترسی ندارند. همچنین می‌توان از آن برای فراهم کردن یک نمایش رشته‌ای کاربرپسند برای اشیاء دیگری استفاده کرد که حاوی مقادیری هستند که معمولاً در حاشیه‌نویسی‌ها  با آن‌ها مواجه می‌شوید."

msgid "Recipes"
msgstr "دستور پخت‌ها"

msgid "Using annotations in a metaclass"
msgstr "استفاده از حاشیه‌نویسی‌ها در یک فراکلاس"

msgid "A :ref:`metaclass <metaclasses>` may want to inspect or even modify the annotations in a class body during class creation. Doing so requires retrieving annotations from the class namespace dictionary. For classes created with ``from __future__ import annotations``, the annotations will be in the ``__annotations__`` key of the dictionary. For other classes with annotations, :func:`get_annotate_from_class_namespace` can be used to get the annotate function, and :func:`call_annotate_function` can be used to call it and retrieve the annotations. Using the :attr:`~Format.FORWARDREF` format will usually be best, because this allows the annotations to refer to names that cannot yet be resolved when the class is created."
msgstr "ممکن است یک :ref:`فراکلاس <metaclasses>` بخواهد در جریان ایجاد کلاس، حاشیه‌نویسی‌های موجود در بدنه کلاس را بررسی یا حتی اصلاح کند. این کار مستلزم بازیابی حاشیه‌نویسی‌ها از دیکشنری فضای نام کلاس است. برای کلاس‌هایی که با ``from __future__ import annotations`` ایجاد شده‌اند، حاشیه‌نویسی‌ها در کلید ``__annotations__`` دیکشنری قرار خواهند داشت. برای سایر کلاس‌های دارای حاشیه‌نویسی، می‌توان از :func:`get_annotate_from_class_namespace` برای دریافت تابع حاشیه‌نویسی استفاده کرد و می‌توان از :func:`call_annotate_function` برای فراخوانی آن و بازیابی حاشیه‌نویسی‌ها استفاده کرد. استفاده از قالب :attr:`~Format.FORWARDREF` معمولاً بهترین حالت است، زیرا این امر به حاشیه‌نویسی‌ها اجازه می‌دهد به نام‌هایی ارجاع دهند که هنوز در زمان ایجاد کلاس قابل حل نیستند."

msgid "To modify the annotations, it is best to create a wrapper annotate function that calls the original annotate function, makes any necessary adjustments, and returns the result."
msgstr "برای تغییر حاشیه‌نویسی‌ها، بهتر است یک تابع annotate پوششی ایجاد کنید که تابع annotate اصلی را فراخوانی کند، تنظیمات لازم را اعمال کند و نتیجه را برگرداند."

msgid "Below is an example of a metaclass that filters out all :class:`typing.ClassVar` annotations from the class and puts them in a separate attribute:"
msgstr "در زیر مثالی از یک فراکلاس آمده است که تمام حاشیه‌نویسی‌های :class:`typing.ClassVar` را از کلاس جدا می‌کند و آن‌ها را در یک ویژگی جداگانه قرار می‌دهد:"

msgid ""
"import annotationlib\n"
"import typing\n"
"\n"
"class ClassVarSeparator(type):\n"
"   def __new__(mcls, name, bases, ns):\n"
"      if \"__annotations__\" in ns:  # from __future__ import annotations\n"
"         annotations = ns[\"__annotations__\"]\n"
"         classvar_keys = {\n"
"            key for key, value in annotations.items()\n"
"            # Use string comparison for simplicity; a more robust solution\n"
"            # could use annotationlib.ForwardRef.evaluate\n"
"            if value.startswith(\"ClassVar\")\n"
"         }\n"
"         classvars = {key: annotations[key] for key in classvar_keys}\n"
"         ns[\"__annotations__\"] = {\n"
"            key: value for key, value in annotations.items()\n"
"            if key not in classvar_keys\n"
"         }\n"
"         wrapped_annotate = None\n"
"      elif annotate := annotationlib.get_annotate_from_class_namespace(ns):\n"
"         annotations = annotationlib.call_annotate_function(\n"
"            annotate, format=annotationlib.Format.FORWARDREF\n"
"         )\n"
"         classvar_keys = {\n"
"            key for key, value in annotations.items()\n"
"            if typing.get_origin(value) is typing.ClassVar\n"
"         }\n"
"         classvars = {key: annotations[key] for key in classvar_keys}\n"
"\n"
"         def wrapped_annotate(format):\n"
"            annos = annotationlib.call_annotate_function(annotate, format, owner=typ)\n"
"            return {key: value for key, value in annos.items() if key not in classvar_keys}\n"
"\n"
"      else:  # no annotations\n"
"         classvars = {}\n"
"         wrapped_annotate = None\n"
"      typ = super().__new__(mcls, name, bases, ns)\n"
"\n"
"      if wrapped_annotate is not None:\n"
"         # Wrap the original __annotate__ with a wrapper that removes ClassVars\n"
"         typ.__annotate__ = wrapped_annotate\n"
"      typ.classvars = classvars  # Store the ClassVars in a separate attribute\n"
"      return typ"
msgstr ""
"import annotationlib\n"
"import typing\n"
"\n"
"class ClassVarSeparator(type):\n"
"   def __new__(mcls, name, bases, ns):\n"
"      if \"__annotations__\" in ns:  # from __future__ import annotations\n"
"         annotations = ns[\"__annotations__\"]\n"
"         classvar_keys = {\n"
"            key for key, value in annotations.items()\n"
"            # Use string comparison for simplicity; a more robust solution\n"
"            # could use annotationlib.ForwardRef.evaluate\n"
"            if value.startswith(\"ClassVar\")\n"
"         }\n"
"         classvars = {key: annotations[key] for key in classvar_keys}\n"
"         ns[\"__annotations__\"] = {\n"
"            key: value for key, value in annotations.items()\n"
"            if key not in classvar_keys\n"
"         }\n"
"         wrapped_annotate = None\n"
"      elif annotate := annotationlib.get_annotate_from_class_namespace(ns):\n"
"         annotations = annotationlib.call_annotate_function(\n"
"            annotate, format=annotationlib.Format.FORWARDREF\n"
"         )\n"
"         classvar_keys = {\n"
"            key for key, value in annotations.items()\n"
"            if typing.get_origin(value) is typing.ClassVar\n"
"         }\n"
"         classvars = {key: annotations[key] for key in classvar_keys}\n"
"\n"
"         def wrapped_annotate(format):\n"
"            annos = annotationlib.call_annotate_function(annotate, format, owner=typ)\n"
"            return {key: value for key, value in annos.items() if key not in classvar_keys}\n"
"\n"
"      else:  # no annotations\n"
"         classvars = {}\n"
"         wrapped_annotate = None\n"
"      typ = super().__new__(mcls, name, bases, ns)\n"
"\n"
"      if wrapped_annotate is not None:\n"
"         # Wrap the original __annotate__ with a wrapper that removes ClassVars\n"
"         typ.__annotate__ = wrapped_annotate\n"
"      typ.classvars = classvars  # Store the ClassVars in a separate attribute\n"
"      return typ"

msgid "Creating a custom callable annotate function"
msgstr "ایجاد یک تابع حاشیه‌نویسی سفارشی و فراخوانی‌پذیر"

msgid "Custom :term:`annotate functions <annotate function>` may be literal functions like those automatically generated for functions, classes, and modules. Or, they may wish to utilise the encapsulation provided by classes, in which case any :term:`callable` can be used as an :term:`annotate function`."
msgstr ":term:`توابع annotate <annotate function>` سفارشی می‌توانند توابع واقعی (literal functions) باشند، مانند آن‌هایی که به‌طور خودکار برای توابع، کلاس‌ها و ماژول‌ها تولید می‌شوند. یا ممکن است بخواهید از کپسوله‌سازی فراهم‌شده توسط کلاس‌ها استفاده کنید، که در این صورت هر :term:`callable` می‌تواند به‌عنوان یک :term:`annotate function` استفاده شود."

msgid "To provide the :attr:`~Format.VALUE`, :attr:`~Format.STRING`, or :attr:`~Format.FORWARDREF` formats directly, an :term:`annotate function` must provide the following attribute:"
msgstr "برای ارائه مستقیم قالب‌های :attr:`~Format.VALUE`، :attr:`~Format.STRING` یا :attr:`~Format.FORWARDREF`، یک :term:`annotate function` باید ویژگی زیر را فراهم کند:"

msgid "A callable ``__call__`` with signature ``__call__(format, /) -> dict``, that does not raise a :exc:`NotImplementedError` when called with a supported format."
msgstr "یک ``__call__`` فراخوانی‌پذیر با امضای ``__call__(format, /) -> dict``، که هنگام فراخوانی با یک قالب پشتیبانی‌شده، :exc:`NotImplementedError` پرتاب نمی‌کند."

msgid "To provide the :attr:`~Format.VALUE_WITH_FAKE_GLOBALS` format, which is used to automatically generate :attr:`~Format.STRING` or :attr:`~Format.FORWARDREF` if they are not supported directly, :term:`annotate functions <annotate function>` must provide the following attributes:"
msgstr "برای فراهم کردن قالب :attr:`~Format.VALUE_WITH_FAKE_GLOBALS`، که برای تولید خودکار :attr:`~Format.STRING` یا :attr:`~Format.FORWARDREF` در صورتی که به‌طور مستقیم پشتیبانی نشوند استفاده می‌شود، :term:`توابع annotate <annotate function>` باید ویژگی‌های زیر را فراهم کنند:"

msgid "A callable ``__call__`` with signature ``__call__(format, /) -> dict``, that does not raise a :exc:`NotImplementedError` when called with :attr:`~Format.VALUE_WITH_FAKE_GLOBALS`."
msgstr "یک ``__call__`` فراخوانی‌پذیر با امضای ``__call__(format, /) -> dict``، که هنگام فراخوانی با :attr:`~Format.VALUE_WITH_FAKE_GLOBALS` استثنای :exc:`NotImplementedError` را پرتاب نمی‌کند."

msgid "A :ref:`code object <code-objects>` ``__code__`` containing the compiled code for the annotate function."
msgstr "یک :ref:`شیء کد <code-objects>` ``__code__`` که شامل کد کامپایل‌شده برای تابع annotate است."

msgid "Optional: A tuple of the function's positional defaults ``__kwdefaults__``, if the function represented by ``__code__`` uses any positional defaults."
msgstr "اختیاری: یک تاپل از پیش‌فرض‌های جایگاهی تابع ``__kwdefaults__``، اگر تابع نشان‌داده‌شده توسط ``__code__`` از هرگونه پیش‌فرض جایگاهی استفاده کند."

msgid "Optional: A dict of the function's keyword defaults ``__defaults__``, if the function represented by ``__code__`` uses any keyword defaults."
msgstr "اختیاری: یک دیکشنری از مقادیر پیش‌فرض کلیدواژه‌ای تابع ``__defaults__``، اگر تابع نشان‌داده‌شده با ``__code__`` از مقادیر پیش‌فرض کلیدواژه‌ای استفاده کند."

msgid "Optional: All other :ref:`function attributes <inspect-types>`."
msgstr "اختیاری: همه‌ی :ref:`ویژگی‌های دیگر تابع <inspect-types>`."

msgid ""
"class Annotate:\n"
"    called_formats = []\n"
"\n"
"    def __call__(self, format=None, /, *, _self=None):\n"
"        # When called with fake globals, `_self` will be the\n"
"        # actual self value, and `self` will be the format.\n"
"        if _self is not None:\n"
"            self, format = _self, self\n"
"\n"
"        self.called_formats.append(format)\n"
"        if format <= 2:  # VALUE or VALUE_WITH_FAKE_GLOBALS\n"
"            return {\"x\": MyType}\n"
"        raise NotImplementedError\n"
"\n"
"    __code__ = __call__.__code__\n"
"    __defaults__ = (None,)\n"
"    __kwdefaults__ = property(lambda self: dict(_self=self))\n"
"\n"
"    __globals__ = {}\n"
"    __builtins__ = {}\n"
"    __closure__ = None"
msgstr ""
"class Annotate:\n"
"    called_formats = []\n"
"\n"
"    def __call__(self, format=None, /, *, _self=None):\n"
"        # When called with fake globals, `_self` will be the\n"
"        # actual self value, and `self` will be the format.\n"
"        if _self is not None:\n"
"            self, format = _self, self\n"
"\n"
"        self.called_formats.append(format)\n"
"        if format <= 2:  # VALUE or VALUE_WITH_FAKE_GLOBALS\n"
"            return {\"x\": MyType}\n"
"        raise NotImplementedError\n"
"\n"
"    __code__ = __call__.__code__\n"
"    __defaults__ = (None,)\n"
"    __kwdefaults__ = property(lambda self: dict(_self=self))\n"
"\n"
"    __globals__ = {}\n"
"    __builtins__ = {}\n"
"    __closure__ = None"

msgid "This can then be called with:"
msgstr "سپس می‌توان آن را به این صورت فراخوانی کرد:"

msgid ""
">>> from annotationlib import call_annotate_function, Format\n"
">>> call_annotate_function(Annotate(), format=Format.STRING)\n"
"{'x': 'MyType'}"
msgstr ""
">>> from annotationlib import call_annotate_function, Format\n"
">>> call_annotate_function(Annotate(), format=Format.STRING)\n"
"{'x': 'MyType'}"

msgid "Or used as the annotate function for an object:"
msgstr "یا به‌عنوان تابع حاشیه‌نویسی برای یک شیء استفاده شود:"

msgid ""
">>> from annotationlib import get_annotations, Format\n"
">>> class C:\n"
"...   pass\n"
">>> C.__annotate__ = Annotate()\n"
">>> get_annotations(Annotate(), format=Format.STRING)\n"
"{'x': 'MyType'}"
msgstr ""
">>> from annotationlib import get_annotations, Format\n"
">>> class C:\n"
"...   pass\n"
">>> C.__annotate__ = Annotate()\n"
">>> get_annotations(Annotate(), format=Format.STRING)\n"
"{'x': 'MyType'}"

msgid "Limitations of the ``STRING`` format"
msgstr "محدودیت‌های قالب ``STRING``"

msgid "The :attr:`~Format.STRING` format is meant to approximate the source code of the annotation, but the implementation strategy used means that it is not always possible to recover the exact source code."
msgstr "قالب :attr:`~Format.STRING` برای تقریب کد منبع حاشیه‌نویسی در نظر گرفته شده است، اما راهبرد پیاده‌سازی به‌کاررفته باعث می‌شود که همیشه نتوان کد منبع دقیق را بازیابی کرد."

msgid "First, the stringifier of course cannot recover any information that is not present in the compiled code, including comments, whitespace, parenthesization, and operations that get simplified by the compiler."
msgstr "اول، رشته‌ساز (stringifier) البته نمی‌تواند هیچ‌گونه اطلاعاتی را که در کد کامپایل‌شده وجود ندارد، از جمله کامنت‌ها، فضای سفید، پرانتزگذاری و عملیاتی که توسط کامپایلر ساده‌سازی می‌شوند، بازیابی کند."

msgid "Second, the stringifier can intercept almost all operations that involve names looked up in some scope, but it cannot intercept operations that operate fully on constants. As a corollary, this also means it is not safe to request the ``STRING`` format on untrusted code: Python is powerful enough that it is possible to achieve arbitrary code execution even with no access to any globals or builtins. For example:"
msgstr "دوم، رشته‌ساز (stringifier) می‌تواند تقریباً تمام عملیاتی را که شامل نام‌های جستجوشده در محدوده‌ای هستند، رهگیری کند، اما نمی‌تواند عملیاتی را که به‌طور کامل روی ثابت‌ها عمل می‌کنند، رهگیری کند. به‌عنوان یک نتیجه، این همچنین به این معناست که درخواست قالب ``STRING`` برای کد غیرقابل‌اعتماد ایمن نیست: پایتون آن‌قدر قدرتمند است که حتی بدون دسترسی به هیچ‌یک از سراسری‌ها یا توکارها نیز می‌توان به اجرای کد دلخواه دست یافت. برای مثال:"

msgid ""
">>> def f(x: (1).__class__.__base__.__subclasses__()[-1].__init__.__builtins__[\"print\"](\"Hello world\")): pass\n"
"...\n"
">>> annotationlib.get_annotations(f, format=annotationlib.Format.STRING)\n"
"Hello world\n"
"{'x': 'None'}"
msgstr ""
">>> def f(x: (1).__class__.__base__.__subclasses__()[-1].__init__.__builtins__[\"print\"](\"Hello world\")): pass\n"
"...\n"
">>> annotationlib.get_annotations(f, format=annotationlib.Format.STRING)\n"
"Hello world\n"
"{'x': 'None'}"

msgid "This particular example works as of the time of writing, but it relies on implementation details and is not guaranteed to work in the future."
msgstr "این مثال خاص در زمان نگارش کار می‌کند، اما به جزئیات پیاده‌سازی متکی است و تضمینی برای کار کردن آن در آینده وجود ندارد."

msgid "Among the different kinds of expressions that exist in Python, as represented by the :mod:`ast` module, some expressions are supported, meaning that the ``STRING`` format can generally recover the original source code; others are unsupported, meaning that they may result in incorrect output or an error."
msgstr "در میان انواع مختلف عبارت‌هایی که در پایتون وجود دارند و توسط ماژول :mod:`ast` نمایش داده می‌شوند، برخی از عبارت‌ها پشتیبانی می‌شوند، به این معنا که قالب ``STRING`` عموماً می‌تواند کد منبع اصلی را بازیابی کند؛ برخی دیگر پشتیبانی نمی‌شوند، به این معنا که ممکن است به خروجی نادرست یا خطا منجر شوند."

msgid "The following are supported (sometimes with caveats):"
msgstr "موارد زیر پشتیبانی می‌شوند (گاهی با ملاحظات):"

msgid ":class:`ast.BinOp`"
msgstr ":class:`ast.BinOp`"

msgid ":class:`ast.UnaryOp`"
msgstr ":class:`ast.UnaryOp`"

msgid ":class:`ast.Invert` (``~``), :class:`ast.UAdd` (``+``), and :class:`ast.USub` (``-``) are supported"
msgstr "از :class:`ast.Invert` (``~``)، :class:`ast.UAdd` (``+``) و :class:`ast.USub` (``-``) پشتیبانی می‌شود"

msgid ":class:`ast.Not` (``not``) is not supported"
msgstr "از :class:`ast.Not` (``not``) پشتیبانی نمی‌شود"

msgid ":class:`ast.Dict` (except when using ``**`` unpacking)"
msgstr ":class:`ast.Dict` (به‌جز هنگام استفاده از واگشایی ``**``)"

msgid ":class:`ast.Set`"
msgstr ":class:`ast.Set`"

msgid ":class:`ast.Compare`"
msgstr ":class:`ast.Compare`"

msgid ":class:`ast.Eq` and :class:`ast.NotEq` are supported"
msgstr "از :class:`ast.Eq` و :class:`ast.NotEq` پشتیبانی می‌شود"

msgid ":class:`ast.Lt`, :class:`ast.LtE`, :class:`ast.Gt`, and :class:`ast.GtE` are supported, but the operand may be flipped"
msgstr "از :class:`ast.Lt`، :class:`ast.LtE`، :class:`ast.Gt` و :class:`ast.GtE` پشتیبانی می‌شود، اما ممکن است عملوند جابه‌جا شود"

msgid ":class:`ast.Is`, :class:`ast.IsNot`, :class:`ast.In`, and :class:`ast.NotIn` are not supported"
msgstr ":class:`ast.Is`، :class:`ast.IsNot`، :class:`ast.In` و :class:`ast.NotIn` پشتیبانی نمی‌شوند"

msgid ":class:`ast.Call` (except when using ``**`` unpacking)"
msgstr ":class:`ast.Call` (مگر هنگام استفاده از واگشایی ``**``)"

msgid ":class:`ast.Constant` (though not the exact representation of the constant; for example, escape sequences in strings are lost; hexadecimal numbers are converted to decimal)"
msgstr ":class:`ast.Constant` (البته نه نمایش دقیق ثابت؛ برای مثال، دنباله‌های خنثی‌سازی در رشته‌ها از بین می‌روند؛ اعداد مبنای شانزده به مبنای ده تبدیل می‌شوند)"

msgid ":class:`ast.Attribute` (assuming the value is not a constant)"
msgstr ":class:`ast.Attribute` (با فرض اینکه مقدار ثابت نباشد)"

msgid ":class:`ast.Subscript` (assuming the value is not a constant)"
msgstr ":class:`ast.Subscript` (با فرض اینکه مقدار یک ثابت نباشد)"

msgid ":class:`ast.Starred` (``*`` unpacking)"
msgstr ":class:`ast.Starred` (واگشایی ``*``)"

msgid ":class:`ast.Name`"
msgstr ":class:`ast.Name`"

msgid ":class:`ast.List`"
msgstr ":class:`ast.List`"

msgid ":class:`ast.Tuple`"
msgstr ":class:`ast.Tuple`"

msgid ":class:`ast.Slice`"
msgstr ":class:`ast.Slice`"

msgid "The following are unsupported, but throw an informative error when encountered by the stringifier:"
msgstr "موارد زیر پشتیبانی نمی‌شوند، اما هنگامی که رشته‌ساز (stringifier) با آن‌ها مواجه شود، خطای گویایی پرتاب می‌کنند:"

msgid ":class:`ast.FormattedValue` (f-strings; error is not detected if conversion specifiers like ``!r`` are used)"
msgstr ":class:`ast.FormattedValue` (اف‌استرینگ‌ها؛ در صورت استفاده از مشخص‌کننده‌های تبدیل مانند ``!r``، خطا تشخیص داده نمی‌شود)"

msgid ":class:`ast.JoinedStr` (f-strings)"
msgstr ":class:`ast.JoinedStr` (اف‌استرینگ‌ها)"

msgid "The following are unsupported and result in incorrect output:"
msgstr "موارد زیر پشتیبانی نمی‌شوند و منجر به خروجی نادرست می‌شوند:"

msgid ":class:`ast.BoolOp` (``and`` and ``or``)"
msgstr ":class:`ast.BoolOp` (``and`` و ``or``)"

msgid ":class:`ast.IfExp`"
msgstr ":class:`ast.IfExp`"

msgid ":class:`ast.Lambda`"
msgstr ":class:`ast.Lambda`"

msgid ":class:`ast.ListComp`"
msgstr ":class:`ast.ListComp`"

msgid ":class:`ast.SetComp`"
msgstr ":class:`ast.SetComp`"

msgid ":class:`ast.DictComp`"
msgstr ":class:`ast.DictComp`"

msgid ":class:`ast.GeneratorExp`"
msgstr ":class:`ast.GeneratorExp`"

msgid "The following are disallowed in annotation scopes and therefore not relevant:"
msgstr "موارد زیر در محدوده‌های حاشیه‌نویسی (annotation scopes) مجاز نیستند و بنابراین مرتبط نیستند:"

msgid ":class:`ast.NamedExpr` (``:=``)"
msgstr ":class:`ast.NamedExpr` (``:=``)"

msgid ":class:`ast.Await`"
msgstr ":class:`ast.Await`"

msgid ":class:`ast.Yield`"
msgstr ":class:`ast.Yield`"

msgid ":class:`ast.YieldFrom`"
msgstr ":class:`ast.YieldFrom`"

msgid "Limitations of the ``FORWARDREF`` format"
msgstr "محدودیت‌های قالب ``FORWARDREF``"

msgid "The :attr:`~Format.FORWARDREF` format aims to produce real values as much as possible, with anything that cannot be resolved replaced with :class:`ForwardRef` objects. It is affected by broadly the same Limitations as the :attr:`~Format.STRING` format: annotations that perform operations on literals or that use unsupported expression types may raise exceptions when evaluated using the :attr:`~Format.FORWARDREF` format."
msgstr "قالب :attr:`~Format.FORWARDREF` هدف دارد تا حد امکان مقادیر واقعی تولید کند، به‌طوری که هر چیزی که قابل حل نباشد، با اشیای :class:`ForwardRef` جایگزین می‌شود. این قالب تقریباً همان محدودیت‌های قالب :attr:`~Format.STRING` را دارد: حاشیه‌نویسی‌هایی که عملیاتی را روی مقادیر لفظی انجام می‌دهند یا از انواع عبارت پشتیبانی‌نشده استفاده می‌کنند، ممکن است هنگام ارزیابی با قالب :attr:`~Format.FORWARDREF` استثنا پرتاب کنند."

msgid "Below are a few examples of the behavior with unsupported expressions:"
msgstr "در زیر چند مثال از رفتار در مواجهه با عبارت‌های پشتیبانی‌نشده آمده است:"

msgid ""
">>> from annotationlib import get_annotations, Format\n"
">>> def zerodiv(x: 1 / 0): ...\n"
">>> get_annotations(zerodiv, format=Format.STRING)\n"
"Traceback (most recent call last):\n"
"  ...\n"
"ZeroDivisionError: division by zero\n"
">>> get_annotations(zerodiv, format=Format.FORWARDREF)\n"
"Traceback (most recent call last):\n"
"  ...\n"
"ZeroDivisionError: division by zero\n"
">>> def ifexp(x: 1 if y else 0): ...\n"
">>> get_annotations(ifexp, format=Format.STRING)\n"
"{'x': '1'}"
msgstr ""
">>> from annotationlib import get_annotations, Format\n"
">>> def zerodiv(x: 1 / 0): ...\n"
">>> get_annotations(zerodiv, format=Format.STRING)\n"
"Traceback (most recent call last):\n"
"  ...\n"
"ZeroDivisionError: division by zero\n"
">>> get_annotations(zerodiv, format=Format.FORWARDREF)\n"
"Traceback (most recent call last):\n"
"  ...\n"
"ZeroDivisionError: division by zero\n"
">>> def ifexp(x: 1 if y else 0): ...\n"
">>> get_annotations(ifexp, format=Format.STRING)\n"
"{'x': '1'}"

msgid "Security implications of introspecting annotations"
msgstr "پیامدهای امنیتی درون‌نگری حاشیه‌نویسی‌ها"

msgid "Much of the functionality in this module involves executing code related to annotations, which can then do arbitrary things. For example, :func:`get_annotations` may call an arbitrary :term:`annotate function`, and :meth:`ForwardRef.evaluate` may call :func:`eval` on an arbitrary string. Code contained in an annotation might make arbitrary system calls, enter an infinite loop, or perform any other operation. This is also true for any access of the :attr:`~object.__annotations__` attribute, and for various functions in the :mod:`typing` module that work with annotations, such as :func:`typing.get_type_hints`."
msgstr "بخش زیادی از قابلیت‌های این ماژول شامل اجرای کد مرتبط با حاشیه‌نویسی‌ها  می‌شود؛ کدی که سپس می‌تواند هر کار دلخواهی انجام دهد. برای مثال، :func:`get_annotations` ممکن است یک :term:`annotate function` دلخواه را فراخوانی کند و :meth:`ForwardRef.evaluate` ممکن است :func:`eval` را روی یک رشته دلخواه فراخوانی کند. کد موجود در یک حاشیه‌نویسی ممکن است فراخوانی‌های سیستمی دلخواهی انجام دهد، وارد یک حلقه بی‌پایان شود یا هر عملیات دیگری را انجام دهد. این موضوع برای هرگونه دسترسی به ویژگی :attr:`~object.__annotations__` و برای توابع مختلفی در ماژول :mod:`typing` که با حاشیه‌نویسی‌ها کار می‌کنند، مانند :func:`typing.get_type_hints` نیز صادق است."

msgid "Any security issue arising from this also applies immediately after importing code that may contain untrusted annotations: importing code can always cause arbitrary operations to be performed. However, it is unsafe to accept strings or other input from an untrusted source and pass them to any of the APIs for introspecting annotations, for example by editing an ``__annotations__`` dictionary or directly creating a :class:`ForwardRef` object."
msgstr "هر مشکل امنیتی ناشی از این موضوع، بلافاصله پس از ایمپورت کدی که ممکن است حاوی حاشیه‌گذاری‌های غیرقابل‌اعتماد باشد نیز صدق می‌کند: ایمپورت کد همیشه می‌تواند منجر به اجرای عملیات دلخواه شود. با این حال، پذیرفتن رشته‌ها یا سایر ورودی‌ها از یک منبع غیرقابل‌اعتماد و ارسال آن‌ها به هر یک از APIهای مربوط به درون‌نگری حاشیه‌گذاری‌ها ناامن است، برای مثال با ویرایش یک دیکشنری ``__annotations__`` یا ایجاد مستقیم یک شیء :class:`ForwardRef`."