# `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

  Tenga en cuenta que el tipo de `ABC` sigue siendo `ABCMeta`, por lo tanto, heredar de `ABC` requiere las precauciones habituales con respecto al uso de metaclases, ya que la herencia múltiple puede dar lugar a conflictos de metaclases. También se puede definir una clase base abstracta pasando la palabra clave metaclase y usando `ABCMeta` directamente, por ejemplo:

      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.

  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, solo se admite mediante la función `update_abstractmethods()`. `abstractmethod()` solo afecta a las subclases derivadas mediante herencia regular; Las «subclases virtuales» registradas con el método `register()` de ABC no se ven 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, arg1):
              ...
          @classmethod
          @abstractmethod
          def my_abstract_classmethod(cls, arg2):
              ...
          @staticmethod
          @abstractmethod
          def my_abstract_staticmethod(arg3):
              ...

          @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, arg):
              ...

`@``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(arg):
              ...

`@``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.

`abc.``update_abstractmethods`(cls)

  Una función para recalcular el estado de abstracción de una clase abstracta. Se debe llamar a esta función si los métodos abstractos de una clase se han implementado o cambiado después de su creación. Por lo general, esta función debe llamarse desde dentro de un decorador de clases.

  Retorna cls, para permitir su uso como decorador de clases.

  Si cls no es una instancia de `ABCMeta`, no hace nada.

  Nota

  Esta función asume que las superclases de cls ya están actualizadas. No actualiza subclases.

  Nuevo en la versión 3.10.

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++.