Feature/improve applications handling (#31)

* Added build and sample utils.

* Enforcing sample file name as parameter;
Loading only .env, not .env-* files.

* Moved env_util to samples.

* Adding support for custom .env-* files.

* Adding microservice handling utilities.

* Completing applications implementation.

* Multipart object is now optional for post_file function.

* Using UTF-8 encoding to open env file.

* Updated changelog.

Author: chsou

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Work in progress
 
+* Improved Applications API.
+
+* Added microservice utilities for easier testing of provided samples.
+
 * Added Tenant Options API support.
 
 ## Version 1.4

c8y_api/_base_api.py

@@ -192,7 +192,7 @@ 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,
+    def post_file(self, resource: str, file: str | BinaryIO, object: dict = None,
                   accept: str = None, content_type: str = 'application/octet-stream'):
         """Generic HTTP POST wrapper.
 
@@ -217,10 +217,9 @@ def post_file(self, resource: str, file: str | BinaryIO, object: dict,
         """
 
         def perform_post(open_file):
-            files = {
-                'object': (None, json_lib.dumps(object)),
-                'file': (None, open_file, content_type or 'application/octet-stream')
-            }
+            files = {'file': (None, open_file, content_type or 'application/octet-stream')}
+            if object:
+                files['object'] = (None, json_lib.dumps(object))
             additional_headers = self._prepare_headers(accept=accept)
             return self.session.post(self.base_url + resource, files=files, headers=additional_headers)
 

c8y_api/model/applications.py

@@ -6,7 +6,7 @@
 
 from __future__ import annotations
 
-from typing import Generator, List
+from typing import Generator, List, BinaryIO
 
 from c8y_api._base_api import CumulocityRestApi
 from c8y_api.model._base import SimpleObject, CumulocityResource
@@ -22,22 +22,93 @@ class Application(SimpleObject):
     See also: https://cumulocity.com/api/#tag/Application-API
     """
     _parser = SimpleObjectParser({
-        'name': 'name',
-        'type': 'type',
-        'availability': 'availability'})
-    _resource = 'application/applications'
+        '_u_name': 'name',
+        '_u_type': 'type',
+        '_u_key': 'key',
+        '_u_availability': 'availability',
+        'owner': 'owner',
+        'manifest': 'manifest',
+        '_u_roles': 'roles',
+        '_u_required_roles': 'requiredRoles',
+        '_u_breadcrumbs': 'breadcrumbs',
+        '__u_content_security_policy': 'contentSecurityPolicy',
+        '_u_dynamic_options_url': 'dynamicOptionsUrl',
+        '__u_global_title': 'globalTitle',
+        '_u_legacy': 'legacy',
+        '_u_rightDrawer': 'rightDrawer',
+        '_u_upgrade': 'upgrade'
+    })
+    _resource = '/application/applications'
+    _accept = 'application/vnd.com.nsn.cumulocity.application+json'
+    _not_updatable = ['owner']
 
     EXTERNAL_TYPE = "EXTERNAL"
     HOSTED_TYPE = "HOSTED"
     MICROSERVICE_TYPE = "MICROSERVICE"
 
-    def __init__(self, c8y: CumulocityRestApi = None, name: str = None, type: str = None, availability: str = None,
-                 owner: str = None):
+    PRIVATE_AVAILABILITY = 'PRIVATE'
+    MARKET_AVAILABILITY = 'MARKET'
+
+    def __init__(self, c8y: CumulocityRestApi = None, name: str = None, key: str = None, type: str = None,
+                 availability: str = None, context_path: str = None, manifest: dict = None,
+                 roles: List[str] = None, required_roles: List[str] = None,
+                 breadcrumbs: bool = None, content_security_policy: str = None,
+                 dynamic_options_url: str = None, global_title: str = None,
+                 legacy: bool = None, right_drawer: bool = None, upgrade: bool = None):
+        """Create a new Application object.
+
+        Args:
+            c8y (CumulocityRestApi):  Cumulocity connection reference; needs
+                to be set for direct manipulation (create, delete)
+            name (str):  Name of the application
+            key (str):  Key to identify the application
+            type (str):  Type of the application
+            availability (str):  Application access level for tenants
+            context_path (str):  The path where the application is accessible
+            manifest (dict):  Microservice or web application manifest
+            roles (str):  List of roles provided by the application
+            required_roles (str):  List of roles required by the application
+            breadcrumbs (bool):  Whether the (web) application uses breadcrumbs
+            content_security_policy (str):  The content security policy of the application
+            dynamic_options_url (str):  A URL to a JSON object with dynamic content options
+            global_title (str):  The global title of the application
+            legacy (bool):  Whether the (web) application is of legacy type
+            right_drawer (bool): Whether the (web) application uses the
+                right hand context menu
+            upgrade (bool):  Whether the (web) application uses both Angular and AngularJS
+        """
         super().__init__(c8y=c8y)
-        self.name = name
-        self.type = type
-        self.availability = availability
-        self.owner = owner
+        self._u_name = name
+        self._u_type = type
+        self._u_key = key
+        self.owner = None
+        self._u_availability = availability
+        self._u_contextPath = context_path
+        self.manifest = manifest
+        self._u_roles = roles
+        self._u_required_roles = required_roles
+        self._u_breadcrumbs = breadcrumbs
+        self.__u_content_security_policy = content_security_policy
+        self._u_dynamic_options_url = dynamic_options_url
+        self.__u_global_title = global_title
+        self._u_legacy = legacy
+        self._u_rightDrawer = right_drawer
+        self._u_upgrade = upgrade
+
+    name = SimpleObject.UpdatableProperty('_u_name')
+    type = SimpleObject.UpdatableProperty('_u_type')
+    key = SimpleObject.UpdatableProperty('_u_key')
+    availability = SimpleObject.UpdatableProperty('_u_availability')
+    context_path = SimpleObject.UpdatableProperty('_u_contextPath')
+    roles = SimpleObject.UpdatableProperty('_u_roles')
+    required_roles = SimpleObject.UpdatableProperty('_u_required_roles')
+    breadcrumbs = SimpleObject.UpdatableProperty('_u_breadcrumbs')
+    content_security_policy = SimpleObject.UpdatableProperty('__u_content_security_policy')
+    dynamic_options_url = SimpleObject.UpdatableProperty('_u_dynamic_options_url')
+    global_title = SimpleObject.UpdatableProperty('__u_global_title')
+    legacy = SimpleObject.UpdatableProperty('_u_legacy')
+    right_drawer = SimpleObject.UpdatableProperty('_u_rightDrawer')
+    upgrade = SimpleObject.UpdatableProperty('_u_upgrade')
 
     @classmethod
     def from_json(cls, json: dict) -> Application:
@@ -46,6 +117,30 @@ def from_json(cls, json: dict) -> Application:
         obj.owner = json['owner']['tenant']['id']
         return obj
 
+    def create(self) -> Application:
+        """Create the Application within the database.
+
+        Returns:
+            A fresh Application object representing what was
+            created within the database (including the ID).
+        """
+        return super()._create()
+
+    def update(self) -> Application:
+        """Update the Application within the database.
+
+        Note: This will only send changed fields to increase performance.
+
+        Returns:
+            A fresh Application object representing what the updated
+            state within the database (including the ID).
+        """
+        return super()._update()
+
+    def delete(self):
+        """Delete the Application within the database."""
+        super()._delete()
+
 
 class Applications(CumulocityResource):
     """Provides access to the Application API.
@@ -79,7 +174,7 @@ def select(self, name: str = None, type: str = None, owner: str = None, user: st
         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 filters' specification. Filters can be
         combined (within reason).
 
         Args:
@@ -121,3 +216,14 @@ def get_all(self, name: str = None, type: str = None, owner: str = None, user: s
         return list(self.select(name=name, type=type, owner=owner, user=user,
                                 tenant=tenant, subscriber=subscriber, provided_for=provided_for,
                                 limit=limit, page_size=page_size))
+
+    def upload_attachment(self, application_id: str, file: str | BinaryIO):
+        """Upload application binary for a registered application.
+
+        Args:
+            application_id (str):  The Cumulocity object ID of the application
+            file (str|BinaryIO):  File path or file-like object to upload.
+
+         See also: https://cumulocity.com/api/#tag/Application-binaries
+         """
+        self.c8y.post_file(self.build_object_path(application_id) + '/binaries', file=file)

samples/build.sh

@@ -1,3 +1,8 @@
+# Copyright (c) 2020 Software AG,
+# Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA,
+# and/or its subsidiaries and/or its affiliates and/or their licensors.
+# Use, reproduction, transfer, publication or disclosure is prohibited except
+# as specifically provided for in your License Agreement with Software AG.
 
 NAME="$1"
 VERSION="$2"
@@ -34,9 +39,17 @@ cp "./samples/$NAME.py" "$BUILD_DIR"
 cp -r "./c8y_api" "$BUILD_DIR"
 sed -e "s/{VERSION}/$VERSION/g" ./samples/cumulocity.json > "$BUILD_DIR/cumulocity.json"
 sed -e "s/{SAMPLE}/$NAME/g" ./samples/Dockerfile > "$BUILD_DIR/Dockerfile"
+# extend cumulocity.json is defined
+if [[ -r ./samples/cumulocity-$NAME.json ]]; then
+  echo -n "Found custom extension at './samples/cumulocity-$NAME.json'. Applying ..."
+  tmp=`tempfile`
+  jq -s '.[0] + .[1]' "$BUILD_DIR/cumulocity.json" ./samples/cumulocity-$NAME.json > $tmp
+  mv $tmp "$BUILD_DIR/cumulocity.json"
+  echo "  Done."
+fi
 
 # build image
-
+echo "Building image ..."
 docker build -t "$NAME" "$BUILD_DIR"
 docker save -o "$DIST_DIR/image.tar" "$NAME"
 zip -j "$DIST_DIR/$IMG_NAME.zip" "$BUILD_DIR/cumulocity.json" "$DIST_DIR/image.tar"

samples/util.py

@@ -0,0 +1,33 @@
+# Copyright (c) 2020 Software AG,
+# Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA,
+# and/or its subsidiaries and/or its affiliates and/or their licensors.
+# Use, reproduction, transfer, publication or disclosure is prohibited except
+# as specifically provided for in your License Agreement with Software AG.
+
+from __future__ import annotations
+
+import inspect
+import os
+
+import dotenv
+
+
+def load_dotenv(sample_name: str | None = None):
+    """Load environment variables from .env files.
+
+    This function will look for two files within the working directory:
+    A general `.env` file and a sample specific .env-{sample_name} file
+    which has higher priority.
+    """
+    # load general .env
+    dotenv.load_dotenv()
+    # check and load sample .env
+    if not sample_name:
+        caller_file = inspect.stack()[1].filename
+        sample_name = os.path.splitext(os.path.split(caller_file)[1])[0]
+
+    sample_env = f'.env-{sample_name}'
+    if os.path.exists(sample_env):
+        print(f"Found custom .env extension: {sample_env}")
+        with open(sample_env, 'r', encoding='UTF-8') as f:
+            dotenv.load_dotenv(stream=f)

tasks.py

@@ -7,6 +7,8 @@
 from invoke import task
 from setuptools_scm import get_version
 
+import util.microservice_util as ms_util
+
 
 @task
 def show_version(_):
@@ -43,13 +45,53 @@ def build(c):
     "version": "Microservice version. Defaults to '1.0.0'.",
 })
 def build_ms(c, sample, version='1.0.0'):
-    """Build a Cumulocity micro service.
+    """Build a Cumulocity microservice binary for upload.
 
-    This will build a ready to deploy Cumulocity micro service from a sample
+    This will build a ready to deploy Cumulocity microservice from a sample
     file within the `samples` folder. Any sample Python script can be used
-    (if it implements micro service logic).
+    (if it implements microservice logic).
 
     Use the file name without .py extension as name. The build microservice
     will use a similar name, following Cumulocity naming guidelines.
     """
-    c.run(f'samples/build.sh {sample} {version}')
+    sample_name = ms_util.format_sample_name(sample)
+    c.run(f'samples/build.sh {sample_name} {version}')
+
+
+@task(help={
+    'sample': "Which sample to register."
+})
+def register_ms(c, sample):
+    """Register a sample as microservice at Cumulocity."""
+    ms_util.register_microservice(ms_util.format_sample_name(sample))
+
+
+@task(help={
+    'sample': "Which sample to unregister."
+})
+def unregister_ms(c, sample):
+    """Unregister a sample microservice from Cumulocity."""
+    ms_util.unregister_microservice(ms_util.format_sample_name(sample))
+
+
+@task(help={
+    'sample': "Which sample to register."
+})
+def get_credentials(c, sample):
+    """Unregister a sample microservice from Cumulocity."""
+    user, password = ms_util.get_credentials(ms_util.format_sample_name(sample))
+    print(f"Username:  {user}\n"
+          f"Password:  {password}")
+
+
+@task(help={
+    'sample': "Which sample to create a .env file for."
+})
+def create_env(c, sample):
+    """Create a sample specific .env-{sample_name} file using the
+    credentials of a corresponding microservice registered at Cumulocity."""
+    sample_name = ms_util.format_sample_name(sample)
+    user, password = ms_util.get_credentials(sample_name)
+    with open(f'.env-{sample_name}', 'w') as f:
+        f.write(f"C8Y_USER={user}\n"
+                f"C8Y_PASSWORD={password}\n")