![\"FastAPI\"](\"https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png\"){kind=logo}
\n\n \n
\n FastAPI framework, high performance, easy to learn, fast to code, ready for production\n
\n\n\n ![\"Test\"](\"https://github.com/fastapi/fastapi/actions/workflows/test.yml/badge.svg?event=push&branch=master\"){kind=icon}
\n\n\n ![\"Coverage\"](\"https://coverage-badge.samuelcolvin.workers.dev/fastapi/fastapi.svg\"){kind=icon}
\n\n\n ![\"Package](\"https://img.shields.io/pypi/v/fastapi?color=%2334D058&label=pypi%20package\")
![\"Supported](\"https://img.shields.io/pypi/pyversions/fastapi.svg?color=%2334D058\")
\n\n
![](\"https://fastapi.tiangolo.com/img/sponsors/fastapicloud.png\")
\n\n### Gold Sponsors\n\n![](\"https://fastapi.tiangolo.com/img/sponsors/blockbee.png\")
\n![](\"https://fastapi.tiangolo.com/img/sponsors/propelauth.png\")
\n![](\"https://fastapi.tiangolo.com/img/sponsors/render.svg\")
\n![](\"https://fastapi.tiangolo.com/img/sponsors/coderabbit.png\")
\n![](\"https://fastapi.tiangolo.com/img/sponsors/subtotal.svg\")
\n![](\"https://fastapi.tiangolo.com/img/sponsors/railway.png\")
\n![](\"https://fastapi.tiangolo.com/img/sponsors/serpapi.png\")
\n![](\"https://fastapi.tiangolo.com/img/sponsors/greptile.png\")
\n\n### Silver Sponsors\n\n![](\"https://fastapi.tiangolo.com/img/sponsors/databento.svg\")
\n![](\"https://fastapi.tiangolo.com/img/sponsors/svix.svg\")
\n![](\"https://fastapi.tiangolo.com/img/sponsors/permit.png\")
\n![](\"https://fastapi.tiangolo.com/img/sponsors/dribia.png\")
\n![](\"https://fastapi.tiangolo.com/img/sponsors/rapidproxy.png\")
\n![](\"https://fastapi.tiangolo.com/img/sponsors/bairesdev.svg\")
\n\n\n\n[Other sponsors](https://fastapi.tiangolo.com/fastapi-people/#sponsors)", "source_type": "doc", "path": "README.md", "symbol": "Sponsors", "url": "https://github.com/fastapi/fastapi/blob/master/README.md#L45-L75", "start_line": 45, "end_line": 75}
{"id": "README.md::Opinions::L76", "text": "# Doc: README.md | Page: README.md | Section: Opinions\n## Opinions\n\n\n\n![\"FastAPI](\"https://fastapi.tiangolo.com/img/fastapi-conf.jpeg\")
", "source_type": "doc", "path": "README.md", "symbol": "FastAPI Conf", "url": "https://github.com/fastapi/fastapi/blob/master/README.md#L108-L113", "start_line": 108, "end_line": 113}
{"id": "README.md::FastAPI mini documentary::L114", "text": "# Doc: README.md | Page: README.md | Section: FastAPI mini documentary\n## FastAPI mini documentary\n\nThere's a [FastAPI mini documentary](https://www.youtube.com/watch?v=mpR8ngthqiE) released at the end of 2025, you can watch it online:\n\n![\"FastAPI](\"https://fastapi.tiangolo.com/img/fastapi-documentary.jpg\")
", "source_type": "doc", "path": "README.md", "symbol": "FastAPI mini documentary", "url": "https://github.com/fastapi/fastapi/blob/master/README.md#L114-L119", "start_line": 114, "end_line": 119}
{"id": "README.md::**Typer**, the FastAPI of CLIs::L120", "text": "# Doc: README.md | Page: README.md | Section: **Typer**, the FastAPI of CLIs\n## **Typer**, the FastAPI of CLIs\n\n![](\"https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg\"){kind=logo}
\n\nIf you are building a CLI app to be used in the terminal instead of a web API, check out [**Typer**](https://typer.tiangolo.com/).\n\n**Typer** is FastAPI's little sibling. And it's intended to be the **FastAPI of CLIs**. ⌨️ 🚀", "source_type": "doc", "path": "README.md", "symbol": "**Typer**, the FastAPI of CLIs", "url": "https://github.com/fastapi/fastapi/blob/master/README.md#L120-L127", "start_line": 120, "end_line": 127}
{"id": "README.md::Requirements::L128", "text": "# Doc: README.md | Page: README.md | Section: Requirements\n## Requirements\n\nFastAPI stands on the shoulders of giants:\n\n* [Starlette](https://www.starlette.dev/) for the web parts.\n* [Pydantic](https://docs.pydantic.dev/) for the data parts.", "source_type": "doc", "path": "README.md", "symbol": "Requirements", "url": "https://github.com/fastapi/fastapi/blob/master/README.md#L128-L134", "start_line": 128, "end_line": 134}
{"id": "README.md::Installation::L135", "text": "# Doc: README.md | Page: README.md | Section: Installation\n## Installation\n\nCreate and activate a [virtual environment](https://fastapi.tiangolo.com/virtual-environments/) and then install FastAPI:\n\nasync def...fastapi dev...lt\n* XWT\n* PSGI\n\n### The abbr gives a full phrase and an explanation { #the-abbr-gives-a-full-phrase-and-an-explanation }\n\n* MDN\n* I/O.\n\n////\n\n//// tab | Info\n\n\"title\" attributes of \"abbr\" elements are translated following some specific instructions.\n\nTranslations can add their own \"abbr\" elements which the LLM should not remove. E.g. to explain English words.\n\nSee section `### HTML abbr elements` in the general prompt in `scripts/translate.py`.\n\n////", "source_type": "doc", "path": "docs/en/docs/_llm-test.md", "symbol": "HTML \"abbr\" elements { #html-abbr-elements }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/_llm-test.md#L184-L213", "start_line": 184, "end_line": 213}
{"id": "docs/en/docs/_llm-test.md::HTML \"dfn\" elements { #html-dfn-elements }::L214", "text": "# Doc: docs/en/docs/_llm-test.md | Page: LLM test file { #llm-test-file } | Section: HTML \"dfn\" elements { #html-dfn-elements }\n## HTML \"dfn\" elements { #html-dfn-elements }\n\n* cluster\n* Deep Learning", "source_type": "doc", "path": "docs/en/docs/_llm-test.md", "symbol": "HTML \"dfn\" elements { #html-dfn-elements }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/_llm-test.md#L214-L218", "start_line": 214, "end_line": 218}
{"id": "docs/en/docs/_llm-test.md::Headings { #headings }::L219", "text": "# Doc: docs/en/docs/_llm-test.md | Page: LLM test file { #llm-test-file } | Section: Headings { #headings }\n## Headings { #headings }\n\n//// tab | Test\n\n### Develop a webapp - a tutorial { #develop-a-webapp-a-tutorial }\n\nHello.\n\n### Type hints and -annotations { #type-hints-and-annotations }\n\nHello again.\n\n### Super- and subclasses { #super-and-subclasses }\n\nHello again.\n\n////\n\n//// tab | Info\n\nThe only hard rule for headings is that the LLM leaves the hash part inside curly brackets unchanged, which ensures that links do not break.\n\nSee section `### Headings` in the general prompt in `scripts/translate.py`.\n\nFor some language specific instructions, see e.g. section `### Headings` in `docs/de/llm-prompt.md`.\n\n////", "source_type": "doc", "path": "docs/en/docs/_llm-test.md", "symbol": "Headings { #headings }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/_llm-test.md#L219-L246", "start_line": 219, "end_line": 246}
{"id": "docs/en/docs/_llm-test.md::Terms used in the docs { #terms-used-in-the-docs }::L247", "text": "# Doc: docs/en/docs/_llm-test.md | Page: LLM test file { #llm-test-file } | Section: Terms used in the docs { #terms-used-in-the-docs }\n## Terms used in the docs { #terms-used-in-the-docs }\n\n//// tab | Test\n\n* you\n* your\n\n* e.g.\n* etc.\n\n* `foo` as an `int`\n* `bar` as a `str`\n* `baz` as a `list`\n\n* the Tutorial - User guide\n* the Advanced User Guide\n* the SQLModel docs\n* the API docs\n* the automatic docs\n\n* Data Science\n* Deep Learning\n* Machine Learning\n* Dependency Injection\n* HTTP Basic authentication\n* HTTP Digest\n* ISO format\n* the JSON Schema standard\n* the JSON schema\n* the schema definition\n* Password Flow\n* Mobile\n\n* deprecated\n* designed\n* invalid\n* on the fly\n* standard\n* default\n* case-sensitive\n* case-insensitive\n\n* to serve the application\n* to serve the page\n\n* the app\n* the application\n\n* the request\n* the response\n* the error response\n\n* the path operation\n* the path operation decorator\n* the path operation function\n\n* the body\n* the request body\n* the response body\n* the JSON body\n* the form body\n* the file body\n* the function body\n\n* the parameter\n* the body parameter\n* the path parameter\n* the query parameter\n* the cookie parameter\n* the header parameter\n* the form parameter\n* the function parameter\n\n* the event\n* the startup event\n* the startup of the server\n* the shutdown event\n* the lifespan event\n\n* the handler\n* the event handler\n* the exception handler\n* to handle\n\n* the model\n* the Pydantic model\n* the data model\n* the database model\n* the form model\n* the model object\n\n* the class\n* the base class\n* the parent class\n* the subclass\n* the child class\n* the sibling class\n* the class method\n\n* the header\n* the headers\n* the authorization header\n* the `Authorization` header\n* the forwarded header\n\n* the dependency injection system\n* the dependency\n* the dependable\n* the dependant\n\n* I/O bound\n* CPU bound\n* concurrency\n* parallelism\n* multiprocessing\n\n* the env var\n* the environment variable\n* the `PATH`\n* the `PATH` variable\n\n* the authentication\n* the authentication provider\n* the authorization\n* the authorization form\n* the authorization provider\n* the user authenticates\n* the system authenticates the user\n\n* the CLI\n* the command line interface\n\n* the server\n* the client\n\n* the cloud provider\n* the cloud service\n\n* the development\n* the development stages\n\n* the dict\n* the dictionary\n* the enumeration\n* the enum\n* the enum member\n\n* the encoder\n* the decoder\n* to encode\n* to decode\n\n* the exception\n* to raise\n\n* the expression\n* the statement\n\n* the frontend\n* the backend\n\n* the GitHub discussion\n* the GitHub issue\n\n* the performance\n* the performance optimization\n\n* the return type\n* the return value\n\n* the security\n* the security scheme\n\n* the task\n* the background task\n* the task function\n\n* the template\n* the template engine\n\n* the type annotation\n* the type hint\n\n* the server worker\n* the Uvicorn worker\n* the Gunicorn Worker\n* the worker process\n* the worker class\n* the workload\n\n* the deployment\n* to deploy\n\n* the SDK\n* the software development kit\n\n* the `APIRouter`\n* the `requirements.txt`\n* the Bearer Token\n* the breaking change\n* the bug\n* the button\n* the callable\n* the code\n* the commit\n* the context manager\n* the coroutine\n* the database session\n* the disk\n* the domain\n* the engine\n* the fake X\n* the HTTP GET method\n* the item\n* the library\n* the lifespan\n* the lock\n* the middleware\n* the mobile application\n* the module\n* the mounting\n* the network\n* the origin\n* the override\n* the payload\n* the processor\n* the property\n* the proxy\n* the pull request\n* the query\n* the RAM\n* the remote machine\n* the status code\n* the string\n* the tag\n* the web framework\n* the wildcard\n* to return\n* to validate\n\n////\n\n//// tab | Info\n\nThis is neither a complete nor a normative list of (mostly) technical terms seen in the docs. It may be helpful for the prompt designer to figure out for which terms the LLM needs a helping hand. For example when it keeps reverting a good translation to a suboptimal translation. Or when it has problems conjugating/declinating a term in your language.\n\nSee e.g. section `### List of English terms and their preferred German translations` in `docs/de/llm-prompt.md`.\n\n////", "source_type": "doc", "path": "docs/en/docs/_llm-test.md", "symbol": "Terms used in the docs { #terms-used-in-the-docs }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/_llm-test.md#L247-L495", "start_line": 247, "end_line": 495}
{"id": "docs/en/docs/about/index.md::About { #about }::L1", "text": "# Doc: docs/en/docs/about/index.md | Page: About { #about } | Section: About { #about }\n# About { #about }\n\nAbout FastAPI, its design, inspiration and more. 🤓", "source_type": "doc", "path": "docs/en/docs/about/index.md", "symbol": "About { #about }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/about/index.md#L1-L3", "start_line": 1, "end_line": 3}
{"id": "docs/en/docs/advanced/additional-responses.md::Additional Responses in OpenAPI { #additional-responses-in-openapi }::L1", "text": "# Doc: docs/en/docs/advanced/additional-responses.md | Page: Additional Responses in OpenAPI { #additional-responses-in-openapi } | Section: Additional Responses in OpenAPI { #additional-responses-in-openapi }\n# Additional Responses in OpenAPI { #additional-responses-in-openapi }\n\n/// warning\n\nThis is a rather advanced topic.\n\nIf you are starting with **FastAPI**, you might not need this.\n\n///\n\nYou can declare additional responses, with additional status codes, media types, descriptions, etc.\n\nThose additional responses will be included in the OpenAPI schema, so they will also appear in the API docs.\n\nBut for those additional responses you have to make sure you return a `Response` like `JSONResponse` directly, with your status code and content.", "source_type": "doc", "path": "docs/en/docs/advanced/additional-responses.md", "symbol": "Additional Responses in OpenAPI { #additional-responses-in-openapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/additional-responses.md#L1-L16", "start_line": 1, "end_line": 16}
{"id": "docs/en/docs/advanced/additional-responses.md::Additional Response with `model` { #additional-response-with-model }::L17", "text": "# Doc: docs/en/docs/advanced/additional-responses.md | Page: Additional Responses in OpenAPI { #additional-responses-in-openapi } | Section: Additional Response with `model` { #additional-response-with-model }\n## Additional Response with `model` { #additional-response-with-model }\n\nYou can pass to your *path operation decorators* a parameter `responses`.\n\nIt receives a `dict`: the keys are status codes for each response (like `200`), and the values are other `dict`s with the information for each of them.\n\nEach of those response `dict`s can have a key `model`, containing a Pydantic model, just like `response_model`.\n\n**FastAPI** will take that model, generate its JSON Schema and include it in the correct place in OpenAPI.\n\nFor example, to declare another response with a status code `404` and a Pydantic model `Message`, you can write:\n\n{* ../../docs_src/additional_responses/tutorial001_py310.py hl[18,22] *}\n\n/// note\n\nKeep in mind that you have to return the `JSONResponse` directly.\n\n///\n\n/// note\n\nThe `model` key is not part of OpenAPI.\n\n**FastAPI** will take the Pydantic model from there, generate the JSON Schema, and put it in the correct place.\n\nThe correct place is:\n\n* In the key `content`, that has as value another JSON object (`dict`) that contains:\n * A key with the media type, e.g. `application/json`, that contains as value another JSON object, that contains:\n * A key `schema`, that has as the value the JSON Schema from the model, here's the correct place.\n * **FastAPI** adds a reference here to the global JSON Schemas in another place in your OpenAPI instead of including it directly. This way, other applications and clients can use those JSON Schemas directly, provide better code generation tools, etc.\n\n///\n\nThe generated responses in the OpenAPI for this *path operation* will be:\n\n```JSON hl_lines=\"3-12\"\n{\n \"responses\": {\n \"404\": {\n \"description\": \"Additional Response\",\n \"content\": {\n \"application/json\": {\n \"schema\": {\n \"$ref\": \"#/components/schemas/Message\"\n }\n }\n }\n },\n \"200\": {\n \"description\": \"Successful Response\",\n \"content\": {\n \"application/json\": {\n \"schema\": {\n \"$ref\": \"#/components/schemas/Item\"\n }\n }\n }\n },\n \"422\": {\n \"description\": \"Validation Error\",\n \"content\": {\n \"application/json\": {\n \"schema\": {\n \"$ref\": \"#/components/schemas/HTTPValidationError\"\n }\n }\n }\n }\n }\n}\n```\n\nThe schemas are referenced to another place inside the OpenAPI schema:\n\n```JSON hl_lines=\"4-16\"\n{\n \"components\": {\n \"schemas\": {\n \"Message\": {\n \"title\": \"Message\",\n \"required\": [\n \"message\"\n ],\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"title\": \"Message\",\n \"type\": \"string\"\n }\n }\n },\n \"Item\": {\n \"title\": \"Item\",\n \"required\": [\n \"id\",\n \"value\"\n ],\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"title\": \"Id\",\n \"type\": \"string\"\n },\n \"value\": {\n \"title\": \"Value\",\n \"type\": \"string\"\n }\n }\n },\n \"ValidationError\": {\n \"title\": \"ValidationError\",\n \"required\": [\n \"loc\",\n \"msg\",\n \"type\"\n ],\n \"type\": \"object\",\n \"properties\": {\n \"loc\": {\n \"title\": \"Location\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"msg\": {\n \"title\": \"Message\",\n \"type\": \"string\"\n },\n \"type\": {\n \"title\": \"Error Type\",\n \"type\": \"string\"\n }\n }\n },\n \"HTTPValidationError\": {\n \"title\": \"HTTPValidationError\",\n \"type\": \"object\",\n \"properties\": {\n \"detail\": {\n \"title\": \"Detail\",\n \"type\": \"array\",\n \"items\": {\n \"$ref\": \"#/components/schemas/ValidationError\"\n }\n }\n }\n }\n }\n }\n}\n```", "source_type": "doc", "path": "docs/en/docs/advanced/additional-responses.md", "symbol": "Additional Response with `model` { #additional-response-with-model }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/additional-responses.md#L17-L171", "start_line": 17, "end_line": 171}
{"id": "docs/en/docs/advanced/additional-responses.md::Additional media types for the main response { #additional-media-types-for-the-main-response }::L172", "text": "# Doc: docs/en/docs/advanced/additional-responses.md | Page: Additional Responses in OpenAPI { #additional-responses-in-openapi } | Section: Additional media types for the main response { #additional-media-types-for-the-main-response }\n## Additional media types for the main response { #additional-media-types-for-the-main-response }\n\nYou can use this same `responses` parameter to add different media types for the same main response.\n\nFor example, you can add an additional media type of `image/png`, declaring that your *path operation* can return a JSON object (with media type `application/json`) or a PNG image:\n\n{* ../../docs_src/additional_responses/tutorial002_py310.py hl[17:22,26] *}\n\n/// note\n\nNotice that you have to return the image using a `FileResponse` directly.\n\n///\n\n/// note\n\nUnless you specify a different media type explicitly in your `responses` parameter, FastAPI will assume the response has the same media type as the main response class (default `application/json`).\n\nBut if you have specified a custom response class with `None` as its media type, FastAPI will use `application/json` for any additional response that has an associated model.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/additional-responses.md", "symbol": "Additional media types for the main response { #additional-media-types-for-the-main-response }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/additional-responses.md#L172-L193", "start_line": 172, "end_line": 193}
{"id": "docs/en/docs/advanced/additional-responses.md::Combining information { #combining-information }::L194", "text": "# Doc: docs/en/docs/advanced/additional-responses.md | Page: Additional Responses in OpenAPI { #additional-responses-in-openapi } | Section: Combining information { #combining-information }\n## Combining information { #combining-information }\n\nYou can also combine response information from multiple places, including the `response_model`, `status_code`, and `responses` parameters.\n\nYou can declare a `response_model`, using the default status code `200` (or a custom one if you need), and then declare additional information for that same response in `responses`, directly in the OpenAPI schema.\n\n**FastAPI** will keep the additional information from `responses`, and combine it with the JSON Schema from your model.\n\nFor example, you can declare a response with a status code `404` that uses a Pydantic model and has a custom `description`.\n\nAnd a response with a status code `200` that uses your `response_model`, but includes a custom `example`:\n\n{* ../../docs_src/additional_responses/tutorial003_py310.py hl[20:31] *}\n\nIt will all be combined and included in your OpenAPI, and shown in the API docs:\n\n![](\"/img/tutorial/additional-responses/image01.png\")
", "source_type": "doc", "path": "docs/en/docs/advanced/additional-responses.md", "symbol": "Combining information { #combining-information }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/additional-responses.md#L194-L211", "start_line": 194, "end_line": 211}
{"id": "docs/en/docs/advanced/additional-responses.md::Combine predefined responses and custom ones { #combine-predefined-responses-and-custom-ones }::L212", "text": "# Doc: docs/en/docs/advanced/additional-responses.md | Page: Additional Responses in OpenAPI { #additional-responses-in-openapi } | Section: Combine predefined responses and custom ones { #combine-predefined-responses-and-custom-ones }\n## Combine predefined responses and custom ones { #combine-predefined-responses-and-custom-ones }\n\nYou might want to have some predefined responses that apply to many *path operations*, but you want to combine them with custom responses needed by each *path operation*.\n\nFor those cases, you can use the Python technique of \"unpacking\" a `dict` with `**dict_to_unpack`:\n\n```Python\nold_dict = {\n \"old key\": \"old value\",\n \"second old key\": \"second old value\",\n}\nnew_dict = {**old_dict, \"new key\": \"new value\"}\n```\n\nHere, `new_dict` will contain all the key-value pairs from `old_dict` plus the new key-value pair:\n\n```Python\n{\n \"old key\": \"old value\",\n \"second old key\": \"second old value\",\n \"new key\": \"new value\",\n}\n```\n\nYou can use that technique to reuse some predefined responses in your *path operations* and combine them with additional custom ones.\n\nFor example:\n\n{* ../../docs_src/additional_responses/tutorial004_py310.py hl[11:15,24] *}", "source_type": "doc", "path": "docs/en/docs/advanced/additional-responses.md", "symbol": "Combine predefined responses and custom ones { #combine-predefined-responses-and-custom-ones }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/additional-responses.md#L212-L241", "start_line": 212, "end_line": 241}
{"id": "docs/en/docs/advanced/additional-responses.md::More information about OpenAPI responses { #more-information-about-openapi-responses }::L242", "text": "# Doc: docs/en/docs/advanced/additional-responses.md | Page: Additional Responses in OpenAPI { #additional-responses-in-openapi } | Section: More information about OpenAPI responses { #more-information-about-openapi-responses }\n## More information about OpenAPI responses { #more-information-about-openapi-responses }\n\nTo see what exactly you can include in the responses, you can check these sections in the OpenAPI specification:\n\n* [OpenAPI Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object), it includes the `Response Object`.\n* [OpenAPI Response Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object), you can include anything from this directly in each response inside your `responses` parameter. Including `description`, `headers`, `content` (inside of this is that you declare different media types and JSON Schemas), and `links`.", "source_type": "doc", "path": "docs/en/docs/advanced/additional-responses.md", "symbol": "More information about OpenAPI responses { #more-information-about-openapi-responses }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/additional-responses.md#L242-L247", "start_line": 242, "end_line": 247}
{"id": "docs/en/docs/advanced/additional-status-codes.md::Additional Status Codes { #additional-status-codes }::L1", "text": "# Doc: docs/en/docs/advanced/additional-status-codes.md | Page: Additional Status Codes { #additional-status-codes } | Section: Additional Status Codes { #additional-status-codes }\n# Additional Status Codes { #additional-status-codes }\n\nBy default, **FastAPI** will return the responses using a `JSONResponse`, putting the content you return from your *path operation* inside of that `JSONResponse`.\n\nIt will use the default status code or the one you set in your *path operation*.", "source_type": "doc", "path": "docs/en/docs/advanced/additional-status-codes.md", "symbol": "Additional Status Codes { #additional-status-codes }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/additional-status-codes.md#L1-L6", "start_line": 1, "end_line": 6}
{"id": "docs/en/docs/advanced/additional-status-codes.md::Additional status codes { #additional-status-codes_1 }::L7", "text": "# Doc: docs/en/docs/advanced/additional-status-codes.md | Page: Additional Status Codes { #additional-status-codes } | Section: Additional status codes { #additional-status-codes_1 }\n## Additional status codes { #additional-status-codes_1 }\n\nIf you want to return additional status codes apart from the main one, you can do that by returning a `Response` directly, like a `JSONResponse`, and set the additional status code directly.\n\nFor example, let's say that you want to have a *path operation* that allows updating items, and returns HTTP status codes of 200 \"OK\" when successful.\n\nBut you also want it to accept new items. And when the items didn't exist before, it creates them, and returns an HTTP status code of 201 \"Created\".\n\nTo achieve that, import `JSONResponse`, and return your content there directly, setting the `status_code` that you want:\n\n{* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *}\n\n/// warning\n\nWhen you return a `Response` directly, like in the example above, it will be returned directly.\n\nIt won't be serialized with a model, etc.\n\nMake sure it has the data you want it to have, and that the values are valid JSON (if you are using `JSONResponse`).\n\n///\n\n/// note | Technical Details\n\nYou could also use `from starlette.responses import JSONResponse`.\n\n**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette. The same with `status`.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/additional-status-codes.md", "symbol": "Additional status codes { #additional-status-codes_1 }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/additional-status-codes.md#L7-L36", "start_line": 7, "end_line": 36}
{"id": "docs/en/docs/advanced/additional-status-codes.md::OpenAPI and API docs { #openapi-and-api-docs }::L37", "text": "# Doc: docs/en/docs/advanced/additional-status-codes.md | Page: Additional Status Codes { #additional-status-codes } | Section: OpenAPI and API docs { #openapi-and-api-docs }\n## OpenAPI and API docs { #openapi-and-api-docs }\n\nIf you return additional status codes and responses directly, they won't be included in the OpenAPI schema (the API docs), because FastAPI doesn't have a way to know beforehand what you are going to return.\n\nBut you can document that in your code, using: [Additional Responses](additional-responses.md).", "source_type": "doc", "path": "docs/en/docs/advanced/additional-status-codes.md", "symbol": "OpenAPI and API docs { #openapi-and-api-docs }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/additional-status-codes.md#L37-L41", "start_line": 37, "end_line": 41}
{"id": "docs/en/docs/advanced/advanced-dependencies.md::Advanced Dependencies { #advanced-dependencies }::L1", "text": "# Doc: docs/en/docs/advanced/advanced-dependencies.md | Page: Advanced Dependencies { #advanced-dependencies } | Section: Advanced Dependencies { #advanced-dependencies }\n# Advanced Dependencies { #advanced-dependencies }", "source_type": "doc", "path": "docs/en/docs/advanced/advanced-dependencies.md", "symbol": "Advanced Dependencies { #advanced-dependencies }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/advanced-dependencies.md#L1-L2", "start_line": 1, "end_line": 2}
{"id": "docs/en/docs/advanced/advanced-dependencies.md::Parameterized dependencies { #parameterized-dependencies }::L3", "text": "# Doc: docs/en/docs/advanced/advanced-dependencies.md | Page: Advanced Dependencies { #advanced-dependencies } | Section: Parameterized dependencies { #parameterized-dependencies }\n## Parameterized dependencies { #parameterized-dependencies }\n\nAll the dependencies we have seen are a fixed function or class.\n\nBut there could be cases where you want to be able to set parameters on the dependency, without having to declare many different functions or classes.\n\nLet's imagine that we want to have a dependency that checks if the query parameter `q` contains some fixed content.\n\nBut we want to be able to parameterize that fixed content.", "source_type": "doc", "path": "docs/en/docs/advanced/advanced-dependencies.md", "symbol": "Parameterized dependencies { #parameterized-dependencies }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/advanced-dependencies.md#L3-L12", "start_line": 3, "end_line": 12}
{"id": "docs/en/docs/advanced/advanced-dependencies.md::A \"callable\" instance { #a-callable-instance }::L13", "text": "# Doc: docs/en/docs/advanced/advanced-dependencies.md | Page: Advanced Dependencies { #advanced-dependencies } | Section: A \"callable\" instance { #a-callable-instance }\n## A \"callable\" instance { #a-callable-instance }\n\nIn Python there's a way to make an instance of a class a \"callable\".\n\nNot the class itself (which is already a callable), but an instance of that class.\n\nTo do that, we declare a method `__call__`:\n\n{* ../../docs_src/dependencies/tutorial011_an_py310.py hl[12] *}\n\nIn this case, this `__call__` is what **FastAPI** will use to check for additional parameters and sub-dependencies, and this is what will be called to pass a value to the parameter in your *path operation function* later.", "source_type": "doc", "path": "docs/en/docs/advanced/advanced-dependencies.md", "symbol": "A \"callable\" instance { #a-callable-instance }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/advanced-dependencies.md#L13-L24", "start_line": 13, "end_line": 24}
{"id": "docs/en/docs/advanced/advanced-dependencies.md::Parameterize the instance { #parameterize-the-instance }::L25", "text": "# Doc: docs/en/docs/advanced/advanced-dependencies.md | Page: Advanced Dependencies { #advanced-dependencies } | Section: Parameterize the instance { #parameterize-the-instance }\n## Parameterize the instance { #parameterize-the-instance }\n\nAnd now, we can use `__init__` to declare the parameters of the instance that we can use to \"parameterize\" the dependency:\n\n{* ../../docs_src/dependencies/tutorial011_an_py310.py hl[9] *}\n\nIn this case, **FastAPI** won't ever touch or care about `__init__`, we will use it directly in our code.", "source_type": "doc", "path": "docs/en/docs/advanced/advanced-dependencies.md", "symbol": "Parameterize the instance { #parameterize-the-instance }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/advanced-dependencies.md#L25-L32", "start_line": 25, "end_line": 32}
{"id": "docs/en/docs/advanced/advanced-dependencies.md::Create an instance { #create-an-instance }::L33", "text": "# Doc: docs/en/docs/advanced/advanced-dependencies.md | Page: Advanced Dependencies { #advanced-dependencies } | Section: Create an instance { #create-an-instance }\n## Create an instance { #create-an-instance }\n\nWe could create an instance of this class with:\n\n{* ../../docs_src/dependencies/tutorial011_an_py310.py hl[18] *}\n\nAnd that way we are able to \"parameterize\" our dependency, that now has `\"bar\"` inside of it, as the attribute `checker.fixed_content`.", "source_type": "doc", "path": "docs/en/docs/advanced/advanced-dependencies.md", "symbol": "Create an instance { #create-an-instance }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/advanced-dependencies.md#L33-L40", "start_line": 33, "end_line": 40}
{"id": "docs/en/docs/advanced/advanced-dependencies.md::Use the instance as a dependency { #use-the-instance-as-a-dependency }::L41", "text": "# Doc: docs/en/docs/advanced/advanced-dependencies.md | Page: Advanced Dependencies { #advanced-dependencies } | Section: Use the instance as a dependency { #use-the-instance-as-a-dependency }\n## Use the instance as a dependency { #use-the-instance-as-a-dependency }\n\nThen, we could use this `checker` in a `Depends(checker)`, instead of `Depends(FixedContentQueryChecker)`, because the dependency is the instance, `checker`, not the class itself.\n\nAnd when solving the dependency, **FastAPI** will call this `checker` like:\n\n```Python\nchecker(q=\"somequery\")\n```\n\n...and pass whatever that returns as the value of the dependency in our *path operation function* as the parameter `fixed_content_included`:\n\n{* ../../docs_src/dependencies/tutorial011_an_py310.py hl[22] *}\n\n/// tip\n\nAll this might seem contrived. And it might not be very clear how it is useful yet.\n\nThese examples are intentionally simple, but show how it all works.\n\nIn the chapters about security, there are utility functions that are implemented in this same way.\n\nIf you understood all this, you already know how those utility tools for security work underneath.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/advanced-dependencies.md", "symbol": "Use the instance as a dependency { #use-the-instance-as-a-dependency }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/advanced-dependencies.md#L41-L66", "start_line": 41, "end_line": 66}
{"id": "docs/en/docs/advanced/advanced-dependencies.md::Dependencies with `yield`, `HTTPException`, `except` and Background Tasks { #dependencies-with-yield-httpexception-except-and-background-tasks }::L67", "text": "# Doc: docs/en/docs/advanced/advanced-dependencies.md | Page: Advanced Dependencies { #advanced-dependencies } | Section: Dependencies with `yield`, `HTTPException`, `except` and Background Tasks { #dependencies-with-yield-httpexception-except-and-background-tasks }\n## Dependencies with `yield`, `HTTPException`, `except` and Background Tasks { #dependencies-with-yield-httpexception-except-and-background-tasks }\n\n/// warning\n\nYou most probably don't need these technical details.\n\nThese details are useful mainly if you had a FastAPI application older than 0.121.0 and you are facing issues with dependencies with `yield`.\n\n///\n\nDependencies with `yield` have evolved over time to account for the different use cases and to fix some issues, here's a summary of what has changed.\n\n### Dependencies with `yield` and `scope` { #dependencies-with-yield-and-scope }\n\nIn version 0.121.0, FastAPI added support for `Depends(scope=\"function\")` for dependencies with `yield`.\n\nUsing `Depends(scope=\"function\")`, the exit code after `yield` is executed right after the *path operation function* is finished, before the response is sent back to the client.\n\nAnd when using `Depends(scope=\"request\")` (the default), the exit code after `yield` is executed after the response is sent.\n\nYou can read more about it in the docs for [Dependencies with `yield` - Early exit and `scope`](../tutorial/dependencies/dependencies-with-yield.md#early-exit-and-scope).\n\n### Dependencies with `yield` and `StreamingResponse`, Technical Details { #dependencies-with-yield-and-streamingresponse-technical-details }\n\nBefore FastAPI 0.118.0, if you used a dependency with `yield`, it would run the exit code after the *path operation function* returned but right before sending the response.\n\nThe intention was to avoid holding resources for longer than necessary, waiting for the response to travel through the network.\n\nThis change also meant that if you returned a `StreamingResponse`, the exit code of the dependency with `yield` would have been already run.\n\nFor example, if you had a database session in a dependency with `yield`, the `StreamingResponse` would not be able to use that session while streaming data because the session would have already been closed in the exit code after `yield`.\n\nThis behavior was reverted in 0.118.0, to make the exit code after `yield` be executed after the response is sent.\n\n/// note\n\nAs you will see below, this is very similar to the behavior before version 0.106.0, but with several improvements and bug fixes for corner cases.\n\n///\n\n#### Use Cases with Early Exit Code { #use-cases-with-early-exit-code }\n\nThere are some use cases with specific conditions that could benefit from the old behavior of running the exit code of dependencies with `yield` before sending the response.\n\nFor example, imagine you have code that uses a database session in a dependency with `yield` only to verify a user, but the database session is never used again in the *path operation function*, only in the dependency, **and** the response takes a long time to be sent, like a `StreamingResponse` that sends data slowly, but for some reason doesn't use the database.\n\nIn this case, the database session would be held until the response is finished being sent, but if you don't use it, then it wouldn't be necessary to hold it.\n\nHere's how it could look:\n\n{* ../../docs_src/dependencies/tutorial013_an_py310.py *}\n\nThe exit code, the automatic closing of the `Session` in:\n\n{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *}\n\n...would be run after the response finishes sending the slow data:\n\n{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] hl[31:33] *}\n\nBut as `generate_stream()` doesn't use the database session, it is not really necessary to keep the session open while sending the response.\n\nIf you have this specific use case using SQLModel (or SQLAlchemy), you could explicitly close the session after you don't need it anymore:\n\n{* ../../docs_src/dependencies/tutorial014_an_py310.py ln[24:28] hl[28] *}\n\nThat way the session would release the database connection, so other requests could use it.\n\nIf you have a different use case that needs to exit early from a dependency with `yield`, please create a [GitHub Discussion Question](https://github.com/fastapi/fastapi/discussions/new?category=questions) with your specific use case and why you would benefit from having early closing for dependencies with `yield`.\n\nIf there are compelling use cases for early closing in dependencies with `yield`, I would consider adding a new way to opt in to early closing.\n\n### Dependencies with `yield` and `except`, Technical Details { #dependencies-with-yield-and-except-technical-details }\n\nBefore FastAPI 0.110.0, if you used a dependency with `yield`, and then you captured an exception with `except` in that dependency, and you didn't raise the exception again, the exception would be automatically raised/forwarded to any exception handlers or the internal server error handler.\n\nThis was changed in version 0.110.0 to fix unhandled memory consumption from forwarded exceptions without a handler (internal server errors), and to make it consistent with the behavior of regular Python code.\n\n### Background Tasks and Dependencies with `yield`, Technical Details { #background-tasks-and-dependencies-with-yield-technical-details }\n\nBefore FastAPI 0.106.0, raising exceptions after `yield` was not possible, the exit code in dependencies with `yield` was executed *after* the response was sent, so [Exception Handlers](../tutorial/handling-errors.md#install-custom-exception-handlers) would have already run.\n\nThis was designed this way mainly to allow using the same objects \"yielded\" by dependencies inside of background tasks, because the exit code would be executed after the background tasks were finished.\n\nThis was changed in FastAPI 0.106.0 with the intention to not hold resources while waiting for the response to travel through the network.\n\n/// tip\n\nAdditionally, a background task is normally an independent set of logic that should be handled separately, with its own resources (e.g. its own database connection).\n\nSo, this way you will probably have cleaner code.\n\n///\n\nIf you used to rely on this behavior, now you should create the resources for background tasks inside the background task itself, and use internally only data that doesn't depend on the resources of dependencies with `yield`.\n\nFor example, instead of using the same database session, you would create a new database session inside of the background task, and you would obtain the objects from the database using this new session. And then instead of passing the object from the database as a parameter to the background task function, you would pass the ID of that object and then obtain the object again inside the background task function.", "source_type": "doc", "path": "docs/en/docs/advanced/advanced-dependencies.md", "symbol": "Dependencies with `yield`, `HTTPException`, `except` and Background Tasks { #dependencies-with-yield-httpexception-except-and-background-tasks }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/advanced-dependencies.md#L67-L163", "start_line": 67, "end_line": 163}
{"id": "docs/en/docs/advanced/advanced-python-types.md::Advanced Python Types { #advanced-python-types }::L1", "text": "# Doc: docs/en/docs/advanced/advanced-python-types.md | Page: Advanced Python Types { #advanced-python-types } | Section: Advanced Python Types { #advanced-python-types }\n# Advanced Python Types { #advanced-python-types }\n\nHere are some additional ideas that might be useful when working with Python types.", "source_type": "doc", "path": "docs/en/docs/advanced/advanced-python-types.md", "symbol": "Advanced Python Types { #advanced-python-types }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/advanced-python-types.md#L1-L4", "start_line": 1, "end_line": 4}
{"id": "docs/en/docs/advanced/advanced-python-types.md::Using `Union` or `Optional` { #using-union-or-optional }::L5", "text": "# Doc: docs/en/docs/advanced/advanced-python-types.md | Page: Advanced Python Types { #advanced-python-types } | Section: Using `Union` or `Optional` { #using-union-or-optional }\n## Using `Union` or `Optional` { #using-union-or-optional }\n\nIf your code for some reason can't use `|`, for example if it's not in a type annotation but in something like `response_model=`, instead of using the vertical bar (`|`) you can use `Union` from `typing`.\n\nFor example, you could declare that something could be a `str` or `None`:\n\n```python\nfrom typing import Union\n\n\ndef say_hi(name: Union[str, None]):\n print(f\"Hi {name}!\")\n```\n\n`typing` also has a shortcut to declare that something could be `None`, with `Optional`.\n\nHere's a tip from my very **subjective** point of view:\n\n* 🚨 Avoid using `Optional[SomeType]`\n* Instead ✨ **use `Union[SomeType, None]`** ✨.\n\nBoth are equivalent and underneath they are the same, but I would recommend `Union` instead of `Optional` because the word \"**optional**\" would seem to imply that the value is optional, and it actually means \"it can be `None`\", even if it's not optional and is still required.\n\nI think `Union[SomeType, None]` is more explicit about what it means.\n\nIt's just about the words and names. But those words can affect how you and your teammates think about the code.\n\nAs an example, let's take this function:\n\n```python\nfrom typing import Optional\n\n\ndef say_hi(name: Optional[str]):\n print(f\"Hey {name}!\")\n```\n\nThe parameter `name` is defined as `Optional[str]`, but it is **not optional**, you cannot call the function without the parameter:\n\n```Python\nsay_hi() # Oh, no, this throws an error! 😱\n```\n\nThe `name` parameter is **still required** (not *optional*) because it doesn't have a default value. Still, `name` accepts `None` as the value:\n\n```Python\nsay_hi(name=None) # This works, None is valid 🎉\n```\n\nThe good news is, in most cases, you will be able to simply use `|` to define unions of types:\n\n```python\ndef say_hi(name: str | None):\n print(f\"Hey {name}!\")\n```\n\nSo, normally you don't have to worry about names like `Optional` and `Union`. 😎", "source_type": "doc", "path": "docs/en/docs/advanced/advanced-python-types.md", "symbol": "Using `Union` or `Optional` { #using-union-or-optional }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/advanced-python-types.md#L5-L61", "start_line": 5, "end_line": 61}
{"id": "docs/en/docs/advanced/async-tests.md::Async Tests { #async-tests }::L1", "text": "# Doc: docs/en/docs/advanced/async-tests.md | Page: Async Tests { #async-tests } | Section: Async Tests { #async-tests }\n# Async Tests { #async-tests }\n\nYou have already seen how to test your **FastAPI** applications using the provided `TestClient`. Up to now, you have only seen how to write synchronous tests, without using `async` functions.\n\nBeing able to use asynchronous functions in your tests could be useful, for example, when you're querying your database asynchronously. Imagine you want to test sending requests to your FastAPI application and then verify that your backend successfully wrote the correct data in the database, while using an async database library.\n\nLet's look at how we can make that work.", "source_type": "doc", "path": "docs/en/docs/advanced/async-tests.md", "symbol": "Async Tests { #async-tests }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/async-tests.md#L1-L8", "start_line": 1, "end_line": 8}
{"id": "docs/en/docs/advanced/async-tests.md::pytest.mark.anyio { #pytest-mark-anyio }::L9", "text": "# Doc: docs/en/docs/advanced/async-tests.md | Page: Async Tests { #async-tests } | Section: pytest.mark.anyio { #pytest-mark-anyio }\n## pytest.mark.anyio { #pytest-mark-anyio }\n\nIf we want to call asynchronous functions in our tests, our test functions have to be asynchronous. AnyIO provides a neat plugin for this, that allows us to specify that some test functions are to be called asynchronously.", "source_type": "doc", "path": "docs/en/docs/advanced/async-tests.md", "symbol": "pytest.mark.anyio { #pytest-mark-anyio }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/async-tests.md#L9-L12", "start_line": 9, "end_line": 12}
{"id": "docs/en/docs/advanced/async-tests.md::HTTPX { #httpx }::L13", "text": "# Doc: docs/en/docs/advanced/async-tests.md | Page: Async Tests { #async-tests } | Section: HTTPX { #httpx }\n## HTTPX { #httpx }\n\nEven if your **FastAPI** application uses normal `def` functions instead of `async def`, it is still an `async` application underneath.\n\nThe `TestClient` does some magic inside to call the asynchronous FastAPI application in your normal `def` test functions, using standard pytest. But that magic doesn't work anymore when we're using it inside asynchronous functions. By running our tests asynchronously, we can no longer use the `TestClient` inside our test functions.\n\nThe `TestClient` is based on [HTTPX](https://www.python-httpx.org), and luckily, we can use it directly to test the API.", "source_type": "doc", "path": "docs/en/docs/advanced/async-tests.md", "symbol": "HTTPX { #httpx }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/async-tests.md#L13-L20", "start_line": 13, "end_line": 20}
{"id": "docs/en/docs/advanced/async-tests.md::Example { #example }::L21", "text": "# Doc: docs/en/docs/advanced/async-tests.md | Page: Async Tests { #async-tests } | Section: Example { #example }\n## Example { #example }\n\nFor a simple example, let's consider a file structure similar to the one described in [Bigger Applications](../tutorial/bigger-applications.md) and [Testing](../tutorial/testing.md):\n\n```\n.\n├── app\n│ ├── __init__.py\n│ ├── main.py\n│ └── test_main.py\n```\n\nThe file `main.py` would have:\n\n{* ../../docs_src/async_tests/app_a_py310/main.py *}\n\nThe file `test_main.py` would have the tests for `main.py`, it could look like this now:\n\n{* ../../docs_src/async_tests/app_a_py310/test_main.py *}", "source_type": "doc", "path": "docs/en/docs/advanced/async-tests.md", "symbol": "Example { #example }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/async-tests.md#L21-L40", "start_line": 21, "end_line": 40}
{"id": "docs/en/docs/advanced/async-tests.md::Run it { #run-it }::L41", "text": "# Doc: docs/en/docs/advanced/async-tests.md | Page: Async Tests { #async-tests } | Section: Run it { #run-it }\n## Run it { #run-it }\n\nYou can run your tests as usual via:\n\n![](\"/img/tutorial/behind-a-proxy/image01.png\")
\n\nBut if we access the docs UI at the \"official\" URL using the proxy with port `9999`, at `/api/v1/docs`, it works correctly! 🎉\n\nYou can check it at [http://127.0.0.1:9999/api/v1/docs](http://127.0.0.1:9999/api/v1/docs):\n\n![](\"/img/tutorial/behind-a-proxy/image02.png\")
\n\nRight as we wanted it. ✔️\n\nThis is because FastAPI uses this `root_path` to create the default `server` in OpenAPI with the URL provided by `root_path`.", "source_type": "doc", "path": "docs/en/docs/advanced/behind-a-proxy.md", "symbol": "Testing locally with Traefik { #testing-locally-with-traefik }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/behind-a-proxy.md#L252-L386", "start_line": 252, "end_line": 386}
{"id": "docs/en/docs/advanced/behind-a-proxy.md::Additional servers { #additional-servers }::L387", "text": "# Doc: docs/en/docs/advanced/behind-a-proxy.md | Page: Behind a Proxy { #behind-a-proxy } | Section: Additional servers { #additional-servers }\n## Additional servers { #additional-servers }\n\n/// warning\n\nThis is a more advanced use case. Feel free to skip it.\n\n///\n\nBy default, **FastAPI** will create a `server` in the OpenAPI schema with the URL for the `root_path`.\n\nBut you can also provide other alternative `servers`, for example if you want *the same* docs UI to interact with both a staging and a production environment.\n\nIf you pass a custom list of `servers` and there's a `root_path` (because your API lives behind a proxy), **FastAPI** will insert a \"server\" with this `root_path` at the beginning of the list.\n\nFor example:\n\n{* ../../docs_src/behind_a_proxy/tutorial003_py310.py hl[4:7] *}\n\nWill generate an OpenAPI schema like:\n\n```JSON hl_lines=\"5-7\"\n{\n \"openapi\": \"3.1.0\",\n // More stuff here\n \"servers\": [\n {\n \"url\": \"/api/v1\"\n },\n {\n \"url\": \"https://stag.example.com\",\n \"description\": \"Staging environment\"\n },\n {\n \"url\": \"https://prod.example.com\",\n \"description\": \"Production environment\"\n }\n ],\n \"paths\": {\n // More stuff here\n }\n}\n```\n\n/// tip\n\nNotice the auto-generated server with a `url` value of `/api/v1`, taken from the `root_path`.\n\n///\n\nIn the docs UI at [http://127.0.0.1:9999/api/v1/docs](http://127.0.0.1:9999/api/v1/docs) it would look like:\n\n![](\"/img/tutorial/behind-a-proxy/image03.png\")
\n\n/// tip\n\nThe docs UI will interact with the server that you select.\n\n///\n\n/// note | Technical Details\n\nThe `servers` property in the OpenAPI specification is optional.\n\nIf you don't specify the `servers` parameter and `root_path` is equal to `/`, the `servers` property in the generated OpenAPI schema will be omitted entirely by default, which is the equivalent of a single server with a `url` value of `/`.\n\n///\n\n### Disable automatic server from `root_path` { #disable-automatic-server-from-root-path }\n\nIf you don't want **FastAPI** to include an automatic server using the `root_path`, you can use the parameter `root_path_in_servers=False`:\n\n{* ../../docs_src/behind_a_proxy/tutorial004_py310.py hl[9] *}\n\nand then it won't include it in the OpenAPI schema.", "source_type": "doc", "path": "docs/en/docs/advanced/behind-a-proxy.md", "symbol": "Additional servers { #additional-servers }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/behind-a-proxy.md#L387-L461", "start_line": 387, "end_line": 461}
{"id": "docs/en/docs/advanced/behind-a-proxy.md::Mounting a sub-application { #mounting-a-sub-application }::L462", "text": "# Doc: docs/en/docs/advanced/behind-a-proxy.md | Page: Behind a Proxy { #behind-a-proxy } | Section: Mounting a sub-application { #mounting-a-sub-application }\n## Mounting a sub-application { #mounting-a-sub-application }\n\nIf you need to mount a sub-application (as described in [Sub Applications - Mounts](sub-applications.md)) while also using a proxy with `root_path`, you can do it normally, as you would expect.\n\nFastAPI will internally use the `root_path` smartly, so it will just work. ✨", "source_type": "doc", "path": "docs/en/docs/advanced/behind-a-proxy.md", "symbol": "Mounting a sub-application { #mounting-a-sub-application }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/behind-a-proxy.md#L462-L466", "start_line": 462, "end_line": 466}
{"id": "docs/en/docs/advanced/custom-response.md::Custom Response - HTML, Stream, File, others { #custom-response-html-stream-file-others }::L1", "text": "# Doc: docs/en/docs/advanced/custom-response.md | Page: Custom Response - HTML, Stream, File, others { #custom-response-html-stream-file-others } | Section: Custom Response - HTML, Stream, File, others { #custom-response-html-stream-file-others }\n# Custom Response - HTML, Stream, File, others { #custom-response-html-stream-file-others }\n\nBy default, **FastAPI** will return JSON responses.\n\nYou can override it by returning a `Response` directly as seen in [Return a Response directly](response-directly.md).\n\nBut if you return a `Response` directly (or any subclass, like `JSONResponse`), the data won't be automatically converted (even if you declare a `response_model`), and the documentation won't be automatically generated (for example, including the specific \"media type\", in the HTTP header `Content-Type` as part of the generated OpenAPI).\n\nBut you can also declare the `Response` that you want to be used (e.g. any `Response` subclass), in the *path operation decorator* using the `response_class` parameter.\n\nThe contents that you return from your *path operation function* will be put inside of that `Response`.\n\n/// note\n\nIf you use a response class with no media type, FastAPI will expect your response to have no content, so it will not document the response format in its generated OpenAPI docs.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/custom-response.md", "symbol": "Custom Response - HTML, Stream, File, others { #custom-response-html-stream-file-others }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/custom-response.md#L1-L18", "start_line": 1, "end_line": 18}
{"id": "docs/en/docs/advanced/custom-response.md::JSON Responses { #json-responses }::L19", "text": "# Doc: docs/en/docs/advanced/custom-response.md | Page: Custom Response - HTML, Stream, File, others { #custom-response-html-stream-file-others } | Section: JSON Responses { #json-responses }\n## JSON Responses { #json-responses }\n\nBy default FastAPI returns JSON responses.\n\nIf you declare a [Response Model](../tutorial/response-model.md) FastAPI will use it to serialize the data to JSON, using Pydantic.\n\nIf you don't declare a response model, FastAPI will use the `jsonable_encoder` explained in [JSON Compatible Encoder](../tutorial/encoder.md) and put it in a `JSONResponse`.\n\nIf you declare a `response_class` with a JSON media type (`application/json`), like is the case with the `JSONResponse`, the data you return will be automatically converted (and filtered) with any Pydantic `response_model` that you declared in the *path operation decorator*. But the data won't be serialized to JSON bytes with Pydantic, instead it will be converted with the `jsonable_encoder` and then passed to the `JSONResponse` class, which will serialize it to bytes using the standard JSON library in Python.\n\n### JSON Performance { #json-performance }\n\nIn short, if you want the maximum performance, use a [Response Model](../tutorial/response-model.md) and don't declare a `response_class` in the *path operation decorator*.\n\n{* ../../docs_src/response_model/tutorial001_01_py310.py ln[15:17] hl[16] *}", "source_type": "doc", "path": "docs/en/docs/advanced/custom-response.md", "symbol": "JSON Responses { #json-responses }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/custom-response.md#L19-L34", "start_line": 19, "end_line": 34}
{"id": "docs/en/docs/advanced/custom-response.md::HTML Response { #html-response }::L35", "text": "# Doc: docs/en/docs/advanced/custom-response.md | Page: Custom Response - HTML, Stream, File, others { #custom-response-html-stream-file-others } | Section: HTML Response { #html-response }\n## HTML Response { #html-response }\n\nTo return a response with HTML directly from **FastAPI**, use `HTMLResponse`.\n\n* Import `HTMLResponse`.\n* Pass `HTMLResponse` as the parameter `response_class` of your *path operation decorator*.\n\n{* ../../docs_src/custom_response/tutorial002_py310.py hl[2,7] *}\n\n/// note\n\nThe parameter `response_class` will also be used to define the \"media type\" of the response.\n\nIn this case, the HTTP header `Content-Type` will be set to `text/html`.\n\nAnd it will be documented as such in OpenAPI.\n\n///\n\n### Return a `Response` { #return-a-response }\n\nAs seen in [Return a Response directly](response-directly.md), you can also override the response directly in your *path operation*, by returning it.\n\nThe same example from above, returning an `HTMLResponse`, could look like:\n\n{* ../../docs_src/custom_response/tutorial003_py310.py hl[2,7,19] *}\n\n/// warning\n\nA `Response` returned directly by your *path operation function* won't be documented in OpenAPI (for example, the `Content-Type` won't be documented) and won't be visible in the automatic interactive docs.\n\n///\n\n/// note\n\nOf course, the actual `Content-Type` header, status code, etc, will come from the `Response` object you returned.\n\n///\n\n### Document in OpenAPI and override `Response` { #document-in-openapi-and-override-response }\n\nIf you want to override the response from inside of the function but at the same time document the \"media type\" in OpenAPI, you can use the `response_class` parameter AND return a `Response` object.\n\nThe `response_class` will then be used only to document the OpenAPI *path operation*, but your `Response` will be used as is.\n\n#### Return an `HTMLResponse` directly { #return-an-htmlresponse-directly }\n\nFor example, it could be something like:\n\n{* ../../docs_src/custom_response/tutorial004_py310.py hl[7,21,23] *}\n\nIn this example, the function `generate_html_response()` already generates and returns a `Response` instead of returning the HTML in a `str`.\n\nBy returning the result of calling `generate_html_response()`, you are already returning a `Response` that will override the default **FastAPI** behavior.\n\nBut as you passed the `HTMLResponse` in the `response_class` too, **FastAPI** will know how to document it in OpenAPI and the interactive docs as HTML with `text/html`:\n\n![](\"/img/tutorial/custom-response/image01.png\")
", "source_type": "doc", "path": "docs/en/docs/advanced/custom-response.md", "symbol": "HTML Response { #html-response }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/custom-response.md#L35-L93", "start_line": 35, "end_line": 93}
{"id": "docs/en/docs/advanced/custom-response.md::Available responses { #available-responses }::L94", "text": "# Doc: docs/en/docs/advanced/custom-response.md | Page: Custom Response - HTML, Stream, File, others { #custom-response-html-stream-file-others } | Section: Available responses { #available-responses }\n## Available responses { #available-responses }\n\nHere are some of the available responses.\n\nKeep in mind that you can use `Response` to return anything else, or even create a custom sub-class.\n\n/// note | Technical Details\n\nYou could also use `from starlette.responses import HTMLResponse`.\n\n**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.\n\n///\n\n### `Response` { #response }\n\nThe main `Response` class, all the other responses inherit from it.\n\nYou can return it directly.\n\nIt accepts the following parameters:\n\n* `content` - A `str` or `bytes`.\n* `status_code` - An `int` HTTP status code.\n* `headers` - A `dict` of strings.\n* `media_type` - A `str` giving the media type. E.g. `\"text/html\"`.\n\nFastAPI (actually Starlette) will automatically include a Content-Length header. It will also include a Content-Type header, based on the `media_type` and appending a charset for text types.\n\n{* ../../docs_src/response_directly/tutorial002_py310.py hl[1,18] *}\n\n### `HTMLResponse` { #htmlresponse }\n\nTakes some text or bytes and returns an HTML response, as you read above.\n\n### `PlainTextResponse` { #plaintextresponse }\n\nTakes some text or bytes and returns a plain text response.\n\n{* ../../docs_src/custom_response/tutorial005_py310.py hl[2,7,9] *}\n\n### `JSONResponse` { #jsonresponse }\n\nTakes some data and returns an `application/json` encoded response.\n\nThis is the default response used in **FastAPI**, as you read above.\n\n/// note | Technical Details\n\nBut if you declare a response model or return type, that will be used directly to serialize the data to JSON, and a response with the right media type for JSON will be returned directly, without using the `JSONResponse` class.\n\nThis is the ideal way to get the best performance.\n\n///\n\n### `RedirectResponse` { #redirectresponse }\n\nReturns an HTTP redirect. Uses a 307 status code (Temporary Redirect) by default.\n\nYou can return a `RedirectResponse` directly:\n\n{* ../../docs_src/custom_response/tutorial006_py310.py hl[2,9] *}\n\n---\n\nOr you can use it in the `response_class` parameter:\n\n\n{* ../../docs_src/custom_response/tutorial006b_py310.py hl[2,7,9] *}\n\nIf you do that, then you can return the URL directly from your *path operation* function.\n\nIn this case, the `status_code` used will be the default one for the `RedirectResponse`, which is `307`.\n\n---\n\nYou can also use the `status_code` parameter combined with the `response_class` parameter:\n\n{* ../../docs_src/custom_response/tutorial006c_py310.py hl[2,7,9] *}\n\n### `StreamingResponse` { #streamingresponse }\n\nTakes an async generator or a normal generator/iterator (a function with `yield`) and streams the response body.\n\n{* ../../docs_src/custom_response/tutorial007_py310.py hl[3,16] *}\n\n/// note | Technical Details\n\nAn `async` task can only be cancelled when it reaches an `await`. If there is no `await`, the generator (function with `yield`) can not be cancelled properly and may keep running even after cancellation is requested.\n\nSince this small example does not need any `await` statements, we add an `await anyio.sleep(0)` to give the event loop a chance to handle cancellation.\n\nThis would be even more important with large or infinite streams.\n\n///\n\n/// tip\n\nInstead of returning a `StreamingResponse` directly, you should probably follow the style in [Stream Data](./stream-data.md), it's much more convenient and handles cancellation behind the scenes for you.\n\nIf you are streaming JSON Lines, follow the [Stream JSON Lines](../tutorial/stream-json-lines.md) tutorial.\n\n///\n\n### `FileResponse` { #fileresponse }\n\nAsynchronously streams a file as the response.\n\nTakes a different set of arguments to instantiate than the other response types:\n\n* `path` - The file path to the file to stream.\n* `headers` - Any custom headers to include, as a dictionary.\n* `media_type` - A string giving the media type. If unset, the filename or path will be used to infer a media type.\n* `filename` - If set, this will be included in the response `Content-Disposition`.\n\nFile responses will include appropriate `Content-Length`, `Last-Modified` and `ETag` headers.\n\n{* ../../docs_src/custom_response/tutorial009_py310.py hl[2,10] *}\n\nYou can also use the `response_class` parameter:\n\n{* ../../docs_src/custom_response/tutorial009b_py310.py hl[2,8,10] *}\n\nIn this case, you can return the file path directly from your *path operation* function.", "source_type": "doc", "path": "docs/en/docs/advanced/custom-response.md", "symbol": "Available responses { #available-responses }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/custom-response.md#L94-L218", "start_line": 94, "end_line": 218}
{"id": "docs/en/docs/advanced/custom-response.md::Custom response class { #custom-response-class }::L219", "text": "# Doc: docs/en/docs/advanced/custom-response.md | Page: Custom Response - HTML, Stream, File, others { #custom-response-html-stream-file-others } | Section: Custom response class { #custom-response-class }\n## Custom response class { #custom-response-class }\n\nYou can create your own custom response class, inheriting from `Response` and using it.\n\nFor example, let's say that you want to use [`orjson`](https://github.com/ijl/orjson) with some settings.\n\nLet's say you want it to return indented and formatted JSON, so you want to use the orjson option `orjson.OPT_INDENT_2`.\n\nYou could create a `CustomORJSONResponse`. The main thing you have to do is create a `Response.render(content)` method that returns the content as `bytes`:\n\n{* ../../docs_src/custom_response/tutorial009c_py310.py hl[9:14,17] *}\n\nNow instead of returning:\n\n```json\n{\"message\": \"Hello World\"}\n```\n\n...this response will return:\n\n```json\n{\n \"message\": \"Hello World\"\n}\n```\n\nOf course, you will probably find much better ways to take advantage of this than formatting JSON. 😉\n\n### `orjson` or Response Model { #orjson-or-response-model }\n\nIf what you are looking for is performance, you are probably better off using a [Response Model](../tutorial/response-model.md) than an `orjson` response.\n\nWith a response model, FastAPI will use Pydantic to serialize the data to JSON, without using intermediate steps, like converting it with `jsonable_encoder`, which would happen in any other case.\n\nAnd under the hood, Pydantic uses the same underlying Rust mechanisms as `orjson` to serialize to JSON, so you will already get the best performance with a response model.", "source_type": "doc", "path": "docs/en/docs/advanced/custom-response.md", "symbol": "Custom response class { #custom-response-class }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/custom-response.md#L219-L254", "start_line": 219, "end_line": 254}
{"id": "docs/en/docs/advanced/custom-response.md::Default response class { #default-response-class }::L255", "text": "# Doc: docs/en/docs/advanced/custom-response.md | Page: Custom Response - HTML, Stream, File, others { #custom-response-html-stream-file-others } | Section: Default response class { #default-response-class }\n## Default response class { #default-response-class }\n\nWhen creating a **FastAPI** class instance or an `APIRouter` you can specify which response class to use by default.\n\nThe parameter that defines this is `default_response_class`.\n\nIn the example below, **FastAPI** will use `HTMLResponse` by default, in all *path operations*, instead of JSON.\n\n{* ../../docs_src/custom_response/tutorial010_py310.py hl[2,4] *}\n\n/// tip\n\nYou can still override `response_class` in *path operations* as before.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/custom-response.md", "symbol": "Default response class { #default-response-class }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/custom-response.md#L255-L270", "start_line": 255, "end_line": 270}
{"id": "docs/en/docs/advanced/custom-response.md::Additional documentation { #additional-documentation }::L271", "text": "# Doc: docs/en/docs/advanced/custom-response.md | Page: Custom Response - HTML, Stream, File, others { #custom-response-html-stream-file-others } | Section: Additional documentation { #additional-documentation }\n## Additional documentation { #additional-documentation }\n\nYou can also declare the media type and many other details in OpenAPI using `responses`: [Additional Responses in OpenAPI](additional-responses.md).", "source_type": "doc", "path": "docs/en/docs/advanced/custom-response.md", "symbol": "Additional documentation { #additional-documentation }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/custom-response.md#L271-L273", "start_line": 271, "end_line": 273}
{"id": "docs/en/docs/advanced/dataclasses.md::Using Dataclasses { #using-dataclasses }::L1", "text": "# Doc: docs/en/docs/advanced/dataclasses.md | Page: Using Dataclasses { #using-dataclasses } | Section: Using Dataclasses { #using-dataclasses }\n# Using Dataclasses { #using-dataclasses }\n\nFastAPI is built on top of **Pydantic**, and I have been showing you how to use Pydantic models to declare requests and responses.\n\nBut FastAPI also supports using [`dataclasses`](https://docs.python.org/3/library/dataclasses.html) the same way:\n\n{* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *}\n\nThis is still supported thanks to **Pydantic**, as it has [internal support for `dataclasses`](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel).\n\nSo, even with the code above that doesn't use Pydantic explicitly, FastAPI is using Pydantic to convert those standard dataclasses to Pydantic's own flavor of dataclasses.\n\nAnd of course, it supports the same:\n\n* data validation\n* data serialization\n* data documentation, etc.\n\nThis works the same way as with Pydantic models. And it is actually achieved in the same way underneath, using Pydantic.\n\n/// note\n\nKeep in mind that dataclasses can't do everything Pydantic models can do.\n\nSo, you might still need to use Pydantic models.\n\nBut if you have a bunch of dataclasses lying around, this is a nice trick to use them to power a web API using FastAPI. 🤓\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/dataclasses.md", "symbol": "Using Dataclasses { #using-dataclasses }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/dataclasses.md#L1-L30", "start_line": 1, "end_line": 30}
{"id": "docs/en/docs/advanced/dataclasses.md::Dataclasses in `response_model` { #dataclasses-in-response-model }::L31", "text": "# Doc: docs/en/docs/advanced/dataclasses.md | Page: Using Dataclasses { #using-dataclasses } | Section: Dataclasses in `response_model` { #dataclasses-in-response-model }\n## Dataclasses in `response_model` { #dataclasses-in-response-model }\n\nYou can also use `dataclasses` in the `response_model` parameter:\n\n{* ../../docs_src/dataclasses_/tutorial002_py310.py hl[1,6:12,18] *}\n\nThe dataclass will be automatically converted to a Pydantic dataclass.\n\nThis way, its schema will show up in the API docs user interface:\n\n![](\"/img/tutorial/dataclasses/image01.png\")
", "source_type": "doc", "path": "docs/en/docs/advanced/dataclasses.md", "symbol": "Dataclasses in `response_model` { #dataclasses-in-response-model }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/dataclasses.md#L31-L42", "start_line": 31, "end_line": 42}
{"id": "docs/en/docs/advanced/dataclasses.md::Dataclasses in Nested Data Structures { #dataclasses-in-nested-data-structures }::L43", "text": "# Doc: docs/en/docs/advanced/dataclasses.md | Page: Using Dataclasses { #using-dataclasses } | Section: Dataclasses in Nested Data Structures { #dataclasses-in-nested-data-structures }\n## Dataclasses in Nested Data Structures { #dataclasses-in-nested-data-structures }\n\nYou can also combine `dataclasses` with other type annotations to make nested data structures.\n\nIn some cases, you might still have to use Pydantic's version of `dataclasses`. For example, if you have errors with the automatically generated API documentation.\n\nIn that case, you can simply swap the standard `dataclasses` with `pydantic.dataclasses`, which is a drop-in replacement:\n\n{* ../../docs_src/dataclasses_/tutorial003_py310.py hl[1,4,7:10,13:16,22:24,27] *}\n\n1. We still import `field` from standard `dataclasses`.\n\n2. `pydantic.dataclasses` is a drop-in replacement for `dataclasses`.\n\n3. The `Author` dataclass includes a list of `Item` dataclasses.\n\n4. The `Author` dataclass is used as the `response_model` parameter.\n\n5. You can use other standard type annotations with dataclasses as the request body.\n\n In this case, it's a list of `Item` dataclasses.\n\n6. Here we are returning a dictionary that contains `items` which is a list of dataclasses.\n\n FastAPI is still capable of serializing the data to JSON.\n\n7. Here the `response_model` is using a type annotation of a list of `Author` dataclasses.\n\n Again, you can combine `dataclasses` with standard type annotations.\n\n8. Notice that this *path operation function* uses regular `def` instead of `async def`.\n\n As always, in FastAPI you can combine `def` and `async def` as needed.\n\n If you need a refresher about when to use which, check out the section _\"In a hurry?\"_ in the docs about [`async` and `await`](../async.md#in-a-hurry).\n\n9. This *path operation function* is not returning dataclasses (although it could), but a list of dictionaries with internal data.\n\n FastAPI will use the `response_model` parameter (that includes dataclasses) to convert the response.\n\nYou can combine `dataclasses` with other type annotations in many different combinations to form complex data structures.\n\nCheck the in-code annotation tips above to see more specific details.", "source_type": "doc", "path": "docs/en/docs/advanced/dataclasses.md", "symbol": "Dataclasses in Nested Data Structures { #dataclasses-in-nested-data-structures }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/dataclasses.md#L43-L86", "start_line": 43, "end_line": 86}
{"id": "docs/en/docs/advanced/dataclasses.md::Learn More { #learn-more }::L87", "text": "# Doc: docs/en/docs/advanced/dataclasses.md | Page: Using Dataclasses { #using-dataclasses } | Section: Learn More { #learn-more }\n## Learn More { #learn-more }\n\nYou can also combine `dataclasses` with other Pydantic models, inherit from them, include them in your own models, etc.\n\nTo learn more, check the [Pydantic docs about dataclasses](https://docs.pydantic.dev/latest/concepts/dataclasses/).", "source_type": "doc", "path": "docs/en/docs/advanced/dataclasses.md", "symbol": "Learn More { #learn-more }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/dataclasses.md#L87-L92", "start_line": 87, "end_line": 92}
{"id": "docs/en/docs/advanced/dataclasses.md::Version { #version }::L93", "text": "# Doc: docs/en/docs/advanced/dataclasses.md | Page: Using Dataclasses { #using-dataclasses } | Section: Version { #version }\n## Version { #version }\n\nThis is available since FastAPI version `0.67.0`. 🔖", "source_type": "doc", "path": "docs/en/docs/advanced/dataclasses.md", "symbol": "Version { #version }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/dataclasses.md#L93-L95", "start_line": 93, "end_line": 95}
{"id": "docs/en/docs/advanced/events.md::Lifespan Events { #lifespan-events }::L1", "text": "# Doc: docs/en/docs/advanced/events.md | Page: Lifespan Events { #lifespan-events } | Section: Lifespan Events { #lifespan-events }\n# Lifespan Events { #lifespan-events }\n\nYou can define logic (code) that should be executed before the application **starts up**. This means that this code will be executed **once**, **before** the application **starts receiving requests**.\n\nThe same way, you can define logic (code) that should be executed when the application is **shutting down**. In this case, this code will be executed **once**, **after** having handled possibly **many requests**.\n\nBecause this code is executed before the application **starts** taking requests, and right after it **finishes** handling requests, it covers the whole application **lifespan** (the word \"lifespan\" will be important in a second 😉).\n\nThis can be very useful for setting up **resources** that you need to use for the whole app, and that are **shared** among requests, and/or that you need to **clean up** afterwards. For example, a database connection pool, or loading a shared machine learning model.", "source_type": "doc", "path": "docs/en/docs/advanced/events.md", "symbol": "Lifespan Events { #lifespan-events }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/events.md#L1-L10", "start_line": 1, "end_line": 10}
{"id": "docs/en/docs/advanced/events.md::Use Case { #use-case }::L11", "text": "# Doc: docs/en/docs/advanced/events.md | Page: Lifespan Events { #lifespan-events } | Section: Use Case { #use-case }\n## Use Case { #use-case }\n\nLet's start with an example **use case** and then see how to solve it with this.\n\nLet's imagine that you have some **machine learning models** that you want to use to handle requests. 🤖\n\nThe same models are shared among requests, so, it's not one model per request, or one per user or something similar.\n\nLet's imagine that loading the model can **take quite some time**, because it has to read a lot of **data from disk**. So you don't want to do it for every request.\n\nYou could load it at the top level of the module/file, but that would also mean that it would **load the model** even if you are just running a simple automated test, then that test would be **slow** because it would have to wait for the model to load before being able to run an independent part of the code.\n\nThat's what we'll solve, let's load the model before the requests are handled, but only right before the application starts receiving requests, not while the code is being loaded.", "source_type": "doc", "path": "docs/en/docs/advanced/events.md", "symbol": "Use Case { #use-case }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/events.md#L11-L24", "start_line": 11, "end_line": 24}
{"id": "docs/en/docs/advanced/events.md::Lifespan { #lifespan }::L25", "text": "# Doc: docs/en/docs/advanced/events.md | Page: Lifespan Events { #lifespan-events } | Section: Lifespan { #lifespan }\n## Lifespan { #lifespan }\n\nYou can define this *startup* and *shutdown* logic using the `lifespan` parameter of the `FastAPI` app, and a \"context manager\" (I'll show you what that is in a second).\n\nLet's start with an example and then see it in detail.\n\nWe create an async function `lifespan()` with `yield` like this:\n\n{* ../../docs_src/events/tutorial003_py310.py hl[16,19] *}\n\nHere we are simulating the expensive *startup* operation of loading the model by putting the (fake) model function in the dictionary with machine learning models before the `yield`. This code will be executed **before** the application **starts taking requests**, during the *startup*.\n\nAnd then, right after the `yield`, we unload the model. This code will be executed **after** the application **finishes handling requests**, right before the *shutdown*. This could, for example, release resources like memory or a GPU.\n\n/// tip\n\nThe `shutdown` would happen when you are **stopping** the application.\n\nMaybe you need to start a new version, or you just got tired of running it. 🤷\n\n///\n\n### Lifespan function { #lifespan-function }\n\nThe first thing to notice, is that we are defining an async function with `yield`. This is very similar to Dependencies with `yield`.\n\n{* ../../docs_src/events/tutorial003_py310.py hl[14:19] *}\n\nThe first part of the function, before the `yield`, will be executed **before** the application starts.\n\nAnd the part after the `yield` will be executed **after** the application has finished.\n\n### Async Context Manager { #async-context-manager }\n\nIf you check, the function is decorated with an `@asynccontextmanager`.\n\nThat converts the function into something called an \"**async context manager**\".\n\n{* ../../docs_src/events/tutorial003_py310.py hl[1,13] *}\n\nA **context manager** in Python is something that you can use in a `with` statement, for example, `open()` can be used as a context manager:\n\n```Python\nwith open(\"file.txt\") as file:\n file.read()\n```\n\nIn recent versions of Python, there's also an **async context manager**. You would use it with `async with`:\n\n```Python\nasync with lifespan(app):\n await do_stuff()\n```\n\nWhen you create a context manager or an async context manager like above, what it does is that, before entering the `with` block, it will execute the code before the `yield`, and after exiting the `with` block, it will execute the code after the `yield`.\n\nIn our code example above, we don't use it directly, but we pass it to FastAPI for it to use it.\n\nThe `lifespan` parameter of the `FastAPI` app takes an **async context manager**, so we can pass our new `lifespan` async context manager to it.\n\n{* ../../docs_src/events/tutorial003_py310.py hl[22] *}", "source_type": "doc", "path": "docs/en/docs/advanced/events.md", "symbol": "Lifespan { #lifespan }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/events.md#L25-L86", "start_line": 25, "end_line": 86}
{"id": "docs/en/docs/advanced/events.md::Alternative Events (deprecated) { #alternative-events-deprecated }::L87", "text": "# Doc: docs/en/docs/advanced/events.md | Page: Lifespan Events { #lifespan-events } | Section: Alternative Events (deprecated) { #alternative-events-deprecated }\n## Alternative Events (deprecated) { #alternative-events-deprecated }\n\n/// warning\n\nThe recommended way to handle the *startup* and *shutdown* is using the `lifespan` parameter of the `FastAPI` app as described above. If you provide a `lifespan` parameter, `startup` and `shutdown` event handlers will no longer be called. It's all `lifespan` or all events, not both.\n\nYou can probably skip this part.\n\n///\n\nThere's an alternative way to define this logic to be executed during *startup* and during *shutdown*.\n\nYou can define event handlers (functions) that need to be executed before the application starts up, or when the application is shutting down.\n\nThese functions can be declared with `async def` or normal `def`.\n\n### `startup` event { #startup-event }\n\nTo add a function that should be run before the application starts, declare it with the event `\"startup\"`:\n\n{* ../../docs_src/events/tutorial001_py310.py hl[8] *}\n\nIn this case, the `startup` event handler function will initialize the items \"database\" (just a `dict`) with some values.\n\nYou can add more than one event handler function.\n\nAnd your application won't start receiving requests until all the `startup` event handlers have completed.\n\n### `shutdown` event { #shutdown-event }\n\nTo add a function that should be run when the application is shutting down, declare it with the event `\"shutdown\"`:\n\n{* ../../docs_src/events/tutorial002_py310.py hl[6] *}\n\nHere, the `shutdown` event handler function will write a text line `\"Application shutdown\"` to a file `log.txt`.\n\n/// note\n\nIn the `open()` function, the `mode=\"a\"` means \"append\", so, the line will be added after whatever is on that file, without overwriting the previous contents.\n\n///\n\n/// tip\n\nNotice that in this case we are using a standard Python `open()` function that interacts with a file.\n\nSo, it involves I/O (input/output), that requires \"waiting\" for things to be written to disk.\n\nBut `open()` doesn't use `async` and `await`.\n\nSo, we declare the event handler function with standard `def` instead of `async def`.\n\n///\n\n### `startup` and `shutdown` together { #startup-and-shutdown-together }\n\nThere's a high chance that the logic for your *startup* and *shutdown* is connected, you might want to start something and then finish it, acquire a resource and then release it, etc.\n\nDoing that in separate functions that don't share logic or variables together is more difficult as you would need to store values in global variables or similar tricks.\n\nBecause of that, it's now recommended to instead use the `lifespan` as explained above.", "source_type": "doc", "path": "docs/en/docs/advanced/events.md", "symbol": "Alternative Events (deprecated) { #alternative-events-deprecated }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/events.md#L87-L148", "start_line": 87, "end_line": 148}
{"id": "docs/en/docs/advanced/events.md::Technical Details { #technical-details }::L149", "text": "# Doc: docs/en/docs/advanced/events.md | Page: Lifespan Events { #lifespan-events } | Section: Technical Details { #technical-details }\n## Technical Details { #technical-details }\n\nJust a technical detail for the curious nerds. 🤓\n\nUnderneath, in the ASGI technical specification, this is part of the [Lifespan Protocol](https://asgi.readthedocs.io/en/latest/specs/lifespan.html), and it defines events called `startup` and `shutdown`.\n\n/// note\n\nYou can read more about the Starlette `lifespan` handlers in [Starlette's Lifespan' docs](https://www.starlette.dev/lifespan/).\n\nIncluding how to handle lifespan state that can be used in other areas of your code.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/events.md", "symbol": "Technical Details { #technical-details }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/events.md#L149-L162", "start_line": 149, "end_line": 162}
{"id": "docs/en/docs/advanced/events.md::Sub Applications { #sub-applications }::L163", "text": "# Doc: docs/en/docs/advanced/events.md | Page: Lifespan Events { #lifespan-events } | Section: Sub Applications { #sub-applications }\n## Sub Applications { #sub-applications }\n\n🚨 Keep in mind that these lifespan events (startup and shutdown) will only be executed for the main application, not for [Sub Applications - Mounts](sub-applications.md).", "source_type": "doc", "path": "docs/en/docs/advanced/events.md", "symbol": "Sub Applications { #sub-applications }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/events.md#L163-L165", "start_line": 163, "end_line": 165}
{"id": "docs/en/docs/advanced/generate-clients.md::Generating SDKs { #generating-sdks }::L1", "text": "# Doc: docs/en/docs/advanced/generate-clients.md | Page: Generating SDKs { #generating-sdks } | Section: Generating SDKs { #generating-sdks }\n# Generating SDKs { #generating-sdks }\n\nBecause **FastAPI** is based on the **OpenAPI** specification, its APIs can be described in a standard format that many tools understand.\n\nThis makes it easy to generate up-to-date **documentation**, client libraries (**SDKs**) in multiple languages, and **testing** or **automation workflows** that stay in sync with your code.\n\nIn this guide, you'll learn how to generate a **TypeScript SDK** for your FastAPI backend.", "source_type": "doc", "path": "docs/en/docs/advanced/generate-clients.md", "symbol": "Generating SDKs { #generating-sdks }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/generate-clients.md#L1-L8", "start_line": 1, "end_line": 8}
{"id": "docs/en/docs/advanced/generate-clients.md::Open Source SDK Generators { #open-source-sdk-generators }::L9", "text": "# Doc: docs/en/docs/advanced/generate-clients.md | Page: Generating SDKs { #generating-sdks } | Section: Open Source SDK Generators { #open-source-sdk-generators }\n## Open Source SDK Generators { #open-source-sdk-generators }\n\nA versatile option is the [OpenAPI Generator](https://openapi-generator.tech/), which supports **many programming languages** and can generate SDKs from your OpenAPI specification.\n\nFor **TypeScript clients**, [Hey API](https://heyapi.dev/) is a purpose-built solution, providing an optimized experience for the TypeScript ecosystem.\n\nYou can discover more SDK generators on [OpenAPI.Tools](https://openapi.tools/#sdk).\n\n/// tip\n\nFastAPI automatically generates **OpenAPI 3.1** specifications, so any tool you use must support this version.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/generate-clients.md", "symbol": "Open Source SDK Generators { #open-source-sdk-generators }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/generate-clients.md#L9-L22", "start_line": 9, "end_line": 22}
{"id": "docs/en/docs/advanced/generate-clients.md::Create a TypeScript SDK { #create-a-typescript-sdk }::L23", "text": "# Doc: docs/en/docs/advanced/generate-clients.md | Page: Generating SDKs { #generating-sdks } | Section: Create a TypeScript SDK { #create-a-typescript-sdk }\n## Create a TypeScript SDK { #create-a-typescript-sdk }\n\nLet's start with a simple FastAPI application:\n\n{* ../../docs_src/generate_clients/tutorial001_py310.py hl[7:9,12:13,16:17,21] *}\n\nNotice that the *path operations* define the models they use for request payload and response payload, using the models `Item` and `ResponseMessage`.\n\n### API Docs { #api-docs }\n\nIf you go to `/docs`, you will see that it has the **schemas** for the data to be sent in requests and received in responses:\n\n![](\"/img/tutorial/generate-clients/image01.png\")
\n\nYou can see those schemas because they were declared with the models in the app.\n\nThat information is available in the app's **OpenAPI schema**, and then shown in the API docs.\n\nThat same information from the models that is included in OpenAPI is what can be used to **generate the client code**.\n\n### Hey API { #hey-api }\n\nOnce we have a FastAPI app with the models, we can use Hey API to generate a TypeScript client. The fastest way to do that is via npx.\n\n```sh\nnpx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client\n```\n\nThis will generate a TypeScript SDK in `./src/client`.\n\nYou can learn how to [install `@hey-api/openapi-ts`](https://heyapi.dev/openapi-ts/get-started) and read about the [generated output](https://heyapi.dev/openapi-ts/output) on their website.\n\n### Using the SDK { #using-the-sdk }\n\nNow you can import and use the client code. It could look like this, notice that you get autocompletion for the methods:\n\n![](\"/img/tutorial/generate-clients/image02.png\")
\n\nYou will also get autocompletion for the payload to send:\n\n![](\"/img/tutorial/generate-clients/image03.png\")
\n\n/// tip\n\nNotice the autocompletion for `name` and `price`, that was defined in the FastAPI application, in the `Item` model.\n\n///\n\nYou will have inline errors for the data that you send:\n\n![](\"/img/tutorial/generate-clients/image04.png\")
\n\nThe response object will also have autocompletion:\n\n![](\"/img/tutorial/generate-clients/image05.png\")
", "source_type": "doc", "path": "docs/en/docs/advanced/generate-clients.md", "symbol": "Create a TypeScript SDK { #create-a-typescript-sdk }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/generate-clients.md#L23-L78", "start_line": 23, "end_line": 78}
{"id": "docs/en/docs/advanced/generate-clients.md::FastAPI App with Tags { #fastapi-app-with-tags }::L79", "text": "# Doc: docs/en/docs/advanced/generate-clients.md | Page: Generating SDKs { #generating-sdks } | Section: FastAPI App with Tags { #fastapi-app-with-tags }\n## FastAPI App with Tags { #fastapi-app-with-tags }\n\nIn many cases, your FastAPI app will be bigger, and you will probably use tags to separate different groups of *path operations*.\n\nFor example, you could have a section for **items** and another section for **users**, and they could be separated by tags:\n\n{* ../../docs_src/generate_clients/tutorial002_py310.py hl[21,26,34] *}\n\n### Generate a TypeScript Client with Tags { #generate-a-typescript-client-with-tags }\n\nIf you generate a client for a FastAPI app using tags, it will normally also separate the client code based on the tags.\n\nThis way, you will be able to have things ordered and grouped correctly for the client code:\n\n![](\"/img/tutorial/generate-clients/image06.png\")
\n\nIn this case, you have:\n\n* `ItemsService`\n* `UsersService`\n\n### Client Method Names { #client-method-names }\n\nRight now, the generated method names like `createItemItemsPost` don't look very clean:\n\n```TypeScript\nItemsService.createItemItemsPost({name: \"Plumbus\", price: 5})\n```\n\n...that's because the client generator uses the OpenAPI internal **operation ID** for each *path operation*.\n\nOpenAPI requires that each operation ID is unique across all the *path operations*, so FastAPI uses the **function name**, the **path**, and the **HTTP method/operation** to generate that operation ID, because that way it can make sure that the operation IDs are unique.\n\nBut I'll show you how to improve that next. 🤓", "source_type": "doc", "path": "docs/en/docs/advanced/generate-clients.md", "symbol": "FastAPI App with Tags { #fastapi-app-with-tags }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/generate-clients.md#L79-L113", "start_line": 79, "end_line": 113}
{"id": "docs/en/docs/advanced/generate-clients.md::Custom Operation IDs and Better Method Names { #custom-operation-ids-and-better-method-names }::L114", "text": "# Doc: docs/en/docs/advanced/generate-clients.md | Page: Generating SDKs { #generating-sdks } | Section: Custom Operation IDs and Better Method Names { #custom-operation-ids-and-better-method-names }\n## Custom Operation IDs and Better Method Names { #custom-operation-ids-and-better-method-names }\n\nYou can **modify** the way these operation IDs are **generated** to make them simpler and have **simpler method names** in the clients.\n\nIn this case, you will have to ensure that each operation ID is **unique** in some other way.\n\nFor example, you could make sure that each *path operation* has a tag, and then generate the operation ID based on the **tag** and the *path operation* **name** (the function name).\n\n### Custom Generate Unique ID Function { #custom-generate-unique-id-function }\n\nFastAPI uses a **unique ID** for each *path operation*, which is used for the **operation ID** and also for the names of any needed custom models, for requests or responses.\n\nYou can customize that function. It takes an `APIRoute` and outputs a string.\n\nFor example, here it is using the first tag (you will probably have only one tag) and the *path operation* name (the function name).\n\nYou can then pass that custom function to **FastAPI** as the `generate_unique_id_function` parameter:\n\n{* ../../docs_src/generate_clients/tutorial003_py310.py hl[6:7,10] *}\n\n### Generate a TypeScript Client with Custom Operation IDs { #generate-a-typescript-client-with-custom-operation-ids }\n\nNow, if you generate the client again, you will see that it has the improved method names:\n\n![](\"/img/tutorial/generate-clients/image07.png\")
\n\nAs you see, the method names now have the tag and then the function name, now they don't include information from the URL path and the HTTP operation.\n\n### Preprocess the OpenAPI Specification for the Client Generator { #preprocess-the-openapi-specification-for-the-client-generator }\n\nThe generated code still has some **duplicated information**.\n\nWe already know that this method is related to the **items** because that word is in the `ItemsService` (taken from the tag), but we still have the tag name prefixed in the method name too. 😕\n\nWe will probably still want to keep it for OpenAPI in general, as that will ensure that the operation IDs are **unique**.\n\nBut for the generated client, we could **modify** the OpenAPI operation IDs right before generating the clients, just to make those method names nicer and **cleaner**.\n\nWe could download the OpenAPI JSON to a file `openapi.json` and then we could **remove that prefixed tag** with a script like this:\n\n{* ../../docs_src/generate_clients/tutorial004_py310.py *}\n\n//// tab | Node.js\n\n```Javascript\n{!> ../../docs_src/generate_clients/tutorial004.js!}\n```\n\n////\n\nWith that, the operation IDs would be renamed from things like `items-get_items` to just `get_items`, that way the client generator can generate simpler method names.\n\n### Generate a TypeScript Client with the Preprocessed OpenAPI { #generate-a-typescript-client-with-the-preprocessed-openapi }\n\nSince the end result is now in an `openapi.json` file, you need to update your input location:\n\n```sh\nnpx @hey-api/openapi-ts -i ./openapi.json -o src/client\n```\n\nAfter generating the new client, you would now have **clean method names**, with all the **autocompletion**, **inline errors**, etc:\n\n![](\"/img/tutorial/generate-clients/image08.png\")
", "source_type": "doc", "path": "docs/en/docs/advanced/generate-clients.md", "symbol": "Custom Operation IDs and Better Method Names { #custom-operation-ids-and-better-method-names }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/generate-clients.md#L114-L177", "start_line": 114, "end_line": 177}
{"id": "docs/en/docs/advanced/generate-clients.md::Benefits { #benefits }::L178", "text": "# Doc: docs/en/docs/advanced/generate-clients.md | Page: Generating SDKs { #generating-sdks } | Section: Benefits { #benefits }\n## Benefits { #benefits }\n\nWhen using the automatically generated clients, you would get **autocompletion** for:\n\n* Methods.\n* Request payloads in the body, query parameters, etc.\n* Response payloads.\n\nYou would also have **inline errors** for everything.\n\nAnd whenever you update the backend code, and **regenerate** the frontend, it would have any new *path operations* available as methods, the old ones removed, and any other change would be reflected on the generated code. 🤓\n\nThis also means that if something changed, it will be **reflected** on the client code automatically. And if you **build** the client, it will error out if you have any **mismatch** in the data used.\n\nSo, you would **detect many errors** very early in the development cycle instead of having to wait for the errors to show up to your final users in production and then trying to debug where the problem is. ✨", "source_type": "doc", "path": "docs/en/docs/advanced/generate-clients.md", "symbol": "Benefits { #benefits }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/generate-clients.md#L178-L192", "start_line": 178, "end_line": 192}
{"id": "docs/en/docs/advanced/index.md::Additional Features { #additional-features }::L3", "text": "# Doc: docs/en/docs/advanced/index.md | Page: Advanced User Guide { #advanced-user-guide } | Section: Additional Features { #additional-features }\n## Additional Features { #additional-features }\n\nThe main [Tutorial - User Guide](../tutorial/index.md) should be enough to give you a tour through all the main features of **FastAPI**.\n\nIn the next sections you will see other options, configurations, and additional features.\n\n/// tip\n\nThe next sections are **not necessarily \"advanced\"**.\n\nAnd it's possible that for your use case, the solution is in one of them.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/index.md", "symbol": "Additional Features { #additional-features }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/index.md#L3-L16", "start_line": 3, "end_line": 16}
{"id": "docs/en/docs/advanced/index.md::Read the Tutorial first { #read-the-tutorial-first }::L17", "text": "# Doc: docs/en/docs/advanced/index.md | Page: Advanced User Guide { #advanced-user-guide } | Section: Read the Tutorial first { #read-the-tutorial-first }\n## Read the Tutorial first { #read-the-tutorial-first }\n\nYou could still use most of the features in **FastAPI** with the knowledge from the main [Tutorial - User Guide](../tutorial/index.md).\n\nAnd the next sections assume you already read it, and assume that you know those main ideas.", "source_type": "doc", "path": "docs/en/docs/advanced/index.md", "symbol": "Read the Tutorial first { #read-the-tutorial-first }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/index.md#L17-L21", "start_line": 17, "end_line": 21}
{"id": "docs/en/docs/advanced/json-base64-bytes.md::JSON with Bytes as Base64 { #json-with-bytes-as-base64 }::L1", "text": "# Doc: docs/en/docs/advanced/json-base64-bytes.md | Page: JSON with Bytes as Base64 { #json-with-bytes-as-base64 } | Section: JSON with Bytes as Base64 { #json-with-bytes-as-base64 }\n# JSON with Bytes as Base64 { #json-with-bytes-as-base64 }\n\nIf your app needs to receive and send JSON data, but you need to include binary data in it, you can encode it as base64.", "source_type": "doc", "path": "docs/en/docs/advanced/json-base64-bytes.md", "symbol": "JSON with Bytes as Base64 { #json-with-bytes-as-base64 }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/json-base64-bytes.md#L1-L4", "start_line": 1, "end_line": 4}
{"id": "docs/en/docs/advanced/json-base64-bytes.md::Base64 vs Files { #base64-vs-files }::L5", "text": "# Doc: docs/en/docs/advanced/json-base64-bytes.md | Page: JSON with Bytes as Base64 { #json-with-bytes-as-base64 } | Section: Base64 vs Files { #base64-vs-files }\n## Base64 vs Files { #base64-vs-files }\n\nConsider first if you can use [Request Files](../tutorial/request-files.md) for uploading binary data and [Custom Response - FileResponse](./custom-response.md#fileresponse) for sending binary data, instead of encoding it in JSON.\n\nJSON can only contain UTF-8 encoded strings, so it can't contain raw bytes.\n\nBase64 can encode binary data in strings, but to do it, it needs to use more characters than the original binary data, so it would normally be less efficient than regular files.\n\nUse base64 only if you definitely need to include binary data in JSON, and you can't use files for that.", "source_type": "doc", "path": "docs/en/docs/advanced/json-base64-bytes.md", "symbol": "Base64 vs Files { #base64-vs-files }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/json-base64-bytes.md#L5-L14", "start_line": 5, "end_line": 14}
{"id": "docs/en/docs/advanced/json-base64-bytes.md::Pydantic `bytes` { #pydantic-bytes }::L15", "text": "# Doc: docs/en/docs/advanced/json-base64-bytes.md | Page: JSON with Bytes as Base64 { #json-with-bytes-as-base64 } | Section: Pydantic `bytes` { #pydantic-bytes }\n## Pydantic `bytes` { #pydantic-bytes }\n\nYou can declare a Pydantic model with `bytes` fields, and then use `val_json_bytes` in the model config to tell it to use base64 to *validate* input JSON data, as part of that validation it will decode the base64 string into bytes.\n\n{* ../../docs_src/json_base64_bytes/tutorial001_py310.py ln[1:9,29:35] hl[9] *}\n\nIf you check the `/docs`, they will show that the field `data` expects base64 encoded bytes:\n\n![](\"/img/tutorial/json-base64-bytes/image01.png\")
\n![](\"/img/tutorial/openapi-callbacks/image01.png\")
", "source_type": "doc", "path": "docs/en/docs/advanced/openapi-callbacks.md", "symbol": "Write the callback documentation code { #write-the-callback-documentation-code }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/openapi-callbacks.md#L73-L186", "start_line": 73, "end_line": 186}
{"id": "docs/en/docs/advanced/openapi-webhooks.md::OpenAPI Webhooks { #openapi-webhooks }::L1", "text": "# Doc: docs/en/docs/advanced/openapi-webhooks.md | Page: OpenAPI Webhooks { #openapi-webhooks } | Section: OpenAPI Webhooks { #openapi-webhooks }\n# OpenAPI Webhooks { #openapi-webhooks }\n\nThere are cases where you want to tell your API **users** that your app could call *their* app (sending a request) with some data, normally to **notify** of some type of **event**.\n\nThis means that instead of the normal process of your users sending requests to your API, it's **your API** (or your app) that could **send requests to their system** (to their API, their app).\n\nThis is normally called a **webhook**.", "source_type": "doc", "path": "docs/en/docs/advanced/openapi-webhooks.md", "symbol": "OpenAPI Webhooks { #openapi-webhooks }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/openapi-webhooks.md#L1-L8", "start_line": 1, "end_line": 8}
{"id": "docs/en/docs/advanced/openapi-webhooks.md::Webhooks steps { #webhooks-steps }::L9", "text": "# Doc: docs/en/docs/advanced/openapi-webhooks.md | Page: OpenAPI Webhooks { #openapi-webhooks } | Section: Webhooks steps { #webhooks-steps }\n## Webhooks steps { #webhooks-steps }\n\nThe process normally is that **you define** in your code what is the message that you will send, the **body of the request**.\n\nYou also define in some way at which **moments** your app will send those requests or events.\n\nAnd **your users** define in some way (for example in a web dashboard somewhere) the **URL** where your app should send those requests.\n\nAll the **logic** about how to register the URLs for webhooks and the code to actually send those requests is up to you. You write it however you want to in **your own code**.", "source_type": "doc", "path": "docs/en/docs/advanced/openapi-webhooks.md", "symbol": "Webhooks steps { #webhooks-steps }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/openapi-webhooks.md#L9-L18", "start_line": 9, "end_line": 18}
{"id": "docs/en/docs/advanced/openapi-webhooks.md::Documenting webhooks with **FastAPI** and OpenAPI { #documenting-webhooks-with-fastapi-and-openapi }::L19", "text": "# Doc: docs/en/docs/advanced/openapi-webhooks.md | Page: OpenAPI Webhooks { #openapi-webhooks } | Section: Documenting webhooks with **FastAPI** and OpenAPI { #documenting-webhooks-with-fastapi-and-openapi }\n## Documenting webhooks with **FastAPI** and OpenAPI { #documenting-webhooks-with-fastapi-and-openapi }\n\nWith **FastAPI**, using OpenAPI, you can define the names of these webhooks, the types of HTTP operations that your app can send (e.g. `POST`, `PUT`, etc.) and the request **bodies** that your app would send.\n\nThis can make it a lot easier for your users to **implement their APIs** to receive your **webhook** requests, they might even be able to autogenerate some of their own API code.\n\n/// note\n\nWebhooks are available in OpenAPI 3.1.0 and above, supported by FastAPI `0.99.0` and above.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/openapi-webhooks.md", "symbol": "Documenting webhooks with **FastAPI** and OpenAPI { #documenting-webhooks-with-fastapi-and-openapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/openapi-webhooks.md#L19-L30", "start_line": 19, "end_line": 30}
{"id": "docs/en/docs/advanced/openapi-webhooks.md::An app with webhooks { #an-app-with-webhooks }::L31", "text": "# Doc: docs/en/docs/advanced/openapi-webhooks.md | Page: OpenAPI Webhooks { #openapi-webhooks } | Section: An app with webhooks { #an-app-with-webhooks }\n## An app with webhooks { #an-app-with-webhooks }\n\nWhen you create a **FastAPI** application, there is a `webhooks` attribute that you can use to define *webhooks*, the same way you would define *path operations*, for example with `@app.webhooks.post()`.\n\n{* ../../docs_src/openapi_webhooks/tutorial001_py310.py hl[9:12,15:20] *}\n\nThe webhooks that you define will end up in the **OpenAPI** schema and the automatic **docs UI**.\n\n/// note\n\nThe `app.webhooks` object is actually just an `APIRouter`, the same type you would use when structuring your app with multiple files.\n\n///\n\nNotice that with webhooks you are actually not declaring a *path* (like `/items/`), the text you pass there is just an **identifier** of the webhook (the name of the event), for example in `@app.webhooks.post(\"new-subscription\")`, the webhook name is `new-subscription`.\n\nThis is because it is expected that **your users** would define the actual **URL path** where they want to receive the webhook request in some other way (e.g. a web dashboard).\n\n### Check the docs { #check-the-docs }\n\nNow you can start your app and go to [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).\n\nYou will see your docs have the normal *path operations* and now also some **webhooks**:\n\n![](\"/img/tutorial/openapi-webhooks/image01.png\")
", "source_type": "doc", "path": "docs/en/docs/advanced/openapi-webhooks.md", "symbol": "An app with webhooks { #an-app-with-webhooks }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/openapi-webhooks.md#L31-L55", "start_line": 31, "end_line": 55}
{"id": "docs/en/docs/advanced/path-operation-advanced-configuration.md::Path Operation Advanced Configuration { #path-operation-advanced-configuration }::L1", "text": "# Doc: docs/en/docs/advanced/path-operation-advanced-configuration.md | Page: Path Operation Advanced Configuration { #path-operation-advanced-configuration } | Section: Path Operation Advanced Configuration { #path-operation-advanced-configuration }\n# Path Operation Advanced Configuration { #path-operation-advanced-configuration }", "source_type": "doc", "path": "docs/en/docs/advanced/path-operation-advanced-configuration.md", "symbol": "Path Operation Advanced Configuration { #path-operation-advanced-configuration }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/path-operation-advanced-configuration.md#L1-L2", "start_line": 1, "end_line": 2}
{"id": "docs/en/docs/advanced/path-operation-advanced-configuration.md::OpenAPI operationId { #openapi-operationid }::L3", "text": "# Doc: docs/en/docs/advanced/path-operation-advanced-configuration.md | Page: Path Operation Advanced Configuration { #path-operation-advanced-configuration } | Section: OpenAPI operationId { #openapi-operationid }\n## OpenAPI operationId { #openapi-operationid }\n\n/// warning\n\nIf you are not an \"expert\" in OpenAPI, you probably don't need this.\n\n///\n\nYou can set the OpenAPI `operationId` to be used in your *path operation* with the parameter `operation_id`.\n\nYou would have to make sure that it is unique for each operation.\n\n{* ../../docs_src/path_operation_advanced_configuration/tutorial001_py310.py hl[6] *}\n\n### Using the *path operation function* name as the operationId { #using-the-path-operation-function-name-as-the-operationid }\n\nIf you want to use your APIs' function names as `operationId`s, you can pass a custom `generate_unique_id_function` to `FastAPI`.\n\nThe function receives each `APIRoute` and returns the `operationId` to use for that path operation.\n\n{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py310.py hl[2,5:6,9] *}\n\n/// warning\n\nIf you do this, you have to make sure each one of your *path operation functions* has a unique name.\n\nEven if they are in different modules (Python files).\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/path-operation-advanced-configuration.md", "symbol": "OpenAPI operationId { #openapi-operationid }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/path-operation-advanced-configuration.md#L3-L32", "start_line": 3, "end_line": 32}
{"id": "docs/en/docs/advanced/path-operation-advanced-configuration.md::Exclude from OpenAPI { #exclude-from-openapi }::L33", "text": "# Doc: docs/en/docs/advanced/path-operation-advanced-configuration.md | Page: Path Operation Advanced Configuration { #path-operation-advanced-configuration } | Section: Exclude from OpenAPI { #exclude-from-openapi }\n## Exclude from OpenAPI { #exclude-from-openapi }\n\nTo exclude a *path operation* from the generated OpenAPI schema (and thus, from the automatic documentation systems), use the parameter `include_in_schema` and set it to `False`:\n\n{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py310.py hl[6] *}", "source_type": "doc", "path": "docs/en/docs/advanced/path-operation-advanced-configuration.md", "symbol": "Exclude from OpenAPI { #exclude-from-openapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/path-operation-advanced-configuration.md#L33-L38", "start_line": 33, "end_line": 38}
{"id": "docs/en/docs/advanced/path-operation-advanced-configuration.md::Advanced description from docstring { #advanced-description-from-docstring }::L39", "text": "# Doc: docs/en/docs/advanced/path-operation-advanced-configuration.md | Page: Path Operation Advanced Configuration { #path-operation-advanced-configuration } | Section: Advanced description from docstring { #advanced-description-from-docstring }\n## Advanced description from docstring { #advanced-description-from-docstring }\n\nYou can limit the lines used from the docstring of a *path operation function* for OpenAPI.\n\nAdding an `\\f` (an escaped \"form feed\" character) causes **FastAPI** to truncate the output used for OpenAPI at this point.\n\nIt won't show up in the documentation, but other tools (such as Sphinx) will be able to use the rest.\n\n{* ../../docs_src/path_operation_advanced_configuration/tutorial004_py310.py hl[17:27] *}", "source_type": "doc", "path": "docs/en/docs/advanced/path-operation-advanced-configuration.md", "symbol": "Advanced description from docstring { #advanced-description-from-docstring }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/path-operation-advanced-configuration.md#L39-L48", "start_line": 39, "end_line": 48}
{"id": "docs/en/docs/advanced/path-operation-advanced-configuration.md::Additional Responses { #additional-responses }::L49", "text": "# Doc: docs/en/docs/advanced/path-operation-advanced-configuration.md | Page: Path Operation Advanced Configuration { #path-operation-advanced-configuration } | Section: Additional Responses { #additional-responses }\n## Additional Responses { #additional-responses }\n\nYou probably have seen how to declare the `response_model` and `status_code` for a *path operation*.\n\nThat defines the metadata about the main response of a *path operation*.\n\nYou can also declare additional responses with their models, status codes, etc.\n\nThere's a whole chapter here in the documentation about it, you can read it at [Additional Responses in OpenAPI](additional-responses.md).", "source_type": "doc", "path": "docs/en/docs/advanced/path-operation-advanced-configuration.md", "symbol": "Additional Responses { #additional-responses }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/path-operation-advanced-configuration.md#L49-L58", "start_line": 49, "end_line": 58}
{"id": "docs/en/docs/advanced/path-operation-advanced-configuration.md::OpenAPI Extra { #openapi-extra }::L59", "text": "# Doc: docs/en/docs/advanced/path-operation-advanced-configuration.md | Page: Path Operation Advanced Configuration { #path-operation-advanced-configuration } | Section: OpenAPI Extra { #openapi-extra }\n## OpenAPI Extra { #openapi-extra }\n\nWhen you declare a *path operation* in your application, **FastAPI** automatically generates the relevant metadata about that *path operation* to be included in the OpenAPI schema.\n\n/// note | Technical details\n\nIn the OpenAPI specification it is called the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object).\n\n///\n\nIt has all the information about the *path operation* and is used to generate the automatic documentation.\n\nIt includes the `tags`, `parameters`, `requestBody`, `responses`, etc.\n\nThis *path operation*-specific OpenAPI schema is normally generated automatically by **FastAPI**, but you can also extend it.\n\n/// tip\n\nThis is a low level extension point.\n\nIf you only need to declare additional responses, a more convenient way to do it is with [Additional Responses in OpenAPI](additional-responses.md).\n\n///\n\nYou can extend the OpenAPI schema for a *path operation* using the parameter `openapi_extra`.\n\n### OpenAPI Extensions { #openapi-extensions }\n\nThis `openapi_extra` can be helpful, for example, to declare [OpenAPI Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions):\n\n{* ../../docs_src/path_operation_advanced_configuration/tutorial005_py310.py hl[6] *}\n\nIf you open the automatic API docs, your extension will show up at the bottom of the specific *path operation*.\n\n![](\"/img/tutorial/path-operation-advanced-configuration/image01.png\")
\n\nAnd if you see the resulting OpenAPI (at `/openapi.json` in your API), you will see your extension as part of the specific *path operation* too:\n\n```JSON hl_lines=\"22\"\n{\n \"openapi\": \"3.1.0\",\n \"info\": {\n \"title\": \"FastAPI\",\n \"version\": \"0.1.0\"\n },\n \"paths\": {\n \"/items/\": {\n \"get\": {\n \"summary\": \"Read Items\",\n \"operationId\": \"read_items_items__get\",\n \"responses\": {\n \"200\": {\n \"description\": \"Successful Response\",\n \"content\": {\n \"application/json\": {\n \"schema\": {}\n }\n }\n }\n },\n \"x-aperture-labs-portal\": \"blue\"\n }\n }\n }\n}\n```\n\n### Custom OpenAPI *path operation* schema { #custom-openapi-path-operation-schema }\n\nThe dictionary in `openapi_extra` will be deeply merged with the automatically generated OpenAPI schema for the *path operation*.\n\nSo, you could add additional data to the automatically generated schema.\n\nFor example, you could decide to read and validate the request with your own code, without using the automatic features of FastAPI with Pydantic, but you could still want to define the request in the OpenAPI schema.\n\nYou could do that with `openapi_extra`:\n\n{* ../../docs_src/path_operation_advanced_configuration/tutorial006_py310.py hl[19:36, 39:40] *}\n\nIn this example, we didn't declare any Pydantic model. In fact, the request body is not even parsed as JSON, it is read directly as `bytes`, and the function `magic_data_reader()` would be in charge of parsing it in some way.\n\nNevertheless, we can declare the expected schema for the request body.\n\n### Custom OpenAPI content type { #custom-openapi-content-type }\n\nUsing this same trick, you could use a Pydantic model to define the JSON Schema that is then included in the custom OpenAPI schema section for the *path operation*.\n\nAnd you could do this even if the data type in the request is not JSON.\n\nFor example, in this application we don't use FastAPI's integrated functionality to extract the JSON Schema from Pydantic models nor the automatic validation for JSON. In fact, we are declaring the request content type as YAML, not JSON:\n\n{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py310.py hl[15:20, 22] *}\n\nNevertheless, although we are not using the default integrated functionality, we are still using a Pydantic model to manually generate the JSON Schema for the data that we want to receive in YAML.\n\nThen we use the request directly, and extract the body as `bytes`. This means that FastAPI won't even try to parse the request payload as JSON.\n\nAnd then in our code, we parse that YAML content directly, and then we are again using the same Pydantic model to validate the YAML content:\n\n{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py310.py hl[24:31] *}\n\n/// tip\n\nHere we reuse the same Pydantic model.\n\nBut the same way, we could have validated it in some other way.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/path-operation-advanced-configuration.md", "symbol": "OpenAPI Extra { #openapi-extra }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/path-operation-advanced-configuration.md#L59-L166", "start_line": 59, "end_line": 166}
{"id": "docs/en/docs/advanced/response-change-status-code.md::Response - Change Status Code { #response-change-status-code }::L1", "text": "# Doc: docs/en/docs/advanced/response-change-status-code.md | Page: Response - Change Status Code { #response-change-status-code } | Section: Response - Change Status Code { #response-change-status-code }\n# Response - Change Status Code { #response-change-status-code }\n\nYou probably read before that you can set a default [Response Status Code](../tutorial/response-status-code.md).\n\nBut in some cases you need to return a different status code than the default.", "source_type": "doc", "path": "docs/en/docs/advanced/response-change-status-code.md", "symbol": "Response - Change Status Code { #response-change-status-code }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/response-change-status-code.md#L1-L6", "start_line": 1, "end_line": 6}
{"id": "docs/en/docs/advanced/response-change-status-code.md::Use case { #use-case }::L7", "text": "# Doc: docs/en/docs/advanced/response-change-status-code.md | Page: Response - Change Status Code { #response-change-status-code } | Section: Use case { #use-case }\n## Use case { #use-case }\n\nFor example, imagine that you want to return an HTTP status code of \"OK\" `200` by default.\n\nBut if the data didn't exist, you want to create it, and return an HTTP status code of \"CREATED\" `201`.\n\nBut you still want to be able to filter and convert the data you return with a `response_model`.\n\nFor those cases, you can use a `Response` parameter.", "source_type": "doc", "path": "docs/en/docs/advanced/response-change-status-code.md", "symbol": "Use case { #use-case }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/response-change-status-code.md#L7-L16", "start_line": 7, "end_line": 16}
{"id": "docs/en/docs/advanced/response-change-status-code.md::Use a `Response` parameter { #use-a-response-parameter }::L17", "text": "# Doc: docs/en/docs/advanced/response-change-status-code.md | Page: Response - Change Status Code { #response-change-status-code } | Section: Use a `Response` parameter { #use-a-response-parameter }\n## Use a `Response` parameter { #use-a-response-parameter }\n\nYou can declare a parameter of type `Response` in your *path operation function* (as you can do for cookies and headers).\n\nAnd then you can set the `status_code` in that *temporary* response object.\n\n{* ../../docs_src/response_change_status_code/tutorial001_py310.py hl[1,9,12] *}\n\nAnd then you can return any object you need, as you normally would (a `dict`, a database model, etc).\n\nAnd if you declared a `response_model`, it will still be used to filter and convert the object you returned.\n\n**FastAPI** will use that *temporary* response to extract the status code (also cookies and headers), and will put them in the final response that contains the value you returned, filtered by any `response_model`.\n\nYou can also declare the `Response` parameter in dependencies, and set the status code in them. But keep in mind that the last one to be set will win.", "source_type": "doc", "path": "docs/en/docs/advanced/response-change-status-code.md", "symbol": "Use a `Response` parameter { #use-a-response-parameter }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/response-change-status-code.md#L17-L31", "start_line": 17, "end_line": 31}
{"id": "docs/en/docs/advanced/response-cookies.md::Use a `Response` parameter { #use-a-response-parameter }::L3", "text": "# Doc: docs/en/docs/advanced/response-cookies.md | Page: Response Cookies { #response-cookies } | Section: Use a `Response` parameter { #use-a-response-parameter }\n## Use a `Response` parameter { #use-a-response-parameter }\n\nYou can declare a parameter of type `Response` in your *path operation function*.\n\nAnd then you can set cookies in that *temporary* response object.\n\n{* ../../docs_src/response_cookies/tutorial002_py310.py hl[1, 8:9] *}\n\nAnd then you can return any object you need, as you normally would (a `dict`, a database model, etc).\n\nAnd if you declared a `response_model`, it will still be used to filter and convert the object you returned.\n\n**FastAPI** will use that *temporary* response to extract the cookies (also headers and status code), and will put them in the final response that contains the value you returned, filtered by any `response_model`.\n\nYou can also declare the `Response` parameter in dependencies, and set cookies (and headers) in them.", "source_type": "doc", "path": "docs/en/docs/advanced/response-cookies.md", "symbol": "Use a `Response` parameter { #use-a-response-parameter }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/response-cookies.md#L3-L18", "start_line": 3, "end_line": 18}
{"id": "docs/en/docs/advanced/response-cookies.md::Return a `Response` directly { #return-a-response-directly }::L19", "text": "# Doc: docs/en/docs/advanced/response-cookies.md | Page: Response Cookies { #response-cookies } | Section: Return a `Response` directly { #return-a-response-directly }\n## Return a `Response` directly { #return-a-response-directly }\n\nYou can also create cookies when returning a `Response` directly in your code.\n\nTo do that, you can create a response as described in [Return a Response Directly](response-directly.md).\n\nThen set Cookies in it, and then return it:\n\n{* ../../docs_src/response_cookies/tutorial001_py310.py hl[10:12] *}\n\n/// tip\n\nKeep in mind that if you return a response directly instead of using the `Response` parameter, FastAPI will return it directly.\n\nSo, you will have to make sure your data is of the correct type. E.g. it is compatible with JSON, if you are returning a `JSONResponse`.\n\nAnd also that you are not sending any data that should have been filtered by a `response_model`.\n\n///\n\n### More info { #more-info }\n\n/// note | Technical Details\n\nYou could also use `from starlette.responses import Response` or `from starlette.responses import JSONResponse`.\n\n**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.\n\nAnd as the `Response` can be used frequently to set headers and cookies, **FastAPI** also provides it at `fastapi.Response`.\n\n///\n\nTo see all the available parameters and options, check the [documentation in Starlette](https://www.starlette.dev/responses/#set-cookie).", "source_type": "doc", "path": "docs/en/docs/advanced/response-cookies.md", "symbol": "Return a `Response` directly { #return-a-response-directly }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/response-cookies.md#L19-L51", "start_line": 19, "end_line": 51}
{"id": "docs/en/docs/advanced/response-directly.md::Return a Response Directly { #return-a-response-directly }::L1", "text": "# Doc: docs/en/docs/advanced/response-directly.md | Page: Return a Response Directly { #return-a-response-directly } | Section: Return a Response Directly { #return-a-response-directly }\n# Return a Response Directly { #return-a-response-directly }\n\nWhen you create a **FastAPI** *path operation* you can normally return any data from it: a `dict`, a `list`, a Pydantic model, a database model, etc.\n\nIf you declare a [Response Model](../tutorial/response-model.md) FastAPI will use it to serialize the data to JSON, using Pydantic.\n\nIf you don't declare a response model, FastAPI will use the `jsonable_encoder` explained in [JSON Compatible Encoder](../tutorial/encoder.md) and put it in a `JSONResponse`.\n\nYou could also create a `JSONResponse` directly and return it.\n\n/// tip\n\nYou will normally have much better performance using a [Response Model](../tutorial/response-model.md) than returning a `JSONResponse` directly, as that way it serializes the data using Pydantic, in Rust.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/response-directly.md", "symbol": "Return a Response Directly { #return-a-response-directly }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/response-directly.md#L1-L16", "start_line": 1, "end_line": 16}
{"id": "docs/en/docs/advanced/response-directly.md::Return a `Response` { #return-a-response }::L17", "text": "# Doc: docs/en/docs/advanced/response-directly.md | Page: Return a Response Directly { #return-a-response-directly } | Section: Return a `Response` { #return-a-response }\n## Return a `Response` { #return-a-response }\n\nYou can return a `Response` or any sub-class of it.\n\n/// note\n\n`JSONResponse` itself is a sub-class of `Response`.\n\n///\n\nAnd when you return a `Response`, **FastAPI** will pass it directly.\n\nIt won't do any data conversion with Pydantic models, it won't convert the contents to any type, etc.\n\nThis gives you a lot of **flexibility**. You can return any data type, override any data declaration or validation, etc.\n\nIt also gives you a lot of **responsibility**. You have to make sure that the data you return is correct, in the correct format, that it can be serialized, etc.", "source_type": "doc", "path": "docs/en/docs/advanced/response-directly.md", "symbol": "Return a `Response` { #return-a-response }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/response-directly.md#L17-L34", "start_line": 17, "end_line": 34}
{"id": "docs/en/docs/advanced/response-directly.md::Using the `jsonable_encoder` in a `Response` { #using-the-jsonable-encoder-in-a-response }::L35", "text": "# Doc: docs/en/docs/advanced/response-directly.md | Page: Return a Response Directly { #return-a-response-directly } | Section: Using the `jsonable_encoder` in a `Response` { #using-the-jsonable-encoder-in-a-response }\n## Using the `jsonable_encoder` in a `Response` { #using-the-jsonable-encoder-in-a-response }\n\nBecause **FastAPI** doesn't make any changes to a `Response` you return, you have to make sure its contents are ready for it.\n\nFor example, you cannot put a Pydantic model in a `JSONResponse` without first converting it to a `dict` with all the data types (like `datetime`, `UUID`, etc) converted to JSON-compatible types.\n\nFor those cases, you can use the `jsonable_encoder` to convert your data before passing it to a response:\n\n{* ../../docs_src/response_directly/tutorial001_py310.py hl[5:6,20:21] *}\n\n/// note | Technical Details\n\nYou could also use `from starlette.responses import JSONResponse`.\n\n**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/response-directly.md", "symbol": "Using the `jsonable_encoder` in a `Response` { #using-the-jsonable-encoder-in-a-response }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/response-directly.md#L35-L52", "start_line": 35, "end_line": 52}
{"id": "docs/en/docs/advanced/response-directly.md::Returning a custom `Response` { #returning-a-custom-response }::L53", "text": "# Doc: docs/en/docs/advanced/response-directly.md | Page: Return a Response Directly { #return-a-response-directly } | Section: Returning a custom `Response` { #returning-a-custom-response }\n## Returning a custom `Response` { #returning-a-custom-response }\n\nThe example above shows all the parts you need, but it's not very useful yet, as you could have just returned the `item` directly, and **FastAPI** would put it in a `JSONResponse` for you, converting it to a `dict`, etc. All that by default.\n\nNow, let's see how you could use that to return a custom response.\n\nLet's say that you want to return an [XML](https://en.wikipedia.org/wiki/XML) response.\n\nYou could put your XML content in a string, put that in a `Response`, and return it:\n\n{* ../../docs_src/response_directly/tutorial002_py310.py hl[1,18] *}", "source_type": "doc", "path": "docs/en/docs/advanced/response-directly.md", "symbol": "Returning a custom `Response` { #returning-a-custom-response }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/response-directly.md#L53-L64", "start_line": 53, "end_line": 64}
{"id": "docs/en/docs/advanced/response-directly.md::How a Response Model Works { #how-a-response-model-works }::L65", "text": "# Doc: docs/en/docs/advanced/response-directly.md | Page: Return a Response Directly { #return-a-response-directly } | Section: How a Response Model Works { #how-a-response-model-works }\n## How a Response Model Works { #how-a-response-model-works }\n\nWhen you declare a [Response Model - Return Type](../tutorial/response-model.md) in a path operation, **FastAPI** will use it to serialize the data to JSON, using Pydantic.\n\n{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *}\n\nAs that will happen on the Rust side, the performance will be much better than if it was done with regular Python and the `JSONResponse` class.\n\nWhen using a `response_model` or return type, FastAPI won't use the `jsonable_encoder` to convert the data (which would be slower) nor the `JSONResponse` class.\n\nInstead it takes the JSON bytes generated with Pydantic using the response model (or return type) and returns a `Response` with the right media type for JSON directly (`application/json`).", "source_type": "doc", "path": "docs/en/docs/advanced/response-directly.md", "symbol": "How a Response Model Works { #how-a-response-model-works }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/response-directly.md#L65-L76", "start_line": 65, "end_line": 76}
{"id": "docs/en/docs/advanced/response-directly.md::Notes { #notes }::L77", "text": "# Doc: docs/en/docs/advanced/response-directly.md | Page: Return a Response Directly { #return-a-response-directly } | Section: Notes { #notes }\n## Notes { #notes }\n\nWhen you return a `Response` directly its data is not validated, converted (serialized), or documented automatically.\n\nBut you can still document it as described in [Additional Responses in OpenAPI](additional-responses.md).\n\nYou can see in later sections how to use/declare these custom `Response`s while still having automatic data conversion, documentation, etc.", "source_type": "doc", "path": "docs/en/docs/advanced/response-directly.md", "symbol": "Notes { #notes }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/response-directly.md#L77-L83", "start_line": 77, "end_line": 83}
{"id": "docs/en/docs/advanced/response-headers.md::Use a `Response` parameter { #use-a-response-parameter }::L3", "text": "# Doc: docs/en/docs/advanced/response-headers.md | Page: Response Headers { #response-headers } | Section: Use a `Response` parameter { #use-a-response-parameter }\n## Use a `Response` parameter { #use-a-response-parameter }\n\nYou can declare a parameter of type `Response` in your *path operation function* (as you can do for cookies).\n\nAnd then you can set headers in that *temporary* response object.\n\n{* ../../docs_src/response_headers/tutorial002_py310.py hl[1, 7:8] *}\n\nAnd then you can return any object you need, as you normally would (a `dict`, a database model, etc).\n\nAnd if you declared a `response_model`, it will still be used to filter and convert the object you returned.\n\n**FastAPI** will use that *temporary* response to extract the headers (also cookies and status code), and will put them in the final response that contains the value you returned, filtered by any `response_model`.\n\nYou can also declare the `Response` parameter in dependencies, and set headers (and cookies) in them.", "source_type": "doc", "path": "docs/en/docs/advanced/response-headers.md", "symbol": "Use a `Response` parameter { #use-a-response-parameter }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/response-headers.md#L3-L18", "start_line": 3, "end_line": 18}
{"id": "docs/en/docs/advanced/response-headers.md::Return a `Response` directly { #return-a-response-directly }::L19", "text": "# Doc: docs/en/docs/advanced/response-headers.md | Page: Response Headers { #response-headers } | Section: Return a `Response` directly { #return-a-response-directly }\n## Return a `Response` directly { #return-a-response-directly }\n\nYou can also add headers when you return a `Response` directly.\n\nCreate a response as described in [Return a Response Directly](response-directly.md) and pass the headers as an additional parameter:\n\n{* ../../docs_src/response_headers/tutorial001_py310.py hl[10:12] *}\n\n/// note | Technical Details\n\nYou could also use `from starlette.responses import Response` or `from starlette.responses import JSONResponse`.\n\n**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.\n\nAnd as the `Response` can be used frequently to set headers and cookies, **FastAPI** also provides it at `fastapi.Response`.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/response-headers.md", "symbol": "Return a `Response` directly { #return-a-response-directly }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/response-headers.md#L19-L36", "start_line": 19, "end_line": 36}
{"id": "docs/en/docs/advanced/response-headers.md::Custom Headers { #custom-headers }::L37", "text": "# Doc: docs/en/docs/advanced/response-headers.md | Page: Response Headers { #response-headers } | Section: Custom Headers { #custom-headers }\n## Custom Headers { #custom-headers }\n\nKeep in mind that custom proprietary headers can be added [using the `X-` prefix](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).\n\nBut if you have custom headers that you want a client in a browser to be able to see, you need to add them to your CORS configurations (read more in [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)), using the parameter `expose_headers` documented in [Starlette's CORS docs](https://www.starlette.dev/middleware/#corsmiddleware).", "source_type": "doc", "path": "docs/en/docs/advanced/response-headers.md", "symbol": "Custom Headers { #custom-headers }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/response-headers.md#L37-L41", "start_line": 37, "end_line": 41}
{"id": "docs/en/docs/advanced/security/http-basic-auth.md::HTTP Basic Auth { #http-basic-auth }::L1", "text": "# Doc: docs/en/docs/advanced/security/http-basic-auth.md | Page: HTTP Basic Auth { #http-basic-auth } | Section: HTTP Basic Auth { #http-basic-auth }\n# HTTP Basic Auth { #http-basic-auth }\n\nFor the simplest cases, you can use HTTP Basic Auth.\n\nIn HTTP Basic Auth, the application expects a header that contains a username and a password.\n\nIf it doesn't receive it, it returns an HTTP 401 \"Unauthorized\" error.\n\nAnd returns a header `WWW-Authenticate` with a value of `Basic`, and an optional `realm` parameter.\n\nThat tells the browser to show the integrated prompt for a username and password.\n\nThen, when you type that username and password, the browser sends them in the header automatically.", "source_type": "doc", "path": "docs/en/docs/advanced/security/http-basic-auth.md", "symbol": "HTTP Basic Auth { #http-basic-auth }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/http-basic-auth.md#L1-L14", "start_line": 1, "end_line": 14}
{"id": "docs/en/docs/advanced/security/http-basic-auth.md::Simple HTTP Basic Auth { #simple-http-basic-auth }::L15", "text": "# Doc: docs/en/docs/advanced/security/http-basic-auth.md | Page: HTTP Basic Auth { #http-basic-auth } | Section: Simple HTTP Basic Auth { #simple-http-basic-auth }\n## Simple HTTP Basic Auth { #simple-http-basic-auth }\n\n* Import `HTTPBasic` and `HTTPBasicCredentials`.\n* Create a \"`security` scheme\" using `HTTPBasic`.\n* Use that `security` with a dependency in your *path operation*.\n* It returns an object of type `HTTPBasicCredentials`:\n * It contains the `username` and `password` sent.\n\n{* ../../docs_src/security/tutorial006_an_py310.py hl[4,8,12] *}\n\nWhen you try to open the URL for the first time (or click the \"Execute\" button in the docs) the browser will ask you for your username and password:\n\n![](\"/img/tutorial/security/image12.png\")
", "source_type": "doc", "path": "docs/en/docs/advanced/security/http-basic-auth.md", "symbol": "Simple HTTP Basic Auth { #simple-http-basic-auth }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/http-basic-auth.md#L15-L28", "start_line": 15, "end_line": 28}
{"id": "docs/en/docs/advanced/security/http-basic-auth.md::Check the username { #check-the-username }::L29", "text": "# Doc: docs/en/docs/advanced/security/http-basic-auth.md | Page: HTTP Basic Auth { #http-basic-auth } | Section: Check the username { #check-the-username }\n## Check the username { #check-the-username }\n\nHere's a more complete example.\n\nUse a dependency to check if the username and password are correct.\n\nFor this, use the Python standard module [`secrets`](https://docs.python.org/3/library/secrets.html) to check the username and password.\n\n`secrets.compare_digest()` needs to take `bytes` or a `str` that only contains ASCII characters (the ones in English), this means it wouldn't work with characters like `á`, as in `Sebastián`.\n\nTo handle that, we first convert the `username` and `password` to `bytes` encoding them with UTF-8.\n\nThen we can use `secrets.compare_digest()` to ensure that `credentials.username` is `\"stanleyjobson\"`, and that `credentials.password` is `\"swordfish\"`.\n\n{* ../../docs_src/security/tutorial007_an_py310.py hl[1,12:24] *}\n\nThis would be similar to:\n\n```Python\nif not (credentials.username == \"stanleyjobson\") or not (credentials.password == \"swordfish\"):\n # Return some error\n ...\n```\n\nBut by using the `secrets.compare_digest()` it will be secure against a type of attacks called \"timing attacks\".\n\n### Timing Attacks { #timing-attacks }\n\nBut what's a \"timing attack\"?\n\nLet's imagine some attackers are trying to guess the username and password.\n\nAnd they send a request with a username `johndoe` and a password `love123`.\n\nThen the Python code in your application would be equivalent to something like:\n\n```Python\nif \"johndoe\" == \"stanleyjobson\" and \"love123\" == \"swordfish\":\n ...\n```\n\nBut right at the moment Python compares the first `j` in `johndoe` to the first `s` in `stanleyjobson`, it will return `False`, because it already knows that those two strings are not the same, thinking that \"there's no need to waste more computation comparing the rest of the letters\". And your application will say \"Incorrect username or password\".\n\nBut then the attackers try with username `stanleyjobsox` and password `love123`.\n\nAnd your application code does something like:\n\n```Python\nif \"stanleyjobsox\" == \"stanleyjobson\" and \"love123\" == \"swordfish\":\n ...\n```\n\nPython will have to compare the whole `stanleyjobso` in both `stanleyjobsox` and `stanleyjobson` before realizing that both strings are not the same. So it will take some extra microseconds to reply back \"Incorrect username or password\".\n\n#### The time to answer helps the attackers { #the-time-to-answer-helps-the-attackers }\n\nAt that point, by noticing that the server took some microseconds longer to send the \"Incorrect username or password\" response, the attackers will know that they got _something_ right, some of the initial letters were right.\n\nAnd then they can try again knowing that it's probably something more similar to `stanleyjobsox` than to `johndoe`.\n\n#### A \"professional\" attack { #a-professional-attack }\n\nOf course, the attackers would not try all this by hand, they would write a program to do it, possibly with thousands or millions of tests per second. And they would get just one extra correct letter at a time.\n\nBut doing that, in some minutes or hours the attackers would have guessed the correct username and password, with the \"help\" of our application, just using the time taken to answer.\n\n#### Fix it with `secrets.compare_digest()` { #fix-it-with-secrets-compare-digest }\n\nBut in our code we are actually using `secrets.compare_digest()`.\n\nIn short, it will take the same time to compare `stanleyjobsox` to `stanleyjobson` than it takes to compare `johndoe` to `stanleyjobson`. And the same for the password.\n\nThat way, using `secrets.compare_digest()` in your application code, it will be safe against this whole range of security attacks.\n\n### Return the error { #return-the-error }\n\nAfter detecting that the credentials are incorrect, return an `HTTPException` with a status code 401 (the same returned when no credentials are provided) and add the header `WWW-Authenticate` to make the browser show the login prompt again:\n\n{* ../../docs_src/security/tutorial007_an_py310.py hl[26:30] *}", "source_type": "doc", "path": "docs/en/docs/advanced/security/http-basic-auth.md", "symbol": "Check the username { #check-the-username }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/http-basic-auth.md#L29-L107", "start_line": 29, "end_line": 107}
{"id": "docs/en/docs/advanced/security/index.md::Additional Features { #additional-features }::L3", "text": "# Doc: docs/en/docs/advanced/security/index.md | Page: Advanced Security { #advanced-security } | Section: Additional Features { #additional-features }\n## Additional Features { #additional-features }\n\nThere are some extra features to handle security apart from the ones covered in the [Tutorial - User Guide: Security](../../tutorial/security/index.md).\n\n/// tip\n\nThe next sections are **not necessarily \"advanced\"**.\n\nAnd it's possible that for your use case, the solution is in one of them.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/security/index.md", "symbol": "Additional Features { #additional-features }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/index.md#L3-L14", "start_line": 3, "end_line": 14}
{"id": "docs/en/docs/advanced/security/index.md::Read the Tutorial first { #read-the-tutorial-first }::L15", "text": "# Doc: docs/en/docs/advanced/security/index.md | Page: Advanced Security { #advanced-security } | Section: Read the Tutorial first { #read-the-tutorial-first }\n## Read the Tutorial first { #read-the-tutorial-first }\n\nThe next sections assume you already read the main [Tutorial - User Guide: Security](../../tutorial/security/index.md).\n\nThey are all based on the same concepts, but allow some extra functionalities.", "source_type": "doc", "path": "docs/en/docs/advanced/security/index.md", "symbol": "Read the Tutorial first { #read-the-tutorial-first }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/index.md#L15-L19", "start_line": 15, "end_line": 19}
{"id": "docs/en/docs/advanced/security/oauth2-scopes.md::OAuth2 scopes { #oauth2-scopes }::L1", "text": "# Doc: docs/en/docs/advanced/security/oauth2-scopes.md | Page: OAuth2 scopes { #oauth2-scopes } | Section: OAuth2 scopes { #oauth2-scopes }\n# OAuth2 scopes { #oauth2-scopes }\n\nYou can use OAuth2 scopes directly with **FastAPI**, they are integrated to work seamlessly.\n\nThis would allow you to have a more fine-grained permission system, following the OAuth2 standard, integrated into your OpenAPI application (and the API docs).\n\nOAuth2 with scopes is the mechanism used by many big authentication providers, like Facebook, Google, GitHub, Microsoft, X (Twitter), etc. They use it to provide specific permissions to users and applications.\n\nEvery time you \"log in with\" Facebook, Google, GitHub, Microsoft, X (Twitter), that application is using OAuth2 with scopes.\n\nIn this section you will see how to manage authentication and authorization with the same OAuth2 with scopes in your **FastAPI** application.\n\n/// warning\n\nThis is a more or less advanced section. If you are just starting, you can skip it.\n\nYou don't necessarily need OAuth2 scopes, and you can handle authentication and authorization however you want.\n\nBut OAuth2 with scopes can be nicely integrated into your API (with OpenAPI) and your API docs.\n\nNevertheless, you still enforce those scopes, or any other security/authorization requirement, however you need, in your code.\n\nIn many cases, OAuth2 with scopes can be an overkill.\n\nBut if you know you need it, or you are curious, keep reading.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/security/oauth2-scopes.md", "symbol": "OAuth2 scopes { #oauth2-scopes }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/oauth2-scopes.md#L1-L28", "start_line": 1, "end_line": 28}
{"id": "docs/en/docs/advanced/security/oauth2-scopes.md::OAuth2 scopes and OpenAPI { #oauth2-scopes-and-openapi }::L29", "text": "# Doc: docs/en/docs/advanced/security/oauth2-scopes.md | Page: OAuth2 scopes { #oauth2-scopes } | Section: OAuth2 scopes and OpenAPI { #oauth2-scopes-and-openapi }\n## OAuth2 scopes and OpenAPI { #oauth2-scopes-and-openapi }\n\nThe OAuth2 specification defines \"scopes\" as a list of strings separated by spaces.\n\nThe content of each of these strings can have any format, but should not contain spaces.\n\nThese scopes represent \"permissions\".\n\nIn OpenAPI (e.g. the API docs), you can define \"security schemes\".\n\nWhen one of these security schemes uses OAuth2, you can also declare and use scopes.\n\nEach \"scope\" is just a string (without spaces).\n\nThey are normally used to declare specific security permissions, for example:\n\n* `users:read` or `users:write` are common examples.\n* `instagram_basic` is used by Facebook / Instagram.\n* `https://www.googleapis.com/auth/drive` is used by Google.\n\n/// note\n\nIn OAuth2 a \"scope\" is just a string that declares a specific permission required.\n\nIt doesn't matter if it has other characters like `:` or if it is a URL.\n\nThose details are implementation specific.\n\nFor OAuth2 they are just strings.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/security/oauth2-scopes.md", "symbol": "OAuth2 scopes and OpenAPI { #oauth2-scopes-and-openapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/oauth2-scopes.md#L29-L60", "start_line": 29, "end_line": 60}
{"id": "docs/en/docs/advanced/security/oauth2-scopes.md::Global view { #global-view }::L61", "text": "# Doc: docs/en/docs/advanced/security/oauth2-scopes.md | Page: OAuth2 scopes { #oauth2-scopes } | Section: Global view { #global-view }\n## Global view { #global-view }\n\nFirst, let's quickly see the parts that change from the examples in the main **Tutorial - User Guide** for [OAuth2 with Password (and hashing), Bearer with JWT tokens](../../tutorial/security/oauth2-jwt.md). Now using OAuth2 scopes:\n\n{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:126,130:136,141,157] *}\n\nNow let's review those changes step by step.", "source_type": "doc", "path": "docs/en/docs/advanced/security/oauth2-scopes.md", "symbol": "Global view { #global-view }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/oauth2-scopes.md#L61-L68", "start_line": 61, "end_line": 68}
{"id": "docs/en/docs/advanced/security/oauth2-scopes.md::OAuth2 Security scheme { #oauth2-security-scheme }::L69", "text": "# Doc: docs/en/docs/advanced/security/oauth2-scopes.md | Page: OAuth2 scopes { #oauth2-scopes } | Section: OAuth2 Security scheme { #oauth2-security-scheme }\n## OAuth2 Security scheme { #oauth2-security-scheme }\n\nThe first change is that now we are declaring the OAuth2 security scheme with two available scopes, `me` and `items`.\n\nThe `scopes` parameter receives a `dict` with each scope as a key and the description as the value:\n\n{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *}\n\nBecause we are now declaring those scopes, they will show up in the API docs when you log-in/authorize.\n\nAnd you will be able to select which scopes you want to give access to: `me` and `items`.\n\nThis is the same mechanism used when you give permissions while logging in with Facebook, Google, GitHub, etc:\n\n![](\"/img/tutorial/security/image11.png\")
", "source_type": "doc", "path": "docs/en/docs/advanced/security/oauth2-scopes.md", "symbol": "OAuth2 Security scheme { #oauth2-security-scheme }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/oauth2-scopes.md#L69-L84", "start_line": 69, "end_line": 84}
{"id": "docs/en/docs/advanced/security/oauth2-scopes.md::JWT token with scopes { #jwt-token-with-scopes }::L85", "text": "# Doc: docs/en/docs/advanced/security/oauth2-scopes.md | Page: OAuth2 scopes { #oauth2-scopes } | Section: JWT token with scopes { #jwt-token-with-scopes }\n## JWT token with scopes { #jwt-token-with-scopes }\n\nNow, modify the token *path operation* to return the scopes requested.\n\nWe are still using the same `OAuth2PasswordRequestForm`. It includes a property `scopes` with a `list` of `str`, with each scope it received in the request.\n\nAnd we return the scopes as part of the JWT token.\n\n/// danger\n\nFor simplicity, here we are just adding the scopes received directly to the token.\n\nBut in your application, for security, you should make sure you only add the scopes that the user is actually able to have, or the ones you have predefined.\n\n///\n\n{* ../../docs_src/security/tutorial005_an_py310.py hl[157] *}", "source_type": "doc", "path": "docs/en/docs/advanced/security/oauth2-scopes.md", "symbol": "JWT token with scopes { #jwt-token-with-scopes }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/oauth2-scopes.md#L85-L102", "start_line": 85, "end_line": 102}
{"id": "docs/en/docs/advanced/security/oauth2-scopes.md::Declare scopes in *path operations* and dependencies { #declare-scopes-in-path-operations-and-dependencies }::L103", "text": "# Doc: docs/en/docs/advanced/security/oauth2-scopes.md | Page: OAuth2 scopes { #oauth2-scopes } | Section: Declare scopes in *path operations* and dependencies { #declare-scopes-in-path-operations-and-dependencies }\n## Declare scopes in *path operations* and dependencies { #declare-scopes-in-path-operations-and-dependencies }\n\nNow we declare that the *path operation* for `/users/me/items/` requires the scope `items`.\n\nFor this, we import and use `Security` from `fastapi`.\n\nYou can use `Security` to declare dependencies (just like `Depends`), but `Security` also receives a parameter `scopes` with a list of scopes (strings).\n\nIn this case, we pass a dependency function `get_current_active_user` to `Security` (the same way we would do with `Depends`).\n\nBut we also pass a `list` of scopes, in this case with just one scope: `items` (it could have more).\n\nAnd the dependency function `get_current_active_user` can also declare sub-dependencies, not only with `Depends` but also with `Security`. Declaring its own sub-dependency function (`get_current_user`), and more scope requirements.\n\nIn this case, it requires the scope `me` (it could require more than one scope).\n\n/// note\n\nYou don't necessarily need to add different scopes in different places.\n\nWe are doing it here to demonstrate how **FastAPI** handles scopes declared at different levels.\n\n///\n\n{* ../../docs_src/security/tutorial005_an_py310.py hl[5,141,172] *}\n\n/// note | Technical Details\n\n`Security` is actually a subclass of `Depends`, and it has just one extra parameter that we'll see later.\n\nBut by using `Security` instead of `Depends`, **FastAPI** will know that it can declare security scopes, use them internally, and document the API with OpenAPI.\n\nBut when you import `Query`, `Path`, `Depends`, `Security` and others from `fastapi`, those are actually functions that return special classes.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/security/oauth2-scopes.md", "symbol": "Declare scopes in *path operations* and dependencies { #declare-scopes-in-path-operations-and-dependencies }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/oauth2-scopes.md#L103-L138", "start_line": 103, "end_line": 138}
{"id": "docs/en/docs/advanced/security/oauth2-scopes.md::Use `SecurityScopes` { #use-securityscopes }::L139", "text": "# Doc: docs/en/docs/advanced/security/oauth2-scopes.md | Page: OAuth2 scopes { #oauth2-scopes } | Section: Use `SecurityScopes` { #use-securityscopes }\n## Use `SecurityScopes` { #use-securityscopes }\n\nNow update the dependency `get_current_user`.\n\nThis is the one used by the dependencies above.\n\nHere's where we are using the same OAuth2 scheme we created before, declaring it as a dependency: `oauth2_scheme`.\n\nBecause this dependency function doesn't have any scope requirements itself, we can use `Depends` with `oauth2_scheme`, we don't have to use `Security` when we don't need to specify security scopes.\n\nWe also declare a special parameter of type `SecurityScopes`, imported from `fastapi.security`.\n\nThis `SecurityScopes` class is similar to `Request` (`Request` was used to get the request object directly).\n\n{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *}", "source_type": "doc", "path": "docs/en/docs/advanced/security/oauth2-scopes.md", "symbol": "Use `SecurityScopes` { #use-securityscopes }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/oauth2-scopes.md#L139-L154", "start_line": 139, "end_line": 154}
{"id": "docs/en/docs/advanced/security/oauth2-scopes.md::Use the `scopes` { #use-the-scopes }::L155", "text": "# Doc: docs/en/docs/advanced/security/oauth2-scopes.md | Page: OAuth2 scopes { #oauth2-scopes } | Section: Use the `scopes` { #use-the-scopes }\n## Use the `scopes` { #use-the-scopes }\n\nThe parameter `security_scopes` will be of type `SecurityScopes`.\n\nIt will have a property `scopes` with a list containing all the scopes required by itself and all the dependencies that use this as a sub-dependency. That means, all the \"dependants\"... this might sound confusing, it is explained again later below.\n\nThe `security_scopes` object (of class `SecurityScopes`) also provides a `scope_str` attribute with a single string, containing those scopes separated by spaces (we are going to use it).\n\nWe create an `HTTPException` that we can reuse (`raise`) later at several points.\n\nIn this exception, we include the scopes required (if any) as a string separated by spaces (using `scope_str`). We put that string containing the scopes in the `WWW-Authenticate` header (this is part of the spec).\n\n{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *}", "source_type": "doc", "path": "docs/en/docs/advanced/security/oauth2-scopes.md", "symbol": "Use the `scopes` { #use-the-scopes }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/oauth2-scopes.md#L155-L168", "start_line": 155, "end_line": 168}
{"id": "docs/en/docs/advanced/security/oauth2-scopes.md::Verify the `username` and data shape { #verify-the-username-and-data-shape }::L169", "text": "# Doc: docs/en/docs/advanced/security/oauth2-scopes.md | Page: OAuth2 scopes { #oauth2-scopes } | Section: Verify the `username` and data shape { #verify-the-username-and-data-shape }\n## Verify the `username` and data shape { #verify-the-username-and-data-shape }\n\nWe verify that we get a `username`, and extract the scopes.\n\nAnd then we validate that data with the Pydantic model (catching the `ValidationError` exception), and if we get an error reading the JWT token or validating the data with Pydantic, we raise the `HTTPException` we created before.\n\nFor that, we update the Pydantic model `TokenData` with a new property `scopes`.\n\nBy validating the data with Pydantic we can make sure that we have, for example, exactly a `list` of `str` with the scopes and a `str` with the `username`.\n\nInstead of, for example, a `dict`, or something else, as it could break the application at some point later, making it a security risk.\n\nWe also verify that we have a user with that username, and if not, we raise that same exception we created before.\n\n{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:129] *}", "source_type": "doc", "path": "docs/en/docs/advanced/security/oauth2-scopes.md", "symbol": "Verify the `username` and data shape { #verify-the-username-and-data-shape }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/oauth2-scopes.md#L169-L184", "start_line": 169, "end_line": 184}
{"id": "docs/en/docs/advanced/security/oauth2-scopes.md::Verify the `scopes` { #verify-the-scopes }::L185", "text": "# Doc: docs/en/docs/advanced/security/oauth2-scopes.md | Page: OAuth2 scopes { #oauth2-scopes } | Section: Verify the `scopes` { #verify-the-scopes }\n## Verify the `scopes` { #verify-the-scopes }\n\nWe now verify that all the scopes required, by this dependency and all the dependants (including *path operations*), are included in the scopes provided in the token received, otherwise raise an `HTTPException`.\n\nFor this, we use `security_scopes.scopes`, that contains a `list` with all these scopes as `str`.\n\n{* ../../docs_src/security/tutorial005_an_py310.py hl[130:136] *}", "source_type": "doc", "path": "docs/en/docs/advanced/security/oauth2-scopes.md", "symbol": "Verify the `scopes` { #verify-the-scopes }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/oauth2-scopes.md#L185-L192", "start_line": 185, "end_line": 192}
{"id": "docs/en/docs/advanced/security/oauth2-scopes.md::Dependency tree and scopes { #dependency-tree-and-scopes }::L193", "text": "# Doc: docs/en/docs/advanced/security/oauth2-scopes.md | Page: OAuth2 scopes { #oauth2-scopes } | Section: Dependency tree and scopes { #dependency-tree-and-scopes }\n## Dependency tree and scopes { #dependency-tree-and-scopes }\n\nLet's review again this dependency tree and the scopes.\n\nAs the `get_current_active_user` dependency has `get_current_user` as a sub-dependency, the scope `\"me\"` declared at `get_current_active_user` will be included in the list of required scopes in the `security_scopes.scopes` passed to `get_current_user`.\n\nThe *path operation* itself also declares a scope, `\"items\"`, so this will also be in the list of `security_scopes.scopes` passed to `get_current_user`.\n\nHere's what the hierarchy of dependencies and scopes looks like:\n\n* The *path operation* `read_own_items` has:\n * Required scopes `[\"items\"]` with the dependency:\n * `get_current_active_user`:\n * The dependency function `get_current_active_user` has:\n * Required scopes `[\"me\"]` with the dependency:\n * `get_current_user`:\n * The dependency function `get_current_user` has:\n * No scopes required by itself.\n * A dependency using `oauth2_scheme`.\n * A `security_scopes` parameter of type `SecurityScopes`:\n * This `security_scopes` parameter has a property `scopes` with a `list` containing all these scopes declared above, so:\n * `security_scopes.scopes` will contain `[\"me\", \"items\"]` for the *path operation* `read_own_items`.\n * `security_scopes.scopes` will contain `[\"me\"]` for the *path operation* `read_users_me`, because it is declared in the dependency `get_current_active_user`.\n * `security_scopes.scopes` will contain `[]` (nothing) for the *path operation* `read_system_status`, because it didn't declare any `Security` with `scopes`, and its dependency, `get_current_user`, doesn't declare any `scopes` either.\n\n/// tip\n\nThe important and \"magic\" thing here is that `get_current_user` will have a different list of `scopes` to check for each *path operation*.\n\nAll depending on the `scopes` declared in each *path operation* and each dependency in the dependency tree for that specific *path operation*.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/security/oauth2-scopes.md", "symbol": "Dependency tree and scopes { #dependency-tree-and-scopes }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/oauth2-scopes.md#L193-L225", "start_line": 193, "end_line": 225}
{"id": "docs/en/docs/advanced/security/oauth2-scopes.md::More details about `SecurityScopes` { #more-details-about-securityscopes }::L226", "text": "# Doc: docs/en/docs/advanced/security/oauth2-scopes.md | Page: OAuth2 scopes { #oauth2-scopes } | Section: More details about `SecurityScopes` { #more-details-about-securityscopes }\n## More details about `SecurityScopes` { #more-details-about-securityscopes }\n\nYou can use `SecurityScopes` at any point, and in multiple places, it doesn't have to be at the \"root\" dependency.\n\nIt will always have the security scopes declared in the current `Security` dependencies and all the dependants for **that specific** *path operation* and **that specific** dependency tree.\n\nBecause the `SecurityScopes` will have all the scopes declared by dependants, you can use it to verify that a token has the required scopes in a central dependency function, and then declare different scope requirements in different *path operations*.\n\nThey will be checked independently for each *path operation*.", "source_type": "doc", "path": "docs/en/docs/advanced/security/oauth2-scopes.md", "symbol": "More details about `SecurityScopes` { #more-details-about-securityscopes }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/oauth2-scopes.md#L226-L235", "start_line": 226, "end_line": 235}
{"id": "docs/en/docs/advanced/security/oauth2-scopes.md::Check it { #check-it }::L236", "text": "# Doc: docs/en/docs/advanced/security/oauth2-scopes.md | Page: OAuth2 scopes { #oauth2-scopes } | Section: Check it { #check-it }\n## Check it { #check-it }\n\nIf you open the API docs, you can authenticate and specify which scopes you want to authorize.\n\n\n\nIf you don't select any scope, you will be \"authenticated\", but when you try to access `/users/me/` or `/users/me/items/` you will get an error saying that you don't have enough permissions. You will still be able to access `/status/`.\n\nAnd if you select the scope `me` but not the scope `items`, you will be able to access `/users/me/` but not `/users/me/items/`.\n\nThat's what would happen to a third party application that tried to access one of these *path operations* with a token provided by a user, depending on how many permissions the user gave the application.", "source_type": "doc", "path": "docs/en/docs/advanced/security/oauth2-scopes.md", "symbol": "Check it { #check-it }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/oauth2-scopes.md#L236-L247", "start_line": 236, "end_line": 247}
{"id": "docs/en/docs/advanced/security/oauth2-scopes.md::About third party integrations { #about-third-party-integrations }::L248", "text": "# Doc: docs/en/docs/advanced/security/oauth2-scopes.md | Page: OAuth2 scopes { #oauth2-scopes } | Section: About third party integrations { #about-third-party-integrations }\n## About third party integrations { #about-third-party-integrations }\n\nIn this example we are using the OAuth2 \"password\" flow.\n\nThis is appropriate when we are logging in to our own application, probably with our own frontend.\n\nBecause we can trust it to receive the `username` and `password`, as we control it.\n\nBut if you are building an OAuth2 application that others would connect to (i.e., if you are building an authentication provider equivalent to Facebook, Google, GitHub, etc.) you should use one of the other flows.\n\nThe most common is the implicit flow.\n\nThe most secure is the code flow, but it's more complex to implement as it requires more steps. As it is more complex, many providers end up suggesting the implicit flow.\n\n/// note\n\nIt's common that each authentication provider names their flows in a different way, to make it part of their brand.\n\nBut in the end, they are implementing the same OAuth2 standard.\n\n///\n\n**FastAPI** includes utilities for all these OAuth2 authentication flows in `fastapi.security.oauth2`.", "source_type": "doc", "path": "docs/en/docs/advanced/security/oauth2-scopes.md", "symbol": "About third party integrations { #about-third-party-integrations }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/oauth2-scopes.md#L248-L271", "start_line": 248, "end_line": 271}
{"id": "docs/en/docs/advanced/security/oauth2-scopes.md::`Security` in decorator `dependencies` { #security-in-decorator-dependencies }::L272", "text": "# Doc: docs/en/docs/advanced/security/oauth2-scopes.md | Page: OAuth2 scopes { #oauth2-scopes } | Section: `Security` in decorator `dependencies` { #security-in-decorator-dependencies }\n## `Security` in decorator `dependencies` { #security-in-decorator-dependencies }\n\nThe same way you can define a `list` of `Depends` in the decorator's `dependencies` parameter (as explained in [Dependencies in path operation decorators](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md)), you could also use `Security` with `scopes` there.", "source_type": "doc", "path": "docs/en/docs/advanced/security/oauth2-scopes.md", "symbol": "`Security` in decorator `dependencies` { #security-in-decorator-dependencies }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/security/oauth2-scopes.md#L272-L274", "start_line": 272, "end_line": 274}
{"id": "docs/en/docs/advanced/settings.md::Settings and Environment Variables { #settings-and-environment-variables }::L1", "text": "# Doc: docs/en/docs/advanced/settings.md | Page: Settings and Environment Variables { #settings-and-environment-variables } | Section: Settings and Environment Variables { #settings-and-environment-variables }\n# Settings and Environment Variables { #settings-and-environment-variables }\n\nIn many cases your application could need some external settings or configurations, for example secret keys, database credentials, credentials for email services, etc.\n\nMost of these settings are variable (can change), like database URLs. And many could be sensitive, like secrets.\n\nFor this reason it's common to provide them in environment variables that are read by the application.\n\n/// tip\n\nTo understand environment variables you can read [Environment Variables](../environment-variables.md).\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/settings.md", "symbol": "Settings and Environment Variables { #settings-and-environment-variables }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/settings.md#L1-L14", "start_line": 1, "end_line": 14}
{"id": "docs/en/docs/advanced/settings.md::Types and validation { #types-and-validation }::L15", "text": "# Doc: docs/en/docs/advanced/settings.md | Page: Settings and Environment Variables { #settings-and-environment-variables } | Section: Types and validation { #types-and-validation }\n## Types and validation { #types-and-validation }\n\nThese environment variables can only handle text strings, as they are external to Python and have to be compatible with other programs and the rest of the system (and even with different operating systems, such as Linux, Windows, and macOS).\n\nThat means that any value read in Python from an environment variable will be a `str`, and any conversion to a different type or any validation has to be done in code.", "source_type": "doc", "path": "docs/en/docs/advanced/settings.md", "symbol": "Types and validation { #types-and-validation }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/settings.md#L15-L20", "start_line": 15, "end_line": 20}
{"id": "docs/en/docs/advanced/settings.md::Pydantic `Settings` { #pydantic-settings }::L21", "text": "# Doc: docs/en/docs/advanced/settings.md | Page: Settings and Environment Variables { #settings-and-environment-variables } | Section: Pydantic `Settings` { #pydantic-settings }\n## Pydantic `Settings` { #pydantic-settings }\n\nFortunately, Pydantic provides a great utility to handle these settings coming from environment variables with [Pydantic: Settings management](https://docs.pydantic.dev/latest/concepts/pydantic_settings/).\n\n### Install `pydantic-settings` { #install-pydantic-settings }\n\nFirst, make sure you create your [virtual environment](../virtual-environments.md), activate it, and then install the `pydantic-settings` package:\n\n![](\"/img/tutorial/sub-applications/image01.png\")
\n\nAnd then, open the docs for the sub-application, at [http://127.0.0.1:8000/subapi/docs](http://127.0.0.1:8000/subapi/docs).\n\nYou will see the automatic API docs for the sub-application, including only its own _path operations_, all under the correct sub-path prefix `/subapi`:\n\n![](\"/img/tutorial/sub-applications/image02.png\")
\n\nIf you try interacting with any of the two user interfaces, they will work correctly, because the browser will be able to talk to each specific app or sub-app.\n\n### Technical Details: `root_path` { #technical-details-root-path }\n\nWhen you mount a sub-application as described above, FastAPI will take care of communicating the mount path for the sub-application using a mechanism from the ASGI specification called a `root_path`.\n\nThat way, the sub-application will know to use that path prefix for the docs UI.\n\nAnd the sub-application could also have its own mounted sub-applications and everything would work correctly, because FastAPI handles all these `root_path`s automatically.\n\nYou will learn more about the `root_path` and how to use it explicitly in the section about [Behind a Proxy](behind-a-proxy.md).", "source_type": "doc", "path": "docs/en/docs/advanced/sub-applications.md", "symbol": "Mounting a **FastAPI** application { #mounting-a-fastapi-application }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/sub-applications.md#L5-L67", "start_line": 5, "end_line": 67}
{"id": "docs/en/docs/advanced/templates.md::Templates { #templates }::L1", "text": "# Doc: docs/en/docs/advanced/templates.md | Page: Templates { #templates } | Section: Templates { #templates }\n# Templates { #templates }\n\nYou can use any template engine you want with **FastAPI**.\n\nA common choice is Jinja2, the same one used by Flask and other tools.\n\nThere are utilities to configure it easily that you can use directly in your **FastAPI** application (provided by Starlette).", "source_type": "doc", "path": "docs/en/docs/advanced/templates.md", "symbol": "Templates { #templates }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/templates.md#L1-L8", "start_line": 1, "end_line": 8}
{"id": "docs/en/docs/advanced/templates.md::Install dependencies { #install-dependencies }::L9", "text": "# Doc: docs/en/docs/advanced/templates.md | Page: Templates { #templates } | Section: Install dependencies { #install-dependencies }\n## Install dependencies { #install-dependencies }\n\nMake sure you create a [virtual environment](../virtual-environments.md), activate it, and install `jinja2`:\n\n![](\"/img/tutorial/websockets/image01.png\")
\n\nYou can type messages in the input box, and send them:\n\n![](\"/img/tutorial/websockets/image02.png\")
\n\nAnd your **FastAPI** application with WebSockets will respond back:\n\n![](\"/img/tutorial/websockets/image03.png\")
\n\nYou can send (and receive) many messages:\n\n![](\"/img/tutorial/websockets/image04.png\")
\n\nAnd all of them will use the same WebSocket connection.", "source_type": "doc", "path": "docs/en/docs/advanced/websockets.md", "symbol": "Try it { #try-it }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/websockets.md#L65-L98", "start_line": 65, "end_line": 98}
{"id": "docs/en/docs/advanced/websockets.md::Using `Depends` and others { #using-depends-and-others }::L99", "text": "# Doc: docs/en/docs/advanced/websockets.md | Page: WebSockets { #websockets } | Section: Using `Depends` and others { #using-depends-and-others }\n## Using `Depends` and others { #using-depends-and-others }\n\nIn WebSocket endpoints you can import from `fastapi` and use:\n\n* `Depends`\n* `Security`\n* `Cookie`\n* `Header`\n* `Path`\n* `Query`\n\nThey work the same way as for other FastAPI endpoints/*path operations*:\n\n{* ../../docs_src/websockets_/tutorial002_an_py310.py hl[68:69,82] *}\n\n/// note\n\nAs this is a WebSocket it doesn't really make sense to raise an `HTTPException`, instead we raise a `WebSocketException`.\n\nYou can use a closing code from the [valid codes defined in the specification](https://tools.ietf.org/html/rfc6455#section-7.4.1).\n\n///\n\n### Try the WebSockets with dependencies { #try-the-websockets-with-dependencies }\n\nRun your application:\n\n![](\"/img/tutorial/websockets/image05.png\")
", "source_type": "doc", "path": "docs/en/docs/advanced/websockets.md", "symbol": "Using `Depends` and others { #using-depends-and-others }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/websockets.md#L99-L152", "start_line": 99, "end_line": 152}
{"id": "docs/en/docs/advanced/websockets.md::Handling disconnections and multiple clients { #handling-disconnections-and-multiple-clients }::L153", "text": "# Doc: docs/en/docs/advanced/websockets.md | Page: WebSockets { #websockets } | Section: Handling disconnections and multiple clients { #handling-disconnections-and-multiple-clients }\n## Handling disconnections and multiple clients { #handling-disconnections-and-multiple-clients }\n\nWhen a WebSocket connection is closed, the `await websocket.receive_text()` will raise a `WebSocketDisconnect` exception, which you can then catch and handle like in this example.\n\n{* ../../docs_src/websockets_/tutorial003_py310.py hl[79:81] *}\n\nTo try it out:\n\n* Open the app with several browser tabs.\n* Write messages from them.\n* Then close one of the tabs.\n\nThat will raise the `WebSocketDisconnect` exception, and all the other clients will receive a message like:\n\n```\nClient #1596980209979 left the chat\n```\n\n/// tip\n\nThe app above is a minimal and simple example to demonstrate how to handle and broadcast messages to several WebSocket connections.\n\nBut keep in mind that, as everything is handled in memory, in a single list, it will only work while the process is running, and will only work with a single process.\n\nIf you need something easy to integrate with FastAPI but that is more robust, supported by Redis, PostgreSQL or others, check [encode/broadcaster](https://github.com/encode/broadcaster).\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/websockets.md", "symbol": "Handling disconnections and multiple clients { #handling-disconnections-and-multiple-clients }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/websockets.md#L153-L180", "start_line": 153, "end_line": 180}
{"id": "docs/en/docs/advanced/websockets.md::More info { #more-info }::L181", "text": "# Doc: docs/en/docs/advanced/websockets.md | Page: WebSockets { #websockets } | Section: More info { #more-info }\n## More info { #more-info }\n\nTo learn more about the options, check Starlette's documentation for:\n\n* [The `WebSocket` class](https://www.starlette.dev/websockets/).\n* [Class-based WebSocket handling](https://www.starlette.dev/endpoints/#websocketendpoint).", "source_type": "doc", "path": "docs/en/docs/advanced/websockets.md", "symbol": "More info { #more-info }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/websockets.md#L181-L186", "start_line": 181, "end_line": 186}
{"id": "docs/en/docs/advanced/wsgi.md::Including WSGI - Flask, Django, others { #including-wsgi-flask-django-others }::L1", "text": "# Doc: docs/en/docs/advanced/wsgi.md | Page: Including WSGI - Flask, Django, others { #including-wsgi-flask-django-others } | Section: Including WSGI - Flask, Django, others { #including-wsgi-flask-django-others }\n# Including WSGI - Flask, Django, others { #including-wsgi-flask-django-others }\n\nYou can mount WSGI applications as you saw with [Sub Applications - Mounts](sub-applications.md), [Behind a Proxy](behind-a-proxy.md).\n\nFor that, you can use the `WSGIMiddleware` and use it to wrap your WSGI application, for example, Flask, Django, etc.", "source_type": "doc", "path": "docs/en/docs/advanced/wsgi.md", "symbol": "Including WSGI - Flask, Django, others { #including-wsgi-flask-django-others }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/wsgi.md#L1-L6", "start_line": 1, "end_line": 6}
{"id": "docs/en/docs/advanced/wsgi.md::Using `WSGIMiddleware` { #using-wsgimiddleware }::L7", "text": "# Doc: docs/en/docs/advanced/wsgi.md | Page: Including WSGI - Flask, Django, others { #including-wsgi-flask-django-others } | Section: Using `WSGIMiddleware` { #using-wsgimiddleware }\n## Using `WSGIMiddleware` { #using-wsgimiddleware }\n\n/// note\n\nThis requires installing `a2wsgi` for example with `pip install a2wsgi`.\n\n///\n\nYou need to import `WSGIMiddleware` from `a2wsgi`.\n\nThen wrap the WSGI (e.g. Flask) app with the middleware.\n\nAnd then mount that under a path.\n\n{* ../../docs_src/wsgi/tutorial001_py310.py hl[1,3,23] *}\n\n/// note\n\nPreviously, it was recommended to use `WSGIMiddleware` from `fastapi.middleware.wsgi`, but it is now deprecated.\n\nIt's advised to use the `a2wsgi` package instead. The usage remains the same.\n\nJust ensure that you have the `a2wsgi` package installed and import `WSGIMiddleware` correctly from `a2wsgi`.\n\n///", "source_type": "doc", "path": "docs/en/docs/advanced/wsgi.md", "symbol": "Using `WSGIMiddleware` { #using-wsgimiddleware }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/wsgi.md#L7-L32", "start_line": 7, "end_line": 32}
{"id": "docs/en/docs/advanced/wsgi.md::Check it { #check-it }::L33", "text": "# Doc: docs/en/docs/advanced/wsgi.md | Page: Including WSGI - Flask, Django, others { #including-wsgi-flask-django-others } | Section: Check it { #check-it }\n## Check it { #check-it }\n\nNow, every request under the path `/v1/` will be handled by the Flask application.\n\nAnd the rest will be handled by **FastAPI**.\n\nIf you run it and go to [http://localhost:8000/v1/](http://localhost:8000/v1/) you will see the response from Flask:\n\n```txt\nHello, World from Flask!\n```\n\nAnd if you go to [http://localhost:8000/v2](http://localhost:8000/v2) you will see the response from FastAPI:\n\n```JSON\n{\n \"message\": \"Hello World\"\n}\n```", "source_type": "doc", "path": "docs/en/docs/advanced/wsgi.md", "symbol": "Check it { #check-it }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/wsgi.md#L33-L51", "start_line": 33, "end_line": 51}
{"id": "docs/en/docs/alternatives.md::Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons }::L1", "text": "# Doc: docs/en/docs/alternatives.md | Page: Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons } | Section: Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons }\n# Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons }\n\nWhat inspired **FastAPI**, how it compares to alternatives and what it learned from them.", "source_type": "doc", "path": "docs/en/docs/alternatives.md", "symbol": "Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/alternatives.md#L1-L4", "start_line": 1, "end_line": 4}
{"id": "docs/en/docs/alternatives.md::Intro { #intro }::L5", "text": "# Doc: docs/en/docs/alternatives.md | Page: Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons } | Section: Intro { #intro }\n## Intro { #intro }\n\n**FastAPI** wouldn't exist if not for the previous work of others.\n\nThere have been many tools created before that have helped inspire its creation.\n\nI have been avoiding the creation of a new framework for several years. First I tried to solve all the features covered by **FastAPI** using many different frameworks, plug-ins, and tools.\n\nBut at some point, there was no other option than creating something that provided all these features, taking the best ideas from previous tools, and combining them in the best way possible, using language features that weren't even available before (Python 3.6+ type hints).", "source_type": "doc", "path": "docs/en/docs/alternatives.md", "symbol": "Intro { #intro }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/alternatives.md#L5-L14", "start_line": 5, "end_line": 14}
{"id": "docs/en/docs/alternatives.md::Previous tools { #previous-tools }::L15", "text": "# Doc: docs/en/docs/alternatives.md | Page: Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons } | Section: Previous tools { #previous-tools }\n## Previous tools { #previous-tools }\n\n### [Django](https://www.djangoproject.com/) { #django }\n\nIt's the most popular Python framework and is widely trusted. It is used to build systems like Instagram.\n\nIt's relatively tightly coupled with relational databases (like MySQL or PostgreSQL), so, having a NoSQL database (like Couchbase, MongoDB, Cassandra, etc) as the main store engine is not very easy.\n\nIt was created to generate the HTML in the backend, not to create APIs used by a modern frontend (like React, Vue.js and Angular) or by other systems (like IoT devices) communicating with it.\n\n### [Django REST Framework](https://www.django-rest-framework.org/) { #django-rest-framework }\n\nDjango REST Framework was created to be a flexible toolkit for building Web APIs using Django underneath, to improve its API capabilities.\n\nIt is used by many companies including Mozilla, Red Hat and Eventbrite.\n\nIt was one of the first examples of **automatic API documentation**, and this was specifically one of the first ideas that inspired \"the search for\" **FastAPI**.\n\n/// note\n\nDjango REST Framework was created by Tom Christie. The same creator of Starlette and Uvicorn, on which **FastAPI** is based.\n\n///\n\n/// tip | Inspired **FastAPI** to\n\nHave an automatic API documentation web user interface.\n\n///\n\n### [Flask](https://flask.palletsprojects.com) { #flask }\n\nFlask is a \"microframework\", it doesn't include database integrations nor many of the things that come by default in Django.\n\nThis simplicity and flexibility allow doing things like using NoSQL databases as the main data storage system.\n\nAs it is very simple, it's relatively intuitive to learn, although the documentation gets somewhat technical at some points.\n\nIt is also commonly used for other applications that don't necessarily need a database, user management, or any of the many features that come pre-built in Django. Although many of these features can be added with plug-ins.\n\nThis decoupling of parts, and being a \"microframework\" that could be extended to cover exactly what is needed was a key feature that I wanted to keep.\n\nGiven the simplicity of Flask, it seemed like a good match for building APIs. The next thing to find was a \"Django REST Framework\" for Flask.\n\n/// tip | Inspired **FastAPI** to\n\nBe a micro-framework. Making it easy to mix and match the tools and parts needed.\n\nHave a simple and easy to use routing system.\n\n///\n\n### [Requests](https://requests.readthedocs.io) { #requests }\n\n**FastAPI** is not actually an alternative to **Requests**. Their scope is very different.\n\nIt would actually be common to use Requests *inside* of a FastAPI application.\n\nBut still, FastAPI got quite some inspiration from Requests.\n\n**Requests** is a library to *interact* with APIs (as a client), while **FastAPI** is a library to *build* APIs (as a server).\n\nThey are, more or less, at opposite ends, complementing each other.\n\nRequests has a very simple and intuitive design, it's very easy to use, with sensible defaults. But at the same time, it's very powerful and customizable.\n\nThat's why, as said in the official website:\n\n> Requests is one of the most downloaded Python packages of all time\n\nThe way you use it is very simple. For example, to do a `GET` request, you would write:\n\n```Python\nresponse = requests.get(\"http://example.com/some/url\")\n```\n\nThe FastAPI counterpart API *path operation* could look like:\n\n```Python hl_lines=\"1\"\n@app.get(\"/some/url\")\ndef read_url():\n return {\"message\": \"Hello World\"}\n```\n\nSee the similarities in `requests.get(...)` and `@app.get(...)`.\n\n/// tip | Inspired **FastAPI** to\n\n* Have a simple and intuitive API.\n* Use HTTP method names (operations) directly, in a straightforward and intuitive way.\n* Have sensible defaults, but powerful customizations.\n\n///\n\n### [Swagger](https://swagger.io/) / [OpenAPI](https://github.com/OAI/OpenAPI-Specification/) { #swagger-openapi }\n\nThe main feature I wanted from Django REST Framework was the automatic API documentation.\n\nThen I found that there was a standard to document APIs, using JSON (or YAML, an extension of JSON) called Swagger.\n\nAnd there was a web user interface for Swagger APIs already created. So, being able to generate Swagger documentation for an API would allow using this web user interface automatically.\n\nAt some point, Swagger was given to the Linux Foundation, to be renamed OpenAPI.\n\nThat's why when talking about version 2.0 it's common to say \"Swagger\", and for version 3+ \"OpenAPI\".\n\n/// tip | Inspired **FastAPI** to\n\nAdopt and use an open standard for API specifications, instead of a custom schema.\n\nAnd integrate standards-based user interface tools:\n\n* [Swagger UI](https://github.com/swagger-api/swagger-ui)\n* [ReDoc](https://github.com/Rebilly/ReDoc)\n\nThese two were chosen for being fairly popular and stable, but doing a quick search, you could find dozens of alternative user interfaces for OpenAPI (that you can use with **FastAPI**).\n\n///\n\n### Flask REST frameworks { #flask-rest-frameworks }\n\nThere are several Flask REST frameworks, but after investing the time and work into investigating them, I found that many are discontinued or abandoned, with several standing issues that made them unfit.\n\n### [Marshmallow](https://marshmallow.readthedocs.io/en/stable/) { #marshmallow }\n\nOne of the main features needed by API systems is data \"serialization\" which is taking data from the code (Python) and converting it into something that can be sent through the network. For example, converting an object containing data from a database into a JSON object. Converting `datetime` objects into strings, etc.\n\nAnother big feature needed by APIs is data validation, making sure that the data is valid, given certain parameters. For example, that some field is an `int`, and not some random string. This is especially useful for incoming data.\n\nWithout a data validation system, you would have to do all the checks by hand, in code.\n\nThese features are what Marshmallow was built to provide. It is a great library, and I have used it a lot before.\n\nBut it was created before there existed Python type hints. So, to define every schema you need to use specific utils and classes provided by Marshmallow.\n\n/// tip | Inspired **FastAPI** to\n\nUse code to define \"schemas\" that provide data types and validation, automatically.\n\n///\n\n### [Webargs](https://webargs.readthedocs.io/en/latest/) { #webargs }\n\nAnother big feature required by APIs is parsing data from incoming requests.\n\nWebargs is a tool that was made to provide that on top of several frameworks, including Flask.\n\nIt uses Marshmallow underneath to do the data validation. And it was created by the same developers.\n\nIt's a great tool and I have used it a lot too, before having **FastAPI**.\n\n/// note\n\nWebargs was created by the same Marshmallow developers.\n\n///\n\n/// tip | Inspired **FastAPI** to\n\nHave automatic validation of incoming request data.\n\n///\n\n### [APISpec](https://apispec.readthedocs.io/en/stable/) { #apispec }\n\nMarshmallow and Webargs provide validation, parsing and serialization as plug-ins.\n\nBut documentation is still missing. Then APISpec was created.\n\nIt is a plug-in for many frameworks (and there's a plug-in for Starlette too).\n\nThe way it works is that you write the definition of the schema using YAML format inside the docstring of each function handling a route.\n\nAnd it generates OpenAPI schemas.\n\nThat's how it works in Flask, Starlette, Responder, etc.\n\nBut then, we have again the problem of having a micro-syntax, inside of a Python string (a big YAML).\n\nThe editor can't help much with that. And if we modify parameters or Marshmallow schemas and forget to also modify that YAML docstring, the generated schema would be obsolete.\n\n/// note\n\nAPISpec was created by the same Marshmallow developers.\n\n///\n\n/// tip | Inspired **FastAPI** to\n\nSupport the open standard for APIs, OpenAPI.\n\n///\n\n### [Flask-apispec](https://flask-apispec.readthedocs.io/en/latest/) { #flask-apispec }\n\nIt's a Flask plug-in, that ties together Webargs, Marshmallow and APISpec.\n\nIt uses the information from Webargs and Marshmallow to automatically generate OpenAPI schemas, using APISpec.\n\nIt's a great tool, very underrated. It should be way more popular than many Flask plug-ins out there. It might be due to its documentation being too concise and abstract.\n\nThis solved having to write YAML (another syntax) inside of Python docstrings.\n\nThis combination of Flask, Flask-apispec with Marshmallow and Webargs was my favorite backend stack until building **FastAPI**.\n\nUsing it led to the creation of several Flask full-stack generators. These are the main stacks I (and several external teams) have been using up to now:\n\n* [https://github.com/tiangolo/full-stack](https://github.com/tiangolo/full-stack)\n* [https://github.com/tiangolo/full-stack-flask-couchbase](https://github.com/tiangolo/full-stack-flask-couchbase)\n* [https://github.com/tiangolo/full-stack-flask-couchdb](https://github.com/tiangolo/full-stack-flask-couchdb)\n\nAnd these same full-stack generators were the base of the [**FastAPI** Project Generators](project-generation.md).\n\n/// note\n\nFlask-apispec was created by the same Marshmallow developers.\n\n///\n\n/// tip | Inspired **FastAPI** to\n\nGenerate the OpenAPI schema automatically, from the same code that defines serialization and validation.\n\n///\n\n### [NestJS](https://nestjs.com/) (and [Angular](https://angular.io/)) { #nestjs-and-angular }\n\nThis isn't even Python, NestJS is a JavaScript (TypeScript) NodeJS framework inspired by Angular.\n\nIt achieves something somewhat similar to what can be done with Flask-apispec.\n\nIt has an integrated dependency injection system, inspired by Angular 2. It requires pre-registering the \"injectables\" (like all the other dependency injection systems I know), so, it adds to the verbosity and code repetition.\n\nAs the parameters are described with TypeScript types (similar to Python type hints), editor support is quite good.\n\nBut as TypeScript data is not preserved after compilation to JavaScript, it cannot rely on the types to define validation, serialization and documentation at the same time. Due to this and some design decisions, to get validation, serialization and automatic schema generation, it's needed to add decorators in many places. So, it becomes quite verbose.\n\nIt can't handle nested models very well. So, if the JSON body in the request is a JSON object that has inner fields that in turn are nested JSON objects, it cannot be properly documented and validated.\n\n/// tip | Inspired **FastAPI** to\n\nUse Python types to have great editor support.\n\nHave a powerful dependency injection system. Find a way to minimize code repetition.\n\n///\n\n### [Sanic](https://sanic.readthedocs.io/en/latest/) { #sanic }\n\nIt was one of the first extremely fast Python frameworks based on `asyncio`. It was made to be very similar to Flask.\n\n/// note | Technical Details\n\nIt used [`uvloop`](https://github.com/MagicStack/uvloop) instead of the default Python `asyncio` loop. That's what made it so fast.\n\nIt clearly inspired Uvicorn and Starlette, that are currently faster than Sanic in open benchmarks.\n\n///\n\n/// tip | Inspired **FastAPI** to\n\nFind a way to have a crazy performance.\n\nThat's why **FastAPI** is based on Starlette, as it is the fastest framework available (tested by third-party benchmarks).\n\n///\n\n### [Falcon](https://falconframework.org/) { #falcon }\n\nFalcon is another high performance Python framework, it is designed to be minimal, and work as the foundation of other frameworks like Hug.\n\nIt is designed to have functions that receive two parameters, one \"request\" and one \"response\". Then you \"read\" parts from the request, and \"write\" parts to the response. Because of this design, it is not possible to declare request parameters and bodies with standard Python type hints as function parameters.\n\nSo, data validation, serialization, and documentation, have to be done in code, not automatically. Or they have to be implemented as a framework on top of Falcon, like Hug. This same distinction happens in other frameworks that are inspired by Falcon's design, of having one request object and one response object as parameters.\n\n/// tip | Inspired **FastAPI** to\n\nFind ways to get great performance.\n\nAlong with Hug (as Hug is based on Falcon) inspired **FastAPI** to declare a `response` parameter in functions.\n\nAlthough in FastAPI it's optional, and is used mainly to set headers, cookies, and alternative status codes.\n\n///\n\n### [Molten](https://moltenframework.com/) { #molten }\n\nI discovered Molten in the first stages of building **FastAPI**. And it has quite similar ideas:\n\n* Based on Python type hints.\n* Validation and documentation from these types.\n* Dependency Injection system.\n\nIt doesn't use a data validation, serialization and documentation third-party library like Pydantic, it has its own. So, these data type definitions would not be reusable as easily.\n\nIt requires a little bit more verbose configurations. And as it is based on WSGI (instead of ASGI), it is not designed to take advantage of the high performance provided by tools like Uvicorn, Starlette and Sanic.\n\nThe dependency injection system requires pre-registration of the dependencies and the dependencies are solved based on the declared types. So, it's not possible to declare more than one \"component\" that provides a certain type.\n\nRoutes are declared in a single place, using functions declared in other places (instead of using decorators that can be placed right on top of the function that handles the endpoint). This is closer to how Django does it than to how Flask (and Starlette) does it. It separates in the code things that are relatively tightly coupled.\n\n/// tip | Inspired **FastAPI** to\n\nDefine extra validations for data types using the \"default\" value of model attributes. This improves editor support, and it was not available in Pydantic before.\n\nThis actually inspired updating parts of Pydantic, to support the same validation declaration style (all this functionality is now already available in Pydantic).\n\n///\n\n### [Hug](https://github.com/hugapi/hug) { #hug }\n\nHug was one of the first frameworks to implement the declaration of API parameter types using Python type hints. This was a great idea that inspired other tools to do the same.\n\nIt used custom types in its declarations instead of standard Python types, but it was still a huge step forward.\n\nIt also was one of the first frameworks to generate a custom schema declaring the whole API in JSON.\n\nIt was not based on a standard like OpenAPI and JSON Schema. So it wouldn't be straightforward to integrate it with other tools, like Swagger UI. But again, it was a very innovative idea.\n\nIt has an interesting, uncommon feature: using the same framework, it's possible to create APIs and also CLIs.\n\nAs it is based on the previous standard for synchronous Python web frameworks (WSGI), it can't handle Websockets and other things, although it still has high performance too.\n\n/// note\n\nHug was created by Timothy Crosley, the same creator of [`isort`](https://github.com/timothycrosley/isort), a great tool to automatically sort imports in Python files.\n\n///\n\n/// tip | Ideas inspiring **FastAPI**\n\nHug inspired parts of APIStar, and was one of the tools I found most promising, alongside APIStar.\n\nHug helped inspire **FastAPI** to use Python type hints to declare parameters, and to generate a schema defining the API automatically.\n\nHug inspired **FastAPI** to declare a `response` parameter in functions to set headers and cookies.\n\n///\n\n### [APIStar](https://github.com/encode/apistar) (<= 0.5) { #apistar-0-5 }\n\nRight before deciding to build **FastAPI** I found **APIStar** server. It had almost everything I was looking for and had a great design.\n\nIt was one of the first implementations of a framework using Python type hints to declare parameters and requests that I ever saw (before NestJS and Molten). I found it more or less at the same time as Hug. But APIStar used the OpenAPI standard.\n\nIt had automatic data validation, data serialization and OpenAPI schema generation based on the same type hints in several places.\n\nBody schema definitions didn't use the same Python type hints like Pydantic, it was a bit more similar to Marshmallow, so, editor support wouldn't be as good, but still, APIStar was the best available option.\n\nIt had the best performance benchmarks at the time (only surpassed by Starlette).\n\nAt first, it didn't have an automatic API documentation web UI, but I knew I could add Swagger UI to it.\n\nIt had a dependency injection system. It required pre-registration of components, as other tools discussed above. But still, it was a great feature.\n\nI was never able to use it in a full project, as it didn't have security integration, so, I couldn't replace all the features I was having with the full-stack generators based on Flask-apispec. I had in my backlog of projects to create a pull request adding that functionality.\n\nBut then, the project's focus shifted.\n\nIt was no longer an API web framework, as the creator needed to focus on Starlette.\n\nNow APIStar is a set of tools to validate OpenAPI specifications, not a web framework.\n\n/// note\n\nAPIStar was created by Tom Christie. The same guy that created:\n\n* Django REST Framework\n* Starlette (on which **FastAPI** is based)\n* Uvicorn (used by Starlette and **FastAPI**)\n\n///\n\n/// tip | Inspired **FastAPI** to\n\nExist.\n\nThe idea of declaring multiple things (data validation, serialization and documentation) with the same Python types, that at the same time provided great editor support, was something I considered a brilliant idea.\n\nAnd after searching for a long time for a similar framework and testing many different alternatives, APIStar was the best option available.\n\nThen APIStar stopped existing as a server and Starlette was created, and was a new better foundation for such a system. That was the final inspiration to build **FastAPI**.\n\nI consider **FastAPI** a \"spiritual successor\" to APIStar, while improving and increasing the features, typing system, and other parts, based on the learnings from all these previous tools.\n\n///", "source_type": "doc", "path": "docs/en/docs/alternatives.md", "symbol": "Previous tools { #previous-tools }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/alternatives.md#L15-L401", "start_line": 15, "end_line": 401}
{"id": "docs/en/docs/alternatives.md::Used by **FastAPI** { #used-by-fastapi }::L402", "text": "# Doc: docs/en/docs/alternatives.md | Page: Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons } | Section: Used by **FastAPI** { #used-by-fastapi }\n## Used by **FastAPI** { #used-by-fastapi }\n\n### [Pydantic](https://docs.pydantic.dev/) { #pydantic }\n\nPydantic is a library to define data validation, serialization and documentation (using JSON Schema) based on Python type hints.\n\nThat makes it extremely intuitive.\n\nIt is comparable to Marshmallow. Although it's faster than Marshmallow in benchmarks. And as it is based on the same Python type hints, the editor support is great.\n\n/// tip | **FastAPI** uses it to\n\nHandle all the data validation, data serialization and automatic model documentation (based on JSON Schema).\n\n**FastAPI** then takes that JSON Schema data and puts it in OpenAPI, apart from all the other things it does.\n\n///\n\n### [Starlette](https://www.starlette.dev/) { #starlette }\n\nStarlette is a lightweight ASGI framework/toolkit, which is ideal for building high-performance asyncio services.\n\nIt is very simple and intuitive. It's designed to be easily extensible, and have modular components.\n\nIt has:\n\n* Seriously impressive performance.\n* WebSocket support.\n* In-process background tasks.\n* Startup and shutdown events.\n* Test client built on HTTPX.\n* CORS, GZip, Static Files, Streaming responses.\n* Session and Cookie support.\n* 100% test coverage.\n* 100% type annotated codebase.\n* Few hard dependencies.\n\nStarlette is currently the fastest Python framework tested. Only surpassed by Uvicorn, which is not a framework, but a server.\n\nStarlette provides all the basic web microframework functionality.\n\nBut it doesn't provide automatic data validation, serialization or documentation.\n\nThat's one of the main things that **FastAPI** adds on top, all based on Python type hints (using Pydantic). That, plus the dependency injection system, security utilities, OpenAPI schema generation, etc.\n\n/// note | Technical Details\n\nASGI is a new \"standard\" being developed by Django core team members. It is still not a \"Python standard\" (a PEP), although they are in the process of doing that.\n\nNevertheless, it is already being used as a \"standard\" by several tools. This greatly improves interoperability, as you could switch Uvicorn for any other ASGI server (like Daphne or Hypercorn), or you could add ASGI compatible tools, like `python-socketio`.\n\n///\n\n/// tip | **FastAPI** uses it to\n\nHandle all the core web parts. Adding features on top.\n\nThe class `FastAPI` itself inherits directly from the class `Starlette`.\n\nSo, anything that you can do with Starlette, you can do it directly with **FastAPI**, as it is basically Starlette on steroids.\n\n///\n\n### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn }\n\nUvicorn is a lightning-fast ASGI server, built on uvloop and httptools.\n\nIt is not a web framework, but a server. For example, it doesn't provide tools for routing by paths. That's something that a framework like Starlette (or **FastAPI**) would provide on top.\n\nIt is the recommended server for Starlette and **FastAPI**.\n\n/// tip | **FastAPI** recommends it as\n\nThe main web server to run **FastAPI** applications.\n\nYou can also use the `--workers` command line option to have an asynchronous multi-process server.\n\nCheck more details in the [Deployment](deployment/index.md) section.\n\n///", "source_type": "doc", "path": "docs/en/docs/alternatives.md", "symbol": "Used by **FastAPI** { #used-by-fastapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/alternatives.md#L402-L482", "start_line": 402, "end_line": 482}
{"id": "docs/en/docs/alternatives.md::Benchmarks and speed { #benchmarks-and-speed }::L483", "text": "# Doc: docs/en/docs/alternatives.md | Page: Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons } | Section: Benchmarks and speed { #benchmarks-and-speed }\n## Benchmarks and speed { #benchmarks-and-speed }\n\nTo understand, compare, and see the difference between Uvicorn, Starlette and FastAPI, check the section about [Benchmarks](benchmarks.md).", "source_type": "doc", "path": "docs/en/docs/alternatives.md", "symbol": "Benchmarks and speed { #benchmarks-and-speed }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/alternatives.md#L483-L485", "start_line": 483, "end_line": 485}
{"id": "docs/en/docs/async.md::Concurrency and async / await { #concurrency-and-async-await }::L1", "text": "# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: Concurrency and async / await { #concurrency-and-async-await }\n# Concurrency and async / await { #concurrency-and-async-await }\n\nDetails about the `async def` syntax for *path operation functions* and some background about asynchronous code, concurrency, and parallelism.", "source_type": "doc", "path": "docs/en/docs/async.md", "symbol": "Concurrency and async / await { #concurrency-and-async-await }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/async.md#L1-L4", "start_line": 1, "end_line": 4}
{"id": "docs/en/docs/async.md::In a hurry? { #in-a-hurry }::L5", "text": "# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: In a hurry? { #in-a-hurry }\n## In a hurry? { #in-a-hurry }\n\nTL;DR:\n\nIf you are using third party libraries that tell you to call them with `await`, like:\n\n```Python\nresults = await some_library()\n```\n\nThen, declare your *path operation functions* with `async def` like:\n\n```Python hl_lines=\"2\"\n@app.get('/')\nasync def read_results():\n results = await some_library()\n return results\n```\n\n/// note\n\nYou can only use `await` inside of functions created with `async def`.\n\n///\n\n---\n\nIf you are using a third party library that communicates with something (a database, an API, the file system, etc.) and doesn't have support for using `await`, (this is currently the case for most database libraries), then declare your *path operation functions* as normally, with just `def`, like:\n\n```Python hl_lines=\"2\"\n@app.get('/')\ndef results():\n results = some_library()\n return results\n```\n\n---\n\nIf your application (somehow) doesn't have to communicate with anything else and wait for it to respond, use `async def`, even if you don't need to use `await` inside.\n\n---\n\nIf you just don't know, use normal `def`.\n\n---\n\n**Note**: You can mix `def` and `async def` in your *path operation functions* as much as you need and define each one using the best option for you. FastAPI will do the right thing with them.\n\nAnyway, in any of the cases above, FastAPI will still work asynchronously and be extremely fast.\n\nBut by following the steps above, it will be able to do some performance optimizations.", "source_type": "doc", "path": "docs/en/docs/async.md", "symbol": "In a hurry? { #in-a-hurry }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/async.md#L5-L56", "start_line": 5, "end_line": 56}
{"id": "docs/en/docs/async.md::Technical Details { #technical-details }::L57", "text": "# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: Technical Details { #technical-details }\n## Technical Details { #technical-details }\n\nModern versions of Python have support for **\"asynchronous code\"** using something called **\"coroutines\"**, with **`async` and `await`** syntax.\n\nLet's see that phrase by parts in the sections below:\n\n* **Asynchronous Code**\n* **`async` and `await`**\n* **Coroutines**", "source_type": "doc", "path": "docs/en/docs/async.md", "symbol": "Technical Details { #technical-details }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/async.md#L57-L66", "start_line": 57, "end_line": 66}
{"id": "docs/en/docs/async.md::Asynchronous Code { #asynchronous-code }::L67", "text": "# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: Asynchronous Code { #asynchronous-code }\n## Asynchronous Code { #asynchronous-code }\n\nAsynchronous code just means that the language 💬 has a way to tell the computer / program 🤖 that at some point in the code, it 🤖 will have to wait for *something else* to finish somewhere else. Let's say that *something else* is called \"slow-file\" 📝.\n\nSo, during that time, the computer can go and do some other work, while \"slow-file\" 📝 finishes.\n\nThen the computer / program 🤖 will come back every time it has a chance because it's waiting again, or whenever it 🤖 finishes all the work it had at that point. And it 🤖 will see if any of the tasks it was waiting for have already finished, doing whatever it had to do.\n\nNext, it 🤖 takes the first task to finish (let's say, our \"slow-file\" 📝) and continues whatever it had to do with it.\n\nThat \"wait for something else\" normally refers to I/O operations that are relatively \"slow\" (compared to the speed of the processor and the RAM memory), like waiting for:\n\n* the data from the client to be sent through the network\n* the data sent by your program to be received by the client through the network\n* the contents of a file on the disk to be read by the system and given to your program\n* the contents your program gave to the system to be written to disk\n* a remote API operation\n* a database operation to finish\n* a database query to return the results\n* etc.\n\nAs the execution time is consumed mostly by waiting for I/O operations, they call them \"I/O bound\" operations.\n\nIt's called \"asynchronous\" because the computer / program doesn't have to be \"synchronized\" with the slow task, waiting for the exact moment that the task finishes, while doing nothing, to be able to take the task result and continue the work.\n\nInstead of that, by being an \"asynchronous\" system, once finished, the task can wait in line a little bit (some microseconds) for the computer / program to finish whatever it went to do, and then come back to take the results and continue working with them.\n\nFor \"synchronous\" (contrary to \"asynchronous\") they commonly also use the term \"sequential\", because the computer / program follows all the steps in sequence before switching to a different task, even if those steps involve waiting.\n\n### Concurrency and Burgers { #concurrency-and-burgers }\n\nThis idea of **asynchronous** code described above is also sometimes called **\"concurrency\"**. It is different from **\"parallelism\"**.\n\n**Concurrency** and **parallelism** both relate to \"different things happening more or less at the same time\".\n\nBut the details between *concurrency* and *parallelism* are quite different.\n\nTo see the difference, imagine the following story about burgers:\n\n### Concurrent Burgers { #concurrent-burgers }\n\nYou go with your crush to get fast food, you stand in line while the cashier takes the orders from the people in front of you. 😍\n\n![](\"/img/async/concurrent-burgers/concurrent-burgers-01.png\")
\n\nThen it's your turn, you place your order of 2 very fancy burgers for your crush and you. 🍔🍔\n\n![](\"/img/async/concurrent-burgers/concurrent-burgers-02.png\")
\n\nThe cashier says something to the cook in the kitchen so they know they have to prepare your burgers (even though they are currently preparing the ones for the previous clients).\n\n![](\"/img/async/concurrent-burgers/concurrent-burgers-03.png\")
\n\nYou pay. 💸\n\nThe cashier gives you the number of your turn.\n\n![](\"/img/async/concurrent-burgers/concurrent-burgers-04.png\")
\n\nWhile you are waiting, you go with your crush and pick a table, you sit and talk with your crush for a long time (as your burgers are very fancy and take some time to prepare).\n\nAs you are sitting at the table with your crush, while you wait for the burgers, you can spend that time admiring how awesome, cute and smart your crush is ✨😍✨.\n\n![](\"/img/async/concurrent-burgers/concurrent-burgers-05.png\")
\n\nWhile waiting and talking to your crush, from time to time, you check the number displayed on the counter to see if it's your turn already.\n\nThen at some point, it finally is your turn. You go to the counter, get your burgers and come back to the table.\n\n![](\"/img/async/concurrent-burgers/concurrent-burgers-06.png\")
\n\nYou and your crush eat the burgers and have a nice time. ✨\n\n![](\"/img/async/concurrent-burgers/concurrent-burgers-07.png\")
\n\n/// note\n\nBeautiful illustrations by [Ketrina Thompson](https://www.instagram.com/ketrinadrawsalot). 🎨\n\n///\n\n---\n\nImagine you are the computer / program 🤖 in that story.\n\nWhile you are at the line, you are just idle 😴, waiting for your turn, not doing anything very \"productive\". But the line is fast because the cashier is only taking the orders (not preparing them), so that's fine.\n\nThen, when it's your turn, you do actual \"productive\" work, you process the menu, decide what you want, get your crush's choice, pay, check that you give the correct bill or card, check that you are charged correctly, check that the order has the correct items, etc.\n\nBut then, even though you still don't have your burgers, your work with the cashier is \"on pause\" ⏸, because you have to wait 🕙 for your burgers to be ready.\n\nBut as you go away from the counter and sit at the table with a number for your turn, you can switch 🔀 your attention to your crush, and \"work\" ⏯ 🤓 on that. Then you are again doing something very \"productive\" as is flirting with your crush 😍.\n\nThen the cashier 💁 says \"I'm finished with doing the burgers\" by putting your number on the counter's display, but you don't jump like crazy immediately when the displayed number changes to your turn number. You know no one will steal your burgers because you have the number of your turn, and they have theirs.\n\nSo you wait for your crush to finish the story (finish the current work ⏯ / task being processed 🤓), smile gently and say that you are going for the burgers ⏸.\n\nThen you go to the counter 🔀, to the initial task that is now finished ⏯, pick the burgers, say thanks and take them to the table. That finishes that step / task of interaction with the counter ⏹. That in turn, creates a new task, of \"eating burgers\" 🔀 ⏯, but the previous one of \"getting burgers\" is finished ⏹.\n\n### Parallel Burgers { #parallel-burgers }\n\nNow let's imagine these aren't \"Concurrent Burgers\", but \"Parallel Burgers\".\n\nYou go with your crush to get parallel fast food.\n\nYou stand in line while several (let's say 8) cashiers that at the same time are cooks take the orders from the people in front of you.\n\nEveryone before you is waiting for their burgers to be ready before leaving the counter because each of the 8 cashiers goes and prepares the burger right away before getting the next order.\n\n![](\"/img/async/parallel-burgers/parallel-burgers-01.png\")
\n\nThen it's finally your turn, you place your order of 2 very fancy burgers for your crush and you.\n\nYou pay 💸.\n\n![](\"/img/async/parallel-burgers/parallel-burgers-02.png\")
\n\nThe cashier goes to the kitchen.\n\nYou wait, standing in front of the counter 🕙, so that no one else takes your burgers before you do, as there are no numbers for turns.\n\n![](\"/img/async/parallel-burgers/parallel-burgers-03.png\")
\n\nAs you and your crush are busy not letting anyone get in front of you and take your burgers whenever they arrive, you cannot pay attention to your crush. 😞\n\nThis is \"synchronous\" work, you are \"synchronized\" with the cashier/cook 👨🍳. You have to wait 🕙 and be there at the exact moment that the cashier/cook 👨🍳 finishes the burgers and gives them to you, or otherwise, someone else might take them.\n\n![](\"/img/async/parallel-burgers/parallel-burgers-04.png\")
\n\nThen your cashier/cook 👨🍳 finally comes back with your burgers, after a long time waiting 🕙 there in front of the counter.\n\n![](\"/img/async/parallel-burgers/parallel-burgers-05.png\")
\n\nYou take your burgers and go to the table with your crush.\n\nYou just eat them, and you are done. ⏹\n\n![](\"/img/async/parallel-burgers/parallel-burgers-06.png\")
\n\nThere was not much talk or flirting as most of the time was spent waiting 🕙 in front of the counter. 😞\n\n/// note\n\nBeautiful illustrations by [Ketrina Thompson](https://www.instagram.com/ketrinadrawsalot). 🎨\n\n///\n\n---\n\nIn this scenario of the parallel burgers, you are a computer / program 🤖 with two processors (you and your crush), both waiting 🕙 and dedicating their attention ⏯ to be \"waiting on the counter\" 🕙 for a long time.\n\nThe fast food store has 8 processors (cashiers/cooks). While the concurrent burgers store might have had only 2 (one cashier and one cook).\n\nBut still, the final experience is not the best. 😞\n\n---\n\nThis would be the parallel equivalent story for burgers. 🍔\n\nFor a more \"real life\" example of this, imagine a bank.\n\nUp to recently, most of the banks had multiple cashiers 👨💼👨💼👨💼👨💼 and a big line 🕙🕙🕙🕙🕙🕙🕙🕙.\n\nAll of the cashiers doing all the work with one client after the other 👨💼⏯.\n\nAnd you have to wait 🕙 in the line for a long time or you lose your turn.\n\nYou probably wouldn't want to take your crush 😍 with you to run errands at the bank 🏦.\n\n### Burger Conclusion { #burger-conclusion }\n\nIn this scenario of \"fast food burgers with your crush\", as there is a lot of waiting 🕙, it makes a lot more sense to have a concurrent system ⏸🔀⏯.\n\nThis is the case for most of the web applications.\n\nMany, many users, but your server is waiting 🕙 for their not-so-good connection to send their requests.\n\nAnd then waiting 🕙 again for the responses to come back.\n\nThis \"waiting\" 🕙 is measured in microseconds, but still, summing it all, it's a lot of waiting in the end.\n\nThat's why it makes a lot of sense to use asynchronous ⏸🔀⏯ code for web APIs.\n\nThis kind of asynchronicity is what made NodeJS popular (even though NodeJS is not parallel) and that's the strength of Go as a programming language.\n\nAnd that's the same level of performance you get with **FastAPI**.\n\nAnd as you can have parallelism and asynchronicity at the same time, you get higher performance than most of the tested NodeJS frameworks and on par with Go, which is a compiled language closer to C [(all thanks to Starlette)](https://www.techempower.com/benchmarks/#section=data-r17&hw=ph&test=query&l=zijmkf-1).\n\n### Is concurrency better than parallelism? { #is-concurrency-better-than-parallelism }\n\nNope! That's not the moral of the story.\n\nConcurrency is different than parallelism. And it is better in **specific** scenarios that involve a lot of waiting. Because of that, it generally is a lot better than parallelism for web application development. But not for everything.\n\nSo, to balance that out, imagine the following short story:\n\n> You have to clean a big, dirty house.\n\n*Yep, that's the whole story*.\n\n---\n\nThere's no waiting 🕙 anywhere, just a lot of work to be done, in multiple places of the house.\n\nYou could have turns as in the burgers example, first the living room, then the kitchen, but as you are not waiting 🕙 for anything, just cleaning and cleaning, the turns wouldn't affect anything.\n\nIt would take the same amount of time to finish with or without turns (concurrency) and you would have done the same amount of work.\n\nBut in this case, if you could bring the 8 ex-cashier/cooks/now-cleaners, and each one of them (plus you) could take a zone of the house to clean it, you could do all the work in **parallel**, with the extra help, and finish much sooner.\n\nIn this scenario, each one of the cleaners (including you) would be a processor, doing their part of the job.\n\nAnd as most of the execution time is taken by actual work (instead of waiting), and the work in a computer is done by a CPU, they call these problems \"CPU bound\".\n\n---\n\nCommon examples of CPU bound operations are things that require complex math processing.\n\nFor example:\n\n* **Audio** or **image processing**.\n* **Computer vision**: an image is composed of millions of pixels, each pixel has 3 values / colors, processing that normally requires computing something on those pixels, all at the same time.\n* **Machine Learning**: it normally requires lots of \"matrix\" and \"vector\" multiplications. Think of a huge spreadsheet with numbers and multiplying all of them together at the same time.\n* **Deep Learning**: this is a sub-field of Machine Learning, so, the same applies. It's just that there is not a single spreadsheet of numbers to multiply, but a huge set of them, and in many cases, you use a special processor to build and / or use those models.\n\n### Concurrency + Parallelism: Web + Machine Learning { #concurrency-parallelism-web-machine-learning }\n\nWith **FastAPI** you can take advantage of concurrency that is very common for web development (the same main attraction of NodeJS).\n\nBut you can also exploit the benefits of parallelism and multiprocessing (having multiple processes running in parallel) for **CPU bound** workloads like those in Machine Learning systems.\n\nThat, plus the simple fact that Python is the main language for **Data Science**, Machine Learning and especially Deep Learning, makes FastAPI a very good match for Data Science / Machine Learning web APIs and applications (among many others).\n\nTo see how to achieve this parallelism in production see the section about [Deployment](deployment/index.md).", "source_type": "doc", "path": "docs/en/docs/async.md", "symbol": "Asynchronous Code { #asynchronous-code }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/async.md#L67-L302", "start_line": 67, "end_line": 302}
{"id": "docs/en/docs/async.md::`async` and `await` { #async-and-await }::L303", "text": "# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: `async` and `await` { #async-and-await }\n## `async` and `await` { #async-and-await }\n\nModern versions of Python have a very intuitive way to define asynchronous code. This makes it look just like normal \"sequential\" code and do the \"awaiting\" for you at the right moments.\n\nWhen there is an operation that will require waiting before giving the results and has support for these new Python features, you can code it like:\n\n```Python\nburgers = await get_burgers(2)\n```\n\nThe key here is the `await`. It tells Python that it has to wait ⏸ for `get_burgers(2)` to finish doing its thing 🕙 before storing the results in `burgers`. With that, Python will know that it can go and do something else 🔀 ⏯ in the meanwhile (like receiving another request).\n\nFor `await` to work, it has to be inside a function that supports this asynchronicity. To do that, you just declare it with `async def`:\n\n```Python hl_lines=\"1\"\nasync def get_burgers(number: int):\n # Do some asynchronous stuff to create the burgers\n return burgers\n```\n\n...instead of `def`:\n\n```Python hl_lines=\"2\"\n# This is not asynchronous\ndef get_sequential_burgers(number: int):\n # Do some sequential stuff to create the burgers\n return burgers\n```\n\nWith `async def`, Python knows that, inside that function, it has to be aware of `await` expressions, and that it can \"pause\" ⏸ the execution of that function and go do something else 🔀 before coming back.\n\nWhen you want to call an `async def` function, you have to \"await\" it. So, this won't work:\n\n```Python\n# This won't work, because get_burgers was defined with: async def\nburgers = get_burgers(2)\n```\n\n---\n\nSo, if you are using a library that tells you that you can call it with `await`, you need to create the *path operation functions* that use it with `async def`, like in:\n\n```Python hl_lines=\"2-3\"\n@app.get('/burgers')\nasync def read_burgers():\n burgers = await get_burgers(2)\n return burgers\n```\n\n### More technical details { #more-technical-details }\n\nYou might have noticed that `await` can only be used inside of functions defined with `async def`.\n\nBut at the same time, functions defined with `async def` have to be \"awaited\". So, functions with `async def` can only be called inside of functions defined with `async def` too.\n\nSo, about the egg and the chicken, how do you call the first `async` function?\n\nIf you are working with **FastAPI** you don't have to worry about that, because that \"first\" function will be your *path operation function*, and FastAPI will know how to do the right thing.\n\nBut if you want to use `async` / `await` without FastAPI, you can do it as well.\n\n### Write your own async code { #write-your-own-async-code }\n\nStarlette (and **FastAPI**) are based on [AnyIO](https://anyio.readthedocs.io/en/stable/), which makes it compatible with both Python's standard library [asyncio](https://docs.python.org/3/library/asyncio-task.html) and [Trio](https://trio.readthedocs.io/en/stable/).\n\nIn particular, you can directly use [AnyIO](https://anyio.readthedocs.io/en/stable/) for your advanced concurrency use cases that require more advanced patterns in your own code.\n\nAnd even if you were not using FastAPI, you could also write your own async applications with [AnyIO](https://anyio.readthedocs.io/en/stable/) to be highly compatible and get its benefits (e.g. *structured concurrency*).\n\nI created another library on top of AnyIO, as a thin layer on top, to improve a bit the type annotations and get better **autocompletion**, **inline errors**, etc. It also has a friendly introduction and tutorial to help you **understand** and write **your own async code**: [Asyncer](https://asyncer.tiangolo.com/). It would be particularly useful if you need to **combine async code with regular** (blocking/synchronous) code.\n\n### Other forms of asynchronous code { #other-forms-of-asynchronous-code }\n\nThis style of using `async` and `await` is relatively new in the language.\n\nBut it makes working with asynchronous code a lot easier.\n\nThis same syntax (or almost identical) was also included recently in modern versions of JavaScript (in Browser and NodeJS).\n\nBut before that, handling asynchronous code was quite more complex and difficult.\n\nIn previous versions of Python, you could have used threads or [Gevent](https://www.gevent.org/). But the code is way more complex to understand, debug, and think about.\n\nIn previous versions of NodeJS / Browser JavaScript, you would have used \"callbacks\". Which leads to \"callback hell\".", "source_type": "doc", "path": "docs/en/docs/async.md", "symbol": "`async` and `await` { #async-and-await }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/async.md#L303-L387", "start_line": 303, "end_line": 387}
{"id": "docs/en/docs/async.md::Coroutines { #coroutines }::L388", "text": "# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: Coroutines { #coroutines }\n## Coroutines { #coroutines }\n\n**Coroutine** is just the very fancy term for the thing returned by an `async def` function. Python knows that it is something like a function, that it can start and that it will end at some point, but that it might be paused ⏸ internally too, whenever there is an `await` inside of it.\n\nBut all this functionality of using asynchronous code with `async` and `await` is many times summarized as using \"coroutines\". It is comparable to the main key feature of Go, the \"Goroutines\".", "source_type": "doc", "path": "docs/en/docs/async.md", "symbol": "Coroutines { #coroutines }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/async.md#L388-L393", "start_line": 388, "end_line": 393}
{"id": "docs/en/docs/async.md::Conclusion { #conclusion }::L394", "text": "# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: Conclusion { #conclusion }\n## Conclusion { #conclusion }\n\nLet's see the same phrase from above:\n\n> Modern versions of Python have support for **\"asynchronous code\"** using something called **\"coroutines\"**, with **`async` and `await`** syntax.\n\nThat should make more sense now. ✨\n\nAll that is what powers FastAPI (through Starlette) and what makes it have such an impressive performance.", "source_type": "doc", "path": "docs/en/docs/async.md", "symbol": "Conclusion { #conclusion }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/async.md#L394-L403", "start_line": 394, "end_line": 403}
{"id": "docs/en/docs/async.md::Very Technical Details { #very-technical-details }::L404", "text": "# Doc: docs/en/docs/async.md | Page: Concurrency and async / await { #concurrency-and-async-await } | Section: Very Technical Details { #very-technical-details }\n## Very Technical Details { #very-technical-details }\n\n/// warning\n\nYou can probably skip this.\n\nThese are very technical details of how **FastAPI** works underneath.\n\nIf you have quite some technical knowledge (coroutines, threads, blocking, etc.) and are curious about how FastAPI handles `async def` vs normal `def`, go ahead.\n\n///\n\n### Path operation functions { #path-operation-functions }\n\nWhen you declare a *path operation function* with normal `def` instead of `async def`, it is run in an external threadpool that is then awaited, instead of being called directly (as it would block the server).\n\nIf you are coming from another async framework that does not work in the way described above and you are used to defining trivial compute-only *path operation functions* with plain `def` for a tiny performance gain (about 100 nanoseconds), please note that in **FastAPI** the effect would be quite opposite. In these cases, it's better to use `async def` unless your *path operation functions* use code that performs blocking I/O.\n\nStill, in both situations, chances are that **FastAPI** will [still be faster](index.md#performance) than (or at least comparable to) your previous framework.\n\n### Dependencies { #dependencies }\n\nThe same applies for [dependencies](tutorial/dependencies/index.md). If a dependency is a standard `def` function instead of `async def`, it is run in the external threadpool.\n\n### Sub-dependencies { #sub-dependencies }\n\nYou can have multiple dependencies and [sub-dependencies](tutorial/dependencies/sub-dependencies.md) requiring each other (as parameters of the function definitions), some of them might be created with `async def` and some with normal `def`. It would still work, and the ones created with normal `def` would be called on an external thread (from the threadpool) instead of being \"awaited\".\n\n### Other utility functions { #other-utility-functions }\n\nAny other utility function that you call directly can be created with normal `def` or `async def` and FastAPI won't affect the way you call it.\n\nThis is in contrast to the functions that FastAPI calls for you: *path operation functions* and dependencies.\n\nIf your utility function is a normal function with `def`, it will be called directly (as you write it in your code), not in a threadpool, if the function is created with `async def` then you should `await` that function when you call it in your code.\n\n---\n\nAgain, these are very technical details that would probably be useful if you came searching for them.\n\nOtherwise, you should be good with the guidelines from the section above: In a hurry?.", "source_type": "doc", "path": "docs/en/docs/async.md", "symbol": "Very Technical Details { #very-technical-details }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/async.md#L404-L444", "start_line": 404, "end_line": 444}
{"id": "docs/en/docs/benchmarks.md::Benchmarks { #benchmarks }::L1", "text": "# Doc: docs/en/docs/benchmarks.md | Page: Benchmarks { #benchmarks } | Section: Benchmarks { #benchmarks }\n# Benchmarks { #benchmarks }\n\nIndependent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as [one of the fastest Python frameworks available](https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7), only below Starlette and Uvicorn themselves (used internally by FastAPI).\n\nBut when checking benchmarks and comparisons you should keep the following in mind.", "source_type": "doc", "path": "docs/en/docs/benchmarks.md", "symbol": "Benchmarks { #benchmarks }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/benchmarks.md#L1-L6", "start_line": 1, "end_line": 6}
{"id": "docs/en/docs/benchmarks.md::Benchmarks and speed { #benchmarks-and-speed }::L7", "text": "# Doc: docs/en/docs/benchmarks.md | Page: Benchmarks { #benchmarks } | Section: Benchmarks and speed { #benchmarks-and-speed }\n## Benchmarks and speed { #benchmarks-and-speed }\n\nWhen you check the benchmarks, it is common to see several tools of different types compared as equivalent.\n\nSpecifically, to see Uvicorn, Starlette and FastAPI compared together (among many other tools).\n\nThe simpler the problem solved by the tool, the better performance it will get. And most of the benchmarks don't test the additional features provided by the tool.\n\nThe hierarchy is like:\n\n* **Uvicorn**: an ASGI server\n * **Starlette**: (uses Uvicorn) a web microframework\n * **FastAPI**: (uses Starlette) an API microframework with several additional features for building APIs, with data validation, etc.\n\n* **Uvicorn**:\n * Will have the best performance, as it doesn't have much extra code apart from the server itself.\n * You wouldn't write an application in Uvicorn directly. That would mean that your code would have to include more or less, at least, all the code provided by Starlette (or **FastAPI**). And if you did that, your final application would have the same overhead as having used a framework and minimizing your app code and bugs.\n * If you are comparing Uvicorn, compare it against Daphne, Hypercorn, uWSGI, etc. Application servers.\n* **Starlette**:\n * Will have the next best performance, after Uvicorn. In fact, Starlette uses Uvicorn to run. So, it probably can only get \"slower\" than Uvicorn by having to execute more code.\n * But it provides you the tools to build simple web applications, with routing based on paths, etc.\n * If you are comparing Starlette, compare it against Sanic, Flask, Django, etc. Web frameworks (or microframeworks).\n* **FastAPI**:\n * The same way that Starlette uses Uvicorn and cannot be faster than it, **FastAPI** uses Starlette, so it cannot be faster than it.\n * FastAPI provides more features on top of Starlette. Features that you almost always need when building APIs, like data validation and serialization. And by using it, you get automatic documentation for free (the automatic documentation doesn't even add overhead to running applications, it is generated on startup).\n * If you didn't use FastAPI and used Starlette directly (or another tool, like Sanic, Flask, Responder, etc) you would have to implement all the data validation and serialization yourself. So, your final application would still have the same overhead as if it was built using FastAPI. And in many cases, this data validation and serialization is the biggest amount of code written in applications.\n * So, by using FastAPI you are saving development time, bugs, lines of code, and you would probably get the same performance (or better) you would if you didn't use it (as you would have to implement it all in your code).\n * If you are comparing FastAPI, compare it against a web application framework (or set of tools) that provides data validation, serialization and documentation, like Flask-apispec, NestJS, Molten, etc. Frameworks with integrated automatic data validation, serialization and documentation.", "source_type": "doc", "path": "docs/en/docs/benchmarks.md", "symbol": "Benchmarks and speed { #benchmarks-and-speed }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/benchmarks.md#L7-L34", "start_line": 7, "end_line": 34}
{"id": "docs/en/docs/contributing.md::Contributing::L1", "text": "# Doc: docs/en/docs/contributing.md | Page: Contributing | Section: Contributing\n# Contributing\n\nFirst, you might want to see the basic ways to [help FastAPI and get help](help-fastapi.md).", "source_type": "doc", "path": "docs/en/docs/contributing.md", "symbol": "Contributing", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/contributing.md#L1-L4", "start_line": 1, "end_line": 4}
{"id": "docs/en/docs/contributing.md::Developing::L5", "text": "# Doc: docs/en/docs/contributing.md | Page: Contributing | Section: Developing\n## Developing\n\nTo contribute code to the project, please follow the guidelines in [tiangolo.com - Contributing](https://tiangolo.com/open-source/contributing/).", "source_type": "doc", "path": "docs/en/docs/contributing.md", "symbol": "Developing", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/contributing.md#L5-L7", "start_line": 5, "end_line": 7}
{"id": "docs/en/docs/deployment/cloud.md::Deploy FastAPI on Cloud Providers { #deploy-fastapi-on-cloud-providers }::L1", "text": "# Doc: docs/en/docs/deployment/cloud.md | Page: Deploy FastAPI on Cloud Providers { #deploy-fastapi-on-cloud-providers } | Section: Deploy FastAPI on Cloud Providers { #deploy-fastapi-on-cloud-providers }\n# Deploy FastAPI on Cloud Providers { #deploy-fastapi-on-cloud-providers }\n\nYou can use virtually **any cloud provider** to deploy your FastAPI application.\n\nIn most of the cases, the main cloud providers have guides to deploy FastAPI with them.", "source_type": "doc", "path": "docs/en/docs/deployment/cloud.md", "symbol": "Deploy FastAPI on Cloud Providers { #deploy-fastapi-on-cloud-providers }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/cloud.md#L1-L6", "start_line": 1, "end_line": 6}
{"id": "docs/en/docs/deployment/cloud.md::FastAPI Cloud { #fastapi-cloud }::L7", "text": "# Doc: docs/en/docs/deployment/cloud.md | Page: Deploy FastAPI on Cloud Providers { #deploy-fastapi-on-cloud-providers } | Section: FastAPI Cloud { #fastapi-cloud }\n## FastAPI Cloud { #fastapi-cloud }\n\n**[FastAPI Cloud](https://fastapicloud.com)** is built by the same author and team behind **FastAPI**.\n\nIt streamlines the process of **building**, **deploying**, and **accessing** an API with minimal effort.\n\nIt brings the same **developer experience** of building apps with FastAPI to **deploying** them to the cloud. 🎉\n\nFastAPI Cloud is the primary sponsor and funding provider for the *FastAPI and friends* open source projects. ✨", "source_type": "doc", "path": "docs/en/docs/deployment/cloud.md", "symbol": "FastAPI Cloud { #fastapi-cloud }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/cloud.md#L7-L16", "start_line": 7, "end_line": 16}
{"id": "docs/en/docs/deployment/cloud.md::Cloud Providers - Sponsors { #cloud-providers-sponsors }::L17", "text": "# Doc: docs/en/docs/deployment/cloud.md | Page: Deploy FastAPI on Cloud Providers { #deploy-fastapi-on-cloud-providers } | Section: Cloud Providers - Sponsors { #cloud-providers-sponsors }\n## Cloud Providers - Sponsors { #cloud-providers-sponsors }\n\nSome other cloud providers ✨ [**sponsor FastAPI**](https://github.com/sponsors/tiangolo) ✨ too. 🙇\n\nYou might also want to consider them to follow their guides and try their services:\n\n* [Render](https://docs.render.com/deploy-fastapi?utm_source=deploydoc&utm_medium=referral&utm_campaign=fastapi)\n* [Railway](https://docs.railway.com/guides/fastapi?utm_medium=integration&utm_source=docs&utm_campaign=fastapi)", "source_type": "doc", "path": "docs/en/docs/deployment/cloud.md", "symbol": "Cloud Providers - Sponsors { #cloud-providers-sponsors }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/cloud.md#L17-L24", "start_line": 17, "end_line": 24}
{"id": "docs/en/docs/deployment/concepts.md::Deployments Concepts { #deployments-concepts }::L1", "text": "# Doc: docs/en/docs/deployment/concepts.md | Page: Deployments Concepts { #deployments-concepts } | Section: Deployments Concepts { #deployments-concepts }\n# Deployments Concepts { #deployments-concepts }\n\nWhen deploying a **FastAPI** application, or actually, any type of web API, there are several concepts that you probably care about, and using them you can find the **most appropriate** way to **deploy your application**.\n\nSome of the important concepts are:\n\n* Security - HTTPS\n* Running on startup\n* Restarts\n* Replication (the number of processes running)\n* Memory\n* Previous steps before starting\n\nWe'll see how they would affect **deployments**.\n\nIn the end, the ultimate objective is to be able to **serve your API clients** in a way that is **secure**, to **avoid disruptions**, and to use the **compute resources** (for example remote servers/virtual machines) as efficiently as possible. 🚀\n\nI'll tell you a bit more about these **concepts** here, and that would hopefully give you the **intuition** you would need to decide how to deploy your API in very different environments, possibly even in **future** ones that don't exist yet.\n\nBy considering these concepts, you will be able to **evaluate and design** the best way to deploy **your own APIs**.\n\nIn the next chapters, I'll give you more **concrete recipes** to deploy FastAPI applications.\n\nBut for now, let's check these important **conceptual ideas**. These concepts also apply to any other type of web API. 💡", "source_type": "doc", "path": "docs/en/docs/deployment/concepts.md", "symbol": "Deployments Concepts { #deployments-concepts }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/concepts.md#L1-L25", "start_line": 1, "end_line": 25}
{"id": "docs/en/docs/deployment/concepts.md::Security - HTTPS { #security-https }::L26", "text": "# Doc: docs/en/docs/deployment/concepts.md | Page: Deployments Concepts { #deployments-concepts } | Section: Security - HTTPS { #security-https }\n## Security - HTTPS { #security-https }\n\nIn the [previous chapter about HTTPS](https.md) we learned about how HTTPS provides encryption for your API.\n\nWe also saw that HTTPS is normally provided by a component **external** to your application server, a **TLS Termination Proxy**.\n\nAnd there has to be something in charge of **renewing the HTTPS certificates**, it could be the same component or it could be something different.\n\n### Example Tools for HTTPS { #example-tools-for-https }\n\nSome of the tools you could use as a TLS Termination Proxy are:\n\n* Traefik\n * Automatically handles certificate renewals ✨\n* Caddy\n * Automatically handles certificate renewals ✨\n* Nginx\n * With an external component like Certbot for certificate renewals\n* HAProxy\n * With an external component like Certbot for certificate renewals\n* Kubernetes with an Ingress Controller like Nginx\n * With an external component like cert-manager for certificate renewals\n* Handled internally by a cloud provider as part of their services (read below 👇)\n\nAnother option is that you could use a **cloud service** that does more of the work including setting up HTTPS. It could have some restrictions or charge you more, etc. But in that case, you wouldn't have to set up a TLS Termination Proxy yourself.\n\nI'll show you some concrete examples in the next chapters.\n\n---\n\nThen the next concepts to consider are all about the program running your actual API (e.g. Uvicorn).", "source_type": "doc", "path": "docs/en/docs/deployment/concepts.md", "symbol": "Security - HTTPS { #security-https }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/concepts.md#L26-L57", "start_line": 26, "end_line": 57}
{"id": "docs/en/docs/deployment/concepts.md::Program and Process { #program-and-process }::L58", "text": "# Doc: docs/en/docs/deployment/concepts.md | Page: Deployments Concepts { #deployments-concepts } | Section: Program and Process { #program-and-process }\n## Program and Process { #program-and-process }\n\nWe will talk a lot about the running \"**process**\", so it's useful to have clarity about what it means, and what's the difference with the word \"**program**\".\n\n### What is a Program { #what-is-a-program }\n\nThe word **program** is commonly used to describe many things:\n\n* The **code** that you write, the **Python files**.\n* The **file** that can be **executed** by the operating system, for example: `python`, `python.exe` or `uvicorn`.\n* A particular program while it is **running** on the operating system, using the CPU, and storing things in memory. This is also called a **process**.\n\n### What is a Process { #what-is-a-process }\n\nThe word **process** is normally used in a more specific way, only referring to the thing that is running in the operating system (like in the last point above):\n\n* A particular program while it is **running** on the operating system.\n * This doesn't refer to the file, nor to the code, it refers **specifically** to the thing that is being **executed** and managed by the operating system.\n* Any program, any code, **can only do things** when it is being **executed**. So, when there's a **process running**.\n* The process can be **terminated** (or \"killed\") by you, or by the operating system. At that point, it stops running/being executed, and it can **no longer do things**.\n* Each application that you have running on your computer has some process behind it, each running program, each window, etc. And there are normally many processes running **at the same time** while a computer is on.\n* There can be **multiple processes** of the **same program** running at the same time.\n\nIf you check out the \"task manager\" or \"system monitor\" (or similar tools) in your operating system, you will be able to see many of those processes running.\n\nAnd, for example, you will probably see that there are multiple processes running the same browser program (Firefox, Chrome, Edge, etc). They normally run one process per tab, plus some other extra processes.\n\n![](\"/img/deployment/concepts/image01.png\")
\n\n---\n\nNow that we know the difference between the terms **process** and **program**, let's continue talking about deployments.", "source_type": "doc", "path": "docs/en/docs/deployment/concepts.md", "symbol": "Program and Process { #program-and-process }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/concepts.md#L58-L90", "start_line": 58, "end_line": 90}
{"id": "docs/en/docs/deployment/concepts.md::Running on Startup { #running-on-startup }::L91", "text": "# Doc: docs/en/docs/deployment/concepts.md | Page: Deployments Concepts { #deployments-concepts } | Section: Running on Startup { #running-on-startup }\n## Running on Startup { #running-on-startup }\n\nIn most cases, when you create a web API, you want it to be **always running**, uninterrupted, so that your clients can always access it. This is of course, unless you have a specific reason why you want it to run only in certain situations, but most of the time you want it constantly running and **available**.\n\n### In a Remote Server { #in-a-remote-server }\n\nWhen you set up a remote server (a cloud server, a virtual machine, etc.) the simplest thing you can do is use `fastapi run` (which uses Uvicorn) or something similar, manually, the same way you do when developing locally.\n\nAnd it will work and will be useful **during development**.\n\nBut if your connection to the server is lost, the **running process** will probably die.\n\nAnd if the server is restarted (for example after updates, or migrations from the cloud provider) you probably **won't notice it**. And because of that, you won't even know that you have to restart the process manually. So, your API will just stay dead. 😱\n\n### Run Automatically on Startup { #run-automatically-on-startup }\n\nIn general, you will probably want the server program (e.g. Uvicorn) to be started automatically on server startup, and without needing any **human intervention**, to have a process always running with your API (e.g. Uvicorn running your FastAPI app).\n\n### Separate Program { #separate-program }\n\nTo achieve this, you will normally have a **separate program** that would make sure your application is run on startup. And in many cases, it would also make sure other components or applications are also run, for example, a database.\n\n### Example Tools to Run at Startup { #example-tools-to-run-at-startup }\n\nSome examples of the tools that can do this job are:\n\n* Docker\n* Kubernetes\n* Docker Compose\n* Docker in Swarm Mode\n* Systemd\n* Supervisor\n* Handled internally by a cloud provider as part of their services\n* Others...\n\nI'll give you more concrete examples in the next chapters.", "source_type": "doc", "path": "docs/en/docs/deployment/concepts.md", "symbol": "Running on Startup { #running-on-startup }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/concepts.md#L91-L127", "start_line": 91, "end_line": 127}
{"id": "docs/en/docs/deployment/concepts.md::Restarts { #restarts }::L128", "text": "# Doc: docs/en/docs/deployment/concepts.md | Page: Deployments Concepts { #deployments-concepts } | Section: Restarts { #restarts }\n## Restarts { #restarts }\n\nSimilar to making sure your application is run on startup, you probably also want to make sure it is **restarted** after failures.\n\n### We Make Mistakes { #we-make-mistakes }\n\nWe, as humans, make **mistakes**, all the time. Software almost *always* has **bugs** hidden in different places. 🐛\n\nAnd we as developers keep improving the code as we find those bugs and as we implement new features (possibly adding new bugs too 😅).\n\n### Small Errors Automatically Handled { #small-errors-automatically-handled }\n\nWhen building web APIs with FastAPI, if there's an error in our code, FastAPI will normally contain it to the single request that triggered the error. 🛡\n\nThe client will get a **500 Internal Server Error** for that request, but the application will continue working for the next requests instead of just crashing completely.\n\n### Bigger Errors - Crashes { #bigger-errors-crashes }\n\nNevertheless, there might be cases where we write some code that **crashes the entire application** making Uvicorn and Python crash. 💥\n\nAnd still, you would probably not want the application to stay dead because there was an error in one place, you probably want it to **continue running** at least for the *path operations* that are not broken.\n\n### Restart After Crash { #restart-after-crash }\n\nBut in those cases with really bad errors that crash the running **process**, you would want an external component that is in charge of **restarting** the process, at least a couple of times...\n\n/// tip\n\n...Although if the whole application is just **crashing immediately** it probably doesn't make sense to keep restarting it forever. But in those cases, you will probably notice it during development, or at least right after deployment.\n\nSo let's focus on the main cases, where it could crash entirely in some particular cases **in the future**, and it still makes sense to restart it.\n\n///\n\nYou would probably want to have the thing in charge of restarting your application as an **external component**, because by that point, the same application with Uvicorn and Python already crashed, so there's nothing in the same code of the same app that could do anything about it.\n\n### Example Tools to Restart Automatically { #example-tools-to-restart-automatically }\n\nIn most cases, the same tool that is used to **run the program on startup** is also used to handle automatic **restarts**.\n\nFor example, this could be handled by:\n\n* Docker\n* Kubernetes\n* Docker Compose\n* Docker in Swarm Mode\n* Systemd\n* Supervisor\n* Handled internally by a cloud provider as part of their services\n* Others...", "source_type": "doc", "path": "docs/en/docs/deployment/concepts.md", "symbol": "Restarts { #restarts }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/concepts.md#L128-L178", "start_line": 128, "end_line": 178}
{"id": "docs/en/docs/deployment/concepts.md::Replication - Processes and Memory { #replication-processes-and-memory }::L179", "text": "# Doc: docs/en/docs/deployment/concepts.md | Page: Deployments Concepts { #deployments-concepts } | Section: Replication - Processes and Memory { #replication-processes-and-memory }\n## Replication - Processes and Memory { #replication-processes-and-memory }\n\nWith a FastAPI application, using a server program like the `fastapi` command that runs Uvicorn, running it once in **one process** can serve multiple clients concurrently.\n\nBut in many cases, you will want to run several worker processes at the same time.\n\n### Multiple Processes - Workers { #multiple-processes-workers }\n\nIf you have more clients than what a single process can handle (for example if the virtual machine is not too big) and you have **multiple cores** in the server's CPU, then you could have **multiple processes** running with the same application at the same time, and distribute all the requests among them.\n\nWhen you run **multiple processes** of the same API program, they are commonly called **workers**.\n\n### Worker Processes and Ports { #worker-processes-and-ports }\n\nRemember from the docs [About HTTPS](https.md) that only one process can be listening on one combination of port and IP address in a server?\n\nThis is still true.\n\nSo, to be able to have **multiple processes** at the same time, there has to be a **single process listening on a port** that then transmits the communication to each worker process in some way.\n\n### Memory per Process { #memory-per-process }\n\nNow, when the program loads things in memory, for example, a machine learning model in a variable, or the contents of a large file in a variable, all that **consumes a bit of the memory (RAM)** of the server.\n\nAnd multiple processes normally **don't share any memory**. This means that each running process has its own things, variables, and memory. And if you are consuming a large amount of memory in your code, **each process** will consume an equivalent amount of memory.\n\n### Server Memory { #server-memory }\n\nFor example, if your code loads a Machine Learning model with **1 GB in size**, when you run one process with your API, it will consume at least 1 GB of RAM. And if you start **4 processes** (4 workers), each will consume 1 GB of RAM. So in total, your API will consume **4 GB of RAM**.\n\nAnd if your remote server or virtual machine only has 3 GB of RAM, trying to load more than 4 GB of RAM will cause problems. 🚨\n\n### Multiple Processes - An Example { #multiple-processes-an-example }\n\nIn this example, there's a **Manager Process** that starts and controls two **Worker Processes**.\n\nThis Manager Process would probably be the one listening on the **port** in the IP. And it would transmit all the communication to the worker processes.\n\nThose worker processes would be the ones running your application, they would perform the main computations to receive a **request** and return a **response**, and they would load anything you put in variables in RAM.\n\n![](\"/img/deployment/concepts/process-ram.drawio.svg\")
\n\nAnd of course, the same machine would probably have **other processes** running as well, apart from your application.\n\nAn interesting detail is that the percentage of the **CPU used** by each process can **vary** a lot over time, but the **memory (RAM)** normally stays more or less **stable**.\n\nIf you have an API that does a comparable amount of computations every time and you have a lot of clients, then the **CPU utilization** will probably *also be stable* (instead of constantly going up and down quickly).\n\n### Examples of Replication Tools and Strategies { #examples-of-replication-tools-and-strategies }\n\nThere can be several approaches to achieve this, and I'll tell you more about specific strategies in the next chapters, for example when talking about Docker and containers.\n\nThe main constraint to consider is that there has to be a **single** component handling the **port** in the **public IP**. And then it has to have a way to **transmit** the communication to the replicated **processes/workers**.\n\nHere are some possible combinations and strategies:\n\n* **Uvicorn** with `--workers`\n * One Uvicorn **process manager** would listen on the **IP** and **port**, and it would start **multiple Uvicorn worker processes**.\n* **Kubernetes** and other distributed **container systems**\n * Something in the **Kubernetes** layer would listen on the **IP** and **port**. The replication would be by having **multiple containers**, each with **one Uvicorn process** running.\n* **Cloud services** that handle this for you\n * The cloud service will probably **handle replication for you**. It would possibly let you define **a process to run**, or a **container image** to use, in any case, it would most probably be **a single Uvicorn process**, and the cloud service would be in charge of replicating it.\n\n/// tip\n\nDon't worry if some of these items about **containers**, Docker, or Kubernetes don't make a lot of sense yet.\n\nI'll tell you more about container images, Docker, Kubernetes, etc. in a future chapter: [FastAPI in Containers - Docker](docker.md).\n\n///", "source_type": "doc", "path": "docs/en/docs/deployment/concepts.md", "symbol": "Replication - Processes and Memory { #replication-processes-and-memory }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/concepts.md#L179-L249", "start_line": 179, "end_line": 249}
{"id": "docs/en/docs/deployment/concepts.md::Previous Steps Before Starting { #previous-steps-before-starting }::L250", "text": "# Doc: docs/en/docs/deployment/concepts.md | Page: Deployments Concepts { #deployments-concepts } | Section: Previous Steps Before Starting { #previous-steps-before-starting }\n## Previous Steps Before Starting { #previous-steps-before-starting }\n\nThere are many cases where you want to perform some steps **before starting** your application.\n\nFor example, you might want to run **database migrations**.\n\nBut in most cases, you will want to perform these steps only **once**.\n\nSo, you will want to have a **single process** to perform those **previous steps**, before starting the application.\n\nAnd you will have to make sure that it's a single process running those previous steps *even* if afterwards, you start **multiple processes** (multiple workers) for the application itself. If those steps were run by **multiple processes**, they would **duplicate** the work by running it in **parallel**, and if the steps were something delicate like a database migration, they could cause conflicts with each other.\n\nOf course, there are some cases where there's no problem in running the previous steps multiple times, in that case, it's a lot easier to handle.\n\n/// tip\n\nAlso, keep in mind that depending on your setup, in some cases you **might not even need any previous steps** before starting your application.\n\nIn that case, you wouldn't have to worry about any of this. 🤷\n\n///\n\n### Examples of Previous Steps Strategies { #examples-of-previous-steps-strategies }\n\nThis will **depend heavily** on the way you **deploy your system**, and it would probably be connected to the way you start programs, handling restarts, etc.\n\nHere are some possible ideas:\n\n* An \"Init Container\" in Kubernetes that runs before your app container\n* A bash script that runs the previous steps and then starts your application\n * You would still need a way to start/restart *that* bash script, detect errors, etc.\n\n/// tip\n\nI'll give you more concrete examples for doing this with containers in a future chapter: [FastAPI in Containers - Docker](docker.md).\n\n///", "source_type": "doc", "path": "docs/en/docs/deployment/concepts.md", "symbol": "Previous Steps Before Starting { #previous-steps-before-starting }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/concepts.md#L250-L287", "start_line": 250, "end_line": 287}
{"id": "docs/en/docs/deployment/concepts.md::Resource Utilization { #resource-utilization }::L288", "text": "# Doc: docs/en/docs/deployment/concepts.md | Page: Deployments Concepts { #deployments-concepts } | Section: Resource Utilization { #resource-utilization }\n## Resource Utilization { #resource-utilization }\n\nYour server(s) is (are) a **resource**, you can consume or **utilize**, with your programs, the computation time on the CPUs, and the RAM memory available.\n\nHow much of the system resources do you want to be consuming/utilizing? It might be easy to think \"not much\", but in reality, you will probably want to consume **as much as possible without crashing**.\n\nIf you are paying for 3 servers but you are using only a little bit of their RAM and CPU, you are probably **wasting money** 💸, and probably **wasting server electric power** 🌎, etc.\n\nIn that case, it could be better to have only 2 servers and use a higher percentage of their resources (CPU, memory, disk, network bandwidth, etc).\n\nOn the other hand, if you have 2 servers and you are using **100% of their CPU and RAM**, at some point one process will ask for more memory, and the server will have to use the disk as \"memory\" (which can be thousands of times slower), or even **crash**. Or one process might need to do some computation and would have to wait until the CPU is free again.\n\nIn this case, it would be better to get **one extra server** and run some processes on it so that they all have **enough RAM and CPU time**.\n\nThere's also the chance that for some reason you have a **spike** of usage of your API. Maybe it went viral, or maybe some other services or bots start using it. And you might want to have extra resources to be safe in those cases.\n\nYou could put an **arbitrary number** to target, for example, something **between 50% to 90%** of resource utilization. The point is that those are probably the main things you will want to measure and use to tweak your deployments.\n\nYou can use simple tools like `htop` to see the CPU and RAM used in your server or the amount used by each process. Or you can use more complex monitoring tools, which may be distributed across servers, etc.", "source_type": "doc", "path": "docs/en/docs/deployment/concepts.md", "symbol": "Resource Utilization { #resource-utilization }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/concepts.md#L288-L307", "start_line": 288, "end_line": 307}
{"id": "docs/en/docs/deployment/concepts.md::Recap { #recap }::L308", "text": "# Doc: docs/en/docs/deployment/concepts.md | Page: Deployments Concepts { #deployments-concepts } | Section: Recap { #recap }\n## Recap { #recap }\n\nYou have been reading here some of the main concepts that you would probably need to keep in mind when deciding how to deploy your application:\n\n* Security - HTTPS\n* Running on startup\n* Restarts\n* Replication (the number of processes running)\n* Memory\n* Previous steps before starting\n\nUnderstanding these ideas and how to apply them should give you the intuition necessary to take any decisions when configuring and tweaking your deployments. 🤓\n\nIn the next sections, I'll give you more concrete examples of possible strategies you can follow. 🚀", "source_type": "doc", "path": "docs/en/docs/deployment/concepts.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/concepts.md#L308-L321", "start_line": 308, "end_line": 321}
{"id": "docs/en/docs/deployment/docker.md::FastAPI in Containers - Docker { #fastapi-in-containers-docker }::L1", "text": "# Doc: docs/en/docs/deployment/docker.md | Page: FastAPI in Containers - Docker { #fastapi-in-containers-docker } | Section: FastAPI in Containers - Docker { #fastapi-in-containers-docker }\n# FastAPI in Containers - Docker { #fastapi-in-containers-docker }\n\nWhen deploying FastAPI applications a common approach is to build a **Linux container image**. It's normally done using [**Docker**](https://www.docker.com/). You can then deploy that container image in one of a few possible ways.\n\nUsing Linux containers has several advantages including **security**, **replicability**, **simplicity**, and others.\n\n/// tip\n\nIn a hurry and already know this stuff? Jump to the [`Dockerfile` below 👇](#build-a-docker-image-for-fastapi).\n\n///\n\n![](\"/img/deployment/https/https01.drawio.svg\")
\n\n### TLS Handshake Start { #tls-handshake-start }\n\nThe browser would then communicate with that IP address on **port 443** (the HTTPS port).\n\nThe first part of the communication is just to establish the connection between the client and the server and to decide the cryptographic keys they will use, etc.\n\n![](\"/img/deployment/https/https02.drawio.svg\")
\n\nThis interaction between the client and the server to establish the TLS connection is called the **TLS handshake**.\n\n### TLS with SNI Extension { #tls-with-sni-extension }\n\n**Only one process** in the server can be listening on a specific **port** in a specific **IP address**. There could be other processes listening on other ports in the same IP address, but only one for each combination of IP address and port.\n\nTLS (HTTPS) uses the specific port `443` by default. So that's the port we would need.\n\nAs only one process can be listening on this port, the process that would do it would be the **TLS Termination Proxy**.\n\nThe TLS Termination Proxy would have access to one or more **TLS certificates** (HTTPS certificates).\n\nUsing the **SNI extension** discussed above, the TLS Termination Proxy would check which of the TLS (HTTPS) certificates available it should use for this connection, using the one that matches the domain expected by the client.\n\nIn this case, it would use the certificate for `someapp.example.com`.\n\n![](\"/img/deployment/https/https03.drawio.svg\")
\n\nThe client already **trusts** the entity that generated that TLS certificate (in this case Let's Encrypt, but we'll see about that later), so it can **verify** that the certificate is valid.\n\nThen, using the certificate, the client and the TLS Termination Proxy **decide how to encrypt** the rest of the **TCP communication**. This completes the **TLS Handshake** part.\n\nAfter this, the client and the server have an **encrypted TCP connection**, this is what TLS provides. And then they can use that connection to start the actual **HTTP communication**.\n\nAnd that's what **HTTPS** is, it's just plain **HTTP** inside a **secure TLS connection** instead of a pure (unencrypted) TCP connection.\n\n/// tip\n\nNotice that the encryption of the communication happens at the **TCP level**, not at the HTTP level.\n\n///\n\n### HTTPS Request { #https-request }\n\nNow that the client and server (specifically the browser and the TLS Termination Proxy) have an **encrypted TCP connection**, they can start the **HTTP communication**.\n\nSo, the client sends an **HTTPS request**. This is just an HTTP request through an encrypted TLS connection.\n\n![](\"/img/deployment/https/https04.drawio.svg\")
\n\n### Decrypt the Request { #decrypt-the-request }\n\nThe TLS Termination Proxy would use the encryption agreed to **decrypt the request**, and would transmit the **plain (decrypted) HTTP request** to the process running the application (for example a process with Uvicorn running the FastAPI application).\n\n![](\"/img/deployment/https/https05.drawio.svg\")
\n\n### HTTP Response { #http-response }\n\nThe application would process the request and send a **plain (unencrypted) HTTP response** to the TLS Termination Proxy.\n\n![](\"/img/deployment/https/https06.drawio.svg\")
\n\n### HTTPS Response { #https-response }\n\nThe TLS Termination Proxy would then **encrypt the response** using the cryptography agreed before (that started with the certificate for `someapp.example.com`), and send it back to the browser.\n\nNext, the browser would verify that the response is valid and encrypted with the right cryptographic key, etc. It would then **decrypt the response** and process it.\n\n![](\"/img/deployment/https/https07.drawio.svg\")
\n\nThe client (browser) will know that the response comes from the correct server because it is using the cryptography they agreed using the **HTTPS certificate** before.\n\n### Multiple Applications { #multiple-applications }\n\nIn the same server (or servers), there could be **multiple applications**, for example, other API programs or a database.\n\nOnly one process can be handling the specific IP and port (the TLS Termination Proxy in our example) but the other applications/processes can be running on the server(s) too, as long as they don't try to use the same **combination of public IP and port**.\n\n![](\"/img/deployment/https/https08.drawio.svg\")
\n\nThat way, the TLS Termination Proxy could handle HTTPS and certificates for **multiple domains**, for multiple applications, and then transmit the requests to the right application in each case.\n\n### Certificate Renewal { #certificate-renewal }\n\nAt some point in the future, each certificate would **expire** (about 3 months after acquiring it).\n\nAnd then, there would be another program (in some cases it's another program, in some cases it could be the same TLS Termination Proxy) that would talk to Let's Encrypt, and renew the certificate(s).\n\n![](\"/img/deployment/https/https.drawio.svg\")
\n\nThe **TLS certificates** are **associated with a domain name**, not with an IP address.\n\nSo, to renew the certificates, the renewal program needs to **prove** to the authority (Let's Encrypt) that it indeed **\"owns\" and controls that domain**.\n\nTo do that, and to accommodate different application needs, there are several ways it can do it. Some popular ways are:\n\n* **Modify some DNS records**.\n * For this, the renewal program needs to support the APIs of the DNS provider, so, depending on the DNS provider you are using, this might or might not be an option.\n* **Run as a server** (at least during the certificate acquisition process) on the public IP address associated with the domain.\n * As we said above, only one process can be listening on a specific IP and port.\n * This is one of the reasons why it's very useful when the same TLS Termination Proxy also takes care of the certificate renewal process.\n * Otherwise, you might have to stop the TLS Termination Proxy momentarily, start the renewal program to acquire the certificates, then configure them with the TLS Termination Proxy, and then restart the TLS Termination Proxy. This is not ideal, as your app(s) will not be available during the time that the TLS Termination Proxy is off.\n\nAll this renewal process, while still serving the app, is one of the main reasons why you would want to have a **separate system to handle HTTPS** with a TLS Termination Proxy instead of just using the TLS certificates with the application server directly (e.g. Uvicorn).", "source_type": "doc", "path": "docs/en/docs/deployment/https.md", "symbol": "HTTPS for Developers { #https-for-developers }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/https.md#L60-L192", "start_line": 60, "end_line": 192}
{"id": "docs/en/docs/deployment/https.md::Proxy Forwarded Headers { #proxy-forwarded-headers }::L193", "text": "# Doc: docs/en/docs/deployment/https.md | Page: About HTTPS { #about-https } | Section: Proxy Forwarded Headers { #proxy-forwarded-headers }\n## Proxy Forwarded Headers { #proxy-forwarded-headers }\n\nWhen using a proxy to handle HTTPS, your **application server** (for example Uvicorn via FastAPI CLI) doesn't know anything about the HTTPS process, it communicates with plain HTTP with the **TLS Termination Proxy**.\n\nThis **proxy** would normally set some HTTP headers on the fly before transmitting the request to the **application server**, to let the application server know that the request is being **forwarded** by the proxy.\n\n/// note | Technical Details\n\nThe proxy headers are:\n\n* [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-For)\n* [X-Forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Proto)\n* [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Host)\n\n///\n\nNevertheless, as the **application server** doesn't know it is behind a trusted **proxy**, by default, it wouldn't trust those headers.\n\nBut you can configure the **application server** to trust the *forwarded* headers sent by the **proxy**. If you are using FastAPI CLI, you can use the *CLI Option* `--forwarded-allow-ips` to tell it from which IPs it should trust those *forwarded* headers.\n\nFor example, if the **application server** is only receiving communication from the trusted **proxy**, you can set it to `--forwarded-allow-ips=\"*\"` to make it trust all incoming IPs, as it will only receive requests from whatever is the IP used by the **proxy**.\n\nThis way the application would be able to know what is its own public URL, if it is using HTTPS, the domain, etc.\n\nThis would be useful for example to properly handle redirects.\n\n/// tip\n\nYou can learn more about this in the documentation for [Behind a Proxy - Enable Proxy Forwarded Headers](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers)\n\n///", "source_type": "doc", "path": "docs/en/docs/deployment/https.md", "symbol": "Proxy Forwarded Headers { #proxy-forwarded-headers }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/https.md#L193-L224", "start_line": 193, "end_line": 224}
{"id": "docs/en/docs/deployment/https.md::Recap { #recap }::L225", "text": "# Doc: docs/en/docs/deployment/https.md | Page: About HTTPS { #about-https } | Section: Recap { #recap }\n## Recap { #recap }\n\nHaving **HTTPS** is very important, and quite **critical** in most cases. Most of the effort you as a developer have to put around HTTPS is just about **understanding these concepts** and how they work.\n\nBut once you know the basic information of **HTTPS for developers** you can easily combine and configure different tools to help you manage everything in a simple way.\n\nIn some of the next chapters, I'll show you several concrete examples of how to set up **HTTPS** for **FastAPI** applications. 🔒", "source_type": "doc", "path": "docs/en/docs/deployment/https.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/https.md#L225-L231", "start_line": 225, "end_line": 231}
{"id": "docs/en/docs/deployment/index.md::Deployment { #deployment }::L1", "text": "# Doc: docs/en/docs/deployment/index.md | Page: Deployment { #deployment } | Section: Deployment { #deployment }\n# Deployment { #deployment }\n\nDeploying a **FastAPI** application is relatively easy.", "source_type": "doc", "path": "docs/en/docs/deployment/index.md", "symbol": "Deployment { #deployment }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/index.md#L1-L4", "start_line": 1, "end_line": 4}
{"id": "docs/en/docs/deployment/index.md::What Does Deployment Mean { #what-does-deployment-mean }::L5", "text": "# Doc: docs/en/docs/deployment/index.md | Page: Deployment { #deployment } | Section: What Does Deployment Mean { #what-does-deployment-mean }\n## What Does Deployment Mean { #what-does-deployment-mean }\n\nTo **deploy** an application means to perform the necessary steps to make it **available to the users**.\n\nFor a **web API**, it normally involves putting it in a **remote machine**, with a **server program** that provides good performance, stability, etc, so that your **users** can **access** the application efficiently and without interruptions or problems.\n\nThis is in contrast to the **development** stages, where you are constantly changing the code, breaking it and fixing it, stopping and restarting the development server, etc.", "source_type": "doc", "path": "docs/en/docs/deployment/index.md", "symbol": "What Does Deployment Mean { #what-does-deployment-mean }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/index.md#L5-L12", "start_line": 5, "end_line": 12}
{"id": "docs/en/docs/deployment/index.md::Deployment Strategies { #deployment-strategies }::L13", "text": "# Doc: docs/en/docs/deployment/index.md | Page: Deployment { #deployment } | Section: Deployment Strategies { #deployment-strategies }\n## Deployment Strategies { #deployment-strategies }\n\nThere are several ways to do it depending on your specific use case and the tools that you use.\n\nYou could **deploy a server** yourself using a combination of tools, you could use a **cloud service** that does part of the work for you, or other possible options.\n\nFor example, we, the team behind FastAPI, built [**FastAPI Cloud**](https://fastapicloud.com), to make deploying FastAPI apps to the cloud as streamlined as possible, with the same developer experience of working with FastAPI.\n\nI will show you some of the main concepts you should probably keep in mind when deploying a **FastAPI** application (although most of it applies to any other type of web application).\n\nYou will see more details to keep in mind and some of the techniques to do it in the next sections. ✨", "source_type": "doc", "path": "docs/en/docs/deployment/index.md", "symbol": "Deployment Strategies { #deployment-strategies }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/index.md#L13-L23", "start_line": 13, "end_line": 23}
{"id": "docs/en/docs/deployment/manually.md::Run a Server Manually { #run-a-server-manually }::L1", "text": "# Doc: docs/en/docs/deployment/manually.md | Page: Run a Server Manually { #run-a-server-manually } | Section: Run a Server Manually { #run-a-server-manually }\n# Run a Server Manually { #run-a-server-manually }", "source_type": "doc", "path": "docs/en/docs/deployment/manually.md", "symbol": "Run a Server Manually { #run-a-server-manually }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/deployment/manually.md#L1-L2", "start_line": 1, "end_line": 2}
{"id": "docs/en/docs/deployment/manually.md::Use the `fastapi run` Command { #use-the-fastapi-run-command }::L3", "text": "# Doc: docs/en/docs/deployment/manually.md | Page: Run a Server Manually { #run-a-server-manually } | Section: Use the `fastapi run` Command { #use-the-fastapi-run-command }\n## Use the `fastapi run` Command { #use-the-fastapi-run-command }\n\nIn short, use `fastapi run` to serve your FastAPI application:\n\n\n\n**FastAPI** wouldn't exist if not for the previous work of others.\n\nThere have been many tools created before that have helped inspire its creation.\n\nI have been avoiding the creation of a new framework for several years. First I tried to solve all the features covered by **FastAPI** using many different frameworks, plug-ins, and tools.\n\nBut at some point, there was no other option than creating something that provided all these features, taking the best ideas from previous tools, and combining them in the best way possible, using language features that weren't even available before (Python 3.6+ type hints).\n\n", "source_type": "doc", "path": "docs/en/docs/history-design-future.md", "symbol": "Alternatives { #alternatives }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/history-design-future.md#L9-L30", "start_line": 9, "end_line": 30} {"id": "docs/en/docs/history-design-future.md::Investigation { #investigation }::L31", "text": "# Doc: docs/en/docs/history-design-future.md | Page: History, Design and Future { #history-design-and-future } | Section: Investigation { #investigation }\n## Investigation { #investigation }\n\nBy using all the previous alternatives I had the chance to learn from all of them, take ideas, and combine them in the best way I could find for myself and the teams of developers I have worked with.\n\nFor example, it was clear that ideally it should be based on standard Python type hints.\n\nAlso, the best approach was to use already existing standards.\n\nSo, before even starting to code **FastAPI**, I spent several months studying the specs for OpenAPI, JSON Schema, OAuth2, etc. Understanding their relationship, overlap, and differences.", "source_type": "doc", "path": "docs/en/docs/history-design-future.md", "symbol": "Investigation { #investigation }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/history-design-future.md#L31-L40", "start_line": 31, "end_line": 40} {"id": "docs/en/docs/history-design-future.md::Design { #design }::L41", "text": "# Doc: docs/en/docs/history-design-future.md | Page: History, Design and Future { #history-design-and-future } | Section: Design { #design }\n## Design { #design }\n\nThen I spent some time designing the developer \"API\" I wanted to have as a user (as a developer using FastAPI).\n\nI tested several ideas in the most popular Python editors: PyCharm, VS Code, Jedi based editors.\n\nBy the last [Python Developer Survey](https://www.jetbrains.com/research/python-developers-survey-2018/#development-tools), that covers about 80% of the users.\n\nIt means that **FastAPI** was specifically tested with the editors used by 80% of the Python developers. And as most of the other editors tend to work similarly, all its benefits should work for virtually all editors.\n\nThat way I could find the best ways to reduce code duplication as much as possible, to have completion everywhere, type and error checks, etc.\n\nAll in a way that provided the best development experience for all the developers.", "source_type": "doc", "path": "docs/en/docs/history-design-future.md", "symbol": "Design { #design }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/history-design-future.md#L41-L54", "start_line": 41, "end_line": 54} {"id": "docs/en/docs/history-design-future.md::Requirements { #requirements }::L55", "text": "# Doc: docs/en/docs/history-design-future.md | Page: History, Design and Future { #history-design-and-future } | Section: Requirements { #requirements }\n## Requirements { #requirements }\n\nAfter testing several alternatives, I decided that I was going to use [**Pydantic**](https://docs.pydantic.dev/) for its advantages.\n\nThen I contributed to it, to make it fully compliant with JSON Schema, to support different ways to define constraint declarations, and to improve editor support (type checks, autocompletion) based on the tests in several editors.\n\nDuring the development, I also contributed to [**Starlette**](https://www.starlette.dev/), the other key requirement.", "source_type": "doc", "path": "docs/en/docs/history-design-future.md", "symbol": "Requirements { #requirements }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/history-design-future.md#L55-L62", "start_line": 55, "end_line": 62} {"id": "docs/en/docs/history-design-future.md::Development { #development }::L63", "text": "# Doc: docs/en/docs/history-design-future.md | Page: History, Design and Future { #history-design-and-future } | Section: Development { #development }\n## Development { #development }\n\nBy the time I started creating **FastAPI** itself, most of the pieces were already in place, the design was defined, the requirements and tools were ready, and the knowledge about the standards and specifications was clear and fresh.", "source_type": "doc", "path": "docs/en/docs/history-design-future.md", "symbol": "Development { #development }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/history-design-future.md#L63-L66", "start_line": 63, "end_line": 66} {"id": "docs/en/docs/history-design-future.md::Future { #future }::L67", "text": "# Doc: docs/en/docs/history-design-future.md | Page: History, Design and Future { #history-design-and-future } | Section: Future { #future }\n## Future { #future }\n\nBy this point, it's already clear that **FastAPI** with its ideas is being useful for many people.\n\nIt is being chosen over previous alternatives for suiting many use cases better.\n\nMany developers and teams already depend on **FastAPI** for their projects (including me and my team).\n\nBut still, there are many improvements and features to come.\n\n**FastAPI** has a great future ahead.\n\nAnd [your help](help-fastapi.md) is greatly appreciated.", "source_type": "doc", "path": "docs/en/docs/history-design-future.md", "symbol": "Future { #future }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/history-design-future.md#L67-L79", "start_line": 67, "end_line": 79} {"id": "docs/en/docs/how-to/authentication-error-status-code.md::Use Old 403 Authentication Error Status Codes { #use-old-403-authentication-error-status-codes }::L1", "text": "# Doc: docs/en/docs/how-to/authentication-error-status-code.md | Page: Use Old 403 Authentication Error Status Codes { #use-old-403-authentication-error-status-codes } | Section: Use Old 403 Authentication Error Status Codes { #use-old-403-authentication-error-status-codes }\n# Use Old 403 Authentication Error Status Codes { #use-old-403-authentication-error-status-codes }\n\nBefore FastAPI version `0.122.0`, when the integrated security utilities returned an error to the client after a failed authentication, they used the HTTP status code `403 Forbidden`.\n\nStarting with FastAPI version `0.122.0`, they use the more appropriate HTTP status code `401 Unauthorized`, and return a sensible `WWW-Authenticate` header in the response, following the HTTP specifications, [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-3.1), [RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#name-401-unauthorized).\n\nBut if for some reason your clients depend on the old behavior, you can revert to it by overriding the method `make_not_authenticated_error` in your security classes.\n\nFor example, you can create a subclass of `HTTPBearer` that returns a `403 Forbidden` error instead of the default `401 Unauthorized` error:\n\n{* ../../docs_src/authentication_error_status_code/tutorial001_an_py310.py hl[9:13] *}\n\n/// tip\n\nNotice that the function returns the exception instance, it doesn't raise it. The raising is done in the rest of the internal code.\n\n///", "source_type": "doc", "path": "docs/en/docs/how-to/authentication-error-status-code.md", "symbol": "Use Old 403 Authentication Error Status Codes { #use-old-403-authentication-error-status-codes }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/authentication-error-status-code.md#L1-L17", "start_line": 1, "end_line": 17} {"id": "docs/en/docs/how-to/conditional-openapi.md::Conditional OpenAPI { #conditional-openapi }::L1", "text": "# Doc: docs/en/docs/how-to/conditional-openapi.md | Page: Conditional OpenAPI { #conditional-openapi } | Section: Conditional OpenAPI { #conditional-openapi }\n# Conditional OpenAPI { #conditional-openapi }\n\nIf you needed to, you could use settings and environment variables to configure OpenAPI conditionally depending on the environment, and even disable it entirely.", "source_type": "doc", "path": "docs/en/docs/how-to/conditional-openapi.md", "symbol": "Conditional OpenAPI { #conditional-openapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/conditional-openapi.md#L1-L4", "start_line": 1, "end_line": 4} {"id": "docs/en/docs/how-to/conditional-openapi.md::About security, APIs, and docs { #about-security-apis-and-docs }::L5", "text": "# Doc: docs/en/docs/how-to/conditional-openapi.md | Page: Conditional OpenAPI { #conditional-openapi } | Section: About security, APIs, and docs { #about-security-apis-and-docs }\n## About security, APIs, and docs { #about-security-apis-and-docs }\n\nHiding your documentation user interfaces in production *shouldn't* be the way to protect your API.\n\nThat doesn't add any extra security to your API, the *path operations* will still be available where they are.\n\nIf there's a security flaw in your code, it will still exist.\n\nHiding the documentation just makes it more difficult to understand how to interact with your API, and could make it more difficult for you to debug it in production. It could be considered simply a form of [Security through obscurity](https://en.wikipedia.org/wiki/Security_through_obscurity).\n\nIf you want to secure your API, there are several better things you can do, for example:\n\n* Make sure you have well defined Pydantic models for your request bodies and responses.\n* Configure any required permissions and roles using dependencies.\n* Never store plaintext passwords, only password hashes.\n* Implement and use well-known cryptographic tools, like pwdlib and JWT tokens, etc.\n* Add more granular permission controls with OAuth2 scopes where needed.\n* ...etc.\n\nNevertheless, you might have a very specific use case where you really need to disable the API docs for some environment (e.g. for production) or depending on configurations from environment variables.", "source_type": "doc", "path": "docs/en/docs/how-to/conditional-openapi.md", "symbol": "About security, APIs, and docs { #about-security-apis-and-docs }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/conditional-openapi.md#L5-L25", "start_line": 5, "end_line": 25} {"id": "docs/en/docs/how-to/conditional-openapi.md::Conditional OpenAPI from settings and env vars { #conditional-openapi-from-settings-and-env-vars }::L26", "text": "# Doc: docs/en/docs/how-to/conditional-openapi.md | Page: Conditional OpenAPI { #conditional-openapi } | Section: Conditional OpenAPI from settings and env vars { #conditional-openapi-from-settings-and-env-vars }\n## Conditional OpenAPI from settings and env vars { #conditional-openapi-from-settings-and-env-vars }\n\nYou can easily use the same Pydantic settings to configure your generated OpenAPI and the docs UIs.\n\nFor example:\n\n{* ../../docs_src/conditional_openapi/tutorial001_py310.py hl[6,11] *}\n\nHere we declare the setting `openapi_url` with the same default of `\"/openapi.json\"`.\n\nAnd then we use it when creating the `FastAPI` app.\n\nThen you could disable OpenAPI (including the UI docs) by setting the environment variable `OPENAPI_URL` to the empty string, like:\n\n
![](\"/img/tutorial/extending-openapi/image02.png\")
\n\nBut you can disable it by setting `syntaxHighlight` to `False`:\n\n{* ../../docs_src/configure_swagger_ui/tutorial001_py310.py hl[3] *}\n\n...and then Swagger UI won't show the syntax highlighting anymore:\n\n![](\"/img/tutorial/extending-openapi/image03.png\")
", "source_type": "doc", "path": "docs/en/docs/how-to/configure-swagger-ui.md", "symbol": "Disable Syntax Highlighting { #disable-syntax-highlighting }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/configure-swagger-ui.md#L11-L26", "start_line": 11, "end_line": 26}
{"id": "docs/en/docs/how-to/configure-swagger-ui.md::Change the Theme { #change-the-theme }::L27", "text": "# Doc: docs/en/docs/how-to/configure-swagger-ui.md | Page: Configure Swagger UI { #configure-swagger-ui } | Section: Change the Theme { #change-the-theme }\n## Change the Theme { #change-the-theme }\n\nThe same way you could set the syntax highlighting theme with the key `\"syntaxHighlight.theme\"` (notice that it has a dot in the middle):\n\n{* ../../docs_src/configure_swagger_ui/tutorial002_py310.py hl[3] *}\n\nThat configuration would change the syntax highlighting color theme:\n\n![](\"/img/tutorial/extending-openapi/image04.png\")
", "source_type": "doc", "path": "docs/en/docs/how-to/configure-swagger-ui.md", "symbol": "Change the Theme { #change-the-theme }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/configure-swagger-ui.md#L27-L36", "start_line": 27, "end_line": 36}
{"id": "docs/en/docs/how-to/configure-swagger-ui.md::Change Default Swagger UI Parameters { #change-default-swagger-ui-parameters }::L37", "text": "# Doc: docs/en/docs/how-to/configure-swagger-ui.md | Page: Configure Swagger UI { #configure-swagger-ui } | Section: Change Default Swagger UI Parameters { #change-default-swagger-ui-parameters }\n## Change Default Swagger UI Parameters { #change-default-swagger-ui-parameters }\n\nFastAPI includes some default configuration parameters appropriate for most of the use cases.\n\nIt includes these default configurations:\n\n{* ../../fastapi/openapi/docs.py ln[9:24] hl[18:24] *}\n\nYou can override any of them by setting a different value in the argument `swagger_ui_parameters`.\n\nFor example, to disable `deepLinking` you could pass these settings to `swagger_ui_parameters`:\n\n{* ../../docs_src/configure_swagger_ui/tutorial003_py310.py hl[3] *}", "source_type": "doc", "path": "docs/en/docs/how-to/configure-swagger-ui.md", "symbol": "Change Default Swagger UI Parameters { #change-default-swagger-ui-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/configure-swagger-ui.md#L37-L50", "start_line": 37, "end_line": 50}
{"id": "docs/en/docs/how-to/configure-swagger-ui.md::Other Swagger UI Parameters { #other-swagger-ui-parameters }::L51", "text": "# Doc: docs/en/docs/how-to/configure-swagger-ui.md | Page: Configure Swagger UI { #configure-swagger-ui } | Section: Other Swagger UI Parameters { #other-swagger-ui-parameters }\n## Other Swagger UI Parameters { #other-swagger-ui-parameters }\n\nTo see all the other possible configurations you can use, read the official [docs for Swagger UI parameters](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/).", "source_type": "doc", "path": "docs/en/docs/how-to/configure-swagger-ui.md", "symbol": "Other Swagger UI Parameters { #other-swagger-ui-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/configure-swagger-ui.md#L51-L54", "start_line": 51, "end_line": 54}
{"id": "docs/en/docs/how-to/configure-swagger-ui.md::JavaScript-only settings { #javascript-only-settings }::L55", "text": "# Doc: docs/en/docs/how-to/configure-swagger-ui.md | Page: Configure Swagger UI { #configure-swagger-ui } | Section: JavaScript-only settings { #javascript-only-settings }\n## JavaScript-only settings { #javascript-only-settings }\n\nSwagger UI also allows other configurations to be **JavaScript-only** objects (for example, JavaScript functions).\n\nFastAPI also includes these JavaScript-only `presets` settings:\n\n```JavaScript\npresets: [\n SwaggerUIBundle.presets.apis,\n SwaggerUIBundle.SwaggerUIStandalonePreset\n]\n```\n\nThese are **JavaScript** objects, not strings, so you can't pass them from Python code directly.\n\nIf you need to use JavaScript-only configurations like those, you can use one of the methods above. Override the whole Swagger UI *path operation* and manually write any JavaScript you need.", "source_type": "doc", "path": "docs/en/docs/how-to/configure-swagger-ui.md", "symbol": "JavaScript-only settings { #javascript-only-settings }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/configure-swagger-ui.md#L55-L70", "start_line": 55, "end_line": 70}
{"id": "docs/en/docs/how-to/custom-docs-ui-assets.md::Custom Docs UI Static Assets (Self-Hosting) { #custom-docs-ui-static-assets-self-hosting }::L1", "text": "# Doc: docs/en/docs/how-to/custom-docs-ui-assets.md | Page: Custom Docs UI Static Assets (Self-Hosting) { #custom-docs-ui-static-assets-self-hosting } | Section: Custom Docs UI Static Assets (Self-Hosting) { #custom-docs-ui-static-assets-self-hosting }\n# Custom Docs UI Static Assets (Self-Hosting) { #custom-docs-ui-static-assets-self-hosting }\n\nThe API docs use **Swagger UI** and **ReDoc**, and each of those need some JavaScript and CSS files.\n\nBy default, those files are served from a CDN.\n\nBut it's possible to customize it, you can set a specific CDN, or serve the files yourself.", "source_type": "doc", "path": "docs/en/docs/how-to/custom-docs-ui-assets.md", "symbol": "Custom Docs UI Static Assets (Self-Hosting) { #custom-docs-ui-static-assets-self-hosting }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/custom-docs-ui-assets.md#L1-L8", "start_line": 1, "end_line": 8}
{"id": "docs/en/docs/how-to/custom-docs-ui-assets.md::Custom CDN for JavaScript and CSS { #custom-cdn-for-javascript-and-css }::L9", "text": "# Doc: docs/en/docs/how-to/custom-docs-ui-assets.md | Page: Custom Docs UI Static Assets (Self-Hosting) { #custom-docs-ui-static-assets-self-hosting } | Section: Custom CDN for JavaScript and CSS { #custom-cdn-for-javascript-and-css }\n## Custom CDN for JavaScript and CSS { #custom-cdn-for-javascript-and-css }\n\nLet's say that you want to use a different CDN, for example you want to use `https://unpkg.com/`.\n\nThis could be useful if for example you live in a country that restricts some URLs.\n\n### Disable the automatic docs { #disable-the-automatic-docs }\n\nThe first step is to disable the automatic docs, as by default, those use the default CDN.\n\nTo disable them, set their URLs to `None` when creating your `FastAPI` app:\n\n{* ../../docs_src/custom_docs_ui/tutorial001_py310.py hl[8] *}\n\n### Include the custom docs { #include-the-custom-docs }\n\nNow you can create the *path operations* for the custom docs.\n\nYou can reuse FastAPI's internal functions to create the HTML pages for the docs, and pass them the needed arguments:\n\n* `openapi_url`: the URL where the HTML page for the docs can get the OpenAPI schema for your API. You can use here the attribute `app.openapi_url`.\n* `title`: the title of your API.\n* `oauth2_redirect_url`: you can use `app.swagger_ui_oauth2_redirect_url` here to use the default.\n* `swagger_js_url`: the URL where the HTML for your Swagger UI docs can get the **JavaScript** file. This is the custom CDN URL.\n* `swagger_css_url`: the URL where the HTML for your Swagger UI docs can get the **CSS** file. This is the custom CDN URL.\n\nAnd similarly for ReDoc...\n\n{* ../../docs_src/custom_docs_ui/tutorial001_py310.py hl[2:6,11:19,22:24,27:33] *}\n\n/// tip\n\nThe *path operation* for `swagger_ui_redirect` is a helper for when you use OAuth2.\n\nIf you integrate your API with an OAuth2 provider, you will be able to authenticate and come back to the API docs with the acquired credentials. And interact with it using the real OAuth2 authentication.\n\nSwagger UI will handle it behind the scenes for you, but it needs this \"redirect\" helper.\n\n///\n\n### Create a *path operation* to test it { #create-a-path-operation-to-test-it }\n\nNow, to be able to test that everything works, create a *path operation*:\n\n{* ../../docs_src/custom_docs_ui/tutorial001_py310.py hl[36:38] *}\n\n### Test it { #test-it }\n\nNow, you should be able to go to your docs at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs), and reload the page, it will load those assets from the new CDN.", "source_type": "doc", "path": "docs/en/docs/how-to/custom-docs-ui-assets.md", "symbol": "Custom CDN for JavaScript and CSS { #custom-cdn-for-javascript-and-css }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/custom-docs-ui-assets.md#L9-L58", "start_line": 9, "end_line": 58}
{"id": "docs/en/docs/how-to/custom-docs-ui-assets.md::Self-hosting JavaScript and CSS for docs { #self-hosting-javascript-and-css-for-docs }::L59", "text": "# Doc: docs/en/docs/how-to/custom-docs-ui-assets.md | Page: Custom Docs UI Static Assets (Self-Hosting) { #custom-docs-ui-static-assets-self-hosting } | Section: Self-hosting JavaScript and CSS for docs { #self-hosting-javascript-and-css-for-docs }\n## Self-hosting JavaScript and CSS for docs { #self-hosting-javascript-and-css-for-docs }\n\nSelf-hosting the JavaScript and CSS could be useful if, for example, you need your app to keep working even while offline, without open Internet access, or in a local network.\n\nHere you'll see how to serve those files yourself, in the same FastAPI app, and configure the docs to use them.\n\n### Project file structure { #project-file-structure }\n\nLet's say your project file structure looks like this:\n\n```\n.\n├── app\n│ ├── __init__.py\n│ ├── main.py\n```\n\nNow create a directory to store those static files.\n\nYour new file structure could look like this:\n\n```\n.\n├── app\n│ ├── __init__.py\n│ ├── main.py\n└── static/\n```\n\n### Download the files { #download-the-files }\n\nDownload the static files needed for the docs and put them on that `static/` directory.\n\nYou can probably right-click each link and select an option similar to \"Save link as...\".\n\n**Swagger UI** uses the files:\n\n* [`swagger-ui-bundle.js`](https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js)\n* [`swagger-ui.css`](https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css)\n\nAnd **ReDoc** uses the file:\n\n* [`redoc.standalone.js`](https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js)\n\nAfter that, your file structure could look like:\n\n```\n.\n├── app\n│ ├── __init__.py\n│ ├── main.py\n└── static\n ├── redoc.standalone.js\n ├── swagger-ui-bundle.js\n └── swagger-ui.css\n```\n\n### Serve the static files { #serve-the-static-files }\n\n* Import `StaticFiles`.\n* \"Mount\" a `StaticFiles()` instance in a specific path.\n\n{* ../../docs_src/custom_docs_ui/tutorial002_py310.py hl[7,11] *}\n\n### Test the static files { #test-the-static-files }\n\nStart your application and go to [http://127.0.0.1:8000/static/redoc.standalone.js](http://127.0.0.1:8000/static/redoc.standalone.js).\n\nYou should see a very long JavaScript file for **ReDoc**.\n\nIt could start with something like:\n\n```JavaScript\n/*! For license information please see redoc.standalone.js.LICENSE.txt */\n!function(e,t){\"object\"==typeof exports&&\"object\"==typeof module?module.exports=t(require(\"null\")):\n...\n```\n\nThat confirms that you are being able to serve static files from your app, and that you placed the static files for the docs in the correct place.\n\nNow we can configure the app to use those static files for the docs.\n\n### Disable the automatic docs for static files { #disable-the-automatic-docs-for-static-files }\n\nThe same as when using a custom CDN, the first step is to disable the automatic docs, as those use the CDN by default.\n\nTo disable them, set their URLs to `None` when creating your `FastAPI` app:\n\n{* ../../docs_src/custom_docs_ui/tutorial002_py310.py hl[9] *}\n\n### Include the custom docs for static files { #include-the-custom-docs-for-static-files }\n\nAnd the same way as with a custom CDN, now you can create the *path operations* for the custom docs.\n\nAgain, you can reuse FastAPI's internal functions to create the HTML pages for the docs, and pass them the needed arguments:\n\n* `openapi_url`: the URL where the HTML page for the docs can get the OpenAPI schema for your API. You can use here the attribute `app.openapi_url`.\n* `title`: the title of your API.\n* `oauth2_redirect_url`: you can use `app.swagger_ui_oauth2_redirect_url` here to use the default.\n* `swagger_js_url`: the URL where the HTML for your Swagger UI docs can get the **JavaScript** file. **This is the one that your own app is now serving**.\n* `swagger_css_url`: the URL where the HTML for your Swagger UI docs can get the **CSS** file. **This is the one that your own app is now serving**.\n\nAnd similarly for ReDoc...\n\n{* ../../docs_src/custom_docs_ui/tutorial002_py310.py hl[2:6,14:22,25:27,30:36] *}\n\n/// tip\n\nThe *path operation* for `swagger_ui_redirect` is a helper for when you use OAuth2.\n\nIf you integrate your API with an OAuth2 provider, you will be able to authenticate and come back to the API docs with the acquired credentials. And interact with it using the real OAuth2 authentication.\n\nSwagger UI will handle it behind the scenes for you, but it needs this \"redirect\" helper.\n\n///\n\n### Create a *path operation* to test static files { #create-a-path-operation-to-test-static-files }\n\nNow, to be able to test that everything works, create a *path operation*:\n\n{* ../../docs_src/custom_docs_ui/tutorial002_py310.py hl[39:41] *}\n\n### Test Static Files UI { #test-static-files-ui }\n\nNow, you should be able to disconnect your WiFi, go to your docs at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs), and reload the page.\n\nAnd even without Internet, you would be able to see the docs for your API and interact with it.", "source_type": "doc", "path": "docs/en/docs/how-to/custom-docs-ui-assets.md", "symbol": "Self-hosting JavaScript and CSS for docs { #self-hosting-javascript-and-css-for-docs }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/custom-docs-ui-assets.md#L59-L185", "start_line": 59, "end_line": 185}
{"id": "docs/en/docs/how-to/custom-request-and-route.md::Custom Request and APIRoute class { #custom-request-and-apiroute-class }::L1", "text": "# Doc: docs/en/docs/how-to/custom-request-and-route.md | Page: Custom Request and APIRoute class { #custom-request-and-apiroute-class } | Section: Custom Request and APIRoute class { #custom-request-and-apiroute-class }\n# Custom Request and APIRoute class { #custom-request-and-apiroute-class }\n\nIn some cases, you may want to override the logic used by the `Request` and `APIRoute` classes.\n\nIn particular, this may be a good alternative to logic in a middleware.\n\nFor example, if you want to read or manipulate the request body before it is processed by your application.\n\n/// danger\n\nThis is an \"advanced\" feature.\n\nIf you are just starting with **FastAPI** you might want to skip this section.\n\n///", "source_type": "doc", "path": "docs/en/docs/how-to/custom-request-and-route.md", "symbol": "Custom Request and APIRoute class { #custom-request-and-apiroute-class }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/custom-request-and-route.md#L1-L16", "start_line": 1, "end_line": 16}
{"id": "docs/en/docs/how-to/custom-request-and-route.md::Use cases { #use-cases }::L17", "text": "# Doc: docs/en/docs/how-to/custom-request-and-route.md | Page: Custom Request and APIRoute class { #custom-request-and-apiroute-class } | Section: Use cases { #use-cases }\n## Use cases { #use-cases }\n\nSome use cases include:\n\n* Converting non-JSON request bodies to JSON (e.g. [`msgpack`](https://msgpack.org/index.html)).\n* Decompressing gzip-compressed request bodies.\n* Automatically logging all request bodies.", "source_type": "doc", "path": "docs/en/docs/how-to/custom-request-and-route.md", "symbol": "Use cases { #use-cases }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/custom-request-and-route.md#L17-L24", "start_line": 17, "end_line": 24}
{"id": "docs/en/docs/how-to/custom-request-and-route.md::Handling custom request body encodings { #handling-custom-request-body-encodings }::L25", "text": "# Doc: docs/en/docs/how-to/custom-request-and-route.md | Page: Custom Request and APIRoute class { #custom-request-and-apiroute-class } | Section: Handling custom request body encodings { #handling-custom-request-body-encodings }\n## Handling custom request body encodings { #handling-custom-request-body-encodings }\n\nLet's see how to make use of a custom `Request` subclass to decompress gzip requests.\n\nAnd an `APIRoute` subclass to use that custom request class.\n\n### Create a custom `GzipRequest` class { #create-a-custom-gziprequest-class }\n\n/// tip\n\nThis is a toy example to demonstrate how it works, if you need Gzip support, you can use the provided [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware).\n\n///\n\nFirst, we create a `GzipRequest` class, which will overwrite the `Request.body()` method to decompress the body in the presence of an appropriate header.\n\nIf there's no `gzip` in the header, it will not try to decompress the body.\n\nThat way, the same route class can handle gzip compressed or uncompressed requests.\n\n{* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[9:16] *}\n\n### Create a custom `GzipRoute` class { #create-a-custom-gziproute-class }\n\nNext, we create a custom subclass of `fastapi.routing.APIRoute` that will make use of the `GzipRequest`.\n\nThis time, it will overwrite the method `APIRoute.get_route_handler()`.\n\nThis method returns a function. And that function is what will receive a request and return a response.\n\nHere we use it to create a `GzipRequest` from the original request.\n\n{* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[19:27] *}\n\n/// note | Technical Details\n\nA `Request` has a `request.scope` attribute, that's just a Python `dict` containing the metadata related to the request.\n\nA `Request` also has a `request.receive`, that's a function to \"receive\" the body of the request.\n\nThe `scope` `dict` and `receive` function are both part of the ASGI specification.\n\nAnd those two things, `scope` and `receive`, are what is needed to create a new `Request` instance.\n\nTo learn more about the `Request` check [Starlette's docs about Requests](https://www.starlette.dev/requests/).\n\n///\n\nThe only thing the function returned by `GzipRequest.get_route_handler` does differently is convert the `Request` to a `GzipRequest`.\n\nDoing this, our `GzipRequest` will take care of decompressing the data (if necessary) before passing it to our *path operations*.\n\nAfter that, all of the processing logic is the same.\n\nBut because of our changes in `GzipRequest.body`, the request body will be automatically decompressed when it is loaded by **FastAPI** when needed.", "source_type": "doc", "path": "docs/en/docs/how-to/custom-request-and-route.md", "symbol": "Handling custom request body encodings { #handling-custom-request-body-encodings }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/custom-request-and-route.md#L25-L80", "start_line": 25, "end_line": 80}
{"id": "docs/en/docs/how-to/custom-request-and-route.md::Accessing the request body in an exception handler { #accessing-the-request-body-in-an-exception-handler }::L81", "text": "# Doc: docs/en/docs/how-to/custom-request-and-route.md | Page: Custom Request and APIRoute class { #custom-request-and-apiroute-class } | Section: Accessing the request body in an exception handler { #accessing-the-request-body-in-an-exception-handler }\n## Accessing the request body in an exception handler { #accessing-the-request-body-in-an-exception-handler }\n\n/// tip\n\nTo solve this same problem, it's probably a lot easier to use the `body` in a custom handler for `RequestValidationError` ([Handling Errors](../tutorial/handling-errors.md#use-the-requestvalidationerror-body)).\n\nBut this example is still valid and it shows how to interact with the internal components.\n\n///\n\nWe can also use this same approach to access the request body in an exception handler.\n\nAll we need to do is handle the request inside a `try`/`except` block:\n\n{* ../../docs_src/custom_request_and_route/tutorial002_an_py310.py hl[14,16] *}\n\nIf an exception occurs, the `Request` instance will still be in scope, so we can read and make use of the request body when handling the error:\n\n{* ../../docs_src/custom_request_and_route/tutorial002_an_py310.py hl[17:19] *}", "source_type": "doc", "path": "docs/en/docs/how-to/custom-request-and-route.md", "symbol": "Accessing the request body in an exception handler { #accessing-the-request-body-in-an-exception-handler }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/custom-request-and-route.md#L81-L100", "start_line": 81, "end_line": 100}
{"id": "docs/en/docs/how-to/custom-request-and-route.md::Custom `APIRoute` class in a router { #custom-apiroute-class-in-a-router }::L101", "text": "# Doc: docs/en/docs/how-to/custom-request-and-route.md | Page: Custom Request and APIRoute class { #custom-request-and-apiroute-class } | Section: Custom `APIRoute` class in a router { #custom-apiroute-class-in-a-router }\n## Custom `APIRoute` class in a router { #custom-apiroute-class-in-a-router }\n\nYou can also set the `route_class` parameter of an `APIRouter`:\n\n{* ../../docs_src/custom_request_and_route/tutorial003_py310.py hl[26] *}\n\nIn this example, the *path operations* under the `router` will use the custom `TimedRoute` class, and will have an extra `X-Response-Time` header in the response with the time it took to generate the response:\n\n{* ../../docs_src/custom_request_and_route/tutorial003_py310.py hl[13:20] *}", "source_type": "doc", "path": "docs/en/docs/how-to/custom-request-and-route.md", "symbol": "Custom `APIRoute` class in a router { #custom-apiroute-class-in-a-router }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/custom-request-and-route.md#L101-L109", "start_line": 101, "end_line": 109}
{"id": "docs/en/docs/how-to/extending-openapi.md::Extending OpenAPI { #extending-openapi }::L1", "text": "# Doc: docs/en/docs/how-to/extending-openapi.md | Page: Extending OpenAPI { #extending-openapi } | Section: Extending OpenAPI { #extending-openapi }\n# Extending OpenAPI { #extending-openapi }\n\nThere are some cases where you might need to modify the generated OpenAPI schema.\n\nIn this section you will see how.", "source_type": "doc", "path": "docs/en/docs/how-to/extending-openapi.md", "symbol": "Extending OpenAPI { #extending-openapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/extending-openapi.md#L1-L6", "start_line": 1, "end_line": 6}
{"id": "docs/en/docs/how-to/extending-openapi.md::The normal process { #the-normal-process }::L7", "text": "# Doc: docs/en/docs/how-to/extending-openapi.md | Page: Extending OpenAPI { #extending-openapi } | Section: The normal process { #the-normal-process }\n## The normal process { #the-normal-process }\n\nThe normal (default) process, is as follows.\n\nA `FastAPI` application (instance) has an `.openapi()` method that is expected to return the OpenAPI schema.\n\nAs part of the application object creation, a *path operation* for `/openapi.json` (or for whatever you set your `openapi_url`) is registered.\n\nIt just returns a JSON response with the result of the application's `.openapi()` method.\n\nBy default, what the method `.openapi()` does is check the property `.openapi_schema` to see if it has contents and return them.\n\nIf it doesn't, it generates them using the utility function at `fastapi.openapi.utils.get_openapi`.\n\nAnd that function `get_openapi()` receives as parameters:\n\n* `title`: The OpenAPI title, shown in the docs.\n* `version`: The version of your API, e.g. `2.5.0`.\n* `openapi_version`: The version of the OpenAPI specification used. By default, the latest: `3.1.0`.\n* `summary`: A short summary of the API.\n* `description`: The description of your API, this can include markdown and will be shown in the docs.\n* `routes`: The routes from the application, taken from `app.routes`. FastAPI uses them to collect the registered *path operations*, including those from included routers.\n\n/// tip | Technical Details\n\n`app.routes` is a lower-level route tree. It can include route candidates that FastAPI uses internally for included routers, not only final `APIRoute` objects.\n\nYou can still pass `app.routes` to `get_openapi()`. FastAPI will traverse that route tree to collect the effective path operations.\n\n///\n\n/// note\n\nThe parameter `summary` is available in OpenAPI 3.1.0 and above, supported by FastAPI 0.99.0 and above.\n\n///", "source_type": "doc", "path": "docs/en/docs/how-to/extending-openapi.md", "symbol": "The normal process { #the-normal-process }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/extending-openapi.md#L7-L43", "start_line": 7, "end_line": 43}
{"id": "docs/en/docs/how-to/extending-openapi.md::Overriding the defaults { #overriding-the-defaults }::L44", "text": "# Doc: docs/en/docs/how-to/extending-openapi.md | Page: Extending OpenAPI { #extending-openapi } | Section: Overriding the defaults { #overriding-the-defaults }\n## Overriding the defaults { #overriding-the-defaults }\n\nUsing the information above, you can use the same utility function to generate the OpenAPI schema and override each part that you need.\n\nFor example, let's add [ReDoc's OpenAPI extension to include a custom logo](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo).\n\n### Normal **FastAPI** { #normal-fastapi }\n\nFirst, write all your **FastAPI** application as normally:\n\n{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[1,4,7:9] *}\n\n### Generate the OpenAPI schema { #generate-the-openapi-schema }\n\nThen, use the same utility function to generate the OpenAPI schema, inside a `custom_openapi()` function:\n\n{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[2,15:21] *}\n\n### Modify the OpenAPI schema { #modify-the-openapi-schema }\n\nNow you can add the ReDoc extension, adding a custom `x-logo` to the `info` \"object\" in the OpenAPI schema:\n\n{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[22:24] *}\n\n### Cache the OpenAPI schema { #cache-the-openapi-schema }\n\nYou can use the property `.openapi_schema` as a \"cache\", to store your generated schema.\n\nThat way, your application won't have to generate the schema every time a user opens your API docs.\n\nIt will be generated only once, and then the same cached schema will be used for the next requests.\n\n{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[13:14,25:26] *}\n\n### Override the method { #override-the-method }\n\nNow you can replace the `.openapi()` method with your new function.\n\n{* ../../docs_src/extending_openapi/tutorial001_py310.py hl[29] *}\n\n### Check it { #check-it }\n\nOnce you go to [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) you will see that you are using your custom logo (in this example, **FastAPI**'s logo):\n\n![](\"/img/tutorial/extending-openapi/image01.png\")
", "source_type": "doc", "path": "docs/en/docs/how-to/extending-openapi.md", "symbol": "Overriding the defaults { #overriding-the-defaults }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/extending-openapi.md#L44-L88", "start_line": 44, "end_line": 88}
{"id": "docs/en/docs/how-to/general.md::General - How To - Recipes { #general-how-to-recipes }::L1", "text": "# Doc: docs/en/docs/how-to/general.md | Page: General - How To - Recipes { #general-how-to-recipes } | Section: General - How To - Recipes { #general-how-to-recipes }\n# General - How To - Recipes { #general-how-to-recipes }\n\nHere are several pointers to other places in the docs, for general or frequent questions.", "source_type": "doc", "path": "docs/en/docs/how-to/general.md", "symbol": "General - How To - Recipes { #general-how-to-recipes }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/general.md#L1-L4", "start_line": 1, "end_line": 4}
{"id": "docs/en/docs/how-to/general.md::Filter Data - Security { #filter-data-security }::L5", "text": "# Doc: docs/en/docs/how-to/general.md | Page: General - How To - Recipes { #general-how-to-recipes } | Section: Filter Data - Security { #filter-data-security }\n## Filter Data - Security { #filter-data-security }\n\nTo ensure that you don't return more data than you should, read the docs for [Tutorial - Response Model - Return Type](../tutorial/response-model.md).", "source_type": "doc", "path": "docs/en/docs/how-to/general.md", "symbol": "Filter Data - Security { #filter-data-security }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/general.md#L5-L8", "start_line": 5, "end_line": 8}
{"id": "docs/en/docs/how-to/general.md::Optimize Response Performance - Response Model - Return Type { #optimize-response-performance-response-model-return-type }::L9", "text": "# Doc: docs/en/docs/how-to/general.md | Page: General - How To - Recipes { #general-how-to-recipes } | Section: Optimize Response Performance - Response Model - Return Type { #optimize-response-performance-response-model-return-type }\n## Optimize Response Performance - Response Model - Return Type { #optimize-response-performance-response-model-return-type }\n\nTo optimize performance when returning JSON data, use a return type or response model, that way Pydantic will handle the serialization to JSON on the Rust side, without going through Python. Read more in the docs for [Tutorial - Response Model - Return Type](../tutorial/response-model.md).", "source_type": "doc", "path": "docs/en/docs/how-to/general.md", "symbol": "Optimize Response Performance - Response Model - Return Type { #optimize-response-performance-response-model-return-type }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/general.md#L9-L12", "start_line": 9, "end_line": 12}
{"id": "docs/en/docs/how-to/general.md::Documentation Tags - OpenAPI { #documentation-tags-openapi }::L13", "text": "# Doc: docs/en/docs/how-to/general.md | Page: General - How To - Recipes { #general-how-to-recipes } | Section: Documentation Tags - OpenAPI { #documentation-tags-openapi }\n## Documentation Tags - OpenAPI { #documentation-tags-openapi }\n\nTo add tags to your *path operations*, and group them in the docs UI, read the docs for [Tutorial - Path Operation Configurations - Tags](../tutorial/path-operation-configuration.md#tags).", "source_type": "doc", "path": "docs/en/docs/how-to/general.md", "symbol": "Documentation Tags - OpenAPI { #documentation-tags-openapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/general.md#L13-L16", "start_line": 13, "end_line": 16}
{"id": "docs/en/docs/how-to/general.md::Documentation Summary and Description - OpenAPI { #documentation-summary-and-description-openapi }::L17", "text": "# Doc: docs/en/docs/how-to/general.md | Page: General - How To - Recipes { #general-how-to-recipes } | Section: Documentation Summary and Description - OpenAPI { #documentation-summary-and-description-openapi }\n## Documentation Summary and Description - OpenAPI { #documentation-summary-and-description-openapi }\n\nTo add a summary and description to your *path operations*, and show them in the docs UI, read the docs for [Tutorial - Path Operation Configurations - Summary and Description](../tutorial/path-operation-configuration.md#summary-and-description).", "source_type": "doc", "path": "docs/en/docs/how-to/general.md", "symbol": "Documentation Summary and Description - OpenAPI { #documentation-summary-and-description-openapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/general.md#L17-L20", "start_line": 17, "end_line": 20}
{"id": "docs/en/docs/how-to/general.md::Documentation Response description - OpenAPI { #documentation-response-description-openapi }::L21", "text": "# Doc: docs/en/docs/how-to/general.md | Page: General - How To - Recipes { #general-how-to-recipes } | Section: Documentation Response description - OpenAPI { #documentation-response-description-openapi }\n## Documentation Response description - OpenAPI { #documentation-response-description-openapi }\n\nTo define the description of the response, shown in the docs UI, read the docs for [Tutorial - Path Operation Configurations - Response description](../tutorial/path-operation-configuration.md#response-description).", "source_type": "doc", "path": "docs/en/docs/how-to/general.md", "symbol": "Documentation Response description - OpenAPI { #documentation-response-description-openapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/general.md#L21-L24", "start_line": 21, "end_line": 24}
{"id": "docs/en/docs/how-to/general.md::Documentation Deprecate a *Path Operation* - OpenAPI { #documentation-deprecate-a-path-operation-openapi }::L25", "text": "# Doc: docs/en/docs/how-to/general.md | Page: General - How To - Recipes { #general-how-to-recipes } | Section: Documentation Deprecate a *Path Operation* - OpenAPI { #documentation-deprecate-a-path-operation-openapi }\n## Documentation Deprecate a *Path Operation* - OpenAPI { #documentation-deprecate-a-path-operation-openapi }\n\nTo deprecate a *path operation*, and show it in the docs UI, read the docs for [Tutorial - Path Operation Configurations - Deprecation](../tutorial/path-operation-configuration.md#deprecate-a-path-operation).", "source_type": "doc", "path": "docs/en/docs/how-to/general.md", "symbol": "Documentation Deprecate a *Path Operation* - OpenAPI { #documentation-deprecate-a-path-operation-openapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/general.md#L25-L28", "start_line": 25, "end_line": 28}
{"id": "docs/en/docs/how-to/general.md::Convert any Data to JSON-compatible { #convert-any-data-to-json-compatible }::L29", "text": "# Doc: docs/en/docs/how-to/general.md | Page: General - How To - Recipes { #general-how-to-recipes } | Section: Convert any Data to JSON-compatible { #convert-any-data-to-json-compatible }\n## Convert any Data to JSON-compatible { #convert-any-data-to-json-compatible }\n\nTo convert any data to JSON-compatible, read the docs for [Tutorial - JSON Compatible Encoder](../tutorial/encoder.md).", "source_type": "doc", "path": "docs/en/docs/how-to/general.md", "symbol": "Convert any Data to JSON-compatible { #convert-any-data-to-json-compatible }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/general.md#L29-L32", "start_line": 29, "end_line": 32}
{"id": "docs/en/docs/how-to/general.md::OpenAPI Metadata - Docs { #openapi-metadata-docs }::L33", "text": "# Doc: docs/en/docs/how-to/general.md | Page: General - How To - Recipes { #general-how-to-recipes } | Section: OpenAPI Metadata - Docs { #openapi-metadata-docs }\n## OpenAPI Metadata - Docs { #openapi-metadata-docs }\n\nTo add metadata to your OpenAPI schema, including a license, version, contact, etc, read the docs for [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md).", "source_type": "doc", "path": "docs/en/docs/how-to/general.md", "symbol": "OpenAPI Metadata - Docs { #openapi-metadata-docs }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/general.md#L33-L36", "start_line": 33, "end_line": 36}
{"id": "docs/en/docs/how-to/general.md::OpenAPI Custom URL { #openapi-custom-url }::L37", "text": "# Doc: docs/en/docs/how-to/general.md | Page: General - How To - Recipes { #general-how-to-recipes } | Section: OpenAPI Custom URL { #openapi-custom-url }\n## OpenAPI Custom URL { #openapi-custom-url }\n\nTo customize the OpenAPI URL (or remove it), read the docs for [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md#openapi-url).", "source_type": "doc", "path": "docs/en/docs/how-to/general.md", "symbol": "OpenAPI Custom URL { #openapi-custom-url }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/general.md#L37-L40", "start_line": 37, "end_line": 40}
{"id": "docs/en/docs/how-to/general.md::OpenAPI Docs URLs { #openapi-docs-urls }::L41", "text": "# Doc: docs/en/docs/how-to/general.md | Page: General - How To - Recipes { #general-how-to-recipes } | Section: OpenAPI Docs URLs { #openapi-docs-urls }\n## OpenAPI Docs URLs { #openapi-docs-urls }\n\nTo update the URLs used for the automatically generated docs user interfaces, read the docs for [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md#docs-urls).", "source_type": "doc", "path": "docs/en/docs/how-to/general.md", "symbol": "OpenAPI Docs URLs { #openapi-docs-urls }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/general.md#L41-L43", "start_line": 41, "end_line": 43}
{"id": "docs/en/docs/how-to/graphql.md::GraphQL { #graphql }::L1", "text": "# Doc: docs/en/docs/how-to/graphql.md | Page: GraphQL { #graphql } | Section: GraphQL { #graphql }\n# GraphQL { #graphql }\n\nAs **FastAPI** is based on the **ASGI** standard, it's very easy to integrate any **GraphQL** library also compatible with ASGI.\n\nYou can combine normal FastAPI *path operations* with GraphQL on the same application.\n\n/// tip\n\n**GraphQL** solves some very specific use cases.\n\nIt has **advantages** and **disadvantages** when compared to common **web APIs**.\n\nMake sure you evaluate if the **benefits** for your use case compensate the **drawbacks**. 🤓\n\n///", "source_type": "doc", "path": "docs/en/docs/how-to/graphql.md", "symbol": "GraphQL { #graphql }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/graphql.md#L1-L16", "start_line": 1, "end_line": 16}
{"id": "docs/en/docs/how-to/graphql.md::GraphQL Libraries { #graphql-libraries }::L17", "text": "# Doc: docs/en/docs/how-to/graphql.md | Page: GraphQL { #graphql } | Section: GraphQL Libraries { #graphql-libraries }\n## GraphQL Libraries { #graphql-libraries }\n\nHere are some of the **GraphQL** libraries that have **ASGI** support. You could use them with **FastAPI**:\n\n* [Strawberry](https://strawberry.rocks/) 🍓\n * With [docs for FastAPI](https://strawberry.rocks/docs/integrations/fastapi)\n* [Ariadne](https://ariadnegraphql.org/)\n * With [docs for FastAPI](https://ariadnegraphql.org/docs/fastapi-integration)\n* [Tartiflette](https://tartiflette.io/)\n * With [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) to provide ASGI integration\n* [Graphene](https://graphene-python.org/)\n * With [starlette-graphene3](https://github.com/ciscorn/starlette-graphene3)", "source_type": "doc", "path": "docs/en/docs/how-to/graphql.md", "symbol": "GraphQL Libraries { #graphql-libraries }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/graphql.md#L17-L29", "start_line": 17, "end_line": 29}
{"id": "docs/en/docs/how-to/graphql.md::GraphQL with Strawberry { #graphql-with-strawberry }::L30", "text": "# Doc: docs/en/docs/how-to/graphql.md | Page: GraphQL { #graphql } | Section: GraphQL with Strawberry { #graphql-with-strawberry }\n## GraphQL with Strawberry { #graphql-with-strawberry }\n\nIf you need or want to work with **GraphQL**, [**Strawberry**](https://strawberry.rocks/) is the **recommended** library as it has the design closest to **FastAPI's** design, it's all based on **type annotations**.\n\nDepending on your use case, you might prefer to use a different library, but if you asked me, I would probably suggest you try **Strawberry**.\n\nHere's a small preview of how you could integrate Strawberry with FastAPI:\n\n{* ../../docs_src/graphql_/tutorial001_py310.py hl[3,22,25] *}\n\nYou can learn more about Strawberry in the [Strawberry documentation](https://strawberry.rocks/).\n\nAnd also the docs about [Strawberry with FastAPI](https://strawberry.rocks/docs/integrations/fastapi).", "source_type": "doc", "path": "docs/en/docs/how-to/graphql.md", "symbol": "GraphQL with Strawberry { #graphql-with-strawberry }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/graphql.md#L30-L43", "start_line": 30, "end_line": 43}
{"id": "docs/en/docs/how-to/graphql.md::Older `GraphQLApp` from Starlette { #older-graphqlapp-from-starlette }::L44", "text": "# Doc: docs/en/docs/how-to/graphql.md | Page: GraphQL { #graphql } | Section: Older `GraphQLApp` from Starlette { #older-graphqlapp-from-starlette }\n## Older `GraphQLApp` from Starlette { #older-graphqlapp-from-starlette }\n\nPrevious versions of Starlette included a `GraphQLApp` class to integrate with [Graphene](https://graphene-python.org/).\n\nIt was deprecated from Starlette, but if you have code that used it, you can easily **migrate** to [starlette-graphene3](https://github.com/ciscorn/starlette-graphene3), that covers the same use case and has an **almost identical interface**.\n\n/// tip\n\nIf you need GraphQL, I still would recommend you check out [Strawberry](https://strawberry.rocks/), as it's based on type annotations instead of custom classes and types.\n\n///", "source_type": "doc", "path": "docs/en/docs/how-to/graphql.md", "symbol": "Older `GraphQLApp` from Starlette { #older-graphqlapp-from-starlette }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/graphql.md#L44-L55", "start_line": 44, "end_line": 55}
{"id": "docs/en/docs/how-to/graphql.md::Learn More { #learn-more }::L56", "text": "# Doc: docs/en/docs/how-to/graphql.md | Page: GraphQL { #graphql } | Section: Learn More { #learn-more }\n## Learn More { #learn-more }\n\nYou can learn more about **GraphQL** in the [official GraphQL documentation](https://graphql.org/).\n\nYou can also read more about each of those libraries described above in their links.", "source_type": "doc", "path": "docs/en/docs/how-to/graphql.md", "symbol": "Learn More { #learn-more }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/graphql.md#L56-L60", "start_line": 56, "end_line": 60}
{"id": "docs/en/docs/how-to/index.md::How To - Recipes { #how-to-recipes }::L1", "text": "# Doc: docs/en/docs/how-to/index.md | Page: How To - Recipes { #how-to-recipes } | Section: How To - Recipes { #how-to-recipes }\n# How To - Recipes { #how-to-recipes }\n\nHere you will see different recipes or \"how to\" guides for **several topics**.\n\nMost of these ideas would be more or less **independent**, and in most cases you should only need to study them if they apply directly to **your project**.\n\nIf something seems interesting and useful to your project, go ahead and check it, but otherwise, you might probably just skip them.\n\n/// tip\n\nIf you want to **learn FastAPI** in a structured way (recommended), go and read the [Tutorial - User Guide](../tutorial/index.md) chapter by chapter instead.\n\n///", "source_type": "doc", "path": "docs/en/docs/how-to/index.md", "symbol": "How To - Recipes { #how-to-recipes }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/index.md#L1-L13", "start_line": 1, "end_line": 13}
{"id": "docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md::Migrate from Pydantic v1 to Pydantic v2 { #migrate-from-pydantic-v1-to-pydantic-v2 }::L1", "text": "# Doc: docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md | Page: Migrate from Pydantic v1 to Pydantic v2 { #migrate-from-pydantic-v1-to-pydantic-v2 } | Section: Migrate from Pydantic v1 to Pydantic v2 { #migrate-from-pydantic-v1-to-pydantic-v2 }\n# Migrate from Pydantic v1 to Pydantic v2 { #migrate-from-pydantic-v1-to-pydantic-v2 }\n\nIf you have an old FastAPI app, you might be using Pydantic version 1.\n\nFastAPI version 0.100.0 had support for either Pydantic v1 or v2. It would use whichever you had installed.\n\nFastAPI version 0.119.0 introduced partial support for Pydantic v1 from inside of Pydantic v2 (as `pydantic.v1`), to facilitate the migration to v2.\n\nFastAPI 0.126.0 dropped support for Pydantic v1, while still supporting `pydantic.v1` for a little while.\n\nFastAPI 0.128.0 dropped support for `pydantic.v1` as well, so the latest versions of FastAPI require Pydantic v2.\n\n/// warning\n\nThe Pydantic team stopped support for Pydantic v1 for the latest versions of Python, starting with **Python 3.14**.\n\nThis includes `pydantic.v1`, which is no longer supported in Python 3.14 and above.\n\nIf you want to use the latest features of Python, you will need to make sure you use Pydantic v2.\n\n///\n\nIf you have an old FastAPI app with Pydantic v1, here I'll show you how to migrate it to Pydantic v2, and the **features in FastAPI 0.119.0** to help you with a gradual migration.", "source_type": "doc", "path": "docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md", "symbol": "Migrate from Pydantic v1 to Pydantic v2 { #migrate-from-pydantic-v1-to-pydantic-v2 }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md#L1-L24", "start_line": 1, "end_line": 24}
{"id": "docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md::Official Guide { #official-guide }::L25", "text": "# Doc: docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md | Page: Migrate from Pydantic v1 to Pydantic v2 { #migrate-from-pydantic-v1-to-pydantic-v2 } | Section: Official Guide { #official-guide }\n## Official Guide { #official-guide }\n\nPydantic has an official [Migration Guide](https://docs.pydantic.dev/latest/migration/) from v1 to v2.\n\nIt also includes what has changed, how validations are now more correct and strict, possible caveats, etc.\n\nYou can read it to understand better what has changed.", "source_type": "doc", "path": "docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md", "symbol": "Official Guide { #official-guide }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md#L25-L32", "start_line": 25, "end_line": 32}
{"id": "docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md::Tests { #tests }::L33", "text": "# Doc: docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md | Page: Migrate from Pydantic v1 to Pydantic v2 { #migrate-from-pydantic-v1-to-pydantic-v2 } | Section: Tests { #tests }\n## Tests { #tests }\n\nMake sure you have [tests](../tutorial/testing.md) for your app and you run them on continuous integration (CI).\n\nThis way, you can do the upgrade and make sure everything is still working as expected.", "source_type": "doc", "path": "docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md", "symbol": "Tests { #tests }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md#L33-L38", "start_line": 33, "end_line": 38}
{"id": "docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md::`bump-pydantic` { #bump-pydantic }::L39", "text": "# Doc: docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md | Page: Migrate from Pydantic v1 to Pydantic v2 { #migrate-from-pydantic-v1-to-pydantic-v2 } | Section: `bump-pydantic` { #bump-pydantic }\n## `bump-pydantic` { #bump-pydantic }\n\nIn many cases, when you use regular Pydantic models without customizations, you will be able to automate most of the process of migrating from Pydantic v1 to Pydantic v2.\n\nYou can use [`bump-pydantic`](https://github.com/pydantic/bump-pydantic) from the same Pydantic team.\n\nThis tool will help you to automatically change most of the code that needs to be changed.\n\nAfter this, you can run the tests and check if everything works. If it does, you are done. 😎", "source_type": "doc", "path": "docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md", "symbol": "`bump-pydantic` { #bump-pydantic }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md#L39-L48", "start_line": 39, "end_line": 48}
{"id": "docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md::Pydantic v1 in v2 { #pydantic-v1-in-v2 }::L49", "text": "# Doc: docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md | Page: Migrate from Pydantic v1 to Pydantic v2 { #migrate-from-pydantic-v1-to-pydantic-v2 } | Section: Pydantic v1 in v2 { #pydantic-v1-in-v2 }\n## Pydantic v1 in v2 { #pydantic-v1-in-v2 }\n\nPydantic v2 includes everything from Pydantic v1 as a submodule `pydantic.v1`. But this is no longer supported in versions above Python 3.13.\n\nThis means that you can install the latest version of Pydantic v2 and import and use the old Pydantic v1 components from this submodule, as if you had the old Pydantic v1 installed.\n\n{* ../../docs_src/pydantic_v1_in_v2/tutorial001_an_py310.py hl[1,4] *}\n\n### FastAPI support for Pydantic v1 in v2 { #fastapi-support-for-pydantic-v1-in-v2 }\n\n/// warning\n\nThis FastAPI support for `pydantic.v1` models was added in **FastAPI 0.119.0** and removed in **FastAPI 0.128.0**. It was meant to be a temporary aid for the migration to Pydantic v2.\n\nIn current versions of FastAPI, using a `pydantic.v1` model in your app will raise an error.\n\nThe rest of this section describes the temporary support available only in those older versions.\n\n///\n\nSince FastAPI 0.119.0, there's also partial support for Pydantic v1 from inside of Pydantic v2, to facilitate the migration to v2.\n\nSo, you could upgrade Pydantic to the latest version 2, and change the imports to use the `pydantic.v1` submodule, and in many cases it would just work.\n\n{* ../../docs_src/pydantic_v1_in_v2/tutorial002_an_py310.py hl[2,5,15] *}\n\n/// warning\n\nHave in mind that as the Pydantic team no longer supports Pydantic v1 in recent versions of Python, starting from Python 3.14, using `pydantic.v1` is also not supported in Python 3.14 and above.\n\n///\n\n### Pydantic v1 and v2 on the same app { #pydantic-v1-and-v2-on-the-same-app }\n\nIt's **not supported** by Pydantic to have a model of Pydantic v2 with its own fields defined as Pydantic v1 models or vice versa.\n\n```mermaid\ngraph TB\n subgraph \"❌ Not Supported\"\n direction TB\n subgraph V2[\"Pydantic v2 Model\"]\n V1Field[\"Pydantic v1 Model\"]\n end\n subgraph V1[\"Pydantic v1 Model\"]\n V2Field[\"Pydantic v2 Model\"]\n end\n end\n\n style V2 fill:#f9fff3\n style V1 fill:#fff6f0\n style V1Field fill:#fff6f0\n style V2Field fill:#f9fff3\n```\n\n...but you can have separate models, some using Pydantic v1 and others using Pydantic v2, in the same app.\n\n```mermaid\ngraph TB\n subgraph \"✅ Supported\"\n direction TB\n subgraph V2[\"Pydantic v2 Model\"]\n V2Field[\"Pydantic v2 Model\"]\n end\n subgraph V1[\"Pydantic v1 Model\"]\n V1Field[\"Pydantic v1 Model\"]\n end\n end\n\n style V2 fill:#f9fff3\n style V1 fill:#fff6f0\n style V1Field fill:#fff6f0\n style V2Field fill:#f9fff3\n```\n\nIn some cases, it's even possible to have both Pydantic v1 and v2 models in the same **path operation** in your FastAPI app:\n\n{* ../../docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py hl[2:3,6,12,21:22] *}\n\nIn this example above, the input model is a Pydantic v1 model, and the output model (defined in `response_model=ItemV2`) is a Pydantic v2 model.\n\n### Pydantic v1 parameters { #pydantic-v1-parameters }\n\nIf you need to use some of the FastAPI-specific tools for parameters like `Body`, `Query`, `Form`, etc. with Pydantic v1 models, you can import them from `fastapi.temp_pydantic_v1_params` while you finish the migration to Pydantic v2:\n\n{* ../../docs_src/pydantic_v1_in_v2/tutorial004_an_py310.py hl[4,18] *}\n\n### Migrate in steps { #migrate-in-steps }\n\n/// warning\n\nThe gradual migration using both Pydantic v1 and v2 models in the same app described below only works in **FastAPI 0.119.0 to 0.127.x**. It was removed in **FastAPI 0.128.0**, the latest versions require **Pydantic v2** models.\n\n///\n\n/// tip\n\nFirst try with `bump-pydantic`, if your tests pass and that works, then you're done in one command. ✨\n\n///\n\nIf `bump-pydantic` doesn't work for your use case, you can use the support for both Pydantic v1 and v2 models in the same app to do the migration to Pydantic v2 gradually.\n\nYou could first upgrade Pydantic to use the latest version 2, and change the imports to use `pydantic.v1` for all your models.\n\nThen, you can start migrating your models from Pydantic v1 to v2 in groups, in gradual steps. 🚶", "source_type": "doc", "path": "docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md", "symbol": "Pydantic v1 in v2 { #pydantic-v1-in-v2 }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md#L49-L153", "start_line": 49, "end_line": 153}
{"id": "docs/en/docs/how-to/separate-openapi-schemas.md::Separate OpenAPI Schemas for Input and Output or Not { #separate-openapi-schemas-for-input-and-output-or-not }::L1", "text": "# Doc: docs/en/docs/how-to/separate-openapi-schemas.md | Page: Separate OpenAPI Schemas for Input and Output or Not { #separate-openapi-schemas-for-input-and-output-or-not } | Section: Separate OpenAPI Schemas for Input and Output or Not { #separate-openapi-schemas-for-input-and-output-or-not }\n# Separate OpenAPI Schemas for Input and Output or Not { #separate-openapi-schemas-for-input-and-output-or-not }\n\nSince **Pydantic v2** was released, the generated OpenAPI is a bit more exact and **correct** than before. 😎\n\nIn fact, in some cases, it will even have **two JSON Schemas** in OpenAPI for the same Pydantic model, for input and output, depending on if they have **default values**.\n\nLet's see how that works and how to change it if you need to do that.", "source_type": "doc", "path": "docs/en/docs/how-to/separate-openapi-schemas.md", "symbol": "Separate OpenAPI Schemas for Input and Output or Not { #separate-openapi-schemas-for-input-and-output-or-not }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/how-to/separate-openapi-schemas.md#L1-L8", "start_line": 1, "end_line": 8}
{"id": "docs/en/docs/how-to/separate-openapi-schemas.md::Pydantic Models for Input and Output { #pydantic-models-for-input-and-output }::L9", "text": "# Doc: docs/en/docs/how-to/separate-openapi-schemas.md | Page: Separate OpenAPI Schemas for Input and Output or Not { #separate-openapi-schemas-for-input-and-output-or-not } | Section: Pydantic Models for Input and Output { #pydantic-models-for-input-and-output }\n## Pydantic Models for Input and Output { #pydantic-models-for-input-and-output }\n\nLet's say you have a Pydantic model with default values, like this one:\n\n{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:7] hl[7] *}\n\n### Model for Input { #model-for-input }\n\nIf you use this model as an input like here:\n\n{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:15] hl[14] *}\n\n...then the `description` field will **not be required**. Because it has a default value of `None`.\n\n### Input Model in Docs { #input-model-in-docs }\n\nYou can confirm that in the docs, the `description` field doesn't have a **red asterisk**, it's not marked as required:\n\n![](\"/img/tutorial/separate-openapi-schemas/image01.png\")
\n![](\"/img/tutorial/separate-openapi-schemas/image02.png\")
\n![](\"/img/tutorial/separate-openapi-schemas/image03.png\")
\n![](\"/img/tutorial/separate-openapi-schemas/image04.png\")
\n![](\"/img/tutorial/separate-openapi-schemas/image05.png\")
\n\n \n
\n FastAPI framework, high performance, easy to learn, fast to code, ready for production\n
\n\n\n \n\n\n \n\n\n \n\n
\"I'm using FastAPI a ton these days. I'm actually planning to use it for all of my team's ML services at Microsoft. Some of them are getting integrated into the core Windows product and some Office products.\"\n
\"We adopted the FastAPI library to spawn a REST server that can be queried to obtain predictions.\" [for Ludwig]\n
\"Netflix is pleased to announce the open-source release of our crisis management orchestration framework: Dispatch!\" [built with FastAPI]\n
\"If anyone is looking to build a production Python API, I would highly recommend FastAPI. It is beautifully designed, simple to use and highly scalable — it has become a key component in our API-first development strategy.\"\n
", "source_type": "doc", "path": "docs/en/docs/index.md", "symbol": "FastAPI Conf { #fastapi-conf }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/index.md#L154-L159", "start_line": 154, "end_line": 159}
{"id": "docs/en/docs/index.md::FastAPI mini documentary { #fastapi-mini-documentary }::L160", "text": "# Doc: docs/en/docs/index.md | Page: FastAPI { #fastapi } | Section: FastAPI mini documentary { #fastapi-mini-documentary }\n## FastAPI mini documentary { #fastapi-mini-documentary }\n\nThere's a [FastAPI mini documentary](https://www.youtube.com/watch?v=mpR8ngthqiE) released at the end of 2025, you can watch it online:\n\n", "source_type": "doc", "path": "docs/en/docs/index.md", "symbol": "FastAPI mini documentary { #fastapi-mini-documentary }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/index.md#L160-L165", "start_line": 160, "end_line": 165}
{"id": "docs/en/docs/index.md::**Typer**, the FastAPI of CLIs { #typer-the-fastapi-of-clis }::L166", "text": "# Doc: docs/en/docs/index.md | Page: FastAPI { #fastapi } | Section: **Typer**, the FastAPI of CLIs { #typer-the-fastapi-of-clis }\n## **Typer**, the FastAPI of CLIs { #typer-the-fastapi-of-clis }\n\n\n\nIf you are building a CLI app to be used in the terminal instead of a web API, check out [**Typer**](https://typer.tiangolo.com/).\n\n**Typer** is FastAPI's little sibling. And it's intended to be the **FastAPI of CLIs**. ⌨️ 🚀", "source_type": "doc", "path": "docs/en/docs/index.md", "symbol": "**Typer**, the FastAPI of CLIs { #typer-the-fastapi-of-clis }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/index.md#L166-L173", "start_line": 166, "end_line": 173}
{"id": "docs/en/docs/index.md::Requirements { #requirements }::L174", "text": "# Doc: docs/en/docs/index.md | Page: FastAPI { #fastapi } | Section: Requirements { #requirements }\n## Requirements { #requirements }\n\nFastAPI stands on the shoulders of giants:\n\n* [Starlette](https://www.starlette.dev/) for the web parts.\n* [Pydantic](https://docs.pydantic.dev/) for the data parts.", "source_type": "doc", "path": "docs/en/docs/index.md", "symbol": "Requirements { #requirements }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/index.md#L174-L180", "start_line": 174, "end_line": 180}
{"id": "docs/en/docs/index.md::Installation { #installation }::L181", "text": "# Doc: docs/en/docs/index.md | Page: FastAPI { #fastapi } | Section: Installation { #installation }\n## Installation { #installation }\n\nCreate and activate a [virtual environment](https://fastapi.tiangolo.com/virtual-environments/) and then install FastAPI:\n\nasync def...fastapi dev...![](\"/img/python-types/image01.png\")
\n\n### Add types { #add-types }\n\nLet's modify a single line from the previous version.\n\nWe will change exactly this fragment, the parameters of the function, from:\n\n```Python\n first_name, last_name\n```\n\nto:\n\n```Python\n first_name: str, last_name: str\n```\n\nThat's it.\n\nThose are the \"type hints\":\n\n{* ../../docs_src/python_types/tutorial002_py310.py hl[1] *}\n\nThat is not the same as declaring default values like it would be with:\n\n```Python\n first_name=\"john\", last_name=\"doe\"\n```\n\nIt's a different thing.\n\nWe are using colons (`:`), not equals (`=`).\n\nAnd adding type hints normally doesn't change what happens from what would happen without them.\n\nBut now, imagine you are again in the middle of creating that function, but with type hints.\n\nAt the same point, you try to trigger the autocomplete with `Ctrl+Space` and you see:\n\n![](\"/img/python-types/image02.png\")
\n\nWith that, you can scroll, seeing the options, until you find the one that \"rings a bell\":\n\n![](\"/img/python-types/image03.png\")
", "source_type": "doc", "path": "docs/en/docs/python-types.md", "symbol": "Motivation { #motivation }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/python-types.md#L21-L104", "start_line": 21, "end_line": 104}
{"id": "docs/en/docs/python-types.md::More motivation { #more-motivation }::L105", "text": "# Doc: docs/en/docs/python-types.md | Page: Python Types Intro { #python-types-intro } | Section: More motivation { #more-motivation }\n## More motivation { #more-motivation }\n\nCheck this function, it already has type hints:\n\n{* ../../docs_src/python_types/tutorial003_py310.py hl[1] *}\n\nBecause the editor knows the types of the variables, you don't only get completion, you also get error checks:\n\n![](\"/img/python-types/image04.png\")
\n\nNow you know that you have to fix it, convert `age` to a string with `str(age)`:\n\n{* ../../docs_src/python_types/tutorial004_py310.py hl[2] *}", "source_type": "doc", "path": "docs/en/docs/python-types.md", "symbol": "More motivation { #more-motivation }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/python-types.md#L105-L118", "start_line": 105, "end_line": 118}
{"id": "docs/en/docs/python-types.md::Declaring types { #declaring-types }::L119", "text": "# Doc: docs/en/docs/python-types.md | Page: Python Types Intro { #python-types-intro } | Section: Declaring types { #declaring-types }\n## Declaring types { #declaring-types }\n\nYou just saw the main place to declare type hints. As function parameters.\n\nThis is also the main place you would use them with **FastAPI**.\n\n### Simple types { #simple-types }\n\nYou can declare all the standard Python types, not only `str`.\n\nYou can use, for example:\n\n* `int`\n* `float`\n* `bool`\n* `bytes`\n\n{* ../../docs_src/python_types/tutorial005_py310.py hl[1] *}\n\n### `typing` module { #typing-module }\n\nFor some additional use cases, you might need to import some things from the standard library `typing` module, for example when you want to declare that something has \"any type\", you can use `Any` from `typing`:\n\n```python\nfrom typing import Any\n\n\ndef some_function(data: Any):\n print(data)\n```\n\n### Generic types { #generic-types }\n\nSome types can take \"type parameters\" in square brackets, to define their internal types, for example a \"list of strings\" would be declared `list[str]`.\n\nThese types that can take type parameters are called **Generic types** or **Generics**.\n\nYou can use the same builtin types as generics (with square brackets and types inside):\n\n* `list`\n* `tuple`\n* `set`\n* `dict`\n\n#### List { #list }\n\nFor example, let's define a variable to be a `list` of `str`.\n\nDeclare the variable, with the same colon (`:`) syntax.\n\nAs the type, put `list`.\n\nAs the list is a type that contains some internal types, you put them in square brackets:\n\n{* ../../docs_src/python_types/tutorial006_py310.py hl[1] *}\n\n/// note\n\nThose internal types in the square brackets are called \"type parameters\".\n\nIn this case, `str` is the type parameter passed to `list`.\n\n///\n\nThat means: \"the variable `items` is a `list`, and each of the items in this list is a `str`\".\n\nBy doing that, your editor can provide support even while processing items from the list:\n\n![](\"/img/python-types/image05.png\")
\n\nWithout types, that's almost impossible to achieve.\n\nNotice that the variable `item` is one of the elements in the list `items`.\n\nAnd still, the editor knows it is a `str`, and provides support for that.\n\n#### Tuple and Set { #tuple-and-set }\n\nYou would do the same to declare `tuple`s and `set`s:\n\n{* ../../docs_src/python_types/tutorial007_py310.py hl[1] *}\n\nThis means:\n\n* The variable `items_t` is a `tuple` with 3 items, an `int`, another `int`, and a `str`.\n* The variable `items_s` is a `set`, and each of its items is of type `bytes`.\n\n#### Dict { #dict }\n\nTo define a `dict`, you pass 2 type parameters, separated by commas.\n\nThe first type parameter is for the keys of the `dict`.\n\nThe second type parameter is for the values of the `dict`:\n\n{* ../../docs_src/python_types/tutorial008_py310.py hl[1] *}\n\nThis means:\n\n* The variable `prices` is a `dict`:\n * The keys of this `dict` are of type `str` (let's say, the name of each item).\n * The values of this `dict` are of type `float` (let's say, the price of each item).\n\n#### Union { #union }\n\nYou can declare that a variable can be any of **several types**, for example, an `int` or a `str`.\n\nTo define it you use the vertical bar (`|`) to separate both types.\n\nThis is called a \"union\", because the variable can be anything in the union of those two sets of types.\n\n```Python hl_lines=\"1\"\n{!> ../../docs_src/python_types/tutorial008b_py310.py!}\n```\n\nThis means that `item` could be an `int` or a `str`.\n\n#### Possibly `None` { #possibly-none }\n\nYou can declare that a value could have a type, like `str`, but that it could also be `None`.\n\n//// tab | Python 3.10+\n\n```Python hl_lines=\"1\"\n{!> ../../docs_src/python_types/tutorial009_py310.py!}\n```\n\n////\n\nUsing `str | None` instead of just `str` will let the editor help you detect errors where you could be assuming that a value is always a `str`, when it could actually be `None` too.\n\n### Classes as types { #classes-as-types }\n\nYou can also declare a class as the type of a variable.\n\nLet's say you have a class `Person`, with a name:\n\n{* ../../docs_src/python_types/tutorial010_py310.py hl[1:3] *}\n\nThen you can declare a variable to be of type `Person`:\n\n{* ../../docs_src/python_types/tutorial010_py310.py hl[6] *}\n\nAnd then, again, you get all the editor support:\n\n![](\"/img/python-types/image06.png\")
\n\nNotice that this means \"`one_person` is an **instance** of the class `Person`\".\n\nIt doesn't mean \"`one_person` is the **class** called `Person`\".", "source_type": "doc", "path": "docs/en/docs/python-types.md", "symbol": "Declaring types { #declaring-types }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/python-types.md#L119-L269", "start_line": 119, "end_line": 269}
{"id": "docs/en/docs/python-types.md::Pydantic models { #pydantic-models }::L270", "text": "# Doc: docs/en/docs/python-types.md | Page: Python Types Intro { #python-types-intro } | Section: Pydantic models { #pydantic-models }\n## Pydantic models { #pydantic-models }\n\n[Pydantic](https://docs.pydantic.dev/) is a Python library to perform data validation.\n\nYou declare the \"shape\" of the data as classes with attributes.\n\nAnd each attribute has a type.\n\nThen you create an instance of that class with some values and it will validate the values, convert them to the appropriate type (if that's the case) and give you an object with all the data.\n\nAnd you get all the editor support with that resulting object.\n\nAn example from the official Pydantic docs:\n\n{* ../../docs_src/python_types/tutorial011_py310.py *}\n\n/// note\n\nTo learn more about [Pydantic, check its docs](https://docs.pydantic.dev/).\n\n///\n\n**FastAPI** is all based on Pydantic.\n\nYou will see a lot more of all this in practice in the [Tutorial - User Guide](tutorial/index.md).", "source_type": "doc", "path": "docs/en/docs/python-types.md", "symbol": "Pydantic models { #pydantic-models }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/python-types.md#L270-L295", "start_line": 270, "end_line": 295}
{"id": "docs/en/docs/python-types.md::Type Hints with Metadata Annotations { #type-hints-with-metadata-annotations }::L296", "text": "# Doc: docs/en/docs/python-types.md | Page: Python Types Intro { #python-types-intro } | Section: Type Hints with Metadata Annotations { #type-hints-with-metadata-annotations }\n## Type Hints with Metadata Annotations { #type-hints-with-metadata-annotations }\n\nPython also has a feature that allows putting **additional metadata** in these type hints using `Annotated`.\n\nYou can import `Annotated` from `typing`.\n\n{* ../../docs_src/python_types/tutorial013_py310.py hl[1,4] *}\n\nPython itself doesn't do anything with this `Annotated`. And for editors and other tools, the type is still `str`.\n\nBut you can use this space in `Annotated` to provide **FastAPI** with additional metadata about how you want your application to behave.\n\nThe important thing to remember is that **the first *type parameter*** you pass to `Annotated` is the **actual type**. The rest, is just metadata for other tools.\n\nFor now, you just need to know that `Annotated` exists, and that it's standard Python. 😎\n\nLater you will see how **powerful** it can be.\n\n/// tip\n\nThe fact that this is **standard Python** means that you will still get the **best possible developer experience** in your editor, with the tools you use to analyze and refactor your code, etc. ✨\n\nAnd also that your code will be very compatible with many other Python tools and libraries. 🚀\n\n///", "source_type": "doc", "path": "docs/en/docs/python-types.md", "symbol": "Type Hints with Metadata Annotations { #type-hints-with-metadata-annotations }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/python-types.md#L296-L321", "start_line": 296, "end_line": 321}
{"id": "docs/en/docs/python-types.md::Type hints in **FastAPI** { #type-hints-in-fastapi }::L322", "text": "# Doc: docs/en/docs/python-types.md | Page: Python Types Intro { #python-types-intro } | Section: Type hints in **FastAPI** { #type-hints-in-fastapi }\n## Type hints in **FastAPI** { #type-hints-in-fastapi }\n\n**FastAPI** takes advantage of these type hints to do several things.\n\nWith **FastAPI** you declare parameters with type hints and you get:\n\n* **Editor support**.\n* **Type checks**.\n\n...and **FastAPI** uses the same declarations to:\n\n* **Define requirements**: from request path parameters, query parameters, headers, bodies, dependencies, etc.\n* **Convert data**: from the request to the required type.\n* **Validate data**: coming from each request:\n * Generating **automatic errors** returned to the client when the data is invalid.\n* **Document** the API using OpenAPI:\n * which is then used by the automatic interactive documentation user interfaces.\n\nThis might all sound abstract. Don't worry. You'll see all this in action in the [Tutorial - User Guide](tutorial/index.md).\n\nThe important thing is that by using standard Python types, in a single place (instead of adding more classes, decorators, etc), **FastAPI** will do a lot of the work for you.\n\n/// note\n\nIf you already went through all the tutorial and came back to see more about types, a good resource is [the \"cheat sheet\" from `mypy`](https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html).\n\n///", "source_type": "doc", "path": "docs/en/docs/python-types.md", "symbol": "Type hints in **FastAPI** { #type-hints-in-fastapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/python-types.md#L322-L348", "start_line": 322, "end_line": 348}
{"id": "docs/en/docs/reference/apirouter.md::`APIRouter` class::L1", "text": "# Doc: docs/en/docs/reference/apirouter.md | Page: `APIRouter` class | Section: `APIRouter` class\n# `APIRouter` class\n\nHere's the reference information for the `APIRouter` class, with all its parameters, attributes and methods.\n\nYou can import the `APIRouter` class directly from `fastapi`:\n\n```python\nfrom fastapi import APIRouter\n```\n\n::: fastapi.APIRouter\n options:\n members:\n - websocket\n - include_router\n - frontend\n - get\n - put\n - post\n - delete\n - options\n - head\n - patch\n - trace\n - on_event", "source_type": "doc", "path": "docs/en/docs/reference/apirouter.md", "symbol": "`APIRouter` class", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/apirouter.md#L1-L25", "start_line": 1, "end_line": 25}
{"id": "docs/en/docs/reference/background.md::Background Tasks - `BackgroundTasks`::L1", "text": "# Doc: docs/en/docs/reference/background.md | Page: Background Tasks - `BackgroundTasks` | Section: Background Tasks - `BackgroundTasks`\n# Background Tasks - `BackgroundTasks`\n\nYou can declare a parameter in a *path operation function* or dependency function with the type `BackgroundTasks`, and then you can use it to schedule the execution of background tasks after the response is sent.\n\nYou can import it directly from `fastapi`:\n\n```python\nfrom fastapi import BackgroundTasks\n```\n\n::: fastapi.BackgroundTasks", "source_type": "doc", "path": "docs/en/docs/reference/background.md", "symbol": "Background Tasks - `BackgroundTasks`", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/background.md#L1-L11", "start_line": 1, "end_line": 11}
{"id": "docs/en/docs/reference/dependencies.md::`Depends()`::L3", "text": "# Doc: docs/en/docs/reference/dependencies.md | Page: Dependencies - `Depends()` and `Security()` | Section: `Depends()`\n## `Depends()`\n\nDependencies are handled mainly with the special function `Depends()` that takes a callable.\n\nHere is the reference for it and its parameters.\n\nYou can import it directly from `fastapi`:\n\n```python\nfrom fastapi import Depends\n```\n\n::: fastapi.Depends", "source_type": "doc", "path": "docs/en/docs/reference/dependencies.md", "symbol": "`Depends()`", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/dependencies.md#L3-L16", "start_line": 3, "end_line": 16}
{"id": "docs/en/docs/reference/dependencies.md::`Security()`::L17", "text": "# Doc: docs/en/docs/reference/dependencies.md | Page: Dependencies - `Depends()` and `Security()` | Section: `Security()`\n## `Security()`\n\nFor many scenarios, you can handle security (authorization, authentication, etc.) with dependencies, using `Depends()`.\n\nBut when you want to also declare OAuth2 scopes, you can use `Security()` instead of `Depends()`.\n\nYou can import `Security()` directly from `fastapi`:\n\n```python\nfrom fastapi import Security\n```\n\n::: fastapi.Security", "source_type": "doc", "path": "docs/en/docs/reference/dependencies.md", "symbol": "`Security()`", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/dependencies.md#L17-L29", "start_line": 17, "end_line": 29}
{"id": "docs/en/docs/reference/encoders.md::Encoders - `jsonable_encoder`::L1", "text": "# Doc: docs/en/docs/reference/encoders.md | Page: Encoders - `jsonable_encoder` | Section: Encoders - `jsonable_encoder`\n# Encoders - `jsonable_encoder`\n\n::: fastapi.encoders.jsonable_encoder", "source_type": "doc", "path": "docs/en/docs/reference/encoders.md", "symbol": "Encoders - `jsonable_encoder`", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/encoders.md#L1-L3", "start_line": 1, "end_line": 3}
{"id": "docs/en/docs/reference/exceptions.md::Exceptions - `HTTPException` and `WebSocketException`::L1", "text": "# Doc: docs/en/docs/reference/exceptions.md | Page: Exceptions - `HTTPException` and `WebSocketException` | Section: Exceptions - `HTTPException` and `WebSocketException`\n# Exceptions - `HTTPException` and `WebSocketException`\n\nThese are the exceptions that you can raise to show errors to the client.\n\nWhen you raise an exception, as would happen with normal Python, the rest of the execution is aborted. This way you can raise these exceptions from anywhere in the code to abort a request and show the error to the client.\n\nYou can use:\n\n* `HTTPException`\n* `WebSocketException`\n\nThese exceptions can be imported directly from `fastapi`:\n\n```python\nfrom fastapi import HTTPException, WebSocketException\n```\n\n::: fastapi.HTTPException\n\n::: fastapi.WebSocketException", "source_type": "doc", "path": "docs/en/docs/reference/exceptions.md", "symbol": "Exceptions - `HTTPException` and `WebSocketException`", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/exceptions.md#L1-L20", "start_line": 1, "end_line": 20}
{"id": "docs/en/docs/reference/fastapi.md::`FastAPI` class::L1", "text": "# Doc: docs/en/docs/reference/fastapi.md | Page: `FastAPI` class | Section: `FastAPI` class\n# `FastAPI` class\n\nHere's the reference information for the `FastAPI` class, with all its parameters, attributes and methods.\n\nYou can import the `FastAPI` class directly from `fastapi`:\n\n```python\nfrom fastapi import FastAPI\n```\n\n::: fastapi.FastAPI\n options:\n members:\n - openapi_version\n - webhooks\n - state\n - dependency_overrides\n - openapi\n - websocket\n - include_router\n - frontend\n - get\n - put\n - post\n - delete\n - options\n - head\n - patch\n - trace\n - on_event\n - middleware\n - exception_handler", "source_type": "doc", "path": "docs/en/docs/reference/fastapi.md", "symbol": "`FastAPI` class", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/fastapi.md#L1-L32", "start_line": 1, "end_line": 32}
{"id": "docs/en/docs/reference/httpconnection.md::`HTTPConnection` class::L1", "text": "# Doc: docs/en/docs/reference/httpconnection.md | Page: `HTTPConnection` class | Section: `HTTPConnection` class\n# `HTTPConnection` class\n\nWhen you want to define dependencies that should be compatible with both HTTP and WebSockets, you can define a parameter that takes an `HTTPConnection` instead of a `Request` or a `WebSocket`.\n\nYou can import it from `fastapi.requests`:\n\n```python\nfrom fastapi.requests import HTTPConnection\n```\n\n::: fastapi.requests.HTTPConnection", "source_type": "doc", "path": "docs/en/docs/reference/httpconnection.md", "symbol": "`HTTPConnection` class", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/httpconnection.md#L1-L11", "start_line": 1, "end_line": 11}
{"id": "docs/en/docs/reference/index.md::Reference::L1", "text": "# Doc: docs/en/docs/reference/index.md | Page: Reference | Section: Reference\n# Reference\n\nHere's the reference or code API, the classes, functions, parameters, attributes, and\nall the FastAPI parts you can use in your applications.\n\nIf you want to **learn FastAPI** you are much better off reading the\n[FastAPI Tutorial](https://fastapi.tiangolo.com/tutorial/).", "source_type": "doc", "path": "docs/en/docs/reference/index.md", "symbol": "Reference", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/index.md#L1-L7", "start_line": 1, "end_line": 7}
{"id": "docs/en/docs/reference/middleware.md::Middleware::L1", "text": "# Doc: docs/en/docs/reference/middleware.md | Page: Middleware | Section: Middleware\n# Middleware\n\nThere are several middlewares available provided by Starlette directly.\n\nRead more about them in the [FastAPI docs for Middleware](https://fastapi.tiangolo.com/advanced/middleware/).\n\n::: fastapi.middleware.cors.CORSMiddleware\n\nIt can be imported from `fastapi`:\n\n```python\nfrom fastapi.middleware.cors import CORSMiddleware\n```\n\n::: fastapi.middleware.gzip.GZipMiddleware\n\nIt can be imported from `fastapi`:\n\n```python\nfrom fastapi.middleware.gzip import GZipMiddleware\n```\n\n::: fastapi.middleware.httpsredirect.HTTPSRedirectMiddleware\n\nIt can be imported from `fastapi`:\n\n```python\nfrom fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware\n```\n\n::: fastapi.middleware.trustedhost.TrustedHostMiddleware\n\nIt can be imported from `fastapi`:\n\n```python\nfrom fastapi.middleware.trustedhost import TrustedHostMiddleware\n```", "source_type": "doc", "path": "docs/en/docs/reference/middleware.md", "symbol": "Middleware", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/middleware.md#L1-L37", "start_line": 1, "end_line": 37}
{"id": "docs/en/docs/reference/openapi/docs.md::OpenAPI `docs`::L1", "text": "# Doc: docs/en/docs/reference/openapi/docs.md | Page: OpenAPI `docs` | Section: OpenAPI `docs`\n# OpenAPI `docs`\n\nUtilities to handle OpenAPI automatic UI documentation, including Swagger UI (by default at `/docs`) and ReDoc (by default at `/redoc`).\n\n::: fastapi.openapi.docs.get_swagger_ui_html\n\n::: fastapi.openapi.docs.get_redoc_html\n\n::: fastapi.openapi.docs.get_swagger_ui_oauth2_redirect_html\n\n::: fastapi.openapi.docs.swagger_ui_default_parameters", "source_type": "doc", "path": "docs/en/docs/reference/openapi/docs.md", "symbol": "OpenAPI `docs`", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/openapi/docs.md#L1-L11", "start_line": 1, "end_line": 11}
{"id": "docs/en/docs/reference/openapi/index.md::OpenAPI::L1", "text": "# Doc: docs/en/docs/reference/openapi/index.md | Page: OpenAPI | Section: OpenAPI\n# OpenAPI\n\nThere are several utilities to handle OpenAPI.\n\nYou normally don't need to use them unless you have a specific advanced use case that requires it.", "source_type": "doc", "path": "docs/en/docs/reference/openapi/index.md", "symbol": "OpenAPI", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/openapi/index.md#L1-L5", "start_line": 1, "end_line": 5}
{"id": "docs/en/docs/reference/openapi/models.md::OpenAPI `models`::L1", "text": "# Doc: docs/en/docs/reference/openapi/models.md | Page: OpenAPI `models` | Section: OpenAPI `models`\n# OpenAPI `models`\n\nOpenAPI Pydantic models used to generate and validate the generated OpenAPI.\n\n::: fastapi.openapi.models", "source_type": "doc", "path": "docs/en/docs/reference/openapi/models.md", "symbol": "OpenAPI `models`", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/openapi/models.md#L1-L5", "start_line": 1, "end_line": 5}
{"id": "docs/en/docs/reference/parameters.md::Request Parameters::L1", "text": "# Doc: docs/en/docs/reference/parameters.md | Page: Request Parameters | Section: Request Parameters\n# Request Parameters\n\nHere's the reference information for the request parameters.\n\nThese are the special functions that you can put in *path operation function* parameters or dependency functions with `Annotated` to get data from the request.\n\nIt includes:\n\n* `Query()`\n* `Path()`\n* `Body()`\n* `Cookie()`\n* `Header()`\n* `Form()`\n* `File()`\n\nYou can import them all directly from `fastapi`:\n\n```python\nfrom fastapi import Body, Cookie, File, Form, Header, Path, Query\n```\n\n::: fastapi.Query\n\n::: fastapi.Path\n\n::: fastapi.Body\n\n::: fastapi.Cookie\n\n::: fastapi.Header\n\n::: fastapi.Form\n\n::: fastapi.File", "source_type": "doc", "path": "docs/en/docs/reference/parameters.md", "symbol": "Request Parameters", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/parameters.md#L1-L35", "start_line": 1, "end_line": 35}
{"id": "docs/en/docs/reference/request.md::`Request` class::L1", "text": "# Doc: docs/en/docs/reference/request.md | Page: `Request` class | Section: `Request` class\n# `Request` class\n\nYou can declare a parameter in a *path operation function* or dependency to be of type `Request` and then you can access the raw request object directly, without any validation, etc.\n\nRead more about it in the [FastAPI docs about using Request directly](https://fastapi.tiangolo.com/advanced/using-request-directly/)\n\nYou can import it directly from `fastapi`:\n\n```python\nfrom fastapi import Request\n```\n\n/// tip\n\nWhen you want to define dependencies that should be compatible with both HTTP and WebSockets, you can define a parameter that takes an `HTTPConnection` instead of a `Request` or a `WebSocket`.\n\n///\n\n::: fastapi.Request", "source_type": "doc", "path": "docs/en/docs/reference/request.md", "symbol": "`Request` class", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/request.md#L1-L19", "start_line": 1, "end_line": 19}
{"id": "docs/en/docs/reference/response.md::`Response` class::L1", "text": "# Doc: docs/en/docs/reference/response.md | Page: `Response` class | Section: `Response` class\n# `Response` class\n\nYou can declare a parameter in a *path operation function* or dependency to be of type `Response` and then you can set data for the response like headers or cookies.\n\nYou can also use it directly to create an instance of it and return it from your *path operations*.\n\nRead more about it in the [FastAPI docs about returning a custom Response](https://fastapi.tiangolo.com/advanced/response-directly/#returning-a-custom-response)\n\nYou can import it directly from `fastapi`:\n\n```python\nfrom fastapi import Response\n```\n\n::: fastapi.Response", "source_type": "doc", "path": "docs/en/docs/reference/response.md", "symbol": "`Response` class", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/response.md#L1-L15", "start_line": 1, "end_line": 15}
{"id": "docs/en/docs/reference/responses.md::Custom Response Classes - File, HTML, Redirect, Streaming, etc.::L1", "text": "# Doc: docs/en/docs/reference/responses.md | Page: Custom Response Classes - File, HTML, Redirect, Streaming, etc. | Section: Custom Response Classes - File, HTML, Redirect, Streaming, etc.\n# Custom Response Classes - File, HTML, Redirect, Streaming, etc.\n\nThere are several custom response classes you can use to create an instance and return them directly from your *path operations*.\n\nRead more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/).\n\nYou can import them directly from `fastapi.responses`:\n\n```python\nfrom fastapi.responses import (\n FileResponse,\n HTMLResponse,\n JSONResponse,\n ORJSONResponse,\n PlainTextResponse,\n RedirectResponse,\n Response,\n StreamingResponse,\n UJSONResponse,\n)\n```", "source_type": "doc", "path": "docs/en/docs/reference/responses.md", "symbol": "Custom Response Classes - File, HTML, Redirect, Streaming, etc.", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/responses.md#L1-L22", "start_line": 1, "end_line": 22}
{"id": "docs/en/docs/reference/responses.md::FastAPI Responses::L23", "text": "# Doc: docs/en/docs/reference/responses.md | Page: Custom Response Classes - File, HTML, Redirect, Streaming, etc. | Section: FastAPI Responses\n## FastAPI Responses\n\nThere were a couple of custom FastAPI response classes that were intended to optimize JSON performance.\n\nHowever, they are now deprecated as you will now get better performance by using a [Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/).\n\nThat way, Pydantic will serialize the data into JSON bytes on the Rust side, which will achieve better performance than these custom JSON responses.\n\nRead more about it in [Custom Response - HTML, Stream, File, others - `orjson` or Response Model](https://fastapi.tiangolo.com/advanced/custom-response/#orjson-or-response-model).\n\n::: fastapi.responses.UJSONResponse\n options:\n members:\n - charset\n - status_code\n - media_type\n - body\n - background\n - raw_headers\n - render\n - init_headers\n - headers\n - set_cookie\n - delete_cookie\n\n::: fastapi.responses.ORJSONResponse\n options:\n members:\n - charset\n - status_code\n - media_type\n - body\n - background\n - raw_headers\n - render\n - init_headers\n - headers\n - set_cookie\n - delete_cookie", "source_type": "doc", "path": "docs/en/docs/reference/responses.md", "symbol": "FastAPI Responses", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/responses.md#L23-L62", "start_line": 23, "end_line": 62}
{"id": "docs/en/docs/reference/responses.md::Starlette Responses::L63", "text": "# Doc: docs/en/docs/reference/responses.md | Page: Custom Response Classes - File, HTML, Redirect, Streaming, etc. | Section: Starlette Responses\n## Starlette Responses\n\nYou can read more about all of them in the [FastAPI docs for Custom Response](https://fastapi.tiangolo.com/advanced/custom-response/) and in the [Starlette docs about Responses](https://starlette.dev/responses/).\n\n::: fastapi.responses.FileResponse\n options:\n members:\n - chunk_size\n - charset\n - status_code\n - media_type\n - body\n - background\n - raw_headers\n - render\n - init_headers\n - headers\n - set_cookie\n - delete_cookie\n\n::: fastapi.responses.HTMLResponse\n options:\n members:\n - charset\n - status_code\n - media_type\n - body\n - background\n - raw_headers\n - render\n - init_headers\n - headers\n - set_cookie\n - delete_cookie\n\n::: fastapi.responses.JSONResponse\n options:\n members:\n - charset\n - status_code\n - media_type\n - body\n - background\n - raw_headers\n - render\n - init_headers\n - headers\n - set_cookie\n - delete_cookie\n\n::: fastapi.responses.PlainTextResponse\n options:\n members:\n - charset\n - status_code\n - media_type\n - body\n - background\n - raw_headers\n - render\n - init_headers\n - headers\n - set_cookie\n - delete_cookie\n\n::: fastapi.responses.RedirectResponse\n options:\n members:\n - charset\n - status_code\n - media_type\n - body\n - background\n - raw_headers\n - render\n - init_headers\n - headers\n - set_cookie\n - delete_cookie\n\n::: fastapi.responses.Response\n options:\n members:\n - charset\n - status_code\n - media_type\n - body\n - background\n - raw_headers\n - render\n - init_headers\n - headers\n - set_cookie\n - delete_cookie\n\n::: fastapi.responses.StreamingResponse\n options:\n members:\n - body_iterator\n - charset\n - status_code\n - media_type\n - body\n - background\n - raw_headers\n - render\n - init_headers\n - headers\n - set_cookie\n - delete_cookie", "source_type": "doc", "path": "docs/en/docs/reference/responses.md", "symbol": "Starlette Responses", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/responses.md#L63-L172", "start_line": 63, "end_line": 172}
{"id": "docs/en/docs/reference/security/index.md::Security Tools::L1", "text": "# Doc: docs/en/docs/reference/security/index.md | Page: Security Tools | Section: Security Tools\n# Security Tools\n\nWhen you need to declare dependencies with OAuth2 scopes you use `Security()`.\n\nBut you still need to define what is the dependable, the callable that you pass as a parameter to `Depends()` or `Security()`.\n\nThere are multiple tools that you can use to create those dependables, and they get integrated into OpenAPI so they are shown in the automatic docs UI, they can be used by automatically generated clients and SDKs, etc.\n\nYou can import them from `fastapi.security`:\n\n```python\nfrom fastapi.security import (\n APIKeyCookie,\n APIKeyHeader,\n APIKeyQuery,\n HTTPAuthorizationCredentials,\n HTTPBasic,\n HTTPBasicCredentials,\n HTTPBearer,\n HTTPDigest,\n OAuth2,\n OAuth2AuthorizationCodeBearer,\n OAuth2PasswordBearer,\n OAuth2PasswordRequestForm,\n OAuth2PasswordRequestFormStrict,\n OpenIdConnect,\n SecurityScopes,\n)\n```\n\nRead more about them in the [FastAPI docs about Security](https://fastapi.tiangolo.com/tutorial/security/).", "source_type": "doc", "path": "docs/en/docs/reference/security/index.md", "symbol": "Security Tools", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/security/index.md#L1-L32", "start_line": 1, "end_line": 32}
{"id": "docs/en/docs/reference/security/index.md::API Key Security Schemes::L33", "text": "# Doc: docs/en/docs/reference/security/index.md | Page: Security Tools | Section: API Key Security Schemes\n## API Key Security Schemes\n\n::: fastapi.security.APIKeyCookie\n\n::: fastapi.security.APIKeyHeader\n\n::: fastapi.security.APIKeyQuery", "source_type": "doc", "path": "docs/en/docs/reference/security/index.md", "symbol": "API Key Security Schemes", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/security/index.md#L33-L40", "start_line": 33, "end_line": 40}
{"id": "docs/en/docs/reference/security/index.md::HTTP Authentication Schemes::L41", "text": "# Doc: docs/en/docs/reference/security/index.md | Page: Security Tools | Section: HTTP Authentication Schemes\n## HTTP Authentication Schemes\n\n::: fastapi.security.HTTPBasic\n\n::: fastapi.security.HTTPBearer\n\n::: fastapi.security.HTTPDigest", "source_type": "doc", "path": "docs/en/docs/reference/security/index.md", "symbol": "HTTP Authentication Schemes", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/security/index.md#L41-L48", "start_line": 41, "end_line": 48}
{"id": "docs/en/docs/reference/security/index.md::HTTP Credentials::L49", "text": "# Doc: docs/en/docs/reference/security/index.md | Page: Security Tools | Section: HTTP Credentials\n## HTTP Credentials\n\n::: fastapi.security.HTTPAuthorizationCredentials\n\n::: fastapi.security.HTTPBasicCredentials", "source_type": "doc", "path": "docs/en/docs/reference/security/index.md", "symbol": "HTTP Credentials", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/security/index.md#L49-L54", "start_line": 49, "end_line": 54}
{"id": "docs/en/docs/reference/security/index.md::OAuth2 Authentication::L55", "text": "# Doc: docs/en/docs/reference/security/index.md | Page: Security Tools | Section: OAuth2 Authentication\n## OAuth2 Authentication\n\n::: fastapi.security.OAuth2\n\n::: fastapi.security.OAuth2AuthorizationCodeBearer\n\n::: fastapi.security.OAuth2PasswordBearer", "source_type": "doc", "path": "docs/en/docs/reference/security/index.md", "symbol": "OAuth2 Authentication", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/security/index.md#L55-L62", "start_line": 55, "end_line": 62}
{"id": "docs/en/docs/reference/security/index.md::OAuth2 Password Form::L63", "text": "# Doc: docs/en/docs/reference/security/index.md | Page: Security Tools | Section: OAuth2 Password Form\n## OAuth2 Password Form\n\n::: fastapi.security.OAuth2PasswordRequestForm\n\n::: fastapi.security.OAuth2PasswordRequestFormStrict", "source_type": "doc", "path": "docs/en/docs/reference/security/index.md", "symbol": "OAuth2 Password Form", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/security/index.md#L63-L68", "start_line": 63, "end_line": 68}
{"id": "docs/en/docs/reference/security/index.md::OAuth2 Security Scopes in Dependencies::L69", "text": "# Doc: docs/en/docs/reference/security/index.md | Page: Security Tools | Section: OAuth2 Security Scopes in Dependencies\n## OAuth2 Security Scopes in Dependencies\n\n::: fastapi.security.SecurityScopes", "source_type": "doc", "path": "docs/en/docs/reference/security/index.md", "symbol": "OAuth2 Security Scopes in Dependencies", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/security/index.md#L69-L72", "start_line": 69, "end_line": 72}
{"id": "docs/en/docs/reference/security/index.md::OpenID Connect::L73", "text": "# Doc: docs/en/docs/reference/security/index.md | Page: Security Tools | Section: OpenID Connect\n## OpenID Connect\n\n::: fastapi.security.OpenIdConnect", "source_type": "doc", "path": "docs/en/docs/reference/security/index.md", "symbol": "OpenID Connect", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/security/index.md#L73-L75", "start_line": 73, "end_line": 75}
{"id": "docs/en/docs/reference/staticfiles.md::Static Files - `StaticFiles`::L1", "text": "# Doc: docs/en/docs/reference/staticfiles.md | Page: Static Files - `StaticFiles` | Section: Static Files - `StaticFiles`\n# Static Files - `StaticFiles`\n\nYou can use the `StaticFiles` class to serve static files, like JavaScript, CSS, images, etc.\n\nRead more about it in the [FastAPI docs for Static Files](https://fastapi.tiangolo.com/tutorial/static-files/).\n\nYou can import it directly from `fastapi.staticfiles`:\n\n```python\nfrom fastapi.staticfiles import StaticFiles\n```\n\n::: fastapi.staticfiles.StaticFiles", "source_type": "doc", "path": "docs/en/docs/reference/staticfiles.md", "symbol": "Static Files - `StaticFiles`", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/staticfiles.md#L1-L13", "start_line": 1, "end_line": 13}
{"id": "docs/en/docs/reference/status.md::Status Codes::L1", "text": "# Doc: docs/en/docs/reference/status.md | Page: Status Codes | Section: Status Codes\n# Status Codes\n\nYou can import the `status` module from `fastapi`:\n\n```python\nfrom fastapi import status\n```\n\n`status` is provided directly by Starlette.\n\nIt contains a group of named constants (variables) with integer status codes.\n\nFor example:\n\n* 200: `status.HTTP_200_OK`\n* 403: `status.HTTP_403_FORBIDDEN`\n* etc.\n\nIt can be convenient to quickly access HTTP (and WebSocket) status codes in your app, using autocompletion for the name without having to memorize the integer status codes.\n\nRead more about it in the [FastAPI docs about Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).", "source_type": "doc", "path": "docs/en/docs/reference/status.md", "symbol": "Status Codes", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/status.md#L1-L22", "start_line": 1, "end_line": 22}
{"id": "docs/en/docs/reference/status.md::Example::L23", "text": "# Doc: docs/en/docs/reference/status.md | Page: Status Codes | Section: Example\n## Example\n\n```python\nfrom fastapi import FastAPI, status\n\napp = FastAPI()\n\n\n@app.get(\"/items/\", status_code=status.HTTP_418_IM_A_TEAPOT)\ndef read_items():\n return [{\"name\": \"Plumbus\"}, {\"name\": \"Portal Gun\"}]\n```\n\n::: fastapi.status", "source_type": "doc", "path": "docs/en/docs/reference/status.md", "symbol": "Example", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/status.md#L23-L36", "start_line": 23, "end_line": 36}
{"id": "docs/en/docs/reference/templating.md::Templating - `Jinja2Templates`::L1", "text": "# Doc: docs/en/docs/reference/templating.md | Page: Templating - `Jinja2Templates` | Section: Templating - `Jinja2Templates`\n# Templating - `Jinja2Templates`\n\nYou can use the `Jinja2Templates` class to render Jinja templates.\n\nRead more about it in the [FastAPI docs for Templates](https://fastapi.tiangolo.com/advanced/templates/).\n\nYou can import it directly from `fastapi.templating`:\n\n```python\nfrom fastapi.templating import Jinja2Templates\n```\n\n::: fastapi.templating.Jinja2Templates", "source_type": "doc", "path": "docs/en/docs/reference/templating.md", "symbol": "Templating - `Jinja2Templates`", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/templating.md#L1-L13", "start_line": 1, "end_line": 13}
{"id": "docs/en/docs/reference/testclient.md::Test Client - `TestClient`::L1", "text": "# Doc: docs/en/docs/reference/testclient.md | Page: Test Client - `TestClient` | Section: Test Client - `TestClient`\n# Test Client - `TestClient`\n\nYou can use the `TestClient` class to test FastAPI applications without creating an actual HTTP and socket connection, just communicating directly with the FastAPI code.\n\nRead more about it in the [FastAPI docs for Testing](https://fastapi.tiangolo.com/tutorial/testing/).\n\nYou can import it directly from `fastapi.testclient`:\n\n```python\nfrom fastapi.testclient import TestClient\n```\n\n::: fastapi.testclient.TestClient", "source_type": "doc", "path": "docs/en/docs/reference/testclient.md", "symbol": "Test Client - `TestClient`", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/testclient.md#L1-L13", "start_line": 1, "end_line": 13}
{"id": "docs/en/docs/reference/uploadfile.md::`UploadFile` class::L1", "text": "# Doc: docs/en/docs/reference/uploadfile.md | Page: `UploadFile` class | Section: `UploadFile` class\n# `UploadFile` class\n\nYou can define *path operation function* parameters to be of the type `UploadFile` to receive files from the request.\n\nYou can import it directly from `fastapi`:\n\n```python\nfrom fastapi import UploadFile\n```\n\n::: fastapi.UploadFile\n options:\n members:\n - file\n - filename\n - size\n - headers\n - content_type\n - read\n - write\n - seek\n - close", "source_type": "doc", "path": "docs/en/docs/reference/uploadfile.md", "symbol": "`UploadFile` class", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/uploadfile.md#L1-L22", "start_line": 1, "end_line": 22}
{"id": "docs/en/docs/reference/websockets.md::WebSockets::L1", "text": "# Doc: docs/en/docs/reference/websockets.md | Page: WebSockets | Section: WebSockets\n# WebSockets\n\nWhen defining WebSockets, you normally declare a parameter of type `WebSocket` and with it you can read data from the client and send data to it.\n\nRead more about it in the [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/)\n\nIt is provided directly by Starlette, but you can import it from `fastapi`:\n\n```python\nfrom fastapi import WebSocket\n```\n\n/// tip\n\nWhen you want to define dependencies that should be compatible with both HTTP and WebSockets, you can define a parameter that takes an `HTTPConnection` instead of a `Request` or a `WebSocket`.\n\n///\n\n::: fastapi.WebSocket\n options:\n members:\n - scope\n - app\n - url\n - base_url\n - headers\n - query_params\n - path_params\n - cookies\n - client\n - state\n - url_for\n - client_state\n - application_state\n - receive\n - send\n - accept\n - receive_text\n - receive_bytes\n - receive_json\n - iter_text\n - iter_bytes\n - iter_json\n - send_text\n - send_bytes\n - send_json\n - close", "source_type": "doc", "path": "docs/en/docs/reference/websockets.md", "symbol": "WebSockets", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/websockets.md#L1-L48", "start_line": 1, "end_line": 48}
{"id": "docs/en/docs/reference/websockets.md::WebSockets - additional classes::L49", "text": "# Doc: docs/en/docs/reference/websockets.md | Page: WebSockets | Section: WebSockets - additional classes\n## WebSockets - additional classes\n\nAdditional classes for handling WebSockets.\n\nProvided directly by Starlette, but you can import them from `fastapi`:\n\n```python\nfrom fastapi.websockets import WebSocketDisconnect, WebSocketState\n```\n\n::: fastapi.websockets.WebSocketDisconnect\n\nWhen a client disconnects, a `WebSocketDisconnect` exception is raised, you can catch it.\n\nYou can import it directly from `fastapi`:\n\n```python\nfrom fastapi import WebSocketDisconnect\n```\n\nRead more about it in the [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/#handling-disconnections-and-multiple-clients)\n\n::: fastapi.websockets.WebSocketState\n\n`WebSocketState` is an enumeration of the possible states of a WebSocket connection.", "source_type": "doc", "path": "docs/en/docs/reference/websockets.md", "symbol": "WebSockets - additional classes", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/reference/websockets.md#L49-L73", "start_line": 49, "end_line": 73}
{"id": "docs/en/docs/resources/index.md::Resources { #resources }::L1", "text": "# Doc: docs/en/docs/resources/index.md | Page: Resources { #resources } | Section: Resources { #resources }\n# Resources { #resources }\n\nAdditional resources, external links, and more. ✈️", "source_type": "doc", "path": "docs/en/docs/resources/index.md", "symbol": "Resources { #resources }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/resources/index.md#L1-L3", "start_line": 1, "end_line": 3}
{"id": "docs/en/docs/translation-banner.md::docs/en/docs/translation-banner.md::L1", "text": "# Doc: docs/en/docs/translation-banner.md | Page: docs/en/docs/translation-banner.md | Section: docs/en/docs/translation-banner.md\n/// details | 🌐 Translation by AI and humans\n\nThis translation was made by AI guided by humans. 🤝\n\nIt could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🤖\n\nYou can improve this translation by [helping us guide the AI LLM better](https://fastapi.tiangolo.com/contributing/#translations).\n\n[English version](ENGLISH_VERSION_URL)\n\n///", "source_type": "doc", "path": "docs/en/docs/translation-banner.md", "symbol": "docs/en/docs/translation-banner.md", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/translation-banner.md#L1-L11", "start_line": 1, "end_line": 11}
{"id": "docs/en/docs/translations.md::Translations::L1", "text": "# Doc: docs/en/docs/translations.md | Page: Translations | Section: Translations\n# Translations\n\nTranslation pull requests are made by LLMs guided with prompts designed by the FastAPI team together with the community of native speakers for each supported language.", "source_type": "doc", "path": "docs/en/docs/translations.md", "symbol": "Translations", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/translations.md#L1-L4", "start_line": 1, "end_line": 4}
{"id": "docs/en/docs/translations.md::LLM Prompt per Language::L5", "text": "# Doc: docs/en/docs/translations.md | Page: Translations | Section: LLM Prompt per Language\n## LLM Prompt per Language\n\nEach language has a directory: [https://github.com/fastapi/fastapi/tree/master/docs](https://github.com/fastapi/fastapi/tree/master/docs), in it you can see a file `llm-prompt.md` with the prompt specific for that language.\n\nFor example, for Spanish, the prompt is at: [`docs/es/llm-prompt.md`](https://github.com/fastapi/fastapi/blob/master/docs/es/llm-prompt.md).\n\nIf you see mistakes in your language, you can make suggestions to the prompt in that file for your language, and request the specific pages you would like to re-generate after the changes.\n\nPRs with suggestions to the language-specific LLM prompt require approval from at least one native speaker. Your help here is very much appreciated!", "source_type": "doc", "path": "docs/en/docs/translations.md", "symbol": "LLM Prompt per Language", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/translations.md#L5-L14", "start_line": 5, "end_line": 14}
{"id": "docs/en/docs/translations.md::Request a New Language::L15", "text": "# Doc: docs/en/docs/translations.md | Page: Translations | Section: Request a New Language\n## Request a New Language\n\nLet's say that you want to request translations for a language that is not yet translated, not even some pages. For example, Latin.\n\n* The first step would be for you to find 2 other people who would be willing to be reviewing translation PRs for that language with you.\n* Once there are at least 3 people that would be willing to commit to help maintain that language, you can continue the next steps.\n* Create a new discussion following the template.\n* Tag the other 2 people that will help with the language, and ask them to confirm in the comments that they will help.\n\nOnce there are several people in the discussion, the FastAPI team can evaluate it and can make it an official translation.\n\nThen the docs will be automatically translated using LLMs, and the team of native speakers can review the translation, and help tweak the LLM prompts.\n\nOnce there's a new translation, for example if docs are updated or there's a new section, there will be a comment in the same discussion with the link to the new translation to review.", "source_type": "doc", "path": "docs/en/docs/translations.md", "symbol": "Request a New Language", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/translations.md#L15-L28", "start_line": 15, "end_line": 28}
{"id": "docs/en/docs/tutorial/background-tasks.md::Background Tasks { #background-tasks }::L1", "text": "# Doc: docs/en/docs/tutorial/background-tasks.md | Page: Background Tasks { #background-tasks } | Section: Background Tasks { #background-tasks }\n# Background Tasks { #background-tasks }\n\nYou can define background tasks to be run *after* returning a response.\n\nThis is useful for operations that need to happen after a request, but that the client doesn't really have to be waiting for the operation to complete before receiving the response.\n\nThis includes, for example:\n\n* Email notifications sent after performing an action:\n * As connecting to an email server and sending an email tends to be \"slow\" (several seconds), you can return the response right away and send the email notification in the background.\n* Processing data:\n * For example, let's say you receive a file that must go through a slow process, you can return a response of \"Accepted\" (HTTP 202) and process the file in the background.", "source_type": "doc", "path": "docs/en/docs/tutorial/background-tasks.md", "symbol": "Background Tasks { #background-tasks }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/background-tasks.md#L1-L13", "start_line": 1, "end_line": 13}
{"id": "docs/en/docs/tutorial/background-tasks.md::Using `BackgroundTasks` { #using-backgroundtasks }::L14", "text": "# Doc: docs/en/docs/tutorial/background-tasks.md | Page: Background Tasks { #background-tasks } | Section: Using `BackgroundTasks` { #using-backgroundtasks }\n## Using `BackgroundTasks` { #using-backgroundtasks }\n\nFirst, import `BackgroundTasks` and define a parameter in your *path operation function* with a type declaration of `BackgroundTasks`:\n\n{* ../../docs_src/background_tasks/tutorial001_py310.py hl[1,13] *}\n\n**FastAPI** will create the object of type `BackgroundTasks` for you and pass it as that parameter.", "source_type": "doc", "path": "docs/en/docs/tutorial/background-tasks.md", "symbol": "Using `BackgroundTasks` { #using-backgroundtasks }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/background-tasks.md#L14-L21", "start_line": 14, "end_line": 21}
{"id": "docs/en/docs/tutorial/background-tasks.md::Create a task function { #create-a-task-function }::L22", "text": "# Doc: docs/en/docs/tutorial/background-tasks.md | Page: Background Tasks { #background-tasks } | Section: Create a task function { #create-a-task-function }\n## Create a task function { #create-a-task-function }\n\nCreate a function to be run as the background task.\n\nIt is just a standard function that can receive parameters.\n\nIt can be an `async def` or normal `def` function, **FastAPI** will know how to handle it correctly.\n\nIn this case, the task function will write to a file (simulating sending an email).\n\nAnd as the write operation doesn't use `async` and `await`, we define the function with normal `def`:\n\n{* ../../docs_src/background_tasks/tutorial001_py310.py hl[6:9] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/background-tasks.md", "symbol": "Create a task function { #create-a-task-function }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/background-tasks.md#L22-L35", "start_line": 22, "end_line": 35}
{"id": "docs/en/docs/tutorial/background-tasks.md::Add the background task { #add-the-background-task }::L36", "text": "# Doc: docs/en/docs/tutorial/background-tasks.md | Page: Background Tasks { #background-tasks } | Section: Add the background task { #add-the-background-task }\n## Add the background task { #add-the-background-task }\n\nInside of your *path operation function*, pass your task function to the *background tasks* object with the method `.add_task()`:\n\n{* ../../docs_src/background_tasks/tutorial001_py310.py hl[14] *}\n\n`.add_task()` receives as arguments:\n\n* A task function to be run in the background (`write_notification`).\n* Any sequence of arguments that should be passed to the task function in order (`email`).\n* Any keyword arguments that should be passed to the task function (`message=\"some notification\"`).", "source_type": "doc", "path": "docs/en/docs/tutorial/background-tasks.md", "symbol": "Add the background task { #add-the-background-task }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/background-tasks.md#L36-L47", "start_line": 36, "end_line": 47}
{"id": "docs/en/docs/tutorial/background-tasks.md::Dependency Injection { #dependency-injection }::L48", "text": "# Doc: docs/en/docs/tutorial/background-tasks.md | Page: Background Tasks { #background-tasks } | Section: Dependency Injection { #dependency-injection }\n## Dependency Injection { #dependency-injection }\n\nUsing `BackgroundTasks` also works with the dependency injection system, you can declare a parameter of type `BackgroundTasks` at multiple levels: in a *path operation function*, in a dependency (dependable), in a sub-dependency, etc.\n\n**FastAPI** knows what to do in each case and how to reuse the same object, so that all the background tasks are merged together and are run in the background afterwards:\n\n\n{* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *}\n\n\nIn this example, the messages will be written to the `log.txt` file *after* the response is sent.\n\nIf there was a query in the request, it will be written to the log in a background task.\n\nAnd then another background task generated at the *path operation function* will write a message using the `email` path parameter.", "source_type": "doc", "path": "docs/en/docs/tutorial/background-tasks.md", "symbol": "Dependency Injection { #dependency-injection }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/background-tasks.md#L48-L63", "start_line": 48, "end_line": 63}
{"id": "docs/en/docs/tutorial/background-tasks.md::Technical Details { #technical-details }::L64", "text": "# Doc: docs/en/docs/tutorial/background-tasks.md | Page: Background Tasks { #background-tasks } | Section: Technical Details { #technical-details }\n## Technical Details { #technical-details }\n\nThe class `BackgroundTasks` comes directly from [`starlette.background`](https://www.starlette.dev/background/).\n\nIt is imported/included directly into FastAPI so that you can import it from `fastapi` and avoid accidentally importing the alternative `BackgroundTask` (without the `s` at the end) from `starlette.background`.\n\nBy only using `BackgroundTasks` (and not `BackgroundTask`), it's then possible to use it as a *path operation function* parameter and have **FastAPI** handle the rest for you, just like when using the `Request` object directly.\n\nIt's still possible to use `BackgroundTask` alone in FastAPI, but you have to create the object in your code and return a Starlette `Response` including it.\n\nYou can see more details in [Starlette's official docs for Background Tasks](https://www.starlette.dev/background/).", "source_type": "doc", "path": "docs/en/docs/tutorial/background-tasks.md", "symbol": "Technical Details { #technical-details }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/background-tasks.md#L64-L75", "start_line": 64, "end_line": 75}
{"id": "docs/en/docs/tutorial/background-tasks.md::Caveat { #caveat }::L76", "text": "# Doc: docs/en/docs/tutorial/background-tasks.md | Page: Background Tasks { #background-tasks } | Section: Caveat { #caveat }\n## Caveat { #caveat }\n\nIf you need to perform heavy background computation and you don't necessarily need it to be run by the same process (for example, you don't need to share memory, variables, etc), you might benefit from using other bigger tools like [Celery](https://docs.celeryq.dev).\n\nThey tend to require more complex configurations, a message/job queue manager, like RabbitMQ or Redis, but they allow you to run background tasks in multiple processes, and especially, in multiple servers.\n\nBut if you need to access variables and objects from the same **FastAPI** app, or you need to perform small background tasks (like sending an email notification), you can simply just use `BackgroundTasks`.", "source_type": "doc", "path": "docs/en/docs/tutorial/background-tasks.md", "symbol": "Caveat { #caveat }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/background-tasks.md#L76-L83", "start_line": 76, "end_line": 83}
{"id": "docs/en/docs/tutorial/background-tasks.md::Recap { #recap }::L84", "text": "# Doc: docs/en/docs/tutorial/background-tasks.md | Page: Background Tasks { #background-tasks } | Section: Recap { #recap }\n## Recap { #recap }\n\nImport and use `BackgroundTasks` with parameters in *path operation functions* and dependencies to add background tasks.", "source_type": "doc", "path": "docs/en/docs/tutorial/background-tasks.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/background-tasks.md#L84-L86", "start_line": 84, "end_line": 86}
{"id": "docs/en/docs/tutorial/bigger-applications.md::Bigger Applications - Multiple Files { #bigger-applications-multiple-files }::L1", "text": "# Doc: docs/en/docs/tutorial/bigger-applications.md | Page: Bigger Applications - Multiple Files { #bigger-applications-multiple-files } | Section: Bigger Applications - Multiple Files { #bigger-applications-multiple-files }\n# Bigger Applications - Multiple Files { #bigger-applications-multiple-files }\n\nIf you are building an application or a web API, it's rarely the case that you can put everything in a single file.\n\n**FastAPI** provides a convenience tool to structure your application while keeping all the flexibility.\n\n/// note\n\nIf you come from Flask, this would be the equivalent of Flask's Blueprints.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/bigger-applications.md", "symbol": "Bigger Applications - Multiple Files { #bigger-applications-multiple-files }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/bigger-applications.md#L1-L12", "start_line": 1, "end_line": 12}
{"id": "docs/en/docs/tutorial/bigger-applications.md::An example file structure { #an-example-file-structure }::L13", "text": "# Doc: docs/en/docs/tutorial/bigger-applications.md | Page: Bigger Applications - Multiple Files { #bigger-applications-multiple-files } | Section: An example file structure { #an-example-file-structure }\n## An example file structure { #an-example-file-structure }\n\nLet's say you have a file structure like this:\n\n```\n.\n├── app\n│ ├── __init__.py\n│ ├── main.py\n│ ├── dependencies.py\n│ └── routers\n│ │ ├── __init__.py\n│ │ ├── items.py\n│ │ └── users.py\n│ └── internal\n│ ├── __init__.py\n│ └── admin.py\n```\n\n/// tip\n\nThere are several `__init__.py` files: one in each directory or subdirectory.\n\nThis is what allows importing code from one file into another.\n\nFor example, in `app/main.py` you could have a line like:\n\n```\nfrom app.routers import items\n```\n\n///\n\n* The `app` directory contains everything. And it has an empty file `app/__init__.py`, so it is a \"Python package\" (a collection of \"Python modules\"): `app`.\n* It contains an `app/main.py` file. As it is inside a Python package (a directory with a file `__init__.py`), it is a \"module\" of that package: `app.main`.\n* There's also an `app/dependencies.py` file, just like `app/main.py`, it is a \"module\": `app.dependencies`.\n* There's a subdirectory `app/routers/` with another file `__init__.py`, so it's a \"Python subpackage\": `app.routers`.\n* The file `app/routers/items.py` is inside a package, `app/routers/`, so, it's a submodule: `app.routers.items`.\n* The same with `app/routers/users.py`, it's another submodule: `app.routers.users`.\n* There's also a subdirectory `app/internal/` with another file `__init__.py`, so it's another \"Python subpackage\": `app.internal`.\n* And the file `app/internal/admin.py` is another submodule: `app.internal.admin`.\n\n![](\"/img/tutorial/bigger-applications/package.drawio.svg\")
\n\nThe same file structure with comments:\n\n```bash\n.\n├── app # \"app\" is a Python package\n│ ├── __init__.py # this file makes \"app\" a \"Python package\"\n│ ├── main.py # \"main\" module, e.g. import app.main\n│ ├── dependencies.py # \"dependencies\" module, e.g. import app.dependencies\n│ └── routers # \"routers\" is a \"Python subpackage\"\n│ │ ├── __init__.py # makes \"routers\" a \"Python subpackage\"\n│ │ ├── items.py # \"items\" submodule, e.g. import app.routers.items\n│ │ └── users.py # \"users\" submodule, e.g. import app.routers.users\n│ └── internal # \"internal\" is a \"Python subpackage\"\n│ ├── __init__.py # makes \"internal\" a \"Python subpackage\"\n│ └── admin.py # \"admin\" submodule, e.g. import app.internal.admin\n```", "source_type": "doc", "path": "docs/en/docs/tutorial/bigger-applications.md", "symbol": "An example file structure { #an-example-file-structure }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/bigger-applications.md#L13-L73", "start_line": 13, "end_line": 73}
{"id": "docs/en/docs/tutorial/bigger-applications.md::`APIRouter` { #apirouter }::L74", "text": "# Doc: docs/en/docs/tutorial/bigger-applications.md | Page: Bigger Applications - Multiple Files { #bigger-applications-multiple-files } | Section: `APIRouter` { #apirouter }\n## `APIRouter` { #apirouter }\n\nLet's say the file dedicated to handling just users is the submodule at `/app/routers/users.py`.\n\nYou want to have the *path operations* related to your users separated from the rest of the code, to keep it organized.\n\nBut it's still part of the same **FastAPI** application/web API (it's part of the same \"Python Package\").\n\nYou can create the *path operations* for that module using `APIRouter`.\n\n### Import `APIRouter` { #import-apirouter }\n\nYou import it and create an \"instance\" the same way you would with the class `FastAPI`:\n\n{* ../../docs_src/bigger_applications/app_an_py310/routers/users.py hl[1,3] title[\"app/routers/users.py\"] *}\n\n### *Path operations* with `APIRouter` { #path-operations-with-apirouter }\n\nAnd then you use it to declare your *path operations*.\n\nUse it the same way you would use the `FastAPI` class:\n\n{* ../../docs_src/bigger_applications/app_an_py310/routers/users.py hl[6,11,16] title[\"app/routers/users.py\"] *}\n\nYou can think of `APIRouter` as a \"mini `FastAPI`\" class.\n\nAll the same options are supported.\n\nAll the same `parameters`, `responses`, `dependencies`, `tags`, etc.\n\n/// tip\n\nIn this example, the variable is called `router`, but you can name it however you want.\n\n///\n\nWe are going to include this `APIRouter` in the main `FastAPI` app, but first, let's check the dependencies and another `APIRouter`.", "source_type": "doc", "path": "docs/en/docs/tutorial/bigger-applications.md", "symbol": "`APIRouter` { #apirouter }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/bigger-applications.md#L74-L111", "start_line": 74, "end_line": 111}
{"id": "docs/en/docs/tutorial/bigger-applications.md::Dependencies { #dependencies }::L112", "text": "# Doc: docs/en/docs/tutorial/bigger-applications.md | Page: Bigger Applications - Multiple Files { #bigger-applications-multiple-files } | Section: Dependencies { #dependencies }\n## Dependencies { #dependencies }\n\nWe see that we are going to need some dependencies used in several places of the application.\n\nSo we put them in their own `dependencies` module (`app/dependencies.py`).\n\nWe will now use a simple dependency to read a custom `X-Token` header:\n\n{* ../../docs_src/bigger_applications/app_an_py310/dependencies.py hl[3,6:8] title[\"app/dependencies.py\"] *}\n\n/// tip\n\nWe are using an invented header to simplify this example.\n\nBut in real cases you will get better results using the integrated [Security utilities](security/index.md).\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/bigger-applications.md", "symbol": "Dependencies { #dependencies }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/bigger-applications.md#L112-L129", "start_line": 112, "end_line": 129}
{"id": "docs/en/docs/tutorial/bigger-applications.md::Another module with `APIRouter` { #another-module-with-apirouter }::L130", "text": "# Doc: docs/en/docs/tutorial/bigger-applications.md | Page: Bigger Applications - Multiple Files { #bigger-applications-multiple-files } | Section: Another module with `APIRouter` { #another-module-with-apirouter }\n## Another module with `APIRouter` { #another-module-with-apirouter }\n\nLet's say you also have the endpoints dedicated to handling \"items\" from your application in the module at `app/routers/items.py`.\n\nYou have *path operations* for:\n\n* `/items/`\n* `/items/{item_id}`\n\nIt's all the same structure as with `app/routers/users.py`.\n\nBut we want to be smarter and simplify the code a bit.\n\nWe know all the *path operations* in this module have the same:\n\n* Path `prefix`: `/items`.\n* `tags`: (just one tag: `items`).\n* Extra `responses`.\n* `dependencies`: they all need that `X-Token` dependency we created.\n\nSo, instead of adding all that to each *path operation*, we can add it to the `APIRouter`.\n\n{* ../../docs_src/bigger_applications/app_an_py310/routers/items.py hl[5:10,16,21] title[\"app/routers/items.py\"] *}\n\nAs the path of each *path operation* has to start with `/`, like in:\n\n```Python hl_lines=\"1\"\n@router.get(\"/{item_id}\")\nasync def read_item(item_id: str):\n ...\n```\n\n...the prefix must not include a final `/`.\n\nSo, the prefix in this case is `/items`.\n\nWe can also add a list of `tags` and extra `responses` that will be applied to all the *path operations* included in this router.\n\nAnd we can add a list of `dependencies` that will be added to all the *path operations* in the router and will be executed/solved for each request made to them.\n\n/// tip\n\nNote that, much like [dependencies in *path operation decorators*](dependencies/dependencies-in-path-operation-decorators.md), no value will be passed to your *path operation function*.\n\n///\n\nThe end result is that the item paths are now:\n\n* `/items/`\n* `/items/{item_id}`\n\n...as we intended.\n\n* They will be marked with a list of tags that contain a single string `\"items\"`.\n * These \"tags\" are especially useful for the automatic interactive documentation systems (using OpenAPI).\n* All of them will include the predefined `responses`.\n* All these *path operations* will have the list of `dependencies` evaluated/executed before them.\n * If you also declare dependencies in a specific *path operation*, **they will be executed too**.\n * The router dependencies are executed first, then the [`dependencies` in the decorator](dependencies/dependencies-in-path-operation-decorators.md), and then the normal parameter dependencies.\n * You can also add [`Security` dependencies with `scopes`](../advanced/security/oauth2-scopes.md).\n\n/// tip\n\nHaving `dependencies` in the `APIRouter` can be used, for example, to require authentication for a whole group of *path operations*. Even if the dependencies are not added individually to each one of them.\n\n///\n\n/// tip\n\nThe `prefix`, `tags`, `responses`, and `dependencies` parameters are (as in many other cases) just a feature from **FastAPI** to help you avoid code duplication.\n\n///\n\n### Import the dependencies { #import-the-dependencies }\n\nThis code lives in the module `app.routers.items`, the file `app/routers/items.py`.\n\nAnd we need to get the dependency function from the module `app.dependencies`, the file `app/dependencies.py`.\n\nSo we use a relative import with `..` for the dependencies:\n\n{* ../../docs_src/bigger_applications/app_an_py310/routers/items.py hl[3] title[\"app/routers/items.py\"] *}\n\n#### How relative imports work { #how-relative-imports-work }\n\n/// tip\n\nIf you know perfectly how imports work, continue to the next section below.\n\n///\n\nA single dot `.`, like in:\n\n```Python\nfrom .dependencies import get_token_header\n```\n\nwould mean:\n\n* Starting in the same package that this module (the file `app/routers/items.py`) lives in (the directory `app/routers/`)...\n* find the module `dependencies` (an imaginary file at `app/routers/dependencies.py`)...\n* and from it, import the function `get_token_header`.\n\nBut that file doesn't exist, our dependencies are in a file at `app/dependencies.py`.\n\nRemember what our app/file structure looks like:\n\n\n\n---\n\nThe two dots `..`, like in:\n\n```Python\nfrom ..dependencies import get_token_header\n```\n\nmean:\n\n* Starting in the same package that this module (the file `app/routers/items.py`) lives in (the directory `app/routers/`)...\n* go to the parent package (the directory `app/`)...\n* and in there, find the module `dependencies` (the file at `app/dependencies.py`)...\n* and from it, import the function `get_token_header`.\n\nThat works correctly! 🎉\n\n---\n\nThe same way, if we had used three dots `...`, like in:\n\n```Python\nfrom ...dependencies import get_token_header\n```\n\nthat would mean:\n\n* Starting in the same package that this module (the file `app/routers/items.py`) lives in (the directory `app/routers/`)...\n* go to the parent package (the directory `app/`)...\n* then go to the parent of that package (there's no parent package, `app` is the top level 😱)...\n* and in there, find the module `dependencies` (the file at `app/dependencies.py`)...\n* and from it, import the function `get_token_header`.\n\nThat would refer to some package above `app/`, with its own file `__init__.py`, etc. But we don't have that. So, that would throw an error in our example. 🚨\n\nBut now you know how it works, so you can use relative imports in your own apps no matter how complex they are. 🤓\n\n### Add some custom `tags`, `responses`, and `dependencies` { #add-some-custom-tags-responses-and-dependencies }\n\nWe are not adding the prefix `/items` nor the `tags=[\"items\"]` to each *path operation* because we added them to the `APIRouter`.\n\nBut we can still add _more_ `tags` that will be applied to a specific *path operation*, and also some extra `responses` specific to that *path operation*:\n\n{* ../../docs_src/bigger_applications/app_an_py310/routers/items.py hl[30:31] title[\"app/routers/items.py\"] *}\n\n/// tip\n\nThis last path operation will have the combination of tags: `[\"items\", \"custom\"]`.\n\nAnd it will also have both responses in the documentation, one for `404` and one for `403`.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/bigger-applications.md", "symbol": "Another module with `APIRouter` { #another-module-with-apirouter }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/bigger-applications.md#L130-L291", "start_line": 130, "end_line": 291}
{"id": "docs/en/docs/tutorial/bigger-applications.md::The main `FastAPI` { #the-main-fastapi }::L292", "text": "# Doc: docs/en/docs/tutorial/bigger-applications.md | Page: Bigger Applications - Multiple Files { #bigger-applications-multiple-files } | Section: The main `FastAPI` { #the-main-fastapi }\n## The main `FastAPI` { #the-main-fastapi }\n\nNow, let's see the module at `app/main.py`.\n\nHere's where you import and use the class `FastAPI`.\n\nThis will be the main file in your application that ties everything together.\n\nAnd as most of your logic will now live in its own specific module, the main file will be quite simple.\n\n### Import `FastAPI` { #import-fastapi }\n\nYou import and create a `FastAPI` class as normally.\n\nAnd we can even declare [global dependencies](dependencies/global-dependencies.md) that will be combined with the dependencies for each `APIRouter`:\n\n{* ../../docs_src/bigger_applications/app_an_py310/main.py hl[1,3,7] title[\"app/main.py\"] *}\n\n### Import the `APIRouter` { #import-the-apirouter }\n\nNow we import the other submodules that have `APIRouter`s:\n\n{* ../../docs_src/bigger_applications/app_an_py310/main.py hl[4:5] title[\"app/main.py\"] *}\n\nAs the files `app/routers/users.py` and `app/routers/items.py` are submodules that are part of the same Python package `app`, we can use a single dot `.` to import them using \"relative imports\".\n\n### How the importing works { #how-the-importing-works }\n\nThe section:\n\n```Python\nfrom .routers import items, users\n```\n\nmeans:\n\n* Starting in the same package that this module (the file `app/main.py`) lives in (the directory `app/`)...\n* look for the subpackage `routers` (the directory at `app/routers/`)...\n* and from it, import the submodule `items` (the file at `app/routers/items.py`) and `users` (the file at `app/routers/users.py`)...\n\nThe module `items` will have a variable `router` (`items.router`). This is the same one we created in the file `app/routers/items.py`, it's an `APIRouter` object.\n\nAnd then we do the same for the module `users`.\n\nWe could also import them like:\n\n```Python\nfrom app.routers import items, users\n```\n\n/// note\n\nThe first version is a \"relative import\":\n\n```Python\nfrom .routers import items, users\n```\n\nThe second version is an \"absolute import\":\n\n```Python\nfrom app.routers import items, users\n```\n\nTo learn more about Python Packages and Modules, read [the official Python documentation about Modules](https://docs.python.org/3/tutorial/modules.html).\n\n///\n\n### Avoid name collisions { #avoid-name-collisions }\n\nWe are importing the submodule `items` directly, instead of importing just its variable `router`.\n\nThis is because we also have another variable named `router` in the submodule `users`.\n\nIf we had imported one after the other, like:\n\n```Python\nfrom .routers.items import router\nfrom .routers.users import router\n```\n\nthe `router` from `users` would overwrite the one from `items` and we wouldn't be able to use them at the same time.\n\nSo, to be able to use both of them in the same file, we import the submodules directly:\n\n{* ../../docs_src/bigger_applications/app_an_py310/main.py hl[5] title[\"app/main.py\"] *}\n\n### Include the `APIRouter`s for `users` and `items` { #include-the-apirouters-for-users-and-items }\n\nNow, let's include the `router`s from the submodules `users` and `items`:\n\n{* ../../docs_src/bigger_applications/app_an_py310/main.py hl[10:11] title[\"app/main.py\"] *}\n\n/// note\n\n`users.router` contains the `APIRouter` inside of the file `app/routers/users.py`.\n\nAnd `items.router` contains the `APIRouter` inside of the file `app/routers/items.py`.\n\n///\n\nWith `app.include_router()` we can add each `APIRouter` to the main `FastAPI` application.\n\nIt will include all the routes from that router as part of it.\n\n/// note | Technical Details\n\nFastAPI keeps the original `APIRouter` and its `APIRoute`s active when the router is included in the main application.\n\nThat means custom `APIRouter` and `APIRoute` subclasses can still participate after the router is included.\n\n///\n\n/// tip\n\nYou don't have to worry about performance when including routers.\n\nThis is designed to be lightweight and to avoid adding overhead to each request.\n\nSo it won't affect performance. ⚡\n\n///\n\n### Include an `APIRouter` with a custom `prefix`, `tags`, `responses`, and `dependencies` { #include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies }\n\nNow, let's imagine your organization gave you the `app/internal/admin.py` file.\n\nIt contains an `APIRouter` with some admin *path operations* that your organization shares between several projects.\n\nFor this example it will be super simple. But let's say that because it is shared with other projects in the organization, we cannot modify it and add a `prefix`, `dependencies`, `tags`, etc. directly to the `APIRouter`:\n\n{* ../../docs_src/bigger_applications/app_an_py310/internal/admin.py hl[3] title[\"app/internal/admin.py\"] *}\n\nBut we still want to set a custom `prefix` when including the `APIRouter` so that all its *path operations* start with `/admin`, we want to secure it with the `dependencies` we already have for this project, and we want to include `tags` and `responses`.\n\nWe can declare all that without having to modify the original `APIRouter` by passing those parameters to `app.include_router()`:\n\n{* ../../docs_src/bigger_applications/app_an_py310/main.py hl[14:17] title[\"app/main.py\"] *}\n\nThat way, the original `APIRouter` will stay unmodified, so we can still share that same `app/internal/admin.py` file with other projects in the organization.\n\nThe result is that in our app, each of the *path operations* from the `admin` module will have:\n\n* The prefix `/admin`.\n* The tag `admin`.\n* The dependency `get_token_header`.\n* The response `418`. 🍵\n\nBut that will only affect that `APIRouter` in our app, not in any other code that uses it.\n\nSo, for example, other projects could use the same `APIRouter` with a different authentication method.\n\n### Include a *path operation* { #include-a-path-operation }\n\nWe can also add *path operations* directly to the `FastAPI` app.\n\nHere we do it... just to show that we can 🤷:\n\n{* ../../docs_src/bigger_applications/app_an_py310/main.py hl[21:23] title[\"app/main.py\"] *}\n\nand it will work correctly, together with all the other *path operations* added with `app.include_router()`.\n\n/// note | Very Technical Details\n\n**Note**: this is a very technical detail that you probably can **just skip**.\n\n---\n\nThe `APIRouter`s are not \"mounted\", they are not isolated from the rest of the application.\n\nThis is because we want to include their *path operations* in the OpenAPI schema and the user interfaces.\n\nFastAPI keeps the original routers and path operations active, and combines the router prefixes, dependencies, tags, responses, and other metadata when handling requests and generating OpenAPI.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/bigger-applications.md", "symbol": "The main `FastAPI` { #the-main-fastapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/bigger-applications.md#L292-L467", "start_line": 292, "end_line": 467}
{"id": "docs/en/docs/tutorial/bigger-applications.md::Configure the `entrypoint` in `pyproject.toml` { #configure-the-entrypoint-in-pyproject-toml }::L468", "text": "# Doc: docs/en/docs/tutorial/bigger-applications.md | Page: Bigger Applications - Multiple Files { #bigger-applications-multiple-files } | Section: Configure the `entrypoint` in `pyproject.toml` { #configure-the-entrypoint-in-pyproject-toml }\n## Configure the `entrypoint` in `pyproject.toml` { #configure-the-entrypoint-in-pyproject-toml }\n\nAs your FastAPI `app` object lives in `app/main.py`, you can configure the `entrypoint` in your `pyproject.toml` file like this:\n\n```toml\n[tool.fastapi]\nentrypoint = \"app.main:app\"\n```\n\nthat is equivalent to importing like:\n\n```python\nfrom app.main import app\n```\n\nThat way the `fastapi` command will know where to find your app.\n\n/// Note\n\nYou could also pass the path to the command, like:\n\n```console\n$ fastapi dev app/main.py\n```\n\nBut you would have to remember to pass the correct path every time you call the `fastapi` command.\n\nAdditionally, other tools might not be able to find it, for example the [VS Code Extension](../editor-support.md) or [FastAPI Cloud](https://fastapicloud.com), so it is recommended to use the `entrypoint` in `pyproject.toml`.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/bigger-applications.md", "symbol": "Configure the `entrypoint` in `pyproject.toml` { #configure-the-entrypoint-in-pyproject-toml }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/bigger-applications.md#L468-L498", "start_line": 468, "end_line": 498}
{"id": "docs/en/docs/tutorial/bigger-applications.md::Check the automatic API docs { #check-the-automatic-api-docs }::L499", "text": "# Doc: docs/en/docs/tutorial/bigger-applications.md | Page: Bigger Applications - Multiple Files { #bigger-applications-multiple-files } | Section: Check the automatic API docs { #check-the-automatic-api-docs }\n## Check the automatic API docs { #check-the-automatic-api-docs }\n\nNow, run your app:\n\n![](\"/img/tutorial/bigger-applications/image01.png\")
", "source_type": "doc", "path": "docs/en/docs/tutorial/bigger-applications.md", "symbol": "Check the automatic API docs { #check-the-automatic-api-docs }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/bigger-applications.md#L499-L518", "start_line": 499, "end_line": 518}
{"id": "docs/en/docs/tutorial/bigger-applications.md::Include the same router multiple times with different `prefix` { #include-the-same-router-multiple-times-with-different-prefix }::L519", "text": "# Doc: docs/en/docs/tutorial/bigger-applications.md | Page: Bigger Applications - Multiple Files { #bigger-applications-multiple-files } | Section: Include the same router multiple times with different `prefix` { #include-the-same-router-multiple-times-with-different-prefix }\n## Include the same router multiple times with different `prefix` { #include-the-same-router-multiple-times-with-different-prefix }\n\nYou can also use `.include_router()` multiple times with the *same* router using different prefixes.\n\nThis could be useful, for example, to expose the same API under different prefixes, e.g. `/api/v1` and `/api/latest`.\n\nThis is an advanced usage that you might not really need, but it's there in case you do.", "source_type": "doc", "path": "docs/en/docs/tutorial/bigger-applications.md", "symbol": "Include the same router multiple times with different `prefix` { #include-the-same-router-multiple-times-with-different-prefix }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/bigger-applications.md#L519-L526", "start_line": 519, "end_line": 526}
{"id": "docs/en/docs/tutorial/bigger-applications.md::Include an `APIRouter` in another { #include-an-apirouter-in-another }::L527", "text": "# Doc: docs/en/docs/tutorial/bigger-applications.md | Page: Bigger Applications - Multiple Files { #bigger-applications-multiple-files } | Section: Include an `APIRouter` in another { #include-an-apirouter-in-another }\n## Include an `APIRouter` in another { #include-an-apirouter-in-another }\n\nThe same way you can include an `APIRouter` in a `FastAPI` application, you can include an `APIRouter` in another `APIRouter` using:\n\n```Python\nrouter.include_router(other_router)\n```\n\nYou can do this before or after including `router` in the `FastAPI` app. FastAPI will still include the *path operations* from `other_router` in routing and OpenAPI.\n\nThe same applies to *path operations* added later to the routers. They will be visible through the earlier inclusion too.\n\n/// warning | Technical Details\n\nAvoid directly mutating `router.routes` after including a router. FastAPI treats router inclusion as live, so the original router and its routes remain part of routing and OpenAPI generation.\n\nUse documented APIs such as path operation decorators and `.include_router()` to add routes and routers.\n\nTreat `router.routes` as a lower-level route tree that can contain route definitions and included routers, and avoid relying on it as a flat list of final path operations.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/bigger-applications.md", "symbol": "Include an `APIRouter` in another { #include-an-apirouter-in-another }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/bigger-applications.md#L527-L547", "start_line": 527, "end_line": 547}
{"id": "docs/en/docs/tutorial/body-fields.md::Body - Fields { #body-fields }::L1", "text": "# Doc: docs/en/docs/tutorial/body-fields.md | Page: Body - Fields { #body-fields } | Section: Body - Fields { #body-fields }\n# Body - Fields { #body-fields }\n\nThe same way you can declare additional validation and metadata in *path operation function* parameters with `Query`, `Path` and `Body`, you can declare validation and metadata inside of Pydantic models using Pydantic's `Field`.", "source_type": "doc", "path": "docs/en/docs/tutorial/body-fields.md", "symbol": "Body - Fields { #body-fields }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-fields.md#L1-L4", "start_line": 1, "end_line": 4}
{"id": "docs/en/docs/tutorial/body-fields.md::Import `Field` { #import-field }::L5", "text": "# Doc: docs/en/docs/tutorial/body-fields.md | Page: Body - Fields { #body-fields } | Section: Import `Field` { #import-field }\n## Import `Field` { #import-field }\n\nFirst, you have to import it:\n\n{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[4] *}\n\n\n/// warning\n\nNotice that `Field` is imported directly from `pydantic`, not from `fastapi` as are all the rest (`Query`, `Path`, `Body`, etc).\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/body-fields.md", "symbol": "Import `Field` { #import-field }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-fields.md#L5-L17", "start_line": 5, "end_line": 17}
{"id": "docs/en/docs/tutorial/body-fields.md::Declare model attributes { #declare-model-attributes }::L18", "text": "# Doc: docs/en/docs/tutorial/body-fields.md | Page: Body - Fields { #body-fields } | Section: Declare model attributes { #declare-model-attributes }\n## Declare model attributes { #declare-model-attributes }\n\nYou can then use `Field` with model attributes:\n\n{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[11:14] *}\n\n`Field` works the same way as `Query`, `Path` and `Body`, it has all the same parameters, etc.\n\n/// note | Technical Details\n\nActually, `Query`, `Path` and others you'll see next create objects of subclasses of a common `Param` class, which is itself a subclass of Pydantic's `FieldInfo` class.\n\nAnd Pydantic's `Field` returns an instance of `FieldInfo` as well.\n\n`Body` also returns objects of a subclass of `FieldInfo` directly. And there are others you will see later that are subclasses of the `Body` class.\n\nRemember that when you import `Query`, `Path`, and others from `fastapi`, those are actually functions that return special classes.\n\n///\n\n/// tip\n\nNotice how each model's attribute with a type, default value and `Field` has the same structure as a *path operation function's* parameter, with `Field` instead of `Path`, `Query` and `Body`.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/body-fields.md", "symbol": "Declare model attributes { #declare-model-attributes }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-fields.md#L18-L43", "start_line": 18, "end_line": 43}
{"id": "docs/en/docs/tutorial/body-fields.md::Add extra information { #add-extra-information }::L44", "text": "# Doc: docs/en/docs/tutorial/body-fields.md | Page: Body - Fields { #body-fields } | Section: Add extra information { #add-extra-information }\n## Add extra information { #add-extra-information }\n\nYou can declare extra information in `Field`, `Query`, `Body`, etc. And it will be included in the generated JSON Schema.\n\nYou will learn more about adding extra information later in the docs, when learning to declare examples.\n\n/// warning\n\nExtra keys passed to `Field` will also be present in the resulting OpenAPI schema for your application.\nAs these keys may not necessarily be part of the OpenAPI specification, some OpenAPI tools, for example [the OpenAPI validator](https://validator.swagger.io/), may not work with your generated schema.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/body-fields.md", "symbol": "Add extra information { #add-extra-information }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-fields.md#L44-L56", "start_line": 44, "end_line": 56}
{"id": "docs/en/docs/tutorial/body-fields.md::Recap { #recap }::L57", "text": "# Doc: docs/en/docs/tutorial/body-fields.md | Page: Body - Fields { #body-fields } | Section: Recap { #recap }\n## Recap { #recap }\n\nYou can use Pydantic's `Field` to declare extra validations and metadata for model attributes.\n\nYou can also use the extra keyword arguments to pass additional JSON Schema metadata.", "source_type": "doc", "path": "docs/en/docs/tutorial/body-fields.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-fields.md#L57-L61", "start_line": 57, "end_line": 61}
{"id": "docs/en/docs/tutorial/body-multiple-params.md::Body - Multiple Parameters { #body-multiple-parameters }::L1", "text": "# Doc: docs/en/docs/tutorial/body-multiple-params.md | Page: Body - Multiple Parameters { #body-multiple-parameters } | Section: Body - Multiple Parameters { #body-multiple-parameters }\n# Body - Multiple Parameters { #body-multiple-parameters }\n\nNow that we have seen how to use `Path` and `Query`, let's see more advanced uses of request body declarations.", "source_type": "doc", "path": "docs/en/docs/tutorial/body-multiple-params.md", "symbol": "Body - Multiple Parameters { #body-multiple-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-multiple-params.md#L1-L4", "start_line": 1, "end_line": 4}
{"id": "docs/en/docs/tutorial/body-multiple-params.md::Mix `Path`, `Query` and body parameters { #mix-path-query-and-body-parameters }::L5", "text": "# Doc: docs/en/docs/tutorial/body-multiple-params.md | Page: Body - Multiple Parameters { #body-multiple-parameters } | Section: Mix `Path`, `Query` and body parameters { #mix-path-query-and-body-parameters }\n## Mix `Path`, `Query` and body parameters { #mix-path-query-and-body-parameters }\n\nFirst, of course, you can mix `Path`, `Query` and request body parameter declarations freely and **FastAPI** will know what to do.\n\nAnd you can also declare body parameters as optional, by setting the default to `None`:\n\n{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *}\n\n/// note\n\nNotice that, in this case, the `item` that would be taken from the body is optional. As it has a `None` default value.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/body-multiple-params.md", "symbol": "Mix `Path`, `Query` and body parameters { #mix-path-query-and-body-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-multiple-params.md#L5-L18", "start_line": 5, "end_line": 18}
{"id": "docs/en/docs/tutorial/body-multiple-params.md::Multiple body parameters { #multiple-body-parameters }::L19", "text": "# Doc: docs/en/docs/tutorial/body-multiple-params.md | Page: Body - Multiple Parameters { #body-multiple-parameters } | Section: Multiple body parameters { #multiple-body-parameters }\n## Multiple body parameters { #multiple-body-parameters }\n\nIn the previous example, the *path operations* would expect a JSON body with the attributes of an `Item`, like:\n\n```JSON\n{\n \"name\": \"Foo\",\n \"description\": \"The pretender\",\n \"price\": 42.0,\n \"tax\": 3.2\n}\n```\n\nBut you can also declare multiple body parameters, e.g. `item` and `user`:\n\n{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *}\n\n\nIn this case, **FastAPI** will notice that there is more than one body parameter in the function (there are two parameters that are Pydantic models).\n\nSo, it will then use the parameter names as keys (field names) in the body, and expect a body like:\n\n```JSON\n{\n \"item\": {\n \"name\": \"Foo\",\n \"description\": \"The pretender\",\n \"price\": 42.0,\n \"tax\": 3.2\n },\n \"user\": {\n \"username\": \"dave\",\n \"full_name\": \"Dave Grohl\"\n }\n}\n```\n\n/// note\n\nNotice that even though the `item` was declared the same way as before, it is now expected to be inside of the body with a key `item`.\n\n///\n\n**FastAPI** will do the automatic conversion from the request, so that the parameter `item` receives its specific content and the same for `user`.\n\nIt will perform the validation of the compound data, and will document it like that for the OpenAPI schema and automatic docs.", "source_type": "doc", "path": "docs/en/docs/tutorial/body-multiple-params.md", "symbol": "Multiple body parameters { #multiple-body-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-multiple-params.md#L19-L65", "start_line": 19, "end_line": 65}
{"id": "docs/en/docs/tutorial/body-multiple-params.md::Singular values in body { #singular-values-in-body }::L66", "text": "# Doc: docs/en/docs/tutorial/body-multiple-params.md | Page: Body - Multiple Parameters { #body-multiple-parameters } | Section: Singular values in body { #singular-values-in-body }\n## Singular values in body { #singular-values-in-body }\n\nThe same way there is a `Query` and `Path` to define extra data for query and path parameters, **FastAPI** provides an equivalent `Body`.\n\nFor example, extending the previous model, you could decide that you want to have another key `importance` in the same body, besides the `item` and `user`.\n\nIf you declare it as is, because it is a singular value, **FastAPI** will assume that it is a query parameter.\n\nBut you can instruct **FastAPI** to treat it as another body key using `Body`:\n\n{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *}\n\n\nIn this case, **FastAPI** will expect a body like:\n\n```JSON\n{\n \"item\": {\n \"name\": \"Foo\",\n \"description\": \"The pretender\",\n \"price\": 42.0,\n \"tax\": 3.2\n },\n \"user\": {\n \"username\": \"dave\",\n \"full_name\": \"Dave Grohl\"\n },\n \"importance\": 5\n}\n```\n\nAgain, it will convert the data types, validate, document, etc.", "source_type": "doc", "path": "docs/en/docs/tutorial/body-multiple-params.md", "symbol": "Singular values in body { #singular-values-in-body }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-multiple-params.md#L66-L98", "start_line": 66, "end_line": 98}
{"id": "docs/en/docs/tutorial/body-multiple-params.md::Multiple body params and query { #multiple-body-params-and-query }::L99", "text": "# Doc: docs/en/docs/tutorial/body-multiple-params.md | Page: Body - Multiple Parameters { #body-multiple-parameters } | Section: Multiple body params and query { #multiple-body-params-and-query }\n## Multiple body params and query { #multiple-body-params-and-query }\n\nOf course, you can also declare additional query parameters whenever you need, additional to any body parameters.\n\nAs, by default, singular values are interpreted as query parameters, you don't have to explicitly add a `Query`, you can just do:\n\n```Python\nq: str | None = None\n```\n\nFor example:\n\n{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *}\n\n\n/// note\n\n`Body` also has all the same extra validation and metadata parameters as `Query`, `Path` and others you will see later.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/body-multiple-params.md", "symbol": "Multiple body params and query { #multiple-body-params-and-query }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-multiple-params.md#L99-L119", "start_line": 99, "end_line": 119}
{"id": "docs/en/docs/tutorial/body-multiple-params.md::Embed a single body parameter { #embed-a-single-body-parameter }::L120", "text": "# Doc: docs/en/docs/tutorial/body-multiple-params.md | Page: Body - Multiple Parameters { #body-multiple-parameters } | Section: Embed a single body parameter { #embed-a-single-body-parameter }\n## Embed a single body parameter { #embed-a-single-body-parameter }\n\nLet's say you only have a single `item` body parameter from a Pydantic model `Item`.\n\nBy default, **FastAPI** will then expect its body directly.\n\nBut if you want it to expect a JSON with a key `item` and inside of it the model contents, as it does when you declare extra body parameters, you can use the special `Body` parameter `embed`:\n\n```Python\nitem: Annotated[Item, Body(embed=True)]\n```\n\nas in:\n\n{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *}\n\n\nIn this case **FastAPI** will expect a body like:\n\n```JSON hl_lines=\"2\"\n{\n \"item\": {\n \"name\": \"Foo\",\n \"description\": \"The pretender\",\n \"price\": 42.0,\n \"tax\": 3.2\n }\n}\n```\n\ninstead of:\n\n```JSON\n{\n \"name\": \"Foo\",\n \"description\": \"The pretender\",\n \"price\": 42.0,\n \"tax\": 3.2\n}\n```", "source_type": "doc", "path": "docs/en/docs/tutorial/body-multiple-params.md", "symbol": "Embed a single body parameter { #embed-a-single-body-parameter }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-multiple-params.md#L120-L160", "start_line": 120, "end_line": 160}
{"id": "docs/en/docs/tutorial/body-multiple-params.md::Recap { #recap }::L161", "text": "# Doc: docs/en/docs/tutorial/body-multiple-params.md | Page: Body - Multiple Parameters { #body-multiple-parameters } | Section: Recap { #recap }\n## Recap { #recap }\n\nYou can add multiple body parameters to your *path operation function*, even though a request can only have a single body.\n\nBut **FastAPI** will handle it, give you the correct data in your function, and validate and document the correct schema in the *path operation*.\n\nYou can also declare singular values to be received as part of the body.\n\nAnd you can instruct **FastAPI** to embed the body in a key even when there is only a single parameter declared.", "source_type": "doc", "path": "docs/en/docs/tutorial/body-multiple-params.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-multiple-params.md#L161-L169", "start_line": 161, "end_line": 169}
{"id": "docs/en/docs/tutorial/body-nested-models.md::Body - Nested Models { #body-nested-models }::L1", "text": "# Doc: docs/en/docs/tutorial/body-nested-models.md | Page: Body - Nested Models { #body-nested-models } | Section: Body - Nested Models { #body-nested-models }\n# Body - Nested Models { #body-nested-models }\n\nWith **FastAPI**, you can define, validate, document, and use arbitrarily deeply nested models (thanks to Pydantic).", "source_type": "doc", "path": "docs/en/docs/tutorial/body-nested-models.md", "symbol": "Body - Nested Models { #body-nested-models }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-nested-models.md#L1-L4", "start_line": 1, "end_line": 4}
{"id": "docs/en/docs/tutorial/body-nested-models.md::List fields { #list-fields }::L5", "text": "# Doc: docs/en/docs/tutorial/body-nested-models.md | Page: Body - Nested Models { #body-nested-models } | Section: List fields { #list-fields }\n## List fields { #list-fields }\n\nYou can define an attribute to be a subtype. For example, a Python `list`:\n\n{* ../../docs_src/body_nested_models/tutorial001_py310.py hl[12] *}\n\nThis will make `tags` be a list, although it doesn't declare the type of the elements of the list.", "source_type": "doc", "path": "docs/en/docs/tutorial/body-nested-models.md", "symbol": "List fields { #list-fields }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-nested-models.md#L5-L12", "start_line": 5, "end_line": 12}
{"id": "docs/en/docs/tutorial/body-nested-models.md::List fields with type parameter { #list-fields-with-type-parameter }::L13", "text": "# Doc: docs/en/docs/tutorial/body-nested-models.md | Page: Body - Nested Models { #body-nested-models } | Section: List fields with type parameter { #list-fields-with-type-parameter }\n## List fields with type parameter { #list-fields-with-type-parameter }\n\nBut Python has a specific way to declare lists with internal types, or \"type parameters\":\n\n### Declare a `list` with a type parameter { #declare-a-list-with-a-type-parameter }\n\nTo declare types that have type parameters (internal types), like `list`, `dict`, `tuple`,\npass the internal type(s) as \"type parameters\" using square brackets: `[` and `]`\n\n```Python\nmy_list: list[str]\n```\n\nThat's all standard Python syntax for type declarations.\n\nUse that same standard syntax for model attributes with internal types.\n\nSo, in our example, we can make `tags` be specifically a \"list of strings\":\n\n{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/body-nested-models.md", "symbol": "List fields with type parameter { #list-fields-with-type-parameter }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-nested-models.md#L13-L33", "start_line": 13, "end_line": 33}
{"id": "docs/en/docs/tutorial/body-nested-models.md::Set types { #set-types }::L34", "text": "# Doc: docs/en/docs/tutorial/body-nested-models.md | Page: Body - Nested Models { #body-nested-models } | Section: Set types { #set-types }\n## Set types { #set-types }\n\nBut then we think about it, and realize that tags shouldn't repeat, they would probably be unique strings.\n\nAnd Python has a special data type for sets of unique items, the `set`.\n\nThen we can declare `tags` as a set of strings:\n\n{* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *}\n\nWith this, even if you receive a request with duplicate data, it will be converted to a set of unique items.\n\nAnd whenever you output that data, even if the source had duplicates, it will be output as a set of unique items.\n\nAnd it will be annotated / documented accordingly too.", "source_type": "doc", "path": "docs/en/docs/tutorial/body-nested-models.md", "symbol": "Set types { #set-types }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-nested-models.md#L34-L49", "start_line": 34, "end_line": 49}
{"id": "docs/en/docs/tutorial/body-nested-models.md::Nested Models { #nested-models }::L50", "text": "# Doc: docs/en/docs/tutorial/body-nested-models.md | Page: Body - Nested Models { #body-nested-models } | Section: Nested Models { #nested-models }\n## Nested Models { #nested-models }\n\nEach attribute of a Pydantic model has a type.\n\nBut that type can itself be another Pydantic model.\n\nSo, you can declare deeply nested JSON \"objects\" with specific attribute names, types and validations.\n\nAll that, arbitrarily nested.\n\n### Define a submodel { #define-a-submodel }\n\nFor example, we can define an `Image` model:\n\n{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *}\n\n### Use the submodel as a type { #use-the-submodel-as-a-type }\n\nAnd then we can use it as the type of an attribute:\n\n{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[18] *}\n\nThis would mean that **FastAPI** would expect a body similar to:\n\n```JSON\n{\n \"name\": \"Foo\",\n \"description\": \"The pretender\",\n \"price\": 42.0,\n \"tax\": 3.2,\n \"tags\": [\"rock\", \"metal\", \"bar\"],\n \"image\": {\n \"url\": \"http://example.com/baz.jpg\",\n \"name\": \"The Foo live\"\n }\n}\n```\n\nAgain, doing just that declaration, with **FastAPI** you get:\n\n* Editor support (completion, etc.), even for nested models\n* Data conversion\n* Data validation\n* Automatic documentation", "source_type": "doc", "path": "docs/en/docs/tutorial/body-nested-models.md", "symbol": "Nested Models { #nested-models }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-nested-models.md#L50-L94", "start_line": 50, "end_line": 94}
{"id": "docs/en/docs/tutorial/body-nested-models.md::Special types and validation { #special-types-and-validation }::L95", "text": "# Doc: docs/en/docs/tutorial/body-nested-models.md | Page: Body - Nested Models { #body-nested-models } | Section: Special types and validation { #special-types-and-validation }\n## Special types and validation { #special-types-and-validation }\n\nApart from normal singular types like `str`, `int`, `float`, etc. you can use more complex singular types that inherit from `str`.\n\nTo see all the options you have, check out [Pydantic's Type Overview](https://docs.pydantic.dev/latest/concepts/types/). You will see some examples in the next chapter.\n\nFor example, as in the `Image` model we have a `url` field, we can declare it to be an instance of Pydantic's `HttpUrl` instead of a `str`:\n\n{* ../../docs_src/body_nested_models/tutorial005_py310.py hl[2,8] *}\n\nThe string will be checked to be a valid URL, and documented in JSON Schema / OpenAPI as such.", "source_type": "doc", "path": "docs/en/docs/tutorial/body-nested-models.md", "symbol": "Special types and validation { #special-types-and-validation }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-nested-models.md#L95-L106", "start_line": 95, "end_line": 106}
{"id": "docs/en/docs/tutorial/body-nested-models.md::Attributes with lists of submodels { #attributes-with-lists-of-submodels }::L107", "text": "# Doc: docs/en/docs/tutorial/body-nested-models.md | Page: Body - Nested Models { #body-nested-models } | Section: Attributes with lists of submodels { #attributes-with-lists-of-submodels }\n## Attributes with lists of submodels { #attributes-with-lists-of-submodels }\n\nYou can also use Pydantic models as subtypes of `list`, `set`, etc.:\n\n{* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *}\n\nThis will expect (convert, validate, document, etc.) a JSON body like:\n\n```JSON hl_lines=\"11\"\n{\n \"name\": \"Foo\",\n \"description\": \"The pretender\",\n \"price\": 42.0,\n \"tax\": 3.2,\n \"tags\": [\n \"rock\",\n \"metal\",\n \"bar\"\n ],\n \"images\": [\n {\n \"url\": \"http://example.com/baz.jpg\",\n \"name\": \"The Foo live\"\n },\n {\n \"url\": \"http://example.com/dave.jpg\",\n \"name\": \"The Baz\"\n }\n ]\n}\n```\n\n/// note\n\nNotice how the `images` key now has a list of image objects.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/body-nested-models.md", "symbol": "Attributes with lists of submodels { #attributes-with-lists-of-submodels }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-nested-models.md#L107-L144", "start_line": 107, "end_line": 144}
{"id": "docs/en/docs/tutorial/body-nested-models.md::Deeply nested models { #deeply-nested-models }::L145", "text": "# Doc: docs/en/docs/tutorial/body-nested-models.md | Page: Body - Nested Models { #body-nested-models } | Section: Deeply nested models { #deeply-nested-models }\n## Deeply nested models { #deeply-nested-models }\n\nYou can define arbitrarily deeply nested models:\n\n{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *}\n\n/// note\n\nNotice how `Offer` has a list of `Item`s, which in turn have an optional list of `Image`s\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/body-nested-models.md", "symbol": "Deeply nested models { #deeply-nested-models }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-nested-models.md#L145-L156", "start_line": 145, "end_line": 156}
{"id": "docs/en/docs/tutorial/body-nested-models.md::Bodies of pure lists { #bodies-of-pure-lists }::L157", "text": "# Doc: docs/en/docs/tutorial/body-nested-models.md | Page: Body - Nested Models { #body-nested-models } | Section: Bodies of pure lists { #bodies-of-pure-lists }\n## Bodies of pure lists { #bodies-of-pure-lists }\n\nIf the top level value of the JSON body you expect is a JSON `array` (a Python `list`), you can declare the type in the parameter of the function, the same as in Pydantic models:\n\n```Python\nimages: list[Image]\n```\n\nas in:\n\n{* ../../docs_src/body_nested_models/tutorial008_py310.py hl[13] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/body-nested-models.md", "symbol": "Bodies of pure lists { #bodies-of-pure-lists }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-nested-models.md#L157-L168", "start_line": 157, "end_line": 168}
{"id": "docs/en/docs/tutorial/body-nested-models.md::Editor support everywhere { #editor-support-everywhere }::L169", "text": "# Doc: docs/en/docs/tutorial/body-nested-models.md | Page: Body - Nested Models { #body-nested-models } | Section: Editor support everywhere { #editor-support-everywhere }\n## Editor support everywhere { #editor-support-everywhere }\n\nAnd you get editor support everywhere.\n\nEven for items inside of lists:\n\n![](\"/img/tutorial/body-nested-models/image01.png\")
\n\nYou couldn't get this kind of editor support if you were working directly with `dict` instead of Pydantic models.\n\nBut you don't have to worry about them either, incoming dicts are converted automatically and your output is converted automatically to JSON too.", "source_type": "doc", "path": "docs/en/docs/tutorial/body-nested-models.md", "symbol": "Editor support everywhere { #editor-support-everywhere }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-nested-models.md#L169-L180", "start_line": 169, "end_line": 180}
{"id": "docs/en/docs/tutorial/body-nested-models.md::Bodies of arbitrary `dict`s { #bodies-of-arbitrary-dicts }::L181", "text": "# Doc: docs/en/docs/tutorial/body-nested-models.md | Page: Body - Nested Models { #body-nested-models } | Section: Bodies of arbitrary `dict`s { #bodies-of-arbitrary-dicts }\n## Bodies of arbitrary `dict`s { #bodies-of-arbitrary-dicts }\n\nYou can also declare a body as a `dict` with keys of some type and values of some other type.\n\nThis way, you don't have to know beforehand what the valid field/attribute names are (as would be the case with Pydantic models).\n\nThis would be useful if you want to receive keys that you don't already know.\n\n---\n\nAnother useful case is when you want to have keys of another type (e.g., `int`).\n\nThat's what we are going to see here.\n\nIn this case, you would accept any `dict` as long as it has `int` keys with `float` values:\n\n{* ../../docs_src/body_nested_models/tutorial009_py310.py hl[7] *}\n\n/// tip\n\nKeep in mind that JSON only supports `str` as keys.\n\nBut Pydantic has automatic data conversion.\n\nThis means that, even though your API clients can only send strings as keys, as long as those strings contain pure integers, Pydantic will convert them and validate them.\n\nAnd the `dict` you receive as `weights` will actually have `int` keys and `float` values.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/body-nested-models.md", "symbol": "Bodies of arbitrary `dict`s { #bodies-of-arbitrary-dicts }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-nested-models.md#L181-L210", "start_line": 181, "end_line": 210}
{"id": "docs/en/docs/tutorial/body-nested-models.md::Recap { #recap }::L211", "text": "# Doc: docs/en/docs/tutorial/body-nested-models.md | Page: Body - Nested Models { #body-nested-models } | Section: Recap { #recap }\n## Recap { #recap }\n\nWith **FastAPI** you have the maximum flexibility provided by Pydantic models, while keeping your code simple, short and elegant.\n\nBut with all the benefits:\n\n* Editor support (completion everywhere!)\n* Data conversion (a.k.a. parsing / serialization)\n* Data validation\n* Schema documentation\n* Automatic docs", "source_type": "doc", "path": "docs/en/docs/tutorial/body-nested-models.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-nested-models.md#L211-L221", "start_line": 211, "end_line": 221}
{"id": "docs/en/docs/tutorial/body-updates.md::Update replacing with `PUT` { #update-replacing-with-put }::L3", "text": "# Doc: docs/en/docs/tutorial/body-updates.md | Page: Body - Updates { #body-updates } | Section: Update replacing with `PUT` { #update-replacing-with-put }\n## Update replacing with `PUT` { #update-replacing-with-put }\n\nTo update an item you can use the [HTTP `PUT`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) operation.\n\nYou can use the `jsonable_encoder` to convert the input data to data that can be stored as JSON (e.g. with a NoSQL database). For example, converting `datetime` to `str`.\n\n{* ../../docs_src/body_updates/tutorial001_py310.py hl[28:33] *}\n\n`PUT` is used to receive data that should replace the existing data.\n\n### Warning about replacing { #warning-about-replacing }\n\nThat means that if you want to update the item `bar` using `PUT` with a body containing:\n\n```Python\n{\n \"name\": \"Barz\",\n \"price\": 3,\n \"description\": None,\n}\n```\n\nbecause it doesn't include the already stored attribute `\"tax\": 20.2`, the input model would take the default value of `\"tax\": 10.5`.\n\nAnd the data would be saved with that \"new\" `tax` of `10.5`.", "source_type": "doc", "path": "docs/en/docs/tutorial/body-updates.md", "symbol": "Update replacing with `PUT` { #update-replacing-with-put }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-updates.md#L3-L28", "start_line": 3, "end_line": 28}
{"id": "docs/en/docs/tutorial/body-updates.md::Partial updates with `PATCH` { #partial-updates-with-patch }::L29", "text": "# Doc: docs/en/docs/tutorial/body-updates.md | Page: Body - Updates { #body-updates } | Section: Partial updates with `PATCH` { #partial-updates-with-patch }\n## Partial updates with `PATCH` { #partial-updates-with-patch }\n\nYou can also use the [HTTP `PATCH`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) operation to *partially* update data.\n\nThis means that you can send only the data that you want to update, leaving the rest intact.\n\n/// note\n\n`PATCH` is less commonly used and known than `PUT`.\n\nAnd many teams use only `PUT`, even for partial updates.\n\nYou are **free** to use them however you want, **FastAPI** doesn't impose any restrictions.\n\nBut this guide shows you, more or less, how they are intended to be used.\n\n///\n\n### Using Pydantic's `exclude_unset` parameter { #using-pydantics-exclude-unset-parameter }\n\nIf you want to receive partial updates, it's very useful to use the parameter `exclude_unset` in Pydantic's model's `.model_dump()`.\n\nLike `item.model_dump(exclude_unset=True)`.\n\nThat would generate a `dict` with only the data that was set when creating the `item` model, excluding default values.\n\nThen you can use this to generate a `dict` with only the data that was set (sent in the request), omitting default values:\n\n{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *}\n\n### Using Pydantic's `update` parameter { #using-pydantics-update-parameter }\n\nNow, you can create a copy of the existing model using `.model_copy()`, and pass the `update` parameter with a `dict` containing the data to update.\n\nLike `stored_item_model.model_copy(update=update_data)`:\n\n{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *}\n\n### Partial updates recap { #partial-updates-recap }\n\nIn summary, to apply partial updates you would:\n\n* (Optionally) use `PATCH` instead of `PUT`.\n* Retrieve the stored data.\n* Put that data in a Pydantic model.\n* Generate a `dict` without default values from the input model (using `exclude_unset`).\n * This way you can update only the values actually set by the user, instead of overriding values already stored with default values in your model.\n* Create a copy of the stored model, updating its attributes with the received partial updates (using the `update` parameter).\n* Convert the copied model to something that can be stored in your DB (for example, using the `jsonable_encoder`).\n * This is comparable to using the model's `.model_dump()` method again, but it makes sure (and converts) the values to data types that can be converted to JSON, for example, `datetime` to `str`.\n* Save the data to your DB.\n* Return the updated model.\n\n{* ../../docs_src/body_updates/tutorial002_py310.py hl[28:35] *}\n\n/// tip\n\nYou can actually use this same technique with an HTTP `PUT` operation.\n\nBut the example here uses `PATCH` because it was created for these use cases.\n\n///\n\n/// note\n\nNotice that the input model is still validated.\n\nSo, if you want to receive partial updates that can omit all the attributes, you need to have a model with all the attributes marked as optional (with default values or `None`).\n\nTo distinguish from the models with all optional values for **updates** and models with required values for **creation**, you can use the ideas described in [Extra Models](extra-models.md).\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/body-updates.md", "symbol": "Partial updates with `PATCH` { #partial-updates-with-patch }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body-updates.md#L29-L100", "start_line": 29, "end_line": 100}
{"id": "docs/en/docs/tutorial/body.md::Request Body { #request-body }::L1", "text": "# Doc: docs/en/docs/tutorial/body.md | Page: Request Body { #request-body } | Section: Request Body { #request-body }\n# Request Body { #request-body }\n\nWhen you need to send data from a client (let's say, a browser) to your API, you send it as a **request body**.\n\nA **request** body is data sent by the client to your API. A **response** body is the data your API sends to the client.\n\nYour API almost always has to send a **response** body. But clients don't necessarily need to send **request bodies** all the time, sometimes they only request a path, maybe with some query parameters, but don't send a body.\n\nTo declare a **request** body, you use [Pydantic](https://docs.pydantic.dev/) models with all their power and benefits.\n\n/// note\n\nTo send data, you should use one of: `POST` (the most common), `PUT`, `DELETE` or `PATCH`.\n\nSending a body with a `GET` request has an undefined behavior in the specifications, nevertheless, it is supported by FastAPI, only for very complex/extreme use cases.\n\nAs it is discouraged, the interactive docs with Swagger UI won't show the documentation for the body when using `GET`, and proxies in the middle might not support it.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/body.md", "symbol": "Request Body { #request-body }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body.md#L1-L20", "start_line": 1, "end_line": 20}
{"id": "docs/en/docs/tutorial/body.md::Import Pydantic's `BaseModel` { #import-pydantics-basemodel }::L21", "text": "# Doc: docs/en/docs/tutorial/body.md | Page: Request Body { #request-body } | Section: Import Pydantic's `BaseModel` { #import-pydantics-basemodel }\n## Import Pydantic's `BaseModel` { #import-pydantics-basemodel }\n\nFirst, you need to import `BaseModel` from `pydantic`:\n\n{* ../../docs_src/body/tutorial001_py310.py hl[2] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/body.md", "symbol": "Import Pydantic's `BaseModel` { #import-pydantics-basemodel }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body.md#L21-L26", "start_line": 21, "end_line": 26}
{"id": "docs/en/docs/tutorial/body.md::Create your data model { #create-your-data-model }::L27", "text": "# Doc: docs/en/docs/tutorial/body.md | Page: Request Body { #request-body } | Section: Create your data model { #create-your-data-model }\n## Create your data model { #create-your-data-model }\n\nThen you declare your data model as a class that inherits from `BaseModel`.\n\nUse standard Python types for all the attributes:\n\n{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *}\n\n\nThe same as when declaring query parameters, when a model attribute has a default value, it is not required. Otherwise, it is required. Use `None` to make it just optional.\n\nFor example, this model above declares a JSON \"`object`\" (or Python `dict`) like:\n\n```JSON\n{\n \"name\": \"Foo\",\n \"description\": \"An optional description\",\n \"price\": 45.2,\n \"tax\": 3.5\n}\n```\n\n...as `description` and `tax` are optional (with a default value of `None`), this JSON \"`object`\" would also be valid:\n\n```JSON\n{\n \"name\": \"Foo\",\n \"price\": 45.2\n}\n```", "source_type": "doc", "path": "docs/en/docs/tutorial/body.md", "symbol": "Create your data model { #create-your-data-model }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body.md#L27-L57", "start_line": 27, "end_line": 57}
{"id": "docs/en/docs/tutorial/body.md::Declare it as a parameter { #declare-it-as-a-parameter }::L58", "text": "# Doc: docs/en/docs/tutorial/body.md | Page: Request Body { #request-body } | Section: Declare it as a parameter { #declare-it-as-a-parameter }\n## Declare it as a parameter { #declare-it-as-a-parameter }\n\nTo add it to your *path operation*, declare it the same way you declared path and query parameters:\n\n{* ../../docs_src/body/tutorial001_py310.py hl[16] *}\n\n...and declare its type as the model you created, `Item`.", "source_type": "doc", "path": "docs/en/docs/tutorial/body.md", "symbol": "Declare it as a parameter { #declare-it-as-a-parameter }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body.md#L58-L65", "start_line": 58, "end_line": 65}
{"id": "docs/en/docs/tutorial/body.md::Results { #results }::L66", "text": "# Doc: docs/en/docs/tutorial/body.md | Page: Request Body { #request-body } | Section: Results { #results }\n## Results { #results }\n\nWith just that Python type declaration, **FastAPI** will:\n\n* Read the body of the request as JSON.\n* Convert the corresponding types (if needed).\n* Validate the data.\n * If the data is invalid, it will return a nice and clear error, indicating exactly where and what was the incorrect data.\n* Give you the received data in the parameter `item`.\n * As you declared it in the function to be of type `Item`, you will also have all the editor support (completion, etc) for all of the attributes and their types.\n* Generate [JSON Schema](https://json-schema.org) definitions for your model, you can also use them anywhere else you like if it makes sense for your project.\n* Those schemas will be part of the generated OpenAPI schema, and used by the automatic documentation UIs.", "source_type": "doc", "path": "docs/en/docs/tutorial/body.md", "symbol": "Results { #results }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body.md#L66-L78", "start_line": 66, "end_line": 78}
{"id": "docs/en/docs/tutorial/body.md::Automatic docs { #automatic-docs }::L79", "text": "# Doc: docs/en/docs/tutorial/body.md | Page: Request Body { #request-body } | Section: Automatic docs { #automatic-docs }\n## Automatic docs { #automatic-docs }\n\nThe JSON Schemas of your models will be part of your OpenAPI generated schema, and will be shown in the interactive API docs:\n\n![](\"/img/tutorial/body/image01.png\")
\n\nAnd will also be used in the API docs inside each *path operation* that needs them:\n\n![](\"/img/tutorial/body/image02.png\")
", "source_type": "doc", "path": "docs/en/docs/tutorial/body.md", "symbol": "Automatic docs { #automatic-docs }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body.md#L79-L88", "start_line": 79, "end_line": 88}
{"id": "docs/en/docs/tutorial/body.md::Editor support { #editor-support }::L89", "text": "# Doc: docs/en/docs/tutorial/body.md | Page: Request Body { #request-body } | Section: Editor support { #editor-support }\n## Editor support { #editor-support }\n\nIn your editor, inside your function you will get type hints and completion everywhere (this wouldn't happen if you received a `dict` instead of a Pydantic model):\n\n![](\"/img/tutorial/body/image03.png\")
\n\nYou also get error checks for incorrect type operations:\n\n![](\"/img/tutorial/body/image04.png\")
\n\nThis is not by chance, the whole framework was built around that design.\n\nAnd it was thoroughly tested at the design phase, before any implementation, to ensure it would work with all the editors.\n\nThere were even some changes to Pydantic itself to support this.\n\nThe previous screenshots were taken with [Visual Studio Code](https://code.visualstudio.com).\n\nBut you would get the same editor support with [PyCharm](https://www.jetbrains.com/pycharm/) and most of the other Python editors:\n\n![](\"/img/tutorial/body/image05.png\")
\n\n/// tip\n\nIf you use [PyCharm](https://www.jetbrains.com/pycharm/) as your editor, you can use the [Pydantic PyCharm Plugin](https://github.com/koxudaxi/pydantic-pycharm-plugin/).\n\nIt improves editor support for Pydantic models, with:\n\n* auto-completion\n* type checks\n* refactoring\n* searching\n* inspections\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/body.md", "symbol": "Editor support { #editor-support }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body.md#L89-L124", "start_line": 89, "end_line": 124}
{"id": "docs/en/docs/tutorial/body.md::Use the model { #use-the-model }::L125", "text": "# Doc: docs/en/docs/tutorial/body.md | Page: Request Body { #request-body } | Section: Use the model { #use-the-model }\n## Use the model { #use-the-model }\n\nInside of the function, you can access all the attributes of the model object directly:\n\n{* ../../docs_src/body/tutorial002_py310.py *}", "source_type": "doc", "path": "docs/en/docs/tutorial/body.md", "symbol": "Use the model { #use-the-model }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body.md#L125-L130", "start_line": 125, "end_line": 130}
{"id": "docs/en/docs/tutorial/body.md::Request body + path parameters { #request-body-path-parameters }::L131", "text": "# Doc: docs/en/docs/tutorial/body.md | Page: Request Body { #request-body } | Section: Request body + path parameters { #request-body-path-parameters }\n## Request body + path parameters { #request-body-path-parameters }\n\nYou can declare path parameters and request body at the same time.\n\n**FastAPI** will recognize that the function parameters that match path parameters should be **taken from the path**, and that function parameters that are declared to be Pydantic models should be **taken from the request body**.\n\n{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/body.md", "symbol": "Request body + path parameters { #request-body-path-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body.md#L131-L139", "start_line": 131, "end_line": 139}
{"id": "docs/en/docs/tutorial/body.md::Request body + path + query parameters { #request-body-path-query-parameters }::L140", "text": "# Doc: docs/en/docs/tutorial/body.md | Page: Request Body { #request-body } | Section: Request body + path + query parameters { #request-body-path-query-parameters }\n## Request body + path + query parameters { #request-body-path-query-parameters }\n\nYou can also declare **body**, **path** and **query** parameters, all at the same time.\n\n**FastAPI** will recognize each of them and take the data from the correct place.\n\n{* ../../docs_src/body/tutorial004_py310.py hl[16] *}\n\nThe function parameters will be recognized as follows:\n\n* If the parameter is also declared in the **path**, it will be used as a path parameter.\n* If the parameter is of a **singular type** (like `int`, `float`, `str`, `bool`, etc) it will be interpreted as a **query** parameter.\n* If the parameter is declared to be of the type of a **Pydantic model**, it will be interpreted as a request **body**.\n\n/// note\n\nFastAPI will know that the value of `q` is not required because of the default value `= None`.\n\nThe `str | None` is not used by FastAPI to determine that the value is not required, it will know it's not required because it has a default value of `= None`.\n\nBut adding the type annotations will allow your editor to give you better support and detect errors.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/body.md", "symbol": "Request body + path + query parameters { #request-body-path-query-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body.md#L140-L163", "start_line": 140, "end_line": 163}
{"id": "docs/en/docs/tutorial/body.md::Without Pydantic { #without-pydantic }::L164", "text": "# Doc: docs/en/docs/tutorial/body.md | Page: Request Body { #request-body } | Section: Without Pydantic { #without-pydantic }\n## Without Pydantic { #without-pydantic }\n\nIf you don't want to use Pydantic models, you can also use **Body** parameters. See the docs for [Body - Multiple Parameters: Singular values in body](body-multiple-params.md#singular-values-in-body).", "source_type": "doc", "path": "docs/en/docs/tutorial/body.md", "symbol": "Without Pydantic { #without-pydantic }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/body.md#L164-L166", "start_line": 164, "end_line": 166}
{"id": "docs/en/docs/tutorial/cookie-param-models.md::Cookie Parameter Models { #cookie-parameter-models }::L1", "text": "# Doc: docs/en/docs/tutorial/cookie-param-models.md | Page: Cookie Parameter Models { #cookie-parameter-models } | Section: Cookie Parameter Models { #cookie-parameter-models }\n# Cookie Parameter Models { #cookie-parameter-models }\n\nIf you have a group of **cookies** that are related, you can create a **Pydantic model** to declare them. 🍪\n\nThis would allow you to **re-use the model** in **multiple places** and also to declare validations and metadata for all the parameters at once. 😎\n\n/// note\n\nThis is supported since FastAPI version `0.115.0`. 🤓\n\n///\n\n/// tip\n\nThis same technique applies to `Query`, `Cookie`, and `Header`. 😎\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/cookie-param-models.md", "symbol": "Cookie Parameter Models { #cookie-parameter-models }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/cookie-param-models.md#L1-L18", "start_line": 1, "end_line": 18}
{"id": "docs/en/docs/tutorial/cookie-param-models.md::Cookies with a Pydantic Model { #cookies-with-a-pydantic-model }::L19", "text": "# Doc: docs/en/docs/tutorial/cookie-param-models.md | Page: Cookie Parameter Models { #cookie-parameter-models } | Section: Cookies with a Pydantic Model { #cookies-with-a-pydantic-model }\n## Cookies with a Pydantic Model { #cookies-with-a-pydantic-model }\n\nDeclare the **cookie** parameters that you need in a **Pydantic model**, and then declare the parameter as `Cookie`:\n\n{* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *}\n\n**FastAPI** will **extract** the data for **each field** from the **cookies** received in the request and give you the Pydantic model you defined.", "source_type": "doc", "path": "docs/en/docs/tutorial/cookie-param-models.md", "symbol": "Cookies with a Pydantic Model { #cookies-with-a-pydantic-model }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/cookie-param-models.md#L19-L26", "start_line": 19, "end_line": 26}
{"id": "docs/en/docs/tutorial/cookie-param-models.md::Check the Docs { #check-the-docs }::L27", "text": "# Doc: docs/en/docs/tutorial/cookie-param-models.md | Page: Cookie Parameter Models { #cookie-parameter-models } | Section: Check the Docs { #check-the-docs }\n## Check the Docs { #check-the-docs }\n\nYou can see the defined cookies in the docs UI at `/docs`:\n\n![](\"/img/tutorial/cookie-param-models/image01.png\")
\n![](\"/img/tutorial/debugging/image01.png\")
\n\n---\n\nIf you use PyCharm, you can:\n\n* Open the \"Run\" menu.\n* Select the option \"Debug...\".\n* Then a context menu shows up.\n* Select the file to debug (in this case, `main.py`).\n\nIt will then start the server with your **FastAPI** code, stop at your breakpoints, etc.\n\nHere's how it might look:\n\n![](\"/img/tutorial/debugging/image02.png\")
", "source_type": "doc", "path": "docs/en/docs/tutorial/debugging.md", "symbol": "Run your code with your debugger { #run-your-code-with-your-debugger }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/debugging.md#L81-L113", "start_line": 81, "end_line": 113}
{"id": "docs/en/docs/tutorial/dependencies/classes-as-dependencies.md::Classes as Dependencies { #classes-as-dependencies }::L1", "text": "# Doc: docs/en/docs/tutorial/dependencies/classes-as-dependencies.md | Page: Classes as Dependencies { #classes-as-dependencies } | Section: Classes as Dependencies { #classes-as-dependencies }\n# Classes as Dependencies { #classes-as-dependencies }\n\nBefore diving deeper into the **Dependency Injection** system, let's upgrade the previous example.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/classes-as-dependencies.md", "symbol": "Classes as Dependencies { #classes-as-dependencies }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md#L1-L4", "start_line": 1, "end_line": 4}
{"id": "docs/en/docs/tutorial/dependencies/classes-as-dependencies.md::A `dict` from the previous example { #a-dict-from-the-previous-example }::L5", "text": "# Doc: docs/en/docs/tutorial/dependencies/classes-as-dependencies.md | Page: Classes as Dependencies { #classes-as-dependencies } | Section: A `dict` from the previous example { #a-dict-from-the-previous-example }\n## A `dict` from the previous example { #a-dict-from-the-previous-example }\n\nIn the previous example, we were returning a `dict` from our dependency (\"dependable\"):\n\n{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[9] *}\n\nBut then we get a `dict` in the parameter `commons` of the *path operation function*.\n\nAnd we know that editors can't provide a lot of support (like completion) for `dict`s, because they can't know their keys and value types.\n\nWe can do better...", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/classes-as-dependencies.md", "symbol": "A `dict` from the previous example { #a-dict-from-the-previous-example }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md#L5-L16", "start_line": 5, "end_line": 16}
{"id": "docs/en/docs/tutorial/dependencies/classes-as-dependencies.md::What makes a dependency { #what-makes-a-dependency }::L17", "text": "# Doc: docs/en/docs/tutorial/dependencies/classes-as-dependencies.md | Page: Classes as Dependencies { #classes-as-dependencies } | Section: What makes a dependency { #what-makes-a-dependency }\n## What makes a dependency { #what-makes-a-dependency }\n\nUp to now you have seen dependencies declared as functions.\n\nBut that's not the only way to declare dependencies (although it would probably be the more common).\n\nThe key factor is that a dependency should be a \"callable\".\n\nA \"**callable**\" in Python is anything that Python can \"call\" like a function.\n\nSo, if you have an object `something` (that might _not_ be a function) and you can \"call\" it (execute it) like:\n\n```Python\nsomething()\n```\n\nor\n\n```Python\nsomething(some_argument, some_keyword_argument=\"foo\")\n```\n\nthen it is a \"callable\".", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/classes-as-dependencies.md", "symbol": "What makes a dependency { #what-makes-a-dependency }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md#L17-L40", "start_line": 17, "end_line": 40}
{"id": "docs/en/docs/tutorial/dependencies/classes-as-dependencies.md::Classes as dependencies { #classes-as-dependencies_1 }::L41", "text": "# Doc: docs/en/docs/tutorial/dependencies/classes-as-dependencies.md | Page: Classes as Dependencies { #classes-as-dependencies } | Section: Classes as dependencies { #classes-as-dependencies_1 }\n## Classes as dependencies { #classes-as-dependencies_1 }\n\nYou might notice that to create an instance of a Python class, you use that same syntax.\n\nFor example:\n\n```Python\nclass Cat:\n def __init__(self, name: str):\n self.name = name\n\n\nfluffy = Cat(name=\"Mr Fluffy\")\n```\n\nIn this case, `fluffy` is an instance of the class `Cat`.\n\nAnd to create `fluffy`, you are \"calling\" `Cat`.\n\nSo, a Python class is also a **callable**.\n\nThen, in **FastAPI**, you could use a Python class as a dependency.\n\nWhat FastAPI actually checks is that it is a \"callable\" (function, class or anything else) and the parameters defined.\n\nIf you pass a \"callable\" as a dependency in **FastAPI**, it will analyze the parameters for that \"callable\", and process them in the same way as the parameters for a *path operation function*. Including sub-dependencies.\n\nThat also applies to callables with no parameters at all. The same as it would be for *path operation functions* with no parameters.\n\nThen, we can change the dependency \"dependable\" `common_parameters` from above to the class `CommonQueryParams`:\n\n{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[11:15] *}\n\nPay attention to the `__init__` method used to create the instance of the class:\n\n{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[12] *}\n\n...it has the same parameters as our previous `common_parameters`:\n\n{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[8] *}\n\nThose parameters are what **FastAPI** will use to \"solve\" the dependency.\n\nIn both cases, it will have:\n\n* An optional `q` query parameter that is a `str`.\n* A `skip` query parameter that is an `int`, with a default of `0`.\n* A `limit` query parameter that is an `int`, with a default of `100`.\n\nIn both cases the data will be converted, validated, documented on the OpenAPI schema, etc.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/classes-as-dependencies.md", "symbol": "Classes as dependencies { #classes-as-dependencies_1 }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md#L41-L91", "start_line": 41, "end_line": 91}
{"id": "docs/en/docs/tutorial/dependencies/classes-as-dependencies.md::Use it { #use-it }::L92", "text": "# Doc: docs/en/docs/tutorial/dependencies/classes-as-dependencies.md | Page: Classes as Dependencies { #classes-as-dependencies } | Section: Use it { #use-it }\n## Use it { #use-it }\n\nNow you can declare your dependency using this class.\n\n{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[19] *}\n\n**FastAPI** calls the `CommonQueryParams` class. This creates an \"instance\" of that class and the instance will be passed as the parameter `commons` to your function.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/classes-as-dependencies.md", "symbol": "Use it { #use-it }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md#L92-L99", "start_line": 92, "end_line": 99}
{"id": "docs/en/docs/tutorial/dependencies/classes-as-dependencies.md::Type annotation vs `Depends` { #type-annotation-vs-depends }::L100", "text": "# Doc: docs/en/docs/tutorial/dependencies/classes-as-dependencies.md | Page: Classes as Dependencies { #classes-as-dependencies } | Section: Type annotation vs `Depends` { #type-annotation-vs-depends }\n## Type annotation vs `Depends` { #type-annotation-vs-depends }\n\nNotice how we write `CommonQueryParams` twice in the above code:\n\n//// tab | Python 3.10+\n\n```Python\ncommons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]\n```\n\n////\n\n//// tab | Python 3.10+ non-Annotated\n\n/// tip\n\nPrefer to use the `Annotated` version if possible.\n\n///\n\n```Python\ncommons: CommonQueryParams = Depends(CommonQueryParams)\n```\n\n////\n\nThe last `CommonQueryParams`, in:\n\n```Python\n... Depends(CommonQueryParams)\n```\n\n...is what **FastAPI** will actually use to know what is the dependency.\n\nIt is from this one that FastAPI will extract the declared parameters and that is what FastAPI will actually call.\n\n---\n\nIn this case, the first `CommonQueryParams`, in:\n\n//// tab | Python 3.10+\n\n```Python\ncommons: Annotated[CommonQueryParams, ...\n```\n\n////\n\n//// tab | Python 3.10+ non-Annotated\n\n/// tip\n\nPrefer to use the `Annotated` version if possible.\n\n///\n\n```Python\ncommons: CommonQueryParams ...\n```\n\n////\n\n...doesn't have any special meaning for **FastAPI**. FastAPI won't use it for data conversion, validation, etc. (as it is using the `Depends(CommonQueryParams)` for that).\n\nYou could actually write just:\n\n//// tab | Python 3.10+\n\n```Python\ncommons: Annotated[Any, Depends(CommonQueryParams)]\n```\n\n////\n\n//// tab | Python 3.10+ non-Annotated\n\n/// tip\n\nPrefer to use the `Annotated` version if possible.\n\n///\n\n```Python\ncommons = Depends(CommonQueryParams)\n```\n\n////\n\n...as in:\n\n{* ../../docs_src/dependencies/tutorial003_an_py310.py hl[19] *}\n\nBut declaring the type is encouraged as that way your editor will know what will be passed as the parameter `commons`, and then it can help you with code completion, type checks, etc:\n\n![](\"/img/tutorial/dependencies/image02.png\")
", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/classes-as-dependencies.md", "symbol": "Type annotation vs `Depends` { #type-annotation-vs-depends }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md#L100-L195", "start_line": 100, "end_line": 195}
{"id": "docs/en/docs/tutorial/dependencies/classes-as-dependencies.md::Shortcut { #shortcut }::L196", "text": "# Doc: docs/en/docs/tutorial/dependencies/classes-as-dependencies.md | Page: Classes as Dependencies { #classes-as-dependencies } | Section: Shortcut { #shortcut }\n## Shortcut { #shortcut }\n\nBut you see that we are having some code repetition here, writing `CommonQueryParams` twice:\n\n//// tab | Python 3.10+\n\n```Python\ncommons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]\n```\n\n////\n\n//// tab | Python 3.10+ non-Annotated\n\n/// tip\n\nPrefer to use the `Annotated` version if possible.\n\n///\n\n```Python\ncommons: CommonQueryParams = Depends(CommonQueryParams)\n```\n\n////\n\n**FastAPI** provides a shortcut for these cases, in where the dependency is *specifically* a class that **FastAPI** will \"call\" to create an instance of the class itself.\n\nFor those specific cases, you can do the following:\n\nInstead of writing:\n\n//// tab | Python 3.10+\n\n```Python\ncommons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]\n```\n\n////\n\n//// tab | Python 3.10+ non-Annotated\n\n/// tip\n\nPrefer to use the `Annotated` version if possible.\n\n///\n\n```Python\ncommons: CommonQueryParams = Depends(CommonQueryParams)\n```\n\n////\n\n...you write:\n\n//// tab | Python 3.10+\n\n```Python\ncommons: Annotated[CommonQueryParams, Depends()]\n```\n\n////\n\n//// tab | Python 3.10+ non-Annotated\n\n/// tip\n\nPrefer to use the `Annotated` version if possible.\n\n///\n\n```Python\ncommons: CommonQueryParams = Depends()\n```\n\n////\n\nYou declare the dependency as the type of the parameter, and you use `Depends()` without any parameter, instead of having to write the full class *again* inside of `Depends(CommonQueryParams)`.\n\nThe same example would then look like:\n\n{* ../../docs_src/dependencies/tutorial004_an_py310.py hl[19] *}\n\n...and **FastAPI** will know what to do.\n\n/// tip\n\nIf that seems more confusing than helpful, disregard it, you don't *need* it.\n\nIt is just a shortcut. Because **FastAPI** cares about helping you minimize code repetition.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/classes-as-dependencies.md", "symbol": "Shortcut { #shortcut }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md#L196-L288", "start_line": 196, "end_line": 288}
{"id": "docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md::Dependencies in path operation decorators { #dependencies-in-path-operation-decorators }::L1", "text": "# Doc: docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md | Page: Dependencies in path operation decorators { #dependencies-in-path-operation-decorators } | Section: Dependencies in path operation decorators { #dependencies-in-path-operation-decorators }\n# Dependencies in path operation decorators { #dependencies-in-path-operation-decorators }\n\nIn some cases you don't really need the return value of a dependency inside your *path operation function*.\n\nOr the dependency doesn't return a value.\n\nBut you still need it to be executed/solved.\n\nFor those cases, instead of declaring a *path operation function* parameter with `Depends`, you can add a `list` of `dependencies` to the *path operation decorator*.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md", "symbol": "Dependencies in path operation decorators { #dependencies-in-path-operation-decorators }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md#L1-L10", "start_line": 1, "end_line": 10}
{"id": "docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md::Add `dependencies` to the *path operation decorator* { #add-dependencies-to-the-path-operation-decorator }::L11", "text": "# Doc: docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md | Page: Dependencies in path operation decorators { #dependencies-in-path-operation-decorators } | Section: Add `dependencies` to the *path operation decorator* { #add-dependencies-to-the-path-operation-decorator }\n## Add `dependencies` to the *path operation decorator* { #add-dependencies-to-the-path-operation-decorator }\n\nThe *path operation decorator* receives an optional argument `dependencies`.\n\nIt should be a `list` of `Depends()`:\n\n{* ../../docs_src/dependencies/tutorial006_an_py310.py hl[19] *}\n\nThese dependencies will be executed/solved the same way as normal dependencies. But their value (if they return any) won't be passed to your *path operation function*.\n\n/// tip\n\nSome editors check for unused function parameters, and show them as errors.\n\nUsing these `dependencies` in the *path operation decorator* you can make sure they are executed while avoiding editor/tooling errors.\n\nIt might also help avoid confusion for new developers that see an unused parameter in your code and could think it's unnecessary.\n\n///\n\n/// note\n\nIn this example we use invented custom headers `X-Key` and `X-Token`.\n\nBut in real cases, when implementing security, you would get more benefits from using the integrated [Security utilities (the next chapter)](../security/index.md).\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md", "symbol": "Add `dependencies` to the *path operation decorator* { #add-dependencies-to-the-path-operation-decorator }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md#L11-L38", "start_line": 11, "end_line": 38}
{"id": "docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md::Dependencies errors and return values { #dependencies-errors-and-return-values }::L39", "text": "# Doc: docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md | Page: Dependencies in path operation decorators { #dependencies-in-path-operation-decorators } | Section: Dependencies errors and return values { #dependencies-errors-and-return-values }\n## Dependencies errors and return values { #dependencies-errors-and-return-values }\n\nYou can use the same dependency *functions* you use normally.\n\n### Dependency requirements { #dependency-requirements }\n\nThey can declare request requirements (like headers) or other sub-dependencies:\n\n{* ../../docs_src/dependencies/tutorial006_an_py310.py hl[8,13] *}\n\n### Raise exceptions { #raise-exceptions }\n\nThese dependencies can `raise` exceptions, the same as normal dependencies:\n\n{* ../../docs_src/dependencies/tutorial006_an_py310.py hl[10,15] *}\n\n### Return values { #return-values }\n\nAnd they can return values or not, the values won't be used.\n\nSo, you can reuse a normal dependency (that returns a value) you already use somewhere else, and even though the value won't be used, the dependency will be executed:\n\n{* ../../docs_src/dependencies/tutorial006_an_py310.py hl[11,16] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md", "symbol": "Dependencies errors and return values { #dependencies-errors-and-return-values }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md#L39-L62", "start_line": 39, "end_line": 62}
{"id": "docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md::Dependencies for a group of *path operations* { #dependencies-for-a-group-of-path-operations }::L63", "text": "# Doc: docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md | Page: Dependencies in path operation decorators { #dependencies-in-path-operation-decorators } | Section: Dependencies for a group of *path operations* { #dependencies-for-a-group-of-path-operations }\n## Dependencies for a group of *path operations* { #dependencies-for-a-group-of-path-operations }\n\nLater, when reading about how to structure bigger applications ([Bigger Applications - Multiple Files](../../tutorial/bigger-applications.md)), possibly with multiple files, you will learn how to declare a single `dependencies` parameter for a group of *path operations*.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md", "symbol": "Dependencies for a group of *path operations* { #dependencies-for-a-group-of-path-operations }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md#L63-L66", "start_line": 63, "end_line": 66}
{"id": "docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md::Global Dependencies { #global-dependencies }::L67", "text": "# Doc: docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md | Page: Dependencies in path operation decorators { #dependencies-in-path-operation-decorators } | Section: Global Dependencies { #global-dependencies }\n## Global Dependencies { #global-dependencies }\n\nNext we will see how to add dependencies to the whole `FastAPI` application, so that they apply to each *path operation*.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md", "symbol": "Global Dependencies { #global-dependencies }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md#L67-L69", "start_line": 67, "end_line": 69}
{"id": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md::Dependencies with yield { #dependencies-with-yield }::L1", "text": "# Doc: docs/en/docs/tutorial/dependencies/dependencies-with-yield.md | Page: Dependencies with yield { #dependencies-with-yield } | Section: Dependencies with yield { #dependencies-with-yield }\n# Dependencies with yield { #dependencies-with-yield }\n\nFastAPI supports dependencies that do some extra steps after finishing.\n\nTo do this, use `yield` instead of `return`, and write the extra steps (code) after.\n\n/// tip\n\nMake sure to use `yield` one single time per dependency.\n\n///\n\n/// note | Technical Details\n\nAny function that is valid to use with:\n\n* [`@contextlib.contextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager) or\n* [`@contextlib.asynccontextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.asynccontextmanager)\n\nwould be valid to use as a **FastAPI** dependency.\n\nIn fact, FastAPI uses those two decorators internally.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md", "symbol": "Dependencies with yield { #dependencies-with-yield }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md#L1-L25", "start_line": 1, "end_line": 25}
{"id": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md::A database dependency with `yield` { #a-database-dependency-with-yield }::L26", "text": "# Doc: docs/en/docs/tutorial/dependencies/dependencies-with-yield.md | Page: Dependencies with yield { #dependencies-with-yield } | Section: A database dependency with `yield` { #a-database-dependency-with-yield }\n## A database dependency with `yield` { #a-database-dependency-with-yield }\n\nFor example, you could use this to create a database session and close it after finishing.\n\nOnly the code prior to and including the `yield` statement is executed before creating a response:\n\n{* ../../docs_src/dependencies/tutorial007_py310.py hl[2:4] *}\n\nThe yielded value is what is injected into *path operations* and other dependencies:\n\n{* ../../docs_src/dependencies/tutorial007_py310.py hl[4] *}\n\nThe code following the `yield` statement is executed after the response:\n\n{* ../../docs_src/dependencies/tutorial007_py310.py hl[5:6] *}\n\n/// tip\n\nYou can use `async` or regular functions.\n\n**FastAPI** will do the right thing with each, the same as with normal dependencies.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md", "symbol": "A database dependency with `yield` { #a-database-dependency-with-yield }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md#L26-L49", "start_line": 26, "end_line": 49}
{"id": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md::A dependency with `yield` and `try` { #a-dependency-with-yield-and-try }::L50", "text": "# Doc: docs/en/docs/tutorial/dependencies/dependencies-with-yield.md | Page: Dependencies with yield { #dependencies-with-yield } | Section: A dependency with `yield` and `try` { #a-dependency-with-yield-and-try }\n## A dependency with `yield` and `try` { #a-dependency-with-yield-and-try }\n\nIf you use a `try` block in a dependency with `yield`, you'll receive any exception that was thrown when using the dependency.\n\nFor example, if some code at some point in the middle, in another dependency or in a *path operation*, made a database transaction \"rollback\" or created any other exception, you would receive the exception in your dependency.\n\nSo, you can look for that specific exception inside the dependency with `except SomeException`.\n\nIn the same way, you can use `finally` to make sure the exit steps are executed, no matter if there was an exception or not.\n\n{* ../../docs_src/dependencies/tutorial007_py310.py hl[3,5] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md", "symbol": "A dependency with `yield` and `try` { #a-dependency-with-yield-and-try }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md#L50-L61", "start_line": 50, "end_line": 61}
{"id": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md::Sub-dependencies with `yield` { #sub-dependencies-with-yield }::L62", "text": "# Doc: docs/en/docs/tutorial/dependencies/dependencies-with-yield.md | Page: Dependencies with yield { #dependencies-with-yield } | Section: Sub-dependencies with `yield` { #sub-dependencies-with-yield }\n## Sub-dependencies with `yield` { #sub-dependencies-with-yield }\n\nYou can have sub-dependencies and \"trees\" of sub-dependencies of any size and shape, and any or all of them can use `yield`.\n\n**FastAPI** will make sure that the \"exit code\" in each dependency with `yield` is run in the correct order.\n\nFor example, `dependency_c` can have a dependency on `dependency_b`, and `dependency_b` on `dependency_a`:\n\n{* ../../docs_src/dependencies/tutorial008_an_py310.py hl[6,14,22] *}\n\nAnd all of them can use `yield`.\n\nIn this case `dependency_c`, to execute its exit code, needs the value from `dependency_b` (here named `dep_b`) to still be available.\n\nAnd, in turn, `dependency_b` needs the value from `dependency_a` (here named `dep_a`) to be available for its exit code.\n\n{* ../../docs_src/dependencies/tutorial008_an_py310.py hl[18:19,26:27] *}\n\nThe same way, you could have some dependencies with `yield` and some other dependencies with `return`, and have some of those depend on some of the others.\n\nAnd you could have a single dependency that requires several other dependencies with `yield`, etc.\n\nYou can have any combinations of dependencies that you want.\n\n**FastAPI** will make sure everything is run in the correct order.\n\n/// note | Technical Details\n\nThis works thanks to Python's [Context Managers](https://docs.python.org/3/library/contextlib.html).\n\n**FastAPI** uses them internally to achieve this.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md", "symbol": "Sub-dependencies with `yield` { #sub-dependencies-with-yield }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md#L62-L95", "start_line": 62, "end_line": 95}
{"id": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md::Dependencies with `yield` and `HTTPException` { #dependencies-with-yield-and-httpexception }::L96", "text": "# Doc: docs/en/docs/tutorial/dependencies/dependencies-with-yield.md | Page: Dependencies with yield { #dependencies-with-yield } | Section: Dependencies with `yield` and `HTTPException` { #dependencies-with-yield-and-httpexception }\n## Dependencies with `yield` and `HTTPException` { #dependencies-with-yield-and-httpexception }\n\nYou saw that you can use dependencies with `yield` and have `try` blocks that try to execute some code and then run some exit code after `finally`.\n\nYou can also use `except` to catch the exception that was raised and do something with it.\n\nFor example, you can raise a different exception, like `HTTPException`.\n\n/// tip\n\nThis is a somewhat advanced technique, and in most of the cases you won't really need it, as you can raise exceptions (including `HTTPException`) from inside of the rest of your application code, for example, in the *path operation function*.\n\nBut it's there for you if you need it. 🤓\n\n///\n\n{* ../../docs_src/dependencies/tutorial008b_an_py310.py hl[18:22,31] *}\n\nIf you want to catch exceptions and create a custom response based on that, create a [Custom Exception Handler](../handling-errors.md#install-custom-exception-handlers).", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md", "symbol": "Dependencies with `yield` and `HTTPException` { #dependencies-with-yield-and-httpexception }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md#L96-L115", "start_line": 96, "end_line": 115}
{"id": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md::Dependencies with `yield` and `except` { #dependencies-with-yield-and-except }::L116", "text": "# Doc: docs/en/docs/tutorial/dependencies/dependencies-with-yield.md | Page: Dependencies with yield { #dependencies-with-yield } | Section: Dependencies with `yield` and `except` { #dependencies-with-yield-and-except }\n## Dependencies with `yield` and `except` { #dependencies-with-yield-and-except }\n\nIf you catch an exception using `except` in a dependency with `yield` and you don't raise it again (or raise a new exception), FastAPI won't be able to notice there was an exception, the same way that would happen with regular Python:\n\n{* ../../docs_src/dependencies/tutorial008c_an_py310.py hl[15:16] *}\n\nIn this case, the client will see an *HTTP 500 Internal Server Error* response as it should, given that we are not raising an `HTTPException` or similar, but the server will **not have any logs** or any other indication of what was the error. 😱\n\n### Always `raise` in Dependencies with `yield` and `except` { #always-raise-in-dependencies-with-yield-and-except }\n\nIf you catch an exception in a dependency with `yield`, unless you are raising another `HTTPException` or similar, **you should re-raise the original exception**.\n\nYou can re-raise the same exception using `raise`:\n\n{* ../../docs_src/dependencies/tutorial008d_an_py310.py hl[17] *}\n\nNow the client will get the same *HTTP 500 Internal Server Error* response, but the server will have our custom `InternalError` in the logs. 😎", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md", "symbol": "Dependencies with `yield` and `except` { #dependencies-with-yield-and-except }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md#L116-L133", "start_line": 116, "end_line": 133}
{"id": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md::Execution of dependencies with `yield` { #execution-of-dependencies-with-yield }::L134", "text": "# Doc: docs/en/docs/tutorial/dependencies/dependencies-with-yield.md | Page: Dependencies with yield { #dependencies-with-yield } | Section: Execution of dependencies with `yield` { #execution-of-dependencies-with-yield }\n## Execution of dependencies with `yield` { #execution-of-dependencies-with-yield }\n\nThe sequence of execution is more or less like this diagram. Time flows from top to bottom. And each column is one of the parts interacting or executing code.\n\n```mermaid\nsequenceDiagram\n\nparticipant client as Client\nparticipant handler as Exception handler\nparticipant dep as Dep with yield\nparticipant operation as Path Operation\nparticipant tasks as Background tasks\n\n Note over client,operation: Can raise exceptions, including HTTPException\n client ->> dep: Start request\n Note over dep: Run code up to yield\n opt raise Exception\n dep -->> handler: Raise Exception\n handler -->> client: HTTP error response\n end\n dep ->> operation: Run dependency, e.g. DB session\n opt raise\n operation -->> dep: Raise Exception (e.g. HTTPException)\n opt handle\n dep -->> dep: Can catch exception, raise a new HTTPException, raise other exception\n end\n handler -->> client: HTTP error response\n end\n\n operation ->> client: Return response to client\n Note over client,operation: Response is already sent, can't change it anymore\n opt Tasks\n operation -->> tasks: Send background tasks\n end\n opt Raise other exception\n tasks -->> tasks: Handle exceptions in the background task code\n end\n```\n\n/// note\n\nOnly **one response** will be sent to the client. It might be one of the error responses or it will be the response from the *path operation*.\n\nAfter one of those responses is sent, no other response can be sent.\n\n///\n\n/// tip\n\nIf you raise any exception in the code from the *path operation function*, it will be passed to the dependencies with yield, including `HTTPException`. In most cases you will want to re-raise that same exception or a new one from the dependency with `yield` to make sure it's properly handled.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md", "symbol": "Execution of dependencies with `yield` { #execution-of-dependencies-with-yield }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md#L134-L186", "start_line": 134, "end_line": 186}
{"id": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md::Early exit and `scope` { #early-exit-and-scope }::L187", "text": "# Doc: docs/en/docs/tutorial/dependencies/dependencies-with-yield.md | Page: Dependencies with yield { #dependencies-with-yield } | Section: Early exit and `scope` { #early-exit-and-scope }\n## Early exit and `scope` { #early-exit-and-scope }\n\nNormally the exit code of dependencies with `yield` is executed **after the response** is sent to the client.\n\nBut if you know that you won't need to use the dependency after returning from the *path operation function*, you can use `Depends(scope=\"function\")` to tell FastAPI that it should close the dependency after the *path operation function* returns, but **before** the **response is sent**.\n\n{* ../../docs_src/dependencies/tutorial008e_an_py310.py hl[12,16] *}\n\n`Depends()` receives a `scope` parameter that can be:\n\n* `\"function\"`: start the dependency before the *path operation function* that handles the request, end the dependency after the *path operation function* ends, but **before** the response is sent back to the client. So, the dependency function will be executed **around** the *path operation **function***.\n* `\"request\"`: start the dependency before the *path operation function* that handles the request (similar to when using `\"function\"`), but end **after** the response is sent back to the client. So, the dependency function will be executed **around** the **request** and response cycle.\n\nIf not specified and the dependency has `yield`, it will have a `scope` of `\"request\"` by default.\n\n### `scope` for sub-dependencies { #scope-for-sub-dependencies }\n\nWhen you declare a dependency with a `scope=\"request\"` (the default), any sub-dependency needs to also have a `scope` of `\"request\"`.\n\nBut a dependency with `scope` of `\"function\"` can have dependencies with `scope` of `\"function\"` and `scope` of `\"request\"`.\n\nThis is because any dependency needs to be able to run its exit code before the sub-dependencies, as it might need to still use them during its exit code.\n\n```mermaid\nsequenceDiagram\n\nparticipant client as Client\nparticipant dep_req as Dep scope=\"request\"\nparticipant dep_func as Dep scope=\"function\"\nparticipant operation as Path Operation\n\n client ->> dep_req: Start request\n Note over dep_req: Run code up to yield\n dep_req ->> dep_func: Pass dependency\n Note over dep_func: Run code up to yield\n dep_func ->> operation: Run path operation with dependency\n operation ->> dep_func: Return from path operation\n Note over dep_func: Run code after yield\n Note over dep_func: ✅ Dependency closed\n dep_func ->> client: Send response to client\n Note over client: Response sent\n Note over dep_req: Run code after yield\n Note over dep_req: ✅ Dependency closed\n```", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md", "symbol": "Early exit and `scope` { #early-exit-and-scope }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md#L187-L231", "start_line": 187, "end_line": 231}
{"id": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md::Dependencies with `yield`, `HTTPException`, `except` and Background Tasks { #dependencies-with-yield-httpexception-except-and-background-tasks }::L232", "text": "# Doc: docs/en/docs/tutorial/dependencies/dependencies-with-yield.md | Page: Dependencies with yield { #dependencies-with-yield } | Section: Dependencies with `yield`, `HTTPException`, `except` and Background Tasks { #dependencies-with-yield-httpexception-except-and-background-tasks }\n## Dependencies with `yield`, `HTTPException`, `except` and Background Tasks { #dependencies-with-yield-httpexception-except-and-background-tasks }\n\nDependencies with `yield` have evolved over time to cover different use cases and fix some issues.\n\nIf you want to see what has changed in different versions of FastAPI, you can read more about it in the advanced guide, in [Advanced Dependencies - Dependencies with `yield`, `HTTPException`, `except` and Background Tasks](../../advanced/advanced-dependencies.md#dependencies-with-yield-httpexception-except-and-background-tasks).", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md", "symbol": "Dependencies with `yield`, `HTTPException`, `except` and Background Tasks { #dependencies-with-yield-httpexception-except-and-background-tasks }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md#L232-L237", "start_line": 232, "end_line": 237}
{"id": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md::Context Managers { #context-managers }::L238", "text": "# Doc: docs/en/docs/tutorial/dependencies/dependencies-with-yield.md | Page: Dependencies with yield { #dependencies-with-yield } | Section: Context Managers { #context-managers }\n## Context Managers { #context-managers }\n\n### What are \"Context Managers\" { #what-are-context-managers }\n\n\"Context Managers\" are any of those Python objects that you can use in a `with` statement.\n\nFor example, [you can use `with` to read a file](https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files):\n\n```Python\nwith open(\"./somefile.txt\") as f:\n contents = f.read()\n print(contents)\n```\n\nUnderneath, the `open(\"./somefile.txt\")` creates an object that is called a \"Context Manager\".\n\nWhen the `with` block finishes, it makes sure to close the file, even if there were exceptions.\n\nWhen you create a dependency with `yield`, **FastAPI** will internally create a context manager for it, and combine it with some other related tools.\n\n### Using context managers in dependencies with `yield` { #using-context-managers-in-dependencies-with-yield }\n\n/// warning\n\nThis is, more or less, an \"advanced\" idea.\n\nIf you are just starting with **FastAPI** you might want to skip it for now.\n\n///\n\nIn Python, you can create Context Managers by [creating a class with two methods: `__enter__()` and `__exit__()`](https://docs.python.org/3/reference/datamodel.html#context-managers).\n\nYou can also use them inside of **FastAPI** dependencies with `yield` by using\n`with` or `async with` statements inside of the dependency function:\n\n{* ../../docs_src/dependencies/tutorial010_py310.py hl[1:9,13] *}\n\n/// tip\n\nAnother way to create a context manager is with:\n\n* [`@contextlib.contextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager) or\n* [`@contextlib.asynccontextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.asynccontextmanager)\n\nusing them to decorate a function with a single `yield`.\n\nThat's what **FastAPI** uses internally for dependencies with `yield`.\n\nBut you don't have to use the decorators for FastAPI dependencies (and you shouldn't).\n\nFastAPI will do it for you internally.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/dependencies-with-yield.md", "symbol": "Context Managers { #context-managers }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md#L238-L290", "start_line": 238, "end_line": 290}
{"id": "docs/en/docs/tutorial/dependencies/global-dependencies.md::Global Dependencies { #global-dependencies }::L1", "text": "# Doc: docs/en/docs/tutorial/dependencies/global-dependencies.md | Page: Global Dependencies { #global-dependencies } | Section: Global Dependencies { #global-dependencies }\n# Global Dependencies { #global-dependencies }\n\nFor some types of applications you might want to add dependencies to the whole application.\n\nSimilar to the way you can [add `dependencies` to the *path operation decorators*](dependencies-in-path-operation-decorators.md), you can add them to the `FastAPI` application.\n\nIn that case, they will be applied to all the *path operations* in the application:\n\n{* ../../docs_src/dependencies/tutorial012_an_py310.py hl[17] *}\n\n\nAnd all the ideas in the section about [adding `dependencies` to the *path operation decorators*](dependencies-in-path-operation-decorators.md) still apply, but in this case, to all of the *path operations* in the app.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/global-dependencies.md", "symbol": "Global Dependencies { #global-dependencies }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/global-dependencies.md#L1-L13", "start_line": 1, "end_line": 13}
{"id": "docs/en/docs/tutorial/dependencies/global-dependencies.md::Dependencies for groups of *path operations* { #dependencies-for-groups-of-path-operations }::L14", "text": "# Doc: docs/en/docs/tutorial/dependencies/global-dependencies.md | Page: Global Dependencies { #global-dependencies } | Section: Dependencies for groups of *path operations* { #dependencies-for-groups-of-path-operations }\n## Dependencies for groups of *path operations* { #dependencies-for-groups-of-path-operations }\n\nLater, when reading about how to structure bigger applications ([Bigger Applications - Multiple Files](../../tutorial/bigger-applications.md)), possibly with multiple files, you will learn how to declare a single `dependencies` parameter for a group of *path operations*.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/global-dependencies.md", "symbol": "Dependencies for groups of *path operations* { #dependencies-for-groups-of-path-operations }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/global-dependencies.md#L14-L16", "start_line": 14, "end_line": 16}
{"id": "docs/en/docs/tutorial/dependencies/index.md::Dependencies { #dependencies }::L1", "text": "# Doc: docs/en/docs/tutorial/dependencies/index.md | Page: Dependencies { #dependencies } | Section: Dependencies { #dependencies }\n# Dependencies { #dependencies }\n\n**FastAPI** has a very powerful but intuitive **Dependency Injection** system.\n\nIt is designed to be very simple to use, and to make it very easy for any developer to integrate other components with **FastAPI**.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/index.md", "symbol": "Dependencies { #dependencies }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/index.md#L1-L6", "start_line": 1, "end_line": 6}
{"id": "docs/en/docs/tutorial/dependencies/index.md::What is \"Dependency Injection\" { #what-is-dependency-injection }::L7", "text": "# Doc: docs/en/docs/tutorial/dependencies/index.md | Page: Dependencies { #dependencies } | Section: What is \"Dependency Injection\" { #what-is-dependency-injection }\n## What is \"Dependency Injection\" { #what-is-dependency-injection }\n\n**\"Dependency Injection\"** means, in programming, that there is a way for your code (in this case, your *path operation functions*) to declare things that it requires to work and use: \"dependencies\".\n\nAnd then, that system (in this case **FastAPI**) will take care of doing whatever is needed to provide your code with those needed dependencies (\"inject\" the dependencies).\n\nThis is very useful when you need to:\n\n* Have shared logic (the same code logic again and again).\n* Share database connections.\n* Enforce security, authentication, role requirements, etc.\n* And many other things...\n\nAll these, while minimizing code repetition.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/index.md", "symbol": "What is \"Dependency Injection\" { #what-is-dependency-injection }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/index.md#L7-L21", "start_line": 7, "end_line": 21}
{"id": "docs/en/docs/tutorial/dependencies/index.md::First Steps { #first-steps }::L22", "text": "# Doc: docs/en/docs/tutorial/dependencies/index.md | Page: Dependencies { #dependencies } | Section: First Steps { #first-steps }\n## First Steps { #first-steps }\n\nLet's see a very simple example. It will be so simple that it is not very useful, for now.\n\nBut this way we can focus on how the **Dependency Injection** system works.\n\n### Create a dependency, or \"dependable\" { #create-a-dependency-or-dependable }\n\nLet's first focus on the dependency.\n\nIt is just a function that can take all the same parameters that a *path operation function* can take:\n\n{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[8:9] *}\n\nThat's it.\n\n**2 lines**.\n\nAnd it has the same shape and structure that all your *path operation functions* have.\n\nYou can think of it as a *path operation function* without the \"decorator\" (without the `@app.get(\"/some-path\")`).\n\nAnd it can return anything you want.\n\nIn this case, this dependency expects:\n\n* An optional query parameter `q` that is a `str`.\n* An optional query parameter `skip` that is an `int`, and by default is `0`.\n* An optional query parameter `limit` that is an `int`, and by default is `100`.\n\nAnd then it just returns a `dict` containing those values.\n\n/// note\n\nFastAPI added support for `Annotated` (and started recommending it) in version 0.95.0.\n\nIf you have an older version, you would get errors when trying to use `Annotated`.\n\nMake sure you [Upgrade the FastAPI version](../../deployment/versions.md#upgrading-the-fastapi-versions) to at least 0.95.1 before using `Annotated`.\n\n///\n\n### Import `Depends` { #import-depends }\n\n{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[3] *}\n\n### Declare the dependency, in the \"dependant\" { #declare-the-dependency-in-the-dependant }\n\nThe same way you use `Body`, `Query`, etc. with your *path operation function* parameters, use `Depends` with a new parameter:\n\n{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[13,18] *}\n\nAlthough you use `Depends` in the parameters of your function the same way you use `Body`, `Query`, etc, `Depends` works a bit differently.\n\nYou only give `Depends` a single parameter.\n\nThis parameter must be something like a function.\n\nYou **don't call it** directly (don't add the parenthesis at the end), you just pass it as a parameter to `Depends()`.\n\nAnd that function takes parameters in the same way that *path operation functions* do.\n\n/// tip\n\nYou'll see what other \"things\", apart from functions, can be used as dependencies in the next chapter.\n\n///\n\nWhenever a new request arrives, **FastAPI** will take care of:\n\n* Calling your dependency (\"dependable\") function with the correct parameters.\n* Get the result from your function.\n* Assign that result to the parameter in your *path operation function*.\n\n```mermaid\ngraph TB\n\ncommon_parameters([\"common_parameters\"])\nread_items[\"/items/\"]\nread_users[\"/users/\"]\n\ncommon_parameters --> read_items\ncommon_parameters --> read_users\n```\n\nThis way you write shared code once and **FastAPI** takes care of calling it for your *path operations*.\n\n/// tip\n\nNotice that you don't have to create a special class and pass it somewhere to **FastAPI** to \"register\" it or anything similar.\n\nYou just pass it to `Depends` and **FastAPI** knows how to do the rest.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/index.md", "symbol": "First Steps { #first-steps }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/index.md#L22-L116", "start_line": 22, "end_line": 116}
{"id": "docs/en/docs/tutorial/dependencies/index.md::Share `Annotated` dependencies { #share-annotated-dependencies }::L117", "text": "# Doc: docs/en/docs/tutorial/dependencies/index.md | Page: Dependencies { #dependencies } | Section: Share `Annotated` dependencies { #share-annotated-dependencies }\n## Share `Annotated` dependencies { #share-annotated-dependencies }\n\nIn the examples above, you see that there's a tiny bit of **code duplication**.\n\nWhen you need to use the `common_parameters()` dependency, you have to write the whole parameter with the type annotation and `Depends()`:\n\n```Python\ncommons: Annotated[dict, Depends(common_parameters)]\n```\n\nBut because we are using `Annotated`, we can store that `Annotated` value in a variable and use it in multiple places:\n\n{* ../../docs_src/dependencies/tutorial001_02_an_py310.py hl[12,16,21] *}\n\n/// tip\n\nThis is just standard Python, it's called a \"type alias\", it's actually not specific to **FastAPI**.\n\nBut because **FastAPI** is based on the Python standards, including `Annotated`, you can use this trick in your code. 😎\n\n///\n\nThe dependencies will keep working as expected, and the **best part** is that the **type information will be preserved**, which means that your editor will be able to keep providing you with **autocompletion**, **inline errors**, etc. The same for other tools like `mypy`.\n\nThis will be especially useful when you use it in a **large code base** where you use **the same dependencies** over and over again in **many *path operations***.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/index.md", "symbol": "Share `Annotated` dependencies { #share-annotated-dependencies }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/index.md#L117-L142", "start_line": 117, "end_line": 142}
{"id": "docs/en/docs/tutorial/dependencies/index.md::To `async` or not to `async` { #to-async-or-not-to-async }::L143", "text": "# Doc: docs/en/docs/tutorial/dependencies/index.md | Page: Dependencies { #dependencies } | Section: To `async` or not to `async` { #to-async-or-not-to-async }\n## To `async` or not to `async` { #to-async-or-not-to-async }\n\nAs dependencies will also be called by **FastAPI** (the same as your *path operation functions*), the same rules apply while defining your functions.\n\nYou can use `async def` or normal `def`.\n\nAnd you can declare dependencies with `async def` inside of normal `def` *path operation functions*, or `def` dependencies inside of `async def` *path operation functions*, etc.\n\nIt doesn't matter. **FastAPI** will know what to do.\n\n/// note\n\nIf you don't know, check the [Async: *\"In a hurry?\"*](../../async.md#in-a-hurry) section about `async` and `await` in the docs.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/index.md", "symbol": "To `async` or not to `async` { #to-async-or-not-to-async }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/index.md#L143-L158", "start_line": 143, "end_line": 158}
{"id": "docs/en/docs/tutorial/dependencies/index.md::Integrated with OpenAPI { #integrated-with-openapi }::L159", "text": "# Doc: docs/en/docs/tutorial/dependencies/index.md | Page: Dependencies { #dependencies } | Section: Integrated with OpenAPI { #integrated-with-openapi }\n## Integrated with OpenAPI { #integrated-with-openapi }\n\nAll the request declarations, validations and requirements of your dependencies (and sub-dependencies) will be integrated in the same OpenAPI schema.\n\nSo, the interactive docs will have all the information from these dependencies too:\n\n![](\"/img/tutorial/dependencies/image01.png\")
", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/index.md", "symbol": "Integrated with OpenAPI { #integrated-with-openapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/index.md#L159-L166", "start_line": 159, "end_line": 166}
{"id": "docs/en/docs/tutorial/dependencies/index.md::Simple usage { #simple-usage }::L167", "text": "# Doc: docs/en/docs/tutorial/dependencies/index.md | Page: Dependencies { #dependencies } | Section: Simple usage { #simple-usage }\n## Simple usage { #simple-usage }\n\nIf you look at it, *path operation functions* are declared to be used whenever a *path* and *operation* matches, and then **FastAPI** takes care of calling the function with the correct parameters, extracting the data from the request.\n\nActually, all (or most) of the web frameworks work in this same way.\n\nYou never call those functions directly. They are called by your framework (in this case, **FastAPI**).\n\nWith the Dependency Injection system, you can also tell **FastAPI** that your *path operation function* also \"depends\" on something else that should be executed before your *path operation function*, and **FastAPI** will take care of executing it and \"injecting\" the results.\n\nOther common terms for this same idea of \"dependency injection\" are:\n\n* resources\n* providers\n* services\n* injectables\n* components", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/index.md", "symbol": "Simple usage { #simple-usage }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/index.md#L167-L184", "start_line": 167, "end_line": 184}
{"id": "docs/en/docs/tutorial/dependencies/index.md::**FastAPI** plug-ins { #fastapi-plug-ins }::L185", "text": "# Doc: docs/en/docs/tutorial/dependencies/index.md | Page: Dependencies { #dependencies } | Section: **FastAPI** plug-ins { #fastapi-plug-ins }\n## **FastAPI** plug-ins { #fastapi-plug-ins }\n\nIntegrations and \"plug-ins\" can be built using the **Dependency Injection** system. But in fact, there is actually **no need to create \"plug-ins\"**, as by using dependencies it's possible to declare an infinite number of integrations and interactions that become available to your *path operation functions*.\n\nAnd dependencies can be created in a very simple and intuitive way that allows you to just import the Python packages you need, and integrate them with your API functions in a couple of lines of code, *literally*.\n\nYou will see examples of this in the next chapters, about relational and NoSQL databases, security, etc.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/index.md", "symbol": "**FastAPI** plug-ins { #fastapi-plug-ins }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/index.md#L185-L192", "start_line": 185, "end_line": 192}
{"id": "docs/en/docs/tutorial/dependencies/index.md::**FastAPI** compatibility { #fastapi-compatibility }::L193", "text": "# Doc: docs/en/docs/tutorial/dependencies/index.md | Page: Dependencies { #dependencies } | Section: **FastAPI** compatibility { #fastapi-compatibility }\n## **FastAPI** compatibility { #fastapi-compatibility }\n\nThe simplicity of the dependency injection system makes **FastAPI** compatible with:\n\n* all the relational databases\n* NoSQL databases\n* external packages\n* external APIs\n* authentication and authorization systems\n* API usage monitoring systems\n* response data injection systems\n* etc.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/index.md", "symbol": "**FastAPI** compatibility { #fastapi-compatibility }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/index.md#L193-L205", "start_line": 193, "end_line": 205}
{"id": "docs/en/docs/tutorial/dependencies/index.md::Simple and Powerful { #simple-and-powerful }::L206", "text": "# Doc: docs/en/docs/tutorial/dependencies/index.md | Page: Dependencies { #dependencies } | Section: Simple and Powerful { #simple-and-powerful }\n## Simple and Powerful { #simple-and-powerful }\n\nAlthough the hierarchical dependency injection system is very simple to define and use, it's still very powerful.\n\nYou can define dependencies that in turn can define dependencies themselves.\n\nIn the end, a hierarchical tree of dependencies is built, and the **Dependency Injection** system takes care of solving all these dependencies for you (and their sub-dependencies) and providing (injecting) the results at each step.\n\nFor example, let's say you have 4 API endpoints (*path operations*):\n\n* `/items/public/`\n* `/items/private/`\n* `/users/{user_id}/activate`\n* `/items/pro/`\n\nthen you could add different permission requirements for each of them just with dependencies and sub-dependencies:\n\n```mermaid\ngraph TB\n\ncurrent_user([\"current_user\"])\nactive_user([\"active_user\"])\nadmin_user([\"admin_user\"])\npaying_user([\"paying_user\"])\n\npublic[\"/items/public/\"]\nprivate[\"/items/private/\"]\nactivate_user[\"/users/{user_id}/activate\"]\npro_items[\"/items/pro/\"]\n\ncurrent_user --> active_user\nactive_user --> admin_user\nactive_user --> paying_user\n\ncurrent_user --> public\nactive_user --> private\nadmin_user --> activate_user\npaying_user --> pro_items\n```", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/index.md", "symbol": "Simple and Powerful { #simple-and-powerful }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/index.md#L206-L245", "start_line": 206, "end_line": 245}
{"id": "docs/en/docs/tutorial/dependencies/index.md::Integrated with **OpenAPI** { #integrated-with-openapi_1 }::L246", "text": "# Doc: docs/en/docs/tutorial/dependencies/index.md | Page: Dependencies { #dependencies } | Section: Integrated with **OpenAPI** { #integrated-with-openapi_1 }\n## Integrated with **OpenAPI** { #integrated-with-openapi_1 }\n\nAll these dependencies, while declaring their requirements, also add parameters, validations, etc. to your *path operations*.\n\n**FastAPI** will take care of adding it all to the OpenAPI schema, so that it is shown in the interactive documentation systems.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/index.md", "symbol": "Integrated with **OpenAPI** { #integrated-with-openapi_1 }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/index.md#L246-L250", "start_line": 246, "end_line": 250}
{"id": "docs/en/docs/tutorial/dependencies/sub-dependencies.md::Sub-dependencies { #sub-dependencies }::L1", "text": "# Doc: docs/en/docs/tutorial/dependencies/sub-dependencies.md | Page: Sub-dependencies { #sub-dependencies } | Section: Sub-dependencies { #sub-dependencies }\n# Sub-dependencies { #sub-dependencies }\n\nYou can create dependencies that have **sub-dependencies**.\n\nThey can be as **deep** as you need them to be.\n\n**FastAPI** will take care of solving them.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/sub-dependencies.md", "symbol": "Sub-dependencies { #sub-dependencies }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/sub-dependencies.md#L1-L8", "start_line": 1, "end_line": 8}
{"id": "docs/en/docs/tutorial/dependencies/sub-dependencies.md::First dependency \"dependable\" { #first-dependency-dependable }::L9", "text": "# Doc: docs/en/docs/tutorial/dependencies/sub-dependencies.md | Page: Sub-dependencies { #sub-dependencies } | Section: First dependency \"dependable\" { #first-dependency-dependable }\n## First dependency \"dependable\" { #first-dependency-dependable }\n\nYou could create a first dependency (\"dependable\") like:\n\n{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[8:9] *}\n\nIt declares an optional query parameter `q` as a `str`, and then it just returns it.\n\nThis is quite simple (not very useful), but will help us focus on how the sub-dependencies work.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/sub-dependencies.md", "symbol": "First dependency \"dependable\" { #first-dependency-dependable }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/sub-dependencies.md#L9-L18", "start_line": 9, "end_line": 18}
{"id": "docs/en/docs/tutorial/dependencies/sub-dependencies.md::Second dependency, \"dependable\" and \"dependant\" { #second-dependency-dependable-and-dependant }::L19", "text": "# Doc: docs/en/docs/tutorial/dependencies/sub-dependencies.md | Page: Sub-dependencies { #sub-dependencies } | Section: Second dependency, \"dependable\" and \"dependant\" { #second-dependency-dependable-and-dependant }\n## Second dependency, \"dependable\" and \"dependant\" { #second-dependency-dependable-and-dependant }\n\nThen you can create another dependency function (a \"dependable\") that at the same time declares a dependency of its own (so it is a \"dependant\" too):\n\n{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[13] *}\n\nLet's focus on the parameters declared:\n\n* Even though this function is a dependency (\"dependable\") itself, it also declares another dependency (it \"depends\" on something else).\n * It depends on the `query_extractor`, and assigns the value returned by it to the parameter `q`.\n* It also declares an optional `last_query` cookie, as a `str`.\n * If the user didn't provide any query `q`, we use the last query used, which we saved to a cookie before.", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/sub-dependencies.md", "symbol": "Second dependency, \"dependable\" and \"dependant\" { #second-dependency-dependable-and-dependant }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/sub-dependencies.md#L19-L31", "start_line": 19, "end_line": 31}
{"id": "docs/en/docs/tutorial/dependencies/sub-dependencies.md::Use the dependency { #use-the-dependency }::L32", "text": "# Doc: docs/en/docs/tutorial/dependencies/sub-dependencies.md | Page: Sub-dependencies { #sub-dependencies } | Section: Use the dependency { #use-the-dependency }\n## Use the dependency { #use-the-dependency }\n\nThen we can use the dependency with:\n\n{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[23] *}\n\n/// note\n\nNotice that we are only declaring one dependency in the *path operation function*, the `query_or_cookie_extractor`.\n\nBut **FastAPI** will know that it has to solve `query_extractor` first, to pass the results of that to `query_or_cookie_extractor` while calling it.\n\n///\n\n```mermaid\ngraph TB\n\nquery_extractor([\"query_extractor\"])\nquery_or_cookie_extractor([\"query_or_cookie_extractor\"])\n\nread_query[\"/items/\"]\n\nquery_extractor --> query_or_cookie_extractor --> read_query\n```", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/sub-dependencies.md", "symbol": "Use the dependency { #use-the-dependency }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/sub-dependencies.md#L32-L56", "start_line": 32, "end_line": 56}
{"id": "docs/en/docs/tutorial/dependencies/sub-dependencies.md::Using the same dependency multiple times { #using-the-same-dependency-multiple-times }::L57", "text": "# Doc: docs/en/docs/tutorial/dependencies/sub-dependencies.md | Page: Sub-dependencies { #sub-dependencies } | Section: Using the same dependency multiple times { #using-the-same-dependency-multiple-times }\n## Using the same dependency multiple times { #using-the-same-dependency-multiple-times }\n\nIf one of your dependencies is declared multiple times for the same *path operation*, for example, multiple dependencies have a common sub-dependency, **FastAPI** will know to call that sub-dependency only once per request.\n\nAnd it will save the returned value in a \"cache\" and pass it to all the \"dependants\" that need it in that specific request, instead of calling the dependency multiple times for the same request.\n\nIn an advanced scenario where you know you need the dependency to be called at every step (possibly multiple times) in the same request instead of using the \"cached\" value, you can set the parameter `use_cache=False` when using `Depends`:\n\n//// tab | Python 3.10+\n\n```Python hl_lines=\"1\"\nasync def needy_dependency(fresh_value: Annotated[str, Depends(get_value, use_cache=False)]):\n return {\"fresh_value\": fresh_value}\n```\n\n////\n\n//// tab | Python 3.10+ non-Annotated\n\n/// tip\n\nPrefer to use the `Annotated` version if possible.\n\n///\n\n```Python hl_lines=\"1\"\nasync def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False)):\n return {\"fresh_value\": fresh_value}\n```\n\n////", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/sub-dependencies.md", "symbol": "Using the same dependency multiple times { #using-the-same-dependency-multiple-times }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/sub-dependencies.md#L57-L88", "start_line": 57, "end_line": 88}
{"id": "docs/en/docs/tutorial/dependencies/sub-dependencies.md::Recap { #recap }::L89", "text": "# Doc: docs/en/docs/tutorial/dependencies/sub-dependencies.md | Page: Sub-dependencies { #sub-dependencies } | Section: Recap { #recap }\n## Recap { #recap }\n\nApart from all the fancy words used here, the **Dependency Injection** system is quite simple.\n\nJust functions that look the same as the *path operation functions*.\n\nBut still, it is very powerful, and allows you to declare arbitrarily deeply nested dependency \"graphs\" (trees).\n\n/// tip\n\nAll this might not seem as useful with these simple examples.\n\nBut you will see how useful it is in the chapters about **security**.\n\nAnd you will also see the amounts of code it will save you.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/dependencies/sub-dependencies.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/dependencies/sub-dependencies.md#L89-L105", "start_line": 89, "end_line": 105}
{"id": "docs/en/docs/tutorial/encoder.md::JSON Compatible Encoder { #json-compatible-encoder }::L1", "text": "# Doc: docs/en/docs/tutorial/encoder.md | Page: JSON Compatible Encoder { #json-compatible-encoder } | Section: JSON Compatible Encoder { #json-compatible-encoder }\n# JSON Compatible Encoder { #json-compatible-encoder }\n\nThere are some cases where you might need to convert a data type (like a Pydantic model) to something compatible with JSON (like a `dict`, `list`, etc).\n\nFor example, if you need to store it in a database.\n\nFor that, **FastAPI** provides a `jsonable_encoder()` function.", "source_type": "doc", "path": "docs/en/docs/tutorial/encoder.md", "symbol": "JSON Compatible Encoder { #json-compatible-encoder }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/encoder.md#L1-L8", "start_line": 1, "end_line": 8}
{"id": "docs/en/docs/tutorial/encoder.md::Using the `jsonable_encoder` { #using-the-jsonable-encoder }::L9", "text": "# Doc: docs/en/docs/tutorial/encoder.md | Page: JSON Compatible Encoder { #json-compatible-encoder } | Section: Using the `jsonable_encoder` { #using-the-jsonable-encoder }\n## Using the `jsonable_encoder` { #using-the-jsonable-encoder }\n\nLet's imagine that you have a database `fake_db` that only receives JSON compatible data.\n\nFor example, it doesn't receive `datetime` objects, as those are not compatible with JSON.\n\nSo, a `datetime` object would have to be converted to a `str` containing the data in [ISO format](https://en.wikipedia.org/wiki/ISO_8601).\n\nThe same way, this database wouldn't receive a Pydantic model (an object with attributes), only a `dict`.\n\nYou can use `jsonable_encoder` for that.\n\nIt receives an object, like a Pydantic model, and returns a JSON compatible version:\n\n{* ../../docs_src/encoder/tutorial001_py310.py hl[4,21] *}\n\nIn this example, it would convert the Pydantic model to a `dict`, and the `datetime` to a `str`.\n\nThe result of calling it is something that can be encoded with the Python standard [`json.dumps()`](https://docs.python.org/3/library/json.html#json.dumps).\n\nIt doesn't return a large `str` containing the data in JSON format (as a string). It returns a Python standard data structure (e.g. a `dict`) with values and sub-values that are all compatible with JSON.\n\n/// note\n\n`jsonable_encoder` is actually used by **FastAPI** internally to convert data. But it is useful in many other scenarios.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/encoder.md", "symbol": "Using the `jsonable_encoder` { #using-the-jsonable-encoder }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/encoder.md#L9-L35", "start_line": 9, "end_line": 35}
{"id": "docs/en/docs/tutorial/extra-data-types.md::Extra Data Types { #extra-data-types }::L1", "text": "# Doc: docs/en/docs/tutorial/extra-data-types.md | Page: Extra Data Types { #extra-data-types } | Section: Extra Data Types { #extra-data-types }\n# Extra Data Types { #extra-data-types }\n\nUp to now, you have been using common data types, like:\n\n* `int`\n* `float`\n* `str`\n* `bool`\n\nBut you can also use more complex data types.\n\nAnd you will still have the same features as seen up to now:\n\n* Great editor support.\n* Data conversion from incoming requests.\n* Data conversion for response data.\n* Data validation.\n* Automatic annotation and documentation.", "source_type": "doc", "path": "docs/en/docs/tutorial/extra-data-types.md", "symbol": "Extra Data Types { #extra-data-types }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/extra-data-types.md#L1-L19", "start_line": 1, "end_line": 19}
{"id": "docs/en/docs/tutorial/extra-data-types.md::Other data types { #other-data-types }::L20", "text": "# Doc: docs/en/docs/tutorial/extra-data-types.md | Page: Extra Data Types { #extra-data-types } | Section: Other data types { #other-data-types }\n## Other data types { #other-data-types }\n\nHere are some of the additional data types you can use:\n\n* `UUID`:\n * A standard \"Universally Unique Identifier\", common as an ID in many databases and systems.\n * In requests and responses will be represented as a `str`.\n* `datetime.datetime`:\n * A Python `datetime.datetime`.\n * In requests and responses will be represented as a `str` in ISO 8601 format, like: `2008-09-15T15:53:00+05:00`.\n* `datetime.date`:\n * Python `datetime.date`.\n * In requests and responses will be represented as a `str` in ISO 8601 format, like: `2008-09-15`.\n* `datetime.time`:\n * A Python `datetime.time`.\n * In requests and responses will be represented as a `str` in ISO 8601 format, like: `14:23:55.003`.\n* `datetime.timedelta`:\n * A Python `datetime.timedelta`.\n * In requests and responses will be represented as a `float` of total seconds.\n * Pydantic also allows representing it as an \"ISO 8601 time diff encoding\", [see the docs for more info](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers).\n* `frozenset`:\n * In requests and responses, treated the same as a `set`:\n * In requests, a list will be read, eliminating duplicates and converting it to a `set`.\n * In responses, the `set` will be converted to a `list`.\n * The generated schema will specify that the `set` values are unique (using JSON Schema's `uniqueItems`).\n* `bytes`:\n * Standard Python `bytes`.\n * In requests and responses will be treated as `str`.\n * The generated schema will specify that it's a `str` with `binary` \"format\".\n* `Decimal`:\n * Standard Python `Decimal`.\n * In requests and responses, handled the same as a `float`.\n* You can check all the valid Pydantic data types here: [Pydantic data types](https://docs.pydantic.dev/latest/usage/types/types/).", "source_type": "doc", "path": "docs/en/docs/tutorial/extra-data-types.md", "symbol": "Other data types { #other-data-types }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/extra-data-types.md#L20-L53", "start_line": 20, "end_line": 53}
{"id": "docs/en/docs/tutorial/extra-data-types.md::Example { #example }::L54", "text": "# Doc: docs/en/docs/tutorial/extra-data-types.md | Page: Extra Data Types { #extra-data-types } | Section: Example { #example }\n## Example { #example }\n\nHere's an example *path operation* with parameters using some of the above types.\n\n{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[1,3,12:16] *}\n\nNote that the parameters inside the function have their natural data type, and you can, for example, perform normal date manipulations, like:\n\n{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[18:19] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/extra-data-types.md", "symbol": "Example { #example }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/extra-data-types.md#L54-L62", "start_line": 54, "end_line": 62}
{"id": "docs/en/docs/tutorial/extra-models.md::Extra Models { #extra-models }::L1", "text": "# Doc: docs/en/docs/tutorial/extra-models.md | Page: Extra Models { #extra-models } | Section: Extra Models { #extra-models }\n# Extra Models { #extra-models }\n\nContinuing with the previous example, it will be common to have more than one related model.\n\nThis is especially the case for user models, because:\n\n* The **input model** needs to be able to have a password.\n* The **output model** should not have a password.\n* The **database model** would probably need to have a hashed password.\n\n/// danger\n\nNever store user's plaintext passwords. Always store a \"secure hash\" that you can then verify.\n\nIf you don't know, you will learn what a \"password hash\" is in the [security chapters](security/simple-oauth2.md#password-hashing).\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/extra-models.md", "symbol": "Extra Models { #extra-models }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/extra-models.md#L1-L18", "start_line": 1, "end_line": 18}
{"id": "docs/en/docs/tutorial/extra-models.md::Multiple models { #multiple-models }::L19", "text": "# Doc: docs/en/docs/tutorial/extra-models.md | Page: Extra Models { #extra-models } | Section: Multiple models { #multiple-models }\n## Multiple models { #multiple-models }\n\nHere's a general idea of what the models could look like with their password fields and the places where they are used:\n\n{* ../../docs_src/extra_models/tutorial001_py310.py hl[7,9,14,20,22,27:28,31:33,38:39] *}\n\n### About `**user_in.model_dump()` { #about-user-in-model-dump }\n\n#### Pydantic's `.model_dump()` { #pydantics-model-dump }\n\n`user_in` is a Pydantic model of class `UserIn`.\n\nPydantic models have a `.model_dump()` method that returns a `dict` with the model's data.\n\nSo, if we create a Pydantic object `user_in` like:\n\n```Python\nuser_in = UserIn(username=\"john\", password=\"secret\", email=\"john.doe@example.com\")\n```\n\nand then we call:\n\n```Python\nuser_dict = user_in.model_dump()\n```\n\nwe now have a `dict` with the data in the variable `user_dict` (it's a `dict` instead of a Pydantic model object).\n\nAnd if we call:\n\n```Python\nprint(user_dict)\n```\n\nwe would get a Python `dict` with:\n\n```Python\n{\n 'username': 'john',\n 'password': 'secret',\n 'email': 'john.doe@example.com',\n 'full_name': None,\n}\n```\n\n#### Unpacking a `dict` { #unpacking-a-dict }\n\nIf we take a `dict` like `user_dict` and pass it to a function (or class) with `**user_dict`, Python will \"unpack\" it. It will pass the keys and values of the `user_dict` directly as key-value arguments.\n\nSo, continuing with the `user_dict` from above, writing:\n\n```Python\nUserInDB(**user_dict)\n```\n\nwould result in something equivalent to:\n\n```Python\nUserInDB(\n username=\"john\",\n password=\"secret\",\n email=\"john.doe@example.com\",\n full_name=None,\n)\n```\n\nOr more exactly, using `user_dict` directly, with whatever contents it might have in the future:\n\n```Python\nUserInDB(\n username = user_dict[\"username\"],\n password = user_dict[\"password\"],\n email = user_dict[\"email\"],\n full_name = user_dict[\"full_name\"],\n)\n```\n\n#### A Pydantic model from the contents of another { #a-pydantic-model-from-the-contents-of-another }\n\nAs in the example above we got `user_dict` from `user_in.model_dump()`, this code:\n\n```Python\nuser_dict = user_in.model_dump()\nUserInDB(**user_dict)\n```\n\nwould be equivalent to:\n\n```Python\nUserInDB(**user_in.model_dump())\n```\n\n...because `user_in.model_dump()` is a `dict`, and then we make Python \"unpack\" it by passing it to `UserInDB` prefixed with `**`.\n\nSo, we get a Pydantic model from the data in another Pydantic model.\n\n#### Unpacking a `dict` and extra keywords { #unpacking-a-dict-and-extra-keywords }\n\nAnd then adding the extra keyword argument `hashed_password=hashed_password`, like in:\n\n```Python\nUserInDB(**user_in.model_dump(), hashed_password=hashed_password)\n```\n\n...ends up being like:\n\n```Python\nUserInDB(\n username = user_dict[\"username\"],\n password = user_dict[\"password\"],\n email = user_dict[\"email\"],\n full_name = user_dict[\"full_name\"],\n hashed_password = hashed_password,\n)\n```\n\n/// warning\n\nThe supporting additional functions `fake_password_hasher` and `fake_save_user` are just to demo a possible flow of the data, but they of course are not providing any real security.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/extra-models.md", "symbol": "Multiple models { #multiple-models }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/extra-models.md#L19-L140", "start_line": 19, "end_line": 140}
{"id": "docs/en/docs/tutorial/extra-models.md::Reduce duplication { #reduce-duplication }::L141", "text": "# Doc: docs/en/docs/tutorial/extra-models.md | Page: Extra Models { #extra-models } | Section: Reduce duplication { #reduce-duplication }\n## Reduce duplication { #reduce-duplication }\n\nReducing code duplication is one of the core ideas in **FastAPI**.\n\nAs code duplication increases the chances of bugs, security issues, code desynchronization issues (when you update in one place but not in the others), etc.\n\nAnd these models are all sharing a lot of the data and duplicating attribute names and types.\n\nWe could do better.\n\nWe can declare a `UserBase` model that serves as a base for our other models. And then we can make subclasses of that model that inherit its attributes (type declarations, validation, etc).\n\nAll the data conversion, validation, documentation, etc. will still work as normally.\n\nThat way, we can declare just the differences between the models (with plaintext `password`, with `hashed_password` and without password):\n\n{* ../../docs_src/extra_models/tutorial002_py310.py hl[7,13:14,17:18,21:22] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/extra-models.md", "symbol": "Reduce duplication { #reduce-duplication }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/extra-models.md#L141-L158", "start_line": 141, "end_line": 158}
{"id": "docs/en/docs/tutorial/extra-models.md::`Union` or `anyOf` { #union-or-anyof }::L159", "text": "# Doc: docs/en/docs/tutorial/extra-models.md | Page: Extra Models { #extra-models } | Section: `Union` or `anyOf` { #union-or-anyof }\n## `Union` or `anyOf` { #union-or-anyof }\n\nYou can declare a response to be the `Union` of two or more types, that means, that the response would be any of them.\n\nIt will be defined in OpenAPI with `anyOf`.\n\nTo do that, use the standard Python type hint [`typing.Union`](https://docs.python.org/3/library/typing.html#typing.Union):\n\n/// note\n\nWhen defining a [`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions), include the most specific type first, followed by the less specific type. In the example below, the more specific `PlaneItem` comes before `CarItem` in `Union[PlaneItem, CarItem]`.\n\n///\n\n{* ../../docs_src/extra_models/tutorial003_py310.py hl[1,14:15,18:20,33] *}\n\n### `Union` in Python 3.10 { #union-in-python-3-10 }\n\nIn this example we pass `Union[PlaneItem, CarItem]` as the value of the argument `response_model`.\n\nBecause we are passing it as a **value to an argument** instead of putting it in a **type annotation**, we have to use `Union` even in Python 3.10.\n\nIf it was in a type annotation we could have used the vertical bar, as:\n\n```Python\nsome_variable: PlaneItem | CarItem\n```\n\nBut if we put that in the assignment `response_model=PlaneItem | CarItem` we would get an error, because Python would try to perform an **invalid operation** between `PlaneItem` and `CarItem` instead of interpreting that as a type annotation.", "source_type": "doc", "path": "docs/en/docs/tutorial/extra-models.md", "symbol": "`Union` or `anyOf` { #union-or-anyof }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/extra-models.md#L159-L188", "start_line": 159, "end_line": 188}
{"id": "docs/en/docs/tutorial/extra-models.md::List of models { #list-of-models }::L189", "text": "# Doc: docs/en/docs/tutorial/extra-models.md | Page: Extra Models { #extra-models } | Section: List of models { #list-of-models }\n## List of models { #list-of-models }\n\nThe same way, you can declare responses of lists of objects.\n\nFor that, use the standard Python `list`:\n\n{* ../../docs_src/extra_models/tutorial004_py310.py hl[18] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/extra-models.md", "symbol": "List of models { #list-of-models }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/extra-models.md#L189-L196", "start_line": 189, "end_line": 196}
{"id": "docs/en/docs/tutorial/extra-models.md::Response with arbitrary `dict` { #response-with-arbitrary-dict }::L197", "text": "# Doc: docs/en/docs/tutorial/extra-models.md | Page: Extra Models { #extra-models } | Section: Response with arbitrary `dict` { #response-with-arbitrary-dict }\n## Response with arbitrary `dict` { #response-with-arbitrary-dict }\n\nYou can also declare a response using a plain arbitrary `dict`, declaring just the type of the keys and values, without using a Pydantic model.\n\nThis is useful if you don't know the valid field/attribute names (that would be needed for a Pydantic model) beforehand.\n\nIn this case, you can use `dict`:\n\n{* ../../docs_src/extra_models/tutorial005_py310.py hl[6] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/extra-models.md", "symbol": "Response with arbitrary `dict` { #response-with-arbitrary-dict }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/extra-models.md#L197-L206", "start_line": 197, "end_line": 206}
{"id": "docs/en/docs/tutorial/extra-models.md::Recap { #recap }::L207", "text": "# Doc: docs/en/docs/tutorial/extra-models.md | Page: Extra Models { #extra-models } | Section: Recap { #recap }\n## Recap { #recap }\n\nUse multiple Pydantic models and inherit freely for each case.\n\nYou don't need to have a single data model per entity if that entity must be able to have different \"states\". The **user** \"entity\" is an example, with states that include `password`, `password_hash`, or no password.", "source_type": "doc", "path": "docs/en/docs/tutorial/extra-models.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/extra-models.md#L207-L211", "start_line": 207, "end_line": 211}
{"id": "docs/en/docs/tutorial/first-steps.md::First Steps { #first-steps }::L1", "text": "# Doc: docs/en/docs/tutorial/first-steps.md | Page: First Steps { #first-steps } | Section: First Steps { #first-steps }\n# First Steps { #first-steps }\n\nThe simplest FastAPI file could look like this:\n\n{* ../../docs_src/first_steps/tutorial001_py310.py *}\n\nCopy that to a file `main.py`.\n\nRun the live server:\n\nget operation\n\n/// note | `@decorator` Info\n\nThat `@something` syntax in Python is called a \"decorator\".\n\nYou put it on top of a function. Like a pretty decorative hat (I guess that's where the term came from).\n\nA \"decorator\" takes the function below and does something with it.\n\nIn our case, this decorator tells **FastAPI** that the function below corresponds to the **path** `/` with an **operation** `get`.\n\nIt is the \"**path operation decorator**\".\n\n///\n\nYou can also use the other operations:\n\n* `@app.post()`\n* `@app.put()`\n* `@app.delete()`\n\nAnd the more exotic ones:\n\n* `@app.options()`\n* `@app.head()`\n* `@app.patch()`\n* `@app.trace()`\n\n/// tip\n\nYou are free to use each operation (HTTP method) as you wish.\n\n**FastAPI** doesn't enforce any specific meaning.\n\nThe information here is presented as a guideline, not a requirement.\n\nFor example, when using GraphQL you normally perform all the actions using only `POST` operations.\n\n///\n\n### Step 4: define the **path operation function** { #step-4-define-the-path-operation-function }\n\nThis is our \"**path operation function**\":\n\n* **path**: is `/`.\n* **operation**: is `get`.\n* **function**: is the function below the \"decorator\" (below `@app.get(\"/\")`).\n\n{* ../../docs_src/first_steps/tutorial001_py310.py hl[7] *}\n\nThis is a Python function.\n\nIt will be called by **FastAPI** whenever it receives a request to the URL \"`/`\" using a `GET` operation.\n\nIn this case, it is an `async` function.\n\n---\n\nYou could also define it as a normal function instead of `async def`:\n\n{* ../../docs_src/first_steps/tutorial003_py310.py hl[7] *}\n\n/// note\n\nIf you don't know the difference, check the [Async: *\"In a hurry?\"*](../async.md#in-a-hurry).\n\n///\n\n### Step 5: return the content { #step-5-return-the-content }\n\n{* ../../docs_src/first_steps/tutorial001_py310.py hl[8] *}\n\nYou can return a `dict`, `list`, singular values as `str`, `int`, etc.\n\nYou can also return Pydantic models (you'll see more about that later).\n\nThere are many other objects and models that will be automatically converted to JSON (including ORMs, etc). Try using your favorite ones, it's highly probable that they are already supported.\n\n### Step 6: Deploy it { #step-6-deploy-it }\n\nDeploy your app to **[FastAPI Cloud](https://fastapicloud.com)** with one command: `fastapi deploy`. 🎉\n\n#### About FastAPI Cloud { #about-fastapi-cloud }\n\n**[FastAPI Cloud](https://fastapicloud.com)** is built by the same author and team behind **FastAPI**.\n\nIt streamlines the process of **building**, **deploying**, and **accessing** an API with minimal effort.\n\nIt brings the same **developer experience** of building apps with FastAPI to **deploying** them to the cloud. 🎉\n\nFastAPI Cloud is the primary sponsor and funding provider for the *FastAPI and friends* open source projects. ✨\n\n#### Deploy to other cloud providers { #deploy-to-other-cloud-providers }\n\nFastAPI is open source and based on standards. You can deploy FastAPI apps to any cloud provider you choose.\n\nFollow your cloud provider's guides to deploy FastAPI apps with them. 🤓", "source_type": "doc", "path": "docs/en/docs/tutorial/first-steps.md", "symbol": "Recap, step by step { #recap-step-by-step }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/first-steps.md#L223-L413", "start_line": 223, "end_line": 413}
{"id": "docs/en/docs/tutorial/first-steps.md::Recap { #recap }::L414", "text": "# Doc: docs/en/docs/tutorial/first-steps.md | Page: First Steps { #first-steps } | Section: Recap { #recap }\n## Recap { #recap }\n\n* Import `FastAPI`.\n* Create an `app` instance.\n* Write a **path operation decorator** using decorators like `@app.get(\"/\")`.\n* Define a **path operation function**; for example, `def root(): ...`.\n* Run the development server using the command `fastapi dev`.\n* Optionally deploy your app with `fastapi deploy`.", "source_type": "doc", "path": "docs/en/docs/tutorial/first-steps.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/first-steps.md#L414-L421", "start_line": 414, "end_line": 421}
{"id": "docs/en/docs/tutorial/frontend.md::Frontend { #frontend }::L1", "text": "# Doc: docs/en/docs/tutorial/frontend.md | Page: Frontend { #frontend } | Section: Frontend { #frontend }\n# Frontend { #frontend }\n\nYou can serve static frontend apps with `app.frontend()` (or `router.frontend()`).\n\nThis is useful for frontend tools that generate static files, like React with Vite, TanStack Router, Astro, Vue, Svelte, Angular, Solid, and others.\n\nWith these tools, you normally have a step that builds the frontend, with a command like:\n\n```bash\nnpm run build\n```\n\nThat would generate a directory like `./dist/` with your frontend files.\n\nYou can use `app.frontend()` to serve that directory following the conventions needed by these frontend frameworks.\n\n**FastAPI** checks *path operations* first. The frontend files are checked only if no normal route matched, so your API won't be affected.", "source_type": "doc", "path": "docs/en/docs/tutorial/frontend.md", "symbol": "Frontend { #frontend }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/frontend.md#L1-L18", "start_line": 1, "end_line": 18}
{"id": "docs/en/docs/tutorial/frontend.md::Serve a Frontend { #serve-a-frontend }::L19", "text": "# Doc: docs/en/docs/tutorial/frontend.md | Page: Frontend { #frontend } | Section: Serve a Frontend { #serve-a-frontend }\n## Serve a Frontend { #serve-a-frontend }\n\nAfter building your frontend, for example with `npm run build`, put the generated files in a directory, for example, `dist`.\n\nYour project structure could look like this:\n\n```text\n.\n├── pyproject.toml\n├── app\n│ ├── __init__.py\n│ └── main.py\n└── dist\n ├── index.html\n └── assets\n └── app.js\n```\n\nThen serve it with `app.frontend()`:\n\n{* ../../docs_src/frontend/tutorial001_py310.py hl[5] *}\n\nWith this, a request for `/assets/app.js` can serve `dist/assets/app.js`.\n\nIf you also have a **FastAPI** *path operation*, the *path operation* wins.", "source_type": "doc", "path": "docs/en/docs/tutorial/frontend.md", "symbol": "Serve a Frontend { #serve-a-frontend }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/frontend.md#L19-L44", "start_line": 19, "end_line": 44}
{"id": "docs/en/docs/tutorial/frontend.md::Client-Side Routing { #client-side-routing }::L45", "text": "# Doc: docs/en/docs/tutorial/frontend.md | Page: Frontend { #frontend } | Section: Client-Side Routing { #client-side-routing }\n## Client-Side Routing { #client-side-routing }\n\nMany frontend apps, including **single-page apps** (SPAs), use client-side routing. A path like `/dashboard/settings` might not be a real file but the framework would take care of handling it.\n\nSo, if accessing that URL directly (instead of navigating through the app), the backend should serve the frontend app from `index.html`, so that the frontend framework can then handle the client-side routing.\n\nFor that, use `fallback=\"index.html\"`:\n\n{* ../../docs_src/frontend/tutorial002_py310.py hl[5] *}\n\n**FastAPI** uses this fallback only for `GET` and `HEAD` requests that look like browser navigation. Missing files like JavaScript, CSS, and images still return `404`.\n\nRequests with other methods, like `POST` or `PUT`, to paths that only match the frontend fallback also return `404`. Regular **FastAPI** *path operations* still have higher priority than frontend routes.\n\n/// tip\n\nBy default, `fallback` has a value of `fallback=\"auto\"`. In most cases you won't need to specify `fallback`. Read below for details.\n\n///\n\nThis is what you would want with many frontend apps that use client-side routing, for example, React with TanStack Router, Vue, Angular, SvelteKit, or Solid.", "source_type": "doc", "path": "docs/en/docs/tutorial/frontend.md", "symbol": "Client-Side Routing { #client-side-routing }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/frontend.md#L45-L66", "start_line": 45, "end_line": 66}
{"id": "docs/en/docs/tutorial/frontend.md::Custom 404 Page { #custom-404-page }::L67", "text": "# Doc: docs/en/docs/tutorial/frontend.md | Page: Frontend { #frontend } | Section: Custom 404 Page { #custom-404-page }\n## Custom 404 Page { #custom-404-page }\n\nYou can also serve a static `404.html` page for missing frontend paths:\n\n{* ../../docs_src/frontend/tutorial003_py310.py hl[5] *}\n\nThat response keeps a status code of `404`.\n\nIn this case, **FastAPI** won't serve `index.html` for missing frontend paths. It will return the `404.html` file instead.\n\n/// tip\n\nBy default, `fallback` has a value of `fallback=\"auto\"`. With this, if a `404.html` file is found, it will be used as the fallback automatically.\n\nSo, you can normally omit the `fallback` argument.\n\n///\n\nThis is useful with frontend tools that generate static HTML files for each page, like Astro.", "source_type": "doc", "path": "docs/en/docs/tutorial/frontend.md", "symbol": "Custom 404 Page { #custom-404-page }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/frontend.md#L67-L86", "start_line": 67, "end_line": 86}
{"id": "docs/en/docs/tutorial/frontend.md::Fallback Auto { #fallback-auto }::L87", "text": "# Doc: docs/en/docs/tutorial/frontend.md | Page: Frontend { #frontend } | Section: Fallback Auto { #fallback-auto }\n## Fallback Auto { #fallback-auto }\n\nBy default, `app.frontend()` uses `fallback=\"auto\"`.\n\nIf there is a `404.html` file in the frontend directory, missing frontend paths serve that file with status code `404`.\n\nOtherwise, if there is an `index.html` file, missing browser navigation paths serve `index.html`, which is what many frontend apps with client-side routing expect.\n\nSo, in most cases you can use `app.frontend(\"/\", directory=\"dist\")` without specifying the `fallback` argument.\n\n{* ../../docs_src/frontend/tutorial001_py310.py hl[5] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/frontend.md", "symbol": "Fallback Auto { #fallback-auto }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/frontend.md#L87-L98", "start_line": 87, "end_line": 98}
{"id": "docs/en/docs/tutorial/frontend.md::Disable Fallback { #disable-fallback }::L99", "text": "# Doc: docs/en/docs/tutorial/frontend.md | Page: Frontend { #frontend } | Section: Disable Fallback { #disable-fallback }\n## Disable Fallback { #disable-fallback }\n\nIf you don't want to serve a fallback file for missing frontend paths, use `fallback=None`:\n\n{* ../../docs_src/frontend/tutorial005_py310.py hl[5] *}\n\nThen missing frontend paths return the normal `404`.", "source_type": "doc", "path": "docs/en/docs/tutorial/frontend.md", "symbol": "Disable Fallback { #disable-fallback }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/frontend.md#L99-L106", "start_line": 99, "end_line": 106}
{"id": "docs/en/docs/tutorial/frontend.md::Check Directory { #check-directory }::L107", "text": "# Doc: docs/en/docs/tutorial/frontend.md | Page: Frontend { #frontend } | Section: Check Directory { #check-directory }\n## Check Directory { #check-directory }\n\nBy default, `app.frontend()` checks that the directory exists when the app is created.\n\nThis helps catch configuration errors early. For example, if the frontend build output directory is missing, **FastAPI** will raise an error on startup.\n\nIf your frontend files are created later, for example by a separate build step after the app object is created, set `check_dir=False`:\n\n{* ../../docs_src/frontend/tutorial006_py310.py hl[5] *}\n\nWith `check_dir=False`, **FastAPI** will not check the directory when the app is created. If the configured directory is still missing when a request is handled, **FastAPI** will raise an error then.", "source_type": "doc", "path": "docs/en/docs/tutorial/frontend.md", "symbol": "Check Directory { #check-directory }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/frontend.md#L107-L118", "start_line": 107, "end_line": 118}
{"id": "docs/en/docs/tutorial/frontend.md::Use it with `APIRouter` { #use-it-with-apirouter }::L119", "text": "# Doc: docs/en/docs/tutorial/frontend.md | Page: Frontend { #frontend } | Section: Use it with `APIRouter` { #use-it-with-apirouter }\n## Use it with `APIRouter` { #use-it-with-apirouter }\n\nYou can also add frontend files to an `APIRouter` and include it with a prefix:\n\n{* ../../docs_src/frontend/tutorial004_py310.py hl[6,7] *}\n\nIn this example, frontend paths are served under `/app`.\n\nAny regular *path operations* in the app will still take precedence, including in other routers.", "source_type": "doc", "path": "docs/en/docs/tutorial/frontend.md", "symbol": "Use it with `APIRouter` { #use-it-with-apirouter }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/frontend.md#L119-L128", "start_line": 119, "end_line": 128}
{"id": "docs/en/docs/tutorial/frontend.md::Dependencies and Middleware { #dependencies-and-middleware }::L129", "text": "# Doc: docs/en/docs/tutorial/frontend.md | Page: Frontend { #frontend } | Section: Dependencies and Middleware { #dependencies-and-middleware }\n## Dependencies and Middleware { #dependencies-and-middleware }\n\nFrontend responses run inside the normal **FastAPI** application, so HTTP middleware applies to them.\n\nDependencies from the app, from an `APIRouter`, and from `include_router()` also apply to frontend responses. This can be useful for protecting a frontend with cookie authentication or similar.", "source_type": "doc", "path": "docs/en/docs/tutorial/frontend.md", "symbol": "Dependencies and Middleware { #dependencies-and-middleware }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/frontend.md#L129-L134", "start_line": 129, "end_line": 134}
{"id": "docs/en/docs/tutorial/frontend.md::Static Build Output Only { #static-build-output-only }::L135", "text": "# Doc: docs/en/docs/tutorial/frontend.md | Page: Frontend { #frontend } | Section: Static Build Output Only { #static-build-output-only }\n## Static Build Output Only { #static-build-output-only }\n\n`app.frontend()` serves files already generated by your frontend build.\n\nIt does not run server-side rendering. It is for frontend frameworks that generate static files, not for frameworks that need dynamic rendering on the server for each request.", "source_type": "doc", "path": "docs/en/docs/tutorial/frontend.md", "symbol": "Static Build Output Only { #static-build-output-only }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/frontend.md#L135-L139", "start_line": 135, "end_line": 139}
{"id": "docs/en/docs/tutorial/handling-errors.md::Handling Errors { #handling-errors }::L1", "text": "# Doc: docs/en/docs/tutorial/handling-errors.md | Page: Handling Errors { #handling-errors } | Section: Handling Errors { #handling-errors }\n# Handling Errors { #handling-errors }\n\nThere are many situations in which you need to report an error to a client that is using your API.\n\nThis client could be a browser with a frontend, a code from someone else, an IoT device, etc.\n\nYou could need to tell the client that:\n\n* The client doesn't have enough privileges for that operation.\n* The client doesn't have access to that resource.\n* The item the client was trying to access doesn't exist.\n* etc.\n\nIn these cases, you would normally return an **HTTP status code** in the range of **400** (from 400 to 499).\n\nThis is similar to the 200 HTTP status codes (from 200 to 299). Those \"200\" status codes mean that somehow there was a \"success\" in the request.\n\nThe status codes in the 400 range mean that there was an error from the client.\n\nRemember all those **\"404 Not Found\"** errors (and jokes)?", "source_type": "doc", "path": "docs/en/docs/tutorial/handling-errors.md", "symbol": "Handling Errors { #handling-errors }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/handling-errors.md#L1-L21", "start_line": 1, "end_line": 21}
{"id": "docs/en/docs/tutorial/handling-errors.md::Use `HTTPException` { #use-httpexception }::L22", "text": "# Doc: docs/en/docs/tutorial/handling-errors.md | Page: Handling Errors { #handling-errors } | Section: Use `HTTPException` { #use-httpexception }\n## Use `HTTPException` { #use-httpexception }\n\nTo return HTTP responses with errors to the client you use `HTTPException`.\n\n### Import `HTTPException` { #import-httpexception }\n\n{* ../../docs_src/handling_errors/tutorial001_py310.py hl[1] *}\n\n### Raise an `HTTPException` in your code { #raise-an-httpexception-in-your-code }\n\n`HTTPException` is a normal Python exception with additional data relevant for APIs.\n\nBecause it's a Python exception, you don't `return` it, you `raise` it.\n\nThis also means that if you are inside a utility function that you are calling inside of your *path operation function*, and you raise the `HTTPException` from inside of that utility function, it won't run the rest of the code in the *path operation function*, it will terminate that request right away and send the HTTP error from the `HTTPException` to the client.\n\nThe benefit of raising an exception over returning a value will be more evident in the section about Dependencies and Security.\n\nIn this example, when the client requests an item by an ID that doesn't exist, raise an exception with a status code of `404`:\n\n{* ../../docs_src/handling_errors/tutorial001_py310.py hl[11] *}\n\n### The resulting response { #the-resulting-response }\n\nIf the client requests `http://example.com/items/foo` (an `item_id` `\"foo\"`), that client will receive an HTTP status code of 200, and a JSON response of:\n\n```JSON\n{\n \"item\": \"The Foo Wrestlers\"\n}\n```\n\nBut if the client requests `http://example.com/items/bar` (a non-existent `item_id` `\"bar\"`), that client will receive an HTTP status code of 404 (the \"not found\" error), and a JSON response of:\n\n```JSON\n{\n \"detail\": \"Item not found\"\n}\n```\n\n/// tip\n\nWhen raising an `HTTPException`, you can pass any value that can be converted to JSON as the parameter `detail`, not only `str`.\n\nYou could pass a `dict`, a `list`, etc.\n\nThey are handled automatically by **FastAPI** and converted to JSON.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/handling-errors.md", "symbol": "Use `HTTPException` { #use-httpexception }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/handling-errors.md#L22-L71", "start_line": 22, "end_line": 71}
{"id": "docs/en/docs/tutorial/handling-errors.md::Add custom headers { #add-custom-headers }::L72", "text": "# Doc: docs/en/docs/tutorial/handling-errors.md | Page: Handling Errors { #handling-errors } | Section: Add custom headers { #add-custom-headers }\n## Add custom headers { #add-custom-headers }\n\nThere are some situations where it's useful to be able to add custom headers to the HTTP error. For example, for some types of security.\n\nYou probably won't need to use it directly in your code.\n\nBut in case you needed it for an advanced scenario, you can add custom headers:\n\n{* ../../docs_src/handling_errors/tutorial002_py310.py hl[14] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/handling-errors.md", "symbol": "Add custom headers { #add-custom-headers }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/handling-errors.md#L72-L81", "start_line": 72, "end_line": 81}
{"id": "docs/en/docs/tutorial/handling-errors.md::Install custom exception handlers { #install-custom-exception-handlers }::L82", "text": "# Doc: docs/en/docs/tutorial/handling-errors.md | Page: Handling Errors { #handling-errors } | Section: Install custom exception handlers { #install-custom-exception-handlers }\n## Install custom exception handlers { #install-custom-exception-handlers }\n\nYou can add custom exception handlers with [the same exception utilities from Starlette](https://www.starlette.dev/exceptions/).\n\nLet's say you have a custom exception `UnicornException` that you (or a library you use) might `raise`.\n\nAnd you want to handle this exception globally with FastAPI.\n\nYou could add a custom exception handler with `@app.exception_handler()`:\n\n{* ../../docs_src/handling_errors/tutorial003_py310.py hl[5:7,13:18,24] *}\n\nHere, if you request `/unicorns/yolo`, the *path operation* will `raise` a `UnicornException`.\n\nBut it will be handled by the `unicorn_exception_handler`.\n\nSo, you will receive a clean error, with an HTTP status code of `418` and a JSON content of:\n\n```JSON\n{\"message\": \"Oops! yolo did something. There goes a rainbow...\"}\n```\n\n/// note | Technical Details\n\nYou could also use `from starlette.requests import Request` and `from starlette.responses import JSONResponse`.\n\n**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette. The same with `Request`.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/handling-errors.md", "symbol": "Install custom exception handlers { #install-custom-exception-handlers }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/handling-errors.md#L82-L111", "start_line": 82, "end_line": 111}
{"id": "docs/en/docs/tutorial/handling-errors.md::Override the default exception handlers { #override-the-default-exception-handlers }::L112", "text": "# Doc: docs/en/docs/tutorial/handling-errors.md | Page: Handling Errors { #handling-errors } | Section: Override the default exception handlers { #override-the-default-exception-handlers }\n## Override the default exception handlers { #override-the-default-exception-handlers }\n\n**FastAPI** has some default exception handlers.\n\nThese handlers are in charge of returning the default JSON responses when you `raise` an `HTTPException` and when the request has invalid data.\n\nYou can override these exception handlers with your own.\n\n### Override request validation exceptions { #override-request-validation-exceptions }\n\nWhen a request contains invalid data, **FastAPI** internally raises a `RequestValidationError`.\n\nAnd it also includes a default exception handler for it.\n\nTo override it, import the `RequestValidationError` and use it with `@app.exception_handler(RequestValidationError)` to decorate the exception handler.\n\nThe exception handler will receive a `Request` and the exception.\n\n{* ../../docs_src/handling_errors/tutorial004_py310.py hl[2,14:19] *}\n\nNow, if you go to `/items/foo`, instead of getting the default JSON error with:\n\n```JSON\n{\n \"detail\": [\n {\n \"loc\": [\n \"path\",\n \"item_id\"\n ],\n \"msg\": \"value is not a valid integer\",\n \"type\": \"type_error.integer\"\n }\n ]\n}\n```\n\nyou will get a text version, with:\n\n```\nValidation errors:\nField: ('path', 'item_id'), Error: Input should be a valid integer, unable to parse string as an integer\n```\n\n### Override the `HTTPException` error handler { #override-the-httpexception-error-handler }\n\nThe same way, you can override the `HTTPException` handler.\n\nFor example, you could want to return a plain text response instead of JSON for these errors:\n\n{* ../../docs_src/handling_errors/tutorial004_py310.py hl[3:4,9:11,25] *}\n\n/// note | Technical Details\n\nYou could also use `from starlette.responses import PlainTextResponse`.\n\n**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.\n\n///\n\n/// warning\n\nHave in mind that the `RequestValidationError` contains the information of the file name and line where the validation error happens so that you can show it in your logs with the relevant information if you want to.\n\nBut that means that if you just convert it to a string and return that information directly, you could be leaking a bit of information about your system, that's why here the code extracts and shows each error independently.\n\n///\n\n### Use the `RequestValidationError` body { #use-the-requestvalidationerror-body }\n\nThe `RequestValidationError` contains the `body` it received with invalid data.\n\nYou could use it while developing your app to log the body and debug it, return it to the user, etc.\n\n{* ../../docs_src/handling_errors/tutorial005_py310.py hl[14] *}\n\nNow try sending an invalid item like:\n\n```JSON\n{\n \"title\": \"towel\",\n \"size\": \"XL\"\n}\n```\n\nYou will receive a response telling you that the data is invalid containing the received body:\n\n```JSON hl_lines=\"12-15\"\n{\n \"detail\": [\n {\n \"loc\": [\n \"body\",\n \"size\"\n ],\n \"msg\": \"value is not a valid integer\",\n \"type\": \"type_error.integer\"\n }\n ],\n \"body\": {\n \"title\": \"towel\",\n \"size\": \"XL\"\n }\n}\n```\n\n#### FastAPI's `HTTPException` vs Starlette's `HTTPException` { #fastapis-httpexception-vs-starlettes-httpexception }\n\n**FastAPI** has its own `HTTPException`.\n\nAnd **FastAPI**'s `HTTPException` error class inherits from Starlette's `HTTPException` error class.\n\nThe only difference is that **FastAPI**'s `HTTPException` accepts any JSON-able data for the `detail` field, while Starlette's `HTTPException` only accepts strings for it.\n\nSo, you can keep raising **FastAPI**'s `HTTPException` as normally in your code.\n\nBut when you register an exception handler, you should register it for Starlette's `HTTPException`.\n\nThis way, if any part of Starlette's internal code, or a Starlette extension or plug-in, raises a Starlette `HTTPException`, your handler will be able to catch and handle it.\n\nIn this example, to be able to have both `HTTPException`s in the same code, Starlette's exceptions is renamed to `StarletteHTTPException`:\n\n```Python\nfrom starlette.exceptions import HTTPException as StarletteHTTPException\n```\n\n### Reuse **FastAPI**'s exception handlers { #reuse-fastapis-exception-handlers }\n\nIf you want to use the exception along with the same default exception handlers from **FastAPI**, you can import and reuse the default exception handlers from `fastapi.exception_handlers`:\n\n{* ../../docs_src/handling_errors/tutorial006_py310.py hl[2:5,15,21] *}\n\nIn this example you are just printing the error with a very expressive message, but you get the idea. You can use the exception and then just reuse the default exception handlers.", "source_type": "doc", "path": "docs/en/docs/tutorial/handling-errors.md", "symbol": "Override the default exception handlers { #override-the-default-exception-handlers }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/handling-errors.md#L112-L244", "start_line": 112, "end_line": 244}
{"id": "docs/en/docs/tutorial/header-param-models.md::Header Parameter Models { #header-parameter-models }::L1", "text": "# Doc: docs/en/docs/tutorial/header-param-models.md | Page: Header Parameter Models { #header-parameter-models } | Section: Header Parameter Models { #header-parameter-models }\n# Header Parameter Models { #header-parameter-models }\n\nIf you have a group of related **header parameters**, you can create a **Pydantic model** to declare them.\n\nThis would allow you to **re-use the model** in **multiple places** and also to declare validations and metadata for all the parameters at once. 😎\n\n/// note\n\nThis is supported since FastAPI version `0.115.0`. 🤓\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/header-param-models.md", "symbol": "Header Parameter Models { #header-parameter-models }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/header-param-models.md#L1-L12", "start_line": 1, "end_line": 12}
{"id": "docs/en/docs/tutorial/header-param-models.md::Header Parameters with a Pydantic Model { #header-parameters-with-a-pydantic-model }::L13", "text": "# Doc: docs/en/docs/tutorial/header-param-models.md | Page: Header Parameter Models { #header-parameter-models } | Section: Header Parameters with a Pydantic Model { #header-parameters-with-a-pydantic-model }\n## Header Parameters with a Pydantic Model { #header-parameters-with-a-pydantic-model }\n\nDeclare the **header parameters** that you need in a **Pydantic model**, and then declare the parameter as `Header`:\n\n{* ../../docs_src/header_param_models/tutorial001_an_py310.py hl[9:14,18] *}\n\n**FastAPI** will **extract** the data for **each field** from the **headers** in the request and give you the Pydantic model you defined.", "source_type": "doc", "path": "docs/en/docs/tutorial/header-param-models.md", "symbol": "Header Parameters with a Pydantic Model { #header-parameters-with-a-pydantic-model }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/header-param-models.md#L13-L20", "start_line": 13, "end_line": 20}
{"id": "docs/en/docs/tutorial/header-param-models.md::Check the Docs { #check-the-docs }::L21", "text": "# Doc: docs/en/docs/tutorial/header-param-models.md | Page: Header Parameter Models { #header-parameter-models } | Section: Check the Docs { #check-the-docs }\n## Check the Docs { #check-the-docs }\n\nYou can see the required headers in the docs UI at `/docs`:\n\n![](\"/img/tutorial/header-param-models/image01.png\")
\ncontact fields| Parameter | Type | Description |
|---|---|---|
name | str | The identifying name of the contact person/organization. |
url | str | The URL pointing to the contact information. MUST be in the format of a URL. |
email | str | The email address of the contact person/organization. MUST be in the format of an email address. |
license_info fields| Parameter | Type | Description |
|---|---|---|
name | str | REQUIRED (if a license_info is set). The license name used for the API. |
identifier | str | An [SPDX](https://spdx.org/licenses/) license expression for the API. The identifier field is mutually exclusive of the url field. Available since OpenAPI 3.1.0, FastAPI 0.99.0. |
url | str | A URL to the license used for the API. MUST be in the format of a URL. |
![](\"/img/tutorial/metadata/image01.png\")
", "source_type": "doc", "path": "docs/en/docs/tutorial/metadata.md", "symbol": "Metadata for API { #metadata-for-api }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/metadata.md#L5-L32", "start_line": 5, "end_line": 32}
{"id": "docs/en/docs/tutorial/metadata.md::License identifier { #license-identifier }::L33", "text": "# Doc: docs/en/docs/tutorial/metadata.md | Page: Metadata and Docs URLs { #metadata-and-docs-urls } | Section: License identifier { #license-identifier }\n## License identifier { #license-identifier }\n\nSince OpenAPI 3.1.0 and FastAPI 0.99.0, you can also set the `license_info` with an `identifier` instead of a `url`.\n\nFor example:\n\n{* ../../docs_src/metadata/tutorial001_1_py310.py hl[31] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/metadata.md", "symbol": "License identifier { #license-identifier }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/metadata.md#L33-L40", "start_line": 33, "end_line": 40}
{"id": "docs/en/docs/tutorial/metadata.md::Metadata for tags { #metadata-for-tags }::L41", "text": "# Doc: docs/en/docs/tutorial/metadata.md | Page: Metadata and Docs URLs { #metadata-and-docs-urls } | Section: Metadata for tags { #metadata-for-tags }\n## Metadata for tags { #metadata-for-tags }\n\nYou can also add additional metadata for the different tags used to group your path operations with the parameter `openapi_tags`.\n\nIt takes a list containing one dictionary for each tag.\n\nEach dictionary can contain:\n\n* `name` (**required**): a `str` with the same tag name you use in the `tags` parameter in your *path operations* and `APIRouter`s.\n* `description`: a `str` with a short description for the tag. It can have Markdown and will be shown in the docs UI.\n* `externalDocs`: a `dict` describing external documentation with:\n * `description`: a `str` with a short description for the external docs.\n * `url` (**required**): a `str` with the URL for the external documentation.\n\n### Create metadata for tags { #create-metadata-for-tags }\n\nLet's try that in an example with tags for `users` and `items`.\n\nCreate metadata for your tags and pass it to the `openapi_tags` parameter:\n\n{* ../../docs_src/metadata/tutorial004_py310.py hl[3:16,18] *}\n\nNotice that you can use Markdown inside of the descriptions, for example \"login\" will be shown in bold (**login**) and \"fancy\" will be shown in italics (_fancy_).\n\n/// tip\n\nYou don't have to add metadata for all the tags that you use.\n\n///\n\n### Use your tags { #use-your-tags }\n\nUse the `tags` parameter with your *path operations* (and `APIRouter`s) to assign them to different tags:\n\n{* ../../docs_src/metadata/tutorial004_py310.py hl[21,26] *}\n\n/// note\n\nRead more about tags in [Path Operation Configuration](path-operation-configuration.md#tags).\n\n///\n\n### Check the docs { #check-the-docs }\n\nNow, if you check the docs, they will show all the additional metadata:\n\n![](\"/img/tutorial/metadata/image02.png\")
\n\n### Order of tags { #order-of-tags }\n\nThe order of each tag metadata dictionary also defines the order shown in the docs UI.\n\nFor example, even though `users` would go after `items` in alphabetical order, it is shown before them, because we added their metadata as the first dictionary in the list.", "source_type": "doc", "path": "docs/en/docs/tutorial/metadata.md", "symbol": "Metadata for tags { #metadata-for-tags }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/metadata.md#L41-L94", "start_line": 41, "end_line": 94}
{"id": "docs/en/docs/tutorial/metadata.md::OpenAPI URL { #openapi-url }::L95", "text": "# Doc: docs/en/docs/tutorial/metadata.md | Page: Metadata and Docs URLs { #metadata-and-docs-urls } | Section: OpenAPI URL { #openapi-url }\n## OpenAPI URL { #openapi-url }\n\nBy default, the OpenAPI schema is served at `/openapi.json`.\n\nBut you can configure it with the parameter `openapi_url`.\n\nFor example, to set it to be served at `/api/v1/openapi.json`:\n\n{* ../../docs_src/metadata/tutorial002_py310.py hl[3] *}\n\nIf you want to disable the OpenAPI schema completely you can set `openapi_url=None`, that will also disable the documentation user interfaces that use it.", "source_type": "doc", "path": "docs/en/docs/tutorial/metadata.md", "symbol": "OpenAPI URL { #openapi-url }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/metadata.md#L95-L106", "start_line": 95, "end_line": 106}
{"id": "docs/en/docs/tutorial/metadata.md::Docs URLs { #docs-urls }::L107", "text": "# Doc: docs/en/docs/tutorial/metadata.md | Page: Metadata and Docs URLs { #metadata-and-docs-urls } | Section: Docs URLs { #docs-urls }\n## Docs URLs { #docs-urls }\n\nYou can configure the two documentation user interfaces included:\n\n* **Swagger UI**: served at `/docs`.\n * You can set its URL with the parameter `docs_url`.\n * You can disable it by setting `docs_url=None`.\n* **ReDoc**: served at `/redoc`.\n * You can set its URL with the parameter `redoc_url`.\n * You can disable it by setting `redoc_url=None`.\n\nFor example, to set Swagger UI to be served at `/documentation` and disable ReDoc:\n\n{* ../../docs_src/metadata/tutorial003_py310.py hl[3] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/metadata.md", "symbol": "Docs URLs { #docs-urls }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/metadata.md#L107-L120", "start_line": 107, "end_line": 120}
{"id": "docs/en/docs/tutorial/middleware.md::Middleware { #middleware }::L1", "text": "# Doc: docs/en/docs/tutorial/middleware.md | Page: Middleware { #middleware } | Section: Middleware { #middleware }\n# Middleware { #middleware }\n\nYou can add middleware to **FastAPI** applications.\n\nA \"middleware\" is a function that works with every **request** before it is processed by any specific *path operation*. And also with every **response** before returning it.\n\n* It takes each **request** that comes to your application.\n* It can then do something to that **request** or run any needed code.\n* Then it passes the **request** to be processed by the rest of the application (by some *path operation*).\n* It then takes the **response** generated by the application (by some *path operation*).\n* It can do something to that **response** or run any needed code.\n* Then it returns the **response**.\n\n/// note | Technical Details\n\nIf you have dependencies with `yield`, the exit code will run *after* the middleware.\n\nIf there were any background tasks (covered in the [Background Tasks](background-tasks.md) section, you will see it later), they will run *after* all the middleware.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/middleware.md", "symbol": "Middleware { #middleware }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/middleware.md#L1-L21", "start_line": 1, "end_line": 21}
{"id": "docs/en/docs/tutorial/middleware.md::Create a middleware { #create-a-middleware }::L22", "text": "# Doc: docs/en/docs/tutorial/middleware.md | Page: Middleware { #middleware } | Section: Create a middleware { #create-a-middleware }\n## Create a middleware { #create-a-middleware }\n\nTo create a middleware you use the decorator `@app.middleware(\"http\")` on top of a function.\n\nThe middleware function receives:\n\n* The `request`.\n* A function `call_next` that will receive the `request` as a parameter.\n * This function will pass the `request` to the corresponding *path operation*.\n * Then it returns the `response` generated by the corresponding *path operation*.\n* You can then further modify the `response` before returning it.\n\n{* ../../docs_src/middleware/tutorial001_py310.py hl[8:9,11,14] *}\n\n/// tip\n\nKeep in mind that custom proprietary headers can be added [using the `X-` prefix](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).\n\nBut if you have custom headers that you want a client in a browser to be able to see, you need to add them to your CORS configurations ([CORS (Cross-Origin Resource Sharing)](cors.md)) using the parameter `expose_headers` documented in [Starlette's CORS docs](https://www.starlette.dev/middleware/#corsmiddleware).\n\n///\n\n/// note | Technical Details\n\nYou could also use `from starlette.requests import Request`.\n\n**FastAPI** provides it as a convenience for you, the developer. But it comes directly from Starlette.\n\n///\n\n### Before and after the `response` { #before-and-after-the-response }\n\nYou can add code to be run with the `request`, before any *path operation* receives it.\n\nAnd also after the `response` is generated, before returning it.\n\nFor example, you could add a custom header `X-Process-Time` containing the time in seconds that it took to process the request and generate a response:\n\n{* ../../docs_src/middleware/tutorial001_py310.py hl[10,12:13] *}\n\n/// tip\n\nHere we use [`time.perf_counter()`](https://docs.python.org/3/library/time.html#time.perf_counter) instead of `time.time()` because it can be more precise for these use cases. 🤓\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/middleware.md", "symbol": "Create a middleware { #create-a-middleware }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/middleware.md#L22-L67", "start_line": 22, "end_line": 67}
{"id": "docs/en/docs/tutorial/middleware.md::Multiple middleware execution order { #multiple-middleware-execution-order }::L68", "text": "# Doc: docs/en/docs/tutorial/middleware.md | Page: Middleware { #middleware } | Section: Multiple middleware execution order { #multiple-middleware-execution-order }\n## Multiple middleware execution order { #multiple-middleware-execution-order }\n\nWhen you add multiple middlewares using either `@app.middleware()` decorator or `app.add_middleware()` method, each new middleware wraps the application, forming a stack. The last middleware added is the *outermost*, and the first is the *innermost*.\n\nOn the request path, the *outermost* middleware runs first.\n\nOn the response path, it runs last.\n\nFor example:\n\n```Python\napp.add_middleware(MiddlewareA)\napp.add_middleware(MiddlewareB)\n```\n\nThis results in the following execution order:\n\n* **Request**: MiddlewareB → MiddlewareA → route\n\n* **Response**: route → MiddlewareA → MiddlewareB\n\nThis stacking behavior ensures that middlewares are executed in a predictable and controllable order.", "source_type": "doc", "path": "docs/en/docs/tutorial/middleware.md", "symbol": "Multiple middleware execution order { #multiple-middleware-execution-order }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/middleware.md#L68-L90", "start_line": 68, "end_line": 90}
{"id": "docs/en/docs/tutorial/middleware.md::Other middlewares { #other-middlewares }::L91", "text": "# Doc: docs/en/docs/tutorial/middleware.md | Page: Middleware { #middleware } | Section: Other middlewares { #other-middlewares }\n## Other middlewares { #other-middlewares }\n\nYou can later read more about other middlewares in the [Advanced User Guide: Advanced Middleware](../advanced/middleware.md).\n\nYou will read about how to handle CORS with a middleware in the next section.", "source_type": "doc", "path": "docs/en/docs/tutorial/middleware.md", "symbol": "Other middlewares { #other-middlewares }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/middleware.md#L91-L95", "start_line": 91, "end_line": 95}
{"id": "docs/en/docs/tutorial/path-operation-configuration.md::Path Operation Configuration { #path-operation-configuration }::L1", "text": "# Doc: docs/en/docs/tutorial/path-operation-configuration.md | Page: Path Operation Configuration { #path-operation-configuration } | Section: Path Operation Configuration { #path-operation-configuration }\n# Path Operation Configuration { #path-operation-configuration }\n\nThere are several parameters that you can pass to your *path operation decorator* to configure it.\n\n/// warning\n\nNotice that these parameters are passed directly to the *path operation decorator*, not to your *path operation function*.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/path-operation-configuration.md", "symbol": "Path Operation Configuration { #path-operation-configuration }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-operation-configuration.md#L1-L10", "start_line": 1, "end_line": 10}
{"id": "docs/en/docs/tutorial/path-operation-configuration.md::Response Status Code { #response-status-code }::L11", "text": "# Doc: docs/en/docs/tutorial/path-operation-configuration.md | Page: Path Operation Configuration { #path-operation-configuration } | Section: Response Status Code { #response-status-code }\n## Response Status Code { #response-status-code }\n\nYou can define the (HTTP) `status_code` to be used in the response of your *path operation*.\n\nYou can pass directly the `int` code, like `404`.\n\nBut if you don't remember what each number code is for, you can use the shortcut constants in `status`:\n\n{* ../../docs_src/path_operation_configuration/tutorial001_py310.py hl[1,15] *}\n\nThat status code will be used in the response and will be added to the OpenAPI schema.\n\n/// note | Technical Details\n\nYou could also use `from starlette import status`.\n\n**FastAPI** provides the same `starlette.status` as `fastapi.status` just as a convenience for you, the developer. But it comes directly from Starlette.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/path-operation-configuration.md", "symbol": "Response Status Code { #response-status-code }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-operation-configuration.md#L11-L30", "start_line": 11, "end_line": 30}
{"id": "docs/en/docs/tutorial/path-operation-configuration.md::Tags { #tags }::L31", "text": "# Doc: docs/en/docs/tutorial/path-operation-configuration.md | Page: Path Operation Configuration { #path-operation-configuration } | Section: Tags { #tags }\n## Tags { #tags }\n\nYou can add tags to your *path operation*, pass the parameter `tags` with a `list` of `str` (commonly just one `str`):\n\n{* ../../docs_src/path_operation_configuration/tutorial002_py310.py hl[15,20,25] *}\n\nThey will be added to the OpenAPI schema and used by the automatic documentation interfaces:\n\n![](\"/img/tutorial/path-operation-configuration/image01.png\")
\n\n### Tags with Enums { #tags-with-enums }\n\nIf you have a big application, you might end up accumulating **several tags**, and you would want to make sure you always use the **same tag** for related *path operations*.\n\nIn these cases, it could make sense to store the tags in an `Enum`.\n\n**FastAPI** supports that the same way as with plain strings:\n\n{* ../../docs_src/path_operation_configuration/tutorial002b_py310.py hl[1,8:10,13,18] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/path-operation-configuration.md", "symbol": "Tags { #tags }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-operation-configuration.md#L31-L50", "start_line": 31, "end_line": 50}
{"id": "docs/en/docs/tutorial/path-operation-configuration.md::Summary and description { #summary-and-description }::L51", "text": "# Doc: docs/en/docs/tutorial/path-operation-configuration.md | Page: Path Operation Configuration { #path-operation-configuration } | Section: Summary and description { #summary-and-description }\n## Summary and description { #summary-and-description }\n\nYou can add a `summary` and `description`:\n\n{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[17:18] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/path-operation-configuration.md", "symbol": "Summary and description { #summary-and-description }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-operation-configuration.md#L51-L56", "start_line": 51, "end_line": 56}
{"id": "docs/en/docs/tutorial/path-operation-configuration.md::Description from docstring { #description-from-docstring }::L57", "text": "# Doc: docs/en/docs/tutorial/path-operation-configuration.md | Page: Path Operation Configuration { #path-operation-configuration } | Section: Description from docstring { #description-from-docstring }\n## Description from docstring { #description-from-docstring }\n\nAs descriptions tend to be long and cover multiple lines, you can declare the *path operation* description in the function docstring and **FastAPI** will read it from there.\n\nYou can write [Markdown](https://en.wikipedia.org/wiki/Markdown) in the docstring, it will be interpreted and displayed correctly (taking into account docstring indentation).\n\n{* ../../docs_src/path_operation_configuration/tutorial004_py310.py hl[17:25] *}\n\nIt will be used in the interactive docs:\n\n![](\"/img/tutorial/path-operation-configuration/image02.png\")
", "source_type": "doc", "path": "docs/en/docs/tutorial/path-operation-configuration.md", "symbol": "Description from docstring { #description-from-docstring }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-operation-configuration.md#L57-L68", "start_line": 57, "end_line": 68}
{"id": "docs/en/docs/tutorial/path-operation-configuration.md::Response description { #response-description }::L69", "text": "# Doc: docs/en/docs/tutorial/path-operation-configuration.md | Page: Path Operation Configuration { #path-operation-configuration } | Section: Response description { #response-description }\n## Response description { #response-description }\n\nYou can specify the response description with the parameter `response_description`:\n\n{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[18] *}\n\n/// note\n\nNotice that `response_description` refers specifically to the response, the `description` refers to the *path operation* in general.\n\n///\n\n/// tip\n\nOpenAPI specifies that each *path operation* requires a response description.\n\nSo, if you don't provide one, **FastAPI** will automatically generate one of \"Successful response\".\n\n///\n\n![](\"/img/tutorial/path-operation-configuration/image03.png\")
", "source_type": "doc", "path": "docs/en/docs/tutorial/path-operation-configuration.md", "symbol": "Response description { #response-description }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-operation-configuration.md#L69-L90", "start_line": 69, "end_line": 90}
{"id": "docs/en/docs/tutorial/path-operation-configuration.md::Deprecate a *path operation* { #deprecate-a-path-operation }::L91", "text": "# Doc: docs/en/docs/tutorial/path-operation-configuration.md | Page: Path Operation Configuration { #path-operation-configuration } | Section: Deprecate a *path operation* { #deprecate-a-path-operation }\n## Deprecate a *path operation* { #deprecate-a-path-operation }\n\nIf you need to mark a *path operation* as deprecated, but without removing it, pass the parameter `deprecated`:\n\n{* ../../docs_src/path_operation_configuration/tutorial006_py310.py hl[16] *}\n\nIt will be clearly marked as deprecated in the interactive docs:\n\n![](\"/img/tutorial/path-operation-configuration/image04.png\")
\n\nCheck how deprecated and non-deprecated *path operations* look:\n\n![](\"/img/tutorial/path-operation-configuration/image05.png\")
", "source_type": "doc", "path": "docs/en/docs/tutorial/path-operation-configuration.md", "symbol": "Deprecate a *path operation* { #deprecate-a-path-operation }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-operation-configuration.md#L91-L104", "start_line": 91, "end_line": 104}
{"id": "docs/en/docs/tutorial/path-operation-configuration.md::Recap { #recap }::L105", "text": "# Doc: docs/en/docs/tutorial/path-operation-configuration.md | Page: Path Operation Configuration { #path-operation-configuration } | Section: Recap { #recap }\n## Recap { #recap }\n\nYou can configure and add metadata for your *path operations* easily by passing parameters to the *path operation decorators*.", "source_type": "doc", "path": "docs/en/docs/tutorial/path-operation-configuration.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-operation-configuration.md#L105-L107", "start_line": 105, "end_line": 107}
{"id": "docs/en/docs/tutorial/path-params-numeric-validations.md::Path Parameters and Numeric Validations { #path-parameters-and-numeric-validations }::L1", "text": "# Doc: docs/en/docs/tutorial/path-params-numeric-validations.md | Page: Path Parameters and Numeric Validations { #path-parameters-and-numeric-validations } | Section: Path Parameters and Numeric Validations { #path-parameters-and-numeric-validations }\n# Path Parameters and Numeric Validations { #path-parameters-and-numeric-validations }\n\nIn the same way that you can declare more validations and metadata for query parameters with `Query`, you can declare the same type of validations and metadata for path parameters with `Path`.", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params-numeric-validations.md", "symbol": "Path Parameters and Numeric Validations { #path-parameters-and-numeric-validations }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params-numeric-validations.md#L1-L4", "start_line": 1, "end_line": 4}
{"id": "docs/en/docs/tutorial/path-params-numeric-validations.md::Import `Path` { #import-path }::L5", "text": "# Doc: docs/en/docs/tutorial/path-params-numeric-validations.md | Page: Path Parameters and Numeric Validations { #path-parameters-and-numeric-validations } | Section: Import `Path` { #import-path }\n## Import `Path` { #import-path }\n\nFirst, import `Path` from `fastapi`, and import `Annotated`:\n\n{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}\n\n/// note\n\nFastAPI added support for `Annotated` (and started recommending it) in version 0.95.0.\n\nIf you have an older version, you would get errors when trying to use `Annotated`.\n\nMake sure you [Upgrade the FastAPI version](../deployment/versions.md#upgrading-the-fastapi-versions) to at least 0.95.1 before using `Annotated`.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params-numeric-validations.md", "symbol": "Import `Path` { #import-path }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params-numeric-validations.md#L5-L20", "start_line": 5, "end_line": 20}
{"id": "docs/en/docs/tutorial/path-params-numeric-validations.md::Declare metadata { #declare-metadata }::L21", "text": "# Doc: docs/en/docs/tutorial/path-params-numeric-validations.md | Page: Path Parameters and Numeric Validations { #path-parameters-and-numeric-validations } | Section: Declare metadata { #declare-metadata }\n## Declare metadata { #declare-metadata }\n\nYou can declare all the same parameters as for `Query`.\n\nFor example, to declare a `title` metadata value for the path parameter `item_id` you can type:\n\n{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *}\n\n/// note\n\nA path parameter is always required as it has to be part of the path. Even if you declared it with `None` or set a default value, it would not affect anything, it would still be always required.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params-numeric-validations.md", "symbol": "Declare metadata { #declare-metadata }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params-numeric-validations.md#L21-L34", "start_line": 21, "end_line": 34}
{"id": "docs/en/docs/tutorial/path-params-numeric-validations.md::Order the parameters as you need { #order-the-parameters-as-you-need }::L35", "text": "# Doc: docs/en/docs/tutorial/path-params-numeric-validations.md | Page: Path Parameters and Numeric Validations { #path-parameters-and-numeric-validations } | Section: Order the parameters as you need { #order-the-parameters-as-you-need }\n## Order the parameters as you need { #order-the-parameters-as-you-need }\n\n/// tip\n\nThis is probably not as important or necessary if you use `Annotated`.\n\n///\n\nLet's say that you want to declare the query parameter `q` as a required `str`.\n\nAnd you don't need to declare anything else for that parameter, so you don't really need to use `Query`.\n\nBut you still need to use `Path` for the `item_id` path parameter. And you don't want to use `Annotated` for some reason.\n\nPython will complain if you put a value with a \"default\" before a value that doesn't have a \"default\".\n\nBut you can re-order them, and have the value without a default (the query parameter `q`) first.\n\nIt doesn't matter for **FastAPI**. It will detect the parameters by their names, types and default declarations (`Query`, `Path`, etc), it doesn't care about the order.\n\nSo, you can declare your function as:\n\n{* ../../docs_src/path_params_numeric_validations/tutorial002_py310.py hl[7] *}\n\nBut keep in mind that if you use `Annotated`, you won't have this problem, it won't matter as you're not using the function parameter default values for `Query()` or `Path()`.\n\n{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py310.py *}", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params-numeric-validations.md", "symbol": "Order the parameters as you need { #order-the-parameters-as-you-need }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params-numeric-validations.md#L35-L62", "start_line": 35, "end_line": 62}
{"id": "docs/en/docs/tutorial/path-params-numeric-validations.md::Order the parameters as you need, tricks { #order-the-parameters-as-you-need-tricks }::L63", "text": "# Doc: docs/en/docs/tutorial/path-params-numeric-validations.md | Page: Path Parameters and Numeric Validations { #path-parameters-and-numeric-validations } | Section: Order the parameters as you need, tricks { #order-the-parameters-as-you-need-tricks }\n## Order the parameters as you need, tricks { #order-the-parameters-as-you-need-tricks }\n\n/// tip\n\nThis is probably not as important or necessary if you use `Annotated`.\n\n///\n\nHere's a **small trick** that can be handy, but you won't need it often.\n\nIf you want to:\n\n* declare the `q` query parameter without a `Query` nor any default value\n* declare the path parameter `item_id` using `Path`\n* have them in a different order\n* not use `Annotated`\n\n...Python has a little special syntax for that.\n\nPass `*`, as the first parameter of the function.\n\nPython won't do anything with that `*`, but it will know that all the following parameters should be called as keyword arguments (key-value pairs), also known as kwargs. Even if they don't have a default value.\n\n{* ../../docs_src/path_params_numeric_validations/tutorial003_py310.py hl[7] *}\n\n### Better with `Annotated` { #better-with-annotated }\n\nKeep in mind that if you use `Annotated`, as you are not using function parameter default values, you won't have this problem, and you probably won't need to use `*`.\n\n{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py310.py hl[10] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params-numeric-validations.md", "symbol": "Order the parameters as you need, tricks { #order-the-parameters-as-you-need-tricks }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params-numeric-validations.md#L63-L93", "start_line": 63, "end_line": 93}
{"id": "docs/en/docs/tutorial/path-params-numeric-validations.md::Number validations: greater than or equal { #number-validations-greater-than-or-equal }::L94", "text": "# Doc: docs/en/docs/tutorial/path-params-numeric-validations.md | Page: Path Parameters and Numeric Validations { #path-parameters-and-numeric-validations } | Section: Number validations: greater than or equal { #number-validations-greater-than-or-equal }\n## Number validations: greater than or equal { #number-validations-greater-than-or-equal }\n\nWith `Query` and `Path` (and others you'll see later) you can declare number constraints.\n\nHere, with `ge=1`, `item_id` will need to be an integer number \"`g`reater than or `e`qual\" to `1`.\n\n{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py310.py hl[10] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params-numeric-validations.md", "symbol": "Number validations: greater than or equal { #number-validations-greater-than-or-equal }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params-numeric-validations.md#L94-L101", "start_line": 94, "end_line": 101}
{"id": "docs/en/docs/tutorial/path-params-numeric-validations.md::Number validations: greater than and less than or equal { #number-validations-greater-than-and-less-than-or-equal }::L102", "text": "# Doc: docs/en/docs/tutorial/path-params-numeric-validations.md | Page: Path Parameters and Numeric Validations { #path-parameters-and-numeric-validations } | Section: Number validations: greater than and less than or equal { #number-validations-greater-than-and-less-than-or-equal }\n## Number validations: greater than and less than or equal { #number-validations-greater-than-and-less-than-or-equal }\n\nThe same applies for:\n\n* `gt`: `g`reater `t`han\n* `le`: `l`ess than or `e`qual\n\n{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py310.py hl[10] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params-numeric-validations.md", "symbol": "Number validations: greater than and less than or equal { #number-validations-greater-than-and-less-than-or-equal }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params-numeric-validations.md#L102-L110", "start_line": 102, "end_line": 110}
{"id": "docs/en/docs/tutorial/path-params-numeric-validations.md::Number validations: floats, greater than and less than { #number-validations-floats-greater-than-and-less-than }::L111", "text": "# Doc: docs/en/docs/tutorial/path-params-numeric-validations.md | Page: Path Parameters and Numeric Validations { #path-parameters-and-numeric-validations } | Section: Number validations: floats, greater than and less than { #number-validations-floats-greater-than-and-less-than }\n## Number validations: floats, greater than and less than { #number-validations-floats-greater-than-and-less-than }\n\nNumber validations also work for `float` values.\n\nHere's where it becomes important to be able to declare gt and not just ge. As with it you can require, for example, that a value must be greater than `0`, even if it is less than `1`.\n\nSo, `0.5` would be a valid value. But `0.0` or `0` would not.\n\nAnd the same for lt.\n\n{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py310.py hl[13] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params-numeric-validations.md", "symbol": "Number validations: floats, greater than and less than { #number-validations-floats-greater-than-and-less-than }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params-numeric-validations.md#L111-L122", "start_line": 111, "end_line": 122}
{"id": "docs/en/docs/tutorial/path-params-numeric-validations.md::Recap { #recap }::L123", "text": "# Doc: docs/en/docs/tutorial/path-params-numeric-validations.md | Page: Path Parameters and Numeric Validations { #path-parameters-and-numeric-validations } | Section: Recap { #recap }\n## Recap { #recap }\n\nWith `Query`, `Path` (and others you haven't seen yet) you can declare metadata and string validations in the same ways as with [Query Parameters and String Validations](query-params-str-validations.md).\n\nAnd you can also declare numeric validations:\n\n* `gt`: `g`reater `t`han\n* `ge`: `g`reater than or `e`qual\n* `lt`: `l`ess `t`han\n* `le`: `l`ess than or `e`qual\n\n/// note\n\n`Query`, `Path`, and other classes you will see later are subclasses of a common `Param` class.\n\nAll of them share the same parameters for additional validation and metadata you have seen.\n\n///\n\n/// note | Technical Details\n\nWhen you import `Query`, `Path` and others from `fastapi`, they are actually functions.\n\nThat when called, return instances of classes of the same name.\n\nSo, you import `Query`, which is a function. And when you call it, it returns an instance of a class also named `Query`.\n\nThese functions are there (instead of just using the classes directly) so that your editor doesn't mark errors about their types.\n\nThat way you can use your normal editor and coding tools without having to add custom configurations to disregard those errors.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params-numeric-validations.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params-numeric-validations.md#L123-L154", "start_line": 123, "end_line": 154}
{"id": "docs/en/docs/tutorial/path-params.md::Path Parameters { #path-parameters }::L1", "text": "# Doc: docs/en/docs/tutorial/path-params.md | Page: Path Parameters { #path-parameters } | Section: Path Parameters { #path-parameters }\n# Path Parameters { #path-parameters }\n\nYou can declare path \"parameters\" or \"variables\" with the same syntax used by Python format strings:\n\n{* ../../docs_src/path_params/tutorial001_py310.py hl[6:7] *}\n\nThe value of the path parameter `item_id` will be passed to your function as the argument `item_id`.\n\nSo, if you run this example and go to [http://127.0.0.1:8000/items/foo](http://127.0.0.1:8000/items/foo), you will see a response of:\n\n```JSON\n{\"item_id\":\"foo\"}\n```", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params.md", "symbol": "Path Parameters { #path-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params.md#L1-L14", "start_line": 1, "end_line": 14}
{"id": "docs/en/docs/tutorial/path-params.md::Path parameters with types { #path-parameters-with-types }::L15", "text": "# Doc: docs/en/docs/tutorial/path-params.md | Page: Path Parameters { #path-parameters } | Section: Path parameters with types { #path-parameters-with-types }\n## Path parameters with types { #path-parameters-with-types }\n\nYou can declare the type of a path parameter in the function, using standard Python type annotations:\n\n{* ../../docs_src/path_params/tutorial002_py310.py hl[7] *}\n\nIn this case, `item_id` is declared to be an `int`.\n\n/// tip\n\nThis will give you editor support inside of your function, with error checks, completion, etc.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params.md", "symbol": "Path parameters with types { #path-parameters-with-types }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params.md#L15-L28", "start_line": 15, "end_line": 28}
{"id": "docs/en/docs/tutorial/path-params.md::Data conversion { #data-conversion }::L29", "text": "# Doc: docs/en/docs/tutorial/path-params.md | Page: Path Parameters { #path-parameters } | Section: Data conversion { #data-conversion }\n## Data conversion { #data-conversion }\n\nIf you run this example and open your browser at [http://127.0.0.1:8000/items/3](http://127.0.0.1:8000/items/3), you will see a response of:\n\n```JSON\n{\"item_id\":3}\n```\n\n/// tip\n\nNotice that the value your function received (and returned) is `3`, as a Python `int`, not a string `\"3\"`.\n\nSo, with that type declaration, **FastAPI** gives you automatic request \"parsing\".\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params.md", "symbol": "Data conversion { #data-conversion }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params.md#L29-L44", "start_line": 29, "end_line": 44}
{"id": "docs/en/docs/tutorial/path-params.md::Data validation { #data-validation }::L45", "text": "# Doc: docs/en/docs/tutorial/path-params.md | Page: Path Parameters { #path-parameters } | Section: Data validation { #data-validation }\n## Data validation { #data-validation }\n\nBut if you go to the browser at [http://127.0.0.1:8000/items/foo](http://127.0.0.1:8000/items/foo), you will see a nice HTTP error of:\n\n```JSON\n{\n \"detail\": [\n {\n \"type\": \"int_parsing\",\n \"loc\": [\n \"path\",\n \"item_id\"\n ],\n \"msg\": \"Input should be a valid integer, unable to parse string as an integer\",\n \"input\": \"foo\"\n }\n ]\n}\n```\n\nbecause the path parameter `item_id` had a value of `\"foo\"`, which is not an `int`.\n\nThe same error would appear if you provided a `float` instead of an `int`, as in: [http://127.0.0.1:8000/items/4.2](http://127.0.0.1:8000/items/4.2)\n\n/// tip\n\nSo, with the same Python type declaration, **FastAPI** gives you data validation.\n\nNotice that the error also clearly states exactly the point where the validation didn't pass.\n\nThis is incredibly helpful while developing and debugging code that interacts with your API.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params.md", "symbol": "Data validation { #data-validation }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params.md#L45-L78", "start_line": 45, "end_line": 78}
{"id": "docs/en/docs/tutorial/path-params.md::Documentation { #documentation }::L79", "text": "# Doc: docs/en/docs/tutorial/path-params.md | Page: Path Parameters { #path-parameters } | Section: Documentation { #documentation }\n## Documentation { #documentation }\n\nAnd when you open your browser at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs), you will see an automatic, interactive, API documentation like:\n\n![](\"/img/tutorial/path-params/image01.png\")
\n\n/// tip\n\nAgain, just with that same Python type declaration, **FastAPI** gives you automatic, interactive documentation (integrating Swagger UI).\n\nNotice that the path parameter is declared to be an integer.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params.md", "symbol": "Documentation { #documentation }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params.md#L79-L92", "start_line": 79, "end_line": 92}
{"id": "docs/en/docs/tutorial/path-params.md::Standards-based benefits, alternative documentation { #standards-based-benefits-alternative-documentation }::L93", "text": "# Doc: docs/en/docs/tutorial/path-params.md | Page: Path Parameters { #path-parameters } | Section: Standards-based benefits, alternative documentation { #standards-based-benefits-alternative-documentation }\n## Standards-based benefits, alternative documentation { #standards-based-benefits-alternative-documentation }\n\nAnd because the generated schema is from the [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md) standard, there are many compatible tools.\n\nBecause of this, **FastAPI** itself provides an alternative API documentation (using ReDoc), which you can access at [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc):\n\n![](\"/img/tutorial/path-params/image02.png\")
\n\nThe same way, there are many compatible tools. Including code generation tools for many languages.", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params.md", "symbol": "Standards-based benefits, alternative documentation { #standards-based-benefits-alternative-documentation }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params.md#L93-L102", "start_line": 93, "end_line": 102}
{"id": "docs/en/docs/tutorial/path-params.md::Pydantic { #pydantic }::L103", "text": "# Doc: docs/en/docs/tutorial/path-params.md | Page: Path Parameters { #path-parameters } | Section: Pydantic { #pydantic }\n## Pydantic { #pydantic }\n\nAll the data validation is performed under the hood by [Pydantic](https://docs.pydantic.dev/), so you get all the benefits from it. And you know you are in good hands.\n\nYou can use the same type declarations with `str`, `float`, `bool` and many other complex data types.\n\nSeveral of these are explored in the next chapters of the tutorial.", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params.md", "symbol": "Pydantic { #pydantic }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params.md#L103-L110", "start_line": 103, "end_line": 110}
{"id": "docs/en/docs/tutorial/path-params.md::Order matters { #order-matters }::L111", "text": "# Doc: docs/en/docs/tutorial/path-params.md | Page: Path Parameters { #path-parameters } | Section: Order matters { #order-matters }\n## Order matters { #order-matters }\n\nWhen creating *path operations*, you can find situations where you have a fixed path.\n\nLike `/users/me`, let's say that it's to get data about the current user.\n\nAnd then you can also have a path `/users/{user_id}` to get data about a specific user by some user ID.\n\nBecause *path operations* are evaluated in order, you need to make sure that the path for `/users/me` is declared before the one for `/users/{user_id}`:\n\n{* ../../docs_src/path_params/tutorial003_py310.py hl[6,11] *}\n\nOtherwise, the path for `/users/{user_id}` would match also for `/users/me`, \"thinking\" that it's receiving a parameter `user_id` with a value of `\"me\"`.\n\nSimilarly, you cannot redefine a path operation:\n\n{* ../../docs_src/path_params/tutorial003b_py310.py hl[6,11] *}\n\nThe first one will always be used since the path matches first.", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params.md", "symbol": "Order matters { #order-matters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params.md#L111-L130", "start_line": 111, "end_line": 130}
{"id": "docs/en/docs/tutorial/path-params.md::Predefined values { #predefined-values }::L131", "text": "# Doc: docs/en/docs/tutorial/path-params.md | Page: Path Parameters { #path-parameters } | Section: Predefined values { #predefined-values }\n## Predefined values { #predefined-values }\n\nIf you have a *path operation* that receives a *path parameter*, but you want the possible valid *path parameter* values to be predefined, you can use a standard Python `Enum`.\n\n### Create an `Enum` class { #create-an-enum-class }\n\nImport `Enum` and create a sub-class that inherits from `str` and from `Enum`.\n\nBy inheriting from `str` the API docs will be able to know that the values must be of type `string` and will be able to render correctly.\n\nThen create class attributes with fixed values, which will be the available valid values:\n\n{* ../../docs_src/path_params/tutorial005_py310.py hl[1,6:9] *}\n\n/// tip\n\nIf you are wondering, \"AlexNet\", \"ResNet\", and \"LeNet\" are just names of Machine Learning models.\n\n///\n\n### Declare a *path parameter* { #declare-a-path-parameter }\n\nThen create a *path parameter* with a type annotation using the enum class you created (`ModelName`):\n\n{* ../../docs_src/path_params/tutorial005_py310.py hl[16] *}\n\n### Check the docs { #check-the-docs }\n\nBecause the available values for the *path parameter* are predefined, the interactive docs can show them nicely:\n\n![](\"/img/tutorial/path-params/image03.png\")
\n\n### Working with Python *enumerations* { #working-with-python-enumerations }\n\nThe value of the *path parameter* will be an *enumeration member*.\n\n#### Compare *enumeration members* { #compare-enumeration-members }\n\nYou can compare it with the *enumeration member* in your created enum `ModelName`:\n\n{* ../../docs_src/path_params/tutorial005_py310.py hl[17] *}\n\n#### Get the *enumeration value* { #get-the-enumeration-value }\n\nYou can get the actual value (a `str` in this case) using `model_name.value`, or in general, `your_enum_member.value`:\n\n{* ../../docs_src/path_params/tutorial005_py310.py hl[20] *}\n\n/// tip\n\nYou could also access the value `\"lenet\"` with `ModelName.lenet.value`.\n\n///\n\n#### Return *enumeration members* { #return-enumeration-members }\n\nYou can return *enum members* from your *path operation*, even nested in a JSON body (e.g. a `dict`).\n\nThey will be converted to their corresponding values (strings in this case) before returning them to the client:\n\n{* ../../docs_src/path_params/tutorial005_py310.py hl[18,21,23] *}\n\nIn your client you will get a JSON response like:\n\n```JSON\n{\n \"model_name\": \"alexnet\",\n \"message\": \"Deep Learning FTW!\"\n}\n```", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params.md", "symbol": "Predefined values { #predefined-values }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params.md#L131-L201", "start_line": 131, "end_line": 201}
{"id": "docs/en/docs/tutorial/path-params.md::Path parameters containing paths { #path-parameters-containing-paths }::L202", "text": "# Doc: docs/en/docs/tutorial/path-params.md | Page: Path Parameters { #path-parameters } | Section: Path parameters containing paths { #path-parameters-containing-paths }\n## Path parameters containing paths { #path-parameters-containing-paths }\n\nLet's say you have a *path operation* with a path `/files/{file_path}`.\n\nBut you need `file_path` itself to contain a *path*, like `home/johndoe/myfile.txt`.\n\nSo, the URL for that file would be something like: `/files/home/johndoe/myfile.txt`.\n\n### OpenAPI support { #openapi-support }\n\nOpenAPI doesn't support a way to declare a *path parameter* to contain a *path* inside, as that could lead to scenarios that are difficult to test and define.\n\nNevertheless, you can still do it in **FastAPI**, using one of the internal tools from Starlette.\n\nAnd the docs would still work, although not adding any documentation telling that the parameter should contain a path.\n\n### Path convertor { #path-convertor }\n\nUsing an option directly from Starlette you can declare a *path parameter* containing a *path* using a URL like:\n\n```\n/files/{file_path:path}\n```\n\nIn this case, the name of the parameter is `file_path`, and the last part, `:path`, tells it that the parameter should match any *path*.\n\nSo, you can use it with:\n\n{* ../../docs_src/path_params/tutorial004_py310.py hl[6] *}\n\n/// tip\n\nYou might need the parameter to contain `/home/johndoe/myfile.txt`, with a leading slash (`/`).\n\nIn that case, the URL would be: `/files//home/johndoe/myfile.txt`, with a double slash (`//`) between `files` and `home`.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params.md", "symbol": "Path parameters containing paths { #path-parameters-containing-paths }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params.md#L202-L239", "start_line": 202, "end_line": 239}
{"id": "docs/en/docs/tutorial/path-params.md::Recap { #recap }::L240", "text": "# Doc: docs/en/docs/tutorial/path-params.md | Page: Path Parameters { #path-parameters } | Section: Recap { #recap }\n## Recap { #recap }\n\nWith **FastAPI**, by using short, intuitive and standard Python type declarations, you get:\n\n* Editor support: error checks, autocompletion, etc.\n* Data \"parsing\"\n* Data validation\n* API annotation and automatic documentation\n\nAnd you only have to declare them once.\n\nThat's probably the main visible advantage of **FastAPI** compared to alternative frameworks (apart from the raw performance).", "source_type": "doc", "path": "docs/en/docs/tutorial/path-params.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/path-params.md#L240-L251", "start_line": 240, "end_line": 251}
{"id": "docs/en/docs/tutorial/query-param-models.md::Query Parameter Models { #query-parameter-models }::L1", "text": "# Doc: docs/en/docs/tutorial/query-param-models.md | Page: Query Parameter Models { #query-parameter-models } | Section: Query Parameter Models { #query-parameter-models }\n# Query Parameter Models { #query-parameter-models }\n\nIf you have a group of **query parameters** that are related, you can create a **Pydantic model** to declare them.\n\nThis would allow you to **re-use the model** in **multiple places** and also to declare validations and metadata for all the parameters at once. 😎\n\n/// note\n\nThis is supported since FastAPI version `0.115.0`. 🤓\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/query-param-models.md", "symbol": "Query Parameter Models { #query-parameter-models }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/query-param-models.md#L1-L12", "start_line": 1, "end_line": 12}
{"id": "docs/en/docs/tutorial/query-param-models.md::Query Parameters with a Pydantic Model { #query-parameters-with-a-pydantic-model }::L13", "text": "# Doc: docs/en/docs/tutorial/query-param-models.md | Page: Query Parameter Models { #query-parameter-models } | Section: Query Parameters with a Pydantic Model { #query-parameters-with-a-pydantic-model }\n## Query Parameters with a Pydantic Model { #query-parameters-with-a-pydantic-model }\n\nDeclare the **query parameters** that you need in a **Pydantic model**, and then declare the parameter as `Query`:\n\n{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}\n\n**FastAPI** will **extract** the data for **each field** from the **query parameters** in the request and give you the Pydantic model you defined.", "source_type": "doc", "path": "docs/en/docs/tutorial/query-param-models.md", "symbol": "Query Parameters with a Pydantic Model { #query-parameters-with-a-pydantic-model }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/query-param-models.md#L13-L20", "start_line": 13, "end_line": 20}
{"id": "docs/en/docs/tutorial/query-param-models.md::Check the Docs { #check-the-docs }::L21", "text": "# Doc: docs/en/docs/tutorial/query-param-models.md | Page: Query Parameter Models { #query-parameter-models } | Section: Check the Docs { #check-the-docs }\n## Check the Docs { #check-the-docs }\n\nYou can see the query parameters in the docs UI at `/docs`:\n\n![](\"/img/tutorial/query-param-models/image01.png\")
\n![](\"/img/tutorial/query-params-str-validations/image02.png\")
\n\n### Query parameter list / multiple values with defaults { #query-parameter-list-multiple-values-with-defaults }\n\nYou can also define a default `list` of values if none are provided:\n\n{* ../../docs_src/query_params_str_validations/tutorial012_an_py310.py hl[9] *}\n\nIf you go to:\n\n```\nhttp://localhost:8000/items/\n```\n\nthe default of `q` will be: `[\"foo\", \"bar\"]` and your response will be:\n\n```JSON\n{\n \"q\": [\n \"foo\",\n \"bar\"\n ]\n}\n```\n\n#### Using just `list` { #using-just-list }\n\nYou can also use `list` directly instead of `list[str]`:\n\n{* ../../docs_src/query_params_str_validations/tutorial013_an_py310.py hl[9] *}\n\n/// note\n\nKeep in mind that in this case, FastAPI won't check the contents of the list.\n\nFor example, `list[int]` would check (and document) that the contents of the list are integers. But `list` alone wouldn't.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/query-params-str-validations.md", "symbol": "Query parameter list / multiple values { #query-parameter-list-multiple-values }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/query-params-str-validations.md#L231-L304", "start_line": 231, "end_line": 304}
{"id": "docs/en/docs/tutorial/query-params-str-validations.md::Declare more metadata { #declare-more-metadata }::L305", "text": "# Doc: docs/en/docs/tutorial/query-params-str-validations.md | Page: Query Parameters and String Validations { #query-parameters-and-string-validations } | Section: Declare more metadata { #declare-more-metadata }\n## Declare more metadata { #declare-more-metadata }\n\nYou can add more information about the parameter.\n\nThat information will be included in the generated OpenAPI and used by the documentation user interfaces and external tools.\n\n/// note\n\nKeep in mind that different tools might have different levels of OpenAPI support.\n\nSome of them might not show all the extra information declared yet, although in most of the cases, the missing feature is already planned for development.\n\n///\n\nYou can add a `title`:\n\n{* ../../docs_src/query_params_str_validations/tutorial007_an_py310.py hl[10] *}\n\nAnd a `description`:\n\n{* ../../docs_src/query_params_str_validations/tutorial008_an_py310.py hl[14] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/query-params-str-validations.md", "symbol": "Declare more metadata { #declare-more-metadata }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/query-params-str-validations.md#L305-L326", "start_line": 305, "end_line": 326}
{"id": "docs/en/docs/tutorial/query-params-str-validations.md::Alias parameters { #alias-parameters }::L327", "text": "# Doc: docs/en/docs/tutorial/query-params-str-validations.md | Page: Query Parameters and String Validations { #query-parameters-and-string-validations } | Section: Alias parameters { #alias-parameters }\n## Alias parameters { #alias-parameters }\n\nImagine that you want the parameter to be `item-query`.\n\nLike in:\n\n```\nhttp://127.0.0.1:8000/items/?item-query=foobaritems\n```\n\nBut `item-query` is not a valid Python variable name.\n\nThe closest would be `item_query`.\n\nBut you still need it to be exactly `item-query`...\n\nThen you can declare an `alias`, and that alias is what will be used to find the parameter value:\n\n{* ../../docs_src/query_params_str_validations/tutorial009_an_py310.py hl[9] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/query-params-str-validations.md", "symbol": "Alias parameters { #alias-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/query-params-str-validations.md#L327-L346", "start_line": 327, "end_line": 346}
{"id": "docs/en/docs/tutorial/query-params-str-validations.md::Deprecating parameters { #deprecating-parameters }::L347", "text": "# Doc: docs/en/docs/tutorial/query-params-str-validations.md | Page: Query Parameters and String Validations { #query-parameters-and-string-validations } | Section: Deprecating parameters { #deprecating-parameters }\n## Deprecating parameters { #deprecating-parameters }\n\nNow let's say you don't like this parameter anymore.\n\nYou have to leave it there a while because there are clients using it, but you want the docs to clearly show it as deprecated.\n\nThen pass the parameter `deprecated=True` to `Query`:\n\n{* ../../docs_src/query_params_str_validations/tutorial010_an_py310.py hl[19] *}\n\nThe docs will show it like this:\n\n![](\"/img/tutorial/query-params-str-validations/image01.png\")
", "source_type": "doc", "path": "docs/en/docs/tutorial/query-params-str-validations.md", "symbol": "Deprecating parameters { #deprecating-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/query-params-str-validations.md#L347-L360", "start_line": 347, "end_line": 360}
{"id": "docs/en/docs/tutorial/query-params-str-validations.md::Exclude parameters from OpenAPI { #exclude-parameters-from-openapi }::L361", "text": "# Doc: docs/en/docs/tutorial/query-params-str-validations.md | Page: Query Parameters and String Validations { #query-parameters-and-string-validations } | Section: Exclude parameters from OpenAPI { #exclude-parameters-from-openapi }\n## Exclude parameters from OpenAPI { #exclude-parameters-from-openapi }\n\nTo exclude a query parameter from the generated OpenAPI schema (and thus, from the automatic documentation systems), set the parameter `include_in_schema` of `Query` to `False`:\n\n{* ../../docs_src/query_params_str_validations/tutorial014_an_py310.py hl[10] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/query-params-str-validations.md", "symbol": "Exclude parameters from OpenAPI { #exclude-parameters-from-openapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/query-params-str-validations.md#L361-L366", "start_line": 361, "end_line": 366}
{"id": "docs/en/docs/tutorial/query-params-str-validations.md::Custom Validation { #custom-validation }::L367", "text": "# Doc: docs/en/docs/tutorial/query-params-str-validations.md | Page: Query Parameters and String Validations { #query-parameters-and-string-validations } | Section: Custom Validation { #custom-validation }\n## Custom Validation { #custom-validation }\n\nThere could be cases where you need to do some **custom validation** that can't be done with the parameters shown above.\n\nIn those cases, you can use a **custom validator function** that is applied after the normal validation (e.g. after validating that the value is a `str`).\n\nYou can achieve that using [Pydantic's `AfterValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator) inside of `Annotated`.\n\n/// tip\n\nPydantic also has [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator) and others. 🤓\n\n///\n\nFor example, this custom validator checks that the item ID starts with `isbn-` for an ISBN book number or with `imdb-` for an IMDB movie URL ID:\n\n{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *}\n\n/// note\n\nThis is available with Pydantic version 2 or above. 😎\n\n///\n\n/// tip\n\nIf you need to do any type of validation that requires communicating with any **external component**, like a database or another API, you should instead use **FastAPI Dependencies**, you will learn about them later.\n\nThese custom validators are for things that can be checked with **only** the **same data** provided in the request.\n\n///\n\n### Understand that Code { #understand-that-code }\n\nThe important point is just using **`AfterValidator` with a function inside `Annotated`**. Feel free to skip this part. 🤸\n\n---\n\nBut if you're curious about this specific code example and you're still entertained, here are some extra details.\n\n#### String with `value.startswith()` { #string-with-value-startswith }\n\nDid you notice? A string using `value.startswith()` can take a tuple, and it will check each value in the tuple:\n\n{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[16:19] hl[17] *}\n\n#### A Random Item { #a-random-item }\n\nWith `data.items()` we get an iterable object with tuples containing the key and value for each dictionary item.\n\nWe convert this iterable object into a proper `list` with `list(data.items())`.\n\nThen with `random.choice()` we can get a **random value** from the list, so, we get a tuple with `(id, name)`. It will be something like `(\"imdb-tt0371724\", \"The Hitchhiker's Guide to the Galaxy\")`.\n\nThen we **assign those two values** of the tuple to the variables `id` and `name`.\n\nSo, if the user didn't provide an item ID, they will still receive a random suggestion.\n\n...we do all this in a **single simple line**. 🤯 Don't you love Python? 🐍\n\n{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[22:30] hl[29] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/query-params-str-validations.md", "symbol": "Custom Validation { #custom-validation }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/query-params-str-validations.md#L367-L428", "start_line": 367, "end_line": 428}
{"id": "docs/en/docs/tutorial/query-params-str-validations.md::Recap { #recap }::L429", "text": "# Doc: docs/en/docs/tutorial/query-params-str-validations.md | Page: Query Parameters and String Validations { #query-parameters-and-string-validations } | Section: Recap { #recap }\n## Recap { #recap }\n\nYou can declare additional validations and metadata for your parameters.\n\nGeneric validations and metadata:\n\n* `alias`\n* `title`\n* `description`\n* `deprecated`\n\nValidations specific for strings:\n\n* `min_length`\n* `max_length`\n* `pattern`\n\nCustom validations using `AfterValidator`.\n\nIn these examples you saw how to declare validations for `str` values.\n\nSee the next chapters to learn how to declare validations for other types, like numbers.", "source_type": "doc", "path": "docs/en/docs/tutorial/query-params-str-validations.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/query-params-str-validations.md#L429-L450", "start_line": 429, "end_line": 450}
{"id": "docs/en/docs/tutorial/query-params.md::Query Parameters { #query-parameters }::L1", "text": "# Doc: docs/en/docs/tutorial/query-params.md | Page: Query Parameters { #query-parameters } | Section: Query Parameters { #query-parameters }\n# Query Parameters { #query-parameters }\n\nWhen you declare other function parameters that are not part of the path parameters, they are automatically interpreted as \"query\" parameters.\n\n{* ../../docs_src/query_params/tutorial001_py310.py hl[9] *}\n\nThe query is the set of key-value pairs that go after the `?` in a URL, separated by `&` characters.\n\nFor example, in the URL:\n\n```\nhttp://127.0.0.1:8000/items/?skip=0&limit=10\n```\n\n...the query parameters are:\n\n* `skip`: with a value of `0`\n* `limit`: with a value of `10`\n\nAs they are part of the URL, they are \"naturally\" strings.\n\nBut when you declare them with Python types (in the example above, as `int`), they are converted to that type and validated against it.\n\nAll the same processes that apply to path parameters also apply to query parameters:\n\n* Editor support (obviously)\n* Data \"parsing\"\n* Data validation\n* Automatic documentation", "source_type": "doc", "path": "docs/en/docs/tutorial/query-params.md", "symbol": "Query Parameters { #query-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/query-params.md#L1-L30", "start_line": 1, "end_line": 30}
{"id": "docs/en/docs/tutorial/query-params.md::Defaults { #defaults }::L31", "text": "# Doc: docs/en/docs/tutorial/query-params.md | Page: Query Parameters { #query-parameters } | Section: Defaults { #defaults }\n## Defaults { #defaults }\n\nAs query parameters are not a fixed part of a path, they can be optional and can have default values.\n\nIn the example above they have default values of `skip=0` and `limit=10`.\n\nSo, going to the URL:\n\n```\nhttp://127.0.0.1:8000/items/\n```\n\nwould be the same as going to:\n\n```\nhttp://127.0.0.1:8000/items/?skip=0&limit=10\n```\n\nBut if you go to, for example:\n\n```\nhttp://127.0.0.1:8000/items/?skip=20\n```\n\nThe parameter values in your function will be:\n\n* `skip=20`: because you set it in the URL\n* `limit=10`: because that was the default value", "source_type": "doc", "path": "docs/en/docs/tutorial/query-params.md", "symbol": "Defaults { #defaults }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/query-params.md#L31-L59", "start_line": 31, "end_line": 59}
{"id": "docs/en/docs/tutorial/query-params.md::Optional parameters { #optional-parameters }::L60", "text": "# Doc: docs/en/docs/tutorial/query-params.md | Page: Query Parameters { #query-parameters } | Section: Optional parameters { #optional-parameters }\n## Optional parameters { #optional-parameters }\n\nThe same way, you can declare optional query parameters, by setting their default to `None`:\n\n{* ../../docs_src/query_params/tutorial002_py310.py hl[7] *}\n\nIn this case, the function parameter `q` will be optional, and will be `None` by default.\n\n/// tip\n\nAlso notice that **FastAPI** is smart enough to notice that the path parameter `item_id` is a path parameter and `q` is not, so, it's a query parameter.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/query-params.md", "symbol": "Optional parameters { #optional-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/query-params.md#L60-L73", "start_line": 60, "end_line": 73}
{"id": "docs/en/docs/tutorial/query-params.md::Query parameter type conversion { #query-parameter-type-conversion }::L74", "text": "# Doc: docs/en/docs/tutorial/query-params.md | Page: Query Parameters { #query-parameters } | Section: Query parameter type conversion { #query-parameter-type-conversion }\n## Query parameter type conversion { #query-parameter-type-conversion }\n\nYou can also declare `bool` types, and they will be converted:\n\n{* ../../docs_src/query_params/tutorial003_py310.py hl[7] *}\n\nIn this case, if you go to:\n\n```\nhttp://127.0.0.1:8000/items/foo?short=1\n```\n\nor\n\n```\nhttp://127.0.0.1:8000/items/foo?short=True\n```\n\nor\n\n```\nhttp://127.0.0.1:8000/items/foo?short=true\n```\n\nor\n\n```\nhttp://127.0.0.1:8000/items/foo?short=on\n```\n\nor\n\n```\nhttp://127.0.0.1:8000/items/foo?short=yes\n```\n\nor any other case variation (uppercase, first letter in uppercase, etc), your function will see the parameter `short` with a `bool` value of `True`. Otherwise as `False`.", "source_type": "doc", "path": "docs/en/docs/tutorial/query-params.md", "symbol": "Query parameter type conversion { #query-parameter-type-conversion }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/query-params.md#L74-L112", "start_line": 74, "end_line": 112}
{"id": "docs/en/docs/tutorial/query-params.md::Multiple path and query parameters { #multiple-path-and-query-parameters }::L113", "text": "# Doc: docs/en/docs/tutorial/query-params.md | Page: Query Parameters { #query-parameters } | Section: Multiple path and query parameters { #multiple-path-and-query-parameters }\n## Multiple path and query parameters { #multiple-path-and-query-parameters }\n\nYou can declare multiple path parameters and query parameters at the same time, **FastAPI** knows which is which.\n\nAnd you don't have to declare them in any specific order.\n\nThey will be detected by name:\n\n{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/query-params.md", "symbol": "Multiple path and query parameters { #multiple-path-and-query-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/query-params.md#L113-L122", "start_line": 113, "end_line": 122}
{"id": "docs/en/docs/tutorial/query-params.md::Required query parameters { #required-query-parameters }::L123", "text": "# Doc: docs/en/docs/tutorial/query-params.md | Page: Query Parameters { #query-parameters } | Section: Required query parameters { #required-query-parameters }\n## Required query parameters { #required-query-parameters }\n\nWhen you declare a default value for non-path parameters (for now, we have only seen query parameters), then it is not required.\n\nIf you don't want to add a specific value but just make it optional, set the default as `None`.\n\nBut when you want to make a query parameter required, you can just not declare any default value:\n\n{* ../../docs_src/query_params/tutorial005_py310.py hl[6:7] *}\n\nHere the query parameter `needy` is a required query parameter of type `str`.\n\nIf you open in your browser a URL like:\n\n```\nhttp://127.0.0.1:8000/items/foo-item\n```\n\n...without adding the required parameter `needy`, you will see an error like:\n\n```JSON\n{\n \"detail\": [\n {\n \"type\": \"missing\",\n \"loc\": [\n \"query\",\n \"needy\"\n ],\n \"msg\": \"Field required\",\n \"input\": null\n }\n ]\n}\n```\n\nAs `needy` is a required parameter, you would need to set it in the URL:\n\n```\nhttp://127.0.0.1:8000/items/foo-item?needy=sooooneedy\n```\n\n...this would work:\n\n```JSON\n{\n \"item_id\": \"foo-item\",\n \"needy\": \"sooooneedy\"\n}\n```\n\nAnd of course, you can define some parameters as required, some as having a default value, and some entirely optional:\n\n{* ../../docs_src/query_params/tutorial006_py310.py hl[8] *}\n\nIn this case, there are 3 query parameters:\n\n* `needy`, a required `str`.\n* `skip`, an `int` with a default value of `0`.\n* `limit`, an optional `int`.\n\n/// tip\n\nYou could also use `Enum`s the same way as with [Path Parameters](path-params.md#predefined-values).\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/query-params.md", "symbol": "Required query parameters { #required-query-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/query-params.md#L123-L188", "start_line": 123, "end_line": 188}
{"id": "docs/en/docs/tutorial/request-files.md::Request Files { #request-files }::L1", "text": "# Doc: docs/en/docs/tutorial/request-files.md | Page: Request Files { #request-files } | Section: Request Files { #request-files }\n# Request Files { #request-files }\n\nYou can define files to be uploaded by the client using `File`.\n\n/// note\n\nTo receive uploaded files, first install [`python-multipart`](https://github.com/Kludex/python-multipart).\n\nMake sure you create a [virtual environment](../virtual-environments.md), activate it, and then install it, for example:\n\n```console\n$ pip install python-multipart\n```\n\nThis is because uploaded files are sent as \"form data\".\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/request-files.md", "symbol": "Request Files { #request-files }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/request-files.md#L1-L18", "start_line": 1, "end_line": 18}
{"id": "docs/en/docs/tutorial/request-files.md::Import `File` { #import-file }::L19", "text": "# Doc: docs/en/docs/tutorial/request-files.md | Page: Request Files { #request-files } | Section: Import `File` { #import-file }\n## Import `File` { #import-file }\n\nImport `File` and `UploadFile` from `fastapi`:\n\n{* ../../docs_src/request_files/tutorial001_an_py310.py hl[3] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/request-files.md", "symbol": "Import `File` { #import-file }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/request-files.md#L19-L24", "start_line": 19, "end_line": 24}
{"id": "docs/en/docs/tutorial/request-files.md::Define `File` Parameters { #define-file-parameters }::L25", "text": "# Doc: docs/en/docs/tutorial/request-files.md | Page: Request Files { #request-files } | Section: Define `File` Parameters { #define-file-parameters }\n## Define `File` Parameters { #define-file-parameters }\n\nCreate file parameters the same way you would for `Body` or `Form`:\n\n{* ../../docs_src/request_files/tutorial001_an_py310.py hl[9] *}\n\n/// note\n\n`File` is a class that inherits directly from `Form`.\n\nBut remember that when you import `Query`, `Path`, `File` and others from `fastapi`, those are actually functions that return special classes.\n\n///\n\n/// tip\n\nTo declare File bodies, you need to use `File`, because otherwise the parameters would be interpreted as query parameters or body (JSON) parameters.\n\n///\n\nThe files will be uploaded as \"form data\".\n\nIf you declare the type of your *path operation function* parameter as `bytes`, **FastAPI** will read the file for you and you will receive the contents as `bytes`.\n\nKeep in mind that this means that the whole contents will be stored in memory. This will work well for small files.\n\nBut there are several cases in which you might benefit from using `UploadFile`.", "source_type": "doc", "path": "docs/en/docs/tutorial/request-files.md", "symbol": "Define `File` Parameters { #define-file-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/request-files.md#L25-L52", "start_line": 25, "end_line": 52}
{"id": "docs/en/docs/tutorial/request-files.md::File Parameters with `UploadFile` { #file-parameters-with-uploadfile }::L53", "text": "# Doc: docs/en/docs/tutorial/request-files.md | Page: Request Files { #request-files } | Section: File Parameters with `UploadFile` { #file-parameters-with-uploadfile }\n## File Parameters with `UploadFile` { #file-parameters-with-uploadfile }\n\nDefine a file parameter with a type of `UploadFile`:\n\n{* ../../docs_src/request_files/tutorial001_an_py310.py hl[14] *}\n\nUsing `UploadFile` has several advantages over `bytes`:\n\n* You don't have to use `File()` in the default value of the parameter.\n* It uses a \"spooled\" file:\n * A file stored in memory up to a maximum size limit, and after passing this limit it will be stored on disk.\n* This means that it will work well for large files like images, videos, large binaries, etc. without consuming all the memory.\n* You can get metadata from the uploaded file.\n* It has a [file-like](https://docs.python.org/3/glossary.html#term-file-like-object) `async` interface.\n* It exposes an actual Python [`SpooledTemporaryFile`](https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile) object that you can pass directly to other libraries that expect a file-like object.\n\n### `UploadFile` { #uploadfile }\n\n`UploadFile` has the following attributes:\n\n* `filename`: A `str` with the original file name that was uploaded (e.g. `myimage.jpg`).\n* `content_type`: A `str` with the content type (MIME type / media type) (e.g. `image/jpeg`).\n* `file`: A [`SpooledTemporaryFile`](https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile) (a [file-like](https://docs.python.org/3/glossary.html#term-file-like-object) object). This is the actual Python file object that you can pass directly to other functions or libraries that expect a \"file-like\" object.\n\n`UploadFile` has the following `async` methods. They all call the corresponding file methods underneath (using the internal `SpooledTemporaryFile`).\n\n* `write(data)`: Writes `data` (`str` or `bytes`) to the file.\n* `read(size)`: Reads `size` (`int`) bytes/characters of the file.\n* `seek(offset)`: Goes to the byte position `offset` (`int`) in the file.\n * E.g., `await myfile.seek(0)` would go to the start of the file.\n * This is especially useful if you run `await myfile.read()` once and then need to read the contents again.\n* `close()`: Closes the file.\n\nAs all these methods are `async` methods, you need to \"await\" them.\n\nFor example, inside of an `async` *path operation function* you can get the contents with:\n\n```Python\ncontents = await myfile.read()\n```\n\nIf you are inside of a normal `def` *path operation function*, you can access the `UploadFile.file` directly, for example:\n\n```Python\ncontents = myfile.file.read()\n```\n\n/// note | `async` Technical Details\n\nWhen you use the `async` methods, **FastAPI** runs the file methods in a threadpool and awaits for them.\n\n///\n\n/// note | Starlette Technical Details\n\n**FastAPI**'s `UploadFile` inherits directly from **Starlette**'s `UploadFile`, but adds some necessary parts to make it compatible with **Pydantic** and the other parts of FastAPI.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/request-files.md", "symbol": "File Parameters with `UploadFile` { #file-parameters-with-uploadfile }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/request-files.md#L53-L111", "start_line": 53, "end_line": 111}
{"id": "docs/en/docs/tutorial/request-files.md::What is \"Form Data\" { #what-is-form-data }::L112", "text": "# Doc: docs/en/docs/tutorial/request-files.md | Page: Request Files { #request-files } | Section: What is \"Form Data\" { #what-is-form-data }\n## What is \"Form Data\" { #what-is-form-data }\n\nThe way HTML forms (``) send the data to the server normally uses a \"special\" encoding for that data, it's different from JSON.\n\n**FastAPI** will make sure to read that data from the right place instead of JSON.\n\n/// note | Technical Details\n\nData from forms is normally encoded using the \"media type\" `application/x-www-form-urlencoded` when it doesn't include files.\n\nBut when the form includes files, it is encoded as `multipart/form-data`. If you use `File`, **FastAPI** will know it has to get the files from the correct part of the body.\n\nIf you want to read more about these encodings and form fields, head to the [MDN web docs for `POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST).\n\n///\n\n/// warning\n\nYou can declare multiple `File` and `Form` parameters in a *path operation*, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`.\n\nThis is not a limitation of **FastAPI**, it's part of the HTTP protocol.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/request-files.md", "symbol": "What is \"Form Data\" { #what-is-form-data }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/request-files.md#L112-L135", "start_line": 112, "end_line": 135}
{"id": "docs/en/docs/tutorial/request-files.md::Optional File Upload { #optional-file-upload }::L136", "text": "# Doc: docs/en/docs/tutorial/request-files.md | Page: Request Files { #request-files } | Section: Optional File Upload { #optional-file-upload }\n## Optional File Upload { #optional-file-upload }\n\nYou can make a file optional by using standard type annotations and setting a default value of `None`:\n\n{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/request-files.md", "symbol": "Optional File Upload { #optional-file-upload }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/request-files.md#L136-L141", "start_line": 136, "end_line": 141}
{"id": "docs/en/docs/tutorial/request-files.md::`UploadFile` with Additional Metadata { #uploadfile-with-additional-metadata }::L142", "text": "# Doc: docs/en/docs/tutorial/request-files.md | Page: Request Files { #request-files } | Section: `UploadFile` with Additional Metadata { #uploadfile-with-additional-metadata }\n## `UploadFile` with Additional Metadata { #uploadfile-with-additional-metadata }\n\nYou can also use `File()` with `UploadFile`, for example, to set additional metadata:\n\n{* ../../docs_src/request_files/tutorial001_03_an_py310.py hl[9,15] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/request-files.md", "symbol": "`UploadFile` with Additional Metadata { #uploadfile-with-additional-metadata }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/request-files.md#L142-L147", "start_line": 142, "end_line": 147}
{"id": "docs/en/docs/tutorial/request-files.md::Multiple File Uploads { #multiple-file-uploads }::L148", "text": "# Doc: docs/en/docs/tutorial/request-files.md | Page: Request Files { #request-files } | Section: Multiple File Uploads { #multiple-file-uploads }\n## Multiple File Uploads { #multiple-file-uploads }\n\nIt's possible to upload several files at the same time.\n\nThey would be associated to the same \"form field\" sent using \"form data\".\n\nTo use that, declare a list of `bytes` or `UploadFile`:\n\n{* ../../docs_src/request_files/tutorial002_an_py310.py hl[10,15] *}\n\nYou will receive, as declared, a `list` of `bytes` or `UploadFile`s.\n\n/// note | Technical Details\n\nYou could also use `from starlette.responses import HTMLResponse`.\n\n**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.\n\n///\n\n### Multiple File Uploads with Additional Metadata { #multiple-file-uploads-with-additional-metadata }\n\nAnd the same way as before, you can use `File()` to set additional parameters, even for `UploadFile`:\n\n{* ../../docs_src/request_files/tutorial003_an_py310.py hl[11,18:20] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/request-files.md", "symbol": "Multiple File Uploads { #multiple-file-uploads }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/request-files.md#L148-L173", "start_line": 148, "end_line": 173}
{"id": "docs/en/docs/tutorial/request-files.md::Recap { #recap }::L174", "text": "# Doc: docs/en/docs/tutorial/request-files.md | Page: Request Files { #request-files } | Section: Recap { #recap }\n## Recap { #recap }\n\nUse `File`, `bytes`, and `UploadFile` to declare files to be uploaded in the request, sent as form data.", "source_type": "doc", "path": "docs/en/docs/tutorial/request-files.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/request-files.md#L174-L176", "start_line": 174, "end_line": 176}
{"id": "docs/en/docs/tutorial/request-form-models.md::Form Models { #form-models }::L1", "text": "# Doc: docs/en/docs/tutorial/request-form-models.md | Page: Form Models { #form-models } | Section: Form Models { #form-models }\n# Form Models { #form-models }\n\nYou can use **Pydantic models** to declare **form fields** in FastAPI.\n\n/// note\n\nTo use forms, first install [`python-multipart`](https://github.com/Kludex/python-multipart).\n\nMake sure you create a [virtual environment](../virtual-environments.md), activate it, and then install it, for example:\n\n```console\n$ pip install python-multipart\n```\n\n///\n\n/// note\n\nThis is supported since FastAPI version `0.113.0`. 🤓\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/request-form-models.md", "symbol": "Form Models { #form-models }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/request-form-models.md#L1-L22", "start_line": 1, "end_line": 22}
{"id": "docs/en/docs/tutorial/request-form-models.md::Pydantic Models for Forms { #pydantic-models-for-forms }::L23", "text": "# Doc: docs/en/docs/tutorial/request-form-models.md | Page: Form Models { #form-models } | Section: Pydantic Models for Forms { #pydantic-models-for-forms }\n## Pydantic Models for Forms { #pydantic-models-for-forms }\n\nYou just need to declare a **Pydantic model** with the fields you want to receive as **form fields**, and then declare the parameter as `Form`:\n\n{* ../../docs_src/request_form_models/tutorial001_an_py310.py hl[9:11,15] *}\n\n**FastAPI** will **extract** the data for **each field** from the **form data** in the request and give you the Pydantic model you defined.", "source_type": "doc", "path": "docs/en/docs/tutorial/request-form-models.md", "symbol": "Pydantic Models for Forms { #pydantic-models-for-forms }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/request-form-models.md#L23-L30", "start_line": 23, "end_line": 30}
{"id": "docs/en/docs/tutorial/request-form-models.md::Check the Docs { #check-the-docs }::L31", "text": "# Doc: docs/en/docs/tutorial/request-form-models.md | Page: Form Models { #form-models } | Section: Check the Docs { #check-the-docs }\n## Check the Docs { #check-the-docs }\n\nYou can verify it in the docs UI at `/docs`:\n\n![](\"/img/tutorial/request-form-models/image01.png\")
\n![](\"/img/tutorial/response-model/image01.png\")
\n\nAnd both models will be used for the interactive API documentation:\n\n![](\"/img/tutorial/response-model/image02.png\")
", "source_type": "doc", "path": "docs/en/docs/tutorial/response-model.md", "symbol": "See it in the docs { #see-it-in-the-docs }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/response-model.md#L169-L178", "start_line": 169, "end_line": 178}
{"id": "docs/en/docs/tutorial/response-model.md::Other Return Type Annotations { #other-return-type-annotations }::L179", "text": "# Doc: docs/en/docs/tutorial/response-model.md | Page: Response Model - Return Type { #response-model-return-type } | Section: Other Return Type Annotations { #other-return-type-annotations }\n## Other Return Type Annotations { #other-return-type-annotations }\n\nThere might be cases where you return something that is not a valid Pydantic field and you annotate it in the function, only to get the support provided by tooling (the editor, mypy, etc).\n\n### Return a Response Directly { #return-a-response-directly }\n\nThe most common case would be [returning a Response directly as explained later in the advanced docs](../advanced/response-directly.md).\n\n{* ../../docs_src/response_model/tutorial003_02_py310.py hl[8,10:11] *}\n\nThis simple case is handled automatically by FastAPI because the return type annotation is the class (or a subclass of) `Response`.\n\nAnd tools will also be happy because both `RedirectResponse` and `JSONResponse` are subclasses of `Response`, so the type annotation is correct.\n\n### Annotate a Response Subclass { #annotate-a-response-subclass }\n\nYou can also use a subclass of `Response` in the type annotation:\n\n{* ../../docs_src/response_model/tutorial003_03_py310.py hl[8:9] *}\n\nThis will also work because `RedirectResponse` is a subclass of `Response`, and FastAPI will automatically handle this simple case.\n\n### Invalid Return Type Annotations { #invalid-return-type-annotations }\n\nBut when you return some other arbitrary object that is not a valid Pydantic type (e.g. a database object) and you annotate it like that in the function, FastAPI will try to create a Pydantic response model from that type annotation, and will fail.\n\nThe same would happen if you had something like a union between different types where one or more of them are not valid Pydantic types, for example this would fail 💥:\n\n{* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *}\n\n...this fails because the type annotation is not a Pydantic type and is not just a single `Response` class or subclass, it's a union (any of the two) between a `Response` and a `dict`.\n\n### Disable Response Model { #disable-response-model }\n\nContinuing from the example above, you might not want to have the default data validation, documentation, filtering, etc. that is performed by FastAPI.\n\nBut you might want to still keep the return type annotation in the function to get the support from tools like editors and type checkers (e.g. mypy).\n\nIn this case, you can disable the response model generation by setting `response_model=None`:\n\n{* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *}\n\nThis will make FastAPI skip the response model generation and that way you can have any return type annotations you need without it affecting your FastAPI application. 🤓", "source_type": "doc", "path": "docs/en/docs/tutorial/response-model.md", "symbol": "Other Return Type Annotations { #other-return-type-annotations }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/response-model.md#L179-L222", "start_line": 179, "end_line": 222}
{"id": "docs/en/docs/tutorial/response-model.md::Response Model encoding parameters { #response-model-encoding-parameters }::L223", "text": "# Doc: docs/en/docs/tutorial/response-model.md | Page: Response Model - Return Type { #response-model-return-type } | Section: Response Model encoding parameters { #response-model-encoding-parameters }\n## Response Model encoding parameters { #response-model-encoding-parameters }\n\nYour response model could have default values, like:\n\n{* ../../docs_src/response_model/tutorial004_py310.py hl[9,11:12] *}\n\n* `description: Union[str, None] = None` (or `str | None = None` in Python 3.10) has a default of `None`.\n* `tax: float = 10.5` has a default of `10.5`.\n* `tags: List[str] = []` has a default of an empty list: `[]`.\n\nbut you might want to omit them from the result if they were not actually stored.\n\nFor example, if you have models with many optional attributes in a NoSQL database, but you don't want to send very long JSON responses full of default values.\n\n### Use the `response_model_exclude_unset` parameter { #use-the-response-model-exclude-unset-parameter }\n\nYou can set the *path operation decorator* parameter `response_model_exclude_unset=True`:\n\n{* ../../docs_src/response_model/tutorial004_py310.py hl[22] *}\n\nand those default values won't be included in the response, only the values actually set.\n\nSo, if you send a request to that *path operation* for the item with ID `foo`, the response (not including default values) will be:\n\n```JSON\n{\n \"name\": \"Foo\",\n \"price\": 50.2\n}\n```\n\n/// note\n\nYou can also use:\n\n* `response_model_exclude_defaults=True`\n* `response_model_exclude_none=True`\n\nas described in [the Pydantic docs](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict) for `exclude_defaults` and `exclude_none`.\n\n///\n\n#### Data with values for fields with defaults { #data-with-values-for-fields-with-defaults }\n\nBut if your data has values for the model's fields with default values, like the item with ID `bar`:\n\n```Python hl_lines=\"3 5\"\n{\n \"name\": \"Bar\",\n \"description\": \"The bartenders\",\n \"price\": 62,\n \"tax\": 20.2\n}\n```\n\nthey will be included in the response.\n\n#### Data with the same values as the defaults { #data-with-the-same-values-as-the-defaults }\n\nIf the data has the same values as the default ones, like the item with ID `baz`:\n\n```Python hl_lines=\"3 5-6\"\n{\n \"name\": \"Baz\",\n \"description\": None,\n \"price\": 50.2,\n \"tax\": 10.5,\n \"tags\": []\n}\n```\n\nFastAPI is smart enough (actually, Pydantic is smart enough) to realize that, even though `description`, `tax`, and `tags` have the same values as the defaults, they were set explicitly (instead of taken from the defaults).\n\nSo, they will be included in the JSON response.\n\n/// tip\n\nNotice that the default values can be anything, not only `None`.\n\nThey can be a list (`[]`), a `float` of `10.5`, etc.\n\n///\n\n### `response_model_include` and `response_model_exclude` { #response-model-include-and-response-model-exclude }\n\nYou can also use the *path operation decorator* parameters `response_model_include` and `response_model_exclude`.\n\nThey take a `set` of `str` with the name of the attributes to include (omitting the rest) or to exclude (including the rest).\n\nThis can be used as a quick shortcut if you have only one Pydantic model and want to remove some data from the output.\n\n/// tip\n\nBut it is still recommended to use the ideas above, using multiple classes, instead of these parameters.\n\nThis is because the JSON Schema generated in your app's OpenAPI (and the docs) will still be the one for the complete model, even if you use `response_model_include` or `response_model_exclude` to omit some attributes.\n\nThis also applies to `response_model_by_alias` that works similarly.\n\n///\n\n{* ../../docs_src/response_model/tutorial005_py310.py hl[29,35] *}\n\n/// tip\n\nThe syntax `{\"name\", \"description\"}` creates a `set` with those two values.\n\nIt is equivalent to `set([\"name\", \"description\"])`.\n\n///\n\n#### Using `list`s instead of `set`s { #using-lists-instead-of-sets }\n\nIf you forget to use a `set` and use a `list` or `tuple` instead, FastAPI will still convert it to a `set` and it will work correctly:\n\n{* ../../docs_src/response_model/tutorial006_py310.py hl[29,35] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/response-model.md", "symbol": "Response Model encoding parameters { #response-model-encoding-parameters }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/response-model.md#L223-L339", "start_line": 223, "end_line": 339}
{"id": "docs/en/docs/tutorial/response-model.md::Recap { #recap }::L340", "text": "# Doc: docs/en/docs/tutorial/response-model.md | Page: Response Model - Return Type { #response-model-return-type } | Section: Recap { #recap }\n## Recap { #recap }\n\nUse the *path operation decorator's* parameter `response_model` to define response models and especially to ensure private data is filtered out.\n\nUse `response_model_exclude_unset` to return only the values explicitly set.", "source_type": "doc", "path": "docs/en/docs/tutorial/response-model.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/response-model.md#L340-L344", "start_line": 340, "end_line": 344}
{"id": "docs/en/docs/tutorial/response-status-code.md::Response Status Code { #response-status-code }::L1", "text": "# Doc: docs/en/docs/tutorial/response-status-code.md | Page: Response Status Code { #response-status-code } | Section: Response Status Code { #response-status-code }\n# Response Status Code { #response-status-code }\n\nThe same way you can specify a response model, you can also declare the HTTP status code used for the response with the parameter `status_code` in any of the *path operations*:\n\n* `@app.get()`\n* `@app.post()`\n* `@app.put()`\n* `@app.delete()`\n* etc.\n\n{* ../../docs_src/response_status_code/tutorial001_py310.py hl[6] *}\n\n/// note\n\nNotice that `status_code` is a parameter of the \"decorator\" method (`get`, `post`, etc). Not of your *path operation function*, like all the parameters and body.\n\n///\n\nThe `status_code` parameter receives a number with the HTTP status code.\n\n/// note\n\n`status_code` can alternatively also receive an `IntEnum`, such as Python's [`http.HTTPStatus`](https://docs.python.org/3/library/http.html#http.HTTPStatus).\n\n///\n\nIt will:\n\n* Return that status code in the response.\n* Document it as such in the OpenAPI schema (and so, in the user interfaces):\n\n![](\"/img/tutorial/response-status-code/image01.png\")
\n\n/// note\n\nSome response codes (see the next section) indicate that the response does not have a body.\n\nFastAPI knows this, and will produce OpenAPI docs that state there is no response body.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/response-status-code.md", "symbol": "Response Status Code { #response-status-code }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/response-status-code.md#L1-L41", "start_line": 1, "end_line": 41}
{"id": "docs/en/docs/tutorial/response-status-code.md::About HTTP status codes { #about-http-status-codes }::L42", "text": "# Doc: docs/en/docs/tutorial/response-status-code.md | Page: Response Status Code { #response-status-code } | Section: About HTTP status codes { #about-http-status-codes }\n## About HTTP status codes { #about-http-status-codes }\n\n/// note\n\nIf you already know what HTTP status codes are, skip to the next section.\n\n///\n\nIn HTTP, you send a numeric status code of 3 digits as part of the response.\n\nThese status codes have an associated name to help recognize them, but the important part is the number.\n\nIn short:\n\n* `100 - 199` are for \"Information\". You rarely use them directly. Responses with these status codes cannot have a body.\n* **`200 - 299`** are for \"Successful\" responses. These are the ones you would use the most.\n * `200` is the default status code, which means everything was \"OK\".\n * Another example would be `201`, \"Created\". It is commonly used after creating a new record in the database.\n * A special case is `204`, \"No Content\". This response is used when there is no content to return to the client, and so the response must not have a body.\n* **`300 - 399`** are for \"Redirection\". Responses with these status codes may or may not have a body, except for `304`, \"Not Modified\", which must not have one.\n* **`400 - 499`** are for \"Client error\" responses. These are the second type you would probably use the most.\n * An example is `404`, for a \"Not Found\" response.\n * For generic errors from the client, you can just use `400`.\n* `500 - 599` are for server errors. You almost never use them directly. When something goes wrong at some part in your application code, or server, it will automatically return one of these status codes.\n\n/// tip\n\nTo know more about each status code and which code is for what, check the [MDN documentation about HTTP status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status).\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/response-status-code.md", "symbol": "About HTTP status codes { #about-http-status-codes }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/response-status-code.md#L42-L72", "start_line": 42, "end_line": 72}
{"id": "docs/en/docs/tutorial/response-status-code.md::Shortcut to remember the names { #shortcut-to-remember-the-names }::L73", "text": "# Doc: docs/en/docs/tutorial/response-status-code.md | Page: Response Status Code { #response-status-code } | Section: Shortcut to remember the names { #shortcut-to-remember-the-names }\n## Shortcut to remember the names { #shortcut-to-remember-the-names }\n\nLet's see the previous example again:\n\n{* ../../docs_src/response_status_code/tutorial001_py310.py hl[6] *}\n\n`201` is the status code for \"Created\".\n\nBut you don't have to memorize what each of these codes mean.\n\nYou can use the convenience variables from `fastapi.status`.\n\n{* ../../docs_src/response_status_code/tutorial002_py310.py hl[1,6] *}\n\nThey are just a convenience, they hold the same number, but that way you can use the editor's autocomplete to find them:\n\n![](\"/img/tutorial/response-status-code/image02.png\")
\n\n/// note | Technical Details\n\nYou could also use `from starlette import status`.\n\n**FastAPI** provides the same `starlette.status` as `fastapi.status` just as a convenience for you, the developer. But it comes directly from Starlette.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/response-status-code.md", "symbol": "Shortcut to remember the names { #shortcut-to-remember-the-names }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/response-status-code.md#L73-L98", "start_line": 73, "end_line": 98}
{"id": "docs/en/docs/tutorial/response-status-code.md::Changing the default { #changing-the-default }::L99", "text": "# Doc: docs/en/docs/tutorial/response-status-code.md | Page: Response Status Code { #response-status-code } | Section: Changing the default { #changing-the-default }\n## Changing the default { #changing-the-default }\n\nLater, in the [Advanced User Guide](../advanced/response-change-status-code.md), you will see how to return a different status code than the default you are declaring here.", "source_type": "doc", "path": "docs/en/docs/tutorial/response-status-code.md", "symbol": "Changing the default { #changing-the-default }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/response-status-code.md#L99-L101", "start_line": 99, "end_line": 101}
{"id": "docs/en/docs/tutorial/schema-extra-example.md::Declare Request Example Data { #declare-request-example-data }::L1", "text": "# Doc: docs/en/docs/tutorial/schema-extra-example.md | Page: Declare Request Example Data { #declare-request-example-data } | Section: Declare Request Example Data { #declare-request-example-data }\n# Declare Request Example Data { #declare-request-example-data }\n\nYou can declare examples of the data your app can receive.\n\nHere are several ways to do it.", "source_type": "doc", "path": "docs/en/docs/tutorial/schema-extra-example.md", "symbol": "Declare Request Example Data { #declare-request-example-data }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/schema-extra-example.md#L1-L6", "start_line": 1, "end_line": 6}
{"id": "docs/en/docs/tutorial/schema-extra-example.md::Extra JSON Schema data in Pydantic models { #extra-json-schema-data-in-pydantic-models }::L7", "text": "# Doc: docs/en/docs/tutorial/schema-extra-example.md | Page: Declare Request Example Data { #declare-request-example-data } | Section: Extra JSON Schema data in Pydantic models { #extra-json-schema-data-in-pydantic-models }\n## Extra JSON Schema data in Pydantic models { #extra-json-schema-data-in-pydantic-models }\n\nYou can declare `examples` for a Pydantic model that will be added to the generated JSON Schema.\n\n{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *}\n\nThat extra info will be added as-is to the output **JSON Schema** for that model, and it will be used in the API docs.\n\nYou can use the attribute `model_config` that takes a `dict` as described in [Pydantic's docs: Configuration](https://docs.pydantic.dev/latest/api/config/).\n\nYou can set `\"json_schema_extra\"` with a `dict` containing any additional data you would like to show up in the generated JSON Schema, including `examples`.\n\n/// tip\n\nYou could use the same technique to extend the JSON Schema and add your own custom extra info.\n\nFor example you could use it to add metadata for a frontend user interface, etc.\n\n///\n\n/// note\n\nOpenAPI 3.1.0 (used since FastAPI 0.99.0) added support for `examples`, which is part of the **JSON Schema** standard.\n\nBefore that, it only supported the keyword `example` with a single example. That is still supported by OpenAPI 3.1.0, but is deprecated and is not part of the JSON Schema standard. So you are encouraged to migrate `example` to `examples`. 🤓\n\nYou can read more at the end of this page.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/schema-extra-example.md", "symbol": "Extra JSON Schema data in Pydantic models { #extra-json-schema-data-in-pydantic-models }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/schema-extra-example.md#L7-L36", "start_line": 7, "end_line": 36}
{"id": "docs/en/docs/tutorial/schema-extra-example.md::`Field` additional arguments { #field-additional-arguments }::L37", "text": "# Doc: docs/en/docs/tutorial/schema-extra-example.md | Page: Declare Request Example Data { #declare-request-example-data } | Section: `Field` additional arguments { #field-additional-arguments }\n## `Field` additional arguments { #field-additional-arguments }\n\nWhen using `Field()` with Pydantic models, you can also declare additional `examples`:\n\n{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/schema-extra-example.md", "symbol": "`Field` additional arguments { #field-additional-arguments }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/schema-extra-example.md#L37-L42", "start_line": 37, "end_line": 42}
{"id": "docs/en/docs/tutorial/schema-extra-example.md::`examples` in JSON Schema - OpenAPI { #examples-in-json-schema-openapi }::L43", "text": "# Doc: docs/en/docs/tutorial/schema-extra-example.md | Page: Declare Request Example Data { #declare-request-example-data } | Section: `examples` in JSON Schema - OpenAPI { #examples-in-json-schema-openapi }\n## `examples` in JSON Schema - OpenAPI { #examples-in-json-schema-openapi }\n\nWhen using any of:\n\n* `Path()`\n* `Query()`\n* `Header()`\n* `Cookie()`\n* `Body()`\n* `Form()`\n* `File()`\n\nyou can also declare a group of `examples` with additional information that will be added to their **JSON Schemas** inside of **OpenAPI**.\n\n### `Body` with `examples` { #body-with-examples }\n\nHere we pass `examples` containing one example of the data expected in `Body()`:\n\n{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *}\n\n### Example in the docs UI { #example-in-the-docs-ui }\n\nWith any of the methods above it would look like this in the `/docs`:\n\n![](\"/img/tutorial/body-fields/image01.png\")
\n\n### `Body` with multiple `examples` { #body-with-multiple-examples }\n\nYou can of course also pass multiple `examples`:\n\n{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *}\n\nWhen you do this, the examples will be part of the internal **JSON Schema** for that body data.\n\nNevertheless, at the time of writing this, Swagger UI, the tool in charge of showing the docs UI, doesn't support showing multiple examples for the data in **JSON Schema**. But read below for a workaround.\n\n### OpenAPI-specific `examples` { #openapi-specific-examples }\n\nSince before **JSON Schema** supported `examples`, OpenAPI had support for a different field also called `examples`.\n\nThis **OpenAPI-specific** `examples` goes in another section in the OpenAPI specification. It goes in the **details for each *path operation***, not inside each JSON Schema.\n\nAnd Swagger UI has supported this particular `examples` field for a while. So, you can use it to **show** different **examples in the docs UI**.\n\nThe shape of this OpenAPI-specific field `examples` is a `dict` with **multiple examples** (instead of a `list`), each with extra information that will be added to **OpenAPI** too.\n\nThis doesn't go inside of each JSON Schema contained in OpenAPI, this goes outside, in the *path operation* directly.\n\n### Using the `openapi_examples` Parameter { #using-the-openapi-examples-parameter }\n\nYou can declare the OpenAPI-specific `examples` in FastAPI with the parameter `openapi_examples` for:\n\n* `Path()`\n* `Query()`\n* `Header()`\n* `Cookie()`\n* `Body()`\n* `Form()`\n* `File()`\n\nThe keys of the `dict` identify each example, and each value is another `dict`.\n\nEach specific example `dict` in the `examples` can contain:\n\n* `summary`: Short description for the example.\n* `description`: A long description that can contain Markdown text.\n* `value`: This is the actual example shown, e.g. a `dict`.\n* `externalValue`: alternative to `value`, a URL pointing to the example. Although this might not be supported by as many tools as `value`.\n\nYou can use it like this:\n\n{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *}\n\n### OpenAPI Examples in the Docs UI { #openapi-examples-in-the-docs-ui }\n\nWith `openapi_examples` added to `Body()` the `/docs` would look like:\n\n![](\"/img/tutorial/body-fields/image02.png\")
", "source_type": "doc", "path": "docs/en/docs/tutorial/schema-extra-example.md", "symbol": "`examples` in JSON Schema - OpenAPI { #examples-in-json-schema-openapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/schema-extra-example.md#L43-L121", "start_line": 43, "end_line": 121}
{"id": "docs/en/docs/tutorial/schema-extra-example.md::Technical Details { #technical-details }::L122", "text": "# Doc: docs/en/docs/tutorial/schema-extra-example.md | Page: Declare Request Example Data { #declare-request-example-data } | Section: Technical Details { #technical-details }\n## Technical Details { #technical-details }\n\n/// tip\n\nIf you are already using **FastAPI** version **0.99.0 or above**, you can probably **skip** these details.\n\nThey are more relevant for older versions, before OpenAPI 3.1.0 was available.\n\nYou can consider this a brief OpenAPI and JSON Schema **history lesson**. 🤓\n\n///\n\n/// warning\n\nThese are very technical details about the standards **JSON Schema** and **OpenAPI**.\n\nIf the ideas above already work for you, that might be enough, and you probably don't need these details, feel free to skip them.\n\n///\n\nBefore OpenAPI 3.1.0, OpenAPI used an older and modified version of **JSON Schema**.\n\nJSON Schema didn't have `examples`, so OpenAPI added its own `example` field to its own modified version.\n\nOpenAPI also added `example` and `examples` fields to other parts of the specification:\n\n* [`Parameter Object` (in the specification)](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object) that was used by FastAPI's:\n * `Path()`\n * `Query()`\n * `Header()`\n * `Cookie()`\n* [`Request Body Object`, in the field `content`, on the `Media Type Object` (in the specification)](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object) that was used by FastAPI's:\n * `Body()`\n * `File()`\n * `Form()`\n\n/// note\n\nThis old OpenAPI-specific `examples` parameter is now `openapi_examples` since FastAPI `0.103.0`.\n\n///\n\n### JSON Schema's `examples` field { #json-schemas-examples-field }\n\nBut then JSON Schema added an [`examples`](https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.9.5) field to a new version of the specification.\n\nAnd then the new OpenAPI 3.1.0 was based on the latest version (JSON Schema 2020-12) that included this new field `examples`.\n\nAnd now this new `examples` field takes precedence over the old single (and custom) `example` field, that is now deprecated.\n\nThis new `examples` field in JSON Schema is **just a `list`** of examples, not a dict with extra metadata as in the other places in OpenAPI (described above).\n\n/// note\n\nEven after OpenAPI 3.1.0 was released with this new simpler integration with JSON Schema, for a while, Swagger UI, the tool that provides the automatic docs, didn't support OpenAPI 3.1.0 (it does since version 5.0.0 🎉).\n\nBecause of that, versions of FastAPI previous to 0.99.0 still used versions of OpenAPI lower than 3.1.0.\n\n///\n\n### Pydantic and FastAPI `examples` { #pydantic-and-fastapi-examples }\n\nWhen you add `examples` inside a Pydantic model, using `schema_extra` or `Field(examples=[\"something\"])` that example is added to the **JSON Schema** for that Pydantic model.\n\nAnd that **JSON Schema** of the Pydantic model is included in the **OpenAPI** of your API, and then it's used in the docs UI.\n\nIn versions of FastAPI before 0.99.0 (0.99.0 and above use the newer OpenAPI 3.1.0) when you used `example` or `examples` with any of the other utilities (`Query()`, `Body()`, etc.) those examples were not added to the JSON Schema that describes that data (not even to OpenAPI's own version of JSON Schema), they were added directly to the *path operation* declaration in OpenAPI (outside the parts of OpenAPI that use JSON Schema).\n\nBut now that FastAPI 0.99.0 and above uses OpenAPI 3.1.0, that uses JSON Schema 2020-12, and Swagger UI 5.0.0 and above, everything is more consistent and the examples are included in JSON Schema.\n\n### Swagger UI and OpenAPI-specific `examples` { #swagger-ui-and-openapi-specific-examples }\n\nNow, as Swagger UI didn't support multiple JSON Schema examples (as of 2023-08-26), users didn't have a way to show multiple examples in the docs.\n\nTo solve that, FastAPI `0.103.0` **added support** for declaring the same old **OpenAPI-specific** `examples` field with the new parameter `openapi_examples`. 🤓\n\n### Summary { #summary }\n\nI used to say I didn't like history that much... and look at me now giving \"tech history\" lessons. 😅\n\nIn short, **upgrade to FastAPI 0.99.0 or above**, and things are much **simpler, consistent, and intuitive**, and you don't have to know all these historic details. 😎", "source_type": "doc", "path": "docs/en/docs/tutorial/schema-extra-example.md", "symbol": "Technical Details { #technical-details }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/schema-extra-example.md#L122-L202", "start_line": 122, "end_line": 202}
{"id": "docs/en/docs/tutorial/security/first-steps.md::Security - First Steps { #security-first-steps }::L1", "text": "# Doc: docs/en/docs/tutorial/security/first-steps.md | Page: Security - First Steps { #security-first-steps } | Section: Security - First Steps { #security-first-steps }\n# Security - First Steps { #security-first-steps }\n\nLet's imagine that you have your **backend** API in some domain.\n\nAnd you have a **frontend** in another domain or in a different path of the same domain (or in a mobile application).\n\nAnd you want to have a way for the frontend to authenticate with the backend, using a **username** and **password**.\n\nWe can use **OAuth2** to build that with **FastAPI**.\n\nBut let's save you the time of reading the full long specification just to find those little pieces of information you need.\n\nLet's use the tools provided by **FastAPI** to handle security.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/first-steps.md", "symbol": "Security - First Steps { #security-first-steps }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/first-steps.md#L1-L14", "start_line": 1, "end_line": 14}
{"id": "docs/en/docs/tutorial/security/first-steps.md::How it looks { #how-it-looks }::L15", "text": "# Doc: docs/en/docs/tutorial/security/first-steps.md | Page: Security - First Steps { #security-first-steps } | Section: How it looks { #how-it-looks }\n## How it looks { #how-it-looks }\n\nLet's first just use the code and see how it works, and then we'll come back to understand what's happening.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/first-steps.md", "symbol": "How it looks { #how-it-looks }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/first-steps.md#L15-L18", "start_line": 15, "end_line": 18}
{"id": "docs/en/docs/tutorial/security/first-steps.md::Create `main.py` { #create-main-py }::L19", "text": "# Doc: docs/en/docs/tutorial/security/first-steps.md | Page: Security - First Steps { #security-first-steps } | Section: Create `main.py` { #create-main-py }\n## Create `main.py` { #create-main-py }\n\nCopy the example in a file `main.py`:\n\n{* ../../docs_src/security/tutorial001_an_py310.py *}", "source_type": "doc", "path": "docs/en/docs/tutorial/security/first-steps.md", "symbol": "Create `main.py` { #create-main-py }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/first-steps.md#L19-L24", "start_line": 19, "end_line": 24}
{"id": "docs/en/docs/tutorial/security/first-steps.md::Run it { #run-it }::L25", "text": "# Doc: docs/en/docs/tutorial/security/first-steps.md | Page: Security - First Steps { #security-first-steps } | Section: Run it { #run-it }\n## Run it { #run-it }\n\n/// note\n\nThe [`python-multipart`](https://github.com/Kludex/python-multipart) package is automatically installed with **FastAPI** when you run the `pip install \"fastapi[standard]\"` command.\n\nHowever, if you use the `pip install fastapi` command, the `python-multipart` package is not included by default.\n\nTo install it manually, make sure you create a [virtual environment](../../virtual-environments.md), activate it, and then install it with:\n\n```console\n$ pip install python-multipart\n```\n\nThis is because **OAuth2** uses \"form data\" for sending the `username` and `password`.\n\n///\n\nRun the example with:\n\n![](\"/img/tutorial/security/image01.png\")
\n\n/// tip | Authorize button!\n\nYou already have a shiny new \"Authorize\" button.\n\nAnd your *path operation* has a little lock in the top-right corner that you can click.\n\n///\n\nAnd if you click it, you have a little authorization form to type a `username` and `password` (and other optional fields):\n\n![](\"/img/tutorial/security/image02.png\")
\n\n/// note\n\nIt doesn't matter what you type in the form, it won't work yet. But we'll get there.\n\n///\n\nThis is of course not the frontend for the final users, but it's a great automatic tool to document interactively all your API.\n\nIt can be used by the frontend team (that can also be yourself).\n\nIt can be used by third party applications and systems.\n\nAnd it can also be used by yourself, to debug, check and test the same application.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/first-steps.md", "symbol": "Check it { #check-it }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/first-steps.md#L55-L88", "start_line": 55, "end_line": 88}
{"id": "docs/en/docs/tutorial/security/first-steps.md::The `password` flow { #the-password-flow }::L89", "text": "# Doc: docs/en/docs/tutorial/security/first-steps.md | Page: Security - First Steps { #security-first-steps } | Section: The `password` flow { #the-password-flow }\n## The `password` flow { #the-password-flow }\n\nNow let's go back a bit and understand what all that is.\n\nThe `password` \"flow\" is one of the ways (\"flows\") defined in OAuth2, to handle security and authentication.\n\nOAuth2 was designed so that the backend or API could be independent of the server that authenticates the user.\n\nBut in this case, the same **FastAPI** application will handle the API and the authentication.\n\nSo, let's review it from that simplified point of view:\n\n* The user types the `username` and `password` in the frontend, and hits `Enter`.\n* The frontend (running in the user's browser) sends that `username` and `password` to a specific URL in our API (declared with `tokenUrl=\"token\"`).\n* The API checks that `username` and `password`, and responds with a \"token\" (we haven't implemented any of this yet).\n * A \"token\" is just a string with some content that we can use later to verify this user.\n * Normally, a token is set to expire after some time.\n * So, the user will have to log in again at some point later.\n * And if the token is stolen, the risk is less. It is not like a permanent key that will work forever (in most of the cases).\n* The frontend stores that token temporarily somewhere.\n* The user clicks in the frontend to go to another section of the frontend web app.\n* The frontend needs to fetch some more data from the API.\n * But it needs authentication for that specific endpoint.\n * So, to authenticate with our API, it sends a header `Authorization` with a value of `Bearer ` plus the token.\n * If the token contains `foobar`, the content of the `Authorization` header would be: `Bearer foobar`.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/first-steps.md", "symbol": "The `password` flow { #the-password-flow }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/first-steps.md#L89-L114", "start_line": 89, "end_line": 114}
{"id": "docs/en/docs/tutorial/security/first-steps.md::**FastAPI**'s `OAuth2PasswordBearer` { #fastapis-oauth2passwordbearer }::L115", "text": "# Doc: docs/en/docs/tutorial/security/first-steps.md | Page: Security - First Steps { #security-first-steps } | Section: **FastAPI**'s `OAuth2PasswordBearer` { #fastapis-oauth2passwordbearer }\n## **FastAPI**'s `OAuth2PasswordBearer` { #fastapis-oauth2passwordbearer }\n\n**FastAPI** provides several tools, at different levels of abstraction, to implement these security features.\n\nIn this example we are going to use **OAuth2**, with the **Password** flow, using a **Bearer** token. We do that using the `OAuth2PasswordBearer` class.\n\n/// note\n\nA \"bearer\" token is not the only option.\n\nBut it's the best one for our use case.\n\nAnd it might be the best for most use cases, unless you are an OAuth2 expert and know exactly why there's another option that better suits your needs.\n\nIn that case, **FastAPI** also provides you with the tools to build it.\n\n///\n\nWhen we create an instance of the `OAuth2PasswordBearer` class we pass in the `tokenUrl` parameter. This parameter contains the URL that the client (the frontend running in the user's browser) will use to send the `username` and `password` in order to get a token.\n\n{* ../../docs_src/security/tutorial001_an_py310.py hl[8] *}\n\n/// tip\n\nHere `tokenUrl=\"token\"` refers to a relative URL `token` that we haven't created yet. As it's a relative URL, it's equivalent to `./token`.\n\nBecause we are using a relative URL, if your API was located at `https://example.com/`, then it would refer to `https://example.com/token`. But if your API was located at `https://example.com/api/v1/`, then it would refer to `https://example.com/api/v1/token`.\n\nUsing a relative URL is important to make sure your application keeps working even in an advanced use case like [Behind a Proxy](../../advanced/behind-a-proxy.md).\n\n///\n\nThis parameter doesn't create that endpoint / *path operation*, but declares that the URL `/token` will be the one that the client should use to get the token. That information is used in OpenAPI, and then in the interactive API documentation systems.\n\nWe will soon also create the actual path operation.\n\n/// note\n\nIf you are a very strict \"Pythonista\" you might dislike the style of the parameter name `tokenUrl` instead of `token_url`.\n\nThat's because it is using the same name as in the OpenAPI spec. So that if you need to investigate more about any of these security schemes you can just copy and paste it to find more information about it.\n\n///\n\nThe `oauth2_scheme` variable is an instance of `OAuth2PasswordBearer`, but it is also a \"callable\".\n\nIt could be called as:\n\n```Python\noauth2_scheme(some, parameters)\n```\n\nSo, it can be used with `Depends`.\n\n### Use it { #use-it }\n\nNow you can pass that `oauth2_scheme` in a dependency with `Depends`.\n\n{* ../../docs_src/security/tutorial001_an_py310.py hl[12] *}\n\nThis dependency will provide a `str` that is assigned to the parameter `token` of the *path operation function*.\n\n**FastAPI** will know that it can use this dependency to define a \"security scheme\" in the OpenAPI schema (and the automatic API docs).\n\n/// note | Technical Details\n\n**FastAPI** will know that it can use the class `OAuth2PasswordBearer` (declared in a dependency) to define the security scheme in OpenAPI because it inherits from `fastapi.security.oauth2.OAuth2`, which in turn inherits from `fastapi.security.base.SecurityBase`.\n\nAll the security utilities that integrate with OpenAPI (and the automatic API docs) inherit from `SecurityBase`, that's how **FastAPI** can know how to integrate them in OpenAPI.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/security/first-steps.md", "symbol": "**FastAPI**'s `OAuth2PasswordBearer` { #fastapis-oauth2passwordbearer }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/first-steps.md#L115-L186", "start_line": 115, "end_line": 186}
{"id": "docs/en/docs/tutorial/security/first-steps.md::What it does { #what-it-does }::L187", "text": "# Doc: docs/en/docs/tutorial/security/first-steps.md | Page: Security - First Steps { #security-first-steps } | Section: What it does { #what-it-does }\n## What it does { #what-it-does }\n\nIt will go and look in the request for that `Authorization` header, check if the value is `Bearer ` plus some token, and will return the token as a `str`.\n\nIf it doesn't see an `Authorization` header, or the value doesn't have a `Bearer ` token, it will respond with a 401 status code error (`UNAUTHORIZED`) directly.\n\nYou don't even have to check if the token exists to return an error. You can be sure that if your function is executed, it will have a `str` in that token.\n\nYou can try it already in the interactive docs:\n\n![](\"/img/tutorial/security/image03.png\")
\n\nWe are not verifying the validity of the token yet, but that's a start already.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/first-steps.md", "symbol": "What it does { #what-it-does }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/first-steps.md#L187-L200", "start_line": 187, "end_line": 200}
{"id": "docs/en/docs/tutorial/security/first-steps.md::Recap { #recap }::L201", "text": "# Doc: docs/en/docs/tutorial/security/first-steps.md | Page: Security - First Steps { #security-first-steps } | Section: Recap { #recap }\n## Recap { #recap }\n\nSo, in just 3 or 4 extra lines, you already have some primitive form of security.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/first-steps.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/first-steps.md#L201-L203", "start_line": 201, "end_line": 203}
{"id": "docs/en/docs/tutorial/security/get-current-user.md::Get Current User { #get-current-user }::L1", "text": "# Doc: docs/en/docs/tutorial/security/get-current-user.md | Page: Get Current User { #get-current-user } | Section: Get Current User { #get-current-user }\n# Get Current User { #get-current-user }\n\nIn the previous chapter the security system (which is based on the dependency injection system) was giving the *path operation function* a `token` as a `str`:\n\n{* ../../docs_src/security/tutorial001_an_py310.py hl[12] *}\n\nBut that is still not that useful.\n\nLet's make it give us the current user.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/get-current-user.md", "symbol": "Get Current User { #get-current-user }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/get-current-user.md#L1-L10", "start_line": 1, "end_line": 10}
{"id": "docs/en/docs/tutorial/security/get-current-user.md::Create a user model { #create-a-user-model }::L11", "text": "# Doc: docs/en/docs/tutorial/security/get-current-user.md | Page: Get Current User { #get-current-user } | Section: Create a user model { #create-a-user-model }\n## Create a user model { #create-a-user-model }\n\nFirst, let's create a Pydantic user model.\n\nThe same way we use Pydantic to declare bodies, we can use it anywhere else:\n\n{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:16] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/security/get-current-user.md", "symbol": "Create a user model { #create-a-user-model }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/get-current-user.md#L11-L18", "start_line": 11, "end_line": 18}
{"id": "docs/en/docs/tutorial/security/get-current-user.md::Create a `get_current_user` dependency { #create-a-get-current-user-dependency }::L19", "text": "# Doc: docs/en/docs/tutorial/security/get-current-user.md | Page: Get Current User { #get-current-user } | Section: Create a `get_current_user` dependency { #create-a-get-current-user-dependency }\n## Create a `get_current_user` dependency { #create-a-get-current-user-dependency }\n\nLet's create a dependency `get_current_user`.\n\nRemember that dependencies can have sub-dependencies?\n\n`get_current_user` will have a dependency with the same `oauth2_scheme` we created before.\n\nThe same as we were doing before in the *path operation* directly, our new dependency `get_current_user` will receive a `token` as a `str` from the sub-dependency `oauth2_scheme`:\n\n{* ../../docs_src/security/tutorial002_an_py310.py hl[25] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/security/get-current-user.md", "symbol": "Create a `get_current_user` dependency { #create-a-get-current-user-dependency }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/get-current-user.md#L19-L30", "start_line": 19, "end_line": 30}
{"id": "docs/en/docs/tutorial/security/get-current-user.md::Get the user { #get-the-user }::L31", "text": "# Doc: docs/en/docs/tutorial/security/get-current-user.md | Page: Get Current User { #get-current-user } | Section: Get the user { #get-the-user }\n## Get the user { #get-the-user }\n\n`get_current_user` will use a (fake) utility function we created, that takes a token as a `str` and returns our Pydantic `User` model:\n\n{* ../../docs_src/security/tutorial002_an_py310.py hl[19:22,26:27] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/security/get-current-user.md", "symbol": "Get the user { #get-the-user }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/get-current-user.md#L31-L36", "start_line": 31, "end_line": 36}
{"id": "docs/en/docs/tutorial/security/get-current-user.md::Inject the current user { #inject-the-current-user }::L37", "text": "# Doc: docs/en/docs/tutorial/security/get-current-user.md | Page: Get Current User { #get-current-user } | Section: Inject the current user { #inject-the-current-user }\n## Inject the current user { #inject-the-current-user }\n\nSo now we can use the same `Depends` with our `get_current_user` in the *path operation*:\n\n{* ../../docs_src/security/tutorial002_an_py310.py hl[31] *}\n\nNotice that we declare the type of `current_user` as the Pydantic model `User`.\n\nThis will help us inside of the function with all the completion and type checks.\n\n/// tip\n\nYou might remember that request bodies are also declared with Pydantic models.\n\nHere **FastAPI** won't get confused because you are using `Depends`.\n\n///\n\n/// tip\n\nThe way this dependency system is designed allows us to have different dependencies (different \"dependables\") that all return a `User` model.\n\nWe are not restricted to having only one dependency that can return that type of data.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/security/get-current-user.md", "symbol": "Inject the current user { #inject-the-current-user }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/get-current-user.md#L37-L62", "start_line": 37, "end_line": 62}
{"id": "docs/en/docs/tutorial/security/get-current-user.md::Other models { #other-models }::L63", "text": "# Doc: docs/en/docs/tutorial/security/get-current-user.md | Page: Get Current User { #get-current-user } | Section: Other models { #other-models }\n## Other models { #other-models }\n\nYou can now get the current user directly in the *path operation functions* and deal with the security mechanisms at the **Dependency Injection** level, using `Depends`.\n\nAnd you can use any model or data for the security requirements (in this case, a Pydantic model `User`).\n\nBut you are not restricted to using some specific data model, class or type.\n\nDo you want to have an `id` and `email` and not have any `username` in your model? Sure. You can use these same tools.\n\nDo you want to just have a `str`? Or just a `dict`? Or a database class model instance directly? It all works the same way.\n\nYou actually don't have users that log in to your application but robots, bots, or other systems, that have just an access token? Again, it all works the same.\n\nJust use any kind of model, any kind of class, any kind of database that you need for your application. **FastAPI** has you covered with the dependency injection system.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/get-current-user.md", "symbol": "Other models { #other-models }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/get-current-user.md#L63-L78", "start_line": 63, "end_line": 78}
{"id": "docs/en/docs/tutorial/security/get-current-user.md::Code size { #code-size }::L79", "text": "# Doc: docs/en/docs/tutorial/security/get-current-user.md | Page: Get Current User { #get-current-user } | Section: Code size { #code-size }\n## Code size { #code-size }\n\nThis example might seem verbose. Keep in mind that we are mixing security, data models, utility functions and *path operations* in the same file.\n\nBut here's the key point.\n\nThe security and dependency injection stuff is written once.\n\nAnd you can make it as complex as you want. And still, have it written only once, in a single place. With all the flexibility.\n\nBut you can have thousands of endpoints (*path operations*) using the same security system.\n\nAnd all of them (or any portion of them that you want) can take advantage of re-using these dependencies or any other dependencies you create.\n\nAnd all these thousands of *path operations* can be as small as 3 lines:\n\n{* ../../docs_src/security/tutorial002_an_py310.py hl[30:32] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/security/get-current-user.md", "symbol": "Code size { #code-size }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/get-current-user.md#L79-L96", "start_line": 79, "end_line": 96}
{"id": "docs/en/docs/tutorial/security/get-current-user.md::Recap { #recap }::L97", "text": "# Doc: docs/en/docs/tutorial/security/get-current-user.md | Page: Get Current User { #get-current-user } | Section: Recap { #recap }\n## Recap { #recap }\n\nYou can now get the current user directly in your *path operation function*.\n\nWe are already halfway there.\n\nWe just need to add a *path operation* for the user/client to actually send the `username` and `password`.\n\nThat comes next.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/get-current-user.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/get-current-user.md#L97-L105", "start_line": 97, "end_line": 105}
{"id": "docs/en/docs/tutorial/security/index.md::Security { #security }::L1", "text": "# Doc: docs/en/docs/tutorial/security/index.md | Page: Security { #security } | Section: Security { #security }\n# Security { #security }\n\nThere are many ways to handle security, authentication and authorization.\n\nAnd it normally is a complex and \"difficult\" topic.\n\nIn many frameworks and systems just handling security and authentication takes a big amount of effort and code (in many cases it can be 50% or more of all the code written).\n\n**FastAPI** provides several tools to help you deal with **Security** easily, rapidly, in a standard way, without having to study and learn all the security specifications.\n\nBut first, let's check some small concepts.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/index.md", "symbol": "Security { #security }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/index.md#L1-L12", "start_line": 1, "end_line": 12}
{"id": "docs/en/docs/tutorial/security/index.md::In a hurry? { #in-a-hurry }::L13", "text": "# Doc: docs/en/docs/tutorial/security/index.md | Page: Security { #security } | Section: In a hurry? { #in-a-hurry }\n## In a hurry? { #in-a-hurry }\n\nIf you don't care about any of these terms and you just need to add security with authentication based on username and password *right now*, skip to the next chapters.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/index.md", "symbol": "In a hurry? { #in-a-hurry }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/index.md#L13-L16", "start_line": 13, "end_line": 16}
{"id": "docs/en/docs/tutorial/security/index.md::OAuth2 { #oauth2 }::L17", "text": "# Doc: docs/en/docs/tutorial/security/index.md | Page: Security { #security } | Section: OAuth2 { #oauth2 }\n## OAuth2 { #oauth2 }\n\nOAuth2 is a specification that defines several ways to handle authentication and authorization.\n\nIt is quite an extensive specification and covers several complex use cases.\n\nIt includes ways to authenticate using a \"third party\".\n\nThat's what all the systems with \"login with Facebook, Google, X (Twitter), GitHub\" use underneath.\n\n### OAuth 1 { #oauth-1 }\n\nThere was an OAuth 1, which is very different from OAuth2, and more complex, as it included direct specifications on how to encrypt the communication.\n\nIt is not very popular or used nowadays.\n\nOAuth2 doesn't specify how to encrypt the communication, it expects you to have your application served with HTTPS.\n\n/// tip\n\nIn the section about **deployment** you will see how to set up HTTPS for free, using Traefik and Let's Encrypt.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/security/index.md", "symbol": "OAuth2 { #oauth2 }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/index.md#L17-L40", "start_line": 17, "end_line": 40}
{"id": "docs/en/docs/tutorial/security/index.md::OpenID Connect { #openid-connect }::L41", "text": "# Doc: docs/en/docs/tutorial/security/index.md | Page: Security { #security } | Section: OpenID Connect { #openid-connect }\n## OpenID Connect { #openid-connect }\n\nOpenID Connect is another specification, based on **OAuth2**.\n\nIt just extends OAuth2 specifying some things that are relatively ambiguous in OAuth2, to try to make it more interoperable.\n\nFor example, Google login uses OpenID Connect (which underneath uses OAuth2).\n\nBut Facebook login doesn't support OpenID Connect. It has its own flavor of OAuth2.\n\n### OpenID (not \"OpenID Connect\") { #openid-not-openid-connect }\n\nThere was also an \"OpenID\" specification. That tried to solve the same thing as **OpenID Connect**, but was not based on OAuth2.\n\nSo, it was a complete additional system.\n\nIt is not very popular or used nowadays.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/index.md", "symbol": "OpenID Connect { #openid-connect }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/index.md#L41-L58", "start_line": 41, "end_line": 58}
{"id": "docs/en/docs/tutorial/security/index.md::OpenAPI { #openapi }::L59", "text": "# Doc: docs/en/docs/tutorial/security/index.md | Page: Security { #security } | Section: OpenAPI { #openapi }\n## OpenAPI { #openapi }\n\nOpenAPI (previously known as Swagger) is the open specification for building APIs (now part of the Linux Foundation).\n\n**FastAPI** is based on **OpenAPI**.\n\nThat's what makes it possible to have multiple automatic interactive documentation interfaces, code generation, etc.\n\nOpenAPI has a way to define multiple security \"schemes\".\n\nBy using them, you can take advantage of all these standard-based tools, including these interactive documentation systems.\n\nOpenAPI defines the following security schemes:\n\n* `apiKey`: an application specific key that can come from:\n * A query parameter.\n * A header.\n * A cookie.\n* `http`: standard HTTP authentication systems, including:\n * `bearer`: a header `Authorization` with a value of `Bearer ` plus a token. This is inherited from OAuth2.\n * HTTP Basic authentication.\n * HTTP Digest, etc.\n* `oauth2`: all the OAuth2 ways to handle security (called \"flows\").\n * Several of these flows are appropriate for building an OAuth 2.0 authentication provider (like Google, Facebook, X (Twitter), GitHub, etc):\n * `implicit`\n * `clientCredentials`\n * `authorizationCode`\n * But there is one specific \"flow\" that can be perfectly used for handling authentication in the same application directly:\n * `password`: some next chapters will cover examples of this.\n* `openIdConnect`: has a way to define how to discover OAuth2 authentication data automatically.\n * This automatic discovery is what is defined in the OpenID Connect specification.\n\n\n/// tip\n\nIntegrating other authentication/authorization providers like Google, Facebook, X (Twitter), GitHub, etc. is also possible and relatively easy.\n\nThe most complex problem is building an authentication/authorization provider like those, but **FastAPI** gives you the tools to do it easily, while doing the heavy lifting for you.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/security/index.md", "symbol": "OpenAPI { #openapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/index.md#L59-L99", "start_line": 59, "end_line": 99}
{"id": "docs/en/docs/tutorial/security/index.md::**FastAPI** utilities { #fastapi-utilities }::L100", "text": "# Doc: docs/en/docs/tutorial/security/index.md | Page: Security { #security } | Section: **FastAPI** utilities { #fastapi-utilities }\n## **FastAPI** utilities { #fastapi-utilities }\n\nFastAPI provides several tools for each of these security schemes in the `fastapi.security` module that simplify using these security mechanisms.\n\nIn the next chapters you will see how to add security to your API using those tools provided by **FastAPI**.\n\nAnd you will also see how it gets automatically integrated into the interactive documentation system.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/index.md", "symbol": "**FastAPI** utilities { #fastapi-utilities }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/index.md#L100-L106", "start_line": 100, "end_line": 106}
{"id": "docs/en/docs/tutorial/security/oauth2-jwt.md::OAuth2 with Password (and hashing), Bearer with JWT tokens { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens }::L1", "text": "# Doc: docs/en/docs/tutorial/security/oauth2-jwt.md | Page: OAuth2 with Password (and hashing), Bearer with JWT tokens { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens } | Section: OAuth2 with Password (and hashing), Bearer with JWT tokens { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens }\n# OAuth2 with Password (and hashing), Bearer with JWT tokens { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens }\n\nNow that we have all the security flow, let's make the application actually secure, using JWT tokens and secure password hashing.\n\nThis code is something you can actually use in your application, save the password hashes in your database, etc.\n\nWe are going to start from where we left in the previous chapter and increment it.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/oauth2-jwt.md", "symbol": "OAuth2 with Password (and hashing), Bearer with JWT tokens { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/oauth2-jwt.md#L1-L8", "start_line": 1, "end_line": 8}
{"id": "docs/en/docs/tutorial/security/oauth2-jwt.md::About JWT { #about-jwt }::L9", "text": "# Doc: docs/en/docs/tutorial/security/oauth2-jwt.md | Page: OAuth2 with Password (and hashing), Bearer with JWT tokens { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens } | Section: About JWT { #about-jwt }\n## About JWT { #about-jwt }\n\nJWT means \"JSON Web Tokens\".\n\nIt's a standard to codify a JSON object in a long dense string without spaces. It looks like this:\n\n```\neyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\n```\n\nIt is not encrypted, so, anyone could recover the information from the contents.\n\nBut it's signed. So, when you receive a token that you issued, you can verify that it was you who issued it.\n\nThat way, you can create a token with an expiration of, let's say, 1 week. And then when the user comes back the next day with the token, you know that user is still logged in to your system.\n\nAfter a week, the token will be expired and the user will not be authorized and will have to sign in again to get a new token. And if the user (or a third party) tried to modify the token to change the expiration, you would be able to discover it, because the signatures would not match.\n\nIf you want to play with JWT tokens and see how they work, check [https://jwt.io](https://jwt.io/).", "source_type": "doc", "path": "docs/en/docs/tutorial/security/oauth2-jwt.md", "symbol": "About JWT { #about-jwt }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/oauth2-jwt.md#L9-L28", "start_line": 9, "end_line": 28}
{"id": "docs/en/docs/tutorial/security/oauth2-jwt.md::Install `PyJWT` { #install-pyjwt }::L29", "text": "# Doc: docs/en/docs/tutorial/security/oauth2-jwt.md | Page: OAuth2 with Password (and hashing), Bearer with JWT tokens { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens } | Section: Install `PyJWT` { #install-pyjwt }\n## Install `PyJWT` { #install-pyjwt }\n\nWe need to install `PyJWT` to generate and verify the JWT tokens in Python.\n\nMake sure you create a [virtual environment](../../virtual-environments.md), activate it, and then install `pyjwt`:\n\n![](\"/img/tutorial/security/image07.png\")
\n\nAuthorize the application the same way as before.\n\nUsing the credentials:\n\nUsername: `johndoe`\nPassword: `secret`\n\n/// tip\n\nNotice that nowhere in the code is the plaintext password \"`secret`\", we only have the hashed version.\n\n///\n\n![](\"/img/tutorial/security/image08.png\")
\n\nCall the endpoint `/users/me/`, you will get the response as:\n\n```JSON\n{\n \"username\": \"johndoe\",\n \"email\": \"johndoe@example.com\",\n \"full_name\": \"John Doe\",\n \"disabled\": false\n}\n```\n\n![](\"/img/tutorial/security/image09.png\")
\n\nIf you open the developer tools, you could see how the data sent only includes the token, the password is only sent in the first request to authenticate the user and get that access token, but not afterwards:\n\n![](\"/img/tutorial/security/image10.png\")
\n\n/// note\n\nNotice the header `Authorization`, with a value that starts with `Bearer `.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/security/oauth2-jwt.md", "symbol": "Check it { #check-it }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/oauth2-jwt.md#L201-L246", "start_line": 201, "end_line": 246}
{"id": "docs/en/docs/tutorial/security/oauth2-jwt.md::Advanced usage with `scopes` { #advanced-usage-with-scopes }::L247", "text": "# Doc: docs/en/docs/tutorial/security/oauth2-jwt.md | Page: OAuth2 with Password (and hashing), Bearer with JWT tokens { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens } | Section: Advanced usage with `scopes` { #advanced-usage-with-scopes }\n## Advanced usage with `scopes` { #advanced-usage-with-scopes }\n\nOAuth2 has the notion of \"scopes\".\n\nYou can use them to add a specific set of permissions to a JWT token.\n\nThen you can give this token to a user directly or a third party, to interact with your API with a set of restrictions.\n\nYou can learn how to use them and how they are integrated into **FastAPI** later in the **Advanced User Guide**.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/oauth2-jwt.md", "symbol": "Advanced usage with `scopes` { #advanced-usage-with-scopes }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/oauth2-jwt.md#L247-L256", "start_line": 247, "end_line": 256}
{"id": "docs/en/docs/tutorial/security/oauth2-jwt.md::Recap { #recap }::L257", "text": "# Doc: docs/en/docs/tutorial/security/oauth2-jwt.md | Page: OAuth2 with Password (and hashing), Bearer with JWT tokens { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens } | Section: Recap { #recap }\n## Recap { #recap }\n\nWith what you have seen up to now, you can set up a secure **FastAPI** application using standards like OAuth2 and JWT.\n\nIn almost any framework handling the security becomes a rather complex subject quite quickly.\n\nMany packages that simplify it a lot have to make many compromises with the data model, database, and available features. And some of these packages that simplify things too much actually have security flaws underneath.\n\n---\n\n**FastAPI** doesn't make any compromise with any database, data model or tool.\n\nIt gives you all the flexibility to choose the ones that fit your project the best.\n\nAnd you can use directly many well maintained and widely used packages like `pwdlib` and `PyJWT`, because **FastAPI** doesn't require any complex mechanisms to integrate external packages.\n\nBut it provides you the tools to simplify the process as much as possible without compromising flexibility, robustness, or security.\n\nAnd you can use and implement secure, standard protocols, like OAuth2 in a relatively simple way.\n\nYou can learn more in the **Advanced User Guide** about how to use OAuth2 \"scopes\", for a more fine-grained permission system, following these same standards. OAuth2 with scopes is the mechanism used by many big authentication providers, like Facebook, Google, GitHub, Microsoft, X (Twitter), etc. to authorize third party applications to interact with their APIs on behalf of their users.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/oauth2-jwt.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/oauth2-jwt.md#L257-L277", "start_line": 257, "end_line": 277}
{"id": "docs/en/docs/tutorial/security/simple-oauth2.md::Simple OAuth2 with Password and Bearer { #simple-oauth2-with-password-and-bearer }::L1", "text": "# Doc: docs/en/docs/tutorial/security/simple-oauth2.md | Page: Simple OAuth2 with Password and Bearer { #simple-oauth2-with-password-and-bearer } | Section: Simple OAuth2 with Password and Bearer { #simple-oauth2-with-password-and-bearer }\n# Simple OAuth2 with Password and Bearer { #simple-oauth2-with-password-and-bearer }\n\nNow let's build from the previous chapter and add the missing parts to have a complete security flow.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/simple-oauth2.md", "symbol": "Simple OAuth2 with Password and Bearer { #simple-oauth2-with-password-and-bearer }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/simple-oauth2.md#L1-L4", "start_line": 1, "end_line": 4}
{"id": "docs/en/docs/tutorial/security/simple-oauth2.md::Get the `username` and `password` { #get-the-username-and-password }::L5", "text": "# Doc: docs/en/docs/tutorial/security/simple-oauth2.md | Page: Simple OAuth2 with Password and Bearer { #simple-oauth2-with-password-and-bearer } | Section: Get the `username` and `password` { #get-the-username-and-password }\n## Get the `username` and `password` { #get-the-username-and-password }\n\nWe are going to use **FastAPI** security utilities to get the `username` and `password`.\n\nOAuth2 specifies that when using the \"password flow\" (that we are using) the client/user must send `username` and `password` fields as form data.\n\nAnd the spec says that the fields have to be named like that. So `user-name` or `email` wouldn't work.\n\nBut don't worry, you can show it as you wish to your final users in the frontend.\n\nAnd your database models can use any other names you want.\n\nBut for the login *path operation*, we need to use these names to be compatible with the spec (and be able to, for example, use the integrated API documentation system).\n\nThe spec also states that the `username` and `password` must be sent as form data (so, no JSON here).\n\n### `scope` { #scope }\n\nThe spec also says that the client can send another form field \"`scope`\".\n\nThe form field name is `scope` (in singular), but it is actually a long string with \"scopes\" separated by spaces.\n\nEach \"scope\" is just a string (without spaces).\n\nThey are normally used to declare specific security permissions, for example:\n\n* `users:read` or `users:write` are common examples.\n* `instagram_basic` is used by Facebook / Instagram.\n* `https://www.googleapis.com/auth/drive` is used by Google.\n\n/// note\n\nIn OAuth2 a \"scope\" is just a string that declares a specific permission required.\n\nIt doesn't matter if it has other characters like `:` or if it is a URL.\n\nThose details are implementation specific.\n\nFor OAuth2 they are just strings.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/security/simple-oauth2.md", "symbol": "Get the `username` and `password` { #get-the-username-and-password }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/simple-oauth2.md#L5-L46", "start_line": 5, "end_line": 46}
{"id": "docs/en/docs/tutorial/security/simple-oauth2.md::Code to get the `username` and `password` { #code-to-get-the-username-and-password }::L47", "text": "# Doc: docs/en/docs/tutorial/security/simple-oauth2.md | Page: Simple OAuth2 with Password and Bearer { #simple-oauth2-with-password-and-bearer } | Section: Code to get the `username` and `password` { #code-to-get-the-username-and-password }\n## Code to get the `username` and `password` { #code-to-get-the-username-and-password }\n\nNow let's use the utilities provided by **FastAPI** to handle this.\n\n### `OAuth2PasswordRequestForm` { #oauth2passwordrequestform }\n\nFirst, import `OAuth2PasswordRequestForm`, and use it as a dependency with `Depends` in the *path operation* for `/token`:\n\n{* ../../docs_src/security/tutorial003_an_py310.py hl[4,78] *}\n\n`OAuth2PasswordRequestForm` is a class dependency that declares a form body with:\n\n* The `username`.\n* The `password`.\n* An optional `scope` field as a big string, composed of strings separated by spaces.\n* An optional `grant_type`.\n\n/// tip\n\nThe OAuth2 spec actually *requires* a field `grant_type` with a fixed value of `password`, but `OAuth2PasswordRequestForm` doesn't enforce it.\n\nIf you need to enforce it, use `OAuth2PasswordRequestFormStrict` instead of `OAuth2PasswordRequestForm`.\n\n///\n\n* An optional `client_id` (we don't need it for our example).\n* An optional `client_secret` (we don't need it for our example).\n\n/// note\n\nThe `OAuth2PasswordRequestForm` is not a special class for **FastAPI** as is `OAuth2PasswordBearer`.\n\n`OAuth2PasswordBearer` makes **FastAPI** know that it is a security scheme. So it is added that way to OpenAPI.\n\nBut `OAuth2PasswordRequestForm` is just a class dependency that you could have written yourself, or you could have declared `Form` parameters directly.\n\nBut as it's a common use case, it is provided by **FastAPI** directly, just to make it easier.\n\n///\n\n### Use the form data { #use-the-form-data }\n\n/// tip\n\nThe instance of the dependency class `OAuth2PasswordRequestForm` won't have an attribute `scope` with the long string separated by spaces, instead, it will have a `scopes` attribute with the actual list of strings for each scope sent.\n\nWe are not using `scopes` in this example, but the functionality is there if you need it.\n\n///\n\nNow, get the user data from the (fake) database, using the `username` from the form field.\n\nIf there is no such user, we return an error saying \"Incorrect username or password\".\n\nFor the error, we use the exception `HTTPException`:\n\n{* ../../docs_src/security/tutorial003_an_py310.py hl[3,79:81] *}\n\n### Check the password { #check-the-password }\n\nAt this point we have the user data from our database, but we haven't checked the password.\n\nLet's put that data in the Pydantic `UserInDB` model first.\n\nYou should never save plaintext passwords, so, we'll use the (fake) password hashing system.\n\nIf the passwords don't match, we return the same error.\n\n#### Password hashing { #password-hashing }\n\n\"Hashing\" means: converting some content (a password in this case) into a sequence of bytes (just a string) that looks like gibberish.\n\nWhenever you pass exactly the same content (exactly the same password) you get exactly the same gibberish.\n\nBut you cannot convert from the gibberish back to the password.\n\n##### Why use password hashing { #why-use-password-hashing }\n\nIf your database is stolen, the thief won't have your users' plaintext passwords, only the hashes.\n\nSo, the thief won't be able to try to use those same passwords in another system (as many users use the same password everywhere, this would be dangerous).\n\n{* ../../docs_src/security/tutorial003_an_py310.py hl[82:85] *}\n\n#### About `**user_dict` { #about-user-dict }\n\n`UserInDB(**user_dict)` means:\n\n*Pass the keys and values of the `user_dict` directly as key-value arguments, equivalent to:*\n\n```Python\nUserInDB(\n username = user_dict[\"username\"],\n email = user_dict[\"email\"],\n full_name = user_dict[\"full_name\"],\n disabled = user_dict[\"disabled\"],\n hashed_password = user_dict[\"hashed_password\"],\n)\n```\n\n/// note\n\nFor a more complete explanation of `**user_dict` check back in [the documentation for **Extra Models**](../extra-models.md#about-user-in-model-dump).\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/security/simple-oauth2.md", "symbol": "Code to get the `username` and `password` { #code-to-get-the-username-and-password }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/simple-oauth2.md#L47-L152", "start_line": 47, "end_line": 152}
{"id": "docs/en/docs/tutorial/security/simple-oauth2.md::Return the token { #return-the-token }::L153", "text": "# Doc: docs/en/docs/tutorial/security/simple-oauth2.md | Page: Simple OAuth2 with Password and Bearer { #simple-oauth2-with-password-and-bearer } | Section: Return the token { #return-the-token }\n## Return the token { #return-the-token }\n\nThe response of the `token` endpoint must be a JSON object.\n\nIt should have a `token_type`. In our case, as we are using \"Bearer\" tokens, the token type should be \"`bearer`\".\n\nAnd it should have an `access_token`, with a string containing our access token.\n\nFor this simple example, we are going to just be completely insecure and return the same `username` as the token.\n\n/// tip\n\nIn the next chapter, you will see a real secure implementation, with password hashing and JWT tokens.\n\nBut for now, let's focus on the specific details we need.\n\n///\n\n{* ../../docs_src/security/tutorial003_an_py310.py hl[87] *}\n\n/// tip\n\nBy the spec, you should return a JSON with an `access_token` and a `token_type`, the same as in this example.\n\nThis is something that you have to do yourself in your code, and make sure you use those JSON keys.\n\nIt's almost the only thing that you have to remember to do correctly yourself, to be compliant with the specifications.\n\nFor the rest, **FastAPI** handles it for you.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/security/simple-oauth2.md", "symbol": "Return the token { #return-the-token }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/simple-oauth2.md#L153-L184", "start_line": 153, "end_line": 184}
{"id": "docs/en/docs/tutorial/security/simple-oauth2.md::Update the dependencies { #update-the-dependencies }::L185", "text": "# Doc: docs/en/docs/tutorial/security/simple-oauth2.md | Page: Simple OAuth2 with Password and Bearer { #simple-oauth2-with-password-and-bearer } | Section: Update the dependencies { #update-the-dependencies }\n## Update the dependencies { #update-the-dependencies }\n\nNow we are going to update our dependencies.\n\nWe want to get the `current_user` *only* if this user is active.\n\nSo, we create an additional dependency `get_current_active_user` that in turn uses `get_current_user` as a dependency.\n\nBoth of these dependencies will just return an HTTP error if the user doesn't exist, or is inactive.\n\nSo, in our endpoint, we will only get a user if the user exists, was correctly authenticated, and is active:\n\n{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *}\n\n/// note\n\nThe additional header `WWW-Authenticate` with value `Bearer` we are returning here is also part of the spec.\n\nAny HTTP (error) status code 401 \"UNAUTHORIZED\" is supposed to also return a `WWW-Authenticate` header.\n\nIn the case of bearer tokens (our case), the value of that header should be `Bearer`.\n\nYou can actually skip that extra header and it would still work.\n\nBut it's provided here to be compliant with the specifications.\n\nAlso, there might be tools that expect and use it (now or in the future) and that might be useful for you or your users, now or in the future.\n\nThat's the benefit of standards...\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/security/simple-oauth2.md", "symbol": "Update the dependencies { #update-the-dependencies }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/simple-oauth2.md#L185-L216", "start_line": 185, "end_line": 216}
{"id": "docs/en/docs/tutorial/security/simple-oauth2.md::See it in action { #see-it-in-action }::L217", "text": "# Doc: docs/en/docs/tutorial/security/simple-oauth2.md | Page: Simple OAuth2 with Password and Bearer { #simple-oauth2-with-password-and-bearer } | Section: See it in action { #see-it-in-action }\n## See it in action { #see-it-in-action }\n\nOpen the interactive docs: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).\n\n### Authenticate { #authenticate }\n\nClick the \"Authorize\" button.\n\nUse the credentials:\n\nUser: `johndoe`\n\nPassword: `secret`\n\n![](\"/img/tutorial/security/image04.png\")
\n\nAfter authenticating in the system, you will see it like:\n\n![](\"/img/tutorial/security/image05.png\")
\n\n### Get your own user data { #get-your-own-user-data }\n\nNow use the operation `GET` with the path `/users/me`.\n\nYou will get your user's data, like:\n\n```JSON\n{\n \"username\": \"johndoe\",\n \"email\": \"johndoe@example.com\",\n \"full_name\": \"John Doe\",\n \"disabled\": false,\n \"hashed_password\": \"fakehashedsecret\"\n}\n```\n\n![](\"/img/tutorial/security/image06.png\")
\n\nIf you click the lock icon and logout, and then try the same operation again, you will get an HTTP 401 error of:\n\n```JSON\n{\n \"detail\": \"Not authenticated\"\n}\n```\n\n### Inactive user { #inactive-user }\n\nNow try with an inactive user, authenticate with:\n\nUser: `alice`\n\nPassword: `secret2`\n\nAnd try to use the operation `GET` with the path `/users/me`.\n\nYou will get an \"Inactive user\" error, like:\n\n```JSON\n{\n \"detail\": \"Inactive user\"\n}\n```", "source_type": "doc", "path": "docs/en/docs/tutorial/security/simple-oauth2.md", "symbol": "See it in action { #see-it-in-action }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/simple-oauth2.md#L217-L280", "start_line": 217, "end_line": 280}
{"id": "docs/en/docs/tutorial/security/simple-oauth2.md::Recap { #recap }::L281", "text": "# Doc: docs/en/docs/tutorial/security/simple-oauth2.md | Page: Simple OAuth2 with Password and Bearer { #simple-oauth2-with-password-and-bearer } | Section: Recap { #recap }\n## Recap { #recap }\n\nYou now have the tools to implement a complete security system based on `username` and `password` for your API.\n\nUsing these tools, you can make the security system compatible with any database and with any user or data model.\n\nThe only detail missing is that it is not actually \"secure\" yet.\n\nIn the next chapter you'll see how to use a secure password hashing library and JWT tokens.", "source_type": "doc", "path": "docs/en/docs/tutorial/security/simple-oauth2.md", "symbol": "Recap { #recap }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/security/simple-oauth2.md#L281-L289", "start_line": 281, "end_line": 289}
{"id": "docs/en/docs/tutorial/server-sent-events.md::Server-Sent Events (SSE) { #server-sent-events-sse }::L1", "text": "# Doc: docs/en/docs/tutorial/server-sent-events.md | Page: Server-Sent Events (SSE) { #server-sent-events-sse } | Section: Server-Sent Events (SSE) { #server-sent-events-sse }\n# Server-Sent Events (SSE) { #server-sent-events-sse }\n\nYou can stream data to the client using **Server-Sent Events** (SSE).\n\nThis is similar to [Stream JSON Lines](stream-json-lines.md), but uses the `text/event-stream` format, which is supported natively by browsers with the [`EventSource` API](https://developer.mozilla.org/en-US/docs/Web/API/EventSource).\n\n/// note\n\nAdded in FastAPI 0.135.0.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/server-sent-events.md", "symbol": "Server-Sent Events (SSE) { #server-sent-events-sse }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/server-sent-events.md#L1-L12", "start_line": 1, "end_line": 12}
{"id": "docs/en/docs/tutorial/server-sent-events.md::What are Server-Sent Events? { #what-are-server-sent-events }::L13", "text": "# Doc: docs/en/docs/tutorial/server-sent-events.md | Page: Server-Sent Events (SSE) { #server-sent-events-sse } | Section: What are Server-Sent Events? { #what-are-server-sent-events }\n## What are Server-Sent Events? { #what-are-server-sent-events }\n\nSSE is a standard for streaming data from the server to the client over HTTP.\n\nEach event is a small text block with \"fields\" like `data`, `event`, `id`, and `retry`, separated by blank lines.\n\nIt looks like this:\n\n```\ndata: {\"name\": \"Portal Gun\", \"price\": 999.99}\n\ndata: {\"name\": \"Plumbus\", \"price\": 32.99}\n\n```\n\nSSE is commonly used for AI chat streaming, live notifications, logs and observability, and other cases where the server pushes updates to the client.\n\n/// tip\n\nIf you want to stream binary data, for example video or audio, check the advanced guide: [Stream Data](../advanced/stream-data.md).\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/server-sent-events.md", "symbol": "What are Server-Sent Events? { #what-are-server-sent-events }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/server-sent-events.md#L13-L35", "start_line": 13, "end_line": 35}
{"id": "docs/en/docs/tutorial/server-sent-events.md::Stream SSE with FastAPI { #stream-sse-with-fastapi }::L36", "text": "# Doc: docs/en/docs/tutorial/server-sent-events.md | Page: Server-Sent Events (SSE) { #server-sent-events-sse } | Section: Stream SSE with FastAPI { #stream-sse-with-fastapi }\n## Stream SSE with FastAPI { #stream-sse-with-fastapi }\n\nTo stream SSE with FastAPI, use `yield` in your *path operation function* and set `response_class=EventSourceResponse`.\n\nImport `EventSourceResponse` from `fastapi.sse`:\n\n{* ../../docs_src/server_sent_events/tutorial001_py310.py ln[1:25] hl[4,22] *}\n\nEach yielded item is encoded as JSON and sent in the `data:` field of an SSE event.\n\nIf you declare the return type as `AsyncIterable[Item]`, FastAPI will use it to **validate**, **document**, and **serialize** the data using Pydantic.\n\n{* ../../docs_src/server_sent_events/tutorial001_py310.py ln[1:25] hl[10:12,23] *}\n\n/// tip\n\nAs Pydantic will serialize it in the **Rust** side, you will get much higher **performance** than if you don't declare a return type.\n\n///\n\n### Non-async *path operation functions* { #non-async-path-operation-functions }\n\nYou can also use regular `def` functions (without `async`), and use `yield` the same way.\n\nFastAPI will make sure it's run correctly so that it doesn't block the event loop.\n\nAs in this case the function is not async, the right return type would be `Iterable[Item]`:\n\n{* ../../docs_src/server_sent_events/tutorial001_py310.py ln[28:31] hl[29] *}\n\n### No Return Type { #no-return-type }\n\nYou can also omit the return type. FastAPI will use the [`jsonable_encoder`](./encoder.md) to convert the data and send it.\n\n{* ../../docs_src/server_sent_events/tutorial001_py310.py ln[34:37] hl[35] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/server-sent-events.md", "symbol": "Stream SSE with FastAPI { #stream-sse-with-fastapi }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/server-sent-events.md#L36-L71", "start_line": 36, "end_line": 71}
{"id": "docs/en/docs/tutorial/server-sent-events.md::`ServerSentEvent` { #serversentevent }::L72", "text": "# Doc: docs/en/docs/tutorial/server-sent-events.md | Page: Server-Sent Events (SSE) { #server-sent-events-sse } | Section: `ServerSentEvent` { #serversentevent }\n## `ServerSentEvent` { #serversentevent }\n\nIf you need to set SSE fields like `event`, `id`, `retry`, or `comment`, you can yield `ServerSentEvent` objects instead of plain data.\n\nImport `ServerSentEvent` from `fastapi.sse`:\n\n{* ../../docs_src/server_sent_events/tutorial002_py310.py hl[4,26] *}\n\nThe `data` field is always encoded as JSON. You can pass any value that can be serialized as JSON, including Pydantic models.", "source_type": "doc", "path": "docs/en/docs/tutorial/server-sent-events.md", "symbol": "`ServerSentEvent` { #serversentevent }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/server-sent-events.md#L72-L81", "start_line": 72, "end_line": 81}
{"id": "docs/en/docs/tutorial/server-sent-events.md::Raw Data { #raw-data }::L82", "text": "# Doc: docs/en/docs/tutorial/server-sent-events.md | Page: Server-Sent Events (SSE) { #server-sent-events-sse } | Section: Raw Data { #raw-data }\n## Raw Data { #raw-data }\n\nIf you need to send data **without** JSON encoding, use `raw_data` instead of `data`.\n\nThis is useful for sending pre-formatted text, log lines, or special \"sentinel\" values like `[DONE]`.\n\n{* ../../docs_src/server_sent_events/tutorial003_py310.py hl[17] *}\n\n/// note\n\n`data` and `raw_data` are mutually exclusive. You can only set one of them on each `ServerSentEvent`.\n\n///", "source_type": "doc", "path": "docs/en/docs/tutorial/server-sent-events.md", "symbol": "Raw Data { #raw-data }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/server-sent-events.md#L82-L95", "start_line": 82, "end_line": 95}
{"id": "docs/en/docs/tutorial/server-sent-events.md::Resuming with `Last-Event-ID` { #resuming-with-last-event-id }::L96", "text": "# Doc: docs/en/docs/tutorial/server-sent-events.md | Page: Server-Sent Events (SSE) { #server-sent-events-sse } | Section: Resuming with `Last-Event-ID` { #resuming-with-last-event-id }\n## Resuming with `Last-Event-ID` { #resuming-with-last-event-id }\n\nWhen a browser reconnects after a connection drop, it sends the last received `id` in the `Last-Event-ID` header.\n\nYou can read it as a header parameter and use it to resume the stream from where the client left off:\n\n{* ../../docs_src/server_sent_events/tutorial004_py310.py hl[25,27,31] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/server-sent-events.md", "symbol": "Resuming with `Last-Event-ID` { #resuming-with-last-event-id }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/server-sent-events.md#L96-L103", "start_line": 96, "end_line": 103}
{"id": "docs/en/docs/tutorial/server-sent-events.md::SSE with POST { #sse-with-post }::L104", "text": "# Doc: docs/en/docs/tutorial/server-sent-events.md | Page: Server-Sent Events (SSE) { #server-sent-events-sse } | Section: SSE with POST { #sse-with-post }\n## SSE with POST { #sse-with-post }\n\nSSE works with **any HTTP method**, not just `GET`.\n\nThis is useful for protocols like [MCP](https://modelcontextprotocol.io) that stream SSE over `POST`:\n\n{* ../../docs_src/server_sent_events/tutorial005_py310.py hl[14] *}", "source_type": "doc", "path": "docs/en/docs/tutorial/server-sent-events.md", "symbol": "SSE with POST { #sse-with-post }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/server-sent-events.md#L104-L111", "start_line": 104, "end_line": 111}
{"id": "docs/en/docs/tutorial/server-sent-events.md::Technical Details { #technical-details }::L112", "text": "# Doc: docs/en/docs/tutorial/server-sent-events.md | Page: Server-Sent Events (SSE) { #server-sent-events-sse } | Section: Technical Details { #technical-details }\n## Technical Details { #technical-details }\n\nFastAPI implements some SSE best practices out of the box.\n\n* Send a **\"keep alive\" `ping` comment** every 15 seconds when there hasn't been any message, to prevent some proxies from closing the connection, as suggested in the [HTML specification: Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html#authoring-notes).\n* Set the `Cache-Control: no-cache` header to **prevent caching** of the stream.\n* Set a special header `X-Accel-Buffering: no` to **prevent buffering** in some proxies like Nginx.\n\nYou don't have to do anything about it, it works out of the box. 🤓", "source_type": "doc", "path": "docs/en/docs/tutorial/server-sent-events.md", "symbol": "Technical Details { #technical-details }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/server-sent-events.md#L112-L120", "start_line": 112, "end_line": 120}
{"id": "docs/en/docs/tutorial/sql-databases.md::SQL (Relational) Databases { #sql-relational-databases }::L1", "text": "# Doc: docs/en/docs/tutorial/sql-databases.md | Page: SQL (Relational) Databases { #sql-relational-databases } | Section: SQL (Relational) Databases { #sql-relational-databases }\n# SQL (Relational) Databases { #sql-relational-databases }\n\n**FastAPI** doesn't require you to use a SQL (relational) database. But you can use **any database** that you want.\n\nHere we'll see an example using [SQLModel](https://sqlmodel.tiangolo.com/).\n\n**SQLModel** is built on top of [SQLAlchemy](https://www.sqlalchemy.org/) and Pydantic. It was made by the same author of **FastAPI** to be the perfect match for FastAPI applications that need to use **SQL databases**.\n\n/// tip\n\nYou could use any other SQL or NoSQL database library you want (in some cases called \"ORMs\"), FastAPI doesn't force you to use anything. 😎\n\n///\n\nAs SQLModel is based on SQLAlchemy, you can easily use **any database supported** by SQLAlchemy (which makes them also supported by SQLModel), like:\n\n* PostgreSQL\n* MySQL\n* SQLite\n* Oracle\n* Microsoft SQL Server, etc.\n\nIn this example, we'll use **SQLite**, because it uses a single file and Python has integrated support. So, you can copy this example and run it as is.\n\nLater, for your production application, you might want to use a database server like **PostgreSQL**.\n\n/// tip\n\nThere is an official project generator with **FastAPI** and **PostgreSQL** including a frontend and more tools: [https://github.com/fastapi/full-stack-fastapi-template](https://github.com/fastapi/full-stack-fastapi-template)\n\n///\n\nThis is a very simple and short tutorial, if you want to learn about databases in general, about SQL, or more advanced features, go to the [SQLModel docs](https://sqlmodel.tiangolo.com/).", "source_type": "doc", "path": "docs/en/docs/tutorial/sql-databases.md", "symbol": "SQL (Relational) Databases { #sql-relational-databases }", "url": "https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/sql-databases.md#L1-L34", "start_line": 1, "end_line": 34}
{"id": "docs/en/docs/tutorial/sql-databases.md::Install `SQLModel` { #install-sqlmodel }::L35", "text": "# Doc: docs/en/docs/tutorial/sql-databases.md | Page: SQL (Relational) Databases { #sql-relational-databases } | Section: Install `SQLModel` { #install-sqlmodel }\n## Install `SQLModel` { #install-sqlmodel }\n\nFirst, make sure you create your [virtual environment](../virtual-environments.md), activate it, and then install `sqlmodel`:\n\n![](\"/img/tutorial/sql-databases/image01.png\")
\n![](\"/img/tutorial/sql-databases/image02.png\")
\n