Reached feature parity with HTTP API

README.md

@@ -36,12 +36,12 @@ Further details on the input and output of each function (usually JSON) can be f
 ## What works
 
 - [x] Authentication
-- [ ] Objects
+- [x] Objects
     - [x] Reading a list of all objects
     - [x] Getting the current object version
     - [x] Reading an object version
-    - [ ] Creating a new object
-    - [ ] Updating an object / Creating a new object version
+    - [x] Creating a new object
+    - [x] Updating an object / Creating a new object version
 - [x] Object permissions
     - [x] Reading whether an object is public
     - [x] Setting whether an object is public
@@ -57,7 +57,7 @@ Further details on the input and output of each function (usually JSON) can be f
 - [x] Instruments
     - [x] Reading a list of all instruments
     - [x] Reading an instrument
-- [ ] Instrument log entries
+- [x] Instrument log entries
     - [x] Reading a list of all log entries for an instrument
     - [x] Reading an instrument log entry
     - [x] Reading a list of all log categories for an instrument
@@ -66,7 +66,7 @@ Further details on the input and output of each function (usually JSON) can be f
     - [x] Reading a file attachment for a log entry
     - [x] Reading a list of all object attachments for a log entry
     - [x] Reading an object attachment for a log entry
-    - [ ] Creating an instrument log entry
+    - [x] Creating an instrument log entry
 - [x] Actions
     - [x] Reading a list of all actions
     - [x] Reading an action

doc/conf.py

@@ -42,6 +42,7 @@ release = version
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

doc/sampledbapi.files.rst

-sampledbapi.files module
-========================
-
-.. automodule:: sampledbapi.files
-   :members:
-   :undoc-members:
-   :show-inheritance:
-   :private-members:

sampledbapi/instruments.py

+import base64
+import os
 from typing import Dict, List
 
-from sampledbapi import getData
+from requests import Response
+
+from sampledbapi import getData, postData
 
 __all__ = ["getList", "get", "getLogEntryList", "getLogEntry",
            "getLogCategoryList", "getLogCategory",
            "getFileAttachmentList", "getFileAttachment",
-           "getObjectAttachmentList", "getObjectAttachment"]
+           "getObjectAttachmentList", "getObjectAttachment", "createLogEntry"]
 
 
 def getList() -> List:
@@ -93,3 +97,44 @@ def getObjectAttachment(instrument_id: int, log_entry_id: int, object_attachment
             instrument_id, log_entry_id, object_attachment_id))
     else:
         raise TypeError()
+
+
+def createLogEntry(instrument_id: int, content: str, category_ids: List = [],
+                   file_attachments: List = [],
+                   object_attachments: List = []) -> Response:
+    """Create a log entry for an instrument (instrument_id) and optionally attach files and objects to it.
+    
+    Args:
+        instrument_id (int): Instrument ID for which the log entry is created.
+        content (str): Log message.
+        category_ids (list of ints): An optional list of category IDs for the log entry.
+        file_attachments (list of strings): List of file paths to be read and attached to the log entry.
+        object_attachments (list of integers): Object IDs to be attached to the log entry.
+
+    Returns:
+        HTTPResponse: The HTTP response.
+    """
+    if (isinstance(instrument_id, int) and isinstance(content, str) and
+            isinstance(category_ids, list) and
+            isinstance(file_attachments, list) and
+            isinstance(object_attachments, list)):
+        data = {"content": content}
+
+        def conv_file(path: str):
+            with open(path, "rb") as f:
+                base64encoded = base64.b64encode(f.read())
+            return {"file_name": os.path.basename(path),
+                    "base64_content": base64encoded.decode()}
+
+        if len(category_ids) > 0:
+            data["category_ids"] = category_ids
+        if len(file_attachments) > 0:
+            data["file_attachments"] = [conv_file(f) for f in file_attachments]
+        if len(object_attachments) > 0:
+            data["object_attachments"] = [
+                {"object_id": i} for i in object_attachments]
+
+        return postData(
+            "instruments/{}/log_entries/".format(instrument_id), data)
+    else:
+        raise TypeError()

sampledbapi/objects.py

@@ -47,7 +47,17 @@ def getVersion(object_id: int, version_id: int) -> Dict:
 
 
 def create(action_id: int, data: dict) -> Response:
-    """Create a new object."""
+    """Create a new object.
+
+    The data is a dictionary that has to be formatted according to the action's
+    schema. Exemplary data:
+    ```
+    {"name": {
+        "_type": "text",
+        "text": "Example Object"
+    }}
+    ```
+    """
     if isinstance(action_id, int) and isinstance(data, dict):
         return postData("objects/", {"action_id": action_id, "data": data})
     else:
@@ -55,7 +65,16 @@ def create(action_id: int, data: dict) -> Response:
 
 
 def update(object_id: int, data: dict) -> Response:
-    """Create a new version of an object (object_id)."""
+    """Create a new version of an object (object_id).
+
+    The data is a dictionary that has to be formatted according to the action's
+    schema. Exemplary data:
+    ```
+    {"name": {
+        "_type": "text",
+        "text": "Example Object"
+    }}
+    """
     if isinstance(object_id, int) and isinstance(data, dict):
         return postData("objects/{}/versions/".format(object_id),
                         {"data": data})
@@ -224,6 +243,9 @@ def uploadFile(object_id: int, path: str) -> Response:
     Args:
         object_id (int): ID of the object
         path (str): Path of the file to be uploaded.
+
+    Returns:
+        HTTPResponse: The HTTP response.
     """
     if isinstance(object_id, int) and isinstance(path, str):
         with open(path, "rb") as f:
@@ -240,6 +262,9 @@ def uploadFileRaw(object_id: int, name: str, file_obj: BinaryIO) -> Response:
         object_id (int): ID of the object
         name (str): Name that the file will have online.
         file_obj (BinaryIO): A binary stream that can be read to be uploaded.
+
+    Returns:
+        HTTPResponse: The HTTP response.
     """
     if (isinstance(object_id, int) and isinstance(name, str) and
             isinstance(file_obj, IOBase)):

setup.py

@@ -19,10 +19,10 @@ out = setup(
     # Versions should comply with PEP440.  For a discussion on single-sourcing
     # the version across setup.py and the project code, see
     # http://packaging.python.org/en/latest/tutorial.html#version
-    version="0.0.7",
+    version="0.1.0",
 
     description="API wrapper for SampleDB",
-    long_description=long_description,  # this is the
+    long_description=long_description,
 
     # The project's main homepage.
     url="https://zivgitlab.uni-muenster.de/ag-salinga/sampledb-api-wrapper",
@@ -40,7 +40,7 @@ out = setup(
         #   3 - Alpha
         #   4 - Beta
         #   5 - Production/Stable
-        "Development Status :: 3 - Alpha",
+        "Development Status :: 4 - Beta",
 
         # Indicate who your project is intended for
         "Intended Audience :: Science/Research",
@@ -72,9 +72,9 @@ out = setup(
     # install_requires=requirements,
 
     # Entry point (none so far)
-    entry_points={
-        "console_scripts": [
-            # "puzzlestream = puzzlestream.launch:launchPuzzlestream",
-        ]
-    },
+    # entry_points={
+    #     "console_scripts": [
+    #         "puzzlestream = puzzlestream.launch:launchPuzzlestream",
+    #     ]
+    # },
 )