Implement class-based readers/writers

[dalonsoa]

Problem

Currently, each reader/writer need to read the header, extract the information it needs from there, and then read the data - and in the future, validate it (see #14). That is a lot of repetition of the same code when each reader/writer should only worry about the actual read/write of the data. It also makes harder to implement common functionality across all readers/writers, should it be necessary, as the code would need to be updated in multiple places.

Solution

Move to class-based readers where all the common functionality can be packed together in a base class and where each reader/writer only needs to implement the specific reading action.

It could look something like the following, sticking the whole reading process in one go in the __init__ method, as if it were a function:

class BaseReader(ABC):

    def __init__(...):
        ...
        with filename.open(...) as f:
            self._read_header(f)
            self._read_data(f)

        self._validate_data()

    @abstractmethod
    def _read_data(...):
        # Read the actual tabular data. The main method to be overridden

    def _read_header(...):
        # Read the header and extract any common metadata

    def _validate_data(...):
        # Validate the data. Might be overridden for each format

    @property
    def data(...) -> Any:
        # Return the data. Subclasses might override this to return a specific type

    @property
    def metadata(...) -> Dict[str, Any]:
        # Return the metadata.

And similar for the writers. This has the advantage that the same file object is used for both the header and the data, as suggested in #28 . Actually adding validation is a task for #14 .

Addressing this PR will require multiple issues - and multiple PR - so convert the following in issues as needed:

Readers

• Write base class for readers
• Write specific subclass for reading into lists
• Write specific subclass for reading into dicts
• Write specific subclass for reading into numpy arrays
• Write specific subclass for reading into pandas dataframes
• Write specific subclass for reading into polars dataframes
• [New] Write specific subclass for reading into iterators

Writers

This should be compatible with the existing Writer class, which will need updating.

• Write base class for writers
• Write specific subclass for writing lists
• Write specific subclass for writing dicts
• Write specific subclass for writing numpy arrays
• Write specific subclass for writing pandas dataframes
• Write specific subclass for writing polars dataframes
• Write specific subclass for writing incrementally (replaces current class for that)

As the class-based readers are implemented, the existing functions should be replaced and include a deprecation warning. Eg:

def read_to_array(...):
    raise FutureWarning(...) # Mention version 2.0.0, for example
    reader = ArrayReader(...)
    return reader.data, reader.metadata

So we keep the same API, but internally we use the class-based approach.