Add repositories argument to audb.available() (#489)

* Add repositories argument to audb.available()

* Fix tests

* Extend tests for all repositories

Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>

* Fix and extend tests

* Raise error for empty repositories argument

* Do not raise an error for empty argument

* Extend docstring

---------

Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>

audb/core/api.py

@@ -26,11 +26,15 @@
 def available(
     *,
     only_latest: bool = False,
+    repositories: Repository | Sequence[Repository] = None,
 ) -> pd.DataFrame:
     r"""List all databases that are available to the user.
 
     Args:
         only_latest: include only latest version of database
+        repositories: search only in the given repositories.
+            If ``None``,
+            :attr:`audb.config.REPOSITORIES` is used
 
     Returns:
         table with database name as index,
@@ -59,7 +63,12 @@ def add_database(name: str, version: str, repository: Repository):
             ]
         )
 
-    for repository in config.REPOSITORIES:
+    if repositories is not None:
+        repositories = audeer.to_list(repositories)
+    else:
+        repositories = config.REPOSITORIES
+
+    for repository in repositories:
         try:
             backend_interface = repository.create_backend_interface()
             with backend_interface.backend as backend:

tests/test_api.py

@@ -93,6 +93,57 @@ def test_default(self):
         assert "name0" in df.index
         assert "name1" in df.index
 
+    def test_repositories_all(self):
+        """Test repositories argument with all repositories."""
+        repositories = audb.config.REPOSITORIES
+        df = audb.available(repositories=repositories)
+        assert len(df) == 2
+
+        # Verify repositories
+        expected_repos = set([repo.name for repo in repositories])
+        assert set(df.repository.unique()) == expected_repos
+
+        # Verify database names
+        assert "name0" in df.index
+        assert "name1" in df.index
+
+        # Verify hosts
+        assert df.loc["name0", "host"] == repositories[0].host
+        assert df.loc["name1", "host"] == repositories[1].host
+
+    @pytest.mark.parametrize("repository_index", [0, 1])
+    @pytest.mark.parametrize("preprocess_repository", [lambda x: x, lambda x: [x]])
+    def test_repositories_single(self, repository_index, preprocess_repository):
+        """Test repositories argument with single repositories.
+
+        Args:
+            repository_index: select single repository
+                by the given index
+                from ``audb.config.REPOSITORIES``
+            preprocess_repository: apply given function
+                to single repository
+                before using as ``repositories`` argument
+
+        """
+        repository = audb.config.REPOSITORIES[repository_index]
+        df = audb.available(repositories=preprocess_repository(repository))
+        assert len(df) == 1
+
+        # Verify repository
+        assert df.repository.iloc[0] == repository.name
+
+        # Verify database name
+        assert df.index[0] == f"name{repository_index}"
+
+        # Verify host
+        assert df.host.iloc[0] == repository.host
+
+    @pytest.mark.parametrize("repositories", [[], ()])
+    def test_repositories_empty(self, repositories):
+        """Tests empty repositories argument."""
+        df = audb.available(repositories=repositories)
+        assert len(df) == 0
+
     def test_broken_database(self, repository_with_broken_database):
         """Test having a database only given as a folder."""
         df = audb.available()