Source code for pyvergeos.filters

"""OData-style filter expression builder for VergeOS API queries.

VergeOS filtering is "similar to OData" but has its own grammar. The
supported comparison operators are ``eq``, ``ne``, ``gt``, ``ge``, ``lt``,
``le``, ``bw`` (begins-with), ``ew`` (ends-with), ``cs`` (contains,
case-sensitive), ``ct`` (contains, case-insensitive) and ``rx`` (POSIX ERE
regex). There is no ``like`` and no ``in`` -- the platform rejects both
tokens with HTTP 422 -- so the wildcard and list shorthands below are
translated to supported operators (issue #103).

``and``/``or`` have no precedence and are evaluated strictly left-to-right,
so every generated ``or`` chain is parenthesized.
"""

from __future__ import annotations

import re
from enum import Enum
from typing import Any

# The platform's ``rx`` dialect is POSIX ERE: PCRE shorthands such as ``\d``
# and inline flags such as ``(?i)`` do not error -- they silently match
# nothing -- so only backslash-escaping of metacharacters is safe.
_POSIX_ERE_SPECIALS = re.compile(r"[.\[\]()*+?{}|^$\\]")


# Characters the platform reserves inside a filter string literal. Measured by
# sweeping all 95 printable ASCII characters against a live system (issue #100):
# only these three carry meaning; the other 92 are inert, including ``}``.
#   ``\\``  the escape character itself
#   ``'``   terminates the literal
#   ``{``   opens a balanced, nesting-aware construct
# All three are escaped with a single backslash. ``\\`` MUST be replaced first,
# or the backslash it inserts for a later character gets doubled.
_RESERVED_IN_LITERAL = ("\\", "'", "{")


[docs] def quote_value(value: str) -> str: """Quote a string literal for a VergeOS filter expression. VergeOS uses backslash escaping, not SQL quote doubling. Three characters are reserved inside a literal and each is escaped with a backslash: ``\\`` (the escape character), ``'`` (terminates the literal) and ``{`` (opens a balanced construct). ``}`` is not reserved. An unescaped ``{`` is the dangerous one: a *balanced* ``{...}`` is consumed silently and the query matches whatever the stripped string names, so a lookup-by-name can return - and the caller can then modify or delete - the wrong object (issue #100). An unbalanced ``{`` is merely rejected with HTTP 422. This only quotes the value; wildcard conversion belongs to the caller. """ escaped = value for char in _RESERVED_IN_LITERAL: escaped = escaped.replace(char, "\\" + char) return f"'{escaped}'"
def _posix_escape(text: str) -> str: """Escape POSIX ERE metacharacters for the platform's ``rx`` operator. ``re.escape()`` is deliberately not used: it targets Python's PCRE-style dialect, while VergeOS evaluates POSIX ERE, where unsupported escapes silently match nothing instead of raising (issue #103). """ return _POSIX_ERE_SPECIALS.sub(lambda m: "\\" + m.group(0), text)
[docs] def wildcard_condition(field: str, pattern: str) -> str: """Translate a ``*``/``?`` wildcard pattern into supported operators. Public so resource managers with a ``name`` search parameter share one translation instead of hand-rolling their own (issue #103, PR #104). VergeOS has no ``like`` operator (HTTP 422 "Invalid argument"), so wildcard patterns are translated (issue #103): - ``foo*`` -> ``field bw 'foo'`` (begins-with) - ``*foo`` -> ``field ew 'foo'`` (ends-with) - ``*foo*`` -> ``field cs 'foo'`` (contains) - ``*`` -> ``field bw ''`` (matches every row) - patterns with ``?`` or an interior ``*`` -> anchored POSIX-ERE ``rx`` with metacharacters escaped, e.g. ``a*b`` -> ``field rx '^a.*b$'`` Matching is case-sensitive throughout, consistent with ``eq``. For a case-insensitive contains, use a raw ``filter="field ct '...'"``. The anchored form guarantees the ``rx`` pattern is never empty (an empty ``rx`` pattern matches every row on the platform). """ if "?" not in pattern: body = pattern.strip("*") if "*" not in body: leading = pattern.startswith("*") trailing = pattern.endswith("*") if not body: if leading or trailing: # Only wildcards ('*', '**', ...): match everything, # as LIKE '%' would have. return f"{field} bw ''" return f"{field} eq {quote_value(pattern)}" if leading and trailing: return f"{field} cs {quote_value(body)}" if trailing: return f"{field} bw {quote_value(body)}" if leading: return f"{field} ew {quote_value(body)}" return f"{field} eq {quote_value(pattern)}" # Complex pattern ('?' anywhere, or '*' between literals): anchored regex. out = ["^"] for ch in pattern: if ch == "*": out.append(".*") elif ch == "?": out.append(".") else: out.append(_posix_escape(ch)) out.append("$") return f"{field} rx {quote_value(''.join(out))}"
def _scalar_condition(field: str, value: Any) -> str: """Equality condition, with wildcard translation for string values.""" if isinstance(value, str) and ("*" in value or "?" in value): return wildcard_condition(field, value) return f"{field} eq {_format_value(value)}" def _in_condition(field: str, values: Any) -> str: """Expand a sequence into a parenthesized ``or`` chain of conditions. VergeOS has no ``in`` operator (HTTP 422 "Invalid argument"). The chain must be parenthesized: the platform evaluates ``and``/``or`` strictly left-to-right with no precedence, so an unparenthesized chain silently regroups when combined with ``and`` (issue #103). String elements get the same wildcard translation as scalar values. Raises: ValueError: If the sequence is empty. An empty ``in`` would match no rows, which is almost certainly a caller bug and must not fail silently. """ items = list(values) if not items: raise ValueError( f"Cannot build a filter for {field!r} from an empty sequence; it would match no rows" ) terms = " or ".join(_scalar_condition(field, v) for v in items) return f"({terms})"
[docs] class FilterOperator(Enum): """Filter operators. ``LIKE`` and ``IN`` are accepted for backwards compatibility but are never sent to the API: VergeOS rejects both tokens, so they are translated to supported operators (issue #103). """ EQ = "eq" NE = "ne" LT = "lt" GT = "gt" LE = "le" GE = "ge" BW = "bw" EW = "ew" CS = "cs" CT = "ct" RX = "rx" LIKE = "like" IN = "in"
[docs] class Filter: """OData-style filter expression builder. Example: >>> f = Filter() >>> f.eq("status", "running").and_().like("name", "web*") >>> str(f) "status eq 'running' and name bw 'web'" """
[docs] def __init__(self) -> None: self._parts: list[str] = []
def _add(self, field: str, op: FilterOperator, value: Any) -> Filter: """Add a filter condition, translating unsupported operators.""" if op is FilterOperator.LIKE: # VergeOS has no 'like' operator (issue #103). self._parts.append(wildcard_condition(field, str(value))) return self if op is FilterOperator.IN: # VergeOS has no 'in' operator (issue #103). seq = value if isinstance(value, (list, tuple)) else [value] self._parts.append(_in_condition(field, seq)) return self self._parts.append(f"{field} {op.value} {_format_value(value)}") return self def _auto_and(self) -> None: """Auto-add AND if needed (implicit AND between conditions).""" if self._parts and self._parts[-1] not in ("and", "or"): self._parts.append("and")
[docs] def eq(self, field: str, value: Any) -> Filter: """Add equals condition.""" self._auto_and() return self._add(field, FilterOperator.EQ, value)
[docs] def ne(self, field: str, value: Any) -> Filter: """Add not equals condition.""" self._auto_and() return self._add(field, FilterOperator.NE, value)
[docs] def lt(self, field: str, value: Any) -> Filter: """Add less than condition.""" self._auto_and() return self._add(field, FilterOperator.LT, value)
[docs] def gt(self, field: str, value: Any) -> Filter: """Add greater than condition.""" self._auto_and() return self._add(field, FilterOperator.GT, value)
[docs] def le(self, field: str, value: Any) -> Filter: """Add less than or equal condition.""" self._auto_and() return self._add(field, FilterOperator.LE, value)
[docs] def ge(self, field: str, value: Any) -> Filter: """Add greater than or equal condition.""" self._auto_and() return self._add(field, FilterOperator.GE, value)
[docs] def like(self, field: str, pattern: str) -> Filter: """Add a wildcard pattern condition. ``*`` = any run, ``?`` = one char. VergeOS has no ``like`` operator, so the pattern is translated to supported operators: ``foo*`` -> ``bw``, ``*foo`` -> ``ew``, ``*foo*`` -> ``cs``, complex patterns -> anchored POSIX-ERE ``rx``. Matching is case-sensitive, consistent with ``eq`` (issue #103). """ self._auto_and() return self._add(field, FilterOperator.LIKE, pattern)
[docs] def in_(self, field: str, values: list[Any] | Any) -> Filter: """Add a membership condition as a parenthesized ``or`` chain. VergeOS has no ``in`` operator, so the list expands to ``(field eq v1 or field eq v2 ...)``. String values follow the same wildcard translation as :meth:`like` (issue #103). Raises: ValueError: If ``values`` is an empty sequence. """ self._auto_and() return self._add(field, FilterOperator.IN, values)
[docs] def bw(self, field: str, value: str) -> Filter: """Add begins-with condition (case-sensitive).""" self._auto_and() return self._add(field, FilterOperator.BW, value)
[docs] def ew(self, field: str, value: str) -> Filter: """Add ends-with condition (case-sensitive).""" self._auto_and() return self._add(field, FilterOperator.EW, value)
[docs] def cs(self, field: str, value: str) -> Filter: """Add contains condition (case-sensitive).""" self._auto_and() return self._add(field, FilterOperator.CS, value)
[docs] def ct(self, field: str, value: str) -> Filter: """Add contains condition (case-insensitive).""" self._auto_and() return self._add(field, FilterOperator.CT, value)
[docs] def rx(self, field: str, pattern: str) -> Filter: """Add a POSIX-ERE regex condition (partial match, case-sensitive). The platform dialect is POSIX ERE: bracket classes like ``[0-9]`` and ``[[:digit:]]`` work, but PCRE shorthands (``\\d``) and inline flags (``(?i)``) silently match nothing, and an **empty pattern matches every row**. Escape literal metacharacters with a backslash. """ self._auto_and() return self._add(field, FilterOperator.RX, pattern)
[docs] def and_(self) -> Filter: """Add explicit AND connector (usually not needed, AND is implicit).""" self._parts.append("and") return self
[docs] def or_(self) -> Filter: """Add OR connector (must be explicit, unlike AND).""" self._parts.append("or") return self
def __str__(self) -> str: return " ".join(self._parts) def __bool__(self) -> bool: return bool(self._parts) def __repr__(self) -> str: return f"Filter({str(self)!r})"
def _format_value(value: Any) -> str: """Format a value for a filter expression.""" if value is None: return "null" if isinstance(value, bool): return "true" if value else "false" if isinstance(value, (int, float)): return str(value) return quote_value(str(value))
[docs] def combine_filters(filter: str | None, filter_kwargs: dict[str, Any]) -> str | None: # noqa: A002 """Merge an explicit filter string with shorthand filter kwargs. Both filter forms are honoured: when both are supplied the result is ``(filter) and (built)``. Previously shorthand kwargs were silently dropped whenever an explicit filter was present (issue #96). Args: filter: OData filter string, or None. filter_kwargs: Shorthand field-value filter arguments. Returns: Combined filter string, or None when no filtering was requested. Raises: ValueError: If filter kwargs were supplied but every value was None. An empty filter would silently match every row, so it is rejected instead of widening the result set (issue #96). """ built = "" if filter_kwargs: built = build_filter(**filter_kwargs) if not built: names = ", ".join(sorted(filter_kwargs)) raise ValueError( f"Filter argument(s) {names} are all None and would produce an " "empty filter matching every row; omit them to list all resources" ) if filter and built: return f"({filter}) and ({built})" return filter or built or None
[docs] def build_filter(**kwargs: Any) -> str: """Build a filter string from keyword arguments. Supports: - Simple equality: name="value" - Wildcards: name="prefix*" (translated to bw/ew/cs/rx; VergeOS has no LIKE operator -- see issue #103). Case-sensitive. - Lists: status=["running", "stopped"] (expanded to a parenthesized or-chain of equality/wildcard conditions; VergeOS has no IN operator). Raises ValueError for an empty sequence. Args: **kwargs: Field-value pairs for filtering. Returns: OData-style filter string. Example: >>> build_filter(status="running", name="web*") "status eq 'running' and name bw 'web'" >>> build_filter(status=["running", "stopped"]) "(status eq 'running' or status eq 'stopped')" """ parts = [] for field, value in kwargs.items(): if value is None: continue if isinstance(value, (list, tuple)): parts.append(_in_condition(field, value)) else: parts.append(_scalar_condition(field, value)) return " and ".join(parts)