{"id":2990,"library":"magic-filter","title":"magic-filter","description":"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.","status":"active","version":"1.0.12","language":"en","source_language":"en","source_url":"https://github.com/aiogram/magic-filter","tags":["filtering","aiogram","telegram","conditional-logic","declarative"],"install":[{"cmd":"pip install magic-filter","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The primary 'F' object is directly available from the top-level package.","wrong":"from magic_filter.magic_filter import F","symbol":"F","correct":"from magic_filter import F"}],"quickstart":{"code":"from magic_filter import F\n\ndata = {\"text\": \"Hello World\", \"user\": {\"id\": 123, \"is_bot\": False}}\n\n# Define filters using the F object\nis_admin = F.user.id == 123\nstarts_with_H = F.text.startswith(\"H\")\n\n# Apply a single filter\nprint(f\"Is admin: {is_admin(data)}\")\n\n# Combine filters with logical operators\ncomplex_filter = is_admin & starts_with_H & ~F.user.is_bot\nprint(f\"Complex filter result: {complex_filter(data)}\")\n\n# Using with lists\nnumbers = [1, 5, 10, 3, 7]\ngt_5 = F > 5\nfiltered_numbers = [num for num in numbers if gt_5(num)]\nprint(f\"Numbers greater than 5: {filtered_numbers}\")","lang":"python","description":"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."},"warnings":[{"fix":"Update logic to check for `None` or handle both `None` and `False` if maintaining compatibility with older versions.","message":"The `extract` operation for negative results (conditions not met) now returns `None` instead of `False`. Code that explicitly checked for `False` will need adjustment.","severity":"breaking","affected_versions":">=1.0.12"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.11"},{"fix":"Remove any code attempting to iterate over `F` objects. `magic-filter` is designed for building conditions, not for direct iteration.","message":"MagicFilter instances can no longer be used as iterable objects. Attempting to iterate over an `F` object will now raise an error.","severity":"breaking","affected_versions":">=1.0.9"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.5"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}