Feature/event attachments (#37)

* Default content type for file attachments is now set in the code; Minor documentation fixes.
* Adding support for event attachments; Minor documentation fixes.
* Added event handling sample.
* Fix username determination from HTTPBasicAuth.
* Added integration tests for event attachment handling.
* Added event attachment handling to the Events API.
* Update CHANGELOG.md

Author: chsou

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+* Added support for event attachment handling.
+
 * Adding support for bulk operations.
 
 ## Version 1.6.1
@@ -8,7 +10,7 @@
 
 ## Version 1.6
 
-*  Added API support for Notification 2.0 subscriptions and tokens.
+* Added API support for Notification 2.0 subscriptions and tokens.
 
 * Added new package c8y_tk for additional features.
 

c8y_api/_base_api.py

@@ -43,7 +43,7 @@ def __init__(self, base_url: str, tenant_id: str, username: str = None, password
             tenant_id (str):  The ID of the tenant to connect to
             username (str):  Username
             password (str):  User password
-            tfa_token (str):  Currently valid two factor authorization token
+            tfa_token (str):  Currently valid two-factor authorization token
             auth (AuthBase):  Authentication details
             application_key (str):  Application ID to include in requests
                 (for billing/metering purposes).
@@ -83,7 +83,7 @@ def prepare_request(self, method: str, resource: str,
         Args:
             method (str):  One of 'GET', 'POST', 'PUT', 'DELETE'
             resource (str):  Path to the HTTP resource
-            json (dict):  JSON body (nested dict) to send witht he request
+            json (dict):  JSON body (nested dict) to send with the request
             additional_headers (dict):  Additional non-standard headers to
                 include in the request
 
@@ -106,7 +106,7 @@ def get(self, resource: str, params: dict = None, accept: str = None, ordered: b
             resource (str): Resource path
             params (dict): Additional request parameters
             accept (str|None): Custom Accept header to use (default is
-                application/json). Specify '' to sent no Accept header.
+                application/json). Specify '' to send no Accept header.
             ordered (bool): Whether the result JSON needs to be ordered
                 (default is False)
 
@@ -166,7 +166,7 @@ def post(self, resource: str, json: dict, accept: str = None, content_type: str
             resource (str): Resource path
             json (dict): JSON body (nested dict)
             accept (str|None): Custom Accept header to use (default is
-                application/json). Specify '' to sent no Accept header.
+                application/json). Specify '' to send no Accept header.
             content_type (str|None): Custom Content-Type header to use
                 (default is application/json)
 
@@ -192,8 +192,8 @@ def post(self, resource: str, json: dict, accept: str = None, content_type: str
             return r.json()
         return {}
 
-    def post_file(self, resource: str, file: str | BinaryIO, object: dict = None,
-                  accept: str = None, content_type: str = 'application/octet-stream'):
+    def post_file(self, resource: str, file: str | BinaryIO, object: dict = None,  # noqa (object)
+                  accept: str = None, content_type: str = None):
         """Generic HTTP POST wrapper.
 
         Used for posting binary data, i.e. creating binary objects in Cumulocity.
@@ -203,7 +203,7 @@ def post_file(self, resource: str, file: str | BinaryIO, object: dict = None,
             file (str|BinaryIO):  File-like object or a file path
             object (dict):  File metadata, stored within Cumulocity
             accept (str|None): Custom Accept header to use (default is
-                application/json). Specify '' to sent no Accept header.
+                application/json). Specify '' to send no Accept header.
             content_type (str): Content type of the file sent
                 (default is application/octet-stream)
 
@@ -247,7 +247,7 @@ def put(self, resource: str, json: dict, params: dict = None,
             json (dict): JSON body (nested dict)
             params (dict): Additional request parameters
             accept (str|None): Custom Accept header to use (default is
-                application/json). Specify '' to sent no Accept header.
+                application/json). Specify '' to send no Accept header.
             content_type (str|None): Custom Content-Type header to use
                 (default is application/json)
 
@@ -274,7 +274,7 @@ def put(self, resource: str, json: dict, params: dict = None,
         return {}
 
     def put_file(self, resource: str, file: str | BinaryIO,
-                 accept: str = None, content_type: str = 'application/octet-stream'):
+                 accept: str = None, content_type: str = None):
         """Generic HTTP PUT wrapper.
 
         Used for put'ing binary data, i.e. updating binaries in Cumulocity.
@@ -283,7 +283,7 @@ def put_file(self, resource: str, file: str | BinaryIO,
             resource (str): Resource path
             file (str|BinaryIO):  File-like object or a file path
             accept (str|None): Custom Accept header to use (default is
-                application/json). Specify '' to sent no Accept header.
+                application/json). Specify '' to send no Accept header.
             content_type (str): Content type of the file sent
                 (default is application/octet-stream)
 
@@ -357,7 +357,8 @@ def _resolve_username_from_auth(cls, auth: AuthBase):
         and the username resolved from the payload.
         """
         if isinstance(auth, HTTPBasicAuth):
-            return auth.username
+            # the username may contain the tenant ID (<tenant ID>/<username>)
+            return auth.username.split('/')[-1]
         if isinstance(auth, HTTPBearerAuth):
             return JWT(auth.token).username
         raise ValueError(f"Unexpected AuthBase instance: {auth.__class__}. Unable to resolve username.")

c8y_api/model/events.py

@@ -10,7 +10,7 @@
 from __future__ import annotations
 
 from datetime import datetime, timedelta
-from typing import Generator, List
+from typing import Generator, List, BinaryIO
 
 from c8y_api._base_api import CumulocityRestApi
 from c8y_api.model._base import CumulocityResource, SimpleObject, ComplexObject
@@ -28,7 +28,7 @@ class Event(ComplexObject):
     """
 
     _resource = '/event/events'
-    # _accept can remain default
+    _accept = 'application/vnd.com.nsn.cumulocity.event+json'
     _parser = ComplexObjectParser({
         'type': 'type',
         'time': 'time',
@@ -37,8 +37,8 @@ class Event(ComplexObject):
         'updated_time': 'lastUpdated',
         }, ['source'])
 
-    def __init__(self, c8y: CumulocityRestApi = None, type: str = None, time: str | datetime = None,
-                 source: str = None, text: str = None, **kwargs):  # noqa (type)
+    def __init__(self, c8y: CumulocityRestApi = None, type: str = None, time: str | datetime = None,  # noqa (type)
+                 source: str = None, text: str = None, **kwargs):
         """Create a new Event object.
 
         Args:
@@ -91,6 +91,9 @@ def updated_datetime(self) -> datetime:
         """
         return super()._to_datetime(self.updated_time)
 
+    def _build_attachment_path(self) -> str:
+        return super()._build_object_path() + '/binaries'
+
     @classmethod
     def from_json(cls, json: dict) -> Event:
         # (no doc update required)
@@ -146,6 +149,69 @@ def apply_to(self, other_id: str) -> Event:
         """
         return super()._apply_to(other_id)
 
+    def has_attachment(self) -> bool:
+        """Check whether the event has a binary attachment.
+
+        Event objects that have an attachment feature a `c8y_IsBinary`
+        fragment. This function checks the presence of that fragment.
+
+        Note: This does not query the database. Hence, the information might
+        be outdated if a binary was attached _after_ the event object was
+        last read from the database.
+
+        Returns:
+            True if the event object has an attachment, False otherwise.
+        """
+        return 'c8y_IsBinary' in self
+
+    def download_attachment(self) -> bytes:
+        """Read the binary attachment.
+
+        Returns:
+            The event's binary attachment as bytes.
+        """
+        super()._assert_c8y()
+        super()._assert_id()
+        return self.c8y.get_file(self._build_attachment_path())
+
+    def create_attachment(self, file: str|BinaryIO, content_type: str = None) -> dict:
+        """Create the binary attachment.
+
+        Args:
+            file (str|BinaryIO): File-like object or a file path
+            content_type (str):  Content type of the file sent
+                (default is application/octet-stream)
+
+        Returns:
+            Attachment details as JSON object (dict).
+        """
+        super()._assert_c8y()
+        super()._assert_id()
+        return self.c8y.post_file(self._build_attachment_path(), file,
+                                  accept='application/json', content_type=content_type)
+
+    def update_attachment(self, file: str|BinaryIO, content_type: str = None) -> dict:
+        """Update the binary attachment.
+
+        Args:
+            file (str|BinaryIO): File-like object or a file path
+            content_type (str):  Content type of the file sent
+                (default is application/octet-stream)
+
+        Returns:
+            Attachment details as JSON object (dict).
+        """
+        super()._assert_c8y()
+        super()._assert_id()
+        return self.c8y.put_file(self._build_attachment_path(), file,
+                                 accept='application/json', content_type=content_type)
+
+    def delete_attachment(self):
+        """Remove the binary attachment."""
+        super()._assert_c8y()
+        super()._assert_id()
+        self.c8y.delete(self._build_attachment_path())
+
 
 class Events(CumulocityResource):
     """Provides access to the Events API.
@@ -159,6 +225,17 @@ class Events(CumulocityResource):
     def __init__(self, c8y):
         super().__init__(c8y, '/event/events')
 
+    def build_attachment_path(self, event_id: str) -> str:
+        """Build the attachment path of a specific event.
+
+        Args:
+            event_id (int|str):  Database ID of the event
+
+        Returns:
+            The relative path to the event attachment within Cumulocity.
+        """
+        return super().build_object_path(event_id) + '/binaries'
+
     def get(self, event_id: str) -> Event:  # noqa (id)
         """Retrieve a specific object from the database.
 
@@ -184,7 +261,7 @@ def select(self, type: str = None, source: str = None, fragment: str = None,  #
         fetched from the database as long there is a consumer for them.
 
         All parameters are considered to be filters, limiting the result set
-        to objects which meet the filters specification.  Filters can be
+        to objects which meet the filter's specification.  Filters can be
         combined (within reason).
 
         Args:
@@ -286,7 +363,7 @@ def delete_by(self, type: str = None, source: str = None, fragment: str = None,
         """Query the database and delete matching events.
 
         All parameters are considered to be filters, limiting the result set
-        to objects which meet the filters specification.  Filters can be
+        to objects which meet the filter's specification.  Filters can be
         combined (within reason).
 
         Args:
@@ -306,3 +383,52 @@ def delete_by(self, type: str = None, source: str = None, fragment: str = None,
         # remove &page_number= from the end
         query = base_query[:base_query.rindex('&')]
         self.c8y.delete(query)
+
+    def create_attachment(self, event_id: str, file: str|BinaryIO, content_type: str = None) -> dict:
+        """Add an event's binary attachment.
+
+        Args:
+            event_id (str):  The database ID of the event
+            file (str|BinaryIO): File-like object or a file path
+            content_type (str):  Content type of the file sent
+                (default is application/octet-stream)
+
+        Returns:
+            Attachment details as JSON object (dict).
+        """
+        return self.c8y.post_file(self.build_attachment_path(event_id), file,
+                                  accept='application/json', content_type=content_type)
+
+    def update_attachment(self, event_id: str, file: str|BinaryIO, content_type: str = None) -> dict:
+        """Update an event's binary attachment.
+
+        Args:
+            event_id (str):  The database ID of the event
+            file (str|BinaryIO): File-like object or a file path
+            content_type (str):  Content type of the file sent
+                (default is application/octet-stream)
+
+        Returns:
+            Attachment details as JSON object (dict).
+        """
+        return self.c8y.put_file(self.build_attachment_path(event_id), file,
+                                 accept='application/json', content_type=content_type)
+
+    def download_attachment(self, event_id: str) -> bytes:
+        """Read an event's binary attachment.
+
+        Args:
+            event_id (str):  The database ID of the event
+
+        Returns:
+            The event's binary attachment as bytes.
+        """
+        return self.c8y.get_file(self.build_attachment_path(event_id))
+
+    def delete_attachment(self, event_id: str):
+        """Remove an event's binary attachment.
+
+        Args:
+            event_id (str):  The database ID of the event
+        """
+        self.c8y.delete(self.build_attachment_path(event_id))