# `abc` — Classes Base Abstratas

Código-fonte: Lib/abc.py

Este módulo fornece a infraestrutura para definir classes base abstratas (ABCs, do inglês abstract base class) 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 tipo para números baseado nas ABCs.)

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 é hasheável ou se é um mapeamento.

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

class `abc.``ABC`

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

      from abc import ABC

      class MyABC(ABC):
          pass

  Note que o tipo da classe `ABC` ainda é `ABCMeta`, portanto herdar da `ABC` requer as precauções usuais a respeito do uso da metaclasse, pois herança múltipla pode levar a conflitos de metaclasse. Pode-se também definir uma classe base abstrata ao passar a palavra reservada metaclasse e usar `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 (ABCs).

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

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

  `register`(subclass)

    Registra subclass como uma “subclasse virtual” desta ABC. 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 ABC:

      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 `Mylterable` da CBA 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__`) é considerada 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 decorador indicando métodos abstratos.

  Usar este decorador requer que a metaclasse da classe seja `ABCMeta` ou seja derivada desta. Uma classe que tem uma metaclasse derivada de `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 mecanismos 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 descritores 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, 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 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 `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 `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á descontinuado, 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, arg):
              ...

`@``abc.``abstractstaticmethod`

  Novo na versão 3.2.

  Obsoleto desde a versão 3.3: Agora é possível usar `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(arg):
              ...

`@``abc.``abstractproperty`

  Obsoleto desde a versão 3.3: Agora é possível usar `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 escrita 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 `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 classe base virtual do Python não é o mesmo que o de C++.