Flask Parameter Validation

Get and validate all Flask input parameters with ease.

Install

• Pip: Install with pip install flask_parameter_validation.
• Manually:
  • git clone https://github.com/Ge0rg3/flask-parameter-validation.git
  • python setup.py install

Usage Example

from flask import Flask
from typing import Optional
from flask_parameter_validation import ValidateParameters, Route, Json, Query
from datetime import datetime
from enum import Enum

class AccountStatus(int, Enum):  # In Python 3.11 or later, subclass IntEnum from enum package instead of int, Enum
  ACTIVE = 1
  DISABLED = 0

class UserType(str, Enum):  # In Python 3.11 or later, subclass StrEnum from enum package instead of str, Enum
  USER = "user"
  SERVICE = "service"

app = Flask(__name__)

@app.route("/update/<int:id>", methods=["POST"])
@ValidateParameters()
def hello(
        id: int = Route(),
        username: str = Json(min_str_length=5, blacklist="<>"),
        age: int = Json(min_int=18, max_int=99),
        nicknames: list[str] = Json(),
        date_of_birth: datetime = Json(),
        password_expiry: Optional[int] = Json(5),
        is_admin: bool = Query(False),
        user_type: UserType = Json(alias="type"),
        status: AccountStatus = Json()
     ):
    return "Hello World!"

if __name__ == "__main__":
    app.run()

Usage

To validate parameters with flask-parameter-validation, two conditions must be met.

1. The @ValidateParameters() decorator must be applied to the function
2. Type hints (supported types) and a default of a subclass of Parameter must be supplied per parameter

Enable and customize Validation for a Route with the @ValidateParameters decorator

The @ValidateParameters() decorator takes parameters that alter route validation behavior or provide documentation information:

Overwriting Default Errors

By default, the error messages are returned as a JSON response, with the detailed error in the "error" field, eg:

{
    "error": "Parameter 'age' must be type 'int'"
}

However, this can be edited by passing a custom error function into the ValidateParameters() decorator. For example:

def error_handler(err):
    error_name = type(err)
    error_parameters = err.args
    error_message = str(err)
    return {
        "error_name": type(err).__name__,
        "error_parameters": err.args,
        "error_message": str(err)
    }, 400

@app.route(...)
@ValidateParameters(error_handler)
def api(...)

Specify Parameter types and constraints with type hints and subclasses of Parameter

Parameter Class

The Parameter class provides a base for validation common among all input types, all location-specific classes extend Parameter. These subclasses are:

Note: "POST Methods" refers to the HTTP methods that send data in the request body, such as POST, PUT, PATCH and DELETE. Although sending data via some methods such as DELETE is not standard, it is supported by Flask and this library.

MultiSource Parameters

Using the MultiSource parameter type, parameters can be accepted from any combination of Parameter subclasses. Example usage is as follows:

@app.route("/")
@app.route("/<v>")  # If accepting parameters by Route and another type, a path with and without that Route parameter must be specified
@ValidateParameters()
def multi_source_example(
        value: int = MultiSource(Route, Query, Json, min_int=0)
)

The above example will accept parameters passed to the route through Route, Query, and JSON Body.

Note: "POST Methods" refers to the HTTP methods that send data in the request body, such as POST, PUT, PATCH and DELETE. Although sending data via some methods such as DELETE is not standard, it is supported by Flask and this library.

Type Hints and Accepted Input Types

Type Hints allow for inline specification of the input type of a parameter. Some types are only available to certain Parameter subclasses.

These can be used in tandem to describe a parameter to validate: parameter_name: type_hint = ParameterSubclass()

• parameter_name: The field name itself, such as username
• type_hint: The expected Python data type
• ParameterSubclass: An instance of a subclass of Parameter

Validation with arguments to Parameter

Validation beyond type-checking can be done by passing arguments into the constructor of the Parameter subclass. The arguments available for use on each type hint are:

These validators are passed into the Parameter subclass in the route function, such as:

• username: str = Json(default="defaultusername", min_length=5)
• profile_picture: werkzeug.datastructures.FileStorage = File(content_types=["image/png", "image/jpeg"])
• filter: str = Query()

Custom Validation Function

Custom validation functions passed into the func property can be used to validate an input against custom logic and return customized error responses for that validation

Example custom validation functions are below:

def is_even(val: int):
    """Return a single bool, True if valid, False if invalid"""
    return val % 2 == 0

def is_odd(val: int):
    """Return a tuple with a bool, as above, and the error message if the bool is False"""
    return val % 2 != 0, "val must be odd"

Configuration Options

API Documentation Configuration

• FPV_DOCS_SITE_NAME: str: Your site's name, to be displayed in the page title, default: Site
• FPV_DOCS_CUSTOM_BLOCKS: array: An array of dicts to display as cards at the top of your documentation, with the (optional) keys:
  • title: Optional[str]: The title of the card
  • body: Optional[str] (HTML allowed): The body of the card
  • order: int: The order in which to display this card (out of the other custom cards)
• FPV_DOCS_DEFAULT_THEME: str: The default theme to display in the generated webpage

See the API Documentation below for other information on API Documentation generation

Validation Behavior Configuration

• FPV_BLANK_NONE: bool: Globally override the default blank_none behavior for routes in your application, defaults to False if unset

API Documentation

Using the data provided through parameters, docstrings, and Flask route registrations, Flask Parameter Validation can generate API Documentation in various formats. To make this easy to use, it comes with a Blueprint and the output shown below and configuration options above:

Included Blueprint

The documentation blueprint can be added using the following code:

from flask_parameter_validation.docs_blueprint import docs_blueprint
...
app.register_blueprint(docs_blueprint)

The default blueprint adds two GET routes:

• /: HTML Page with Bootstrap CSS and toggleable light/dark mode
• /json: Non-standard Format JSON Representation of the generated documentation

The /json route yields a response with the following format:

{
  "custom_blocks": "<array entered in the FPV_DOCS_CUSTOM_BLOCKS config option, default: []>",
  "default_theme": "<string entered in the FPV_DOCS_DEFAULT_THEME config option, default: 'light'>",
  "docs": "<see get_route_docs() return value format below>",
  "site_name": "<string entered in the FPV_DOCS_SITE_NAME config option, default: 'Site'"
}

Example with included Blueprint

Code:

@config_api.get("/")
@ValidateParameters()
def get_all_configs():
    """
    Get the System Configuration
    Returns:
    <code>{"configs":
        [{"id": int,
        "module": str,
        "name": str,
        "description": str,
        "value": str}, ...]
    }</code>
    """
    system_configs = []
    for system_config in SystemConfig.query.all():
        system_configs.append(system_config.toDict())
    return resp_success({"configs": system_configs})

@config_api.post("/<int:config_id>")
@ValidateParameters()
def edit_config(
        config_id: int = Route(comment="The ID of the Config Record to Edit"),
        value: str = Json(max_str_length=2000, comment="The value to set in the Config Record")
):
    """Edit a specific System Configuration value"""
    config = SystemConfig.get_by_id(config_id)
    if config is None:
        return resp_not_found("No link exists with ID " + str(config_id))
    else:
        config.update(value)
        return resp_success()

Documentation Generated:

Custom Blueprint

If you would like to use your own blueprint, you can get the raw data from the following function:

from flask_parameter_validation.docs_blueprint import get_route_docs
...
get_route_docs()

get_route_docs() return value format

This method returns an object with the following structure:

[
  {
    "rule": "/path/to/route",
    "methods": ["HTTPVerb"],
    "docstring": "String, unsanitized of HTML Tags",
    "decorators": ["@decorator1", "@decorator2(param)"],
    "args": {
      "<Subclass of Parameter this route uses>": [
        {
          "name": "Argument Name",
          "type": "Argument Type",
          "loc_args": {
            "<Name of argument passed to Parameter Subclass>": "Value passed to Argument",
            "<Name of another argument passed to Parameter Subclass>": 0
          }
        }
      ],
      "<Another Subclass of Parameter this route uses>": []
    }
  },

  ...
]

JSON Schema Validation

An example of the JSON Schema validation is provided below:

json_schema = {
    "type": "object",
    "required": ["user_id", "first_name", "last_name", "tags"],
    "properties": {
        "user_id": {"type": "integer"},
        "first_name": {"type": "string"},
        "last_name": {"type": "string"},
        "tags": {
            "type": "array",
            "items": {"type": "string"}
        }
    }
}

@api.get("/json_schema_example")
@ValidateParameters()
def json_schema(data: dict = Json(json_schema=json_schema)):
    return jsonify({"data": data})

Contributions

Many thanks to all those who have made contributions to the project:

• d3-steichman/smt5541: API documentation, custom error handling, datetime validation and bug fixes
• summersz: Parameter aliases, async support, form type conversion and list bug fixes
• Garcel: Allow passing custom validator function
• iml1111: Implement regex validation
• borisowww: Fix file handling bugs
• Charlie-Mindified: Fix JSON handling bug
• dkassen: Helped to resolve broken list parsing logic