Some optimizations to the as_tuples parameter; Added as_tuples to Operations, Users, AuditRecords.

Author: chisou

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+* Added `as_tuples` parameter to `get_all` and `select` functions of the Inventory, DeviceInventory,
+  DeviceGroupInventory, Events, Alarms, Users, Operations, and AuditRecords API.
 * Added code coverage reporting to `test` target for _invoke_.
 * Updated `as_tuple` for  complex objects as well as the `as_tuples` parameter for `select`
   and `get_all` functions to work with strings or 2-tuples. The use of a dictionary

c8y_api/model/_parser.py

@@ -8,12 +8,12 @@
 from c8y_api.model._util import _StringUtil
 
 
-def as_tuples(json_data, *path: str | tuple):
+def as_tuples(json_data, paths: str | tuple | list[str|tuple]):
     """Parse a JSON structure as tuples from paths.
 
     Args:
         json_data (dict):  A JSON structure as Python dict
-        path (*str|tuple):  Path(s) to extract from
+        paths (list[str|tuple]):  Path(s) to extract from
             the structure; Use dots to separate JSON levels; Arrays are not
             supported.
 
@@ -39,7 +39,9 @@ def resolve(segments, default=None):
         return json_level.get(segments[-1], json_level.get(_StringUtil.to_pascal_case(segments[-1]), default))
 
     # each p in path(s) can be a string or a tuple
-    return tuple(resolve(p[0].split('.'), p[1]) if isinstance(p, tuple) else resolve(p.split('.')) for p in path )
+    return tuple(
+        resolve(p[0].split('.'), p[1]) if isinstance(p, tuple)
+        else resolve(p.split('.')) for p in ([paths] if isinstance(paths, (str, tuple)) else paths))
 
 class SimpleObjectParser(object):
     """A parser for simple (without fragments) Cumulocity database objects.

c8y_api/model/administration.py

@@ -9,7 +9,7 @@
 
 from c8y_api._base_api import CumulocityRestApi, AccessDeniedError
 from c8y_api.model._base import CumulocityResource, SimpleObject
-from c8y_api.model._parser import SimpleObjectParser, ComplexObjectParser
+from c8y_api.model._parser import SimpleObjectParser, ComplexObjectParser, as_tuples as parse_as_tuples
 from c8y_api.model._util import _DateUtil
 
 
@@ -1067,6 +1067,7 @@ def select(
             limit: int = None,
             page_size: int = 5,
             page_number: int = None,
+            as_tuples: str | tuple | list[str | tuple] = None,
             **kwargs
     ) -> Generator[User]:
         """Lazily select and yield User instances.
@@ -1091,6 +1092,10 @@ def select(
                 parsed in one chunk). This is a performance related setting.
             page_number (int): Pull a specific page; this effectively disables
                 automatic follow-up page retrieval.
+            as_tuples: (*str|tuple):  Don't parse objects, but directly extract
+                the values at certain JSON paths as tuples; If the path is not
+                defined in a result, None is used; Specify a tuple to define
+                a proper default value for each path.
 
         Returns:
             Generator of User instances
@@ -1120,10 +1125,14 @@ def select(
             only_devices=only_devices,
             with_subusers_count=with_subusers_count,
             page_size=page_size,
-
             **kwargs
         )
-        return super()._iterate(base_query, page_number, limit, User.from_json)
+        return super()._iterate(
+            base_query,
+            page_number,
+            limit,
+            User.from_json if not as_tuples else
+            lambda x: parse_as_tuples(x, as_tuples))
 
     def get_all(
             self,
@@ -1133,6 +1142,7 @@ def get_all(
             only_devices: bool = None,
             with_subusers_count: bool = None,
             page_size: int = 1000,
+            as_tuples: str | tuple | list[str|tuple] = None,
             **kwargs
     ) -> list[User]:
         """Select and retrieve User instances as list.
@@ -1151,6 +1161,7 @@ def get_all(
             only_devices=only_devices,
             with_subusers_count=with_subusers_count,
             page_size=page_size,
+            as_tuples=as_tuples,
             **kwargs))
 
     def create(self, *users):

c8y_api/model/alarms.py

@@ -334,7 +334,7 @@ def select(self,
             page_number,
             limit,
             Alarm.from_json if not as_tuples else
-            lambda x: parse_as_tuples(x, *([as_tuples] if isinstance(as_tuples, str) else as_tuples)))
+            lambda x: parse_as_tuples(x, as_tuples))
 
     def get_all(
             self,

c8y_api/model/audit.py

@@ -8,7 +8,7 @@
 
 from c8y_api._base_api import CumulocityRestApi
 from c8y_api.model._base import CumulocityResource, ComplexObject
-from c8y_api.model._parser import ComplexObjectParser, SimpleObjectParser
+from c8y_api.model._parser import ComplexObjectParser, SimpleObjectParser, as_tuples as parse_as_tuples
 from c8y_api.model._util import _DateUtil
 
 
@@ -207,6 +207,7 @@ def select(
             min_age: timedelta = None, max_age: timedelta = None,
             reverse: bool = False, limit: int = None,
             page_size: int = 1000, page_number: int = None,
+            as_tuples: str | tuple | list[str | tuple] = None,
             **kwargs
     ) -> Generator[AuditRecord]:
         """Query the database for audit records and iterate over the results.
@@ -239,6 +240,10 @@ def select(
                 parsed in one chunk). This is a performance related setting.
             page_number (int): Pull a specific page; this effectively disables
                 automatic follow-up page retrieval.
+            as_tuples: (*str|tuple):  Don't parse objects, but directly extract
+                the values at certain JSON paths as tuples; If the path is not
+                defined in a result, None is used; Specify a tuple to define
+                a proper default value for each path.
 
         Returns:
             Generator for AuditRecord objects
@@ -250,7 +255,12 @@ def select(
             min_age=min_age, max_age=max_age,
             reverse=reverse, page_size=page_size,
             **kwargs)
-        return super()._iterate(base_query, page_number, limit, AuditRecord.from_json)
+        return super()._iterate(
+            base_query,
+            page_number,
+            limit,
+            AuditRecord.from_json if not as_tuples else
+            lambda x: parse_as_tuples(x, as_tuples))
 
     def get_all(
             self,
@@ -260,6 +270,7 @@ def get_all(
             min_age: timedelta = None, max_age: timedelta = None,
             reverse: bool = False, limit: int = None,
             page_size: int = 1000, page_number: int = None,
+            as_tuples: str | tuple | list[str | tuple] = None,
             **kwargs
     ) -> List[AuditRecord]:
         """Query the database for audit records and return the results as list.
@@ -278,6 +289,7 @@ def get_all(
             before=before, after=after,
             min_age=min_age, max_age=max_age,
             reverse=reverse, limit=limit, page_size=page_size, page_number=page_number,
+            as_tuples=as_tuples,
             **kwargs,
         ))
 

c8y_api/model/events.py

@@ -345,7 +345,7 @@ def select(self,
             page_number,
             limit,
             Event.from_json if not as_tuples else
-            lambda x: parse_as_tuples(x, *([as_tuples] if isinstance(as_tuples, str) else as_tuples)))
+            lambda x: parse_as_tuples(x, as_tuples))
 
     def get_all(
             self,

c8y_api/model/inventory.py

@@ -353,7 +353,7 @@ def _select(self, parse_fun, device_mode: bool, page_number, limit, as_tuples, *
             page_number,
             limit,
             parse_fun if not as_tuples else
-            lambda x: parse_as_tuples(x, *([as_tuples] if isinstance(as_tuples, str) else as_tuples)))
+            lambda x: parse_as_tuples(x, as_tuples))
 
     def create(self, *objects: ManagedObject):
         """Create managed objects within the database.

c8y_api/model/measurements.py

@@ -569,7 +569,7 @@ def select(
             page_number,
             limit,
             Measurement.from_json if not as_tuples else
-            lambda x: parse_as_tuples(x, *([as_tuples] if isinstance(as_tuples, str) else as_tuples)))
+            lambda x: parse_as_tuples(x, as_tuples))
 
     def get_all(
             self,

c8y_api/model/operations.py

@@ -8,7 +8,7 @@
 from c8y_api._base_api import CumulocityRestApi
 
 from c8y_api.model._base import CumulocityResource, ComplexObject, SimpleObject, _DictWrapper
-from c8y_api.model._parser import ComplexObjectParser
+from c8y_api.model._parser import ComplexObjectParser, as_tuples as parse_as_tuples
 from c8y_api.model._util import _DateUtil
 
 
@@ -161,6 +161,7 @@ def select(
             min_age: timedelta = None, max_age: timedelta = None,
             reverse: bool = False, limit: int = None,
             page_size: int = 1000, page_number: int = None,
+            as_tuples: str | tuple | list[str|tuple] = None,
             **kwargs
     ) -> Generator[Operation]:
         """ Query the database for operations and iterate over the results.
@@ -199,6 +200,10 @@ def select(
                 related setting.
             page_number (int): Pull a specific page; this effectively disables
                 automatic follow-up page retrieval.
+            as_tuples: (*str|tuple):  Don't parse objects, but directly extract
+                the values at certain JSON paths as tuples; If the path is not
+                defined in a result, None is used; Specify a tuple to define
+                a proper default value for each path.
 
         Returns:
             Generator[Operation]: Iterable of matching Operation objects
@@ -211,7 +216,12 @@ def select(
             reverse=reverse, page_size=page_size,
             **kwargs
         )
-        return super()._iterate(base_query, page_number, limit, Operation.from_json)
+        return super()._iterate(
+            base_query,
+            page_number,
+            limit,
+            Operation.from_json if not as_tuples else
+            lambda x: parse_as_tuples(x, as_tuples))
 
     def get_all(
             self,
@@ -222,6 +232,7 @@ def get_all(
             min_age: timedelta = None, max_age: timedelta = None,
             reverse: bool = False, limit: int = None,
             page_size: int = 1000, page_number: int = None,
+            as_tuples: str | tuple | list[str|tuple] = None,
             **kwargs
     ) -> List[Operation]:
         """ Query the database for operations and return the results
@@ -237,7 +248,7 @@ def get_all(
             expression=expression,
             agent_id=agent_id, device_id=device_id, status=status, bulk_id=bulk_id,
             fragment=fragment, before=before, after=after, min_age=min_age, max_age=max_age,
-            reverse=reverse, limit=limit, page_size=page_size, page_number=page_number,
+            reverse=reverse, limit=limit, page_size=page_size, page_number=page_number, as_tuples=as_tuples,
             **kwargs
         ))
 

tests/model/test_administration.py

@@ -5,7 +5,8 @@
 
 import pytest
 
-from c8y_api import CumulocityApi
+from c8y_api import CumulocityApi, CumulocityRestApi
+from c8y_api.model import Users
 from tests.utils import isolate_last_call_arg
 
 
@@ -40,3 +41,47 @@ def test_select_users(params, expected, not_expected):
         assert e in resource
     for ne in not_expected:
         assert ne not in resource
+
+
+def test_select_as_tuples():
+    """Verify that select as tuples works as expected."""
+    jsons = [
+        {'userName': 'user1',
+         'enabled': True,
+         'applications': [],
+         'customProperties': {'p1': 'v1', 'p2': 'v2'}},
+        {'userName': 'user2',
+         'enabled': False,
+         'applications': [{'a': 1}, {'b': 2}],
+         'customProperties': {'p1': 'v2'},
+         'phone': '+123'},
+    ]
+
+    c8y = CumulocityRestApi(base_url='base', tenant_id='t123', username='u', password='p')
+    api = Users(c8y)
+    api.c8y.get = Mock(side_effect=[{'users': jsons}, {'users': []}])
+    result = api.get_all(as_tuples=[
+        'user_name', 'enabled', 'applications', 'customProperties.p1', 'customProperties.p2', 'phone'])
+    assert result == [
+        ('user1', True, [], 'v1', 'v2', None),
+        ('user2', False, [{'a': 1}, {'b': 2}], 'v2', None, '+123'),
+    ]
+
+    c8y = CumulocityRestApi(base_url='base', tenant_id='t123', username='u', password='p')
+    api = Users(c8y)
+    api.c8y.get = Mock(side_effect=[{'users': jsons}, {'users': []}])
+    result = api.get_all(as_tuples=[
+        'userName', 'enabled', 'applications', 'custom_properties.p1', ('customProperties.p2', 'v3'), ('phone', '')])
+    assert result == [
+        ('user1', True, [], 'v1', 'v2', ''),
+        ('user2', False, [{'a': 1}, {'b': 2}], 'v2', 'v3', '+123'),
+    ]
+
+    c8y = CumulocityRestApi(base_url='base', tenant_id='t123', username='u', password='p')
+    api = Users(c8y)
+    api.c8y.get = Mock(side_effect=[{'users': jsons}, {'users': []}])
+    result = api.get_all(as_tuples='enabled')
+    assert result == [
+        (True, ),
+        (False, ),
+    ]