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

`abc` — Clases de Base Abstracta¶

Tema anterior

Próximo tema

Esta página

abc — Clases de Base Abstracta¶

`abc` — Clases de Base Abstracta¶