collections.abc — Abstrakte Basisklassen für Container

Hinzugefügt in Version 3.3: Früher war dieses Modul Teil des Moduls collections.

Quellcode: Lib/_collections_abc.py

Dieses Modul stellt abstrakte Basisklassen bereit, die verwendet werden können, um zu testen, ob eine Klasse eine bestimmte Schnittstelle bietet; zum Beispiel, ob sie hashbar ist oder ob sie eine Zuordnung ist.

Ein Test mit issubclass() oder isinstance() für eine Schnittstelle funktioniert auf eine von drei Arten.

  1. Eine neu geschriebene Klasse kann direkt von einer der abstrakten Basisklassen erben. Die Klasse muss die erforderlichen abstrakten Methoden bereitstellen. Die verbleibenden Mixin-Methoden stammen aus der Vererbung und können bei Bedarf überschrieben werden. Andere Methoden können nach Bedarf hinzugefügt werden.

    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

  2. Bestehende Klassen und eingebaute Klassen können als „virtuelle Unterklassen“ der ABCs registriert werden. Diese Klassen sollten die vollständige API definieren, einschließlich aller abstrakten Methoden und aller Mixin-Methoden. Dies ermöglicht es Benutzern, issubclass()- oder isinstance()-Tests zu verwenden, um zu bestimmen, ob die vollständige Schnittstelle unterstützt wird. Die Ausnahme von dieser Regel sind Methoden, die automatisch aus dem Rest der API abgeleitet werden.

    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

    In diesem Beispiel muss die Klasse D nicht __contains__, __iter__ und __reversed__ definieren, da der in-Operator, die Iteration-Logik und die Funktion reversed() automatisch auf die Verwendung von __getitem__ und __len__ zurückfallen.

  3. Einige einfache Schnittstellen sind direkt durch das Vorhandensein der erforderlichen Methoden erkennbar (es sei denn, diese Methoden wurden auf None gesetzt)

    class E:
    def __iter__(self): ...
    def __next__(self): ...

    >>> issubclass(E, Iterable)
True
>>> isinstance(E(), Iterable)
True

    Komplexe Schnittstellen unterstützen diese letzte Technik nicht, da eine Schnittstelle mehr ist als nur das Vorhandensein von Methodennamen. Schnittstellen legen Semantik und Beziehungen zwischen Methoden fest, die nicht allein aus dem Vorhandensein spezifischer Methodennamen abgeleitet werden können. Beispielsweise reicht es nicht aus zu wissen, dass eine Klasse __getitem__, __len__ und __iter__ bereitstellt, um eine Sequence von einer Mapping zu unterscheiden.

Hinzugefügt in Version 3.9: Diese abstrakten Klassen unterstützen nun []. Siehe Generic Alias Type und PEP 585.

Abstrakte Basisklassen für Sammlungen

Das Modul `collections` bietet die folgenden ABCs.

ABC

Erbt von

Abstrakte Methoden

Mixin-Methoden

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 und count

MutableSequence

Sequence

__getitem__, __setitem__, __delitem__, __len__, insert

Geerbte Sequence-Methoden und append, clear, reverse, extend, pop, remove und __iadd__

ByteString

Sequence

__getitem__, __len__

Geerbte Sequence-Methoden

Set

Collection

__contains__, __iter__, __len__

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

MutableSet

Set

__contains__, __iter__, __len__, add, discard

Geerbte Set-Methoden und clear, pop, remove, __ior__, __iand__, __ixor__ und __isub__

Mapping

Collection

__getitem__, __iter__, __len__

__contains__, keys, items, values, get, __eq__ und __ne__

MutableMapping

Mapping

__getitem__, __setitem__, __delitem__, __iter__, __len__

Geerbte Mapping-Methoden und pop, popitem, clear, update und setdefault

MappingView

Sized

__init__, __len__ und __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__

Fußnoten

Abstrakte Basisklassen für Sammlungen – Detaillierte Beschreibungen

class collections.abc.Container

ABC für Klassen, die die Methode __contains__() bereitstellen.

class collections.abc.Hashable

ABC für Klassen, die die Methode __hash__() bereitstellen.

class collections.abc.Sized

ABC für Klassen, die die Methode __len__() bereitstellen.

class collections.abc.Callable

ABC für Klassen, die die Methode __call__() bereitstellen.

Siehe Beschriftung aufrufbare Objekte für Details zur Verwendung von Callable in Typannotationen.

class collections.abc.Iterable

ABC für Klassen, die die Methode __iter__() bereitstellen.

Die Überprüfung isinstance(obj, Iterable) erkennt Klassen, die als Iterable registriert sind oder eine Methode __iter__() haben, aber sie erkennt keine Klassen, die mit der Methode __getitem__() iterieren. Der einzig zuverlässige Weg festzustellen, ob ein Objekt iterierbar ist, besteht darin, iter(obj) aufzurufen.

class collections.abc.Collection

ABC für bemaßt-iterable Container-Klassen.

Hinzugefügt in Version 3.6.

class collections.abc.Iterator

ABC für Klassen, die die Methoden __iter__() und __next__() bereitstellen. Siehe auch die Definition von Iterator.

class collections.abc.Reversible

ABC für iterierbare Klassen, die auch die Methode __reversed__() bereitstellen.

Hinzugefügt in Version 3.6.

class collections.abc.Generator

ABC für Generator-Klassen, die das Protokoll implementieren, das in PEP 342 definiert ist und Iteratoren um die Methoden send(), throw() und close() erweitert.

Siehe Beschriftung von Generatoren und Koroutinen für Details zur Verwendung von Generator in Typannotationen.

Hinzugefügt in Version 3.5.

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

ABCs für schreibgeschützte und veränderbare Sequenzen.

Implementierungshinweis: Einige der Mixin-Methoden, wie __iter__(), __reversed__() und index(), rufen die zugrunde liegende Methode __getitem__() wiederholt auf. Folglich, wenn __getitem__() mit konstanter Zugriffsgeschwindigkeit implementiert ist, werden die Mixin-Methoden eine lineare Leistung aufweisen; wenn jedoch die zugrunde liegende Methode linear ist (wie bei einer verketteten Liste), werden die Mixins eine quadratische Leistung aufweisen und müssen wahrscheinlich überschrieben werden.

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

Gibt den ersten Index von value zurück.

Löst ValueError aus, wenn der Wert nicht gefunden wird.

Die Unterstützung der Argumente start und stop ist optional, wird aber empfohlen.

Geändert in Version 3.5: Die Methode index() unterstützt nun die Argumente stop und start.

Veraltet seit Version 3.12, wird in Version 3.17 entfernt: Die ABC ByteString wurde als veraltet markiert.

Verwenden Sie isinstance(obj, collections.abc.Buffer), um zur Laufzeit zu testen, ob obj das Buffer-Protokoll implementiert. Für die Verwendung in Typannotationen verwenden Sie entweder Buffer oder eine Union, die die von Ihrem Code unterstützten Typen explizit angibt (z.B. bytes | bytearray | memoryview).

ByteString war ursprünglich als abstrakte Klasse gedacht, die als Obertyp sowohl für bytes als auch für bytearray dienen sollte. Da die ABC jedoch nie Methoden hatte, wusste man bei der Prüfung, ob ein Objekt eine Instanz von ByteString war, nie wirklich etwas Nützliches über das Objekt. Andere gängige Puffertypen wie memoryview wurden ebenfalls nie als Untertypen von ByteString verstanden (weder zur Laufzeit noch von statischen Typ-Checkern).

Weitere Details finden Sie in PEP 688.

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

ABCs für schreibgeschützte und veränderliche Sets.

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

ABCs für schreibgeschützte und veränderliche Mappings.

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

ABCs für Mapping-, Items-, Keys- und Values-Views.

class collections.abc.Awaitable

ABC für awaitable Objekte, die in await-Ausdrücken verwendet werden können. Benutzerdefinierte Implementierungen müssen die __await__()-Methode bereitstellen.

Coroutine-Objekte und Instanzen der Coroutine ABC sind alle Instanzen dieser ABC.

Hinweis

In CPython sind generatorbasierte Coroutinen (Generatoren, die mit @types.coroutine dekoriert sind) *awaitables*, auch wenn sie keine __await__()-Methode haben. Die Verwendung von isinstance(gencoro, Awaitable) für sie gibt False zurück. Verwenden Sie inspect.isawaitable(), um sie zu erkennen.

Hinzugefügt in Version 3.5.

class collections.abc.Coroutine

ABC für Coroutine-kompatible Klassen. Diese implementieren die folgenden Methoden, die in Coroutine Objects definiert sind: send(), throw() und close(). Benutzerdefinierte Implementierungen müssen auch __await__() implementieren. Alle Coroutine-Instanzen sind auch Instanzen von Awaitable.

Hinweis

In CPython sind generatorbasierte Coroutinen (Generatoren, die mit @types.coroutine dekoriert sind) *awaitables*, auch wenn sie keine __await__()-Methode haben. Die Verwendung von isinstance(gencoro, Coroutine) für sie gibt False zurück. Verwenden Sie inspect.isawaitable(), um sie zu erkennen.

Weitere Details zur Verwendung von Coroutine in Typ-Annotationen finden Sie unter Annotationen für Generatoren und Coroutinen. Die Varianz und Reihenfolge der Typ-Parameter entspricht denen von Generator.

Hinzugefügt in Version 3.5.

class collections.abc.AsyncIterable

ABC für Klassen, die eine __aiter__-Methode bereitstellen. Siehe auch die Definition von asynchrones Iterable.

Hinzugefügt in Version 3.5.

class collections.abc.AsyncIterator

ABC für Klassen, die __aiter__ und __anext__ Methoden bereitstellen. Siehe auch die Definition von asynchroner Iterator.

Hinzugefügt in Version 3.5.

class collections.abc.AsyncGenerator

ABC für Klassen von asynchronen Generatoren, die das in PEP 525 und PEP 492 definierte Protokoll implementieren.

Weitere Details zur Verwendung von AsyncGenerator in Typ-Annotationen finden Sie unter Annotationen für Generatoren und Coroutinen.

Hinzugefügt in Version 3.6.

class collections.abc.Buffer

ABC für Klassen, die die __buffer__()-Methode bereitstellen und das Pufferprotokoll implementieren. Siehe PEP 688.

Hinzugefügt in Version 3.12.

Beispiele und Rezepte

ABCs ermöglichen es uns zu fragen, ob Klassen oder Instanzen bestimmte Funktionalitäten bereitstellen, zum Beispiel

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

Einige der ABCs sind auch als Mixins nützlich, die es einfacher machen, Klassen zu entwickeln, die Container-APIs unterstützen. Um beispielsweise eine Klasse zu schreiben, die die vollständige Set-API unterstützt, müssen nur die drei zugrunde liegenden abstrakten Methoden bereitgestellt werden: __contains__(), __iter__() und __len__(). Die ABC liefert die verbleibenden Methoden wie __and__() und 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

Hinweise zur Verwendung von Set und MutableSet als Mixin

  1. Da einige Set-Operationen neue Sets erzeugen, benötigen die Standard-Mixin-Methoden eine Möglichkeit, neue Instanzen aus einem Iterable zu erstellen. Der Konstruktor der Klasse wird angenommen, eine Signatur in der Form KlassenName(iterable) zu haben. Diese Annahme wird in eine interne classmethod namens _from_iterable() ausgelagert, die cls(iterable) aufruft, um ein neues Set zu erzeugen. Wenn das Set-Mixin in einer Klasse mit einer anderen Konstruktorsignatur verwendet wird, müssen Sie _from_iterable() durch eine Klassen- oder reguläre Methode überschreiben, die neue Instanzen aus einem Iterable-Argument erstellen kann.

  2. Um die Vergleiche zu überschreiben (vermutlich aus Geschwindigkeitsgründen, da die Semantik fest ist), definieren Sie __le__() und __ge__() neu, dann folgen automatisch die anderen Operationen.

  3. Das Set-Mixin bietet eine _hash()-Methode zur Berechnung eines Hash-Werts für das Set; __hash__() ist jedoch nicht definiert, da nicht alle Sets hashable oder unveränderlich sind. Um die Hashbarkeit von Sets mit Mixins hinzuzufügen, erben Sie sowohl von Set() als auch von Hashable() und definieren Sie dann __hash__ = Set._hash.

Siehe auch