{"id":13690344,"url":"https://github.com/sloria/webargs-starlette","last_synced_at":"2025-04-16T03:46:08.565Z","repository":{"id":49210854,"uuid":"164156537","full_name":"sloria/webargs-starlette","owner":"sloria","description":"Declarative request parsing and validation for Starlette with webargs","archived":false,"fork":false,"pushed_at":"2022-12-04T19:50:52.000Z","size":81,"stargazers_count":39,"open_issues_count":3,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-29T04:43:19.005Z","etag":null,"topics":["asgi","marshmallow","parsing","request","starlette","validation","webargs"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sloria.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-04T21:28:58.000Z","updated_at":"2024-05-31T15:34:02.000Z","dependencies_parsed_at":"2023-01-23T06:31:42.790Z","dependency_job_id":null,"html_url":"https://github.com/sloria/webargs-starlette","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sloria%2Fwebargs-starlette","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sloria%2Fwebargs-starlette/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sloria%2Fwebargs-starlette/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sloria%2Fwebargs-starlette/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sloria","download_url":"https://codeload.github.com/sloria/webargs-starlette/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248617759,"owners_count":21134197,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asgi","marshmallow","parsing","request","starlette","validation","webargs"],"created_at":"2024-08-02T16:01:03.654Z","updated_at":"2025-04-16T03:46:08.546Z","avatar_url":"https://github.com/sloria.png","language":"Python","readme":"*****************\nwebargs-starlette\n*****************\n\n.. image:: https://badgen.net/pypi/v/webargs-starlette\n    :target: https://badge.fury.io/py/webargs-starlette\n    :alt: PyPI version\n\n.. image:: https://dev.azure.com/sloria/sloria/_apis/build/status/sloria.webargs-starlette?branchName=master\n    :target: https://dev.azure.com/sloria/sloria/_build/latest?definitionId=11\u0026branchName=master\n    :alt: Build status\n\n.. image:: https://badgen.net/badge/marshmallow/3\n    :target: https://marshmallow.readthedocs.io/en/stable/\n    :alt: marshmallow 3 compatible\n\n.. image:: https://badgen.net/badge/code%20style/black/000\n    :target: https://github.com/ambv/black\n    :alt: code style: black\n\n\nwebargs-starlette is a library for declarative request parsing and\nvalidation with `Starlette \u003chttps://github.com/encode/starlette\u003e`_,\nbuilt on top of `webargs \u003chttps://github.com/marshmallow-code/webargs\u003e`_.\n\nIt has all the goodness of `webargs \u003chttps://github.com/marshmallow-code/webargs\u003e`_, \nwith some extra sugar for type annotations.\n\n.. code-block:: python\n\n    import uvicorn\n    from starlette.applications import Starlette\n    from starlette.responses import JSONResponse\n    from webargs_starlette import use_annotations\n\n    app = Starlette()\n\n\n    @app.route(\"/\")\n    @use_annotations(location=\"query\")\n    async def index(request, name: str = \"World\"):\n        return JSONResponse({\"Hello\": name})\n\n\n    if __name__ == \"__main__\":\n        uvicorn.run(app, port=5000)\n\n    # curl 'http://localhost:5000/'\n    # {\"Hello\": \"World\"}\n    # curl 'http://localhost:5000/?name=Ada'\n    # {\"Hello\": \"Ada\"}\n\nInstall\n=======\n\n::\n\n    pip install -U webargs-starlette\n\n\nUsage\n=====\n\nParser Usage\n------------\n\nUse ``parser.parse`` to parse a Starlette ``Request`` with a\ndictionary of fields.\n\n.. code-block:: python\n\n    from starlette.applications import Starlette\n    from starlette.responses import JSONResponse\n    from webargs import fields\n    from webargs_starlette import parser\n\n    app = Starlette()\n\n\n    @app.route(\"/\")\n    async def homepage(request):\n        args = {\n            \"name\": fields.Str(required=True),\n            \"greeting\": fields.Str(load_default=\"hello\"),\n        }\n        parsed = await parser.parse(args, request)\n        greeting = parsed[\"greeting\"]\n        name = parsed[\"name\"]\n        return JSONResponse({\"message\": f\"{greeting} {name}\"})\n\n\nDecorators\n----------\n\nUse the ``use_args`` decorator to inject the parsed arguments\ndictionary into the handler function. The following snippet is equivalent to the\nfirst example.\n\n**Important**: Decorated functions MUST be coroutine functions.\n\n.. code-block:: python\n\n    from starlette.applications import Starlette\n    from starlette.responses import JSONResponse\n    from webargs import fields\n    from webargs_starlette import use_args\n\n    app = Starlette()\n\n\n    @app.route(\"/\")\n    @use_args(\n        {\"name\": fields.Str(required=True), \"greeting\": fields.Str(load_default=\"hello\")}\n    )\n    async def homepage(request, args):\n        greeting = args[\"greeting\"]\n        name = args[\"name\"]\n        return JSONResponse({\"message\": f\"{greeting} {name}\"})\n\n\nThe ``use_kwargs`` decorator injects the parsed arguments as keyword arguments.\n\n.. code-block:: python\n\n    from starlette.applications import Starlette\n    from starlette.responses import JSONResponse\n    from webargs import fields\n    from webargs_starlette import use_args\n\n    app = Starlette()\n\n\n    @app.route(\"/\")\n    @use_kwargs(\n        {\"name\": fields.Str(required=True), \"greeting\": fields.Str(load_default=\"hello\")}\n    )\n    async def homepage(request, name, greeting):\n        return JSONResponse({\"message\": f\"{greeting} {name}\"})\n\n\nSee `decorator_example.py \u003chttps://github.com/sloria/webargs-starlette/blob/master/examples/decorator_example.py\u003e`_\nfor a more complete example of ``use_args`` and ``use_kwargs`` usage.\n\nError Handling\n--------------\n\nWhen validation fails, the parser will raise a ``WebargsHTTPException``,\nwhich is the same as Starlette's ``HTTPException`` with the addition of\nof the ``messages`` (validation messages), ``headers`` , ``exception`` (underlying exception), and ``schema`` (marshmallow ``Schema``) attributes.\n\nYou can use a custom exception handler to return the error messages as\nJSON.\n\n\n.. code-block:: python\n\n    from starlette.responses import JSONResponse\n    from webargs_starlette import WebargsHTTPException\n\n\n    @app.exception_handler(WebargsHTTPException)\n    async def http_exception(request, exc):\n        return JSONResponse(exc.messages, status_code=exc.status_code, headers=exc.headers)\n\n\nAnnotations\n-----------\n\nThe ``use_annotations`` decorator allows you to parse request objects\nusing type annotations.\n\n\n.. code-block:: python\n\n    from starlette.applications import Starlette\n    from starlette.responses import JSONResponse\n    from webargs_starlette import use_annotations\n\n    app = Starlette()\n\n\n    @app.route(\"/\")\n    @use_annotations(location=\"query\")\n    async def welcome(request, name: str = \"Friend\"):\n        return JSONResponse({\"message\": f\"Welcome, {name}!\"})\n\n\n    # curl 'http://localhost:5000/'.\n    # {\"message\":\"Welcome, Friend!\"}\n    # curl 'http://localhost:5000/?name=Ada'.\n    # {\"message\":\"Welcome, Ada!\"}\n\nAny annotated argument that doesn't have a default value will be required.\nFor example, if we remove the default for ``name`` in the above example,\nan 422 error response is returned if ``?name`` isn't passed.\n\n\n.. code-block:: python\n\n    from starlette.applications import Starlette\n    from starlette.responses import JSONResponse\n    from webargs_starlette import use_annotations, WebargsHTTPException\n\n    app = Starlette()\n\n\n    @app.route(\"/\")\n    @use_annotations(location=\"query\")\n    async def welcome(request, name: str):\n        return JSONResponse({\"message\": f\"Welcome, {name}!\"})\n\n\n    @app.exception_handler(WebargsHTTPException)\n    async def http_exception(request, exc):\n        return JSONResponse(exc.messages, status_code=exc.status_code, headers=exc.headers)\n\n\n    # curl \"http://localhost:5000/\"\n    # {\"name\":[\"Missing data for required field.\"]}\n\nArguments may also be annotated with ``Field`` instances when you need\nmore control. For example, you may want to add a validator.\n\n.. code-block:: python\n\n    from starlette.applications import Starlette\n    from starlette.responses import JSONResponse\n    from webargs import fields\n    from marshmallow import validate\n    from webargs_starlette import use_annotations, WebargsHTTPException\n\n    app = Starlette()\n\n\n    @app.route(\"/\")\n    @use_annotations(location=\"query\")\n    async def welcome(request, name: fields.Str(validate=validate.Length(min=2))):\n        return JSONResponse({\"message\": f\"Welcome, {name}!\"})\n\n\n    @app.exception_handler(WebargsHTTPException)\n    async def http_exception(request, exc):\n        return JSONResponse(exc.messages, status_code=exc.status_code, headers=exc.headers)\n\n\n    # curl \"http://localhost:5000/?name=A\"\n    # {\"name\":[\"Shorter than minimum length 2.\"]}\n\n``HTTPEndpoint`` methods may also be decorated with ``use_annotations``.\n\n.. code-block:: python\n\n    from starlette.applications import Starlette\n    from starlette.responses import JSONResponse\n    from starlette.endpoints import HTTPEndpoint\n    from webargs_starlette import use_annotations\n\n    app = Starlette()\n\n\n    @app.route(\"/\")\n    class WelcomeEndpoint(HTTPEndpoint):\n        @use_annotations(location=\"query\")\n        async def get(self, request, name: str = \"World\"):\n            return JSONResponse({\"message\": f\"Welcome, {name}!\"})\n\nSee `annotation_example.py \u003chttps://github.com/sloria/webargs-starlette/blob/master/examples/annotation_example.py\u003e`_\nfor a more complete example of ``use_annotations`` usage.\n\nMore\n----\n\nFor more information on how to use webargs, see the `webargs documentation \u003chttps://webargs.readthedocs.io/\u003e`_.\n\nLicense\n=======\n\nMIT licensed. See the `LICENSE \u003chttps://github.com/sloria/webargs-starlette/blob/master/LICENSE\u003e`_ file for more details.\n","funding_links":[],"categories":["Extensions"],"sub_categories":["Base","Core Utilities"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsloria%2Fwebargs-starlette","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsloria%2Fwebargs-starlette","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsloria%2Fwebargs-starlette/lists"}