Metadata-Version: 2.4
Name: fast-magic-filter
Version: 1.0.0
Summary: An ultimately fast, zero-dependency declarative filter and introspection library for Python, compiled using JIT.
Author-email: Dmitrii Gagarin <madgagarin@gmail.com>
Keywords: filter,magic-filter,jit,declarative,introspection
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: magic-filter>=1.0.12; extra == "test"
Dynamic: license-file

**EN** | [RU](docs/README.ru.md)

# Fast-Filter

[![PyPI version](https://img.shields.io/pypi/v/fast-magic-filter.svg)](https://pypi.org/project/fast-magic-filter/)
[![Python versions](https://img.shields.io/pypi/pyversions/fast-magic-filter.svg)](https://pypi.org/project/fast-magic-filter/)
[![License](https://img.shields.io/github/license/madgagarin/fast-filter.svg)](LICENSE)

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
```bash
pip install fast-filter
```

### 2. Copy & Run
```python
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:
> ```bash
> 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](docs/GUIDE.md)**: Explore advanced features like value capturing with `.as_()` & `.extract()`, slicing, and bitwise operations.
*   **[COMPARISON](docs/COMPARISON.md)**: 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](LICENSE) file for details.

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