Développement - Contribuer¶

Tout d'abord, vous voudrez peut-être voir les moyens de base pour aider FastAPI et obtenir de l'aide.

Développement¶

Si vous avez déjà cloné le dépôt et que vous savez que vous devez vous plonger dans le code, voici quelques directives pour mettre en place votre environnement.

Environnement virtuel avec `venv`¶

Vous pouvez créer un environnement virtuel dans un répertoire en utilisant le module venv de Python :

$ python -m venv env

Cela va créer un répertoire ./env/ avec les binaires Python et vous pourrez alors installer des paquets pour cet environnement isolé.

Activer l'environnement¶

Activez le nouvel environnement avec :

Linux, macOSWindows PowerShellWindows Bash

$ source ./env/bin/activate

$ .\env\Scripts\Activate.ps1

Ou si vous utilisez Bash pour Windows (par exemple Git Bash):

$ source ./env/Scripts/activate

Pour vérifier que cela a fonctionné, utilisez :

Linux, macOS, Windows BashWindows PowerShell

$ which pip

some/directory/fastapi/env/bin/pip

$ Get-Command pip

some/directory/fastapi/env/bin/pip

Si celui-ci montre le binaire pip à env/bin/pip, alors ça a fonctionné. 🎉

Tip

Chaque fois que vous installez un nouveau paquet avec pip sous cet environnement, activez à nouveau l'environnement.

Cela permet de s'assurer que si vous utilisez un programme terminal installé par ce paquet (comme flit), vous utilisez celui de votre environnement local et pas un autre qui pourrait être installé globalement.

Flit¶

FastAPI utilise Flit pour build, packager et publier le projet.

Après avoir activé l'environnement comme décrit ci-dessus, installez flit :

$ pip install flit

---> 100%

Réactivez maintenant l'environnement pour vous assurer que vous utilisez le "flit" que vous venez d'installer (et non un environnement global).

Et maintenant, utilisez flit pour installer les dépendances de développement :

Linux, macOSWindows

$ flit install --deps develop --symlink

---> 100%

Si vous êtes sous Windows, utilisez --pth-file au lieu de --symlink :

$ flit install --deps develop --pth-file

---> 100%

Il installera toutes les dépendances et votre FastAPI local dans votre environnement local.

Utiliser votre FastAPI local¶

Si vous créez un fichier Python qui importe et utilise FastAPI, et que vous l'exécutez avec le Python de votre environnement local, il utilisera votre code source FastAPI local.

Et si vous mettez à jour le code source local de FastAPI, tel qu'il est installé avec --symlink (ou --pth-file sous Windows), lorsque vous exécutez à nouveau ce fichier Python, il utilisera la nouvelle version de FastAPI que vous venez d'éditer.

De cette façon, vous n'avez pas à "installer" votre version locale pour pouvoir tester chaque changement.

Formatage¶

Il existe un script que vous pouvez exécuter qui formatera et nettoiera tout votre code :

$ bash scripts/format.sh

Il effectuera également un tri automatique de touts vos imports.

Pour qu'il puisse les trier correctement, vous devez avoir FastAPI installé localement dans votre environnement, avec la commande dans la section ci-dessus en utilisant --symlink (ou --pth-file sous Windows).

Formatage des imports¶

Il existe un autre script qui permet de formater touts les imports et de s'assurer que vous n'avez pas d'imports inutilisés :

$ bash scripts/format-imports.sh

Comme il exécute une commande après l'autre et modifie et inverse de nombreux fichiers, il prend un peu plus de temps à s'exécuter, il pourrait donc être plus facile d'utiliser fréquemment scripts/format.sh et scripts/format-imports.sh seulement avant de commit.

Documentation¶

Tout d'abord, assurez-vous que vous configurez votre environnement comme décrit ci-dessus, qui installera toutes les exigences.

La documentation utilise MkDocs.

Et il y a des outils/scripts supplémentaires en place pour gérer les traductions dans ./scripts/docs.py.

Tip

Vous n'avez pas besoin de voir le code dans ./scripts/docs.py, vous l'utilisez simplement dans la ligne de commande.

Toute la documentation est au format Markdown dans le répertoire ./docs/fr/.

De nombreux tutoriels comportent des blocs de code.

Dans la plupart des cas, ces blocs de code sont de véritables applications complètes qui peuvent être exécutées telles quelles.

En fait, ces blocs de code ne sont pas écrits à l'intérieur du Markdown, ce sont des fichiers Python dans le répertoire ./docs_src/.

Et ces fichiers Python sont inclus/injectés dans la documentation lors de la génération du site.

Documentation pour les tests¶

La plupart des tests sont en fait effectués par rapport aux exemples de fichiers sources dans la documentation.

Cela permet de s'assurer que :

La documentation est à jour.
Les exemples de documentation peuvent être exécutés tels quels.
La plupart des fonctionnalités sont couvertes par la documentation, assurées par la couverture des tests.

Au cours du développement local, un script build le site et vérifie les changements éventuels, puis il est rechargé en direct :

$ python ./scripts/docs.py live

<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> Start watching changes
<span style="color: green;">[INFO]</span> Start detecting changes

Il servira la documentation sur http://127.0.0.1:8008.

De cette façon, vous pouvez modifier la documentation/les fichiers sources et voir les changements en direct.

Typer CLI (facultatif)¶

Les instructions ici vous montrent comment utiliser le script à ./scripts/docs.py avec le programme python directement.

Mais vous pouvez également utiliser Typer CLI, et vous obtiendrez l'auto-complétion dans votre terminal pour les commandes après l'achèvement de l'installation.

Si vous installez Typer CLI, vous pouvez installer la complétion avec :

$ typer --install-completion

zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.

Apps et documentation en même temps¶

Si vous exécutez les exemples avec, par exemple :

$ uvicorn tutorial001:app --reload

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Comme Uvicorn utilisera par défaut le port 8000, la documentation sur le port 8008 n'entrera pas en conflit.

Traductions¶

L'aide aux traductions est TRÈS appréciée ! Et cela ne peut se faire sans l'aide de la communauté. 🌎 🚀

Voici les étapes à suivre pour aider à la traduction.

Conseils et lignes directrices¶

Vérifiez les pull requests existantes pour votre langue et ajouter des reviews demandant des changements ou les approuvant.

Tip

Vous pouvez ajouter des commentaires avec des suggestions de changement aux pull requests existantes.

Consultez les documents concernant l'ajout d'un review de pull request pour l'approuver ou demander des modifications.

Vérifiez dans issues pour voir s'il y a une personne qui coordonne les traductions pour votre langue.
Ajoutez une seule pull request par page traduite. Il sera ainsi beaucoup plus facile pour les autres de l'examiner.

Pour les langues que je ne parle pas, je vais attendre plusieurs autres reviews de la traduction avant de merge.

Vous pouvez également vérifier s'il existe des traductions pour votre langue et y ajouter une review, ce qui m'aidera à savoir si la traduction est correcte et je pourrai la fusionner.
Utilisez les mêmes exemples en Python et ne traduisez que le texte des documents. Vous n'avez pas besoin de changer quoi que ce soit pour que cela fonctionne.
Utilisez les mêmes images, noms de fichiers et liens. Vous n'avez pas besoin de changer quoi que ce soit pour que cela fonctionne.
Pour vérifier le code à 2 lettres de la langue que vous souhaitez traduire, vous pouvez utiliser le tableau Liste des codes ISO 639-1.

Langue existante¶

Disons que vous voulez traduire une page pour une langue qui a déjà des traductions pour certaines pages, comme l'espagnol.

Dans le cas de l'espagnol, le code à deux lettres est es. Ainsi, le répertoire des traductions espagnoles se trouve à l'adresse docs/es/.

Tip

La langue principale ("officielle") est l'anglais, qui se trouve à l'adresse "docs/en/".

Maintenant, lancez le serveur en live pour les documents en espagnol :

// Use the command "live" and pass the language code as a CLI argument
$ python ./scripts/docs.py live es

<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> Start watching changes
<span style="color: green;">[INFO]</span> Start detecting changes

Vous pouvez maintenant aller sur http://127.0.0.1:8008 et voir vos changements en direct.

Si vous regardez le site web FastAPI docs, vous verrez que chaque langue a toutes les pages. Mais certaines pages ne sont pas traduites et sont accompagnées d'une notification concernant la traduction manquante.

Mais si vous le gérez localement de cette manière, vous ne verrez que les pages déjà traduites.

Disons maintenant que vous voulez ajouter une traduction pour la section Features.

Copiez le fichier à :

docs/en/docs/features.md

Collez-le exactement au même endroit mais pour la langue que vous voulez traduire, par exemple :

docs/es/docs/features.md

Tip

Notez que le seul changement dans le chemin et le nom du fichier est le code de langue, qui passe de en à es.

Ouvrez maintenant le fichier de configuration de MkDocs pour l'anglais à

docs/en/docs/mkdocs.yml

Trouvez l'endroit où cette docs/features.md se trouve dans le fichier de configuration. Quelque part comme :

site_name: FastAPI
# More stuff
nav:
- FastAPI: index.md
- Languages:
  - en: /
  - es: /es/
- features.md

Ouvrez le fichier de configuration MkDocs pour la langue que vous éditez, par exemple :

docs/es/docs/mkdocs.yml

Ajoutez-le à l'endroit exact où il se trouvait pour l'anglais, par exemple :

site_name: FastAPI
# More stuff
nav:
- FastAPI: index.md
- Languages:
  - en: /
  - es: /es/
- features.md

Assurez-vous que s'il y a d'autres entrées, la nouvelle entrée avec votre traduction est exactement dans le même ordre que dans la version anglaise.

Si vous allez sur votre navigateur, vous verrez que maintenant les documents montrent votre nouvelle section. 🎉

Vous pouvez maintenant tout traduire et voir à quoi cela ressemble au fur et à mesure que vous enregistrez le fichier.

Nouvelle langue¶

Disons que vous voulez ajouter des traductions pour une langue qui n'est pas encore traduite, pas même quelques pages.

Disons que vous voulez ajouter des traductions pour le Créole, et que ce n'est pas encore dans les documents.

En vérifiant le lien ci-dessus, le code pour "Créole" est ht.

L'étape suivante consiste à exécuter le script pour générer un nouveau répertoire de traduction :

// Use the command new-lang, pass the language code as a CLI argument
$ python ./scripts/docs.py new-lang ht

Successfully initialized: docs/ht
Updating ht
Updating en

Vous pouvez maintenant vérifier dans votre éditeur de code le répertoire nouvellement créé docs/ht/.

Tip

Créez une première demande d'extraction à l'aide de cette fonction, afin de configurer la nouvelle langue avant d'ajouter des traductions.

Ainsi, d'autres personnes peuvent vous aider à rédiger d'autres pages pendant que vous travaillez sur la première. 🚀

Commencez par traduire la page principale, docs/ht/index.md.

Vous pouvez ensuite continuer avec les instructions précédentes, pour une "langue existante".

Nouvelle langue non prise en charge¶

Si, lors de l'exécution du script du serveur en direct, vous obtenez une erreur indiquant que la langue n'est pas prise en charge, quelque chose comme :

 raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: partials/language/xx.html

Cela signifie que le thème ne supporte pas cette langue (dans ce cas, avec un faux code de 2 lettres de xx).

Mais ne vous inquiétez pas, vous pouvez définir la langue du thème en anglais et ensuite traduire le contenu des documents.

Si vous avez besoin de faire cela, modifiez le fichier mkdocs.yml pour votre nouvelle langue, il aura quelque chose comme :

site_name: FastAPI
# More stuff
theme:
  # More stuff
  language: xx

Changez cette langue de xx (de votre code de langue) à fr.

Vous pouvez ensuite relancer le serveur live.

Prévisualisez le résultat¶

Lorsque vous utilisez le script à ./scripts/docs.py avec la commande live, il n'affiche que les fichiers et les traductions disponibles pour la langue courante.

Mais une fois que vous avez terminé, vous pouvez tester le tout comme il le ferait en ligne.

Pour ce faire, il faut d'abord construire tous les documents :

// Use the command "build-all", this will take a bit
$ python ./scripts/docs.py build-all

Updating es
Updating en
Building docs for: en
Building docs for: es
Successfully built docs for: es
Copying en index.md to README.md

Cela génère tous les documents à ./docs_build/ pour chaque langue. Cela inclut l'ajout de tout fichier dont la traduction est manquante, avec une note disant que "ce fichier n'a pas encore de traduction". Mais vous n'avez rien à faire avec ce répertoire.

Ensuite, il construit tous ces sites MkDocs indépendants pour chaque langue, les combine, et génère le résultat final à ./site/.

Ensuite, vous pouvez servir cela avec le commandement serve:

// Use the command "serve" after running "build-all"
$ python ./scripts/docs.py serve

Warning: this is a very simple server. For development, use mkdocs serve instead.
This is here only to preview a site with translations already built.
Make sure you run the build-all command first.
Serving at: http://127.0.0.1:8008

Tests¶

Il existe un script que vous pouvez exécuter localement pour tester tout le code et générer des rapports de couverture en HTML :

$ bash scripts/test-cov-html.sh

Cette commande génère un répertoire ./htmlcov/, si vous ouvrez le fichier ./htmlcov/index.html dans votre navigateur, vous pouvez explorer interactivement les régions de code qui sont couvertes par les tests, et remarquer s'il y a une région manquante.