abstracts 0.0.12

Abstract class and interface definitions

Abstract class and interface definitions.

Create an abstract.Abstraction

An Abstraction is a metaclass for defining abstract classes.

Let’s define an abstract AFoo class and give it an abstract do_foo method.

Like any python class, an Abstraction can have any name, but it may be helpful to distinguish abstract classes from others by prefixing their name with A.

>>> import abc
>>> import abstracts

>>> class AFoo(metaclass=abstracts.Abstraction):
...
...     @abc.abstractmethod
...     def do_foo(self):
...         raise NotImplementedError

Abstract classes cannot be instantiated directly.

>>> AFoo()
Traceback (most recent call last):
...
TypeError: Can't instantiate abstract class AFoo with abstract method... do_foo

Create an implementer for an abstract.Abstraction

In order to make use of AFoo, we need to create an implementer for it.

>>> @abstracts.implementer(AFoo)
... class Foo:
...     pass

The implementer must implement all of the abstract methods, defined by its abstract classes.

>>> Foo()
Traceback (most recent call last):
...
TypeError: Can't instantiate abstract class Foo with abstract method... do_foo

>>> @abstracts.implementer(AFoo)
... class Foo2:
...
...     def do_foo(self):
...         return "DID FOO"

>>> Foo2()
<__main__.Foo2 object at ...>

An implementer inherits from its Abstractions

An implementer class is a subclass of its Abstraction.

>>> issubclass(Foo2, AFoo)
True

Likewise an instance of an implementer is an instance of its Abstraction

>>> isinstance(Foo2(), AFoo)
True

The Abstraction class can be seen in the class bases, and the methods of the Abstraction can be invoked by the implementer.

>>> import inspect
>>> AFoo in inspect.getmro(Foo2)
True

Create an implementer that implements multiple Abstraction s.

An implementer can implement multiple abstractions.

Let’s create a second abstraction.

>>> class ABar(metaclass=abstracts.Abstraction):
...
...     @abc.abstractmethod
...     def do_bar(self):
...         raise NotImplementedError

And now we can create an implementer that implememts both the AFoo and ABar Abstraction s.

>>> @abstracts.implementer((AFoo, ABar))
... class FooBar:
...
...     def do_foo(self):
...         return "DID FOO"
...
...     def do_bar(self):
...         return "DID BAR"

>>> FooBar()
<__main__.FooBar object at ...>

Defining abstract properties

Properties can be defined in an abstract class, and just like with normal methods, they must be implemented by any implementers.

>>> class AMover(metaclass=abstracts.Abstraction):
...
...     @property
...     @abc.abstractmethod
...     def speed(self):
...         return 5
...
...     @property
...     @abc.abstractmethod
...     def direction(self):
...         return "forwards"

Calling super() on an abstractmethod

Just like with pythons “Abstract Base Classes” you can call super() in an abstractmethod, to invoke an abstract implementation.

>>> @abstracts.implementer(AMover)
... class Mover:
...
...     @property
...     def direction(self):
...         return "backwards"
...
...     @property
...     def speed(self):
...         return super().speed

This custom implementation of AMover must implement both speed and direction, even if its implementation invokes the abstract implementation.

In this case it uses the default/abstract implementation of speed while providing its own implementation of direction.

>>> mover = Mover()
>>> mover
<__main__.Mover object at ...>

>>> mover.speed
5
>>> mover.direction
'backwards'

Defining an abstracts.Interface class

An Interface is much like an Abstraction, but with a few differences.

An Interface can only define methods with the @interfacemethod decorator.

It cannot define normal methods or methods with the @abstractmethod, only methods with @interfacemethod.

An @interfacemethod if invoked will always raise an NotImplementedError, and therefore cannot be used as an abstract implementation.

Lets add an Interface class that we can use.

In the way that it may be helpful to distinguish an Abstraction from other types of classes, it may be also useful to distinguish an Interface by using an I prefix when naming them.

>>> class IGeared(metaclass=abstracts.Interface):
...
...     @property
...     @abstracts.interfacemethod
...     def number_of_gears(self):
...         # Raising an error is ~superfluous as the decorator will raise
...         # anyway if the method is invoked.
...         raise NotImplementedError

Implementing an Interface

Just like with an Abstraction, an Interface can be implemented using the @implementer decorator.

An implementer, can implement a combination of Abstractions and Interfaces.

>>> @abstracts.implementer((AMover, IGeared))
... class Bicycle:
...
...     @property
...     def direction(self):
...         return super().direction
...
...     @property
...     def speed(self):
...         return super().speed
...
...     @property
...     def number_of_gears(self):
...         return 7

>>> Bicycle().number_of_gears
7

An implementer does not inherit from its Interfaces

An implementer class is a subclass of its Interfaces.

>>> issubclass(Bicycle, AMover)
True
>>> issubclass(Bicycle, IGeared)
True

Likewise an instance of an implementer is an instance of its Interfaces

>>> isinstance(Bicycle(), AMover)
True
>>> isinstance(Bicycle(), IGeared)
True

Unlike with Abstractions it does not however, inherit from its Interfaces.

>>> AMover in inspect.getmro(Bicycle)
True

>>> IGeared in inspect.getmro(Bicycle)
False

@interfacemethods can never be invoked

The key thing to remember is that you cannot call super() on any @interfacemethod, or directly invoke it.

If it was defined as part of an Interface you will receive an AttributeError, as the implementation does not inherit directly from the interface.

>>> @abstracts.implementer((AMover, IGeared))
... class BrokenBicycle:
...
...     @property
...     def direction(self):
...         return super().direction
...
...     @property
...     def speed(self):
...         return super().speed
...
...     @property
...     def number_of_gears(self):
...         return super().number_of_gears

>>> BrokenBicycle().number_of_gears
Traceback (most recent call last):
...
AttributeError: 'super' object has no attribute 'number_of_gears'

Warning

Misuse of this class can have unintended consequences

If you invoke super() on an @interfacemethod defined as part of an Abstraction it will raise NotImplementedError.

As an Interface can only hold this type of method, you can never invoke any of its methods. Doing so directly will raising a NotImplementedError.

>>> IGeared.number_of_gears.__get__(Bicycle())
Traceback (most recent call last):
...
NotImplementedError

Combining @abstractmethod and @interfacemethod in an Abstraction

As Interfaces are “pure”, they cannot use @abstractmethod or contain any implementation.

An Abstraction on the other hand can combine both.

Lets create a pure Interface that represents a “shed”.

>>> class IShed(metaclass=abstracts.Interface):
...
...     @property
...     @abstracts.interfacemethod
...     def size(self):
...         raise NotImplementedError

We can use this interface to create an ABikeShed Abstraction

>>> class ABikeShed(IShed, metaclass=abstracts.Abstraction):
...
...     @property
...     @abstracts.interfacemethod
...     def max_bike_size(self):
...         raise NotImplementedError
...
...     @abc.abstractmethod
...     def get_capacity(self):
...         return int(self.size / self.max_bike_size)

We can now create an implementation.

It will need to define both the size and the max_bike_size, as these are interfacemethods.

It can, however, make use of the abstract implementation of get_capacity, even if it must be defined.

>>> @abstracts.implementer(ABikeShed)
... class BikeShed:
...
...     @property
...     def max_bike_size(self):
...         return 7
...
...     @property
...     def size(self):
...         return 161
...
...     def get_capacity(self):
...         return super().get_capacity()

>>> bikeshed = BikeShed()
>>> bikeshed.get_capacity()
23