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

El módulo collections tiene algunas clases concretas que se derivan de ABC; estos, por supuesto, pueden derivarse más. Además, el submódulo collections.abc tiene algunos ABC que se pueden usar para probar si una clase o instancia proporciona una interfaz en particular, por ejemplo, si es hash o si es un mapeo.

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.

Dynamically adding abstract methods to a class, or attempting to modify the abstraction status of a method or class once it is created, are only supported using the update_abstractmethods() function. The abstractmethod() only affects subclasses derived using regular inheritance; «virtual subclasses» registered with the ABC’s register() method are not affected.

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.

abc.update_abstractmethods(cls)

A function to recalculate an abstract class’s abstraction status. This function should be called if a class’s abstract methods have been implemented or changed after it was created. Usually, this function should be called from within a class decorator.

Returns cls, to allow usage as a class decorator.

If cls is not an instance of ABCMeta, does nothing.

Nota

This function assumes that cls’s superclasses are already updated. It does not update any subclasses.

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