magic-filter

1.0.12 · active · verified Sat Apr 11

magic-filter is a lightweight Python library designed to simplify conditional logic, particularly useful in event-driven programming like Telegram bots (e.g., aiogram). It provides a fluent, declarative syntax for building complex filtering expressions using the `F` object, allowing developers to write more readable and concise conditions. It is currently at version 1.0.12 and sees active, though not strictly regular, development with several minor releases annually.

Warnings

breaking The `extract` operation for negative results (conditions not met) now returns `None` instead of `False`. Code that explicitly checked for `False` will need adjustment.
Fix: Update logic to check for `None` or handle both `None` and `False` if maintaining compatibility with older versions.
gotcha The `__bool__` method for `F` objects now always returns `True`. This means `if F.attribute:` will always evaluate to true, regardless of whether `F.attribute` would pass a condition. This can be misleading if expecting conditional evaluation.
Fix: Always use explicit comparison or function calls for conditional logic (e.g., `if F.attribute == 'value':` or `if some_filter(data):`) instead of relying on implicit boolean conversion of the filter object itself.
breaking MagicFilter instances can no longer be used as iterable objects. Attempting to iterate over an `F` object will now raise an error.
Fix: Remove any code attempting to iterate over `F` objects. `magic-filter` is designed for building conditions, not for direct iteration.
gotcha Starting from 1.0.5, `TypeError` and `ValueError` are suppressed when calling function operations on `F` objects. This means operations that previously might have failed with an error (e.g., `F.attribute.len()` on `None`) will now silently fail the filter condition.
Fix: Be aware that errors from underlying data access or method calls are now absorbed. If you rely on such errors for debugging or specific error handling, you might need to pre-validate data or use explicit checks before applying `magic-filter` conditions.

Install

pip install magic-filter Install stable version

Imports

F
```
from magic_filter import F
```
The primary 'F' object is directly available from the top-level package.

Quickstart

This quickstart demonstrates how to define and apply simple and complex filters using the `F` object. It shows attribute access, method calls, logical operators (`&`, `|`, `~`), and how to use `magic-filter` with dictionaries and lists.

from magic_filter import F

data = {"text": "Hello World", "user": {"id": 123, "is_bot": False}}

# Define filters using the F object
is_admin = F.user.id == 123
starts_with_H = F.text.startswith("H")

# Apply a single filter
print(f"Is admin: {is_admin(data)}")

# Combine filters with logical operators
complex_filter = is_admin & starts_with_H & ~F.user.is_bot
print(f"Complex filter result: {complex_filter(data)}")

# Using with lists
numbers = [1, 5, 10, 3, 7]
gt_5 = F > 5
filtered_numbers = [num for num in numbers if gt_5(num)]
print(f"Numbers greater than 5: {filtered_numbers}")

view raw JSON →