Namespace restructure

[lochhh]

Context

• I find it a little strange that Reader is now in api.py. Does it make sense to add an internal "base.py" or "core.py" module that contains Reader? This could in the future contain also the base Writer class? That way we would avoid the cyclical dependency where reader.py and api.py import from each other.

Indeed this was initially forced by the cyclic dependency, but in fact I can see that "api.py" is really playing the role here of "base.py" or "core.py". Most of the times I think we should recommend just importing directly from swc.aeon.io and maybe we could make "api.py" private or move it into __init__.py.

I did not do this for backwards compatibility purposes (note Reader is still available as a simbol in "reader.py" since it is imported as a base class there), but I'm happy to discuss restructuring all these namespaces as I've mentioned before.

@lochhh Let me know your thoughts on this, they are very helpful.

In my mind, api contains the end-user-facing functions (e.g. for achieving what is in this notebook) - a casual user is not expected to create a Reader but rather access this through an existing Device, whereas core/base is dev-facing (e.g. devs can build on Readers, add Devices, etc.). But this is getting out of scope for the current PR, which is good to go!

Originally posted by @lochhh in #60 (comment)

Proposal

Introduce base.py or core.py (similar to #44) , i.e. the Reader class would remain in reader.py, Reader subclasses in core.py

[glopesdev]

@lochhh now that we finished the type hints and docs, we probably should come back to this discussion. I started #65 to refactor the name of an argument which I think is misleading, but we could go further and consider this change as well.

In my mind, api contains the end-user-facing functions (e.g. for achieving what is in this notebook) - a casual user is not expected to create a Reader but rather access this through an existing Device

The Reader abstract base class needs to be user-facing since it is a core part of the io package (the load function requires it). Even if we don't need people to implement them, they still need to understand what it is to understand the signature of load.

Therefore I still feel it is a good thing for them to show up together in the docs, and to keep them both in api.py. I would be open to rename this package as core.py since it defines all the core architecture types of aeon.io, or we could also make it a private module entirely.

whereas core/base is dev-facing (e.g. devs can build on Readers, add Devices, etc.).

Maybe I am not understanding what you mean here by "user-facing" and "dev-facing". In my mind all of aeon_api is about defining a set of core contracts and reusable building blocks to analyse and combine data.

I consider the implementations in reader.py to be the set of common reusable building blocks, but in principle all of them could be entirely ignored and remade from scratch, e.g. to work with formats other than what we use for Aeon. Because of this, I hesitate to rename this module as core.py since I don't see it as really being part of the "core" of the aeon.io namespace.

The core part in my head are the essential contracts defining the core functions around load. The Reader class is definitely part of that core contract, but the specific implementations are not essential for this.