collections.abc — Abstrakta basklasser för behållare

Tillagd i version 3.3: Tidigare var denna modul en del av modulen collections.

Källkod: Lib/_collections_abc.py

Denna modul tillhandahåller abstrakta basklasser som kan användas för att testa om en klass tillhandahåller ett visst gränssnitt, till exempel om den är hashable eller om den är en mapping.

Ett issubclass()- eller isinstance()-test för ett gränssnitt fungerar på ett av tre sätt.

  1. En nyskriven klass kan ärva direkt från en av de abstrakta basklasserna. Klassen måste tillhandahålla de abstrakta metoder som krävs. De återstående mixin-metoderna kommer från arv och kan åsidosättas om så önskas. Andra metoder kan läggas till efter behov:

    klass C(Sekvens):                      # Direkt arv
    def __init__(self): ...             # Extra metod som inte krävs av ABC
    def __getitem__(self, index): ...  # Nödvändig abstrakt metod
    def __len__(self):  ...             # Krävs abstrakt metod
    def count(self, värde): ...         # Eventuellt åsidosätta en mixin-metod

    >>> issubclass(C, Sequence)
True
>>> isinstance(C(), Sequence)
True

  2. Befintliga klasser och inbyggda klasser kan registreras som ”virtuella underklasser” av ABC. Dessa klasser bör definiera hela API:et, inklusive alla abstrakta metoder och alla mixin-metoder. Detta gör att användare kan förlita sig på issubclass() eller isinstance()-tester för att avgöra om det fullständiga gränssnittet stöds. Undantaget från denna regel är för metoder som automatiskt härleds från resten av API:et:

    klass D:                                 # Ingen nedärvning
    def __init__(self): ...              # Extra metod som inte krävs av ABC
    def __getitem__(self, index): ...   # Abstrakt metod
    def __len__(self):  ...              # Abstrakt metod
    def count(self, värde): ...          # Mixin-metod
    def index(self, värde): ...          # Mixin-metod

Sequence.register(D) # Registrera istället för att ärva

    >>> issubclass(D, Sequence)
True
>>> isinstance(D(), Sequence)
True

    I det här exemplet behöver klassen D inte definiera __contains__, __iter__ och __reversed__ eftersom logiken in-operator, logiken iteration och funktionen reversed() automatiskt faller tillbaka till att använda __getitem__ och __len__.

  3. Vissa enkla gränssnitt är direkt igenkännliga genom att de nödvändiga metoderna finns (såvida inte dessa metoder har ställts in på None):

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

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

    Komplexa gränssnitt stöder inte denna sista teknik eftersom ett gränssnitt är mer än bara förekomsten av metodnamn. Gränssnitt specificerar semantik och relationer mellan metoder som inte kan härledas enbart från förekomsten av specifika metodnamn. Att veta att en klass tillhandahåller __getitem__, __len__ och __iter__ är till exempel inte tillräckligt för att skilja en Sequence från en Mapping.

Tillagd i version 3.9: Dessa abstrakta klasser har nu stöd för []. Se Generisk aliastyp och PEP 585.

Samlingar Abstrakta basklasser

Samlingsmodulen erbjuder följande ABCs:

ABC

Ärver från

Abstrakta metoder

Mixin-metoder

Container [1]

__contains__

Hashable [1]

__hash__

Iterable [1] [2]

__iter__

Iterator [1]

Iterable

__next__

__iter__

Reversible [1]

Iterable

__reversed__

Generator [1]

Iterator

”skicka”, ”kasta

close, __iter__, __next__

Sized [1]

__len__

Callable [1]

__call__

Collection [1]

Sized, Iterable, Container

__innehåller__, __iter__, __len__

Sequence

Reversible, Collection

__getitem__, __len__

__contains__, __iter__, __reversed__, index och count

MutableSequence

Sequence

__getitem__, __setitem__, __delitem__, __len__, insert

Ärvda Sequence-metoder och append, clear, reverse, extend, pop, remove och __iadd__

Set

Collection

__innehåller__, __iter__, __len__

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

MutableSet

Set

__contains__, __iter__, __len__, add, discard

Ärvda Set-metoder och clear, pop, remove, __ior__, __iand__, __ixor__ och __isub__

Mapping

Collection

__getitem__, __iter__, __len__

__contains__, keys, items, values, get, __eq__ och ne__

MutableMapping

Mapping

__getitem__, __setitem__, __delitem__, __iter__, __len__

Ärvda Mapping-metoder och pop, popitem, clear, update och setdefault

MappingView

Sized

__init__, __len__ och __repr__

ItemsView

MappingView, Set

__innehåller__, __iter__

KeysView

MappingView, Set

__innehåller__, __iter__

ValuesView

MappingView, Collection

__innehåller__, __iter__

Awaitable [1]

__avvakta__

Coroutine [1]

Awaitable

”skicka”, ”kasta

stänga

AsyncIterable [1]

__aiter__

AsyncIterator [1]

AsyncIterable

__anext__

__aiter__

AsyncGenerator [1]

AsyncIterator

asend, athrow

sluta, __aiter__, __anext__

Buffer [1]

__buffer__

Fotnoter

Collections Abstrakta basklasser – Detaljerade beskrivningar

class collections.abc.Container

ABC för klasser som tillhandahåller metoden __contains__().

class collections.abc.Hashable

ABC för klasser som tillhandahåller metoden __hash__().

class collections.abc.Sized

ABC för klasser som tillhandahåller metoden __len__().

class collections.abc.Callable

ABC för klasser som tillhandahåller metoden __call__().

Se Annotering av anropsbara objekt för detaljer om hur man använder Callable i typannoteringar.

class collections.abc.Iterable

ABC för klasser som tillhandahåller metoden __iter__().

Kontrollen isinstance(obj, Iterable) upptäcker klasser som är registrerade som Iterable eller som har en __iter__()-metod, men den upptäcker inte klasser som itererar med __getitem__()-metoden. Det enda tillförlitliga sättet att avgöra om ett objekt är iterable är att anropa iter(obj).

class collections.abc.Collection

ABC för stora iterabla containerklasser.

Tillagd i version 3.6.

class collections.abc.Iterator

ABC för klasser som tillhandahåller metoderna __iter__() och __next__(). Se även definitionen av iterator.

class collections.abc.Reversible

ABC för iterabla klasser som också tillhandahåller metoden __reversed__().

Tillagd i version 3.6.

class collections.abc.Generator

ABC för generator-klasser som implementerar protokollet definierat i PEP 342 som utökar iterators med metoderna send(), throw() och close().

Se Annotering av generatorer och coroutines för detaljer om hur man använder Generator i typannoteringar.

Tillagd i version 3.5.

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

ABC för skrivskyddade och muterbara sekvenser.

Implementationsanmärkning: Vissa av mixinmetoderna, t.ex. __iter__(), __reversed__() och index(), gör upprepade anrop till den underliggande metoden __getitem__(). Följaktligen, om __getitem__() implementeras med konstant åtkomsthastighet, kommer mixinmetoderna att ha linjär prestanda; men om den underliggande metoden är linjär (som den skulle vara med en länkad lista), kommer mixinerna att ha kvadratisk prestanda och kommer sannolikt att behöva åsidosättas.

Ändrad i version 3.5: I metoden index() har stöd för argumenten stop och start lagts till.

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

ABC för skrivskyddade och muterbara sets.

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

ABC för skrivskyddade och muterbara mappningar.

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

ABC för mappning, objekt, nycklar och värden views.

class collections.abc.Awaitable

ABC för awaitable-objekt, som kan användas i await-uttryck. Anpassade implementationer måste tillhandahålla metoden __await__().

Coroutine objekt och instanser av Coroutine ABC är alla instanser av denna ABC.

Anteckning

I CPython är generatorbaserade coroutines (generators dekorerad med @types.coroutine) awaitables, även om de inte har en __await__()-metod. Att använda isinstance(gencoro, Awaitable) för dem kommer att returnera False. Använd inspect.isawaitable() för att upptäcka dem.

Tillagd i version 3.5.

class collections.abc.Coroutine

ABC för coroutine-kompatibla klasser. Dessa implementerar följande metoder, definierade i Coroutine-objekt: send(), throw(), och close(). Anpassade implementationer måste också implementera __await__(). Alla Coroutine-instanser är också instanser av Awaitable.

Anteckning

I CPython är generatorbaserade coroutines (generators dekorerad med @types.coroutine) awaitables, även om de inte har en __await__()-metod. Att använda isinstance(gencoro, Coroutine) för dem kommer att returnera False. Använd inspect.isawaitable() för att upptäcka dem.

Se Annotering av generatorer och coroutines för detaljer om hur man använder Coroutine i typannoteringar. Variansen och ordningen på typ-parametrarna motsvarar de i Generator.

Tillagd i version 3.5.

class collections.abc.AsyncIterable

ABC för klasser som tillhandahåller en __aiter__-metod. Se även definitionen av asynkron iterabel.

Tillagd i version 3.5.

class collections.abc.AsyncIterator

ABC för klasser som tillhandahåller metoderna __aiter__ och __anext__. Se även definitionen av asynkron iterator.

Tillagd i version 3.5.

class collections.abc.AsyncGenerator

ABC för asynkron generator-klasser som implementerar protokollet definierat i PEP 525 och PEP 492.

Se Annotering av generatorer och coroutines för detaljer om hur man använder AsyncGenerator i typannoteringar.

Tillagd i version 3.6.

class collections.abc.Buffer

ABC för klasser som tillhandahåller metoden __buffer__() och som implementerar buffer protocol. Se PEP 688.

Tillagd i version 3.12.

Exempel och recept

ABC gör det möjligt för oss att fråga klasser eller instanser om de tillhandahåller viss funktionalitet, till exempel:

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

Flera av ABC:erna är också användbara som mixins som gör det enklare att utveckla klasser som stöder container-API:er. Om du till exempel vill skriva en klass som stöder hela Set API behöver du bara tillhandahålla de tre underliggande abstrakta metoderna: __contains__(), __iter__() och __len__(). ABC tillhandahåller de återstående metoderna som __and__() och 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

Anteckningar om hur man använder Set och MutableSet som mixin:

  1. Eftersom vissa set-operationer skapar nya set, behöver standardmixinmetoderna ett sätt att skapa nya instanser från en iterable. Klasskonstruktören antas ha en signatur i formen ClassName(iterable). Detta antagande faktureras ut till en intern classmethod som kallas _from_iterable() som anropar cls(iterable) för att producera en ny uppsättning. Om mixinen Set används i en klass med en annan konstruktörsignatur, måste du åsidosätta _from_iterable() med en klassmetod eller vanlig metod som kan konstruera nya instanser från ett iterabelt argument.

  2. För att åsidosätta jämförelserna (förmodligen för snabbhetens skull, eftersom semantiken är fast), omdefiniera __le__() och __ge__(), så kommer de andra operationerna automatiskt att följa efter.

  3. Mixinen Set tillhandahåller en metod _hash() för att beräkna ett hashvärde för uppsättningen, men __hash__() definieras inte eftersom inte alla uppsättningar är hashable eller oföränderliga. För att lägga till hashbarhet för set med hjälp av mixins, ärva från både Set() och Hashable() och definiera sedan __hash__ = Set._hash.

Se även