Skip to main content

Parses query args or body parameters in sanic using type annotations

Project description

Build Status Latest Version Python Support


Parses query parameters and json body parameters for Sanic using type annotations.


Please fill out this survey if you are using Sanicargs, we are gathering feedback :-)


Install with pip

$ pip install sanicargs


Use the parse_parameters decorator to parse query parameters (GET) or body parameters (POST) and type cast them together with path params in Sanic's routes or blueprints like in this example below:

import datetime
from sanic import Sanic, response
from sanicargs import parse_parameters

app = Sanic("test_sanic_app")

@app.route("/me/<id>/birthdate", methods=['GET'])
async def test_datetime(req, id: str, birthdate: datetime.datetime):
    return response.json({
        'id': id, 
        'birthdate': birthdate.isoformat()

if __name__ == "__main__":"", port=8080, access_log=False, debug=False)

Test it running with

$ curl ''

Query parameters

  • str : ex: ?message=hello world
  • int : ex: ?age=100
  • bool : ex: ?missing=false
  • datetime.datetime : ex: ?currentdate=2017-10-30T10:10:30 or 2017-10-30
  • : ex: ?birthdate=2017-10-30
  • List[str] : ex: ?words=you,me,them,we

JSON body parameters

{ "message": "hello word", "age": 100, "missing": false, "currentDate": "2017-10-30", "currentDateTime": "2017-10-30T10:10:30", "words": ["you", "me", "them", "we"] }

Note about datetimes

Dates and datetimes are parsed without timezone information giving you a "naive datetime" object. See the note on datetime.timestamp() about handling timezones if you require epoch format timestamps.

Important notice about decorators

The sequence of decorators is, as usual, important in Python.

You need to apply the parse_parameters decorator as the first one executed which means closest to the def.

request is mandatory!

You should always have request as the first argument in your function in order to use parse_parameters.

Note that request arg can be renamed and even type-annotated as long as it is the first arg.

parse_query_args deprecation

parse_query_args will be deprecated in future version in favor of parse_parameters Currently it is still usable as a legacy decorator

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sanicargs-2.1.0.tar.gz (5.0 kB view hashes)

Uploaded source

Built Distribution

sanicargs-2.1.0-py3-none-any.whl (5.0 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page