fast-magic-filter 1.0.0.post1

An ultimately fast, zero-dependency declarative filter and introspection library for Python, compiled using JIT.

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

pip install fast-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() > 0): ~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. 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.
3. 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.