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
user_schema.apply(request_data)

if user_schema.is_valid():
    # Save to database
    user = User.create(**user_schema.cleaned_data)
else:
    # Return validation errors to client
    return {"errors": user_schema.errors}, 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, visit https://filters.readthedocs.io/

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]

1. Build the Project

1. Delete artefacts from previous builds, if applicable:

   rm dist/*

2. Run the build:

   uv build

3. The build artefacts will be located in the dist directory at the top level of the project.

2. Upload to PyPI

1. One-time setup — install keyring and store your PyPI token:

   uv tool install keyring
   uv tool update-shell
   keyring set https://upload.pypi.org/legacy/ __token__

2. Bump the version (updates pyproject.toml and re-locks uv.lock):

   uv version <version>

3. Upload build artefacts to PyPI:

   uv publish --username __token__

3. Create GitHub Release

1. Create an annotated tag and push to GitHub:

   git tag -a <version> -m "Release <version>"
   git push origin <version>

   <version> must match the version set in step 2 above.

2. Go to the Releases page for the repo.

3. Click Draft a new release.

4. Select the tag that you created in step 1.

5. Specify the title of the release (e.g., Filters v1.2.3).

6. Write a description for the release. Make sure to include: - Credit for code contributed by community members. - Significant functionality that was added/changed/removed. - Any backwards-incompatible changes and/or migration instructions. - SHA256 hashes of the build artefacts.

7. GPG-sign the description for the release (ASCII-armoured).

8. Attach the build artefacts to the release.

9. Click Publish release.