Add logical_operator parameter for AND/OR tag filtering 🪛

[01100100]

This PR introduces a new filter_logical_operator parameter to all QuackOSM converter functions, allowing users to control how tags_filter conditions are logically combined. Choose between "OR" (default) and "AND" logic when filtering OSM features by tags 🏷️

Motivation

When filtering with multiple tag conditions, QuackOSM returns features matching ANY of these conditions (OR logic). In many cases, you actually want to filter features that match ALL conditions (AND logic). Without this possibility I would first use quackosm to produce a result set and then add on a second processing step to filter the results. This PR allows returning only features that match all specified conditions directly.

eg) if you only want gravel tracks, you could combine highway=track and surface=gravel. However with the current (AND) logic, many rows would be included that do not fit eg) asphalt tracks and anything tagged to be gravel.

Changes

• Update PbfFileReader to include the logic that parses the new filter_logical_operator parameter and uses the relevant AND or OR logic in formatted SQL query.
• Update all QuackOSM converter functions to accept the new filter_logical_operator parameter and pass it to the PbfFileReader.

Note

I didn't think about how this might work with the negative filtering.. For my use case I don't need it, so it didn't come up, sorry that I didn't think it through.

I also didn't add any tests, as I don't know how to do it in this codebase. If you can point me in the right direction, I would be happy to add some tests.

p.s. Thanks for this tool! It works great and is a real benefit to the community. Really appreciate the work you put into it 🙏

[RaczeQ]

Hi @01100100

Thank you for tackling this challenge and your contribution to the library. Unfortunately, I might not be able to make a proper review in the near future since I'll be involved in some other tasks, but I will look at it in 2-3 weeks.

If you want, I can also chime in and write tests myself and maybe incorporate it with 'negative' filters.

For now, the tests are located in the tests/ directory, and given the scope, I would add them to the tests/base/test_osm_tags_filtering.py file. I'm using pytest for running tests in this project. Sorry for not providing proper contribution guidelines :p

[codecov]

Codecov Report

❌ Patch coverage is 75.00000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 92.05%. Comparing base (4816766) to head (6b28f2d).

Files with missing lines	Patch %	Lines
quackosm/pbf_file_reader.py	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #223      +/-   ##
==========================================
- Coverage   92.12%   92.05%   -0.07%     
==========================================
  Files          23       23              
  Lines        2160     2141      -19     
==========================================
- Hits         1990     1971      -19     
  Misses        170      170              

Flag	Coverage Δ
macos-13-python3.13	?
ubuntu-latest-python3.10	92.05% <75.00%> (-0.07%)	⬇️
ubuntu-latest-python3.11	?
ubuntu-latest-python3.12	92.05% <75.00%> (-0.07%)	⬇️
ubuntu-latest-python3.13	92.05% <75.00%> (-0.07%)	⬇️
ubuntu-latest-python3.9	92.05% <75.00%> (-0.07%)	⬇️
windows-latest-python3.13	92.05% <75.00%> (-0.07%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.