mirror of https://github.com/tiangolo/fastapi.git
📝 Reword in docs, from "have in mind" to "keep in mind" (#10376)
Co-authored-by: Alejandra <90076947+alejsdev@users.noreply.github.com>
This commit is contained in:
parent
facdc91629
commit
838e9c964e
|
|
@ -28,7 +28,7 @@ For example, to declare another response with a status code `404` and a Pydantic
|
|||
```
|
||||
|
||||
!!! note
|
||||
Have in mind that you have to return the `JSONResponse` directly.
|
||||
Keep in mind that you have to return the `JSONResponse` directly.
|
||||
|
||||
!!! info
|
||||
The `model` key is not part of OpenAPI.
|
||||
|
|
|
|||
|
|
@ -125,7 +125,7 @@ Passing the `root_path` to `FastAPI` would be the equivalent of passing the `--r
|
|||
|
||||
### About `root_path`
|
||||
|
||||
Have in mind that the server (Uvicorn) won't use that `root_path` for anything else than passing it to the app.
|
||||
Keep in mind that the server (Uvicorn) won't use that `root_path` for anything else than passing it to the app.
|
||||
|
||||
But if you go with your browser to <a href="http://127.0.0.1:8000" class="external-link" target="_blank">http://127.0.0.1:8000/app</a> you will see the normal response:
|
||||
|
||||
|
|
@ -142,7 +142,7 @@ Uvicorn will expect the proxy to access Uvicorn at `http://127.0.0.1:8000/app`,
|
|||
|
||||
## About proxies with a stripped path prefix
|
||||
|
||||
Have in mind that a proxy with stripped path prefix is only one of the ways to configure it.
|
||||
Keep in mind that a proxy with stripped path prefix is only one of the ways to configure it.
|
||||
|
||||
Probably in many cases the default will be that the proxy doesn't have a stripped path prefix.
|
||||
|
||||
|
|
|
|||
|
|
@ -101,7 +101,7 @@ But as you passed the `HTMLResponse` in the `response_class` too, **FastAPI** wi
|
|||
|
||||
Here are some of the available responses.
|
||||
|
||||
Have in mind that you can use `Response` to return anything else, or even create a custom sub-class.
|
||||
Keep in mind that you can use `Response` to return anything else, or even create a custom sub-class.
|
||||
|
||||
!!! note "Technical Details"
|
||||
You could also use `from starlette.responses import HTMLResponse`.
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ And of course, it supports the same:
|
|||
This works the same way as with Pydantic models. And it is actually achieved in the same way underneath, using Pydantic.
|
||||
|
||||
!!! info
|
||||
Have in mind that dataclasses can't do everything Pydantic models can do.
|
||||
Keep in mind that dataclasses can't do everything Pydantic models can do.
|
||||
|
||||
So, you might still need to use Pydantic models.
|
||||
|
||||
|
|
|
|||
|
|
@ -159,4 +159,4 @@ Underneath, in the ASGI technical specification, this is part of the <a href="ht
|
|||
|
||||
## Sub Applications
|
||||
|
||||
🚨 Have 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){.internal-link target=_blank}.
|
||||
🚨 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){.internal-link target=_blank}.
|
||||
|
|
|
|||
|
|
@ -30,4 +30,4 @@ And if you declared a `response_model`, it will still be used to filter and conv
|
|||
|
||||
**FastAPI** will use that *temporal* 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`.
|
||||
|
||||
You can also declare the `Response` parameter in dependencies, and set the status code in them. But have in mind that the last one to be set will win.
|
||||
You 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.
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ Then set Cookies in it, and then return it:
|
|||
```
|
||||
|
||||
!!! tip
|
||||
Have in mind that if you return a response directly instead of using the `Response` parameter, FastAPI will return it directly.
|
||||
Keep in mind that if you return a response directly instead of using the `Response` parameter, FastAPI will return it directly.
|
||||
|
||||
So, 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`.
|
||||
|
||||
|
|
|
|||
|
|
@ -37,6 +37,6 @@ Create a response as described in [Return a Response Directly](response-directly
|
|||
|
||||
## Custom Headers
|
||||
|
||||
Have in mind that custom proprietary headers can be added <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" class="external-link" target="_blank">using the 'X-' prefix</a>.
|
||||
Keep in mind that custom proprietary headers can be added <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" class="external-link" target="_blank">using the 'X-' prefix</a>.
|
||||
|
||||
But 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){.internal-link target=_blank}), using the parameter `expose_headers` documented in <a href="https://www.starlette.io/middleware/#corsmiddleware" class="external-link" target="_blank">Starlette's CORS docs</a>.
|
||||
|
|
|
|||
|
|
@ -212,7 +212,7 @@ Client #1596980209979 left the chat
|
|||
!!! tip
|
||||
The app above is a minimal and simple example to demonstrate how to handle and broadcast messages to several WebSocket connections.
|
||||
|
||||
But have 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.
|
||||
But 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.
|
||||
|
||||
If you need something easy to integrate with FastAPI but that is more robust, supported by Redis, PostgreSQL or others, check <a href="https://github.com/encode/broadcaster" class="external-link" target="_blank">encode/broadcaster</a>.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" class="external-link" target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
|
||||
|
||||
But when checking benchmarks and comparisons you should have the following in mind.
|
||||
But when checking benchmarks and comparisons you should keep the following in mind.
|
||||
|
||||
## Benchmarks and speed
|
||||
|
||||
|
|
|
|||
|
|
@ -258,7 +258,7 @@ And you will have to make sure that it's a single process running those previous
|
|||
Of 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.
|
||||
|
||||
!!! tip
|
||||
Also, have in mind that depending on your setup, in some cases you **might not even need any previous steps** before starting your application.
|
||||
Also, keep in mind that depending on your setup, in some cases you **might not even need any previous steps** before starting your application.
|
||||
|
||||
In that case, you wouldn't have to worry about any of this. 🤷
|
||||
|
||||
|
|
@ -297,7 +297,7 @@ You can use simple tools like `htop` to see the CPU and RAM used in your server
|
|||
|
||||
## Recap
|
||||
|
||||
You have been reading here some of the main concepts that you would probably need to have in mind when deciding how to deploy your application:
|
||||
You 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:
|
||||
|
||||
* Security - HTTPS
|
||||
* Running on startup
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ But it is way more complex than that.
|
|||
|
||||
To **learn the basics of HTTPS**, from a consumer perspective, check <a href="https://howhttps.works/" class="external-link" target="_blank">https://howhttps.works/</a>.
|
||||
|
||||
Now, from a **developer's perspective**, here are several things to have in mind while thinking about HTTPS:
|
||||
Now, from a **developer's perspective**, here are several things to keep in mind while thinking about HTTPS:
|
||||
|
||||
* For HTTPS, **the server** needs to **have "certificates"** generated by a **third party**.
|
||||
* Those certificates are actually **acquired** from the third party, not "generated".
|
||||
|
|
|
|||
|
|
@ -16,6 +16,6 @@ There are several ways to do it depending on your specific use case and the tool
|
|||
|
||||
You 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.
|
||||
|
||||
I will show you some of the main concepts you should probably have in mind when deploying a **FastAPI** application (although most of it applies to any other type of web application).
|
||||
I 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).
|
||||
|
||||
You will see more details to have in mind and some of the techniques to do it in the next sections. ✨
|
||||
You will see more details to keep in mind and some of the techniques to do it in the next sections. ✨
|
||||
|
|
|
|||
|
|
@ -10,11 +10,11 @@ There are 3 main alternatives:
|
|||
|
||||
## Server Machine and Server Program
|
||||
|
||||
There's a small detail about names to have in mind. 💡
|
||||
There's a small detail about names to keep in mind. 💡
|
||||
|
||||
The word "**server**" is commonly used to refer to both the remote/cloud computer (the physical or virtual machine) and also the program that is running on that machine (e.g. Uvicorn).
|
||||
|
||||
Just have that in mind when you read "server" in general, it could refer to one of those two things.
|
||||
Just keep in mind that when you read "server" in general, it could refer to one of those two things.
|
||||
|
||||
When referring to the remote machine, it's common to call it **server**, but also **machine**, **VM** (virtual machine), **node**. Those all refer to some type of remote machine, normally running Linux, where you run programs.
|
||||
|
||||
|
|
|
|||
|
|
@ -106,7 +106,7 @@ In many cases they will only copy a fragment of the code, but that's not enough
|
|||
|
||||
* You can ask them to provide a <a href="https://stackoverflow.com/help/minimal-reproducible-example" class="external-link" target="_blank">minimal, reproducible, example</a>, that you can **copy-paste** and run locally to see the same error or behavior they are seeing, or to understand their use case better.
|
||||
|
||||
* If you are feeling too generous, you can try to **create an example** like that yourself, just based on the description of the problem. Just have in mind that this might take a lot of time and it might be better to ask them to clarify the problem first.
|
||||
* If you are feeling too generous, you can try to **create an example** like that yourself, just based on the description of the problem. Just keep in mind that this might take a lot of time and it might be better to ask them to clarify the problem first.
|
||||
|
||||
### Suggest solutions
|
||||
|
||||
|
|
@ -148,7 +148,7 @@ Again, please try your best to be kind. 🤗
|
|||
|
||||
---
|
||||
|
||||
Here's what to have in mind and how to review a pull request:
|
||||
Here's what to keep in mind and how to review a pull request:
|
||||
|
||||
### Understand the problem
|
||||
|
||||
|
|
@ -233,7 +233,7 @@ Join the 👥 <a href="https://discord.gg/VQjSZaeJmf" class="external-link" targ
|
|||
|
||||
### Don't use the chat for questions
|
||||
|
||||
Have in mind that as chats allow more "free conversation", it's easy to ask questions that are too general and more difficult to answer, so, you might not receive answers.
|
||||
Keep in mind that as chats allow more "free conversation", it's easy to ask questions that are too general and more difficult to answer, so, you might not receive answers.
|
||||
|
||||
In GitHub, the template will guide you to write the right question so that you can more easily get a good answer, or even solve the problem yourself even before asking. And in GitHub I can make sure I always answer everything, even if it takes some time. I can't personally do that with the chat systems. 😅
|
||||
|
||||
|
|
|
|||
|
|
@ -75,7 +75,7 @@ Let's first check all the normal Peewee code, create a Peewee database:
|
|||
```
|
||||
|
||||
!!! tip
|
||||
Have in mind that if you wanted to use a different database, like PostgreSQL, you couldn't just change the string. You would need to use a different Peewee database class.
|
||||
Keep in mind that if you wanted to use a different database, like PostgreSQL, you couldn't just change the string. You would need to use a different Peewee database class.
|
||||
|
||||
#### Note
|
||||
|
||||
|
|
@ -493,7 +493,7 @@ This means that, with Peewee's current implementation, multiple tasks could be u
|
|||
|
||||
Python 3.7 has <a href="https://docs.python.org/3/library/contextvars.html" class="external-link" target="_blank">`contextvars`</a> that can create a local variable very similar to `threading.local`, but also supporting these async features.
|
||||
|
||||
There are several things to have in mind.
|
||||
There are several things to keep in mind.
|
||||
|
||||
The `ContextVar` has to be created at the top of the module, like:
|
||||
|
||||
|
|
|
|||
|
|
@ -3379,7 +3379,7 @@ Note: all the previous parameters are still there, so it's still possible to dec
|
|||
|
||||
* Add OAuth2 redirect page for Swagger UI. This allows having delegated authentication in the Swagger UI docs. For this to work, you need to add `{your_origin}/docs/oauth2-redirect` to the allowed callbacks in your OAuth2 provider (in Auth0, Facebook, Google, etc).
|
||||
* For example, during development, it could be `http://localhost:8000/docs/oauth2-redirect`.
|
||||
* Have in mind that this callback URL is independent of whichever one is used by your frontend. You might also have another callback at `https://yourdomain.com/login/callback`.
|
||||
* Keep in mind that this callback URL is independent of whichever one is used by your frontend. You might also have another callback at `https://yourdomain.com/login/callback`.
|
||||
* This is only to allow delegated authentication in the API docs with Swagger UI.
|
||||
* PR [#198](https://github.com/tiangolo/fastapi/pull/198) by [@steinitzu](https://github.com/steinitzu).
|
||||
|
||||
|
|
|
|||
|
|
@ -361,7 +361,7 @@ In this case, you would accept any `dict` as long as it has `int` keys with `flo
|
|||
```
|
||||
|
||||
!!! tip
|
||||
Have in mind that JSON only supports `str` as keys.
|
||||
Keep in mind that JSON only supports `str` as keys.
|
||||
|
||||
But Pydantic has automatic data conversion.
|
||||
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ The middleware function receives:
|
|||
```
|
||||
|
||||
!!! tip
|
||||
Have in mind that custom proprietary headers can be added <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" class="external-link" target="_blank">using the 'X-' prefix</a>.
|
||||
Keep in mind that custom proprietary headers can be added <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" class="external-link" target="_blank">using the 'X-' prefix</a>.
|
||||
|
||||
But 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){.internal-link target=_blank}) using the parameter `expose_headers` documented in <a href="https://www.starlette.io/middleware/#corsmiddleware" class="external-link" target="_blank">Starlette's CORS docs</a>.
|
||||
|
||||
|
|
|
|||
|
|
@ -126,7 +126,7 @@ So, you can declare your function as:
|
|||
{!> ../../../docs_src/path_params_numeric_validations/tutorial002.py!}
|
||||
```
|
||||
|
||||
But have 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()`.
|
||||
But 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()`.
|
||||
|
||||
=== "Python 3.9+"
|
||||
|
||||
|
|
@ -166,7 +166,7 @@ Python won't do anything with that `*`, but it will know that all the following
|
|||
|
||||
### Better with `Annotated`
|
||||
|
||||
Have 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 `*`.
|
||||
Keep 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 `*`.
|
||||
|
||||
=== "Python 3.9+"
|
||||
|
||||
|
|
|
|||
|
|
@ -173,7 +173,7 @@ q: str | None = None
|
|||
But it declares it explicitly as being a query parameter.
|
||||
|
||||
!!! info
|
||||
Have in mind that the most important part to make a parameter optional is the part:
|
||||
Keep in mind that the most important part to make a parameter optional is the part:
|
||||
|
||||
```Python
|
||||
= None
|
||||
|
|
@ -199,7 +199,7 @@ This will validate the data, show a clear error when the data is not valid, and
|
|||
|
||||
### `Query` as the default value or in `Annotated`
|
||||
|
||||
Have in mind that when using `Query` inside of `Annotated` you cannot use the `default` parameter for `Query`.
|
||||
Keep in mind that when using `Query` inside of `Annotated` you cannot use the `default` parameter for `Query`.
|
||||
|
||||
Instead use the actual default value of the function parameter. Otherwise, it would be inconsistent.
|
||||
|
||||
|
|
@ -659,7 +659,7 @@ You can also use `list` directly instead of `List[str]` (or `list[str]` in Pytho
|
|||
```
|
||||
|
||||
!!! note
|
||||
Have in mind that in this case, FastAPI won't check the contents of the list.
|
||||
Keep in mind that in this case, FastAPI won't check the contents of the list.
|
||||
|
||||
For example, `List[int]` would check (and document) that the contents of the list are integers. But `list` alone wouldn't.
|
||||
|
||||
|
|
@ -670,7 +670,7 @@ You can add more information about the parameter.
|
|||
That information will be included in the generated OpenAPI and used by the documentation user interfaces and external tools.
|
||||
|
||||
!!! note
|
||||
Have in mind that different tools might have different levels of OpenAPI support.
|
||||
Keep in mind that different tools might have different levels of OpenAPI support.
|
||||
|
||||
Some 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -71,7 +71,7 @@ The files will be uploaded as "form data".
|
|||
|
||||
If 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`.
|
||||
|
||||
Have in mind that this means that the whole contents will be stored in memory. This will work well for small files.
|
||||
Keep in mind that this means that the whole contents will be stored in memory. This will work well for small files.
|
||||
|
||||
But there are several cases in which you might benefit from using `UploadFile`.
|
||||
|
||||
|
|
|
|||
|
|
@ -227,7 +227,7 @@ Just use any kind of model, any kind of class, any kind of database that you nee
|
|||
|
||||
## Code size
|
||||
|
||||
This example might seem verbose. Have in mind that we are mixing security, data models, utility functions and *path operations* in the same file.
|
||||
This example might seem verbose. Keep in mind that we are mixing security, data models, utility functions and *path operations* in the same file.
|
||||
|
||||
But here's the key point.
|
||||
|
||||
|
|
|
|||
|
|
@ -318,7 +318,7 @@ In those cases, several of those entities could have the same ID, let's say `foo
|
|||
|
||||
So, to avoid ID collisions, when creating the JWT token for the user, you could prefix the value of the `sub` key, e.g. with `username:`. So, in this example, the value of `sub` could have been: `username:johndoe`.
|
||||
|
||||
The important thing to have in mind is that the `sub` key should have a unique identifier across the entire application, and it should be a string.
|
||||
The important thing to keep in mind is that the `sub` key should have a unique identifier across the entire application, and it should be a string.
|
||||
|
||||
## Check it
|
||||
|
||||
|
|
|
|||
|
|
@ -301,7 +301,7 @@ while Pydantic *models* declare the types using `:`, the new type annotation syn
|
|||
name: str
|
||||
```
|
||||
|
||||
Have it in mind, so you don't get confused when using `=` and `:` with them.
|
||||
Keep these in mind, so you don't get confused when using `=` and `:` with them.
|
||||
|
||||
### Create Pydantic *models* / schemas for reading / returning
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue