create(): remove return value

audbackend/core/api.py

@@ -133,16 +133,12 @@ def create(
         name: str,
         host: str,
         repository: str,
-        *,
-        interface: typing.Type[Interface] = Versioned,
-        interface_kwargs: dict = None
-) -> Interface:
+ ):
     r"""Create repository.
 
     Creates ``repository`` on the ``host``
-    and returns an ``interface`` instance for it.
-    The backend is an object of the class
-    registered under the alias ``name``
+    using the class registered
+    under the alias ``name``
     with :func:`audbackend.register`.
 
     If the repository cannot be created
@@ -159,11 +155,6 @@ def create(
         name: alias under which backend class is registered
         host: host address
         repository: repository name
-        interface: interface class
-        interface_kwargs: keyword arguments for interface class
-
-    Returns:
-        interface object
 
     Raises:
         BackendError: if an error is raised on the backend,
@@ -174,13 +165,12 @@ def create(
 
     Examples:
         >>> create('file-system', 'host', 'repository')
-        audbackend.core.interface.versioned.Versioned('audbackend.core.backend.filesystem.FileSystem', 'host', 'repository')
 
     """  # noqa: E501
     backend = _backend(name, host, repository)
     utils.call_function_on_backend(backend._create)
-    interface_kwargs = interface_kwargs or {}
-    return interface(backend, **interface_kwargs)
+    # for legacy reasons we return a versioned interface
+    return Versioned(backend)
 
 
 def delete(
@@ -211,7 +201,8 @@ def delete(
         >>> access('file-system', 'host', 'repo').ls()
         [('/a.zip', '1.0.0'), ('/a/b.ext', '1.0.0'), ('/f.ext', '1.0.0'), ('/f.ext', '2.0.0')]
         >>> delete('file-system', 'host', 'repo')
-        >>> create('file-system', 'host', 'repo').ls()
+        >>> create('file-system', 'host', 'repo')
+        >>> access('file-system', 'host', 'repo').ls()
         []
 
     """  # noqa: E501

audbackend/core/conftest.py

@@ -30,6 +30,15 @@ def _owner(
         return 'doctest'
 
 
+def doctest_create(
+        name: str,
+        host: str,
+        repository: str,
+):
+    # call create without return value
+    audbackend.create(name, host, repository)
+
+
 @pytest.fixture(scope='function', autouse=True)
 def prepare_docstring_tests(doctest_namespace):
 
@@ -42,18 +51,26 @@ def prepare_docstring_tests(doctest_namespace):
         audeer.touch(file)
 
         audbackend.register('file-system', DoctestFileSystem)
+        doctest_namespace['create'] = doctest_create
 
         # backend
 
         backend = audbackend.backend.Base('host', 'repo')
         doctest_namespace['backend'] = backend
 
+        # interface
+
         interface = audbackend.interface.Base(backend)
         doctest_namespace['interface'] = interface
 
         # versioned interface
 
-        versioned = audbackend.create(
+        audbackend.create(
+            'file-system',
+            'host',
+            'repo',
+            )
+        versioned = audbackend.access(
             'file-system',
             'host',
             'repo',
@@ -68,7 +85,12 @@ def prepare_docstring_tests(doctest_namespace):
 
         # unversioned interface
 
-        unversioned = audbackend.create(
+        audbackend.create(
+            'file-system',
+            'host',
+            'repo-unversioned',
+        )
+        unversioned = audbackend.access(
             'file-system',
             'host',
             'repo-unversioned',
@@ -85,5 +107,6 @@ def prepare_docstring_tests(doctest_namespace):
         audbackend.delete('file-system', 'host', 'repo')
         audbackend.delete('file-system', 'host', 'repo-unversioned')
         audbackend.register('file-system', audbackend.backend.FileSystem)
+        doctest_namespace['create'] = audbackend.create
 
         os.chdir(current_dir)

docs/legacy.rst

@@ -50,7 +50,8 @@ you have to list those extensions explicitly.
 
     import audbackend
 
-    backend = audbackend.create('file-system', './host', 'repo')
+    audbackend.create('file-system', './host', 'repo')
+    backend = audbackend.access('file-system', './host', 'repo')
     extensions = ['tar.gz']
     backend._use_legacy_file_structure(extensions=extensions)
 

docs/usage.rst

@@ -66,10 +66,9 @@ if we do it again).
 To make sure we can keep track
 of all existing backend instances,
 we use :func:`audbackend.create`
-to instantiate a backend
+to create a repository
 instead of calling the class ourselves.
-When creating the instance
-we provide three arguments:
+We provide three arguments:
 
 * ``name``: the name under which the backend class is registered
 * ``host``: the host address,
@@ -80,8 +79,9 @@ we provide three arguments:
   on the same host).
 
 .. jupyter-execute::
+    :hide-output:
 
-    backend = audbackend.create('file-system', './host', 'repo')
+    audbackend.create('file-system', './host', 'repo')
 
 
 This will create an empty repository
@@ -94,7 +94,7 @@ we would do:
     audbackend.available()
 
 
-We can access an existing instance with:
+We can access an existing repository with:
 
 .. jupyter-execute::
 
@@ -294,7 +294,12 @@ in versioning we can use
 
 .. jupyter-execute::
 
-    backend = audbackend.create(
+    audbackend.create(
+        'file-system',
+        './host',
+        'repo',
+    )
+    backend = audbackend.access(
         'file-system',
         './host',
         'repo',
@@ -386,12 +391,13 @@ we implement the interface.
             return self.backend.ls(f'/{username}/')
 
 
-Let's create a backend
+Let's create a repository and access it
 with our custom interface:
 
 .. jupyter-execute::
 
-    backend = audbackend.create('file-system', tmp, 'repo', interface=UserContent)
+    audbackend.create('file-system', tmp, 'repo')
+    backend = audbackend.access('file-system', tmp, 'repo', interface=UserContent)
 
     backend.add_user('audeering', 'pa$$word')
     backend.upload('audeering', 'pa$$word', 'local.txt')
@@ -548,16 +554,17 @@ stored on our backend:
             db.execute(query)
 
 
-Now we create an instance.
+Now we create a repository.
 
 .. jupyter-execute::
+    :hide-output:
 
-    backend = audbackend.create('sql', 'host', 'repo')
+    audbackend.create('sql', 'host', 'repo')
 
 
 We also add a method to access
-an existing database
-(or raise an error
+an existing repository
+(or raise an error if
 it is not found).
 
 .. jupyter-execute::

tests/conftest.py

@@ -69,13 +69,19 @@ def owner(request):
 @pytest.fixture(scope='function', autouse=False)
 def interface(hosts, request):
 
-    name, interface = request.param
+    name, interface_cls = request.param
     host = hosts[name]
     repository = f'unittest-{pytest.UID}-{audeer.uid()[:8]}'
 
-    backend = audbackend.create(name, host, repository, interface=interface)
+    audbackend.create(name, host, repository)
+    interface = audbackend.access(
+        name,
+        host,
+        repository,
+        interface=interface_cls,
+    )
 
-    yield backend
+    yield interface
 
     # Deleting repositories on Artifactory might fail
     for n in range(3):

tests/test_api.py

@@ -63,7 +63,9 @@ def test_api(hosts, name, host, repository, cls):
     with pytest.raises(audbackend.BackendError, match=error_msg):
         audbackend.access(name, host, repository)
 
+    # returns versioned interface for legacy reasons
     interface = audbackend.create(name, host, repository)
+    assert isinstance(interface, audbackend.interface.Versioned)
     assert isinstance(interface.backend, cls)
 
     with pytest.raises(audbackend.BackendError, match=error_msg):