# `collections.abc` — Αφηρημένες Βασικές Κλάσεις για Containers

Added in version 3.3: Παλαιότερα, αυτό το module ήταν μέρος του `collections` module.

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

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

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

1. Μια νέα γραμμένη κλάση μπορεί να κληρονομήσει άμεσα από τις αφηρημένες βασικές κλάσεις. Η κλάση πρέπει να παρέχει τις απαιτούμενες αφηρημένες μεθόδους. Οι υπόλοιπες μέθοδοι mixin προέρχονται από την κληρονομικότητα και μπορούν να παρακαμφθούν αν χρειάζεται. Άλλες μέθοδοι μπορούν να προστεθούν όταν είναι αναγκαίο:

       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. Υπάρχουσες κλάσεις και ενσωματωμένες κλάσεις μπορούν να καταχωρηθούν ως «εικονικές υποκλάσεις» των ABCs. Αυτές οι κλάσεις θα πρέπει να ορίζουν το πλήρες API, συμπεριλαμβανομένων όλων των αφηρημένων μεθόδων και όλων των μεθόδων mixin. Αυτό επιτρέπει στους χρήστες να βασίζονται στους ελέγχους `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-operator, η λογική iteration, και η συνάρτηση `reversed()` χρησιμοποιούν αυτόματα τις μεθόδους `__getitem__` και `__len__`.

3. Ορισμένες απλές διεπαφές είναι άμεσα αναγνωρίσιμες από την παρουσία των απαιτούμενων μεθόδων (εκτός αν αυτές οι μέθοδοι έχουν οριστεί σε `None`):

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

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

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

Added in version 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__`, `__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__` and `__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__` |

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

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

Αυτές οι 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__()`.

  Ανατρέξτε στο Annotating callable objects για λεπτομέρειες σχετικά με τον τρόπο χρήσης του `Callable` σε τύπους annotations.

class collections.abc.Iterable

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

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

class collections.abc.Collection

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

  Added in version 3.6.

class collections.abc.Iterator

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

class collections.abc.Reversible

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

  Added in version 3.6.

class collections.abc.Generator

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

  Δείτε. Annotating generators and coroutines για λεπτομέρειες σχετικά με τη χρήση του `Generator` σε τύπους annotations.

  Added in version 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 θα έχουν τετραγωνική απόδοση και πιθανώς θα χρειαστεί να αντικατασταθούν.

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

    Επιστρέφει τον πρώτο δείκτη του value.

    Κάνει raise μια `ValueError` αν η τιμή δεν είναι παρούσα.

    Η υποστήριξη των ορισμάτων start και stop είναι προαιρετική, αλλά συνιστάται.

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

  Καταργήθηκε από την έκδοση 3.12, θα αφαιρεθεί στην έκδοση 3.17: Η ABC `ByteString` έχει αποσυρθεί.

  Χρησιμοποιήστε το `isinstance(obj, collections.abc.Buffer)` για να ελέγξετε αν το `obj` υλοποιεί το buffer protocol κατά το runtime. Για χρήση σε type annotations, είτε χρησιμοποιήστε την `Buffer` είτε μια ένωση που να καθορίζει ρητά τους τύπους που υποστηρίζει ο κώδικάς σας (π.χ., `bytes | bytearray | memoryview`).

  Η `ByteString` προοριζόταν αρχικά να είναι μια αφηρημένη κλάση που θα λειτουργούσε ως υπερτύπος τόσο για την `bytes` όσο και για την `bytearray`. Ωστόσο, δεδομένου ότι η ABC δεν είχε καμία μέθοδο, η γνώση ότι ένα αντικείμενο ήταν στιγμιότυπο της `ByteString` δεν σας έλεγε ποτέ κάτι χρήσιμο για το αντικείμενο. Άλλοι κοινοί τύποι buffer όπως η `memoryview` επίσης δεν θεωρούνταν ποτέ ως υποτύποι της `ByteString` (ούτε κατά το runtime ούτε από στατικούς ελεγκτές τύπων).

  Δείτε PEP 688 για περισσότερες λεπτομέρειες.

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()` για να τις εντοπίσετε.

  Added in version 3.5.

class collections.abc.Coroutine

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

  Σημείωση

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

  Βλ. Annotating generators and coroutines για λεπτομέρειες σχετικά με τη χρήση της `Coroutine` σε σχολιασμούς τύπου. Η διακύμανση και η σειρά των παραμέτρων τύπου αντιστοιχούν σε εκείνες της `Generator`.

  Added in version 3.5.

class collections.abc.AsyncIterable

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

  Added in version 3.5.

class collections.abc.AsyncIterator

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

  Added in version 3.5.

class collections.abc.AsyncGenerator

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

  Δείτε Annotating generators and coroutines για λεπτομέρειες σχετικά με τη χρήση του `AsyncGenerator` σε σχολιασμούς τύπου.

  Added in version 3.6.

class collections.abc.Buffer

  ABC για κλάσεις που παρέχουν τη μέθοδο `__buffer__()`, υλοποιώντας το buffer protocol. Δείτε το PEP 688.

  Added in version 3.12.

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

Οι 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` παρέχει τη μέθοδο `_hash()` για να υπολογίσει μια τιμή κατακερματισμού για το σύνολο. Ωστόσο, η μέθοδος `__hash__()` δεν είναι ορισμένη, επειδή δεν είναι όλα τα σύνολα hashable ή αμετάβλητα. Για να προσθέσετε hashability σε ένα σύνολο χρησιμοποιώντας mixins, κληρονομήστε τόσο από τις κλάσεις `Set()` όσο και `Hashable()`, και στη συνέχεια ορίστε `__hash__ = Set._hash`.

Δείτε επίσης

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

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