collections.abc — Abstract Base Classes for Containers

Νέο στην έκδοση 3.3: Παλαιότερα, αυτό το module ήταν μέρος του collections module.

Πηγαίος κώδικας: Lib/_collections_abc.py

---

Αυτό το module παρέχει αφηρημένες βασικές κλάσεις που μπορούν να χρησιμοποιηθούν για να ελεγχθεί εάν μια κλάση παρέχει μια συγκεκριμένη διεπαφή· για παράδειγμα, εάν είναι hashable ή εάν είναι mapping.

Ένας έλεγχος issubclass() ή isinstance() για μια διεπαφή λειτουργεί με έναν από τρεις τρόπους.

1) A newly written class can inherit directly from one of the abstract base classes. The class must supply the required abstract methods. The remaining mixin methods come from inheritance and can be overridden if desired. Other methods may be added as needed:

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) Existing classes and built-in classes can be registered as «virtual subclasses» of the ABCs. Those classes should define the full API including all of the abstract methods and all of the mixin methods. This lets users rely on issubclass() or isinstance() tests to determine whether the full interface is supported. The exception to this rule is for methods that are automatically inferred from the rest of the 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-operator, η λογική iteration, και η συνάρτηση reversed() χρησιμοποιούν αυτόματα τις μεθόδους __getitem__ και __len__.

3) Some simple interfaces are directly recognizable by the presence of the required methods (unless those methods have been set to None):

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

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

Οι σύνθετες διεπαφές δεν υποστηρίζουν αυτή την τελευταία τεχνική επειδή μια διεπαφή είναι κάτι περισσότερο από την παρουσία ονομάτων μεθόδων. Οι διεπαφές καθορίζουν τη σημασιολογία και τις σχέσεις μεταξύ των μεθόδων που δεν μπορούν να συναχθούν αποκλειστικά από την παρουσία συγκεκριμένων ονομάτων μεθόδων. Για παράδειγμα, η γνώση ότι μια κλάση παρέχει τις μεθόδους __getitem__, __len__ και __iter__ δεν είναι επαρκής για να διακρίνει μια κλάση Sequence από μια κλάση Mapping.

Νέο στην έκδοση 3.9: Αυτές οι αφηρημένες κλάσεις υποστηρίζουν πλέον []. Δείτε Τύπος Generic Alias και PEP 585.

Αφηρημένες Βασικές Κλάσεις Συλλογών

Το collections module προσφέρει τις εξής ABCs:

ABC	Κληρονομεί από	Αφηρημένες Μέθοδοι	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, and count
MutableSequence	Sequence	__getitem__, __setitem__, __delitem__, __len__, insert	Κληρονομημένες Sequence μέθοδοι και append, clear, reverse, extend, pop, remove, and __iadd__
ByteString	Sequence	__getitem__, __len__	Κληρονομημένες Sequence μέθοδοι
Set	Collection	__contains__, __iter__, __len__	__le__, __lt__, __eq__, __ne__, __gt__, __ge__, __and__, __or__, __sub__, __xor__, and 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		__len__
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__

Υποσημειώσεις

[1] (1,2,3,4,5,6,7,8,9,10,11,12,13,14)

Αυτές οι ABCs παρακάμπτουν την μέθοδο __subclasshook__() για να υποστηρίξουν τον έλεγχο μιας διεπαφής μέσω της επαλήθευσης της παρουσίας των απαιτούμενων μεθόδων και του ότι δεν έχουν ρυθμιστεί σε None. Αυτό λειτουργεί μόνο για απλές διεπαφές. Πιο σύνθετες διεπαφές απαιτούν εγγραφή ή άμεση υποκλάση.

[2]

Ο έλεγχος isinstance(obj, Iterable) εντοπίζει κλάσεις που είναι καταχωρημένες ως Iterable ή που έχουν την μέθοδο __iter__(), αλλά δεν εντοπίζει τις κλάσεις που πραγματοποιούν επανάληψη με τη μέθοδο __getitem__(). Ο μόνος αξιόπιστος τρόπος για να προσδιοριστεί αν ένα αντικείμενο είναι iterable είναι να καλέσετε iter(obj).

Αφηρημένες Βασικές Κλάσεις Συλλογών – Αναλυτικές Περιγραφές

class collections.abc.Container

ABC για κλάσεις που παρέχουν την μέθοδο __contains__().

class collections.abc.Hashable

ABC για κλάσεις που παρέχουν την μέθοδο __hash__().

class collections.abc.Sized

ABC για κλάσεις που παρέχουν την μέθοδο __len__().

class collections.abc.Callable

ABC για κλάσεις που παρέχουν την μέθοδο __call__().

class collections.abc.Iterable

ABC για κλάσεις που παρέχουν την μέθοδο __iter__().

Ο έλεγχος isinstance(obj, Iterable) εντοπίζει κλάσεις που είναι καταχωρημένες ως Iterable ή που διαθέτουν τη μέθοδο __iter__(), αλλά δεν εντοπίζει κλάσεις που πραγματοποιούν επανάληψη με τη μέθοδο __getitem__(). Ο μόνος αξιόπιστος τρόπος για να προσδιοριστεί αν ένα αντικείμενο είναι iterable είναι να κληθεί iter(obj).

class collections.abc.Collection

ABC για τις κλάσεις επαναλαμβανόμενων container με μέγεθος.

Νέο στην έκδοση 3.6.

class collections.abc.Iterator

ABC για κλάσεις που παρέχουν τις μεθόδους __iter__() και __next__(). Δείτε επίσης τον ορισμό του iterator.

class collections.abc.Reversible

ABC για τις επαναλαμβανόμενες κλάσεις που παρέχουν επίσης τη μέθοδο __reversed__().

Νέο στην έκδοση 3.6.

class collections.abc.Generator

ABC για τις κλάσεις generator που υλοποιούν το πρωτόκολλο που ορίζεται στο PEP 342 το οποίο επεκτείνει τους iterators με τις μεθόδους send(), throw() και close().

Νέο στην έκδοση 3.5.

class collections.abc.Sequence

class collections.abc.MutableSequence

class collections.abc.ByteString

ABCs μόνο για ανάγνωση (read-only) και mutable sequences.

Σημείωση υλοποίησης: Μερικές από τις μεθόδους mixin, όπως __iter__(), __reversed__() και index(), κάνουν επανειλημμένες κλήσεις στην μέθοδο __getitem__(). Ως αποτέλεσμα, αν η __getitem__() είναι υλοποιημένη με σταθερή ταχύτητα πρόσβασης, οι μέθοδοι mixin θα έχουν γραμμική απόδοση. Ωστόσο, αν η υποκείμενη μέθοδος είναι γραμμική (όπως θα ήταν με μια συνδεδεμένη λίστα), οι mixins θα έχουν τετραγωνική απόδοση και πιθανώς θα χρειαστεί να αντικατασταθούν.

Άλλαξε στην έκδοση 3.5: Η μέθοδος index() πρόσθεσε υποστήριξη για τα ορίσματα stop και start.

class collections.abc.Set

class collections.abc.MutableSet

ABCs μόνο για ανάγνωση (read-only) και mutable sets.

class collections.abc.Mapping

class collections.abc.MutableMapping

ABCs μόνο για ανάγνωση (read-only) και mutable mappings.

class collections.abc.MappingView

class collections.abc.ItemsView

class collections.abc.KeysView

class collections.abc.ValuesView

ABCs για αντιστοιχήσεις, στοιχεία, κλειδιά και τιμές views.

class collections.abc.Awaitable

ABC για αντικείμενα awaitable, που μπορούν να χρησιμοποιηθούν σε εκφράσεις await. Οι προσαρμοσμένες υλοποιήσεις πρέπει να παρέχουν τη μέθοδο __await__().

Τα αντικείμενα Coroutine και τα στιγμιότυπα της κλάσης Coroutine είναι όλα παραδείγματα αυτής της ABC.

Σημείωση

Στην CPython, οι generator-based coroutines (generators που είναι decorated με @types.coroutine) είναι awaitables, αν και δεν διαθέτουν μέθοδο __await__(). Η χρήση της isinstance(gencoro, Awaitable) γι” αυτές θα επιστρέψει False. Χρησιμοποιείτε τη συνάρτηση inspect.isawaitable() για να τις εντοπίσετε.

Νέο στην έκδοση 3.5.

class collections.abc.Coroutine

ABC για κλάσεις συμβατές με το coroutine. Αυτές υλοποιούν τις εξής μεθόδους, οι οποίες ορίζονται στο Coroutine Objects: send(), throw(), και close(). Οι προσαρμοσμένες υλοποιήσεις πρέπει επίσης να υλοποιούν τη μέθοδο __await__(). Όλα τα Coroutine στιγμιότυπα είναι επίσης στιγμιότυπα της κλάσης Awaitable.

Σημείωση

Στην CPython, οι generator-based coroutines (generators που είναι διακοσμημένες με @types.coroutine) είναι awaitables, αν και δεν έχουν τη μέθοδο __await__(). Η χρήση της isinstance (gencoro, Coroutine) γι” αυτές θα επιστρέψει False. Χρησιμοποιείται η συνάρτηση inspect.isawaitable() για να εντοπιστούν.

Νέο στην έκδοση 3.5.

class collections.abc.AsyncIterable

ABC για κλάσεις που παρέχουν μια μέθοδο __aiter__. Δείτε επίσης τον ορισμό του asynchronous iterable.

Νέο στην έκδοση 3.5.

class collections.abc.AsyncIterator

ABC για κλάσεις που παρέχουν τις μεθόδους __aiter__ και __anext__. Δείτε επίσης τον ορισμό του asynchronous iterator.

Νέο στην έκδοση 3.5.

class collections.abc.AsyncGenerator

ABC για κλάσεις asynchronous generator που υλοποιούν το πρωτόκολλο που ορίζεται στο PEP 525 και PEP 492.

Νέο στην έκδοση 3.6.

Παραδείγματα και Συνταγές

Οι ABCs επιτρέπουν να ρωτήσουμε τις κλάσεις ή τα αντικείμενα αν παρέχουν συγκεκριμένη λειτουργικότητα, για παράδειγμα:

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

Μερικές από τις ABCs είναι επίσης χρήσιμες ως mixins που διευκολύνουν την ανάπτυξη κλάσεων που υποστηρίζουν τα APIs των container. Για παράδειγμα, για να γράψετε μια κλάση που υποστηρίζει το πλήρες 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 ως mixin:

1. Δεδομένου ότι ορισμένες λειτουργίες συνόλων δημιουργούν νέα σύνολα, οι προεπιλεγμένες μέθοδοι mixin χρειάζονται έναν τρόπο δημιουργίας νέων αντικειμένων από ένα iterable. Υποτίθεται ότι ο κατασκευαστής της κλάσης έχει μια υπογραφή της μορφής ClassName(iterable). Αυτή η υπόθεση είναι αποσυνδεδεμένη σε μια εσωτερική classmethod που ονομάζεται _from_iterable(), η οποία καλεί το cls(iterable) για να δημιουργήσει ένα νέο σύνολο. Εάν το mixin Set χρησιμοποιείται σε μια κλάση με διαφορετική υπογραφή κατασκευαστή, θα χρειαστεί να αντικαταστήσετε την _from_iterable() με μια μέθοδο κλάσης ή κανονική μέθοδο που μπορεί να δημιουργήσει νέα αντικείμενα από ένα όρισμα iterable.

2. Για να παρακάμψετε τις συγκρίσεις (πιθανότατα για λόγους απόδοσης, καθώς η σημασιολογία είναι καθορισμένη), ορίστε ξανά τις μεθόδους __le__(), και __ge__(), και οι άλλες λειτουργίες θα ακολουθήσουν αυτόματα.

3. Το mixin Set παρέχει τη μέθοδο meth:!_hash για να υπολογίσει μια τιμή κατακερματισμού για το σύνολο. Ωστόσο, η μέθοδος __hash__() δεν είναι ορισμένη, επειδή δεν είναι όλα τα σύνολα hashable ή αμετάβλητα. Για να προσθέσετε hashability σε ένα σύνολο χρησιμοποιώντας mixins, κληρονομήστε τόσο από τις κλάσεις Set() όσο και Hashable(), και στη συνέχεια ορίστε __hash__ = Set._hash.

Δείτε επίσης

• Συνταγή OrderedSet για ένα παράδειγμα που βασίζεται στην κλάση MutableSet.

• Για περισσότερα σχετικά με τις ABCs, δείτε το abc module και το PEP 3119.