tessl/pypi-flask-restx
Fully featured framework for fast, easy and documented API development with Flask
—
Pending
request-parsing.mddocs/
Request Parsing and Validation
Flask-RESTX provides a comprehensive request parsing system that declaratively extracts and validates data from various request sources including query parameters, form data, JSON body, headers, and uploaded files. The system automatically generates documentation and provides detailed error messages for validation failures.
Capabilities
RequestParser Class
Main class for defining and parsing request arguments with automatic validation and documentation generation.
class RequestParser:
def __init__(
self,
argument_class=None,
result_class=None,
trim=False,
bundle_errors=False
):
"""
Initialize a new request parser.
Parameters:
- argument_class: Custom Argument class to use
- result_class: Custom result class for parsed arguments
- trim: Whether to trim whitespace from string arguments
- bundle_errors: Whether to bundle validation errors
"""
def add_argument(
self,
name,
default=None,
dest=None,
required=False,
ignore=False,
type=str,
location=("json", "values"),
choices=(),
action='store',
help=None,
operators=('=',),
case_sensitive=True,
store_missing=True,
trim=False,
nullable=True
):
"""
Add an argument to be parsed from the request.
Parameters:
- name: Argument name or list of option strings
- default: Default value if argument is absent
- dest: Destination attribute name in parsed result
- required: Whether argument is required (raises error if missing)
- ignore: Whether to ignore type conversion failures
- type: Type conversion function (str, int, float, etc.)
- location: Request locations to search ('args', 'form', 'headers', 'json', 'files', 'cookies', 'values')
- choices: List of allowed values
- action: Action type ('store' or 'append')
- help: Help message for validation errors
- operators: List of operators for query parsing
- case_sensitive: Whether values are case sensitive
- store_missing: Whether to store default if missing
- trim: Whether to trim whitespace
- nullable: Whether null values are allowed
"""
def parse_args(self, req=None, strict=False):
"""
Parse arguments from request.
Parameters:
- req: Flask request object (uses current request if None)
- strict: Whether to raise error for unknown arguments
Returns:
ParseResult: Dictionary-like object with parsed arguments
"""
def copy(self):
"""Create a copy of this parser."""
def replace_argument(self, name, **kwargs):
"""Replace an existing argument definition."""
def remove_argument(self, name):
"""Remove an argument from the parser."""Argument Class
Individual argument definition with validation rules and documentation.
class Argument:
def __init__(
self,
name,
default=None,
dest=None,
required=False,
ignore=False,
type=str,
location=("json", "values"),
choices=(),
action='store',
help=None,
operators=('=',),
case_sensitive=True,
store_missing=True,
trim=False,
nullable=True
):
"""
Define a request argument with validation rules.
Parameters: Same as RequestParser.add_argument()
"""
def convert(self, value, op):
"""Convert and validate argument value."""
def source(self, request):
"""Extract argument values from request."""ParseResult Class
Result container for parsed arguments with dictionary-like access and attribute access.
class ParseResult(dict):
"""Dictionary-like container for parsed arguments."""
def __getattr__(self, name):
"""Access parsed arguments as attributes."""
def __setattr__(self, name, value):
"""Set parsed arguments as attributes."""Input Validation Functions
Pre-built validation functions for common data types and formats.
def boolean(value):
"""
Convert string to boolean.
Accepts: 'true', 'false', '1', '0', 'yes', 'no', 'on', 'off' (case insensitive)
Returns: bool
Raises: ValueError for invalid values
"""
def date_from_iso8601(value):
"""
Parse ISO8601 date string.
Parameters:
- value: ISO8601 date string (YYYY-MM-DD)
Returns: datetime.date object
Raises: ValueError for invalid format
"""
def datetime_from_iso8601(value):
"""
Parse ISO8601 datetime string.
Parameters:
- value: ISO8601 datetime string
Returns: datetime.datetime object
Raises: ValueError for invalid format
"""
def datetime_from_rfc822(value):
"""
Parse RFC822 datetime string.
Parameters:
- value: RFC822 datetime string
Returns: datetime.datetime object
Raises: ValueError for invalid format
"""
def ipv4(value):
"""
Validate IPv4 address.
Parameters:
- value: IP address string
Returns: str (validated IP address)
Raises: ValueError for invalid IP
"""
def ipv6(value):
"""
Validate IPv6 address.
Parameters:
- value: IP address string
Returns: str (validated IP address)
Raises: ValueError for invalid IP
"""
def ip(value):
"""
Validate IP address (IPv4 or IPv6).
Parameters:
- value: IP address string
Returns: str (validated IP address)
Raises: ValueError for invalid IP
"""
def natural(value):
"""
Validate natural number (positive integer).
Parameters:
- value: Value to validate
Returns: int (validated natural number)
Raises: ValueError for non-natural numbers
"""
def positive(value):
"""
Validate positive number (> 0).
Parameters:
- value: Value to validate
Returns: int or float (validated positive number)
Raises: ValueError for non-positive numbers
"""
def date(value):
"""
Parse date from various formats.
Parameters:
- value: Date string in various formats
Returns: datetime.date object
Raises: ValueError for unparseable dates
"""
def iso8601interval(value):
"""
Parse ISO8601 time interval.
Parameters:
- value: ISO8601 interval string
Returns: tuple of datetime objects (start, end)
Raises: ValueError for invalid intervals
"""Input Validation Classes
Advanced validation classes for complex validation rules.
class regex:
def __init__(self, pattern):
"""
Regular expression validator.
Parameters:
- pattern: Regular expression pattern string
"""
def __call__(self, value):
"""Validate value against pattern."""
class int_range:
def __init__(self, low, high, argument="argument"):
"""
Integer range validator.
Parameters:
- low: Minimum allowed value
- high: Maximum allowed value
- argument: Argument name for error messages
"""
def __call__(self, value):
"""Validate value is within range."""
class URL:
def __init__(
self,
check=False,
ip=False,
local=False,
port=False,
auth=False,
schemes=None,
domains=None,
exclude=None
):
"""
URL validator.
Parameters:
- check: Whether to check URL accessibility
- ip: Whether to allow IP addresses
- local: Whether to allow local URLs
- port: Whether to require port in URL
- auth: Whether to allow authentication in URL
- schemes: List of allowed schemes (http, https, etc.)
- domains: List of allowed domains
- exclude: List of excluded domains
"""
def __call__(self, value):
"""Validate URL format and rules."""
class email:
def __init__(
self,
check=False,
ip=False,
local=False,
domains=None,
exclude=None
):
"""
Email address validator.
Parameters:
- check: Whether to check domain accessibility
- ip: Whether to allow IP addresses in domain
- local: Whether to allow local addresses
- domains: List of allowed domains
- exclude: List of excluded domains
"""
def __call__(self, value):
"""Validate email address format and rules."""Usage Examples
Basic Request Parsing
from flask_restx import Resource, reqparse
parser = reqparse.RequestParser()
parser.add_argument('name', type=str, required=True, help='Name is required')
parser.add_argument('age', type=int, default=0, help='Age as integer')
parser.add_argument('active', type=bool, default=True)
class UserCreate(Resource):
def post(self):
args = parser.parse_args()
return {
'name': args.name,
'age': args.age,
'active': args.active
}Multiple Locations
# Parse from different request locations
parser = reqparse.RequestParser()
parser.add_argument('token', location=['headers'], required=True)
parser.add_argument('user_id', location=['json', 'form'], type=int)
parser.add_argument('filter', location=['args'], action='append')
class SecureResource(Resource):
def post(self):
args = parser.parse_args()
# args.token from headers
# args.user_id from JSON body or form data
# args.filter as list from query parameters
return {'received': args}Advanced Validation
from flask_restx import inputs
parser = reqparse.RequestParser()
parser.add_argument('email', type=inputs.email(), required=True)
parser.add_argument('url', type=inputs.url())
parser.add_argument('ip_address', type=inputs.ip)
parser.add_argument('date', type=inputs.date_from_iso8601)
parser.add_argument('priority', type=int, choices=[1, 2, 3, 4, 5])
parser.add_argument('pattern', type=inputs.regex(r'^[A-Z]{2,4}$'))
class ValidatedResource(Resource):
def post(self):
args = parser.parse_args() # Automatic validation
return {'validated_data': args}File Upload Parsing
from werkzeug.datastructures import FileStorage
upload_parser = reqparse.RequestParser()
upload_parser.add_argument('file',
location='files',
type=FileStorage,
required=True,
help='File upload is required')
upload_parser.add_argument('description',
location='form',
type=str)
class FileUpload(Resource):
def post(self):
args = upload_parser.parse_args()
file = args['file']
if file.filename == '':
return {'error': 'No file selected'}, 400
# Process file upload
return {
'filename': file.filename,
'description': args.get('description', '')
}Namespace Integration
from flask_restx import Namespace
api = Namespace('users', description='User operations')
# Reusable parser
user_parser = api.parser()
user_parser.add_argument('name', required=True, help='User name')
user_parser.add_argument('email', type=inputs.email(), required=True)
@api.route('/')
class UserList(Resource):
@api.expect(user_parser)
def post(self):
args = user_parser.parse_args()
return {'created_user': args}, 201Install with Tessl CLI
npx tessl i tessl/pypi-flask-restx