Utiliser des dataclasses¶

🌐 Traduction par IA et humains

Cette traduction a été réalisée par une IA guidée par des humains. 🤝

Elle peut contenir des erreurs d'interprétation du sens original, ou paraître peu naturelle, etc. 🤖

Vous pouvez améliorer cette traduction en nous aidant à mieux guider le LLM d'IA.

FastAPI est construit au‑dessus de Pydantic, et je vous ai montré comment utiliser des modèles Pydantic pour déclarer les requêtes et les réponses.

Mais FastAPI prend aussi en charge l'utilisation de dataclasses de la même manière :

Python 3.10+

from dataclasses import dataclass

from fastapi import FastAPI


@dataclass
class Item:
    name: str
    price: float
    description: str | None = None
    tax: float | None = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item

Cela fonctionne grâce à Pydantic, qui offre une prise en charge interne des dataclasses.

Ainsi, même avec le code ci‑dessus qui n'emploie pas explicitement Pydantic, FastAPI utilise Pydantic pour convertir ces dataclasses standard en la variante de dataclasses de Pydantic.

Et bien sûr, cela prend en charge la même chose :

validation des données
sérialisation des données
documentation des données, etc.

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

Gardez à l'esprit que les dataclasses ne peuvent pas tout ce que peuvent faire les modèles Pydantic.

Vous pourriez donc avoir encore besoin d'utiliser des modèles Pydantic.

Mais si vous avez déjà un ensemble de dataclasses sous la main, c'est une astuce pratique pour les utiliser afin d'alimenter une API Web avec FastAPI. 🤓

Utiliser des dataclasses dans `response_model`¶

Vous pouvez aussi utiliser dataclasses dans le paramètre response_model :

Python 3.10+

from dataclasses import dataclass, field

from fastapi import FastAPI


@dataclass
class Item:
    name: str
    price: float
    tags: list[str] = field(default_factory=list)
    description: str | None = None
    tax: float | None = None


app = FastAPI()


@app.get("/items/next", response_model=Item)
async def read_next_item():
    return {
        "name": "Island In The Moon",
        "price": 12.99,
        "description": "A place to be playin' and havin' fun",
        "tags": ["breater"],
    }

La dataclass sera automatiquement convertie en dataclass Pydantic.

Ainsi, son schéma apparaîtra dans l'interface utilisateur de la documentation de l'API :

Utiliser des dataclasses dans des structures de données imbriquées¶

Vous pouvez aussi combiner dataclasses avec d'autres annotations de type pour créer des structures de données imbriquées.

Dans certains cas, vous devrez peut‑être encore utiliser la version dataclasses de Pydantic. Par exemple, si vous rencontrez des erreurs avec la documentation d'API générée automatiquement.

Dans ce cas, vous pouvez simplement remplacer les dataclasses standard par pydantic.dataclasses, qui est un remplacement drop‑in :

Python 3.10+

from dataclasses import field  # (1)

from fastapi import FastAPI
from pydantic.dataclasses import dataclass  # (2)


@dataclass
class Item:
    name: str
    description: str | None = None


@dataclass
class Author:
    name: str
    items: list[Item] = field(default_factory=list)  # (3)


app = FastAPI()


@app.post("/authors/{author_id}/items/", response_model=Author)  # (4)
async def create_author_items(author_id: str, items: list[Item]):  # (5)
    return {"name": author_id, "items": items}  # (6)


@app.get("/authors/", response_model=list[Author])  # (7)
def get_authors():  # (8)
    return [  # (9)
        {
            "name": "Breaters",
            "items": [
                {
                    "name": "Island In The Moon",
                    "description": "A place to be playin' and havin' fun",
                },
                {"name": "Holy Buddies"},
            ],
        },
        {
            "name": "System of an Up",
            "items": [
                {
                    "name": "Salt",
                    "description": "The kombucha mushroom people's favorite",
                },
                {"name": "Pad Thai"},
                {
                    "name": "Lonely Night",
                    "description": "The mostests lonliest nightiest of allest",
                },
            ],
        },
    ]

Nous continuons à importer field depuis les dataclasses standard.
pydantic.dataclasses est un remplacement drop‑in pour dataclasses.
La dataclass Author inclut une liste de dataclasses Item.
La dataclass Author est utilisée comme paramètre response_model.
Vous pouvez utiliser d'autres annotations de type standard avec des dataclasses comme corps de la requête.

Dans ce cas, il s'agit d'une liste de dataclasses Item.
Ici, nous renvoyons un dictionnaire qui contient items, qui est une liste de dataclasses.

FastAPI est toujours capable de sérialiser les données en JSON.
Ici, response_model utilise une annotation de type correspondant à une liste de dataclasses Author.

Là encore, vous pouvez combiner dataclasses avec des annotations de type standard.
Notez que cette fonction de chemin d'accès utilise un def classique au lieu de async def.

Comme toujours, avec FastAPI vous pouvez combiner def et async def selon vos besoins.

Si vous avez besoin d'un rappel sur quand utiliser l'un ou l'autre, consultez la section « In a hurry? » dans la documentation à propos de async et await.
Cette fonction de chemin d'accès ne renvoie pas des dataclasses (même si elle le pourrait), mais une liste de dictionnaires contenant des données internes.

FastAPI utilisera le paramètre response_model (qui inclut des dataclasses) pour convertir la réponse.

Vous pouvez combiner dataclasses avec d'autres annotations de type, selon de nombreuses combinaisons, pour former des structures de données complexes.

Reportez‑vous aux annotations dans le code ci‑dessus pour voir plus de détails spécifiques.

En savoir plus¶

Vous pouvez aussi combiner dataclasses avec d'autres modèles Pydantic, en hériter, les inclure dans vos propres modèles, etc.

Pour en savoir plus, consultez la documentation Pydantic sur les dataclasses.

Version¶

C'est disponible depuis FastAPI version 0.67.0. 🔖

Utiliser des dataclasses¶

Utiliser des dataclasses dans response_model¶

Utiliser des dataclasses dans des structures de données imbriquées¶

En savoir plus¶

Version¶

Utiliser des dataclasses dans `response_model`¶