Fast-Filter

Your declarative filters in Python are 10x slower than they should be. Fast-Filter compiles them into optimized, native Python bytecode on the fly, making them 10x-15x faster with zero external dependencies.

Why Fast-Filter?

Many modern Python frameworks and libraries rely heavily on declarative query filters (e.g., magic-filter). While beautiful and readable, magic-filter acts as an AST interpreter, walking through object structures and evaluating attributes on every single incoming event.

For high-load bots and applications processing thousands of messages per second, this constant interpretation becomes a major CPU bottleneck.

Fast-Filter solves this. It keeps the exact same, intuitive F syntax but acts as a Lazy JIT Compiler. The first time a filter is resolved, it dynamically compiles the filter's syntax tree into a native, single-line Python lambda function, which is then reused for subsequent events.

Quickstart

Get up and running in less than 30 seconds.

1. Install

[!NOTE] PyPI Name Note: The package is currently published on PyPI as fast-magic-filter while PyPI support ticket #11230 is under review. The Python import name is always fast_filter.

pip install fast-magic-filter

2. Copy & Run

from fast_filter import F

# 1. Define your filter (exact same F-syntax)
my_filter = (F.from_user.role == "admin") & (F.text.startswith("/alert"))

# 2. Resolve immediately against any object/dict
class Message:
    def __init__(self, text, role):
        self.text = text
        self.from_user = type("User", (), {"role": role})()

msg = Message("/alert high CPU usage", "admin")

# The first call JIT-compiles the lambda; subsequent calls run at native speed
assert my_filter.resolve(msg) is True

Measured Performance

Benchmarks run with 100,000 iterations comparing fast-filter against magic-filter:

• Simple Attribute Access (F.from_user.id == 1): ~6.1x faster.
• Logic & Methods (role == 'admin' & text.startswith): ~6.0x faster.
• Mapping & Aggregators (tags[...].len().any()): ~20.6x faster.

[!TIP] Try running the benchmarks locally to see the speedup on your machine:

python benchmarks/final_report.py

Sane Defaults & Fixes

Fast-Filter is not just faster; it fixes several behavioral quirks of magic-filter:

1. RegExp Everywhere: Magic-filter uses re.match (matching only the beginning of a string). Fast-filter uses re.search (matching anywhere), which is the behavior most developers expect.
2. Multi-Level Mapping: Supports arbitrary depth nested sequence mapping (e.g. F.matrix[...][...].val > 0).
3. Sane None Logic: Comparing a missing attribute in magic-filter (e.g., F.missing == None) resolves to None. In Fast-Filter, this evaluates to True, consistent with standard Python logic.
4. Exception-Free Compilation: Fast-Filter compiles code with built-in safety guards, ensuring that missing attributes or type conflicts do not raise uncaught exceptions but safely return None or False.

What to Read Next?

• GUIDE: Explore advanced features like value capturing with .as_() & .extract(), slicing, and bitwise operations.
• COMPARISON: Detailed feature-by-feature matrix comparing Fast-Filter and Magic-Filter.

Contribution

If you find this library useful, please give it a star on GitHub! Feel free to open issues and pull requests to help improve the project.

License

This project is licensed under the Mozilla Public License 2.0 (MPL 2.0). See the LICENSE file for details.

Copyright (c) 2025-2026 Dmitrii Gagarin aka madgagarin.