Merge pull request #67 from Cumulocity-IoT/feature/cascade-deletion

Generic enhancements

Author: chsou

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+* Added `reload` function to inventory object classes
+* Added `delete_tree` function to inventory object classes, implicitly using `cascade` or
+  `forceCascade` parameters depending on the use case.
+* Added `__repr__` function to relevant object classes.
+* Removed redundant `util.py` file which impeded importing.
+
 ## Version 3.1.1
 
 * Fixing project dependencies for older Python versions.

c8y_api/model/_base.py

@@ -1,8 +1,4 @@
-# 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.
+# Copyright (c) 2025 Cumulocity GmbH
 
 from __future__ import annotations
 
@@ -121,6 +117,20 @@ def _assert_id(self):
         if not self.id:
             raise ValueError("The object ID must be set to allow direct object access.")
 
+    def _repr(self, *names) -> str:
+        return ''.join([
+            type(self).__name__,
+            '(',
+            ', '.join(filter(lambda x: x is not None,
+                         [
+                             f'{n}={self.__getattribute__(n)}' if self.__getattribute__(n) else None
+                             for n in ['id', *names]
+                         ])),
+            ')'])
+
+    def __repr__(self) -> str:
+        return self._repr()
+
     @classmethod
     def _to_datetime(cls, timestring):
         if timestring:
@@ -338,12 +348,12 @@ def _update(self) -> Any[SimpleObject]:
         result.c8y = self.c8y
         return result
 
-    def _delete(self):
+    def _delete(self, **params):
         self._assert_c8y()
         self._assert_id()
-        self.c8y.delete(self._build_object_path())
+        self.c8y.delete(self._build_object_path(), params=params)
 
-    def delete(self):
+    def delete(self, **_):
         """Delete the object within the database."""
         self._delete()
 

c8y_api/model/_util.py

@@ -1,11 +1,9 @@
-# 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.
+# Copyright (c) 2025 Cumulocity GmbH
 
 import re
 from datetime import datetime, timedelta, timezone
+from typing import Union
+
 from dateutil import parser
 from re import sub
 
@@ -14,6 +12,14 @@ class _StringUtil(object):
 
     TO_PASCAL_PATTERN = re.compile(r'_([a-z])')
 
+    @staticmethod
+    def concat(*strings:Union[str, None]):
+        return ''.join(x for x in strings if x)
+
+    @staticmethod
+    def concat_with(sep: str, *strings:Union[str, None]):
+        return sep.join(x for x in strings if x)
+
     @staticmethod
     def to_pascal_case(name: str):
         """Convert a given snake case (default Python style) name to pascal case (default for names in Cumulocity)"""

c8y_api/model/administration.py

@@ -147,6 +147,9 @@ def __init__(self, c8y: CumulocityRestApi = None, name: str = None, description:
     name = SimpleObject.UpdatableProperty('_u_name')
     description = SimpleObject.UpdatableProperty('_u_description')
 
+    def __repr__(self):
+        return self._repr('name')
+
     @classmethod
     def from_json(cls, json: dict) -> InventoryRole:
         # no doc change required
@@ -257,6 +260,9 @@ def __init__(self, c8y=None, name=None, description=None):
     name = SimpleObject.UpdatableProperty('_u_name')
     description = SimpleObject.UpdatableProperty('_u_description')
 
+    def __repr__(self):
+        return self._repr('name')
+
     @classmethod
     def from_json(cls, json: dict) -> GlobalRole:
         # no doc change
@@ -550,6 +556,9 @@ def __init__(self, c8y=None, username=None, email=None, enabled=True, display_na
         # self.effective_permission_ids = set()
         # self.custom_properties = WithUpdatableFragments()
 
+    def __repr__(self):
+        return self._repr('username')
+
     @classmethod
     def from_json(cls, json: dict) -> User:
         user = cls._from_json(json, User())

c8y_api/model/alarms.py

@@ -128,6 +128,9 @@ def first_occurrence_datetime(self) -> datetime:
         """
         return super()._to_datetime(self.first_occurrence_time)
 
+    def __repr__(self):
+        return self._repr('source', 'type', 'status', 'severity')
+
     @classmethod
     def from_json(cls, json: dict) -> Alarm:
         """Build a new Alarm instance from JSON.

c8y_api/model/binaries.py

@@ -32,6 +32,9 @@ def content_type(self) -> str:
         """Content type set for this binary."""
         return self.contentType
 
+    def __repr__(self):
+        return self._repr('name', 'type')
+
     @classmethod
     def from_json(cls, json: dict) -> Binary:
         """ Build a new Binary instance from JSON.

c8y_api/model/events.py

@@ -94,6 +94,9 @@ def updated_datetime(self) -> datetime:
     def _build_attachment_path(self) -> str:
         return super()._build_object_path() + '/binaries'
 
+    def __repr__(self):
+        return self._repr('source', 'type')
+
     @classmethod
     def from_json(cls, json: dict) -> Event:
         # (no doc update required)

c8y_api/model/identity.py

@@ -49,6 +49,9 @@ def __init__(self, c8y: CumulocityRestApi = None, external_id: str = None, exter
         self.external_type = external_type
         self.managed_object_id = managed_object_id
 
+    def __repr__(self):
+        return self._repr('external_type', 'external_id', 'managed_object_id')
+
     @classmethod
     def from_json(cls, json: dict) -> ExternalId:
         """ Build a new ExternalId instance from JSON.

c8y_api/model/inventory.py

@@ -1,8 +1,4 @@
-# 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.
+# Copyright (c) 2025 Cumulocity GmbH
 # pylint: disable=too-many-lines
 
 from __future__ import annotations
@@ -966,7 +962,7 @@ def delete_trees(self, *groups: DeviceGroup | str):
         Args:
             *groups (str|DeviceGroup):  Collection of objects (or ID).
         """
-        self._delete(False, *groups)
+        self._delete(True, *groups)
 
     def _delete(self, cascade: bool, *objects: DeviceGroup | str):
         try:

c8y_api/model/managedobjects.py

@@ -1,3 +1,5 @@
+# Copyright (c) 2025 Cumulocity GmbH
+
 from __future__ import annotations
 
 from datetime import datetime
@@ -7,7 +9,7 @@
 from c8y_api.model.administration import User, Users
 from c8y_api.model._base import _DictWrapper, SimpleObject, ComplexObject
 from c8y_api.model._parser import ComplexObjectParser
-from c8y_api.model._util import _DateUtil
+from c8y_api.model._util import _DateUtil, _StringUtil
 
 
 class NamedObject(object):
@@ -316,6 +318,9 @@ def update_datetime(self):
         """
         return super()._to_datetime(self.update_time)
 
+    def __repr__(self):
+        return self._repr('name', 'type')
+
     @classmethod
     def _from_json(cls, json: dict, obj: Any) -> Any:
         # pylint: disable=arguments-differ
@@ -365,6 +370,22 @@ def to_json(self, only_updated=False) -> dict:
     def _parse_references(cls, base_json):
         return [NamedObject.from_json(j['managedObject']) for j in base_json['references']]
 
+    def _reload(self, new_object):
+        self._assert_c8y()
+        self._assert_id()
+        result = self._from_json(self.c8y.get(self._build_object_path()), new_object)
+        result.c8y = self.c8y
+        return result
+
+    def reload(self) -> ManagedObject:
+        """Reload this object's data from database.
+
+        Returns:
+            New ManagedObject instance built from latest data.
+        """
+        return self._reload(ManagedObject())
+
+
     def create(self) -> ManagedObject:
         """ Create a new representation of this object within the database.
 
@@ -415,12 +436,26 @@ def apply_to(self, other_id: str | int) -> ManagedObject:
     def delete(self):
         """ Delete this object within the database.
 
-        The database ID must be defined for this to function.
+        Note: child additions, assets (and devices) are not implicitly
+        deleted. The database ID must be defined for this to function.
 
         See also function Inventory.delete to delete multiple objects.
         """
         self._delete()
 
+    def delete_tree(self):
+        """Delete this managed object within the database including child.
+        additions, devices and assets.
+        This is equivalent to using the `forceCascade` parameter of the
+        Cumulocity REST API.
+
+        The database ID must be defined for this to function.
+
+        See also function DeviceInventory.delete_trees to delete multiple objects.
+        """
+        self._delete(forceCascade='true')
+
+
     def add_child_asset(self, child: ManagedObject | str | int):
         """ Link a child asset to this managed object.
 
@@ -601,6 +636,49 @@ def get_user(self) -> User:
         """
         return Users(self.c8y).get(self.get_username())
 
+    def reload(self) -> Device:
+        """Reload this object's data from database.
+
+        Returns:
+            New Device instance built from latest data.
+        """
+        return self._reload(Device())
+
+    def delete(self, with_device_user=False):
+        """Delete this device object within the database.
+
+        Note: child additions, assets (and devices) are not implicitly
+        deleted. The database ID must be defined for this to function.
+
+        Args:
+            with_device_user (bool):  Whether the device user is deleted
+                as well.
+
+        See also function DeviceInventory.delete to delete multiple objects.
+        """
+        if with_device_user:
+            self._delete(withDeviceUser='true')
+        else:
+            self._delete()
+
+    def delete_tree(self, with_device_user=False):
+        """Delete this device object within the database including child.
+        additions, devices and assets.
+
+        The database ID must be defined for this to function.
+
+        Args:
+            with_device_user (bool):  Whether the device user is deleted
+                as well.
+
+        See also function DeviceInventory.delete to delete multiple objects.
+        """
+        if with_device_user:
+            self._delete(cascade='true', withDeviceUser='true')
+        else:
+            self._delete(cascade='true')
+
+
 
 class DeviceGroup(ManagedObject):
     """ Represent a device group within Cumulocity.
@@ -663,6 +741,14 @@ def from_json(cls, json: dict) -> DeviceGroup:
         """
         return super()._from_json(json, DeviceGroup())
 
+    def reload(self) -> DeviceGroup:
+        """Reload this object's data from database.
+
+        Returns:
+            New DeviceGroup instance built from latest data.
+        """
+        return self._reload(DeviceGroup())
+
     def create_child(self, name: str, owner: str = None, **kwargs) -> DeviceGroup:
         """ Create and assign a child group.
 
@@ -715,19 +801,15 @@ def delete(self):
         equivalent to using the `cascade=false` parameter in the
         Cumulocity REST API.
         """
-        self._assert_c8y()
-        self._assert_id()
-        self.c8y.delete(self._build_object_path() + '?cascade=false')
+        self._delete(cascade='false')
 
     def delete_tree(self):
         """Delete this device group and its children.
 
         This is equivalent to using the `cascade=true` parameter in the
         Cumulocity REST API.
         """
-        self._assert_c8y()
-        self._assert_id()
-        self.c8y.delete(self._build_object_path() + '?cascade=true')
+        self._delete(cascade='true')
 
     def assign_child_group(self, child: DeviceGroup | str | int):
         """Link a child group to this device group.