OR, XOR and NOT in filters

[yfukai]

Human summary

Currently only "AND" concatenation is supported for the AttrComparison. I updated the Attr codebase to support intuitive "OR", "XOR" and "NOT" operations (now AttrFilter exists for this purpose). I chose not to allow combining node and edge filters in AttrFilter since that would complicate the codebase significantly.

Copilot summary

This pull request introduces a new AttrFilter class to enable expressive, compound boolean filtering of node and edge attributes using logical operators (&, |, ^, ~). It updates the API throughout the codebase to support these compound filters, allowing for more flexible and readable queries.

Major new feature: Compound attribute filtering

• Added the AttrFilter class, which allows combining AttrComparison objects (and nested AttrFilters) using logical operators (&, |, ^, ~) to build complex boolean filters for graph queries. This enables expressions like (NodeAttr("t") == 1) | (NodeAttr("t") == 2) and ensures that filters are type-safe and validated.

API and type annotation updates

• Updated type annotations and function signatures across the graph API (filter, split_attr_comps, etc.) to accept both AttrComparison and AttrFilter objects, using the new FilterInput type alias. This ensures that all relevant methods and internal logic can handle compound filters transparently. [1] [2] [3] [4] [5] [6] [7]

Filtering logic and backend improvements

• Refactored the logic for splitting, stringifying, and evaluating attribute filters to support nested/compound filters, including new helper functions and changes to how filters are reduced to polars expressions. [1] [2]

Documentation and usage examples

• Expanded the documentation in attrs.py to explain and demonstrate the use of logical operators for combining attribute comparisons, with clear code examples for users.

Comprehensive testing for new filter functionality

• Added a suite of tests for AttrFilter covering construction, operator overloading, error handling, filter splitting, and evaluation with polars, ensuring robust and correct behavior for all supported logical operations. [1] [2]

[codecov-commenter]

Codecov Report

❌ Patch coverage is 89.14729% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.73%. Comparing base (a4f7607) to head (cafe1b9).

Files with missing lines	Patch %	Lines
src/tracksdata/attrs.py	85.26%	12 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #296      +/-   ##
==========================================
- Coverage   87.75%   87.73%   -0.02%     
==========================================
  Files          57       57              
  Lines        4947     5055     +108     
  Branches      872      899      +27     
==========================================
+ Hits         4341     4435      +94     
- Misses        381      393      +12     
- Partials      225      227       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.