"""The Reader classes return high-level content structures from files.

The Reader fulfills two purposes:
    First, it brokers between multiple libraries and file formats.
    Second, it separates multiple aspects of a file into distinct content types.

Part of the bsie module.
A copy of the license is provided with the project.
Author: Matthias Baumgartner, 2022
"""
# imports
import abc
import typing

# inner-module imports
from bsie.utils.bsfs import URI, typename

# exports
__all__: typing.Sequence[str] = (
    'Aggregator',
    'Reader',
    )


## code ##

class Reader(abc.ABC):
    """Read and return some content from a file."""

    # In what data structure content is returned
    CONTENT_TYPE = typing.Union[typing.Any]
    # NOTE: Child classes must also assign a typing.Union even if there's
    # only one options

    def __str__(self) -> str:
        return typename(self)

    def __repr__(self) -> str:
        return f'{typename(self)}()'

    # FIXME: How about using contexts instead of calls?
    @abc.abstractmethod
    def __call__(self, path: URI) -> CONTENT_TYPE:
        """Return some content of the file at *path*.
        Raises a `ReaderError` if the reader cannot make sense of the file format.
        """

## EOF ##