Filters

siglip2_toolkit.filters

Serializable, general-purpose filters over mappings.

Filters are plain, JSON-serializable expressions over any dict-like subject (typically a record's metadata, but nothing ties them to images, EXIF schemas or storage engines). Example::

from siglip2_toolkit.filters import field, And, Not

f = And(
    field("width").between(1000, 4000),
    field("camera.make").contains("nikon"),
    Not(field("tags").exists()),
)
matches({"width": 2000, "camera": {"make": "NIKON Z6"}}, f)  # -> True

A missing field never matches (any operator, including !=); compose with Not/Or when you want the opposite. Order comparisons coerce numeric strings ("240.0" compares as a number) and fall back to lexicographic comparison when both sides are strings. contains/startswith are case-insensitive by default.

And dataclass module-attribute

And = _make_combinator(And)

Every child filter must match.

Or dataclass module-attribute

Or = _make_combinator(Or)

At least one child filter must match.

Filter dataclass

Filter(path, op, value=None, case_sensitive=False)

A leaf filter: path (dotted), op and value.

Field

Field(path)

Builder for filter leaves over a (possibly dotted) field path.

between

between(low, high)

Convenience: low <= field <= high.

in_

in_(values)

Membership: the field value must be one of values.

contains

contains(value, case_sensitive=False)

Substring test for string fields.

startswith

startswith(value, case_sensitive=False)

Prefix test for string fields.

exists

exists()

The field is present and not empty (None/""/[]/{} count as empty).

Not dataclass

Not(filter)

Negates a child filter (missing fields included).

field

field(path)

Start a filter expression over path (dotted paths allowed).

matches

matches(subject, node)

Whether subject (a mapping) satisfies node.

to_dict

to_dict(node)

Serialize a filter expression to plain JSON-compatible data.

from_dict

from_dict(data)

Rebuild a filter expression from to_dict output.