"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",   | "__contains__",         |                                                      |
|                                | "Container"            | "__iter__", "__len__"   |                                                      |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Sequence"                     | "Reversible",          | "__getitem__",          | "__contains__", "__iter__", "__reversed__", "index", |
|                                | "Collection"           | "__len__"               | and "count"                                          |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MutableSequence"              | "Sequence"             | "__getitem__",          | Κληρονομημένες "Sequence" μέθοδοι και "append",      |
|                                |                        | "__setitem__",          | "clear", "reverse", "extend", "pop", "remove", and   |
|                                |                        | "__delitem__",          | "__iadd__"                                           |
|                                |                        | "__len__", "insert"     |                                                      |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "ByteString"                   | "Sequence"             | "__getitem__",          | Κληρονομημένες "Sequence" μέθοδοι                    |
|                                |                        | "__len__"               |                                                      |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Set"                          | "Collection"           | "__contains__",         | "__le__", "__lt__", "__eq__", "__ne__", "__gt__",    |
|                                |                        | "__iter__", "__len__"   | "__ge__", "__and__", "__or__", "__sub__", "__xor__", |
|                                |                        |                         | and "isdisjoint"                                     |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MutableSet"                   | "Set"                  | "__contains__",         | Κληρονομημένες "Set" μέθοδοι και "clear", "pop",     |
|                                |                        | "__iter__", "__len__",  | "remove", "__ior__", "__iand__", "__ixor__", και     |
|                                |                        | "add", "discard"        | "__isub__"                                           |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Mapping"                      | "Collection"           | "__getitem__",          | "__contains__", "keys", "items", "values", "get",    |
|                                |                        | "__iter__", "__len__"   | "__eq__", και "__ne__"                               |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MutableMapping"               | "Mapping"              | "__getitem__",          | Κληρονομημένες "Mapping" μέθοδοι και "pop",          |
|                                |                        | "__setitem__",          | "popitem", "clear", "update", και "setdefault"       |
|                                |                        | "__delitem__",          |                                                      |
|                                |                        | "__iter__", "__len__"   |                                                      |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MappingView"                  | "Sized"                |                         | "__len__"                                            |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "ItemsView"                    | "MappingView", "Set"   |                         | "__contains__", "__iter__"                           |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "KeysView"                     | "MappingView", "Set"   |                         | "__contains__", "__iter__"                           |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "ValuesView"                   | "MappingView",         |                         | "__contains__", "__iter__"                           |
|                                | "Collection"           |                         |                                                      |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "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] Αυτές οι 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**.
