Visual Studio Code

Pydantic fonctionne bien avec n'importe quel éditeur ou IDE prêt à l'emploi car il est basé sur les annotations de type Python standard.

Lors de l'utilisation de Visual Studio Code (VS Code) , certaines fonctionnalités d'édition supplémentaires sont prises en charge, comparables à celles fournies par le plugin PyCharm .

Cela signifie que vous disposerez de la saisie semi-automatique (ou «IntelliSense») et de vérifications d'erreurs pour les types et les arguments requis, même lors de la création de nouvelles instances de modèle Pydantic.

pydantic autocompletion in VS Code

Configurer VSCode¶

Pour profiter de ces fonctionnalités, vous devez vous assurer de configurer correctement VS Code, en utilisant les paramètres recommandés.

Si vous avez une configuration différente, voici un bref aperçu des étapes.

Installer Pylance¶

Vous devez utiliser l'extension Pylance pour VS Code. Il s’agit du plug-in VS Code officiel de nouvelle génération recommandé pour Python.

Pylance est installé par défaut dans le cadre de l' extension Python pour VS Code , il devrait donc probablement fonctionner. Sinon, vous pouvez vérifier qu'il est installé et activé dans votre éditeur.

Configurez votre environnement¶

Ensuite, vous devez vous assurer que votre éditeur connaît l' environnement Python (probablement un environnement virtuel) pour votre projet Python.

Ce serait l'environnement dans lequel vous avez installé Pydantic.

Configurer Pylance¶

Avec les configurations par défaut, vous bénéficierez de la prise en charge de la saisie semi-automatique, mais Pylance pourrait ne pas vérifier les erreurs de type.

Vous pouvez activer les vérifications d'erreurs de type à partir de Pylance en procédant comme suit:

Ouvrez les "Paramètres utilisateur"
Rechercher Type Checking Mode
Vous trouverez une option sous Python › Analysis: Type Checking Mode
Réglez-le sur basic ou strict (par défaut, il est off )

Type Checking Mode set to strict in VS Code

Désormais, vous obtiendrez non seulement la saisie semi-automatique lors de la création de nouvelles instances de modèle Pydantic, mais également des vérifications d'erreurs pour les arguments requis .

Required arguments error checks in VS Code

Et vous obtiendrez également des contrôles d'erreur pour les types de données non valides .

Invalid data types error checks in VS Code

!!! note "Détails techniques" Pylance est l'extension VS Code, elle est fermée, mais gratuite à utiliser. En dessous, Pylance utilise un outil open source (également de Microsoft) appelé Pyright qui fait tout le gros du travail.

You can read more about it in the [Pylance Frequently Asked Questions](https://github.com/microsoft/pylance-release/blob/main/FAQ.md#what-is-the-relationship-between-pylance-pyright-and-the-python-extension).

Configurer mypy¶

Vous souhaiterez peut-être également configurer mypy dans VS Code pour obtenir des vérifications d'erreur mypy en ligne dans votre éditeur (en alternative/en plus de Pylance).

Cela inclurait les erreurs détectées par le plugin Pydantic mypy , si vous l'avez configuré.

Pour activer mypy dans VS Code, procédez comme suit:

Ouvrez les "Paramètres utilisateur"
Recherche de Mypy Enabled
Vous trouverez une option sous Python › Linting: Mypy Enabled
Cochez la case (par défaut elle est décochée)

mypy enabled in VS Code

Trucs et astuces¶

Voici quelques trucs et astuces supplémentaires pour améliorer votre expérience de développeur lorsque vous utilisez VS Code avec Pydantic.

Erreurs strictes¶

La façon dont fonctionne cette prise en charge supplémentaire de l'éditeur est que Pylance traitera vos modèles Pydantic comme s'il s'agissait de pures dataclasses Python.

Et il affichera des vérifications strictes des erreurs de type sur les types de données transmis dans les arguments lors de la création d'une nouvelle instance de modèle Pydantic.

Dans cet exemple, vous pouvez voir qu'il montre qu'une str de '23' n'est pas un int valide pour l'argument age .

VS Code strict type errors

Il s'attendrait age=23 au lieu de age='23' .

Néanmoins, la conception, et l’une des principales caractéristiques de Pydantic, est qu’il est très indulgent avec les types de données .

Il acceptera en fait le str avec la valeur '23' et le convertira en un int avec la valeur 23 .

Ces contrôles d'erreur stricts sont très utiles la plupart du temps et peuvent vous aider à détecter de nombreux bogues à un stade précoce . Mais il y a des cas, comme avec age='23' , où ils pourraient être gênants en signalant une erreur de « faux positif ».

Cet exemple ci-dessus avec age='23' est intentionnellement simple, pour montrer l'erreur et les différences de types.

Mais les cas les plus courants où ces erreurs strictes seraient gênantes seraient lors de l'utilisation de types de données plus sophistiqués, comme les valeurs int pour les champs datetime ou les valeurs dict pour les sous-modèles Pydantic.

Par exemple, ceci est valable pour Pydantic:

from pydantic import BaseModel


class Knight(BaseModel):
    title: str
    age: int
    color: str = 'blue'


class Quest(BaseModel):
    title: str
    knight: Knight


quest = Quest(
    title='To seek the Holy Grail', knight={'title': 'Sir Lancelot', 'age': 23}
)

Le type du knight de terrain est déclaré avec la classe Knight (un modèle Pydantic) et le code transmet à la place un dict littéral. Ceci est toujours valable pour Pydantic, et le dict serait automatiquement converti en instance Knight .

Néanmoins, cela serait détecté comme une erreur de type:

VS Code strict type errors with model

Dans ces cas-là, il existe plusieurs façons de désactiver ou d’ignorer les erreurs strictes à des endroits très spécifiques, tout en les préservant dans le reste du code.

Voici ci-dessous plusieurs techniques pour y parvenir.

Désactiver les vérifications de type dans une ligne¶

Vous pouvez désactiver les erreurs pour une ligne spécifique en utilisant un commentaire de:

# type: ignore

ou (pour être spécifique à pylance/pyright):

# pyright: ignore

( pyright est le serveur de langue utilisé par Pylance.).

en revenant à l'exemple avec age='23' , ce serait:

from pydantic import BaseModel


class Knight(BaseModel):
    title: str
    age: int
    color: str = 'blue'


lancelot = Knight(title='Sir Lancelot', age='23')  # pyright: ignore

de cette façon, Pylance et mypy ignoreront les erreurs dans cette ligne.

Avantages : c'est un simple changement dans cette ligne pour y supprimer les erreurs.

Inconvénients: toute autre erreur dans cette ligne sera également omise, y compris les vérifications de type, les arguments mal orthographiés, les arguments requis non fournis, etc.

Remplacer le type d'une variable¶

Vous pouvez également créer une variable avec la valeur que vous souhaitez utiliser et déclarer explicitement son type avec Any .

from typing import Any

from pydantic import BaseModel


class Knight(BaseModel):
    title: str
    age: int
    color: str = 'blue'


age_str: Any = '23'
lancelot = Knight(title='Sir Lancelot', age=age_str)

de cette façon, Pylance et mypy interpréteront la variable age_str comme s'ils ne connaissaient pas son type, au lieu de savoir qu'elle a un type de str alors qu'un int était attendu (et d'afficher ensuite l'erreur correspondante).

Avantages : les erreurs seront ignorées uniquement pour une valeur spécifique, et vous verrez toujours les erreurs supplémentaires pour les autres arguments.

Inconvénients : cela nécessite d'importer Any et une nouvelle variable dans une nouvelle ligne pour chaque argument qui doit ignorer les erreurs.

Remplacer le type d'une valeur avec `cast`¶

La même idée de l’exemple précédent peut être mise sur la même ligne à l’aide de cast() .

De cette façon, la déclaration de type de la valeur est remplacée en ligne, sans nécessiter une autre variable.

from typing import Any, cast

from pydantic import BaseModel


class Knight(BaseModel):
    title: str
    age: int
    color: str = 'blue'


lancelot = Knight(title='Sir Lancelot', age=cast(Any, '23'))

cast(Any, '23') n'affecte pas la valeur, c'est toujours juste '23' , mais maintenant Pylance et mypy supposeront qu'il est de type Any , ce qui signifie qu'ils agiront comme s'ils ne connaissaient pas le type de la valeur.

C'est donc l'équivalent de l'exemple précédent, sans la variable supplémentaire.

Avantages : les erreurs seront ignorées uniquement pour une valeur spécifique, et vous verrez toujours les erreurs supplémentaires pour les autres arguments. Il n'y a pas besoin de variables supplémentaires.

Inconvénients : cela nécessite d'importer Any et cast , et si vous n'êtes pas habitué à utiliser cast() , cela peut paraître étrange au début.

Configuration dans les arguments de classe¶

Pydantic dispose d'un riche ensemble de Configurations de modèles disponibles.

Ces configurations peuvent être définies dans une class Config sur chaque modèle:

from pydantic import BaseModel


class Knight(BaseModel):
    model_config = dict(frozen=True)
    title: str
    age: int
    color: str = 'blue'

ou passé comme arguments de mot-clé lors de la définition de la classe de modèle:

from pydantic import BaseModel


class Knight(BaseModel, frozen=True):
    title: str
    age: int
    color: str = 'blue'

La configuration spécifique frozen (en bêta) a une signification particulière.

Cela empêche tout autre code de modifier une instance de modèle une fois celle-ci créée, la gardant ainsi "gelée" .

Lorsque vous utilisez la deuxième version pour déclarer frozen=True (avec des arguments de mot-clé dans la définition de classe), Pylance peut l'utiliser pour vous aider à archiver votre code et à détecter les erreurs lorsque quelque chose tente de définir des valeurs dans un modèle "gelé".

VS Code strict type errors with model

Ajout d'une valeur par défaut avec `Field`¶

Pylance/pyright nécessite que default soit un argument de mot-clé pour Field afin de déduire que le champ est facultatif.

from pydantic import BaseModel, Field


class Knight(BaseModel):
    title: str = Field(default='Sir Lancelot')  # this is okay
    age: int = Field(
        23
    )  # this works fine at runtime but will case an error for pyright


lance = Knight()  # error: Argument missing for parameter "age"

Il s'agit d'une limitation des transformations de classe de données et ne peut pas être corrigée dans pydantic.

Détails techniques¶

!!! avertissement En tant qu'utilisateur de Pydantic, vous n'avez pas besoin des détails ci-dessous. N'hésitez pas à ignorer le reste de cette section.

These details are only useful for other library authors, etc.

Cette prise en charge supplémentaire de l'éditeur fonctionne en implémentant le projet de norme proposé pour Dataclass Transform (PEP 681) .

Le projet de norme proposé est rédigé par Eric Traut, de l'équipe Microsoft, le même auteur du package open source Pyright (utilisé par Pylance pour fournir le support Python dans VS Code).

L'intention de la norme est de fournir un moyen aux bibliothèques comme Pydantic et d'autres d'indiquer aux éditeurs et aux outils qu'ils (les éditeurs) doivent traiter ces bibliothèques (par exemple Pydantic) comme s'il s'agissait dataclasses , en fournissant l'auto-complétion, les vérifications de type, etc.

Le projet de norme comprend également un formulaire alternatif pour les premiers utilisateurs, comme Pydantic, afin d'ajouter immédiatement une prise en charge, avant même que le nouveau projet de norme ne soit terminé et approuvé.

Ce nouveau projet de norme, avec la forme alternative, est déjà pris en charge par Pyright, il peut donc être utilisé via Pylance dans VS Code.

Comme il est proposé comme standard officiel pour Python, d’autres éditeurs peuvent également facilement en ajouter la prise en charge.

Et les auteurs d'autres bibliothèques similaires à Pydantic peuvent également facilement adopter la norme immédiatement (en utilisant la « forme alternative ») et bénéficier des avantages de ces fonctionnalités d'éditeur supplémentaires.

本文总阅读量次