///
-/// info
+/// note | Remarque
La clé `model` ne fait pas partie d'OpenAPI.
///
-/// info
+/// note | Remarque
Ă moins que vous ne spĂ©cifiiez explicitement un type de mĂ©dia diffĂ©rent dans votre paramĂštre `responses`, FastAPI supposera que la rĂ©ponse a le mĂȘme type de mĂ©dia que la classe de rĂ©ponse principale (par dĂ©faut `application/json`).
### DĂ©pendances avec `yield` et `scope` { #dependencies-with-yield-and-scope }
-Dans la version 0.121.0, **FastAPI** a ajouté la prise en charge de `Depends(scope="function")` pour les dépendances avec `yield`.
+Dans la version 0.121.0, FastAPI a ajouté la prise en charge de `Depends(scope="function")` pour les dépendances avec `yield`.
Avec `Depends(scope="function")`, le code dâarrĂȘt aprĂšs `yield` sâexĂ©cute immĂ©diatement aprĂšs la fin de la *fonction de chemin d'accĂšs*, avant que la rĂ©ponse ne soit renvoyĂ©e au client.
Ce comportement a Ă©tĂ© annulĂ© en 0.118.0, afin que le code dâarrĂȘt aprĂšs `yield` sâexĂ©cute aprĂšs lâenvoi de la rĂ©ponse.
-/// info
+/// note | Remarque
Comme vous le verrez ciâdessous, câest trĂšs similaire au comportement avant la version 0.106.0, mais avec plusieurs amĂ©liorations et corrections de bogues pour des cas limites.
{* ../../docs_src/custom_response/tutorial002_py310.py hl[2,7] *}
-/// info
+/// note | Remarque
Le paramÚtre `response_class` sera aussi utilisé pour définir le « media type » de la réponse.
///
-/// info
+/// note | Remarque
Bien sĂ»r, l'en-tĂȘte `Content-Type` rĂ©el, le code d'Ă©tat, etc., proviendront de l'objet `Response` que vous avez renvoyĂ©.
Cela fonctionne de la mĂȘme maniĂšre qu'avec les modĂšles Pydantic. Et, en rĂ©alitĂ©, c'est mis en Ćuvre de la mĂȘme façon en interne, en utilisant Pydantic.
-/// info
+/// note | Remarque
Gardez Ă l'esprit que les dataclasses ne peuvent pas tout ce que peuvent faire les modĂšles Pydantic.
Ici, la fonction gestionnaire de l'événement `shutdown` écrira une ligne de texte « Application shutdown » dans un fichier `log.txt`.
-/// info
+/// note | Remarque
Dans la fonction `open()`, le `mode="a"` signifie « append » (ajouter) ; la ligne sera donc ajoutée aprÚs ce qui se trouve déjà dans ce fichier, sans écraser le contenu précédent.
Sous le capot, dans la spécification technique ASGI, cela fait partie du [protocole Lifespan](https://asgi.readthedocs.io/en/latest/specs/lifespan.html), et il y définit des événements appelés `startup` et `shutdown`.
-/// info
+/// note | Remarque
Vous pouvez en lire plus sur les gestionnaires `lifespan` de Starlette dans la [documentation « Lifespan » de Starlette](https://www.starlette.dev/lifespan/).
-# Générer des SDK { #generating-sdks }
+# Générer des SDKs { #generating-sdks }
Parce que **FastAPI** est basĂ© sur la spĂ©cification **OpenAPI**, ses API peuvent ĂȘtre dĂ©crites dans un format standard compris par de nombreux outils.
Par exemple, vous pourriez essayer :
* [Stainless](https://www.stainless.com/?utm_source=fastapi&utm_medium=referral)
-* [liblab](https://developers.liblab.com/tutorials/sdk-for-fastapi?utm_source=fastapi)
Certaines de ces solutions peuvent aussi ĂȘtre open source ou proposer des niveaux gratuits, afin que vous puissiez les essayer sans engagement financier. Dâautres gĂ©nĂ©rateurs de SDK commerciaux existent et peuvent ĂȘtre trouvĂ©s en ligne. đ€
Ă ce stade, vous avez le(s) *chemin(s) d'accĂšs de callback* nĂ©cessaire(s) (celui/ceux que la *personne dĂ©veloppeuse externe* doit implĂ©menter dans lâ*API externe*) dans le routeur de callback que vous avez crĂ©Ă© ci-dessus.
-Utilisez maintenant le paramĂštre `callbacks` dans *le dĂ©corateur de chemin d'accĂšs de votre API* pour passer lâattribut `.routes` (qui est en fait juste une `list` de routes/*chemins d'accĂšs*) depuis ce routeur de callback :
+Utilisez maintenant le paramĂštre `callbacks` dans *le dĂ©corateur de chemin d'accĂšs de votre API* pour passer lâattribut `.routes` depuis ce routeur de callback :
{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[33] *}
/// tip | Astuce
-Remarquez que vous ne passez pas le routeur lui-mĂȘme (`invoices_callback_router`) Ă `callback=`, mais lâattribut `.routes`, comme dans `invoices_callback_router.routes`.
+Remarquez que vous ne passez pas le routeur lui-mĂȘme (`invoices_callback_router`) Ă `callbacks=`, mais son attribut `.routes`, comme dans `invoices_callback_router.routes`. FastAPI utilisera ces routes pour gĂ©nĂ©rer la documentation OpenAPI du callback.
///
Toute la logique de gestion des URL des webhooks et le code qui envoie effectivement ces requĂȘtes vous incombent. Vous l'implĂ©mentez comme vous le souhaitez dans votre propre code.
-## Documenter des webhooks avec FastAPI et OpenAPI { #documenting-webhooks-with-fastapi-and-openapi }
+## Documenter des webhooks avec **FastAPI** et OpenAPI { #documenting-webhooks-with-fastapi-and-openapi }
-Avec FastAPI, en utilisant OpenAPI, vous pouvez dĂ©finir les noms de ces webhooks, les types d'opĂ©rations HTTP que votre application peut envoyer (par exemple `POST`, `PUT`, etc.) et les corps des requĂȘtes que votre application enverra.
+Avec **FastAPI**, en utilisant OpenAPI, vous pouvez dĂ©finir les noms de ces webhooks, les types d'opĂ©rations HTTP que votre application peut envoyer (par exemple `POST`, `PUT`, etc.) et les **corps** des requĂȘtes que votre application enverra.
-Cela peut grandement faciliter la tĂąche de vos utilisateurs pour implĂ©menter leurs API afin de recevoir vos requĂȘtes de webhook ; ils pourront mĂȘme peut-ĂȘtre gĂ©nĂ©rer automatiquement une partie de leur propre code d'API.
+Cela peut grandement faciliter la tĂąche de vos utilisateurs pour **implĂ©menter leurs API** afin de recevoir vos requĂȘtes de **webhook** ; ils pourront mĂȘme peut-ĂȘtre gĂ©nĂ©rer automatiquement une partie de leur propre code d'API.
-/// info
+/// note | Remarque
Les webhooks sont disponibles dans OpenAPI 3.1.0 et versions ultérieures, pris en charge par FastAPI `0.99.0` et versions ultérieures.
## Créer une application avec des webhooks { #an-app-with-webhooks }
-Lorsque vous crĂ©ez une application FastAPI, il existe un attribut `webhooks` que vous pouvez utiliser pour dĂ©finir des webhooks, de la mĂȘme maniĂšre que vous dĂ©finiriez des chemins d'accĂšs, par exemple avec `@app.webhooks.post()`.
+Lorsque vous crĂ©ez une application **FastAPI**, il existe un attribut `webhooks` que vous pouvez utiliser pour dĂ©finir des webhooks, de la mĂȘme maniĂšre que vous dĂ©finiriez des chemins d'accĂšs, par exemple avec `@app.webhooks.post()`.
{* ../../docs_src/openapi_webhooks/tutorial001_py310.py hl[9:12,15:20] *}
-Les webhooks que vous définissez apparaßtront dans le schéma OpenAPI et dans l'interface de documentation automatique.
+Les webhooks que vous définissez apparaßtront dans le schéma **OpenAPI** et dans l'**interface de documentation** automatique.
-/// info
+/// note | Remarque
L'objet `app.webhooks` est en fait simplement un `APIRouter`, le mĂȘme type que vous utiliseriez pour structurer votre application en plusieurs fichiers.
Vous pouvez maintenant démarrer votre application et aller sur [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
-Vous verrez que votre documentation contient les chemins d'accÚs habituels et désormais aussi des webhooks :
+Vous verrez que votre documentation contient les *chemins d'accÚs* habituels et désormais aussi des **webhooks** :
<img src="/img/tutorial/openapi-webhooks/image01.png">
### Utiliser le nom de la fonction de chemin dâaccĂšs comme operationId { #using-the-path-operation-function-name-as-the-operationid }
-Si vous souhaitez utiliser les noms de fonction de vos API comme `operationId`, vous pouvez les parcourir tous et remplacer lâ`operation_id` de chaque chemin dâaccĂšs en utilisant leur `APIRoute.name`.
+Si vous souhaitez utiliser les noms de fonction de vos API comme `operationId`, vous pouvez passer une fonction personnalisée `generate_unique_id_function` à `FastAPI`.
-Vous devez le faire aprĂšs avoir ajoutĂ© tous vos chemins dâaccĂšs.
+Cette fonction reçoit chaque `APIRoute` et renvoie lâ`operationId` Ă utiliser pour ce chemin dâaccĂšs.
-{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py310.py hl[2, 12:21, 24] *}
-
-/// tip | Astuce
-
-Si vous appelez manuellement `app.openapi()`, vous devez mettre Ă jour les `operationId` avant cela.
-
-///
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py310.py hl[2,5:6,9] *}
/// warning | Alertes
Vous pouvez renvoyer une `Response` ou n'importe laquelle de ses sous-classes.
-/// info
+/// note | Remarque
`JSONResponse` est elle-mĂȘme une sous-classe de `Response`.
* `instagram_basic` est utilisé par Facebook / Instagram.
* `https://www.googleapis.com/auth/drive` est utilisé par Google.
-/// info
+/// note | Remarque
Dans OAuth2, un « scope » est simplement une chaßne qui déclare une permission spécifique requise.
{* ../../docs_src/security/tutorial005_an_py310.py hl[5,141,172] *}
-/// info | DĂ©tails techniques
+/// note | DĂ©tails techniques
`Security` est en rĂ©alitĂ© une sous-classe de `Depends`, et elle nâa quâun paramĂštre supplĂ©mentaire que nous verrons plus tard.
Mais si vous voulez diffuser des données binaires pures ou des chaßnes, voici comment procéder.
-/// info
+/// note | Remarque
Ajouté dans FastAPI 0.134.0.
Et dans de nombreux cas, leur lecture serait une opération bloquante (pouvant bloquer la boucle d'événements), car ils sont lus depuis le disque ou le réseau.
-/// info
+/// note | Remarque
L'exemple ci-dessus est en réalité une exception, car l'objet `io.BytesIO` est déjà en mémoire ; sa lecture ne bloquera donc rien.
Avec ce paramĂštre, les requĂȘtes sans en-tĂȘte `Content-Type` verront leur corps analysĂ© comme JSON, ce qui correspond au comportement des anciennes versions de FastAPI.
-/// info
+/// note | Remarque
Ce comportement et cette configuration ont été ajoutés dans FastAPI 0.132.0.
{* ../../docs_src/websockets_/tutorial002_an_py310.py hl[68:69,82] *}
-/// info
+/// note | Remarque
Comme il s'agit d'un WebSocket, il n'est pas vraiment logique de lever une `HTTPException`, nous levons plutĂŽt une `WebSocketException`.
## Utiliser `WSGIMiddleware` { #using-wsgimiddleware }
-/// info
+/// note | Remarque
Cela nécessite l'installation de `a2wsgi`, par exemple avec `pip install a2wsgi`.
</div>
-/// info
+/// note | Remarque
Il existe d'autres formats et outils pour définir et installer des dépendances de paquets.
Si vous avez **plusieurs conteneurs**, probablement chacun exécutant un **seul processus** (par exemple, dans un cluster **Kubernetes**), alors vous voudrez probablement avoir un **conteneur séparé** effectuant le travail des **étapes préalables** dans un seul conteneur, exécutant un seul processus, **avant** d'exécuter les conteneurs worker répliqués.
-/// info
+/// note | Remarque
Si vous utilisez Kubernetes, ce sera probablement un [Init Container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/).
# FastAPI Cloud { #fastapi-cloud }
-Vous pouvez dĂ©ployer votre application FastAPI sur [FastAPI Cloud](https://fastapicloud.com) avec une **seule commande**, allez vous inscrire sur la liste dâattente si ce nâest pas dĂ©jĂ fait. đ
-
-## Se connecter { #login }
-
-Vous devez vous assurer que vous avez dĂ©jĂ un compte **FastAPI Cloud** (nous vous avons invitĂ© depuis la liste dâattente đ).
-
-Connectez-vous ensuite :
-
-<div class="termy">
-
-```console
-$ fastapi login
-
-You are logged in to FastAPI Cloud đ
-```
-
-</div>
-
-## DĂ©ployer { #deploy }
-
-DĂ©ployez maintenant votre application, avec une **seule commande** :
+Vous pouvez dĂ©ployer votre application FastAPI sur [FastAPI Cloud](https://fastapicloud.com) avec une **seule commande**. đ
<div class="termy">
</div>
+La CLI dĂ©tecte automatiquement votre application FastAPI et la dĂ©ploie dans le cloud. Si vous nâĂȘtes pas connectĂ©, votre navigateur sâouvrira pour terminer le processus dâauthentification.
+
Câest tout ! Vous pouvez maintenant accĂ©der Ă votre application Ă cette URL. âš
## Ă propos de FastAPI Cloud { #about-fastapi-cloud }
## DĂ©ployer votre propre serveur { #deploy-your-own-server }
-Je vous expliquerai Ă©galement plus loin dans ce guide de **DĂ©ploiement** tous les dĂ©tails, afin que vous compreniez ce qui se passe, ce qui doit ĂȘtre fait, et comment dĂ©ployer des applications FastAPI par vous-mĂȘme, y compris sur vos propres serveurs. đ€
+Je vous expliquerai Ă©galement plus loin dans ce guide de **DĂ©ploiement** tous les dĂ©tails, afin que vous compreniez ce qui se passe, ce qui doit ĂȘtre fait, ou comment dĂ©ployer des applications FastAPI par vous-mĂȘme, y compris sur vos propres serveurs. đ€
* [Hypercorn](https://hypercorn.readthedocs.io/) : un serveur ASGI compatible avec HTTP/2 et Trio entre autres fonctionnalités.
* [Daphne](https://github.com/django/daphne) : le serveur ASGI conçu pour Django Channels.
* [Granian](https://github.com/emmett-framework/granian)Â : un serveur HTTP Rust pour les applications Python.
-* [NGINX Unit](https://unit.nginx.org/howto/fastapi/) : NGINX Unit est un environnement d'exécution d'applications web léger et polyvalent.
## Machine serveur et programme serveur { #server-machine-and-server-program }
Ici, je vais vous montrer comment utiliser Uvicorn avec des processus workers en utilisant la commande `fastapi` ou directement la commande `uvicorn`.
-/// info | Info
+/// note | Remarque
Si vous utilisez des conteneurs, par exemple avec Docker ou Kubernetes, je vous en dirai plus Ă ce sujet dans le prochain chapitre : [FastAPI dans des conteneurs - Docker](docker.md).
* `openapi_version` : La version de la spécification OpenAPI utilisée. Par défaut, la plus récente : `3.1.0`.
* `summary` : Un court résumé de l'API.
* `description` : La description de votre API ; elle peut inclure du markdown et sera affichée dans la documentation.
-* `routes` : Une liste de routes ; chacune correspond à un *chemin d'accÚs* enregistré. Elles sont extraites de `app.routes`.
+* `routes` : Les routes de l'application, extraites de `app.routes`. FastAPI les utilise pour collecter les *chemins d'accÚs* enregistrés, y compris ceux provenant des routeurs inclus.
-/// info
+/// tip | DĂ©tails techniques
+
+`app.routes` est un arbre de routes de plus bas niveau. Il peut inclure des routes candidates que FastAPI utilise en interne pour les routeurs inclus, et pas uniquement des objets `APIRoute` finaux.
+
+Vous pouvez néanmoins passer `app.routes` à `get_openapi()`. FastAPI parcourra cet arbre de routes pour collecter les chemins d'accÚs effectifs.
+
+///
+
+/// note | Remarque
Le paramÚtre `summary` est disponible à partir d'OpenAPI 3.1.0, pris en charge par FastAPI 0.99.0 et versions ultérieures.
Dans ce cas, vous pouvez désactiver cette fonctionnalité dans **FastAPI**, avec le paramÚtre `separate_input_output_schemas=False`.
-/// info | info
+/// note | Remarque
La prise en charge de `separate_input_output_schemas` a Ă©tĂ© ajoutĂ©e dans FastAPI `0.102.0`. đ€
---
-« _Si quelquâun cherche Ă construire une API Python de production, je recommande vivement **FastAPI**. Il est **magnifiquement conçu**, **simple Ă utiliser** et **hautement scalable** â il est devenu un **composant clĂ©** de notre stratĂ©gie de dĂ©veloppement API-first._ »
+« _Si quelquâun cherche Ă construire une API Python de production, je recommande vivement **FastAPI**. Il est **magnifiquement conçu**, **simple Ă utiliser** et **hautement scalable**, il est devenu un **composant clĂ©** de notre stratĂ©gie de dĂ©veloppement API-first et alimente de nombreuses automatisations et services tels que notre Virtual TAC Engineer._ »
<div style="text-align: right; margin-right: 10%;">Deon Pillsbury - <strong>Cisco</strong> <a href="https://www.linkedin.com/posts/deonpillsbury_cisco-cx-python-activity-6963242628536487936-trAp/"><small>(ref)</small></a></div>
### DĂ©ployer votre application (optionnel) { #deploy-your-app-optional }
-Vous pouvez, si vous le souhaitez, dĂ©ployer votre application FastAPI sur [FastAPI Cloud](https://fastapicloud.com), allez vous inscrire sur la liste d'attente si ce n'est pas dĂ©jĂ fait. đ
-
-Si vous avez dĂ©jĂ un compte **FastAPI Cloud** (nous vous avons invitĂ© depuis la liste d'attente đ), vous pouvez dĂ©ployer votre application avec une seule commande.
+Vous pouvez, si vous le souhaitez, dĂ©ployer votre application FastAPI sur [FastAPI Cloud](https://fastapicloud.com) avec une seule commande. đ
<div class="termy">
</div>
+La CLI dĂ©tectera automatiquement votre application FastAPI et la dĂ©ploiera dans le cloud. Si vous n'ĂȘtes pas connectĂ©, votre navigateur s'ouvrira pour terminer le processus d'authentification.
+
C'est tout ! Vous pouvez maintenant accĂ©der Ă votre application Ă cette URL. âš
#### Ă propos de FastAPI Cloud { #about-fastapi-cloud }
/// note | DĂ©tails techniques
-En interne, cela créera en fait un *chemin d'accÚs* pour chaque *chemin d'accÚs* qui a été déclaré dans le `APIRouter`.
+FastAPI conserve le `APIRouter` original et ses `APIRoute` actifs lorsque le routeur est inclus dans l'application principale.
-Donc, en coulisses, cela fonctionnera comme si tout faisait partie d'une seule et mĂȘme application.
+Cela signifie que des sous-classes personnalisées de `APIRouter` et `APIRoute` peuvent toujours intervenir aprÚs l'inclusion du routeur.
///
Vous n'avez pas Ă vous soucier de la performance lors de l'inclusion de routeurs.
-Cela prendra des microsecondes et ne se produira qu'au démarrage.
+C'est conçu pour ĂȘtre lĂ©ger et pour Ă©viter d'ajouter une surcharge Ă chaque requĂȘte.
Donc cela n'affectera pas la performance. âĄ
C'est parce que nous voulons inclure leurs *chemins d'accÚs* dans le schéma OpenAPI et les interfaces utilisateur.
-Comme nous ne pouvons pas simplement les isoler et les « monter » indépendamment du reste, les *chemins d'accÚs* sont « clonés » (recréés), pas inclus directement.
+FastAPI conserve les routeurs et chemins d'accĂšs originaux actifs, et combine les prĂ©fixes de routeur, dĂ©pendances, tags, rĂ©ponses et autres mĂ©tadonnĂ©es lors du traitement des requĂȘtes et de la gĂ©nĂ©ration d'OpenAPI.
///
De cette façon, la commande `fastapi` saura oĂč trouver votre app.
-/// note | Remarque
+/// Note | Remarque
Vous pourriez aussi passer le chemin Ă la commande, comme :
router.include_router(other_router)
```
-Vous devez vous assurer de le faire avant d'inclure `router` dans l'application `FastAPI`, afin que les *chemins d'accĂšs* de `other_router` soient Ă©galement inclus.
+Vous pouvez le faire avant ou aprĂšs avoir inclus `router` dans l'application `FastAPI`. FastAPI inclura quand mĂȘme les *chemins d'accĂšs* de `other_router` dans le routage et dans OpenAPI.
+
+Il en va de mĂȘme pour les *chemins d'accĂšs* ajoutĂ©s plus tard aux routeurs. Ils seront visibles via l'inclusion antĂ©rieure Ă©galement.
+
+/// warning | DĂ©tails techniques
+
+Ăvitez de modifier directement `router.routes` aprĂšs avoir inclus un routeur. FastAPI considĂšre l'inclusion d'un routeur comme « en direct », de sorte que le routeur original et ses routes restent utilisĂ©s pour le routage et la gĂ©nĂ©ration d'OpenAPI.
+
+Utilisez les API documentées comme les décorateurs de *chemin d'accÚs* et `.include_router()` pour ajouter des routes et des routeurs.
+
+Considérez `router.routes` comme un arbre de routes de plus bas niveau pouvant contenir des définitions de routes et des routeurs inclus, et évitez de vous y fier comme à une liste plate de *chemins d'accÚs* finaux.
+
+///
{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *}
-/// info
+/// note | Remarque
`Body` possĂšde Ă©galement les mĂȘmes paramĂštres supplĂ©mentaires de validation et de mĂ©tadonnĂ©es que `Query`, `Path` et d'autres que vous verrez plus tard.
Mais si vous voulez qu'il attende un JSON avec une clĂ© `item` contenant le contenu du modĂšle, comme lorsqu'on dĂ©clare des paramĂštres supplĂ©mentaires du corps de la requĂȘte, vous pouvez utiliser le paramĂštre spĂ©cial `embed` de `Body` :
```Python
-item: Item = Body(embed=True)
+item: Annotated[Item, Body(embed=True)]
```
comme dans :
]
}
```
-/// info
+/// note | Remarque
Remarquez que la clé `images` contient maintenant une liste d'objets image.
{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *}
-/// info
+/// note | Remarque
Remarquez que `Offer` a une liste dâ`Item`, qui Ă leur tour ont une liste optionnelle dâ`Image`.
Pour dĂ©clarer un corps de **requĂȘte**, on utilise les modĂšles de [Pydantic](https://docs.pydantic.dev/) en profitant de tous leurs avantages et fonctionnalitĂ©s.
-/// info
+/// note | Remarque
Pour envoyer de la donnée, vous devez utiliser : `POST` (le plus populaire), `PUT`, `DELETE` ou `PATCH`.
<img src="/img/tutorial/cookie-param-models/image01.png">
</div>
-/// info
+/// note | Remarque
Gardez à l'esprit que, comme les **navigateurs gÚrent les cookies** de maniÚre particuliÚre et en arriÚre-plan, ils **n'autorisent pas** facilement **JavaScript** à y accéder.
///
-/// info
+/// note | Remarque
Pour dĂ©clarer des cookies, vous devez utiliser `Cookie`, sinon les paramĂštres seraient interprĂ©tĂ©s comme des paramĂštres de requĂȘte.
///
-/// info
+/// note | Remarque
Gardez à l'esprit que, comme **les navigateurs gÚrent les cookies** de maniÚre particuliÚre et en coulisses, ils **n'autorisent pas** facilement **JavaScript** à y accéder.
ne sera pas exécutée.
-/// info
+/// note | Remarque
Pour plus d'informations, consultez [la documentation officielle de Python](https://docs.python.org/3/library/__main__.html).
///
-/// info | Info
+/// note | Remarque
Dans cet exemple, nous utilisons des en-tĂȘtes personnalisĂ©s fictifs `X-Key` et `X-Token`.
end
```
-/// info
+/// note | Remarque
Une **seule réponse** sera envoyée au client. Il peut s'agir d'une des réponses d'erreur ou de la réponse provenant du *chemin d'accÚs*.
## Quâest-ce que « lâinjection de dĂ©pendances » { #what-is-dependency-injection }
-Lâ**« injection de dĂ©pendances »** signifie, en programmation, quâil existe un moyen pour votre code (dans ce cas, vos fonctions de chemins dâaccĂšs) de dĂ©clarer ce dont il a besoin pour fonctionner et utiliser : « dĂ©pendances ».
+Lâ**« injection de dĂ©pendances »** signifie, en programmation, quâil existe un moyen pour votre code (dans ce cas, vos fonctions de chemin dâaccĂšs) de dĂ©clarer ce dont il a besoin pour fonctionner et utiliser : « dĂ©pendances ».
Ensuite, ce systÚme (dans ce cas **FastAPI**) se charge de faire tout le nécessaire pour fournir à votre code ces dépendances requises (« injecter » les dépendances).
**2 lignes**.
-Et elle a la mĂȘme forme et structure que toutes vos fonctions de chemins dâaccĂšs.
+Et elle a la mĂȘme forme et structure que toutes vos fonctions de chemin dâaccĂšs.
Vous pouvez la considĂ©rer comme une fonction de chemin dâaccĂšs sans le « dĂ©corateur » (sans le `@app.get("/some-path")`).
Puis elle retourne simplement un `dict` contenant ces valeurs.
-/// info
+/// note | Remarque
FastAPI a ajouté la prise en charge de `Annotated` (et a commencé à le recommander) dans la version 0.95.0.
Vous ne lâappelez pas directement (nâajoutez pas de parenthĂšses Ă la fin), vous le passez simplement en paramĂštre Ă `Depends()`.
-Et cette fonction prend des paramĂštres de la mĂȘme maniĂšre que les fonctions de chemins dâaccĂšs.
+Et cette fonction prend des paramĂštres de la mĂȘme maniĂšre que les fonctions de chemin dâaccĂšs.
/// tip | Astuce
De cette façon vous Ă©crivez le code partagĂ© une seule fois et **FastAPI** se charge de lâappeler pour vos chemins dâaccĂšs.
-/// check | VĂ©rifications
+/// tip | Astuce
Notez que vous nâavez pas Ă crĂ©er une classe spĂ©ciale et Ă la passer quelque part Ă **FastAPI** pour lâ« enregistrer » ou quoi que ce soit de similaire.
## Utiliser `async` ou non { #to-async-or-not-to-async }
-Comme les dĂ©pendances seront aussi appelĂ©es par **FastAPI** (tout comme vos fonctions de chemins dâaccĂšs), les mĂȘmes rĂšgles sâappliquent lors de la dĂ©finition de vos fonctions.
+Comme les dĂ©pendances seront aussi appelĂ©es par **FastAPI** (tout comme vos fonctions de chemin dâaccĂšs), les mĂȘmes rĂšgles sâappliquent lors de la dĂ©finition de vos fonctions.
Vous pouvez utiliser `async def` ou un `def` normal.
-Et vous pouvez dĂ©clarer des dĂ©pendances avec `async def` Ă lâintĂ©rieur de fonctions de chemins dâaccĂšs `def` normales, ou des dĂ©pendances `def` Ă lâintĂ©rieur de fonctions de chemins dâaccĂšs `async def`, etc.
+Et vous pouvez dĂ©clarer des dĂ©pendances avec `async def` Ă lâintĂ©rieur de fonctions de chemin dâaccĂšs `def` normales, ou des dĂ©pendances `def` Ă lâintĂ©rieur de fonctions de chemin dâaccĂšs `async def`, etc.
Peu importe. **FastAPI** saura quoi faire.
## Utilisation simple { #simple-usage }
-Si vous y regardez de prĂšs, les fonctions de chemins dâaccĂšs sont dĂ©clarĂ©es pour ĂȘtre utilisĂ©es chaque fois quâun « chemin » et une « opĂ©ration » correspondent, puis **FastAPI** se charge dâappeler la fonction avec les bons paramĂštres, en extrayant les donnĂ©es de la requĂȘte.
+Si vous y regardez de prĂšs, les fonctions de chemin dâaccĂšs sont dĂ©clarĂ©es pour ĂȘtre utilisĂ©es chaque fois quâun « chemin » et une « opĂ©ration » correspondent, puis **FastAPI** se charge dâappeler la fonction avec les bons paramĂštres, en extrayant les donnĂ©es de la requĂȘte.
En réalité, tous (ou la plupart) des frameworks web fonctionnent de cette maniÚre.
## Plug-ins **FastAPI** { #fastapi-plug-ins }
-Les intĂ©grations et « plug-ins » peuvent ĂȘtre construits en utilisant le systĂšme dâ**injection de dĂ©pendances**. Mais en rĂ©alitĂ©, il nây a **pas besoin de crĂ©er des « plug-ins »**, car en utilisant des dĂ©pendances il est possible de dĂ©clarer un nombre infini dâintĂ©grations et dâinteractions qui deviennent disponibles pour vos fonctions de chemins dâaccĂšs.
+Les intĂ©grations et « plug-ins » peuvent ĂȘtre construits en utilisant le systĂšme dâ**injection de dĂ©pendances**. Mais en rĂ©alitĂ©, il nây a **pas besoin de crĂ©er des « plug-ins »**, car en utilisant des dĂ©pendances il est possible de dĂ©clarer un nombre infini dâintĂ©grations et dâinteractions qui deviennent disponibles pour vos fonctions de chemin dâaccĂšs.
Et les dĂ©pendances peuvent ĂȘtre crĂ©Ă©es de maniĂšre trĂšs simple et intuitive, ce qui vous permet dâimporter juste les packages Python dont vous avez besoin, et de les intĂ©grer Ă vos fonctions dâAPI en quelques lignes de code, *littĂ©ralement*.
# Sous-dépendances { #sub-dependencies }
-Vous pouvez créer des dépendances qui ont des sous-dépendances.
+Vous pouvez créer des dépendances qui ont des **sous-dépendances**.
-Elles peuvent ĂȘtre aussi profondes que nĂ©cessaire.
+Elles peuvent ĂȘtre aussi **profondes** que nĂ©cessaire.
**FastAPI** se chargera de les résoudre.
{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[23] *}
-/// info
+/// note | Remarque
Notez que nous ne déclarons qu'une seule dépendance dans la *fonction de chemin d'accÚs*, `query_or_cookie_extractor`.
from backend.main import app
```
-### `fastapi dev` avec un chemin { #fastapi-dev-with-path }
+### `fastapi dev` avec un chemin ou avec lâoption CLI `--entrypoint` { #fastapi-dev-with-path-or-with-entrypoint-cli-option }
Vous pouvez Ă©galement passer le chemin du fichier Ă la commande `fastapi dev`, et elle devinera lâobjet dâapplication FastAPI Ă utiliserâŻ:
$ fastapi dev main.py
```
-Mais vous devrez vous souvenir de passer le chemin correct à chaque exécution de la commande `fastapi`.
-
-De plus, dâautres outils pourraient ne pas ĂȘtre capables de le trouver, par exemple lâ[Extension VS Code](../editor-support.md) ou [FastAPI Cloud](https://fastapicloud.com), il est donc recommandĂ© dâutiliser le `entrypoint` dans `pyproject.toml`.
-
-### DĂ©ployer votre application (optionnel) { #deploy-your-app-optional }
-
-Vous pouvez, si vous le souhaitez, dĂ©ployer votre application FastAPI sur [FastAPI Cloud](https://fastapicloud.com), allez rejoindre la liste dâattente si ce nâest pas dĂ©jĂ fait. đ
-
-Si vous avez dĂ©jĂ un compte **FastAPI Cloud** (nous vous avons invitĂ© depuis la liste dâattente đ), vous pouvez dĂ©ployer votre application avec une seule commande.
-
-Avant de dĂ©ployer, vous devez vous assurer que vous ĂȘtes connectĂ© :
-
-<div class="termy">
+Ou bien, vous pouvez aussi passer lâoption `--entrypoint` Ă la commande `fastapi dev`âŻ:
```console
-$ fastapi login
-
-You are logged in to FastAPI Cloud đ
+$ fastapi dev --entrypoint main:app
```
-</div>
+Mais vous devrez vous souvenir de passer le chemin\entrypoint correct à chaque exécution de la commande `fastapi`.
+
+De plus, dâautres outils pourraient ne pas ĂȘtre capables de le trouver, par exemple lâ[Extension VS Code](../editor-support.md) ou [FastAPI Cloud](https://fastapicloud.com), il est donc recommandĂ© dâutiliser le `entrypoint` dans `pyproject.toml`.
-Puis déployez votre application :
+### DĂ©ployer votre application (optionnel) { #deploy-your-app-optional }
+
+Vous pouvez Ă©ventuellement dĂ©ployer votre application FastAPI sur [FastAPI Cloud](https://fastapicloud.com) avec une seule commande. đ
<div class="termy">
</div>
+Le CLI dĂ©tectera automatiquement votre application FastAPI et la dĂ©ploiera dans le cloud. Si vous nâĂȘtes pas connectĂ©, votre navigateur sâouvrira pour terminer le processus dâauthentification.
+
Câest tout ! Vous pouvez maintenant accĂ©der Ă votre application Ă cette URL. âš
## RĂ©capitulatif, Ă©tape par Ă©tape { #recap-step-by-step }
/items/foo
```
-/// info
+/// note | Remarque
Un « chemin » est aussi couramment appelé « endpoint » ou « route ».
* le chemin `/`
* en utilisant une <dfn title="une méthode HTTP GET"><code>get</code> opération</dfn>
-/// info | `@decorator` Info
+/// note | Informations sur `@decorator`
Cette syntaxe `@something` en Python est appelée un « décorateur ».
{* ../../docs_src/metadata/tutorial004_py310.py hl[21,26] *}
-/// info
+/// note | Remarque
En savoir plus sur les tags dans [Configuration de chemins d'accĂšs](path-operation-configuration.md#tags).
{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[18] *}
-/// info
+/// note | Remarque
Notez que `response_description` se réfÚre spécifiquement à la réponse, tandis que `description` se réfÚre au *chemin d'accÚs* en général.
///
-/// check | VĂ©rifications
+/// tip | Astuce
OpenAPI spécifie que chaque *chemin d'accÚs* requiert une description de réponse.
{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
-/// info
+/// note | Remarque
FastAPI a ajouté le support pour `Annotated` (et a commencé à le recommander) dans la version 0.95.0.
* `lt` : `l`ess `t`han
* `le` : `l`ess than or `e`qual
-/// info
+/// note | Remarque
`Query`, `Path`, et d'autres classes que vous verrez plus tard sont des sous-classes d'une classe commune `Param`.
Ici, `item_id` est déclaré comme `int`.
-/// check | VĂ©rifications
+/// tip | Astuce
Cela vous apporte la prise en charge par l'éditeur dans votre fonction, avec vérifications d'erreurs, autocomplétion, etc.
{"item_id":3}
```
-/// check | VĂ©rifications
+/// tip | Astuce
Remarquez que la valeur reçue par votre fonction (et renvoyée) est `3`, en tant qu'entier (`int`) Python, pas la chaßne de caractÚres « 3 ».
La mĂȘme erreur apparaĂźtrait si vous fournissiez un `float` au lieu d'un `int`, comme ici : [http://127.0.0.1:8000/items/4.2](http://127.0.0.1:8000/items/4.2)
-/// check | VĂ©rifications
+/// tip | Astuce
Ainsi, avec la mĂȘme dĂ©claration de type Python, **FastAPI** vous fournit la validation de donnĂ©es.
<img src="/img/tutorial/path-params/image01.png">
-/// check | VĂ©rifications
+/// tip | Astuce
Ă nouveau, simplement avec cette mĂȘme dĂ©claration de type Python, **FastAPI** vous fournit une documentation interactive automatique (intĂ©grant Swagger UI).
{* ../../docs_src/query_params_str_validations/tutorial002_an_py310.py hl[1,3] *}
-/// info
+/// note | Remarque
FastAPI a ajouté la prise en charge de `Annotated` (et a commencé à le recommander) dans la version 0.95.0.
{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *}
-/// info
+/// note | Remarque
Câest disponible avec Pydantic version 2 ou supĂ©rieure. đ
Dans ce cas, le paramÚtre de fonction `q` sera optionnel et vaudra `None` par défaut.
-/// check | VĂ©rifications
+/// tip | Astuce
Notez Ă©galement que **FastAPI** est suffisamment intelligent pour remarquer que le paramĂštre de chemin `item_id` est un paramĂštre de chemin et que `q` ne l'est pas, c'est donc un paramĂštre de requĂȘte.
Vous pouvez définir des fichiers à téléverser par le client en utilisant `File`.
-/// info
+/// note | Remarque
Pour recevoir des fichiers téléversés, installez d'abord [`python-multipart`](https://github.com/Kludex/python-multipart).
{* ../../docs_src/request_files/tutorial001_an_py310.py hl[9] *}
-/// info
+/// note | Remarque
`File` est une classe qui hérite directement de `Form`.
Les fichiers seront téléversés en « données de formulaire ».
-Si vous déclarez le type de votre paramÚtre de *fonction de chemin d'accÚs* comme `bytes`, **FastAPI** lira le fichier pour vous et vous recevrez le contenu sous forme de `bytes`.
+Si vous déclarez le type de votre *fonction de chemin d'accÚs* comme `bytes`, **FastAPI** lira le fichier pour vous et vous recevrez le contenu sous forme de `bytes`.
Gardez à l'esprit que cela signifie que tout le contenu sera stocké en mémoire. Cela fonctionnera bien pour de petits fichiers.
Vous pouvez utiliser des **modÚles Pydantic** pour déclarer des **champs de formulaire** dans FastAPI.
-/// info
+/// note | Remarque
Pour utiliser les formulaires, installez d'abord [`python-multipart`](https://github.com/Kludex/python-multipart).
Vous pouvez dĂ©finir des fichiers et des champs de formulaire en mĂȘme temps Ă l'aide de `File` et `Form`.
-/// info
+/// note | Remarque
Pour recevoir des fichiers téléversés et/ou des données de formulaire, installez d'abord [`python-multipart`](https://github.com/Kludex/python-multipart).
Lorsque vous devez recevoir des champs de formulaire au lieu de JSON, vous pouvez utiliser `Form`.
-/// info
+/// note | Remarque
Pour utiliser les formulaires, installez d'abord [`python-multipart`](https://github.com/Kludex/python-multipart).
-Assurez-vous de créer un [environnement virtuel](../virtual-environments.md), de l'activer, puis installez-le, par exemple :
+Vous devez créer un [environnement virtuel](../virtual-environments.md), l'activer, puis installer le paquet, par exemple :
```console
$ pip install python-multipart
Avec `Form`, vous pouvez dĂ©clarer les mĂȘmes configurations que pour `Body` (ainsi que `Query`, `Path`, `Cookie`), y compris la validation, des exemples, un alias (p. ex. `user-name` au lieu de `username`), etc.
-/// info
+/// note | Remarque
`Form` est une classe qui hérite directement de `Body`.
{* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *}
-/// info | Info
+/// note | Remarque
Pour utiliser `EmailStr`, installez d'abord [`email-validator`](https://github.com/JoshData/python-email-validator).
}
```
-/// info | Info
+/// note | Remarque
Vous pouvez Ă©galement utiliser :
Le paramÚtre `status_code` reçoit un nombre correspondant au code d'état HTTP.
-/// info
+/// note | Remarque
`status_code` peut aussi recevoir un `IntEnum`, comme le [`http.HTTPStatus`](https://docs.python.org/3/library/http.html#http.HTTPStatus) de Python.
///
-/// info
+/// note | Remarque
OpenAPI 3.1.0 (utilisé depuis FastAPI 0.99.0) a ajouté la prise en charge de `examples`, qui fait partie du standard **JSON Schema**.
* `File()`
* `Form()`
-/// info
+/// note | Remarque
Ce paramÚtre `examples` ancien et spécifique à OpenAPI est désormais `openapi_examples` depuis FastAPI `0.103.0`.
Ce nouveau champ `examples` dans JSON Schema est **juste une `list`** d'exemples, et non pas un dict avec des métadonnées supplémentaires comme dans les autres endroits d'OpenAPI (décrits ci-dessus).
-/// info
+/// note | Remarque
MĂȘme aprĂšs la sortie d'OpenAPI 3.1.0 avec cette nouvelle intĂ©gration plus simple avec JSON Schema, pendant un temps, Swagger UI, l'outil qui fournit la documentation automatique, ne prenait pas en charge OpenAPI 3.1.0 (il le fait depuis la version 5.0.0 đ).
## Exécuter { #run-it }
-/// info
+/// note | Remarque
Le package [`python-multipart`](https://github.com/Kludex/python-multipart) est installé automatiquement avec **FastAPI** lorsque vous exécutez la commande `pip install "fastapi[standard]"`.
<img src="/img/tutorial/security/image01.png">
-/// check | Bouton « Authorize » !
+/// tip | Bouton « Authorize » !
Vous avez déjà un tout nouveau bouton « Authorize ».
Dans cet exemple, nous allons utiliser **OAuth2**, avec le flux **Password**, en utilisant un token **Bearer**. Nous le faisons avec la classe `OAuth2PasswordBearer`.
-/// info
+/// note | Remarque
Un token « bearer » n'est pas la seule option.
Nous créerons bientÎt aussi le véritable chemin d'accÚs.
-/// info
+/// note | Remarque
Si vous ĂȘtes un « Pythonista » trĂšs strict, vous pourriez ne pas apprĂ©cier le style du nom de paramĂštre `tokenUrl` au lieu de `token_url`.
**FastAPI** saura qu'il peut utiliser cette dépendance pour définir un « schéma de sécurité » dans le schéma OpenAPI (et la documentation API automatique).
-/// info | DĂ©tails techniques
+/// note | DĂ©tails techniques
**FastAPI** saura qu'il peut utiliser la classe `OAuth2PasswordBearer` (déclarée dans une dépendance) pour définir le schéma de sécurité dans OpenAPI parce qu'elle hérite de `fastapi.security.oauth2.OAuth2`, qui hérite à son tour de `fastapi.security.base.SecurityBase`.
///
-/// check | VĂ©rifications
+/// tip | Astuce
La maniÚre dont ce systÚme de dépendances est conçu nous permet d'avoir différentes dépendances (différents « dependables ») qui retournent toutes un modÚle `User`.
</div>
-/// info
+/// note | Remarque
Si vous prévoyez d'utiliser des algorithmes de signature numérique comme RSA ou ECDSA, vous devez installer la dépendance de bibliothÚque de cryptographie `pyjwt[crypto]`.
Nom d'utilisateur : `johndoe`
Mot de passe : `secret`
-/// check | VĂ©rifications
+/// tip | Astuce
Remarquez qu'à aucun endroit du code le mot de passe en clair « secret » n'apparaßt, nous n'avons que la version hachée.
* `instagram_basic` est utilisé par Facebook / Instagram.
* `https://www.googleapis.com/auth/drive` est utilisé par Google.
-/// info
+/// note | Remarque
En OAuth2, un « scope » est simplement une chaßne qui déclare une permission spécifique requise.
* Un `client_id` optionnel (nous n'en avons pas besoin pour notre exemple).
* Un `client_secret` optionnel (nous n'en avons pas besoin pour notre exemple).
-/// info
+/// note | Remarque
La classe `OAuth2PasswordRequestForm` n'est pas une classe spéciale pour **FastAPI** comme l'est `OAuth2PasswordBearer`.
)
```
-/// info
+/// note | Remarque
Pour une explication plus complÚte de `**user_dict`, consultez [la documentation pour **ModÚles supplémentaires**](../extra-models.md#about-user-in-dict).
{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *}
-/// info
+/// note | Remarque
L'enâtĂȘte supplĂ©mentaire `WWW-Authenticate` avec la valeur `Bearer` que nous renvoyons ici fait Ă©galement partie de la spĂ©cification.
C'est similaire Ă [Diffuser des JSON Lines](stream-json-lines.md), mais cela utilise le format `text/event-stream`, pris en charge nativement par les navigateurs via lâAPI [`EventSource`](https://developer.mozilla.org/en-US/docs/Web/API/EventSource).
-/// info | Info
+/// note | Remarque
Ajouté dans FastAPI 0.135.0.
# Diffuser des JSON Lines { #stream-json-lines }
-Vous pouvez avoir une séquence de données que vous souhaitez envoyer en « flux » ; vous pouvez le faire avec « JSON Lines ».
+Vous pouvez avoir une séquence de données que vous souhaitez envoyer en « flux », vous pouvez le faire avec « JSON Lines ».
-/// info
+/// note | Remarque
Ajouté dans FastAPI 0.134.0.
C'est trĂšs similaire Ă un tableau JSON (Ă©quivalent d'une liste Python), mais au lieu d'ĂȘtre entourĂ© de `[]` et d'avoir des `,` entre les Ă©lĂ©ments, il y a un objet JSON par ligne, ils sont sĂ©parĂ©s par un caractĂšre de saut de ligne.
-/// info
+/// note | Remarque
Le point important est que votre application pourra produire chaque ligne à son tour, tandis que le client consomme les lignes précédentes.
## Utiliser `TestClient` { #using-testclient }
-/// info
+/// note | Remarque
Pour utiliser `TestClient`, installez dâabord [`httpx`](https://www.python-httpx.org).
Pour plus dâinformations sur la maniĂšre de transmettre des donnĂ©es au backend (en utilisant `httpx` ou le `TestClient`), consultez la [documentation HTTPX](https://www.python-httpx.org).
-/// info
+/// note | Remarque
Notez que le `TestClient` reçoit des donnĂ©es qui peuvent ĂȘtre converties en JSON, pas des modĂšles Pydantic.
projects / thirdparty / fastapi / fastapi.git / commitdiff
