Jan Vollmer
7 months ago
committed by
GitHub
GitHub
324 changed files with 11850 additions and 1801 deletions
@ -0,0 +1,133 @@ |
|||
# Von Pydantic v1 zu Pydantic v2 migrieren { #migrate-from-pydantic-v1-to-pydantic-v2 } |
|||
|
|||
Wenn Sie eine ältere FastAPI-App haben, nutzen Sie möglicherweise Pydantic Version 1. |
|||
|
|||
FastAPI unterstützt seit Version 0.100.0 sowohl Pydantic v1 als auch v2. |
|||
|
|||
Wenn Sie Pydantic v2 installiert hatten, wurde dieses verwendet. Wenn stattdessen Pydantic v1 installiert war, wurde jenes verwendet. |
|||
|
|||
Pydantic v1 ist jetzt deprecatet und die Unterstützung dafür wird in den nächsten Versionen von FastAPI entfernt, Sie sollten also zu **Pydantic v2 migrieren**. Auf diese Weise erhalten Sie die neuesten Features, Verbesserungen und Fixes. |
|||
|
|||
/// warning | Achtung |
|||
|
|||
Außerdem hat das Pydantic-Team die Unterstützung für Pydantic v1 in den neuesten Python-Versionen eingestellt, beginnend mit **Python 3.14**. |
|||
|
|||
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 **neuen Features in FastAPI 0.119.0**, die Ihnen bei einer schrittweisen Migration helfen. |
|||
|
|||
## Offizieller Leitfaden { #official-guide } |
|||
|
|||
Pydantic hat einen offiziellen <a href="https://docs.pydantic.dev/latest/migration/" class="external-link" target="_blank">Migrationsleitfaden</a> 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 { #tests } |
|||
|
|||
Stellen Sie sicher, dass Sie [Tests](../tutorial/testing.md){.internal-link target=_blank} 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` { #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 <a href="https://github.com/pydantic/bump-pydantic" class="external-link" target="_blank">`bump-pydantic`</a> 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-v1-in-v2 } |
|||
|
|||
Pydantic v2 enthält alles aus Pydantic v1 als Untermodul `pydantic.v1`. |
|||
|
|||
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. |
|||
|
|||
{* ../../docs_src/pydantic_v1_in_v2/tutorial001_an_py310.py hl[1,4] *} |
|||
|
|||
### FastAPI-Unterstützung für Pydantic v1 in v2 { #fastapi-support-for-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. |
|||
|
|||
{* ../../docs_src/pydantic_v1_in_v2/tutorial002_an_py310.py hl[2,5,15] *} |
|||
|
|||
/// warning | 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 { #pydantic-v1-and-v2-on-the-same-app } |
|||
|
|||
Es wird von Pydantic **nicht unterstützt**, dass ein Pydantic‑v2‑Modell Felder hat, die als Pydantic‑v1‑Modelle definiert sind, und umgekehrt. |
|||
|
|||
```mermaid |
|||
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. |
|||
|
|||
```mermaid |
|||
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: |
|||
|
|||
{* ../../docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py hl[2:3,6,12,21:22] *} |
|||
|
|||
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 { #pydantic-v1-parameters } |
|||
|
|||
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: |
|||
|
|||
{* ../../docs_src/pydantic_v1_in_v2/tutorial004_an_py310.py hl[4,18] *} |
|||
|
|||
### In Schritten migrieren { #migrate-in-steps } |
|||
|
|||
/// tip | 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. 🚶 |
|||
@ -0,0 +1,133 @@ |
|||
# Migrate from Pydantic v1 to Pydantic v2 { #migrate-from-pydantic-v1-to-pydantic-v2 } |
|||
|
|||
If you have an old FastAPI app, you might be using Pydantic version 1. |
|||
|
|||
FastAPI has had support for either Pydantic v1 or v2 since version 0.100.0. |
|||
|
|||
If you had installed Pydantic v2, it would use it. If instead you had Pydantic v1, it would use that. |
|||
|
|||
Pydantic v1 is now deprecated and support for it will be removed in the next versions of FastAPI, you should **migrate to Pydantic v2**. This way you will get the latest features, improvements, and fixes. |
|||
|
|||
/// warning |
|||
|
|||
Also, the Pydantic team stopped support for Pydantic v1 for the latest versions of Python, starting with **Python 3.14**. |
|||
|
|||
If you want to use the latest features of Python, you will need to make sure you use Pydantic v2. |
|||
|
|||
/// |
|||
|
|||
If you have an old FastAPI app with Pydantic v1, here I'll show you how to migrate it to Pydantic v2, and the **new features in FastAPI 0.119.0** to help you with a gradual migration. |
|||
|
|||
## Official Guide { #official-guide } |
|||
|
|||
Pydantic has an official <a href="https://docs.pydantic.dev/latest/migration/" class="external-link" target="_blank">Migration Guide</a> from v1 to v2. |
|||
|
|||
It also includes what has changed, how validations are now more correct and strict, possible caveats, etc. |
|||
|
|||
You can read it to understand better what has changed. |
|||
|
|||
## Tests { #tests } |
|||
|
|||
Make sure you have [tests](../tutorial/testing.md){.internal-link target=_blank} for your app and you run them on continuous integration (CI). |
|||
|
|||
This way, you can do the upgrade and make sure everything is still working as expected. |
|||
|
|||
## `bump-pydantic` { #bump-pydantic } |
|||
|
|||
In many cases, when you use regular Pydantic models without customizations, you will be able to automate most of the process of migrating from Pydantic v1 to Pydantic v2. |
|||
|
|||
You can use <a href="https://github.com/pydantic/bump-pydantic" class="external-link" target="_blank">`bump-pydantic`</a> from the same Pydantic team. |
|||
|
|||
This tool will help you to automatically change most of the code that needs to be changed. |
|||
|
|||
After this, you can run the tests and check if everything works. If it does, you are done. 😎 |
|||
|
|||
## Pydantic v1 in v2 { #pydantic-v1-in-v2 } |
|||
|
|||
Pydantic v2 includes everything from Pydantic v1 as a submodule `pydantic.v1`. |
|||
|
|||
This means that you can install the latest version of Pydantic v2 and import and use the old Pydantic v1 components from this submodule, as if you had the old Pydantic v1 installed. |
|||
|
|||
{* ../../docs_src/pydantic_v1_in_v2/tutorial001_an_py310.py hl[1,4] *} |
|||
|
|||
### FastAPI support for Pydantic v1 in v2 { #fastapi-support-for-pydantic-v1-in-v2 } |
|||
|
|||
Since FastAPI 0.119.0, there's also partial support for Pydantic v1 from inside of Pydantic v2, to facilitate the migration to v2. |
|||
|
|||
So, you could upgrade Pydantic to the latest version 2, and change the imports to use the `pydantic.v1` submodule, and in many cases it would just work. |
|||
|
|||
{* ../../docs_src/pydantic_v1_in_v2/tutorial002_an_py310.py hl[2,5,15] *} |
|||
|
|||
/// warning |
|||
|
|||
Have in mind that as the Pydantic team no longer supports Pydantic v1 in recent versions of Python, starting from Python 3.14, using `pydantic.v1` is also not supported in Python 3.14 and above. |
|||
|
|||
/// |
|||
|
|||
### Pydantic v1 and v2 on the same app { #pydantic-v1-and-v2-on-the-same-app } |
|||
|
|||
It's **not supported** by Pydantic to have a model of Pydantic v2 with its own fields defined as Pydantic v1 models or vice versa. |
|||
|
|||
```mermaid |
|||
graph TB |
|||
subgraph "❌ Not Supported" |
|||
direction TB |
|||
subgraph V2["Pydantic v2 Model"] |
|||
V1Field["Pydantic v1 Model"] |
|||
end |
|||
subgraph V1["Pydantic v1 Model"] |
|||
V2Field["Pydantic v2 Model"] |
|||
end |
|||
end |
|||
|
|||
style V2 fill:#f9fff3 |
|||
style V1 fill:#fff6f0 |
|||
style V1Field fill:#fff6f0 |
|||
style V2Field fill:#f9fff3 |
|||
``` |
|||
|
|||
...but, you can have separated models using Pydantic v1 and v2 in the same app. |
|||
|
|||
```mermaid |
|||
graph TB |
|||
subgraph "✅ Supported" |
|||
direction TB |
|||
subgraph V2["Pydantic v2 Model"] |
|||
V2Field["Pydantic v2 Model"] |
|||
end |
|||
subgraph V1["Pydantic v1 Model"] |
|||
V1Field["Pydantic v1 Model"] |
|||
end |
|||
end |
|||
|
|||
style V2 fill:#f9fff3 |
|||
style V1 fill:#fff6f0 |
|||
style V1Field fill:#fff6f0 |
|||
style V2Field fill:#f9fff3 |
|||
``` |
|||
|
|||
In some cases, it's even possible to have both Pydantic v1 and v2 models in the same **path operation** in your FastAPI app: |
|||
|
|||
{* ../../docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py hl[2:3,6,12,21:22] *} |
|||
|
|||
In this example above, the input model is a Pydantic v1 model, and the output model (defined in `response_model=ItemV2`) is a Pydantic v2 model. |
|||
|
|||
### Pydantic v1 parameters { #pydantic-v1-parameters } |
|||
|
|||
If you need to use some of the FastAPI-specific tools for parameters like `Body`, `Query`, `Form`, etc. with Pydantic v1 models, you can import them from `fastapi.temp_pydantic_v1_params` while you finish the migration to Pydantic v2: |
|||
|
|||
{* ../../docs_src/pydantic_v1_in_v2/tutorial004_an_py310.py hl[4,18] *} |
|||
|
|||
### Migrate in steps { #migrate-in-steps } |
|||
|
|||
/// tip |
|||
|
|||
First try with `bump-pydantic`, if your tests pass and that works, then you're done in one command. ✨ |
|||
|
|||
/// |
|||
|
|||
If `bump-pydantic` doesn't work for your use case, you can use the support for both Pydantic v1 and v2 models in the same app to do the migration to Pydantic v2 gradually. |
|||
|
|||
You could fist upgrade Pydantic to use the latest version 2, and change the imports to use `pydantic.v1` for all your models. |
|||
|
|||
Then, you can start migrating your models from Pydantic v1 to v2 in groups, in gradual steps. 🚶 |
|||
|
After Width: | Height: | Size: 18 KiB |
|
After Width: | Height: | Size: 6.3 KiB |
|
After Width: | Height: | Size: 10 KiB |
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue