Add backend interface

[frankenjoe]

Closes #155

Introduces the concept of an interface as an intermediate layer between the user and the backend. For instance, the default interface audbackend.interface.Versioned takes as input /sub/file.ext and version and converts it to /path/version/file.ext. Whereas the interface audbackend.interface.Unversioned does not take an additional version parameter and stores a file directly under /sub/file.txt. It will also offer a more elegant solution for the issue the old file structure if we introduce another interface, e.g. VersionedLegacy (not done in this PR).

Documentation

The documentation is extended accordingly:

And the usage section has a new section "Backend interface":

Tests

The test file tests/test_backend.py is now further split into tests/test_versioned.py and tests/test_unversioned.py. Since we now test with both interfaces (Unversioned and Versioned), we have twice as many tests that involve Artifactory. To shorten the time it takes to execute the tests we could think about testing only one of the interface with Artifactory.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (a64eba6) 100.0% compared to head (ec65725) 100.0%.

Additional details and impacted files

Files	Coverage Δ
audbackend/__init__.py	100.0% <100.0%> (ø)
audbackend/core/api.py	100.0% <100.0%> (ø)
audbackend/core/backend.py	100.0% <100.0%> (ø)
audbackend/core/conftest.py	100.0% <100.0%> (ø)
audbackend/core/errors.py	100.0% <ø> (ø)
audbackend/core/interface/base.py	100.0% <100.0%> (ø)
audbackend/core/interface/unversioned.py	100.0% <100.0%> (ø)
audbackend/core/interface/versioned.py	100.0% <100.0%> (ø)
audbackend/interface/__init__.py	100.0% <100.0%> (ø)

[hagenw]

Before I start reviewing in detail a few remarks/questions:

• The interface layer seems elegant, but as a user I'm totally lost at the moment in the API documentation as I have no clue were to look what I can do with a backend. In general, it might even better with the interfaces as the I don't have to care about the specific backend, but can just look at the documentation for the Versioned interafce. But I guess we need to point this out to a user. One solution might be to hide all methods in the audbackend.Backend, audbackend.FileSystem, ... classes and add a link to the interafce documentation instead.
• As a developer I also feel slightly lost, as the interface classes seem to implement again all the methods from backend. This feels especially strange for Unversioned as I guess this is the default behavior of audbackend.Backend anyway?
• Regarding the tests it should be sufficient to test the interfaces only on a single backend, e.g. FileSystem as they should be independent of the backend (otherwise we would have to add more interafce tests when adding a new backend, which feels strange to me).

[frankenjoe]

One solution might be to hide all methods in the audbackend.Backend, audbackend.FileSystem, ... classes and add a link to the interafce documentation instead.

Yes, I was thinking the same. But maybe we do it in a separate PR?

As a developer I also feel slightly lost, as the interface classes seem to implement again all the methods from backend.

Not necessarily, e.g. Versioned adds the version argument and also new methods like versions().

This feels especially strange for Unversioned as I guess this is the default behavior of audbackend.Backend anyway?

Yes, that is true, in principle we could directly return the Backend object instead of the Unversioned interface. But to me it feels cleaner to always return an interface and not sometimes a backend.

[frankenjoe]

• Regarding the tests it should be sufficient to test the interfaces only on a single backend, e.g. FileSystem as they should be independent of the backend (otherwise we would have to add more interafce tests when adding a new backend, which feels strange to me).

done

[frankenjoe]

One more thought: to make it easier for a developer to distinguish between backend and interface, I suggest we create a follow-up PR where we move Backend, Artifactory, and FileSystem to backend.Base, backend.Artifactory and backend.FileSystem (for legacy reasons we also keep the old import paths, but do not mention them in the documentation).

[hagenw]

I think it would be easier to grasp if you rename the following tests functions:

• test_backend.py -> test_backend_base.py
• test_artifactory.py -> test_backend_artifactory.py
• test_filesystem.py -> test_backend_filesystem.py
• test_unversioned.py -> test_interface_unversioned.py
• test_versioned.py -> test_interface_versioned.py

[frankenjoe]

I think it would be easier to grasp if you rename the following tests functions:

Good idea. Done.

[hagenw]

I created #168 to track the VersionedLegacy interface mentioned in the description of this pull request.

[hagenw]

One solution might be to hide all methods in the audbackend.Backend, audbackend.FileSystem, ... classes and add a link to the interafce documentation instead.

Yes, I was thinking the same. But maybe we do it in a separate PR?

I created #169 to track this.

[hagenw]

One more thought: to make it easier for a developer to distinguish between backend and interface, I suggest we create a follow-up PR where we move Backend, Artifactory, and FileSystem to backend.Base, backend.Artifactory and backend.FileSystem (for legacy reasons we also keep the old import paths, but do not mention them in the documentation).

I created #170 to track this.