collections.abc --- Các lớp cơ sở trừu tượng cho vùng chứa

Added in version 3.3: Trước đây, mô-đun này là một phần của mô-đun collections.

Source code: Lib/_collections_abc.py

Mô-đun này cung cấp abstract base classes có thể được sử dụng để kiểm tra xem một lớp có cung cấp giao diện cụ thể hay không; ví dụ: đó là hashable hay mapping.

Kiểm tra issubclass() hoặc isinstance() cho một giao diện hoạt động theo một trong ba cách.

  1. Một lớp mới được viết có thể kế thừa trực tiếp từ một trong các lớp cơ sở trừu tượng. Lớp phải cung cấp các phương thức trừu tượng cần thiết. Các phương thức mixin còn lại đến từ sự kế thừa và có thể được ghi đè nếu muốn. Các phương pháp khác có thể được thêm vào khi cần thiết:

    lớp C (Trình tự): kế thừa # Direct
    def __init__(self): ... phương thức # Extra không được ABC yêu cầu
    def __getitem__(self, index): ... phương thức trừu tượng # Required
    def __len__(self): ... phương thức trừu tượng # Required
    def count(self, value): ... # Optionally ghi đè phương thức mixin

    >>> issubclass(C, Sequence)
đúng
>>> isinstance(C(), Trình tự)
đúng

  2. Các lớp hiện có và các lớp tích hợp có thể được đăng ký làm "lớp con ảo" của ABC. Các lớp đó phải xác định API đầy đủ bao gồm tất cả các phương thức trừu tượng và tất cả các phương thức mixin. Điều này cho phép người dùng dựa vào các bài kiểm tra issubclass() hoặc isinstance() để xác định xem giao diện đầy đủ có được hỗ trợ hay không. Ngoại lệ đối với quy tắc này là dành cho các phương thức được suy ra tự động từ phần còn lại của API:

    lớp D: kế thừa # No
    def __init__(self): ... phương thức # Extra không được ABC yêu cầu
    def __getitem__(self, index): ... phương thức # Abstract
    def __len__(self): ... phương thức # Abstract
    số def (tự, giá trị): ... phương thức # Mixin
    chỉ số def (tự, giá trị): ... phương thức # Mixin

Sequence.register(D) # Register thay vì kế thừa

    >>> issubclass(D, Sequence)
đúng
>>> isinstance(D(), Trình tự)
đúng

    Trong ví dụ này, lớp D không cần xác định __contains__, __iter__ và __reversed__ vì in-operator, logic iteration và hàm reversed() tự động quay lại sử dụng __getitem__ và __len__.

  3. Một số giao diện đơn giản có thể được nhận dạng trực tiếp nhờ sự hiện diện của các phương thức được yêu cầu (trừ khi các phương thức đó được đặt thành None):

    lớp E:
    chắc chắn __iter__(tự): ...
    chắc chắn __next__(tự): ...

    >>> issubclass(E, Iterable)
đúng
>>> isinstance(E(), Iterable)
đúng

    Các giao diện phức tạp không hỗ trợ kỹ thuật cuối cùng này vì giao diện không chỉ có sự hiện diện của tên phương thức. Các giao diện chỉ định ngữ nghĩa và mối quan hệ giữa các phương thức không thể được suy ra chỉ từ sự hiện diện của tên phương thức cụ thể. Ví dụ: biết rằng một lớp cung cấp __getitem__, __len__ và __iter__ là không đủ để phân biệt Sequence với Mapping.

Added in version 3.9: Các lớp trừu tượng này hiện hỗ trợ []. Xem Loại bí danh chung và PEP 585.

Bộ sưu tập Các lớp cơ sở trừu tượng

Mô-đun bộ sưu tập cung cấp ABCs sau:

ABC

Kế thừa từ

Phương pháp trừu tượng

Phương pháp Mixin

Container [1]

__contains__

Hashable [1]

__hash__

Iterable [1] [2]

__iter__

Iterator [1]

Iterable

__next__

__iter__

Reversible [1]

Iterable

__reversed__

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 và count

MutableSequence

Sequence

__getitem__, __setitem__, __delitem__, __len__, insert

Kế thừa các phương thức Sequence và append, clear, reverse, extend, pop, remove và __iadd__

ByteString

Sequence

__getitem__, __len__

Các phương thức Sequence được kế thừa

Set

Collection

__contains__, __iter__, __len__

__le__, __lt__, __eq__, __ne__, __gt__, __ge__, __and__, __or__, __sub__, __rsub__, __xor__, __rxor__ và isdisjoint

MutableSet

Set

__contains__, __iter__, __len__, add, discard

Kế thừa các phương thức Set và clear, pop, remove, __ior__, __iand__, __ixor__ và __isub__

Mapping

Collection

__getitem__, __iter__, __len__

__contains__, keys, items, values, get, __eq__, và __ne__

MutableMapping

Mapping

__getitem__, __setitem__, __delitem__, __iter__, __len__

Kế thừa các phương thức Mapping và pop, popitem, clear, update và setdefault

MappingView

Sized

__init__, __len__ và __repr__

ItemsView

MappingView, Set

__contains__, __iter__

KeysView

MappingView, Set

__contains__, __iter__

ValuesView

MappingView, Collection

__contains__, __iter__

Awaitable [1]

__await__

Coroutine [1]

Awaitable

send, throw

close

AsyncIterable [1]

__aiter__

AsyncIterator [1]

AsyncIterable

__anext__

__aiter__

AsyncGenerator [1]

AsyncIterator

asend, athrow

aclose, __aiter__, __anext__

Buffer [1]

__buffer__

Chú thích cuối trang

Bộ sưu tập Các lớp cơ sở trừu tượng -- Mô tả chi tiết

class collections.abc.Container

ABC cho các lớp cung cấp phương thức __contains__().

class collections.abc.Hashable

ABC cho các lớp cung cấp phương thức __hash__().

class collections.abc.Sized

ABC cho các lớp cung cấp phương thức __len__().

class collections.abc.Callable

ABC cho các lớp cung cấp phương thức __call__().

Xem Chú thích các đối tượng có thể gọi được để biết chi tiết về cách sử dụng Callable trong chú thích kiểu.

class collections.abc.Iterable

ABC cho các lớp cung cấp phương thức __iter__().

Việc kiểm tra isinstance(obj, Iterable) sẽ phát hiện các lớp được đăng ký là Iterable hoặc có phương thức __iter__(), nhưng nó không phát hiện các lớp lặp lại bằng phương thức __getitem__(). Cách đáng tin cậy duy nhất để xác định xem một đối tượng có phải là iterable hay không là gọi iter(obj).

class collections.abc.Collection

ABC dành cho các lớp vùng chứa có thể lặp lại có kích thước.

Added in version 3.6.

class collections.abc.Iterator

ABC cho các lớp cung cấp phương thức __iter__() và __next__(). Xem thêm định nghĩa của iterator.

class collections.abc.Reversible

ABC cho các lớp lặp cũng cung cấp phương thức __reversed__().

Added in version 3.6.

class collections.abc.Generator

ABC dành cho các lớp generator triển khai giao thức được xác định trong PEP 342 mở rộng iterators bằng các phương thức send(), throw() và close().

Xem Trình tạo chú thích và coroutine để biết chi tiết về cách sử dụng Generator trong chú thích loại.

Added in version 3.5.

class collections.abc.Sequence
class collections.abc.MutableSequence
class collections.abc.ByteString

ABC dành cho sequences chỉ đọc và có thể thay đổi.

Lưu ý triển khai: Một số phương thức mixin, chẳng hạn như __iter__(), __reversed__() và index() thực hiện các lệnh gọi lặp lại đến phương thức __getitem__() cơ bản. Do đó, nếu __getitem__() được triển khai với tốc độ truy cập không đổi, các phương thức mixin sẽ có hiệu suất tuyến tính; tuy nhiên, nếu phương thức cơ bản là tuyến tính (như với danh sách liên kết), các mixin sẽ có hiệu suất bậc hai và có thể sẽ cần được ghi đè.

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

Trả về chỉ mục đầu tiên của value.

Tăng ValueError nếu không có giá trị.

Việc hỗ trợ các đối số start và stop là tùy chọn nhưng được khuyến nghị.

Thay đổi trong phiên bản 3.5: Phương thức index() đã nhận được sự hỗ trợ cho các đối số stop và start.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.17: ByteString ABC không còn được dùng nữa.

Sử dụng isinstance(obj, collections.abc.Buffer) để kiểm tra xem obj có triển khai buffer protocol khi chạy hay không. Để sử dụng trong chú thích loại, hãy sử dụng Buffer hoặc liên kết chỉ định rõ ràng các loại mà mã của bạn hỗ trợ (ví dụ: bytes | bytearray | memoryview).

ByteString ban đầu được dự định là một lớp trừu tượng sẽ đóng vai trò là siêu kiểu của cả bytes và bytearray. Tuy nhiên, vì ABC chưa bao giờ có bất kỳ phương thức nào nên việc biết rằng một đối tượng là một thể hiện của ByteString chưa bao giờ thực sự cho bạn biết bất kỳ điều gì hữu ích về đối tượng đó. Các loại bộ đệm phổ biến khác như memoryview cũng không bao giờ được hiểu là kiểu con của ByteString (trong thời gian chạy hoặc bằng trình kiểm tra kiểu tĩnh).

Xem PEP 688 để biết thêm chi tiết.

class collections.abc.Set
class collections.abc.MutableSet

ABC dành cho sets chỉ đọc và có thể thay đổi.

class collections.abc.Mapping
class collections.abc.MutableMapping

ABC dành cho mappings chỉ đọc và có thể thay đổi.

class collections.abc.MappingView
class collections.abc.ItemsView
class collections.abc.KeysView
class collections.abc.ValuesView

ABC để ánh xạ, mục, khóa và giá trị views.

class collections.abc.Awaitable

ABC cho các đối tượng awaitable, có thể được sử dụng trong biểu thức await. Việc triển khai tùy chỉnh phải cung cấp phương thức __await__().

Các đối tượng Coroutine và các phiên bản của Coroutine ABC đều là các phiên bản của ABC này.

Ghi chú

Trong CPython, các coroutine dựa trên trình tạo (generators được trang trí bằng @types.coroutine) là awaitables, mặc dù chúng không có phương thức __await__(). Sử dụng isinstance(gencoro, Awaitable) cho chúng sẽ trả về False. Sử dụng inspect.isawaitable() để phát hiện chúng.

Added in version 3.5.

class collections.abc.Coroutine

ABC cho các lớp tương thích với coroutine. Chúng triển khai các phương thức sau, được xác định trong Đối tượng Coroutine: send(), throw() và close(). Việc triển khai tùy chỉnh cũng phải triển khai __await__(). Tất cả các phiên bản Coroutine cũng là phiên bản của Awaitable.

Ghi chú

Trong CPython, các coroutine dựa trên trình tạo (generators được trang trí bằng @types.coroutine) là awaitables, mặc dù chúng không có phương thức __await__(). Sử dụng isinstance(gencoro, Coroutine) cho chúng sẽ trả về False. Sử dụng inspect.isawaitable() để phát hiện chúng.

Xem Trình tạo chú thích và coroutine để biết chi tiết về cách sử dụng Coroutine trong chú thích loại. Phương sai và thứ tự của các tham số loại tương ứng với Generator.

Added in version 3.5.

class collections.abc.AsyncIterable

ABC cho các lớp cung cấp phương thức __aiter__. Xem thêm định nghĩa của asynchronous iterable.

Added in version 3.5.

class collections.abc.AsyncIterator

ABC cho các lớp cung cấp phương thức __aiter__ và __anext__. Xem thêm định nghĩa của asynchronous iterator.

Added in version 3.5.

class collections.abc.AsyncGenerator

ABC dành cho các lớp asynchronous generator triển khai giao thức được xác định trong PEP 525 và PEP 492.

Xem Trình tạo chú thích và coroutine để biết chi tiết về cách sử dụng AsyncGenerator trong chú thích loại.

Added in version 3.6.

class collections.abc.Buffer

ABC cho các lớp cung cấp phương thức __buffer__(), triển khai buffer protocol. Xem PEP 688.

Added in version 3.12.

Ví dụ và Bí quyết

ABC cho phép chúng ta hỏi các lớp hoặc phiên bản xem chúng có cung cấp chức năng cụ thể hay không, ví dụ:

kích thước = Không có
nếu isinstance(myvar, Collection.abc.Sized):
    kích thước = len(myvar)

Một số ABC cũng hữu ích như các mixin giúp phát triển các lớp hỗ trợ API vùng chứa dễ dàng hơn. Ví dụ: để viết một lớp hỗ trợ Set API đầy đủ, chỉ cần cung cấp ba phương thức trừu tượng cơ bản: __contains__(), __iter__() và __len__(). ABC cung cấp các phương thức còn lại như __and__() và isdisjoint():

lớp ListBasedSet(collections.abc.Set):
    ''' Triển khai tập thay thế ưu tiên không gian hơn tốc độ
        và không yêu cầu các phần tử đã đặt phải có thể băm được. '''
    def __init__(tự, có thể lặp lại):
        self.elements = lst = []
        cho giá trị trong iterable:
            nếu giá trị không có trong lst:
                lst.append(giá trị)

    chắc chắn __iter__(tự):
        trả về iter(self.elements)

    def __contains__(bản thân, giá trị):
        giá trị trả về trong self.elements

    chắc chắn __len__(tự):
        trả về len(self.elements)

s1 = ListBasedSet('abcdef')
s2 = ListBasedSet('defghi')
chồng chéo = phương thức s1 & s2 # The __and__() được hỗ trợ tự động

Lưu ý khi sử dụng Set và MutableSet làm mixin:

  1. Vì một số thao tác tập hợp tạo tập hợp mới nên các phương thức mixin mặc định cần một cách để tạo các phiên bản mới từ iterable. Hàm tạo của lớp được giả sử có chữ ký ở dạng ClassName(iterable). Giả định đó được đưa vào một classmethod nội bộ có tên là _from_iterable() gọi cls(iterable) để tạo ra một bộ mới. Nếu mixin Set đang được sử dụng trong một lớp có chữ ký hàm tạo khác, bạn sẽ cần ghi đè _from_iterable() bằng một phương thức lớp hoặc phương thức thông thường có thể tạo các phiên bản mới từ một đối số có thể lặp lại.

  2. Để ghi đè các so sánh (có lẽ là về tốc độ, vì ngữ nghĩa đã được cố định), hãy xác định lại __le__() và __ge__(), sau đó các thao tác khác sẽ tự động thực hiện tương tự.

  3. Mixin Set cung cấp phương thức _hash() để tính giá trị băm cho tập hợp; tuy nhiên, __hash__() không được xác định vì không phải tất cả các bộ đều là hashable hoặc bất biến. Để thêm khả năng băm tập hợp bằng mixin, hãy kế thừa từ cả Set() và Hashable(), sau đó xác định __hash__ = Set._hash.

Xem thêm