Specify interfaces for inheritance with abstract base classes

[jlvdb]

Some base classes in RAIL are commonly used implement algorithms or other utilities. In some cases it is not immediately clear which class methods are part of the base implementation and which should be overwritten/implemented by a subclass.

Example

rail.core.DataHandle: The methods _open, _read, _write, _initialize_write, _write_chunk, _finalize_write, _size, _iterator all raise NotImplementedErrors when the subclass does not implement them. ModelHandle for example implements only the first three methods, which may lead to unexpected behaviour. It is not clear which methods are required and in which context exceptions may occur. Furthermore, the methods are not fully documented and it is not always clear which functionality and in/outputs must be covered.

Suggestions

• Description of the expected behaviour in the doc-string and implementation of base classes with python's abc.ABC, and methods with the @abstract... decorators. Missing method implementations will be flagged when creating a class instance instead of during runtime.

• If some methods are only required in certain context, create a new subclass for theses situations and move the methods there, e.g.:

  class ChunkedDataHandle(DataHandle):
  @abstractmethod
  def _initialize_write(self): ...
  
  @abstractmethod
  def _write_chunk(self): ...

  and remove these methods from DataHandle.

Impact

Simplifies subclassing and clarifies the logical relationship between different classes.

[jlvdb]

I will start by adding the missing doc strings in core.data

[jlvdb]

Next add a subclassing guide to the class docstring