"abc" --- Clases de Base Abstracta
**********************************

**Código fuente:** Lib/abc.py

======================================================================

Este módulo proporciona la infraestructura para definir *clases de
base abstracta* (CBAs) en Python, como se describe en **PEP 3119**;
consulte en el PEP el porqué fue agregado a Python. (Véase también
**PEP 3141** y el módulo "numbers" con respecto a una jerarquía de
tipos para números basados en CBAs.)

The "collections" module has some concrete classes that derive from
ABCs; these can, of course, be further derived. In addition, the
"collections.abc" submodule has some ABCs that can be used to test
whether a class or instance provides a particular interface, for
example, if it is hashable or if it is a mapping.

Este módulo provee la metaclase "ABCMeta" para definir CBAs y una
clase auxiliar "ABC" para definir CBAs alternativamente a través de
herencia:

class abc.ABC

   Una clase auxiliar que tiene una "ABCMeta" como su metaclase.  Con
   esta clase, una clase de base abstracta puede ser creada
   simplemente derivándola desde "ABC" evitando el uso de metaclases
   algunas veces confusos, por ejemplo:

      from abc import ABC

      class MyABC(ABC):
          pass

   Note that the type of "ABC" is still "ABCMeta", therefore
   inheriting from "ABC" requires the usual precautions regarding
   metaclass usage, as multiple inheritance may lead to metaclass
   conflicts. One may also define an abstract base class by passing
   the metaclass keyword and using "ABCMeta" directly, for example:

      from abc import ABCMeta

      class MyABC(metaclass=ABCMeta):
          pass

   Nuevo en la versión 3.4.

class abc.ABCMeta

   Metaclases para definir Clases de Base Abstracta (CBAs).

   Utilice esta metaclase para crear una CBA.  Una CBA puede ser
   heredada directamente y así, actuar como una clase mixta.  También
   se puede registrar clases concretas no relacionadas (incluso clases
   integradas) y CBAs no relacionadas como "subclases virtuales" --
   estas y sus descendientes serán consideradas subclases del CBA
   registrado por la función integrada "issubclass()", pero la CBA
   registrada no aparecerá en su *MRO* (Orden de Resolución de
   Métodos) ni las implementaciones de método definidas por la CBA
   registrada serán invocables (ni siquiera a través de "super()").
   [1]

   Las clases creadas con una metaclase de "ABCMeta" tienen el
   siguiente método:

   register(subclass)

      Registre la *subclase* como una "subclase virtual" de esta CBA.
      Por ejemplo:

         from abc import ABC

         class MyABC(ABC):
             pass

         MyABC.register(tuple)

         assert issubclass(tuple, MyABC)
         assert isinstance((), MyABC)

      Distinto en la versión 3.3: Retorna la subclase registrada, para
      permitir su uso como decorador de clase.

      Distinto en la versión 3.4: Para detectar llamadas a
      "register()", se puede usar la función "get_cache_token()".

   También se puede redefinir este método en una clase de base
   abstracta:

   __subclasshook__(subclass)

      (Debe ser definido como un método de clase.)

      Compruebe si la *subclase* se considera una subclase de esta
      CBA.  Esto significa que puede personalizar aún más el
      comportamiento de "issubclass" sin necesidad de llamar a
      "register()" en cada clase que desee considerar una subclase de
      la CBA.  (Este método de clase es llamado desde el método
      "__subclasscheck__()" del CBA.)

      Este método debe retornar "True", "False" o "NotImplemented".
      Si retorna "True", la *subclase* se considera una subclase de
      esta CBA. Si retorna "False", la *subclase* no se considera una
      subclase de esta CBA, incluso si normalmente fuese una.  Si
      retorna "NotImplemented", la comprobación de subclase se
      continúa con el mecanismo usual.

   Para una demostración de estos conceptos, vea este ejemplo de la
   definición CBA:

      class Foo:
          def __getitem__(self, index):
              ...
          def __len__(self):
              ...
          def get_iterator(self):
              return iter(self)

      class MyIterable(ABC):

          @abstractmethod
          def __iter__(self):
              while False:
                  yield None

          def get_iterator(self):
              return self.__iter__()

          @classmethod
          def __subclasshook__(cls, C):
              if cls is MyIterable:
                  if any("__iter__" in B.__dict__ for B in C.__mro__):
                      return True
              return NotImplemented

      MyIterable.register(Foo)

   La CBA "MyIterable" define el método iterable estándar,
   "__iter__()", como un método abstracto.  La implementación dada
   aquí aún se puede llamar desde subclases.  El método
   "get_iterator()" también forma parte de la clase de base abstracta
   "MyIterable", pero no tiene que ser reemplazado en clases derivadas
   no abstractas.

   El método de la clase "__subclasshook__()" definido aquí dice que
   cualquier clase que tenga un método "__iter__()" en su "__dict__"
   (o en la de una de sus clases base, a la que se accede a través de
   la lista "__mro__") también se considera un "MyIterable".

   Por último, la última línea convierte "Foo" en una subclase virtual
   de "MyIterable", aunque no define un método "__iter__()" (utiliza
   el protocolo iterable al estilo antiguo, definido en términos de
   "__len__()" y "__getitem__()").  Tenga en cuenta que esto no hará
   que "get_iterator" esté disponible como un método de "Foo", por lo
   que es proporcionado por separado.

El módulo "abc" también proporciona el siguiente decorador:

@abc.abstractmethod

   Un decorador que indica métodos abstractos.

   El uso de este decorador requiere que la metaclase de la clase sea
   "ABCMeta" o se derive de esta.  Una clase que tiene una metaclase
   derivada de "ABCMeta" no puede ser instanciada, a menos que todas
   sus propiedades y métodos abstractos sean anulados.  Los métodos
   abstractos se pueden invocar usando cualquiera de los mecanismos de
   'super' invocación normales.  "abstractmethod()" se puede utilizar
   para declarar métodos abstractos para propiedades y descriptores.

   No se admite la adición dinámica de métodos abstractos a una clase
   o el intento de modificar el estado de abstracción de un método o
   clase una vez creado.  El "abstractmethod()" sólo afecta a las
   subclases derivadas mediante herencia regular; las "subclases
   virtuales" registradas con el método "register()" de CBAs no son
   afectadas.

   Cuando "abstractmethod()" se aplica en combinación con otros
   descriptores de método, se debe aplicar como el decorador más
   interno, como se muestra en los siguientes ejemplos de uso:

      class C(ABC):
          @abstractmethod
          def my_abstract_method(self, ...):
              ...
          @classmethod
          @abstractmethod
          def my_abstract_classmethod(cls, ...):
              ...
          @staticmethod
          @abstractmethod
          def my_abstract_staticmethod(...):
              ...

          @property
          @abstractmethod
          def my_abstract_property(self):
              ...
          @my_abstract_property.setter
          @abstractmethod
          def my_abstract_property(self, val):
              ...

          @abstractmethod
          def _get_x(self):
              ...
          @abstractmethod
          def _set_x(self, val):
              ...
          x = property(_get_x, _set_x)

   Para interoperar correctamente con la maquinaria de clase de base
   abstracta, el descriptor debe identificarse como abstracto
   utilizando "__isabstractmethod__". En general, este atributo debe
   ser "True" si alguno de los métodos utilizados para componer el
   descriptor es abstracto. Por ejemplo, la clase de propiedad
   integrada de Python "property" hace el equivalente de:

      class Descriptor:
          ...
          @property
          def __isabstractmethod__(self):
              return any(getattr(f, '__isabstractmethod__', False) for
                         f in (self._fget, self._fset, self._fdel))

   Nota:

     A diferencia de los métodos abstractos de Java, estos métodos
     abstractos pueden tener una implementación. Esta implementación
     se puede llamar a través del mecanismo "super()" de la clase que
     lo invalida.  Esto podría ser útil como un *end-point* para una
     super llamada en un *framework* que use herencia múltiple
     cooperativa.

El módulo "abc" también es compatible con los siguientes decoradores
heredados:

@abc.abstractclassmethod

   Nuevo en la versión 3.2.

   Obsoleto desde la versión 3.3: Ahora es posible utilizar
   "classmethod" con "abstractmethod()", lo cual hace que este
   decorador sea redundante.

   Una subclase de la "classmethod()" incorporada, indicando un método
   de clase abstracto. De otra forma, es similar a "abstractmethod()".

   Este caso especial está obsoleto, ya que el decorador
   "classmethod()" ahora es identificado correctamente como abstracto
   cuando se aplica a un método abstracto:

      class C(ABC):
          @classmethod
          @abstractmethod
          def my_abstract_classmethod(cls, ...):
              ...

@abc.abstractstaticmethod

   Nuevo en la versión 3.2.

   Obsoleto desde la versión 3.3: Ahora es posible utilizar
   "staticmethod" con "abstractmethod()", haciendo que este decorador
   sea redundante.

   Una subclase de la "staticmethod()" incorporada, indicando un
   método estático abstracto. De otra forma, es similar a
   "abstractmethod()".

   Este caso especial está obsoleto, ya que el decorador
   "staticmethod()" ahora es identificado correctamente como abstracto
   cuando se aplica a un método abstracto:

      class C(ABC):
          @staticmethod
          @abstractmethod
          def my_abstract_staticmethod(...):
              ...

@abc.abstractproperty

   Obsoleto desde la versión 3.3: Ahora es posible utilizar
   "property", "property.getter()", "property.setter()" y
   "property.deleter()" con "abstractmethod()", lo cual hace que este
   decorador sea redundante.

   Una subclase de la "property()" integrada, que indica una propiedad
   abstracta.

   Este caso especial está obsoleto, ya que el decorador "property()"
   ahora es identificado correctamente como abstracto cuando es
   aplicado a un método abstracto:

      class C(ABC):
          @property
          @abstractmethod
          def my_abstract_property(self):
              ...

   En el ejemplo anterior se define una propiedad de solo lectura;
   también se puede definir una propiedad abstracta de lectura y
   escritura marcando adecuadamente uno o varios de los métodos
   subyacentes como abstractos:

      class C(ABC):
          @property
          def x(self):
              ...

          @x.setter
          @abstractmethod
          def x(self, val):
              ...

   Si solo algunos componentes son abstractos, solo estos componentes
   necesitan ser actualizados para crear una propiedad concreta en una
   subclase:

      class D(C):
          @C.x.setter
          def x(self, val):
              ...

El módulo "abc" también proporciona las siguientes funciones:

abc.get_cache_token()

   Retorna el token de caché de la clase base abstracta actual.

   El token es un objeto opaco (que admite pruebas de igualdad) que
   identifica la versión actual de la caché de clases de base
   abstractas para subclases virtuales. El token cambia con cada
   llamada a "ABCMeta.register()" en cualquier CBA.

   Nuevo en la versión 3.4.

-[ Notas al pie ]-

[1] Los desarrolladores de C++ pueden notar que el concepto de clase
    base virtual de Python no es el mismo que en C++.
