tessl/pypi-flask-restplus
Fully featured framework for fast, easy and documented API development with Flask
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
request-parsing.mddocs/
Request Parsing
Request parsing system for handling URL parameters, form data, JSON payloads, and file uploads with validation and type conversion. Flask-RESTPlus provides a comprehensive request parser that integrates with automatic documentation generation.
Capabilities
RequestParser Class
Main class for parsing and validating request data from various sources.
class RequestParser:
def __init__(self, argument_class=None, result_class=None, trim=False, bundle_errors=False):
"""
Initialize the request parser.
Args:
argument_class (class, optional): Custom Argument class
result_class (class, optional): Custom result class
trim (bool): Automatically trim string values
bundle_errors (bool): Return all validation errors at once
"""
def add_argument(self, name, dest=None, type=str, location=('json', 'form', 'args'),
required=False, default=None, help=None, action='store',
choices=None, ignore=False, case_sensitive=True, store_missing=True,
nullable=True, **kwargs):
"""
Add an argument to the parser.
Args:
name (str): Argument name
dest (str, optional): Destination attribute name
type (callable): Type conversion function
location (tuple or str): Where to look for the argument
required (bool): Whether argument is required
default: Default value if argument is missing
help (str, optional): Help text for documentation
action (str): How to handle the argument ('store', 'store_const', 'store_true', 'store_false', 'append', 'append_const', 'count')
choices (list, optional): List of allowed values
ignore (bool): Ignore parsing errors
case_sensitive (bool): Case sensitive argument matching
store_missing (bool): Store missing arguments with None value
nullable (bool): Allow None values
**kwargs: Additional argument options
Returns:
Argument: The added argument instance
"""
def parse_args(self, req=None, strict=False):
"""
Parse arguments from the request.
Args:
req (Request, optional): Flask request object (uses current request if None)
strict (bool): Raise exception on unknown arguments
Returns:
ParseResult: Parsed arguments
"""
def copy(self):
"""
Create a copy of this parser.
Returns:
RequestParser: Copied parser
"""
def replace_argument(self, name, **kwargs):
"""
Replace an existing argument.
Args:
name (str): Argument name to replace
**kwargs: New argument parameters
Returns:
Argument: The replaced argument
"""
def remove_argument(self, name):
"""
Remove an argument from the parser.
Args:
name (str): Argument name to remove
"""Argument Class
Individual argument configuration for request parsing.
class Argument:
def __init__(self, name, default=None, dest=None, required=False, ignore=False,
type=str, location=('json', 'form', 'args'), choices=None,
action='store', help=None, operators=('=',), case_sensitive=True,
store_missing=True, trim=False, nullable=True, **kwargs):
"""
Initialize an argument.
Args:
name (str): Argument name
default: Default value
dest (str, optional): Destination attribute name
required (bool): Whether argument is required
ignore (bool): Ignore parsing errors
type (callable): Type conversion function
location (tuple or str): Request locations to search
choices (list, optional): Allowed values
action (str): Parsing action
help (str, optional): Help text
operators (tuple): Allowed operators for filtering
case_sensitive (bool): Case sensitive matching
store_missing (bool): Store missing arguments
trim (bool): Trim string values
nullable (bool): Allow None values
**kwargs: Additional options
"""
def source(self, request):
"""
Extract argument values from request.
Args:
request (Request): Flask request object
Returns:
list: Extracted values
"""
def convert(self, value, op):
"""
Convert argument value to the specified type.
Args:
value: Raw argument value
op (str): Operator used
Returns:
Converted value
"""
def handle_validation_error(self, error, bundle_errors):
"""
Handle validation errors.
Args:
error (Exception): Validation error
bundle_errors (bool): Whether to bundle errors
"""
def parse(self, request, bundle_errors=False):
"""
Parse this argument from the request.
Args:
request (Request): Flask request object
bundle_errors (bool): Bundle all errors
Returns:
tuple: (parsed_value, found_in_request)
"""ParseResult Class
Container for parsed arguments with attribute-style access.
class ParseResult(dict):
def __init__(self, *args, **kwargs):
"""
Initialize parse result.
Args:
*args: Dictionary arguments
**kwargs: Keyword arguments
"""
def __getattr__(self, name):
"""
Get parsed argument by attribute access.
Args:
name (str): Argument name
Returns:
Parsed argument value
"""
def __setattr__(self, name, value):
"""
Set parsed argument by attribute access.
Args:
name (str): Argument name
value: Argument value
"""Constants and Helpers
Request parsing constants and utility mappings.
LOCATIONS: dict # Maps Flask-RESTPlus locations to Swagger parameter types
PY_TYPES: dict # Maps Python types to Swagger types
SPLIT_CHAR: str = ',' # Default character for splitting array valuesUsage Examples
Basic Request Parsing
from flask_restplus import Api, Resource, reqparse
api = Api()
# Create a request parser
parser = reqparse.RequestParser()
# Add arguments
parser.add_argument('name', type=str, required=True, help='Name is required')
parser.add_argument('age', type=int, location='args', help='Age parameter')
parser.add_argument('active', type=bool, default=True, help='Active status')
@api.route('/users')
class UserList(Resource):
@api.expect(parser)
def post(self):
# Parse arguments from request
args = parser.parse_args()
# Access parsed values
name = args['name'] # or args.name
age = args['age']
active = args['active']
# Process the data...
return {'message': f'Created user {name}, age {age}, active: {active}'}, 201Argument Locations
from flask_restplus import reqparse
parser = reqparse.RequestParser()
# URL query parameters (?param=value)
parser.add_argument('page', type=int, location='args', default=1)
# Form data (POST form submission)
parser.add_argument('username', type=str, location='form', required=True)
# JSON payload data
parser.add_argument('data', type=dict, location='json')
# HTTP headers
parser.add_argument('api-key', location='headers', required=True)
# File uploads
parser.add_argument('upload', location='files', type=FileStorage)
# Cookies
parser.add_argument('session_id', location='cookies')
# Multiple locations (search in order)
parser.add_argument('token', location=['headers', 'args'], required=True)
# All locations (json, form, args)
parser.add_argument('flexible_param', location=('json', 'form', 'args'))Type Conversion and Validation
from flask_restplus import reqparse
from datetime import datetime
parser = reqparse.RequestParser()
# Built-in type conversions
parser.add_argument('count', type=int, help='Must be an integer')
parser.add_argument('rate', type=float, help='Must be a float')
parser.add_argument('enabled', type=bool, help='Boolean value')
# Custom type conversion function
def date_type(date_str):
"""Convert date string to datetime object."""
try:
return datetime.strptime(date_str, '%Y-%m-%d')
except ValueError:
raise ValueError(f"Invalid date format: {date_str}. Use YYYY-MM-DD")
parser.add_argument('start_date', type=date_type, help='Date in YYYY-MM-DD format')
# Choices validation
parser.add_argument('status',
choices=['active', 'inactive', 'pending'],
help='Status must be one of: active, inactive, pending')
# List/array arguments
parser.add_argument('tags', action='append', help='Can be specified multiple times')
# Store constants
parser.add_argument('verbose', action='store_true', help='Enable verbose mode')
parser.add_argument('quiet', action='store_false', help='Disable quiet mode')Advanced Parsing Features
from flask_restplus import reqparse
# Bundle all validation errors
parser = reqparse.RequestParser(bundle_errors=True)
parser.add_argument('name', type=str, required=True, trim=True)
parser.add_argument('email', type=str, required=True)
parser.add_argument('age', type=int, required=True)
@api.route('/users')
class UserCreate(Resource):
@api.expect(parser)
def post(self):
try:
args = parser.parse_args()
# All arguments validated successfully
return {'message': 'User created', 'data': args}, 201
except Exception as e:
# Returns all validation errors at once:
# {
# "message": "Input payload validation failed",
# "errors": {
# "name": "Name is required",
# "email": "Email is required",
# "age": "Age must be an integer"
# }
# }
return {'error': str(e)}, 400Parser Inheritance and Modification
from flask_restplus import reqparse
# Base parser with common arguments
base_parser = reqparse.RequestParser()
base_parser.add_argument('page', type=int, location='args', default=1)
base_parser.add_argument('per_page', type=int, location='args', default=10)
# Create specialized parsers by copying
user_parser = base_parser.copy()
user_parser.add_argument('name', type=str, location='args')
user_parser.add_argument('active', type=bool, location='args')
product_parser = base_parser.copy()
product_parser.add_argument('category', type=str, location='args')
product_parser.add_argument('min_price', type=float, location='args')
product_parser.add_argument('max_price', type=float, location='args')
# Modify existing arguments
user_parser.replace_argument('per_page', type=int, default=20, help='Users per page')
# Remove arguments
user_parser.remove_argument('page') # Remove paginationFile Upload Handling
from flask_restplus import reqparse
from werkzeug.datastructures import FileStorage
upload_parser = reqparse.RequestParser()
# Single file upload
upload_parser.add_argument('file',
location='files',
type=FileStorage,
required=True,
help='File to upload')
# Multiple file uploads
upload_parser.add_argument('attachments',
location='files',
type=FileStorage,
action='append',
help='Multiple files can be uploaded')
@api.route('/upload')
class FileUpload(Resource):
@api.expect(upload_parser)
def post(self):
args = upload_parser.parse_args()
uploaded_file = args['file']
if uploaded_file and uploaded_file.filename:
# Save the file
filename = secure_filename(uploaded_file.filename)
uploaded_file.save(os.path.join('/uploads', filename))
return {'message': f'File {filename} uploaded successfully'}, 201
return {'error': 'No file provided'}, 400Integration with API Documentation
from flask_restplus import Api, Resource, reqparse, fields
api = Api()
# Parser automatically generates Swagger documentation
user_parser = reqparse.RequestParser()
user_parser.add_argument('name',
type=str,
required=True,
help='User full name (required)')
user_parser.add_argument('email',
type=str,
required=True,
help='User email address (required)')
user_parser.add_argument('age',
type=int,
help='User age (optional)')
user_parser.add_argument('active',
type=bool,
default=True,
help='Account status (default: true)')
@api.route('/users')
class UserList(Resource):
@api.expect(user_parser) # Documents expected parameters
def post(self):
"""Create a new user"""
args = user_parser.parse_args()
# Implementation...
return {'message': 'User created'}, 201Error Handling and Validation
from flask_restplus import reqparse, abort
parser = reqparse.RequestParser()
def validate_positive_int(value):
"""Custom validator for positive integers."""
try:
int_value = int(value)
if int_value <= 0:
raise ValueError("Must be a positive integer")
return int_value
except (ValueError, TypeError):
raise ValueError("Must be a valid positive integer")
parser.add_argument('quantity',
type=validate_positive_int,
required=True,
help='Quantity must be a positive integer')
@api.route('/orders')
class OrderCreate(Resource):
@api.expect(parser)
def post(self):
try:
args = parser.parse_args()
quantity = args['quantity']
# Process order...
return {'message': f'Order created for {quantity} items'}, 201
except Exception as e:
# Validation errors are automatically handled by Flask-RESTPlus
# and return appropriate error responses
abort(400, message=str(e))Complex Nested Parsing
from flask_restplus import reqparse
import json
parser = reqparse.RequestParser()
def json_type(value):
"""Parse JSON string into Python object."""
try:
return json.loads(value)
except (json.JSONDecodeError, TypeError):
raise ValueError("Must be valid JSON")
# Accept complex nested data as JSON strings
parser.add_argument('metadata',
type=json_type,
location='json',
help='Metadata as JSON object')
parser.add_argument('settings',
type=json_type,
location=['json', 'form'],
help='Settings configuration as JSON')
@api.route('/configure')
class Configuration(Resource):
@api.expect(parser)
def post(self):
args = parser.parse_args()
metadata = args['metadata'] # Already parsed as dict/list
settings = args['settings'] # Already parsed as dict/list
# Use the parsed objects directly
return {
'message': 'Configuration updated',
'metadata_keys': list(metadata.keys()) if isinstance(metadata, dict) else [],
'settings_keys': list(settings.keys()) if isinstance(settings, dict) else []
}, 200Install with Tessl CLI
npx tessl i tessl/pypi-flask-restplus