PyDF now being the default matcher.

Author: chsou

CHANGELOG.md

@@ -3,7 +3,7 @@
 * Added client-side filtering to many of the standard API (wherever sensibly applicable); These APIs `select`
   and `get_all` functions now feature optional `include` and `exclude` parameters which can be used to filter 
   the results before being wrapped into Python objects; Added multiple matchers including a JSONPath matcher
-  and a JMESPath matcher.
+  a JMESPath matcher and a PyDF (Python Display Filter) matcher with PyDF as default.
 * Added `QueueListener` and `AsyncQueueListener` classes to the Notification 2.0 toolkit. These pre-defined
   listener implementation append new notifications to standard queues that can be monitored/listened to which 
   makes Notification 2.0 solutions even simpler to implement.

c8y_api/model/_base.py

@@ -13,7 +13,7 @@
 from c8y_api.model.matcher import JsonMatcher
 from c8y_api.model._util import _DateUtil, _StringUtil, _QueryUtil
 try:
-    from c8y_api.model.matcher import JmesPathMatcher
+    from c8y_api.model.matcher import PydfMatcher
 except ImportError:
     pass
 
@@ -639,7 +639,7 @@ def __init__(self, c8y: CumulocityRestApi, resource: str):
         # the last event for e.g. /event/events
         self.object_name = self.resource.split('/')[-1]
         # the default JSON matcher for client-side filtering
-        self.default_matcher = JmesPathMatcher
+        self.default_matcher = PydfMatcher
 
     def build_object_path(self, object_id: int | str) -> str:
         """Build the path to a specific object of this resource.

c8y_api/model/administration.py

@@ -959,17 +959,20 @@ def select(
             limit (int): Limit the number of results to this number.
             include (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The inclusion is applied first.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             exclude (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The exclusion is applied second.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             page_size (int): Define the number of objects read (and 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.
 
         Returns:
             Generator for InventoryRole objects
+
+        See also:
+            https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language
         """
         base_query = self._prepare_query(page_size=page_size)
         return super()._iterate(base_query, page_number, limit, include, exclude, InventoryRole.from_json)
@@ -1116,10 +1119,10 @@ def select(
             limit (int): Limit the number of results to this number.
             include (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The inclusion is applied first.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             exclude (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The exclusion is applied second.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             page_size (int): Define the number of events which are read (and
                 parsed in one chunk). This is a performance related setting.
             page_number (int): Pull a specific page; this effectively disables
@@ -1131,6 +1134,9 @@ def select(
 
         Returns:
             Generator of User instances
+
+        See also:
+            https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language
         """
         # group_list can be ints, strings (names) or Group objects
         # it needs to become a comma-separated string
@@ -1337,15 +1343,18 @@ def select(
                 If omitted, all available global roles are returned
             include (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The inclusion is applied first.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             exclude (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The exclusion is applied second.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             page_size (int): Maximum number of entries fetched per requests;
                 this is a performance setting
 
         Return:
             Generator of GlobalRole instances
+
+        See also:
+            https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language
         """
         # unfortunately, as selecting by username can't be implemented using the
         # generic _iterate method, we have to do everything manually.
@@ -1400,15 +1409,18 @@ def get_all(
                 If omitted, all available global roles are returned
             include (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The inclusion is applied first.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             exclude (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The exclusion is applied second.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             page_size (int): Maximum number of entries fetched per requests;
                 this is a performance setting
 
         Return:
             List of GlobalRole instances
+
+        See also:
+            https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language
         """
         return list(self.select(username=username, include=include, exclude=exclude, page_size=page_size))
 

c8y_api/model/alarms.py

@@ -307,10 +307,10 @@ def select(self,
             limit (int): Limit the number of results to this number.
             include (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The inclusion is applied first.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             exclude (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The exclusion is applied second.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             page_size (int): Define the number of alarms which are read (and
                 parsed in one chunk). This is a performance related setting.
             page_number (int): Pull a specific page; this effectively disables
@@ -322,6 +322,9 @@ def select(self,
 
         Returns:
             Generator of Alarm objects
+
+        See also:
+            https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language
         """
         base_query = self._prepare_query(
             expression=expression,

c8y_api/model/audit.py

@@ -240,10 +240,10 @@ def select(
             limit (int): Limit the number of results to this number.
             include (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The inclusion is applied first.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             exclude (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The exclusion is applied second.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             page_size (int): Define the number of objects which are read (and
                 parsed in one chunk). This is a performance related setting.
             page_number (int): Pull a specific page; this effectively disables
@@ -255,6 +255,9 @@ def select(
 
         Returns:
             Generator for AuditRecord objects
+
+        See also:
+            https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language
         """
         base_query = self._prepare_query(
             expression=expression,

c8y_api/model/events.py

@@ -330,10 +330,10 @@ def select(self,
             limit (int): Limit the number of results to this number.
             include (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The inclusion is applied first.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             exclude (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The exclusion is applied second.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             page_size (int): Define the number of events which are read (and
                 parsed in one chunk). This is a performance related setting.
             page_number (int): Pull a specific page; this effectively disables
@@ -345,6 +345,9 @@ def select(self,
 
         Returns:
             Generator for Event objects
+
+        See also:
+            https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language
         """
         base_query = self._prepare_event_query(
             expression=expression,

c8y_api/model/inventory.py

@@ -298,10 +298,10 @@ def select(
             limit (int): Limit the number of results to this number.
             include (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The inclusion is applied first.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             exclude (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The exclusion is applied second.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             page_size (int): Define the number of events which are read (and
                 parsed in one chunk). This is a performance related setting.
             page_number (int): Pull a specific page; this effectively disables
@@ -313,8 +313,10 @@ def select(
 
         Returns:
             Generator for ManagedObject instances
-        """
 
+        See also:
+            https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language
+        """
         return self._select(
             ManagedObject.from_json,
             device_mode=False,
@@ -694,10 +696,10 @@ def select(  # noqa (order)
             limit (int): Limit the number of results to this number.
             include (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The inclusion is applied first.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             exclude (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The exclusion is applied second.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             page_size (int): Define the number of events which are read (and
                 parsed in one chunk). This is a performance related setting.
             page_number (int): Pull a specific page; this effectively disables
@@ -709,6 +711,9 @@ def select(  # noqa (order)
 
         Returns:
             Generator for Device objects
+
+        See also:
+            https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language
         """
         return super()._select(
             Device.from_json,
@@ -962,10 +967,10 @@ def select(  # noqa (changed signature)
             limit (int): Limit the number of results to this number.
             include (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The inclusion is applied first.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             exclude (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The exclusion is applied second.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             page_size (int): Define the number of events which are read (and
                 parsed in one chunk). This is a performance related setting.
             page_number (int): Pull a specific page; this effectively disables
@@ -977,6 +982,9 @@ def select(  # noqa (changed signature)
 
         Returns:
             Generator of DeviceGroup instances
+
+        See also:
+            https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language
         """
         type = type or (DeviceGroup.CHILD_TYPE if parent else None)
         if fragments:

c8y_api/model/operations.py

@@ -201,10 +201,10 @@ def select(
             limit (int):  Limit the number of results to this number.
             include (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The inclusion is applied first.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             exclude (str | JsonMatcher): Matcher/expression to filter the query
                 results (on client side). The exclusion is applied second.
-                Creates a JMESPath matcher by default for strings.
+                Creates a PyDF (Python Display Filter) matcher by default for strings.
             page_size (int):  Define the number of operations which are
                 read (and parsed in one chunk). This is a performance
                 related setting.
@@ -217,6 +217,9 @@ def select(
 
         Returns:
             Generator[Operation]: Iterable of matching Operation objects
+
+        See also:
+            https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language
         """
         base_query = self._prepare_query(
             expression=expression,

samples/client_side_filtering.py

@@ -2,7 +2,7 @@
 
 from c8y_api.app import SimpleCumulocityApp
 from c8y_api.model import Device
-from c8y_api.model.matcher import field, match_all, match_not
+from c8y_api.model.matcher import field, match_all, match_not, pydf
 from util.testing_util import load_dotenv
 
 logging.basicConfig(level=logging.DEBUG)
@@ -23,11 +23,16 @@
 Client-side filters are defined for the _raw_ JSON structure. Hence, when you
 want to use them you must be aware of Cumulocity's JSON data format. 
 
+By default, PyDF (Python Display Filter) expression can be specified directly
+as strings. See also
+https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language
+for details. 
+
 Performance: Hi there, optimization kids! To put it bluntly - using this
 feature does most likely _not_ increase performance in any way. This is
 because the actual JSON parsing will happen in any case and this is the
 expensive part. So - all the illustrated methods below do only marginally
-differ in speeed.  
+differ in speeed.
 """
 
 load_dotenv()  # load environment from a .env if present
@@ -57,11 +62,11 @@
 
 # Option 2: using the client-side filtering with JMESPath filters
 # The following statement will simply list "all" devices (there are no DB
-# filters) and subsequently filter the results using a JMESPath expression.
-# The JMESPath is matched against the unprocessed JSON, hence it is required
+# filters) and subsequently filter the results using a PyDF expression.
+# The PyDF expression is matched against the unprocessed JSON, hence it is required
 # to understand Cumulocity's native JSON formats (but they are close to how
 # the Python API resembles it:
-filtered_devices_2 = c8y.device_inventory.get_all(type='c8y_TestDevice', include="contains(name, 'Device')")
+filtered_devices_2 = c8y.device_inventory.get_all(type='c8y_TestDevice', include="name contains Device")
 # -> We will only have devices which are named "Device something"
 print("Option #2 result (same thing):")
 for d in filtered_devices_2:
@@ -84,14 +89,15 @@
 
 # Option 4: the client-side filtering with nested filters
 # The following statement applies the same as above, but using ridiculously
-# nested Python matchers to get the same logic.
+# nested Python matchers to get the same logic. Note that we combine custom
+# filters with a PyDF expression filter.
 
 filtered_devices_4 = c8y.device_inventory.get_all(
     type='c8y_TestDevice',
     include=match_all(
         field('name', '*Device*'),
         match_not(
-            field('name', '*#*')
+            pydf("name contains '#'")
         )
     ))
 # -> Same result