Registry / magic-filter

magic-filter

library1.0.12pypypi✓ verified 24d ago

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.

pip install magic-filter

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · MAGIC-FILTER

magic-filter

pythonv1.0.12

Install

1.6s avg

Import

17ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.12 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.018s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.016s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ from magic_filter import F

✗ from magic_filter.magic_filter import F

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

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}")

Debug

Known issues

breakingThe `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.

affects: >=1.0.12

gotchaThe `__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.

affects: >=1.0.11

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

affects: >=1.0.9

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

affects: >=1.0.5

Errors

Common errors & fixes

AttributeError: 'MagicFilter' object has no attribute 'startswith'

The `F` object itself doesn't have methods like `startswith`; these methods are applied to attributes accessed via `F`, such as `F.text.startswith()`.

fix

Access the intended attribute (e.g., `F.text`) before calling the method. For example, use `F.text.startswith('your_prefix')`.

TypeError: 'MagicFilter' object is not callable

The `F` object from `magic-filter` is an instance used for building expressions, not a function that can be called directly.

fix

Do not attempt to call `F` as a function. Instead, use its attributes and operators (e.g., `F.text`, `F.text == 'value'`) to construct filter expressions.

ImportError: cannot import name 'f' from 'magic_filter'

The `F` object is imported with an uppercase 'F', but the user attempted to import it with a lowercase 'f'. Python imports are case-sensitive.

fix

Ensure that `F` is imported with the correct uppercase 'F': `from magic_filter import F`.

TypeError: MagicFilter object cannot be interpreted as a boolean value

The `MagicFilter` object (e.g., `F`) represents a filtering expression and cannot be directly evaluated as a boolean without a comparison or specific attribute access.

fix

Use `F` with comparison operators (e.g., `F.text == 'value'`) or access its attributes (e.g., `F.is_something`) to create a boolean expression; do not use `F` directly in an `if` statement.

Upgrade

Version history

1.0.12latest on PyPI · released Oct 1, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/aiogram/magic-filter ↗

packagehttps://pypi.org/project/magic-filter/ ↗

docshttps://docs.aiogram.dev/en/dev-3.x/dispatcher/filters/magic_filters.html ↗