GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing python.github.io — collections.abc --- کلاس‌های پایه انتزاعی برای ظروف

`collections.abc` --- کلاس‌های پایه انتزاعی برای ظروف¶

اضافه شده در نسخه‌ی 3.3: پیش‌تر، این ماژول بخشی از ماژول collections بود.

این ماژول کلاس‌های پایه انتزاعی را فراهم می‌کند که می‌توان از آن‌ها برای بررسی این‌که آیا یک کلاس رابط خاصی را ارائه می‌دهد استفاده کرد؛ برای مثال، این‌که آیا هش‌پذیر است یا یک نگاشت است.

یک آزمون issubclass() یا isinstance() برای یک رابط به یکی از سه روش عمل می‌کند.

یک کلاس تازه‌نوشته‌شده می‌تواند مستقیماً از یکی از کلاس‌های پایه انتزاعی ارث ببرد. این کلاس باید متدهای انتزاعی مورد نیاز را فراهم کند. متدهای میکس‌این باقی‌مانده از طریق ارث‌بری به دست می‌آیند و در صورت تمایل می‌توان آن‌ها را بازنویسی کرد. در صورت نیاز، می‌توان متدهای دیگری اضافه کرد:
```
class C(Sequence):                      # Direct inheritance
    def __init__(self): ...             # Extra method not required by the ABC
    def __getitem__(self, index):  ...  # Required abstract method
    def __len__(self):  ...             # Required abstract method
    def count(self, value): ...         # Optionally override a mixin method
```
```
>>> issubclass(C, Sequence)
True
>>> isinstance(C(), Sequence)
True
```
کلاس‌های موجود و کلاس‌های توکار می‌توانند به‌عنوان «زیرکلاس‌های مجازی» ABCها ثبت شوند. آن کلاس‌ها باید API کامل را، شامل تمام متدهای انتزاعی و تمام متدهای میکس‌این، تعریف کنند. این امر به کاربران اجازه می‌دهد برای تعیین اینکه آیا رابط کامل پشتیبانی می‌شود، به آزمون‌های issubclass() یا isinstance() اتکا کنند. استثنای این قاعده برای متدهایی است که به‌طور خودکار از باقی API استنتاج می‌شوند:
```
class D:                                 # No inheritance
    def __init__(self): ...              # Extra method not required by the ABC
    def __getitem__(self, index):  ...   # Abstract method
    def __len__(self):  ...              # Abstract method
    def count(self, value): ...          # Mixin method
    def index(self, value): ...          # Mixin method

Sequence.register(D)                     # Register instead of inherit
```
```
>>> issubclass(D, Sequence)
True
>>> isinstance(D(), Sequence)
True
```
در این مثال، کلاس D نیازی به تعریف __contains__، __iter__ و __reversed__ ندارد، زیرا عملگر in، منطق پیمایش و تابع reversed() به‌طور خودکار به استفاده از __getitem__ و __len__ بازمی‌گردند.
برخی رابط‌های ساده مستقیماً از روی وجود متدهای مورد نیاز قابل تشخیص هستند (مگر آنکه آن متدها روی None تنظیم شده باشند):
```
class E:
    def __iter__(self): ...
    def __next__(self): ...
```
```
>>> issubclass(E, Iterable)
True
>>> isinstance(E(), Iterable)
True
```
رابط‌های پیچیده از این روش آخر پشتیبانی نمی‌کنند، زیرا یک رابط چیزی فراتر از صرف وجود نام متدها است. رابط‌ها معناشناسی و روابط میان متدها را مشخص می‌کنند، که نمی‌توان آن‌ها را صرفاً از وجود نام متدهای خاص استنتاج کرد. برای مثال، دانستن اینکه یک کلاس __getitem__، __len__ و __iter__ را فراهم می‌کند، برای تمایز Sequence از Mapping کافی نیست.

اضافه شده در نسخه‌ی 3.9: این کلاس‌های انتزاعی اکنون از [] پشتیبانی می‌کنند. نوع نام مستعار عام و PEP 585 را ببینید.

کلاس‌های پایه انتزاعی مجموعه‌ها¶

The collections module offers the following ABCs, where the "Abstract Methods" column lists all required abstract methods, including those inherited from parent classes:

ABC	به ارث می‌برد از	متدهای انتزاعی	متدهای میکس‌این
`Container` [1]		`__contains__`
`Hashable` [1]		`__hash__`
`Iterable` [1] [2]		`__iter__`
`Iterator` [1]	`Iterable`	`__next__`	`__iter__`
`Reversible` [1]	`Iterable`	`__getitem__`, `__len__`
`Generator` [1]	`Iterator`	`send`, `throw`	`close`, `__iter__`, `__next__`
`Sized` [1]		`__len__`
`Callable` [1]		`__call__`
`Collection` [1]	`Sized`, `Iterable`, `Container`	`__contains__`, `__iter__`, `__len__`
`Sequence`	`Reversible`, `Collection`	`__getitem__`, `__len__`	`__contains__`، `__iter__`، `__reversed__`، `index` و `count`
`MutableSequence`	`Sequence`	`__getitem__`, `__setitem__`, `__delitem__`, `__len__`, `insert`	متدهای به ارث رسیده از `Sequence` و `append`، `clear`، `reverse`، `extend`، `pop`، `remove` و `__iadd__`
`ByteString`	`Sequence`	`__getitem__`, `__len__`	متدهای موروثی `Sequence`
`Set`	`Collection`	`__contains__`, `__iter__`, `__len__`	`__le__`، `__lt__`، `__eq__`، `__ne__`، `__gt__`، `__ge__`، `__and__`، `__or__`، `__sub__`، `__rsub__`، `__xor__`، `__rxor__` و `isdisjoint`
`MutableSet`	`Set`	`__contains__`, `__iter__`, `__len__`, `add`, `discard`	متدهای به‌ارث‌رسیده از `Set` و `clear`، `pop`، `remove`، `__ior__`، `__iand__`، `__ixor__` و `__isub__`
`Mapping`	`Collection`	`__getitem__`, `__iter__`, `__len__`	`__contains__`، `keys`، `items`، `values`، `get`، `__eq__` و `__ne__`
`MutableMapping`	`Mapping`	`__getitem__`, `__setitem__`, `__delitem__`, `__iter__`, `__len__`	متدهای به‌ارث‌رسیده از `Mapping` و `pop`، `popitem`، `clear`، `update` و `setdefault`
`MappingView`	`Sized`		`__init__`، `__len__` و `__repr__`
`ItemsView`	`MappingView`, `Set`		`__contains__`, `__iter__`
`KeysView`	`MappingView`, `Set`		`__contains__`, `__iter__`
`ValuesView`	`MappingView`, `Collection`		`__contains__`, `__iter__`
`Awaitable` [1]		`__await__`
`Coroutine` [1]	`Awaitable`	`asend`, `athrow`	`close`
`AsyncIterable` [1]		`__aiter__`
`AsyncIterator` [1]	`AsyncIterable`	`__anext__`	`__aiter__`
`AsyncGenerator` [1]	`AsyncIterator`	`asend`, `athrow`	`aclose`, `__aiter__`, `__anext__`
`Buffer` [1]		`__buffer__`

پانویس‌ها

کلاس‌های پایه انتزاعی مجموعه‌ها -- توضیحات تفصیلی¶

class collections.abc.Container¶: کلاس پایه انتزاعی (ABC) برای کلاس‌هایی که متد __contains__() را فراهم می‌کنند.

class collections.abc.Hashable¶: کلاس پایه انتزاعی (ABC) برای کلاس‌هایی که متد __hash__() را ارائه می‌دهند.

class collections.abc.Sized¶: کلاس پایه انتزاعی (ABC) برای کلاس‌هایی که متد __len__() را فراهم می‌کنند.

class collections.abc.Callable¶

ABC برای کلاس‌هایی که متد __call__() را فراهم می‌کنند.

برای جزئیات درباره‌ی نحوه‌ی استفاده از Callable در حاشیه‌نویسی‌های نوع، حاشیه‌نویسی اشیاء فراخوانی‌پذیر را ببینید.

class collections.abc.Iterable¶

کلاس پایه انتزاعی (ABC) برای کلاس‌هایی که متد __iter__() را فراهم می‌کنند.

بررسی isinstance(obj, Iterable) کلاس‌هایی را که به‌عنوان Iterable ثبت شده‌اند یا دارای متد __iter__() هستند تشخیص می‌دهد، اما کلاس‌هایی را که پیمایش آن‌ها از طریق متد __getitem__() انجام می‌شود تشخیص نمی‌دهد. تنها راه قابل‌اطمینان برای تشخیص اینکه آیا یک شیء پیمایش‌پذیر است، فراخوانی iter(obj) است.

class collections.abc.Collection¶: کلاس پایه انتزاعی (ABC) برای کلاس‌های ظرف اندازه‌دار و پیمایش‌پذیر.

اضافه شده در نسخه‌ی 3.6.

class collections.abc.Iterator¶: ABC برای کلاس‌هایی که متدهای __iter__() و __next__() را فراهم می‌کنند. همچنین تعریف iterator را ببینید.

class collections.abc.Reversible¶: ABC برای کلاس‌های پیمایش‌پذیری که متد __reversed__() را نیز ارائه می‌دهند.

اضافه شده در نسخه‌ی 3.6.

class collections.abc.Generator¶

کلاس پایه انتزاعی (ABC) برای کلاس‌های تولیدگر که پروتکل تعریف‌شده در PEP 342 را پیاده‌سازی می‌کنند؛ پروتکلی که پیمایش‌گرها را با متدهای send()، throw() و close() گسترش می‌دهد.

برای جزئیات درباره استفاده از Generator در حاشیه‌نویسی‌های نوع، حاشیه‌نویسی تولیدگرها و هم‌روال‌ها را ببینید.

اضافه شده در نسخه‌ی 3.5.

class collections.abc.Sequence¶

class collections.abc.MutableSequence¶

class collections.abc.ByteString¶

کلاس‌های پایه انتزاعی (ABC) برای دنباله‌های فقط‌خواندنی و تغییرپذیر.

یادداشت پیاده‌سازی: برخی از متدهای میکس‌این، مانند __iter__()، __reversed__() و index()، فراخوانی‌های مکرری به متد زیربنایی __getitem__() انجام می‌دهند. در نتیجه، اگر __getitem__() با سرعت دسترسی ثابت پیاده‌سازی شده باشد، متدهای میکس‌این عملکرد خطی خواهند داشت؛ اما اگر متد زیربنایی خطی باشد (همان‌طور که در یک فهرست پیوندی این‌گونه خواهد بود)، میکس‌این‌ها عملکرد درجه دو خواهند داشت و احتمالاً لازم است بازنویسی شوند.

index(value, start=0, stop=None)¶

نخستین اندیس value را برمی‌گرداند.

اگر مقدار موجود نباشد، ValueError پرتاب می‌شود.

پشتیبانی از آرگومان‌های start و stop اختیاری است، اما توصیه می‌شود.

تغییر یافته در نسخه‌ی 3.5: پشتیبانی از آرگومان‌های stop و start به متد index() اضافه شد.

منسوخ شده از نسخه‌ی 3.12, در نسخه‌ی 3.17 حذف خواهد شد: کلاس پایه انتزاعی (ABC) ByteString منسوخ شده است.

برای بررسی اینکه obj پروتکل بافر را در زمان ران‌تایم پیاده‌سازی می‌کند، از isinstance(obj, collections.abc.Buffer) استفاده کنید. برای استفاده در حاشیه‌نویسی‌های نوع، یا از Buffer استفاده کنید یا از یک اجتماع (union) که به‌صراحت انواع مورد پشتیبانی کد شما را مشخص می‌کند (مثلاً bytes | bytearray | memoryview).

ByteString در ابتدا قرار بود یک کلاس انتزاعی باشد که به‌عنوان نوع والد هر دو کلاس bytes و bytearray عمل کند. با این حال، از آنجا که این کلاس پایه انتزاعی هرگز هیچ متدی نداشت، دانستن این‌که یک شیء نمونه‌ای از ByteString است، در عمل هرگز اطلاعات مفیدی درباره‌ی آن شیء به شما نمی‌داد. سایر انواع رایج بافر مانند memoryview نیز هرگز به‌عنوان زیرنوع‌هایی از ByteString در نظر گرفته نمی‌شدند (نه در ران‌تایم و نه توسط بررسی‌کننده‌های نوع ایستا).

برای جزئیات بیشتر PEP 688 را ببینید.

class collections.abc.Set¶
class collections.abc.MutableSet¶: کلاس‌های پایه انتزاعی برای مجموعه‌های فقط‌خواندنی و تغییرپذیر.

class collections.abc.Mapping¶
class collections.abc.MutableMapping¶: کلاس‌های پایه انتزاعی برای نگاشت‌های فقط‌خواندنی و تغییرپذیر.

class collections.abc.MappingView¶
class collections.abc.ItemsView¶
class collections.abc.KeysView¶
class collections.abc.ValuesView¶: کلاس‌های پایه انتزاعی (ABCs) برای نماهای نگاشت، آیتم‌ها، کلیدها و مقدارها.

class collections.abc.Awaitable¶

کلاس پایه انتزاعی (ABC) برای اشیاء awaitable، که می‌توان از آن‌ها در عبارت‌های await استفاده کرد. پیاده‌سازی‌های سفارشی باید متد __await__() را فراهم کنند.

اشیاء هم‌روال و نمونه‌های کلاس پایه انتزاعی (ABC) Coroutine، همگی نمونه‌هایی از این ABC هستند.

نکته

در CPython، هم‌روال‌های مبتنی بر تولیدگر (تولیدگرها که با @types.coroutine دکور شده‌اند) awaitable هستند، اگرچه متد __await__() ندارند. استفاده از isinstance(gencoro, Awaitable) برای آن‌ها False را برمی‌گرداند. برای شناسایی آن‌ها از inspect.isawaitable() استفاده کنید.

اضافه شده در نسخه‌ی 3.5.

class collections.abc.Coroutine¶

ABC برای کلاس‌های سازگار با هم‌روال. این کلاس‌ها متدهای زیر را، که در اشیاء هم‌روال تعریف شده‌اند، پیاده‌سازی می‌کنند: send()، throw() و close(). پیاده‌سازی‌های سفارشی باید __await__() را نیز پیاده‌سازی کنند. تمام نمونه‌های Coroutine نیز نمونه‌هایی از Awaitable هستند.

نکته

در CPython، هم‌روال‌های مبتنی بر تولیدگر (تولیدگرها که با @types.coroutine آراییده شده‌اند) awaitable هستند، اگرچه آن‌ها متد __await__() ندارند. استفاده از isinstance(gencoro, Coroutine) برای آن‌ها False را برمی‌گرداند. برای تشخیص آن‌ها از inspect.isawaitable() استفاده کنید.

برای جزئیات درباره‌ی استفاده از Coroutine در حاشیه‌نویسی‌های نوع، حاشیه‌نویسی تولیدگرها و هم‌روال‌ها را ببینید. واریانس و ترتیب پارامترهای نوع، متناظر با موارد مربوط به Generator است.

اضافه شده در نسخه‌ی 3.5.

class collections.abc.AsyncIterable¶: ABC برای کلاس‌هایی که متد __aiter__ را ارائه می‌دهند. همچنین تعریف پیمایش‌پذیر ناهمگام را ببینید.

اضافه شده در نسخه‌ی 3.5.

class collections.abc.AsyncIterator¶: کلاس پایه انتزاعی (ABC) برای کلاس‌هایی که متدهای __aiter__ و __anext__ را فراهم می‌کنند. همچنین تعریف asynchronous iterator را ببینید.

اضافه شده در نسخه‌ی 3.5.

class collections.abc.AsyncGenerator¶

ABC برای کلاس‌های asynchronous generator که پروتکل تعریف‌شده در PEP 525 و PEP 492 را پیاده‌سازی می‌کنند.

برای جزئیات درباره‌ی استفاده از AsyncGenerator در حاشیه‌نویسی‌های نوع، حاشیه‌نویسی تولیدگرها و هم‌روال‌ها را ببینید.

اضافه شده در نسخه‌ی 3.6.

class collections.abc.Buffer¶: کلاس پایه انتزاعی (ABC) برای کلاس‌هایی که متد __buffer__() را ارائه می‌دهند و پروتکل بافر را پیاده‌سازی می‌کنند. PEP 688 را ببینید.

اضافه شده در نسخه‌ی 3.12.

مثال‌ها و راهکارها¶

کلاس‌های پایه انتزاعی (ABCs) به ما امکان می‌دهند از کلاس‌ها یا نمونه‌ها بپرسیم که آیا قابلیت خاصی را فراهم می‌کنند یا خیر، برای مثال:

size = None
if isinstance(myvar, collections.abc.Sized):
    size = len(myvar)

برخی از کلاس‌های پایه انتزاعی (ABC) نیز به‌عنوان میکس‌این مفید هستند و توسعه کلاس‌هایی را که از APIهای ظرف پشتیبانی می‌کنند، آسان‌تر می‌کنند. برای مثال، برای نوشتن کلاسی که از API کامل Set پشتیبانی می‌کند، تنها لازم است سه متد انتزاعی زیربنایی را فراهم کنید: __contains__()، __iter__() و __len__(). ABC متدهای باقی‌مانده مانند __and__() و isdisjoint() را فراهم می‌کند:

class ListBasedSet(collections.abc.Set):
    ''' Alternate set implementation favoring space over speed
        and not requiring the set elements to be hashable. '''
    def __init__(self, iterable):
        self.elements = lst = []
        for value in iterable:
            if value not in lst:
                lst.append(value)

    def __iter__(self):
        return iter(self.elements)

    def __contains__(self, value):
        return value in self.elements

    def __len__(self):
        return len(self.elements)

s1 = ListBasedSet('abcdef')
s2 = ListBasedSet('defghi')
overlap = s1 & s2            # The __and__() method is supported automatically

نکاتی درباره‌ی استفاده از Set و MutableSet به‌عنوان میکس‌این :

از آنجا که برخی از عملیات مجموعه‌ای، مجموعه‌های جدیدی ایجاد می‌کنند، متدهای پیش‌فرض میکس‌این به راهی برای ایجاد نمونه‌های جدید از یک پیمایش‌پذیر نیاز دارند. فرض می‌شود که سازنده‌ی کلاس، امضایی به شکل ClassName(iterable) داشته باشد. این فرض در قالب یک classmethod داخلی به نام _from_iterable() استخراج شده است که cls(iterable) را فراخوانی می‌کند تا یک مجموعه جدید تولید کند. اگر از میکس‌این Set در کلاسی با امضای سازنده متفاوت استفاده شود، لازم است _from_iterable() را با یک classmethod یا متد معمولی که بتواند نمونه‌های جدید را از یک آرگومان پیمایش‌پذیر بسازد، بازنویسی کنید.
برای بازنویسی مقایسه‌ها (احتمالاً برای سرعت، زیرا معنای آن‌ها ثابت است)، __le__() و __ge__() را بازتعریف کنید؛ سپس سایر عملیات به‌طور خودکار از آن‌ها پیروی خواهند کرد.
میکس‌این Set یک متد _hash() برای محاسبه‌ی مقدار هش مجموعه ارائه می‌کند؛ با این حال، __hash__() تعریف نشده است، زیرا همه‌ی مجموعه‌ها هش‌پذیر یا تغییرناپذیر نیستند. برای افزودن هش‌پذیری مجموعه با استفاده از میکس‌این‌ها، از هر دو Set و Hashable ارث‌بری کنید، سپس __hash__ = Set._hash را تعریف کنید.

همچنین ببینید

دستور پخت OrderedSet برای نمونه‌ای که بر پایه‌ی MutableSet ساخته شده است.
برای اطلاعات بیشتر درباره ABCها، ماژول abc و PEP 3119 را ببینید.

© حق نشر 2001 Python Software Foundation.
این صفحه تحت مجوز بنیاد نرم‌افزار پایتون نسخه ۲ منتشر شده است.
مثال‌ها، دستورالعمل‌ها، و سایر کدهای موجود در مستندات همچنین تحت مجوز بدون بند BSD منتشر شده‌اند.
برای اطلاعات بیشتر به تاریخچه و مجوز مراجعه کنید.

بنیاد نرم‌افزار پایتون یک شرکت غیرانتفاعی است. لطفاً کمک مالی کنید.

آخرین به‌روزرسانی در نوامبر 12, 2026 (06:19 UTC). آیا اشکالی یافتید؟
ساخته شده با Sphinx 9.1.0.

You are visitor 01402520 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.

GeezerVison

collections.abc --- کلاس‌های پایه انتزاعی برای ظروف¶

کلاس‌های پایه انتزاعی مجموعه‌ها¶

کلاس‌های پایه انتزاعی مجموعه‌ها -- توضیحات تفصیلی¶

مثال‌ها و راهکارها¶

`collections.abc` --- کلاس‌های پایه انتزاعی برای ظروف¶