Zum Inhalt

Von Pydantic v1 zu Pydantic v2 migrieren

Wenn Sie eine Àltere FastAPI-App haben, nutzen Sie möglicherweise Pydantic Version 1.

FastAPI Version 0.100.0 unterstĂŒtzte sowohl Pydantic v1 als auch v2. Es verwendete, was auch immer Sie installiert hatten.

FastAPI Version 0.119.0 fĂŒhrte eine teilweise UnterstĂŒtzung fĂŒr Pydantic v1 innerhalb von Pydantic v2 (als pydantic.v1) ein, um die Migration zu v2 zu erleichtern.

FastAPI 0.126.0 entfernte die UnterstĂŒtzung fĂŒr Pydantic v1, wĂ€hrend pydantic.v1 noch eine Weile unterstĂŒtzt wurde.

Achtung

Das Pydantic-Team hat die UnterstĂŒtzung fĂŒr Pydantic v1 in den neuesten Python-Versionen eingestellt, beginnend mit Python 3.14.

Dies schließt pydantic.v1 ein, das unter Python 3.14 und höher nicht mehr unterstĂŒtzt wird.

Wenn Sie die neuesten Features von Python nutzen möchten, mĂŒssen Sie sicherstellen, dass Sie Pydantic v2 verwenden.

Wenn Sie eine Àltere FastAPI-App mit Pydantic v1 haben, zeige ich Ihnen hier, wie Sie sie zu Pydantic v2 migrieren, und die Features in FastAPI 0.119.0, die Ihnen bei einer schrittweisen Migration helfen.

Offizieller Leitfaden

Pydantic hat einen offiziellen Migrationsleitfaden von v1 zu v2.

Er enthÀlt auch, was sich geÀndert hat, wie Validierungen nun korrekter und strikter sind, mögliche Stolpersteine, usw.

Sie können ihn lesen, um besser zu verstehen, was sich geÀndert hat.

Tests

Stellen Sie sicher, dass Sie Tests fĂŒr Ihre App haben und diese in Continuous Integration (CI) ausfĂŒhren.

Auf diese Weise können Sie das Update durchfĂŒhren und sicherstellen, dass weiterhin alles wie erwartet funktioniert.

bump-pydantic

In vielen FĂ€llen, wenn Sie regulĂ€re Pydantic-Modelle ohne Anpassungen verwenden, können Sie den Großteil des Prozesses der Migration von Pydantic v1 auf Pydantic v2 automatisieren.

Sie können bump-pydantic vom selben Pydantic-Team verwenden.

Dieses Tool hilft Ihnen, den Großteil des zu Ă€ndernden Codes automatisch anzupassen.

Danach können Sie die Tests ausfĂŒhren und prĂŒfen, ob alles funktioniert. Falls ja, sind Sie fertig. 😎

Pydantic v1 in v2

Pydantic v2 enthĂ€lt alles aus Pydantic v1 als Untermodul pydantic.v1. Dies wird aber in Versionen oberhalb von Python 3.13 nicht mehr unterstĂŒtzt.

Das bedeutet, Sie können die neueste Version von Pydantic v2 installieren und die alten Pydantic‑v1‑Komponenten aus diesem Untermodul importieren und verwenden, als hĂ€tten Sie das alte Pydantic v1 installiert.

from pydantic.v1 import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    size: float
đŸ€“ Other versions and variants 
from typing import Union

from pydantic.v1 import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    size: float

FastAPI-UnterstĂŒtzung fĂŒr Pydantic v1 in v2

Seit FastAPI 0.119.0 gibt es außerdem eine teilweise UnterstĂŒtzung fĂŒr Pydantic v1 innerhalb von Pydantic v2, um die Migration auf v2 zu erleichtern.

Sie könnten also Pydantic auf die neueste Version 2 aktualisieren und die Importe so Ă€ndern, dass das Untermodul pydantic.v1 verwendet wird, und in vielen FĂ€llen wĂŒrde es einfach funktionieren.

from fastapi import FastAPI
from pydantic.v1 import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    size: float


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item) -> Item:
    return item
đŸ€“ Other versions and variants 
from typing import Union

from fastapi import FastAPI
from pydantic.v1 import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    size: float


app = FastAPI()


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

Achtung

Beachten Sie, dass, da das Pydantic‑Team Pydantic v1 in neueren Python‑Versionen nicht mehr unterstĂŒtzt, beginnend mit Python 3.14, auch die Verwendung von pydantic.v1 unter Python 3.14 und höher nicht unterstĂŒtzt wird.

Pydantic v1 und v2 in derselben App

Es wird von Pydantic nicht unterstĂŒtzt, dass ein Pydantic‑v2‑Modell Felder hat, die als Pydantic‑v1‑Modelle definiert sind, und umgekehrt.

graph TB
    subgraph "❌ Nicht unterstĂŒtzt"
        direction TB
        subgraph V2["Pydantic-v2-Modell"]
            V1Field["Pydantic-v1-Modell"]
        end
        subgraph V1["Pydantic-v1-Modell"]
            V2Field["Pydantic-v2-Modell"]
        end
    end

    style V2 fill:#f9fff3
    style V1 fill:#fff6f0
    style V1Field fill:#fff6f0
    style V2Field fill:#f9fff3

... aber Sie können getrennte Modelle, die Pydantic v1 bzw. v2 nutzen, in derselben App verwenden.

graph TB
    subgraph "✅ UnterstĂŒtzt"
        direction TB
        subgraph V2["Pydantic-v2-Modell"]
            V2Field["Pydantic-v2-Modell"]
        end
        subgraph V1["Pydantic-v1-Modell"]
            V1Field["Pydantic-v1-Modell"]
        end
    end

    style V2 fill:#f9fff3
    style V1 fill:#fff6f0
    style V1Field fill:#fff6f0
    style V2Field fill:#f9fff3

In einigen FĂ€llen ist es sogar möglich, sowohl Pydantic‑v1‑ als auch Pydantic‑v2‑Modelle in derselben Pfadoperation Ihrer FastAPI‑App zu verwenden:

from fastapi import FastAPI
from pydantic import BaseModel as BaseModelV2
from pydantic.v1 import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    size: float


class ItemV2(BaseModelV2):
    name: str
    description: str | None = None
    size: float


app = FastAPI()


@app.post("/items/", response_model=ItemV2)
async def create_item(item: Item):
    return item
đŸ€“ Other versions and variants 
from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel as BaseModelV2
from pydantic.v1 import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    size: float


class ItemV2(BaseModelV2):
    name: str
    description: Union[str, None] = None
    size: float


app = FastAPI()


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

Im obigen Beispiel ist das Eingabemodell ein Pydantic‑v1‑Modell, und das Ausgabemodell (definiert in response_model=ItemV2) ist ein Pydantic‑v2‑Modell.

Pydantic v1 Parameter

Wenn Sie einige der FastAPI-spezifischen Tools fĂŒr Parameter wie Body, Query, Form, usw. zusammen mit Pydantic‑v1‑Modellen verwenden mĂŒssen, können Sie die aus fastapi.temp_pydantic_v1_params importieren, wĂ€hrend Sie die Migration zu Pydantic v2 abschließen:

from typing import Annotated

from fastapi import FastAPI
from fastapi.temp_pydantic_v1_params import Body
from pydantic.v1 import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    size: float


app = FastAPI()


@app.post("/items/")
async def create_item(item: Annotated[Item, Body(embed=True)]) -> Item:
    return item
đŸ€“ Other versions and variants 
from typing import Annotated, Union

from fastapi import FastAPI
from fastapi.temp_pydantic_v1_params import Body
from pydantic.v1 import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    size: float


app = FastAPI()


@app.post("/items/")
async def create_item(item: Annotated[Item, Body(embed=True)]) -> Item:
    return item

In Schritten migrieren

Tipp

Probieren Sie zuerst bump-pydantic aus. Wenn Ihre Tests erfolgreich sind und das funktioniert, sind Sie mit einem einzigen Befehl fertig. ✹

Wenn bump-pydantic fĂŒr Ihren Anwendungsfall nicht funktioniert, können Sie die UnterstĂŒtzung fĂŒr Pydantic‑v1‑ und Pydantic‑v2‑Modelle in derselben App nutzen, um die Migration zu Pydantic v2 schrittweise durchzufĂŒhren.

Sie könnten zuerst Pydantic auf die neueste Version 2 aktualisieren und die Importe so Ă€ndern, dass fĂŒr all Ihre Modelle pydantic.v1 verwendet wird.

Anschließend können Sie beginnen, Ihre Modelle gruppenweise von Pydantic v1 auf v2 zu migrieren – in kleinen, schrittweisen Etappen. đŸš¶