File upload helper

.gitlab-ci.yml

@@ -8,7 +8,7 @@ client-tests:
 
   script:
   - pip install .[test]
-  # - pytest
+  - pytest
   - flake8
 
 client-schema-validation:

README.rst

@@ -83,6 +83,22 @@ your API client:
 
    cli = ArkindexClient(base_url='https://somewhere')
 
+Uploading a file
+^^^^^^^^^^^^^^^^
+
+The underlying API client we use does not currently handle sending anything
+other than JSON; therefore, the client adds a helper method to upload files
+to a corpus using the ``UploadDataFile`` endpoint: ``ArkindexClient.upload``.
+
+.. code:: python
+
+   # Any readable file-like object is supported
+   with open('cat.jpg', 'rb') as f:
+       cli.upload('CORPUS_ID', f)
+
+   # You can also use a path directly
+   cli.upload('CORPUS_ID', 'cat.jpg')
+
 Examples
 --------
 

arkindex/client.py

@@ -58,3 +58,37 @@ class ArkindexClient(apistar.Client):
         if 'auth_token' in resp:
             self.transport.session.auth.token = resp['auth_token']
         return resp
+
+    def upload(self, corpus_id, f, mode='rb'):
+        """
+        Upload a file-like object or a file path to a corpus.
+        This helper is required as APIStar does not currently handle
+        anything else than JSON as request parameters.
+
+        :param str corpus_id: ID of a writable corpus to upload files to.
+        :param f: File-like object, or path to a readable file, to upload.
+        :type f: str or file-like object
+        :param str mode: When specifying a path, sets the mode to use when
+           opening the file.
+        :return: The JSON response from the endpoint
+        :rtype: dict
+        """
+        if isinstance(f, str):
+            assert os.path.exists(f), 'File {} does not exist'.format(f)
+            f = open(f, mode)
+
+        params = {'id': corpus_id}
+        content = {'file': f}
+        encoding = apistar.client.encoders.MultiPartEncoder.media_type
+
+        link = self.lookup_operation('UploadDataFile')
+        url = self.get_url(link, params)
+        query_params = self.get_query_params(link, params)
+
+        return self.transport.send(
+            link.method,
+            url,
+            query_params=query_params,
+            content=content,
+            encoding=encoding,
+        )

arkindex/tests/test_upload.py

+import json
+import responses
+from arkindex import ArkindexClient
+from io import BytesIO
+
+
+@responses.activate
+def test_upload():
+
+    def callback(request):
+        assert request.method == 'POST'
+        assert request.headers['Referer'] == 'https://dummy.test'
+        assert request.headers['Content-Type'].startswith('multipart/form-data')
+
+        # Ignore form-data boundary lines
+        lines = request.body.splitlines()[1:-1]
+        assert lines == [
+            b'Content-Disposition: form-data; name="file"; filename="text.txt"',
+            b'',
+            b'something',
+        ]
+
+        return 201, {}, json.dumps({'id': 'file-id'})
+
+    responses.add_callback(
+        responses.POST,
+        'https://dummy.test/api/v1/imports/upload/corpus-id/',
+        callback=callback,
+        content_type='application/json',
+    )
+
+    cli = ArkindexClient('t0k3n', base_url='https://dummy.test')
+    content = BytesIO(b'something')
+    content.name = 'text.txt'
+    assert cli.upload('corpus-id', content) == {'id': 'file-id'}

requirements-tests.txt

-pytest>=3.6.2
-responses>=0.9.0
-flake8>=3.5.0
+pytest>=4.4.0
+responses>=0.10.0
+flake8>=3.7.0