diff --git a/docs/en/docs/advanced/dataclasses.md b/docs/en/docs/advanced/dataclasses.md index dbc91409a5..be85303bfb 100644 --- a/docs/en/docs/advanced/dataclasses.md +++ b/docs/en/docs/advanced/dataclasses.md @@ -64,7 +64,7 @@ In that case, you can simply swap the standard `dataclasses` with `pydantic.data 6. Here we are returning a dictionary that contains `items` which is a list of dataclasses. - FastAPI is still capable of serializing the data to JSON. + FastAPI is still capable of serializing the data to JSON. 7. Here the `response_model` is using a type annotation of a list of `Author` dataclasses. diff --git a/docs/en/docs/advanced/path-operation-advanced-configuration.md b/docs/en/docs/advanced/path-operation-advanced-configuration.md index e0e3c96a0e..3d7bfdee59 100644 --- a/docs/en/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/en/docs/advanced/path-operation-advanced-configuration.md @@ -141,7 +141,7 @@ You could do that with `openapi_extra`: {* ../../docs_src/path_operation_advanced_configuration/tutorial006_py39.py hl[19:36, 39:40] *} -In 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. +In 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. Nevertheless, we can declare the expected schema for the request body. diff --git a/docs/en/docs/alternatives.md b/docs/en/docs/alternatives.md index e656815430..73a6c1cb59 100644 --- a/docs/en/docs/alternatives.md +++ b/docs/en/docs/alternatives.md @@ -137,7 +137,7 @@ There are several Flask REST frameworks, but after investing the time and work i ### Marshmallow { #marshmallow } -One 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. +One 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. Another 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. @@ -145,7 +145,7 @@ Without a data validation system, you would have to do all the checks by hand, i These features are what Marshmallow was built to provide. It is a great library, and I have used it a lot before. -But 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. +But 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. /// check | Inspired **FastAPI** to @@ -155,7 +155,7 @@ Use code to define "schemas" that provide data types and validation, automatical ### Webargs { #webargs } -Another big feature required by APIs is parsing data from incoming requests. +Another big feature required by APIs is parsing data from incoming requests. Webargs is a tool that was made to provide that on top of several frameworks, including Flask. @@ -419,7 +419,7 @@ Handle all the data validation, data serialization and automatic model documenta ### Starlette { #starlette } -Starlette is a lightweight ASGI framework/toolkit, which is ideal for building high-performance asyncio services. +Starlette is a lightweight ASGI framework/toolkit, which is ideal for building high-performance asyncio services. It is very simple and intuitive. It's designed to be easily extensible, and have modular components. diff --git a/docs/en/docs/deployment/docker.md b/docs/en/docs/deployment/docker.md index 6b71f7360d..9044163c1b 100644 --- a/docs/en/docs/deployment/docker.md +++ b/docs/en/docs/deployment/docker.md @@ -456,7 +456,7 @@ Without using containers, making applications run on startup and with restarts c ## Replication - Number of Processes { #replication-number-of-processes } -If you have a cluster of machines with **Kubernetes**, Docker Swarm Mode, Nomad, or another similar complex system to manage distributed containers on multiple machines, then you will probably want to **handle replication** at the **cluster level** instead of using a **process manager** (like Uvicorn with workers) in each container. +If you have a cluster of machines with **Kubernetes**, Docker Swarm Mode, Nomad, or another similar complex system to manage distributed containers on multiple machines, then you will probably want to **handle replication** at the **cluster level** instead of using a **process manager** (like Uvicorn with workers) in each container. One of those distributed container management systems like Kubernetes normally has some integrated way of handling **replication of containers** while still supporting **load balancing** for the incoming requests. All at the **cluster level**. diff --git a/docs/en/docs/deployment/https.md b/docs/en/docs/deployment/https.md index a249a36721..6f45a8903a 100644 --- a/docs/en/docs/deployment/https.md +++ b/docs/en/docs/deployment/https.md @@ -65,7 +65,7 @@ Here's an example of how an HTTPS API could look like, step by step, paying atte It would probably all start by you **acquiring** some **domain name**. Then, you would configure it in a DNS server (possibly your same cloud provider). -You would probably get a cloud server (a virtual machine) or something similar, and it would have a fixed **public IP address**. +You would probably get a cloud server (a virtual machine) or something similar, and it would have a fixed **public IP address**. In the DNS server(s) you would configure a record (an "`A record`") to point **your domain** to the public **IP address of your server**. diff --git a/docs/en/docs/features.md b/docs/en/docs/features.md index a345e4a0e3..307607ad7f 100644 --- a/docs/en/docs/features.md +++ b/docs/en/docs/features.md @@ -6,7 +6,7 @@ ### Based on open standards { #based-on-open-standards } -* OpenAPI for API creation, including declarations of path operations, parameters, request bodies, security, etc. +* OpenAPI for API creation, including declarations of path operations, parameters, request bodies, security, etc. * Automatic data model documentation with JSON Schema (as OpenAPI itself is based on JSON Schema). * Designed around these standards, after a meticulous study. Instead of an afterthought layer on top. * This also allows using automatic **client code generation** in many languages. @@ -136,7 +136,7 @@ All built as reusable tools and components that are easy to integrate with your ### Dependency Injection { #dependency-injection } -FastAPI includes an extremely easy to use, but extremely powerful Dependency Injection system. +FastAPI includes an extremely easy to use, but extremely powerful Dependency Injection system. * Even dependencies can have dependencies, creating a hierarchy or **"graph" of dependencies**. * All **automatically handled** by the framework. @@ -153,8 +153,8 @@ Any integration is designed to be so simple to use (with dependencies) that you ### Tested { #tested } -* 100% test coverage. -* 100% type annotated code base. +* 100% test coverage. +* 100% type annotated code base. * Used in production applications. ## Starlette features { #starlette-features } @@ -190,7 +190,7 @@ With **FastAPI** you get all of **Pydantic**'s features (as FastAPI is based on * **No brainfuck**: * No new schema definition micro-language to learn. * If you know Python types you know how to use Pydantic. -* Plays nicely with your **IDE/linter/brain**: +* Plays nicely with your **IDE/linter/brain**: * Because pydantic data structures are just instances of classes you define; auto-completion, linting, mypy and your intuition should all work properly with your validated data. * Validate **complex structures**: * Use of hierarchical Pydantic models, Python `typing`’s `List` and `Dict`, etc. diff --git a/docs/en/docs/index.md b/docs/en/docs/index.md index 5eb47c7b32..4897af5c95 100644 --- a/docs/en/docs/index.md +++ b/docs/en/docs/index.md @@ -40,7 +40,7 @@ The key features are: * **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic). [One of the fastest Python frameworks available](#performance). * **Fast to code**: Increase the speed to develop features by about 200% to 300%. * * **Fewer bugs**: Reduce about 40% of human (developer) induced errors. * -* **Intuitive**: Great editor support. Completion everywhere. Less time debugging. +* **Intuitive**: Great editor support. Completion everywhere. Less time debugging. * **Easy**: Designed to be easy to use and learn. Less time reading docs. * **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs. * **Robust**: Get production-ready code. With automatic interactive documentation. @@ -374,7 +374,7 @@ item: Item * Validation of data: * Automatic and clear errors when the data is invalid. * Validation even for deeply nested JSON objects. -* Conversion of input data: coming from the network to Python data and types. Reading from: +* Conversion of input data: coming from the network to Python data and types. Reading from: * JSON. * Path parameters. * Query parameters. @@ -382,7 +382,7 @@ item: Item * Headers. * Forms. * Files. -* Conversion of output data: converting from Python data and types to network data (as JSON): +* Conversion of output data: converting from Python data and types to network data (as JSON): * Convert Python types (`str`, `int`, `float`, `bool`, `list`, etc). * `datetime` objects. * `UUID` objects. @@ -445,7 +445,7 @@ For a more complete example including more features, see the Dependency Injection** system. +* A very powerful and easy to use **Dependency Injection** system. * Security and authentication, including support for **OAuth2** with **JWT tokens** and **HTTP Basic** auth. * More advanced (but equally easy) techniques for declaring **deeply nested JSON models** (thanks to Pydantic). * **GraphQL** integration with Strawberry and other libraries. @@ -530,7 +530,7 @@ Used by Starlette: * httpx - Required if you want to use the `TestClient`. * jinja2 - Required if you want to use the default template configuration. -* python-multipart - Required if you want to support form "parsing", with `request.form()`. +* python-multipart - Required if you want to support form "parsing", with `request.form()`. Used by FastAPI: diff --git a/docs/en/docs/python-types.md b/docs/en/docs/python-types.md index b685deef29..6de170ada4 100644 --- a/docs/en/docs/python-types.md +++ b/docs/en/docs/python-types.md @@ -2,7 +2,7 @@ Python has support for optional "type hints" (also called "type annotations"). -These **"type hints"** or annotations are a special syntax that allow declaring the type of a variable. +These **"type hints"** or annotations are a special syntax that allow declaring the type of a variable. By declaring types for your variables, editors and tools can give you better support. @@ -34,7 +34,7 @@ The function does the following: * Takes a `first_name` and `last_name`. * Converts the first letter of each one to upper case with `title()`. -* Concatenates them with a space in the middle. +* Concatenates them with a space in the middle. {* ../../docs_src/python_types/tutorial001_py39.py hl[2] *} @@ -222,7 +222,7 @@ You can declare that a variable can be any of **several types**, for example, an In Python 3.6 and above (including Python 3.10) you can use the `Union` type from `typing` and put inside the square brackets the possible types to accept. -In Python 3.10 there's also a **new syntax** where you can put the possible types separated by a vertical bar (`|`). +In Python 3.10 there's also a **new syntax** where you can put the possible types separated by a vertical bar (`|`). //// tab | Python 3.10+ @@ -336,7 +336,7 @@ And the same as with previous Python versions, from the `typing` module: * `Optional` * ...and others. -In Python 3.10, as an alternative to using the generics `Union` and `Optional`, you can use the vertical bar (`|`) to declare unions of types, that's a lot better and simpler. +In Python 3.10, as an alternative to using the generics `Union` and `Optional`, you can use the vertical bar (`|`) to declare unions of types, that's a lot better and simpler. //// @@ -411,7 +411,7 @@ Pydantic has a special behavior when you use `Optional` or `Union[Something, Non ## Type Hints with Metadata Annotations { #type-hints-with-metadata-annotations } -Python also has a feature that allows putting **additional metadata** in these type hints using `Annotated`. +Python also has a feature that allows putting **additional metadata** in these type hints using `Annotated`. Since Python 3.9, `Annotated` is a part of the standard library, so you can import it from `typing`. diff --git a/docs/en/docs/tutorial/cookie-param-models.md b/docs/en/docs/tutorial/cookie-param-models.md index 016a65d7f0..609838f766 100644 --- a/docs/en/docs/tutorial/cookie-param-models.md +++ b/docs/en/docs/tutorial/cookie-param-models.md @@ -46,7 +46,7 @@ But even if you **fill the data** and click "Execute", because the docs UI works In some special use cases (probably not very common), you might want to **restrict** the cookies that you want to receive. -Your API now has the power to control its own cookie consent. ðŸĪŠðŸŠ +Your API now has the power to control its own cookie consent. ðŸĪŠðŸŠ You can use Pydantic's model configuration to `forbid` any `extra` fields: @@ -54,9 +54,9 @@ You can use Pydantic's model configuration to `forbid` any `extra` fields: If a client tries to send some **extra cookies**, they will receive an **error** response. -Poor cookie banners with all their effort to get your consent for the API to reject it. 🍊 +Poor cookie banners with all their effort to get your consent for the API to reject it. 🍊 -For example, if the client tries to send a `santa_tracker` cookie with a value of `good-list-please`, the client will receive an **error** response telling them that the `santa_tracker` cookie is not allowed: +For example, if the client tries to send a `santa_tracker` cookie with a value of `good-list-please`, the client will receive an **error** response telling them that the `santa_tracker` cookie is not allowed: ```json { @@ -73,4 +73,4 @@ For example, if the client tries to send a `santa_tracker` cookie with a value o ## Summary { #summary } -You can use **Pydantic models** to declare **cookies** in **FastAPI**. 😎 +You can use **Pydantic models** to declare **cookies** in **FastAPI**. 😎 diff --git a/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md index d9f3345619..cfcd961baa 100644 --- a/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md +++ b/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md @@ -1,6 +1,6 @@ # Dependencies with yield { #dependencies-with-yield } -FastAPI supports dependencies that do some extra steps after finishing. +FastAPI supports dependencies that do some extra steps after finishing. To do this, use `yield` instead of `return`, and write the extra steps (code) after. diff --git a/docs/en/docs/tutorial/dependencies/index.md b/docs/en/docs/tutorial/dependencies/index.md index d1116b2be0..4a1bb774d9 100644 --- a/docs/en/docs/tutorial/dependencies/index.md +++ b/docs/en/docs/tutorial/dependencies/index.md @@ -1,6 +1,6 @@ # Dependencies { #dependencies } -**FastAPI** has a very powerful but intuitive **Dependency Injection** system. +**FastAPI** has a very powerful but intuitive **Dependency Injection** system. It is designed to be very simple to use, and to make it very easy for any developer to integrate other components with **FastAPI**. diff --git a/docs/en/docs/tutorial/dependencies/sub-dependencies.md b/docs/en/docs/tutorial/dependencies/sub-dependencies.md index 967bffda79..b9a4e3ce74 100644 --- a/docs/en/docs/tutorial/dependencies/sub-dependencies.md +++ b/docs/en/docs/tutorial/dependencies/sub-dependencies.md @@ -58,7 +58,7 @@ query_extractor --> query_or_cookie_extractor --> read_query If 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. -And 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. +And 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. In 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`: diff --git a/docs/en/docs/tutorial/first-steps.md b/docs/en/docs/tutorial/first-steps.md index df8e91ecd4..a3263593dd 100644 --- a/docs/en/docs/tutorial/first-steps.md +++ b/docs/en/docs/tutorial/first-steps.md @@ -271,7 +271,7 @@ We are going to call them "**operations**" too. The `@app.get("/")` tells **FastAPI** that the function right below is in charge of handling requests that go to: * the path `/` -* using a get operation +* using a get operation /// info | `@decorator` Info diff --git a/docs/en/docs/tutorial/path-operation-configuration.md b/docs/en/docs/tutorial/path-operation-configuration.md index 59be5ab376..7abf350d19 100644 --- a/docs/en/docs/tutorial/path-operation-configuration.md +++ b/docs/en/docs/tutorial/path-operation-configuration.md @@ -56,7 +56,7 @@ You can add a `summary` and `description`: ## Description from docstring { #description-from-docstring } -As 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. +As 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. You can write Markdown in the docstring, it will be interpreted and displayed correctly (taking into account docstring indentation). @@ -90,7 +90,7 @@ So, if you don't provide one, **FastAPI** will automatically generate one of "Su ## Deprecate a *path operation* { #deprecate-a-path-operation } -If you need to mark a *path operation* as deprecated, but without removing it, pass the parameter `deprecated`: +If you need to mark a *path operation* as deprecated, but without removing it, pass the parameter `deprecated`: {* ../../docs_src/path_operation_configuration/tutorial006_py39.py hl[16] *} diff --git a/docs/en/docs/tutorial/path-params.md b/docs/en/docs/tutorial/path-params.md index ea4307900c..cf312f1fef 100644 --- a/docs/en/docs/tutorial/path-params.md +++ b/docs/en/docs/tutorial/path-params.md @@ -26,7 +26,7 @@ This will give you editor support inside of your function, with error checks, co /// -## Data conversion { #data-conversion } +## Data conversion { #data-conversion } If you run this example and open your browser at http://127.0.0.1:8000/items/3, you will see a response of: @@ -38,7 +38,7 @@ If you run this example and open your browser at "parsing". +So, with that type declaration, **FastAPI** gives you automatic request "parsing". /// @@ -144,7 +144,7 @@ Then create class attributes with fixed values, which will be the available vali /// tip -If you are wondering, "AlexNet", "ResNet", and "LeNet" are just names of Machine Learning models. +If you are wondering, "AlexNet", "ResNet", and "LeNet" are just names of Machine Learning models. /// @@ -242,7 +242,7 @@ In that case, the URL would be: `/files//home/johndoe/myfile.txt`, with a double With **FastAPI**, by using short, intuitive and standard Python type declarations, you get: * Editor support: error checks, autocompletion, etc. -* Data "parsing" +* Data "parsing" * Data validation * API annotation and automatic documentation diff --git a/docs/en/docs/tutorial/query-params-str-validations.md b/docs/en/docs/tutorial/query-params-str-validations.md index 692e8cfa73..1846ad56a9 100644 --- a/docs/en/docs/tutorial/query-params-str-validations.md +++ b/docs/en/docs/tutorial/query-params-str-validations.md @@ -109,7 +109,7 @@ FastAPI will now: ## Alternative (old): `Query` as the default value { #alternative-old-query-as-the-default-value } -Previous versions of FastAPI (before 0.95.0) required you to use `Query` as the default value of your parameter, instead of putting it in `Annotated`, there's a high chance that you will see code using it around, so I'll explain it to you. +Previous versions of FastAPI (before 0.95.0) required you to use `Query` as the default value of your parameter, instead of putting it in `Annotated`, there's a high chance that you will see code using it around, so I'll explain it to you. /// tip @@ -192,7 +192,7 @@ You can also add a parameter `min_length`: ## Add regular expressions { #add-regular-expressions } -You can define a regular expression `pattern` that the parameter should match: +You can define a regular expression `pattern` that the parameter should match: {* ../../docs_src/query_params_str_validations/tutorial004_an_py310.py hl[11] *} @@ -372,7 +372,7 @@ Then you can declare an `alias`, and that alias is what will be used to find the Now let's say you don't like this parameter anymore. -You have to leave it there a while because there are clients using it, but you want the docs to clearly show it as deprecated. +You have to leave it there a while because there are clients using it, but you want the docs to clearly show it as deprecated. Then pass the parameter `deprecated=True` to `Query`: @@ -436,7 +436,7 @@ Did you notice? a string using `value.startswith()` can take a tuple, and it wil #### A Random Item { #a-random-item } -With `data.items()` we get an iterable object with tuples containing the key and value for each dictionary item. +With `data.items()` we get an iterable object with tuples containing the key and value for each dictionary item. We convert this iterable object into a proper `list` with `list(data.items())`. diff --git a/docs/en/docs/tutorial/query-params.md b/docs/en/docs/tutorial/query-params.md index 3c9c225fb0..eeb59f9258 100644 --- a/docs/en/docs/tutorial/query-params.md +++ b/docs/en/docs/tutorial/query-params.md @@ -24,7 +24,7 @@ But when you declare them with Python types (in the example above, as `int`), th All the same process that applied for path parameters also applies for query parameters: * Editor support (obviously) -* Data "parsing" +* Data "parsing" * Data validation * Automatic documentation diff --git a/docs/en/docs/tutorial/request-forms.md b/docs/en/docs/tutorial/request-forms.md index d743c2ec4e..d63ffd5655 100644 --- a/docs/en/docs/tutorial/request-forms.md +++ b/docs/en/docs/tutorial/request-forms.md @@ -28,7 +28,7 @@ Create form parameters the same way you would for `Body` or `Query`: For example, in one of the ways the OAuth2 specification can be used (called "password flow") it is required to send a `username` and `password` as form fields. -The spec requires the fields to be exactly named `username` and `password`, and to be sent as form fields, not JSON. +The spec requires the fields to be exactly named `username` and `password`, and to be sent as form fields, not JSON. With `Form` you can declare the same configurations as with `Body` (and `Query`, `Path`, `Cookie`), including validation, examples, an alias (e.g. `user-name` instead of `username`), etc. diff --git a/docs/en/docs/tutorial/response-model.md b/docs/en/docs/tutorial/response-model.md index b287cdf50a..ac35390fad 100644 --- a/docs/en/docs/tutorial/response-model.md +++ b/docs/en/docs/tutorial/response-model.md @@ -201,7 +201,7 @@ This will also work because `RedirectResponse` is a subclass of `Response`, and But 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. -The 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 ðŸ’Ĩ: +The 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 ðŸ’Ĩ: {* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *} diff --git a/docs/en/docs/tutorial/schema-extra-example.md b/docs/en/docs/tutorial/schema-extra-example.md index daaea73c87..432f58b1e3 100644 --- a/docs/en/docs/tutorial/schema-extra-example.md +++ b/docs/en/docs/tutorial/schema-extra-example.md @@ -74,7 +74,7 @@ You can of course also pass multiple `examples`: When you do this, the examples will be part of the internal **JSON Schema** for that body data. -Nevertheless, 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. +Nevertheless, 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. ### OpenAPI-specific `examples` { #openapi-specific-examples } diff --git a/docs/en/docs/virtual-environments.md b/docs/en/docs/virtual-environments.md index c02e43ab91..615d7949f9 100644 --- a/docs/en/docs/virtual-environments.md +++ b/docs/en/docs/virtual-environments.md @@ -53,7 +53,7 @@ $ cd awesome-project ## Create a Virtual Environment { #create-a-virtual-environment } -When you start working on a Python project **for the first time**, create a virtual environment **inside your project**. +When you start working on a Python project **for the first time**, create a virtual environment **inside your project**. /// tip