Contents

Filters

The Filters library provides an easy and readable way to create complex data validation and processing pipelines, including:

Validating complex JSON structures in API requests or config files.
Parsing timestamps and converting to UTC.
Converting Unicode strings to NFC, normalising line endings and removing unprintable characters.
Decoding Base64, including URL-safe variants.

And much more!

The output from one filter can be “piped” into the input of another, enabling you to “chain” filters together to quickly and easily create complex data pipelines.

Philosophy

Filters applies the UNIX philosophy to data validation: do one thing well, and compose small tools together.

Each filter performs a single, focused task. Chain them using the | operator to build sophisticated validation pipelines that are easy to read and maintain.

Type-safe: Full type hint support for IDE autocomplete and static analysis.

Opinionated: Makes deliberate choices to handle common issues automatically (Unicode normalisation, UTC conversion, etc.) so you write less boilerplate.

Quick Start

Install via pip:

pip install phx-filters

Create a validation schema:

import filters as f
from decimal import Decimal

# Define your schema
schema = f.FilterRunner(
    f.FilterMapper({
        "lat": f.Required | f.Decimal | f.Min(Decimal(-90)) | f.Max(Decimal(90)),
        "lon": f.Required | f.Decimal | f.Min(Decimal(-180)) | f.Max(Decimal(180)),
        "name": f.Required | f.Unicode | f.Strip,
    })
)

# Validate data
result = schema.apply({"lat": "42.36", "lon": "-71.06", "name": "  Boston  "})

if result.is_valid():
    clean_data = result.value
    # clean_data = {
    #     "lat": Decimal("42.36"),
    #     "lon": Decimal("-71.06"),
    #     "name": "Boston"
    # }
else:
    errors = result.error_messages
    # errors = {"lat": ["Decimal value is too small (minimum is -90)."]}

FilterRunner provides a familiar interface similar to Django forms, making it easy to integrate into web applications.

Examples

Validate API Request Data

When building APIs, you need to validate request payloads and handle errors gracefully. FilterRunner makes this straightforward:

from decimal import Decimal
import filters as f

# Define validation for a user registration endpoint
user_schema = f.FilterRunner(
    f.FilterMapper(
        {
            "email": f.Required | f.Unicode | f.Strip | f.MaxLength(254),
            "age": f.Required | f.Int | f.Min(13) | f.Max(120),
            "timezone": f.Decimal | f.Min(Decimal("-15")) | f.Max(Decimal("15")),
        },
        allow_extra_keys=False,
    )
)

# Validate incoming data
result = user_schema.apply(request_data)

if result.is_valid():
    # Save to database
    user = User.create(**result.value)
else:
    # Return validation errors to client
    return {"errors": result.error_messages}, 400

Parse Complex JSON Structures

Filters excels at validating nested data structures with complex constraints:

schema = f.FilterRunner(
    f.JsonDecode |
    f.FilterMapper(
        {
            "birthday": f.Date,
            "gender": f.CaseFold | f.Choice(choices={"f", "m", "n"}),
            "utcOffset": (
                f.Decimal |
                f.Min(Decimal("-15")) |
                f.Max(Decimal("15")) |
                f.Round(to_nearest="0.25")
            ),
        },
        allow_extra_keys=False,
        allow_missing_keys=False,
    )
)

result = schema.apply('{"birthday":"1879-03-14", "gender":"M", "utcOffset":"1"}')

Process Lists of Data

Use FilterRepeater to apply validation to every item in a collection:

# Clean a list of user-generated strings
schema = f.FilterRunner(
    f.FilterRepeater(f.Unicode | f.Strip | f.MaxLength(100))
)

result = schema.apply([
    "  some text  ",
    b"\xe2\x99\xaa unicode bytes ",
    "another string",
])

For more examples and detailed documentation, explore the sections in the table of contents above.

Features

Composable: Chain filters using the | operator
Type-safe: Full type hint support for IDE autocomplete and mypy
Familiar API: FilterRunner provides Django-form-like interface
Extensible: Create custom filters by extending BaseFilter
Battle-tested: Used in production applications for years
Well-documented: Comprehensive documentation with examples

Requirements

Filters is known to be compatible with the following Python versions:

3.14
3.13
3.12

Note

I’m only one person, so to keep from getting overwhelmed, I’m only committing to supporting the 3 most recent versions of Python.

Installation

Install the latest stable version via pip:

pip install phx-filters

Important

Make sure to install phx-filters, not filters. I created the latter at a previous job years ago, and after I left they never touched that project again and stopped responding to my emails — so in the end I had to fork it 🤷

Extensions

The following extensions are available:

Django Filters: Adds filters designed to work with Django applications. To install:
```
pip install phx-filters[django]
```
ISO Filters: Adds filters for interpreting standard codes and identifiers. To install:
```
pip install phx-filters[iso]
```

Tip

To install multiple extensions, separate them with commas, e.g.:

pip install phx-filters[django,iso]

Happy filtering!