Changed as_tuples parameter in select/get_all functions to as_values as sometimes you really just want to have one value and don't want to deal with a 1-tuple.

Author: chisou

CHANGELOG.md

@@ -1,12 +1,12 @@
 # Changelog
 
-* Added `as_tuples` parameter to `get_all` and `select` functions of the Inventory, DeviceInventory,
+* Added `as_values` 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`
+* Updated `as_tuple` for  complex objects as well as the `as_values` parameter for `select`
   and `get_all` functions to work with strings or 2-tuples. The use of a dictionary
   was removed as dictionaries don't define an order.
-* Added `as_tuples` parameter to the Measurements API `select` and `get_all` functions.
+* Added `as_values` parameter to the Measurements API `select` and `get_all` functions.
 * Adding `c8y_tk.analytics` package with `to_numpy`, `to_series` and `to_data_frame` functions to
   ease incorporating Cumulocity data into standard analytics pipelines.
 

c8y_api/model/_parser.py

@@ -8,8 +8,8 @@
 from c8y_api.model._util import _StringUtil
 
 
-def as_tuples(json_data, paths: str | tuple | list[str|tuple]):
-    """Parse a JSON structure as tuples from paths.
+def as_values(json_data, paths: str | tuple | list[str | tuple]):
+    """Parse a JSON structure as value(s) from paths.
 
     Args:
         json_data (dict):  A JSON structure as Python dict
@@ -23,7 +23,8 @@ def as_tuples(json_data, paths: str | tuple | list[str|tuple]):
 
     Returns:
         A tuple with `len(path)` elements containing the values as-is defined
-        in the JSON structure; an invalid path will result in None.
+        in the JSON structure or a single value if `len(path) == 1` ; an
+        invalid path will result in None.
     """
     def resolve(segments, default=None):
         json_level = json_data
@@ -39,9 +40,13 @@ 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
+    if isinstance(paths, str):
+        return resolve(paths.split('.'))
+    if isinstance(paths, tuple):
+        return resolve(paths[0].split('.'), paths[1])
     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))
+        else resolve(p.split('.')) for p in 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, as_tuples as parse_as_tuples
+from c8y_api.model._parser import SimpleObjectParser, ComplexObjectParser, as_values as parse_as_values
 from c8y_api.model._util import _DateUtil
 
 
@@ -1067,7 +1067,7 @@ def select(
             limit: int = None,
             page_size: int = 5,
             page_number: int = None,
-            as_tuples: str | tuple | list[str | tuple] = None,
+            as_values: str | tuple | list[str | tuple] = None,
             **kwargs
     ) -> Generator[User]:
         """Lazily select and yield User instances.
@@ -1092,7 +1092,7 @@ 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
+            as_values: (*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.
@@ -1131,8 +1131,8 @@ def select(
             base_query,
             page_number,
             limit,
-            User.from_json if not as_tuples else
-            lambda x: parse_as_tuples(x, as_tuples))
+            User.from_json if not as_values else
+            lambda x: parse_as_values(x, as_values))
 
     def get_all(
             self,
@@ -1142,7 +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,
+            as_values: str | tuple | list[str|tuple] = None,
             **kwargs
     ) -> list[User]:
         """Select and retrieve User instances as list.
@@ -1161,7 +1161,7 @@ def get_all(
             only_devices=only_devices,
             with_subusers_count=with_subusers_count,
             page_size=page_size,
-            as_tuples=as_tuples,
+            as_values=as_values,
             **kwargs))
 
     def create(self, *users):

c8y_api/model/alarms.py

@@ -7,7 +7,7 @@
 
 from c8y_api._base_api import CumulocityRestApi
 from c8y_api.model._base import CumulocityResource, SimpleObject, ComplexObject
-from c8y_api.model._parser import as_tuples as parse_as_tuples, ComplexObjectParser
+from c8y_api.model._parser import as_values as parse_as_values, ComplexObjectParser
 from c8y_api.model._util import _DateUtil
 
 
@@ -255,7 +255,7 @@ def select(self,
                reverse: bool = False, limit: int = None,
                with_source_assets: bool = None, with_source_devices: bool = None,
                page_size: int = 1000, page_number: int = None,
-               as_tuples: str | tuple | list[str | tuple] = None,
+               as_values: str | tuple | list[str | tuple] = None,
                **kwargs) -> Generator[Alarm]:
         """Query the database for alarms and iterate over the results.
 
@@ -307,7 +307,7 @@ def select(self,
                 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
+            as_values: (*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.
@@ -333,8 +333,8 @@ def select(self,
             base_query,
             page_number,
             limit,
-            Alarm.from_json if not as_tuples else
-            lambda x: parse_as_tuples(x, as_tuples))
+            Alarm.from_json if not as_values else
+            lambda x: parse_as_values(x, as_values))
 
     def get_all(
             self,
@@ -351,7 +351,7 @@ def get_all(
             with_source_assets: bool = None, with_source_devices: bool = None,
             reverse: bool = False, limit: int = None,
             page_size: int = 1000, page_number: int = None,
-            as_tuples: str | tuple | list[str|tuple] = None,
+            as_values: str | tuple | list[str | tuple] = None,
             **kwargs) -> List[Alarm]:
         """Query the database for alarms and return the results as list.
 
@@ -376,7 +376,7 @@ def get_all(
             min_age=min_age, max_age=max_age, reverse=reverse,
             with_source_devices=with_source_devices, with_source_assets=with_source_assets,
             limit=limit, page_size=page_size, page_number=page_number,
-            as_tuples=as_tuples,
+            as_values=as_values,
             **kwargs))
 
     def count(

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, as_tuples as parse_as_tuples
+from c8y_api.model._parser import ComplexObjectParser, SimpleObjectParser, as_values as parse_as_values
 from c8y_api.model._util import _DateUtil
 
 
@@ -207,7 +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,
+            as_values: str | tuple | list[str | tuple] = None,
             **kwargs
     ) -> Generator[AuditRecord]:
         """Query the database for audit records and iterate over the results.
@@ -240,7 +240,7 @@ 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
+            as_values: (*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.
@@ -259,8 +259,8 @@ def select(
             base_query,
             page_number,
             limit,
-            AuditRecord.from_json if not as_tuples else
-            lambda x: parse_as_tuples(x, as_tuples))
+            AuditRecord.from_json if not as_values else
+            lambda x: parse_as_values(x, as_values))
 
     def get_all(
             self,
@@ -270,7 +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,
+            as_values: str | tuple | list[str | tuple] = None,
             **kwargs
     ) -> List[AuditRecord]:
         """Query the database for audit records and return the results as list.
@@ -289,7 +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,
+            as_values=as_values,
             **kwargs,
         ))
 

c8y_api/model/events.py

@@ -10,7 +10,7 @@
 
 from c8y_api._base_api import CumulocityRestApi
 from c8y_api.model._base import CumulocityResource, SimpleObject, ComplexObject
-from c8y_api.model._parser import as_tuples as parse_as_tuples, ComplexObjectParser
+from c8y_api.model._parser import as_values as parse_as_values, ComplexObjectParser
 from c8y_api.model._util import _DateUtil
 
 
@@ -264,7 +264,7 @@ def select(self,
                reverse: bool = False, limit: int = None,
                with_source_assets: bool = None, with_source_devices: bool = None,
                page_size: int = 1000, page_number: int = None,
-               as_tuples: str | tuple | list[str|tuple] = None,
+               as_values: str | tuple | list[str | tuple] = None,
                **kwargs) -> Generator[Event]:
         """Query the database for events and iterate over the results.
 
@@ -315,7 +315,7 @@ def select(self,
                 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
+            as_values: (*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.
@@ -344,8 +344,8 @@ def select(self,
             base_query,
             page_number,
             limit,
-            Event.from_json if not as_tuples else
-            lambda x: parse_as_tuples(x, as_tuples))
+            Event.from_json if not as_values else
+            lambda x: parse_as_values(x, as_values))
 
     def get_all(
             self,
@@ -362,7 +362,7 @@ def get_all(
             reverse: bool = False, limit: int = None,
             with_source_assets: bool = None, with_source_devices: bool = None,
             page_size: int = 1000, page_number: int = None,
-            as_tuples: str | tuple | list[str|tuple] = None,
+            as_values: str | tuple | list[str | tuple] = None,
             **kwargs) -> List[Event]:
         """Query the database for events and return the results as list.
 
@@ -388,7 +388,7 @@ def get_all(
             reverse=reverse,
             with_source_devices=with_source_devices, with_source_assets=with_source_assets,
             limit=limit, page_size=page_size, page_number=page_number,
-            as_tuples=as_tuples,
+            as_values=as_values,
             **kwargs
         ))