"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"Descriptor Guide"
msgstr"راهنمای توصیفگر"
msgid"Author"
msgstr"نویسنده"
msgid"Raymond Hettinger"
msgstr"ریموند هتینگر"
msgid"Contact"
msgstr"تماس"
msgid"<python at rcn dot com>"
msgstr"<python at rcn dot com>"
msgid"Contents"
msgstr"فهرست مطالب"
msgid":term:`Descriptors <descriptor>` let objects customize attribute lookup, storage, and deletion."
msgstr":term:`توصیفگرها (Descriptors) <descriptor>` به اشیاء امکان میدهند تا جستجو، ذخیرهسازی و حذف ویژگیها را سفارشیسازی کنند."
msgid"This guide has four major sections:"
msgstr"این راهنما دارای ۴ بخش اصلی است:"
msgid"The \"primer\" gives a basic overview, moving gently from simple examples, adding one feature at a time. Start here if you're new to descriptors."
msgstr"«primer» یک مرور کلی مقدماتی ارائه میدهد و بهآرامی از مثالهای ساده پیش میرود و هر بار یک قابلیت را اضافه میکند. اگر با توصیفگرها تازهکار هستید، از اینجا شروع کنید."
msgid"The second section shows a complete, practical descriptor example. If you already know the basics, start there."
msgstr"بخش دوم نمونهای کامل و کاربردی از توصیفگر (descriptor) را نشان میدهد. اگر از قبل مبانی را میدانید، از همانجا شروع کنید."
msgid"The third section provides a more technical tutorial that goes into the detailed mechanics of how descriptors work. Most people don't need this level of detail."
msgstr"بخش سوم، آموزش فنیتری ارائه میدهد که به سازوکار دقیق چگونگی کار توصیفگرها میپردازد. بیشتر افراد به این سطح از جزئیات نیازی ندارند."
msgid"The last section has pure Python equivalents for built-in descriptors that are written in C. Read this if you're curious about how functions turn into bound methods or about the implementation of common tools like :deco:`classmethod`, :deco:`staticmethod`, :deco:`property`, and :term:`__slots__`."
msgstr"بخش آخر شامل معادلهای پایتون خالص برای توصیفگرهای توکاری است که به زبان C نوشته شدهاند. اگر درباره چگونگی تبدیل توابع به متدهای مقید یا پیادهسازی ابزارهای رایجی مانند :deco:`classmethod`، :deco:`staticmethod`، :deco:`property` و :term:`__slots__` کنجکاوید، این بخش را بخوانید."
msgid"Primer"
msgstr"مقدمات"
msgid"In this primer, we start with the most basic possible example and then we'll add new capabilities one by one."
msgstr"در این آموزش مقدماتی، با سادهترین مثال ممکن شروع میکنیم و سپس قابلیتهای جدید را یکییکی اضافه خواهیم کرد."
msgid"Simple example: A descriptor that returns a constant"
msgstr"مثال ساده: یک توصیفگر که یک مقدار ثابت برمیگرداند"
msgid"The :class:`!Ten` class is a descriptor whose :meth:`~object.__get__` method always returns the constant ``10``:"
msgstr"کلاس :class:`!Ten` یک توصیفگر است که متد :meth:`~object.__get__` آن همیشه ثابت ``10`` را برمیگرداند:"
msgid""
"class Ten:\n"
" def __get__(self, obj, objtype=None):\n"
" return 10"
msgstr""
"class Ten:\n"
" def __get__(self, obj, objtype=None):\n"
" return 10"
msgid"To use the descriptor, it must be stored as a class variable in another class:"
msgstr"برای استفاده از توصیفگر، باید آن را بهعنوان یک متغیر کلاس در کلاس دیگری ذخیره کنید:"
msgid""
"class A:\n"
" x = 5 # Regular class attribute\n"
" y = Ten() # Descriptor instance"
msgstr""
"class A:\n"
" x = 5 # Regular class attribute\n"
" y = Ten() # Descriptor instance"
msgid"An interactive session shows the difference between normal attribute lookup and descriptor lookup:"
msgstr"یک نشست تعاملی تفاوت میان جستجوی عادی ویژگی و جستجوی توصیفگر را نشان میدهد:"
msgid""
">>> a = A() # Make an instance of class A\n"
">>> a.x # Normal attribute lookup\n"
"5\n"
">>> a.y # Descriptor lookup\n"
"10"
msgstr""
">>> a = A() # Make an instance of class A\n"
">>> a.x # Normal attribute lookup\n"
"5\n"
">>> a.y # Descriptor lookup\n"
"10"
msgid"In the ``a.x`` attribute lookup, the dot operator finds ``'x': 5`` in the class dictionary. In the ``a.y`` lookup, the dot operator finds a descriptor instance, recognized by its ``__get__`` method. Calling that method returns ``10``."
msgstr"در جستوجوی ویژگی ``a.x``، عملگر نقطه ``'x': 5`` را در دیکشنری کلاس مییابد. در جستوجوی ``a.y``، عملگر نقطه یک نمونهی توصیفگر را مییابد که با متد ``__get__`` خود شناخته میشود. فراخوانی آن متد ``10`` را برمیگرداند."
msgid"Note that the value ``10`` is not stored in either the class dictionary or the instance dictionary. Instead, the value ``10`` is computed on demand."
msgstr"توجه داشته باشید که مقدار ``10`` در هیچیک از دیکشنری کلاس یا دیکشنری نمونه ذخیره نمیشود. در عوض، مقدار ``10`` در صورت درخواست محاسبه میشود."
msgid"This example shows how a simple descriptor works, but it isn't very useful. For retrieving constants, normal attribute lookup would be better."
msgstr"این مثال نشان میدهد که یک توصیفگر ساده چگونه کار میکند، اما چندان مفید نیست. برای بازیابی ثابتها، جستجوی عادی ویژگی بهتر است."
msgid"In the next section, we'll create something more useful, a dynamic lookup."
msgstr"در بخش بعدی، چیزی مفیدتر ایجاد خواهیم کرد: یک جستجوی پویا."
msgid"Dynamic lookups"
msgstr"جستجوهای پویا"
msgid"Interesting descriptors typically run computations instead of returning constants:"
msgstr"توصیفگرهای جالب معمولاً بهجای برگرداندن ثابتها، محاسبات را اجرا میکنند:"
msgid"An interactive session shows that the lookup is dynamic — it computes different, updated answers each time::"
msgstr"یک نشست تعاملی نشان میدهد که جستجو پویا است — هر بار پاسخهایی متفاوت و بهروز محاسبه میکند::"
msgid""
">>> s = Directory('songs')\n"
">>> g = Directory('games')\n"
">>> s.size # The songs directory has twenty files\n"
"20\n"
">>> g.size # The games directory has three files\n"
"3\n"
">>> os.remove('games/chess') # Delete a game\n"
">>> g.size # File count is automatically updated\n"
"2"
msgstr""
">>> s = Directory('songs')\n"
">>> g = Directory('games')\n"
">>> s.size # The songs directory has twenty files\n"
"20\n"
">>> g.size # The games directory has three files\n"
"3\n"
">>> os.remove('games/chess') # Delete a game\n"
">>> g.size # File count is automatically updated\n"
"2"
msgid"Besides showing how descriptors can run computations, this example also reveals the purpose of the parameters to :meth:`~object.__get__`. The *self* parameter is *size*, an instance of *DirectorySize*. The *obj* parameter is either *g* or *s*, an instance of *Directory*. It is the *obj* parameter that lets the :meth:`~object.__get__` method learn the target directory. The *objtype* parameter is the class *Directory*."
msgstr"علاوه بر نشان دادن این که توصیفگرها چگونه میتوانند محاسبات را اجرا کنند، این مثال همچنین هدف از پارامترهای :meth:`~object.__get__` را آشکار میکند. پارامتر *self*، *size* است که یک نمونه از *DirectorySize* است. پارامتر *obj* یا *g* است یا *s*، یعنی یک نمونه از *Directory*. این پارامتر *obj* است که به متد :meth:`~object.__get__` امکان میدهد پوشه هدف را بشناسد. پارامتر *objtype*، کلاس *Directory* است."
msgid"Managed attributes"
msgstr"ویژگیهای مدیریتشده"
msgid"A popular use for descriptors is managing access to instance data. The descriptor is assigned to a public attribute in the class dictionary while the actual data is stored as a private attribute in the instance dictionary. The descriptor's :meth:`~object.__get__` and :meth:`~object.__set__` methods are triggered when the public attribute is accessed."
msgstr"یک کاربرد رایج توصیفگرها، مدیریت دسترسی به دادههای نمونه است. توصیفگر به یک ویژگی عمومی در دیکشنری کلاس اختصاص داده میشود، در حالی که داده واقعی بهصورت یک ویژگی خصوصی در دیکشنری نمونه ذخیره میشود. متدهای :meth:`~object.__get__` و :meth:`~object.__set__` توصیفگر، هنگام دسترسی به ویژگی عمومی فراخوانی میشوند."
msgid"In the following example, *age* is the public attribute and *_age* is the private attribute. When the public attribute is accessed, the descriptor logs the lookup or update:"
msgstr"در مثال زیر، *age* ویژگی عمومی و *_age* ویژگی خصوصی است. هنگام دسترسی به ویژگی عمومی، توصیفگر جستوجو یا بهروزرسانی را ثبت میکند:"
">>> dave.age # Only the managed attribute is logged\n"
"INFO:root:Accessing 'age' giving 40\n"
"40"
msgid"One major issue with this example is that the private name *_age* is hardwired in the *LoggedAgeAccess* class. That means that each instance can only have one logged attribute and that its name is unchangeable. In the next example, we'll fix that problem."
msgstr"یکی از مشکلات اساسی این مثال این است که نام خصوصی *_age* در کلاس *LoggedAgeAccess* بهصورت سختکد تعریف شده است. این بدان معناست که هر نمونه فقط میتواند یک ویژگی ثبتشده داشته باشد و نام آن تغییرناپذیر است. در مثال بعدی، این مشکل را برطرف خواهیم کرد."
msgid"Customized names"
msgstr"نامهای سفارشی"
msgid"When a class uses descriptors, it can inform each descriptor about which variable name was used."
msgstr"هنگامی که یک کلاس از توصیفگرها استفاده میکند، میتواند به هر توصیفگر اطلاع دهد که کدام نام متغیر استفاده شده است."
msgid"In this example, the :class:`!Person` class has two descriptor instances, *name* and *age*. When the :class:`!Person` class is defined, it makes a callback to :meth:`~object.__set_name__` in *LoggedAccess* so that the field names can be recorded, giving each descriptor its own *public_name* and *private_name*:"
msgstr"در این مثال، کلاس :class:`!Person` دارای دو نمونه از توصیفگرها، *name* و *age* است. هنگامی که کلاس :class:`!Person` تعریف میشود، یک فراخوانی بازگشتی به :meth:`~object.__set_name__` در *LoggedAccess* انجام میدهد تا نام فیلدها بتوانند ثبت شوند و به هر توصیفگر، *public_name* و *private_name* خودش داده شود:"
" logging.info('Updating %r to %r', self.public_name, value)\n"
" setattr(obj, self.private_name, value)\n"
"\n"
"class Person:\n"
"\n"
" name = LoggedAccess() # First descriptor instance\n"
" age = LoggedAccess() # Second descriptor instance\n"
"\n"
" def __init__(self, name, age):\n"
" self.name = name # Calls the first descriptor\n"
" self.age = age # Calls the second descriptor\n"
"\n"
" def birthday(self):\n"
" self.age += 1"
msgid"An interactive session shows that the :class:`!Person` class has called :meth:`~object.__set_name__` so that the field names would be recorded. Here we call :func:`vars` to look up the descriptor without triggering it:"
msgstr"یک نشست تعاملی نشان میدهد که کلاس :class:`!Person` متد :meth:`~object.__set_name__` را فراخوانی کرده است تا نام فیلدها ثبت شوند. در اینجا :func:`vars` را فراخوانی میکنیم تا توصیفگر را بدون فعالسازی آن جستجو کنیم:"
msgid"The new class now logs access to both *name* and *age*:"
msgstr"کلاس جدید اکنون دسترسی به هر دو *name* و *age* را ثبت میکند:"
msgid""
">>> pete = Person('Peter P', 10)\n"
"INFO:root:Updating 'name' to 'Peter P'\n"
"INFO:root:Updating 'age' to 10\n"
">>> kate = Person('Catherine C', 20)\n"
"INFO:root:Updating 'name' to 'Catherine C'\n"
"INFO:root:Updating 'age' to 20"
msgstr""
">>> pete = Person('Peter P', 10)\n"
"INFO:root:Updating 'name' to 'Peter P'\n"
"INFO:root:Updating 'age' to 10\n"
">>> kate = Person('Catherine C', 20)\n"
"INFO:root:Updating 'name' to 'Catherine C'\n"
"INFO:root:Updating 'age' to 20"
msgid"The two *Person* instances contain only the private names:"
msgstr"این دو نمونهی *Person* فقط شامل نامهای خصوصی هستند:"
msgid""
">>> vars(pete)\n"
"{'_name': 'Peter P', '_age': 10}\n"
">>> vars(kate)\n"
"{'_name': 'Catherine C', '_age': 20}"
msgstr""
">>> vars(pete)\n"
"{'_name': 'Peter P', '_age': 10}\n"
">>> vars(kate)\n"
"{'_name': 'Catherine C', '_age': 20}"
msgid"Closing thoughts"
msgstr"سخن پایانی"
msgid"A :term:`descriptor` is what we call any object that defines :meth:`~object.__get__`, :meth:`~object.__set__`, or :meth:`~object.__delete__`."
msgstr"به هر شیءای که :meth:`~object.__get__`، :meth:`~object.__set__`، یا :meth:`~object.__delete__` را تعریف میکند، یک :term:`descriptor` گفته میشود."
msgid"Optionally, descriptors can have a :meth:`~object.__set_name__` method. This is only used in cases where a descriptor needs to know either the class where it was created or the name of class variable it was assigned to. (This method, if present, is called even if the class is not a descriptor.)"
msgstr"بهصورت اختیاری، توصیفگرها میتوانند یک متد :meth:`~object.__set_name__` داشته باشند. این متد فقط در مواردی استفاده میشود که یک توصیفگر نیاز دارد بداند یا کلاسی که در آن ایجاد شده است یا نام متغیر کلاسی که به آن اختصاص داده شده است. (این متد، در صورت وجود، حتی اگر کلاس یک توصیفگر نباشد نیز فراخوانی میشود.)"
msgid"Descriptors get invoked by the dot operator during attribute lookup. If a descriptor is accessed indirectly with ``vars(some_class)[descriptor_name]``, the descriptor instance is returned without invoking it."
msgstr"توصیفگرها در حین جستوجوی ویژگی، بهوسیله عملگر نقطه فراخوانی میشوند. اگر به یک توصیفگر بهطور غیرمستقیم از طریق ``vars(some_class)[descriptor_name]`` دسترسی پیدا شود، نمونهی توصیفگر بدون فراخوانی آن برگردانده میشود."
msgid"Descriptors only work when used as class variables. When put in instances, they have no effect."
msgstr"توصیفگرها تنها زمانی کار میکنند که بهعنوان متغیرهای کلاس استفاده شوند. هنگامی که در نمونهها قرار داده شوند، هیچ تأثیری ندارند."
msgid"The main motivation for descriptors is to provide a hook allowing objects stored in class variables to control what happens during attribute lookup."
msgstr"انگیزهی اصلی توصیفگرها، فراهم کردن قلابی است که به اشیاء ذخیرهشده در متغیرهای کلاس اجازه میدهد کنترل کنند در هنگام جستوجوی ویژگی چه اتفاقی میافتد."
msgid"Traditionally, the calling class controls what happens during lookup. Descriptors invert that relationship and allow the data being looked-up to have a say in the matter."
msgstr"بهطور سنتی، کلاس فراخوان کنترل میکند که در حین جستجو چه اتفاقی بیفتد. توصیفگرها آن رابطه را معکوس میکنند و به دادهی مورد جستجو اجازه میدهند در این موضوع دخالت داشته باشد."
msgid"Descriptors are used throughout the language. It is how functions turn into bound methods. Common tools like :deco:`classmethod`, :deco:`staticmethod`, :deco:`property`, and :deco:`functools.cached_property` are all implemented as descriptors."
msgstr"توصیفگرها در سراسر زبان استفاده میشوند. این سازوکاری است که از طریق آن توابع به متدهای مقید (bound methods) تبدیل میشوند. ابزارهای رایجی مانند :deco:`classmethod`، :deco:`staticmethod`، :deco:`property` و :deco:`functools.cached_property` همگی بهعنوان توصیفگر پیادهسازی شدهاند."
msgid"Complete Practical Example"
msgstr"مثال عملی کامل"
msgid"In this example, we create a practical and powerful tool for locating notoriously hard to find data corruption bugs."
msgstr"در این مثال، یک ابزار کاربردی و قدرتمند برای یافتن اشکالهای خرابی داده که یافتنشان بسیار دشوار است، میسازیم."
msgid"Validator class"
msgstr"کلاس اعتبارسنج"
msgid"A validator is a descriptor for managed attribute access. Prior to storing any data, it verifies that the new value meets various type and range restrictions. If those restrictions aren't met, it raises an exception to prevent data corruption at its source."
msgstr"اعتبارسنج توصیفگری برای دسترسی مدیریتشده به ویژگی است. پیش از ذخیره هرگونه داده، بررسی میکند که مقدار جدید محدودیتهای مختلف نوع و دامنه را برآورده میکند. اگر این محدودیتها برآورده نشوند، استثنایی را پرتاب میکند تا از فساد داده در مبدأ جلوگیری شود."
msgid"This :class:`!Validator` class is both an :term:`abstract base class` and a managed attribute descriptor:"
msgstr"این کلاس :class:`!Validator` هم یک :term:`کلاس پایه انتزاعی <abstract base class>` و هم یک توصیفگر ویژگی مدیریتشده است:"
msgid""
"from abc import ABC, abstractmethod\n"
"\n"
"class Validator(ABC):\n"
"\n"
" def __set_name__(self, owner, name):\n"
" self.private_name = '_' + name\n"
"\n"
" def __get__(self, obj, objtype=None):\n"
" return getattr(obj, self.private_name)\n"
"\n"
" def __set__(self, obj, value):\n"
" self.validate(value)\n"
" setattr(obj, self.private_name, value)\n"
"\n"
" @abstractmethod\n"
" def validate(self, value):\n"
" pass"
msgstr""
"from abc import ABC, abstractmethod\n"
"\n"
"class Validator(ABC):\n"
"\n"
" def __set_name__(self, owner, name):\n"
" self.private_name = '_' + name\n"
"\n"
" def __get__(self, obj, objtype=None):\n"
" return getattr(obj, self.private_name)\n"
"\n"
" def __set__(self, obj, value):\n"
" self.validate(value)\n"
" setattr(obj, self.private_name, value)\n"
"\n"
" @abstractmethod\n"
" def validate(self, value):\n"
" pass"
msgid"Custom validators need to inherit from :class:`!Validator` and must supply a :meth:`!validate` method to test various restrictions as needed."
msgstr"اعتبارسنجهای سفارشی باید از :class:`!Validator` ارثبری کنند و یک متد :meth:`!validate` برای آزمایش محدودیتهای مختلف در صورت نیاز فراهم کنند."
msgid"Custom validators"
msgstr"اعتبارسنجهای سفارشی"
msgid"Here are three practical data validation utilities:"
msgstr"در اینجا سه ابزار کاربردی برای اعتبارسنجی دادهها آمده است:"
msgid":class:`!OneOf` verifies that a value is one of a restricted set of options."
msgstr":class:`!OneOf` تأیید میکند که یک مقدار یکی از اعضای مجموعهای محدود از گزینهها است."
msgid":class:`!Number` verifies that a value is either an :class:`int` or :class:`float`. Optionally, it verifies that a value is between a given minimum or maximum."
msgstr":class:`!Number` تأیید میکند که یک مقدار یا :class:`int` است یا :class:`float`. بهصورت اختیاری، تأیید میکند که یک مقدار بین یک کمینه یا بیشینهی دادهشده باشد."
msgid":class:`!String` verifies that a value is a :class:`str`. Optionally, it validates a given minimum or maximum length. It can validate a user-defined `predicate <https://en.wikipedia.org/wiki/Predicate_(mathematical_logic)>`_ as well."
msgstr":class:`!String` تأیید میکند که یک مقدار از نوع :class:`str` است. بهصورت اختیاری، حداقل یا حداکثر طول دادهشده را اعتبارسنجی میکند. همچنین میتواند یک `محمول (predicate) <https://fa.wikipedia.org/wiki/محمول>`_ تعریفشده توسط کاربر را نیز اعتبارسنجی کند."
msgid""
"class OneOf(Validator):\n"
"\n"
" def __init__(self, *options):\n"
" self.options = set(options)\n"
"\n"
" def validate(self, value):\n"
" if value not in self.options:\n"
" raise ValueError(\n"
" f'Expected {value!r} to be one of {self.options!r}'\n"
" raise TypeError(f'Expected {value!r} to be a str')\n"
" if self.minsize is not None and len(value) < self.minsize:\n"
" raise ValueError(\n"
" f'Expected {value!r} to be no smaller than {self.minsize!r}'\n"
" )\n"
" if self.maxsize is not None and len(value) > self.maxsize:\n"
" raise ValueError(\n"
" f'Expected {value!r} to be no bigger than {self.maxsize!r}'\n"
" )\n"
" if self.predicate is not None and not self.predicate(value):\n"
" raise ValueError(\n"
" f'Expected {self.predicate} to be true for {value!r}'\n"
" )"
msgid"Practical application"
msgstr"کاربرد عملی"
msgid"Here's how the data validators can be used in a real class:"
msgstr"در اینجا چگونگی استفاده از اعتبارسنجهای داده در یک کلاس واقعی آمده است:"
msgid""
"class Component:\n"
"\n"
" name = String(minsize=3, maxsize=10, predicate=str.isupper)\n"
" kind = OneOf('wood', 'metal', 'plastic')\n"
" quantity = Number(minvalue=0)\n"
"\n"
" def __init__(self, name, kind, quantity):\n"
" self.name = name\n"
" self.kind = kind\n"
" self.quantity = quantity"
msgstr""
"class Component:\n"
"\n"
" name = String(minsize=3, maxsize=10, predicate=str.isupper)\n"
" kind = OneOf('wood', 'metal', 'plastic')\n"
" quantity = Number(minvalue=0)\n"
"\n"
" def __init__(self, name, kind, quantity):\n"
" self.name = name\n"
" self.kind = kind\n"
" self.quantity = quantity"
msgid"The descriptors prevent invalid instances from being created:"
msgstr"توصیفگرها از ایجاد نمونههای نامعتبر جلوگیری میکنند:"
msgid""
">>> Component('Widget', 'metal', 5) # Blocked: 'Widget' is not all uppercase\n"
"Traceback (most recent call last):\n"
" ...\n"
"ValueError: Expected <method 'isupper' of 'str' objects> to be true for 'Widget'\n"
"\n"
">>> Component('WIDGET', 'metle', 5) # Blocked: 'metle' is misspelled\n"
"Traceback (most recent call last):\n"
" ...\n"
"ValueError: Expected 'metle' to be one of {'metal', 'plastic', 'wood'}\n"
"\n"
">>> Component('WIDGET', 'metal', -5) # Blocked: -5 is negative\n"
"Traceback (most recent call last):\n"
" ...\n"
"ValueError: Expected -5 to be at least 0\n"
"\n"
">>> Component('WIDGET', 'metal', 'V') # Blocked: 'V' isn't a number\n"
"Traceback (most recent call last):\n"
" ...\n"
"TypeError: Expected 'V' to be an int or float\n"
"\n"
">>> c = Component('WIDGET', 'metal', 5) # Allowed: The inputs are valid"
msgstr""
">>> Component('Widget', 'metal', 5) # Blocked: 'Widget' is not all uppercase\n"
"Traceback (most recent call last):\n"
" ...\n"
"ValueError: Expected <method 'isupper' of 'str' objects> to be true for 'Widget'\n"
"\n"
">>> Component('WIDGET', 'metle', 5) # Blocked: 'metle' is misspelled\n"
"Traceback (most recent call last):\n"
" ...\n"
"ValueError: Expected 'metle' to be one of {'metal', 'plastic', 'wood'}\n"
"\n"
">>> Component('WIDGET', 'metal', -5) # Blocked: -5 is negative\n"
"Traceback (most recent call last):\n"
" ...\n"
"ValueError: Expected -5 to be at least 0\n"
"\n"
">>> Component('WIDGET', 'metal', 'V') # Blocked: 'V' isn't a number\n"
"Traceback (most recent call last):\n"
" ...\n"
"TypeError: Expected 'V' to be an int or float\n"
"\n"
">>> c = Component('WIDGET', 'metal', 5) # Allowed: The inputs are valid"
msgid"Technical Tutorial"
msgstr"آموزش فنی"
msgid"What follows is a more technical tutorial for the mechanics and details of how descriptors work."
msgstr"آنچه در ادامه میآید، آموزش فنیتری دربارهی سازوکار و جزئیات چگونگی کار توصیفگرها است."
msgid"Abstract"
msgstr"چکیده"
msgid"Defines descriptors, summarizes the protocol, and shows how descriptors are called. Provides an example showing how object relational mappings work."
msgstr"توصیفگرها را تعریف میکند، پروتکل را خلاصه میکند و نحوه فراخوانی توصیفگرها را نشان میدهد. مثالی ارائه میکند که نشان میدهد نگاشتهای شیء-رابطهای چگونه کار میکنند."
msgid"Learning about descriptors not only provides access to a larger toolset, it creates a deeper understanding of how Python works."
msgstr"یادگیری توصیفگرها نهتنها دسترسی به مجموعهابزار بزرگتری را فراهم میکند، بلکه درک عمیقتری از نحوه کارکرد پایتون ایجاد میکند."
msgid"Definition and introduction"
msgstr"تعریف و مقدمه"
msgid"In general, a descriptor is an attribute value that has one of the methods in the descriptor protocol. Those methods are :meth:`~object.__get__`, :meth:`~object.__set__`, and :meth:`~object.__delete__`. If any of those methods are defined for an attribute, it is said to be a :term:`descriptor`."
msgstr"بهطور کلی، توصیفگر یک مقدار ویژگی است که یکی از متدهای پروتکل توصیفگر را دارد. آن متدها عبارتاند از :meth:`~object.__get__`، :meth:`~object.__set__` و :meth:`~object.__delete__`. اگر هر یک از آن متدها برای یک ویژگی تعریف شده باشد، به آن :term:`توصیفگر <descriptor>` گفته میشود."
msgid"The default behavior for attribute access is to get, set, or delete the attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and continuing through the method resolution order of ``type(a)``. If the looked-up value is an object defining one of the descriptor methods, then Python may override the default behavior and invoke the descriptor method instead. Where this occurs in the precedence chain depends on which descriptor methods were defined."
msgstr"رفتار پیشفرض برای دسترسی به ویژگی این است که ویژگی از دیکشنری یک شیء دریافت، تنظیم یا حذف شود. برای مثال، ``a.x`` یک زنجیره جستجو دارد که با ``a.__dict__['x']`` شروع میشود، سپس به ``type(a).__dict__['x']`` میرسد و از طریق ترتیب حل متد ``type(a)`` ادامه مییابد. اگر مقدار جستجوشده شیئی باشد که یکی از متدهای توصیفگر را تعریف میکند، پایتون ممکن است رفتار پیشفرض را نادیده بگیرد و در عوض متد توصیفگر را فراخوانی کند. اینکه این اتفاق در کجای زنجیره اولویت رخ میدهد، به این بستگی دارد که کدام متدهای توصیفگر تعریف شدهاند."
msgid"Descriptors are a powerful, general purpose protocol. They are the mechanism behind properties, methods, static methods, class methods, and :func:`super`. They are used throughout Python itself. Descriptors simplify the underlying C code and offer a flexible set of new tools for everyday Python programs."
msgstr"توصیفگرها یک پروتکل قدرتمند و با کاربرد عمومی هستند. آنها سازوکار پشت ویژگیها، متدها، متدهای ایستا، متدهای کلاس و :func:`super` هستند. آنها در سراسر خود پایتون استفاده میشوند. توصیفگرها کد C زیربنایی را ساده میکنند و مجموعهای انعطافپذیر از ابزارهای جدید برای برنامههای روزمره پایتون ارائه میدهند."
msgid"Descriptor protocol"
msgstr"پروتکل توصیفگر"
msgid"``descr.__get__(self, obj, type=None)``"
msgstr"``descr.__get__(self, obj, type=None)``"
msgid"``descr.__set__(self, obj, value)``"
msgstr"``descr.__set__(self, obj, value)``"
msgid"``descr.__delete__(self, obj)``"
msgstr"``descr.__delete__(self, obj)``"
msgid"That is all there is to it. Define any of these methods and an object is considered a descriptor and can override default behavior upon being looked up as an attribute."
msgstr"تمام مطلب همین است. هر یک از این متدها را تعریف کنید، آن شیء یک توصیفگر محسوب میشود و میتواند رفتار پیشفرض را هنگامی که بهعنوان یک ویژگی مورد جستجو قرار میگیرد، بازنویسی کند."
msgid"If an object defines :meth:`~object.__set__` or :meth:`~object.__delete__`, it is considered a data descriptor. Descriptors that only define :meth:`~object.__get__` are called non-data descriptors (they are often used for methods but other uses are possible)."
msgstr"اگر یک شیء :meth:`~object.__set__` یا :meth:`~object.__delete__` را تعریف کند، یک توصیفگر داده محسوب میشود. توصیفگرهایی که فقط :meth:`~object.__get__` را تعریف میکنند، توصیفگرهای غیرداده نامیده میشوند (آنها اغلب برای متدها استفاده میشوند، اما ممکن است کاربردهای دیگری نیز داشته باشند)."
msgid"Data and non-data descriptors differ in how overrides are calculated with respect to entries in an instance's dictionary. If an instance's dictionary has an entry with the same name as a data descriptor, the data descriptor takes precedence. If an instance's dictionary has an entry with the same name as a non-data descriptor, the dictionary entry takes precedence."
msgstr"توصیفگرهای دادهای و غیردادهای در نحوه محاسبه بازنویسیها نسبت به ورودیهای دیکشنری یک نمونه تفاوت دارند. اگر دیکشنری یک نمونه ورودیای با همان نام یک توصیفگر دادهای داشته باشد، توصیفگر دادهای اولویت دارد. اگر دیکشنری یک نمونه ورودیای با همان نام یک توصیفگر غیردادهای داشته باشد، ورودی دیکشنری اولویت دارد."
msgid"To make a read-only data descriptor, define both :meth:`~object.__get__` and :meth:`~object.__set__` with the :meth:`~object.__set__` raising an :exc:`AttributeError` when called. Defining the :meth:`~object.__set__` method with an exception raising placeholder is enough to make it a data descriptor."
msgstr"برای ساخت یک توصیفگر دادهی فقطخواندنی، هر دو :meth:`~object.__get__` و :meth:`~object.__set__` را تعریف کنید، بهگونهای که :meth:`~object.__set__` هنگام فراخوانی یک :exc:`AttributeError` پرتاب کند. تعریف متد :meth:`~object.__set__` با یک جاینگهدار که استثنا پرتاب میکند، برای تبدیل آن به یک توصیفگر داده کافی است."
msgid"Overview of descriptor invocation"
msgstr"نمای کلی از فراخوانی توصیفگر"
msgid"A descriptor can be called directly with ``desc.__get__(obj)`` or ``desc.__get__(None, cls)``."
msgstr"میتوان یک توصیفگر را مستقیماً با ``desc.__get__(obj)`` یا ``desc.__get__(None, cls)`` فراخوانی کرد."
msgid"But it is more common for a descriptor to be invoked automatically from attribute access."
msgstr"اما رایجتر است که یک توصیفگر بهطور خودکار از طریق دسترسی به ویژگی فراخوانی شود."
msgid"The expression ``obj.x`` looks up the attribute ``x`` in the chain of namespaces for ``obj``. If the search finds a descriptor outside of the instance :attr:`~object.__dict__`, its :meth:`~object.__get__` method is invoked according to the precedence rules listed below."
msgstr"عبارت ``obj.x`` ویژگی ``x`` را در زنجیرهای از فضای نامها برای ``obj`` جستجو میکند. اگر جستجو یک توصیفگر را خارج از :attr:`~object.__dict__` نمونه بیابد، متد :meth:`~object.__get__` آن بر اساس قواعد تقدم فهرستشده در زیر فراخوانی میشود."
msgid"The details of invocation depend on whether ``obj`` is an object, class, or instance of super."
msgstr"جزئیات فراخوانی به این بستگی دارد که ``obj`` یک شیء، کلاس یا نمونهای از super باشد."
msgid"Invocation from an instance"
msgstr"فراخوانی از یک نمونه"
msgid"Instance lookup scans through a chain of namespaces giving data descriptors the highest priority, followed by instance variables, then non-data descriptors, then class variables, and lastly :meth:`~object.__getattr__` if it is provided."
msgstr"جستجوی نمونه، زنجیرهای از فضای نامها را پیمایش میکند و بیشترین اولویت را به توصیفگرهای دادهای میدهد؛ پس از آنها متغیرهای نمونه، سپس توصیفگرهای غیردادهای، سپس متغیرهای کلاس و در نهایت :meth:`~object.__getattr__`، اگر فراهم شده باشد، قرار دارند."
msgid"If a descriptor is found for ``a.x``, then it is invoked with: ``desc.__get__(a, type(a))``."
msgstr"اگر توصیفگری برای ``a.x`` یافت شود، سپس با ``desc.__get__(a, type(a))`` فراخوانی میشود."
msgid"The logic for a dotted lookup is in :meth:`object.__getattribute__`. Here is a pure Python equivalent:"
msgstr"منطق جستجوی نقطهدار در :meth:`object.__getattribute__` قرار دارد. در اینجا یک معادل پایتون خالص آمده است:"
msgid""
"def find_name_in_mro(cls, name, default):\n"
" \"Emulate _PyType_Lookup() in Objects/typeobject.c\"\n"
" for base in cls.__mro__:\n"
" if name in vars(base):\n"
" return vars(base)[name]\n"
" return default\n"
"\n"
"def object_getattribute(obj, name):\n"
" \"Emulate PyObject_GenericGetAttr() in Objects/object.c\"\n"
msgid"Note, there is no :meth:`~object.__getattr__` hook in the :meth:`~object.__getattribute__` code. That is why calling :meth:`~object.__getattribute__` directly or with ``super().__getattribute__`` will bypass :meth:`~object.__getattr__` entirely."
msgstr"توجه داشته باشید که در کد :meth:`~object.__getattribute__` هیچ قلاب :meth:`~object.__getattr__` وجود ندارد. به همین دلیل است که فراخوانی مستقیم :meth:`~object.__getattribute__` یا از طریق ``super().__getattribute__``، :meth:`~object.__getattr__` را بهطور کامل دور میزند."
msgid"Instead, it is the dot operator and the :func:`getattr` function that are responsible for invoking :meth:`~object.__getattr__` whenever :meth:`~object.__getattribute__` raises an :exc:`AttributeError`. Their logic is encapsulated in a helper function:"
msgstr"در عوض، این عملگر نقطه و تابع :func:`getattr` هستند که هرگاه :meth:`~object.__getattribute__` استثنای :exc:`AttributeError` را پرتاب کند، مسئول فراخوانی :meth:`~object.__getattr__` هستند. منطق آنها در یک تابع کمکی کپسوله شده است:"
msgid""
"def getattr_hook(obj, name):\n"
" \"Emulate slot_tp_getattr_hook() in Objects/typeobject.c\"\n"
msgid"The logic for a dotted lookup such as ``A.x`` is in :meth:`!type.__getattribute__`. The steps are similar to those for :meth:`!object.__getattribute__` but the instance dictionary lookup is replaced by a search through the class's :term:`method resolution order`."
msgstr"منطق جستجوی نقطهدار مانند ``A.x`` در :meth:`!type.__getattribute__` قرار دارد. این مراحل مشابه مراحل :meth:`!object.__getattribute__` هستند، اما جستجوی دیکشنری نمونه با جستجو در :term:`ترتیب حل متد <method resolution order>` کلاس جایگزین میشود."
msgid"If a descriptor is found, it is invoked with ``desc.__get__(None, A)``."
msgstr"اگر یک توصیفگر یافت شود، با ``desc.__get__(None, A)`` فراخوانی میشود."
msgid"The full C implementation can be found in :c:func:`!type_getattro` and :c:func:`!_PyType_Lookup` in :source:`Objects/typeobject.c`."
msgstr"پیادهسازی کامل به زبان C را میتوان در :c:func:`!type_getattro` و :c:func:`!_PyType_Lookup` در :source:`Objects/typeobject.c` یافت."
msgid"Invocation from super"
msgstr"فراخوانی از super"
msgid"The logic for super's dotted lookup is in the :meth:`~object.__getattribute__` method for object returned by :func:`super`."
msgstr"منطق جستجوی نقطهدار super در متد :meth:`~object.__getattribute__` برای شیء برگرداندهشده توسط :func:`super` قرار دارد."
msgid"A dotted lookup such as ``super(A, obj).m`` searches ``obj.__class__.__mro__`` for the base class ``B`` immediately following ``A`` and then returns ``B.__dict__['m'].__get__(obj, A)``. If not a descriptor, ``m`` is returned unchanged."
msgstr"یک جستجوی نقطهای مانند ``super(A, obj).m`` در ``obj.__class__.__mro__`` به دنبال کلاس پایه ``B`` میگردد که بلافاصله پس از ``A`` قرار دارد و سپس ``B.__dict__['m'].__get__(obj, A)`` را برمیگرداند. اگر توصیفگر نباشد، ``m`` بدون تغییر برمیگردد."
msgid"The full C implementation can be found in :c:func:`!super_getattro` in :source:`Objects/typeobject.c`. A pure Python equivalent can be found in `Guido's Tutorial <https://www.python.org/download/releases/2.2.3/descrintro/#cooperation>`_."
msgstr"پیادهسازی کامل C را میتوان در :c:func:`!super_getattro` در :source:`Objects/typeobject.c` یافت. یک معادل پایتون خالص را میتوان در `Guido's Tutorial <https://www.python.org/download/releases/2.2.3/descrintro/#cooperation>`_ یافت."
msgid"Summary of invocation logic"
msgstr"خلاصه منطق فراخوانی"
msgid"The mechanism for descriptors is embedded in the :meth:`~object.__getattribute__` methods for :class:`object`, :class:`type`, and :func:`super`."
msgstr"سازوکار توصیفگرها در متدهای :meth:`~object.__getattribute__` برای :class:`object`، :class:`type` و :func:`super` تعبیه شده است."
msgid"The important points to remember are:"
msgstr"نکات مهمی که باید به خاطر داشته باشید:"
msgid"Descriptors are invoked by the :meth:`~object.__getattribute__` method."
msgstr"توصیفگرها توسط متد :meth:`~object.__getattribute__` فراخوانی میشوند."
msgid"Classes inherit this machinery from :class:`object`, :class:`type`, or :func:`super`."
msgstr"کلاسها این سازوکار را از :class:`object`، :class:`type` یا :func:`super` به ارث میبرند."
msgid"Overriding :meth:`~object.__getattribute__` prevents automatic descriptor calls because all the descriptor logic is in that method."
msgstr"بازنویسی :meth:`~object.__getattribute__` از فراخوانیهای خودکار توصیفگر جلوگیری میکند، زیرا تمام منطق توصیفگر در آن متد قرار دارد."
msgid":meth:`!object.__getattribute__` and :meth:`!type.__getattribute__` make different calls to :meth:`~object.__get__`. The first includes the instance and may include the class. The second puts in ``None`` for the instance and always includes the class."
msgstr":meth:`!object.__getattribute__` و :meth:`!type.__getattribute__` :meth:`~object.__get__` را بهصورت متفاوتی فراخوانی میکنند. فراخوانی اول شامل نمونه است و ممکن است شامل کلاس باشد. فراخوانی دوم برای نمونه ``None`` قرار میدهد و همیشه شامل کلاس است."
msgstr"توصیفگرهای داده همیشه بر دیکشنریهای نمونه اولویت دارند."
msgid"Non-data descriptors may be overridden by instance dictionaries."
msgstr"توصیفگرهای غیردادهای ممکن است توسط دیکشنریهای نمونه پوشانده شوند."
msgid"Automatic name notification"
msgstr"اطلاعرسانی خودکار نام"
msgid"Sometimes it is desirable for a descriptor to know what class variable name it was assigned to. When a new class is created, the :class:`type` metaclass scans the dictionary of the new class. If any of the entries are descriptors and if they define :meth:`~object.__set_name__`, that method is called with two arguments. The *owner* is the class where the descriptor is used, and the *name* is the class variable the descriptor was assigned to."
msgstr"گاهی مطلوب است که یک توصیفگر بداند به نام کدام متغیر کلاس اختصاص داده شده است. هنگامی که یک کلاس جدید ایجاد میشود، فراکلاس :class:`type` دیکشنری کلاس جدید را پیمایش میکند. اگر هر یک از آیتمها توصیفگر باشند و اگر :meth:`~object.__set_name__` را تعریف کرده باشند، آن متد با دو آرگومان فراخوانی میشود. *owner* کلاسی است که توصیفگر در آن استفاده میشود، و *name* متغیر کلاس است که توصیفگر به آن اختصاص داده شده است."
msgid"The implementation details are in :c:func:`!type_new` and :c:func:`!set_names` in :source:`Objects/typeobject.c`."
msgstr"جزئیات پیادهسازی در :c:func:`!type_new` و :c:func:`!set_names` در :source:`Objects/typeobject.c` قرار دارد."
msgid"Since the update logic is in :meth:`!type.__new__`, notifications only take place at the time of class creation. If descriptors are added to the class afterwards, :meth:`~object.__set_name__` will need to be called manually."
msgstr"از آنجا که منطق بهروزرسانی در :meth:`!type.__new__` قرار دارد، اعلانها فقط در زمان ایجاد کلاس رخ میدهند. اگر توصیفگرها بعداً به کلاس اضافه شوند، باید :meth:`~object.__set_name__` بهصورت دستی فراخوانی شود."
msgid"ORM example"
msgstr"مثال ORM"
msgid"The following code is a simplified skeleton showing how data descriptors could be used to implement an `object relational mapping <https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping>`_."
msgstr"کد زیر اسکلت سادهشدهای است که نشان میدهد چگونه میتوان از توصیفگرهای داده برای پیادهسازی یک `نگاشت شیء-رابطهای <https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping>`_ استفاده کرد."
msgid"The essential idea is that the data is stored in an external database. The Python instances only hold keys to the database's tables. Descriptors take care of lookups or updates:"
msgstr"ایده اصلی این است که دادهها در یک پایگاه داده خارجی ذخیره میشوند. نمونههای پایتون تنها کلیدهای جدولهای پایگاه داده را نگه میدارند. توصیفگرها به جستوجوها یا بهروزرسانیها رسیدگی میکنند:"
msgid""
"class Field:\n"
"\n"
" def __set_name__(self, owner, name):\n"
" self.fetch = f'SELECT {name} FROM {owner.table} WHERE {owner.key}=?;'\n"
" self.store = f'UPDATE {owner.table} SET {name}=? WHERE {owner.key}=?;'\n"
msgid"We can use the :class:`!Field` class to define `models <https://en.wikipedia.org/wiki/Database_model>`_ that describe the schema for each table in a database:"
msgstr"میتوانیم از کلاس :class:`!Field` برای تعریف `مدلها <https://fa.wikipedia.org/wiki/مدلهای_انتزاعی_پایگاه_دادهها>`_ استفاده کنیم که طرحواره هر جدول در یک پایگاه داده را توصیف میکنند:"
msgid""
"class Movie:\n"
" table = 'Movies' # Table name\n"
" key = 'title' # Primary key\n"
" director = Field()\n"
" year = Field()\n"
"\n"
" def __init__(self, key):\n"
" self.key = key\n"
"\n"
"class Song:\n"
" table = 'Music'\n"
" key = 'title'\n"
" artist = Field()\n"
" year = Field()\n"
" genre = Field()\n"
"\n"
" def __init__(self, key):\n"
" self.key = key"
msgstr""
"class Movie:\n"
" table = 'Movies' # Table name\n"
" key = 'title' # Primary key\n"
" director = Field()\n"
" year = Field()\n"
"\n"
" def __init__(self, key):\n"
" self.key = key\n"
"\n"
"class Song:\n"
" table = 'Music'\n"
" key = 'title'\n"
" artist = Field()\n"
" year = Field()\n"
" genre = Field()\n"
"\n"
" def __init__(self, key):\n"
" self.key = key"
msgid"To use the models, first connect to the database::"
msgstr"برای استفاده از مدلها، ابتدا به پایگاه داده متصل شوید::"
msgid""
">>> import sqlite3\n"
">>> conn = sqlite3.connect('entertainment.db')"
msgstr""
">>> import sqlite3\n"
">>> conn = sqlite3.connect('entertainment.db')"
msgid"An interactive session shows how data is retrieved from the database and how it can be updated:"