29.7. `abc` — Classes Base Abstratas¶

Código Fonte: Lib/abc.py

Este módulo fornece a infraestrutura para definir abstract base classes (CBAs) em Python, como delineado em PEP 3119; veja o PEP para entender o porquê isto foi adicionado ao Python. (Veja também PEP 3141 e o módulo numbers sobre uma hierarquia de tipos para números baseado nas CBAs.)

O módulo collections tem algumas classes concretas que derivam de CBAs; essas podem, evidentemente, ser ainda mais derivadas. Além disso, o submódulo collections.abc tem algumas CBAs que podem ser usadas para testar se uma classe ou instância oferece uma interface particular, por exemplo, se é hashable ou se é um mapping.

Este módulo fornece a metaclasse ABCMeta para definir CBAs e uma classe de ajuda ABC para alternativamente definir CBAs através de herança:

class abc.ABC¶

Uma classe auxiliar que tem :classe:`ABCMeta` como sua metaclasse. Com essa classe, uma classe base abstrata pode ser criada simplesmente derivando da :classe:`ABC` evitando às vezes confundir o uso da metaclasse, por exemplo:

from abc import ABC

class MyABC(ABC):
    pass

Note que o tipo de classe ABC ainda é :classe:`ABCMeta`, portanto herdando da :classe:`ABC` requer as precauções usuais a respeito do uso da metaclasse, como herança múltipla pode levar a conflitos de metaclasse. Pode-se também definir uma classe base abstrata ao passar a palavra reservada da metaclasse e usar :classe:`ABCMeta` diretamente, por exemplo:

from abc import ABCMeta

class MyABC(metaclass=ABCMeta):
    pass

Novo na versão 3.4.

class abc.ABCMeta¶

Metaclasse para definir Classe Base Abstrata (CBAs).

Use esta metaclasse para criar uma CBA. Uma CBA pode ser diretamente subclasseada, e então agir como uma classe misturada. Você também pode registrar classes concretas não relacionadas (até mesmo classes embutidas) e CBAs não relacionadas como “subclasses virtuais” – estas e suas descendentes serão consideradas subclasses da CBA de registro pela função embutida issubclass(), mas a CBA de registro não irá aparecer na ORM (Ordem de Resolução do Método) e nem as implementações do método definidas pela CBA de registro será chamável (nem mesmo via super()). 1

Classes criadas com a metaclasse de :classe:`ABCMeta` tem o seguinte método:

register(subclass)¶

Registrar subclasse como uma “subclasse virtual” desta CBA. Por exemplo:

from abc import ABC

class MyABC(ABC):
    pass

MyABC.register(tuple)

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

Alterado na versão 3.3: Retorna a subclasse registrada, para permitir o uso como um decorador de classe.

Alterado na versão 3.4: Para detectar chamadas para register(), você pode usar a função get_cache_token().

Você também pode sobrepor este método em uma classe base abstrata:

__subclasshook__(subclass)¶

(Deve obrigatoriamente ser definido como um método de classe.)

Cheque se a subclasse é considerada uma subclasse desta CBA. Isto significa que você pode customizar ainda mais o comportamento da issubclass sem a necessidade de chamar register() em toda classe que você queira considerar uma subclasse da CBA. (Este método de classe é chamado do método da CBA __subclasscheck__() .)

Este método deve retornar True, False ou NotImplemented. Se retornar True, a subclasse é considerada uma subclasse desta CBA. Se retornar False, a subclasse não é considerada uma subclasse desta CBA, mesmo que normalmente seria uma. Se retornar NotImplemented, a verificação da subclasse é continuada com o mecanismo usual.

Para uma demonstração destes conceitos, veja este exemplo de definição 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)

A CBA Mylterable define o método iterável padrão, __iter__(), como um método abstrato. A implementação dada aqui pode ainda ser chamada da subclasse. O método get_iterator() é também parte da classe base abstrata MyIterable, mas não precisa ser substituído nas classes derivadas não abstratas.

O método de classe __subclasshook__() definido aqui diz que qualquer classe que tenha um método __iter__() em seu __dict__ (ou no de uma de suas classes base, acessados via lista __mro__) é considerado uma MyIterable também.

Finalmente, a última linha faz de Foo uma subclasse virtual da MyIterable, apesar de não definir um método __iter__() (ela usa o protocolo iterável antigo, definido em termos de __len__() e __getitem__()). Note que isto não fará o get_iterator disponível como um método de Foo, então ele é fornecido separadamente.

O módulo abc também fornece o seguinte decorador:

@abc.abstractmethod¶

Um decorator indicando métodos abstratos.

Usar este decorador requer que a metaclasse da classe seja :classe:`ABCMeta` ou seja derivada desta. Uma classe que tem uma metaclasse derivada de :classe:`ABCMeta` não pode ser instanciada a menos que todos os seus métodos abstratos e propriedades estejam substituídos. Os métodos abstratos podem ser chamados usando qualquer um dos mechanismos normais de ‘super’ chamadas. abstractmethod() pode ser usado para declarar métodos abstratos para propriedades e descritores.

Adicionar dinamicamente métodos abstratos a uma classe, ou tentar modificar o status de abstração de um método ou classe uma vez que estejam criados, não é tolerado. A abstractmethod() afeta apenas subclasses derivadas usando herança regular; “subclasses virtuais” registradas com o método da CBA register() não são afetadas.

Quando abstractmethod() é aplicado em combinação com outros descriptores de método, ele deve ser aplicado como o decorador mais interno, como mostrado nos seguintes exemplos 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 que interopere corretamente com o maquinário da classe base abstrata, o descritor precisa identificar-se como abstrato usando __isabstractmethod__. No geral, este atributo deve ser True se algum dos métodos usados para compor o descritor for abstrato. Por exemplo, a :classe:`property` embutida do Python faz o equivalente a:

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

Nota

Diferente de métodos abstratos Java, esses métodos abstratos podem ter uma implementação. Esta implementação pode ser chamada via mecanismo da super() da classe que a substitui. Isto pode ser útil como um ponto final para uma super chamada em um framework que usa herança múltipla cooperativa.

O módulo abc também suporta os seguintes decoradores herdados:

@abc.abstractclassmethod¶

Novo na versão 3.2.

Obsoleto desde a versão 3.3: Agora é possível usar :classe:`classmethod` com abstractmethod(), tornando redundante este decorador.

Uma subclasse da classmethod() embutida, indicando um método de classe abstrato. Caso contrário, é similar à abstractmethod().

Este caso especial está depreciado, pois o decorador da classmethod() está agora corretamente identificado como abstrato quando aplicado a um método abstrato:

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

@abc.abstractstaticmethod¶

Novo na versão 3.2.

Obsoleto desde a versão 3.3: Agora é possível usar :classe:`staticmethod` com abstractmethod(), tornando redundante este decorador.

Uma subclasse da staticmethod() embutida, indicando um método estático abstrato. Caso contrário, ela é similar à abstractmethod().

Este caso especial está descontinuado, pois o decorador da staticmethod() está agora corretamente identificado como abstrato quando aplicado a um método abstrato:

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

@abc.abstractproperty¶

Obsoleto desde a versão 3.3: Agora é possível usar :classe:`property`, property.getter(), property.setter() e property.deleter() com abstractmethod(), tornando redundante este decorador.

Uma subclasse da property() embutida, indicando uma propriedade abstrata.

Este caso especial está descontinuado, pois o decorador da property() está agora corretamente identificado como abstrato quando aplicado a um método abstrato:

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

O exemplo acima define uma propriedade somente leitura; você também pode definir uma propriedade abstrata de leitura e gravação marcando apropriadamente um ou mais dos métodos subjacentes como abstratos:

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

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

Se apenas alguns componentes são abstratos, apenas estes componentes precisam ser atualizados para criar uma propriedade concreta em uma subclasse:

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

O módulo: mod: abc também fornece as seguintes funções:

abc.get_cache_token()¶

Retorna o token de cache da classe base abstrata atual.

O token é um objeto opaco (que suporta teste de igualdade) identificando a versão atual do cache da classe base abstrata para subclasses virtuais. O token muda a cada chamada ao ABCMeta.register() em qualquer CBA.

Novo na versão 3.4.

Notas de rodapé

1: Programadores C++ devem notar que o conceito da casse base virtual do Python não é o mesmo que o de C++.

29.7. `abc` — Classes Base Abstratas¶

Tópico anterior

Próximo tópico

Essa Página

29.7. abc — Classes Base Abstratas¶

29.7. `abc` — Classes Base Abstratas¶