Improve CORE documentation

Author: Epse

src/obelisk/__init__.py

@@ -2,6 +2,7 @@
 Obelisk-py is a client for the Obelisk data platform.
 We support both "classic" Obelisk and HFS,
 each with a synchronous and async API.
+We also support Obelisk CORE, in async only for now.
 The PyPi package name is ``obelisk-py``, the Python module is called ``obelisk``.
 
 Your starting point will be one of the Obelisk instances in :mod:`~.sync` or :mod:`~.asynchronous` depending on your preferred API.

src/obelisk/asynchronous/core.py

@@ -25,6 +25,13 @@
 
 
 def type_suffix(metric: str) -> DataType:
+    """
+    Extracts the :any:`DataType` from a string metric,
+    useful for the dataType field in queries.
+
+    Throws a :py:exc:`ValueError` if the provided string does not appear to be a typed metric,
+    or the found type suffix is not a known one.
+    """
     split = metric.split('::')
 
     if len(split) != 2:
@@ -96,7 +103,12 @@ class QueryParams(BaseModel):
     orderBy: Optional[List[str]] = None # More complex than just FieldName, can be prefixed with - to invert sort
     dataType: Optional[DataType] = None
     filter_: Annotated[Optional[str|Filter], Field(serialization_alias='filter')] = None
-    """Filter in `RSQL format <https://obelisk.pages.ilabt.imec.be/obelisk-core/query.html#rsql-format>`__ Suffix to avoid collisions."""
+    """
+    Obelisk CORE handles filtering in `RSQL format <https://obelisk.pages.ilabt.imec.be/obelisk-core/query.html#rsql-format>`__ ,
+    to make it easier to also programatically write these filters, we provide the :class:`Filter` option as well.
+
+    Suffix to avoid collisions.
+    """
     cursor: Optional[str] = None
     limit: int = 1000
 

src/obelisk/types/core.py

@@ -12,25 +12,43 @@
 ...     Comparison.less('timestamp', datetime.fromtimestamp(1757422128))
 ... ))
 >>> print(f)
-((('source'=='test source');('metricType'=in=('number', 'number[]'))),('timestamp'<'2025-09-09T14:48:48'))
+(('source'=='test source';'metricType'=in=('number', 'number[]')),'timestamp'<'2025-09-09T14:48:48')
 """
 from __future__ import annotations
 from abc import ABC
 from datetime import datetime
 from typing import Any, Iterable, List
 
 
-FieldName = str # TODO: validate field names?
+FieldName = str
 """https://obelisk.pages.ilabt.imec.be/obelisk-core/query.html#available-data-point-fields
 Field names are not validated at this time, due to the inherent complexity.
 """
 
 
 class Constraint(ABC):
+    """
+    Constraints are simply groups of :class:`Comparison`,
+    such as :class:`And`, or :class:`Or`.
+
+    These constraints always enclose their contents in parentheses,
+    to avoid confusing precendence situations in serialised format.
+    """
     pass
 
 
 class Comparison():
+    """
+    Comparisons are the basic items of a :class:`Filter`.
+    They consist of a field name, operator, and possibly a value on the right.
+
+    It is strongly suggested you create comparisons by using the staticmethods
+    on this class, rather than trying to construct them yourselves.
+
+    When serializing to RSQL format,
+    each argument is single quoted as to accept any otherwise reserved characters,
+    and serialised using :func:`str`.
+    """
     left: FieldName
     right: Any
     op: str
@@ -42,10 +60,10 @@ def __init__(self, left: FieldName, right: Any, op: str):
 
     def __str__(self) -> str:
         right = self._sstr(self.right)
-        if not right.startswith('('):
+        if not right.startswith('(') and len(right) > 0:
             right = f"'{right}'"
 
-        return f"('{self.left}'{self.op}{right})"
+        return f"'{self.left}'{self.op}{right}"
 
     @staticmethod
     def _sstr(item: Any):
@@ -124,6 +142,18 @@ def __str__(self) -> str:
 
 
 class Filter():
+    """
+    Filter is an easier way to programatically create filters for the Obelisk CORE platform.
+
+    We still recommend you familiarise yourself with the CORE filter documentation,
+    as not everything is typechecked.
+    Specifically, the left hand side of any comparison is left unchecked.
+    Checking this would be borderline impossible with the optional arguments to some fields,
+    and the dot notation for labels.
+
+    As this field is not checked, we also do not check whether the type of left operand
+    and right operand make sense in the provided comparison.
+    """
     content: Item | None = None
 
     def __init__(self, content: Constraint | None = None):
@@ -133,13 +163,29 @@ def __str__(self) -> str:
         return str(self.content)
 
     def add_and(self, *other: Item) -> Filter:
+        """
+        Encloses the current filter contents, if any,
+        in an :class:`And`, along with any other provided Items.
+
+        >>> str(Filter(Comparison.not_null('labels.username'))
+        ... .add_and(Comparison.equal('labels.username', 'stpletin'), Comparison.less_equal('timestamp', '2025-01-12T00:00:00Z')))
+        "('labels.username'=notnull=;'labels.username'=='stpletin';'timestamp'<='2025-01-12T00:00:00Z')"
+        """
         if self.content is None:
             self.content = And(*other)
         else:
             self.content = And(self.content, *other)
         return self
 
     def add_or(self, *other: Item) -> Filter:
+        """
+        Encloses the current filter contents, if any,
+        in an :class:`Or`, along with any other provided Items.
+
+        >>> str(Filter(Comparison.not_null('labels.username'))
+        ... .add_or(Comparison.equal('labels.username', 'stpletin'), Comparison.less_equal('timestamp', '2025-01-12T00:00:00Z')))
+        "('labels.username'=notnull=,'labels.username'=='stpletin','timestamp'<='2025-01-12T00:00:00Z')"
+        """
         if self.content is None:
             self.content = Or(*other)
         else:

src/tests/typetest/filter_test.py

@@ -15,5 +15,5 @@ def test_basic_filter():
             Comparison.is_in('metricType', ['number', 'number[]']),
         )
 
-    expected = f"(((('source'=='test source')),('timestamp'<'{test_dt.isoformat()}')),('metricType'=in=('number', 'number[]')))"
+    expected = f"((('source'=='test source'),'timestamp'<'{test_dt.isoformat()}'),'metricType'=in=('number', 'number[]'))"
     assert str(f) == expected