diff --git a/.SYNC_INFO.md b/.SYNC_INFO.md index 63aa06b..b32bf5d 100644 --- a/.SYNC_INFO.md +++ b/.SYNC_INFO.md @@ -4,8 +4,8 @@ This is a mirror of the Fastapi repository. **Synced from:** https://github.com/tiangolo/fastapi.git **Branch:** master -**Commit:** 3e8d1526d83a90aaf7d6eb6dc682bf150f180b25 -**Sync Date:** 2026-08-11 +**Commit:** 50113da16fec53b66b80d75e80a89296de4fa5a5 +**Sync Date:** 2026-09-11 **Content:** Paths: docs, docs_src --- diff --git a/docs/de/docs/advanced/additional-responses.md b/docs/de/docs/advanced/additional-responses.md index f221471..c58c8b0 100644 --- a/docs/de/docs/advanced/additional-responses.md +++ b/docs/de/docs/advanced/additional-responses.md @@ -18,7 +18,7 @@ Für diese zusätzlichen Responses müssen Sie jedoch sicherstellen, dass Sie ei Sie können Ihren *Pfadoperation-Dekoratoren* einen Parameter `responses` übergeben. -Der nimmt ein `dict` entgegen, die Schlüssel sind Statuscodes für jede Response, wie etwa `200`, und die Werte sind andere `dict`s mit den Informationen für jede Response. +Der nimmt ein `dict` entgegen: Die Schlüssel sind Statuscodes für jede Response (wie etwa `200`), und die Werte sind andere `dict`s mit den Informationen für jede Response. Jedes dieser Response-`dict`s kann einen Schlüssel `model` haben, welcher ein Pydantic-Modell enthält, genau wie `response_model`. @@ -185,7 +185,7 @@ Beachten Sie, dass Sie das Bild direkt mit einer `FileResponse` zurückgeben mü /// note | Hinweis -Sofern Sie in Ihrem Parameter `responses` nicht explizit einen anderen Medientyp angeben, geht FastAPI davon aus, dass die Response denselben Medientyp wie die Haupt-Response-Klasse hat (Standardmäßig `application/json`). +Sofern Sie in Ihrem Parameter `responses` nicht explizit einen anderen Medientyp angeben, geht FastAPI davon aus, dass die Response denselben Medientyp wie die Haupt-Response-Klasse hat (standardmäßig `application/json`). Wenn Sie jedoch eine benutzerdefinierte Response-Klasse mit `None` als Medientyp angegeben haben, verwendet FastAPI `application/json` für jede zusätzliche Response, die über ein zugehöriges Modell verfügt. @@ -195,7 +195,7 @@ Wenn Sie jedoch eine benutzerdefinierte Response-Klasse mit `None` als Medientyp Sie können auch Response-Informationen von mehreren Stellen kombinieren, einschließlich der Parameter `response_model`, `status_code` und `responses`. -Sie können ein `response_model` deklarieren, indem Sie den Standardstatuscode `200` (oder bei Bedarf einen benutzerdefinierten) verwenden und dann zusätzliche Informationen für dieselbe Response in `responses` direkt im OpenAPI-Schema deklarieren. +Sie können ein `response_model` deklarieren, indem Sie den Defaultstatuscode `200` (oder bei Bedarf einen benutzerdefinierten) verwenden und dann zusätzliche Informationen für dieselbe Response in `responses` direkt im OpenAPI-Schema deklarieren. **FastAPI** behält die zusätzlichen Informationen aus `responses` und kombiniert sie mit dem JSON-Schema aus Ihrem Modell. @@ -243,5 +243,5 @@ Zum Beispiel: Um zu sehen, was genau Sie in die Responses aufnehmen können, können Sie die folgenden Abschnitte in der OpenAPI-Spezifikation überprüfen: -* [OpenAPI Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object), enthält das `Response Object`. -* [OpenAPI Response Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object), Sie können alles davon direkt in jede Response innerhalb Ihres `responses`-Parameter einfügen. Einschließlich `description`, `headers`, `content` (darin deklarieren Sie verschiedene Medientypen und JSON-Schemas) und `links`. +* [OpenAPI Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object), enthält das `Response Object`. +* [OpenAPI Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object), Sie können alles davon direkt in jede Response innerhalb Ihres `responses`-Parameters einfügen. Einschließlich `description`, `headers`, `content` (darin deklarieren Sie verschiedene Medientypen und JSON-Schemas) und `links`. diff --git a/docs/de/docs/advanced/async-tests.md b/docs/de/docs/advanced/async-tests.md index 58c925a..b3e9530 100644 --- a/docs/de/docs/advanced/async-tests.md +++ b/docs/de/docs/advanced/async-tests.md @@ -45,7 +45,7 @@ Sie können Ihre Tests wie gewohnt ausführen mit:
```console -$ pytest +$ uv run pytest ---> 100% ``` diff --git a/docs/de/docs/advanced/behind-a-proxy.md b/docs/de/docs/advanced/behind-a-proxy.md index 7260202..b1709d4 100644 --- a/docs/de/docs/advanced/behind-a-proxy.md +++ b/docs/de/docs/advanced/behind-a-proxy.md @@ -6,7 +6,7 @@ Diese Proxys könnten HTTPS-Zertifikate und andere Dinge handhaben. ## Proxy-Forwarded-Header { #proxy-forwarded-headers } -Ein **Proxy** vor Ihrer Anwendung würde normalerweise einige Header on-the-fly setzen, bevor er die Requests an den **Server** sendet, um den Server wissen zu lassen, dass der Request vom Proxy **weitergeleitet** wurde, einschließlich der ursprünglichen (öffentlichen) URL, inklusive der Domain, dass HTTPS verwendet wird, usw. +Ein **Proxy** vor Ihrer Anwendung würde normalerweise einige Header on-the-fly setzen, bevor er die Requests an Ihren **Server** sendet, um den Server wissen zu lassen, dass der Request vom Proxy **weitergeleitet** wurde, einschließlich der ursprünglichen (öffentlichen) URL, inklusive der Domain, dass HTTPS verwendet wird, usw. Das **Server**-Programm (z. B. **Uvicorn** via **FastAPI CLI**) ist in der Lage, diese Header zu interpretieren und diese Information dann an Ihre Anwendung weiterzugeben. @@ -33,7 +33,7 @@ Wenn Ihr **Server** hinter einem vertrauenswürdigen **Proxy** sitzt und nur der
```console -$ fastapi run --forwarded-allow-ips="*" +$ uv run fastapi run --forwarded-allow-ips="*" INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -82,7 +82,7 @@ sequenceDiagram Note over Server: Server interpretiert die Header
(wenn --forwarded-allow-ips gesetzt ist) - Server->>Proxy: HTTP-Response
mit correkten HTTPS-URLs + Server->>Proxy: HTTP-Response
mit korrekten HTTPS-URLs Proxy->>Client: HTTPS-Response ``` @@ -170,7 +170,7 @@ Um dies zu erreichen, können Sie die Kommandozeilenoption `--root-path` wie fol
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -200,7 +200,7 @@ Wenn Sie Uvicorn dann starten mit:
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -253,7 +253,7 @@ In einem solchen Fall (ohne ein abgetrenntes Pfadpräfix) würde der Proxy auf e Sie können das Experiment mit einem abgetrennten Pfadpräfix einfach lokal ausführen, indem Sie [Traefik](https://docs.traefik.io/) verwenden. -[Laden Sie Traefik herunter](https://github.com/containous/traefik/releases), es ist eine einzelne Binärdatei, Sie können die komprimierte Datei extrahieren und sie direkt vom Terminal aus ausführen. +[Laden Sie Traefik herunter](https://github.com/traefik/traefik/releases), es ist eine einzelne Binärdatei, Sie können die komprimierte Datei extrahieren und sie direkt vom Terminal aus ausführen. Dann erstellen Sie eine Datei `traefik.toml` mit: @@ -316,12 +316,12 @@ INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml
-Und jetzt starten Sie Ihre Anwendung mit Uvicorn, indem Sie die Option `--root-path` verwenden: +Und jetzt starten Sie Ihre Anwendung, indem Sie die Option `--root-path` verwenden:
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -461,6 +461,6 @@ Dann wird er nicht in das OpenAPI-Schema aufgenommen. ## Mounten einer Unteranwendung { #mounting-a-sub-application } -Wenn Sie gleichzeitig eine Unteranwendung mounten (wie beschrieben in [Unteranwendungen – Mounts](sub-applications.md)) und einen Proxy mit `root_path` verwenden wollen, können Sie das normal tun, wie Sie es erwarten würden. +Wenn Sie eine Unteranwendung mounten müssen (wie beschrieben in [Unteranwendungen – Mounts](sub-applications.md)) und dabei auch einen Proxy mit `root_path` verwenden, können Sie das normal tun, wie Sie es erwarten würden. FastAPI verwendet intern den `root_path` auf intelligente Weise, sodass es einfach funktioniert. ✨ diff --git a/docs/de/docs/advanced/dataclasses.md b/docs/de/docs/advanced/dataclasses.md index bacf9d1..8afe3b6 100644 --- a/docs/de/docs/advanced/dataclasses.md +++ b/docs/de/docs/advanced/dataclasses.md @@ -1,13 +1,12 @@ # Datenklassen verwenden { #using-dataclasses } - FastAPI basiert auf **Pydantic**, und ich habe Ihnen gezeigt, wie Sie Pydantic-Modelle verwenden können, um Requests und Responses zu deklarieren. Aber FastAPI unterstützt auf die gleiche Weise auch die Verwendung von [`dataclasses`](https://docs.python.org/3/library/dataclasses.html): {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -Das ist dank **Pydantic** ebenfalls möglich, da es [„`dataclasses` intern unterstützt“](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel). +Das ist dank **Pydantic** ebenfalls möglich, da es [interne Unterstützung für `dataclasses`](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/#usage-of-stdlib-dataclasses-with-basemodel) bietet. Auch wenn im obigen Code Pydantic nicht explizit vorkommt, verwendet FastAPI Pydantic, um diese Standard-Datenklassen in Pydantics eigene Variante von Datenklassen zu konvertieren. @@ -65,7 +64,7 @@ In diesem Fall können Sie einfach die Standard-`dataclasses` durch `pydantic.da 6. Hier geben wir ein Dictionary zurück, das `items` enthält, welches eine Liste von Datenklassen ist. - FastAPI ist weiterhin in der Lage, die Daten nach JSON zu Serialisieren. + FastAPI ist weiterhin in der Lage, die Daten nach JSON zu serialisieren. 7. Hier verwendet das `response_model` als Typannotation eine Liste von `Author`-Datenklassen. @@ -75,7 +74,7 @@ In diesem Fall können Sie einfach die Standard-`dataclasses` durch `pydantic.da Wie immer können Sie in FastAPI `def` und `async def` beliebig kombinieren. - Wenn Sie eine Auffrischung darüber benötigen, wann welche Anwendung sinnvoll ist, lesen Sie den Abschnitt „In Eile?“ in der Dokumentation zu [`async` und `await`](../async.md#in-a-hurry). + Wenn Sie eine Auffrischung darüber benötigen, wann welche Anwendung sinnvoll ist, lesen Sie den Abschnitt _„In Eile?“_ in der Dokumentation zu [`async` und `await`](../async.md#in-a-hurry). 9. Diese *Pfadoperation-Funktion* gibt keine Datenklassen zurück (obwohl dies möglich wäre), sondern eine Liste von Dictionarys mit internen Daten. @@ -83,13 +82,13 @@ In diesem Fall können Sie einfach die Standard-`dataclasses` durch `pydantic.da Sie können `dataclasses` mit anderen Typannotationen auf vielfältige Weise kombinieren, um komplexe Datenstrukturen zu bilden. -Weitere Einzelheiten finden Sie in den Bemerkungen im Quellcode oben. +Weitere spezifische Details finden Sie in den Annotationstipps im Code oben. ## Mehr erfahren { #learn-more } Sie können `dataclasses` auch mit anderen Pydantic-Modellen kombinieren, von ihnen erben, sie in Ihre eigenen Modelle einbinden, usw. -Weitere Informationen finden Sie in der [Pydantic-Dokumentation zu Datenklassen](https://docs.pydantic.dev/latest/concepts/dataclasses/). +Weitere Informationen finden Sie in der [Pydantic-Dokumentation zu Datenklassen](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/). ## Version { #version } diff --git a/docs/de/docs/advanced/events.md b/docs/de/docs/advanced/events.md index 6efe968..a6d3430 100644 --- a/docs/de/docs/advanced/events.md +++ b/docs/de/docs/advanced/events.md @@ -32,7 +32,7 @@ Wir erstellen eine asynchrone Funktion `lifespan()` mit `yield` wie folgt: {* ../../docs_src/events/tutorial003_py310.py hl[16,19] *} -Hier simulieren wir den langsamen *Startup*, das Laden des Modells, indem wir die (Fake-)Modellfunktion vor dem `yield` in das Dictionary mit Modellen für maschinelles Lernen einfügen. Dieser Code wird ausgeführt, **bevor** die Anwendung **beginnt, Requests entgegenzunehmen**, während des *Startups*. +Hier simulieren wir den aufwendigen *Startup*-Vorgang des Ladens des Modells, indem wir die (Fake-)Modellfunktion vor dem `yield` in das Dictionary mit Modellen für maschinelles Lernen einfügen. Dieser Code wird ausgeführt, **bevor** die Anwendung **beginnt, Requests entgegenzunehmen**, während des *Startups*. Und dann, direkt nach dem `yield`, entladen wir das Modell. Dieser Code wird ausgeführt, **nachdem** die Anwendung **die Bearbeitung von Requests abgeschlossen hat**, direkt vor dem *Shutdown*. Dadurch könnten beispielsweise Ressourcen wie Arbeitsspeicher oder eine GPU freigegeben werden. @@ -140,7 +140,7 @@ Daher deklarieren wir die Eventhandler-Funktion mit Standard-`def` statt mit `as ### `startup` und `shutdown` zusammen { #startup-and-shutdown-together } -Es besteht eine hohe Wahrscheinlichkeit, dass die Logik für Ihr *Startup* und *Shutdown* miteinander verknüpft ist. Vielleicht möchten Sie etwas beginnen und es dann beenden, eine Ressource laden und sie dann freigeben usw. +Es besteht eine hohe Wahrscheinlichkeit, dass die Logik für Ihr *Startup* und *Shutdown* miteinander verknüpft ist. Vielleicht möchten Sie etwas beginnen und es dann beenden, eine Ressource belegen und sie dann freigeben usw. Bei getrennten Funktionen, die keine gemeinsame Logik oder Variablen haben, ist dies schwieriger, da Sie Werte in globalen Variablen speichern oder ähnliche Tricks verwenden müssen. @@ -154,9 +154,9 @@ In der technischen ASGI-Spezifikation ist dies Teil des [Lifespan-Protokolls](ht /// note | Hinweis -Weitere Informationen zu Starlettes `lifespan`-Handlern finden Sie in [Starlettes Lifespan-Dokumentation](https://www.starlette.dev/lifespan/). +Weitere Informationen zu Starlettes `lifespan`-Handlern finden Sie in [Starlettes Lifespan-Dokumentation](https://starlette.dev/lifespan/). -Einschließlich, wie man Lifespan-Zustand handhabt, der in anderen Bereichen Ihres Codes verwendet werden kann. +Einschließlich, wie Sie Lifespan-Zustand handhaben, der in anderen Bereichen Ihres Codes verwendet werden kann. /// diff --git a/docs/de/docs/advanced/generate-clients.md b/docs/de/docs/advanced/generate-clients.md index d93641b..ce14e84 100644 --- a/docs/de/docs/advanced/generate-clients.md +++ b/docs/de/docs/advanced/generate-clients.md @@ -6,13 +6,13 @@ Dies vereinfacht es, aktuelle **Dokumentation** und Client-Bibliotheken ( ```console -$ pip install pydantic-settings +$ uv add pydantic-settings ---> 100% ```
-Es ist bereits enthalten, wenn Sie die `all`-Extras installiert haben, mit: +Es ist auch enthalten, wenn Sie die `all`-Extras installieren mit:
```console -$ pip install "fastapi[all]" +$ uv add "fastapi[all]" ---> 100% ``` @@ -76,19 +80,39 @@ Dann können Sie das neue `settings`-Objekt in Ihrer Anwendung verwenden: Als Nächstes würden Sie den Server ausführen und die Konfigurationen als Umgebungsvariablen übergeben. Sie könnten beispielsweise `ADMIN_EMAIL` und `APP_NAME` festlegen mit: +//// tab | Linux, macOS, Windows Bash +
```console -$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py +$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uv run fastapi run main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
+//// + +//// tab | Windows PowerShell + +
+ +```console +$ $Env:ADMIN_EMAIL = "deadpool@example.com" +$ $Env:APP_NAME = "ChimichangApp" +$ uv run fastapi run main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +//// + /// tip | Tipp -Um mehrere Umgebungsvariablen für einen einzelnen Befehl festzulegen, trennen Sie diese einfach durch ein Leerzeichen und fügen Sie alle vor dem Befehl ein. +In Bash trennen Sie, um mehrere Umgebungsvariablen für einen einzelnen Befehl festzulegen, diese durch ein Leerzeichen und fügen sie alle vor dem Befehl ein. /// @@ -172,11 +196,11 @@ Aber eine dotenv-Datei muss nicht unbedingt genau diesen Dateinamen haben. /// -Pydantic unterstützt das Lesen dieser Dateitypen mithilfe einer externen Bibliothek. Weitere Informationen finden Sie unter [Pydantic Settings: Dotenv (.env)-Unterstützung](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support). +Pydantic unterstützt das Lesen dieser Dateitypen mithilfe einer externen Bibliothek. Weitere Informationen finden Sie unter [Pydantic Settings: Dotenv (.env)-Unterstützung](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#dotenv-env-support). /// tip | Tipp -Damit das funktioniert, müssen Sie `pip install python-dotenv` ausführen. +Damit das funktioniert, fügen Sie Ihrem Projekt `python-dotenv` mit `uv add python-dotenv` hinzu. /// @@ -197,7 +221,7 @@ Und dann aktualisieren Sie Ihre `config.py` mit: /// tip | Tipp -Das Attribut `model_config` wird nur für die Pydantic-Konfiguration verwendet. Weitere Informationen finden Sie unter [Pydantic: Konzepte: Konfiguration](https://docs.pydantic.dev/latest/concepts/config/). +Das Attribut `model_config` wird nur für die Pydantic-Konfiguration verwendet. Weitere Informationen finden Sie unter [Pydantic: Konzepte: Konfiguration](https://pydantic.dev/docs/validation/latest/concepts/config/). /// diff --git a/docs/de/docs/advanced/sub-applications.md b/docs/de/docs/advanced/sub-applications.md index 206ee7b..e311ac7 100644 --- a/docs/de/docs/advanced/sub-applications.md +++ b/docs/de/docs/advanced/sub-applications.md @@ -4,11 +4,11 @@ Wenn Sie zwei unabhängige FastAPI-Anwendungen mit deren eigenen unabhängigen O ## Eine **FastAPI**-Anwendung mounten { #mounting-a-fastapi-application } -„Mounten“ („Einhängen“) bedeutet das Hinzufügen einer völlig „unabhängigen“ Anwendung an einem bestimmten Pfad, die sich dann um die Handhabung aller unter diesem Pfad liegenden _Pfadoperationen_ kümmert, welche in dieser Unteranwendung deklariert sind. +„Mounten“ bedeutet das Hinzufügen einer völlig „unabhängigen“ Anwendung an einem bestimmten Pfad, die sich dann um die Handhabung aller unter diesem Pfad liegenden _Pfadoperationen_ kümmert, welche in dieser Unteranwendung deklariert sind. -### Hauptanwendung { #top-level-application } +### Top-Level-Anwendung { #top-level-application } -Erstellen Sie zunächst die Hauptanwendung **FastAPI** und deren *Pfadoperationen*: +Erstellen Sie zunächst die Haupt-, Top-Level-**FastAPI**-Anwendung und deren *Pfadoperationen*: {* ../../docs_src/sub_applications/tutorial001_py310.py hl[3, 6:8] *} @@ -35,7 +35,7 @@ Führen Sie nun den Befehl `fastapi` aus:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/de/docs/advanced/templates.md b/docs/de/docs/advanced/templates.md index 218b043..71ffc9b 100644 --- a/docs/de/docs/advanced/templates.md +++ b/docs/de/docs/advanced/templates.md @@ -8,12 +8,12 @@ Es gibt Werkzeuge zur einfachen Konfiguration, die Sie direkt in Ihrer **FastAPI ## Abhängigkeiten installieren { #install-dependencies } -Stellen Sie sicher, dass Sie eine [virtuelle Umgebung](../virtual-environments.md) erstellen, sie aktivieren und `jinja2` installieren: +Fügen Sie `jinja2` Ihrem Projekt hinzu:
```console -$ pip install jinja2 +$ uv add jinja2 ---> 100% ``` @@ -53,7 +53,7 @@ Sie können auch `from starlette.templating import Jinja2Templates` verwenden. ## Templates erstellen { #writing-templates } -Dann können Sie unter `templates/item.html` ein Template erstellen, mit z. B. folgendem Inhalt: +Dann können Sie unter `templates/item.html` ein Template erstellen, mit z. B.: ```jinja hl_lines="7" {!../../docs_src/templates/templates/item.html!} @@ -123,4 +123,4 @@ Und da Sie `StaticFiles` verwenden, wird diese CSS-Datei automatisch von Ihrer * ## Mehr Details { #more-details } -Weitere Informationen, einschließlich, wie man Templates testet, finden Sie in [Starlettes Dokumentation zu Templates](https://www.starlette.dev/templates/). +Weitere Informationen, einschließlich, wie man Templates testet, finden Sie in [Starlettes Dokumentation zu Templates](https://starlette.dev/templates/). diff --git a/docs/de/docs/advanced/testing-events.md b/docs/de/docs/advanced/testing-events.md index 053aeff..903b377 100644 --- a/docs/de/docs/advanced/testing-events.md +++ b/docs/de/docs/advanced/testing-events.md @@ -5,7 +5,7 @@ Wenn Sie `lifespan` in Ihren Tests ausführen müssen, können Sie den `TestClie {* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *} -Sie können mehr Details unter [„Lifespan in Tests ausführen in der offiziellen Starlette-Dokumentation.“](https://www.starlette.dev/lifespan/#running-lifespan-in-tests) nachlesen. +Sie können mehr Details unter [„Lifespan in Tests ausführen auf der offiziellen Starlette-Dokumentationswebsite.“](https://starlette.dev/lifespan/#running-lifespan-in-tests) nachlesen. Für die deprecateten Events `startup` und `shutdown` können Sie den `TestClient` wie folgt verwenden: diff --git a/docs/de/docs/advanced/testing-websockets.md b/docs/de/docs/advanced/testing-websockets.md index 3c06f19..63ae41c 100644 --- a/docs/de/docs/advanced/testing-websockets.md +++ b/docs/de/docs/advanced/testing-websockets.md @@ -8,6 +8,6 @@ Dazu verwenden Sie den `TestClient` in einer `with`-Anweisung, eine Verbindung z /// note | Hinweis -Weitere Informationen finden Sie in Starlettes Dokumentation zum [Testen von WebSockets](https://www.starlette.dev/testclient/#testing-websocket-sessions). +Weitere Informationen finden Sie in Starlettes Dokumentation zum [Testen von WebSockets](https://starlette.dev/testclient/#testing-websocket-sessions). /// diff --git a/docs/de/docs/advanced/using-request-directly.md b/docs/de/docs/advanced/using-request-directly.md index 623ddbb..27e767d 100644 --- a/docs/de/docs/advanced/using-request-directly.md +++ b/docs/de/docs/advanced/using-request-directly.md @@ -15,7 +15,7 @@ Es gibt jedoch Situationen, in denen Sie möglicherweise direkt auf das `Request ## Details zum `Request`-Objekt { #details-about-the-request-object } -Da **FastAPI** unter der Haube eigentlich **Starlette** ist, mit einer Ebene von mehreren Tools darüber, können Sie Starlettes [`Request`](https://www.starlette.dev/requests/)-Objekt direkt verwenden, wenn Sie es benötigen. +Da **FastAPI** unter der Haube eigentlich **Starlette** ist, mit einer Ebene von mehreren Tools darüber, können Sie Starlettes [`Request`](https://starlette.dev/requests/)-Objekt direkt verwenden, wenn Sie es benötigen. Das bedeutet allerdings auch, dass, wenn Sie Daten direkt vom `Request`-Objekt nehmen (z. B. dessen Body lesen), diese von FastAPI nicht validiert, konvertiert oder dokumentiert werden (mit OpenAPI, für die automatische API-Benutzeroberfläche). @@ -45,7 +45,7 @@ Auf die gleiche Weise können Sie wie gewohnt jeden anderen Parameter deklariere ## `Request`-Dokumentation { #request-documentation } -Weitere Details zum [`Request`-Objekt auf der offiziellen Starlette-Dokumentationsseite](https://www.starlette.dev/requests/). +Weitere Details zum [`Request`-Objekt auf der offiziellen Starlette-Dokumentationsseite](https://starlette.dev/requests/). /// note | Technische Details diff --git a/docs/de/docs/advanced/websockets.md b/docs/de/docs/advanced/websockets.md index a0f3a1f..5c32d11 100644 --- a/docs/de/docs/advanced/websockets.md +++ b/docs/de/docs/advanced/websockets.md @@ -4,12 +4,12 @@ Sie können [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSoc ## `websockets` installieren { #install-websockets } -Stellen Sie sicher, dass Sie eine [virtuelle Umgebung](../virtual-environments.md) erstellen, sie aktivieren und `websockets` installieren (eine Python-Bibliothek, die die Verwendung des „WebSocket“-Protokolls erleichtert): +Fügen Sie `websockets` (eine Python-Bibliothek, die die Verwendung des „WebSocket“-Protokolls erleichtert) zu Ihrem Projekt hinzu:
```console -$ pip install websockets +$ uv add websockets ---> 100% ``` @@ -69,7 +69,7 @@ Legen Sie Ihren Code in einer Datei `main.py` ab und führen Sie dann Ihre Anwen
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -96,7 +96,7 @@ Sie können viele Nachrichten senden (und empfangen): Und alle verwenden dieselbe WebSocket-Verbindung. -## Verwendung von `Depends` und anderen { #using-depends-and-others } +## `Depends` und andere verwenden { #using-depends-and-others } In WebSocket-Endpunkten können Sie Folgendes aus `fastapi` importieren und verwenden: @@ -126,7 +126,7 @@ Führen Sie Ihre Anwendung aus:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -182,5 +182,5 @@ Wenn Sie etwas benötigen, das sich leicht in FastAPI integrieren lässt, aber r Weitere Informationen zu Optionen finden Sie in der Dokumentation von Starlette: -* [Die `WebSocket`-Klasse](https://www.starlette.dev/websockets/). -* [Klassen-basierte Handhabung von WebSockets](https://www.starlette.dev/endpoints/#websocketendpoint). +* [Die `WebSocket`-Klasse](https://starlette.dev/websockets/). +* [Klassen-basierte Handhabung von WebSockets](https://starlette.dev/endpoints/#websocketendpoint). diff --git a/docs/de/docs/advanced/wsgi.md b/docs/de/docs/advanced/wsgi.md index 353734a..b9d8d7d 100644 --- a/docs/de/docs/advanced/wsgi.md +++ b/docs/de/docs/advanced/wsgi.md @@ -9,13 +9,13 @@ Dazu können Sie die `WSGIMiddleware` verwenden und damit Ihre WSGI-Anwendung wr /// note | Hinweis -Dafür muss `a2wsgi` installiert sein, z. B. mit `pip install a2wsgi`. +Dafür muss `a2wsgi` zu Ihrem Projekt hinzugefügt werden, z. B. mit `uv add a2wsgi`. /// Sie müssen `WSGIMiddleware` aus `a2wsgi` importieren. -Wrappen Sie dann die WSGI-Anwendung (z. B. Flask) mit der Middleware. +Wrappen Sie dann die WSGI-App (z. B. Flask) mit der Middleware. Und dann mounten Sie das auf einem Pfad. diff --git a/docs/de/docs/alternatives.md b/docs/de/docs/alternatives.md index 5a814cb..35944da 100644 --- a/docs/de/docs/alternatives.md +++ b/docs/de/docs/alternatives.md @@ -125,7 +125,7 @@ Einen offenen Standard für API-Spezifikationen zu übernehmen und zu verwenden, Und Standard-basierte Tools für die Oberfläche zu integrieren: * [Swagger UI](https://github.com/swagger-api/swagger-ui) -* [ReDoc](https://github.com/Rebilly/ReDoc) +* [ReDoc](https://github.com/Redocly/redoc) Diese beiden wurden ausgewählt, weil sie ziemlich beliebt und stabil sind, aber bei einer schnellen Suche könnten Sie Dutzende alternativer Benutzeroberflächen für OpenAPI finden (welche Sie mit **FastAPI** verwenden können). @@ -137,7 +137,7 @@ Es gibt mehrere Flask REST Frameworks, aber nachdem ich die Zeit und Arbeit inve ### [Marshmallow](https://marshmallow.readthedocs.io/en/stable/) { #marshmallow } -Eine der von API-Systemen benötigten Hauptfunktionen ist die Daten-„Serialisierung“, welche Daten aus dem Code (Python) entnimmt und in etwas umwandelt, was durch das Netzwerk gesendet werden kann. Beispielsweise das Konvertieren eines Objekts, welches Daten aus einer Datenbank enthält, in ein JSON-Objekt. Konvertieren von `datetime`-Objekten in Strings, usw. +Eine der von API-Systemen benötigten Hauptfunktionen ist die Daten-„Serialisierung“, welche Daten aus dem Code (Python) entnimmt und in etwas umwandelt, was durch das Netzwerk gesendet werden kann. Beispielsweise das Konvertieren eines Objekts, welches Daten aus einer Datenbank enthält, in ein JSON-Objekt. Konvertieren von `datetime`-Objekten in Strings, usw. Eine weitere wichtige Funktion, benötigt von APIs, ist die Datenvalidierung, welche sicherstellt, dass die Daten unter gegebenen Umständen gültig sind. Zum Beispiel, dass ein Feld ein `int` ist und kein zufälliger String. Das ist besonders nützlich für hereinkommende Daten. @@ -237,7 +237,7 @@ Das OpenAPI-Schema automatisch zu generieren, aus demselben Code, welcher die Se /// -### [NestJS](https://nestjs.com/) (und [Angular](https://angular.io/)) { #nestjs-and-angular } +### [NestJS](https://nestjs.com/) (und [Angular](https://angular.dev/)) { #nestjs-and-angular } Dies ist nicht einmal Python, NestJS ist ein von Angular inspiriertes JavaScript (TypeScript) NodeJS Framework. @@ -337,7 +337,7 @@ Da es auf dem bisherigen Standard für synchrone Python-Webframeworks (WSGI) bas /// note | Hinweis -Hug wurde von Timothy Crosley erstellt, demselben Schöpfer von [`isort`](https://github.com/timothycrosley/isort), einem großartigen Tool zum automatischen Sortieren von Importen in Python-Dateien. +Hug wurde von Timothy Crosley erstellt, demselben Schöpfer von [`isort`](https://github.com/PyCQA/isort), einem großartigen Tool zum automatischen Sortieren von Importen in Python-Dateien. /// @@ -401,7 +401,7 @@ Ich betrachte **FastAPI** als einen „spirituellen Nachfolger“ von APIStar, w ## Verwendet von **FastAPI** { #used-by-fastapi } -### [Pydantic](https://docs.pydantic.dev/) { #pydantic } +### [Pydantic](https://pydantic.dev/docs/) { #pydantic } Pydantic ist eine Bibliothek zum Definieren von Datenvalidierung, Serialisierung und Dokumentation (unter Verwendung von JSON Schema) basierend auf Python-Typhinweisen. @@ -417,7 +417,7 @@ Die gesamte Datenvalidierung, Datenserialisierung und automatische Modelldokumen /// -### [Starlette](https://www.starlette.dev/) { #starlette } +### [Starlette](https://starlette.dev/) { #starlette } Starlette ist ein leichtgewichtiges ASGI-Framework/Toolkit, welches sich ideal für die Erstellung hochperformanter asynchroner Dienste eignet. @@ -462,7 +462,7 @@ Alles, was Sie also mit Starlette machen können, können Sie direkt mit **FastA /// -### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn } +### [Uvicorn](https://uvicorn.dev) { #uvicorn } Uvicorn ist ein blitzschneller ASGI-Server, der auf uvloop und httptools basiert. diff --git a/docs/de/docs/deployment/docker.md b/docs/de/docs/deployment/docker.md index 0ab886c..d653016 100644 --- a/docs/de/docs/deployment/docker.md +++ b/docs/de/docs/deployment/docker.md @@ -105,36 +105,32 @@ Das ist, was Sie in **den meisten Fällen** tun möchten, zum Beispiel: ### Paketanforderungen { #package-requirements } -Normalerweise befinden sich die **Paketanforderungen** für Ihre Anwendung in einer Datei. +Wenn Sie Ihr Projekt mit `uv` verwalten, werden dessen direkte Abhängigkeiten in `pyproject.toml` deklariert und die exakt aufgelösten Versionen in `uv.lock` gespeichert. -Dies hängt hauptsächlich von dem Tool ab, mit dem Sie diese Anforderungen **installieren**. - -Die gebräuchlichste Methode besteht darin, eine Datei `requirements.txt` mit den Namen der Packages und deren Versionen zu erstellen, eine pro Zeile. - -Sie würden natürlich die gleichen Ideen verwenden, die Sie in [Über FastAPI-Versionen](versions.md) gelesen haben, um die Versionsbereiche festzulegen. - -Ihre `requirements.txt` könnte beispielsweise so aussehen: - -``` -fastapi[standard]>=0.113.0,<0.114.0 -pydantic>=2.7.0,<3.0.0 -``` - -Und normalerweise würden Sie diese Paketabhängigkeiten mit `pip` installieren, zum Beispiel: +Sie können die Packages, die Ihre Anwendung benötigt, hinzufügen mit:
```console -$ pip install -r requirements.txt +$ uv add "fastapi[standard]" pydantic ---> 100% -Successfully installed fastapi pydantic ```
/// note | Hinweis -Es gibt andere Formate und Tools zum Definieren und Installieren von Paketabhängigkeiten. +Das Dockerfile unten verwendet `pip` innerhalb des Containers. Sie können die gelockten Abhängigkeiten aus Ihrem uv-Projekt in das erwartete Format `requirements.txt` exportieren: + +
+ +```console +$ uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt +``` + +
+ +Die generierte `requirements.txt` ist ein Export für den Container-Build. Verwalten Sie Abhängigkeiten weiterhin mit `uv add` und generieren Sie sie neu, wenn sich `uv.lock` ändert. /// @@ -372,7 +368,7 @@ Sie sehen die automatische interaktive API-Dokumentation (bereitgestellt von [Sw Sie können auch auf [http://192.168.99.100/redoc](http://192.168.99.100/redoc) oder [http://127.0.0.1/redoc](http://127.0.0.1/redoc) gehen (oder ähnlich, unter Verwendung Ihres Docker-Hosts). -Sie sehen die alternative automatische Dokumentation (bereitgestellt von [ReDoc](https://github.com/Rebilly/ReDoc)): +Sie sehen die alternative automatische Dokumentation (bereitgestellt von [ReDoc](https://github.com/Redocly/redoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -529,7 +525,7 @@ Dann möchten Sie vielleicht **einen einzelnen Container** mit einem **Prozessma --- -Der Hauptpunkt ist, dass **keine** dieser Regeln **in Stein gemeißelt** ist, der man blind folgen muss. Sie können diese Ideen verwenden, um **I Ihren eigenen Anwendungsfall zu evaluieren**, zu entscheiden, welcher Ansatz für Ihr System am besten geeignet ist und herauszufinden, wie Sie folgende Konzepte verwalten: +Der Hauptpunkt ist, dass **keine** dieser Regeln **in Stein gemeißelt** ist, der man blind folgen muss. Sie können diese Ideen verwenden, um **Ihren eigenen Anwendungsfall zu evaluieren**, zu entscheiden, welcher Ansatz für Ihr System am besten geeignet ist und herauszufinden, wie Sie folgende Konzepte verwalten: * Sicherheit – HTTPS * Beim Hochfahren ausführen diff --git a/docs/de/docs/deployment/fastapicloud.md b/docs/de/docs/deployment/fastapicloud.md index d563fd8..d8827c8 100644 --- a/docs/de/docs/deployment/fastapicloud.md +++ b/docs/de/docs/deployment/fastapicloud.md @@ -5,7 +5,7 @@ Sie können Ihre FastAPI-App in der [FastAPI Cloud](https://fastapicloud.com) mi
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... diff --git a/docs/de/docs/deployment/manually.md b/docs/de/docs/deployment/manually.md index fa8a9c9..4f023e2 100644 --- a/docs/de/docs/deployment/manually.md +++ b/docs/de/docs/deployment/manually.md @@ -52,7 +52,7 @@ Das Wichtigste, was Sie benötigen, um eine **FastAPI**-Anwendung (oder eine and Es gibt mehrere Alternativen, einschließlich: -* [Uvicorn](https://www.uvicorn.dev/): ein hochperformanter ASGI-Server. +* [Uvicorn](https://uvicorn.dev): ein hochperformanter ASGI-Server. * [Hypercorn](https://hypercorn.readthedocs.io/): ein ASGI-Server, der unter anderem kompatibel mit HTTP/2 und Trio ist. * [Daphne](https://github.com/django/daphne): der für Django Channels entwickelte ASGI-Server. * [Granian](https://github.com/emmett-framework/granian): Ein Rust-HTTP-Server für Python-Anwendungen. @@ -73,14 +73,14 @@ Wenn Sie FastAPI installieren, wird es mit einem Produktionsserver, Uvicorn, gel Aber Sie können auch ein ASGI-Serverprogramm manuell installieren. -Stellen Sie sicher, dass Sie eine [virtuelle Umgebung](../virtual-environments.md) erstellen, sie aktivieren und dann die Serveranwendung installieren. +Fügen Sie die Serveranwendung Ihrem Projekt hinzu. Zum Beispiel, um Uvicorn zu installieren:
```console -$ pip install "uvicorn[standard]" +$ uv add "uvicorn[standard]" ---> 100% ``` @@ -95,7 +95,7 @@ Durch das Hinzufügen von `standard` installiert und verwendet Uvicorn einige em Dazu gehört `uvloop`, der hochperformante Drop-in-Ersatz für `asyncio`, der den großen Nebenläufigkeits-Leistungsschub bietet. -Wenn Sie FastAPI mit etwas wie `pip install "fastapi[standard]"` installieren, erhalten Sie auch `uvicorn[standard]`. +Wenn Sie FastAPI mit etwas wie `uv add "fastapi[standard]"` hinzufügen, erhalten Sie auch bereits `uvicorn[standard]`. /// @@ -106,7 +106,7 @@ Wenn Sie einen ASGI-Server manuell installiert haben, müssen Sie normalerweise
```console -$ uvicorn main:app --host 0.0.0.0 --port 80 +$ uv run uvicorn main:app --host 0.0.0.0 --port 80 INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) ``` diff --git a/docs/de/docs/deployment/server-workers.md b/docs/de/docs/deployment/server-workers.md index 6b0cc83..73d35bf 100644 --- a/docs/de/docs/deployment/server-workers.md +++ b/docs/de/docs/deployment/server-workers.md @@ -86,7 +86,7 @@ Wenn Sie den `uvicorn`-Befehl direkt verwenden möchten:
```console -$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 +$ uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit) INFO: Started parent process [27365] INFO: Started server process [27368] diff --git a/docs/de/docs/environment-variables.md b/docs/de/docs/environment-variables.md index 1678ead..3f72ecc 100644 --- a/docs/de/docs/environment-variables.md +++ b/docs/de/docs/environment-variables.md @@ -1,298 +1,11 @@ # Umgebungsvariablen { #environment-variables } -/// tip | Tipp +Eine **Umgebungsvariable** (auch bekannt als **env var**) ist ein Wert, der außerhalb Ihres Python-Codes im Betriebssystem existiert und von Ihrer Anwendung und anderen Programmen gelesen werden kann. -Wenn Sie bereits wissen, was „Umgebungsvariablen“ sind und wie man sie verwendet, können Sie dies überspringen. +FastAPI-Anwendungen verwenden häufig Umgebungsvariablen für Konfigurationen wie Datenbank-URLs, E-Mail-Zugangsdaten und Secret-Keys. -/// +Sie werden lernen, wie Sie sie für Anwendungskonfigurationen verwenden, in [Einstellungen und Umgebungsvariablen](advanced/settings.md). -Eine Umgebungsvariable (auch bekannt als „**env var**“) ist eine Variable, die **außerhalb** des Python-Codes im **Betriebssystem** lebt und von Ihrem Python-Code (oder auch von anderen Programmen) gelesen werden kann. +## Mehr erfahren { #learn-more } -Umgebungsvariablen können nützlich sein, um **Einstellungen** der Anwendung zu handhaben, als Teil der **Installation** von Python usw. - -## Umgebungsvariablen erstellen und verwenden { #create-and-use-env-vars } - -Sie können Umgebungsvariablen in der **Shell (Terminal)** **erstellen** und verwenden, ohne Python zu benötigen: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// Sie können eine Umgebungsvariable MY_NAME erstellen mit -$ export MY_NAME="Wade Wilson" - -// Dann können Sie sie mit anderen Programmen verwenden, etwa -$ echo "Hello $MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// Erstellen Sie eine Umgebungsvariable MY_NAME -$ $Env:MY_NAME = "Wade Wilson" - -// Verwenden Sie sie mit anderen Programmen, etwa -$ echo "Hello $Env:MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -## Umgebungsvariablen in Python lesen { #read-env-vars-in-python } - -Sie können auch Umgebungsvariablen **außerhalb** von Python erstellen, im Terminal (oder mit jeder anderen Methode) und sie dann **in Python** lesen. - -Zum Beispiel könnten Sie eine Datei `main.py` haben mit: - -```Python hl_lines="3" -import os - -name = os.getenv("MY_NAME", "World") -print(f"Hello {name} from Python") -``` - -/// tip | Tipp - -Das zweite Argument von [`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) ist der Defaultwert, der zurückgegeben wird. - -Wenn er nicht angegeben wird, ist er standardmäßig `None`. Hier geben wir `"World"` als den zu verwendenden Defaultwert an. - -/// - -Dann könnten Sie das Python-Programm aufrufen: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// Hier setzen wir die Umgebungsvariable noch nicht -$ python main.py - -// Da wir die Umgebungsvariable nicht gesetzt haben, erhalten wir den Defaultwert - -Hello World from Python - -// Aber wenn wir zuerst eine Umgebungsvariable erstellen -$ export MY_NAME="Wade Wilson" - -// Und dann das Programm erneut aufrufen -$ python main.py - -// Jetzt kann es die Umgebungsvariable lesen - -Hello Wade Wilson from Python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// Hier setzen wir die Umgebungsvariable noch nicht -$ python main.py - -// Da wir die Umgebungsvariable nicht gesetzt haben, erhalten wir den Defaultwert - -Hello World from Python - -// Aber wenn wir zuerst eine Umgebungsvariable erstellen -$ $Env:MY_NAME = "Wade Wilson" - -// Und dann das Programm erneut aufrufen -$ python main.py - -// Jetzt kann es die Umgebungsvariable lesen - -Hello Wade Wilson from Python -``` - -
- -//// - -Da Umgebungsvariablen außerhalb des Codes gesetzt werden können, aber vom Code gelesen werden können und nicht mit den restlichen Dateien gespeichert (in `git` committet) werden müssen, werden sie häufig für Konfigurationen oder **Einstellungen** verwendet. - -Sie können auch eine Umgebungsvariable nur für einen **spezifischen Programmaufruf** erstellen, die nur für dieses Programm und nur für dessen Dauer verfügbar ist. - -Um dies zu tun, erstellen Sie sie direkt vor dem Programmaufruf, in derselben Zeile: - -
- -```console -// Erstellen Sie eine Umgebungsvariable MY_NAME in der Zeile für diesen Programmaufruf -$ MY_NAME="Wade Wilson" python main.py - -// Jetzt kann es die Umgebungsvariable lesen - -Hello Wade Wilson from Python - -// Die Umgebungsvariable existiert danach nicht mehr -$ python main.py - -Hello World from Python -``` - -
- -/// tip | Tipp - -Sie können mehr darüber lesen auf [The Twelve-Factor App: Config](https://12factor.net/config). - -/// - -## Typen und Validierung { #types-and-validation } - -Diese Umgebungsvariablen können nur **Textstrings** handhaben, da sie extern zu Python sind und kompatibel mit anderen Programmen und dem Rest des Systems (und sogar mit verschiedenen Betriebssystemen, wie Linux, Windows, macOS) sein müssen. - -Das bedeutet, dass **jeder Wert**, der in Python von einer Umgebungsvariablen gelesen wird, **ein `str` sein wird**, und jede Konvertierung in einen anderen Typ oder jede Validierung muss im Code vorgenommen werden. - -Sie werden mehr darüber lernen, wie man Umgebungsvariablen zur Handhabung von **Anwendungseinstellungen** verwendet, im [Handbuch für fortgeschrittene Benutzer – Einstellungen und Umgebungsvariablen](./advanced/settings.md). - -## `PATH`-Umgebungsvariable { #path-environment-variable } - -Es gibt eine **spezielle** Umgebungsvariable namens **`PATH`**, die von den Betriebssystemen (Linux, macOS, Windows) verwendet wird, um Programme zu finden, die ausgeführt werden sollen. - -Der Wert der Variable `PATH` ist ein langer String, der aus Verzeichnissen besteht, die auf Linux und macOS durch einen Doppelpunkt `:` und auf Windows durch ein Semikolon `;` getrennt sind. - -Zum Beispiel könnte die `PATH`-Umgebungsvariable so aussehen: - -//// tab | Linux, macOS - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -Das bedeutet, dass das System nach Programmen in den Verzeichnissen suchen sollte: - -* `/usr/local/bin` -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32 -``` - -Das bedeutet, dass das System nach Programmen in den Verzeichnissen suchen sollte: - -* `C:\Program Files\Python312\Scripts` -* `C:\Program Files\Python312` -* `C:\Windows\System32` - -//// - -Wenn Sie einen **Befehl** im Terminal eingeben, **sucht** das Betriebssystem nach dem Programm in **jedem dieser Verzeichnisse**, die in der `PATH`-Umgebungsvariablen aufgeführt sind. - -Zum Beispiel, wenn Sie `python` im Terminal eingeben, sucht das Betriebssystem nach einem Programm namens `python` im **ersten Verzeichnis** in dieser Liste. - -Wenn es es findet, wird es **benutzt**. Andernfalls sucht es weiter in den **anderen Verzeichnissen**. - -### Python installieren und den `PATH` aktualisieren { #installing-python-and-updating-the-path } - -Wenn Sie Python installieren, könnten Sie gefragt werden, ob Sie die `PATH`-Umgebungsvariable aktualisieren möchten. - -//// tab | Linux, macOS - -Angenommen, Sie installieren Python und es landet in einem Verzeichnis `/opt/custompython/bin`. - -Wenn Sie erlauben, die `PATH`-Umgebungsvariable zu aktualisieren, fügt der Installer `/opt/custompython/bin` zur `PATH`-Umgebungsvariable hinzu. - -Das könnte so aussehen: - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin -``` - -Auf diese Weise, wenn Sie `python` im Terminal eingeben, findet das System das Python-Programm in `/opt/custompython/bin` (das letzte Verzeichnis) und verwendet dieses. - -//// - -//// tab | Windows - -Angenommen, Sie installieren Python und es landet in einem Verzeichnis `C:\opt\custompython\bin`. - -Wenn Sie erlauben, die `PATH`-Umgebungsvariable zu aktualisieren, fügt der Installer `C:\opt\custompython\bin` zur `PATH`-Umgebungsvariable hinzu. - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin -``` - -Auf diese Weise, wenn Sie `python` im Terminal eingeben, findet das System das Python-Programm in `C:\opt\custompython\bin` (das letzte Verzeichnis) und verwendet dieses. - -//// - -Also, wenn Sie tippen: - -
- -```console -$ python -``` - -
- -//// tab | Linux, macOS - -Das System wird das `python`-Programm in `/opt/custompython/bin` **finden** und es ausführen. - -Es wäre ungefähr gleichbedeutend mit der Eingabe von: - -
- -```console -$ /opt/custompython/bin/python -``` - -
- -//// - -//// tab | Windows - -Das System wird das `python`-Programm in `C:\opt\custompython\bin\python` **finden** und es ausführen. - -Es wäre ungefähr gleichbedeutend mit der Eingabe von: - -
- -```console -$ C:\opt\custompython\bin\python -``` - -
- -//// - -Diese Informationen werden nützlich sein, wenn Sie über [Virtuelle Umgebungen](virtual-environments.md) lernen. - -## Fazit { #conclusion } - -Mit diesem Wissen sollten Sie ein grundlegendes Verständnis davon haben, was **Umgebungsvariablen** sind und wie man sie in Python verwendet. - -Sie können auch mehr darüber in der [Wikipedia zu Umgebungsvariablen](https://en.wikipedia.org/wiki/Environment_variable) lesen. - -In vielen Fällen ist es nicht sehr offensichtlich, wie Umgebungsvariablen nützlich und sofort anwendbar sein könnten. Aber sie tauchen immer wieder in vielen verschiedenen Szenarien auf, wenn Sie entwickeln, deshalb ist es gut, darüber Bescheid zu wissen. - -Zum Beispiel werden Sie diese Informationen im nächsten Abschnitt über [Virtuelle Umgebungen](virtual-environments.md) benötigen. +Lesen Sie den [Leitfaden zu Umgebungsvariablen](https://tiangolo.com/guides/environment-variables/) für eine detaillierte, plattformübergreifende Erklärung, einschließlich der Erstellung und des Lesens von Umgebungsvariablen und wie die `PATH`-Umgebungsvariable funktioniert. diff --git a/docs/de/docs/fastapi-cli.md b/docs/de/docs/fastapi-cli.md index 4202501..ddb543d 100644 --- a/docs/de/docs/fastapi-cli.md +++ b/docs/de/docs/fastapi-cli.md @@ -2,7 +2,7 @@ **FastAPI CLI** ist ein Kommandozeilenprogramm, mit dem Sie Ihre FastAPI-App bereitstellen, Ihr FastAPI-Projekt verwalten und mehr. -Wenn Sie FastAPI installieren (z. B. mit `pip install "fastapi[standard]"`), erhalten Sie ein Kommandozeilenprogramm, das Sie im Terminal ausführen können. +Wenn Sie FastAPI zu Ihrem Projekt hinzufügen (z. B. mit `uv add "fastapi[standard]"`), erhalten Sie ein Kommandozeilenprogramm, das Sie im Terminal ausführen können. Um Ihre FastAPI-App für die Entwicklung auszuführen, können Sie den Befehl `fastapi dev` verwenden: @@ -52,7 +52,7 @@ Für die Produktion würden Sie statt `fastapi dev` `fastapi run` verwenden. /// -Intern verwendet das **FastAPI CLI** [Uvicorn](https://www.uvicorn.dev), einen leistungsstarken, produktionsreifen, ASGI-Server. 😎 +Intern verwendet das **FastAPI CLI** [Uvicorn](https://uvicorn.dev), einen leistungsstarken, produktionsreifen, ASGI-Server. 😎 Das `fastapi`-CLI versucht automatisch, die auszuführende FastAPI-App zu erkennen, und geht davon aus, dass es sich um ein Objekt namens `app` in einer Datei `main.py` handelt (oder ein paar weitere Varianten). @@ -100,13 +100,13 @@ from backend.main import app Sie können auch den Dateipfad an den Befehl `fastapi dev` übergeben, dann wird das zu verwendende FastAPI-App-Objekt erraten: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` Oder Sie können auch die Option `--entrypoint` an den Befehl `fastapi dev` übergeben: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` Aber Sie müssten sich merken, bei jedem Aufruf des `fastapi`-Befehls den korrekten Pfad\entrypoint zu übergeben. @@ -119,6 +119,10 @@ Das Ausführen von `fastapi dev` startet den Entwicklermodus. Standardmäßig ist **Autoreload** aktiviert, das den Server automatisch neu lädt, wenn Sie Änderungen an Ihrem Code vornehmen. Dies ist ressourcenintensiv und könnte weniger stabil sein als wenn es deaktiviert ist. Sie sollten es nur für die Entwicklung verwenden. Es horcht auch auf der IP-Adresse `127.0.0.1`, die die IP für Ihre Maschine ist, um nur mit sich selbst zu kommunizieren (`localhost`). +Vor dem Importieren Ihrer App setzt `fastapi dev` die Umgebungsvariable `FASTAPI_ENV` auf `development`. Wenn `FASTAPI_ENV` bereits gesetzt ist, bleibt der vorhandene Wert erhalten. Dadurch kann App-Startup-Code entwicklungsfreundliches Verhalten wählen, während Sie eine app-spezifische Umgebung wie `staging` bereitstellen können. + +Die konventionellen `FASTAPI_ENV`-Werte sind `development` und `production`. `fastapi run` lässt `FASTAPI_ENV` derzeit unverändert, setzen Sie es also explizit, wenn Ihre App den Produktionsmodus erkennen muss. + ## `fastapi run` { #fastapi-run } Das Ausführen von `fastapi run` startet FastAPI im Produktionsmodus. diff --git a/docs/de/docs/features.md b/docs/de/docs/features.md index f24ec24..892bf1e 100644 --- a/docs/de/docs/features.md +++ b/docs/de/docs/features.md @@ -19,15 +19,15 @@ Interaktive API-Dokumentation und erkundbare Web-Benutzeroberflächen. Da das Fr ![Swagger UI Interaktion](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* Alternative API-Dokumentation mit [**ReDoc**](https://github.com/Rebilly/ReDoc). +* Alternative API-Dokumentation mit [**ReDoc**](https://github.com/Redocly/redoc). ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) ### Nur modernes Python { #just-modern-python } -Alles basiert auf Standard-**Python-Typ**deklarationen (dank Pydantic). Es muss keine neue Syntax gelernt werden, nur standardisiertes modernes Python. +Alles basiert auf Standard-**Python-Typ**deklarationen (dank Pydantic). Es muss keine neue Syntax gelernt werden. Nur modernes Standard-Python. -Wenn Sie eine zweiminütige Auffrischung benötigen, wie man Python-Typen verwendet (auch wenn Sie FastAPI nicht benutzen), schauen Sie sich das kurze Tutorial an: [Einführung in Python-Typen](python-types.md). +Wenn Sie eine zweiminütige Auffrischung benötigen, wie man Python-Typen verwendet (auch wenn Sie FastAPI nicht benutzen), schauen Sie sich das kurze Tutorial an: [Python-Typen](python-types.md). Sie schreiben Standard-Python mit Typen: @@ -140,7 +140,7 @@ FastAPI enthält ein extrem einfach zu verwendendes, aber extrem mächtiges ORMs, ODMs für Datenbanken. +Inklusive externer Bibliotheken, die auf Pydantic basieren, wie ORMs und ODMs für Datenbanken. -Daher können Sie in vielen Fällen das Objekt eines Requests **direkt zur Datenbank** schicken, weil alles automatisch validiert wird. +Das bedeutet auch, dass Sie in vielen Fällen dasselbe Objekt, das Sie von einem Request erhalten, **direkt an die Datenbank** übergeben können, da alles automatisch validiert wird. -Das gleiche gilt auch für die andere Richtung: Sie können in vielen Fällen das Objekt aus der Datenbank **direkt zum Client** senden. +Das Gleiche gilt auch umgekehrt: In vielen Fällen können Sie einfach das Objekt, das Sie aus der Datenbank erhalten, **direkt an den Client** übergeben. Mit **FastAPI** bekommen Sie alle Funktionen von **Pydantic** (da FastAPI für die gesamte Datenverarbeitung Pydantic nutzt): diff --git a/docs/de/docs/help-fastapi.md b/docs/de/docs/help-fastapi.md index 4a86875..94ad796 100644 --- a/docs/de/docs/help-fastapi.md +++ b/docs/de/docs/help-fastapi.md @@ -46,20 +46,6 @@ Sie können [mir (Sebastián Ramírez / `tiangolo`)](https://tiangolo.com), dem * [@tiangolo.com auf **Bluesky**](https://bsky.app/profile/tiangolo.com) * [@tiangolo auf **LinkedIn**](https://www.linkedin.com/in/tiangolo/). -## Anderen bei Fragen auf GitHub helfen { #help-others-with-questions-in-github } - -Sie können versuchen, anderen bei ihren Fragen in [GitHub-Diskussionen](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered) zu helfen. - -In vielen Fällen kennen Sie möglicherweise bereits die Antwort auf diese Fragen. 🤓 - -Wenn Sie vielen Menschen bei ihren Fragen helfen, werden Sie offizieller [FastAPI-Experte](fastapi-people.md#fastapi-experts). 🎉 - -Denken Sie daran, der wichtigste Punkt ist: Versuchen Sie, freundlich zu sein. 🤗 - -### So helfen { #how-to-help } - -Folgen Sie der [Anleitung, wie Sie helfen können](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github) hier. - ## Fragen stellen { #ask-questions } Sie können im GitHub-Repository [eine neue Frage erstellen](https://github.com/fastapi/fastapi/discussions/new?category=questions), zum Beispiel um: @@ -69,7 +55,7 @@ Sie können im GitHub-Repository [eine neue Frage erstellen](https://github.com/ ## Am Chat teilnehmen { #join-the-chat } -Treten Sie dem 👥 [Discord-Chatserver](https://discord.gg/VQjSZaeJmf) 👥 bei und treffen Sie sich mit anderen Mitgliedern der FastAPI-Community. +Treten Sie dem 👥 [Discord-Chatserver](https://discord.com/invite/VQjSZaeJmf) 👥 bei und treffen Sie sich mit anderen Mitgliedern der FastAPI-Community. /// tip | Tipp @@ -86,3 +72,9 @@ Bedenken Sie, dass Sie in Chats, die „freie Konversation“ erlauben, leicht F Auf GitHub hilft Ihnen die Vorlage dabei, die richtige Frage zu stellen, sodass Sie leichter eine gute Antwort erhalten können, oder sogar das Problem selbst lösen, bevor Sie überhaupt fragen. Unterhaltungen in den Chat-Systemen sind auch nicht so leicht durchsuchbar wie auf GitHub, sie gehen verloren. + +## FastAPI Cloud ausprobieren { #try-fastapi-cloud } + +Die Hauptfinanzierung für FastAPI und Freunde kommt von [**FastAPI Cloud**](https://fastapicloud.com), einer Plattform, um FastAPI-Anwendungen auf einfache und schnelle Weise zu deployen, mit einem einzigen Kommando, `fastapi deploy`. + +FastAPI Cloud wird vom selben Team hinter FastAPI entwickelt. Sie können es ausprobieren und für Ihre Projekte in Betracht ziehen. diff --git a/docs/de/docs/history-design-future.md b/docs/de/docs/history-design-future.md index 5984274..41dd3dd 100644 --- a/docs/de/docs/history-design-future.md +++ b/docs/de/docs/history-design-future.md @@ -54,11 +54,11 @@ Alles auf eine Weise, die allen Entwicklern das beste Entwicklungserlebnis bot. ## Anforderungen { #requirements } -Nachdem ich mehrere Alternativen getestet hatte, entschied ich, dass ich [**Pydantic**](https://docs.pydantic.dev/) wegen seiner Vorteile verwenden würde. +Nachdem ich mehrere Alternativen getestet hatte, entschied ich, dass ich [**Pydantic**](https://pydantic.dev/docs/) wegen seiner Vorteile verwenden würde. Dann habe ich zu dessen Code beigetragen, um es vollständig mit JSON Schema kompatibel zu machen, und so verschiedene Möglichkeiten zum Definieren von einschränkenden Deklarationen (Constraints) zu unterstützen, und die Editorunterstützung (Typprüfungen, Codevervollständigung) zu verbessern, basierend auf den Tests in mehreren Editoren. -Während der Entwicklung habe ich auch zu [**Starlette**](https://www.starlette.dev/) beigetragen, die andere Schlüsselanforderung. +Während der Entwicklung habe ich auch zu [**Starlette**](https://starlette.dev/) beigetragen, die andere Schlüsselanforderung. ## Entwicklung { #development } diff --git a/docs/de/docs/how-to/custom-request-and-route.md b/docs/de/docs/how-to/custom-request-and-route.md index 60fe71e..4add729 100644 --- a/docs/de/docs/how-to/custom-request-and-route.md +++ b/docs/de/docs/how-to/custom-request-and-route.md @@ -1,6 +1,5 @@ # Benutzerdefinierte Request- und APIRoute-Klasse { #custom-request-and-apiroute-class } - In einigen Fällen möchten Sie möglicherweise die von den Klassen `Request` und `APIRoute` verwendete Logik überschreiben. Das kann insbesondere eine gute Alternative zur Logik in einer Middleware sein. @@ -67,7 +66,7 @@ Das `scope`-`dict` und die `receive`-Funktion sind beide Teil der ASGI-Spezifika Und diese beiden Dinge, `scope` und `receive`, werden benötigt, um eine neue `Request`-Instanz zu erstellen. -Um mehr über den `Request` zu erfahren, schauen Sie sich [Starlettes Dokumentation zu Requests](https://www.starlette.dev/requests/) an. +Um mehr über den `Request` zu erfahren, schauen Sie sich [Starlettes Dokumentation zu Requests](https://starlette.dev/requests/) an. /// diff --git a/docs/de/docs/how-to/extending-openapi.md b/docs/de/docs/how-to/extending-openapi.md index 2382411..f3dcfbb 100644 --- a/docs/de/docs/how-to/extending-openapi.md +++ b/docs/de/docs/how-to/extending-openapi.md @@ -45,7 +45,7 @@ Der Parameter `summary` ist in OpenAPI 3.1.0 und höher verfügbar und wird von Mithilfe der oben genannten Informationen können Sie dieselbe Hilfsfunktion verwenden, um das OpenAPI-Schema zu generieren und jeden benötigten Teil zu überschreiben. -Fügen wir beispielsweise [ReDocs OpenAPI-Erweiterung zum Einbinden eines benutzerdefinierten Logos](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo) hinzu. +Fügen wir beispielsweise [ReDocs OpenAPI-Erweiterung zum Einbinden eines benutzerdefinierten Logos](https://github.com/Redocly/redoc/blob/main/docs/redoc-vendor-extensions.md#x-logo) hinzu. ### Normales **FastAPI** { #normal-fastapi } diff --git a/docs/de/docs/how-to/graphql.md b/docs/de/docs/how-to/graphql.md index cb1891b..7ffae39 100644 --- a/docs/de/docs/how-to/graphql.md +++ b/docs/de/docs/how-to/graphql.md @@ -22,7 +22,7 @@ Hier sind einige der **GraphQL**-Bibliotheken, die **ASGI**-Unterstützung haben * [Strawberry](https://strawberry.rocks/) 🍓 * Mit [Dokumentation für FastAPI](https://strawberry.rocks/docs/integrations/fastapi) * [Ariadne](https://ariadnegraphql.org/) - * Mit [Dokumentation für FastAPI](https://ariadnegraphql.org/docs/fastapi-integration) + * Mit [Dokumentation für FastAPI](https://ariadnegraphql.org/server/Integrations/fastapi-integration) * [Tartiflette](https://tartiflette.io/) * Mit [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) für ASGI-Integration * [Graphene](https://graphene-python.org/) diff --git a/docs/de/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/de/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index 5ea3b95..820cdb2 100644 --- a/docs/de/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/de/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -24,7 +24,7 @@ Wenn Sie eine ältere FastAPI-App mit Pydantic v1 haben, zeige ich Ihnen hier, w ## Offizieller Leitfaden { #official-guide } -Pydantic hat einen offiziellen [Migrationsleitfaden](https://docs.pydantic.dev/latest/migration/) von v1 zu v2. +Pydantic hat einen offiziellen [Migrationsleitfaden](https://pydantic.dev/docs/validation/latest/get-started/migration/) von v1 zu v2. Er enthält auch, was sich geändert hat, wie Validierungen nun korrekter und strikter sind, mögliche Stolpersteine, usw. diff --git a/docs/de/docs/index.md b/docs/de/docs/index.md index 9922e76..e35b5f6 100644 --- a/docs/de/docs/index.md +++ b/docs/de/docs/index.md @@ -110,7 +110,7 @@ Seine Schlüssel-Merkmale sind:
-## FastAPI Conf { #fastapi-conf } - -[**FastAPI Conf ’26**](https://fastapiconf.com) findet am **28. Oktober 2026** in **Amsterdam, NL** statt. Alles über FastAPI, direkt von der Quelle. 🎤 - -FastAPI Conf ’26 - 28. Oktober 2026 - Amsterdam, NL - ## FastAPI Mini-Dokumentarfilm { #fastapi-mini-documentary } Es gibt einen [FastAPI-Mini-Dokumentarfilm](https://www.youtube.com/watch?v=mpR8ngthqiE), veröffentlicht Ende 2025, Sie können ihn online ansehen: @@ -175,28 +169,30 @@ Wenn Sie eine CLI FastAPI steht auf den Schultern von Giganten: -* [Starlette](https://www.starlette.dev/) für die Webanteile. -* [Pydantic](https://docs.pydantic.dev/) für die Datenanteile. +* [Starlette](https://starlette.dev/) für die Webanteile. +* [Pydantic](https://pydantic.dev/docs/) für die Datenanteile. ## Installation { #installation } -Erstellen und aktivieren Sie eine [virtuelle Umgebung](https://fastapi.tiangolo.com/de/virtual-environments/) und installieren Sie dann FastAPI: +Installieren Sie zuerst [`uv`](https://docs.astral.sh/uv/getting-started/installation/) und fügen Sie dann FastAPI zu Ihrem Projekt hinzu:
```console -$ pip install "fastapi[standard]" +$ uv add "fastapi[standard]" ---> 100% ```
-**Hinweis**: Stellen Sie sicher, dass Sie „fastapi[standard]“ in Anführungszeichen setzen, damit es in allen Terminals funktioniert. +**Hinweis**: Stellen Sie sicher, dass Sie `"fastapi[standard]"` in Anführungszeichen setzen, damit es in allen Terminals funktioniert. + +Wenn Sie lieber `pip` verwenden, installieren Sie `fastapi[standard]` innerhalb einer virtuellen Umgebung. Siehe die [Installationsanleitung](tutorial/#install-fastapi) für die alternativen Schritte. ## Beispiel { #example } -### Erstellung { #create-it } +### Erstellen { #create-it } Erstellen Sie eine Datei `main.py` mit: @@ -250,7 +246,7 @@ Starten Sie den Server mit:
```console -$ fastapi dev +$ uv run fastapi dev ╭────────── FastAPI CLI - Development mode ───────────╮ │ │ @@ -277,7 +273,7 @@ INFO: Application startup complete.
Über den Befehl fastapi dev ... -Der Befehl `fastapi dev` liest Ihre `main.py`-Datei, erkennt die **FastAPI**-App darin und startet einen Server mit [Uvicorn](https://www.uvicorn.dev). +Der Befehl `fastapi dev` liest Ihre `main.py`-Datei automatisch, erkennt die **FastAPI**-App darin und startet einen Server mit [Uvicorn](https://uvicorn.dev). Standardmäßig wird `fastapi dev` mit aktiviertem Auto-Reload für die lokale Entwicklung gestartet. @@ -314,7 +310,7 @@ Sie sehen die automatische interaktive API-Dokumentation (bereitgestellt von [Sw Und jetzt gehen Sie auf [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc). -Sie sehen die alternative automatische Dokumentation (bereitgestellt von [ReDoc](https://github.com/Rebilly/ReDoc)): +Sie sehen die alternative automatische Dokumentation (bereitgestellt von [ReDoc](https://github.com/Redocly/redoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -497,7 +493,7 @@ Optional können Sie Ihre FastAPI-App mit einem einzigen Befehl in die [FastAPI
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -540,7 +536,7 @@ FastAPI hängt von Pydantic und Starlette ab. ### `standard`-Abhängigkeiten { #standard-dependencies } -Wenn Sie FastAPI mit `pip install "fastapi[standard]"` installieren, kommt es mit der `standard`-Gruppe optionaler Abhängigkeiten: +Wenn Sie FastAPI mit `uv add "fastapi[standard]"` installieren, kommt es mit der `standard`-Gruppe optionaler Abhängigkeiten: Verwendet von Pydantic: @@ -554,17 +550,17 @@ Verwendet von Starlette: Verwendet von FastAPI: -* [`uvicorn`](https://www.uvicorn.dev) – für den Server, der Ihre Anwendung lädt und bereitstellt. Dies umfasst `uvicorn[standard]`, das einige Abhängigkeiten (z. B. `uvloop`) beinhaltet, die für eine Bereitstellung mit hoher Performanz benötigt werden. +* [`uvicorn`](https://uvicorn.dev) – für den Server, der Ihre Anwendung lädt und bereitstellt. Dies umfasst `uvicorn[standard]`, das einige Abhängigkeiten (z. B. `uvloop`) beinhaltet, die für eine Bereitstellung mit hoher Performanz benötigt werden. * `fastapi-cli[standard]` – um den `fastapi`-Befehl bereitzustellen. * Dies beinhaltet `fastapi-cloud-cli`, das es Ihnen ermöglicht, Ihre FastAPI-Anwendung auf [FastAPI Cloud](https://fastapicloud.com) bereitzustellen. ### Ohne `standard`-Abhängigkeiten { #without-standard-dependencies } -Wenn Sie die `standard` optionalen Abhängigkeiten nicht einschließen möchten, können Sie mit `pip install fastapi` statt `pip install "fastapi[standard]"` installieren. +Wenn Sie die `standard` optionalen Abhängigkeiten nicht einschließen möchten, können Sie mit `uv add fastapi` statt `uv add "fastapi[standard]"` installieren. ### Ohne `fastapi-cloud-cli` { #without-fastapi-cloud-cli } -Wenn Sie FastAPI mit den Standardabhängigkeiten, aber ohne das `fastapi-cloud-cli` installieren möchten, können Sie mit `pip install "fastapi[standard-no-fastapi-cloud-cli]"` installieren. +Wenn Sie FastAPI mit den Standardabhängigkeiten, aber ohne das `fastapi-cloud-cli` installieren möchten, können Sie mit `uv add "fastapi[standard-no-fastapi-cloud-cli]"` installieren. ### Zusätzliche optionale Abhängigkeiten { #additional-optional-dependencies } @@ -572,13 +568,13 @@ Es gibt einige zusätzliche Abhängigkeiten, die Sie installieren möchten. Zusätzliche optionale Pydantic-Abhängigkeiten: -* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) – für die Verwaltung von Einstellungen. -* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) – für zusätzliche Typen zur Verwendung mit Pydantic. +* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) – für die Verwaltung von Einstellungen. +* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) – für zusätzliche Typen zur Verwendung mit Pydantic. Zusätzliche optionale FastAPI-Abhängigkeiten: * [`orjson`](https://github.com/ijl/orjson) – erforderlich, wenn Sie `ORJSONResponse` verwenden möchten. -* [`ujson`](https://github.com/esnme/ultrajson) – erforderlich, wenn Sie `UJSONResponse` verwenden möchten. +* [`ujson`](https://github.com/ultrajson/ultrajson) – erforderlich, wenn Sie `UJSONResponse` verwenden möchten. ## Lizenz { #license } diff --git a/docs/de/docs/project-generation.md b/docs/de/docs/project-generation.md index d2dbadb..6c518f6 100644 --- a/docs/de/docs/project-generation.md +++ b/docs/de/docs/project-generation.md @@ -4,13 +4,13 @@ Vorlagen, die normalerweise mit einem bestimmten Setup geliefert werden, sind so Sie können diese Vorlage verwenden, um loszulegen, da sie bereits vieles der anfänglichen Einrichtung, Sicherheit, Datenbank und einige API-Endpunkte für Sie eingerichtet hat. -GitHub-Repository: [Full Stack FastAPI Template](https://github.com/tiangolo/full-stack-fastapi-template) +GitHub-Repository: [Full Stack FastAPI Template](https://github.com/fastapi/full-stack-fastapi-template) ## Full Stack FastAPI Template – Technologiestack und Funktionen { #full-stack-fastapi-template-technology-stack-and-features } - ⚡ [**FastAPI**](https://fastapi.tiangolo.com/de) für die Python-Backend-API. - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) für die Interaktion mit der Python-SQL-Datenbank (ORM). - - 🔍 [Pydantic](https://docs.pydantic.dev), verwendet von FastAPI, für die Datenvalidierung und das Einstellungsmanagement. + - 🔍 [Pydantic](https://pydantic.dev/docs/), verwendet von FastAPI, für die Datenvalidierung und das Einstellungsmanagement. - 💾 [PostgreSQL](https://www.postgresql.org) als SQL-Datenbank. - 🚀 [React](https://react.dev) für das Frontend. - 💃 Verwendung von TypeScript, Hooks, Vite und anderen Teilen eines modernen Frontend-Stacks. diff --git a/docs/de/docs/python-types.md b/docs/de/docs/python-types.md index a67b8b3..2c52fcc 100644 --- a/docs/de/docs/python-types.md +++ b/docs/de/docs/python-types.md @@ -269,7 +269,7 @@ Es bedeutet nicht: „`one_person` ist die **Klasse** namens `Person`“. ## Pydantic-Modelle { #pydantic-models } -[Pydantic](https://docs.pydantic.dev/) ist eine Python-Bibliothek für die Validierung von Daten. +[Pydantic](https://pydantic.dev/docs/) ist eine Python-Bibliothek für die Validierung von Daten. Sie deklarieren die „Form“ der Daten als Klassen mit Attributen. @@ -285,7 +285,7 @@ Ein Beispiel aus der offiziellen Pydantic-Dokumentation: /// note | Hinweis -Um mehr über [Pydantic zu erfahren, schauen Sie sich dessen Dokumentation an](https://docs.pydantic.dev/). +Um mehr über [Pydantic zu erfahren, schauen Sie sich dessen Dokumentation an](https://pydantic.dev/docs/). /// diff --git a/docs/de/docs/tutorial/background-tasks.md b/docs/de/docs/tutorial/background-tasks.md index 7d6c35a..ffd5732 100644 --- a/docs/de/docs/tutorial/background-tasks.md +++ b/docs/de/docs/tutorial/background-tasks.md @@ -63,7 +63,7 @@ Und dann schreibt ein weiterer Hintergrundtask, der in der *Pfadoperation-Funkti ## Technische Details { #technical-details } -Die Klasse `BackgroundTasks` stammt direkt von [`starlette.background`](https://www.starlette.dev/background/). +Die Klasse `BackgroundTasks` stammt direkt von [`starlette.background`](https://starlette.dev/background/). Sie wird direkt in FastAPI importiert/inkludiert, sodass Sie sie von `fastapi` importieren können und vermeiden, versehentlich das alternative `BackgroundTask` (ohne das `s` am Ende) von `starlette.background` zu importieren. @@ -71,7 +71,7 @@ Indem Sie nur `BackgroundTasks` (und nicht `BackgroundTask`) verwenden, ist es d Es ist immer noch möglich, `BackgroundTask` allein in FastAPI zu verwenden, aber Sie müssen das Objekt in Ihrem Code erstellen und eine Starlette-`Response` zurückgeben, die es enthält. -Weitere Details finden Sie in [Starlettes offizieller Dokumentation für Hintergrundtasks](https://www.starlette.dev/background/). +Weitere Details finden Sie in [Starlettes offizieller Dokumentation für Hintergrundtasks](https://starlette.dev/background/). ## Vorbehalt { #caveat } diff --git a/docs/de/docs/tutorial/bigger-applications.md b/docs/de/docs/tutorial/bigger-applications.md index 119f3e8..be4a5f4 100644 --- a/docs/de/docs/tutorial/bigger-applications.md +++ b/docs/de/docs/tutorial/bigger-applications.md @@ -487,7 +487,7 @@ Auf diese Weise weiß der `fastapi`-Befehl, wo er Ihre App findet. Sie könnten auch den Pfad an den Befehl übergeben, etwa: ```console -$ fastapi dev app/main.py +$ uv run fastapi dev app/main.py ``` Aber dann müssten Sie sich jedes Mal, wenn Sie den `fastapi`-Befehl aufrufen, an den korrekten Pfad erinnern. @@ -503,7 +503,7 @@ Führen Sie nun Ihre App aus:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/de/docs/tutorial/body-nested-models.md b/docs/de/docs/tutorial/body-nested-models.md index f95b65e..b12bb76 100644 --- a/docs/de/docs/tutorial/body-nested-models.md +++ b/docs/de/docs/tutorial/body-nested-models.md @@ -96,7 +96,7 @@ Wiederum, nur mit dieser Deklaration erhalten Sie mit **FastAPI**: Abgesehen von normalen einfachen Typen wie `str`, `int`, `float`, usw. können Sie komplexere einfache Typen verwenden, die von `str` erben. -Um alle Optionen kennenzulernen, die Sie haben, schauen Sie sich [Pydantics Typübersicht](https://docs.pydantic.dev/latest/concepts/types/) an. Sie werden einige Beispiele im nächsten Kapitel kennenlernen. +Um alle Optionen kennenzulernen, die Sie haben, schauen Sie sich [Pydantics Typübersicht](https://pydantic.dev/docs/validation/latest/concepts/types/) an. Sie werden einige Beispiele im nächsten Kapitel kennenlernen. Zum Beispiel, da wir im `Image`-Modell ein Feld `url` haben, können wir deklarieren, dass das eine Instanz von Pydantics `HttpUrl` sein soll, anstelle eines `str`: diff --git a/docs/de/docs/tutorial/body.md b/docs/de/docs/tutorial/body.md index 6ced5f7..847762d 100644 --- a/docs/de/docs/tutorial/body.md +++ b/docs/de/docs/tutorial/body.md @@ -6,7 +6,7 @@ Ein **Request**body sind Daten, die vom Clie Ihre API muss fast immer einen **Response**body senden. Aber Clients müssen nicht unbedingt immer **Requestbodys** senden, manchmal fordern sie nur einen Pfad an, vielleicht mit einigen Query-Parametern, aber senden keinen Body. -Um einen **Request**body zu deklarieren, verwenden Sie [Pydantic](https://docs.pydantic.dev/)-Modelle mit all deren Fähigkeiten und Vorzügen. +Um einen **Request**body zu deklarieren, verwenden Sie [Pydantic](https://pydantic.dev/docs/)-Modelle mit all deren Fähigkeiten und Vorzügen. /// note | Hinweis diff --git a/docs/de/docs/tutorial/debugging.md b/docs/de/docs/tutorial/debugging.md index f7949d0..d764fed 100644 --- a/docs/de/docs/tutorial/debugging.md +++ b/docs/de/docs/tutorial/debugging.md @@ -15,7 +15,7 @@ Der Hauptzweck von `__name__ == "__main__"` ist, dass Code ausgeführt wird, wen
```console -$ python myapp.py +$ uv run python myapp.py ```
@@ -35,7 +35,7 @@ Wenn Sie sie mit folgendem Befehl ausführen:
```console -$ python myapp.py +$ uv run python myapp.py ```
@@ -88,7 +88,7 @@ Zum Beispiel können Sie in Visual Studio Code: * Zum „Debug“-Panel gehen. * „Konfiguration hinzufügen ...“ auswählen. -* „Python“ auswählen. +* „Python“ auswählen * Den Debugger mit der Option „`Python: Current File (Integrated Terminal)`“ ausführen. Der Server wird dann mit Ihrem **FastAPI**-Code gestartet, an Ihren Haltepunkten angehalten, usw. diff --git a/docs/de/docs/tutorial/extra-data-types.md b/docs/de/docs/tutorial/extra-data-types.md index d1feab1..38a6f27 100644 --- a/docs/de/docs/tutorial/extra-data-types.md +++ b/docs/de/docs/tutorial/extra-data-types.md @@ -1,6 +1,5 @@ # Zusätzliche Datentypen { #extra-data-types } - Bisher haben Sie gängige Datentypen verwendet, wie zum Beispiel: * `int` @@ -37,7 +36,7 @@ Hier sind einige der zusätzlichen Datentypen, die Sie verwenden können: * `datetime.timedelta`: * Ein Python-`datetime.timedelta`. * Wird in Requests und Responses als `float` der Gesamtsekunden dargestellt. - * Pydantic ermöglicht auch die Darstellung als „ISO 8601 Zeitdifferenz-Kodierung“, [siehe die Dokumentation für weitere Informationen](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers). + * Pydantic ermöglicht auch die Darstellung als „ISO 8601 Zeitdifferenz-Kodierung“, [siehe die Dokumentation für weitere Informationen](https://pydantic.dev/docs/validation/latest/concepts/serialization/#custom-serializers). * `frozenset`: * Wird in Requests und Responses wie ein `set` behandelt: * Bei Requests wird eine Liste gelesen, Duplikate entfernt und in ein `set` umgewandelt. @@ -50,7 +49,7 @@ Hier sind einige der zusätzlichen Datentypen, die Sie verwenden können: * `Decimal`: * Standard-Python-`Decimal`. * In Requests und Responses wird es wie ein `float` behandelt. -* Sie können alle gültigen Pydantic-Datentypen hier überprüfen: [Pydantic-Datentypen](https://docs.pydantic.dev/latest/usage/types/types/). +* Sie können alle gültigen Pydantic-Datentypen hier überprüfen: [Pydantic-Datentypen](https://pydantic.dev/docs/validation/latest/concepts/types/). ## Beispiel { #example } diff --git a/docs/de/docs/tutorial/extra-models.md b/docs/de/docs/tutorial/extra-models.md index 8e0b094..4e8bc24 100644 --- a/docs/de/docs/tutorial/extra-models.md +++ b/docs/de/docs/tutorial/extra-models.md @@ -166,7 +166,7 @@ Um das zu tun, verwenden Sie den Standard-Python-Typhinweis [`typing.Union`](htt /// note | Hinweis -Wenn Sie eine [`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions) definieren, listen Sie den spezifischeren Typ zuerst auf, gefolgt vom weniger spezifischen Typ. Im Beispiel unten steht `PlaneItem` vor `CarItem` in `Union[PlaneItem, CarItem]`. +Wenn Sie eine [`Union`](https://pydantic.dev/docs/validation/latest/concepts/unions/) definieren, listen Sie den spezifischsten Typ zuerst auf, gefolgt vom weniger spezifischen Typ. Im folgenden Beispiel kommt der spezifischere `PlaneItem` vor `CarItem` in `Union[PlaneItem, CarItem]`. /// diff --git a/docs/de/docs/tutorial/first-steps.md b/docs/de/docs/tutorial/first-steps.md index 8e97b5b..04daf41 100644 --- a/docs/de/docs/tutorial/first-steps.md +++ b/docs/de/docs/tutorial/first-steps.md @@ -6,12 +6,18 @@ Die einfachste FastAPI-Datei könnte wie folgt aussehen: Kopieren Sie das in eine Datei `main.py`. +/// tip | Tipp + +FastAPI hat eine [offizielle Erweiterung für VS Code](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (und Cursor), die viele Features bereitstellt, darunter einen Pfadoperation-Explorer, Pfadoperation-Suche, CodeLens-Navigation in Tests (Sprung zur Definition aus Tests) sowie Deployment und Logs von FastAPI Cloud, alles aus Ihrem Editor heraus. + +/// + Starten Sie den Live-Server:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -78,7 +84,7 @@ Sie werden die automatisch erzeugte, interaktive API-Dokumentation sehen (bereit Gehen Sie nun auf [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc). -Dort sehen Sie die alternative, automatische Dokumentation (bereitgestellt durch [ReDoc](https://github.com/Rebilly/ReDoc)): +Dort sehen Sie die alternative, automatische Dokumentation (bereitgestellt durch [ReDoc](https://github.com/Redocly/redoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -185,13 +191,13 @@ from backend.main import app Sie können auch den Dateipfad an den Befehl `fastapi dev` übergeben, und er wird das zu verwendende FastAPI-App-Objekt erraten: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` Oder Sie können die Option `--entrypoint` an den Befehl `fastapi dev` übergeben: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` Aber Sie müssten sich daran erinnern, bei jedem Aufruf des `fastapi`-Befehls den korrekten Pfad\entrypoint zu übergeben. @@ -205,7 +211,7 @@ Sie können optional Ihre FastAPI-App in der [FastAPI Cloud](https://fastapiclou
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -218,7 +224,7 @@ Deploying to FastAPI Cloud... Das CLI erkennt Ihre FastAPI-Anwendung automatisch und deployt sie in die Cloud. Wenn Sie nicht eingeloggt sind, wird Ihr Browser geöffnet, um die Authentifizierung abzuschließen. -Das war's! Jetzt können Sie Ihre App unter dieser URL aufrufen. ✨ +Das war’s! Jetzt können Sie Ihre App unter dieser URL aufrufen. ✨ ## Zusammenfassung, Schritt für Schritt { #recap-step-by-step } @@ -232,7 +238,7 @@ Das war's! Jetzt können Sie Ihre App unter dieser URL aufrufen. ✨ `FastAPI` ist eine Klasse, die direkt von `Starlette` erbt. -Sie können alle [Starlette](https://www.starlette.dev/)-Funktionalitäten auch mit `FastAPI` nutzen. +Sie können alle [Starlette](https://starlette.dev/)-Funktionalitäten auch mit `FastAPI` nutzen. /// @@ -349,7 +355,7 @@ Es steht Ihnen frei, jede Operation (HTTP-Methode) so zu verwenden, wie Sie es m Die hier aufgeführten Informationen dienen als Leitfaden und sind nicht verbindlich. -Wenn Sie beispielsweise GraphQL verwenden, führen Sie normalerweise alle Aktionen nur mit „POST“-Operationen durch. +Wenn Sie beispielsweise GraphQL verwenden, führen Sie normalerweise alle Aktionen nur mit `POST`-Operationen durch. /// diff --git a/docs/de/docs/tutorial/frontend.md b/docs/de/docs/tutorial/frontend.md index 55213e5..91b7119 100644 --- a/docs/de/docs/tutorial/frontend.md +++ b/docs/de/docs/tutorial/frontend.md @@ -52,7 +52,7 @@ Verwenden Sie dafür `fallback="index.html"`: {* ../../docs_src/frontend/tutorial002_py310.py hl[5] *} -**FastAPI** verwendet diesen Fallback nur für `GET`- und `HEAD`-Requests, die wie Browser-Navigation aussehen. Fehlende Dateien wie JavaScript, CSS und Bilder geben weiterhin `404` zurück. +**FastAPI** verwendet diesen Fallback nur für `GET`- und `HEAD`-Requests, die explizit HTML mit `Accept: text/html` oder `Accept: application/xhtml+xml` akzeptieren, wie Browser-Navigationsrequests es normalerweise tun. Fehlende Dateien wie JavaScript, CSS und Bilder geben weiterhin `404` zurück. Requests mit anderen Methoden, wie `POST` oder `PUT`, an Pfade, die nur zum Frontend-Fallback passen, geben ebenfalls `404` zurück. Reguläre **FastAPI**-*Pfadoperationen* haben weiterhin eine höhere Priorität als Frontend-Routen. @@ -106,9 +106,13 @@ Dann geben fehlende Frontend-Pfade das normale `404` zurück. ## Verzeichnis prüfen { #check-directory } -Standardmäßig prüft `app.frontend()`, dass das Verzeichnis existiert, wenn die App erstellt wird. +Standardmäßig verwendet `app.frontend()` `check_dir="auto"`. -Das hilft, Konfigurationsfehler früh zu erkennen. Wenn zum Beispiel das Output-Verzeichnis des Frontend-Builds fehlt, löst **FastAPI** beim Startup einen Fehler aus. +Wenn die `FASTAPI_ENV`-Umgebungsvariable auf `development` gesetzt ist, zeigt **FastAPI** nur eine Warnung an, wenn das Output-Verzeichnis des Frontend-Builds fehlt. Der [`fastapi dev`-Befehl](https://github.com/fastapi/fastapi-cli#fastapi-dev) setzt diese Umgebungsvariable für Sie, wenn sie nicht bereits gesetzt ist. Dadurch können Sie während der Entwicklung das Backend starten, bevor Sie das Frontend bauen oder starten. + +In jeder anderen Umgebung löst **FastAPI** einen Fehler aus, wenn die App erstellt wird. Das hilft, Konfigurationsfehler früh zu erkennen, bevor eine App ohne ihre Frontend-Dateien deployt wird. + +Sie können auch `check_dir=True` setzen, um das Verzeichnis immer zu prüfen, wenn die App erstellt wird. Wenn Ihre Frontend-Dateien später erstellt werden, zum Beispiel durch einen separaten Build-Schritt, nachdem das App-Objekt erstellt wurde, setzen Sie `check_dir=False`: @@ -132,6 +136,8 @@ Frontend-Responses laufen innerhalb der normalen **FastAPI**-Anwendung, daher gi Abhängigkeiten aus der App, aus einem `APIRouter` und aus `include_router()` gelten ebenfalls für Frontend-Responses. Das kann nützlich sein, um ein Frontend mit Cookie-Authentifizierung oder Ähnlichem zu schützen. +Abhängigkeiten können auch Response-Header ändern und Hintergrundtasks hinzufügen, wie bei normalen *Pfadoperationen*. + ## Nur statischer Build-Output { #static-build-output-only } `app.frontend()` liefert Dateien aus, die bereits von Ihrem Frontend-Build generiert wurden. diff --git a/docs/de/docs/tutorial/handling-errors.md b/docs/de/docs/tutorial/handling-errors.md index 17e2767..6fdc2fc 100644 --- a/docs/de/docs/tutorial/handling-errors.md +++ b/docs/de/docs/tutorial/handling-errors.md @@ -81,7 +81,7 @@ Aber falls Sie es für ein fortgeschrittenes Szenario benötigen, können Sie be ## Benutzerdefinierte Exceptionhandler installieren { #install-custom-exception-handlers } -Sie können benutzerdefinierte Exceptionhandler mit [denselben Exception-Werkzeugen von Starlette](https://www.starlette.dev/exceptions/) hinzufügen. +Sie können benutzerdefinierte Exceptionhandler mit [denselben Exception-Werkzeugen von Starlette](https://starlette.dev/exceptions/) hinzufügen. Angenommen, Sie haben eine benutzerdefinierte Exception `UnicornException`, die Sie (oder eine Bibliothek, die Sie verwenden) `raise`n könnten. diff --git a/docs/de/docs/tutorial/index.md b/docs/de/docs/tutorial/index.md index c0f25c9..f19dfa0 100644 --- a/docs/de/docs/tutorial/index.md +++ b/docs/de/docs/tutorial/index.md @@ -1,22 +1,21 @@ # Tutorial – Benutzerhandbuch { #tutorial-user-guide } +This tutorial shows you how to use **FastAPI** with most of its features, step by step. -Dieses Tutorial zeigt Ihnen Schritt für Schritt, wie Sie **FastAPI** mit den meisten seiner Funktionen verwenden können. +Each section gradually builds on the previous ones, but it's structured to separate topics, so that you can go directly to any specific one to solve your specific API needs. -Jeder Abschnitt baut schrittweise auf den vorhergehenden auf, ist jedoch in einzelne Themen gegliedert, sodass Sie direkt zu einem bestimmten Thema übergehen können, um Ihre spezifischen API-Anforderungen zu lösen. - -Es ist auch so gestaltet, dass es als zukünftige Referenz dient, sodass Sie jederzeit zurückkommen und genau das sehen, was Sie benötigen. +It is also built to work as a future reference so you can come back and see exactly what you need. ## Den Code ausführen { #run-the-code } Alle Codeblöcke können kopiert und direkt verwendet werden (es sind tatsächlich getestete Python-Dateien). -Um eines der Beispiele auszuführen, kopieren Sie den Code in eine Datei `main.py`, und starten Sie `fastapi dev`: +Um eines der Beispiele auszuführen, kopieren Sie den Code in eine Datei `main.py`, und starten Sie `fastapi dev` mit `uv run`:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -61,35 +60,75 @@ Die Verwendung in Ihrem eigenen Editor zeigt Ihnen die Vorteile von FastAPI am b ## FastAPI installieren { #install-fastapi } -Der erste Schritt besteht darin, FastAPI zu installieren. +Der erste Schritt besteht darin, Ihr Projekt einzurichten und FastAPI hinzuzufügen. -Stellen Sie sicher, dass Sie eine [virtuelle Umgebung](../virtual-environments.md) erstellen, sie aktivieren und dann **FastAPI installieren**: +Installieren Sie [`uv`](https://docs.astral.sh/uv/getting-started/installation/), erstellen Sie dann ein Projekt und fügen Sie FastAPI hinzu:
```console -$ pip install "fastapi[standard]" +$ uv init awesome-project --bare +$ cd awesome-project +$ uv add "fastapi[standard]" ---> 100% ```
+`uv add` erstellt die virtuelle Umgebung des Projekts in `.venv`, fügt FastAPI zu `pyproject.toml` hinzu und erstellt `uv.lock`, sodass dieselben Packageversionen später installiert werden können. + +/// details | Was diese Befehle tun + +* `uv init`: Erstellt ein neues Python-Projekt. +* `awesome-project`: Erstellt das Projekt in einem neuen Verzeichnis mit diesem Namen. +* `--bare`: Erstellt nur die minimale Datei `pyproject.toml`, ohne eine Beispiel-`main.py`, `README.md` oder andere Dateien zu generieren. Sie erstellen die Anwendungsdateien in den nächsten Schritten dieses Tutorials selbst. + +Dann betritt `cd awesome-project` das neue Projektverzeichnis, bevor FastAPI hinzugefügt wird. + +`uv` verwendet eine kompatible Python-Version, die bereits auf Ihrem System installiert ist, oder lädt bei Bedarf eine herunter. + +Wenn Sie `uv add` ausführen, wählt es kompatible Versionen von FastAPI und aller Packages aus, von denen FastAPI abhängt. Es zeichnet die exakten Versionen in `uv.lock` auf, wodurch es möglich wird, dieselben Packageversionen später auf einem anderen Computer oder beim Deployen der Anwendung zu installieren. + +Das Erstellen oder Aktualisieren dieser Datei wird [**Locking** der Projektabhängigkeiten](https://docs.astral.sh/uv/concepts/projects/sync/) genannt. `uv` erledigt dies automatisch, wenn Sie ein Package hinzufügen. + +/// + +/// details | FastAPI-Installationsoptionen + +Wenn Sie mit `uv add "fastapi[standard]"` installieren, werden einige optionale Standard-Abhängigkeiten mit installiert, einschließlich `fastapi-cloud-cli`, welches Ihnen das Deployment in der [FastAPI Cloud](https://fastapicloud.com) ermöglicht. + +Wenn Sie diese optionalen Abhängigkeiten nicht haben möchten, können Sie stattdessen `uv add fastapi` installieren. + +Wenn Sie die Standard-Abhängigkeiten, aber ohne das `fastapi-cloud-cli` installieren möchten, können Sie mit `uv add "fastapi[standard-no-fastapi-cloud-cli]"` installieren. + +/// + +/// details | Stattdessen `pip` verwenden + +Wenn Sie es bevorzugen, eine virtuelle Umgebung und Packages manuell zu verwalten, erstellen und aktivieren Sie eine virtuelle Umgebung und installieren Sie dann FastAPI mit `pip install "fastapi[standard]"`. + +Lesen Sie den [Leitfaden zu virtuellen Umgebungen](https://tiangolo.com/guides/virtual-environments/) für die detaillierten Schritte. + +/// + +## Skills für AI-Agenten { #ai-agent-skills } + +FastAPI enthält einen offiziellen Skill für AI-Coding-Agenten. Er ist mit dem Package gebündelt, sodass seine Anleitung mit der in Ihrem Projekt installierten FastAPI-Version übereinstimmt und aktualisiert wird, wenn Sie FastAPI aktualisieren. + +Nachdem Sie FastAPI in Ihrem Projekt installiert haben, können Sie den Skill mit Library Skills installieren: + +```bash +uvx library-skills +``` + /// note | Hinweis -Wenn Sie mit `pip install "fastapi[standard]"` installieren, werden einige optionale Standard-Abhängigkeiten mit installiert, einschließlich `fastapi-cloud-cli`, welches Ihnen das Deployment in der [FastAPI Cloud](https://fastapicloud.com) ermöglicht. - -Wenn Sie diese optionalen Abhängigkeiten nicht haben möchten, können Sie stattdessen `pip install fastapi` installieren. - -Wenn Sie die Standard-Abhängigkeiten, aber ohne das `fastapi-cloud-cli` installieren möchten, können Sie mit `pip install "fastapi[standard-no-fastapi-cloud-cli]"` installieren. +`uvx` ist ein Alias für `uv tool run`. Es führt Library Skills in einer temporären, isolierten Umgebung aus, während Library Skills die in Ihrem Projekt installierten Packages scannt. /// -/// tip | Tipp - -FastAPI hat eine [offizielle Erweiterung für VS Code](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (und Cursor), die viele Funktionen bereitstellt, darunter einen Pfadoperation-Explorer, eine Pfadoperation-Suche, CodeLens-Navigation in Tests (zur Definition aus Tests springen) sowie FastAPI-Cloud-Deployment und Logs – alles direkt aus Ihrem Editor. - -/// +Der Skill ist kompatibel mit Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Pi, OpenCode und den meisten anderen Coding-Agenten. Wählen Sie bei Claude Code `.claude/skills`, wenn Sie gefragt werden, wo der Skill installiert werden soll. ## Handbuch für fortgeschrittene Benutzer { #advanced-user-guide } diff --git a/docs/de/docs/tutorial/middleware.md b/docs/de/docs/tutorial/middleware.md index 0e8da4d..c164773 100644 --- a/docs/de/docs/tutorial/middleware.md +++ b/docs/de/docs/tutorial/middleware.md @@ -5,10 +5,10 @@ Sie können Middleware zu **FastAPI**-Anwendungen hinzufügen. Eine „Middleware“ ist eine Funktion, die mit jedem **Request** arbeitet, bevor er von einer bestimmten *Pfadoperation* verarbeitet wird. Und auch mit jeder **Response**, bevor sie zurückgegeben wird. * Sie nimmt jeden **Request** entgegen, der an Ihre Anwendung gesendet wird. -* Sie kann dann etwas mit diesem **Request** tun oder beliebigen Code ausführen. +* Sie kann dann etwas mit diesem **Request** tun oder jeden notwendigen Code ausführen. * Dann gibt sie den **Request** zur Verarbeitung durch den Rest der Anwendung weiter (durch eine bestimmte *Pfadoperation*). * Sie nimmt dann die **Response** entgegen, die von der Anwendung generiert wurde (durch eine bestimmte *Pfadoperation*). -* Sie kann etwas mit dieser **Response** tun oder beliebigen Code ausführen. +* Sie kann etwas mit dieser **Response** tun oder jeden notwendigen Code ausführen. * Dann gibt sie die **Response** zurück. /// note | Technische Details @@ -28,8 +28,8 @@ Die Middleware-Funktion erhält: * Den `request`. * Eine Funktion `call_next`, die den `request` als Parameter erhält. * Diese Funktion gibt den `request` an die entsprechende *Pfadoperation* weiter. - * Dann gibt es die von der entsprechenden *Pfadoperation* generierte `response` zurück. -* Sie können die `response` dann weiter modifizieren, bevor Sie sie zurückgeben. + * Dann gibt sie die von der entsprechenden *Pfadoperation* generierte `response` zurück. +* Sie können die `response` dann weiter ändern, bevor Sie sie zurückgeben. {* ../../docs_src/middleware/tutorial001_py310.py hl[8:9,11,14] *} @@ -37,7 +37,7 @@ Die Middleware-Funktion erhält: Beachten Sie, dass benutzerdefinierte proprietäre Header hinzugefügt werden können [unter Verwendung des `X-`-Präfixes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). -Wenn Sie jedoch benutzerdefinierte Header haben, die ein Client in einem Browser sehen soll, müssen Sie sie zu Ihrer CORS-Konfiguration ([CORS (Cross-Origin Resource Sharing)](cors.md)) hinzufügen, indem Sie den Parameter `expose_headers` verwenden, der in [Starlettes CORS-Dokumentation](https://www.starlette.dev/middleware/#corsmiddleware) dokumentiert ist. +Wenn Sie jedoch benutzerdefinierte Header haben, die ein Client in einem Browser sehen soll, müssen Sie sie zu Ihren CORS-Konfigurationen ([CORS (Cross-Origin Resource Sharing)](cors.md)) hinzufügen, indem Sie den Parameter `expose_headers` verwenden, der in [Starlettes CORS-Dokumentation](https://starlette.dev/middleware/#corsmiddleware) dokumentiert ist. /// @@ -67,7 +67,7 @@ Hier verwenden wir [`time.perf_counter()`](https://docs.python.org/3/library/tim ## Ausführungsreihenfolge bei mehreren Middlewares { #multiple-middleware-execution-order } -Wenn Sie mehrere Middlewares hinzufügen, entweder mit dem `@app.middleware()` Dekorator oder der Methode `app.add_middleware()`, umschließt jede neue Middleware die Anwendung und bildet einen Stapel. Die zuletzt hinzugefügte Middleware ist die *äußerste*, und die erste ist die *innerste*. +Wenn Sie mehrere Middlewares hinzufügen, entweder mit dem `@app.middleware()`-Dekorator oder der Methode `app.add_middleware()`, wrappt jede neue Middleware die Anwendung und bildet einen Stapel. Die zuletzt hinzugefügte Middleware ist die *äußerste*, und die erste ist die *innerste*. Auf dem Requestpfad läuft die *äußerste* Middleware zuerst. @@ -92,4 +92,4 @@ Dieses Stapelverhalten stellt sicher, dass Middlewares in einer vorhersehbaren u Sie können später mehr über andere Middlewares im [Handbuch für fortgeschrittene Benutzer: Fortgeschrittene Middleware](../advanced/middleware.md) lesen. -In der nächsten Sektion erfahren Sie, wie Sie CORS mit einer Middleware behandeln können. +In der nächsten Sektion erfahren Sie, wie Sie CORS mit einer Middleware behandeln können. diff --git a/docs/de/docs/tutorial/path-params.md b/docs/de/docs/tutorial/path-params.md index d462a74..9ec8280 100644 --- a/docs/de/docs/tutorial/path-params.md +++ b/docs/de/docs/tutorial/path-params.md @@ -6,7 +6,7 @@ Sie können Pfad-„Parameter“ oder -„Variablen“ mit der gleichen Syntax d Der Wert des Pfad-Parameters `item_id` wird Ihrer Funktion als das Argument `item_id` übergeben. -Wenn Sie dieses Beispiel ausführen und auf [http://127.0.0.1:8000/items/foo](http://127.0.0.1:8000/items/foo) gehen, sehen Sie als Response: +Wenn Sie also dieses Beispiel ausführen und auf [http://127.0.0.1:8000/items/foo](http://127.0.0.1:8000/items/foo) gehen, sehen Sie als Response: ```JSON {"item_id":"foo"} @@ -14,11 +14,11 @@ Wenn Sie dieses Beispiel ausführen und auf [http://127.0.0.1:8000/items/foo](ht ## Pfad-Parameter mit Typen { #path-parameters-with-types } -Sie können den Typ eines Pfad-Parameters in der Argumentliste der Funktion deklarieren, mit Standard-Python-Typannotationen: +Sie können den Typ eines Pfad-Parameters in der Funktion deklarieren, mit Standard-Python-Typannotationen: {* ../../docs_src/path_params/tutorial002_py310.py hl[7] *} -In diesem Fall wird `item_id` als `int` deklariert, also als Ganzzahl. +In diesem Fall wird `item_id` als `int` deklariert. /// tip | Tipp @@ -36,9 +36,9 @@ Wenn Sie dieses Beispiel ausführen und Ihren Browser unter [http://127.0.0.1:80 /// tip | Tipp -Beachten Sie, dass der Wert, den Ihre Funktion erhält und zurückgibt, die Zahl `3` ist, also ein `int`. Nicht der String „3“, also ein `str`. +Beachten Sie, dass der Wert, den Ihre Funktion erhalten (und zurückgegeben) hat, `3` ist, als Python-`int`, nicht als String `"3"`. -Sprich, mit dieser Typdeklaration wird **FastAPI** den „parsen“. +Sprich, mit dieser Typdeklaration bietet **FastAPI** Ihnen automatisches Request-„Parsing“. /// @@ -62,9 +62,9 @@ Wenn Sie aber im Browser [http://127.0.0.1:8000/items/foo](http://127.0.0.1:8000 } ``` -Der Pfad-Parameter `item_id` hatte den Wert „foo“, was kein `int` ist. +denn der Pfad-Parameter `item_id` hatte den Wert `"foo"`, was kein `int` ist. -Die gleiche Fehlermeldung würde angezeigt werden, wenn Sie ein `float` (also eine Kommazahl) statt eines `int`s übergeben würden, wie etwa in: [http://127.0.0.1:8000/items/4.2](http://127.0.0.1:8000/items/4.2) +Die gleiche Fehlermeldung würde angezeigt werden, wenn Sie ein `float` statt eines `int`s übergeben würden, wie etwa in: [http://127.0.0.1:8000/items/4.2](http://127.0.0.1:8000/items/4.2) /// tip | Tipp @@ -78,101 +78,101 @@ Das ist unglaublich hilfreich, wenn Sie Code entwickeln und debuggen, welcher mi ## Dokumentation { #documentation } -Wenn Sie die Seite [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) in Ihrem Browser öffnen, sehen Sie eine automatische, interaktive API-Dokumentation: +Und wenn Sie die Seite [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) in Ihrem Browser öffnen, sehen Sie eine automatische, interaktive API-Dokumentation wie: /// tip | Tipp -Wiederum, mit dieser gleichen Python-Typdeklaration gibt Ihnen **FastAPI** eine automatische, interaktive Dokumentation (verwendet die Swagger-Benutzeroberfläche). +Wiederum, nur mit dieser gleichen Python-Typdeklaration gibt Ihnen **FastAPI** eine automatische, interaktive Dokumentation (integriert Swagger UI). Beachten Sie, dass der Pfad-Parameter dort als Ganzzahl deklariert ist. /// -## Nützliche Standards, alternative Dokumentation { #standards-based-benefits-alternative-documentation } +## Standardbasierte Vorteile, alternative Dokumentation { #standards-based-benefits-alternative-documentation } -Und weil das generierte Schema vom [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md)-Standard kommt, gibt es viele kompatible Tools. +Und weil das generierte Schema vom [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md)-Standard kommt, gibt es viele kompatible Tools. -Zum Beispiel bietet **FastAPI** selbst eine alternative API-Dokumentation (verwendet ReDoc), welche Sie unter [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) einsehen können: +Aus diesem Grund bietet **FastAPI** selbst eine alternative API-Dokumentation (verwendet ReDoc), welche Sie unter [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) einsehen können: -Und viele weitere kompatible Tools. Inklusive Codegenerierung für viele Sprachen. +Auf die gleiche Weise gibt es viele kompatible Tools. Inklusive Codegenerierungstools für viele Sprachen. ## Pydantic { #pydantic } -Die ganze Datenvalidierung wird hinter den Kulissen von [Pydantic](https://docs.pydantic.dev/) durchgeführt, Sie profitieren also von dessen Vorteilen. Und Sie wissen, dass Sie in guten Händen sind. +Die ganze Datenvalidierung wird hinter den Kulissen von [Pydantic](https://pydantic.dev/docs/) durchgeführt, Sie profitieren also von dessen Vorteilen. Und Sie wissen, dass Sie in guten Händen sind. -Sie können für Typdeklarationen auch `str`, `float`, `bool` und viele andere komplexe Datentypen verwenden. +Sie können die gleichen Typdeklarationen auch mit `str`, `float`, `bool` und vielen anderen komplexen Datentypen verwenden. -Mehrere davon werden wir in den nächsten Kapiteln erkunden. +Mehrere davon werden in den nächsten Kapiteln des Tutorials erkundet. ## Die Reihenfolge ist wichtig { #order-matters } -Wenn Sie *Pfadoperationen* erstellen, haben Sie manchmal einen fixen Pfad. +Wenn Sie *Pfadoperationen* erstellen, haben Sie manchmal Situationen, in denen Sie einen fixen Pfad haben. -Etwa `/users/me`, um Daten über den aktuellen Benutzer zu erhalten. +Etwa `/users/me`, sagen wir, um Daten über den aktuellen Benutzer zu erhalten. -Und Sie haben auch einen Pfad `/users/{user_id}`, um Daten über einen spezifischen Benutzer zu erhalten, mittels einer Benutzer-ID. +Und Sie können auch einen Pfad `/users/{user_id}` haben, um Daten über einen spezifischen Benutzer mittels irgendeiner Benutzer-ID zu erhalten. -Weil *Pfadoperationen* in ihrer Reihenfolge ausgewertet werden, müssen Sie sicherstellen, dass der Pfad `/users/me` vor `/users/{user_id}` deklariert wurde: +Weil *Pfadoperationen* in ihrer Reihenfolge ausgewertet werden, müssen Sie sicherstellen, dass der Pfad für `/users/me` vor dem für `/users/{user_id}` deklariert wurde: {* ../../docs_src/path_params/tutorial003_py310.py hl[6,11] *} -Ansonsten würde der Pfad für `/users/{user_id}` auch `/users/me` auswerten, und annehmen, dass ein Parameter `user_id` mit dem Wert „me“ übergeben wurde. +Ansonsten würde der Pfad für `/users/{user_id}` auch auf `/users/me` passen und „denken“, dass er einen Parameter `user_id` mit dem Wert `"me"` erhält. -Sie können eine Pfadoperation auch nicht erneut definieren: +Ebenso können Sie eine Pfadoperation nicht erneut definieren: {* ../../docs_src/path_params/tutorial003b_py310.py hl[6,11] *} Die erste Definition wird immer verwendet werden, da ihr Pfad zuerst übereinstimmt. -## Vordefinierte Parameterwerte { #predefined-values } +## Vordefinierte Werte { #predefined-values } -Wenn Sie eine *Pfadoperation* haben, welche einen *Pfad-Parameter* hat, aber Sie wollen, dass dessen gültige Werte vordefiniert sind, können Sie ein Standard-Python `Enum` verwenden. +Wenn Sie eine *Pfadoperation* haben, welche einen *Pfad-Parameter* erhält, aber Sie wollen, dass die möglichen gültigen *Pfad-Parameter*-Werte vordefiniert sind, können Sie ein Standard-Python-`Enum` verwenden. ### Eine `Enum`-Klasse erstellen { #create-an-enum-class } Importieren Sie `Enum` und erstellen Sie eine Unterklasse, die von `str` und `Enum` erbt. -Indem Sie von `str` erben, weiß die API-Dokumentation, dass die Werte vom Typ `str` sein müssen, und wird in der Lage sein, korrekt zu rendern. +Indem Sie von `str` erben, weiß die API-Dokumentation, dass die Werte vom Typ `string` sein müssen, und wird in der Lage sein, korrekt zu rendern. -Erstellen Sie dann Klassen-Attribute mit festgelegten Werten, welches die erlaubten Werte sein werden: +Erstellen Sie dann Klassen-Attribute mit festgelegten Werten, welche die verfügbaren gültigen Werte sein werden: {* ../../docs_src/path_params/tutorial005_py310.py hl[1,6:9] *} /// tip | Tipp -Falls Sie sich fragen, was „AlexNet“, „ResNet“ und „LeNet“ ist, das sind Namen von Modellen für maschinelles Lernen. +Falls Sie sich fragen: „AlexNet“, „ResNet“ und „LeNet“ sind nur Namen von Modellen für maschinelles Lernen. /// ### Einen *Pfad-Parameter* deklarieren { #declare-a-path-parameter } -Dann erstellen Sie einen *Pfad-Parameter*, der als Typ die gerade erstellte Enum-Klasse hat (`ModelName`): +Dann erstellen Sie einen *Pfad-Parameter* mit einer Typannotation, welche die von Ihnen erstellte Enum-Klasse (`ModelName`) verwendet: {* ../../docs_src/path_params/tutorial005_py310.py hl[16] *} -### Die API-Dokumentation testen { #check-the-docs } +### Die Dokumentation testen { #check-the-docs } -Weil die erlaubten Werte für den *Pfad-Parameter* nun vordefiniert sind, kann die interaktive Dokumentation sie als Auswahl-Drop-Down anzeigen: +Weil die verfügbaren Werte für den *Pfad-Parameter* nun vordefiniert sind, kann die interaktive Dokumentation diese hübsch anzeigen: ### Mit Python-*Enumerationen* arbeiten { #working-with-python-enumerations } -Der *Pfad-Parameter* wird ein *Member einer Enumeration* sein. +Der Wert des *Pfad-Parameters* wird ein *Member einer Enumeration* sein. #### *Enumeration-Member* vergleichen { #compare-enumeration-members } -Sie können ihn mit einem Member Ihrer Enumeration `ModelName` vergleichen: +Sie können ihn mit dem *Enumeration-Member* in Ihrem erstellten Enum `ModelName` vergleichen: {* ../../docs_src/path_params/tutorial005_py310.py hl[17] *} #### *Enumerations-Wert* erhalten { #get-the-enumeration-value } -Den tatsächlichen Wert (in diesem Fall ein `str`) erhalten Sie via `model_name.value`, oder generell, `your_enum_member.value`: +Den tatsächlichen Wert (in diesem Fall ein `str`) erhalten Sie mittels `model_name.value`, oder generell, `your_enum_member.value`: {* ../../docs_src/path_params/tutorial005_py310.py hl[20] *} @@ -184,13 +184,13 @@ Sie können den Wert `"lenet"` außerdem mittels `ModelName.lenet.value` abrufen #### *Enumeration-Member* zurückgeben { #return-enumeration-members } -Sie können *Enum-Member* in ihrer *Pfadoperation* zurückgeben, sogar verschachtelt in einem JSON-Body (z. B. als `dict`). +Sie können *Enum-Member* von Ihrer *Pfadoperation* zurückgeben, sogar verschachtelt in einem JSON-Body (z. B. als `dict`). -Diese werden zu ihren entsprechenden Werten konvertiert (in diesem Fall Strings), bevor sie zum Client übertragen werden: +Diese werden zu ihren entsprechenden Werten konvertiert (in diesem Fall Strings), bevor sie an den Client zurückgegeben werden: {* ../../docs_src/path_params/tutorial005_py310.py hl[18,21,23] *} -In Ihrem Client erhalten Sie eine JSON-Response, wie etwa: +In Ihrem Client erhalten Sie eine JSON-Response wie: ```JSON { @@ -209,21 +209,21 @@ Sprich, die URL für diese Datei wäre etwas wie: `/files/home/johndoe/myfile.tx ### OpenAPI-Unterstützung { #openapi-support } -OpenAPI bietet nicht die Möglichkeit, dass ein *Pfad-Parameter* seinerseits einen *Pfad* enthalten kann, das würde zu Szenarios führen, die schwierig zu testen und zu definieren sind. +OpenAPI bietet nicht die Möglichkeit, zu deklarieren, dass ein *Pfad-Parameter* in sich einen *Pfad* enthalten kann, da das zu Szenarios führen könnte, die schwierig zu testen und zu definieren sind. Trotzdem können Sie das in **FastAPI** tun, indem Sie eines der internen Tools von Starlette verwenden. -Die Dokumentation würde weiterhin funktionieren, allerdings wird nicht dokumentiert werden, dass der Parameter ein Pfad sein sollte. +Die Dokumentation würde weiterhin funktionieren, allerdings ohne irgendeine Dokumentation hinzuzufügen, die besagt, dass der Parameter einen Pfad enthalten sollte. ### Pfad-Konverter { #path-convertor } -Mittels einer Option direkt von Starlette können Sie einen *Pfad-Parameter* deklarieren, der einen Pfad enthalten soll, indem Sie eine URL wie folgt definieren: +Mittels einer Option direkt von Starlette können Sie einen *Pfad-Parameter* deklarieren, der einen *Pfad* enthält, indem Sie eine URL wie folgt definieren: ``` /files/{file_path:path} ``` -In diesem Fall ist der Name des Parameters `file_path`. Der letzte Teil, `:path`, sagt aus, dass der Parameter ein *Pfad* sein soll. +In diesem Fall ist der Name des Parameters `file_path`, und der letzte Teil, `:path`, sagt ihm, dass der Parameter mit jedem *Pfad* übereinstimmen sollte. Sie verwenden das also wie folgt: @@ -231,7 +231,7 @@ Sie verwenden das also wie folgt: /// tip | Tipp -Der Parameter könnte einen führenden Schrägstrich (`/`) haben, wie etwa in `/home/johndoe/myfile.txt`. +Der Parameter könnte `/home/johndoe/myfile.txt` enthalten müssen, mit einem führenden Schrägstrich (`/`). In dem Fall wäre die URL: `/files//home/johndoe/myfile.txt`, mit einem doppelten Schrägstrich (`//`) zwischen `files` und `home`. @@ -239,13 +239,13 @@ In dem Fall wäre die URL: `/files//home/johndoe/myfile.txt`, mit einem doppelte ## Zusammenfassung { #recap } -In **FastAPI** erhalten Sie mittels kurzer, intuitiver Typdeklarationen: +Mit **FastAPI** erhalten Sie mittels kurzer, intuitiver und Standard-Python-Typdeklarationen: * Editor-Unterstützung: Fehlerprüfungen, Codevervollständigung, usw. * Daten „parsen“ * Datenvalidierung -* API-Annotationen und automatische Dokumentation +* API-Annotation und automatische Dokumentation Und Sie müssen sie nur einmal deklarieren. -Das ist wahrscheinlich der sichtbarste Unterschied zwischen **FastAPI** und alternativen Frameworks (abgesehen von der reinen Performanz). +Das ist wahrscheinlich der wichtigste sichtbare Vorteil von **FastAPI** im Vergleich zu alternativen Frameworks (abgesehen von der rohen Performanz). diff --git a/docs/de/docs/tutorial/query-params-str-validations.md b/docs/de/docs/tutorial/query-params-str-validations.md index bec5f57..09f8b0b 100644 --- a/docs/de/docs/tutorial/query-params-str-validations.md +++ b/docs/de/docs/tutorial/query-params-str-validations.md @@ -369,11 +369,11 @@ Es kann Fälle geben, in denen Sie eine **benutzerdefinierte Validierung** durch In diesen Fällen können Sie eine **benutzerdefinierte Validierungsfunktion** verwenden, die nach der normalen Validierung angewendet wird (z. B. nach der Validierung, dass der Wert ein `str` ist). -Sie können dies mit [Pydantics `AfterValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator) innerhalb von `Annotated` erreichen. +Sie können dies mit [Pydantics `AfterValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-after-validator) innerhalb von `Annotated` erreichen. /// tip | Tipp -Pydantic unterstützt auch [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator) und andere. 🤓 +Pydantic unterstützt auch [`BeforeValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-before-validator) und andere. 🤓 /// diff --git a/docs/de/docs/tutorial/request-files.md b/docs/de/docs/tutorial/request-files.md index 7a34460..59c878c 100644 --- a/docs/de/docs/tutorial/request-files.md +++ b/docs/de/docs/tutorial/request-files.md @@ -6,10 +6,10 @@ Sie können Dateien, die vom Client hochgeladen werden, mithilfe von `File` defi Um hochgeladene Dateien zu empfangen, installieren Sie zuerst [`python-multipart`](https://github.com/Kludex/python-multipart). -Stellen Sie sicher, dass Sie eine [virtuelle Umgebung](../virtual-environments.md) erstellen, sie aktivieren und dann das Paket installieren, zum Beispiel: +Fügen Sie es Ihrem Projekt hinzu: ```console -$ pip install python-multipart +$ uv add python-multipart ``` Das liegt daran, dass hochgeladene Dateien als „Formulardaten“ gesendet werden. @@ -147,7 +147,7 @@ Sie können auch `File()` mit `UploadFile` verwenden, um zum Beispiel zusätzlic ## Mehrere Datei-Uploads { #multiple-file-uploads } -Es ist auch möglich, mehrere Dateien gleichzeitig hochzuladen. +Es ist möglich, mehrere Dateien gleichzeitig hochzuladen. Diese werden demselben „Formularfeld“ zugeordnet, welches mittels „Formulardaten“ gesendet wird. @@ -159,7 +159,7 @@ Sie erhalten, wie deklariert, eine `list` von `bytes` oder `UploadFile`s. /// note | Technische Details -Sie können auch `from starlette.responses import HTMLResponse` verwenden. +Sie könnten auch `from starlette.responses import HTMLResponse` verwenden. **FastAPI** bietet dieselben `starlette.responses` auch via `fastapi.responses` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Responses kommen aber direkt von Starlette. diff --git a/docs/de/docs/tutorial/request-form-models.md b/docs/de/docs/tutorial/request-form-models.md index b40d60d..5da7038 100644 --- a/docs/de/docs/tutorial/request-form-models.md +++ b/docs/de/docs/tutorial/request-form-models.md @@ -6,10 +6,10 @@ Sie können **Pydantic-Modelle** verwenden, um **Formularfelder** in FastAPI zu Um Formulare zu verwenden, installieren Sie zuerst [`python-multipart`](https://github.com/Kludex/python-multipart). -Stellen Sie sicher, dass Sie eine [Virtuelle Umgebung](../virtual-environments.md) erstellen, sie aktivieren und es dann installieren, zum Beispiel: +Fügen Sie es zu Ihrem Projekt hinzu: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// @@ -38,7 +38,7 @@ Sie können dies in der Dokumentations-UI unter `/docs` testen: ## Zusätzliche Formularfelder verbieten { #forbid-extra-form-fields } -In einigen speziellen Anwendungsfällen (wahrscheinlich nicht sehr häufig) möchten Sie möglicherweise die Formularfelder auf nur diejenigen beschränken, die im Pydantic-Modell deklariert sind, und jegliche **zusätzlichen** Felder **verbieten**. +In einigen speziellen Anwendungsfällen (wahrscheinlich nicht sehr häufig) möchten Sie möglicherweise die Formularfelder auf nur diejenigen **beschränken**, die im Pydantic-Modell deklariert sind. Und jegliche **zusätzlichen** Felder **verbieten**. /// note | Hinweis @@ -46,11 +46,11 @@ Dies wird seit FastAPI Version `0.114.0` unterstützt. 🤓 /// -Sie können die Modellkonfiguration von Pydantic verwenden, um jegliche `extra` Felder zu `verbieten`: +Sie können Pydantics Modellkonfiguration verwenden, um jegliche `extra`-Felder auf `forbid` zu setzen: {* ../../docs_src/request_form_models/tutorial002_an_py310.py hl[12] *} -Wenn ein Client versucht, einige zusätzliche Daten zu senden, erhält er eine **Error-Response**. +Wenn ein Client versucht, einige zusätzliche Daten zu senden, erhält er eine **Error**-Response. Zum Beispiel, wenn der Client versucht, folgende Formularfelder zu senden: @@ -58,7 +58,7 @@ Zum Beispiel, wenn der Client versucht, folgende Formularfelder zu senden: * `password`: `Portal Gun` * `extra`: `Mr. Poopybutthole` -erhält er eine Error-Response, die ihm mitteilt, dass das Feld `extra` nicht erlaubt ist: +Er erhält eine Error-Response, die ihm mitteilt, dass das Feld `extra` nicht erlaubt ist: ```json { diff --git a/docs/de/docs/tutorial/request-forms-and-files.md b/docs/de/docs/tutorial/request-forms-and-files.md index 98e5428..b033802 100644 --- a/docs/de/docs/tutorial/request-forms-and-files.md +++ b/docs/de/docs/tutorial/request-forms-and-files.md @@ -1,15 +1,15 @@ # Formulardaten und Dateien im Request { #request-forms-and-files } -Sie können gleichzeitig Dateien und Formulardaten mit `File` und `Form` definieren. +Sie können gleichzeitig Dateien und Formularfelder mit `File` und `Form` definieren. /// note | Hinweis Um hochgeladene Dateien und/oder Formulardaten zu empfangen, installieren Sie zuerst [`python-multipart`](https://github.com/Kludex/python-multipart). -Stellen Sie sicher, dass Sie eine [virtuelle Umgebung](../virtual-environments.md) erstellen, diese aktivieren und es dann installieren, z. B.: +Fügen Sie es Ihrem Projekt hinzu: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/de/docs/tutorial/request-forms.md b/docs/de/docs/tutorial/request-forms.md index aedcd4a..c93945c 100644 --- a/docs/de/docs/tutorial/request-forms.md +++ b/docs/de/docs/tutorial/request-forms.md @@ -7,10 +7,10 @@ Wenn Sie Felder aus Formularen statt JSON empfangen müssen, können Sie `Form` Um Formulare zu verwenden, installieren Sie zuerst [`python-multipart`](https://github.com/Kludex/python-multipart). -Erstellen Sie unbedingt eine [virtuelle Umgebung](../virtual-environments.md), aktivieren Sie diese und installieren Sie dann das Paket, zum Beispiel: +Fügen Sie es Ihrem Projekt hinzu: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/de/docs/tutorial/response-model.md b/docs/de/docs/tutorial/response-model.md index 2b580bd..443f555 100644 --- a/docs/de/docs/tutorial/response-model.md +++ b/docs/de/docs/tutorial/response-model.md @@ -1,8 +1,8 @@ # Responsemodell – Rückgabetyp { #response-model-return-type } -Sie können den Typ der Response deklarieren, indem Sie den **Rückgabetyp** der *Pfadoperation* annotieren. +Sie können den Typ der Response deklarieren, indem Sie den **Rückgabetyp** der *Pfadoperation-Funktion* annotieren. -Hierbei können Sie **Typannotationen** genauso verwenden, wie Sie es bei Werten von Funktions-**Parametern** machen; verwenden Sie Pydantic-Modelle, Listen, Dicts und skalare Werte wie Nummern, Booleans, usw. +Hierbei können Sie **Typannotationen** genauso verwenden, wie Sie es bei Eingabedaten in Funktions-**Parametern** machen; verwenden Sie Pydantic-Modelle, Listen, Dictionaries und skalare Werte wie Integer, Booleans, usw. {* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *} @@ -24,9 +24,9 @@ Aber am wichtigsten: Es gibt Fälle, da möchten oder müssen Sie Daten zurückgeben, die nicht genau dem entsprechen, was der Typ deklariert. -Zum Beispiel könnten Sie **ein Dictionary zurückgeben** wollen, oder ein Datenbank-Objekt, aber **es als Pydantic-Modell deklarieren**. Auf diese Weise übernimmt das Pydantic-Modell alle Datendokumentation, -validierung, usw. für das Objekt, welches Sie zurückgeben (z. B. ein Dictionary oder ein Datenbank-Objekt). +Zum Beispiel könnten Sie **ein Dictionary zurückgeben** wollen, oder ein Datenbankobjekt, aber **es als Pydantic-Modell deklarieren**. Auf diese Weise übernimmt das Pydantic-Modell alle Datendokumentation, -validierung, usw. für das Objekt, welches Sie zurückgeben (z. B. ein Dictionary oder ein Datenbankobjekt). -Würden Sie eine hierfür eine Rückgabetyp-Annotation verwenden, dann würden Tools und Editoren (korrekterweise) Fehler ausgeben, die Ihnen sagen, dass Ihre Funktion einen Typ zurückgibt (z. B. ein Dict), der sich unterscheidet von dem, was Sie deklariert haben (z. B. ein Pydantic-Modell). +Würden Sie eine Rückgabetyp-Annotation hinzufügen, dann würden Tools und Editoren (korrekterweise) Fehler ausgeben, die Ihnen sagen, dass Ihre Funktion einen Typ zurückgibt (z. B. ein Dict), der sich unterscheidet von dem, was Sie deklariert haben (z. B. ein Pydantic-Modell). In solchen Fällen können Sie statt des Rückgabetyps den **Pfadoperation-Dekorator**-Parameter `response_model` verwenden. @@ -42,17 +42,17 @@ Sie können `response_model` in jeder möglichen *Pfadoperation* verwenden: /// note | Hinweis -Beachten Sie, dass `response_model` ein Parameter der „Dekorator“-Methode ist (`get`, `post`, usw.). Nicht der *Pfadoperation-Funktion*, so wie die anderen Parameter und der Body. +Beachten Sie, dass `response_model` ein Parameter der „Dekorator“-Methode ist (`get`, `post`, usw.). Nicht Ihrer *Pfadoperation-Funktion*, so wie alle Parameter und der Body. /// -`response_model` nimmt denselben Typ entgegen, den Sie auch für ein Pydantic-Modellfeld deklarieren würden, also etwa ein Pydantic-Modell, aber es kann auch z. B. eine `list`e von Pydantic-Modellen sein, wie etwa `List[Item]`. +`response_model` nimmt denselben Typ entgegen, den Sie auch für ein Pydantic-Modellfeld deklarieren würden, also etwa ein Pydantic-Modell, aber es kann auch z. B. eine `list` von Pydantic-Modellen sein, wie etwa `List[Item]`. FastAPI wird dieses `response_model` nehmen, um die Daten zu dokumentieren, validieren, usw. und auch, um **die Ausgabedaten** entsprechend der Typdeklaration **zu konvertieren und filtern**. /// tip | Tipp -Wenn Sie in Ihrem Editor strikte Typchecks haben, mypy, usw., können Sie den Funktions-Rückgabetyp als `Any` deklarieren. +Wenn Sie in Ihrem Editor strikte Typchecks haben, mypy, usw., können Sie den Funktions-Rückgabetyp als `Any` deklarieren. So sagen Sie dem Editor, dass Sie absichtlich *irgendetwas* zurückgeben. Aber FastAPI wird trotzdem die Dokumentation, Validierung, Filterung, usw. der Daten übernehmen, via `response_model`. @@ -60,11 +60,11 @@ So sagen Sie dem Editor, dass Sie absichtlich *irgendetwas* zurückgeben. Aber F ### `response_model`-Priorität { #response-model-priority } -Wenn sowohl Rückgabetyp als auch `response_model` deklariert sind, hat `response_model` die Priorität und wird von FastAPI bevorzugt verwendet. +Wenn sowohl Rückgabetyp als auch `response_model` deklariert sind, hat `response_model` die Priorität und wird von FastAPI verwendet. -So können Sie korrekte Typannotationen zu Ihrer Funktion hinzufügen, die von Ihrem Editor und Tools wie mypy verwendet werden. Und dennoch übernimmt FastAPI die Validierung und Dokumentation, usw., der Daten anhand von `response_model`. +So können Sie korrekte Typannotationen zu Ihren Funktionen hinzufügen, selbst wenn Sie einen anderen Typ als das Responsemodell zurückgeben, die von Ihrem Editor und Tools wie mypy verwendet werden. Und dennoch übernimmt FastAPI die Validierung und Dokumentation, usw., der Daten anhand von `response_model`. -Sie können auch `response_model=None` verwenden, um das Erstellen eines Responsemodells für diese *Pfadoperation* zu unterbinden. Sie könnten das tun wollen, wenn Sie Dinge annotieren, die nicht gültige Pydantic-Felder sind. Ein Beispiel dazu werden Sie in einer der Abschnitte unten sehen. +Sie können auch `response_model=None` verwenden, um das Erstellen eines Responsemodells für diese *Pfadoperation* zu unterbinden. Sie könnten das tun müssen, wenn Sie Typannotationen für Dinge hinzufügen, die keine gültigen Pydantic-Felder sind. Ein Beispiel dazu werden Sie in einem der Abschnitte unten sehen. ## Dieselben Eingabedaten zurückgeben { #return-the-same-input-data } @@ -76,16 +76,16 @@ Im Folgenden deklarieren wir ein `UserIn`-Modell; es enthält ein Klartext-Passw Um `EmailStr` zu verwenden, installieren Sie zuerst [`email-validator`](https://github.com/JoshData/python-email-validator). -Stellen Sie sicher, dass Sie eine [virtuelle Umgebung](../virtual-environments.md) erstellen, sie aktivieren und es dann installieren, zum Beispiel: +Fügen Sie es Ihrem Projekt hinzu: ```console -$ pip install email-validator +$ uv add email-validator ``` oder mit: ```console -$ pip install "pydantic[email]" +$ uv add "pydantic[email]" ``` /// @@ -98,11 +98,11 @@ Immer wenn jetzt ein Browser einen Benutzer mit Passwort erzeugt, gibt die API d Hier ist das möglicherweise kein Problem, da es derselbe Benutzer ist, der das Passwort sendet. -Aber wenn wir dasselbe Modell für eine andere *Pfadoperation* verwenden, könnten wir das Passwort dieses Benutzers zu jedem Client schicken. +Aber wenn wir dasselbe Modell für eine andere *Pfadoperation* verwenden, könnten wir die Passwörter unserer Benutzer an jeden Client senden. /// danger | Gefahr -Speichern Sie niemals das Klartext-Passwort eines Benutzers, oder versenden Sie es in einer Response wie dieser, wenn Sie sich nicht der resultierenden Gefahren bewusst sind und nicht wissen, was Sie tun. +Speichern Sie niemals das Klartext-Passwort eines Benutzers, oder versenden Sie es in einer Response wie dieser, es sei denn, Sie kennen alle Einschränkungen und wissen, was Sie tun. /// @@ -116,31 +116,31 @@ Obwohl unsere *Pfadoperation-Funktion* hier denselben `user` von der Eingabe zur {* ../../docs_src/response_model/tutorial003_py310.py hl[24] *} -... haben wir deklariert, dass `response_model` das Modell `UserOut` ist, welches das Passwort nicht enthält: +... haben wir deklariert, dass `response_model` unser Modell `UserOut` ist, welches das Passwort nicht enthält: {* ../../docs_src/response_model/tutorial003_py310.py hl[22] *} Darum wird **FastAPI** sich darum kümmern, dass alle Daten, die nicht im Ausgabemodell deklariert sind, herausgefiltert werden (mittels Pydantic). -### `response_model` oder Rückgabewert { #response-model-or-return-type } +### `response_model` oder Rückgabetyp { #response-model-or-return-type } -Da unsere zwei Modelle in diesem Fall unterschiedlich sind, würde, wenn wir den Rückgabewert der Funktion als `UserOut` deklarieren, der Editor sich beschweren, dass wir einen ungültigen Typ zurückgeben, weil das unterschiedliche Klassen sind. +Da unsere zwei Modelle in diesem Fall unterschiedlich sind, würde, wenn wir den Funktions-Rückgabetyp als `UserOut` deklarieren, der Editor sich beschweren, dass wir einen ungültigen Typ zurückgeben, weil das unterschiedliche Klassen sind. -Darum müssen wir es in diesem Fall im `response_model`-Parameter deklarieren. +Darum müssen wir es in diesem Beispiel im `response_model`-Parameter deklarieren. ... aber lesen Sie weiter, um zu sehen, wie man das anders lösen kann. -## Rückgabewert und Datenfilterung { #return-type-and-data-filtering } +## Rückgabetyp und Datenfilterung { #return-type-and-data-filtering } Führen wir unser vorheriges Beispiel fort. Wir wollten **die Funktion mit einem Typ annotieren**, aber wir wollten in der Funktion tatsächlich etwas zurückgeben, das **mehr Daten** enthält. Wir möchten, dass FastAPI die Daten weiterhin mithilfe des Responsemodells **filtert**. Selbst wenn die Funktion mehr Daten zurückgibt, soll die Response nur die Felder enthalten, die im Responsemodell deklariert sind. -Im vorherigen Beispiel mussten wir den `response_model`-Parameter verwenden, weil die Klassen unterschiedlich waren. Das bedeutet aber auch, wir bekommen keine Unterstützung vom Editor und anderen Tools, die den Funktions-Rückgabewert überprüfen. +Im vorherigen Beispiel mussten wir den `response_model`-Parameter verwenden, weil die Klassen unterschiedlich waren. Das bedeutet aber auch, wir bekommen keine Unterstützung vom Editor und anderen Tools, die den Funktions-Rückgabetyp überprüfen. Aber in den meisten Fällen, wenn wir so etwas machen, wollen wir nur, dass das Modell einige der Daten **filtert/entfernt**, so wie in diesem Beispiel. -Und in solchen Fällen können wir Klassen und Vererbung verwenden, um Vorteil aus den Typannotationen in der Funktion zu ziehen, was vom Editor und von Tools besser unterstützt wird, während wir gleichzeitig FastAPIs **Datenfilterung** behalten. +Und in solchen Fällen können wir Klassen und Vererbung verwenden, um Vorteil aus den **Typannotationen** in der Funktion zu ziehen, was vom Editor und von Tools besser unterstützt wird, während wir gleichzeitig FastAPIs **Datenfilterung** behalten. {* ../../docs_src/response_model/tutorial003_01_py310.py hl[7:10,13:14,18] *} @@ -156,7 +156,7 @@ Sehen wir uns zunächst an, wie Editor, mypy und andere Tools dies sehen würden Wir annotieren den Funktionsrückgabetyp als `BaseUser`, geben aber tatsächlich eine `UserIn`-Instanz zurück. -Für den Editor, mypy und andere Tools ist das kein Problem, da `UserIn` eine Unterklasse von `BaseUser` ist (Salopp: `UserIn` ist ein `BaseUser`). Es handelt sich um einen *gültigen* Typ, solange irgendetwas überreicht wird, das ein `BaseUser` ist. +Der Editor, mypy und andere Tools werden sich darüber nicht beschweren, weil `UserIn` im Sinne des Typings eine Unterklasse von `BaseUser` ist. Das bedeutet, es ist ein *gültiger* Typ, wenn etwas erwartet wird, das ein `BaseUser` ist. ### FastAPI Datenfilterung { #fastapi-data-filtering } @@ -182,7 +182,7 @@ Es kann Fälle geben, bei denen Sie etwas zurückgeben, das kein gültiges Pydan ### Eine Response direkt zurückgeben { #return-a-response-directly } -Der häufigste Anwendungsfall ist, wenn Sie [eine Response direkt zurückgeben, wie es später im Handbuch für fortgeschrittene Benutzer erläutert wird](../advanced/response-directly.md). +Der häufigste Anwendungsfall ist, wenn Sie [eine Response direkt zurückgeben, wie es später in der Dokumentation für fortgeschrittene Benutzer erläutert wird](../advanced/response-directly.md). {* ../../docs_src/response_model/tutorial003_02_py310.py hl[8,10:11] *} @@ -192,7 +192,7 @@ Und Tools werden auch glücklich sein, weil sowohl `RedirectResponse` als auch ` ### Eine Unterklasse von Response annotieren { #annotate-a-response-subclass } -Sie können auch eine Unterklasse von `Response` in der Typannotation verwenden. +Sie können auch eine Unterklasse von `Response` in der Typannotation verwenden: {* ../../docs_src/response_model/tutorial003_03_py310.py hl[8:9] *} @@ -200,9 +200,9 @@ Das wird ebenfalls funktionieren, weil `RedirectResponse` eine Unterklasse von ` ### Ungültige Rückgabetyp-Annotationen { #invalid-return-type-annotations } -Aber wenn Sie ein beliebiges anderes Objekt zurückgeben, das kein gültiger Pydantic-Typ ist (z. B. ein Datenbank-Objekt), und Sie annotieren es so in der Funktion, wird FastAPI versuchen, ein Pydantic-Responsemodell von dieser Typannotation zu erstellen, und scheitern. +Aber wenn Sie ein beliebiges anderes Objekt zurückgeben, das kein gültiger Pydantic-Typ ist (z. B. ein Datenbankobjekt), und Sie annotieren es so in der Funktion, wird FastAPI versuchen, ein Pydantic-Responsemodell von dieser Typannotation zu erstellen, und scheitern. -Das gleiche wird passieren, wenn Sie eine Union mehrerer Typen haben, und einer oder mehrere sind nicht gültige Pydantic-Typen. Zum Beispiel funktioniert folgendes nicht 💥: +Das gleiche wird passieren, wenn Sie eine Union mehrerer Typen haben, und einer oder mehrere sind nicht gültige Pydantic-Typen. Zum Beispiel funktioniert folgendes nicht 💥: {* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *} @@ -230,7 +230,7 @@ Ihr Responsemodell könnte Defaultwerte haben, wie: * `tax: float = 10.5` hat einen Defaultwert `10.5`. * `tags: List[str] = []` hat eine leere Liste als Defaultwert: `[]`. -Aber Sie möchten diese vielleicht vom Resultat ausschließen, wenn Sie gar nicht gesetzt wurden. +Aber Sie möchten diese vielleicht vom Resultat ausschließen, wenn sie tatsächlich nicht gespeichert wurden. Wenn Sie zum Beispiel Modelle mit vielen optionalen Attributen in einer NoSQL-Datenbank haben, und Sie möchten nicht ellenlange JSON-Responses voller Defaultwerte senden. @@ -242,7 +242,7 @@ Sie können den *Pfadoperation-Dekorator*-Parameter `response_model_exclude_unse Die Defaultwerte werden dann nicht in der Response enthalten sein, sondern nur die tatsächlich gesetzten Werte. -Wenn Sie also den Artikel mit der ID `foo` bei der *Pfadoperation* anfragen, wird (ohne die Defaultwerte) die Response sein: +Wenn Sie also einen Request an diese *Pfadoperation* für den Artikel mit der ID `foo` senden, wird (ohne die Defaultwerte) die Response sein: ```JSON { @@ -258,13 +258,13 @@ Sie können auch: * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -verwenden, wie in der [Pydantic-Dokumentation](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict) für `exclude_defaults` und `exclude_none` beschrieben. +verwenden, wie in der [Pydantic-Dokumentation](https://pydantic.dev/docs/validation/latest/concepts/serialization/#excluding-and-including-fields-based-on-their-value) für `exclude_defaults` und `exclude_none` beschrieben. /// #### Daten mit Werten für Felder mit Defaultwerten { #data-with-values-for-fields-with-defaults } -Aber wenn Ihre Daten Werte für Modellfelder mit Defaultwerten haben, wie etwa der Artikel mit der ID `bar`: +Aber wenn Ihre Daten Werte für die Felder des Modells mit Defaultwerten haben, wie etwa der Artikel mit der ID `bar`: ```Python hl_lines="3 5" { @@ -331,14 +331,14 @@ Die Syntax `{"name", "description"}` erzeugt ein `set` mit diesen zwei Werten. /// -#### `list`en statt `set`s verwenden { #using-lists-instead-of-sets } +#### `list`s statt `set`s verwenden { #using-lists-instead-of-sets } -Wenn Sie vergessen, ein `set` zu verwenden, und stattdessen eine `list`e oder ein `tuple` übergeben, wird FastAPI die dennoch in ein `set` konvertieren, und es wird korrekt funktionieren: +Wenn Sie vergessen, ein `set` zu verwenden, und stattdessen eine `list` oder ein `tuple` übergeben, wird FastAPI die dennoch in ein `set` konvertieren, und es wird korrekt funktionieren: {* ../../docs_src/response_model/tutorial006_py310.py hl[29,35] *} ## Zusammenfassung { #recap } -Verwenden Sie den Parameter `response_model` im *Pfadoperation-Dekorator*, um Responsemodelle zu definieren, und besonders, um private Daten herauszufiltern. +Verwenden Sie den Parameter `response_model` im *Pfadoperation-Dekorator*, um Responsemodelle zu definieren, und besonders, um sicherzustellen, dass private Daten herausgefiltert werden. Verwenden Sie `response_model_exclude_unset`, um nur explizit gesetzte Werte zurückzugeben. diff --git a/docs/de/docs/tutorial/schema-extra-example.md b/docs/de/docs/tutorial/schema-extra-example.md index 9bf0eaf..1d52f5a 100644 --- a/docs/de/docs/tutorial/schema-extra-example.md +++ b/docs/de/docs/tutorial/schema-extra-example.md @@ -12,7 +12,7 @@ Sie können `examples` („Beispiele“) für ein Pydantic-Modell deklarieren, w Diese zusätzlichen Informationen werden unverändert zum für dieses Modell ausgegebenen **JSON-Schema** hinzugefügt und in der API-Dokumentation verwendet. -Sie können das Attribut `model_config` verwenden, das ein `dict` akzeptiert, wie beschrieben in [Pydantic-Dokumentation: Configuration](https://docs.pydantic.dev/latest/api/config/). +Sie können das Attribut `model_config` verwenden, das ein `dict` akzeptiert, wie beschrieben in [Pydantic-Dokumentation: Configuration](https://pydantic.dev/docs/validation/latest/api/pydantic/config/). Sie können `"json_schema_extra"` setzen, mit einem `dict`, das alle zusätzlichen Daten enthält, die im generierten JSON-Schema angezeigt werden sollen, einschließlich `examples`. diff --git a/docs/de/docs/tutorial/security/first-steps.md b/docs/de/docs/tutorial/security/first-steps.md index 69e8abe..1c527f2 100644 --- a/docs/de/docs/tutorial/security/first-steps.md +++ b/docs/de/docs/tutorial/security/first-steps.md @@ -1,6 +1,5 @@ # Sicherheit – Erste Schritte { #security-first-steps } - Stellen wir uns vor, dass Sie Ihre **Backend**-API auf einer Domain haben. Und Sie haben ein **Frontend** auf einer anderen Domain oder in einem anderen Pfad derselben Domain (oder in einer Mobile-Anwendung). @@ -27,18 +26,16 @@ Kopieren Sie das Beispiel in eine Datei `main.py`: /// note | Hinweis -Das Paket [`python-multipart`](https://github.com/Kludex/python-multipart) wird automatisch mit **FastAPI** installiert, wenn Sie den Befehl `pip install "fastapi[standard]"` ausführen. +Das Paket [`python-multipart`](https://github.com/Kludex/python-multipart) wird automatisch mit **FastAPI** installiert, wenn Sie den Befehl `uv add "fastapi[standard]"` ausführen. -Wenn Sie jedoch den Befehl `pip install fastapi` verwenden, ist das Paket `python-multipart` nicht standardmäßig enthalten. +Wenn Sie jedoch den Befehl `uv add fastapi` verwenden, ist das Paket `python-multipart` nicht standardmäßig enthalten. -Um es manuell zu installieren, stellen Sie sicher, dass Sie eine [virtuelle Umgebung](../../virtual-environments.md) erstellen, sie aktivieren und es dann mit: +Um es manuell zu installieren, fügen Sie es Ihrem Projekt hinzu mit: ```console -$ pip install python-multipart +$ uv add python-multipart ``` -installieren. - Das liegt daran, dass **OAuth2** „Formulardaten“ zum Senden von `username` und `password` verwendet. /// @@ -48,7 +45,7 @@ Führen Sie das Beispiel aus mit:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/de/docs/tutorial/security/oauth2-jwt.md b/docs/de/docs/tutorial/security/oauth2-jwt.md index d04bd00..2b7e4ba 100644 --- a/docs/de/docs/tutorial/security/oauth2-jwt.md +++ b/docs/de/docs/tutorial/security/oauth2-jwt.md @@ -30,12 +30,12 @@ Wenn Sie mit JWT-Tokens spielen und sehen möchten, wie sie funktionieren, schau Wir müssen `PyJWT` installieren, um die JWT-Tokens in Python zu generieren und zu verifizieren. -Stellen Sie sicher, dass Sie eine [virtuelle Umgebung](../../virtual-environments.md) erstellen, sie aktivieren und dann `pyjwt` installieren: +Fügen Sie `pyjwt` zu Ihrem Projekt hinzu:
```console -$ pip install pyjwt +$ uv add pyjwt ---> 100% ``` @@ -44,7 +44,7 @@ $ pip install pyjwt /// note | Hinweis -Wenn Sie planen, digitale Signaturalgorithmen wie RSA oder ECDSA zu verwenden, sollten Sie die Kryptografie-Abhängigkeit `pyjwt[crypto]` installieren. +Wenn Sie planen, digitale Signaturalgorithmen wie RSA oder ECDSA zu verwenden, sollten Sie die Kryptografie-Bibliotheksabhängigkeit `pyjwt[crypto]` installieren. Weitere Informationen finden Sie in der [PyJWT-Installationsdokumentation](https://pyjwt.readthedocs.io/en/latest/installation.html). @@ -72,12 +72,12 @@ Es unterstützt viele sichere Hashing-Algorithmen und Werkzeuge, um mit diesen z Der empfohlene Algorithmus ist „Argon2“. -Stellen Sie sicher, dass Sie eine [virtuelle Umgebung](../../virtual-environments.md) erstellen, sie aktivieren, und installieren Sie dann pwdlib mit Argon2: +Fügen Sie `pwdlib` mit Argon2 zu Ihrem Projekt hinzu:
```console -$ pip install "pwdlib[argon2]" +$ uv add "pwdlib[argon2]" ---> 100% ``` @@ -206,7 +206,7 @@ Die Benutzeroberfläche sieht wie folgt aus: -Melden Sie sich bei der Anwendung auf die gleiche Weise wie zuvor an. +Autorisieren Sie die Anwendung auf die gleiche Weise wie zuvor. Verwenden Sie die Anmeldeinformationen: @@ -260,7 +260,7 @@ Mit dem, was Sie bis hier gesehen haben, können Sie eine sichere **FastAPI**-An In fast jedem Framework wird die Handhabung der Sicherheit recht schnell zu einem ziemlich komplexen Thema. -Viele Packages, die es stark vereinfachen, müssen viele Kompromisse beim Datenmodell, der Datenbank und den verfügbaren Funktionen eingehen. Und einige dieser Pakete, die die Dinge zu sehr vereinfachen, weisen tatsächlich Sicherheitslücken auf. +Viele Packages, die es stark vereinfachen, müssen viele Kompromisse beim Datenmodell, der Datenbank und den verfügbaren Funktionen eingehen. Und einige dieser Packages, die die Dinge zu sehr vereinfachen, weisen tatsächlich Sicherheitslücken auf. --- @@ -268,7 +268,7 @@ Viele Packages, die es stark vereinfachen, müssen viele Kompromisse beim Datenm Es gibt Ihnen die volle Flexibilität, diejenigen auszuwählen, die am besten zu Ihrem Projekt passen. -Und Sie können viele gut gepflegte und weit verbreitete Packages wie `pwdlib` und `PyJWT` direkt verwenden, da **FastAPI** keine komplexen Mechanismen zur Integration externer Pakete erfordert. +Und Sie können viele gut gepflegte und weit verbreitete Packages wie `pwdlib` und `PyJWT` direkt verwenden, da **FastAPI** keine komplexen Mechanismen zur Integration externer Packages erfordert. Aber es bietet Ihnen die Werkzeuge, um den Prozess so weit wie möglich zu vereinfachen, ohne Kompromisse bei Flexibilität, Robustheit oder Sicherheit einzugehen. diff --git a/docs/de/docs/tutorial/sql-databases.md b/docs/de/docs/tutorial/sql-databases.md index 3c7aaba..acd1165 100644 --- a/docs/de/docs/tutorial/sql-databases.md +++ b/docs/de/docs/tutorial/sql-databases.md @@ -8,7 +8,7 @@ Hier werden wir ein Beispiel mit [SQLModel](https://sqlmodel.tiangolo.com/) sehe /// tip | Tipp -Sie könnten jede andere SQL- oder NoSQL-Datenbankbibliothek verwenden, die Sie möchten (in einigen Fällen als „ORMs“ bezeichnet), FastAPI zwingt Sie nicht, irgendetwas zu verwenden. 😎 +Sie könnten jede andere SQL- oder NoSQL-Datenbankbibliothek verwenden, die Sie möchten (in einigen Fällen als „ORMs“ bezeichnet), FastAPI zwingt Sie nicht, irgendetwas zu verwenden. 😎 /// @@ -34,12 +34,12 @@ Dies ist ein sehr einfaches und kurzes Tutorial. Wenn Sie mehr über Datenbanken ## `SQLModel` installieren { #install-sqlmodel } -Stellen Sie zunächst sicher, dass Sie Ihre [virtuelle Umgebung](../virtual-environments.md) erstellen, sie aktivieren und dann `sqlmodel` installieren: +Fügen Sie `sqlmodel` Ihrem Projekt hinzu:
```console -$ pip install sqlmodel +$ uv add sqlmodel ---> 100% ``` @@ -152,7 +152,7 @@ Sie können die App ausführen:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -337,7 +337,7 @@ Sie können die App erneut ausführen:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/de/docs/tutorial/static-files.md b/docs/de/docs/tutorial/static-files.md index ef75ca9..3c535bd 100644 --- a/docs/de/docs/tutorial/static-files.md +++ b/docs/de/docs/tutorial/static-files.md @@ -21,7 +21,7 @@ Wenn Sie ein Frontend hosten müssen, verwenden Sie stattdessen `app.frontend()` Sie könnten auch `from starlette.staticfiles import StaticFiles` verwenden. -**FastAPI** stellt dasselbe `starlette.staticfiles` auch via `fastapi.staticfiles` bereit, als Annehmlichkeit für Sie, den Entwickler. Es kommt aber tatsächlich direkt von Starlette. +**FastAPI** stellt dasselbe `starlette.staticfiles` auch als `fastapi.staticfiles` bereit, nur als Annehmlichkeit für Sie, den Entwickler. Es kommt aber tatsächlich direkt von Starlette. /// @@ -45,4 +45,4 @@ Alle diese Parameter können anders als „`static`“ lauten, passen Sie sie an ## Weitere Informationen { #more-info } -Weitere Details und Optionen finden Sie in [Starlettes Dokumentation zu statischen Dateien](https://www.starlette.dev/staticfiles/). +Weitere Details und Optionen finden Sie in [Starlettes Dokumentation zu statischen Dateien](https://starlette.dev/staticfiles/). diff --git a/docs/de/docs/tutorial/testing.md b/docs/de/docs/tutorial/testing.md index 59d0be6..066a456 100644 --- a/docs/de/docs/tutorial/testing.md +++ b/docs/de/docs/tutorial/testing.md @@ -1,6 +1,6 @@ # Testen { #testing } -Dank [Starlette](https://www.starlette.dev/testclient/) ist das Testen von **FastAPI**-Anwendungen einfach und macht Spaß. +Dank [Starlette](https://starlette.dev/testclient/) ist das Testen von **FastAPI**-Anwendungen einfach und macht Spaß. Es basiert auf [HTTPX](https://www.python-httpx.org), welches wiederum auf der Grundlage von Requests konzipiert wurde, es ist also sehr vertraut und intuitiv. @@ -12,10 +12,10 @@ Damit können Sie [pytest](https://docs.pytest.org/) direkt mit **FastAPI** verw Um `TestClient` zu verwenden, installieren Sie zunächst [`httpx`](https://www.python-httpx.org). -Erstellen Sie eine [virtuelle Umgebung](../virtual-environments.md), aktivieren Sie sie und installieren Sie es dann, z. B.: +Fügen Sie es zu Ihrem Projekt hinzu: ```console -$ pip install httpx +$ uv add httpx ``` /// @@ -52,7 +52,7 @@ Sie könnten auch `from starlette.testclient import TestClient` verwenden. /// tip | Tipp -Wenn Sie in Ihren Tests neben dem Senden von Requests an Ihre FastAPI-Anwendung auch `async`-Funktionen aufrufen möchten (z. B. asynchrone Datenbankfunktionen), werfen Sie einen Blick auf die [Async-Tests](../advanced/async-tests.md) im Handbuch für fortgeschrittene Benutzer. +Wenn Sie in Ihren Tests neben dem Senden von Requests an Ihre FastAPI-Anwendung auch `async`-Funktionen aufrufen möchten (z. B. asynchrone Datenbankfunktionen), werfen Sie einen Blick auf die [Async-Tests](../advanced/async-tests.md) im Tutorial für fortgeschrittene Benutzer. /// @@ -153,16 +153,16 @@ Wenn Sie ein Pydantic-Modell in Ihrem Test haben und dessen Daten während des T /// -## Tests ausführen { #run-it } +## Ausführen { #run-it } Danach müssen Sie nur noch `pytest` installieren. -Erstellen Sie eine [virtuelle Umgebung](../virtual-environments.md), aktivieren Sie sie und installieren Sie es dann, z. B.: +Fügen Sie es zu Ihrem Projekt hinzu:
```console -$ pip install pytest +$ uv add pytest ---> 100% ``` @@ -176,7 +176,7 @@ Führen Sie die Tests aus, mit:
```console -$ pytest +$ uv run pytest ================ test session starts ================ platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1 diff --git a/docs/de/docs/virtual-environments.md b/docs/de/docs/virtual-environments.md index 782d1cd..9459890 100644 --- a/docs/de/docs/virtual-environments.md +++ b/docs/de/docs/virtual-environments.md @@ -1,864 +1,35 @@ # Virtuelle Umgebungen { #virtual-environments } -Wenn Sie an Python-Projekten arbeiten, sollten Sie wahrscheinlich eine **virtuelle Umgebung** (oder einen ähnlichen Mechanismus) verwenden, um die Packages, die Sie für jedes Projekt installieren, zu isolieren. +Wenn Sie mit Python-Projekten arbeiten, sollten Sie eine **virtuelle Umgebung** verwenden, um die für jedes Projekt installierten Packages zu isolieren. -/// note | Hinweis - -Wenn Sie bereits über virtuelle Umgebungen Bescheid wissen, wie man sie erstellt und verwendet, möchten Sie diesen Abschnitt vielleicht überspringen. 🤓 - -/// - -/// tip | Tipp - -Eine **virtuelle Umgebung** unterscheidet sich von einer **Umgebungsvariable**. - -Eine **Umgebungsvariable** ist eine Variable im System, die von Programmen verwendet werden kann. - -Eine **virtuelle Umgebung** ist ein Verzeichnis mit einigen Dateien darin. - -/// - -/// note | Hinweis - -Diese Seite wird Ihnen beibringen, wie Sie **virtuelle Umgebungen** verwenden und wie sie funktionieren. - -Wenn Sie bereit sind, ein **Tool zu verwenden, das alles für Sie verwaltet** (einschließlich der Installation von Python), probieren Sie [uv](https://github.com/astral-sh/uv). - -/// +Für FastAPI-Projekte empfehle ich die Verwendung von [uv](https://docs.astral.sh/uv/), um das Projekt, seine Abhängigkeiten und seine virtuelle Umgebung zu verwalten. ## Ein Projekt erstellen { #create-a-project } -Erstellen Sie zuerst ein Verzeichnis für Ihr Projekt. - -Was ich normalerweise mache, ist, dass ich ein Verzeichnis namens `code` in meinem Home/Benutzerverzeichnis erstelle. - -Und darin erstelle ich ein Verzeichnis pro Projekt. +Installieren Sie `uv` mithilfe der [offiziellen Installationsanleitung](https://docs.astral.sh/uv/getting-started/installation/) und erstellen Sie dann ein Projekt:
```console -// Gehe zum Home-Verzeichnis -$ cd -// Erstelle ein Verzeichnis für alle Ihre Code-Projekte -$ mkdir code -// Gehe in dieses Code-Verzeichnis -$ cd code -// Erstelle ein Verzeichnis für dieses Projekt -$ mkdir awesome-project -// Gehe in dieses Projektverzeichnis +$ uv init awesome-project --bare $ cd awesome-project +$ uv add "fastapi[standard]" ```
-## Eine virtuelle Umgebung erstellen { #create-a-virtual-environment } +`uv` erstellt automatisch eine virtuelle Umgebung für das Projekt. Sie müssen selbst keine erstellen oder aktivieren. -Wenn Sie zum **ersten Mal** an einem Python-Projekt arbeiten, erstellen Sie eine virtuelle Umgebung **innerhalb Ihres Projekts**. - -/// tip | Tipp - -Sie müssen dies nur **einmal pro Projekt** tun, nicht jedes Mal, wenn Sie daran arbeiten. - -/// - -//// tab | `venv` - -Um eine virtuelle Umgebung zu erstellen, können Sie das `venv`-Modul verwenden, das mit Python geliefert wird. +Führen Sie Befehle innerhalb der Projektumgebung mit `uv run` aus, zum Beispiel:
```console -$ python -m venv .venv +$ uv run fastapi dev ```
-/// details | Was dieser Befehl bedeutet +## Mehr erfahren { #learn-more } -* `python`: das Programm namens `python` verwenden -* `-m`: ein Modul als Skript aufrufen, wir geben als nächstes an, welches Modul -* `venv`: das Modul namens `venv` verwenden, das normalerweise mit Python installiert wird -* `.venv`: die virtuelle Umgebung im neuen Verzeichnis `.venv` erstellen - -/// - -//// - -//// tab | `uv` - -Wenn Sie [`uv`](https://github.com/astral-sh/uv) installiert haben, können Sie es verwenden, um eine virtuelle Umgebung zu erstellen. - -
- -```console -$ uv venv -``` - -
- -/// tip | Tipp - -Standardmäßig erstellt `uv` eine virtuelle Umgebung in einem Verzeichnis namens `.venv`. - -Aber Sie könnten es anpassen, indem Sie ein zusätzliches Argument mit dem Verzeichnisnamen übergeben. - -/// - -//// - -Dieser Befehl erstellt eine neue virtuelle Umgebung in einem Verzeichnis namens `.venv`. - -/// details | `.venv` oder ein anderer Name - -Sie könnten die virtuelle Umgebung in einem anderen Verzeichnis erstellen, aber es ist eine Konvention, sie `.venv` zu nennen. - -/// - -## Die virtuelle Umgebung aktivieren { #activate-the-virtual-environment } - -Aktivieren Sie die neue virtuelle Umgebung, damit jeder Python-Befehl, den Sie ausführen oder jedes Paket, das Sie installieren, diese Umgebung verwendet. - -/// tip | Tipp - -Tun Sie dies **jedes Mal**, wenn Sie eine **neue Terminalsitzung** starten, um an dem Projekt zu arbeiten. - -/// - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Oder wenn Sie Bash für Windows verwenden (z. B. [Git Bash](https://gitforwindows.org/)): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -/// tip | Tipp - -Jedes Mal, wenn Sie ein **neues Paket** in dieser Umgebung installieren, aktivieren Sie die Umgebung erneut. - -So stellen Sie sicher, dass, wenn Sie ein **Terminalprogramm (CLI)** verwenden, das durch dieses Paket installiert wurde, Sie das aus Ihrer virtuellen Umgebung verwenden und nicht eines, das global installiert ist, wahrscheinlich mit einer anderen Version als der, die Sie benötigen. - -/// - -## Testen, ob die virtuelle Umgebung aktiv ist { #check-the-virtual-environment-is-active } - -Testen Sie, dass die virtuelle Umgebung aktiv ist (der vorherige Befehl funktioniert hat). - -/// tip | Tipp - -Dies ist **optional**, aber es ist eine gute Möglichkeit, **zu überprüfen**, ob alles wie erwartet funktioniert und Sie die beabsichtigte virtuelle Umgebung verwenden. - -/// - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -Wenn es das `python`-Binary in `.venv/bin/python` anzeigt, innerhalb Ihres Projekts (in diesem Fall `awesome-project`), dann hat es funktioniert. 🎉 - -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -Wenn es das `python`-Binary in `.venv\Scripts\python` anzeigt, innerhalb Ihres Projekts (in diesem Fall `awesome-project`), dann hat es funktioniert. 🎉 - -//// - -## `pip` aktualisieren { #upgrade-pip } - -/// tip | Tipp - -Wenn Sie [`uv`](https://github.com/astral-sh/uv) verwenden, würden Sie das verwenden, um Dinge zu installieren anstelle von `pip`, sodass Sie `pip` nicht aktualisieren müssen. 😎 - -/// - -Wenn Sie `pip` verwenden, um Pakete zu installieren (es wird standardmäßig mit Python geliefert), sollten Sie es auf die neueste Version **aktualisieren**. - -Viele exotische Fehler beim Installieren eines Pakets werden einfach dadurch gelöst, dass zuerst `pip` aktualisiert wird. - -/// tip | Tipp - -Normalerweise würden Sie dies **einmal** tun, unmittelbar nachdem Sie die virtuelle Umgebung erstellt haben. - -/// - -Stellen Sie sicher, dass die virtuelle Umgebung aktiv ist (mit dem obigen Befehl) und führen Sie dann aus: - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip | Tipp - -Manchmal kann beim Versuch, `pip` zu aktualisieren, der Fehler **`No module named pip`** auftreten. - -Wenn das passiert, installieren und aktualisieren Sie `pip` mit dem folgenden Befehl: - -
- -```console -$ python -m ensurepip --upgrade - ----> 100% -``` - -
- -Dieser Befehl installiert `pip`, falls es noch nicht installiert ist, und stellt außerdem sicher, dass die installierte Version von `pip` mindestens so aktuell ist wie die in `ensurepip` verfügbare. - -/// - -## `.gitignore` hinzufügen { #add-gitignore } - -Wenn Sie **Git** verwenden (was Sie sollten), fügen Sie eine `.gitignore`-Datei hinzu, um alles in Ihrem `.venv` von Git auszuschließen. - -/// tip | Tipp - -Wenn Sie [`uv`](https://github.com/astral-sh/uv) verwendet haben, um die virtuelle Umgebung zu erstellen, hat es dies bereits für Sie getan, Sie können diesen Schritt überspringen. 😎 - -/// - -/// tip | Tipp - -Tun Sie dies **einmal**, unmittelbar nachdem Sie die virtuelle Umgebung erstellt haben. - -/// - -
- -```console -$ echo "*" > .venv/.gitignore -``` - -
- -/// details | Was dieser Befehl bedeutet - -* `echo "*"`: wird den Text `*` im Terminal „drucken“ (der nächste Teil ändert das ein wenig) -* `>`: alles, was durch den Befehl links von `>` im Terminal ausgegeben wird, sollte nicht gedruckt, sondern stattdessen in die Datei geschrieben werden, die rechts von `>` kommt -* `.gitignore`: der Name der Datei, in die der Text geschrieben werden soll - -Und `*` bedeutet für Git „alles“. Also wird alles im `.venv`-Verzeichnis ignoriert. - -Dieser Befehl erstellt eine Datei `.gitignore` mit dem Inhalt: - -```gitignore -* -``` - -/// - -## Pakete installieren { #install-packages } - -Nachdem Sie die Umgebung aktiviert haben, können Sie Pakete darin installieren. - -/// tip | Tipp - -Tun Sie dies **einmal**, wenn Sie die Pakete installieren oder aktualisieren, die Ihr Projekt benötigt. - -Wenn Sie eine Version aktualisieren oder ein neues Paket hinzufügen müssen, würden Sie **dies erneut tun**. - -/// - -### Pakete direkt installieren { #install-packages-directly } - -Wenn Sie es eilig haben und keine Datei verwenden möchten, um die Paketanforderungen Ihres Projekts zu deklarieren, können Sie sie direkt installieren. - -/// tip | Tipp - -Es ist eine (sehr) gute Idee, die Pakete und Versionen, die Ihr Programm benötigt, in einer Datei zu speichern (zum Beispiel `requirements.txt` oder `pyproject.toml`). - -/// - -//// tab | `pip` - -
- -```console -$ pip install "fastapi[standard]" - ----> 100% -``` - -
- -//// - -//// tab | `uv` - -Wenn Sie [`uv`](https://github.com/astral-sh/uv) haben: - -
- -```console -$ uv pip install "fastapi[standard]" ----> 100% -``` - -
- -//// - -### Installation von `requirements.txt` { #install-from-requirements-txt } - -Wenn Sie eine `requirements.txt` haben, können Sie diese nun verwenden, um deren Pakete zu installieren. - -//// tab | `pip` - -
- -```console -$ pip install -r requirements.txt ----> 100% -``` - -
- -//// - -//// tab | `uv` - -Wenn Sie [`uv`](https://github.com/astral-sh/uv) haben: - -
- -```console -$ uv pip install -r requirements.txt ----> 100% -``` - -
- -//// - -/// details | `requirements.txt` - -Eine `requirements.txt` mit einigen Paketen könnte folgendermaßen aussehen: - -```requirements.txt -fastapi[standard]==0.113.0 -pydantic==2.8.0 -``` - -/// - -## Ihr Programm ausführen { #run-your-program } - -Nachdem Sie die virtuelle Umgebung aktiviert haben, können Sie Ihr Programm ausführen, und es wird das Python innerhalb Ihrer virtuellen Umgebung mit den Paketen verwenden, die Sie dort installiert haben. - -
- -```console -$ python main.py - -Hello World -``` - -
- -## Ihren Editor konfigurieren { #configure-your-editor } - -Sie würden wahrscheinlich einen Editor verwenden, stellen Sie sicher, dass Sie ihn so konfigurieren, dass er dieselbe virtuelle Umgebung verwendet, die Sie erstellt haben (er wird sie wahrscheinlich automatisch erkennen), sodass Sie Autovervollständigungen und Inline-Fehler erhalten können. - -Zum Beispiel: - -* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) -* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) - -/// tip | Tipp - -Normalerweise müssen Sie dies nur **einmal** tun, wenn Sie die virtuelle Umgebung erstellen. - -/// - -## Die virtuelle Umgebung deaktivieren { #deactivate-the-virtual-environment } - -Sobald Sie mit der Arbeit an Ihrem Projekt fertig sind, können Sie die virtuelle Umgebung **deaktivieren**. - -
- -```console -$ deactivate -``` - -
- -Auf diese Weise, wenn Sie `python` ausführen, wird nicht versucht, es aus dieser virtuellen Umgebung mit den dort installierten Paketen auszuführen. - -## Bereit zu arbeiten { #ready-to-work } - -Jetzt sind Sie bereit, mit Ihrem Projekt zu arbeiten. - - - -/// tip | Tipp - -Möchten Sie verstehen, was das alles oben bedeutet? - -Lesen Sie weiter. 👇🤓 - -/// - -## Warum virtuelle Umgebungen { #why-virtual-environments } - -Um mit FastAPI zu arbeiten, müssen Sie [Python](https://www.python.org/) installieren. - -Danach müssen Sie FastAPI und alle anderen **Pakete**, die Sie verwenden möchten, **installieren**. - -Um Pakete zu installieren, würden Sie normalerweise den `pip`-Befehl verwenden, der mit Python geliefert wird (oder ähnliche Alternativen). - -Wenn Sie jedoch `pip` direkt verwenden, werden die Pakete in Ihrer **globalen Python-Umgebung** (der globalen Installation von Python) installiert. - -### Das Problem { #the-problem } - -Was ist also das Problem beim Installieren von Paketen in der globalen Python-Umgebung? - -Irgendwann werden Sie wahrscheinlich viele verschiedene Programme schreiben, die von **verschiedenen Paketen** abhängen. Und einige dieser Projekte, an denen Sie arbeiten, werden von **verschiedenen Versionen** desselben Pakets abhängen. 😱 - -Zum Beispiel könnten Sie ein Projekt namens `philosophers-stone` erstellen, dieses Programm hängt von einem anderen Paket namens **`harry`, Version `1`** ab. Also müssen Sie `harry` installieren. - -```mermaid -flowchart LR - stone(philosophers-stone) -->|benötigt| harry-1[harry v1] -``` - -Dann erstellen Sie zu einem späteren Zeitpunkt ein weiteres Projekt namens `prisoner-of-azkaban`, und dieses Projekt hängt ebenfalls von `harry` ab, aber dieses Projekt benötigt **`harry` Version `3`**. - -```mermaid -flowchart LR - azkaban(prisoner-of-azkaban) --> |benötigt| harry-3[harry v3] -``` - -Aber jetzt ist das Problem, wenn Sie die Pakete global (in der globalen Umgebung) installieren anstatt in einer lokalen **virtuellen Umgebung**, müssen Sie wählen, welche Version von `harry` zu installieren ist. - -Wenn Sie `philosophers-stone` ausführen möchten, müssen Sie zuerst `harry` Version `1` installieren, zum Beispiel mit: - -
- -```console -$ pip install "harry==1" -``` - -
- -Und dann hätten Sie `harry` Version `1` in Ihrer globalen Python-Umgebung installiert. - -```mermaid -flowchart LR - subgraph global[globale Umgebung] - harry-1[harry v1] - end - subgraph stone-project[philosophers-stone-Projekt] - stone(philosophers-stone) -->|benötigt| harry-1 - end -``` - -Aber dann, wenn Sie `prisoner-of-azkaban` ausführen möchten, müssen Sie `harry` Version `1` deinstallieren und `harry` Version `3` installieren (oder einfach die Version `3` installieren, was die Version `1` automatisch deinstallieren würde). - -
- -```console -$ pip install "harry==3" -``` - -
- -Und dann hätten Sie `harry` Version `3` in Ihrer globalen Python-Umgebung installiert. - -Und wenn Sie versuchen, `philosophers-stone` erneut auszuführen, besteht die Möglichkeit, dass es **nicht funktioniert**, weil es `harry` Version `1` benötigt. - -```mermaid -flowchart LR - subgraph global[globale Umgebung] - harry-1[harry v1] - style harry-1 fill:#ccc,stroke-dasharray: 5 5 - harry-3[harry v3] - end - subgraph stone-project[philosophers-stone-Projekt] - stone(philosophers-stone) -.-x|⛔️| harry-1 - end - subgraph azkaban-project[prisoner-of-azkaban-Projekt] - azkaban(prisoner-of-azkaban) --> |benötigt| harry-3 - end -``` - -/// tip | Tipp - -Es ist sehr üblich in Python-Paketen, alles zu versuchen, **Breaking Changes** in **neuen Versionen** zu vermeiden, aber es ist besser, auf Nummer sicher zu gehen und neue Versionen absichtlich zu installieren und wenn Sie die Tests ausführen können, sicherzustellen, dass alles korrekt funktioniert. - -/// - -Stellen Sie sich das jetzt mit **vielen** anderen **Paketen** vor, von denen alle Ihre **Projekte abhängen**. Das ist sehr schwierig zu verwalten. Und Sie würden wahrscheinlich einige Projekte mit einigen **inkompatiblen Versionen** der Pakete ausführen und nicht wissen, warum etwas nicht funktioniert. - -Darüber hinaus könnte es je nach Ihrem Betriebssystem (z. B. Linux, Windows, macOS) bereits mit installiertem Python geliefert worden sein. Und in diesem Fall hatte es wahrscheinlich einige Pakete mit bestimmten Versionen **installiert**, die von Ihrem System benötigt werden. Wenn Sie Pakete in der globalen Python-Umgebung installieren, könnten Sie einige der Programme, die mit Ihrem Betriebssystem geliefert wurden, **kaputtmachen**. - -## Wo werden Pakete installiert { #where-are-packages-installed } - -Wenn Sie Python installieren, werden einige Verzeichnisse mit einigen Dateien auf Ihrem Rechner erstellt. - -Einige dieser Verzeichnisse sind dafür zuständig, alle Pakete, die Sie installieren, aufzunehmen. - -Wenn Sie ausführen: - -
- -```console -// Führen Sie dies jetzt nicht aus, es ist nur ein Beispiel 🤓 -$ pip install "fastapi[standard]" ----> 100% -``` - -
- -Das lädt eine komprimierte Datei mit dem FastAPI-Code herunter, normalerweise von [PyPI](https://pypi.org/project/fastapi/). - -Es wird auch Dateien für andere Pakete **herunterladen**, von denen FastAPI abhängt. - -Dann wird es all diese Dateien **extrahieren** und sie in ein Verzeichnis auf Ihrem Rechner legen. - -Standardmäßig werden diese heruntergeladenen und extrahierten Dateien in das Verzeichnis gelegt, das mit Ihrer Python-Installation kommt, das ist die **globale Umgebung**. - -## Was sind virtuelle Umgebungen { #what-are-virtual-environments } - -Die Lösung für die Probleme, alle Pakete in der globalen Umgebung zu haben, besteht darin, eine **virtuelle Umgebung für jedes Projekt** zu verwenden, an dem Sie arbeiten. - -Eine virtuelle Umgebung ist ein **Verzeichnis**, sehr ähnlich zu dem globalen, in dem Sie die Pakete für ein Projekt installieren können. - -Auf diese Weise hat jedes Projekt seine eigene virtuelle Umgebung (`.venv`-Verzeichnis) mit seinen eigenen Paketen. - -```mermaid -flowchart TB - subgraph stone-project[philosophers-stone-Projekt] - stone(philosophers-stone) --->|benötigt| harry-1 - subgraph venv1[.venv] - harry-1[harry v1] - end - end - subgraph azkaban-project[prisoner-of-azkaban-Projekt] - azkaban(prisoner-of-azkaban) --->|benötigt| harry-3 - subgraph venv2[.venv] - harry-3[harry v3] - end - end - stone-project ~~~ azkaban-project -``` - -## Was bedeutet das Aktivieren einer virtuellen Umgebung { #what-does-activating-a-virtual-environment-mean } - -Wenn Sie eine virtuelle Umgebung aktivieren, zum Beispiel mit: - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Oder wenn Sie Bash für Windows verwenden (z. B. [Git Bash](https://gitforwindows.org/)): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -Dieser Befehl erstellt oder ändert einige [Umgebungsvariablen](environment-variables.md), die für die nächsten Befehle verfügbar sein werden. - -Eine dieser Variablen ist die `PATH`-Variable. - -/// tip | Tipp - -Sie können mehr über die `PATH`-Umgebungsvariable im Abschnitt [Umgebungsvariablen](environment-variables.md#path-environment-variable) erfahren. - -/// - -Das Aktivieren einer virtuellen Umgebung fügt deren Pfad `.venv/bin` (auf Linux und macOS) oder `.venv\Scripts` (auf Windows) zur `PATH`-Umgebungsvariable hinzu. - -Angenommen, die `PATH`-Variable sah vor dem Aktivieren der Umgebung so aus: - -//// tab | Linux, macOS - -```plaintext -/usr/bin:/bin:/usr/sbin:/sbin -``` - -Das bedeutet, dass das System nach Programmen sucht in: - -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Windows\System32 -``` - -Das bedeutet, dass das System nach Programmen sucht in: - -* `C:\Windows\System32` - -//// - -Nach dem Aktivieren der virtuellen Umgebung würde die `PATH`-Variable folgendermaßen aussehen: - -//// tab | Linux, macOS - -```plaintext -/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -Das bedeutet, dass das System nun zuerst nach Programmen sucht in: - -```plaintext -/home/user/code/awesome-project/.venv/bin -``` - -bevor es in den anderen Verzeichnissen sucht. - -Wenn Sie also `python` im Terminal eingeben, wird das System das Python-Programm in - -```plaintext -/home/user/code/awesome-project/.venv/bin/python -``` - -finden und dieses verwenden. - -//// - -//// tab | Windows - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32 -``` - -Das bedeutet, dass das System nun zuerst nach Programmen sucht in: - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts -``` - -bevor es in den anderen Verzeichnissen sucht. - -Wenn Sie also `python` im Terminal eingeben, wird das System das Python-Programm in - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -finden und dieses verwenden. - -//// - -Ein wichtiger Punkt ist, dass es den Pfad der virtuellen Umgebung am **Anfang** der `PATH`-Variable platziert. Das System wird es **vor** allen anderen verfügbaren Pythons finden. Auf diese Weise, wenn Sie `python` ausführen, wird das Python **aus der virtuellen Umgebung** verwendet anstelle eines anderen `python` (zum Beispiel, einem `python` aus einer globalen Umgebung). - -Das Aktivieren einer virtuellen Umgebung ändert auch ein paar andere Dinge, aber dies ist eines der wichtigsten Dinge, die es tut. - -## Testen einer virtuellen Umgebung { #checking-a-virtual-environment } - -Wenn Sie testen, ob eine virtuelle Umgebung aktiv ist, zum Beispiel mit: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -//// - -bedeutet das, dass das `python`-Programm, das verwendet wird, das in der **virtuellen Umgebung** ist. - -Sie verwenden `which` auf Linux und macOS und `Get-Command` in Windows PowerShell. - -So funktioniert dieser Befehl: Er wird in der `PATH`-Umgebungsvariable nachsehen und **jeden Pfad in der Reihenfolge durchgehen**, um das Programm namens `python` zu finden. Sobald er es findet, wird er Ihnen **den Pfad** zu diesem Programm anzeigen. - -Der wichtigste Punkt ist, dass, wenn Sie `python` aufrufen, genau dieses „`python`“ ausgeführt wird. - -So können Sie überprüfen, ob Sie sich in der richtigen virtuellen Umgebung befinden. - -/// tip | Tipp - -Es ist einfach, eine virtuelle Umgebung zu aktivieren, ein Python zu bekommen und dann **zu einem anderen Projekt zu wechseln**. - -Und das zweite Projekt **würde nicht funktionieren**, weil Sie das **falsche Python** verwenden, aus einer virtuellen Umgebung für ein anderes Projekt. - -Es ist nützlich, überprüfen zu können, welches `python` verwendet wird. 🤓 - -/// - -## Warum eine virtuelle Umgebung deaktivieren { #why-deactivate-a-virtual-environment } - -Zum Beispiel könnten Sie an einem Projekt `philosophers-stone` arbeiten, diese virtuelle Umgebung **aktivieren**, Pakete installieren und mit dieser Umgebung arbeiten. - -Und dann möchten Sie an **einem anderen Projekt** `prisoner-of-azkaban` arbeiten. - -Sie gehen zu diesem Projekt: - -
- -```console -$ cd ~/code/prisoner-of-azkaban -``` - -
- -Wenn Sie die virtuelle Umgebung für `philosophers-stone` nicht deaktivieren, wird beim Ausführen von `python` im Terminal versucht, das Python von `philosophers-stone` zu verwenden. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -$ python main.py - -// Fehler beim Importieren von sirius, es ist nicht installiert 😱 -Traceback (most recent call last): - File "main.py", line 1, in - import sirius -``` - -
- -Wenn Sie jedoch die virtuelle Umgebung deaktivieren und die neue für `prisoner-of-azkaban` aktivieren, wird beim Ausführen von `python` das Python aus der virtuellen Umgebung in `prisoner-of-azkaban` verwendet. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -// Sie müssen nicht im alten Verzeichnis sein, um zu deaktivieren, Sie können dies überall tun, sogar nachdem Sie zum anderen Projekt gewechselt haben 😎 -$ deactivate - -// Die virtuelle Umgebung in prisoner-of-azkaban/.venv 🚀 aktivieren -$ source .venv/bin/activate - -// Jetzt, wenn Sie python ausführen, wird das Paket sirius in dieser virtuellen Umgebung gefunden ✨ -$ python main.py - -I solemnly swear 🐺 -``` - -
- -## Alternativen { #alternatives } - -Dies ist ein einfacher Leitfaden, um Ihnen den Einstieg zu erleichtern und Ihnen beizubringen, wie alles **unter der Haube** funktioniert. - -Es gibt viele **Alternativen** zur Verwaltung von virtuellen Umgebungen, Paketabhängigkeiten (Anforderungen), Projekten. - -Sobald Sie bereit sind und ein Tool verwenden möchten, das **das gesamte Projekt verwaltet**, Paketabhängigkeiten, virtuelle Umgebungen usw., würde ich Ihnen vorschlagen, [uv](https://github.com/astral-sh/uv) auszuprobieren. - -`uv` kann viele Dinge tun, es kann: - -* **Python für Sie installieren**, einschließlich verschiedener Versionen -* Die **virtuelle Umgebung** für Ihre Projekte verwalten -* **Pakete installieren** -* Paket**abhängigkeiten und Versionen** für Ihr Projekt verwalten -* Sicherstellen, dass Sie eine **exakte** Menge an Paketen und Versionen zur Installation haben, einschließlich ihrer Abhängigkeiten, damit Sie sicher sein können, dass Sie Ihr Projekt in der Produktionsumgebung genauso ausführen können wie auf Ihrem Rechner während der Entwicklung, dies wird **Locking** genannt -* Und viele andere Dinge - -## Fazit { #conclusion } - -Wenn Sie das alles gelesen und verstanden haben, wissen Sie jetzt **viel mehr** über virtuelle Umgebungen als viele Entwickler da draußen. 🤓 - -Das Wissen über diese Details wird in Zukunft wahrscheinlich nützlich sein, wenn Sie etwas debuggen, das komplex erscheint, aber Sie werden wissen, **wie alles unter der Haube funktioniert**. 😎 +Lesen Sie den [Leitfaden zu virtuellen Umgebungen](https://tiangolo.com/guides/virtual-environments/), um zu erfahren, wie virtuelle Umgebungen unter der Haube funktionieren, einschließlich Aktivierung und dem alternativen `python -m venv`- und `pip`-Workflow. diff --git a/docs/en/data/github_sponsors.yml b/docs/en/data/github_sponsors.yml index 519e7af..51ba39f 100644 --- a/docs/en/data/github_sponsors.yml +++ b/docs/en/data/github_sponsors.yml @@ -74,12 +74,21 @@ sponsors: - login: ChargeStorm avatarUrl: https://avatars.githubusercontent.com/u/26000165?v=4 url: https://github.com/ChargeStorm + - login: tltaylor1 + avatarUrl: https://avatars.githubusercontent.com/u/234697691?u=f9bf860a7a6e1109b35f1eb930920bd37e3bf571&v=4 + url: https://github.com/tltaylor1 + - login: justoutofcuriosity + avatarUrl: https://avatars.githubusercontent.com/u/57193655?v=4 + url: https://github.com/justoutofcuriosity - login: nilslindemann avatarUrl: https://avatars.githubusercontent.com/u/6892179?u=1dca6a22195d6cd1ab20737c0e19a4c55d639472&v=4 url: https://github.com/nilslindemann - - login: samuelcolvin avatarUrl: https://avatars.githubusercontent.com/u/4039449?u=42eb3b833047c8c4b4f647a031eaef148c16d93f&v=4 url: https://github.com/samuelcolvin + - login: roboflow + avatarUrl: https://avatars.githubusercontent.com/u/53104118?v=4 + url: https://github.com/roboflow - login: otosky avatarUrl: https://avatars.githubusercontent.com/u/42260747?u=69d089387c743d89427aa4ad8740cfb34045a9e0&v=4 url: https://github.com/otosky @@ -98,9 +107,6 @@ sponsors: - login: ashi-agrawal avatarUrl: https://avatars.githubusercontent.com/u/17105294?u=99c7a854035e5398d8e7b674f2d42baae6c957f8&v=4 url: https://github.com/ashi-agrawal - - login: mjohnsey - avatarUrl: https://avatars.githubusercontent.com/u/16784016?u=38fad2e6b411244560b3af99c5f5a4751bc81865&v=4 - url: https://github.com/mjohnsey - login: jugeeem avatarUrl: https://avatars.githubusercontent.com/u/116043716?u=e4df530e99a086a1085f3dc125b94783670fb383&v=4 url: https://github.com/jugeeem @@ -119,15 +125,21 @@ sponsors: - login: anthonycepeda avatarUrl: https://avatars.githubusercontent.com/u/72019805?u=60bdf46240cff8fca482ff0fc07d963fd5e1a27c&v=4 url: https://github.com/anthonycepeda + - login: PedroRuizCode + avatarUrl: https://avatars.githubusercontent.com/u/69810923?u=26f9b262922b724deacdfa16ccd5785d093ac371&v=4 + url: https://github.com/PedroRuizCode - login: patsatsia avatarUrl: https://avatars.githubusercontent.com/u/61111267?u=3271b85f7a37b479c8d0ae0a235182e83c166edf&v=4 url: https://github.com/patsatsia + - login: bradsward + avatarUrl: https://avatars.githubusercontent.com/u/60303274?u=6b74120e142c8bd4dae22edcf3ac6bb9c3b427bb&v=4 + url: https://github.com/bradsward - login: dudikbender avatarUrl: https://avatars.githubusercontent.com/u/53487583?u=3a57542938ebfd57579a0111db2b297e606d9681&v=4 url: https://github.com/dudikbender - - login: roboflow - avatarUrl: https://avatars.githubusercontent.com/u/53104118?v=4 - url: https://github.com/roboflow + - login: jaredtrog + avatarUrl: https://avatars.githubusercontent.com/u/4381365?v=4 + url: https://github.com/jaredtrog - login: Ryandaydev avatarUrl: https://avatars.githubusercontent.com/u/4292423?u=87b1afc7f4fff933779959270e2d168339e91402&v=4 url: https://github.com/Ryandaydev @@ -152,9 +164,6 @@ sponsors: - login: knallgelb avatarUrl: https://avatars.githubusercontent.com/u/2358812?u=c48cb6362b309d74cbf144bd6ad3aed3eb443e82&v=4 url: https://github.com/knallgelb - - login: keimos - avatarUrl: https://avatars.githubusercontent.com/u/1723255?u=fb87c72da55f72da6618aa94c8f3791ebab6b68a&v=4 - url: https://github.com/keimos - login: dodo5522 avatarUrl: https://avatars.githubusercontent.com/u/1362607?u=9bf1e0e520cccc547c046610c468ce6115bbcf9f&v=4 url: https://github.com/dodo5522 @@ -170,6 +179,12 @@ sponsors: - login: jstanden avatarUrl: https://avatars.githubusercontent.com/u/63288?u=c3658d57d2862c607a0e19c2101c3c51876e36ad&v=4 url: https://github.com/jstanden + - login: mjohnsey + avatarUrl: https://avatars.githubusercontent.com/u/16784016?u=38fad2e6b411244560b3af99c5f5a4751bc81865&v=4 + url: https://github.com/mjohnsey + - login: cizekmilan + avatarUrl: https://avatars.githubusercontent.com/u/15999191?u=df194a9bf279f503bc96af41a35c0027eb94ad4f&v=4 + url: https://github.com/cizekmilan - login: khadrawy avatarUrl: https://avatars.githubusercontent.com/u/13686061?u=59f25ef42ecf04c22657aac4238ce0e2d3d30304&v=4 url: https://github.com/khadrawy @@ -200,9 +215,6 @@ sponsors: - login: ternaus avatarUrl: https://avatars.githubusercontent.com/u/5481618?u=513a26b02a39e7a28d587cd37c6cc877ea368e6e&v=4 url: https://github.com/ternaus - - login: jaredtrog - avatarUrl: https://avatars.githubusercontent.com/u/4381365?v=4 - url: https://github.com/jaredtrog - - login: jpfyoder avatarUrl: https://avatars.githubusercontent.com/u/7548821?u=1683290ed65dae6987d673da044067577ee71521&v=4 url: https://github.com/jpfyoder @@ -215,18 +227,15 @@ sponsors: - - login: pawamoy avatarUrl: https://avatars.githubusercontent.com/u/3999221?u=b030e4c89df2f3a36bc4710b925bdeb6745c9856&v=4 url: https://github.com/pawamoy - - login: caviri - avatarUrl: https://avatars.githubusercontent.com/u/45425937?u=cab1bb03a0326fe45b2363866b1d78c9bc8055d8&v=4 - url: https://github.com/caviri + - login: hgalytoby + avatarUrl: https://avatars.githubusercontent.com/u/50397689?u=6cc9028f3db63f8f60ad21c17b1ce4b88c4e2e60&v=4 + url: https://github.com/hgalytoby - login: mobyw avatarUrl: https://avatars.githubusercontent.com/u/44370805?v=4 url: https://github.com/mobyw - login: siavashyj avatarUrl: https://avatars.githubusercontent.com/u/43583410?u=562005ddc7901cd27a1219a118a2363817b14977&v=4 url: https://github.com/siavashyj - - login: petercool - avatarUrl: https://avatars.githubusercontent.com/u/37613029?u=75aa8c6729e6e8f85a300561c4dbeef9d65c8797&v=4 - url: https://github.com/petercool - login: bnkc avatarUrl: https://avatars.githubusercontent.com/u/34930566?u=888af82706afa36727feebce0e62225905926131&v=4 url: https://github.com/bnkc @@ -242,12 +251,9 @@ sponsors: - login: joshuatz avatarUrl: https://avatars.githubusercontent.com/u/17817563?u=f1bf05b690d1fc164218f0b420cdd3acb7913e21&v=4 url: https://github.com/joshuatz - - login: hgalytoby - avatarUrl: https://avatars.githubusercontent.com/u/50397689?u=6cc9028f3db63f8f60ad21c17b1ce4b88c4e2e60&v=4 - url: https://github.com/hgalytoby - - login: TheR1D - avatarUrl: https://avatars.githubusercontent.com/u/16740832?u=b0dfdbdb27b79729430c71c6128962f77b7b53f7&v=4 - url: https://github.com/TheR1D + - login: danielunderwood + avatarUrl: https://avatars.githubusercontent.com/u/4472301?v=4 + url: https://github.com/danielunderwood - login: my3 avatarUrl: https://avatars.githubusercontent.com/u/1825270?v=4 url: https://github.com/my3 @@ -275,15 +281,15 @@ sponsors: - login: ddanier avatarUrl: https://avatars.githubusercontent.com/u/113563?u=ed1dc79de72f93bd78581f88ebc6952b62f472da&v=4 url: https://github.com/ddanier + - login: TheR1D + avatarUrl: https://avatars.githubusercontent.com/u/16740832?u=b0dfdbdb27b79729430c71c6128962f77b7b53f7&v=4 + url: https://github.com/TheR1D - login: Zuzah avatarUrl: https://avatars.githubusercontent.com/u/10934846?u=1ef43e075ddc87bd1178372bf4d95ee6175cae27&v=4 url: https://github.com/Zuzah - login: DMantis avatarUrl: https://avatars.githubusercontent.com/u/9536869?u=652dd0d49717803c0cbcbf44f7740e53cf2d4892&v=4 url: https://github.com/DMantis - - login: xncbf - avatarUrl: https://avatars.githubusercontent.com/u/9462045?u=a80a7bb349555b277645632ed66639ff43400614&v=4 - url: https://github.com/xncbf - login: moonape1226 avatarUrl: https://avatars.githubusercontent.com/u/8532038?u=d9f8b855a429fff9397c3833c2ff83849ebf989d&v=4 url: https://github.com/moonape1226 @@ -302,10 +308,13 @@ sponsors: - login: rangulvers avatarUrl: https://avatars.githubusercontent.com/u/5235430?u=e254d4af4ace5a05fa58372ae677c7d26f0d5a53&v=4 url: https://github.com/rangulvers - - login: danielunderwood - avatarUrl: https://avatars.githubusercontent.com/u/4472301?v=4 - url: https://github.com/danielunderwood -- - login: ArtyomVancyan +- - login: mohammadi-hadi + avatarUrl: https://avatars.githubusercontent.com/u/50410241?u=1137b5ff9ea8585c0192fe9ddb4ae5e21bc3d2e8&v=4 + url: https://github.com/mohammadi-hadi + - login: morzan1001 + avatarUrl: https://avatars.githubusercontent.com/u/47593005?u=c30ab7230f82a12a9b938dcb54f84a996931409a&v=4 + url: https://github.com/morzan1001 + - login: ArtyomVancyan avatarUrl: https://avatars.githubusercontent.com/u/44609997?v=4 url: https://github.com/ArtyomVancyan - login: rwxd @@ -323,15 +332,12 @@ sponsors: - login: diogotoporcov avatarUrl: https://avatars.githubusercontent.com/u/207575398?u=1fa7cf41b4181faa4d27f38bc37a374c17b5163b&v=4 url: https://github.com/diogotoporcov + - login: anandakrishnone + avatarUrl: https://avatars.githubusercontent.com/u/100110721?u=5d30e6fea1524bf3c8be3547027dbce59cc699af&v=4 + url: https://github.com/anandakrishnone - login: onestn avatarUrl: https://avatars.githubusercontent.com/u/62360849?u=746dd21c34e7e06eefb11b03e8bb01aaae3c2a4f&v=4 url: https://github.com/onestn - - login: mohammadi-hadi - avatarUrl: https://avatars.githubusercontent.com/u/50410241?u=1137b5ff9ea8585c0192fe9ddb4ae5e21bc3d2e8&v=4 - url: https://github.com/mohammadi-hadi - - login: morzan1001 - avatarUrl: https://avatars.githubusercontent.com/u/47593005?u=c30ab7230f82a12a9b938dcb54f84a996931409a&v=4 - url: https://github.com/morzan1001 - login: Toothwitch avatarUrl: https://avatars.githubusercontent.com/u/1710406?u=5eebb23b46cd26e48643b9e5179536cad491c17a&v=4 url: https://github.com/Toothwitch @@ -341,6 +347,9 @@ sponsors: - login: 0xsummerday avatarUrl: https://avatars.githubusercontent.com/u/13888940?u=d0d45d5e2d7efd880a32d030fb222a51406c986f&v=4 url: https://github.com/0xsummerday + - login: xncbf + avatarUrl: https://avatars.githubusercontent.com/u/9462045?u=a80a7bb349555b277645632ed66639ff43400614&v=4 + url: https://github.com/xncbf - login: DaxServer avatarUrl: https://avatars.githubusercontent.com/u/7479937?u=cf2f97f958e47b209679d6aa2ad8723ef0d1cd0f&v=4 url: https://github.com/DaxServer diff --git a/docs/en/data/topic_repos.yml b/docs/en/data/topic_repos.yml index 01ede9c..938fc01 100644 --- a/docs/en/data/topic_repos.yml +++ b/docs/en/data/topic_repos.yml @@ -1,372 +1,387 @@ repos: - name: headroom html_url: https://github.com/headroomlabs-ai/headroom - stars: 65565 + stars: 68267 owner_login: headroomlabs-ai owner_html_url: https://github.com/headroomlabs-ai - name: full-stack-fastapi-template html_url: https://github.com/fastapi/full-stack-fastapi-template - stars: 44681 + stars: 45272 owner_login: fastapi owner_html_url: https://github.com/fastapi - name: Hello-Python html_url: https://github.com/mouredev/Hello-Python - stars: 36837 + stars: 37219 owner_login: mouredev owner_html_url: https://github.com/mouredev - name: serve html_url: https://github.com/jina-ai/serve - stars: 21863 + stars: 21860 owner_login: jina-ai owner_html_url: https://github.com/jina-ai - name: HivisionIDPhotos html_url: https://github.com/Zeyi-Lin/HivisionIDPhotos - stars: 21351 + stars: 21468 owner_login: Zeyi-Lin owner_html_url: https://github.com/Zeyi-Lin - name: Douyin_TikTok_Download_API html_url: https://github.com/Evil0ctal/Douyin_TikTok_Download_API - stars: 19234 + stars: 19776 owner_login: Evil0ctal owner_html_url: https://github.com/Evil0ctal - name: sqlmodel html_url: https://github.com/fastapi/sqlmodel - stars: 18254 + stars: 18295 owner_login: fastapi owner_html_url: https://github.com/fastapi - name: fastapi-best-practices html_url: https://github.com/zhanymkanov/fastapi-best-practices - stars: 17860 + stars: 18006 owner_login: zhanymkanov owner_html_url: https://github.com/zhanymkanov - name: SurfSense html_url: https://github.com/MODSetter/SurfSense - stars: 15831 + stars: 16046 owner_login: MODSetter owner_html_url: https://github.com/MODSetter - name: machine-learning-zoomcamp html_url: https://github.com/DataTalksClub/machine-learning-zoomcamp - stars: 13871 + stars: 14069 owner_login: DataTalksClub owner_html_url: https://github.com/DataTalksClub - name: XHS-Downloader html_url: https://github.com/JoeanAmier/XHS-Downloader - stars: 12279 + stars: 12563 owner_login: JoeanAmier owner_html_url: https://github.com/JoeanAmier -- name: peewee - html_url: https://github.com/coleifer/peewee - stars: 11980 - owner_login: coleifer - owner_html_url: https://github.com/coleifer - name: fastapi_mcp html_url: https://github.com/tadata-org/fastapi_mcp - stars: 11977 + stars: 11994 owner_login: tadata-org owner_html_url: https://github.com/tadata-org +- name: peewee + html_url: https://github.com/coleifer/peewee + stars: 11986 + owner_login: coleifer + owner_html_url: https://github.com/coleifer - name: awesome-fastapi html_url: https://github.com/mjhea0/awesome-fastapi - stars: 11583 + stars: 11633 owner_login: mjhea0 owner_html_url: https://github.com/mjhea0 +- name: WhisperLiveKit + html_url: https://github.com/QuentinFuxa/WhisperLiveKit + stars: 10983 + owner_login: QuentinFuxa + owner_html_url: https://github.com/QuentinFuxa - name: polar html_url: https://github.com/polarsource/polar - stars: 10174 + stars: 10225 owner_login: polarsource owner_html_url: https://github.com/polarsource - name: pycaret html_url: https://github.com/pycaret/pycaret - stars: 9835 + stars: 9833 owner_login: pycaret owner_html_url: https://github.com/pycaret - name: FastUI html_url: https://github.com/pydantic/FastUI - stars: 8964 + stars: 8953 owner_login: pydantic owner_html_url: https://github.com/pydantic - name: FileCodeBox html_url: https://github.com/vastsa/FileCodeBox - stars: 8452 + stars: 8498 owner_login: vastsa owner_html_url: https://github.com/vastsa - name: hatchet html_url: https://github.com/hatchet-dev/hatchet - stars: 7688 + stars: 7824 owner_login: hatchet-dev owner_html_url: https://github.com/hatchet-dev - name: nonebot2 html_url: https://github.com/nonebot/nonebot2 - stars: 7657 + stars: 7691 owner_login: nonebot owner_html_url: https://github.com/nonebot - name: honcho html_url: https://github.com/plastic-labs/honcho - stars: 6533 + stars: 6974 owner_login: plastic-labs owner_html_url: https://github.com/plastic-labs - name: Yuxi html_url: https://github.com/xerrors/Yuxi - stars: 6415 + stars: 6604 owner_login: xerrors owner_html_url: https://github.com/xerrors - name: fastapi-users html_url: https://github.com/fastapi-users/fastapi-users - stars: 6212 + stars: 6236 owner_login: fastapi-users owner_html_url: https://github.com/fastapi-users - name: serge html_url: https://github.com/serge-chat/serge - stars: 5716 + stars: 5712 owner_login: serge-chat owner_html_url: https://github.com/serge-chat -- name: Kokoro-FastAPI - html_url: https://github.com/remsky/Kokoro-FastAPI - stars: 5304 - owner_login: remsky - owner_html_url: https://github.com/remsky - name: YouDub-webui html_url: https://github.com/liuzhao1225/YouDub-webui - stars: 5256 + stars: 5401 owner_login: liuzhao1225 owner_html_url: https://github.com/liuzhao1225 +- name: Kokoro-FastAPI + html_url: https://github.com/remsky/Kokoro-FastAPI + stars: 5392 + owner_login: remsky + owner_html_url: https://github.com/remsky +- name: dramaclaw + html_url: https://github.com/dramaclaw/dramaclaw + stars: 4892 + owner_login: dramaclaw + owner_html_url: https://github.com/dramaclaw - name: devpush html_url: https://github.com/hunvreus/devpush - stars: 4739 + stars: 4747 owner_login: hunvreus owner_html_url: https://github.com/hunvreus - name: strawberry html_url: https://github.com/strawberry-graphql/strawberry - stars: 4702 + stars: 4710 owner_login: strawberry-graphql owner_html_url: https://github.com/strawberry-graphql -- name: poem - html_url: https://github.com/poem-web/poem - stars: 4430 - owner_login: poem-web - owner_html_url: https://github.com/poem-web - name: logfire html_url: https://github.com/pydantic/logfire - stars: 4416 + stars: 4449 owner_login: pydantic owner_html_url: https://github.com/pydantic -- name: dynaconf - html_url: https://github.com/dynaconf/dynaconf - stars: 4320 - owner_login: dynaconf - owner_html_url: https://github.com/dynaconf -- name: huma - html_url: https://github.com/danielgtaylor/huma - stars: 4302 - owner_login: danielgtaylor - owner_html_url: https://github.com/danielgtaylor +- name: poem + html_url: https://github.com/poem-web/poem + stars: 4438 + owner_login: poem-web + owner_html_url: https://github.com/poem-web - name: mcp-context-forge html_url: https://github.com/IBM/mcp-context-forge - stars: 4286 + stars: 4400 owner_login: IBM owner_html_url: https://github.com/IBM +- name: huma + html_url: https://github.com/danielgtaylor/huma + stars: 4365 + owner_login: danielgtaylor + owner_html_url: https://github.com/danielgtaylor +- name: dynaconf + html_url: https://github.com/dynaconf/dynaconf + stars: 4325 + owner_login: dynaconf + owner_html_url: https://github.com/dynaconf - name: chatgpt-web-share html_url: https://github.com/chatpire/chatgpt-web-share stars: 4273 owner_login: chatpire owner_html_url: https://github.com/chatpire +- name: tick-stock-panel + html_url: https://github.com/shy3130/tick-stock-panel + stars: 4101 + owner_login: shy3130 + owner_html_url: https://github.com/shy3130 - name: atrilabs-engine html_url: https://github.com/Atri-Labs/atrilabs-engine - stars: 4068 + stars: 4066 owner_login: Atri-Labs owner_html_url: https://github.com/Atri-Labs - name: datamodel-code-generator html_url: https://github.com/koxudaxi/datamodel-code-generator - stars: 4000 + stars: 4008 owner_login: koxudaxi owner_html_url: https://github.com/koxudaxi - name: LitServe html_url: https://github.com/Lightning-AI/LitServe - stars: 3923 + stars: 3934 owner_login: Lightning-AI owner_html_url: https://github.com/Lightning-AI +- name: RVG + html_url: https://github.com/arvin341az-glitch/RVG + stars: 3906 + owner_login: arvin341az-glitch + owner_html_url: https://github.com/arvin341az-glitch - name: fastapi-admin html_url: https://github.com/fastapi-admin/fastapi-admin - stars: 3810 + stars: 3819 owner_login: fastapi-admin owner_html_url: https://github.com/fastapi-admin - name: tracecat html_url: https://github.com/TracecatHQ/tracecat - stars: 3761 + stars: 3782 owner_login: TracecatHQ owner_html_url: https://github.com/TracecatHQ -- name: farfalle - html_url: https://github.com/rashadphz/farfalle - stars: 3539 - owner_login: rashadphz - owner_html_url: https://github.com/rashadphz - name: Rapid-MLX html_url: https://github.com/raullenchai/Rapid-MLX - stars: 3423 + stars: 3630 owner_login: raullenchai owner_html_url: https://github.com/raullenchai -- name: dramaclaw - html_url: https://github.com/dramaclaw/dramaclaw - stars: 3373 - owner_login: dramaclaw - owner_html_url: https://github.com/dramaclaw +- name: farfalle + html_url: https://github.com/rashadphz/farfalle + stars: 3543 + owner_login: rashadphz + owner_html_url: https://github.com/rashadphz +- name: OpenExecutive + html_url: https://github.com/SenteLabsAI/OpenExecutive + stars: 3322 + owner_login: SenteLabsAI + owner_html_url: https://github.com/SenteLabsAI +- name: any-auto-register + html_url: https://github.com/lxf746/any-auto-register + stars: 3221 + owner_login: lxf746 + owner_html_url: https://github.com/lxf746 - name: opyrator html_url: https://github.com/ml-tooling/opyrator - stars: 3133 + stars: 3131 owner_login: ml-tooling owner_html_url: https://github.com/ml-tooling - name: docarray html_url: https://github.com/docarray/docarray - stars: 3123 + stars: 3124 owner_login: docarray owner_html_url: https://github.com/docarray -- name: any-auto-register - html_url: https://github.com/lxf746/any-auto-register - stars: 3111 - owner_login: lxf746 - owner_html_url: https://github.com/lxf746 - name: fastapi-realworld-example-app html_url: https://github.com/nsidnev/fastapi-realworld-example-app - stars: 3108 + stars: 3107 owner_login: nsidnev owner_html_url: https://github.com/nsidnev - name: uvicorn-gunicorn-fastapi-docker html_url: https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker - stars: 2915 + stars: 2916 owner_login: tiangolo owner_html_url: https://github.com/tiangolo +- name: codex-lb + html_url: https://github.com/Soju06/codex-lb + stars: 2904 + owner_login: Soju06 + owner_html_url: https://github.com/Soju06 - name: FastAPI-template html_url: https://github.com/s3rius/FastAPI-template - stars: 2815 + stars: 2826 owner_login: s3rius owner_html_url: https://github.com/s3rius - name: sqladmin html_url: https://github.com/smithyhq/sqladmin - stars: 2808 + stars: 2817 owner_login: smithyhq owner_html_url: https://github.com/smithyhq - name: YC-Killer html_url: https://github.com/sahibzada-allahyar/YC-Killer - stars: 2792 + stars: 2805 owner_login: sahibzada-allahyar owner_html_url: https://github.com/sahibzada-allahyar -- name: best-of-web-python - html_url: https://github.com/ml-tooling/best-of-web-python - stars: 2750 - owner_login: ml-tooling - owner_html_url: https://github.com/ml-tooling - name: NoteDiscovery html_url: https://github.com/gamosoft/NoteDiscovery - stars: 2737 + stars: 2776 owner_login: gamosoft owner_html_url: https://github.com/gamosoft -- name: tickflow-stock-panel - html_url: https://github.com/shy3130/tickflow-stock-panel - stars: 2684 - owner_login: shy3130 - owner_html_url: https://github.com/shy3130 -- name: codex-lb - html_url: https://github.com/Soju06/codex-lb - stars: 2641 - owner_login: Soju06 - owner_html_url: https://github.com/Soju06 -- name: fastapi-react - html_url: https://github.com/Buuntu/fastapi-react - stars: 2583 - owner_login: Buuntu - owner_html_url: https://github.com/Buuntu +- name: best-of-web-python + html_url: https://github.com/ml-tooling/best-of-web-python + stars: 2755 + owner_login: ml-tooling + owner_html_url: https://github.com/ml-tooling - name: fastapi-langgraph-agent-production-ready-template html_url: https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template - stars: 2568 + stars: 2630 owner_login: wassim249 owner_html_url: https://github.com/wassim249 +- name: fastapi-react + html_url: https://github.com/Buuntu/fastapi-react + stars: 2584 + owner_login: Buuntu + owner_html_url: https://github.com/Buuntu - name: supabase-py html_url: https://github.com/supabase/supabase-py - stars: 2555 + stars: 2571 owner_login: supabase owner_html_url: https://github.com/supabase - name: fastapi-best-architecture html_url: https://github.com/fastapi-practices/fastapi-best-architecture - stars: 2505 + stars: 2530 owner_login: fastapi-practices owner_html_url: https://github.com/fastapi-practices - name: 30-Days-of-Python html_url: https://github.com/codingforentrepreneurs/30-Days-of-Python - stars: 2501 + stars: 2511 owner_login: codingforentrepreneurs owner_html_url: https://github.com/codingforentrepreneurs - name: AIstudioProxyAPI html_url: https://github.com/CJackHwang/AIstudioProxyAPI - stars: 2475 + stars: 2496 owner_login: CJackHwang owner_html_url: https://github.com/CJackHwang - name: RasaGPT html_url: https://github.com/paulpierre/RasaGPT - stars: 2464 + stars: 2463 owner_login: paulpierre owner_html_url: https://github.com/paulpierre +- name: open-wearables + html_url: https://github.com/the-momentum/open-wearables + stars: 2432 + owner_login: the-momentum + owner_html_url: https://github.com/the-momentum - name: nextpy html_url: https://github.com/dot-agent/nextpy - stars: 2343 + stars: 2349 owner_login: dot-agent owner_html_url: https://github.com/dot-agent - name: langserve html_url: https://github.com/langchain-ai/langserve - stars: 2331 + stars: 2329 owner_login: langchain-ai owner_html_url: https://github.com/langchain-ai -- name: open-wearables - html_url: https://github.com/the-momentum/open-wearables - stars: 2311 - owner_login: the-momentum - owner_html_url: https://github.com/the-momentum - name: fastapi-utils html_url: https://github.com/fastapiutils/fastapi-utils - stars: 2305 + stars: 2309 owner_login: fastapiutils owner_html_url: https://github.com/fastapiutils -- name: vue-fastapi-admin - html_url: https://github.com/mizhexiaoxiao/vue-fastapi-admin - stars: 2221 - owner_login: mizhexiaoxiao - owner_html_url: https://github.com/mizhexiaoxiao - name: kiro-gateway html_url: https://github.com/jwadow/kiro-gateway - stars: 2198 + stars: 2251 owner_login: jwadow owner_html_url: https://github.com/jwadow +- name: vue-fastapi-admin + html_url: https://github.com/mizhexiaoxiao/vue-fastapi-admin + stars: 2245 + owner_login: mizhexiaoxiao + owner_html_url: https://github.com/mizhexiaoxiao - name: solara html_url: https://github.com/widgetti/solara - stars: 2167 + stars: 2172 owner_login: widgetti owner_html_url: https://github.com/widgetti - name: mangum html_url: https://github.com/Kludex/mangum - stars: 2130 + stars: 2131 owner_login: Kludex owner_html_url: https://github.com/Kludex -- name: xhs_ai_publisher - html_url: https://github.com/BetaStreetOmnis/xhs_ai_publisher - stars: 2053 - owner_login: BetaStreetOmnis - owner_html_url: https://github.com/BetaStreetOmnis - name: FastAPI-boilerplate html_url: https://github.com/benavlabs/FastAPI-boilerplate - stars: 2044 + stars: 2070 owner_login: benavlabs owner_html_url: https://github.com/benavlabs +- name: xhs_ai_publisher + html_url: https://github.com/BetaStreetOmnis/xhs_ai_publisher + stars: 2068 + owner_login: BetaStreetOmnis + owner_html_url: https://github.com/BetaStreetOmnis - name: slowapi html_url: https://github.com/laurentS/slowapi - stars: 2041 + stars: 2052 owner_login: laurentS owner_html_url: https://github.com/laurentS - name: openapi-python-client html_url: https://github.com/openapi-generators/openapi-python-client - stars: 1979 + stars: 1985 owner_login: openapi-generators owner_html_url: https://github.com/openapi-generators - name: agentkit html_url: https://github.com/BCG-X-Official/agentkit - stars: 1948 + stars: 1949 owner_login: BCG-X-Official owner_html_url: https://github.com/BCG-X-Official - name: piccolo @@ -374,14 +389,9 @@ repos: stars: 1936 owner_login: piccolo-orm owner_html_url: https://github.com/piccolo-orm -- name: Vibe-Research - html_url: https://github.com/simonlin1212/Vibe-Research - stars: 1923 - owner_login: simonlin1212 - owner_html_url: https://github.com/simonlin1212 - name: manage-fastapi html_url: https://github.com/ycd/manage-fastapi - stars: 1909 + stars: 1907 owner_login: ycd owner_html_url: https://github.com/ycd - name: fastapi-cache @@ -391,34 +401,39 @@ repos: owner_html_url: https://github.com/long2ice - name: WebRPA html_url: https://github.com/pmh1314520/WebRPA - stars: 1832 + stars: 1866 owner_login: pmh1314520 owner_html_url: https://github.com/pmh1314520 +- name: full-stack-ai-agent-template + html_url: https://github.com/vstorm-co/full-stack-ai-agent-template + stars: 1862 + owner_login: vstorm-co + owner_html_url: https://github.com/vstorm-co +- name: creatorhub + html_url: https://github.com/3441293738/creatorhub + stars: 1816 + owner_login: '3441293738' + owner_html_url: https://github.com/3441293738 - name: ormar html_url: https://github.com/ormar-orm/ormar - stars: 1804 + stars: 1802 owner_login: ormar-orm owner_html_url: https://github.com/ormar-orm - name: python-week-2022 html_url: https://github.com/rochacbruno/python-week-2022 - stars: 1801 + stars: 1797 owner_login: rochacbruno owner_html_url: https://github.com/rochacbruno - name: termpair html_url: https://github.com/cs01/termpair - stars: 1775 + stars: 1779 owner_login: cs01 owner_html_url: https://github.com/cs01 - name: bracket html_url: https://github.com/evroon/bracket - stars: 1709 + stars: 1728 owner_login: evroon owner_html_url: https://github.com/evroon -- name: full-stack-ai-agent-template - html_url: https://github.com/vstorm-co/full-stack-ai-agent-template - stars: 1697 - owner_login: vstorm-co - owner_html_url: https://github.com/vstorm-co - name: fastapi-crudrouter html_url: https://github.com/awtkns/fastapi-crudrouter stars: 1696 @@ -426,7 +441,7 @@ repos: owner_html_url: https://github.com/awtkns - name: fastapi-pagination html_url: https://github.com/uriyyo/fastapi-pagination - stars: 1674 + stars: 1680 owner_login: uriyyo owner_html_url: https://github.com/uriyyo - name: langchain-serve @@ -436,61 +451,46 @@ repos: owner_html_url: https://github.com/jina-ai - name: awesome-fastapi-projects html_url: https://github.com/Kludex/awesome-fastapi-projects - stars: 1615 + stars: 1618 owner_login: Kludex owner_html_url: https://github.com/Kludex - name: docling-api html_url: https://github.com/drmingler/docling-api - stars: 1570 + stars: 1597 owner_login: drmingler owner_html_url: https://github.com/drmingler +- name: fastcrud + html_url: https://github.com/benavlabs/fastcrud + stars: 1577 + owner_login: benavlabs + owner_html_url: https://github.com/benavlabs - name: coronavirus-tracker-api html_url: https://github.com/ExpDev07/coronavirus-tracker-api - stars: 1570 + stars: 1569 owner_login: ExpDev07 owner_html_url: https://github.com/ExpDev07 - name: fastapi-amis-admin html_url: https://github.com/amisadmin/fastapi-amis-admin - stars: 1564 + stars: 1566 owner_login: amisadmin owner_html_url: https://github.com/amisadmin -- name: fastcrud - html_url: https://github.com/benavlabs/fastcrud - stars: 1545 - owner_login: benavlabs - owner_html_url: https://github.com/benavlabs - name: tavily-key-generator html_url: https://github.com/skernelx/tavily-key-generator - stars: 1542 + stars: 1553 owner_login: skernelx owner_html_url: https://github.com/skernelx -- name: fastapi-boilerplate - html_url: https://github.com/teamhide/fastapi-boilerplate - stars: 1491 - owner_login: teamhide - owner_html_url: https://github.com/teamhide -- name: prometheus-fastapi-instrumentator - html_url: https://github.com/trallnag/prometheus-fastapi-instrumentator - stars: 1478 - owner_login: trallnag - owner_html_url: https://github.com/trallnag -- name: RuoYi-Vue3-FastAPI - html_url: https://github.com/insistence/RuoYi-Vue3-FastAPI - stars: 1478 - owner_login: insistence - owner_html_url: https://github.com/insistence - name: yubal html_url: https://github.com/guillevc/yubal - stars: 1469 + stars: 1529 owner_login: guillevc owner_html_url: https://github.com/guillevc -- name: aktools - html_url: https://github.com/akfamily/aktools - stars: 1457 - owner_login: akfamily - owner_html_url: https://github.com/akfamily -- name: awesome-python-resources - html_url: https://github.com/DjangoEx/awesome-python-resources - stars: 1455 - owner_login: DjangoEx - owner_html_url: https://github.com/DjangoEx +- name: RuoYi-Vue3-FastAPI + html_url: https://github.com/insistence/RuoYi-Vue3-FastAPI + stars: 1516 + owner_login: insistence + owner_html_url: https://github.com/insistence +- name: FileSync + html_url: https://github.com/polius/FileSync + stars: 1494 + owner_login: polius + owner_html_url: https://github.com/polius diff --git a/docs/en/docs/css/custom.css b/docs/en/docs/css/custom.css index 147181c..a6fcc27 100644 --- a/docs/en/docs/css/custom.css +++ b/docs/en/docs/css/custom.css @@ -437,6 +437,105 @@ Inspired by Termynal's CSS tricks with modifications .fastapi-sponsors__card--silver .fastapi-sponsors__banner { height: 50px; } } +.fastapi-conf-rail { + display: block; + margin: 1.25rem 0.5rem 0; + padding: 0.9rem 0.85rem 0.85rem; + border: 1px solid var(--md-default-fg-color--lightest); + border-left: 3px solid var(--md-primary-fg-color); + border-radius: 0.2rem; + background: color-mix(in srgb, var(--md-primary-fg-color) 6%, transparent); + color: var(--md-default-fg-color); + text-decoration: none; + transition: border-color 0.15s ease, background-color 0.15s ease, transform 0.15s ease; +} + +.fastapi-conf-rail__eyebrow { + display: block; + font-size: 0.56rem; + font-weight: 700; + letter-spacing: 0.11em; + text-transform: uppercase; + color: var(--md-primary-fg-color); +} + +.fastapi-conf-rail__date { + display: block; + margin-top: 0.45rem; + font-size: 0.74rem; + font-weight: 700; + line-height: 1.25; +} + +.fastapi-conf-rail__place { + display: block; + margin-top: 0.1rem; + font-size: 0.68rem; + line-height: 1.3; + color: var(--md-default-fg-color--light); +} + +.fastapi-conf-rail__summary { + display: block; + margin-top: 0.55rem; + font-size: 0.67rem; + line-height: 1.5; + color: var(--md-default-fg-color--light); +} + +.fastapi-conf-rail__cta { + display: block; + margin-top: 0.65rem; + font-size: 0.68rem; + font-weight: 700; + color: var(--md-primary-fg-color); +} + +.fastapi-conf-rail:hover { + border-color: var(--md-primary-fg-color); + background: color-mix(in srgb, var(--md-primary-fg-color) 10%, transparent); +} + +.fastapi-conf-rail:hover .fastapi-conf-rail__cta, +.fastapi-conf-rail:focus-visible .fastapi-conf-rail__cta { + color: var(--md-accent-fg-color); + text-decoration: underline; +} + +.fastapi-conf-rail:focus-visible { + outline: 2px solid var(--md-accent-fg-color); + outline-offset: 2px; +} + +.fastapi-conf-rail--mobile { + display: none; +} + +@media screen and (max-width: 76.234375em) { + .fastapi-conf-rail:not(.fastapi-conf-rail--mobile) { + display: none; + } + + .md-typeset .fastapi-conf-rail--mobile { + display: grid; + grid-template-columns: minmax(0, 1fr) auto; + margin: 0 0 1.25rem; + text-decoration: none; + } + + .fastapi-conf-rail--mobile .fastapi-conf-rail__summary { + display: none; + } + + .fastapi-conf-rail--mobile .fastapi-conf-rail__cta { + grid-column: 2; + grid-row: 1 / 4; + align-self: center; + margin: 0 0 0 0.8rem; + white-space: nowrap; + } +} + .fastapi-feature-banner { display: block; max-width: 680px; diff --git a/docs/en/docs/img/fastapi-conf.jpeg b/docs/en/docs/img/fastapi-conf.jpeg deleted file mode 100644 index 14e77b9..0000000 Binary files a/docs/en/docs/img/fastapi-conf.jpeg and /dev/null differ diff --git a/docs/en/docs/index.md b/docs/en/docs/index.md index b9086f4..d7b35a2 100644 --- a/docs/en/docs/index.md +++ b/docs/en/docs/index.md @@ -151,12 +151,6 @@ The key features are:
-## FastAPI Conf { #fastapi-conf } - -[**FastAPI Conf '26**](https://fastapiconf.com) is happening on **October 28, 2026** in **Amsterdam, NL**. All about FastAPI, right from the source. 🎤 - -FastAPI Conf '26 - October 28, 2026 - Amsterdam, NL - ## FastAPI mini documentary { #fastapi-mini-documentary } There's a [FastAPI mini documentary](https://www.youtube.com/watch?v=mpR8ngthqiE) released at the end of 2025, you can watch it online: diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index deb7541..bffd7a0 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,16 +7,49 @@ hide: ## Latest Changes +### Refactors + +* 📱 Improve mobile responsiveness of conference rail. PR [#16196](https://github.com/fastapi/fastapi/pull/16196) by [@alejsdev](https://github.com/alejsdev). +* ♻️ Remove conf section and add event banner. PR [#16193](https://github.com/fastapi/fastapi/pull/16193) by [@alejsdev](https://github.com/alejsdev). + ### Docs +* 🔥 Remove unused image. PR [#16195](https://github.com/fastapi/fastapi/pull/16195) by [@alejsdev](https://github.com/alejsdev). * 🐛 Use buttons for Termynal controls. PR [#16132](https://github.com/fastapi/fastapi/pull/16132) by [@tiangolo](https://github.com/tiangolo). ### Translations +* 🌐 Update translations for hi (update-outdated). PR [#16212](https://github.com/fastapi/fastapi/pull/16212) by [@pr-submit[bot]](https://github.com/apps/pr-submit). +* 🌐 Update translations for ru (update-outdated). PR [#16210](https://github.com/fastapi/fastapi/pull/16210) by [@pr-submit[bot]](https://github.com/apps/pr-submit). +* 🌐 Update translations for zh-hant (update-outdated). PR [#16211](https://github.com/fastapi/fastapi/pull/16211) by [@pr-submit[bot]](https://github.com/apps/pr-submit). +* 🌐 Update translations for uk (update-outdated). PR [#16208](https://github.com/fastapi/fastapi/pull/16208) by [@pr-submit[bot]](https://github.com/apps/pr-submit). +* 🌐 Update translations for de (update-outdated). PR [#16209](https://github.com/fastapi/fastapi/pull/16209) by [@pr-submit[bot]](https://github.com/apps/pr-submit). +* 🌐 Update translations for tr (update-outdated). PR [#16207](https://github.com/fastapi/fastapi/pull/16207) by [@pr-submit[bot]](https://github.com/apps/pr-submit). +* 🌐 Update translations for ja (update-outdated). PR [#16206](https://github.com/fastapi/fastapi/pull/16206) by [@pr-submit[bot]](https://github.com/apps/pr-submit). +* 🌐 Update translations for fr (update-outdated). PR [#16205](https://github.com/fastapi/fastapi/pull/16205) by [@pr-submit[bot]](https://github.com/apps/pr-submit). +* 🌐 Update translations for zh (update-outdated). PR [#16204](https://github.com/fastapi/fastapi/pull/16204) by [@pr-submit[bot]](https://github.com/apps/pr-submit). +* 🌐 Update translations for es (update-outdated). PR [#16203](https://github.com/fastapi/fastapi/pull/16203) by [@pr-submit[bot]](https://github.com/apps/pr-submit). +* 🌐 Update translations for pt (update-outdated). PR [#16202](https://github.com/fastapi/fastapi/pull/16202) by [@pr-submit[bot]](https://github.com/apps/pr-submit). +* 🌐 Update translations for ko (update-outdated). PR [#16201](https://github.com/fastapi/fastapi/pull/16201) by [@pr-submit[bot]](https://github.com/apps/pr-submit). * 🌐 Update translations for ko (update-outdated). PR [#16171](https://github.com/fastapi/fastapi/pull/16171) by [@pr-submit[bot]](https://github.com/apps/pr-submit). ### Internal +* ⬆ Bump the python-packages group across 1 directory with 15 updates. PR [#16285](https://github.com/fastapi/fastapi/pull/16285) by [@dependabot[bot]](https://github.com/apps/dependabot). +* ⬆ Bump starlette from 1.3.1 to 1.6.0. PR [#16289](https://github.com/fastapi/fastapi/pull/16289) by [@dependabot[bot]](https://github.com/apps/dependabot). +* ⬆ Bump annotated-doc from 0.0.4 to 0.0.5. PR [#16288](https://github.com/fastapi/fastapi/pull/16288) by [@dependabot[bot]](https://github.com/apps/dependabot). +* ⬆ Bump typing-inspection from 0.4.2 to 0.4.4. PR [#16286](https://github.com/fastapi/fastapi/pull/16286) by [@dependabot[bot]](https://github.com/apps/dependabot). +* ⬆ Bump fastar from 0.11.0 to 0.12.0. PR [#16287](https://github.com/fastapi/fastapi/pull/16287) by [@dependabot[bot]](https://github.com/apps/dependabot). +* ⬆ Bump the github-actions group with 5 updates. PR [#16284](https://github.com/fastapi/fastapi/pull/16284) by [@dependabot[bot]](https://github.com/apps/dependabot). +* ⬆ Bump pre-commit hooks. PR [#16290](https://github.com/fastapi/fastapi/pull/16290) by [@pr-submit[bot]](https://github.com/apps/pr-submit). +* 👥 Update FastAPI GitHub topic repositories. PR [#16291](https://github.com/fastapi/fastapi/pull/16291) by [@pr-submit[bot]](https://github.com/apps/pr-submit). +* 👥 Update FastAPI People - Sponsors. PR [#16282](https://github.com/fastapi/fastapi/pull/16282) by [@pr-submit[bot]](https://github.com/apps/pr-submit). +* ⬆️ Bump Typer min version to 0.26.1. PR [#16252](https://github.com/fastapi/fastapi/pull/16252) by [@YuriiMotov](https://github.com/YuriiMotov). +* ⬆️ Bump `setup-uv` action to `10.0.1`. PR [#16249](https://github.com/fastapi/fastapi/pull/16249) by [@YuriiMotov](https://github.com/YuriiMotov). +* 👷 Update translation PR branches with PR Push. PR [#16224](https://github.com/fastapi/fastapi/pull/16224) by [@tiangolo](https://github.com/tiangolo). +* ⏪️ Restore `commit_in_place` input in `translate.yml`. PR [#16216](https://github.com/fastapi/fastapi/pull/16216) by [@YuriiMotov](https://github.com/YuriiMotov). +* 👷 Migrate automatic labels to Latest Changes. PR [#16185](https://github.com/fastapi/fastapi/pull/16185) by [@tiangolo](https://github.com/tiangolo). +* 👷 Fix branch name in `zizmor.yml` workflow (`main` -> `master`). PR [#16178](https://github.com/fastapi/fastapi/pull/16178) by [@YuriiMotov](https://github.com/YuriiMotov). * 👷 Remove legacy label check. PR [#16180](https://github.com/fastapi/fastapi/pull/16180) by [@tiangolo](https://github.com/tiangolo). * ⬆ Bump pymdown-extensions from 11.0 to 11.0.1. PR [#16162](https://github.com/fastapi/fastapi/pull/16162) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump gitpython from 3.1.57 to 3.1.58. PR [#16157](https://github.com/fastapi/fastapi/pull/16157) by [@dependabot[bot]](https://github.com/apps/dependabot). diff --git a/docs/en/overrides/main.html b/docs/en/overrides/main.html index 1905a65..9acf758 100644 --- a/docs/en/overrides/main.html +++ b/docs/en/overrides/main.html @@ -1,5 +1,57 @@ {% extends "base.html" %} +{% block site_nav %} + {% if nav %} + {% if page.meta and page.meta.hide %} + {% set hidden = "hidden" if "navigation" in page.meta.hide %} + {% endif %} + + {% endif %} + {% if "toc.integrate" not in features %} + {% if page.meta and page.meta.hide %} + {% set hidden = "hidden" if "toc" in page.meta.hide %} + {% endif %} + + {% endif %} +{% endblock %} + +{% block content %} + {% if not page.url %} + {% set conf_rail_mobile = true %} + {% include "partials/conf-rail.html" %} + {% endif %} + {% include "partials/content.html" %} +{% endblock %} + {% block announce %}
diff --git a/docs/en/overrides/partials/conf-rail.html b/docs/en/overrides/partials/conf-rail.html new file mode 100644 index 0000000..c4be54a --- /dev/null +++ b/docs/en/overrides/partials/conf-rail.html @@ -0,0 +1,7 @@ + + FastAPI Conf '26 + October 28, 2026 + Amsterdam, NL + All about FastAPI, right from the source. + Learn more + diff --git a/docs/es/docs/advanced/additional-responses.md b/docs/es/docs/advanced/additional-responses.md index 6695caf..cff4431 100644 --- a/docs/es/docs/advanced/additional-responses.md +++ b/docs/es/docs/advanced/additional-responses.md @@ -243,5 +243,5 @@ Por ejemplo: Para ver exactamente qué puedes incluir en los responses, puedes revisar estas secciones en la especificación OpenAPI: -* [Objeto de Responses de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object), incluye el `Response Object`. -* [Objeto de Response de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object), puedes incluir cualquier cosa de esto directamente en cada response dentro de tu parámetro `responses`. Incluyendo `description`, `headers`, `content` (dentro de este es que declaras diferentes media types y JSON Schemas), y `links`. +* [Objeto de Responses de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object), incluye el `Response Object`. +* [Objeto de Response de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object), puedes incluir cualquier cosa de esto directamente en cada response dentro de tu parámetro `responses`. Incluyendo `description`, `headers`, `content` (dentro de este es que declaras diferentes media types y JSON Schemas), y `links`. diff --git a/docs/es/docs/advanced/async-tests.md b/docs/es/docs/advanced/async-tests.md index 4ccd664..500baf3 100644 --- a/docs/es/docs/advanced/async-tests.md +++ b/docs/es/docs/advanced/async-tests.md @@ -45,7 +45,7 @@ Puedes ejecutar tus tests como de costumbre vía:
```console -$ pytest +$ uv run pytest ---> 100% ``` diff --git a/docs/es/docs/advanced/behind-a-proxy.md b/docs/es/docs/advanced/behind-a-proxy.md index 31d38c1..a6cf0cc 100644 --- a/docs/es/docs/advanced/behind-a-proxy.md +++ b/docs/es/docs/advanced/behind-a-proxy.md @@ -33,7 +33,7 @@ Si tu **server** está detrás de un **proxy** confiable y solo el proxy le habl
```console -$ fastapi run --forwarded-allow-ips="*" +$ uv run fastapi run --forwarded-allow-ips="*" INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -170,7 +170,7 @@ Para lograr esto, puedes usar la opción de línea de comandos `--root-path` com
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -200,7 +200,7 @@ Luego, si inicias Uvicorn con:
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -253,7 +253,7 @@ En un caso así (sin un prefijo de path eliminado), el proxy escucharía algo co Puedes ejecutar fácilmente el experimento localmente con un prefijo de path eliminado usando [Traefik](https://docs.traefik.io/). -[Descarga Traefik](https://github.com/containous/traefik/releases), es un archivo binario único, puedes extraer el archivo comprimido y ejecutarlo directamente desde la terminal. +[Descarga Traefik](https://github.com/traefik/traefik/releases), es un archivo binario único, puedes extraer el archivo comprimido y ejecutarlo directamente desde la terminal. Luego crea un archivo `traefik.toml` con: @@ -321,7 +321,7 @@ Y ahora inicia tu app, utilizando la opción `--root-path`:
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/es/docs/advanced/dataclasses.md b/docs/es/docs/advanced/dataclasses.md index 9c988dc..ee603d8 100644 --- a/docs/es/docs/advanced/dataclasses.md +++ b/docs/es/docs/advanced/dataclasses.md @@ -6,7 +6,7 @@ Pero FastAPI también soporta el uso de [`dataclasses`](https://docs.python.org/ {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -Esto sigue siendo soportado gracias a **Pydantic**, ya que tiene [soporte interno para `dataclasses`](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel). +Esto sigue siendo soportado gracias a **Pydantic**, ya que tiene [soporte interno para `dataclasses`](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/#usage-of-stdlib-dataclasses-with-basemodel). Así que, incluso con el código anterior que no usa Pydantic explícitamente, FastAPI está usando Pydantic para convertir esos dataclasses estándar en su propia versión de dataclasses de Pydantic. @@ -88,7 +88,7 @@ Revisa los consejos de anotación en el código arriba para ver más detalles es También puedes combinar `dataclasses` con otros modelos de Pydantic, heredar de ellos, incluirlos en tus propios modelos, etc. -Para saber más, revisa la [documentación de Pydantic sobre dataclasses](https://docs.pydantic.dev/latest/concepts/dataclasses/). +Para saber más, revisa la [documentación de Pydantic sobre dataclasses](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/). ## Versión { #version } diff --git a/docs/es/docs/advanced/events.md b/docs/es/docs/advanced/events.md index 1d221e0..361c607 100644 --- a/docs/es/docs/advanced/events.md +++ b/docs/es/docs/advanced/events.md @@ -154,7 +154,7 @@ Por debajo, en la especificación técnica ASGI, esto es parte del [Protocolo de /// note | Nota -Puedes leer más sobre los manejadores `lifespan` de Starlette en [la documentación de `Lifespan` de Starlette](https://www.starlette.dev/lifespan/). +Puedes leer más sobre los manejadores `lifespan` de Starlette en [la documentación de Lifespan de Starlette](https://starlette.dev/lifespan/). Incluyendo cómo manejar el estado de lifespan que puede ser usado en otras áreas de tu código. diff --git a/docs/es/docs/advanced/generate-clients.md b/docs/es/docs/advanced/generate-clients.md index a44c922..71e3274 100644 --- a/docs/es/docs/advanced/generate-clients.md +++ b/docs/es/docs/advanced/generate-clients.md @@ -12,7 +12,7 @@ Una opción versátil es el [OpenAPI Generator](https://openapi-generator.tech/) Para **clientes de TypeScript**, [Hey API](https://heyapi.dev/) es una solución diseñada específicamente, que ofrece una experiencia optimizada para el ecosistema de TypeScript. -Puedes descubrir más generadores de SDK en [OpenAPI.Tools](https://openapi.tools/#sdk). +Puedes descubrir más generadores de SDK en [OpenAPI.Tools](https://openapi.tools/categories/sdk-generators). /// tip | Consejo diff --git a/docs/es/docs/advanced/middleware.md b/docs/es/docs/advanced/middleware.md index bfe7026..bc2905a 100644 --- a/docs/es/docs/advanced/middleware.md +++ b/docs/es/docs/advanced/middleware.md @@ -91,7 +91,7 @@ Hay muchos otros middlewares ASGI. Por ejemplo: -* [`ProxyHeadersMiddleware` de Uvicorn](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) +* [`ProxyHeadersMiddleware` de Uvicorn](https://github.com/Kludex/uvicorn/blob/main/uvicorn/middleware/proxy_headers.py) * [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -Para ver otros middlewares disponibles, revisa [la documentación de Middleware de Starlette](https://www.starlette.dev/middleware/) y la [Lista ASGI Awesome](https://github.com/florimondmanca/awesome-asgi). +Para ver otros middlewares disponibles, revisa [la documentación de Middleware de Starlette](https://starlette.dev/middleware/) y la [Lista ASGI Awesome](https://github.com/florimondmanca/awesome-asgi). diff --git a/docs/es/docs/advanced/openapi-callbacks.md b/docs/es/docs/advanced/openapi-callbacks.md index 6b04f2d..4172030 100644 --- a/docs/es/docs/advanced/openapi-callbacks.md +++ b/docs/es/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ Esta parte es bastante normal, probablemente ya estés familiarizado con la mayo /// tip | Consejo -El parámetro de query `callback_url` utiliza un tipo [Url](https://docs.pydantic.dev/latest/api/networks/) de Pydantic. +El parámetro de query `callback_url` utiliza un tipo [Url](https://pydantic.dev/docs/validation/latest/api/pydantic/networks/) de Pydantic. /// @@ -106,11 +106,11 @@ Debería verse como una *path operation* normal de FastAPI: Hay 2 diferencias principales respecto a una *path operation* normal: * No necesita tener ningún código real, porque tu aplicación nunca llamará a este código. Solo se usa para documentar la *API externa*. Así que, la función podría simplemente tener `pass`. -* El *path* puede contener una [expresión OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) (ver más abajo) donde puede usar variables con parámetros y partes del request original enviado a *tu API*. +* El *path* puede contener una [expresión OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression) (ver más abajo) donde puede usar variables con parámetros y partes del request original enviado a *tu API*. ### La expresión del path del callback { #the-callback-path-expression } -El *path* del callback puede tener una [expresión OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) que puede contener partes del request original enviado a *tu API*. +El *path* del callback puede tener una [expresión OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression) que puede contener partes del request original enviado a *tu API*. En este caso, es el `str`: @@ -165,7 +165,7 @@ Observa cómo la URL del callback utilizada contiene la URL recibida como parám ### Agrega el router de callback { #add-the-callback-router } -En este punto tienes las *path operation(s)* del callback necesarias (las que el *desarrollador externo* debería implementar en la *API externa*) en el router de callback que creaste arriba. +En este punto tienes las *callback path operation(s)* necesarias (las que el *desarrollador externo* debería implementar en la *API externa*) en el router de callback que creaste arriba. Ahora usa el parámetro `callbacks` en el *decorador de path operation de tu API* para pasar el atributo `.routes` de ese router de callback: diff --git a/docs/es/docs/advanced/response-cookies.md b/docs/es/docs/advanced/response-cookies.md index 917072c..373fb8d 100644 --- a/docs/es/docs/advanced/response-cookies.md +++ b/docs/es/docs/advanced/response-cookies.md @@ -48,4 +48,4 @@ Y como el `Response` se puede usar frecuentemente para establecer headers y cook /// -Para ver todos los parámetros y opciones disponibles, revisa la [documentación en Starlette](https://www.starlette.dev/responses/#set-cookie). +Para ver todos los parámetros y opciones disponibles, revisa la [documentación en Starlette](https://starlette.dev/responses/#set-cookie). diff --git a/docs/es/docs/advanced/response-headers.md b/docs/es/docs/advanced/response-headers.md index e2eb8f5..0a75fd4 100644 --- a/docs/es/docs/advanced/response-headers.md +++ b/docs/es/docs/advanced/response-headers.md @@ -1,6 +1,5 @@ # Headers de Response { #response-headers } - ## Usa un parámetro `Response` { #use-a-response-parameter } Puedes declarar un parámetro de tipo `Response` en tu *path operation function* (como puedes hacer para cookies). @@ -39,4 +38,4 @@ Y como el `Response` se puede usar frecuentemente para establecer headers y cook Ten en cuenta que los headers propietarios personalizados se pueden agregar [usando el prefijo `X-`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). -Pero si tienes headers personalizados que quieres que un cliente en un navegador pueda ver, necesitas agregarlos a tus configuraciones de CORS (leer más en [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)), usando el parámetro `expose_headers` documentado en [la documentación CORS de Starlette](https://www.starlette.dev/middleware/#corsmiddleware). +Pero si tienes headers personalizados que quieres que un cliente en un navegador pueda ver, necesitas agregarlos a tus configuraciones de CORS (leer más en [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)), usando el parámetro `expose_headers` documentado en [la documentación CORS de Starlette](https://starlette.dev/middleware/#corsmiddleware). diff --git a/docs/es/docs/advanced/settings.md b/docs/es/docs/advanced/settings.md index e61229f..12d68d0 100644 --- a/docs/es/docs/advanced/settings.md +++ b/docs/es/docs/advanced/settings.md @@ -6,30 +6,34 @@ La mayoría de estas configuraciones son variables (pueden cambiar), como las UR Por esta razón, es común proporcionarlas en variables de entorno que son leídas por la aplicación. +Una **variable de entorno** (también conocida como una **env var**) es un valor que vive fuera del código Python, en el sistema operativo, y puede ser leído por tu aplicación y otros programas. + +Puedes crear una variable de entorno para un comando cuando lo ejecutas. Verás los comandos específicos de cada plataforma más abajo. + /// tip | Consejo -Para entender las variables de entorno, puedes leer [Variables de Entorno](../environment-variables.md). +Lee la [guía de Variables de Entorno](https://tiangolo.com/guides/environment-variables/) para una explicación detallada de cómo funcionan las variables de entorno. /// ## Tipos y validación { #types-and-validation } -Estas variables de entorno solo pueden manejar strings de texto, ya que son externas a Python y tienen que ser compatibles con otros programas y el resto del sistema (e incluso con diferentes sistemas operativos, como Linux, Windows, macOS). +Estas variables de entorno solo pueden manejar strings de texto, ya que son externas a Python y tienen que ser compatibles con otros programas y el resto del sistema (e incluso con diferentes sistemas operativos, como Linux, Windows, y macOS). Eso significa que cualquier valor leído en Python desde una variable de entorno será un `str`, y cualquier conversión a un tipo diferente o cualquier validación tiene que hacerse en código. ## Pydantic `Settings` { #pydantic-settings } -Afortunadamente, Pydantic proporciona una gran utilidad para manejar estas configuraciones provenientes de variables de entorno con [Pydantic: Gestión de Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/). +Afortunadamente, Pydantic proporciona una gran utilidad para manejar estas configuraciones provenientes de variables de entorno con [Pydantic: Gestión de Settings](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/). ### Instalar `pydantic-settings` { #install-pydantic-settings } -Primero, asegúrate de crear tu [entorno virtual](../virtual-environments.md), actívalo y luego instala el paquete `pydantic-settings`: +Añade el paquete `pydantic-settings` a tu proyecto:
```console -$ pip install pydantic-settings +$ uv add pydantic-settings ---> 100% ``` @@ -40,7 +44,7 @@ También viene incluido cuando instalas los extras `all` con:
```console -$ pip install "fastapi[all]" +$ uv add "fastapi[all]" ---> 100% ``` @@ -76,19 +80,39 @@ Luego puedes usar el nuevo objeto `settings` en tu aplicación: Luego, ejecutarías el servidor pasando las configuraciones como variables de entorno, por ejemplo, podrías establecer un `ADMIN_EMAIL` y `APP_NAME` con: +//// tab | Linux, macOS, Windows Bash +
```console -$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py +$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uv run fastapi run main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
+//// + +//// tab | Windows PowerShell + +
+ +```console +$ $Env:ADMIN_EMAIL = "deadpool@example.com" +$ $Env:APP_NAME = "ChimichangApp" +$ uv run fastapi run main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +//// + /// tip | Consejo -Para establecer múltiples env vars para un solo comando, simplemente sepáralas con un espacio y ponlas todas antes del comando. +En Bash, para establecer múltiples env vars para un solo comando, sepáralas con un espacio y ponlas todas antes del comando. /// @@ -172,11 +196,11 @@ Pero un archivo dotenv realmente no tiene que tener ese nombre exacto. /// -Pydantic tiene soporte para leer desde estos tipos de archivos usando un paquete externo. Puedes leer más en [Pydantic Settings: soporte para Dotenv (.env)](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support). +Pydantic tiene soporte para leer desde estos tipos de archivos usando un paquete externo. Puedes leer más en [Pydantic Settings: soporte para Dotenv (.env)](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#dotenv-env-support). /// tip | Consejo -Para que esto funcione, necesitas `pip install python-dotenv`. +Para que esto funcione, añade `python-dotenv` a tu proyecto con `uv add python-dotenv`. /// @@ -197,7 +221,7 @@ Y luego actualizar tu `config.py` con: /// tip | Consejo -El atributo `model_config` se usa solo para configuración de Pydantic. Puedes leer más en [Pydantic: Conceptos: Configuración](https://docs.pydantic.dev/latest/concepts/config/). +El atributo `model_config` se usa solo para configuración de Pydantic. Puedes leer más en [Pydantic: Conceptos: Configuración](https://pydantic.dev/docs/validation/latest/concepts/config/). /// diff --git a/docs/es/docs/advanced/sub-applications.md b/docs/es/docs/advanced/sub-applications.md index 934bb16..b755143 100644 --- a/docs/es/docs/advanced/sub-applications.md +++ b/docs/es/docs/advanced/sub-applications.md @@ -1,6 +1,6 @@ # Sub Aplicaciones - Mounts { #sub-applications-mounts } -Si necesitas tener dos aplicaciones de **FastAPI** independientes, cada una con su propio OpenAPI independiente y su propia interfaz de docs, puedes tener una aplicación principal y "montar" una (o más) sub-aplicación(es). +Si necesitas tener dos aplicaciones de **FastAPI** independientes, cada una con su propio OpenAPI independiente y su propia interfaz de documentación, puedes tener una aplicación principal y "montar" una (o más) sub-aplicación(es). ## Montar una aplicación **FastAPI** { #mounting-a-fastapi-application } @@ -35,7 +35,7 @@ Ahora, ejecuta el comando `fastapi`:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/es/docs/advanced/templates.md b/docs/es/docs/advanced/templates.md index ce28c30..5bf75be 100644 --- a/docs/es/docs/advanced/templates.md +++ b/docs/es/docs/advanced/templates.md @@ -8,12 +8,12 @@ Hay utilidades para configurarlo fácilmente que puedes usar directamente en tu ## Instala dependencias { #install-dependencies } -Asegúrate de crear un [entorno virtual](../virtual-environments.md), activarlo e instalar `jinja2`: +Añade `jinja2` a tu proyecto:
```console -$ pip install jinja2 +$ uv add jinja2 ---> 100% ``` @@ -123,4 +123,4 @@ Y porque estás usando `StaticFiles`, ese archivo CSS sería servido automática ## Más detalles { #more-details } -Para más detalles, incluyendo cómo testear plantillas, revisa [la documentación de Starlette sobre plantillas](https://www.starlette.dev/templates/). +Para más detalles, incluyendo cómo escribir pruebas para plantillas, revisa [la documentación de Starlette sobre plantillas](https://starlette.dev/templates/). diff --git a/docs/es/docs/advanced/testing-events.md b/docs/es/docs/advanced/testing-events.md index 1ab9458..8a5c156 100644 --- a/docs/es/docs/advanced/testing-events.md +++ b/docs/es/docs/advanced/testing-events.md @@ -1,11 +1,11 @@ -# Eventos de testing: lifespan y startup - shutdown { #testing-events-lifespan-and-startup-shutdown } +# Eventos al escribir pruebas: lifespan y startup - shutdown { #testing-events-lifespan-and-startup-shutdown } Cuando necesitas que `lifespan` se ejecute en tus tests, puedes usar el `TestClient` con un statement `with`: {* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *} -Puedes leer más detalles sobre ["Ejecutar lifespan en tests en el sitio oficial de documentación de Starlette."](https://www.starlette.dev/lifespan/#running-lifespan-in-tests) +Puedes leer más detalles sobre ["Ejecutar lifespan en tests en el sitio oficial de documentación de Starlette."](https://starlette.dev/lifespan/#running-lifespan-in-tests) Para los eventos obsoletos `startup` y `shutdown`, puedes usar el `TestClient` así: diff --git a/docs/es/docs/advanced/testing-websockets.md b/docs/es/docs/advanced/testing-websockets.md index 4736031..b772838 100644 --- a/docs/es/docs/advanced/testing-websockets.md +++ b/docs/es/docs/advanced/testing-websockets.md @@ -8,6 +8,6 @@ Para esto, usas el `TestClient` en un statement `with`, conectándote al WebSock /// note | Nota -Para más detalles, revisa la documentación de Starlette sobre [probar WebSockets](https://www.starlette.dev/testclient/#testing-websocket-sessions). +Para más detalles, revisa la documentación de Starlette sobre [probar WebSockets](https://starlette.dev/testclient/#testing-websocket-sessions). /// diff --git a/docs/es/docs/advanced/using-request-directly.md b/docs/es/docs/advanced/using-request-directly.md index 3aed8e5..b7d071a 100644 --- a/docs/es/docs/advanced/using-request-directly.md +++ b/docs/es/docs/advanced/using-request-directly.md @@ -15,7 +15,7 @@ Pero hay situaciones donde podrías necesitar acceder al objeto `Request` direct ## Detalles sobre el objeto `Request` { #details-about-the-request-object } -Como **FastAPI** es en realidad **Starlette** por debajo, con una capa de varias herramientas encima, puedes usar el objeto de Starlette [`Request`](https://www.starlette.dev/requests/) directamente cuando lo necesites. +Como **FastAPI** es en realidad **Starlette** por debajo, con una capa de varias herramientas encima, puedes usar el objeto de Starlette [`Request`](https://starlette.dev/requests/) directamente cuando lo necesites. También significa que si obtienes datos del objeto `Request` directamente (por ejemplo, leyendo el cuerpo) no serán validados, convertidos o documentados (con OpenAPI, para la interfaz automática de usuario de la API) por FastAPI. @@ -45,7 +45,7 @@ De la misma manera, puedes declarar cualquier otro parámetro como normalmente, ## Documentación de `Request` { #request-documentation } -Puedes leer más detalles sobre el [objeto `Request` en el sitio de documentación oficial de Starlette](https://www.starlette.dev/requests/). +Puedes leer más detalles sobre el [objeto `Request` en el sitio de documentación oficial de Starlette](https://starlette.dev/requests/). /// note | Detalles Técnicos diff --git a/docs/es/docs/advanced/websockets.md b/docs/es/docs/advanced/websockets.md index e3e0ba5..06014d4 100644 --- a/docs/es/docs/advanced/websockets.md +++ b/docs/es/docs/advanced/websockets.md @@ -2,14 +2,14 @@ Puedes usar [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) con **FastAPI**. -## Instalar `websockets` { #install-websockets } +## Instala `websockets` { #install-websockets } -Asegúrate de crear un [entorno virtual](../virtual-environments.md), activarlo e instalar `websockets` (un paquete de Python que facilita usar el protocolo "WebSocket"): +Añade `websockets` (un paquete de Python que facilita usar el protocolo "WebSocket") a tu proyecto:
```console -$ pip install websockets +$ uv add websockets ---> 100% ``` @@ -40,7 +40,7 @@ Pero es la forma más sencilla de enfocarse en el lado del servidor de WebSocket {* ../../docs_src/websockets_/tutorial001_py310.py hl[2,6:38,41:43] *} -## Crear un `websocket` { #create-a-websocket } +## Crea un `websocket` { #create-a-websocket } En tu aplicación de **FastAPI**, crea un `websocket`: @@ -54,7 +54,7 @@ También podrías usar `from starlette.websockets import WebSocket`. /// -## Esperar mensajes y enviar mensajes { #await-for-messages-and-send-messages } +## Espera mensajes y envía mensajes { #await-for-messages-and-send-messages } En tu ruta de WebSocket puedes `await` para recibir mensajes y enviar mensajes. @@ -69,7 +69,7 @@ Pon tu código en un archivo `main.py` y luego ejecuta tu aplicación:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -126,7 +126,7 @@ Ejecuta tu aplicación:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -182,5 +182,5 @@ Si necesitas algo fácil de integrar con FastAPI pero que sea más robusto, sopo Para aprender más sobre las opciones, revisa la documentación de Starlette para: -* [La clase `WebSocket`](https://www.starlette.dev/websockets/). -* [Manejo de WebSocket basado en clases](https://www.starlette.dev/endpoints/#websocketendpoint). +* [La clase `WebSocket`](https://starlette.dev/websockets/). +* [Manejo de WebSocket basado en clases](https://starlette.dev/endpoints/#websocketendpoint). diff --git a/docs/es/docs/advanced/wsgi.md b/docs/es/docs/advanced/wsgi.md index c85b8cc..71ded0b 100644 --- a/docs/es/docs/advanced/wsgi.md +++ b/docs/es/docs/advanced/wsgi.md @@ -9,7 +9,7 @@ Para eso, puedes usar el `WSGIMiddleware` y usarlo para envolver tu aplicación /// note | Nota -Esto requiere instalar `a2wsgi`, por ejemplo con `pip install a2wsgi`. +Esto requiere agregar `a2wsgi` a tu proyecto, por ejemplo con `uv add a2wsgi`. /// diff --git a/docs/es/docs/alternatives.md b/docs/es/docs/alternatives.md index 693e4d5..b85883d 100644 --- a/docs/es/docs/alternatives.md +++ b/docs/es/docs/alternatives.md @@ -125,7 +125,7 @@ Adoptar y usar un estándar abierto para especificaciones de API, en lugar de us Y a integrar herramientas de interfaz de usuario basadas en estándares: * [Swagger UI](https://github.com/swagger-api/swagger-ui) -* [ReDoc](https://github.com/Rebilly/ReDoc) +* [ReDoc](https://github.com/Redocly/redoc) Estas dos fueron elegidas por ser bastante populares y estables, pero haciendo una búsqueda rápida, podrías encontrar docenas de interfaces de usuario alternativas para OpenAPI (que puedes usar con **FastAPI**). @@ -237,11 +237,11 @@ Generar el esquema OpenAPI automáticamente, desde el mismo código que define l /// -### [NestJS](https://nestjs.com/) (y [Angular](https://angular.io/)) { #nestjs-and-angular } +### [NestJS](https://nestjs.com/) (y [Angular](https://angular.dev/)) { #nestjs-and-angular } Esto ni siquiera es Python, NestJS es un framework de JavaScript (TypeScript) NodeJS inspirado por Angular. -Logra algo algo similar a lo que se puede hacer con Flask-apispec. +Logra algo similar a lo que se puede hacer con Flask-apispec. Tiene un sistema de inyección de dependencias integrado, inspirado por Angular 2. Requiere pre-registrar los "inyectables" (como todos los otros sistemas de inyección de dependencias que conozco), por lo que añade a la verbosidad y repetición de código. @@ -337,7 +337,7 @@ Dado que se basa en el estándar previo para frameworks web Python sincrónicos /// note | Nota -Hug fue creado por Timothy Crosley, el mismo creador de [`isort`](https://github.com/timothycrosley/isort), una gran herramienta para ordenar automáticamente imports en archivos Python. +Hug fue creado por Timothy Crosley, el mismo creador de [`isort`](https://github.com/PyCQA/isort), una gran herramienta para ordenar automáticamente imports en archivos Python. /// @@ -401,7 +401,7 @@ Considero a **FastAPI** un "sucesor espiritual" de APIStar, mientras mejora y au ## Usado por **FastAPI** { #used-by-fastapi } -### [Pydantic](https://docs.pydantic.dev/) { #pydantic } +### [Pydantic](https://pydantic.dev/docs/) { #pydantic } Pydantic es un paquete para definir validación de datos, serialización y documentación (usando JSON Schema) basándose en las anotaciones de tipos de Python. @@ -417,7 +417,7 @@ Manejar toda la validación de datos, serialización de datos y documentación a /// -### [Starlette](https://www.starlette.dev/) { #starlette } +### [Starlette](https://starlette.dev/) { #starlette } Starlette es un framework/toolkit ASGI liviano, ideal para construir servicios asyncio de alto rendimiento. @@ -462,7 +462,7 @@ Por lo tanto, cualquier cosa que puedas hacer con Starlette, puedes hacerlo dire /// -### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn } +### [Uvicorn](https://uvicorn.dev) { #uvicorn } Uvicorn es un servidor ASGI extremadamente rápido, construido sobre uvloop y httptools. diff --git a/docs/es/docs/deployment/docker.md b/docs/es/docs/deployment/docker.md index e54f0c2..0b14a5a 100644 --- a/docs/es/docs/deployment/docker.md +++ b/docs/es/docs/deployment/docker.md @@ -106,36 +106,32 @@ Esto es lo que querrías hacer en **la mayoría de los casos**, por ejemplo: ### Requisitos del Paquete { #package-requirements } -Normalmente tendrías los **requisitos del paquete** para tu aplicación en algún archivo. +Cuando gestionas tu proyecto con `uv`, sus dependencias directas se declaran en `pyproject.toml` y las versiones exactas resueltas se almacenan en `uv.lock`. -Dependería principalmente de la herramienta que uses para **instalar** esos requisitos. - -La forma más común de hacerlo es tener un archivo `requirements.txt` con los nombres de los paquetes y sus versiones, uno por línea. - -Por supuesto, usarías las mismas ideas que leíste en [Acerca de las versiones de FastAPI](versions.md) para establecer los rangos de versiones. - -Por ejemplo, tu `requirements.txt` podría verse así: - -``` -fastapi[standard]>=0.113.0,<0.114.0 -pydantic>=2.7.0,<3.0.0 -``` - -Y normalmente instalarías esas dependencias de los paquetes con `pip`, por ejemplo: +Puedes añadir los paquetes que tu aplicación necesita con:
```console -$ pip install -r requirements.txt +$ uv add "fastapi[standard]" pydantic ---> 100% -Successfully installed fastapi pydantic ```
/// note | Nota -Existen otros formatos y herramientas para definir e instalar dependencias de paquetes. +El Dockerfile de abajo usa `pip` dentro del contenedor. Puedes exportar las dependencias bloqueadas de tu proyecto uv al formato `requirements.txt` que espera: + +
+ +```console +$ uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt +``` + +
+ +El `requirements.txt` generado es una exportación para la construcción del contenedor. Continúa gestionando las dependencias con `uv add` y regenéralo cuando cambie `uv.lock`. /// @@ -373,7 +369,7 @@ Verás la documentación interactiva automática de la API (proporcionada por [S Y también puedes ir a [http://192.168.99.100/redoc](http://192.168.99.100/redoc) o [http://127.0.0.1/redoc](http://127.0.0.1/redoc) (o equivalente, usando tu host de Docker). -Verás la documentación alternativa automática (proporcionada por [ReDoc](https://github.com/Rebilly/ReDoc)): +Verás la documentación alternativa automática (proporcionada por [ReDoc](https://github.com/Redocly/redoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) diff --git a/docs/es/docs/deployment/fastapicloud.md b/docs/es/docs/deployment/fastapicloud.md index 9c289f4..559a278 100644 --- a/docs/es/docs/deployment/fastapicloud.md +++ b/docs/es/docs/deployment/fastapicloud.md @@ -5,7 +5,7 @@ Puedes desplegar tu app de FastAPI en [FastAPI Cloud](https://fastapicloud.com)
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... diff --git a/docs/es/docs/deployment/manually.md b/docs/es/docs/deployment/manually.md index 90e25ec..8f5fa55 100644 --- a/docs/es/docs/deployment/manually.md +++ b/docs/es/docs/deployment/manually.md @@ -52,7 +52,7 @@ Lo principal que necesitas para ejecutar una aplicación **FastAPI** (o cualquie Hay varias alternativas, incluyendo: -* [Uvicorn](https://www.uvicorn.dev/): un servidor ASGI de alto rendimiento. +* [Uvicorn](https://uvicorn.dev): un servidor ASGI de alto rendimiento. * [Hypercorn](https://hypercorn.readthedocs.io/): un servidor ASGI compatible con HTTP/2 y Trio entre otras funcionalidades. * [Daphne](https://github.com/django/daphne): el servidor ASGI construido para Django Channels. * [Granian](https://github.com/emmett-framework/granian): Un servidor HTTP Rust para aplicaciones en Python. @@ -73,14 +73,14 @@ Cuando instalas FastAPI, viene con un servidor de producción, Uvicorn, y puedes Pero también puedes instalar un servidor ASGI manualmente. -Asegúrate de crear un [entorno virtual](../virtual-environments.md), actívalo, y luego puedes instalar la aplicación del servidor. +Añade la aplicación de servidor a tu proyecto. Por ejemplo, para instalar Uvicorn:
```console -$ pip install "uvicorn[standard]" +$ uv add "uvicorn[standard]" ---> 100% ``` @@ -95,7 +95,7 @@ Al añadir `standard`, Uvicorn instalará y usará algunas dependencias adiciona Eso incluye `uvloop`, el reemplazo directo de alto rendimiento para `asyncio`, que proporciona un gran impulso de rendimiento en concurrencia. -Cuando instalas FastAPI con algo como `pip install "fastapi[standard]"` ya obtienes `uvicorn[standard]` también. +Cuando añades FastAPI con algo como `uv add "fastapi[standard]"` ya obtienes `uvicorn[standard]` también. /// @@ -106,7 +106,7 @@ Si instalaste un servidor ASGI manualmente, normalmente necesitarías pasar una
```console -$ uvicorn main:app --host 0.0.0.0 --port 80 +$ uv run uvicorn main:app --host 0.0.0.0 --port 80 INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) ``` diff --git a/docs/es/docs/deployment/server-workers.md b/docs/es/docs/deployment/server-workers.md index a7665cc..986fc59 100644 --- a/docs/es/docs/deployment/server-workers.md +++ b/docs/es/docs/deployment/server-workers.md @@ -86,7 +86,7 @@ Si prefieres usar el comando `uvicorn` directamente:
```console -$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 +$ uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit) INFO: Started parent process [27365] INFO: Started server process [27368] diff --git a/docs/es/docs/environment-variables.md b/docs/es/docs/environment-variables.md index aab76eb..695c8e9 100644 --- a/docs/es/docs/environment-variables.md +++ b/docs/es/docs/environment-variables.md @@ -1,299 +1,11 @@ # Variables de Entorno { #environment-variables } +Una **variable de entorno** (también conocida como **env var**) es un valor que vive fuera de tu código de Python, en el sistema operativo, y puede ser leído por tu aplicación y otros programas. -/// tip | Consejo +Las aplicaciones FastAPI comúnmente usan variables de entorno para configuraciones como URLs de bases de datos, credenciales de email y claves secretas. -Si ya sabes qué son las "variables de entorno" y cómo usarlas, siéntete libre de saltarte esto. +Aprenderás cómo usarlas para la configuración de aplicaciones en [Ajustes y Variables de Entorno](advanced/settings.md). -/// +## Aprende Más { #learn-more } -Una variable de entorno (también conocida como "**env var**") es una variable que vive **fuera** del código de Python, en el **sistema operativo**, y podría ser leída por tu código de Python (o por otros programas también). - -Las variables de entorno pueden ser útiles para manejar **configuraciones** de aplicaciones, como parte de la **instalación** de Python, etc. - -## Crear y Usar Variables de Entorno { #create-and-use-env-vars } - -Puedes **crear** y usar variables de entorno en la **shell (terminal)**, sin necesidad de Python: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// Podrías crear una env var MY_NAME con -$ export MY_NAME="Wade Wilson" - -// Luego podrías usarla con otros programas, como -$ echo "Hello $MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// Crea una env var MY_NAME -$ $Env:MY_NAME = "Wade Wilson" - -// Úsala con otros programas, como -$ echo "Hello $Env:MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -## Leer Variables de Entorno en Python { #read-env-vars-in-python } - -También podrías crear variables de entorno **fuera** de Python, en la terminal (o con cualquier otro método), y luego **leerlas en Python**. - -Por ejemplo, podrías tener un archivo `main.py` con: - -```Python hl_lines="3" -import os - -name = os.getenv("MY_NAME", "World") -print(f"Hello {name} from Python") -``` - -/// tip | Consejo - -El segundo argumento de [`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) es el valor por defecto a retornar. - -Si no se proporciona, es `None` por defecto; aquí proporcionamos `"World"` como el valor por defecto para usar. - -/// - -Luego podrías llamar a ese programa Python: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// Aquí todavía no configuramos la env var -$ python main.py - -// Como no configuramos la env var, obtenemos el valor por defecto - -Hello World from Python - -// Pero si creamos una variable de entorno primero -$ export MY_NAME="Wade Wilson" - -// Y luego llamamos al programa nuevamente -$ python main.py - -// Ahora puede leer la variable de entorno - -Hello Wade Wilson from Python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// Aquí todavía no configuramos la env var -$ python main.py - -// Como no configuramos la env var, obtenemos el valor por defecto - -Hello World from Python - -// Pero si creamos una variable de entorno primero -$ $Env:MY_NAME = "Wade Wilson" - -// Y luego llamamos al programa nuevamente -$ python main.py - -// Ahora puede leer la variable de entorno - -Hello Wade Wilson from Python -``` - -
- -//// - -Dado que las variables de entorno pueden configurarse fuera del código, pero pueden ser leídas por el código, y no tienen que ser almacenadas (committed en `git`) con el resto de los archivos, es común usarlas para configuraciones o **ajustes**. - -También puedes crear una variable de entorno solo para una **invocación específica de un programa**, que está disponible solo para ese programa, y solo durante su duración. - -Para hacer eso, créala justo antes del programa en sí, en la misma línea: - -
- -```console -// Crea una env var MY_NAME en línea para esta llamada del programa -$ MY_NAME="Wade Wilson" python main.py - -// Ahora puede leer la variable de entorno - -Hello Wade Wilson from Python - -// La env var ya no existe después -$ python main.py - -Hello World from Python -``` - -
- -/// tip | Consejo - -Puedes leer más al respecto en [The Twelve-Factor App: Config](https://12factor.net/config). - -/// - -## Tipos y Validación { #types-and-validation } - -Estas variables de entorno solo pueden manejar **strings de texto**, ya que son externas a Python y deben ser compatibles con otros programas y el resto del sistema (e incluso con diferentes sistemas operativos, como Linux, Windows, macOS). - -Esto significa que **cualquier valor** leído en Python desde una variable de entorno **será un `str`**, y cualquier conversión a un tipo diferente o cualquier validación tiene que hacerse en el código. - -Aprenderás más sobre cómo usar variables de entorno para manejar **configuraciones de aplicación** en la [Guía del Usuario Avanzado - Ajustes y Variables de Entorno](./advanced/settings.md). - -## Variable de Entorno `PATH` { #path-environment-variable } - -Hay una variable de entorno **especial** llamada **`PATH`** que es utilizada por los sistemas operativos (Linux, macOS, Windows) para encontrar programas a ejecutar. - -El valor de la variable `PATH` es un string largo que consiste en directorios separados por dos puntos `:` en Linux y macOS, y por punto y coma `;` en Windows. - -Por ejemplo, la variable de entorno `PATH` podría verse así: - -//// tab | Linux, macOS - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -Esto significa que el sistema debería buscar programas en los directorios: - -* `/usr/local/bin` -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32 -``` - -Esto significa que el sistema debería buscar programas en los directorios: - -* `C:\Program Files\Python312\Scripts` -* `C:\Program Files\Python312` -* `C:\Windows\System32` - -//// - -Cuando escribes un **comando** en la terminal, el sistema operativo **busca** el programa en **cada uno de esos directorios** listados en la variable de entorno `PATH`. - -Por ejemplo, cuando escribes `python` en la terminal, el sistema operativo busca un programa llamado `python` en el **primer directorio** de esa lista. - -Si lo encuentra, entonces lo **utilizará**. De lo contrario, continúa buscando en los **otros directorios**. - -### Instalando Python y Actualizando el `PATH` { #installing-python-and-updating-the-path } - -Cuando instalas Python, se te podría preguntar si deseas actualizar la variable de entorno `PATH`. - -//// tab | Linux, macOS - -Digamos que instalas Python y termina en un directorio `/opt/custompython/bin`. - -Si dices que sí para actualizar la variable de entorno `PATH`, entonces el instalador añadirá `/opt/custompython/bin` a la variable de entorno `PATH`. - -Podría verse así: - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin -``` - -De esta manera, cuando escribes `python` en la terminal, el sistema encontrará el programa Python en `/opt/custompython/bin` (el último directorio) y usará ese. - -//// - -//// tab | Windows - -Digamos que instalas Python y termina en un directorio `C:\opt\custompython\bin`. - -Si dices que sí para actualizar la variable de entorno `PATH`, entonces el instalador añadirá `C:\opt\custompython\bin` a la variable de entorno `PATH`. - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin -``` - -De esta manera, cuando escribes `python` en la terminal, el sistema encontrará el programa Python en `C:\opt\custompython\bin` (el último directorio) y usará ese. - -//// - -Entonces, si escribes: - -
- -```console -$ python -``` - -
- -//// tab | Linux, macOS - -El sistema **encontrará** el programa `python` en `/opt/custompython/bin` y lo ejecutará. - -Esto sería más o menos equivalente a escribir: - -
- -```console -$ /opt/custompython/bin/python -``` - -
- -//// - -//// tab | Windows - -El sistema **encontrará** el programa `python` en `C:\opt\custompython\bin\python` y lo ejecutará. - -Esto sería más o menos equivalente a escribir: - -
- -```console -$ C:\opt\custompython\bin\python -``` - -
- -//// - -Esta información será útil al aprender sobre [Entornos Virtuales](virtual-environments.md). - -## Conclusión { #conclusion } - -Con esto deberías tener una comprensión básica de qué son las **variables de entorno** y cómo usarlas en Python. - -También puedes leer más sobre ellas en la [Wikipedia para Variable de Entorno](https://en.wikipedia.org/wiki/Environment_variable). - -En muchos casos no es muy obvio cómo las variables de entorno serían útiles y aplicables de inmediato. Pero siguen apareciendo en muchos escenarios diferentes cuando estás desarrollando, así que es bueno conocerlas. - -Por ejemplo, necesitarás esta información en la siguiente sección, sobre [Entornos Virtuales](virtual-environments.md). +Lee la [guía de Variables de Entorno](https://tiangolo.com/guides/environment-variables/) para una explicación detallada y multiplataforma, incluyendo cómo crear y leer variables de entorno y cómo funciona la variable de entorno `PATH`. diff --git a/docs/es/docs/fastapi-cli.md b/docs/es/docs/fastapi-cli.md index 434e2fe..596f14c 100644 --- a/docs/es/docs/fastapi-cli.md +++ b/docs/es/docs/fastapi-cli.md @@ -2,7 +2,7 @@ **FastAPI CLI** es un programa de línea de comandos que puedes usar para servir tu aplicación FastAPI, gestionar tu proyecto FastAPI, y más. -Cuando instalas FastAPI (por ejemplo, con `pip install "fastapi[standard]"`), viene con un programa de línea de comandos que puedes ejecutar en la terminal. +Cuando añades FastAPI a tu proyecto (por ejemplo, con `uv add "fastapi[standard]"`), viene con un programa de línea de comandos que puedes ejecutar en la terminal. Para ejecutar tu aplicación FastAPI en modo de desarrollo, puedes usar el comando `fastapi dev`: @@ -52,7 +52,7 @@ Para producción usarías `fastapi run` en lugar de `fastapi dev`. 🚀 /// -Internamente, **FastAPI CLI** usa [Uvicorn](https://www.uvicorn.dev), un servidor ASGI de alto rendimiento y listo para producción. 😎 +Internamente, **FastAPI CLI** usa [Uvicorn](https://uvicorn.dev), un servidor ASGI de alto rendimiento y listo para producción. 😎 El CLI `fastapi` intentará detectar automáticamente la app de FastAPI que debe ejecutar, asumiendo que es un objeto llamado `app` en un archivo `main.py` (o un par de variantes más). @@ -100,13 +100,13 @@ from backend.main import app También puedes pasar el path del archivo al comando `fastapi dev`, y adivinará el objeto app de FastAPI a usar: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` O también puedes pasar la opción `--entrypoint` al comando `fastapi dev`: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` Pero tendrías que recordar pasar el path\entrypoint correcto cada vez que llames al comando `fastapi`. @@ -119,6 +119,10 @@ Ejecutar `fastapi dev` inicia el modo de desarrollo. Por defecto, **auto-reload** está habilitado, recargando automáticamente el servidor cuando realizas cambios en tu código. Esto consume muchos recursos y podría ser menos estable que cuando está deshabilitado. Deberías usarlo solo para desarrollo. También escucha en la dirección IP `127.0.0.1`, que es la IP para que tu máquina se comunique solo consigo misma (`localhost`). +Antes de importar tu app, `fastapi dev` establece la variable de entorno `FASTAPI_ENV` en `development`. Si `FASTAPI_ENV` ya está establecida, se conserva su valor existente. Esto permite que el código de startup de la app elija un comportamiento adecuado para desarrollo mientras te permite proporcionar un entorno específico de la app como `staging`. + +Los valores convencionales de `FASTAPI_ENV` son `development` y `production`. Actualmente `fastapi run` deja `FASTAPI_ENV` sin cambios, así que establécela explícitamente si tu app necesita detectar el modo de producción. + ## `fastapi run` { #fastapi-run } Ejecutar `fastapi run` inicia FastAPI en modo de producción. diff --git a/docs/es/docs/features.md b/docs/es/docs/features.md index 1feed92..5112ead 100644 --- a/docs/es/docs/features.md +++ b/docs/es/docs/features.md @@ -19,7 +19,7 @@ Interfaces web de documentación y exploración de APIs interactivas. Como el fr ![Interacción Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* Documentación alternativa de API con [**ReDoc**](https://github.com/Rebilly/ReDoc). +* Documentación alternativa de API con [**ReDoc**](https://github.com/Redocly/redoc). ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) @@ -153,13 +153,13 @@ Cualquier integración está diseñada para ser tan simple de usar (con dependen ### Probado { #tested } -* 100% de cobertura de tests. +* cobertura de tests del 100%. * 100% anotada con tipos code base. * Usado en aplicaciones en producción. ## Funcionalidades de Starlette { #starlette-features } -**FastAPI** es totalmente compatible con (y está basado en) [**Starlette**](https://www.starlette.dev/). Así que, cualquier código adicional de Starlette que tengas, también funcionará. +**FastAPI** es totalmente compatible con (y está basado en) [**Starlette**](https://starlette.dev/). Así que, cualquier código adicional de Starlette que tengas, también funcionará. `FastAPI` es en realidad una subclase de `Starlette`. Así que, si ya conoces o usas Starlette, la mayoría de las funcionalidades funcionarán de la misma manera. @@ -177,7 +177,7 @@ Con **FastAPI** obtienes todas las funcionalidades de **Starlette** (ya que Fast ## Funcionalidades de Pydantic { #pydantic-features } -**FastAPI** es totalmente compatible con (y está basado en) [**Pydantic**](https://docs.pydantic.dev/). Por lo tanto, cualquier código adicional de Pydantic que tengas, también funcionará. +**FastAPI** es totalmente compatible con (y está basado en) [**Pydantic**](https://pydantic.dev/docs/). Por lo tanto, cualquier código adicional de Pydantic que tengas, también funcionará. Incluyendo paquetes externos también basados en Pydantic, como ORMs y ODMs para bases de datos. diff --git a/docs/es/docs/help-fastapi.md b/docs/es/docs/help-fastapi.md index e1a8d1a..f652af8 100644 --- a/docs/es/docs/help-fastapi.md +++ b/docs/es/docs/help-fastapi.md @@ -45,20 +45,6 @@ Puedes seguir [a mí (Sebastián Ramírez / `tiangolo`)](https://tiangolo.com), * [@tiangolo.com en **Bluesky**](https://bsky.app/profile/tiangolo.com) * [@tiangolo en **LinkedIn**](https://www.linkedin.com/in/tiangolo/). -## Ayuda a otros con preguntas en GitHub { #help-others-with-questions-in-github } - -Puedes intentar ayudar a otros con sus preguntas en [GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered). - -En muchos casos, puede que ya conozcas la respuesta a esas preguntas. 🤓 - -Si estás ayudando mucho a la gente con sus preguntas, te convertirás en un [FastAPI Expert](fastapi-people.md#fastapi-experts) oficial. 🎉 - -Solo recuerda, el punto más importante es: intenta ser amable. 🤗 - -### Cómo ayudar { #how-to-help } - -Sigue la [guía sobre cómo ayudar](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github) aquí. - ## Haz preguntas { #ask-questions } Puedes [crear una nueva pregunta](https://github.com/fastapi/fastapi/discussions/new?category=questions) en el repositorio de GitHub, por ejemplo para: @@ -68,7 +54,7 @@ Puedes [crear una nueva pregunta](https://github.com/fastapi/fastapi/discussions ## Únete al chat { #join-the-chat } -Únete al 👥 [servidor de chat de Discord](https://discord.gg/VQjSZaeJmf) 👥 y charla con otros en la comunidad de FastAPI. +Únete al 👥 [servidor de chat de Discord](https://discord.com/invite/VQjSZaeJmf) 👥 y charla con otros en la comunidad de FastAPI. /// tip | Consejo @@ -85,3 +71,9 @@ Ten en cuenta que dado que los chats permiten una "conversación más libre", es En GitHub, la plantilla te guiará para escribir la pregunta correcta para que puedas obtener más fácilmente una buena respuesta, o incluso resolver el problema tú mismo antes de preguntar. Las conversaciones en los sistemas de chat tampoco son tan fáciles de buscar como en GitHub; se pierden. + +## Prueba FastAPI Cloud { #try-fastapi-cloud } + +La financiación principal de FastAPI y amigos proviene de [**FastAPI Cloud**](https://fastapicloud.com), una plataforma para desplegar aplicaciones FastAPI de una forma simple y rápida, con un solo comando, `fastapi deploy`. + +FastAPI Cloud está construido por el mismo equipo detrás de FastAPI. Puedes probarlo y considerarlo para tus proyectos. diff --git a/docs/es/docs/history-design-future.md b/docs/es/docs/history-design-future.md index fc1782f..d3f6f72 100644 --- a/docs/es/docs/history-design-future.md +++ b/docs/es/docs/history-design-future.md @@ -54,11 +54,11 @@ Todo de una manera que proporcionara la mejor experiencia de desarrollo para tod ## Requisitos { #requirements } -Después de probar varias alternativas, decidí que iba a usar [**Pydantic**](https://docs.pydantic.dev/) por sus ventajas. +Después de probar varias alternativas, decidí que iba a usar [**Pydantic**](https://pydantic.dev/docs/) por sus ventajas. Luego contribuí a este, para hacerlo totalmente compatible con JSON Schema, para soportar diferentes maneras de definir declaraciones de restricciones, y para mejorar el soporte de los editores (chequeo de tipos, autocompletado) basado en las pruebas en varios editores. -Durante el desarrollo, también contribuí a [**Starlette**](https://www.starlette.dev/), el otro requisito clave. +Durante el desarrollo, también contribuí a [**Starlette**](https://starlette.dev/), el otro requisito clave. ## Desarrollo { #development } diff --git a/docs/es/docs/how-to/custom-request-and-route.md b/docs/es/docs/how-to/custom-request-and-route.md index 5b4d857..b67a4e4 100644 --- a/docs/es/docs/how-to/custom-request-and-route.md +++ b/docs/es/docs/how-to/custom-request-and-route.md @@ -66,7 +66,7 @@ El `dict` `scope` y la función `receive` son ambos parte de la especificación Y esas dos cosas, `scope` y `receive`, son lo que se necesita para crear una nueva instance de `Request`. -Para aprender más sobre el `Request`, revisa [la documentación de Starlette sobre Requests](https://www.starlette.dev/requests/). +Para aprender más sobre el `Request`, revisa [la documentación de Starlette sobre Requests](https://starlette.dev/requests/). /// diff --git a/docs/es/docs/how-to/extending-openapi.md b/docs/es/docs/how-to/extending-openapi.md index b0fa230..6680f1f 100644 --- a/docs/es/docs/how-to/extending-openapi.md +++ b/docs/es/docs/how-to/extending-openapi.md @@ -45,7 +45,7 @@ El parámetro `summary` está disponible en OpenAPI 3.1.0 y versiones superiores Usando la información anterior, puedes usar la misma función de utilidad para generar el esquema de OpenAPI y sobrescribir cada parte que necesites. -Por ejemplo, vamos a añadir [la extensión OpenAPI de ReDoc para incluir un logo personalizado](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo). +Por ejemplo, vamos a añadir [la extensión OpenAPI de ReDoc para incluir un logo personalizado](https://github.com/Redocly/redoc/blob/main/docs/redoc-vendor-extensions.md#x-logo). ### **FastAPI** normal { #normal-fastapi } diff --git a/docs/es/docs/how-to/graphql.md b/docs/es/docs/how-to/graphql.md index a58a117..bcc784b 100644 --- a/docs/es/docs/how-to/graphql.md +++ b/docs/es/docs/how-to/graphql.md @@ -21,7 +21,7 @@ Aquí algunos de los paquetes de **GraphQL** que tienen soporte **ASGI**. Podrí * [Strawberry](https://strawberry.rocks/) 🍓 * Con [documentación para FastAPI](https://strawberry.rocks/docs/integrations/fastapi) * [Ariadne](https://ariadnegraphql.org/) - * Con [documentación para FastAPI](https://ariadnegraphql.org/docs/fastapi-integration) + * Con [documentación para FastAPI](https://ariadnegraphql.org/server/Integrations/fastapi-integration) * [Tartiflette](https://tartiflette.io/) * Con [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) para proporcionar integración con ASGI * [Graphene](https://graphene-python.org/) diff --git a/docs/es/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/es/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index 571554c..d95aae7 100644 --- a/docs/es/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/es/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -24,7 +24,7 @@ Si tienes una app de FastAPI antigua con Pydantic v1, aquí te muestro cómo mig ## Guía oficial { #official-guide } -Pydantic tiene una [Guía de migración](https://docs.pydantic.dev/latest/migration/) oficial de v1 a v2. +Pydantic tiene una [Guía de migración](https://pydantic.dev/docs/validation/latest/get-started/migration/) oficial de v1 a v2. También incluye qué cambió, cómo las validaciones ahora son más correctas y estrictas, posibles consideraciones, etc. diff --git a/docs/es/docs/index.md b/docs/es/docs/index.md index 7a9caec..d1a7044 100644 --- a/docs/es/docs/index.md +++ b/docs/es/docs/index.md @@ -89,7 +89,7 @@ Las funcionalidades clave son:
-
+
@@ -110,7 +110,7 @@ Las funcionalidades clave son:
-## FastAPI Conf { #fastapi-conf } - -[**FastAPI Conf '26**](https://fastapiconf.com) se llevará a cabo el **28 de octubre de 2026** en **Ámsterdam, NL**. Todo sobre FastAPI, directo de la fuente. 🎤 - -FastAPI Conf '26 - October 28, 2026 - Amsterdam, NL - ## Mini documental de FastAPI { #fastapi-mini-documentary } Hay un [mini documental de FastAPI](https://www.youtube.com/watch?v=mpR8ngthqiE) lanzado a finales de 2025, puedes verlo online: @@ -175,17 +169,17 @@ Si estás construyendo una aplicación de ```console -$ pip install "fastapi[standard]" +$ uv add "fastapi[standard]" ---> 100% ``` @@ -194,6 +188,8 @@ $ pip install "fastapi[standard]" **Nota**: Asegúrate de poner `"fastapi[standard]"` entre comillas para asegurar que funcione en todas las terminales. +Si prefieres usar `pip`, instala `fastapi[standard]` dentro de un entorno virtual. Mira la [guía de instalación](tutorial/#install-fastapi) para los pasos alternativos. + ## Ejemplo { #example } ### Créalo { #create-it } @@ -250,7 +246,7 @@ Corre el servidor con:
```console -$ fastapi dev +$ uv run fastapi dev ╭────────── FastAPI CLI - Development mode ───────────╮ │ │ @@ -277,7 +273,7 @@ INFO: Application startup complete.
Acerca del comando fastapi dev... -El comando `fastapi dev` lee tu archivo `main.py` automáticamente, detecta la app **FastAPI** en él y arranca un servidor usando [Uvicorn](https://www.uvicorn.dev). +El comando `fastapi dev` lee tu archivo `main.py` automáticamente, detecta la app **FastAPI** en él y arranca un servidor usando [Uvicorn](https://uvicorn.dev). Por defecto, `fastapi dev` comenzará con auto-recarga habilitada para el desarrollo local. @@ -314,7 +310,7 @@ Verás la documentación interactiva automática de la API (proporcionada por [S Y ahora, ve a [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc). -Verás la documentación alternativa automática (proporcionada por [ReDoc](https://github.com/Rebilly/ReDoc)): +Verás la documentación alternativa automática (proporcionada por [ReDoc](https://github.com/Redocly/redoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -497,7 +493,7 @@ Opcionalmente puedes desplegar tu app de FastAPI en [FastAPI Cloud](https://fast
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -540,7 +536,7 @@ FastAPI depende de Pydantic y Starlette. ### Dependencias `standard` { #standard-dependencies } -Cuando instalas FastAPI con `pip install "fastapi[standard]"` viene con el grupo `standard` de dependencias opcionales: +Cuando instalas FastAPI con `uv add "fastapi[standard]"` viene con el grupo `standard` de dependencias opcionales: Usadas por Pydantic: @@ -554,17 +550,17 @@ Usadas por Starlette: Usadas por FastAPI: -* [`uvicorn`](https://www.uvicorn.dev) - para el servidor que carga y sirve tu aplicación. Esto incluye `uvicorn[standard]`, que incluye algunas dependencias (por ejemplo, `uvloop`) necesarias para servir con alto rendimiento. +* [`uvicorn`](https://uvicorn.dev) - para el servidor que carga y sirve tu aplicación. Esto incluye `uvicorn[standard]`, que incluye algunas dependencias (por ejemplo, `uvloop`) necesarias para servir con alto rendimiento. * `fastapi-cli[standard]` - para proporcionar el comando `fastapi`. * Esto incluye `fastapi-cloud-cli`, que te permite desplegar tu aplicación de FastAPI en [FastAPI Cloud](https://fastapicloud.com). ### Sin Dependencias `standard` { #without-standard-dependencies } -Si no deseas incluir las dependencias opcionales `standard`, puedes instalar con `pip install fastapi` en lugar de `pip install "fastapi[standard]"`. +Si no deseas incluir las dependencias opcionales `standard`, puedes instalar con `uv add fastapi` en lugar de `uv add "fastapi[standard]"`. ### Sin `fastapi-cloud-cli` { #without-fastapi-cloud-cli } -Si quieres instalar FastAPI con las dependencias standard pero sin `fastapi-cloud-cli`, puedes instalar con `pip install "fastapi[standard-no-fastapi-cloud-cli]"`. +Si quieres instalar FastAPI con las dependencias standard pero sin `fastapi-cloud-cli`, puedes instalar con `uv add "fastapi[standard-no-fastapi-cloud-cli]"`. ### Dependencias Opcionales Adicionales { #additional-optional-dependencies } @@ -572,13 +568,13 @@ Existen algunas dependencias adicionales que podrías querer instalar. Dependencias opcionales adicionales de Pydantic: -* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - para la gestión de configuraciones. -* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - para tipos extra para ser usados con Pydantic. +* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) - para la gestión de configuraciones. +* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) - para tipos extra para ser usados con Pydantic. Dependencias opcionales adicionales de FastAPI: * [`orjson`](https://github.com/ijl/orjson) - Requerido si deseas usar `ORJSONResponse`. -* [`ujson`](https://github.com/esnme/ultrajson) - Requerido si deseas usar `UJSONResponse`. +* [`ujson`](https://github.com/ultrajson/ultrajson) - Requerido si deseas usar `UJSONResponse`. ## Licencia { #license } diff --git a/docs/es/docs/project-generation.md b/docs/es/docs/project-generation.md index fd0fd70..4046298 100644 --- a/docs/es/docs/project-generation.md +++ b/docs/es/docs/project-generation.md @@ -4,13 +4,13 @@ Las plantillas, aunque normalmente vienen con una configuración específica, es Puedes usar esta plantilla para comenzar, ya que incluye gran parte de la configuración inicial, seguridad, base de datos y algunos endpoints de API ya hechos para ti. -Repositorio de GitHub: [Plantilla Full Stack FastAPI](https://github.com/tiangolo/full-stack-fastapi-template) +Repositorio de GitHub: [Plantilla Full Stack FastAPI](https://github.com/fastapi/full-stack-fastapi-template) ## Plantilla Full Stack FastAPI - Stack de tecnología y funcionalidades { #full-stack-fastapi-template-technology-stack-and-features } - ⚡ [**FastAPI**](https://fastapi.tiangolo.com/es) para la API del backend en Python. - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) para las interacciones con bases de datos SQL en Python (ORM). - - 🔍 [Pydantic](https://docs.pydantic.dev), utilizado por FastAPI, para la validación de datos y gestión de configuraciones. + - 🔍 [Pydantic](https://pydantic.dev/docs/), utilizado por FastAPI, para la validación de datos y gestión de configuraciones. - 💾 [PostgreSQL](https://www.postgresql.org) como base de datos SQL. - 🚀 [React](https://react.dev) para el frontend. - 💃 Usando TypeScript, hooks, Vite, y otras partes de una stack moderna de frontend. diff --git a/docs/es/docs/python-types.md b/docs/es/docs/python-types.md index 6a13b97..2453ec6 100644 --- a/docs/es/docs/python-types.md +++ b/docs/es/docs/python-types.md @@ -269,7 +269,7 @@ No significa "`one_person` es la **clase** llamada `Person`". ## Modelos Pydantic { #pydantic-models } -[Pydantic](https://docs.pydantic.dev/) es un paquete de Python para realizar la validación de datos. +[Pydantic](https://pydantic.dev/docs/) es un paquete de Python para realizar la validación de datos. Declaras la "forma" de los datos como clases con atributos. @@ -285,7 +285,7 @@ Un ejemplo de la documentación oficial de Pydantic: /// note | Nota -Para saber más sobre [Pydantic, revisa su documentación](https://docs.pydantic.dev/). +Para saber más sobre [Pydantic, revisa su documentación](https://pydantic.dev/docs/). /// diff --git a/docs/es/docs/tutorial/background-tasks.md b/docs/es/docs/tutorial/background-tasks.md index 6ae265b..c0b4e40 100644 --- a/docs/es/docs/tutorial/background-tasks.md +++ b/docs/es/docs/tutorial/background-tasks.md @@ -19,7 +19,7 @@ Primero, importa `BackgroundTasks` y define un parámetro en tu *path operation **FastAPI** creará el objeto de tipo `BackgroundTasks` por ti y lo pasará como ese parámetro. -## Crear una función de tarea { #create-a-task-function } +## Crea una función de tarea { #create-a-task-function } Crea una función para que se ejecute como la tarea en segundo plano. @@ -33,9 +33,9 @@ Y como la operación de escritura no usa `async` y `await`, definimos la funció {* ../../docs_src/background_tasks/tutorial001_py310.py hl[6:9] *} -## Agregar la tarea en segundo plano { #add-the-background-task } +## Agrega la tarea en segundo plano { #add-the-background-task } -Dentro de tu *path operation function*, pasa tu función de tarea al objeto de *background tasks* con el método `.add_task()`: +Dentro de tu *path operation function*, pasa tu función de tarea al objeto de *tareas en segundo plano* con el método `.add_task()`: {* ../../docs_src/background_tasks/tutorial001_py310.py hl[14] *} @@ -51,8 +51,10 @@ Usar `BackgroundTasks` también funciona con el sistema de inyección de depende **FastAPI** sabe qué hacer en cada caso y cómo reutilizar el mismo objeto, de modo que todas las tareas en segundo plano se combinan y ejecutan en segundo plano después: + {* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *} + En este ejemplo, los mensajes se escribirán en el archivo `log.txt` *después* de que se envíe el response. Si hay un query en el request, se escribirá en el log en una tarea en segundo plano. @@ -61,7 +63,7 @@ Y luego otra tarea en segundo plano generada en la *path operation function* esc ## Detalles Técnicos { #technical-details } -La clase `BackgroundTasks` proviene directamente de [`starlette.background`](https://www.starlette.dev/background/). +La clase `BackgroundTasks` proviene directamente de [`starlette.background`](https://starlette.dev/background/). Se importa/incluye directamente en FastAPI para que puedas importarla desde `fastapi` y evitar importar accidentalmente la alternativa `BackgroundTask` (sin la `s` al final) de `starlette.background`. @@ -69,7 +71,7 @@ Al usar solo `BackgroundTasks` (y no `BackgroundTask`), es posible usarla como u Todavía es posible usar `BackgroundTask` solo en FastAPI, pero debes crear el objeto en tu código y devolver una `Response` de Starlette incluyéndolo. -Puedes ver más detalles en [la documentación oficial de Starlette sobre Background Tasks](https://www.starlette.dev/background/). +Puedes ver más detalles en [la documentación oficial de Starlette sobre Background Tasks](https://starlette.dev/background/). ## Advertencia { #caveat } diff --git a/docs/es/docs/tutorial/bigger-applications.md b/docs/es/docs/tutorial/bigger-applications.md index 31688d8..8da56dc 100644 --- a/docs/es/docs/tutorial/bigger-applications.md +++ b/docs/es/docs/tutorial/bigger-applications.md @@ -81,7 +81,7 @@ Pero todavía es parte de la misma aplicación/web API de **FastAPI** (es parte Puedes crear las *path operations* para ese módulo usando `APIRouter`. -### Importar `APIRouter` { #import-apirouter } +### Importa `APIRouter` { #import-apirouter } Lo importas y creas una "instance" de la misma manera que lo harías con la clase `FastAPI`: @@ -200,7 +200,7 @@ Los parámetros `prefix`, `tags`, `responses`, y `dependencies` son (como en muc /// -### Importar las dependencias { #import-the-dependencies } +### Importa las dependencias { #import-the-dependencies } Este código vive en el módulo `app.routers.items`, el archivo `app/routers/items.py`. @@ -273,7 +273,7 @@ Eso se referiría a algún paquete arriba de `app/`, con su propio archivo `__in Pero ahora sabes cómo funciona, para que puedas usar imports relativos en tus propias apps sin importar cuán complejas sean. 🤓 -### Agregar algunos `tags`, `responses`, y `dependencies` personalizados { #add-some-custom-tags-responses-and-dependencies } +### Agrega algunos `tags`, `responses`, y `dependencies` personalizados { #add-some-custom-tags-responses-and-dependencies } No estamos agregando el prefijo `/items` ni los `tags=["items"]` a cada *path operation* porque los hemos añadido al `APIRouter`. @@ -299,7 +299,7 @@ Este será el archivo principal en tu aplicación que conecta todo. Y como la mayor parte de tu lógica ahora vivirá en su propio módulo específico, el archivo principal será bastante simple. -### Importar `FastAPI` { #import-fastapi } +### Importa `FastAPI` { #import-fastapi } Importas y creas una clase `FastAPI` como normalmente. @@ -307,7 +307,7 @@ Y podemos incluso declarar [dependencias globales](dependencies/global-dependenc {* ../../docs_src/bigger_applications/app_an_py310/main.py hl[1,3,7] title["app/main.py"] *} -### Importar el `APIRouter` { #import-the-apirouter } +### Importa el `APIRouter` { #import-the-apirouter } Ahora importamos los otros submódulos que tienen `APIRouter`s: @@ -315,7 +315,7 @@ Ahora importamos los otros submódulos que tienen `APIRouter`s: Como los archivos `app/routers/users.py` y `app/routers/items.py` son submódulos que son parte del mismo paquete de Python `app`, podemos usar un solo punto `.` para importarlos usando "imports relativos". -### Cómo funciona la importación { #how-the-importing-works } +### Cómo funciona el import { #how-the-importing-works } La sección: @@ -357,7 +357,7 @@ Para aprender más sobre Paquetes y Módulos de Python, lee [la documentación o /// -### Evitar colisiones de nombres { #avoid-name-collisions } +### Evita colisiones de nombres { #avoid-name-collisions } Estamos importando el submódulo `items` directamente, en lugar de importar solo su variable `router`. @@ -376,7 +376,7 @@ Así que, para poder usar ambos en el mismo archivo, importamos los submódulos {* ../../docs_src/bigger_applications/app_an_py310/main.py hl[5] title["app/main.py"] *} -### Incluir los `APIRouter`s para `users` y `items` { #include-the-apirouters-for-users-and-items } +### Incluye los `APIRouter`s para `users` y `items` { #include-the-apirouters-for-users-and-items } Ahora, incluyamos los `router`s de los submódulos `users` y `items`: @@ -412,7 +412,7 @@ Así que no afectará el rendimiento. ⚡ /// -### Incluir un `APIRouter` con un `prefix`, `tags`, `responses`, y `dependencies` personalizados { #include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies } +### Incluye un `APIRouter` con un `prefix`, `tags`, `responses`, y `dependencies` personalizados { #include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies } Ahora, imaginemos que tu organización te dio el archivo `app/internal/admin.py`. @@ -441,7 +441,7 @@ Pero eso solo afectará a ese `APIRouter` en nuestra app, no en ningún otro có Así, por ejemplo, otros proyectos podrían usar el mismo `APIRouter` con un método de autenticación diferente. -### Incluir una *path operation* { #include-a-path-operation } +### Incluye una *path operation* { #include-a-path-operation } También podemos agregar *path operations* directamente a la app de `FastAPI`. @@ -465,7 +465,7 @@ FastAPI mantiene los routers y path operations originales activos, y combina los /// -## Configurar el `entrypoint` en `pyproject.toml` { #configure-the-entrypoint-in-pyproject-toml } +## Configura el `entrypoint` en `pyproject.toml` { #configure-the-entrypoint-in-pyproject-toml } Como tu objeto `app` de FastAPI vive en `app/main.py`, puedes configurar el `entrypoint` en tu archivo `pyproject.toml` así: @@ -487,7 +487,7 @@ De esa manera el comando `fastapi` sabrá dónde encontrar tu app. También podrías pasar la ruta al comando, como: ```console -$ fastapi dev app/main.py +$ uv run fastapi dev app/main.py ``` Pero tendrías que recordar pasar la ruta correcta cada vez que llames al comando `fastapi`. @@ -503,7 +503,7 @@ Ahora, ejecuta tu app:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -516,7 +516,7 @@ Verás la documentación automática de la API, incluyendo los paths de todos lo -## Incluir el mismo router múltiples veces con diferentes `prefix` { #include-the-same-router-multiple-times-with-different-prefix } +## Incluye el mismo router múltiples veces con diferentes `prefix` { #include-the-same-router-multiple-times-with-different-prefix } También puedes usar `.include_router()` múltiples veces con el *mismo* router usando diferentes prefijos. @@ -524,7 +524,7 @@ Esto podría ser útil, por ejemplo, para exponer la misma API bajo diferentes p Este es un uso avanzado que quizás no necesites realmente, pero está allí en caso de que lo necesites. -## Incluir un `APIRouter` en otro { #include-an-apirouter-in-another } +## Incluye un `APIRouter` en otro { #include-an-apirouter-in-another } De la misma manera que puedes incluir un `APIRouter` en una aplicación `FastAPI`, puedes incluir un `APIRouter` en otro `APIRouter` usando: diff --git a/docs/es/docs/tutorial/body-nested-models.md b/docs/es/docs/tutorial/body-nested-models.md index 3ca5860..2a452fb 100644 --- a/docs/es/docs/tutorial/body-nested-models.md +++ b/docs/es/docs/tutorial/body-nested-models.md @@ -96,7 +96,7 @@ Nuevamente, haciendo solo esa declaración, con **FastAPI** obtienes: Además de tipos singulares normales como `str`, `int`, `float`, etc., puedes usar tipos singulares más complejos que heredan de `str`. -Para ver todas las opciones que tienes, Revisa [Resumen de tipos de Pydantic](https://docs.pydantic.dev/latest/concepts/types/). Verás algunos ejemplos en el siguiente capítulo. +Para ver todas las opciones que tienes, Revisa [Resumen de tipos de Pydantic](https://pydantic.dev/docs/validation/latest/concepts/types/). Verás algunos ejemplos en el siguiente capítulo. Por ejemplo, como en el modelo `Image` tenemos un campo `url`, podemos declararlo como una instance de `HttpUrl` de Pydantic en lugar de un `str`: diff --git a/docs/es/docs/tutorial/body.md b/docs/es/docs/tutorial/body.md index a71b81a..2dceac1 100644 --- a/docs/es/docs/tutorial/body.md +++ b/docs/es/docs/tutorial/body.md @@ -7,7 +7,7 @@ Un **request** body es un dato enviado por el cliente a tu API. Un **response** Tu API casi siempre tiene que enviar un **response** body. Pero los clientes no necesariamente necesitan enviar **request bodies** todo el tiempo, a veces solo solicitan un path, quizás con algunos parámetros de query, pero no envían un body. -Para declarar un **request** body, usas modelos de [Pydantic](https://docs.pydantic.dev/) con todo su poder y beneficios. +Para declarar un **request** body, usas modelos de [Pydantic](https://pydantic.dev/docs/) con todo su poder y beneficios. /// note | Nota diff --git a/docs/es/docs/tutorial/debugging.md b/docs/es/docs/tutorial/debugging.md index 95e19c1..7ef751c 100644 --- a/docs/es/docs/tutorial/debugging.md +++ b/docs/es/docs/tutorial/debugging.md @@ -16,7 +16,7 @@ El objetivo principal de `__name__ == "__main__"` es tener algo de código que s
```console -$ python myapp.py +$ uv run python myapp.py ```
@@ -36,7 +36,7 @@ Si lo ejecutas con:
```console -$ python myapp.py +$ uv run python myapp.py ```
diff --git a/docs/es/docs/tutorial/extra-data-types.md b/docs/es/docs/tutorial/extra-data-types.md index bd5fdc0..4ed54b8 100644 --- a/docs/es/docs/tutorial/extra-data-types.md +++ b/docs/es/docs/tutorial/extra-data-types.md @@ -37,7 +37,7 @@ Aquí hay algunos de los tipos de datos adicionales que puedes usar: * `datetime.timedelta`: * Un `datetime.timedelta` de Python. * En requests y responses se representará como un `float` de segundos totales. - * Pydantic también permite representarlo como una "codificación de diferencia horaria ISO 8601", [consulta la documentación para más información](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers). + * Pydantic también permite representarlo como una "codificación de diferencia horaria ISO 8601", [consulta la documentación para más información](https://pydantic.dev/docs/validation/latest/concepts/serialization/#custom-serializers). * `frozenset`: * En requests y responses, tratado igual que un `set`: * En requests, se leerá una list, eliminando duplicados y convirtiéndola en un `set`. @@ -50,7 +50,7 @@ Aquí hay algunos de los tipos de datos adicionales que puedes usar: * `Decimal`: * `Decimal` estándar de Python. * En requests y responses, manejado igual que un `float`. -* Puedes revisar todos los tipos de datos válidos de Pydantic aquí: [Tipos de datos de Pydantic](https://docs.pydantic.dev/latest/usage/types/types/). +* Puedes revisar todos los tipos de datos válidos de Pydantic aquí: [Tipos de datos de Pydantic](https://pydantic.dev/docs/validation/latest/concepts/types/). ## Ejemplo { #example } diff --git a/docs/es/docs/tutorial/extra-models.md b/docs/es/docs/tutorial/extra-models.md index 903a13c..55a8d32 100644 --- a/docs/es/docs/tutorial/extra-models.md +++ b/docs/es/docs/tutorial/extra-models.md @@ -166,7 +166,7 @@ Para hacerlo, usa la anotación de tipos estándar de Python [`typing.Union`](ht /// note | Nota -Al definir una [`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions), incluye el tipo más específico primero, seguido por el tipo menos específico. En el ejemplo a continuación, el más específico `PlaneItem` viene antes de `CarItem` en `Union[PlaneItem, CarItem]`. +Al definir una [`Union`](https://pydantic.dev/docs/validation/latest/concepts/unions/), incluye el tipo más específico primero, seguido por el tipo menos específico. En el ejemplo a continuación, el más específico `PlaneItem` viene antes de `CarItem` en `Union[PlaneItem, CarItem]`. /// diff --git a/docs/es/docs/tutorial/first-steps.md b/docs/es/docs/tutorial/first-steps.md index 61e5f40..be3006e 100644 --- a/docs/es/docs/tutorial/first-steps.md +++ b/docs/es/docs/tutorial/first-steps.md @@ -6,12 +6,18 @@ El archivo FastAPI más simple podría verse así: Copia eso en un archivo `main.py`. +/// tip | Consejo + +FastAPI tiene una [extensión oficial para VS Code](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (y Cursor), que proporciona muchas funcionalidades, incluyendo un explorador de path operations, búsqueda de path operations, navegación CodeLens en tests (saltar a la definición desde los tests), y despliegue y logs de FastAPI Cloud, todo desde tu editor. + +/// + Ejecuta el servidor en vivo:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -78,7 +84,7 @@ Verás la documentación interactiva automática de la API (proporcionada por [S Y ahora, ve a [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc). -Verás la documentación alternativa automática (proporcionada por [ReDoc](https://github.com/Rebilly/ReDoc)): +Verás la documentación alternativa automática (proporcionada por [ReDoc](https://github.com/Redocly/redoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -185,13 +191,13 @@ from backend.main import app También puedes pasar el path del archivo al comando `fastapi dev`, y adivinará el objeto app de FastAPI que debe usar: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` O, también puedes pasar la opción `--entrypoint` al comando `fastapi dev`: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` Pero tendrías que recordar pasar el path\entrypoint correcto cada vez que llames al comando `fastapi`. @@ -205,7 +211,7 @@ Opcionalmente puedes desplegar tu app de FastAPI en [FastAPI Cloud](https://fast
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -232,7 +238,7 @@ La CLI detectará automáticamente tu aplicación de FastAPI y la desplegará en `FastAPI` es una clase que hereda directamente de `Starlette`. -Puedes usar toda la funcionalidad de [Starlette](https://www.starlette.dev/) con `FastAPI` también. +Puedes usar toda la funcionalidad de [Starlette](https://starlette.dev/) con `FastAPI` también. /// diff --git a/docs/es/docs/tutorial/frontend.md b/docs/es/docs/tutorial/frontend.md index 3365ae7..faacbb5 100644 --- a/docs/es/docs/tutorial/frontend.md +++ b/docs/es/docs/tutorial/frontend.md @@ -52,7 +52,7 @@ Para eso, usa `fallback="index.html"`: {* ../../docs_src/frontend/tutorial002_py310.py hl[5] *} -**FastAPI** usa este fallback solo para requests `GET` y `HEAD` que parecen navegación del navegador. Los archivos faltantes como JavaScript, CSS e imágenes siguen devolviendo `404`. +**FastAPI** usa este fallback solo para requests `GET` y `HEAD` que aceptan HTML explícitamente con `Accept: text/html` o `Accept: application/xhtml+xml`, como normalmente hacen los requests de navegación del navegador. Los archivos faltantes como JavaScript, CSS e imágenes siguen devolviendo `404`. Los requests con otros métodos, como `POST` o `PUT`, a paths que solo coinciden con el fallback del frontend también devuelven `404`. Las *path operations* normales de **FastAPI** siguen teniendo mayor prioridad que las rutas frontend. @@ -106,9 +106,13 @@ Entonces los paths frontend faltantes devuelven el `404` normal. ## Revisa el directorio { #check-directory } -Por defecto, `app.frontend()` revisa que el directorio exista cuando se crea la app. +Por defecto, `app.frontend()` usa `check_dir="auto"`. -Esto ayuda a detectar errores de configuración temprano. Por ejemplo, si falta el directorio de salida del build del frontend, **FastAPI** lanzará un error al iniciar. +Cuando la variable de entorno `FASTAPI_ENV` se configura como `development`, **FastAPI** solo muestra una advertencia si falta el directorio de salida del build del frontend. El [comando `fastapi dev`](https://github.com/fastapi/fastapi-cli#fastapi-dev) configura esta variable de entorno por ti si todavía no está configurada. Esto te permite iniciar el backend antes de construir o iniciar el frontend durante el desarrollo. + +En cualquier otro entorno, **FastAPI** lanza un error cuando se crea la app. Esto ayuda a detectar errores de configuración temprano antes de desplegar una app sin sus archivos frontend. + +También puedes configurar `check_dir=True` para revisar siempre el directorio cuando se crea la app. Si tus archivos frontend se crean más tarde, por ejemplo mediante un paso de build separado después de crear el objeto app, configura `check_dir=False`: @@ -132,6 +136,8 @@ Las responses frontend se ejecutan dentro de la aplicación **FastAPI** normal, Las dependencias de la app, de un `APIRouter` y de `include_router()` también se aplican a las responses frontend. Esto puede ser útil para proteger un frontend con autenticación por cookie o similar. +Las dependencias también pueden modificar headers de response y agregar tareas en background, como con las *path operations* normales. + ## Solo salida estática del build { #static-build-output-only } `app.frontend()` sirve archivos ya generados por tu build del frontend. diff --git a/docs/es/docs/tutorial/handling-errors.md b/docs/es/docs/tutorial/handling-errors.md index f640642..ad01d39 100644 --- a/docs/es/docs/tutorial/handling-errors.md +++ b/docs/es/docs/tutorial/handling-errors.md @@ -81,7 +81,7 @@ Pero en caso de que los necesites para un escenario avanzado, puedes agregar hea ## Instalar manejadores de excepciones personalizados { #install-custom-exception-handlers } -Puedes agregar manejadores de excepciones personalizados con [las mismas utilidades de excepciones de Starlette](https://www.starlette.dev/exceptions/). +Puedes agregar manejadores de excepciones personalizados con [las mismas utilidades de excepciones de Starlette](https://starlette.dev/exceptions/). Supongamos que tienes una excepción personalizada `UnicornException` que tú (o un paquete que usas) podrías lanzar. @@ -91,7 +91,7 @@ Podrías agregar un manejador de excepciones personalizado con `@app.exception_h {* ../../docs_src/handling_errors/tutorial003_py310.py hl[5:7,13:18,24] *} -Aquí, si solicitas `/unicorns/yolo`, la *path operation* lanzará un `UnicornException`. +Aquí, si solicitas `/unicorns/yolo`, la *path operation* hará `raise` de un `UnicornException`. Pero será manejado por el `unicorn_exception_handler`. diff --git a/docs/es/docs/tutorial/index.md b/docs/es/docs/tutorial/index.md index 59b9e41..20d4784 100644 --- a/docs/es/docs/tutorial/index.md +++ b/docs/es/docs/tutorial/index.md @@ -10,12 +10,12 @@ También está diseñado para funcionar como una referencia futura para que pued Todos los bloques de código pueden ser copiados y usados directamente (de hecho, son archivos Python probados). -Para ejecutar cualquiera de los ejemplos, copia el código a un archivo `main.py`, y comienza `fastapi dev`: +Para ejecutar cualquiera de los ejemplos, copia el código a un archivo `main.py`, y comienza `fastapi dev` con `uv run`:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -60,35 +60,75 @@ Usarlo en tu editor es lo que realmente te muestra los beneficios de FastAPI, al ## Instalar FastAPI { #install-fastapi } -El primer paso es instalar FastAPI. +El primer paso es configurar tu proyecto y añadir FastAPI. -Asegúrate de crear un [entorno virtual](../virtual-environments.md), actívalo, y luego **instala FastAPI**: +Instala [`uv`](https://docs.astral.sh/uv/getting-started/installation/), luego crea un proyecto y añade FastAPI:
```console -$ pip install "fastapi[standard]" +$ uv init awesome-project --bare +$ cd awesome-project +$ uv add "fastapi[standard]" ---> 100% ```
+`uv add` crea el entorno virtual del proyecto en `.venv`, añade FastAPI a `pyproject.toml`, y crea `uv.lock` para que se puedan instalar las mismas versiones de paquetes más adelante. + +/// details | Qué hacen estos comandos + +* `uv init`: crea un nuevo proyecto Python. +* `awesome-project`: crea el proyecto en un nuevo directorio con este nombre. +* `--bare`: crea solo el archivo mínimo `pyproject.toml`, sin generar un `main.py`, `README.md`, u otros archivos de ejemplo. Tú crearás los archivos de la aplicación en los siguientes pasos de este tutorial. + +Luego `cd awesome-project` entra al nuevo directorio del proyecto antes de añadir FastAPI. + +`uv` usará una versión compatible de Python ya instalada en tu sistema, o descargará una si es necesario. + +Cuando ejecutas `uv add`, selecciona versiones compatibles de FastAPI y todos los paquetes de los que depende FastAPI. Registra las versiones exactas en `uv.lock`, haciendo posible instalar las mismas versiones de paquetes más adelante en otra computadora o al hacer deploy de la aplicación. + +Crear o actualizar este archivo se llama hacer [**locking** de las dependencias del proyecto](https://docs.astral.sh/uv/concepts/projects/sync/). `uv` hace esto automáticamente cuando añades un paquete. + +/// + +/// details | Opciones de instalación de FastAPI + +Cuando instalas con `uv add "fastapi[standard]"` viene con algunas dependencias opcionales estándar por defecto, incluyendo `fastapi-cloud-cli`, que te permite hacer deploy a [FastAPI Cloud](https://fastapicloud.com). + +Si no quieres tener esas dependencias opcionales, en su lugar puedes instalar `uv add fastapi`. + +Si quieres instalar las dependencias estándar pero sin `fastapi-cloud-cli`, puedes instalar con `uv add "fastapi[standard-no-fastapi-cloud-cli]"`. + +/// + +/// details | Usar `pip` en su lugar + +Si prefieres gestionar un entorno virtual y paquetes manualmente, crea y activa un entorno virtual y luego instala FastAPI con `pip install "fastapi[standard]"`. + +Lee la [guía de Entornos Virtuales](https://tiangolo.com/guides/virtual-environments/) para ver los pasos detallados. + +/// + +## Habilidades de agentes de IA { #ai-agent-skills } + +FastAPI incluye una habilidad oficial para agentes de programación con IA. Viene incluida con el paquete, por lo que su guía se mantiene alineada con la versión de FastAPI instalada en tu proyecto y se actualiza cuando actualizas FastAPI. + +Después de instalar FastAPI en tu proyecto, puedes instalar la habilidad con Library Skills: + +```bash +uvx library-skills +``` + /// note | Nota -Cuando instalas con `pip install "fastapi[standard]"` viene con algunas dependencias opcionales estándar por defecto, incluyendo `fastapi-cloud-cli`, que te permite hacer deploy a [FastAPI Cloud](https://fastapicloud.com). - -Si no quieres tener esas dependencias opcionales, en su lugar puedes instalar `pip install fastapi`. - -Si quieres instalar las dependencias estándar pero sin `fastapi-cloud-cli`, puedes instalar con `pip install "fastapi[standard-no-fastapi-cloud-cli]"`. +`uvx` es un alias de `uv tool run`. Ejecuta Library Skills en un entorno temporal y aislado mientras Library Skills escanea los paquetes instalados en tu proyecto. /// -/// tip | Consejo - -FastAPI tiene una [extensión oficial para VS Code](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (y Cursor), que ofrece muchas funcionalidades, incluyendo un explorador de path operation, búsqueda de path operation, navegación de CodeLens en tests (saltar a la definición desde tests), y deploy y logs de FastAPI Cloud, todo desde tu editor. - -/// +La habilidad es compatible con Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Pi, OpenCode, y la mayoría de otros agentes de programación. Para Claude Code, selecciona `.claude/skills` cuando se te pregunte dónde instalar la habilidad. ## Guía Avanzada del Usuario { #advanced-user-guide } diff --git a/docs/es/docs/tutorial/middleware.md b/docs/es/docs/tutorial/middleware.md index 4729cad..520a291 100644 --- a/docs/es/docs/tutorial/middleware.md +++ b/docs/es/docs/tutorial/middleware.md @@ -37,7 +37,7 @@ La función middleware recibe: Ten en cuenta que los custom proprietary headers se pueden añadir [usando el prefijo `X-`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). -Pero si tienes custom headers que deseas que un cliente en un navegador pueda ver, necesitas añadirlos a tus configuraciones de CORS ([CORS (Cross-Origin Resource Sharing)](cors.md)) usando el parámetro `expose_headers` documentado en [la documentación de CORS de Starlette](https://www.starlette.dev/middleware/#corsmiddleware). +Pero si tienes custom headers que deseas que un cliente en un navegador pueda ver, necesitas añadirlos a tus configuraciones de CORS ([CORS (Cross-Origin Resource Sharing)](cors.md)) usando el parámetro `expose_headers` documentado en [la documentación de CORS de Starlette](https://starlette.dev/middleware/#corsmiddleware). /// @@ -67,9 +67,9 @@ Aquí usamos [`time.perf_counter()`](https://docs.python.org/3/library/time.html ## Orden de ejecución con múltiples middlewares { #multiple-middleware-execution-order } -Cuando añades múltiples middlewares usando ya sea el decorador `@app.middleware()` o el método `app.add_middleware()`, cada nuevo middleware envuelve la aplicación, formando un stack. El último middleware añadido es el más externo, y el primero es el más interno. +Cuando añades múltiples middlewares usando ya sea el decorador `@app.middleware()` o el método `app.add_middleware()`, cada nuevo middleware envuelve la aplicación, formando un stack. El último middleware añadido es el *más externo*, y el primero es el *más interno*. -En el camino de la request, el middleware más externo se ejecuta primero. +En el camino de la request, el middleware *más externo* se ejecuta primero. En el camino de la response, se ejecuta al final. diff --git a/docs/es/docs/tutorial/path-params.md b/docs/es/docs/tutorial/path-params.md index 9446501..600a96e 100644 --- a/docs/es/docs/tutorial/path-params.md +++ b/docs/es/docs/tutorial/path-params.md @@ -92,7 +92,7 @@ Nota que el parámetro de path está declarado como un entero. ## Beneficios basados en estándares, documentación alternativa { #standards-based-benefits-alternative-documentation } -Y porque el esquema generado es del estándar [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md), hay muchas herramientas compatibles. +Y porque el esquema generado es del estándar [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md), hay muchas herramientas compatibles. Debido a esto, el propio **FastAPI** proporciona una documentación de API alternativa (usando ReDoc), a la cual puedes acceder en [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc): @@ -102,7 +102,7 @@ De la misma manera, hay muchas herramientas compatibles. Incluyendo herramientas ## Pydantic { #pydantic } -Toda la validación de datos se realiza internamente con [Pydantic](https://docs.pydantic.dev/), así que obtienes todos los beneficios de esta. Y sabes que estás en buenas manos. +Toda la validación de datos se realiza internamente con [Pydantic](https://pydantic.dev/docs/), así que obtienes todos los beneficios de esta. Y sabes que estás en buenas manos. Puedes usar las mismas declaraciones de tipo con `str`, `float`, `bool` y muchos otros tipos de datos complejos. diff --git a/docs/es/docs/tutorial/query-params-str-validations.md b/docs/es/docs/tutorial/query-params-str-validations.md index fab02dd..cc227a7 100644 --- a/docs/es/docs/tutorial/query-params-str-validations.md +++ b/docs/es/docs/tutorial/query-params-str-validations.md @@ -370,11 +370,11 @@ Podría haber casos donde necesites hacer alguna **validación personalizada** q En esos casos, puedes usar una **función validadora personalizada** que se aplique después de la validación normal (por ejemplo, después de validar que el valor es un `str`). -Puedes lograr eso usando [`AfterValidator` de Pydantic](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator) dentro de `Annotated`. +Puedes lograr eso usando [`AfterValidator` de Pydantic](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-after-validator) dentro de `Annotated`. /// tip | Consejo -Pydantic también tiene [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator) y otros. 🤓 +Pydantic también tiene [`BeforeValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-before-validator) y otros. 🤓 /// diff --git a/docs/es/docs/tutorial/request-files.md b/docs/es/docs/tutorial/request-files.md index 090d147..652d49a 100644 --- a/docs/es/docs/tutorial/request-files.md +++ b/docs/es/docs/tutorial/request-files.md @@ -6,10 +6,10 @@ Puedes definir archivos que serán subidos por el cliente utilizando `File`. Para recibir archivos subidos, primero instala [`python-multipart`](https://github.com/Kludex/python-multipart). -Asegúrate de crear un [entorno virtual](../virtual-environments.md), activarlo y luego instalarlo, por ejemplo: +Agrégalo a tu proyecto: ```console -$ pip install python-multipart +$ uv add python-multipart ``` Esto es porque los archivos subidos se envían como "form data". diff --git a/docs/es/docs/tutorial/request-form-models.md b/docs/es/docs/tutorial/request-form-models.md index e0685d4..7504284 100644 --- a/docs/es/docs/tutorial/request-form-models.md +++ b/docs/es/docs/tutorial/request-form-models.md @@ -6,10 +6,10 @@ Puedes usar **modelos de Pydantic** para declarar **campos de formulario** en Fa Para usar formularios, primero instala [`python-multipart`](https://github.com/Kludex/python-multipart). -Asegúrate de crear un [entorno virtual](../virtual-environments.md), activarlo, y luego instalarlo, por ejemplo: +Agrégalo a tu proyecto: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/es/docs/tutorial/request-forms-and-files.md b/docs/es/docs/tutorial/request-forms-and-files.md index 434a665..b151e34 100644 --- a/docs/es/docs/tutorial/request-forms-and-files.md +++ b/docs/es/docs/tutorial/request-forms-and-files.md @@ -6,10 +6,10 @@ Puedes definir archivos y campos de formulario al mismo tiempo usando `File` y ` Para recibir archivos subidos y/o form data, primero instala [`python-multipart`](https://github.com/Kludex/python-multipart). -Asegúrate de crear un [entorno virtual](../virtual-environments.md), actívalo y luego instálalo, por ejemplo: +Añádelo a tu proyecto: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/es/docs/tutorial/request-forms.md b/docs/es/docs/tutorial/request-forms.md index 640e022..72f40c6 100644 --- a/docs/es/docs/tutorial/request-forms.md +++ b/docs/es/docs/tutorial/request-forms.md @@ -6,10 +6,10 @@ Cuando necesitas recibir campos de formulario en lugar de JSON, puedes usar `For Para usar formularios, primero instala [`python-multipart`](https://github.com/Kludex/python-multipart). -Asegúrate de crear un [entorno virtual](../virtual-environments.md), activarlo, y luego instalarlo, por ejemplo: +Añádelo a tu proyecto: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/es/docs/tutorial/response-model.md b/docs/es/docs/tutorial/response-model.md index 2c97a67..25b0a5b 100644 --- a/docs/es/docs/tutorial/response-model.md +++ b/docs/es/docs/tutorial/response-model.md @@ -76,16 +76,16 @@ Aquí estamos declarando un modelo `UserIn`, contendrá una contraseña en texto Para usar `EmailStr`, primero instala [`email-validator`](https://github.com/JoshData/python-email-validator). -Asegúrate de crear un [entorno virtual](../virtual-environments.md), activarlo, y luego instalarlo, por ejemplo: +Añádelo a tu proyecto: ```console -$ pip install email-validator +$ uv add email-validator ``` o con: ```console -$ pip install "pydantic[email]" +$ uv add "pydantic[email]" ``` /// @@ -258,7 +258,7 @@ También puedes usar: * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -como se describe en [la documentación de Pydantic](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict) para `exclude_defaults` y `exclude_none`. +como se describe en [la documentación de Pydantic](https://pydantic.dev/docs/validation/latest/concepts/serialization/#excluding-and-including-fields-based-on-their-value) para `exclude_defaults` y `exclude_none`. /// diff --git a/docs/es/docs/tutorial/schema-extra-example.md b/docs/es/docs/tutorial/schema-extra-example.md index 310697d..61219da 100644 --- a/docs/es/docs/tutorial/schema-extra-example.md +++ b/docs/es/docs/tutorial/schema-extra-example.md @@ -12,7 +12,7 @@ Puedes declarar `examples` para un modelo de Pydantic que se añadirá al JSON S Esa información extra se añadirá tal cual al **JSON Schema** resultante para ese modelo, y se usará en la documentación de la API. -Puedes usar el atributo `model_config` que toma un `dict` como se describe en [Documentación de Pydantic: Configuración](https://docs.pydantic.dev/latest/api/config/). +Puedes usar el atributo `model_config` que toma un `dict` como se describe en [Documentación de Pydantic: Configuración](https://pydantic.dev/docs/validation/latest/api/pydantic/config/). Puedes establecer `"json_schema_extra"` con un `dict` que contenga cualquier dato adicional que te gustaría que aparezca en el JSON Schema generado, incluyendo `examples`. diff --git a/docs/es/docs/tutorial/security/first-steps.md b/docs/es/docs/tutorial/security/first-steps.md index a8df7e9..9ee805f 100644 --- a/docs/es/docs/tutorial/security/first-steps.md +++ b/docs/es/docs/tutorial/security/first-steps.md @@ -26,14 +26,14 @@ Copia el ejemplo en un archivo `main.py`: /// note | Nota -El paquete [`python-multipart`](https://github.com/Kludex/python-multipart) se instala automáticamente con **FastAPI** cuando ejecutas el comando `pip install "fastapi[standard]"`. +El paquete [`python-multipart`](https://github.com/Kludex/python-multipart) se instala automáticamente con **FastAPI** cuando ejecutas el comando `uv add "fastapi[standard]"`. -Sin embargo, si usas el comando `pip install fastapi`, el paquete `python-multipart` no se incluye por defecto. +Sin embargo, si usas el comando `uv add fastapi`, el paquete `python-multipart` no se incluye por defecto. -Para instalarlo manualmente, asegúrate de crear un [entorno virtual](../../virtual-environments.md), activarlo, y luego instalarlo con: +Para instalarlo manualmente, agrégalo a tu proyecto con: ```console -$ pip install python-multipart +$ uv add python-multipart ``` Esto se debe a que **OAuth2** utiliza "form data" para enviar el `username` y `password`. @@ -45,7 +45,7 @@ Ejecuta el ejemplo con:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/es/docs/tutorial/security/oauth2-jwt.md b/docs/es/docs/tutorial/security/oauth2-jwt.md index 5b74ffd..a77315b 100644 --- a/docs/es/docs/tutorial/security/oauth2-jwt.md +++ b/docs/es/docs/tutorial/security/oauth2-jwt.md @@ -1,6 +1,5 @@ # OAuth2 con Password (y hashing), Bearer con tokens JWT { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens } - Ahora que tenemos todo el flujo de seguridad, hagamos que la aplicación sea realmente segura, usando tokens JWT y hashing de contraseñas seguras. Este código es algo que puedes usar realmente en tu aplicación, guardar los hashes de las contraseñas en tu base de datos, etc. @@ -31,12 +30,12 @@ Si quieres jugar con tokens JWT y ver cómo funcionan, revisa [https://jwt.io](h Necesitamos instalar `PyJWT` para generar y verificar los tokens JWT en Python. -Asegúrate de crear un [entorno virtual](../../virtual-environments.md), activarlo y luego instalar `pyjwt`: +Añade `pyjwt` a tu proyecto:
```console -$ pip install pyjwt +$ uv add pyjwt ---> 100% ``` @@ -73,12 +72,12 @@ Soporta muchos algoritmos de hashing seguros y utilidades para trabajar con ello El algoritmo recomendado es "Argon2". -Asegúrate de crear un [entorno virtual](../../virtual-environments.md), activarlo y luego instalar pwdlib con Argon2: +Añade `pwdlib` con Argon2 a tu proyecto:
```console -$ pip install "pwdlib[argon2]" +$ uv add "pwdlib[argon2]" ---> 100% ``` diff --git a/docs/es/docs/tutorial/sql-databases.md b/docs/es/docs/tutorial/sql-databases.md index 3bb3209..6705a67 100644 --- a/docs/es/docs/tutorial/sql-databases.md +++ b/docs/es/docs/tutorial/sql-databases.md @@ -34,12 +34,12 @@ Este es un tutorial muy simple y corto, si deseas aprender sobre bases de datos ## Instalar `SQLModel` { #install-sqlmodel } -Primero, asegúrate de crear tu [entorno virtual](../virtual-environments.md), actívalo, y luego instala `sqlmodel`: +Añade `sqlmodel` a tu proyecto:
```console -$ pip install sqlmodel +$ uv add sqlmodel ---> 100% ``` @@ -152,7 +152,7 @@ Puedes ejecutar la aplicación:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -337,7 +337,7 @@ Puedes ejecutar la aplicación de nuevo:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/es/docs/tutorial/static-files.md b/docs/es/docs/tutorial/static-files.md index 177be63..f5efa74 100644 --- a/docs/es/docs/tutorial/static-files.md +++ b/docs/es/docs/tutorial/static-files.md @@ -45,4 +45,4 @@ Todos estos parámetros pueden ser diferentes a "`static`", ajústalos según la ## Más info { #more-info } -Para más detalles y opciones revisa [la documentación de Starlette sobre Archivos Estáticos](https://www.starlette.dev/staticfiles/). +Para más detalles y opciones revisa [la documentación de Starlette sobre Archivos Estáticos](https://starlette.dev/staticfiles/). diff --git a/docs/es/docs/tutorial/testing.md b/docs/es/docs/tutorial/testing.md index 9c4ff69..588fce4 100644 --- a/docs/es/docs/tutorial/testing.md +++ b/docs/es/docs/tutorial/testing.md @@ -1,6 +1,6 @@ # Pruebas { #testing } -Gracias a [Starlette](https://www.starlette.dev/testclient/), escribir pruebas para aplicaciones de **FastAPI** es fácil y agradable. +Gracias a [Starlette](https://starlette.dev/testclient/), escribir pruebas para aplicaciones de **FastAPI** es fácil y agradable. Está basado en [HTTPX](https://www.python-httpx.org), que a su vez está diseñado basado en Requests, por lo que es muy familiar e intuitivo. @@ -12,10 +12,10 @@ Con él, puedes usar [pytest](https://docs.pytest.org/) directamente con **FastA Para usar `TestClient`, primero instala [`httpx`](https://www.python-httpx.org). -Asegúrate de crear un [entorno virtual](../virtual-environments.md), activarlo y luego instalarlo, por ejemplo: +Añádelo a tu proyecto: ```console -$ pip install httpx +$ uv add httpx ``` /// @@ -94,11 +94,12 @@ Debido a que este archivo está en el mismo paquete, puedes usar imports relativ {* ../../docs_src/app_testing/app_a_py310/test_main.py hl[3] *} + ...y tener el código para las pruebas tal como antes. ## Pruebas: ejemplo extendido { #testing-extended-example } -Ahora extiende este ejemplo y añade más detalles para ver cómo escribir pruebas para diferentes partes. +Ahora extendamos este ejemplo y añade más detalles para ver cómo escribir pruebas para diferentes partes. ### Archivo de aplicación **FastAPI** extendido { #extended-fastapi-app-file } @@ -128,6 +129,7 @@ Podrías entonces actualizar `test_main.py` con las pruebas extendidas: {* ../../docs_src/app_testing/app_b_an_py310/test_main.py *} + Cada vez que necesites que el cliente pase información en el request y no sepas cómo, puedes buscar (Googlear) cómo hacerlo en `httpx`, o incluso cómo hacerlo con `requests`, dado que el diseño de HTTPX está basado en el diseño de Requests. Luego simplemente haces lo mismo en tus pruebas. @@ -154,12 +156,12 @@ Si tienes un modelo de Pydantic en tu prueba y quieres enviar sus datos a la apl Después de eso, solo necesitas instalar `pytest`. -Asegúrate de crear un [entorno virtual](../virtual-environments.md), activarlo y luego instalarlo, por ejemplo: +Añádelo a tu proyecto:
```console -$ pip install pytest +$ uv add pytest ---> 100% ``` @@ -173,7 +175,7 @@ Ejecuta las pruebas con:
```console -$ pytest +$ uv run pytest ================ test session starts ================ platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1 diff --git a/docs/es/docs/virtual-environments.md b/docs/es/docs/virtual-environments.md index 92cb83b..4697e5b 100644 --- a/docs/es/docs/virtual-environments.md +++ b/docs/es/docs/virtual-environments.md @@ -1,864 +1,35 @@ # Entornos Virtuales { #virtual-environments } -Cuando trabajas en proyectos de Python probablemente deberías usar un **entorno virtual** (o un mecanismo similar) para aislar los paquetes que instalas para cada proyecto. +Cuando trabajas con proyectos de Python, deberías usar un **entorno virtual** para aislar los paquetes instalados para cada proyecto. -/// note | Nota - -Si ya sabes sobre entornos virtuales, cómo crearlos y usarlos, podrías querer saltar esta sección. 🤓 - -/// - -/// tip | Consejo - -Un **entorno virtual** es diferente de una **variable de entorno**. - -Una **variable de entorno** es una variable en el sistema que puede ser usada por programas. - -Un **entorno virtual** es un directorio con algunos archivos en él. - -/// - -/// note | Nota - -Esta página te enseñará cómo usar **entornos virtuales** y cómo funcionan. - -Si estás listo para adoptar una **herramienta que gestiona todo** por ti (incluyendo la instalación de Python), prueba [uv](https://github.com/astral-sh/uv). - -/// +Para proyectos de FastAPI, recomiendo usar [uv](https://docs.astral.sh/uv/) para gestionar el proyecto, sus dependencias y su entorno virtual. ## Crea un Proyecto { #create-a-project } -Primero, crea un directorio para tu proyecto. - -Lo que normalmente hago es crear un directorio llamado `code` dentro de mi directorio de usuario. - -Y dentro de eso creo un directorio por proyecto. +Instala `uv` usando la [guía oficial de instalación](https://docs.astral.sh/uv/getting-started/installation/), y luego crea un proyecto:
```console -// Ve al directorio principal -$ cd -// Crea un directorio para todos tus proyectos de código -$ mkdir code -// Entra en ese directorio de código -$ cd code -// Crea un directorio para este proyecto -$ mkdir awesome-project -// Entra en ese directorio del proyecto +$ uv init awesome-project --bare $ cd awesome-project +$ uv add "fastapi[standard]" ```
-## Crea un Entorno Virtual { #create-a-virtual-environment } +`uv` crea un entorno virtual para el proyecto automáticamente. No necesitas crear ni activar uno tú mismo. -Cuando empiezas a trabajar en un proyecto de Python **por primera vez**, crea un entorno virtual **dentro de tu proyecto**. - -/// tip | Consejo - -Solo necesitas hacer esto **una vez por proyecto**, no cada vez que trabajas. - -/// - -//// tab | `venv` - -Para crear un entorno virtual, puedes usar el módulo `venv` que viene con Python. +Ejecuta comandos dentro del entorno del proyecto con `uv run`, por ejemplo:
```console -$ python -m venv .venv +$ uv run fastapi dev ```
-/// details | Qué significa ese comando +## Aprende Más { #learn-more } -* `python`: usa el programa llamado `python` -* `-m`: llama a un módulo como un script, indicaremos cuál módulo a continuación -* `venv`: usa el módulo llamado `venv` que normalmente viene instalado con Python -* `.venv`: crea el entorno virtual en el nuevo directorio `.venv` - -/// - -//// - -//// tab | `uv` - -Si tienes instalado [`uv`](https://github.com/astral-sh/uv), puedes usarlo para crear un entorno virtual. - -
- -```console -$ uv venv -``` - -
- -/// tip | Consejo - -Por defecto, `uv` creará un entorno virtual en un directorio llamado `.venv`. - -Pero podrías personalizarlo pasando un argumento adicional con el nombre del directorio. - -/// - -//// - -Ese comando crea un nuevo entorno virtual en un directorio llamado `.venv`. - -/// details | `.venv` u otro nombre - -Podrías crear el entorno virtual en un directorio diferente, pero hay una convención de llamarlo `.venv`. - -/// - -## Activa el Entorno Virtual { #activate-the-virtual-environment } - -Activa el nuevo entorno virtual para que cualquier comando de Python que ejecutes o paquete que instales lo utilicen. - -/// tip | Consejo - -Haz esto **cada vez** que inicies una **nueva sesión de terminal** para trabajar en el proyecto. - -/// - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -O si usas Bash para Windows (por ejemplo, [Git Bash](https://gitforwindows.org/)): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -/// tip | Consejo - -Cada vez que instales un **nuevo paquete** en ese entorno, **activa** el entorno de nuevo. - -Esto asegura que si usas un **programa de terminal (CLI)** instalado por ese paquete, uses el de tu entorno virtual y no cualquier otro que podría estar instalado globalmente, probablemente con una versión diferente a la que necesitas. - -/// - -## Revisa que el Entorno Virtual esté Activo { #check-the-virtual-environment-is-active } - -Revisa que el entorno virtual esté activo (el comando anterior funcionó). - -/// tip | Consejo - -Esto es **opcional**, pero es una buena forma de **revisar** que todo está funcionando como se esperaba y estás usando el entorno virtual que pretendes. - -/// - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -Si muestra el binario de `python` en `.venv/bin/python`, dentro de tu proyecto (en este caso `awesome-project`), entonces funcionó. 🎉 - -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -Si muestra el binario de `python` en `.venv\Scripts\python`, dentro de tu proyecto (en este caso `awesome-project`), entonces funcionó. 🎉 - -//// - -## Actualiza `pip` { #upgrade-pip } - -/// tip | Consejo - -Si usas [`uv`](https://github.com/astral-sh/uv) usarías eso para instalar cosas en lugar de `pip`, por lo que no necesitas actualizar `pip`. 😎 - -/// - -Si estás usando `pip` para instalar paquetes (viene por defecto con Python), deberías **actualizarlo** a la última versión. - -Muchos errores exóticos al instalar un paquete se resuelven simplemente actualizando `pip` primero. - -/// tip | Consejo - -Normalmente harías esto **una vez**, justo después de crear el entorno virtual. - -/// - -Asegúrate de que el entorno virtual esté activo (con el comando anterior) y luego ejecuta: - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip | Consejo - -A veces, podrías obtener un error **`No module named pip`** al intentar actualizar pip. - -Si esto pasa, instala y actualiza pip usando el siguiente comando: - -
- -```console -$ python -m ensurepip --upgrade - ----> 100% -``` - -
- -Este comando instalará pip si aún no está instalado y también se asegura de que la versión instalada de pip sea al menos tan reciente como la disponible en `ensurepip`. - -/// - -## Añade `.gitignore` { #add-gitignore } - -Si estás usando **Git** (deberías), añade un archivo `.gitignore` para excluir todo en tu `.venv` de Git. - -/// tip | Consejo - -Si usaste [`uv`](https://github.com/astral-sh/uv) para crear el entorno virtual, ya lo hizo por ti, puedes saltarte este paso. 😎 - -/// - -/// tip | Consejo - -Haz esto **una vez**, justo después de crear el entorno virtual. - -/// - -
- -```console -$ echo "*" > .venv/.gitignore -``` - -
- -/// details | Qué significa ese comando - -* `echo "*"`: "imprimirá" el texto `*` en la terminal (la siguiente parte cambia eso un poco) -* `>`: cualquier cosa impresa en la terminal por el comando a la izquierda de `>` no debería imprimirse, sino escribirse en el archivo que va a la derecha de `>` -* `.gitignore`: el nombre del archivo donde debería escribirse el texto - -Y `*` para Git significa "todo". Así que, ignorará todo en el directorio `.venv`. - -Ese comando creará un archivo `.gitignore` con el contenido: - -```gitignore -* -``` - -/// - -## Instala Paquetes { #install-packages } - -Después de activar el entorno, puedes instalar paquetes en él. - -/// tip | Consejo - -Haz esto **una vez** al instalar o actualizar los paquetes que necesita tu proyecto. - -Si necesitas actualizar una versión o agregar un nuevo paquete, **harías esto de nuevo**. - -/// - -### Instala Paquetes Directamente { #install-packages-directly } - -Si tienes prisa y no quieres usar un archivo para declarar los requisitos de paquetes de tu proyecto, puedes instalarlos directamente. - -/// tip | Consejo - -Es una (muy) buena idea poner los paquetes y las versiones que necesita tu programa en un archivo (por ejemplo, `requirements.txt` o `pyproject.toml`). - -/// - -//// tab | `pip` - -
- -```console -$ pip install "fastapi[standard]" - ----> 100% -``` - -
- -//// - -//// tab | `uv` - -Si tienes [`uv`](https://github.com/astral-sh/uv): - -
- -```console -$ uv pip install "fastapi[standard]" ----> 100% -``` - -
- -//// - -### Instala desde `requirements.txt` { #install-from-requirements-txt } - -Si tienes un `requirements.txt`, ahora puedes usarlo para instalar sus paquetes. - -//// tab | `pip` - -
- -```console -$ pip install -r requirements.txt ----> 100% -``` - -
- -//// - -//// tab | `uv` - -Si tienes [`uv`](https://github.com/astral-sh/uv): - -
- -```console -$ uv pip install -r requirements.txt ----> 100% -``` - -
- -//// - -/// details | `requirements.txt` - -Un `requirements.txt` con algunos paquetes podría verse así: - -```requirements.txt -fastapi[standard]==0.113.0 -pydantic==2.8.0 -``` - -/// - -## Ejecuta Tu Programa { #run-your-program } - -Después de activar el entorno virtual, puedes ejecutar tu programa, y usará el Python dentro de tu entorno virtual con los paquetes que instalaste allí. - -
- -```console -$ python main.py - -Hello World -``` - -
- -## Configura Tu Editor { #configure-your-editor } - -Probablemente usarías un editor, asegúrate de configurarlo para que use el mismo entorno virtual que creaste (probablemente lo autodetectará) para que puedas obtener autocompletado y errores en línea. - -Por ejemplo: - -* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) -* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) - -/// tip | Consejo - -Normalmente solo tendrías que hacer esto **una vez**, cuando crees el entorno virtual. - -/// - -## Desactiva el Entorno Virtual { #deactivate-the-virtual-environment } - -Una vez que hayas terminado de trabajar en tu proyecto, puedes **desactivar** el entorno virtual. - -
- -```console -$ deactivate -``` - -
- -De esta manera, cuando ejecutes `python` no intentará ejecutarse desde ese entorno virtual con los paquetes instalados allí. - -## Listo para Trabajar { #ready-to-work } - -Ahora estás listo para empezar a trabajar en tu proyecto. - - - -/// tip | Consejo - -¿Quieres entender todo lo anterior? - -Continúa leyendo. 👇🤓 - -/// - -## Por qué Entornos Virtuales { #why-virtual-environments } - -Para trabajar con FastAPI necesitas instalar [Python](https://www.python.org/). - -Después de eso, necesitarías **instalar** FastAPI y cualquier otro **paquete** que desees usar. - -Para instalar paquetes normalmente usarías el comando `pip` que viene con Python (o alternativas similares). - -Sin embargo, si solo usas `pip` directamente, los paquetes se instalarían en tu **entorno global de Python** (la instalación global de Python). - -### El Problema { #the-problem } - -Entonces, ¿cuál es el problema de instalar paquetes en el entorno global de Python? - -En algún momento, probablemente terminarás escribiendo muchos programas diferentes que dependen de **diferentes paquetes**. Y algunos de estos proyectos en los que trabajas dependerán de **diferentes versiones** del mismo paquete. 😱 - -Por ejemplo, podrías crear un proyecto llamado `philosophers-stone`, este programa depende de otro paquete llamado **`harry`, usando la versión `1`**. Así que, necesitas instalar `harry`. - -```mermaid -flowchart LR - stone(philosophers-stone) -->|requires| harry-1[harry v1] -``` - -Luego, en algún momento después, creas otro proyecto llamado `prisoner-of-azkaban`, y este proyecto también depende de `harry`, pero este proyecto necesita **`harry` versión `3`**. - -```mermaid -flowchart LR - azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3] -``` - -Pero ahora el problema es, si instalas los paquetes globalmente (en el entorno global) en lugar de en un **entorno virtual local**, tendrás que elegir qué versión de `harry` instalar. - -Si deseas ejecutar `philosophers-stone` necesitarás primero instalar `harry` versión `1`, por ejemplo con: - -
- -```console -$ pip install "harry==1" -``` - -
- -Y entonces terminarías con `harry` versión `1` instalada en tu entorno global de Python. - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -->|requires| harry-1 - end -``` - -Pero luego si deseas ejecutar `prisoner-of-azkaban`, necesitarás desinstalar `harry` versión `1` e instalar `harry` versión `3` (o simplemente instalar la versión `3` automáticamente desinstalaría la versión `1`). - -
- -```console -$ pip install "harry==3" -``` - -
- -Y entonces terminarías con `harry` versión `3` instalada en tu entorno global de Python. - -Y si intentas ejecutar `philosophers-stone` de nuevo, hay una posibilidad de que **no funcione** porque necesita `harry` versión `1`. - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - style harry-1 fill:#ccc,stroke-dasharray: 5 5 - harry-3[harry v3] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -.-x|⛔️| harry-1 - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --> |requires| harry-3 - end -``` - -/// tip | Consejo - -Es muy común en los paquetes de Python intentar lo mejor para **evitar romper cambios** en **nuevas versiones**, pero es mejor estar seguro e instalar nuevas versiones intencionalmente y cuando puedas ejecutar las pruebas para verificar que todo está funcionando correctamente. - -/// - -Ahora, imagina eso con **muchos** otros **paquetes** de los que dependen todos tus **proyectos**. Eso es muy difícil de manejar. Y probablemente terminarías ejecutando algunos proyectos con algunas **versiones incompatibles** de los paquetes, y sin saber por qué algo no está funcionando. - -Además, dependiendo de tu sistema operativo (por ejemplo, Linux, Windows, macOS), podría haber venido con Python ya instalado. Y en ese caso probablemente tenía algunos paquetes preinstalados con algunas versiones específicas **necesitadas por tu sistema**. Si instalas paquetes en el entorno global de Python, podrías terminar **rompiendo** algunos de los programas que vinieron con tu sistema operativo. - -## Dónde se Instalan los Paquetes { #where-are-packages-installed } - -Cuando instalas Python, crea algunos directorios con algunos archivos en tu computadora. - -Algunos de estos directorios son los encargados de tener todos los paquetes que instalas. - -Cuando ejecutas: - -
- -```console -// No ejecutes esto ahora, solo es un ejemplo 🤓 -$ pip install "fastapi[standard]" ----> 100% -``` - -
- -Eso descargará un archivo comprimido con el código de FastAPI, normalmente desde [PyPI](https://pypi.org/project/fastapi/). - -También **descargará** archivos para otros paquetes de los que depende FastAPI. - -Luego, **extraerá** todos esos archivos y los pondrá en un directorio en tu computadora. - -Por defecto, pondrá esos archivos descargados y extraídos en el directorio que viene con tu instalación de Python, eso es el **entorno global**. - -## Qué son los Entornos Virtuales { #what-are-virtual-environments } - -La solución a los problemas de tener todos los paquetes en el entorno global es usar un **entorno virtual para cada proyecto** en el que trabajas. - -Un entorno virtual es un **directorio**, muy similar al global, donde puedes instalar los paquetes para un proyecto. - -De esta manera, cada proyecto tendrá su propio entorno virtual (directorio `.venv`) con sus propios paquetes. - -```mermaid -flowchart TB - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) --->|requires| harry-1 - subgraph venv1[.venv] - harry-1[harry v1] - end - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --->|requires| harry-3 - subgraph venv2[.venv] - harry-3[harry v3] - end - end - stone-project ~~~ azkaban-project -``` - -## Qué Significa Activar un Entorno Virtual { #what-does-activating-a-virtual-environment-mean } - -Cuando activas un entorno virtual, por ejemplo con: - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -O si usas Bash para Windows (por ejemplo, [Git Bash](https://gitforwindows.org/)): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -Ese comando creará o modificará algunas [variables de entorno](environment-variables.md) que estarán disponibles para los siguientes comandos. - -Una de esas variables es la variable `PATH`. - -/// tip | Consejo - -Puedes aprender más sobre la variable de entorno `PATH` en la sección [Variables de Entorno](environment-variables.md#path-environment-variable). - -/// - -Activar un entorno virtual agrega su path `.venv/bin` (en Linux y macOS) o `.venv\Scripts` (en Windows) a la variable de entorno `PATH`. - -Digamos que antes de activar el entorno, la variable `PATH` se veía así: - -//// tab | Linux, macOS - -```plaintext -/usr/bin:/bin:/usr/sbin:/sbin -``` - -Eso significa que el sistema buscaría programas en: - -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Windows\System32 -``` - -Eso significa que el sistema buscaría programas en: - -* `C:\Windows\System32` - -//// - -Después de activar el entorno virtual, la variable `PATH` se vería algo así: - -//// tab | Linux, macOS - -```plaintext -/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -Eso significa que el sistema ahora comenzará a buscar primero los programas en: - -```plaintext -/home/user/code/awesome-project/.venv/bin -``` - -antes de buscar en los otros directorios. - -Así que, cuando escribas `python` en la terminal, el sistema encontrará el programa Python en - -```plaintext -/home/user/code/awesome-project/.venv/bin/python -``` - -y utilizará ese. - -//// - -//// tab | Windows - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32 -``` - -Eso significa que el sistema ahora comenzará a buscar primero los programas en: - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts -``` - -antes de buscar en los otros directorios. - -Así que, cuando escribas `python` en la terminal, el sistema encontrará el programa Python en - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -y utilizará ese. - -//// - -Un detalle importante es que pondrá el path del entorno virtual al **comienzo** de la variable `PATH`. El sistema lo encontrará **antes** que cualquier otro Python disponible. De esta manera, cuando ejecutes `python`, utilizará el Python **del entorno virtual** en lugar de cualquier otro `python` (por ejemplo, un `python` de un entorno global). - -Activar un entorno virtual también cambia un par de otras cosas, pero esta es una de las cosas más importantes que hace. - -## Revisando un Entorno Virtual { #checking-a-virtual-environment } - -Cuando revisas si un entorno virtual está activo, por ejemplo con: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -//// - -Eso significa que el programa `python` que se utilizará es el que está **en el entorno virtual**. - -Usas `which` en Linux y macOS y `Get-Command` en Windows PowerShell. - -La forma en que funciona ese comando es que irá y revisará la variable de entorno `PATH`, pasando por **cada path en orden**, buscando el programa llamado `python`. Una vez que lo encuentre, te **mostrará el path** a ese programa. - -La parte más importante es que cuando llamas a `python`, ese es el exacto "`python`" que será ejecutado. - -Así que, puedes confirmar si estás en el entorno virtual correcto. - -/// tip | Consejo - -Es fácil activar un entorno virtual, obtener un Python, y luego **ir a otro proyecto**. - -Y el segundo proyecto **no funcionaría** porque estás usando el **Python incorrecto**, de un entorno virtual para otro proyecto. - -Es útil poder revisar qué `python` se está usando. 🤓 - -/// - -## Por qué Desactivar un Entorno Virtual { #why-deactivate-a-virtual-environment } - -Por ejemplo, podrías estar trabajando en un proyecto `philosophers-stone`, **activar ese entorno virtual**, instalar paquetes y trabajar con ese entorno. - -Y luego quieres trabajar en **otro proyecto** `prisoner-of-azkaban`. - -Vas a ese proyecto: - -
- -```console -$ cd ~/code/prisoner-of-azkaban -``` - -
- -Si no desactivas el entorno virtual para `philosophers-stone`, cuando ejecutes `python` en la terminal, intentará usar el Python de `philosophers-stone`. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -$ python main.py - -// Error importando sirius, no está instalado 😱 -Traceback (most recent call last): - File "main.py", line 1, in - import sirius -``` - -
- -Pero si desactivas el entorno virtual y activas el nuevo para `prisoner-of-azkaban` entonces cuando ejecutes `python` utilizará el Python del entorno virtual en `prisoner-of-azkaban`. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -// No necesitas estar en el directorio antiguo para desactivar, puedes hacerlo donde sea que estés, incluso después de ir al otro proyecto 😎 -$ deactivate - -// Activa el entorno virtual en prisoner-of-azkaban/.venv 🚀 -$ source .venv/bin/activate - -// Ahora cuando ejecutes python, encontrará el paquete sirius instalado en este entorno virtual ✨ -$ python main.py - -I solemnly swear 🐺 -``` - -
- -## Alternativas { #alternatives } - -Esta es una guía simple para comenzar y enseñarte cómo funciona todo **por debajo**. - -Hay muchas **alternativas** para gestionar entornos virtuales, dependencias de paquetes (requisitos), proyectos. - -Una vez que estés listo y quieras usar una herramienta para **gestionar todo el proyecto**, dependencias de paquetes, entornos virtuales, etc. Te sugeriría probar [uv](https://github.com/astral-sh/uv). - -`uv` puede hacer muchas cosas, puede: - -* **Instalar Python** por ti, incluyendo diferentes versiones -* Gestionar el **entorno virtual** para tus proyectos -* Instalar **paquetes** -* Gestionar **dependencias y versiones** de paquetes para tu proyecto -* Asegurarse de que tengas un conjunto **exacto** de paquetes y versiones para instalar, incluidas sus dependencias, para que puedas estar seguro de que puedes ejecutar tu proyecto en producción exactamente igual que en tu computadora mientras desarrollas, esto se llama **locking** -* Y muchas otras cosas - -## Conclusión { #conclusion } - -Si leíste y comprendiste todo esto, ahora **sabes mucho más** sobre entornos virtuales que muchos desarrolladores por ahí. 🤓 - -Conocer estos detalles probablemente te será útil en el futuro cuando estés depurando algo que parece complejo, pero sabrás **cómo funciona todo por debajo**. 😎 +Lee la [guía de Entornos Virtuales](https://tiangolo.com/guides/virtual-environments/) para aprender cómo funcionan los entornos virtuales por debajo, incluyendo la activación y el flujo de trabajo alternativo con `python -m venv` y `pip`. diff --git a/docs/fr/docs/advanced/additional-responses.md b/docs/fr/docs/advanced/additional-responses.md index bcf562f..bd776c3 100644 --- a/docs/fr/docs/advanced/additional-responses.md +++ b/docs/fr/docs/advanced/additional-responses.md @@ -24,7 +24,7 @@ Chacun de ces `dict` de réponse peut avoir une clé `model`, contenant un modè **FastAPI** prendra ce modèle, générera son schéma JSON et l'inclura au bon endroit dans OpenAPI. -Par exemple, pour déclarer une autre réponse avec un code HTTP `404` et un modèle Pydantic `Message`, vous pouvez écrire : +Par exemple, pour déclarer une autre réponse avec un code HTTP `404` et un modèle Pydantic `Message`, vous pouvez écrire : {* ../../docs_src/additional_responses/tutorial001_py310.py hl[18,22] *} @@ -42,14 +42,14 @@ La clé `model` ne fait pas partie d'OpenAPI. Le bon endroit est : -* Dans la clé `content`, qui a pour valeur un autre objet JSON (`dict`) qui contient : - * Une clé avec le type de support, par ex. `application/json`, qui contient comme valeur un autre objet JSON, qui contient : +* Dans la clé `content`, qui a pour valeur un autre objet JSON (`dict`) qui contient : + * Une clé avec le type de support, par ex. `application/json`, qui contient comme valeur un autre objet JSON, qui contient : * Une clé `schema`, qui a pour valeur le schéma JSON du modèle, voici le bon endroit. * **FastAPI** ajoute ici une référence aux schémas JSON globaux à un autre endroit de votre OpenAPI au lieu de l'inclure directement. De cette façon, d'autres applications et clients peuvent utiliser ces schémas JSON directement, fournir de meilleurs outils de génération de code, etc. /// -Les réponses générées au format OpenAPI pour ce *chemin d'accès* seront : +Les réponses générées au format OpenAPI pour ce *chemin d'accès* seront : ```JSON hl_lines="3-12" { @@ -88,7 +88,7 @@ Les réponses générées au format OpenAPI pour ce *chemin d'accès* seront : } ``` -Les schémas sont référencés à un autre endroit du modèle OpenAPI : +Les schémas sont référencés à un autre endroit du modèle OpenAPI : ```JSON hl_lines="4-16" { @@ -173,7 +173,7 @@ Les schémas sont référencés à un autre endroit du modèle OpenAPI : Vous pouvez utiliser ce même paramètre `responses` pour ajouter différents types de médias pour la même réponse principale. -Par exemple, vous pouvez ajouter un type de média supplémentaire `image/png`, en déclarant que votre *chemin d'accès* peut renvoyer un objet JSON (avec le type de média `application/json`) ou une image PNG : +Par exemple, vous pouvez ajouter un type de média supplémentaire `image/png`, en déclarant que votre *chemin d'accès* peut renvoyer un objet JSON (avec le type de média `application/json`) ou une image PNG : {* ../../docs_src/additional_responses/tutorial002_py310.py hl[17:22,26] *} @@ -201,19 +201,19 @@ Vous pouvez déclarer un `response_model`, en utilisant le code HTTP par défaut Par exemple, vous pouvez déclarer une réponse avec un code HTTP `404` qui utilise un modèle Pydantic et a une `description` personnalisée. -Et une réponse avec un code HTTP `200` qui utilise votre `response_model`, mais inclut un `example` personnalisé : +Et une réponse avec un code HTTP `200` qui utilise votre `response_model`, mais inclut un `example` personnalisé : {* ../../docs_src/additional_responses/tutorial003_py310.py hl[20:31] *} -Tout sera combiné et inclus dans votre OpenAPI, et affiché dans la documentation de l'API : +Tout sera combiné et inclus dans votre OpenAPI, et affiché dans la documentation de l'API : -## Combinez les réponses prédéfinies et les réponses personnalisées { #combine-predefined-responses-and-custom-ones } +## Combiner les réponses prédéfinies et les réponses personnalisées { #combine-predefined-responses-and-custom-ones } Vous voulez peut-être avoir des réponses prédéfinies qui s'appliquent à de nombreux *chemins d'accès*, mais vous souhaitez les combiner avec des réponses personnalisées nécessaires à chaque *chemin d'accès*. -Dans ces cas, vous pouvez utiliser la technique Python « unpacking » d'un `dict` avec `**dict_to_unpack` : +Dans ces cas, vous pouvez utiliser la technique Python « unpacking » d'un `dict` avec `**dict_to_unpack` : ```Python old_dict = { @@ -223,7 +223,7 @@ old_dict = { new_dict = {**old_dict, "new key": "new value"} ``` -Ici, `new_dict` contiendra toutes les paires clé-valeur de `old_dict` plus la nouvelle paire clé-valeur : +Ici, `new_dict` contiendra toutes les paires clé-valeur de `old_dict` plus la nouvelle paire clé-valeur : ```Python { @@ -235,13 +235,13 @@ Ici, `new_dict` contiendra toutes les paires clé-valeur de `old_dict` plus la n Vous pouvez utiliser cette technique pour réutiliser certaines réponses prédéfinies dans vos *chemins d'accès* et les combiner avec des réponses personnalisées supplémentaires. -Par exemple: +Par exemple : {* ../../docs_src/additional_responses/tutorial004_py310.py hl[11:15,24] *} ## Plus d'informations sur les réponses OpenAPI { #more-information-about-openapi-responses } -Pour voir exactement ce que vous pouvez inclure dans les réponses, vous pouvez consulter ces sections dans la spécification OpenAPI : +Pour voir exactement ce que vous pouvez inclure dans les réponses, vous pouvez consulter ces sections dans la spécification OpenAPI : -* [Objet Responses de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object), il inclut le `Response Object`. -* [Objet Response de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object), vous pouvez inclure n'importe quoi directement dans chaque réponse à l'intérieur de votre paramètre `responses`. Y compris `description`, `headers`, `content` (à l'intérieur de cela, vous déclarez différents types de médias et schémas JSON) et `links`. +* [Objet Responses de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object), il inclut le `Response Object`. +* [Objet Response de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object), vous pouvez inclure n'importe quoi directement dans chaque réponse à l'intérieur de votre paramètre `responses`. Y compris `description`, `headers`, `content` (à l'intérieur de cela, vous déclarez différents types de médias et schémas JSON) et `links`. diff --git a/docs/fr/docs/advanced/async-tests.md b/docs/fr/docs/advanced/async-tests.md index a59d651..13c0aea 100644 --- a/docs/fr/docs/advanced/async-tests.md +++ b/docs/fr/docs/advanced/async-tests.md @@ -45,7 +45,7 @@ Vous pouvez lancer vos tests comme d'habitude via :
```console -$ pytest +$ uv run pytest ---> 100% ``` diff --git a/docs/fr/docs/advanced/behind-a-proxy.md b/docs/fr/docs/advanced/behind-a-proxy.md index c53ba40..d178990 100644 --- a/docs/fr/docs/advanced/behind-a-proxy.md +++ b/docs/fr/docs/advanced/behind-a-proxy.md @@ -24,7 +24,7 @@ Les en-têtes du proxy sont : ### Activer les en-têtes transférés par le proxy { #enable-proxy-forwarded-headers } -Vous pouvez démarrer FastAPI CLI avec l'option de CLI `--forwarded-allow-ips` et fournir les adresses IP à considérer comme fiables pour lire ces en‑têtes transférés. +Vous pouvez démarrer FastAPI CLI avec l'*option de CLI* `--forwarded-allow-ips` et fournir les adresses IP à considérer comme fiables pour lire ces en‑têtes transférés. Si vous la définissez à `--forwarded-allow-ips="*"`, elle fera confiance à toutes les IP entrantes. @@ -33,7 +33,7 @@ Si votre **serveur** est derrière un **proxy** de confiance et que seul le prox
```console -$ fastapi run --forwarded-allow-ips="*" +$ uv run fastapi run --forwarded-allow-ips="*" INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -48,7 +48,7 @@ Par exemple, disons que vous définissez un *chemin d'accès* `/items/` : Si le client essaie d'aller à `/items`, par défaut, il sera redirigé vers `/items/`. -Mais avant de définir l'option de CLI `--forwarded-allow-ips`, il pourrait rediriger vers `http://localhost:8000/items/`. +Mais avant de définir l'*option de CLI* `--forwarded-allow-ips`, il pourrait rediriger vers `http://localhost:8000/items/`. Mais peut‑être que votre application est hébergée à `https://mysuperapp.com`, et la redirection devrait être vers `https://mysuperapp.com/items/`. @@ -170,7 +170,7 @@ Pour y parvenir, vous pouvez utiliser l'option de ligne de commande `--root-path
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -200,7 +200,7 @@ Ensuite, si vous démarrez Uvicorn avec :
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -253,7 +253,7 @@ Dans un cas comme celui‑ci (sans préfixe de chemin supprimé), le proxy écou Vous pouvez facilement faire l'expérience en local avec un préfixe de chemin supprimé en utilisant [Traefik](https://docs.traefik.io/). -[Téléchargez Traefik](https://github.com/containous/traefik/releases) ; c'est un binaire unique, vous pouvez extraire le fichier compressé et l'exécuter directement depuis le terminal. +[Téléchargez Traefik](https://github.com/traefik/traefik/releases), c'est un binaire unique, vous pouvez extraire le fichier compressé et l'exécuter directement depuis le terminal. Créez ensuite un fichier `traefik.toml` avec : @@ -321,7 +321,7 @@ Et démarrez maintenant votre application, en utilisant l'option `--root-path` :
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/fr/docs/advanced/dataclasses.md b/docs/fr/docs/advanced/dataclasses.md index 01d1369..508e8f3 100644 --- a/docs/fr/docs/advanced/dataclasses.md +++ b/docs/fr/docs/advanced/dataclasses.md @@ -6,7 +6,7 @@ Mais FastAPI prend aussi en charge l'utilisation de [`dataclasses`](https://docs {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -C'est toujours pris en charge grâce à **Pydantic**, qui offre une [prise en charge interne des `dataclasses`](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel). +C'est toujours pris en charge grâce à **Pydantic**, qui offre une [prise en charge interne des `dataclasses`](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/#usage-of-stdlib-dataclasses-with-basemodel). 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. @@ -36,7 +36,7 @@ Vous pouvez aussi utiliser `dataclasses` dans le paramètre `response_model` : La dataclass sera automatiquement convertie en dataclass Pydantic. -Ainsi, son schéma apparaîtra dans l'interface utilisateur de la documentation de l'API : +Ainsi, son schéma apparaîtra dans l'interface utilisateur des documents de l'API : @@ -74,7 +74,7 @@ Dans ce cas, vous pouvez simplement remplacer les `dataclasses` standard par `py 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`](../async.md#in-a-hurry). + Si vous avez besoin d'un rappel sur quand utiliser l'un ou l'autre, consultez la section _« Vous êtes pressé ? »_ dans les documents à propos de [`async` et `await`](../async.md#in-a-hurry). 9. 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. @@ -82,13 +82,13 @@ Dans ce cas, vous pouvez simplement remplacer les `dataclasses` standard par `py 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. +Reportez‑vous aux astuces d'annotation dans le code ci‑dessus pour voir plus de détails spécifiques. ## En savoir plus { #learn-more } 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](https://docs.pydantic.dev/latest/concepts/dataclasses/). +Pour en savoir plus, consultez les [documents Pydantic sur les dataclasses](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/). ## Version { #version } diff --git a/docs/fr/docs/advanced/events.md b/docs/fr/docs/advanced/events.md index 4ab1752..c936c62 100644 --- a/docs/fr/docs/advanced/events.md +++ b/docs/fr/docs/advanced/events.md @@ -154,7 +154,7 @@ Sous le capot, dans la spécification technique ASGI, cela fait partie du [proto /// note | Remarque -Vous pouvez en lire plus sur les gestionnaires `lifespan` de Starlette dans la [documentation « Lifespan » de Starlette](https://www.starlette.dev/lifespan/). +Vous pouvez en lire plus sur les gestionnaires `lifespan` de Starlette dans les [documents « Lifespan » de Starlette](https://starlette.dev/lifespan/). Y compris comment gérer l'état de cycle de vie qui peut être utilisé dans d'autres parties de votre code. diff --git a/docs/fr/docs/advanced/generate-clients.md b/docs/fr/docs/advanced/generate-clients.md index 7aa0a51..f831d70 100644 --- a/docs/fr/docs/advanced/generate-clients.md +++ b/docs/fr/docs/advanced/generate-clients.md @@ -12,7 +12,7 @@ Une option polyvalente est le [OpenAPI Generator](https://openapi-generator.tech Pour les **clients TypeScript**, [Hey API](https://heyapi.dev/) est une solution dédiée, offrant une expérience optimisée pour l’écosystème TypeScript. -Vous pouvez découvrir davantage de générateurs de SDK sur [OpenAPI.Tools](https://openapi.tools/#sdk). +Vous pouvez découvrir davantage de générateurs de SDK sur [OpenAPI.Tools](https://openapi.tools/categories/sdk-generators). /// tip | Astuce diff --git a/docs/fr/docs/advanced/middleware.md b/docs/fr/docs/advanced/middleware.md index 15de987..b7c0e75 100644 --- a/docs/fr/docs/advanced/middleware.md +++ b/docs/fr/docs/advanced/middleware.md @@ -14,7 +14,7 @@ Un middleware n'a pas besoin d'être conçu pour FastAPI ou Starlette pour fonct En général, les middlewares ASGI sont des classes qui s'attendent à recevoir une application ASGI en premier argument. -Ainsi, dans la documentation de middlewares ASGI tiers, on vous indiquera probablement de faire quelque chose comme : +Ainsi, dans la documentation de middlewares ASGI tiers, on vous indiquera probablement de faire quelque chose comme : ```Python from unicorn import UnicornMiddleware @@ -65,10 +65,10 @@ Impose que toutes les requêtes entrantes aient un en-tête `Host` correctement {* ../../docs_src/advanced_middleware/tutorial002_py310.py hl[2,6:8] *} -Les arguments suivants sont pris en charge : +Les arguments suivants sont pris en charge : -- `allowed_hosts` - Une liste de noms de domaine autorisés comme noms d'hôte. Les domaines génériques tels que `*.example.com` sont pris en charge pour faire correspondre les sous-domaines. Pour autoriser n'importe quel nom d'hôte, utilisez `allowed_hosts=["*"]` ou omettez le middleware. -- `www_redirect` - Si défini à `True`, les requêtes vers les versions sans www des hôtes autorisés seront redirigées vers leurs équivalents avec www. Valeur par défaut : `True`. +* `allowed_hosts` - Une liste de noms de domaine autorisés comme noms d'hôte. Les domaines génériques tels que `*.example.com` sont pris en charge pour faire correspondre les sous-domaines. Pour autoriser n'importe quel nom d'hôte, utilisez `allowed_hosts=["*"]` ou omettez le middleware. +* `www_redirect` - Si défini à True, les requêtes vers les versions sans www des hôtes autorisés seront redirigées vers leurs équivalents avec www. Valeur par défaut : `True`. Si une requête entrante n'est pas valide, une réponse `400` sera envoyée. @@ -80,18 +80,18 @@ Le middleware gérera les réponses standard et en streaming. {* ../../docs_src/advanced_middleware/tutorial003_py310.py hl[2,6] *} -Les arguments suivants sont pris en charge : +Les arguments suivants sont pris en charge : -- `minimum_size` - Ne pas compresser en GZip les réponses dont la taille est inférieure à ce minimum en octets. Valeur par défaut : `500`. -- `compresslevel` - Utilisé pendant la compression GZip. Entier compris entre 1 et 9. Valeur par défaut : `9`. Une valeur plus faible entraîne une compression plus rapide mais des fichiers plus volumineux, tandis qu'une valeur plus élevée entraîne une compression plus lente mais des fichiers plus petits. +* `minimum_size` - Ne pas compresser en GZip les réponses dont la taille est inférieure à ce minimum en octets. Valeur par défaut : `500`. +* `compresslevel` - Utilisé pendant la compression GZip. Entier compris entre 1 et 9. Valeur par défaut : `9`. Une valeur plus faible entraîne une compression plus rapide mais des fichiers plus volumineux, tandis qu'une valeur plus élevée entraîne une compression plus lente mais des fichiers plus petits. ## Autres middlewares { #other-middlewares } Il existe de nombreux autres middlewares ASGI. -Par exemple : +Par exemple : -- [Le `ProxyHeadersMiddleware` d'Uvicorn](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) -- [MessagePack](https://github.com/florimondmanca/msgpack-asgi) +* [Le `ProxyHeadersMiddleware` d'Uvicorn](https://github.com/Kludex/uvicorn/blob/main/uvicorn/middleware/proxy_headers.py) +* [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -Pour voir d'autres middlewares disponibles, consultez la [documentation des middlewares de Starlette](https://www.starlette.dev/middleware/) et la [liste ASGI Awesome](https://github.com/florimondmanca/awesome-asgi). +Pour voir d'autres middlewares disponibles, consultez la [documentation des middlewares de Starlette](https://starlette.dev/middleware/) et la [liste ASGI Awesome](https://github.com/florimondmanca/awesome-asgi). diff --git a/docs/fr/docs/advanced/openapi-callbacks.md b/docs/fr/docs/advanced/openapi-callbacks.md index 54f8e3f..d2748ae 100644 --- a/docs/fr/docs/advanced/openapi-callbacks.md +++ b/docs/fr/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ Cette partie est assez normale, la plupart du code vous est probablement déjà /// tip | Astuce -Le paramètre de requête `callback_url` utilise un type Pydantic [Url](https://docs.pydantic.dev/latest/api/networks/). +Le paramètre de requête `callback_url` utilise un type Pydantic [Url](https://pydantic.dev/docs/validation/latest/api/pydantic/networks/). /// @@ -106,11 +106,11 @@ Il devrait ressembler exactement à un *chemin d'accès* FastAPI normal : Il y a 2 principales différences par rapport à un *chemin d'accès* normal : * Il n’a pas besoin d’avoir de code réel, car votre application n’appellera jamais ce code. Il sert uniquement à documenter l’*API externe*. La fonction peut donc simplement contenir `pass`. -* Le *chemin* peut contenir une [expression OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) (voir plus bas) où il peut utiliser des variables avec des paramètres et des parties de la requête originale envoyée à *votre API*. +* Le *chemin* peut contenir une [expression OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression) (voir plus bas) où il peut utiliser des variables avec des paramètres et des parties de la requête originale envoyée à *votre API*. ### L’expression du chemin de callback { #the-callback-path-expression } -Le *chemin* du callback peut contenir une [expression OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) qui peut inclure des parties de la requête originale envoyée à *votre API*. +Le *chemin* du callback peut contenir une [expression OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression) qui peut inclure des parties de la requête originale envoyée à *votre API*. Dans ce cas, c’est la `str` : @@ -177,10 +177,10 @@ Remarquez que vous ne passez pas le routeur lui-même (`invoices_callback_router /// -### Vérifier la documentation { #check-the-docs } +### Vérifier les documents { #check-the-docs } Vous pouvez maintenant démarrer votre application et aller sur [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). -Vous verrez votre documentation incluant une section « Callbacks » pour votre *chemin d'accès* qui montre à quoi l’*API externe* devrait ressembler : +Vous verrez vos documents incluant une section « Callbacks » pour votre *chemin d'accès* qui montre à quoi l’*API externe* devrait ressembler : diff --git a/docs/fr/docs/advanced/response-cookies.md b/docs/fr/docs/advanced/response-cookies.md index 9efa045..cdead49 100644 --- a/docs/fr/docs/advanced/response-cookies.md +++ b/docs/fr/docs/advanced/response-cookies.md @@ -1,6 +1,5 @@ # Cookies de réponse { #response-cookies } - ## Utiliser un paramètre `Response` { #use-a-response-parameter } Vous pouvez déclarer un paramètre de type `Response` dans votre *fonction de chemin d'accès*. @@ -49,4 +48,4 @@ Et comme `Response` peut être utilisé fréquemment pour définir des en-têtes /// -Pour voir tous les paramètres et options disponibles, consultez la [documentation de Starlette](https://www.starlette.dev/responses/#set-cookie). +Pour voir tous les paramètres et options disponibles, consultez la [documentation de Starlette](https://starlette.dev/responses/#set-cookie). diff --git a/docs/fr/docs/advanced/response-headers.md b/docs/fr/docs/advanced/response-headers.md index e319ffe..332bca9 100644 --- a/docs/fr/docs/advanced/response-headers.md +++ b/docs/fr/docs/advanced/response-headers.md @@ -38,4 +38,4 @@ Et comme `Response` peut être utilisée fréquemment pour définir des en-tête Gardez à l'esprit que des en-têtes propriétaires personnalisés peuvent être ajoutés [en utilisant le préfixe `X-`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). -Mais si vous avez des en-têtes personnalisés que vous voulez qu'un client dans un navigateur puisse voir, vous devez les ajouter à vos configurations CORS (en savoir plus dans [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)), en utilisant le paramètre `expose_headers` documenté dans [la documentation CORS de Starlette](https://www.starlette.dev/middleware/#corsmiddleware). +Mais si vous avez des en-têtes personnalisés que vous voulez qu'un client dans un navigateur puisse voir, vous devez les ajouter à vos configurations CORS (en savoir plus dans [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)), en utilisant le paramètre `expose_headers` documenté dans [la documentation CORS de Starlette](https://starlette.dev/middleware/#corsmiddleware). diff --git a/docs/fr/docs/advanced/settings.md b/docs/fr/docs/advanced/settings.md index 722274d..621907b 100644 --- a/docs/fr/docs/advanced/settings.md +++ b/docs/fr/docs/advanced/settings.md @@ -6,41 +6,45 @@ La plupart de ces paramètres sont variables (peuvent changer), comme les URL de C'est pourquoi il est courant de les fournir via des variables d'environnement lues par l'application. +Une **variable d'environnement** (aussi appelée **env var**) est une valeur qui vit en dehors du code Python, dans le système d'exploitation, et qui peut être lue par votre application et d'autres programmes. + +Vous pouvez créer une variable d'environnement pour une commande lorsque vous l'exécutez. Vous verrez les commandes spécifiques à chaque plateforme ci-dessous. + /// tip | Astuce -Pour comprendre les variables d'environnement, vous pouvez lire [Variables d'environnement](../environment-variables.md). +Lisez le [guide des variables d'environnement](https://tiangolo.com/guides/environment-variables/) pour une explication détaillée du fonctionnement des variables d'environnement. /// ## Types et validation { #types-and-validation } -Ces variables d'environnement ne gèrent que des chaînes de texte, car elles sont externes à Python et doivent être compatibles avec d'autres programmes et le reste du système (et même avec différents systèmes d'exploitation, comme Linux, Windows, macOS). +Ces variables d'environnement ne gèrent que des chaînes de texte, car elles sont externes à Python et doivent être compatibles avec d'autres programmes et le reste du système (et même avec différents systèmes d'exploitation, comme Linux, Windows et macOS). Cela signifie que toute valeur lue en Python depuis une variable d'environnement sera une `str`, et toute conversion vers un autre type ou toute validation doit être effectuée dans le code. ## Pydantic `Settings` { #pydantic-settings } -Heureusement, Pydantic fournit un excellent utilitaire pour gérer ces paramètres provenant des variables d'environnement avec [Pydantic : gestion des paramètres](https://docs.pydantic.dev/latest/concepts/pydantic_settings/). +Heureusement, Pydantic fournit un excellent utilitaire pour gérer ces paramètres provenant des variables d'environnement avec [Pydantic : gestion des paramètres](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/). ### Installer `pydantic-settings` { #install-pydantic-settings } -D'abord, vous devez créer votre [environnement virtuel](../virtual-environments.md), l'activer, puis installer le paquet `pydantic-settings` : +Ajoutez le paquet `pydantic-settings` à votre projet :
```console -$ pip install pydantic-settings +$ uv add pydantic-settings ---> 100% ```
-Il est également inclus lorsque vous installez les extras `all` avec : +Il est aussi inclus lorsque vous installez les extras `all` avec :
```console -$ pip install "fastapi[all]" +$ uv add "fastapi[all]" ---> 100% ``` @@ -62,7 +66,7 @@ Si vous voulez quelque chose à copier-coller rapidement, n'utilisez pas cet exe /// -Ensuite, lorsque vous créez une instance de cette classe `Settings` (dans ce cas, l'objet `settings`), Pydantic lira les variables d'environnement de manière insensible à la casse, donc une variable en majuscules `APP_NAME` sera tout de même lue pour l'attribut `app_name`. +Ensuite, lorsque vous créez une instance de cette classe `Settings` (dans ce cas, dans l'objet `settings`), Pydantic lira les variables d'environnement de manière insensible à la casse, donc une variable en majuscules `APP_NAME` sera tout de même lue pour l'attribut `app_name`. Il convertira ensuite et validera les données. Ainsi, lorsque vous utilisez cet objet `settings`, vous aurez des données des types que vous avez déclarés (par exemple, `items_per_user` sera un `int`). @@ -74,33 +78,53 @@ Vous pouvez ensuite utiliser le nouvel objet `settings` dans votre application : ### Exécuter le serveur { #run-the-server } -Ensuite, vous exécutez le serveur en passant les configurations comme variables d'environnement ; par exemple, vous pouvez définir un `ADMIN_EMAIL` et `APP_NAME` avec : +Ensuite, vous exécuteriez le serveur en passant les configurations comme variables d'environnement ; par exemple, vous pourriez définir un `ADMIN_EMAIL` et `APP_NAME` avec : + +//// tab | Linux, macOS, Windows Bash
```console -$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py +$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uv run fastapi run main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
+//// + +//// tab | Windows PowerShell + +
+ +```console +$ $Env:ADMIN_EMAIL = "deadpool@example.com" +$ $Env:APP_NAME = "ChimichangApp" +$ uv run fastapi run main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +//// + /// tip | Astuce -Pour définir plusieurs variables d'environnement pour une seule commande, séparez-les simplement par un espace et placez-les toutes avant la commande. +Dans Bash, pour définir plusieurs env vars pour une seule commande, séparez-les par un espace et placez-les toutes avant la commande. /// -Ainsi, le paramètre `admin_email` sera défini sur « deadpool@example.com ». +Et alors le paramètre `admin_email` serait défini sur `"deadpool@example.com"`. -Le `app_name` sera « ChimichangApp ». +Le `app_name` serait `"ChimichangApp"`. -Et `items_per_user` conservera sa valeur par défaut de `50`. +Et `items_per_user` conserverait sa valeur par défaut de `50`. ## Paramètres dans un autre module { #settings-in-another-module } -Vous pouvez placer ces paramètres dans un autre module comme vous l'avez vu dans [Applications plus grandes - Plusieurs fichiers](../tutorial/bigger-applications.md). +Vous pouvez placer ces paramètres dans un autre fichier de module comme vous l'avez vu dans [Applications plus grandes - Plusieurs fichiers](../tutorial/bigger-applications.md). Par exemple, vous pourriez avoir un fichier `config.py` avec : @@ -160,7 +184,7 @@ Nous pouvons ensuite tester qu'il est bien utilisé. ## Lire un fichier `.env` { #reading-a-env-file } -Si vous avez de nombreux paramètres susceptibles de beaucoup changer, peut-être selon les environnements, il peut être utile de les placer dans un fichier, puis de les lire comme s'il s'agissait de variables d'environnement. +Si vous avez de nombreux paramètres susceptibles de beaucoup changer, peut-être dans différents environnements, il peut être utile de les placer dans un fichier, puis de les lire depuis celui-ci comme s'il s'agissait de variables d'environnement. Cette pratique est suffisamment courante pour avoir un nom ; ces variables d'environnement sont fréquemment placées dans un fichier `.env`, et le fichier est appelé un « dotenv ». @@ -172,11 +196,11 @@ Mais un fichier dotenv n'a pas forcément exactement ce nom de fichier. /// -Pydantic prend en charge la lecture depuis ce type de fichiers en utilisant une bibliothèque externe. Vous pouvez en lire davantage ici : [Pydantic Settings : prise en charge de Dotenv (.env)](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support). +Pydantic prend en charge la lecture depuis ce type de fichiers en utilisant une bibliothèque externe. Vous pouvez en lire davantage ici : [Pydantic Settings : prise en charge de Dotenv (.env)](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#dotenv-env-support). /// tip | Astuce -Pour que cela fonctionne, vous devez exécuter `pip install python-dotenv`. +Pour que cela fonctionne, ajoutez `python-dotenv` à votre projet avec `uv add python-dotenv`. /// @@ -197,7 +221,7 @@ Puis mettre à jour votre `config.py` avec : /// tip | Astuce -L'attribut `model_config` est utilisé uniquement pour la configuration Pydantic. Vous pouvez en lire davantage ici : [Pydantic : Concepts : Configuration](https://docs.pydantic.dev/latest/concepts/config/). +L'attribut `model_config` est utilisé uniquement pour la configuration Pydantic. Vous pouvez en lire davantage ici : [Pydantic : Concepts : Configuration](https://pydantic.dev/docs/validation/latest/concepts/config/). /// @@ -298,5 +322,5 @@ De cette façon, elle se comporte presque comme s'il s'agissait simplement d'une Vous pouvez utiliser Pydantic Settings pour gérer les paramètres ou configurations de votre application, avec toute la puissance des modèles Pydantic. * En utilisant une dépendance, vous pouvez simplifier les tests. -* Vous pouvez utiliser des fichiers `.env`. +* Vous pouvez utiliser des fichiers `.env` avec. * Utiliser `@lru_cache` vous permet d'éviter de relire le fichier dotenv à chaque requête, tout en vous permettant de le surcharger pendant les tests. diff --git a/docs/fr/docs/advanced/sub-applications.md b/docs/fr/docs/advanced/sub-applications.md index 07bd74b..ae61172 100644 --- a/docs/fr/docs/advanced/sub-applications.md +++ b/docs/fr/docs/advanced/sub-applications.md @@ -35,7 +35,7 @@ Exécutez maintenant la commande `fastapi` :
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/fr/docs/advanced/templates.md b/docs/fr/docs/advanced/templates.md index 582cf92..59332d6 100644 --- a/docs/fr/docs/advanced/templates.md +++ b/docs/fr/docs/advanced/templates.md @@ -8,12 +8,12 @@ Il existe des utilitaires pour le configurer facilement que vous pouvez utiliser ## Installer les dépendances { #install-dependencies } -Vous devez créer un [environnement virtuel](../virtual-environments.md), l'activer, puis installer `jinja2` : +Ajoutez `jinja2` à votre projet :
```console -$ pip install jinja2 +$ uv add jinja2 ---> 100% ``` @@ -22,10 +22,10 @@ $ pip install jinja2 ## Utiliser `Jinja2Templates` { #using-jinja2templates } -- Importez `Jinja2Templates`. -- Créez un objet `templates` que vous pourrez réutiliser par la suite. -- Déclarez un paramètre `Request` dans le *chemin d'accès* qui renverra un template. -- Utilisez l'objet `templates` que vous avez créé pour rendre et retourner une `TemplateResponse`, en transmettant le nom du template, l'objet de requête et un dictionnaire de « context » avec des paires clé-valeur à utiliser dans le template Jinja2. +* Importez `Jinja2Templates`. +* Créez un objet `templates` que vous pourrez réutiliser par la suite. +* Déclarez un paramètre `Request` dans le *chemin d'accès* qui renverra un template. +* Utilisez l'objet `templates` que vous avez créé pour rendre et retourner une `TemplateResponse`, en transmettant le nom du template, l'objet de requête et un dictionnaire de « context » avec des paires clé-valeur à utiliser dans le template Jinja2. {* ../../docs_src/templates/tutorial001_py310.py hl[4,11,15:18] *} @@ -123,4 +123,4 @@ Et comme vous utilisez `StaticFiles`, ce fichier CSS est servi automatiquement p ## En savoir plus { #more-details } -Pour plus de détails, y compris sur la façon de tester des templates, consultez [la documentation de Starlette sur les templates](https://www.starlette.dev/templates/). +Pour plus de détails, y compris sur la façon de tester des templates, consultez [la documentation de Starlette sur les templates](https://starlette.dev/templates/). diff --git a/docs/fr/docs/advanced/testing-events.md b/docs/fr/docs/advanced/testing-events.md index c4f9141..0d41679 100644 --- a/docs/fr/docs/advanced/testing-events.md +++ b/docs/fr/docs/advanced/testing-events.md @@ -4,7 +4,8 @@ Lorsque vous avez besoin d'exécuter `lifespan` dans vos tests, vous pouvez util {* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *} -Vous pouvez lire plus de détails dans [« Exécuter lifespan dans les tests sur le site de documentation officiel de Starlette. »](https://www.starlette.dev/lifespan/#running-lifespan-in-tests) + +Vous pouvez lire plus de détails dans [« Exécuter lifespan dans les tests sur le site de documentation officiel de Starlette. »](https://starlette.dev/lifespan/#running-lifespan-in-tests) Pour les événements dépréciés `startup` et `shutdown`, vous pouvez utiliser le `TestClient` comme suit : diff --git a/docs/fr/docs/advanced/testing-websockets.md b/docs/fr/docs/advanced/testing-websockets.md index 3f35e13..c3bdeb3 100644 --- a/docs/fr/docs/advanced/testing-websockets.md +++ b/docs/fr/docs/advanced/testing-websockets.md @@ -8,6 +8,6 @@ Pour cela, vous utilisez `TestClient` dans une instruction `with`, en vous conne /// note | Remarque -Pour plus de détails, consultez la documentation de Starlette sur le [test des WebSockets](https://www.starlette.dev/testclient/#testing-websocket-sessions). +Pour plus de détails, consultez la documentation de Starlette sur le [test des WebSockets](https://starlette.dev/testclient/#testing-websocket-sessions). /// diff --git a/docs/fr/docs/advanced/using-request-directly.md b/docs/fr/docs/advanced/using-request-directly.md index f7779f1..a598cff 100644 --- a/docs/fr/docs/advanced/using-request-directly.md +++ b/docs/fr/docs/advanced/using-request-directly.md @@ -15,7 +15,7 @@ Mais il existe des situations où vous pouvez avoir besoin d'accéder directemen ## Détails sur l'objet `Request` { #details-about-the-request-object } -Comme **FastAPI** est en fait **Starlette** en dessous, avec une couche de plusieurs outils au-dessus, vous pouvez utiliser directement l'objet [`Request`](https://www.starlette.dev/requests/) de Starlette lorsque vous en avez besoin. +Comme **FastAPI** est en fait **Starlette** en dessous, avec une couche de plusieurs outils au-dessus, vous pouvez utiliser directement l'objet [`Request`](https://starlette.dev/requests/) de Starlette lorsque vous en avez besoin. Cela signifie aussi que si vous récupérez des données directement à partir de l'objet `Request` (par exemple, lire le corps), elles ne seront pas validées, converties ni documentées (avec OpenAPI, pour l'interface utilisateur automatique de l'API) par FastAPI. @@ -25,13 +25,13 @@ Mais il existe des cas spécifiques où il est utile d'obtenir l'objet `Request` ## Utiliser l'objet `Request` directement { #use-the-request-object-directly } -Imaginons que vous souhaitiez obtenir l'adresse IP/l'hôte du client dans votre fonction de chemin d'accès. +Imaginons que vous souhaitiez obtenir l'adresse IP/l'hôte du client dans votre *fonction de chemin d'accès*. Pour cela, vous devez accéder directement à la requête. {* ../../docs_src/using_request_directly/tutorial001_py310.py hl[1,7:8] *} -En déclarant un paramètre de fonction de chemin d'accès de type `Request`, **FastAPI** saura passer la `Request` dans ce paramètre. +En déclarant un paramètre de *fonction de chemin d'accès* de type `Request`, **FastAPI** saura passer la `Request` dans ce paramètre. /// tip | Astuce @@ -45,7 +45,7 @@ De la même façon, vous pouvez déclarer tout autre paramètre normalement, et ## Documentation de `Request` { #request-documentation } -Vous pouvez lire plus de détails sur [l'objet `Request` sur le site de documentation officiel de Starlette](https://www.starlette.dev/requests/). +Vous pouvez lire plus de détails sur [l'objet `Request` sur le site de documentation officiel de Starlette](https://starlette.dev/requests/). /// note | Détails techniques diff --git a/docs/fr/docs/advanced/websockets.md b/docs/fr/docs/advanced/websockets.md index b544c6d..d0f0c24 100644 --- a/docs/fr/docs/advanced/websockets.md +++ b/docs/fr/docs/advanced/websockets.md @@ -4,12 +4,12 @@ Vous pouvez utiliser [WebSockets](https://developer.mozilla.org/en-US/docs/Web/A ## Installer `websockets` { #install-websockets } -Vous devez créer un [environnement virtuel](../virtual-environments.md), l'activer, et installer `websockets` (une bibliothèque Python qui facilite l'utilisation du protocole « WebSocket ») : +Ajoutez `websockets` (une bibliothèque Python qui facilite l'utilisation du protocole « WebSocket ») à votre projet :
```console -$ pip install websockets +$ uv add websockets ---> 100% ``` @@ -69,7 +69,7 @@ Mettez votre code dans un fichier `main.py` puis exécutez votre application :
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -126,7 +126,7 @@ Exécutez votre application :
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -182,5 +182,5 @@ Si vous avez besoin de quelque chose de facile à intégrer avec FastAPI mais pl Pour en savoir plus sur les options, consultez la documentation de Starlette concernant : -* [La classe `WebSocket`](https://www.starlette.dev/websockets/). -* [Gestion des WebSocket basée sur des classes](https://www.starlette.dev/endpoints/#websocketendpoint). +* [La classe `WebSocket`](https://starlette.dev/websockets/). +* [Gestion des WebSocket basée sur des classes](https://starlette.dev/endpoints/#websocketendpoint). diff --git a/docs/fr/docs/advanced/wsgi.md b/docs/fr/docs/advanced/wsgi.md index 6e6ce85..4d148af 100644 --- a/docs/fr/docs/advanced/wsgi.md +++ b/docs/fr/docs/advanced/wsgi.md @@ -9,7 +9,7 @@ Pour cela, vous pouvez utiliser `WSGIMiddleware` et l'utiliser pour envelopper v /// note | Remarque -Cela nécessite l'installation de `a2wsgi`, par exemple avec `pip install a2wsgi`. +Cela nécessite d'ajouter `a2wsgi` à votre projet, par exemple avec `uv add a2wsgi`. /// @@ -27,7 +27,7 @@ Auparavant, il était recommandé d'utiliser `WSGIMiddleware` depuis `fastapi.mi Il est conseillé d'utiliser le package `a2wsgi` à la place. L'utilisation reste la même. -Assurez-vous simplement que le package `a2wsgi` est installé et importez `WSGIMiddleware` correctement depuis `a2wsgi`. +Vous devez simplement vous assurer que le package `a2wsgi` est installé et importer `WSGIMiddleware` correctement depuis `a2wsgi`. /// diff --git a/docs/fr/docs/alternatives.md b/docs/fr/docs/alternatives.md index 91a81e2..9e16338 100644 --- a/docs/fr/docs/alternatives.md +++ b/docs/fr/docs/alternatives.md @@ -135,7 +135,7 @@ Adopter et utiliser une norme ouverte pour les spécifications des API, au lieu Et intégrer des outils d'interface utilisateur basés sur des normes : * [Swagger UI](https://github.com/swagger-api/swagger-ui) -* [ReDoc](https://github.com/Rebilly/ReDoc) +* [ReDoc](https://github.com/Redocly/redoc) Ces deux-là ont été choisis parce qu'ils sont populaires et stables, mais en faisant une recherche rapide, vous pourriez trouver des dizaines d'interfaces utilisateur alternatives pour OpenAPI (que vous pouvez utiliser avec **FastAPI**). @@ -254,7 +254,7 @@ Générer le schéma OpenAPI automatiquement, à partir du même code qui défin /// -### [NestJS](https://nestjs.com/) (et [Angular](https://angular.io/)) { #nestjs-and-angular } +### [NestJS](https://nestjs.com/) (et [Angular](https://angular.dev/)) { #nestjs-and-angular } Ce n'est même pas du Python, NestJS est un framework JavaScript (TypeScript) NodeJS inspiré d'Angular. @@ -362,7 +362,7 @@ Comme il est basé sur l'ancienne norme pour les frameworks web Python synchrone /// note | Remarque -Hug a été créé par Timothy Crosley, le même créateur de [`isort`](https://github.com/timothycrosley/isort), un excellent outil pour trier automatiquement les imports dans les fichiers Python. +Hug a été créé par Timothy Crosley, le même créateur de [`isort`](https://github.com/PyCQA/isort), un excellent outil pour trier automatiquement les imports dans les fichiers Python. /// @@ -429,7 +429,7 @@ Je considère **FastAPI** comme un « successeur spirituel » d'APIStar, tout en ## Utilisés par **FastAPI** { #used-by-fastapi } -### [Pydantic](https://docs.pydantic.dev/) { #pydantic } +### [Pydantic](https://pydantic.dev/docs/) { #pydantic } Pydantic est une bibliothèque permettant de définir la validation, la sérialisation et la documentation des données (à l'aide de JSON Schema) en se basant sur les annotations de type Python. @@ -446,7 +446,7 @@ Gérer toute la validation des données, leur sérialisation et la documentation /// -### [Starlette](https://www.starlette.dev/) { #starlette } +### [Starlette](https://starlette.dev/) { #starlette } Starlette est un framework/toolkit léger ASGI, qui est idéal pour construire des services asyncio performants. @@ -491,7 +491,7 @@ Ainsi, tout ce que vous pouvez faire avec Starlette, vous pouvez le faire direct /// -### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn } +### [Uvicorn](https://uvicorn.dev) { #uvicorn } Uvicorn est un serveur ASGI rapide comme l'éclair, basé sur uvloop et httptools. diff --git a/docs/fr/docs/deployment/docker.md b/docs/fr/docs/deployment/docker.md index 688f3b5..24ad207 100644 --- a/docs/fr/docs/deployment/docker.md +++ b/docs/fr/docs/deployment/docker.md @@ -105,36 +105,32 @@ C'est ce que vous voudrez faire dans **la plupart des cas**, par exemple : ### Dépendances des paquets { #package-requirements } -Vous aurez normalement les **dépendances des paquets** de votre application dans un fichier. +Lorsque vous gérez votre projet avec `uv`, ses dépendances directes sont déclarées dans `pyproject.toml` et les versions exactes résolues sont stockées dans `uv.lock`. -Cela dépendra principalement de l'outil que vous utilisez pour **installer** ces dépendances. - -La manière la plus courante consiste à avoir un fichier `requirements.txt` avec les noms des paquets et leurs versions, un par ligne. - -Vous utiliserez bien sûr les mêmes idées que vous avez lues dans [À propos des versions de FastAPI](versions.md) pour définir les plages de versions. - -Par exemple, votre `requirements.txt` pourrait ressembler à : - -``` -fastapi[standard]>=0.113.0,<0.114.0 -pydantic>=2.7.0,<3.0.0 -``` - -Et vous installerez normalement ces dépendances de paquets avec `pip`, par exemple : +Vous pouvez ajouter les paquets dont votre application a besoin avec :
```console -$ pip install -r requirements.txt +$ uv add "fastapi[standard]" pydantic ---> 100% -Successfully installed fastapi pydantic ```
/// note | Remarque -Il existe d'autres formats et outils pour définir et installer des dépendances de paquets. +Le Dockerfile ci-dessous utilise `pip` à l'intérieur du conteneur. Vous pouvez exporter les dépendances verrouillées de votre projet uv vers le format `requirements.txt` qu'il attend : + +
+ +```console +$ uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt +``` + +
+ +Le `requirements.txt` généré est un export pour la construction du conteneur. Continuez à gérer les dépendances avec `uv add` et régénérez-le lorsque `uv.lock` change. /// @@ -372,7 +368,7 @@ Vous verrez la documentation interactive automatique de l'API (fournie par [Swag Et vous pouvez aussi aller sur [http://192.168.99.100/redoc](http://192.168.99.100/redoc) ou [http://127.0.0.1/redoc](http://127.0.0.1/redoc) (ou équivalent, en utilisant votre hôte Docker). -Vous verrez la documentation automatique alternative (fournie par [ReDoc](https://github.com/Rebilly/ReDoc)) : +Vous verrez la documentation automatique alternative (fournie par [ReDoc](https://github.com/Redocly/redoc)) : ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) diff --git a/docs/fr/docs/deployment/fastapicloud.md b/docs/fr/docs/deployment/fastapicloud.md index 82c1633..fc967c7 100644 --- a/docs/fr/docs/deployment/fastapicloud.md +++ b/docs/fr/docs/deployment/fastapicloud.md @@ -5,7 +5,7 @@ Vous pouvez déployer votre application FastAPI sur [FastAPI Cloud](https://fast
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... diff --git a/docs/fr/docs/deployment/manually.md b/docs/fr/docs/deployment/manually.md index 2d9cc4f..6834b4d 100644 --- a/docs/fr/docs/deployment/manually.md +++ b/docs/fr/docs/deployment/manually.md @@ -52,7 +52,7 @@ La principale chose dont vous avez besoin pour exécuter une application **FastA Il existe plusieurs alternatives, notamment : -* [Uvicorn](https://www.uvicorn.dev/) : un serveur ASGI haute performance. +* [Uvicorn](https://uvicorn.dev) : un serveur ASGI haute performance. * [Hypercorn](https://hypercorn.readthedocs.io/) : un serveur ASGI compatible avec HTTP/2 et Trio entre autres fonctionnalités. * [Daphne](https://github.com/django/daphne) : le serveur ASGI conçu pour Django Channels. * [Granian](https://github.com/emmett-framework/granian) : un serveur HTTP Rust pour les applications Python. @@ -73,14 +73,14 @@ Lorsque vous installez FastAPI, il est fourni avec un serveur de production, Uvi Mais vous pouvez également installer un serveur ASGI manuellement. -Vous devez créer un [environnement virtuel](../virtual-environments.md), l'activer, puis vous pouvez installer l'application serveur. +Ajoutez l'application serveur à votre projet. Par exemple, pour installer Uvicorn :
```console -$ pip install "uvicorn[standard]" +$ uv add "uvicorn[standard]" ---> 100% ``` @@ -91,11 +91,11 @@ Un processus similaire s'appliquerait à tout autre programme de serveur ASGI. /// tip | Astuce -En ajoutant `standard`, Uvicorn va installer et utiliser quelques dépendances supplémentaires recommandées. +En ajoutant le `standard`, Uvicorn va installer et utiliser quelques dépendances supplémentaires recommandées. Cela inclut `uvloop`, le remplaçant hautes performances de `asyncio`, qui fournit le gros gain de performance en matière de concurrence. -Lorsque vous installez FastAPI avec quelque chose comme `pip install "fastapi[standard]"`, vous obtenez déjà `uvicorn[standard]` aussi. +Lorsque vous ajoutez FastAPI avec quelque chose comme `uv add "fastapi[standard]"`, vous obtenez déjà `uvicorn[standard]` aussi. /// @@ -106,7 +106,7 @@ Si vous avez installé un serveur ASGI manuellement, vous devrez normalement pas
```console -$ uvicorn main:app --host 0.0.0.0 --port 80 +$ uv run uvicorn main:app --host 0.0.0.0 --port 80 INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) ``` diff --git a/docs/fr/docs/deployment/server-workers.md b/docs/fr/docs/deployment/server-workers.md index 4271621..ad6775a 100644 --- a/docs/fr/docs/deployment/server-workers.md +++ b/docs/fr/docs/deployment/server-workers.md @@ -9,13 +9,13 @@ Reprenons ces concepts de déploiement vus précédemment : * Mémoire * Étapes préalables avant le démarrage -Jusqu'à présent, avec tous les tutoriels dans les documents, vous avez probablement exécuté un programme serveur, par exemple avec la commande `fastapi`, qui lance Uvicorn en exécutant un seul processus. +Jusqu'à présent, avec tous les tutoriels dans les documents, vous avez probablement exécuté un **programme serveur**, par exemple avec la commande `fastapi`, qui lance Uvicorn, en exécutant un **seul processus**. -Lors du déploiement d'applications, vous voudrez probablement avoir une réplication de processus pour tirer parti de plusieurs cœurs et pouvoir gérer davantage de requêtes. +Lors du déploiement d'applications, vous voudrez probablement avoir une **réplication de processus** pour tirer parti de **plusieurs cœurs** et pouvoir gérer davantage de requêtes. Comme vous l'avez vu dans le chapitre précédent sur les [Concepts de déploiement](concepts.md), il existe plusieurs stratégies possibles. -Ici, je vais vous montrer comment utiliser Uvicorn avec des processus workers en utilisant la commande `fastapi` ou directement la commande `uvicorn`. +Ici, je vais vous montrer comment utiliser **Uvicorn** avec des **processus workers** en utilisant la commande `fastapi` ou directement la commande `uvicorn`. /// note | Remarque @@ -86,7 +86,7 @@ Si vous préférez utiliser directement la commande `uvicorn` :
```console -$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 +$ uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit) INFO: Started parent process [27365] INFO: Started server process [27368] @@ -113,9 +113,9 @@ Vous pouvez aussi voir qu'il affiche le **PID** de chaque processus, `27365` pou ## Concepts de déploiement { #deployment-concepts } -Ici, vous avez vu comment utiliser plusieurs workers pour paralléliser l'exécution de l'application, tirer parti de plusieurs cœurs du CPU et être en mesure de servir davantage de requêtes. +Ici, vous avez vu comment utiliser plusieurs **workers** pour **paralléliser** l'exécution de l'application, tirer parti de **plusieurs cœurs** du CPU et être en mesure de servir **davantage de requêtes**. -Dans la liste des concepts de déploiement ci-dessus, l'utilisation de workers aide principalement à la partie réplication, et un peu aux redémarrages, mais vous devez toujours vous occuper des autres : +Dans la liste des concepts de déploiement ci-dessus, l'utilisation de workers aide principalement à la partie **réplication**, et un peu aux **redémarrages**, mais vous devez toujours vous occuper des autres : * **Sécurité - HTTPS** * **Exécution au démarrage** @@ -128,12 +128,12 @@ Dans la liste des concepts de déploiement ci-dessus, l'utilisation de workers a Dans le prochain chapitre sur [FastAPI dans des conteneurs - Docker](docker.md), j'expliquerai quelques stratégies que vous pourriez utiliser pour gérer les autres **concepts de déploiement**. -Je vous montrerai comment créer votre propre image à partir de zéro pour exécuter un seul processus Uvicorn. C'est un processus simple et c'est probablement ce que vous voudrez faire lorsque vous utilisez un système distribué de gestion de conteneurs comme **Kubernetes**. +Je vous montrerai comment **créer votre propre image à partir de zéro** pour exécuter un seul processus Uvicorn. C'est un processus simple et c'est probablement ce que vous voudrez faire lorsque vous utilisez un système distribué de gestion de conteneurs comme **Kubernetes**. ## Récapitulatif { #recap } Vous pouvez utiliser plusieurs processus workers avec l'option CLI `--workers` des commandes `fastapi` ou `uvicorn` pour tirer parti des **CPU multicœurs**, et exécuter **plusieurs processus en parallèle**. -Vous pourriez utiliser ces outils et idées si vous mettez en place votre propre système de déploiement tout en prenant vous-même en charge les autres concepts de déploiement. +Vous pourriez utiliser ces outils et idées si vous mettez en place **votre propre système de déploiement** tout en prenant vous-même en charge les autres concepts de déploiement. Consultez le prochain chapitre pour en savoir plus sur **FastAPI** avec des conteneurs (par exemple Docker et Kubernetes). Vous verrez que ces outils offrent aussi des moyens simples de résoudre les autres **concepts de déploiement**. ✨ diff --git a/docs/fr/docs/environment-variables.md b/docs/fr/docs/environment-variables.md index 0651947..a80ffdf 100644 --- a/docs/fr/docs/environment-variables.md +++ b/docs/fr/docs/environment-variables.md @@ -1,298 +1,11 @@ # Variables d'environnement { #environment-variables } -/// tip | Astuce +Une **variable d'environnement** (également appelée **env var**) est une valeur qui vit en dehors de votre code Python, dans le système d'exploitation, et qui peut être lue par votre application et d'autres programmes. -Si vous savez déjà ce que sont les « variables d'environnement » et comment les utiliser, vous pouvez passer cette section. +Les applications FastAPI utilisent couramment les variables d'environnement pour la configuration, comme les URL de bases de données, les identifiants de messagerie et les clés secrètes. -/// +Vous apprendrez à les utiliser pour la configuration d'application dans [Paramètres et variables d'environnement](advanced/settings.md). -Une variable d'environnement (également appelée « **env var** ») est une variable qui vit **en dehors** du code Python, dans le **système d'exploitation**, et qui peut être lue par votre code Python (ou par d'autres programmes également). +## En savoir plus { #learn-more } -Les variables d'environnement peuvent être utiles pour gérer des **paramètres** d'application, dans le cadre de l'**installation** de Python, etc. - -## Créer et utiliser des variables d'environnement { #create-and-use-env-vars } - -Vous pouvez **créer** et utiliser des variables d'environnement dans le **shell (terminal)**, sans avoir besoin de Python : - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// Vous pouvez créer une variable d'environnement MY_NAME avec -$ export MY_NAME="Wade Wilson" - -// Vous pouvez ensuite l'utiliser avec d'autres programmes, par exemple -$ echo "Hello $MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// Créer une variable d'environnement MY_NAME -$ $Env:MY_NAME = "Wade Wilson" - -// L'utiliser avec d'autres programmes, par exemple -$ echo "Hello $Env:MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -## Lire des variables d'environnement en Python { #read-env-vars-in-python } - -Vous pouvez également créer des variables d'environnement **en dehors** de Python, dans le terminal (ou par tout autre moyen), puis les **lire en Python**. - -Par exemple, vous pouvez avoir un fichier `main.py` contenant : - -```Python hl_lines="3" -import os - -name = os.getenv("MY_NAME", "World") -print(f"Hello {name} from Python") -``` - -/// tip | Astuce - -Le deuxième argument de [`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) est la valeur par défaut à retourner. - -S'il n'est pas fourni, c'est `None` par défaut ; ici, nous fournissons `"World"` comme valeur par défaut à utiliser. - -/// - -Vous pouvez ensuite exécuter ce programme Python : - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// Ici, nous ne définissons pas encore la variable d'environnement -$ python main.py - -// Comme nous ne l'avons pas définie, nous obtenons la valeur par défaut - -Hello World from Python - -// Mais si nous créons d'abord une variable d'environnement -$ export MY_NAME="Wade Wilson" - -// Puis que nous relançons le programme -$ python main.py - -// Il peut maintenant lire la variable d'environnement - -Hello Wade Wilson from Python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// Ici, nous ne définissons pas encore la variable d'environnement -$ python main.py - -// Comme nous ne l'avons pas définie, nous obtenons la valeur par défaut - -Hello World from Python - -// Mais si nous créons d'abord une variable d'environnement -$ $Env:MY_NAME = "Wade Wilson" - -// Puis que nous relançons le programme -$ python main.py - -// Il peut maintenant lire la variable d'environnement - -Hello Wade Wilson from Python -``` - -
- -//// - -Comme les variables d'environnement peuvent être définies en dehors du code, mais lues par le code, et qu'elles n'ont pas besoin d'être stockées (validées dans `git`) avec le reste des fichiers, il est courant de les utiliser pour les configurations ou les **paramètres**. - -Vous pouvez également créer une variable d'environnement uniquement pour l'**invocation d'un programme spécifique**, qui ne sera disponible que pour ce programme et uniquement pendant sa durée d'exécution. - -Pour cela, créez-la juste avant le programme, sur la même ligne : - -
- -```console -// Créer en ligne une variable d'environnement MY_NAME pour cet appel de programme -$ MY_NAME="Wade Wilson" python main.py - -// Il peut maintenant lire la variable d'environnement - -Hello Wade Wilson from Python - -// La variable d'environnement n'existe plus ensuite -$ python main.py - -Hello World from Python -``` - -
- -/// tip | Astuce - -Vous pouvez en lire davantage sur [The Twelve-Factor App : Config](https://12factor.net/config). - -/// - -## Gérer les types et la validation { #types-and-validation } - -Ces variables d'environnement ne peuvent gérer que des **chaînes de texte**, car elles sont externes à Python et doivent être compatibles avec les autres programmes et le reste du système (et même avec différents systèmes d'exploitation, comme Linux, Windows et macOS). - -Cela signifie que **toute valeur** lue en Python à partir d'une variable d'environnement **sera une `str`**, et que toute conversion vers un autre type ou toute validation doit être effectuée dans le code. - -Vous en apprendrez davantage sur l'utilisation des variables d'environnement pour gérer les **paramètres d'application** dans le [Guide utilisateur avancé - Paramètres et variables d'environnement](./advanced/settings.md). - -## Variable d'environnement `PATH` { #path-environment-variable } - -Il existe une variable d'environnement **spéciale** appelée **`PATH`** qui est utilisée par les systèmes d'exploitation (Linux, macOS, Windows) pour trouver les programmes à exécuter. - -La valeur de la variable `PATH` est une longue chaîne composée de répertoires séparés par deux-points `:` sous Linux et macOS, et par point-virgule `;` sous Windows. - -Par exemple, la variable d'environnement `PATH` peut ressembler à ceci : - -//// tab | Linux, macOS - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -Cela signifie que le système doit rechercher les programmes dans les répertoires : - -* `/usr/local/bin` -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32 -``` - -Cela signifie que le système doit rechercher les programmes dans les répertoires : - -* `C:\Program Files\Python312\Scripts` -* `C:\Program Files\Python312` -* `C:\Windows\System32` - -//// - -Lorsque vous tapez une **commande** dans le terminal, le système d'exploitation **cherche** le programme dans **chacun de ces répertoires** listés dans la variable d'environnement `PATH`. - -Par exemple, lorsque vous tapez `python` dans le terminal, le système d'exploitation cherche un programme nommé `python` dans le **premier répertoire** de cette liste. - -S'il le trouve, alors il **l'utilise**. Sinon, il continue à chercher dans les **autres répertoires**. - -### Installer Python et mettre à jour `PATH` { #installing-python-and-updating-the-path } - -Lorsque vous installez Python, il est possible que l'on vous demande si vous souhaitez mettre à jour la variable d'environnement `PATH`. - -//// tab | Linux, macOS - -Supposons que vous installiez Python et qu'il se retrouve dans un répertoire `/opt/custompython/bin`. - -Si vous acceptez de mettre à jour la variable d'environnement `PATH`, l'installateur ajoutera `/opt/custompython/bin` à la variable d'environnement `PATH`. - -Cela pourrait ressembler à ceci : - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin -``` - -Ainsi, lorsque vous tapez `python` dans le terminal, le système trouvera le programme Python dans `/opt/custompython/bin` (le dernier répertoire) et utilisera celui-là. - -//// - -//// tab | Windows - -Supposons que vous installiez Python et qu'il se retrouve dans un répertoire `C:\opt\custompython\bin`. - -Si vous acceptez de mettre à jour la variable d'environnement `PATH`, l'installateur ajoutera `C:\opt\custompython\bin` à la variable d'environnement `PATH`. - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin -``` - -Ainsi, lorsque vous tapez `python` dans le terminal, le système trouvera le programme Python dans `C:\opt\custompython\bin` (le dernier répertoire) et utilisera celui-là. - -//// - -Ainsi, si vous tapez : - -
- -```console -$ python -``` - -
- -//// tab | Linux, macOS - -Le système va **trouver** le programme `python` dans `/opt/custompython/bin` et l'exécuter. - -Cela reviendrait à peu près à taper : - -
- -```console -$ /opt/custompython/bin/python -``` - -
- -//// - -//// tab | Windows - -Le système va **trouver** le programme `python` dans `C:\opt\custompython\bin\python` et l'exécuter. - -Cela reviendrait à peu près à taper : - -
- -```console -$ C:\opt\custompython\bin\python -``` - -
- -//// - -Ces informations vous seront utiles lors de l'apprentissage des [Environnements virtuels](virtual-environments.md). - -## Conclusion { #conclusion } - -Avec cela, vous devriez avoir une compréhension de base de ce que sont les **variables d'environnement** et de la façon de les utiliser en Python. - -Vous pouvez également en lire davantage sur la [page Wikipédia dédiée aux variables d'environnement](https://en.wikipedia.org/wiki/Environment_variable). - -Dans de nombreux cas, il n'est pas évident de voir immédiatement en quoi les variables d'environnement seraient utiles et applicables. Mais elles réapparaissent dans de nombreux scénarios lorsque vous développez, il est donc bon de les connaître. - -Par exemple, vous aurez besoin de ces informations dans la section suivante, sur les [Environnements virtuels](virtual-environments.md). +Lisez le [guide des variables d'environnement](https://tiangolo.com/guides/environment-variables/) pour une explication détaillée et multiplateforme, incluant la façon de créer et de lire des variables d'environnement et le fonctionnement de la variable d'environnement `PATH`. diff --git a/docs/fr/docs/fastapi-cli.md b/docs/fr/docs/fastapi-cli.md index ee58af7..31c763f 100644 --- a/docs/fr/docs/fastapi-cli.md +++ b/docs/fr/docs/fastapi-cli.md @@ -2,7 +2,7 @@ **FastAPI CLI** est un programme en ligne de commande que vous pouvez utiliser pour servir votre application FastAPI, gérer votre projet FastAPI, et plus encore. -Lorsque vous installez FastAPI (par exemple avec `pip install "fastapi[standard]"`), il est fourni avec un programme en ligne de commande que vous pouvez exécuter dans le terminal. +Lorsque vous ajoutez FastAPI à votre projet (par exemple avec `uv add "fastapi[standard]"`), il est fourni avec un programme en ligne de commande que vous pouvez exécuter dans le terminal. Pour exécuter votre application FastAPI en développement, vous pouvez utiliser la commande `fastapi dev` : @@ -52,7 +52,7 @@ Pour la production, utilisez `fastapi run` plutôt que `fastapi dev`. 🚀 /// -En interne, **FastAPI CLI** utilise [Uvicorn](https://www.uvicorn.dev), un serveur ASGI haute performance, prêt pour la production. 😎 +En interne, **FastAPI CLI** utilise [Uvicorn](https://uvicorn.dev), un serveur ASGI haute performance, prêt pour la production. 😎 La CLI `fastapi` tentera de détecter automatiquement l’application FastAPI à exécuter, en supposant qu’il s’agit d’un objet nommé `app` dans un fichier `main.py` (ou quelques autres variantes). @@ -100,13 +100,13 @@ from backend.main import app Vous pouvez également passer le chemin du fichier à la commande `fastapi dev`, et elle devinera l’objet d’application FastAPI à utiliser : ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` Ou bien, vous pouvez aussi passer l’option `--entrypoint` à la commande `fastapi dev` : ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` Mais vous devez vous rappeler de passer le bon chemin\entrypoint à chaque fois que vous appelez la commande `fastapi`. @@ -119,9 +119,13 @@ L’exécution de `fastapi dev` lance le mode développement. Par défaut, l’**auto-reload** est activé et recharge automatiquement le serveur lorsque vous modifiez votre code. Cela consomme des ressources et peut être moins stable que lorsqu’il est désactivé. Vous devez l’utiliser uniquement pour le développement. Il écoute aussi sur l’adresse IP `127.0.0.1`, qui est l’adresse IP permettant à votre machine de communiquer uniquement avec elle‑même (`localhost`). +Avant d’importer votre application, `fastapi dev` définit la variable d’environnement `FASTAPI_ENV` à `development`. Si `FASTAPI_ENV` est déjà définie, sa valeur existante est conservée. Cela permet au code de démarrage de l’application de choisir un comportement adapté au développement tout en vous permettant de fournir un environnement spécifique à l’application, comme `staging`. + +Les valeurs conventionnelles de `FASTAPI_ENV` sont `development` et `production`. `fastapi run` laisse actuellement `FASTAPI_ENV` inchangée, donc définissez-la explicitement si votre application doit détecter le mode production. + ## `fastapi run` { #fastapi-run } -Exécuter `fastapi run` démarre FastAPI en mode production par défaut. +Exécuter `fastapi run` démarre FastAPI en mode production. Par défaut, l’**auto-reload** est désactivé. Il écoute aussi sur l’adresse IP `0.0.0.0`, ce qui signifie toutes les adresses IP disponibles ; de cette manière, il sera accessible publiquement à toute personne pouvant communiquer avec la machine. C’est ainsi que vous l’exécutez normalement en production, par exemple dans un conteneur. diff --git a/docs/fr/docs/features.md b/docs/fr/docs/features.md index 4ded182..f63783b 100644 --- a/docs/fr/docs/features.md +++ b/docs/fr/docs/features.md @@ -19,7 +19,7 @@ Documentation d'API interactive et interfaces web d'exploration. Comme le framew ![interaction avec Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* Documentation d'API alternative avec [**ReDoc**](https://github.com/Rebilly/ReDoc). +* Documentation d'API alternative avec [**ReDoc**](https://github.com/Redocly/redoc). ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) @@ -159,7 +159,7 @@ Toute intégration est conçue pour être si simple à utiliser (avec des dépen ## Fonctionnalités de Starlette { #starlette-features } -**FastAPI** est entièrement compatible avec (et basé sur) [**Starlette**](https://www.starlette.dev/). Donc, tout code Starlette additionnel que vous avez fonctionnera aussi. +**FastAPI** est entièrement compatible avec (et basé sur) [**Starlette**](https://starlette.dev/). Donc, tout code Starlette additionnel que vous avez fonctionnera aussi. `FastAPI` est en fait une sous-classe de `Starlette`. Ainsi, si vous connaissez ou utilisez déjà Starlette, la plupart des fonctionnalités fonctionneront de la même manière. @@ -177,9 +177,9 @@ Avec **FastAPI** vous obtenez toutes les fonctionnalités de **Starlette** (puis ## Fonctionnalités de Pydantic { #pydantic-features } -**FastAPI** est entièrement compatible avec (et basé sur) [**Pydantic**](https://docs.pydantic.dev/). Donc, tout code Pydantic additionnel que vous avez fonctionnera aussi. +**FastAPI** est entièrement compatible avec (et basé sur) [**Pydantic**](https://pydantic.dev/docs/). Donc, tout code Pydantic additionnel que vous avez fonctionnera aussi. -Y compris des bibliothèques externes également basées sur Pydantic, servant d’ORM, d’ODM pour les bases de données. +Y compris des bibliothèques externes également basées sur Pydantic, telles que des ORM et des ODM pour les bases de données. Cela signifie également que, dans de nombreux cas, vous pouvez passer l'objet que vous recevez d'une requête **directement à la base de données**, puisque tout est validé automatiquement. @@ -190,7 +190,7 @@ Avec **FastAPI** vous obtenez toutes les fonctionnalités de **Pydantic** (puisq * **Pas de prise de tête** : * Pas de micro-langage de définition de schéma à apprendre. * Si vous connaissez les types Python vous savez utiliser Pydantic. -* Fonctionne bien avec votre **IDE/linter/cerveau** : +* Fonctionne bien avec votre **IDE/linter/cerveau** : * Parce que les structures de données de Pydantic sont simplement des instances de classes que vous définissez ; l'autocomplétion, le linting, mypy et votre intuition devraient tous bien fonctionner avec vos données validées. * Valider des **structures complexes** : * Utilisation de modèles Pydantic hiérarchiques, de `List` et `Dict` du `typing` Python, etc. diff --git a/docs/fr/docs/help-fastapi.md b/docs/fr/docs/help-fastapi.md index db46bcb..7dc2115 100644 --- a/docs/fr/docs/help-fastapi.md +++ b/docs/fr/docs/help-fastapi.md @@ -46,20 +46,6 @@ Vous pouvez suivre [moi (Sebastián Ramírez / `tiangolo`)](https://tiangolo.com * [@tiangolo.com sur **Bluesky**](https://bsky.app/profile/tiangolo.com) * [@tiangolo sur **LinkedIn**](https://www.linkedin.com/in/tiangolo/). -## Aider les autres avec des questions sur GitHub { #help-others-with-questions-in-github } - -Vous pouvez essayer d'aider les autres avec leurs questions dans [GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered). - -Dans de nombreux cas, vous connaissez peut-être déjà la réponse à ces questions. 🤓 - -Si vous aidez beaucoup de personnes avec leurs questions, vous deviendrez un [Expert FastAPI](fastapi-people.md#fastapi-experts) officiel. 🎉 - -N'oubliez pas, le point le plus important est : essayez d'être aimable. 🤗 - -### Comment aider { #how-to-help } - -Suivez le [guide sur la manière d'aider](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github) ici. - ## Poser des questions { #ask-questions } Vous pouvez [créer une nouvelle question](https://github.com/fastapi/fastapi/discussions/new?category=questions) dans le dépôt GitHub, par exemple pour : @@ -69,7 +55,7 @@ Vous pouvez [créer une nouvelle question](https://github.com/fastapi/fastapi/di ## Rejoindre le chat { #join-the-chat } -Rejoignez le 👥 [serveur Discord](https://discord.gg/VQjSZaeJmf) 👥 et échangez avec d'autres membres de la communauté FastAPI. +Rejoignez le 👥 [serveur Discord](https://discord.com/invite/VQjSZaeJmf) 👥 et échangez avec d'autres membres de la communauté FastAPI. /// tip | Astuce @@ -86,3 +72,9 @@ Gardez à l'esprit que, comme les chats permettent une « conversation libre », Sur GitHub, le modèle vous guidera pour rédiger la bonne question afin que vous puissiez plus facilement obtenir une bonne réponse, ou même résoudre le problème vous‑même avant de demander. Les conversations dans les systèmes de chat ne sont pas non plus aussi facilement recherchables que sur GitHub, elles se perdent. + +## Essayer FastAPI Cloud { #try-fastapi-cloud } + +Le financement principal de FastAPI et de ses amis provient de [**FastAPI Cloud**](https://fastapicloud.com), une plateforme pour déployer des applications FastAPI de manière simple et rapide, avec une seule commande, `fastapi deploy`. + +FastAPI Cloud est construit par la même équipe derrière FastAPI. Vous pouvez l'essayer et l'envisager pour vos projets. diff --git a/docs/fr/docs/history-design-future.md b/docs/fr/docs/history-design-future.md index 6cd530c..b7c14eb 100644 --- a/docs/fr/docs/history-design-future.md +++ b/docs/fr/docs/history-design-future.md @@ -54,11 +54,11 @@ Le tout de manière à offrir la meilleure expérience de développement à tous ## Exigences { #requirements } -Après avoir testé plusieurs alternatives, j'ai décidé que j'allais utiliser [**Pydantic**](https://docs.pydantic.dev/) pour ses avantages. +Après avoir testé plusieurs alternatives, j'ai décidé que j'allais utiliser [**Pydantic**](https://pydantic.dev/docs/) pour ses avantages. J'y ai ensuite contribué, pour le rendre entièrement compatible avec JSON Schema, pour supporter différentes manières de définir les déclarations de contraintes, et pour améliorer le support des éditeurs (vérifications de type, autocomplétion) sur la base des tests effectués dans plusieurs éditeurs. -Pendant le développement, j'ai également contribué à [**Starlette**](https://www.starlette.dev/), l'autre exigence clé. +Pendant le développement, j'ai également contribué à [**Starlette**](https://starlette.dev/), l'autre exigence clé. ## Développement { #development } diff --git a/docs/fr/docs/how-to/custom-request-and-route.md b/docs/fr/docs/how-to/custom-request-and-route.md index 0b3ab88..2fe8b6b 100644 --- a/docs/fr/docs/how-to/custom-request-and-route.md +++ b/docs/fr/docs/how-to/custom-request-and-route.md @@ -66,7 +66,7 @@ Le `dict` `scope` et la fonction `receive` font tous deux partie de la spécific Et ces deux éléments, `scope` et `receive`, sont ce dont on a besoin pour créer une nouvelle instance de `Request`. -Pour en savoir plus sur `Request`, consultez [les documents de Starlette sur les requêtes](https://www.starlette.dev/requests/). +Pour en savoir plus sur `Request`, consultez [les documents de Starlette sur les requêtes](https://starlette.dev/requests/). /// diff --git a/docs/fr/docs/how-to/extending-openapi.md b/docs/fr/docs/how-to/extending-openapi.md index dab3e58..5ca026c 100644 --- a/docs/fr/docs/how-to/extending-openapi.md +++ b/docs/fr/docs/how-to/extending-openapi.md @@ -24,7 +24,7 @@ Et cette fonction `get_openapi()` reçoit comme paramètres : * `version` : La version de votre API, p. ex. `2.5.0`. * `openapi_version` : La version de la spécification OpenAPI utilisée. Par défaut, la plus récente : `3.1.0`. * `summary` : Un court résumé de l'API. -* `description` : La description de votre API ; elle peut inclure du markdown et sera affichée dans la documentation. +* `description` : La description de votre API ; elle peut inclure du markdown et sera affichée dans les documents. * `routes` : Les routes de l'application, extraites de `app.routes`. FastAPI les utilise pour collecter les *chemins d'accès* enregistrés, y compris ceux provenant des routeurs inclus. /// tip | Détails techniques @@ -45,7 +45,7 @@ Le paramètre `summary` est disponible à partir d'OpenAPI 3.1.0, pris en charge En vous appuyant sur les informations ci-dessus, vous pouvez utiliser la même fonction utilitaire pour générer le schéma OpenAPI et remplacer chaque partie dont vous avez besoin. -Par exemple, ajoutons [l’extension OpenAPI de ReDoc pour inclure un logo personnalisé](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo). +Par exemple, ajoutons [l’extension OpenAPI de ReDoc pour inclure un logo personnalisé](https://github.com/Redocly/redoc/blob/main/docs/redoc-vendor-extensions.md#x-logo). ### **FastAPI** normal { #normal-fastapi } diff --git a/docs/fr/docs/how-to/graphql.md b/docs/fr/docs/how-to/graphql.md index 10fa6be..000c6d6 100644 --- a/docs/fr/docs/how-to/graphql.md +++ b/docs/fr/docs/how-to/graphql.md @@ -21,7 +21,7 @@ Voici quelques bibliothèques **GraphQL** qui prennent en charge **ASGI**. Vous * [Strawberry](https://strawberry.rocks/) 🍓 * Avec [les documents pour FastAPI](https://strawberry.rocks/docs/integrations/fastapi) * [Ariadne](https://ariadnegraphql.org/) - * Avec [les documents pour FastAPI](https://ariadnegraphql.org/docs/fastapi-integration) + * Avec [les documents pour FastAPI](https://ariadnegraphql.org/server/Integrations/fastapi-integration) * [Tartiflette](https://tartiflette.io/) * Avec [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) pour fournir l'intégration ASGI * [Graphene](https://graphene-python.org/) diff --git a/docs/fr/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/fr/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index 48d4b3f..1778e94 100644 --- a/docs/fr/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/fr/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -24,7 +24,7 @@ Si vous avez une ancienne application FastAPI avec Pydantic v1, je vais vous mon ## Guide officiel { #official-guide } -Pydantic propose un [Guide de migration](https://docs.pydantic.dev/latest/migration/) officiel de la v1 à la v2. +Pydantic propose un [Guide de migration](https://pydantic.dev/docs/validation/latest/get-started/migration/) officiel de la v1 à la v2. Il inclut aussi ce qui a changé, comment les validations sont désormais plus correctes et strictes, les pièges possibles, etc. diff --git a/docs/fr/docs/index.md b/docs/fr/docs/index.md index ccc0023..352568a 100644 --- a/docs/fr/docs/index.md +++ b/docs/fr/docs/index.md @@ -110,7 +110,7 @@ Les principales fonctionnalités sont :
-## FastAPI Conf { #fastapi-conf } - -[**FastAPI Conf '26**](https://fastapiconf.com) aura lieu le **28 octobre 2026** à **Amsterdam, NL**. Tout sur FastAPI, à la source. 🎤 - -FastAPI Conf '26 - 28 octobre 2026 - Amsterdam, NL - ## Mini documentaire FastAPI { #fastapi-mini-documentary } Un [mini documentaire FastAPI](https://www.youtube.com/watch?v=mpR8ngthqiE) est sorti fin 2025, vous pouvez le regarder en ligne : @@ -175,17 +169,17 @@ Si vous construisez une application ```console -$ pip install "fastapi[standard]" +$ uv add "fastapi[standard]" ---> 100% ``` @@ -194,6 +188,8 @@ $ pip install "fastapi[standard]" **Remarque** : Vous devez vous assurer de mettre `"fastapi[standard]"` entre guillemets pour garantir que cela fonctionne dans tous les terminaux. +Si vous préférez utiliser `pip`, installez `fastapi[standard]` dans un environnement virtuel. Consultez le [guide d'installation](tutorial/#install-fastapi) pour les étapes alternatives. + ## Exemple { #example } ### Créer { #create-it } @@ -250,7 +246,7 @@ Lancez le serveur avec :
```console -$ fastapi dev +$ uv run fastapi dev ╭────────── FastAPI CLI - Development mode ───────────╮ │ │ @@ -277,7 +273,7 @@ INFO: Application startup complete.
À propos de la commande fastapi dev... -La commande `fastapi dev` lit automatiquement votre fichier `main.py`, détecte l'application **FastAPI** qu'il contient et lance un serveur avec [Uvicorn](https://www.uvicorn.dev). +La commande `fastapi dev` lit automatiquement votre fichier `main.py`, détecte l'application **FastAPI** qu'il contient et lance un serveur avec [Uvicorn](https://uvicorn.dev). Par défaut, `fastapi dev` démarre avec le rechargement automatique activé pour le développement local. @@ -314,7 +310,7 @@ Vous verrez la documentation interactive automatique de l'API (fournie par [Swag Et maintenant, rendez-vous sur [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc). -Vous verrez la documentation alternative automatique (fournie par [ReDoc](https://github.com/Rebilly/ReDoc)) : +Vous verrez la documentation alternative automatique (fournie par [ReDoc](https://github.com/Redocly/redoc)) : ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -497,7 +493,7 @@ Vous pouvez, si vous le souhaitez, déployer votre application FastAPI sur [Fast
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -540,7 +536,7 @@ FastAPI dépend de Pydantic et Starlette. ### Dépendances `standard` { #standard-dependencies } -Lorsque vous installez FastAPI avec `pip install "fastapi[standard]"`, il inclut le groupe `standard` de dépendances optionnelles : +Lorsque vous installez FastAPI avec `uv add "fastapi[standard]"`, il inclut le groupe `standard` de dépendances optionnelles : Utilisées par Pydantic : @@ -554,17 +550,17 @@ Utilisées par Starlette : Utilisées par FastAPI : -* [`uvicorn`](https://www.uvicorn.dev) - pour le serveur qui charge et sert votre application. Cela inclut `uvicorn[standard]`, qui comprend certaines dépendances (par ex. `uvloop`) nécessaires pour une haute performance. +* [`uvicorn`](https://uvicorn.dev) - pour le serveur qui charge et sert votre application. Cela inclut `uvicorn[standard]`, qui comprend certaines dépendances (par ex. `uvloop`) nécessaires pour une haute performance. * `fastapi-cli[standard]` - pour fournir la commande `fastapi`. * Cela inclut `fastapi-cloud-cli`, qui vous permet de déployer votre application FastAPI sur [FastAPI Cloud](https://fastapicloud.com). ### Sans les dépendances `standard` { #without-standard-dependencies } -Si vous ne souhaitez pas inclure les dépendances optionnelles `standard`, vous pouvez installer avec `pip install fastapi` au lieu de `pip install "fastapi[standard]"`. +Si vous ne souhaitez pas inclure les dépendances optionnelles `standard`, vous pouvez installer avec `uv add fastapi` au lieu de `uv add "fastapi[standard]"`. ### Sans `fastapi-cloud-cli` { #without-fastapi-cloud-cli } -Si vous souhaitez installer FastAPI avec les dépendances standard mais sans `fastapi-cloud-cli`, vous pouvez installer avec `pip install "fastapi[standard-no-fastapi-cloud-cli]"`. +Si vous souhaitez installer FastAPI avec les dépendances standard mais sans `fastapi-cloud-cli`, vous pouvez installer avec `uv add "fastapi[standard-no-fastapi-cloud-cli]"`. ### Dépendances optionnelles supplémentaires { #additional-optional-dependencies } @@ -572,13 +568,13 @@ Il existe des dépendances supplémentaires que vous pourriez vouloir installer. Dépendances optionnelles supplémentaires pour Pydantic : -* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - pour la gestion des paramètres. -* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - pour des types supplémentaires à utiliser avec Pydantic. +* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) - pour la gestion des paramètres. +* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) - pour des types supplémentaires à utiliser avec Pydantic. Dépendances optionnelles supplémentaires pour FastAPI : * [`orjson`](https://github.com/ijl/orjson) - Obligatoire si vous souhaitez utiliser `ORJSONResponse`. -* [`ujson`](https://github.com/esnme/ultrajson) - Obligatoire si vous souhaitez utiliser `UJSONResponse`. +* [`ujson`](https://github.com/ultrajson/ultrajson) - Obligatoire si vous souhaitez utiliser `UJSONResponse`. ## Licence { #license } diff --git a/docs/fr/docs/project-generation.md b/docs/fr/docs/project-generation.md index b1f3f6c..18651c8 100644 --- a/docs/fr/docs/project-generation.md +++ b/docs/fr/docs/project-generation.md @@ -5,13 +5,13 @@ Les modèles, bien qu'ils soient généralement livrés avec une configuration s Vous pouvez utiliser ce modèle pour démarrer, car il inclut une grande partie de la configuration initiale, la sécurité, la base de données et quelques endpoints d'API déjà prêts pour vous. -Dépôt GitHub : [Modèle Full Stack FastAPI](https://github.com/tiangolo/full-stack-fastapi-template) +Dépôt GitHub : [Modèle Full Stack FastAPI](https://github.com/fastapi/full-stack-fastapi-template) ## Modèle Full Stack FastAPI - Pile technologique et fonctionnalités { #full-stack-fastapi-template-technology-stack-and-features } - ⚡ [**FastAPI**](https://fastapi.tiangolo.com/fr) pour l'API backend Python. - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) pour les interactions avec la base de données SQL en Python (ORM). - - 🔍 [Pydantic](https://docs.pydantic.dev), utilisé par FastAPI, pour la validation des données et la gestion des paramètres. + - 🔍 [Pydantic](https://pydantic.dev/docs/), utilisé par FastAPI, pour la validation des données et la gestion des paramètres. - 💾 [PostgreSQL](https://www.postgresql.org) comme base de données SQL. - 🚀 [React](https://react.dev) pour le frontend. - 💃 Utilisation de TypeScript, des hooks, de Vite et d'autres éléments d'un stack frontend moderne. diff --git a/docs/fr/docs/python-types.md b/docs/fr/docs/python-types.md index 8e9dbc5..0ec4848 100644 --- a/docs/fr/docs/python-types.md +++ b/docs/fr/docs/python-types.md @@ -2,7 +2,7 @@ Python prend en charge des « annotations de type » (aussi appelées « type hints ») facultatives. -Ces **« annotations de type »** sont une syntaxe spéciale qui permet de déclarer le type d'une variable. +Ces **« annotations de type »**, ou annotations, sont une syntaxe spéciale qui permet de déclarer le type d'une variable. En déclarant les types de vos variables, les éditeurs et outils peuvent vous offrir un meilleur support. @@ -269,7 +269,7 @@ Cela ne signifie pas « `one_person` est la **classe** appelée `Person` ». ## Modèles Pydantic { #pydantic-models } -[Pydantic](https://docs.pydantic.dev/) est une bibliothèque Python pour effectuer de la validation de données. +[Pydantic](https://pydantic.dev/docs/) est une bibliothèque Python pour effectuer de la validation de données. Vous déclarez la « forme » de la donnée sous forme de classes avec des attributs. @@ -285,7 +285,7 @@ Un exemple tiré des documents officiels de Pydantic : /// note | Remarque -Pour en savoir plus à propos de [Pydantic, consultez ses documents](https://docs.pydantic.dev/). +Pour en savoir plus à propos de [Pydantic, consultez ses documents](https://pydantic.dev/docs/). /// diff --git a/docs/fr/docs/tutorial/background-tasks.md b/docs/fr/docs/tutorial/background-tasks.md index c8f66e5..3e14132 100644 --- a/docs/fr/docs/tutorial/background-tasks.md +++ b/docs/fr/docs/tutorial/background-tasks.md @@ -23,11 +23,11 @@ Pour commencer, importez `BackgroundTasks` et définissez un paramètre dans vot Créez une fonction à exécuter comme tâche d'arrière-plan. -Une fonction à exécuter comme tâche d'arrière-plan est juste une fonction standard qui peut recevoir des paramètres. +C'est simplement une fonction standard qui peut recevoir des paramètres. Elle peut être une fonction asynchrone (`async def`) ou une fonction normale (`def`), **FastAPI** saura la gérer correctement. -Dans cet exemple, la fonction de tâche écrira dans un fichier (afin de simuler un envoi d'email). +Dans ce cas, la fonction de tâche écrira dans un fichier (afin de simuler un envoi d'email). L'opération d'écriture n'utilisant ni `async` ni `await`, on définit la fonction avec un `def` normal. @@ -35,15 +35,15 @@ L'opération d'écriture n'utilisant ni `async` ni `await`, on définit la fonct ## Ajouter une tâche d'arrière-plan { #add-the-background-task } -Dans votre *fonction de chemin d'accès*, passez votre fonction de tâche à l'objet de type `BackgroundTasks` (`background_tasks` ici) grâce à la méthode `.add_task()` : +Dans votre *fonction de chemin d'accès*, passez votre fonction de tâche à l'objet *tâches d'arrière-plan* avec la méthode `.add_task()` : {* ../../docs_src/background_tasks/tutorial001_py310.py hl[14] *} `.add_task()` reçoit comme arguments : * Une fonction de tâche à exécuter en arrière-plan (`write_notification`). -* Les arguments positionnels à passer à la fonction de tâche dans l'ordre (`email`). -* Les arguments nommés à passer à la fonction de tâche (`message="some notification"`). +* Toute séquence d'arguments à passer à la fonction de tâche dans l'ordre (`email`). +* Tous les arguments nommés à passer à la fonction de tâche (`message="some notification"`). ## Injection de dépendances { #dependency-injection } @@ -51,34 +51,36 @@ Utiliser `BackgroundTasks` fonctionne aussi avec le système d'injection de dép **FastAPI** sait quoi faire dans chaque cas et comment réutiliser le même objet, afin que toutes les tâches d'arrière-plan soient fusionnées et que les tâches soient ensuite exécutées en arrière-plan : + {* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *} -Dans cet exemple, les messages seront écrits dans le fichier `log.txt` après que la réponse soit envoyée. + +Dans cet exemple, les messages seront écrits dans le fichier `log.txt` *après* l'envoi de la réponse. S'il y avait un paramètre de requête dans la requête, alors il sera écrit dans le journal via une tâche d'arrière-plan. -Et ensuite une autre tâche d'arrière-plan (générée dans la *fonction de chemin d'accès*) écrira un message comprenant le paramètre de chemin `email`. +Et ensuite une autre tâche d'arrière-plan (générée dans la *fonction de chemin d'accès*) écrira un message en utilisant le paramètre de chemin `email`. ## Détails techniques { #technical-details } -La classe `BackgroundTasks` provient directement de [`starlette.background`](https://www.starlette.dev/background/). +La classe `BackgroundTasks` provient directement de [`starlette.background`](https://starlette.dev/background/). -Elle est importée/incluse directement dans **FastAPI** pour que vous puissiez l'importer depuis `fastapi` et éviter d'importer accidentellement `BackgroundTask` (sans `s` à la fin) depuis `starlette.background`. +Elle est importée/incluse directement dans FastAPI pour que vous puissiez l'importer depuis `fastapi` et éviter d'importer accidentellement l'alternative `BackgroundTask` (sans `s` à la fin) depuis `starlette.background`. En utilisant seulement `BackgroundTasks` (et non `BackgroundTask`), il est possible de l'utiliser en tant que paramètre de *fonction de chemin d'accès* et de laisser **FastAPI** gérer le reste pour vous, comme en utilisant l'objet `Request` directement. -Il est tout de même possible d'utiliser `BackgroundTask` seul dans **FastAPI**, mais dans ce cas il faut créer l'objet dans le code et renvoyer une `Response` Starlette l'incluant. +Il est tout de même possible d'utiliser `BackgroundTask` seul dans FastAPI, mais dans ce cas il faut créer l'objet dans le code et renvoyer une `Response` Starlette l'incluant. -Plus de détails sont disponibles dans [la documentation officielle de Starlette sur les tâches d'arrière-plan](https://www.starlette.dev/background/). +Plus de détails sont disponibles dans [la documentation officielle de Starlette sur les tâches d'arrière-plan](https://starlette.dev/background/). ## Avertissement { #caveat } -Si vous avez besoin de réaliser des traitements lourds en tâche d'arrière-plan et que vous n'avez pas besoin que ces traitements aient lieu dans le même process (par exemple, pas besoin de partager la mémoire, les variables, etc.), il peut s'avérer profitable d'utiliser des outils plus importants tels que [Celery](https://docs.celeryq.dev). +Si vous avez besoin de réaliser des calculs lourds en tâche d'arrière-plan et que vous n'avez pas nécessairement besoin que ces calculs aient lieu dans le même process (par exemple, pas besoin de partager la mémoire, les variables, etc.), il peut s'avérer profitable d'utiliser des outils plus importants tels que [Celery](https://docs.celeryq.dev). -Ces outils nécessitent généralement des configurations plus complexes ainsi qu'un gestionnaire de queue de message, comme RabbitMQ ou Redis, mais ils permettent d'exécuter des tâches d'arrière-plan dans différents process, et surtout, sur plusieurs serveurs. +Ces outils nécessitent généralement des configurations plus complexes ainsi qu'un gestionnaire de queue de messages/jobs, comme RabbitMQ ou Redis, mais ils permettent d'exécuter des tâches d'arrière-plan dans différents process, et surtout, sur plusieurs serveurs. Mais si vous avez besoin d'accéder aux variables et objets de la même application **FastAPI**, ou si vous avez besoin d'effectuer de petites tâches d'arrière-plan (comme envoyer des notifications par email), vous pouvez simplement vous contenter d'utiliser `BackgroundTasks`. ## Résumé { #recap } -Importez et utilisez `BackgroundTasks` grâce aux paramètres de *fonction de chemin d'accès* et les dépendances pour ajouter des tâches d'arrière-plan. +Importez et utilisez `BackgroundTasks` avec des paramètres dans les *fonctions de chemin d'accès* et les dépendances pour ajouter des tâches d'arrière-plan. diff --git a/docs/fr/docs/tutorial/bigger-applications.md b/docs/fr/docs/tutorial/bigger-applications.md index 92976bc..afe224d 100644 --- a/docs/fr/docs/tutorial/bigger-applications.md +++ b/docs/fr/docs/tutorial/bigger-applications.md @@ -180,7 +180,7 @@ Le résultat final est que les chemins d'item sont désormais : ... comme prévu. -* Ils seront marqués avec une liste de tags qui contient une seule chaîne « items ». +* Ils seront marqués avec une liste de tags qui contient une seule chaîne `"items"`. * Ces « tags » sont particulièrement utiles pour les systèmes de documentation interactive automatique (utilisant OpenAPI). * Ils incluront tous les `responses` prédéfinies. * Tous ces *chemins d'accès* auront la liste des `dependencies` évaluées/exécutées avant eux. @@ -487,7 +487,7 @@ De cette façon, la commande `fastapi` saura où trouver votre app. Vous pourriez aussi passer le chemin à la commande, comme : ```console -$ fastapi dev app/main.py +$ uv run fastapi dev app/main.py ``` Mais vous devez vous rappeler de passer le bon chemin à chaque fois que vous appelez la commande `fastapi`. @@ -503,7 +503,7 @@ Maintenant, exécutez votre application :
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/fr/docs/tutorial/body-nested-models.md b/docs/fr/docs/tutorial/body-nested-models.md index 051317a..8e9706d 100644 --- a/docs/fr/docs/tutorial/body-nested-models.md +++ b/docs/fr/docs/tutorial/body-nested-models.md @@ -96,7 +96,7 @@ Là encore, avec cette simple déclaration, avec **FastAPI** vous obtenez : Outre les types singuliers normaux comme `str`, `int`, `float`, etc. vous pouvez utiliser des types singuliers plus complexes qui héritent de `str`. -Pour voir toutes les options dont vous disposez, consultez [l’aperçu des types de Pydantic](https://docs.pydantic.dev/latest/concepts/types/). Vous verrez quelques exemples au chapitre suivant. +Pour voir toutes les options dont vous disposez, consultez [l’aperçu des types de Pydantic](https://pydantic.dev/docs/validation/latest/concepts/types/). Vous verrez quelques exemples au chapitre suivant. Par exemple, comme dans le modèle `Image` nous avons un champ `url`, nous pouvons le déclarer comme instance de `HttpUrl` de Pydantic au lieu de `str` : diff --git a/docs/fr/docs/tutorial/body.md b/docs/fr/docs/tutorial/body.md index 2ff7161..7ced0db 100644 --- a/docs/fr/docs/tutorial/body.md +++ b/docs/fr/docs/tutorial/body.md @@ -6,7 +6,7 @@ Le corps d'une **requête** est de la donnée envoyée par le client à votre AP Votre API aura presque toujours à envoyer un corps de **réponse**. Mais un client n'a pas toujours à envoyer un **corps de la requête** : parfois il demande seulement un chemin, peut-être avec quelques paramètres de requête, mais n'envoie pas de corps. -Pour déclarer un corps de **requête**, on utilise les modèles de [Pydantic](https://docs.pydantic.dev/) en profitant de tous leurs avantages et fonctionnalités. +Pour déclarer un corps de **requête**, on utilise les modèles de [Pydantic](https://pydantic.dev/docs/) avec toute leur puissance et leurs avantages. /// note | Remarque @@ -14,7 +14,7 @@ Pour envoyer de la donnée, vous devez utiliser l'une de ces méthodes : `POST` Envoyer un corps dans une requête `GET` a un comportement non défini dans les spécifications, cela est néanmoins supporté par FastAPI, seulement pour des cas d'utilisation très complexes/extrêmes. -Ceci étant découragé, la documentation interactive générée par Swagger UI ne montrera pas de documentation pour le corps d'une requête `GET`, et les proxys intermédiaires risquent de ne pas le supporter. +Ceci étant découragé, la documentation interactive avec Swagger UI ne montrera pas de documentation pour le corps d'une requête `GET`, et les proxys intermédiaires risquent de ne pas le supporter. /// @@ -67,7 +67,7 @@ Pour l'ajouter à votre *chemin d'accès*, déclarez-le comme vous déclareriez En utilisant uniquement les déclarations de type Python, **FastAPI** réussit à : -* Lire le contenu de la requête en tant que JSON. +* Lire le corps de la requête en tant que JSON. * Convertir les types correspondants (si nécessaire). * Valider la donnée. * Si la donnée est invalide, une erreur propre et claire sera renvoyée, indiquant exactement où et quelle était la donnée incorrecte. @@ -163,4 +163,4 @@ Mais ajouter ces annotations de type permettra à votre éditeur de vous offrir ## Sans Pydantic { #without-pydantic } -Si vous ne voulez pas utiliser des modèles Pydantic, vous pouvez aussi utiliser des paramètres de **Body**. Pour cela, allez voir la documentation sur [Corps de la requête - Paramètres multiples : Valeurs singulières dans le corps](body-multiple-params.md#singular-values-in-body). +Si vous ne voulez pas utiliser des modèles Pydantic, vous pouvez aussi utiliser des paramètres de **Body**. Consultez les documents pour [Corps de la requête - Paramètres multiples : Valeurs singulières dans le corps](body-multiple-params.md#singular-values-in-body). diff --git a/docs/fr/docs/tutorial/debugging.md b/docs/fr/docs/tutorial/debugging.md index cdcfe70..1c89811 100644 --- a/docs/fr/docs/tutorial/debugging.md +++ b/docs/fr/docs/tutorial/debugging.md @@ -15,7 +15,7 @@ Le but principal de `__name__ == "__main__"` est d'avoir du code qui est exécut
```console -$ python myapp.py +$ uv run python myapp.py ```
@@ -35,7 +35,7 @@ Si vous l'exécutez avec :
```console -$ python myapp.py +$ uv run python myapp.py ```
@@ -54,7 +54,7 @@ va s'exécuter. Cela ne se produira pas si vous importez ce module (fichier). -Par exemple, si vous avez un autre fichier `importer.py` qui contient : +Donc, si vous avez un autre fichier `importer.py` avec : ```Python from myapp import app @@ -88,7 +88,7 @@ Par exemple, dans Visual Studio Code, vous pouvez : * Allez dans le panneau « Debug ». * « Add configuration... ». -* Sélectionnez « Python ». +* Sélectionnez « Python » * Lancez le débogueur avec l'option « `Python: Current File (Integrated Terminal)` ». Il démarrera alors le serveur avec votre code **FastAPI**, s'arrêtera à vos points d'arrêt, etc. diff --git a/docs/fr/docs/tutorial/extra-data-types.md b/docs/fr/docs/tutorial/extra-data-types.md index c0c4df1..d0bb521 100644 --- a/docs/fr/docs/tutorial/extra-data-types.md +++ b/docs/fr/docs/tutorial/extra-data-types.md @@ -36,7 +36,7 @@ Voici quelques types de données supplémentaires que vous pouvez utiliser : * `datetime.timedelta` : * Un `datetime.timedelta` Python. * Dans les requêtes et les réponses, il sera représenté sous forme de `float` de secondes totales. - * Pydantic permet aussi de le représenter sous la forme d'un « encodage de différence de temps ISO 8601 », [voir les documents pour plus d'informations](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers). + * Pydantic permet aussi de le représenter sous la forme d'un « encodage de différence de temps ISO 8601 », [voir les documents pour plus d'informations](https://pydantic.dev/docs/validation/latest/concepts/serialization/#custom-serializers). * `frozenset` : * Dans les requêtes et les réponses, traité de la même manière qu'un `set` : * Dans les requêtes, une liste sera lue, les doublons éliminés, puis convertie en `set`. @@ -49,7 +49,7 @@ Voici quelques types de données supplémentaires que vous pouvez utiliser : * `Decimal` : * `Decimal` Python standard. * Dans les requêtes et les réponses, géré de la même manière qu'un `float`. -* Vous pouvez consulter tous les types de données Pydantic valides ici : [Types de données Pydantic](https://docs.pydantic.dev/latest/usage/types/types/). +* Vous pouvez consulter tous les types de données Pydantic valides ici : [Types de données Pydantic](https://pydantic.dev/docs/validation/latest/concepts/types/). ## Exemple { #example } diff --git a/docs/fr/docs/tutorial/extra-models.md b/docs/fr/docs/tutorial/extra-models.md index 7d54295..980e929 100644 --- a/docs/fr/docs/tutorial/extra-models.md +++ b/docs/fr/docs/tutorial/extra-models.md @@ -166,7 +166,7 @@ Pour ce faire, utilisez l'annotation de type Python standard [`typing.Union`](ht /// note | Remarque -Lors de la définition d'une [`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions), incluez d'abord le type le plus spécifique, suivi du type le moins spécifique. Dans l'exemple ci-dessous, le type le plus spécifique `PlaneItem` précède `CarItem` dans `Union[PlaneItem, CarItem]`. +Lors de la définition d'une [`Union`](https://pydantic.dev/docs/validation/latest/concepts/unions/), incluez d'abord le type le plus spécifique, suivi du type le moins spécifique. Dans l'exemple ci-dessous, le type le plus spécifique `PlaneItem` précède `CarItem` dans `Union[PlaneItem, CarItem]`. /// diff --git a/docs/fr/docs/tutorial/first-steps.md b/docs/fr/docs/tutorial/first-steps.md index 9e31e2b..872f18b 100644 --- a/docs/fr/docs/tutorial/first-steps.md +++ b/docs/fr/docs/tutorial/first-steps.md @@ -6,12 +6,18 @@ Le fichier **FastAPI** le plus simple possible pourrait ressembler à ceci : Copiez cela dans un fichier `main.py`. +/// tip | Astuce + +FastAPI a une [extension officielle pour VS Code](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (et Cursor), qui fournit de nombreuses fonctionnalités, notamment un explorateur de chemins d’accès, la recherche de chemins d’accès, la navigation CodeLens dans les tests (aller à la définition depuis les tests), ainsi que le déploiement et les logs FastAPI Cloud, le tout depuis votre éditeur. + +/// + Démarrez le serveur en direct :
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -78,7 +84,7 @@ Vous verrez la documentation interactive de l’API générée automatiquement ( Et maintenant, allez sur [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc). -Vous verrez la documentation automatique alternative (fournie par [ReDoc](https://github.com/Rebilly/ReDoc)) : +Vous verrez la documentation automatique alternative (fournie par [ReDoc](https://github.com/Redocly/redoc)) : ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -185,13 +191,13 @@ from backend.main import app Vous pouvez également passer le chemin du fichier à la commande `fastapi dev`, et elle devinera l’objet d’application FastAPI à utiliser : ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` Ou bien, vous pouvez aussi passer l’option `--entrypoint` à la commande `fastapi dev` : ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` Mais vous devez vous souvenir de passer le chemin\entrypoint correct à chaque exécution de la commande `fastapi`. @@ -205,7 +211,7 @@ Vous pouvez éventuellement déployer votre application FastAPI sur [FastAPI Clo
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -232,7 +238,7 @@ C’est tout ! Vous pouvez maintenant accéder à votre application à cette URL `FastAPI` est une classe qui hérite directement de `Starlette`. -Vous pouvez donc aussi utiliser toutes les fonctionnalités de [Starlette](https://www.starlette.dev/) avec `FastAPI`. +Vous pouvez donc aussi utiliser toutes les fonctionnalités de [Starlette](https://starlette.dev/) avec `FastAPI`. /// diff --git a/docs/fr/docs/tutorial/frontend.md b/docs/fr/docs/tutorial/frontend.md index 43a1366..fdfa8b1 100644 --- a/docs/fr/docs/tutorial/frontend.md +++ b/docs/fr/docs/tutorial/frontend.md @@ -52,7 +52,7 @@ Pour cela, utilisez `fallback="index.html"` : {* ../../docs_src/frontend/tutorial002_py310.py hl[5] *} -**FastAPI** utilise ce fallback uniquement pour les requêtes `GET` et `HEAD` qui ressemblent à une navigation de navigateur. Les fichiers manquants comme JavaScript, CSS et les images renvoient toujours `404`. +**FastAPI** utilise ce fallback uniquement pour les requêtes `GET` et `HEAD` qui acceptent explicitement HTML avec `Accept: text/html` ou `Accept: application/xhtml+xml`, comme le font normalement les requêtes de navigation de navigateur. Les fichiers manquants comme JavaScript, CSS et les images renvoient toujours `404`. Les requêtes avec d'autres méthodes, comme `POST` ou `PUT`, vers des chemins qui ne correspondent qu'au fallback frontend renvoient également `404`. Les *chemins d'accès* **FastAPI** réguliers ont toujours une priorité plus élevée que les routes frontend. @@ -106,15 +106,19 @@ Les chemins frontend manquants renvoient alors le `404` normal. ## Vérifier le répertoire { #check-directory } -Par défaut, `app.frontend()` vérifie que le répertoire existe lorsque l'application est créée. +Par défaut, `app.frontend()` utilise `check_dir="auto"`. -Cela permet de détecter tôt les erreurs de configuration. Par exemple, si le répertoire de sortie du build frontend est manquant, **FastAPI** lèvera une erreur au démarrage. +Lorsque la variable d'environnement `FASTAPI_ENV` est définie sur `development`, **FastAPI** affiche seulement un avertissement si le répertoire de sortie du build frontend est manquant. La [commande `fastapi dev`](https://github.com/fastapi/fastapi-cli#fastapi-dev) définit cette variable d'environnement pour vous si elle n'est pas déjà définie. Cela vous permet de démarrer le backend avant de build ou de démarrer le frontend pendant le développement. + +Dans tout autre environnement, **FastAPI** lève une erreur lorsque l'application est créée. Cela aide à détecter tôt les erreurs de configuration avant de déployer une application sans ses fichiers frontend. + +Vous pouvez également définir `check_dir=True` pour toujours vérifier le répertoire lorsque l'application est créée. Si vos fichiers frontend sont créés plus tard, par exemple par une étape de build séparée après la création de l'objet app, définissez `check_dir=False` : {* ../../docs_src/frontend/tutorial006_py310.py hl[5] *} -Avec `check_dir=False`, **FastAPI** ne vérifiera pas le répertoire lorsque l'application est créée. Si le répertoire configuré est toujours manquant lorsqu'une requête est traitée, **FastAPI** lèvera alors une erreur. +Avec `check_dir=False`, **FastAPI** ne vérifie pas le répertoire lorsque l'application est créée. Si le répertoire configuré est toujours manquant lorsqu'une requête est traitée, **FastAPI** lèvera alors une erreur. ## L'utiliser avec `APIRouter` { #use-it-with-apirouter } @@ -132,6 +136,8 @@ Les réponses frontend s'exécutent au sein de l'application **FastAPI** normale Les dépendances de l'application, d'un `APIRouter` et de `include_router()` s'appliquent également aux réponses frontend. Cela peut être utile pour protéger un frontend avec une authentification par cookie ou similaire. +Les dépendances peuvent également modifier les headers de réponse et ajouter des tâches d'arrière-plan, comme avec les *chemins d'accès* normaux. + ## Sortie de build statique uniquement { #static-build-output-only } `app.frontend()` sert des fichiers déjà générés par votre build frontend. diff --git a/docs/fr/docs/tutorial/handling-errors.md b/docs/fr/docs/tutorial/handling-errors.md index 5c52e7b..425d4b3 100644 --- a/docs/fr/docs/tutorial/handling-errors.md +++ b/docs/fr/docs/tutorial/handling-errors.md @@ -33,7 +33,7 @@ Pour renvoyer au client des réponses HTTP avec des erreurs, vous utilisez `HTTP Comme il s'agit d'une exception Python, vous ne la `return` pas, vous la `raise`. -Cela signifie aussi que si vous êtes dans une fonction utilitaire appelée depuis votre fonction de chemin d'accès, et que vous levez la `HTTPException` à l'intérieur de cette fonction utilitaire, le reste du code de la fonction de chemin d'accès ne s'exécutera pas : la requête sera immédiatement interrompue et l'erreur HTTP issue de la `HTTPException` sera envoyée au client. +Cela signifie aussi que si vous êtes dans une fonction utilitaire appelée depuis votre *fonction de chemin d'accès*, et que vous levez la `HTTPException` à l'intérieur de cette fonction utilitaire, le reste du code de la *fonction de chemin d'accès* ne s'exécutera pas : la requête sera immédiatement interrompue et l'erreur HTTP issue de la `HTTPException` sera envoyée au client. L'avantage de lever une exception plutôt que de retourner une valeur apparaîtra plus clairement dans la section sur les Dépendances et la Sécurité. @@ -81,7 +81,7 @@ Mais si vous en aviez besoin pour un scénario avancé, vous pouvez ajouter des ## Installer des gestionnaires d'exception personnalisés { #install-custom-exception-handlers } -Vous pouvez ajouter des gestionnaires d'exception personnalisés avec [les mêmes utilitaires d'exception de Starlette](https://www.starlette.dev/exceptions/). +Vous pouvez ajouter des gestionnaires d'exception personnalisés avec [les mêmes utilitaires d'exception de Starlette](https://starlette.dev/exceptions/). Supposons que vous ayez une exception personnalisée `UnicornException` que vous (ou une bibliothèque que vous utilisez) pourriez `raise`. @@ -91,7 +91,7 @@ Vous pouvez ajouter un gestionnaire d'exception personnalisé avec `@app.excepti {* ../../docs_src/handling_errors/tutorial003_py310.py hl[5:7,13:18,24] *} -Ici, si vous appelez `/unicorns/yolo`, le chemin d'accès va `raise` une `UnicornException`. +Ici, si vous appelez `/unicorns/yolo`, le *chemin d'accès* va `raise` une `UnicornException`. Mais elle sera gérée par `unicorn_exception_handler`. diff --git a/docs/fr/docs/tutorial/index.md b/docs/fr/docs/tutorial/index.md index 1e28cfc..69523aa 100644 --- a/docs/fr/docs/tutorial/index.md +++ b/docs/fr/docs/tutorial/index.md @@ -11,12 +11,12 @@ Il est également conçu pour servir de référence ultérieure, afin que vous p Tous les blocs de code peuvent être copiés et utilisés directement (il s'agit en fait de fichiers Python testés). -Pour exécuter l'un de ces exemples, copiez le code dans un fichier `main.py`, et démarrez `fastapi dev` : +Pour exécuter l'un de ces exemples, copiez le code dans un fichier `main.py`, et démarrez `fastapi dev` avec `uv run` :
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -61,35 +61,75 @@ L'utiliser dans votre éditeur est ce qui vous montre vraiment les avantages de ## Installer FastAPI { #install-fastapi } -La première étape consiste à installer FastAPI. +La première étape consiste à configurer votre projet et à ajouter FastAPI. -Assurez-vous de créer un [environnement virtuel](../virtual-environments.md), de l'activer, puis **d'installer FastAPI** : +Installez [`uv`](https://docs.astral.sh/uv/getting-started/installation/), puis créez un projet et ajoutez FastAPI :
```console -$ pip install "fastapi[standard]" +$ uv init awesome-project --bare +$ cd awesome-project +$ uv add "fastapi[standard]" ---> 100% ```
+`uv add` crée l'environnement virtuel du projet dans `.venv`, ajoute FastAPI à `pyproject.toml`, et crée `uv.lock` afin que les mêmes versions de packages puissent être installées plus tard. + +/// details | Ce que font ces commandes + +* `uv init` : crée un nouveau projet Python. +* `awesome-project` : crée le projet dans un nouveau répertoire portant ce nom. +* `--bare` : crée uniquement le fichier `pyproject.toml` minimal, sans générer d'exemple `main.py`, `README.md` ou d'autres fichiers. Vous créerez vous-même les fichiers de l'application dans les prochaines étapes de ce tutoriel. + +Ensuite, `cd awesome-project` entre dans le nouveau répertoire du projet avant d'ajouter FastAPI. + +`uv` utilisera une version compatible de Python déjà installée sur votre système, ou en téléchargera une si nécessaire. + +Lorsque vous exécutez `uv add`, il sélectionne des versions compatibles de FastAPI et de tous les packages dont FastAPI dépend. Il enregistre les versions exactes dans `uv.lock`, ce qui permet d'installer les mêmes versions de packages plus tard sur un autre ordinateur ou lors du déploiement de l'application. + +La création ou la mise à jour de ce fichier est appelée [**verrouillage** des dépendances du projet](https://docs.astral.sh/uv/concepts/projects/sync/). `uv` le fait automatiquement lorsque vous ajoutez un package. + +/// + +/// details | Options d'installation de FastAPI + +Lorsque vous installez avec `uv add "fastapi[standard]"`, cela inclut des dépendances standards optionnelles par défaut, y compris `fastapi-cloud-cli`, qui vous permet de déployer sur [FastAPI Cloud](https://fastapicloud.com). + +Si vous ne souhaitez pas avoir ces dépendances optionnelles, vous pouvez à la place installer `uv add fastapi`. + +Si vous souhaitez installer les dépendances standard mais sans `fastapi-cloud-cli`, vous pouvez installer avec `uv add "fastapi[standard-no-fastapi-cloud-cli]"`. + +/// + +/// details | Utiliser `pip` à la place + +Si vous préférez gérer manuellement un environnement virtuel et les packages, créez et activez un environnement virtuel, puis installez FastAPI avec `pip install "fastapi[standard]"`. + +Lisez le [guide sur les environnements virtuels](https://tiangolo.com/guides/virtual-environments/) pour les étapes détaillées. + +/// + +## Skills des agents IA { #ai-agent-skills } + +FastAPI inclut une skill officielle pour les agents de codage IA. Elle est fournie avec le package, donc ses indications restent alignées avec la version de FastAPI installée dans votre projet et se mettent à jour lorsque vous mettez à niveau FastAPI. + +Après avoir installé FastAPI dans votre projet, vous pouvez installer la skill avec Library Skills : + +```bash +uvx library-skills +``` + /// note | Remarque -Lorsque vous installez avec `pip install "fastapi[standard]"`, cela inclut des dépendances standards optionnelles par défaut, y compris `fastapi-cloud-cli`, qui vous permet de déployer sur [FastAPI Cloud](https://fastapicloud.com). - -Si vous ne souhaitez pas avoir ces dépendances optionnelles, vous pouvez à la place installer `pip install fastapi`. - -Si vous souhaitez installer les dépendances standard mais sans `fastapi-cloud-cli`, vous pouvez installer avec `pip install "fastapi[standard-no-fastapi-cloud-cli]"`. +`uvx` est un alias pour `uv tool run`. Il exécute Library Skills dans un environnement temporaire et isolé pendant que Library Skills analyse les packages installés dans votre projet. /// -/// tip | Astuce - -FastAPI dispose d'une [extension officielle pour VS Code](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (et Cursor), qui fournit de nombreuses fonctionnalités, notamment un explorateur de chemins d'accès, une recherche de chemins d'accès, la navigation CodeLens dans les tests (aller à la définition depuis les tests), ainsi que le déploiement et les journaux FastAPI Cloud, le tout depuis votre éditeur. - -/// +La skill est compatible avec Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Pi, OpenCode, et la plupart des autres agents de codage. Pour Claude Code, sélectionnez `.claude/skills` lorsqu'il vous est demandé où installer la skill. ## Guide d'utilisation avancé { #advanced-user-guide } diff --git a/docs/fr/docs/tutorial/middleware.md b/docs/fr/docs/tutorial/middleware.md index 860b804..541fd6f 100644 --- a/docs/fr/docs/tutorial/middleware.md +++ b/docs/fr/docs/tutorial/middleware.md @@ -37,7 +37,7 @@ La fonction de middleware reçoit : Gardez à l’esprit que des en-têtes propriétaires personnalisés peuvent être ajoutés [en utilisant le préfixe `X-`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). -Mais si vous avez des en-têtes personnalisés que vous voulez rendre visibles pour un client dans un navigateur, vous devez les ajouter à votre configuration CORS ([CORS (Partage des ressources entre origines)](cors.md)) en utilisant le paramètre `expose_headers` documenté dans [la documentation CORS de Starlette](https://www.starlette.dev/middleware/#corsmiddleware). +Mais si vous avez des en-têtes personnalisés que vous voulez rendre visibles pour un client dans un navigateur, vous devez les ajouter à votre configuration CORS ([CORS (Partage des ressources entre origines)](cors.md)) en utilisant le paramètre `expose_headers` documenté dans [la documentation CORS de Starlette](https://starlette.dev/middleware/#corsmiddleware). /// @@ -67,9 +67,9 @@ Ici, nous utilisons [`time.perf_counter()`](https://docs.python.org/3/library/ti ## Ordre d’exécution de plusieurs middlewares { #multiple-middleware-execution-order } -Quand vous ajoutez plusieurs middlewares en utilisant soit le décorateur `@app.middleware()`, soit la méthode `app.add_middleware()`, chaque nouveau middleware enveloppe l’application, formant une pile. Le dernier middleware ajouté est le plus externe, et le premier est le plus interne. +Quand vous ajoutez plusieurs middlewares en utilisant soit le décorateur `@app.middleware()`, soit la méthode `app.add_middleware()`, chaque nouveau middleware enveloppe l’application, formant une pile. Le dernier middleware ajouté est le *plus externe*, et le premier est le *plus interne*. -Sur le chemin de la requête, le plus externe s’exécute en premier. +Sur le chemin de la requête, le *plus externe* s’exécute en premier. Sur le chemin de la réponse, il s’exécute en dernier. @@ -90,6 +90,6 @@ Ce comportement d’empilement garantit que les middlewares s’exécutent dans ## Autres middlewares { #other-middlewares } -Vous pouvez en lire davantage sur d’autres middlewares dans le [Guide de l’utilisateur avancé : Middleware avancé](../advanced/middleware.md). +Vous pouvez plus tard en lire davantage sur d’autres middlewares dans le [Guide de l’utilisateur avancé : Middleware avancé](../advanced/middleware.md). Vous verrez comment gérer CORS avec un middleware dans la section suivante. diff --git a/docs/fr/docs/tutorial/path-params.md b/docs/fr/docs/tutorial/path-params.md index e8d20bb..7824ce7 100644 --- a/docs/fr/docs/tutorial/path-params.md +++ b/docs/fr/docs/tutorial/path-params.md @@ -36,7 +36,7 @@ Si vous exécutez cet exemple et ouvrez votre navigateur sur [http://127.0.0.1:8 /// tip | Astuce -Remarquez que la valeur reçue par votre fonction (et renvoyée) est `3`, en tant qu'entier (`int`) Python, pas la chaîne de caractères « 3 ». +Remarquez que la valeur reçue par votre fonction (et renvoyée) est `3`, en tant qu'entier (`int`) Python, pas une chaîne de caractères `"3"`. Ainsi, avec cette déclaration de type, **FastAPI** vous fournit automatiquement le « parsing » de la requête. @@ -62,7 +62,7 @@ Mais si vous allez dans le navigateur sur [http://127.0.0.1:8000/items/foo](http } ``` -car le paramètre de chemin `item_id` a pour valeur « foo », qui n'est pas un `int`. +car le paramètre de chemin `item_id` a pour valeur `"foo"`, qui n'est pas un `int`. La même erreur apparaîtrait si vous fournissiez un `float` au lieu d'un `int`, comme ici : [http://127.0.0.1:8000/items/4.2](http://127.0.0.1:8000/items/4.2) @@ -92,7 +92,7 @@ Remarquez que le paramètre de chemin est déclaré comme entier. ## Les avantages d'une norme, documentation alternative { #standards-based-benefits-alternative-documentation } -Et comme le schéma généré suit la norme [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md), il existe de nombreux outils compatibles. +Et comme le schéma généré suit la norme [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md), il existe de nombreux outils compatibles. Grâce à cela, **FastAPI** fournit lui-même une documentation d'API alternative (utilisant ReDoc), accessible sur [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) : @@ -102,7 +102,7 @@ De la même façon, il existe de nombreux outils compatibles, y compris des outi ## Pydantic { #pydantic } -Toute la validation de données est effectuée sous le capot par [Pydantic](https://docs.pydantic.dev/), vous en bénéficiez donc pleinement. Vous savez ainsi que vous êtes entre de bonnes mains. +Toute la validation de données est effectuée sous le capot par [Pydantic](https://pydantic.dev/docs/), vous en bénéficiez donc pleinement. Vous savez ainsi que vous êtes entre de bonnes mains. Vous pouvez utiliser les mêmes déclarations de type avec `str`, `float`, `bool` et de nombreux autres types de données complexes. @@ -120,7 +120,7 @@ Comme les *chemins d'accès* sont évalués dans l'ordre, vous devez vous assure {* ../../docs_src/path_params/tutorial003_py310.py hl[6,11] *} -Sinon, le chemin `/users/{user_id}` correspondrait aussi à `/users/me`, « pensant » qu'il reçoit un paramètre `user_id` avec la valeur « me ». +Sinon, le chemin `/users/{user_id}` correspondrait aussi à `/users/me`, « pensant » qu'il reçoit un paramètre `user_id` avec la valeur `"me"`. De même, vous ne pouvez pas redéfinir un chemin d'accès : @@ -154,7 +154,7 @@ Créez ensuite un *paramètre de chemin* avec une annotation de type utilisant l {* ../../docs_src/path_params/tutorial005_py310.py hl[16] *} -### Consulter la documentation { #check-the-docs } +### Consultez les documents { #check-the-docs } Comme les valeurs disponibles pour le *paramètre de chemin* sont prédéfinies, la documentation interactive peut les afficher clairement : @@ -178,7 +178,7 @@ Vous pouvez obtenir la valeur réelle (une `str` dans ce cas) avec `model_name.v /// tip | Astuce -Vous pouvez aussi accéder à la valeur « lenet » avec `ModelName.lenet.value`. +Vous pouvez aussi accéder à la valeur `"lenet"` avec `ModelName.lenet.value`. /// @@ -205,7 +205,7 @@ Disons que vous avez un *chemin d'accès* avec un chemin `/files/{file_path}`. Mais vous avez besoin que `file_path` lui-même contienne un *chemin*, comme `home/johndoe/myfile.txt`. -Ainsi, l'URL pour ce fichier serait : `/files/home/johndoe/myfile.txt`. +Ainsi, l'URL pour ce fichier serait quelque chose comme : `/files/home/johndoe/myfile.txt`. ### Support d'OpenAPI { #openapi-support } @@ -244,7 +244,7 @@ Avec **FastAPI**, en utilisant des déclarations de type Python courtes, intuiti * Support de l'éditeur : vérifications d'erreurs, autocomplétion, etc. * Données « parsing » * Validation de données -* Annotations d'API et documentation automatique +* Annotation d'API et documentation automatique Et vous n'avez besoin de les déclarer qu'une seule fois. diff --git a/docs/fr/docs/tutorial/query-params-str-validations.md b/docs/fr/docs/tutorial/query-params-str-validations.md index 1b0fa88..0b36267 100644 --- a/docs/fr/docs/tutorial/query-params-str-validations.md +++ b/docs/fr/docs/tutorial/query-params-str-validations.md @@ -133,7 +133,7 @@ Par exemple, ceci n’est pas autorisé : q: Annotated[str, Query(default="rick")] = "morty" ``` -... parce qu’il n’est pas clair si la valeur par défaut doit être « rick » ou « morty ». +... parce qu’il n’est pas clair si la valeur par défaut doit être `"rick"` ou `"morty"`. Donc, vous utiliseriez (de préférence) : @@ -185,7 +185,7 @@ Désormais, vous savez que, lorsque vous en aurez besoin, vous pourrez les utili Vous pouvez, bien sûr, utiliser des valeurs par défaut autres que `None`. -Disons que vous voulez déclarer le paramètre de requête `q` avec un `min_length` de `3`, et avec une valeur par défaut de « fixedquery » : +Disons que vous voulez déclarer le paramètre de requête `q` avec un `min_length` de `3`, et avec une valeur par défaut de `"fixedquery"` : {* ../../docs_src/query_params_str_validations/tutorial005_an_py310.py hl[9] *} @@ -369,15 +369,15 @@ Il peut y avoir des cas où vous devez faire une **validation personnalisée** q Dans ces cas, vous pouvez utiliser une **fonction de validation personnalisée** qui est appliquée après la validation normale (par ex. après avoir validé que la valeur est une `str`). -Vous pouvez y parvenir en utilisant [`AfterValidator` de Pydantic](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator) à l’intérieur de `Annotated`. +Vous pouvez y parvenir en utilisant [`AfterValidator` de Pydantic](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-after-validator) à l’intérieur de `Annotated`. /// tip | Astuce -Pydantic a aussi [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator) et d’autres. 🤓 +Pydantic a aussi [`BeforeValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-before-validator) et d’autres. 🤓 /// -Par exemple, ce validateur personnalisé vérifie que l’ID d’item commence par `isbn-` pour un numéro de livre ISBN ou par `imdb-` pour un ID d’URL de film IMDB : +Par exemple, ce validateur personnalisé vérifie que l’ID d’item commence par `isbn-` pour un numéro de livre ISBN ou par `imdb-` pour un ID d’URL de film IMDB : {* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *} diff --git a/docs/fr/docs/tutorial/request-files.md b/docs/fr/docs/tutorial/request-files.md index 79b28d7..8b4748a 100644 --- a/docs/fr/docs/tutorial/request-files.md +++ b/docs/fr/docs/tutorial/request-files.md @@ -7,10 +7,10 @@ Vous pouvez définir des fichiers à téléverser par le client en utilisant `Fi Pour recevoir des fichiers téléversés, installez d'abord [`python-multipart`](https://github.com/Kludex/python-multipart). -Assurez-vous de créer un [environnement virtuel](../virtual-environments.md), de l'activer, puis d'installer le paquet, par exemple : +Ajoutez-le à votre projet : ```console -$ pip install python-multipart +$ uv add python-multipart ``` C'est parce que les fichiers téléversés sont envoyés en « données de formulaire ». @@ -174,4 +174,4 @@ Et de la même manière que précédemment, vous pouvez utiliser `File()` pour d ## Récapitulatif { #recap } -Utilisez `File`, `bytes` et `UploadFile` pour déclarer des fichiers à téléverser dans la requête, envoyés en « données de formulaire ». +Utilisez `File`, `bytes` et `UploadFile` pour déclarer des fichiers à téléverser dans la requête, envoyés en données de formulaire. diff --git a/docs/fr/docs/tutorial/request-form-models.md b/docs/fr/docs/tutorial/request-form-models.md index ae1da24..bfa21b5 100644 --- a/docs/fr/docs/tutorial/request-form-models.md +++ b/docs/fr/docs/tutorial/request-form-models.md @@ -6,10 +6,10 @@ Vous pouvez utiliser des **modèles Pydantic** pour déclarer des **champs de fo Pour utiliser les formulaires, installez d'abord [`python-multipart`](https://github.com/Kludex/python-multipart). -Assurez-vous de créer un [environnement virtuel](../virtual-environments.md), de l'activer, puis d'installer le paquet, par exemple : +Ajoutez-le à votre projet : ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// @@ -38,7 +38,7 @@ Vous pouvez le vérifier dans l'interface des documents à `/docs` : ## Interdire les champs de formulaire supplémentaires { #forbid-extra-form-fields } -Dans certains cas d'utilisation particuliers (probablement peu courants), vous pourriez vouloir **restreindre** les champs de formulaire à ceux déclarés dans le modèle Pydantic, et **interdire** tout champ **supplémentaire**. +Dans certains cas d'utilisation particuliers (probablement peu courants), vous pourriez vouloir **restreindre** les champs de formulaire à ceux déclarés dans le modèle Pydantic. Et **interdire** tout champ **supplémentaire**. /// note | Remarque diff --git a/docs/fr/docs/tutorial/request-forms-and-files.md b/docs/fr/docs/tutorial/request-forms-and-files.md index 4b930de..52a03b6 100644 --- a/docs/fr/docs/tutorial/request-forms-and-files.md +++ b/docs/fr/docs/tutorial/request-forms-and-files.md @@ -6,10 +6,10 @@ Vous pouvez définir des fichiers et des champs de formulaire en même temps à Pour recevoir des fichiers téléversés et/ou des données de formulaire, installez d'abord [`python-multipart`](https://github.com/Kludex/python-multipart). -Vous devez créer un [environnement virtuel](../virtual-environments.md), l'activer, puis installer ce paquet, par exemple : +Ajoutez-le à votre projet : ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// @@ -24,7 +24,7 @@ Créez des paramètres de fichier et de formulaire de la même manière que pour {* ../../docs_src/request_forms_and_files/tutorial001_an_py310.py hl[10:12] *} -Les fichiers et les champs de formulaire seront téléversés en tant que données de formulaire et vous les recevrez. +Les fichiers et les champs de formulaire seront téléversés en tant que données de formulaire et vous recevrez les fichiers et les champs de formulaire. Et vous pouvez déclarer certains fichiers comme `bytes` et d'autres comme `UploadFile`. diff --git a/docs/fr/docs/tutorial/request-forms.md b/docs/fr/docs/tutorial/request-forms.md index 442d505..77b0566 100644 --- a/docs/fr/docs/tutorial/request-forms.md +++ b/docs/fr/docs/tutorial/request-forms.md @@ -6,10 +6,10 @@ Lorsque vous devez recevoir des champs de formulaire au lieu de JSON, vous pouve Pour utiliser les formulaires, installez d'abord [`python-multipart`](https://github.com/Kludex/python-multipart). -Vous devez créer un [environnement virtuel](../virtual-environments.md), l'activer, puis installer le paquet, par exemple : +Ajoutez-le à votre projet : ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/fr/docs/tutorial/response-model.md b/docs/fr/docs/tutorial/response-model.md index 322b170..3e306a7 100644 --- a/docs/fr/docs/tutorial/response-model.md +++ b/docs/fr/docs/tutorial/response-model.md @@ -76,16 +76,16 @@ Ici, nous déclarons un modèle `UserIn`, il contiendra un mot de passe en clair Pour utiliser `EmailStr`, installez d'abord [`email-validator`](https://github.com/JoshData/python-email-validator). -Assurez-vous de créer un [environnement virtuel](../virtual-environments.md), de l'activer, puis de l'installer, par exemple : +Ajoutez-le à votre projet : ```console -$ pip install email-validator +$ uv add email-validator ``` ou avec : ```console -$ pip install "pydantic[email]" +$ uv add "pydantic[email]" ``` /// @@ -258,7 +258,7 @@ Vous pouvez également utiliser : * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -comme décrit dans [la documentation Pydantic](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict) pour `exclude_defaults` et `exclude_none`. +comme décrit dans [les documents Pydantic](https://pydantic.dev/docs/validation/latest/concepts/serialization/#excluding-and-including-fields-based-on-their-value) pour `exclude_defaults` et `exclude_none`. /// diff --git a/docs/fr/docs/tutorial/schema-extra-example.md b/docs/fr/docs/tutorial/schema-extra-example.md index 85905f5..463123b 100644 --- a/docs/fr/docs/tutorial/schema-extra-example.md +++ b/docs/fr/docs/tutorial/schema-extra-example.md @@ -12,7 +12,7 @@ Vous pouvez déclarer `examples` pour un modèle Pydantic qui seront ajoutés au Ces informations supplémentaires seront ajoutées telles quelles au **JSON Schema** de sortie pour ce modèle, et elles seront utilisées dans les documents de l'API. -Vous pouvez utiliser l'attribut `model_config` qui accepte un `dict` comme décrit dans [documents de Pydantic : Configuration](https://docs.pydantic.dev/latest/api/config/). +Vous pouvez utiliser l'attribut `model_config` qui accepte un `dict` comme décrit dans [documents de Pydantic : Configuration](https://pydantic.dev/docs/validation/latest/api/pydantic/config/). Vous pouvez définir `"json_schema_extra"` avec un `dict` contenant toutes les données supplémentaires que vous souhaitez voir apparaître dans le JSON Schema généré, y compris `examples`. diff --git a/docs/fr/docs/tutorial/security/first-steps.md b/docs/fr/docs/tutorial/security/first-steps.md index 66005d9..5005774 100644 --- a/docs/fr/docs/tutorial/security/first-steps.md +++ b/docs/fr/docs/tutorial/security/first-steps.md @@ -26,26 +26,26 @@ Copiez l'exemple dans un fichier `main.py` : /// note | Remarque -Le package [`python-multipart`](https://github.com/Kludex/python-multipart) est installé automatiquement avec **FastAPI** lorsque vous exécutez la commande `pip install "fastapi[standard]"`. +Le package [`python-multipart`](https://github.com/Kludex/python-multipart) est installé automatiquement avec **FastAPI** lorsque vous exécutez la commande `uv add "fastapi[standard]"`. -Cependant, si vous utilisez la commande `pip install fastapi`, le package `python-multipart` n'est pas inclus par défaut. +Cependant, si vous utilisez la commande `uv add fastapi`, le package `python-multipart` n'est pas inclus par défaut. -Pour l'installer manuellement, vous devez vous assurer de créer un [environnement virtuel](../../virtual-environments.md), de l'activer, puis de l'installer avec : +Pour l'installer manuellement, ajoutez-le à votre projet avec : ```console -$ pip install python-multipart +$ uv add python-multipart ``` Cela est dû au fait que **OAuth2** utilise des « form data » pour envoyer le `username` et le `password`. /// -Exécutez l'exemple avec : +Exécutez l'exemple avec :
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -54,9 +54,9 @@ $ fastapi dev ## Vérifier { #check-it } -Allez aux documents interactifs à l'adresse : [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). +Allez aux documents interactifs à l'adresse : [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). -Vous verrez quelque chose comme ceci : +Vous verrez quelque chose comme ceci : @@ -68,7 +68,7 @@ Et votre *chemin d'accès* a un petit cadenas dans le coin supérieur droit sur /// -Et si vous cliquez dessus, vous obtenez un petit formulaire d'autorisation pour saisir un `username` et un `password` (et d'autres champs optionnels) : +Et si vous cliquez dessus, vous obtenez un petit formulaire d'autorisation pour saisir un `username` et un `password` (et d'autres champs optionnels) : @@ -96,7 +96,7 @@ OAuth2 a été conçu pour que le backend ou l'API puisse être indépendant du Mais dans ce cas, la même application **FastAPI** gérera l'API et l'authentification. -Voyons cela selon ce point de vue simplifié : +Voyons cela selon ce point de vue simplifié : * L'utilisateur saisit le `username` et le `password` dans le frontend, puis appuie sur Entrée. * Le frontend (exécuté dans le navigateur de l'utilisateur) envoie ce `username` et ce `password` vers une URL spécifique de notre API (déclarée avec `tokenUrl="token"`). @@ -110,7 +110,7 @@ Voyons cela selon ce point de vue simplifié : * Le frontend doit récupérer d'autres données depuis l'API. * Mais cela nécessite une authentification pour cet endpoint spécifique. * Donc, pour s'authentifier auprès de notre API, il envoie un en-tête `Authorization` avec une valeur `Bearer ` suivie du token. - * Si le token contient `foobar`, le contenu de l'en-tête `Authorization` serait : `Bearer foobar`. + * Si le token contient `foobar`, le contenu de l'en-tête `Authorization` serait : `Bearer foobar`. ## Le `OAuth2PasswordBearer` de **FastAPI** { #fastapis-oauth2passwordbearer } @@ -158,7 +158,7 @@ C'est parce qu'il utilise le même nom que dans la spécification OpenAPI. Ainsi La variable `oauth2_scheme` est une instance de `OAuth2PasswordBearer`, mais c'est aussi un « callable ». -Elle pourrait être appelée ainsi : +Elle pourrait être appelée ainsi : ```Python oauth2_scheme(some, parameters) @@ -192,7 +192,7 @@ S'il ne voit pas d'en-tête `Authorization`, ou si la valeur n'a pas de token `B Vous n'avez même pas à vérifier si le token existe pour renvoyer une erreur. Vous pouvez être sûr que si votre fonction est exécutée, elle aura une `str` dans ce token. -Vous pouvez déjà l'essayer dans les documents interactifs : +Vous pouvez déjà l'essayer dans les documents interactifs : diff --git a/docs/fr/docs/tutorial/security/oauth2-jwt.md b/docs/fr/docs/tutorial/security/oauth2-jwt.md index f92fd75..87f8b2c 100644 --- a/docs/fr/docs/tutorial/security/oauth2-jwt.md +++ b/docs/fr/docs/tutorial/security/oauth2-jwt.md @@ -30,12 +30,12 @@ Si vous voulez expérimenter avec des jetons JWT et voir comment ils fonctionnen Nous devons installer `PyJWT` pour générer et vérifier les jetons JWT en Python. -Assurez-vous de créer un [environnement virtuel](../../virtual-environments.md), de l'activer, puis d'installer `pyjwt` : +Ajoutez `pyjwt` à votre projet :
```console -$ pip install pyjwt +$ uv add pyjwt ---> 100% ``` @@ -72,12 +72,12 @@ Il prend en charge de nombreux algorithmes de hachage sécurisés et des utilita L'algorithme recommandé est « Argon2 ». -Assurez-vous de créer un [environnement virtuel](../../virtual-environments.md), de l'activer, puis d'installer pwdlib avec Argon2 : +Ajoutez `pwdlib` avec Argon2 à votre projet :
```console -$ pip install "pwdlib[argon2]" +$ uv add "pwdlib[argon2]" ---> 100% ``` diff --git a/docs/fr/docs/tutorial/sql-databases.md b/docs/fr/docs/tutorial/sql-databases.md index 2f6aad3..d232c1c 100644 --- a/docs/fr/docs/tutorial/sql-databases.md +++ b/docs/fr/docs/tutorial/sql-databases.md @@ -34,12 +34,12 @@ Il s'agit d'un tutoriel très simple et court ; si vous souhaitez apprendre sur ## Installer `SQLModel` { #install-sqlmodel } -D'abord, assurez-vous de créer votre [environnement virtuel](../virtual-environments.md), de l'activer, puis d'installer `sqlmodel` : +Ajoutez `sqlmodel` à votre projet :
```console -$ pip install sqlmodel +$ uv add sqlmodel ---> 100% ``` @@ -152,7 +152,7 @@ Vous pouvez exécuter l'application :
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -337,7 +337,7 @@ Vous pouvez exécuter l'application à nouveau :
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -352,6 +352,6 @@ Si vous allez sur l'UI `/docs` de l'API, vous verrez qu'elle est maintenant à j ## Récapitulatif { #recap } -Vous pouvez utiliser [**SQLModel**](https://sqlmodel.tiangolo.com/) pour interagir avec une base SQL et simplifier le code avec des *modèles de données* et des *modèles de table*. +Vous pouvez utiliser [**SQLModel**](https://sqlmodel.tiangolo.com/) pour interagir avec une base SQL et simplifier le code avec des *modèles de données* et des *modèles de table*. Vous pouvez en apprendre beaucoup plus dans les documents de **SQLModel**, il y a un mini [tutoriel plus long sur l'utilisation de SQLModel avec **FastAPI**](https://sqlmodel.tiangolo.com/tutorial/fastapi/). 🚀 diff --git a/docs/fr/docs/tutorial/static-files.md b/docs/fr/docs/tutorial/static-files.md index cfbbe86..a4a8188 100644 --- a/docs/fr/docs/tutorial/static-files.md +++ b/docs/fr/docs/tutorial/static-files.md @@ -12,8 +12,8 @@ Si vous devez héberger un frontend, utilisez plutôt `app.frontend()`, lisez-en ## Utiliser `StaticFiles` { #use-staticfiles } -- Importer `StaticFiles`. -- « Mount » une instance `StaticFiles()` sur un chemin spécifique. +* Importer `StaticFiles`. +* « Mount » une instance `StaticFiles()` sur un chemin spécifique. {* ../../docs_src/static_files/tutorial001_py310.py hl[2,6] *} @@ -45,4 +45,4 @@ Tous ces paramètres peuvent être différents de « `static` », adaptez-les au ## Plus d'informations { #more-info } -Pour plus de détails et d'options, consultez la [documentation de Starlette sur les fichiers statiques](https://www.starlette.dev/staticfiles/). +Pour plus de détails et d'options, consultez la [documentation de Starlette sur les fichiers statiques](https://starlette.dev/staticfiles/). diff --git a/docs/fr/docs/tutorial/testing.md b/docs/fr/docs/tutorial/testing.md index 883a611..dbeec9b 100644 --- a/docs/fr/docs/tutorial/testing.md +++ b/docs/fr/docs/tutorial/testing.md @@ -1,6 +1,6 @@ # Tester { #testing } -Grâce à [Starlette](https://www.starlette.dev/testclient/), tester des applications **FastAPI** est simple et agréable. +Grâce à [Starlette](https://starlette.dev/testclient/), tester des applications **FastAPI** est simple et agréable. C’est basé sur [HTTPX](https://www.python-httpx.org), dont la conception s’inspire de Requests, ce qui le rend très familier et intuitif. @@ -12,10 +12,10 @@ Avec cela, vous pouvez utiliser [pytest](https://docs.pytest.org/) directement a Pour utiliser `TestClient`, installez d’abord [`httpx`](https://www.python-httpx.org). -Vous devez vous assurer de créer un [environnement virtuel](../virtual-environments.md), de l’activer, puis d’y installer le paquet, par exemple : +Ajoutez-le à votre projet : ```console -$ pip install httpx +$ uv add httpx ``` /// @@ -95,7 +95,7 @@ Comme ce fichier se trouve dans le même package, vous pouvez utiliser des impor {* ../../docs_src/app_testing/app_a_py310/test_main.py hl[3] *} -… et avoir le code des tests comme précédemment. +... et avoir le code des tests comme précédemment. ## Tester : exemple étendu { #testing-extended-example } @@ -119,7 +119,7 @@ Il a une opération `GET` qui pourrait renvoyer une erreur. Il a une opération `POST` qui pourrait renvoyer plusieurs erreurs. -Les deux chemins d’accès requièrent un en-tête `X-Token`. +Les deux *chemins d’accès* requièrent un en-tête `X-Token`. {* ../../docs_src/app_testing/app_b_an_py310/main.py *} @@ -156,12 +156,12 @@ Si vous avez un modèle Pydantic dans votre test et que vous souhaitez envoyer s Après cela, vous avez simplement besoin d’installer `pytest`. -Vous devez vous assurer de créer un [environnement virtuel](../virtual-environments.md), de l’activer, puis d’y installer le paquet, par exemple : +Ajoutez-le à votre projet :
```console -$ pip install pytest +$ uv add pytest ---> 100% ``` @@ -175,7 +175,7 @@ Exécutez les tests avec :
```console -$ pytest +$ uv run pytest ================ test session starts ================ platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1 diff --git a/docs/fr/docs/virtual-environments.md b/docs/fr/docs/virtual-environments.md index f2a9f47..67d8f4b 100644 --- a/docs/fr/docs/virtual-environments.md +++ b/docs/fr/docs/virtual-environments.md @@ -1,864 +1,35 @@ # Environnements virtuels { #virtual-environments } -Lorsque vous travaillez sur des projets Python, vous devriez probablement utiliser un **environnement virtuel** (ou un mécanisme similaire) pour isoler les packages que vous installez pour chaque projet. +Lorsque vous travaillez sur des projets Python, vous devez utiliser un **environnement virtuel** pour isoler les packages installés pour chaque projet. -/// note | Remarque - -Si vous connaissez déjà les environnements virtuels, comment les créer et les utiliser, vous pouvez passer cette section. 🤓 - -/// - -/// tip | Astuce - -Un **environnement virtuel** est différent d’une **variable d’environnement**. - -Une **variable d’environnement** est une variable du système qui peut être utilisée par des programmes. - -Un **environnement virtuel** est un répertoire contenant certains fichiers. - -/// - -/// note | Remarque - -Cette page vous apprendra à utiliser les **environnements virtuels** et à comprendre leur fonctionnement. - -Si vous êtes prêt à adopter un **outil qui gère tout** pour vous (y compris l’installation de Python), essayez [uv](https://github.com/astral-sh/uv). - -/// +Pour les projets FastAPI, je recommande d’utiliser [uv](https://docs.astral.sh/uv/) pour gérer le projet, ses dépendances et son environnement virtuel. ## Créer un projet { #create-a-project } -Commencez par créer un répertoire pour votre projet. - -Ce que je fais généralement, c’est créer un répertoire nommé `code` dans mon répertoire personnel/utilisateur. - -Et à l’intérieur, je crée un répertoire par projet. +Installez `uv` en utilisant le [guide d’installation officiel](https://docs.astral.sh/uv/getting-started/installation/), puis créez un projet :
```console -// Aller au répertoire personnel -$ cd -// Créer un répertoire pour tous vos projets de code -$ mkdir code -// Entrer dans ce répertoire code -$ cd code -// Créer un répertoire pour ce projet -$ mkdir awesome-project -// Entrer dans ce répertoire de projet +$ uv init awesome-project --bare $ cd awesome-project +$ uv add "fastapi[standard]" ```
-## Créer un environnement virtuel { #create-a-virtual-environment } +`uv` crée automatiquement un environnement virtuel pour le projet. Vous n’avez pas besoin d’en créer ou d’en activer un vous-même. -Lorsque vous commencez à travailler sur un projet Python **pour la première fois**, créez un environnement virtuel **dans votre projet**. - -/// tip | Astuce - -Vous n’avez besoin de faire cela qu’**une seule fois par projet**, pas à chaque fois que vous travaillez. - -/// - -//// tab | `venv` - -Pour créer un environnement virtuel, vous pouvez utiliser le module `venv` fourni avec Python. +Exécutez les commandes dans l’environnement du projet avec `uv run`, par exemple :
```console -$ python -m venv .venv +$ uv run fastapi dev ```
-/// details | Que signifie cette commande +## En savoir plus { #learn-more } -* `python` : utiliser le programme nommé `python` -* `-m` : appeler un module comme un script, nous préciserons ensuite quel module -* `venv` : utiliser le module nommé `venv` qui est normalement installé avec Python -* `.venv` : créer l’environnement virtuel dans le nouveau répertoire `.venv` - -/// - -//// - -//// tab | `uv` - -Si vous avez installé [`uv`](https://github.com/astral-sh/uv), vous pouvez l’utiliser pour créer un environnement virtuel. - -
- -```console -$ uv venv -``` - -
- -/// tip | Astuce - -Par défaut, `uv` créera un environnement virtuel dans un répertoire appelé `.venv`. - -Mais vous pouvez le personnaliser en passant un argument supplémentaire avec le nom du répertoire. - -/// - -//// - -Cette commande crée un nouvel environnement virtuel dans un répertoire appelé `.venv`. - -/// details | `.venv` ou autre nom - -Vous pourriez créer l’environnement virtuel dans un autre répertoire, mais il est d’usage de l’appeler `.venv`. - -/// - -## Activer l’environnement virtuel { #activate-the-virtual-environment } - -Activez le nouvel environnement virtuel afin que toute commande Python que vous exécutez ou tout package que vous installez l’utilise. - -/// tip | Astuce - -Faites cela **chaque fois** que vous démarrez une **nouvelle session de terminal** pour travailler sur le projet. - -/// - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Ou si vous utilisez Bash pour Windows (par exemple [Git Bash](https://gitforwindows.org/)) : - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -/// tip | Astuce - -Chaque fois que vous installez un **nouveau package** dans cet environnement, **activez** de nouveau l’environnement. - -Vous vous assurez ainsi que si vous utilisez un **programme de terminal (CLI)** installé par ce package, vous utilisez celui de votre environnement virtuel et non un autre qui pourrait être installé globalement, probablement avec une version différente de celle dont vous avez besoin. - -/// - -## Vérifier que l’environnement virtuel est actif { #check-the-virtual-environment-is-active } - -Vérifiez que l’environnement virtuel est actif (la commande précédente a fonctionné). - -/// tip | Astuce - -C’est **facultatif**, mais c’est une bonne manière de **vérifier** que tout fonctionne comme prévu et que vous utilisez l’environnement virtuel voulu. - -/// - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -S’il affiche le binaire `python` à `.venv/bin/python`, dans votre projet (dans cet exemple `awesome-project`), alors cela a fonctionné. 🎉 - -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -S’il affiche le binaire `python` à `.venv\Scripts\python`, dans votre projet (dans cet exemple `awesome-project`), alors cela a fonctionné. 🎉 - -//// - -## Mettre à niveau `pip` { #upgrade-pip } - -/// tip | Astuce - -Si vous utilisez [`uv`](https://github.com/astral-sh/uv), vous l’utiliserez pour installer des éléments à la place de `pip`, vous n’avez donc pas besoin de mettre `pip` à niveau. 😎 - -/// - -Si vous utilisez `pip` pour installer des packages (il est fourni par défaut avec Python), vous devez le **mettre à niveau** vers la dernière version. - -Beaucoup d’erreurs exotiques lors de l’installation d’un package se résolvent simplement en mettant d’abord `pip` à niveau. - -/// tip | Astuce - -Vous feriez normalement cela **une seule fois**, juste après avoir créé l’environnement virtuel. - -/// - -Vous devez vous assurer que l’environnement virtuel est actif (avec la commande ci-dessus), puis exécuter : - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip | Astuce - -Parfois, vous pourriez obtenir une erreur **`No module named pip`** en essayant de mettre à niveau pip. - -Si cela arrive, installez et mettez à niveau pip avec la commande ci-dessous : - -
- -```console -$ python -m ensurepip --upgrade - ----> 100% -``` - -
- -Cette commande installera pip s’il n’est pas déjà installé et garantit aussi que la version de pip installée est au moins aussi récente que celle disponible dans `ensurepip`. - -/// - -## Ajouter `.gitignore` { #add-gitignore } - -Si vous utilisez **Git** (vous devriez), ajoutez un fichier `.gitignore` pour exclure tout ce qui se trouve dans votre `.venv` de Git. - -/// tip | Astuce - -Si vous avez utilisé [`uv`](https://github.com/astral-sh/uv) pour créer l’environnement virtuel, il l’a déjà fait pour vous, vous pouvez passer cette étape. 😎 - -/// - -/// tip | Astuce - -Faites cela **une seule fois**, juste après avoir créé l’environnement virtuel. - -/// - -
- -```console -$ echo "*" > .venv/.gitignore -``` - -
- -/// details | Que signifie cette commande - -* `echo "*"` : va « afficher » le texte `*` dans le terminal (la partie suivante change un peu cela) -* `>` : tout ce qui est affiché dans le terminal par la commande à gauche de `>` ne doit pas être affiché mais écrit dans le fichier à droite de `>` -* `.gitignore` : le nom du fichier dans lequel le texte doit être écrit - -Et `*` signifie pour Git « tout ». Ainsi, il ignorera tout dans le répertoire `.venv`. - -Cette commande créera un fichier `.gitignore` avec le contenu : - -```gitignore -* -``` - -/// - -## Installer des packages { #install-packages } - -Après avoir activé l’environnement, vous pouvez y installer des packages. - -/// tip | Astuce - -Faites cela **une seule fois** lorsque vous installez ou mettez à niveau les packages nécessaires à votre projet. - -Si vous devez mettre à niveau une version ou ajouter un nouveau package, vous le **referez**. - -/// - -### Installer des packages directement { #install-packages-directly } - -Si vous êtes pressé et ne souhaitez pas utiliser un fichier pour déclarer les dépendances de packages de votre projet, vous pouvez les installer directement. - -/// tip | Astuce - -C’est une (très) bonne idée de placer les packages et leurs versions nécessaires à votre programme dans un fichier (par exemple `requirements.txt` ou `pyproject.toml`). - -/// - -//// tab | `pip` - -
- -```console -$ pip install "fastapi[standard]" - ----> 100% -``` - -
- -//// - -//// tab | `uv` - -Si vous avez [`uv`](https://github.com/astral-sh/uv) : - -
- -```console -$ uv pip install "fastapi[standard]" ----> 100% -``` - -
- -//// - -### Installer depuis `requirements.txt` { #install-from-requirements-txt } - -Si vous avez un `requirements.txt`, vous pouvez maintenant l’utiliser pour installer ses packages. - -//// tab | `pip` - -
- -```console -$ pip install -r requirements.txt ----> 100% -``` - -
- -//// - -//// tab | `uv` - -Si vous avez [`uv`](https://github.com/astral-sh/uv) : - -
- -```console -$ uv pip install -r requirements.txt ----> 100% -``` - -
- -//// - -/// details | `requirements.txt` - -Un `requirements.txt` avec quelques packages pourrait ressembler à : - -```requirements.txt -fastapi[standard]==0.113.0 -pydantic==2.8.0 -``` - -/// - -## Exécuter votre programme { #run-your-program } - -Après avoir activé l’environnement virtuel, vous pouvez exécuter votre programme, et il utilisera le Python de votre environnement virtuel avec les packages que vous y avez installés. - -
- -```console -$ python main.py - -Hello World -``` - -
- -## Configurer votre éditeur { #configure-your-editor } - -Vous utiliserez probablement un éditeur, assurez-vous de le configurer pour utiliser le même environnement virtuel que vous avez créé (il le détectera probablement automatiquement) afin d’avoir l’autocomplétion et les erreurs inline. - -Par exemple : - -* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) -* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) - -/// tip | Astuce - -Vous devez normalement faire cela seulement **une fois**, lorsque vous créez l’environnement virtuel. - -/// - -## Désactiver l’environnement virtuel { #deactivate-the-virtual-environment } - -Une fois que vous avez fini de travailler sur votre projet, vous pouvez **désactiver** l’environnement virtuel. - -
- -```console -$ deactivate -``` - -
- -Ainsi, lorsque vous exécutez `python`, il n’essaiera pas de l’exécuter depuis cet environnement virtuel avec les packages qui y sont installés. - -## Prêt à travailler { #ready-to-work } - -Vous êtes maintenant prêt à commencer à travailler sur votre projet. - - - -/// tip | Astuce - -Voulez-vous comprendre tout ce qui précède ? - -Continuez la lecture. 👇🤓 - -/// - -## Pourquoi des environnements virtuels { #why-virtual-environments } - -Pour travailler avec FastAPI, vous devez installer [Python](https://www.python.org/). - -Ensuite, vous devez **installer** FastAPI et tout autre **package** que vous souhaitez utiliser. - -Pour installer des packages, vous utiliseriez normalement la commande `pip` fournie avec Python (ou des alternatives similaires). - -Néanmoins, si vous utilisez simplement `pip` directement, les packages seraient installés dans votre **environnement Python global** (l’installation globale de Python). - -### Le problème { #the-problem } - -Alors, quel est le problème d’installer des packages dans l’environnement Python global ? - -À un moment donné, vous finirez probablement par écrire de nombreux programmes différents qui dépendent de **packages différents**. Et certains de ces projets sur lesquels vous travaillez dépendront de **versions différentes** du même package. 😱 - -Par exemple, vous pourriez créer un projet appelé `philosophers-stone`, ce programme dépend d’un autre package appelé **`harry`, en version `1`**. Vous devez donc installer `harry`. - -```mermaid -flowchart LR - stone(philosophers-stone) -->|requires| harry-1[harry v1] -``` - -Puis, plus tard, vous créez un autre projet appelé `prisoner-of-azkaban`, et ce projet dépend aussi de `harry`, mais il a besoin de **`harry` en version `3`**. - -```mermaid -flowchart LR - azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3] -``` - -Mais maintenant, le problème est que, si vous installez les packages globalement (dans l’environnement global) au lieu de dans un **environnement virtuel** local, vous devrez choisir quelle version de `harry` installer. - -Si vous voulez exécuter `philosophers-stone`, vous devrez d’abord installer `harry` en version `1`, par exemple avec : - -
- -```console -$ pip install "harry==1" -``` - -
- -Et vous vous retrouverez avec `harry` en version `1` installé dans votre environnement Python global. - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -->|requires| harry-1 - end -``` - -Mais si vous voulez ensuite exécuter `prisoner-of-azkaban`, vous devrez désinstaller `harry` version `1` et installer `harry` version `3` (ou bien installer la version `3` désinstallerait automatiquement la version `1`). - -
- -```console -$ pip install "harry==3" -``` - -
- -Et vous vous retrouverez alors avec `harry` version `3` installé dans votre environnement Python global. - -Et si vous essayez d’exécuter à nouveau `philosophers-stone`, il y a une chance que cela **ne fonctionne pas** car il a besoin de `harry` version `1`. - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - style harry-1 fill:#ccc,stroke-dasharray: 5 5 - harry-3[harry v3] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -.-x|⛔️| harry-1 - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --> |requires| harry-3 - end -``` - -/// tip | Astuce - -Il est très courant que les packages Python fassent de leur mieux pour **éviter les changements cassants** dans les **nouvelles versions**, mais il vaut mieux jouer la sécurité et installer de nouvelles versions intentionnellement et lorsque vous pouvez exécuter les tests pour vérifier que tout fonctionne correctement. - -/// - -Maintenant, imaginez cela avec **beaucoup** d’autres **packages** dont tous vos **projets dépendent**. C’est très difficile à gérer. Et vous finiriez probablement par exécuter certains projets avec des **versions incompatibles** des packages, sans savoir pourquoi quelque chose ne fonctionne pas. - -De plus, selon votre système d’exploitation (par exemple Linux, Windows, macOS), il se peut qu’il soit livré avec Python déjà installé. Et dans ce cas, il avait probablement des packages préinstallés avec des versions spécifiques **nécessaires à votre système**. Si vous installez des packages dans l’environnement Python global, vous pourriez finir par **casser** certains des programmes fournis avec votre système d’exploitation. - -## Où les packages sont-ils installés { #where-are-packages-installed } - -Lorsque vous installez Python, il crée des répertoires avec des fichiers sur votre ordinateur. - -Certains de ces répertoires sont chargés de contenir tous les packages que vous installez. - -Lorsque vous exécutez : - -
- -```console -// Ne l’exécutez pas maintenant, c’est juste un exemple 🤓 -$ pip install "fastapi[standard]" ----> 100% -``` - -
- -Cela téléchargera un fichier compressé avec le code de FastAPI, normalement depuis [PyPI](https://pypi.org/project/fastapi/). - -Il **téléchargera** également des fichiers pour d’autres packages dont FastAPI dépend. - -Ensuite, il **extraira** tous ces fichiers et les placera dans un répertoire de votre ordinateur. - -Par défaut, il placera ces fichiers téléchargés et extraits dans le répertoire fourni avec votre installation de Python, c’est l’**environnement global**. - -## Qu’est-ce qu’un environnement virtuel { #what-are-virtual-environments } - -La solution aux problèmes posés par le fait d’avoir tous les packages dans l’environnement global est d’utiliser un **environnement virtuel pour chaque projet** sur lequel vous travaillez. - -Un environnement virtuel est un **répertoire**, très similaire à celui global, où vous pouvez installer les packages pour un projet. - -De cette manière, chaque projet aura son propre environnement virtuel (répertoire `.venv`) avec ses propres packages. - -```mermaid -flowchart TB - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) --->|requires| harry-1 - subgraph venv1[.venv] - harry-1[harry v1] - end - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --->|requires| harry-3 - subgraph venv2[.venv] - harry-3[harry v3] - end - end - stone-project ~~~ azkaban-project -``` - -## Que signifie activer un environnement virtuel { #what-does-activating-a-virtual-environment-mean } - -Lorsque vous activez un environnement virtuel, par exemple avec : - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Ou si vous utilisez Bash pour Windows (par exemple [Git Bash](https://gitforwindows.org/)) : - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -Cette commande créera ou modifiera certaines [variables d’environnement](environment-variables.md) qui seront disponibles pour les prochaines commandes. - -L’une de ces variables est la variable `PATH`. - -/// tip | Astuce - -Vous pouvez en savoir plus sur la variable d’environnement `PATH` dans la section [Variables d’environnement](environment-variables.md#path-environment-variable). - -/// - -Activer un environnement virtuel ajoute son chemin `.venv/bin` (sur Linux et macOS) ou `.venv\Scripts` (sur Windows) à la variable d’environnement `PATH`. - -Disons qu’avant d’activer l’environnement, la variable `PATH` ressemblait à ceci : - -//// tab | Linux, macOS - -```plaintext -/usr/bin:/bin:/usr/sbin:/sbin -``` - -Cela signifie que le système chercherait des programmes dans : - -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Windows\System32 -``` - -Cela signifie que le système chercherait des programmes dans : - -* `C:\Windows\System32` - -//// - -Après avoir activé l’environnement virtuel, la variable `PATH` ressemblerait à quelque chose comme ceci : - -//// tab | Linux, macOS - -```plaintext -/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -Cela signifie que le système commencera maintenant par chercher des programmes dans : - -```plaintext -/home/user/code/awesome-project/.venv/bin -``` - -avant de chercher dans les autres répertoires. - -Ainsi, lorsque vous tapez `python` dans le terminal, le système trouvera le programme Python dans - -```plaintext -/home/user/code/awesome-project/.venv/bin/python -``` - -et utilisera celui-ci. - -//// - -//// tab | Windows - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32 -``` - -Cela signifie que le système commencera maintenant par chercher des programmes dans : - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts -``` - -avant de chercher dans les autres répertoires. - -Ainsi, lorsque vous tapez `python` dans le terminal, le système trouvera le programme Python dans - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -et utilisera celui-ci. - -//// - -Un détail important est qu’il placera le chemin de l’environnement virtuel au **début** de la variable `PATH`. Le système le trouvera **avant** de trouver tout autre Python disponible. Ainsi, lorsque vous exécutez `python`, il utilisera le Python **de l’environnement virtuel** au lieu de tout autre `python` (par exemple, un `python` d’un environnement global). - -Activer un environnement virtuel change aussi deux ou trois autres choses, mais c’est l’un des points les plus importants. - -## Vérifier un environnement virtuel { #checking-a-virtual-environment } - -Lorsque vous vérifiez si un environnement virtuel est actif, par exemple avec : - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -//// - -Cela signifie que le programme `python` qui sera utilisé est celui **dans l’environnement virtuel**. - -Vous utilisez `which` sous Linux et macOS et `Get-Command` sous Windows PowerShell. - -La façon dont cette commande fonctionne est qu’elle va vérifier la variable d’environnement `PATH`, en parcourant **chaque chemin dans l’ordre**, à la recherche du programme nommé `python`. Une fois trouvé, elle vous **affichera le chemin** vers ce programme. - -La partie la plus importante est que lorsque vous appelez `python`, c’est exactement « `python` » qui sera exécuté. - -Ainsi, vous pouvez confirmer si vous êtes dans le bon environnement virtuel. - -/// tip | Astuce - -Il est facile d’activer un environnement virtuel, d’obtenir un Python, puis d’**aller vers un autre projet**. - -Et le second projet **ne fonctionnerait pas** parce que vous utilisez le **Python incorrect**, provenant d’un environnement virtuel d’un autre projet. - -Il est utile de pouvoir vérifier quel `python` est utilisé. 🤓 - -/// - -## Pourquoi désactiver un environnement virtuel { #why-deactivate-a-virtual-environment } - -Par exemple, vous pourriez travailler sur un projet `philosophers-stone`, **activer cet environnement virtuel**, installer des packages et travailler avec cet environnement. - -Puis vous souhaitez travailler sur **un autre projet** `prisoner-of-azkaban`. - -Vous allez vers ce projet : - -
- -```console -$ cd ~/code/prisoner-of-azkaban -``` - -
- -Si vous ne désactivez pas l’environnement virtuel de `philosophers-stone`, lorsque vous exécutez `python` dans le terminal, il essaiera d’utiliser le Python de `philosophers-stone`. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -$ python main.py - -// Erreur lors de l'import de sirius, il n'est pas installé 😱 -Traceback (most recent call last): - File "main.py", line 1, in - import sirius -``` - -
- -Mais si vous désactivez l’environnement virtuel et activez le nouveau pour `prisoner-of-azkaban`, alors lorsque vous exécuterez `python`, il utilisera le Python de l’environnement virtuel de `prisoner-of-azkaban`. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -// Vous n’avez pas besoin d’être dans l’ancien répertoire pour désactiver, vous pouvez le faire où que vous soyez, même après être allé dans l’autre projet 😎 -$ deactivate - -// Activer l’environnement virtuel dans prisoner-of-azkaban/.venv 🚀 -$ source .venv/bin/activate - -// Maintenant, lorsque vous exécutez python, il trouvera le package sirius installé dans cet environnement virtuel ✨ -$ python main.py - -I solemnly swear 🐺 -``` - -
- -## Alternatives { #alternatives } - -Ceci est un guide simple pour vous lancer et vous montrer comment tout fonctionne **en dessous**. - -Il existe de nombreuses **alternatives** pour gérer les environnements virtuels, les dépendances de packages (requirements), les projets. - -Lorsque vous êtes prêt et souhaitez utiliser un outil pour **gérer l’ensemble du projet**, les dépendances de packages, les environnements virtuels, etc., je vous suggère d’essayer [uv](https://github.com/astral-sh/uv). - -`uv` peut faire beaucoup de choses, il peut : - -* **Installer Python** pour vous, y compris différentes versions -* Gérer l’**environnement virtuel** pour vos projets -* Installer des **packages** -* Gérer les **dépendances et versions** de packages pour votre projet -* Vous assurer d’avoir un ensemble **exact** de packages et de versions à installer, y compris leurs dépendances, afin que vous puissiez être certain d’exécuter votre projet en production exactement comme sur votre ordinateur pendant le développement, cela s’appelle le **locking** -* Et bien d’autres choses - -## Conclusion { #conclusion } - -Si vous avez lu et compris tout cela, vous en savez maintenant **bien plus** sur les environnements virtuels que beaucoup de développeurs. 🤓 - -Connaître ces détails vous sera très probablement utile à l’avenir lorsque vous déboguerez quelque chose qui semble complexe, mais vous saurez **comment tout fonctionne en dessous**. 😎 +Lisez le [guide sur les environnements virtuels](https://tiangolo.com/guides/virtual-environments/) pour apprendre comment les environnements virtuels fonctionnent en dessous, y compris l’activation et le workflow alternatif avec `python -m venv` et `pip`. diff --git a/docs/hi/docs/advanced/additional-responses.md b/docs/hi/docs/advanced/additional-responses.md index 410157c..eca286f 100644 --- a/docs/hi/docs/advanced/additional-responses.md +++ b/docs/hi/docs/advanced/additional-responses.md @@ -243,5 +243,5 @@ new_dict = {**old_dict, "new key": "new value"} Responses में आप ठीक-ठीक क्या शामिल कर सकते हैं, यह देखने के लिए आप OpenAPI specification में ये sections देख सकते हैं: -* [OpenAPI Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object), इसमें `Response Object` शामिल है। -* [OpenAPI Response Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object), आप इसमें से कुछ भी सीधे अपने `responses` parameter के अंदर प्रत्येक response में शामिल कर सकते हैं। जिसमें `description`, `headers`, `content` (इसी के अंदर आप अलग-अलग media types और JSON Schemas घोषित करते हैं), और `links` शामिल हैं। +* [OpenAPI Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object), इसमें `Response Object` शामिल है। +* [OpenAPI Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object), आप इसमें से कुछ भी सीधे अपने `responses` parameter के अंदर प्रत्येक response में शामिल कर सकते हैं। जिसमें `description`, `headers`, `content` (इसी के अंदर आप अलग-अलग media types और JSON Schemas घोषित करते हैं), और `links` शामिल हैं। diff --git a/docs/hi/docs/advanced/async-tests.md b/docs/hi/docs/advanced/async-tests.md index 8981d55..dee1651 100644 --- a/docs/hi/docs/advanced/async-tests.md +++ b/docs/hi/docs/advanced/async-tests.md @@ -45,7 +45,7 @@ file `test_main.py` में `main.py` के लिए tests होंगे,
```console -$ pytest +$ uv run pytest ---> 100% ``` diff --git a/docs/hi/docs/advanced/behind-a-proxy.md b/docs/hi/docs/advanced/behind-a-proxy.md index 11bd984..7890efb 100644 --- a/docs/hi/docs/advanced/behind-a-proxy.md +++ b/docs/hi/docs/advanced/behind-a-proxy.md @@ -33,7 +33,7 @@ Proxy headers हैं:
```console -$ fastapi run --forwarded-allow-ips="*" +$ uv run fastapi run --forwarded-allow-ips="*" INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -170,7 +170,7 @@ Docs UI को OpenAPI schema में यह declare करने की भ
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -200,7 +200,7 @@ ASGI specification इस use case के लिए `root_path` define करत
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -253,7 +253,7 @@ Uvicorn अपेक्षा करेगा कि proxy Uvicorn को `http: आप [Traefik](https://docs.traefik.io/) का उपयोग करके stripped path prefix के साथ experiment आसानी से locally चला सकते हैं। -[Traefik download करें](https://github.com/containous/traefik/releases), यह एक single binary है, आप compressed file extract कर सकते हैं और इसे सीधे terminal से चला सकते हैं। +[Traefik download करें](https://github.com/traefik/traefik/releases), यह एक single binary है, आप compressed file extract कर सकते हैं और इसे सीधे terminal से चला सकते हैं। फिर `traefik.toml` नाम की file बनाएँ जिसमें यह हो: @@ -321,7 +321,7 @@ INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/hi/docs/advanced/dataclasses.md b/docs/hi/docs/advanced/dataclasses.md index 55e4876..57f63b4 100644 --- a/docs/hi/docs/advanced/dataclasses.md +++ b/docs/hi/docs/advanced/dataclasses.md @@ -6,7 +6,7 @@ FastAPI **Pydantic** के ऊपर बनाया गया है, और {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -यह अभी भी **Pydantic** की वजह से support किया जाता है, क्योंकि इसमें [`dataclasses` के लिए internal support](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel) है। +यह अभी भी **Pydantic** की वजह से support किया जाता है, क्योंकि इसमें [`dataclasses` के लिए internal support](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/#usage-of-stdlib-dataclasses-with-basemodel) है। इसलिए, ऊपर दिए गए code में भी, जो Pydantic का स्पष्ट रूप से उपयोग नहीं करता, FastAPI उन standard dataclasses को Pydantic की अपनी तरह की dataclasses में बदलने के लिए Pydantic का उपयोग कर रहा है। @@ -88,7 +88,7 @@ dataclass अपने आप Pydantic dataclass में बदल जाए आप `dataclasses` को अन्य Pydantic models के साथ भी जोड़ सकते हैं, उनसे inherit कर सकते हैं, उन्हें अपने models में शामिल कर सकते हैं, आदि। -अधिक जानने के लिए, [dataclasses के बारे में Pydantic docs](https://docs.pydantic.dev/latest/concepts/dataclasses/) देखें। +अधिक जानने के लिए, [dataclasses के बारे में Pydantic docs](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/) देखें। ## Version { #version } diff --git a/docs/hi/docs/advanced/events.md b/docs/hi/docs/advanced/events.md index 05afd4e..9bc5c34 100644 --- a/docs/hi/docs/advanced/events.md +++ b/docs/hi/docs/advanced/events.md @@ -1,4 +1,4 @@ -# Lifespan Events { #lifespan-events } +# Lifespan event { #lifespan-events } आप ऐसी logic (code) define कर सकते हैं जिसे application के **starts up** होने से पहले execute किया जाना चाहिए। इसका मतलब है कि यह code application के **requests receive करना शुरू करने से पहले**, **एक बार** execute होगा। @@ -84,11 +84,11 @@ async with lifespan(app): {* ../../docs_src/events/tutorial003_py310.py hl[22] *} -## Alternative Events (deprecated) { #alternative-events-deprecated } +## Alternative event (deprecated) { #alternative-events-deprecated } /// warning | चेतावनी -*startup* और *shutdown* को handle करने का recommended तरीका ऊपर बताए गए अनुसार `FastAPI` app के `lifespan` parameter का use करना है। अगर आप `lifespan` parameter provide करते हैं, तो `startup` और `shutdown` event handlers अब call नहीं किए जाएंगे। यह पूरा `lifespan` होगा या पूरे events, दोनों नहीं। +*startup* और *shutdown* को handle करने का recommended तरीका ऊपर बताए गए अनुसार `FastAPI` app के `lifespan` parameter का use करना है। अगर आप `lifespan` parameter provide करते हैं, तो `startup` और `shutdown` event handlers अब call नहीं किए जाएंगे। यह पूरा `lifespan` होगा या पूरे event, दोनों नहीं। आप शायद यह हिस्सा skip कर सकते हैं। @@ -150,11 +150,11 @@ application के shutting down होने पर run होने वाल जिज्ञासु nerds के लिए बस एक technical detail। 🤓 -अंदर से, ASGI technical specification में, यह [Lifespan Protocol](https://asgi.readthedocs.io/en/latest/specs/lifespan.html) का हिस्सा है, और यह `startup` और `shutdown` नाम के events define करता है। +अंदर से, ASGI technical specification में, यह [Lifespan Protocol](https://asgi.readthedocs.io/en/latest/specs/lifespan.html) का हिस्सा है, और यह `startup` और `shutdown` नाम के event define करता है। /// note | नोट -आप Starlette `lifespan` handlers के बारे में [Starlette की Lifespan docs](https://www.starlette.dev/lifespan/) में और पढ़ सकते हैं। +आप Starlette `lifespan` handlers के बारे में [Starlette की Lifespan docs](https://starlette.dev/lifespan/) में और पढ़ सकते हैं। इसमें यह भी शामिल है कि lifespan state को कैसे handle किया जाए जिसे आपके code के अन्य areas में use किया जा सकता है। @@ -162,4 +162,4 @@ application के shutting down होने पर run होने वाल ## Sub Applications { #sub-applications } -🚨 ध्यान रखें कि ये lifespan events (startup और shutdown) केवल main application के लिए execute होंगे, [Sub Applications - Mounts](sub-applications.md) के लिए नहीं। +🚨 ध्यान रखें कि ये lifespan event (startup और shutdown) केवल main application के लिए execute होंगे, [Sub Applications - Mounts](sub-applications.md) के लिए नहीं। diff --git a/docs/hi/docs/advanced/generate-clients.md b/docs/hi/docs/advanced/generate-clients.md index fa4b8f4..cd6773c 100644 --- a/docs/hi/docs/advanced/generate-clients.md +++ b/docs/hi/docs/advanced/generate-clients.md @@ -2,7 +2,7 @@ क्योंकि **FastAPI** **OpenAPI** specification पर आधारित है, इसकी APIs को एक standard format में वर्णित किया जा सकता है जिसे कई tools समझते हैं। -इससे up-to-date **documentation**, कई भाषाओं में client libraries (**SDKs**), और **testing** या **automation workflows** जेनरेट करना आसान हो जाता है, जो आपके code के साथ sync में रहते हैं। +इससे up-to-date **documentation**, कई भाषाओं में client libraries (**SDKs**), और **testing** या **automation workflows** जेनरेट करना आसान हो जाता है, जो आपके code के साथ sync में रहते हैं। इस guide में, आप सीखेंगे कि अपने FastAPI backend के लिए **TypeScript SDK** कैसे जेनरेट करें। @@ -12,7 +12,7 @@ **TypeScript clients** के लिए, [Hey API](https://heyapi.dev/) एक purpose-built solution है, जो TypeScript ecosystem के लिए optimized experience प्रदान करता है। -आप [OpenAPI.Tools](https://openapi.tools/#sdk) पर और SDK generators खोज सकते हैं। +आप [OpenAPI.Tools](https://openapi.tools/categories/sdk-generators) पर और SDK generators खोज सकते हैं। /// tip | सुझाव diff --git a/docs/hi/docs/advanced/middleware.md b/docs/hi/docs/advanced/middleware.md index a920ba2..fa03dd2 100644 --- a/docs/hi/docs/advanced/middleware.md +++ b/docs/hi/docs/advanced/middleware.md @@ -91,7 +91,7 @@ middleware standard और streaming दोनों responses को handle क उदाहरण के लिए: -* [Uvicorn का `ProxyHeadersMiddleware`](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) +* [Uvicorn का `ProxyHeadersMiddleware`](https://github.com/Kludex/uvicorn/blob/main/uvicorn/middleware/proxy_headers.py) * [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -अन्य उपलब्ध middleware देखने के लिए [Starlette के Middleware docs](https://www.starlette.dev/middleware/) और [ASGI Awesome List](https://github.com/florimondmanca/awesome-asgi) देखें। +अन्य उपलब्ध middleware देखने के लिए [Starlette के Middleware docs](https://starlette.dev/middleware/) और [ASGI Awesome List](https://github.com/florimondmanca/awesome-asgi) देखें। diff --git a/docs/hi/docs/advanced/openapi-callbacks.md b/docs/hi/docs/advanced/openapi-callbacks.md index 1cdbc82..9ae1263 100644 --- a/docs/hi/docs/advanced/openapi-callbacks.md +++ b/docs/hi/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ Callback जोड़ने से पहले, पहले देखते /// tip | सुझाव -`callback_url` query parameter एक Pydantic [Url](https://docs.pydantic.dev/latest/api/networks/) type का उपयोग करता है। +`callback_url` query parameter एक Pydantic [Url](https://pydantic.dev/docs/validation/latest/api/pydantic/networks/) type का उपयोग करता है। /// @@ -106,11 +106,11 @@ Callback *path operation* बनाने के लिए वही `APIRouter` सामान्य *path operation* से 2 मुख्य अंतर हैं: * इसमें कोई वास्तविक code होना required नहीं है, क्योंकि आपकी app इस code को कभी call नहीं करेगी। इसका उपयोग केवल *external API* को document करने के लिए किया जाता है। इसलिए, function में केवल `pass` हो सकता है। -* *path* में एक [OpenAPI 3 expression](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) (नीचे और देखें) हो सकता है, जहाँ यह *आपकी API* को भेजी गई original request के parameters और parts के साथ variables का उपयोग कर सकता है। +* *path* में एक [OpenAPI 3 expression](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression) (नीचे और देखें) हो सकता है, जहाँ यह *आपकी API* को भेजी गई original request के parameters और parts के साथ variables का उपयोग कर सकता है। ### Callback path expression { #the-callback-path-expression } -Callback *path* में एक [OpenAPI 3 expression](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) हो सकता है जो *आपकी API* को भेजी गई original request के parts शामिल कर सकता है। +Callback *path* में एक [OpenAPI 3 expression](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression) हो सकता है जो *आपकी API* को भेजी गई original request के parts शामिल कर सकता है। इस case में, यह `str` है: diff --git a/docs/hi/docs/advanced/response-cookies.md b/docs/hi/docs/advanced/response-cookies.md index ccd65dc..3f50a48 100644 --- a/docs/hi/docs/advanced/response-cookies.md +++ b/docs/hi/docs/advanced/response-cookies.md @@ -48,4 +48,4 @@ /// -सभी उपलब्ध parameters और options देखने के लिए, [Starlette में documentation](https://www.starlette.dev/responses/#set-cookie) देखें। +सभी उपलब्ध parameters और options देखने के लिए, [Starlette में documentation](https://starlette.dev/responses/#set-cookie) देखें। diff --git a/docs/hi/docs/advanced/response-headers.md b/docs/hi/docs/advanced/response-headers.md index 9d62e2f..cf64d14 100644 --- a/docs/hi/docs/advanced/response-headers.md +++ b/docs/hi/docs/advanced/response-headers.md @@ -38,4 +38,4 @@ ध्यान रखें कि custom proprietary headers को [`X-` prefix का उपयोग करके](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) जोड़ा जा सकता है। -लेकिन अगर आपके पास custom headers हैं जिन्हें आप चाहते हैं कि browser में कोई client देख सके, तो आपको उन्हें अपनी CORS configurations में जोड़ना होगा ([CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md) में और पढ़ें), इसके लिए [Starlette के CORS docs](https://www.starlette.dev/middleware/#corsmiddleware) में documented parameter `expose_headers` का उपयोग करें। +लेकिन अगर आपके पास custom headers हैं जिन्हें आप चाहते हैं कि browser में कोई client देख सके, तो आपको उन्हें अपनी CORS configurations में जोड़ना होगा ([CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md) में और पढ़ें), इसके लिए [Starlette के CORS docs](https://starlette.dev/middleware/#corsmiddleware) में documented parameter `expose_headers` का उपयोग करें। diff --git a/docs/hi/docs/advanced/settings.md b/docs/hi/docs/advanced/settings.md index 0c4d3c0..c8c0b70 100644 --- a/docs/hi/docs/advanced/settings.md +++ b/docs/hi/docs/advanced/settings.md @@ -6,9 +6,13 @@ इसी कारण उन्हें आम तौर पर environment variables में दिया जाता है जिन्हें application पढ़ती है। +एक **environment variable** (जिसे **env var** भी कहा जाता है) एक value है जो Python code के बाहर, operating system में रहती है, और आपकी application और दूसरे programs द्वारा पढ़ी जा सकती है। + +जब आप कोई command चलाते हैं, तो आप उसके लिए एक environment variable बना सकते हैं। आप नीचे platform-specific commands देखेंगे। + /// tip | सुझाव -Environment variables को समझने के लिए आप [Environment Variables](../environment-variables.md) पढ़ सकते हैं। +Environment variables कैसे काम करते हैं, इसकी विस्तृत व्याख्या के लिए [Environment Variables guide](https://tiangolo.com/guides/environment-variables/) पढ़ें। /// @@ -20,27 +24,27 @@ Environment variables को समझने के लिए आप [Environmen ## Pydantic `Settings` { #pydantic-settings } -सौभाग्य से, Pydantic environment variables से आने वाली इन settings को handle करने के लिए एक बेहतरीन utility देता है: [Pydantic: Settings management](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)। +सौभाग्य से, Pydantic environment variables से आने वाली इन settings को handle करने के लिए [Pydantic: Settings management](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) के साथ एक बेहतरीन utility देता है। ### `pydantic-settings` install करें { #install-pydantic-settings } -सबसे पहले, सुनिश्चित करें कि आप अपना [virtual environment](../virtual-environments.md) बनाते हैं, उसे activate करते हैं, और फिर `pydantic-settings` package install करते हैं: +`pydantic-settings` package को अपने project में add करें:
```console -$ pip install pydantic-settings +$ uv add pydantic-settings ---> 100% ```
-जब आप `all` extras को install करते हैं, तो यह भी शामिल आता है: +जब आप `all` extras को इनके साथ install करते हैं, तो यह भी शामिल आता है:
```console -$ pip install "fastapi[all]" +$ uv add "fastapi[all]" ---> 100% ``` @@ -76,19 +80,39 @@ Pydantic models की तरह ही, आप type annotations के सा इसके बाद, आप configurations को environment variables के रूप में pass करते हुए server चलाएँगे, उदाहरण के लिए आप `ADMIN_EMAIL` और `APP_NAME` set कर सकते हैं: +//// tab | Linux, macOS, Windows Bash +
```console -$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py +$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uv run fastapi run main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
+//// + +//// tab | Windows PowerShell + +
+ +```console +$ $Env:ADMIN_EMAIL = "deadpool@example.com" +$ $Env:APP_NAME = "ChimichangApp" +$ uv run fastapi run main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +//// + /// tip | सुझाव -एक ही command के लिए कई env vars set करने के लिए बस उन्हें space से अलग करें, और उन सभी को command से पहले रखें। +Bash में, एक ही command के लिए कई env vars set करने के लिए, उन्हें space से अलग करें और उन सभी को command से पहले रखें। /// @@ -172,11 +196,11 @@ dot (`.`) से शुरू होने वाली file Unix-like systems, /// -Pydantic के पास external library का उपयोग करके इस प्रकार की files से पढ़ने के लिए support है। आप [Pydantic Settings: Dotenv (.env) support](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support) पर और पढ़ सकते हैं। +Pydantic के पास external library का उपयोग करके इस प्रकार की files से पढ़ने के लिए support है। आप [Pydantic Settings: Dotenv (.env) support](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#dotenv-env-support) पर और पढ़ सकते हैं। /// tip | सुझाव -इसे काम करने के लिए, आपको `pip install python-dotenv` करना होगा। +इसे काम करने के लिए, `uv add python-dotenv` के साथ `python-dotenv` को अपने project में add करें। /// @@ -197,7 +221,7 @@ APP_NAME="ChimichangApp" /// tip | सुझाव -`model_config` attribute केवल Pydantic configuration के लिए उपयोग किया जाता है। आप [Pydantic: Concepts: Configuration](https://docs.pydantic.dev/latest/concepts/config/) पर और पढ़ सकते हैं। +`model_config` attribute केवल Pydantic configuration के लिए उपयोग किया जाता है। आप [Pydantic: Concepts: Configuration](https://pydantic.dev/docs/validation/latest/concepts/config/) पर और पढ़ सकते हैं। /// diff --git a/docs/hi/docs/advanced/sub-applications.md b/docs/hi/docs/advanced/sub-applications.md index 3f4ea6d..5cc64e3 100644 --- a/docs/hi/docs/advanced/sub-applications.md +++ b/docs/hi/docs/advanced/sub-applications.md @@ -35,7 +35,7 @@
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/hi/docs/advanced/templates.md b/docs/hi/docs/advanced/templates.md index b16ef4a..a79b025 100644 --- a/docs/hi/docs/advanced/templates.md +++ b/docs/hi/docs/advanced/templates.md @@ -8,12 +8,12 @@ ## Dependencies install करें { #install-dependencies } -सुनिश्चित करें कि आप एक [virtual environment](../virtual-environments.md) बनाएँ, उसे activate करें, और `jinja2` install करें: +अपने project में `jinja2` जोड़ें:
```console -$ pip install jinja2 +$ uv add jinja2 ---> 100% ``` @@ -123,4 +123,4 @@ Item ID: 42 ## अधिक विवरण { #more-details } -अधिक विवरण के लिए, जिसमें templates को test करना भी शामिल है, [templates पर Starlette के docs](https://www.starlette.dev/templates/) देखें। +अधिक विवरण के लिए, जिसमें templates को test करना भी शामिल है, [templates पर Starlette के docs](https://starlette.dev/templates/) देखें। diff --git a/docs/hi/docs/advanced/testing-events.md b/docs/hi/docs/advanced/testing-events.md index 3f09fe1..03af2ac 100644 --- a/docs/hi/docs/advanced/testing-events.md +++ b/docs/hi/docs/advanced/testing-events.md @@ -5,8 +5,8 @@ {* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *} -आप इसके बारे में अधिक विवरण ["आधिकारिक Starlette documentation site में tests में lifespan चलाना।"](https://www.starlette.dev/lifespan/#running-lifespan-in-tests) में पढ़ सकते हैं। +आप इसके बारे में अधिक विवरण ["आधिकारिक Starlette documentation site में tests में lifespan चलाना।"](https://starlette.dev/lifespan/#running-lifespan-in-tests) में पढ़ सकते हैं। -deprecated `startup` और `shutdown` event के लिए, आप `TestClient` का उपयोग इस प्रकार कर सकते हैं: +deprecated `startup` और `shutdown` events के लिए, आप `TestClient` का उपयोग इस प्रकार कर सकते हैं: {* ../../docs_src/app_testing/tutorial003_py310.py hl[9:12,20:24] *} diff --git a/docs/hi/docs/advanced/testing-websockets.md b/docs/hi/docs/advanced/testing-websockets.md index 470b079..36e0e1b 100644 --- a/docs/hi/docs/advanced/testing-websockets.md +++ b/docs/hi/docs/advanced/testing-websockets.md @@ -8,6 +8,6 @@ /// note | नोट -अधिक जानकारी के लिए, Starlette की documentation में [WebSockets की testing](https://www.starlette.dev/testclient/#testing-websocket-sessions) देखें। +अधिक जानकारी के लिए, Starlette की documentation में [WebSockets की testing](https://starlette.dev/testclient/#testing-websocket-sessions) देखें। /// diff --git a/docs/hi/docs/advanced/using-request-directly.md b/docs/hi/docs/advanced/using-request-directly.md index 8110e55..0072d12 100644 --- a/docs/hi/docs/advanced/using-request-directly.md +++ b/docs/hi/docs/advanced/using-request-directly.md @@ -15,7 +15,7 @@ Data लेना: ## `Request` object के बारे में विवरण { #details-about-the-request-object } -क्योंकि **FastAPI** असल में नीचे से **Starlette** है, जिसके ऊपर कई tools की एक layer है, इसलिए जब ज़रूरत हो, आप Starlette के [`Request`](https://www.starlette.dev/requests/) object को सीधे इस्तेमाल कर सकते हैं। +क्योंकि **FastAPI** असल में नीचे से **Starlette** है, जिसके ऊपर कई tools की एक layer है, इसलिए जब ज़रूरत हो, आप Starlette के [`Request`](https://starlette.dev/requests/) object को सीधे इस्तेमाल कर सकते हैं। इसका मतलब यह भी होगा कि अगर आप `Request` object से सीधे data लेते हैं (उदाहरण के लिए, body पढ़ते हैं), तो FastAPI उसे validate, convert या document नहीं करेगा (OpenAPI के साथ, automatic API user interface के लिए)। @@ -45,7 +45,7 @@ Data लेना: ## `Request` documentation { #request-documentation } -आप [`Request` object के बारे में official Starlette documentation site](https://www.starlette.dev/requests/) पर और विवरण पढ़ सकते हैं। +आप [`Request` object के बारे में official Starlette documentation site](https://starlette.dev/requests/) पर और विवरण पढ़ सकते हैं। /// note | तकनीकी विवरण diff --git a/docs/hi/docs/advanced/websockets.md b/docs/hi/docs/advanced/websockets.md index 9e761a9..1461502 100644 --- a/docs/hi/docs/advanced/websockets.md +++ b/docs/hi/docs/advanced/websockets.md @@ -4,12 +4,12 @@ ## `websockets` install करें { #install-websockets } -सुनिश्चित करें कि आप एक [virtual environment](../virtual-environments.md) बनाएँ, उसे activate करें, और `websockets` install करें (एक Python library जो "WebSocket" protocol का उपयोग आसान बनाती है): +अपने project में `websockets` (एक Python library जो "WebSocket" protocol का उपयोग आसान बनाती है) जोड़ें:
```console -$ pip install websockets +$ uv add websockets ---> 100% ``` @@ -69,7 +69,7 @@ production में आपके पास ऊपर दिए गए विक
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -126,7 +126,7 @@ WebSocket endpoints में आप `fastapi` से import कर सकते
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -182,5 +182,5 @@ Client #1596980209979 left the chat विकल्पों के बारे में अधिक जानने के लिए, इनके लिए Starlette का documentation देखें: -* [`WebSocket` class](https://www.starlette.dev/websockets/)। -* [Class-based WebSocket handling](https://www.starlette.dev/endpoints/#websocketendpoint)। +* [`WebSocket` class](https://starlette.dev/websockets/)। +* [Class-based WebSocket handling](https://starlette.dev/endpoints/#websocketendpoint)। diff --git a/docs/hi/docs/advanced/wsgi.md b/docs/hi/docs/advanced/wsgi.md index 1ea60d4..066f6a2 100644 --- a/docs/hi/docs/advanced/wsgi.md +++ b/docs/hi/docs/advanced/wsgi.md @@ -8,7 +8,7 @@ /// note | नोट -इसके लिए `a2wsgi` install करना required है, उदाहरण के लिए `pip install a2wsgi` के साथ। +इसके लिए अपने project में `a2wsgi` जोड़ना required है, उदाहरण के लिए `uv add a2wsgi` के साथ। /// diff --git a/docs/hi/docs/alternatives.md b/docs/hi/docs/alternatives.md index 31ca9e1..a674eae 100644 --- a/docs/hi/docs/alternatives.md +++ b/docs/hi/docs/alternatives.md @@ -125,7 +125,7 @@ Custom schema के बजाय API specifications के लिए एक ope और standards-based user interface tools को integrate किया जाए: * [Swagger UI](https://github.com/swagger-api/swagger-ui) -* [ReDoc](https://github.com/Rebilly/ReDoc) +* [ReDoc](https://github.com/Redocly/redoc) इन दोनों को इसलिए चुना गया क्योंकि ये काफी popular और stable थे, लेकिन एक quick search करने पर, आप OpenAPI के लिए दर्जनों alternative user interfaces पा सकते हैं (जिन्हें आप **FastAPI** के साथ उपयोग कर सकते हैं)। @@ -237,7 +237,7 @@ OpenAPI schema को automatically generate किया जाए, उसी c /// -### [NestJS](https://nestjs.com/) (और [Angular](https://angular.io/)) { #nestjs-and-angular } +### [NestJS](https://nestjs.com/) (और [Angular](https://angular.dev/)) { #nestjs-and-angular } यह Python भी नहीं है, NestJS Angular से प्रेरित एक JavaScript (TypeScript) NodeJS framework है। @@ -337,7 +337,7 @@ Hug उन पहले frameworks में से एक था जिसन /// note | नोट -Hug को Timothy Crosley ने बनाया था, वही [`isort`](https://github.com/timothycrosley/isort) के creator हैं, जो Python files में imports को automatically sort करने के लिए एक बेहतरीन tool है। +Hug को Timothy Crosley ने बनाया था, वही [`isort`](https://github.com/PyCQA/isort) के creator हैं, जो Python files में imports को automatically sort करने के लिए एक बेहतरीन tool है। /// @@ -401,7 +401,7 @@ APIStar को Tom Christie ने बनाया था। वही व्य ## **FastAPI** द्वारा उपयोग किया गया { #used-by-fastapi } -### [Pydantic](https://docs.pydantic.dev/) { #pydantic } +### [Pydantic](https://pydantic.dev/docs/) { #pydantic } Pydantic Python type hints के आधार पर data validation, serialization और documentation (JSON Schema का उपयोग करके) define करने के लिए एक library है। @@ -417,7 +417,7 @@ Pydantic Python type hints के आधार पर data validation, serializa /// -### [Starlette](https://www.starlette.dev/) { #starlette } +### [Starlette](https://starlette.dev/) { #starlette } Starlette एक lightweight ASGI framework/toolkit है, जो high-performance asyncio services बनाने के लिए ideal है। @@ -462,7 +462,7 @@ Class `FastAPI` खुद सीधे class `Starlette` से inherit कर /// -### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn } +### [Uvicorn](https://uvicorn.dev) { #uvicorn } Uvicorn एक lightning-fast ASGI server है, जो uvloop और httptools पर बना है। diff --git a/docs/hi/docs/deployment/docker.md b/docs/hi/docs/deployment/docker.md index 6e8bea0..8bea374 100644 --- a/docs/hi/docs/deployment/docker.md +++ b/docs/hi/docs/deployment/docker.md @@ -105,36 +105,32 @@ Container में सामान्यतः **single process** होता ### Package Requirements { #package-requirements } -आपकी application के लिए **package requirements** सामान्यतः किसी file में होंगे। +जब आप अपना project `uv` से manage करते हैं, तो इसकी direct dependencies `pyproject.toml` में declared होती हैं और exact resolved versions `uv.lock` में stored होते हैं। -यह मुख्य रूप से उस tool पर निर्भर करेगा जिसका उपयोग आप उन requirements को **install** करने के लिए करते हैं। - -इसे करने का सबसे आम तरीका है `requirements.txt` file रखना, जिसमें package names और उनके versions हों, प्रति line एक। - -आप versions की ranges set करने के लिए निश्चित रूप से वही ideas उपयोग करेंगे जो आपने [FastAPI versions के बारे में](versions.md) में पढ़े हैं। - -उदाहरण के लिए, आपका `requirements.txt` ऐसा दिख सकता है: - -``` -fastapi[standard]>=0.113.0,<0.114.0 -pydantic>=2.7.0,<3.0.0 -``` - -और आप सामान्यतः उन package dependencies को `pip` से install करेंगे, उदाहरण के लिए: +आप अपनी application के लिए required packages इस तरह जोड़ सकते हैं:
```console -$ pip install -r requirements.txt +$ uv add "fastapi[standard]" pydantic ---> 100% -Successfully installed fastapi pydantic ```
/// note | नोट -Package dependencies define और install करने के लिए अन्य formats और tools भी हैं। +नीचे दिया गया Dockerfile container के अंदर `pip` उपयोग करता है। आप अपने uv project से locked dependencies को उसके expected `requirements.txt` format में export कर सकते हैं: + +
+ +```console +$ uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt +``` + +
+ +Generated `requirements.txt` container build के लिए एक export है। Dependencies को `uv add` से manage करना जारी रखें और जब `uv.lock` change हो तो इसे regenerate करें। /// @@ -372,7 +368,7 @@ $ docker run -d --name mycontainer -p 80:80 myimage और आप [http://192.168.99.100/redoc](http://192.168.99.100/redoc) या [http://127.0.0.1/redoc](http://127.0.0.1/redoc) (या equivalent, अपने Docker host का उपयोग करके) पर भी जा सकते हैं। -आप alternative automatic documentation देखेंगे ([ReDoc](https://github.com/Rebilly/ReDoc) द्वारा provided): +आप alternative automatic documentation देखेंगे ([ReDoc](https://github.com/Redocly/redoc) द्वारा provided): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) diff --git a/docs/hi/docs/deployment/fastapicloud.md b/docs/hi/docs/deployment/fastapicloud.md index 06a2a2d..6b72595 100644 --- a/docs/hi/docs/deployment/fastapicloud.md +++ b/docs/hi/docs/deployment/fastapicloud.md @@ -5,7 +5,7 @@
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... diff --git a/docs/hi/docs/deployment/manually.md b/docs/hi/docs/deployment/manually.md index 8404215..21972c3 100644 --- a/docs/hi/docs/deployment/manually.md +++ b/docs/hi/docs/deployment/manually.md @@ -46,13 +46,13 @@ $ fastapi run ASGI कहा जाता है। FastAPI एक ASGI web framework है। +FastAPI Python web frameworks और servers बनाने के लिए एक standard का उपयोग करता है जिसे ASGI कहा जाता है। FastAPI एक ASGI web framework है। किसी remote server machine में **FastAPI** application (या कोई भी दूसरी ASGI application) चलाने के लिए आपको मुख्य रूप से एक ASGI server program चाहिए, जैसे **Uvicorn**; यही `fastapi` command में default रूप से आता है। कई विकल्प हैं, जिनमें शामिल हैं: -* [Uvicorn](https://www.uvicorn.dev/): एक high performance ASGI server। +* [Uvicorn](https://uvicorn.dev): एक high performance ASGI server। * [Hypercorn](https://hypercorn.readthedocs.io/): एक ASGI server जो अन्य features के साथ HTTP/2 और Trio के साथ compatible है। * [Daphne](https://github.com/django/daphne): Django Channels के लिए बनाया गया ASGI server। * [Granian](https://github.com/emmett-framework/granian): Python applications के लिए एक Rust HTTP server। @@ -73,14 +73,14 @@ Remote machine का संदर्भ देते समय, इसे **ser लेकिन आप एक ASGI server को मैन्युअली भी install कर सकते हैं। -सुनिश्चित करें कि आप एक [virtual environment](../virtual-environments.md) बनाएँ, उसे activate करें, और फिर आप server application install कर सकते हैं। +Server application को अपने project में जोड़ें। उदाहरण के लिए, Uvicorn install करने के लिए:
```console -$ pip install "uvicorn[standard]" +$ uv add "uvicorn[standard]" ---> 100% ``` @@ -95,7 +95,7 @@ $ pip install "uvicorn[standard]" इसमें `uvloop` शामिल है, जो `asyncio` के लिए high-performance drop-in replacement है, और बड़ा concurrency performance boost देता है। -जब आप `pip install "fastapi[standard]"` जैसी किसी command से FastAPI install करते हैं, तो आपको `uvicorn[standard]` भी मिल जाता है। +जब आप `uv add "fastapi[standard]"` जैसी किसी चीज़ से FastAPI जोड़ते हैं, तो आपको `uvicorn[standard]` भी मिल जाता है। /// @@ -106,7 +106,7 @@ $ pip install "uvicorn[standard]"
```console -$ uvicorn main:app --host 0.0.0.0 --port 80 +$ uv run uvicorn main:app --host 0.0.0.0 --port 80 INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) ``` diff --git a/docs/hi/docs/deployment/server-workers.md b/docs/hi/docs/deployment/server-workers.md index 540c2da..f04bd50 100644 --- a/docs/hi/docs/deployment/server-workers.md +++ b/docs/hi/docs/deployment/server-workers.md @@ -86,7 +86,7 @@ $ fastapi run --workers 4 ```console -$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 +$ uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit) INFO: Started parent process [27365] INFO: Started server process [27368] diff --git a/docs/hi/docs/environment-variables.md b/docs/hi/docs/environment-variables.md index 0545d03..3fce100 100644 --- a/docs/hi/docs/environment-variables.md +++ b/docs/hi/docs/environment-variables.md @@ -1,298 +1,11 @@ # Environment Variables { #environment-variables } -/// tip | टिप +एक **environment variable** (जिसे **env var** भी कहा जाता है) एक value है जो आपके Python code के बाहर, ऑपरेटिंग सिस्टम में रहता है, और आपकी application और दूसरे programs द्वारा पढ़ा जा सकता है। -अगर आप पहले से जानते हैं कि "environment variables" क्या होते हैं और उनका उपयोग कैसे करना है, तो आप इसे छोड़ सकते हैं। +FastAPI applications आमतौर पर database URLs, email credentials, और secret keys जैसे configuration के लिए environment variables का उपयोग करते हैं। -/// +आप [Settings और Environment Variables](advanced/settings.md) में application configuration के लिए उनका उपयोग करना सीखेंगे। -एक environment variable (जिसे "**env var**" भी कहा जाता है) एक variable है जो Python code के **बाहर**, **ऑपरेटिंग सिस्टम** में रहता है, और जिसे आपका Python code (या दूसरे programs भी) पढ़ सकते हैं। +## और जानें { #learn-more } -Environment variables application **settings** संभालने, Python की **installation** के हिस्से के रूप में, आदि में उपयोगी हो सकते हैं। - -## Env Vars बनाएं और उपयोग करें { #create-and-use-env-vars } - -आप Python की ज़रूरत के बिना, **shell (terminal)** में environment variables **बना** और उपयोग कर सकते हैं: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// आप MY_NAME नाम का env var ऐसे बना सकते हैं -$ export MY_NAME="Wade Wilson" - -// फिर आप इसे दूसरे programs के साथ उपयोग कर सकते हैं, जैसे -$ echo "Hello $MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// MY_NAME नाम का env var बनाएं -$ $Env:MY_NAME = "Wade Wilson" - -// इसे दूसरे programs के साथ उपयोग करें, जैसे -$ echo "Hello $Env:MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -## Python में env vars पढ़ें { #read-env-vars-in-python } - -आप Python के **बाहर**, terminal में (या किसी भी दूसरे तरीके से) environment variables बना सकते हैं, और फिर **उन्हें Python में पढ़** सकते हैं। - -उदाहरण के लिए, आपके पास `main.py` नाम की file हो सकती है जिसमें: - -```Python hl_lines="3" -import os - -name = os.getenv("MY_NAME", "World") -print(f"Hello {name} from Python") -``` - -/// tip | टिप - -[`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) का दूसरा argument लौटाने के लिए default value है। - -अगर यह दिया नहीं गया है, तो default रूप से यह `None` होता है, यहाँ हम उपयोग करने के लिए default value के रूप में `"World"` देते हैं। - -/// - -फिर आप उस Python program को call कर सकते हैं: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// यहाँ हमने अभी env var set नहीं किया है -$ python main.py - -// क्योंकि हमने env var set नहीं किया, हमें default value मिलती है - -Hello World from Python - -// लेकिन अगर हम पहले एक environment variable बनाते हैं -$ export MY_NAME="Wade Wilson" - -// और फिर program को फिर से call करते हैं -$ python main.py - -// अब यह environment variable पढ़ सकता है - -Hello Wade Wilson from Python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// यहाँ हमने अभी env var set नहीं किया है -$ python main.py - -// क्योंकि हमने env var set नहीं किया, हमें default value मिलती है - -Hello World from Python - -// लेकिन अगर हम पहले एक environment variable बनाते हैं -$ $Env:MY_NAME = "Wade Wilson" - -// और फिर program को फिर से call करते हैं -$ python main.py - -// अब यह environment variable पढ़ सकता है - -Hello Wade Wilson from Python -``` - -
- -//// - -क्योंकि environment variables code के बाहर set किए जा सकते हैं, लेकिन code द्वारा पढ़े जा सकते हैं, और उन्हें बाकी files के साथ store (`git` में commit) करने की ज़रूरत नहीं होती, इसलिए configurations या **settings** के लिए उनका उपयोग करना आम है। - -आप किसी **specific program invocation** के लिए भी एक environment variable बना सकते हैं, जो केवल उसी program के लिए उपलब्ध होता है, और केवल उसकी अवधि तक। - -ऐसा करने के लिए, program से ठीक पहले, उसी line पर इसे बनाएं: - -
- -```console -// इस program call के लिए line में MY_NAME नाम का env var बनाएं -$ MY_NAME="Wade Wilson" python main.py - -// अब यह environment variable पढ़ सकता है - -Hello Wade Wilson from Python - -// इसके बाद env var मौजूद नहीं रहता -$ python main.py - -Hello World from Python -``` - -
- -/// tip | टिप - -आप इसके बारे में [The Twelve-Factor App: Config](https://12factor.net/config) पर और पढ़ सकते हैं। - -/// - -## Types और Validation { #types-and-validation } - -ये environment variables केवल **text strings** को ही संभाल सकते हैं, क्योंकि ये Python से बाहरी होते हैं और इन्हें दूसरे programs तथा बाकी system (और अलग-अलग ऑपरेटिंग सिस्टम, जैसे Linux, Windows, और macOS) के साथ compatible होना होता है। - -इसका मतलब है कि Python में environment variable से पढ़ा गया **कोई भी value** **`str` होगा**, और किसी अलग type में कोई भी conversion या कोई भी validation code में करना होगा। - -आप [Advanced User Guide - Settings and Environment Variables](./advanced/settings.md) में **application settings** संभालने के लिए environment variables के उपयोग के बारे में और सीखेंगे। - -## `PATH` Environment Variable { #path-environment-variable } - -**`PATH`** नाम का एक **special** environment variable होता है जिसका उपयोग ऑपरेटिंग सिस्टम (Linux, macOS, Windows) चलाने के लिए programs खोजने में करते हैं। - -`PATH` variable का value एक लंबी string होती है जो Linux और macOS पर colon `:` से, और Windows पर semicolon `;` से अलग की गई directories से बनी होती है। - -उदाहरण के लिए, `PATH` environment variable ऐसा दिख सकता है: - -//// tab | Linux, macOS - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -इसका मतलब है कि system को इन directories में programs ढूंढने चाहिए: - -* `/usr/local/bin` -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32 -``` - -इसका मतलब है कि system को इन directories में programs ढूंढने चाहिए: - -* `C:\Program Files\Python312\Scripts` -* `C:\Program Files\Python312` -* `C:\Windows\System32` - -//// - -जब आप terminal में कोई **command** type करते हैं, तो ऑपरेटिंग सिस्टम `PATH` environment variable में listed **उनमें से प्रत्येक directory** में program को **ढूंढता है**। - -उदाहरण के लिए, जब आप terminal में `python` type करते हैं, तो ऑपरेटिंग सिस्टम उस list की **पहली directory** में `python` नाम का program ढूंढता है। - -अगर उसे यह मिल जाता है, तो वह **इसे उपयोग** करेगा। नहीं तो वह **दूसरी directories** में ढूंढना जारी रखता है। - -### Python install करना और `PATH` update करना { #installing-python-and-updating-the-path } - -जब आप Python install करते हैं, तो आपसे पूछा जा सकता है कि क्या आप `PATH` environment variable को update करना चाहते हैं। - -//// tab | Linux, macOS - -मान लें कि आप Python install करते हैं और वह `/opt/custompython/bin` directory में जाता है। - -अगर आप `PATH` environment variable को update करने के लिए yes कहते हैं, तो installer `/opt/custompython/bin` को `PATH` environment variable में जोड़ देगा। - -यह ऐसा दिख सकता है: - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin -``` - -इस तरह, जब आप terminal में `python` type करते हैं, तो system Python program को `/opt/custompython/bin` (आखिरी directory) में ढूंढेगा और उसी का उपयोग करेगा। - -//// - -//// tab | Windows - -मान लें कि आप Python install करते हैं और वह `C:\opt\custompython\bin` directory में जाता है। - -अगर आप `PATH` environment variable को update करने के लिए yes कहते हैं, तो installer `C:\opt\custompython\bin` को `PATH` environment variable में जोड़ देगा। - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin -``` - -इस तरह, जब आप terminal में `python` type करते हैं, तो system Python program को `C:\opt\custompython\bin` (आखिरी directory) में ढूंढेगा और उसी का उपयोग करेगा। - -//// - -तो, अगर आप type करते हैं: - -
- -```console -$ python -``` - -
- -//// tab | Linux, macOS - -System `/opt/custompython/bin` में `python` program को **ढूंढेगा** और उसे चलाएगा। - -यह लगभग ऐसा type करने के बराबर होगा: - -
- -```console -$ /opt/custompython/bin/python -``` - -
- -//// - -//// tab | Windows - -System `C:\opt\custompython\bin\python` में `python` program को **ढूंढेगा** और उसे चलाएगा। - -यह लगभग ऐसा type करने के बराबर होगा: - -
- -```console -$ C:\opt\custompython\bin\python -``` - -
- -//// - -यह जानकारी [Virtual Environments](virtual-environments.md) के बारे में सीखते समय उपयोगी होगी। - -## निष्कर्ष { #conclusion } - -इससे आपको यह basic समझ मिल जानी चाहिए कि **environment variables** क्या होते हैं और Python में उनका उपयोग कैसे करना है। - -आप इनके बारे में [Wikipedia for Environment Variable](https://en.wikipedia.org/wiki/Environment_variable) में भी और पढ़ सकते हैं। - -कई मामलों में तुरंत यह बहुत स्पष्ट नहीं होता कि environment variables कैसे उपयोगी और applicable होंगे। लेकिन जब आप developing कर रहे होते हैं, तो ये कई अलग-अलग scenarios में बार-बार सामने आते हैं, इसलिए इनके बारे में जानना अच्छा है। - -उदाहरण के लिए, अगले section में, [Virtual Environments](virtual-environments.md) के बारे में, आपको इस जानकारी की ज़रूरत होगी। +एक विस्तृत, cross-platform explanation के लिए [Environment Variables guide](https://tiangolo.com/guides/environment-variables/) पढ़ें, जिसमें environment variables बनाना और पढ़ना, और `PATH` environment variable कैसे काम करता है, शामिल है। diff --git a/docs/hi/docs/fastapi-cli.md b/docs/hi/docs/fastapi-cli.md index 87a1a98..e74f091 100644 --- a/docs/hi/docs/fastapi-cli.md +++ b/docs/hi/docs/fastapi-cli.md @@ -2,7 +2,7 @@ **FastAPI CLI** एक command line प्रोग्राम है जिसका उपयोग आप अपने FastAPI ऐप को serve करने, अपने FastAPI project को manage करने, और भी बहुत कुछ करने के लिए कर सकते हैं। -जब आप FastAPI install करते हैं (जैसे `pip install "fastapi[standard]"` के साथ), तो इसके साथ एक command line प्रोग्राम आता है जिसे आप terminal में चला सकते हैं। +जब आप अपने project में FastAPI add करते हैं (जैसे `uv add "fastapi[standard]"` के साथ), तो इसके साथ एक command line प्रोग्राम आता है जिसे आप terminal में चला सकते हैं। development के लिए अपना FastAPI ऐप चलाने के लिए, आप `fastapi dev` command का उपयोग कर सकते हैं: @@ -48,11 +48,11 @@ $ fastapi dev /// tip | सुझाव -production के लिए आप `fastapi dev` की जगह `fastapi run` का उपयोग करेंगे। 🚀 +production के लिए आप `fastapi run` का उपयोग करेंगे, `fastapi dev` की जगह। 🚀 /// -आंतरिक रूप से, **FastAPI CLI** [Uvicorn](https://www.uvicorn.dev) का उपयोग करता है, जो एक high-performance, production-ready, ASGI server है। 😎 +आंतरिक रूप से, **FastAPI CLI** [Uvicorn](https://uvicorn.dev) का उपयोग करता है, जो एक high-performance, production-ready, ASGI server है। 😎 `fastapi` CLI चलाने के लिए FastAPI ऐप को अपने-आप detect करने की कोशिश करेगा, यह मानते हुए कि यह `main.py` file में `app` नाम का object है (या कुछ अन्य variants में से कोई एक)। @@ -95,18 +95,18 @@ entrypoint = "backend.main:app" from backend.main import app ``` -### path के साथ या `--entrypoint` CLI option के साथ `fastapi dev` { #fastapi-dev-with-path-or-with-entrypoint-cli-option } +### `fastapi dev` path के साथ या `--entrypoint` CLI option के साथ { #fastapi-dev-with-path-or-with-entrypoint-cli-option } आप `fastapi dev` command को file path भी pass कर सकते हैं, और यह उपयोग किए जाने वाले FastAPI app object का अनुमान लगा लेगा: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` या, आप `fastapi dev` command को `--entrypoint` option भी pass कर सकते हैं: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` लेकिन आपको हर बार `fastapi` command call करते समय सही path\entrypoint pass करना याद रखना होगा। @@ -119,6 +119,10 @@ $ fastapi dev --entrypoint main:app Default रूप से, **auto-reload** enabled होता है, जो आपके code में changes करने पर server को अपने-आप reload कर देता है। यह resource-intensive है और disabled होने की तुलना में कम stable हो सकता है। आपको इसे केवल development के लिए ही उपयोग करना चाहिए। यह IP address `127.0.0.1` पर भी listen करता है, जो आपकी machine का खुद से ही communicate करने वाला IP है (`localhost`)। +आपके ऐप को import करने से पहले, `fastapi dev` `FASTAPI_ENV` environment variable को `development` पर set करता है। अगर `FASTAPI_ENV` पहले से set है, तो इसकी मौजूदा value सुरक्षित रखी जाती है। इससे app startup code development-friendly व्यवहार चुन सकता है, जबकि आपको `staging` जैसा app-specific environment देने की अनुमति मिलती है। + +Conventional `FASTAPI_ENV` values `development` और `production` हैं। `fastapi run` वर्तमान में `FASTAPI_ENV` को unchanged छोड़ देता है, इसलिए अगर आपके ऐप को production mode detect करने की ज़रूरत है तो इसे स्पष्ट रूप से set करें। + ## `fastapi run` { #fastapi-run } `fastapi run` execute करने से FastAPI production mode में शुरू होता है। diff --git a/docs/hi/docs/features.md b/docs/hi/docs/features.md index a3f5242..56d042d 100644 --- a/docs/hi/docs/features.md +++ b/docs/hi/docs/features.md @@ -19,7 +19,7 @@ Interactive API documentation और exploration web user interfaces। क् ![Swagger UI इंटरैक्शन](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* [**ReDoc**](https://github.com/Rebilly/ReDoc) के साथ वैकल्पिक API documentation। +* [**ReDoc**](https://github.com/Redocly/redoc) के साथ वैकल्पिक API documentation। ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) @@ -159,7 +159,7 @@ FastAPI में एक बेहद आसान, लेकिन बेहद ## Starlette की विशेषताएँ { #starlette-features } -**FastAPI** [**Starlette**](https://www.starlette.dev/) के साथ पूरी तरह compatible है (और उसी पर आधारित है)। इसलिए, आपके पास जो भी अतिरिक्त Starlette code है, वह भी काम करेगा। +**FastAPI** [**Starlette**](https://starlette.dev/) के साथ पूरी तरह compatible है (और उसी पर आधारित है)। इसलिए, आपके पास जो भी अतिरिक्त Starlette code है, वह भी काम करेगा। `FastAPI` वास्तव में `Starlette` का एक sub-class है। इसलिए, अगर आप पहले से Starlette जानते हैं या उपयोग करते हैं, तो अधिकांश functionality उसी तरह काम करेगी। @@ -177,7 +177,7 @@ FastAPI में एक बेहद आसान, लेकिन बेहद ## Pydantic की विशेषताएँ { #pydantic-features } -**FastAPI** [**Pydantic**](https://docs.pydantic.dev/) के साथ पूरी तरह compatible है (और उसी पर आधारित है)। इसलिए, आपके पास जो भी अतिरिक्त Pydantic code है, वह भी काम करेगा। +**FastAPI** [**Pydantic**](https://pydantic.dev/docs/) के साथ पूरी तरह compatible है (और उसी पर आधारित है)। इसलिए, आपके पास जो भी अतिरिक्त Pydantic code है, वह भी काम करेगा। इसमें Pydantic पर आधारित external libraries भी शामिल हैं, जैसे databases के लिए ORMs और ODMs। diff --git a/docs/hi/docs/help-fastapi.md b/docs/hi/docs/help-fastapi.md index bbeb2f1..a5e5dfd 100644 --- a/docs/hi/docs/help-fastapi.md +++ b/docs/hi/docs/help-fastapi.md @@ -45,20 +45,6 @@ Star जोड़ने से, अन्य users इसे अधिक आस * [**Bluesky** पर @tiangolo.com](https://bsky.app/profile/tiangolo.com) * [**LinkedIn** पर @tiangolo](https://www.linkedin.com/in/tiangolo/). -## GitHub में प्रश्नों के साथ दूसरों की मदद करें { #help-others-with-questions-in-github } - -आप [GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered) में दूसरों के प्रश्नों में मदद करने की कोशिश कर सकते हैं। - -कई मामलों में आपको उन प्रश्नों का उत्तर पहले से पता हो सकता है। 🤓 - -यदि आप बहुत से लोगों के प्रश्नों में उनकी मदद कर रहे हैं, तो आप आधिकारिक [FastAPI Expert](fastapi-people.md#fastapi-experts) बन जाएंगे। 🎉 - -बस याद रखें, सबसे महत्वपूर्ण बात है: विनम्र रहने की कोशिश करें। 🤗 - -### मदद कैसे करें { #how-to-help } - -यहाँ [मदद कैसे करें वाली गाइड](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github) का पालन करें। - ## प्रश्न पूछें { #ask-questions } आप GitHub repository में [एक नया प्रश्न बना सकते हैं](https://github.com/fastapi/fastapi/discussions/new?category=questions), उदाहरण के लिए: @@ -68,7 +54,7 @@ Star जोड़ने से, अन्य users इसे अधिक आस ## Chat से जुड़ें { #join-the-chat } -👥 [Discord chat server](https://discord.gg/VQjSZaeJmf) 👥 से जुड़ें और FastAPI community में दूसरों के साथ बातचीत करें। +👥 [Discord chat server](https://discord.com/invite/VQjSZaeJmf) 👥 से जुड़ें और FastAPI community में दूसरों के साथ बातचीत करें। /// tip | सुझाव @@ -85,3 +71,9 @@ Chat का उपयोग केवल अन्य सामान्य ब GitHub में, template आपको सही प्रश्न लिखने में मार्गदर्शन करेगा ताकि आप अधिक आसानी से अच्छा उत्तर पा सकें, या पूछने से पहले ही समस्या को स्वयं भी हल कर सकें। Chat systems में बातचीत GitHub जितनी आसानी से searchable भी नहीं होती, वे खो जाती हैं। + +## FastAPI Cloud आज़माएँ { #try-fastapi-cloud } + +FastAPI और friends के लिए मुख्य funding [**FastAPI Cloud**](https://fastapicloud.com) से आती है, यह FastAPI applications को सरल और तेज़ तरीके से, एक ही command, `fastapi deploy`, के साथ deploy करने का platform है। + +FastAPI Cloud उसी team द्वारा बनाया गया है जो FastAPI के पीछे है। आप इसे आज़मा सकते हैं और अपने projects के लिए इस पर विचार कर सकते हैं। diff --git a/docs/hi/docs/history-design-future.md b/docs/hi/docs/history-design-future.md index a3b97d1..90d1a1c 100644 --- a/docs/hi/docs/history-design-future.md +++ b/docs/hi/docs/history-design-future.md @@ -54,11 +54,11 @@ ## Requirements { #requirements } -कई विकल्पों का परीक्षण करने के बाद, मैंने तय किया कि मैं इसके लाभों के लिए [**Pydantic**](https://docs.pydantic.dev/) का उपयोग करूँगा। +कई विकल्पों का परीक्षण करने के बाद, मैंने तय किया कि मैं इसके लाभों के लिए [**Pydantic**](https://pydantic.dev/docs/) का उपयोग करूँगा। फिर मैंने इसमें योगदान दिया, ताकि इसे JSON Schema के साथ पूरी तरह compliant बनाया जा सके, constraint declarations को define करने के अलग-अलग तरीकों का समर्थन किया जा सके, और कई editors में tests के आधार पर editor support (type checks, autocompletion) को बेहतर बनाया जा सके। -Development के दौरान, मैंने [**Starlette**](https://www.starlette.dev/) में भी योगदान दिया, जो दूसरी मुख्य requirement थी। +Development के दौरान, मैंने [**Starlette**](https://starlette.dev/) में भी योगदान दिया, जो दूसरी मुख्य requirement थी। ## Development { #development } diff --git a/docs/hi/docs/how-to/custom-request-and-route.md b/docs/hi/docs/how-to/custom-request-and-route.md index 97743d1..1e22e0e 100644 --- a/docs/hi/docs/how-to/custom-request-and-route.md +++ b/docs/hi/docs/how-to/custom-request-and-route.md @@ -66,7 +66,7 @@ और ये दो चीजें, `scope` और `receive`, नई `Request` instance बनाने के लिए आवश्यक हैं। -`Request` के बारे में अधिक जानने के लिए [Requests के बारे में Starlette के docs](https://www.starlette.dev/requests/) देखें। +`Request` के बारे में अधिक जानने के लिए [Requests के बारे में Starlette के docs](https://starlette.dev/requests/) देखें। /// diff --git a/docs/hi/docs/how-to/extending-openapi.md b/docs/hi/docs/how-to/extending-openapi.md index f3bebfa..d9b04d8 100644 --- a/docs/hi/docs/how-to/extending-openapi.md +++ b/docs/hi/docs/how-to/extending-openapi.md @@ -45,7 +45,7 @@ parameter `summary` OpenAPI 3.1.0 और उससे ऊपर में उप ऊपर दी गई जानकारी का उपयोग करके, आप OpenAPI schema generate करने और अपनी ज़रूरत के अनुसार प्रत्येक हिस्से को override करने के लिए उसी utility function का उपयोग कर सकते हैं। -उदाहरण के लिए, आइए [custom logo शामिल करने के लिए ReDoc का OpenAPI extension](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo) जोड़ें। +उदाहरण के लिए, आइए [custom logo शामिल करने के लिए ReDoc का OpenAPI extension](https://github.com/Redocly/redoc/blob/main/docs/redoc-vendor-extensions.md#x-logo) जोड़ें। ### सामान्य **FastAPI** { #normal-fastapi } diff --git a/docs/hi/docs/how-to/graphql.md b/docs/hi/docs/how-to/graphql.md index 7a8fbdb..b74d213 100644 --- a/docs/hi/docs/how-to/graphql.md +++ b/docs/hi/docs/how-to/graphql.md @@ -21,7 +21,7 @@ Common **web APIs** की तुलना में इसके **advantages** * [Strawberry](https://strawberry.rocks/) 🍓 * [FastAPI के लिए docs](https://strawberry.rocks/docs/integrations/fastapi) के साथ * [Ariadne](https://ariadnegraphql.org/) - * [FastAPI के लिए docs](https://ariadnegraphql.org/docs/fastapi-integration) के साथ + * [FastAPI के लिए docs](https://ariadnegraphql.org/server/Integrations/fastapi-integration) के साथ * [Tartiflette](https://tartiflette.io/) * ASGI integration प्रदान करने के लिए [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) के साथ * [Graphene](https://graphene-python.org/) diff --git a/docs/hi/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/hi/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index 68bc07e..847d50c 100644 --- a/docs/hi/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/hi/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -24,7 +24,7 @@ Pydantic team ने **Python 3.14** से शुरू करते हुए, ## आधिकारिक गाइड { #official-guide } -Pydantic के पास v1 से v2 के लिए एक आधिकारिक [Migration Guide](https://docs.pydantic.dev/latest/migration/) है। +Pydantic के पास v1 से v2 के लिए एक आधिकारिक [Migration Guide](https://pydantic.dev/docs/validation/latest/get-started/migration/) है। इसमें यह भी शामिल है कि क्या बदला है, validations अब कैसे अधिक सही और strict हैं, संभावित caveats आदि। diff --git a/docs/hi/docs/index.md b/docs/hi/docs/index.md index cbc81db..c0ead33 100644 --- a/docs/hi/docs/index.md +++ b/docs/hi/docs/index.md @@ -13,7 +13,7 @@ include_yaml: FastAPI

- FastAPI फ़्रेमवर्क, उच्च प्रदर्शन, सीखने में आसान, कोड लिखने में तेज़, प्रोडक्शन के लिए तैयार + FastAPI framework, उच्च प्रदर्शन, सीखने में आसान, कोड लिखने में तेज़, production के लिए तैयार

@@ -23,7 +23,7 @@ include_yaml: कवरेज - पैकेज संस्करण + package संस्करण समर्थित Python संस्करण @@ -38,20 +38,20 @@ include_yaml: --- -FastAPI एक आधुनिक, तेज़ (उच्च-प्रदर्शन) वेब फ़्रेमवर्क है जो मानक Python type hints के आधार पर Python से APIs बनाने के लिए है। +FastAPI एक आधुनिक, तेज़ (उच्च-प्रदर्शन) web framework है जो standard Python type hints के आधार पर Python से APIs बनाने के लिए है। मुख्य विशेषताएँ: -* **तेज़**: बहुत उच्च प्रदर्शन, **NodeJS** और **Go** के समकक्ष (Starlette और Pydantic की बदौलत)। [उपलब्ध सबसे तेज़ Python फ़्रेमवर्क्स में से एक](#performance)। -* **कोड लिखने में तेज़**: फ़ीचर्स विकसित करने की गति लगभग 200% से 300% तक बढ़ाएँ। * -* **कम बग्स**: मानवीय (डेवलपर) त्रुटियों में लगभग 40% की कमी। * -* **सहज**: बेहतरीन एडिटर सपोर्ट। हर जगह ऑटो-कम्प्लीट। डिबगिंग में कम समय। -* **आसान**: इस्तेमाल और सीखने में आसान। दस्तावेज़ पढ़ने में कम समय। -* **संक्षिप्त**: कोड डुप्लीकेशन को न्यूनतम करें। प्रत्येक parameter declaration से कई फ़ीचर्स। कम बग्स। -* **मजबूत**: प्रोडक्शन-रेडी कोड प्राप्त करें। स्वतः इंटरैक्टिव दस्तावेज़ीकरण के साथ। -* **मानकों पर आधारित**: APIs के खुले मानकों पर आधारित (और पूर्णतः अनुकूल): [OpenAPI](https://github.com/OAI/OpenAPI-Specification) (जिसे पहले Swagger कहा जाता था) और [JSON Schema](https://json-schema.org/)। +* **तेज़**: बहुत उच्च प्रदर्शन, **NodeJS** और **Go** के समकक्ष (Starlette और Pydantic की बदौलत)। [उपलब्ध सबसे तेज़ Python frameworks में से एक](#performance)। +* **कोड लिखने में तेज़**: features विकसित करने की गति लगभग 200% से 300% तक बढ़ाएँ। * +* **कम बग्स**: मानवीय (developer) त्रुटियों में लगभग 40% की कमी। * +* **सहज**: बेहतरीन editor support। हर जगह Completion। डिबगिंग में कम समय। +* **आसान**: इस्तेमाल और सीखने में आसान होने के लिए डिज़ाइन किया गया। docs पढ़ने में कम समय। +* **संक्षिप्त**: कोड डुप्लीकेशन को न्यूनतम करें। प्रत्येक parameter declaration से कई features। कम बग्स। +* **मजबूत**: production-ready कोड प्राप्त करें। स्वतः इंटरैक्टिव दस्तावेज़ीकरण के साथ। +* **standards-आधारित**: APIs के open standards पर आधारित (और पूर्णतः अनुकूल): [OpenAPI](https://github.com/OAI/OpenAPI-Specification) (जिसे पहले Swagger कहा जाता था) और [JSON Schema](https://json-schema.org/)। -* आंतरिक डेवलपमेंट टीम द्वारा प्रोडक्शन ऐप्स बनाते समय किए गए परीक्षणों के आधार पर अनुमान। +* आंतरिक development team द्वारा production applications बनाते समय किए गए परीक्षणों के आधार पर अनुमान। ## प्रायोजक { #sponsors } @@ -105,19 +105,19 @@ FastAPI एक आधुनिक, तेज़ (उच्च-प्रदर्

-
"मैं इन दिनों FastAPI का बहुत उपयोग कर रहा/रही हूँ। वास्तव में मैं अपनी टीम की Microsoft में ML सेवाओं के लिए इसे उपयोग करने की योजना बना रहा/रही हूँ। इनमें से कुछ को मुख्य Windows प्रोडक्ट और कुछ Office प्रोडक्ट्स में इंटीग्रेट किया जा रहा है।"
+
"मैं इन दिनों FastAPI का बहुत उपयोग कर रहा/रही हूँ। वास्तव में मैं अपनी team की Microsoft में ML सेवाओं के लिए इसे उपयोग करने की योजना बना रहा/रही हूँ। इनमें से कुछ को मुख्य Windows product और कुछ Office products में इंटीग्रेट किया जा रहा है।"
— कबीर खान, Microsoft (संदर्भ)
@@ -125,25 +125,25 @@ FastAPI एक आधुनिक, तेज़ (उच्च-प्रदर्
-"_[...] मैं इन दिनों **FastAPI** का बहुत उपयोग कर रहा/रही हूँ। [...] वास्तव में मैं अपनी टीम की **Microsoft में ML सेवाओं** के लिए इसे उपयोग करने की योजना बना रहा/रही हूँ। इनमें से कुछ को मुख्य **Windows** प्रोडक्ट और कुछ **Office** प्रोडक्ट्स में इंटीग्रेट किया जा रहा है._" +"_[...] मैं इन दिनों **FastAPI** का बहुत उपयोग कर रहा/रही हूँ। [...] वास्तव में मैं अपनी team की **Microsoft में ML सेवाओं** के लिए इसे उपयोग करने की योजना बना रहा/रही हूँ। इनमें से कुछ को मुख्य **Windows** product और कुछ **Office** products में इंटीग्रेट किया जा रहा है._"
कबीर खान - Microsoft (संदर्भ)
--- -"_हमने **FastAPI** लाइब्रेरी अपनाई ताकि एक **REST** सर्वर स्पॉन किया जा सके जिसे **अनुमानों** को प्राप्त करने के लिए क्वेरी किया जा सके। [Ludwig के लिए]_" +"_हमने **FastAPI** लाइब्रेरी अपनाई ताकि एक **REST** सर्वर स्पॉन किया जा सके जिसे **अनुमानों** को प्राप्त करने के लिए query किया जा सके। [Ludwig के लिए]_" -
पिएरो मोलिनो, यारोस्लाव डुडिन, और साई सुमंत मिर्याला - Uber (संदर्भ)
+
पिएरो मोलिनो, यारोस्लाव डुडिन, और साई सुमंत मिर्याला - Uber (संदर्भ)
--- -"_**Netflix** हमारे **संकट प्रबंधन** ऑर्केस्ट्रेशन फ़्रेमवर्क: **Dispatch** के ओपन-सोर्स रिलीज़ की घोषणा करते हुए प्रसन्न है! [**FastAPI** के साथ बनाया गया]_" +"_**Netflix** हमारे **संकट प्रबंधन** ऑर्केस्ट्रेशन framework: **Dispatch** के ओपन-सोर्स रिलीज़ की घोषणा करते हुए प्रसन्न है! [**FastAPI** के साथ बनाया गया]_"
केविन ग्लिसन, मार्क विलानोवा, फॉरेस्ट मॉन्सेन - Netflix (संदर्भ)
--- -"_यदि कोई प्रोडक्शन Python API बनाना चाहता है, तो मैं **FastAPI** की अत्यधिक अनुशंसा करूंगा/करूंगी। यह **सुंदरता से डिज़ाइन** किया गया है, **उपयोग में सरल** है और **बेहद स्केलेबल** है, यह हमारी API-फ़र्स्ट डेवलपमेंट रणनीति का **मुख्य घटक** बन गया है और हमारे Virtual TAC Engineer जैसे कई ऑटोमेशन्स और सेवाओं को चला रहा है._" +"_यदि कोई production Python API बनाना चाहता है, तो मैं **FastAPI** की अत्यधिक अनुशंसा करूंगा/करूंगी। यह **सुंदरता से डिज़ाइन** किया गया है, **उपयोग में सरल** है और **बेहद स्केलेबल** है, यह हमारी API first development रणनीति का **मुख्य घटक** बन गया है और हमारे Virtual TAC Engineer जैसे कई ऑटोमेशन्स और सेवाओं को चला रहा है._"
डीयोन पिल्सबरी - Cisco (संदर्भ)
@@ -151,12 +151,6 @@ FastAPI एक आधुनिक, तेज़ (उच्च-प्रदर्
-## FastAPI कॉन्फ़ { #fastapi-conf } - -[**FastAPI Conf '26**](https://fastapiconf.com) **28 अक्टूबर, 2026** को **एम्स्टर्डम, नीदरलैंड्स** में हो रही है। सब कुछ FastAPI के बारे में, सीधे स्रोत से। 🎤 - -FastAPI Conf '26 - 28 अक्टूबर, 2026 - एम्स्टर्डम, NL - ## FastAPI मिनी डॉक्यूमेंट्री { #fastapi-mini-documentary } साल 2025 के अंत में एक [FastAPI मिनी डॉक्यूमेंट्री](https://www.youtube.com/watch?v=mpR8ngthqiE) रिलीज़ हुई, आप इसे ऑनलाइन देख सकते हैं: @@ -167,7 +161,7 @@ FastAPI एक आधुनिक, तेज़ (उच्च-प्रदर् -यदि आप वेब API के बजाय टर्मिनल में उपयोग होने वाला CLI ऐप बना रहे हैं, तो [**Typer**](https://typer.tiangolo.com/) देखें। +यदि आप web API के बजाय टर्मिनल में उपयोग होने वाला CLI ऐप बना रहे हैं, तो [**Typer**](https://typer.tiangolo.com/) देखें। **Typer**, FastAPI का छोटा भाई/बहन है। और इसका उद्देश्य **CLIs का FastAPI** होना है। ⌨️ 🚀 @@ -175,17 +169,17 @@ FastAPI एक आधुनिक, तेज़ (उच्च-प्रदर् FastAPI दिग्गजों के कंधों पर खड़ा है: -* वेब हिस्सों के लिए [Starlette](https://www.starlette.dev/)। -* डेटा हिस्सों के लिए [Pydantic](https://docs.pydantic.dev/)। +* web हिस्सों के लिए [Starlette](https://starlette.dev/)। +* data हिस्सों के लिए [Pydantic](https://pydantic.dev/docs/)। -## स्थापना { #installation } +## Installation { #installation } -एक [वर्चुअल एन्वायरनमेंट](https://fastapi.tiangolo.com/hi/virtual-environments/) बनाएँ और सक्रिय करें, और फिर FastAPI स्थापित करें: +पहले, [`uv` install करें](https://docs.astral.sh/uv/getting-started/installation/), और फिर अपने project में FastAPI जोड़ें:
```console -$ pip install "fastapi[standard]" +$ uv add "fastapi[standard]" ---> 100% ``` @@ -194,11 +188,13 @@ $ pip install "fastapi[standard]" **नोट**: सुनिश्चित करें कि आप सभी टर्मिनलों में काम करने के लिए `"fastapi[standard]"` को उद्धरण-चिह्नों में रखें। +यदि आप `pip` का उपयोग करना पसंद करते हैं, तो virtual environment के अंदर `fastapi[standard]` install करें। वैकल्पिक चरणों के लिए [installation guide](tutorial/#install-fastapi) देखें। + ## उदाहरण { #example } ### इसे बनाएँ { #create-it } -`main.py` फ़ाइल बनाएँ और इसमें लिखें: +`main.py` file बनाएँ, जिसमें: ```Python from fastapi import FastAPI @@ -239,7 +235,7 @@ async def read_item(item_id: int, q: str | None = None): **नोट**: -यदि आप नहीं जानते, तो _"जल्दी में?"_ सेक्शन देखें: दस्तावेज़ में [`async` और `await`](https://fastapi.tiangolo.com/hi/async/#in-a-hurry) के बारे में। +यदि आप नहीं जानते, तो docs में [`async` और `await`](https://fastapi.tiangolo.com/hi/async/#in-a-hurry) के बारे में _"जल्दी में?"_ section देखें।
@@ -250,7 +246,7 @@ async def read_item(item_id: int, q: str | None = None):
```console -$ fastapi dev +$ uv run fastapi dev ╭────────── FastAPI CLI - Development mode ───────────╮ │ │ @@ -277,11 +273,11 @@ INFO: Application startup complete.
fastapi dev कमांड के बारे में... -`fastapi dev` कमांड आपका `main.py` फ़ाइल स्वतः पढ़ता है, उसमें **FastAPI** ऐप का पता लगाता है, और [Uvicorn](https://www.uvicorn.dev) का उपयोग करके सर्वर शुरू करता है। +`fastapi dev` कमांड आपका `main.py` file स्वतः पढ़ता है, उसमें **FastAPI** ऐप का पता लगाता है, और [Uvicorn](https://uvicorn.dev) का उपयोग करके सर्वर शुरू करता है। -डिफ़ॉल्ट रूप से, `fastapi dev` लोकल डेवलपमेंट के लिए auto-reload सक्षम करके शुरू होगा। +default रूप से, `fastapi dev` लोकल development के लिए auto-reload सक्षम करके शुरू होगा। -आप इसके बारे में और पढ़ सकते हैं: [FastAPI CLI दस्तावेज़](https://fastapi.tiangolo.com/hi/fastapi-cli/) में। +आप इसके बारे में और पढ़ सकते हैं: [FastAPI CLI docs](https://fastapi.tiangolo.com/hi/fastapi-cli/) में।
@@ -289,7 +285,7 @@ INFO: Application startup complete. अपने ब्राउज़र में [http://127.0.0.1:8000/items/5?q=somequery](http://127.0.0.1:8000/items/5?q=somequery) खोलें। -आपको JSON प्रतिक्रिया इस प्रकार दिखेगी: +आपको JSON response इस प्रकार दिखेगी: ```JSON {"item_id": 5, "q": "somequery"} @@ -297,7 +293,7 @@ INFO: Application startup complete. आपने पहले ही एक API बना ली है जो: -* _paths_ `/` और `/items/{item_id}` पर HTTP अनुरोध स्वीकार करती है। +* _paths_ `/` और `/items/{item_id}` पर HTTP requests स्वीकार करती है। * दोनों _paths_ `GET` operations लेती हैं (जिन्हें HTTP _methods_ भी कहा जाता है)। * _path_ `/items/{item_id}` में एक _path parameter_ `item_id` है जो `int` होना चाहिए। * _path_ `/items/{item_id}` में एक वैकल्पिक `str` _query parameter_ `q` है। @@ -314,15 +310,15 @@ INFO: Application startup complete. और अब, [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) पर जाएँ। -आपको वैकल्पिक स्वचालित दस्तावेज़ीकरण दिखेगा (जो [ReDoc](https://github.com/Rebilly/ReDoc) द्वारा प्रदान किया जाता है): +आपको वैकल्पिक स्वचालित दस्तावेज़ीकरण दिखेगा (जो [ReDoc](https://github.com/Redocly/redoc) द्वारा प्रदान किया जाता है): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) ## उदाहरण उन्नयन { #example-upgrade } -अब `PUT` अनुरोध से body प्राप्त करने के लिए `main.py` फ़ाइल संशोधित करें। +अब `PUT` request से body प्राप्त करने के लिए `main.py` file संशोधित करें। -Pydantic की बदौलत, body को मानक Python प्रकारों से घोषित करें। +Pydantic की बदौलत, body को standard Python प्रकारों से घोषित करें। ```Python hl_lines="2 7-10 23-25" from fastapi import FastAPI @@ -378,15 +374,15 @@ def update_item(item_id: int, item: Item): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) -### पुनरावलोकन { #recap } +### Recap { #recap } -संक्षेप में, आप parameters, body, आदि के प्रकार फ़ंक्शन parameters के रूप में **एक बार** घोषित करते हैं। +संक्षेप में, आप parameters, body, आदि के प्रकार function parameters के रूप में **एक बार** घोषित करते हैं। -आप यह मानक आधुनिक Python प्रकारों से करते हैं। +आप यह standard आधुनिक Python प्रकारों से करते हैं। आपको किसी नई सिंटैक्स, किसी विशेष लाइब्रेरी के methods या classes, आदि सीखने की आवश्यकता नहीं है। -बस मानक **Python**। +बस standard **Python**। उदाहरण के लिए, एक `int` के लिए: @@ -394,7 +390,7 @@ def update_item(item_id: int, item: Item): item_id: int ``` -या एक अधिक जटिल `Item` मॉडल के लिए: +या एक अधिक जटिल `Item` model के लिए: ```Python item: Item @@ -402,13 +398,13 @@ item: Item ...और केवल उसी एक घोषणा के साथ आपको मिलता है: -* एडिटर सपोर्ट, जिसमें शामिल है: - * कम्प्लीशन। - * प्रकार जाँच। -* डेटा का वैधीकरण: - * जब डेटा अमान्य हो तो स्वतः और स्पष्ट त्रुटियाँ। +* Editor support, जिसमें शामिल है: + * Completion। + * Type checks। +* data का वैधीकरण: + * जब data अमान्य हो तो स्वतः और स्पष्ट त्रुटियाँ। * गहराई से nested JSON objects के लिए भी वैधीकरण। -* इनपुट डेटा का रूपांतरण: नेटवर्क से Python डेटा और प्रकारों में। इनमें से पढ़ना: +* इनपुट data का Conversion: नेटवर्क से Python data और प्रकारों में। इनमें से पढ़ना: * JSON। * Path parameters। * Query parameters। @@ -416,11 +412,11 @@ item: Item * Headers। * Forms। * Files। -* आउटपुट डेटा का रूपांतरण: Python डेटा और प्रकारों से नेटवर्क डेटा (JSON के रूप में) में: - * Python प्रकारों का रूपांतरण (`str`, `int`, `float`, `bool`, `list`, आदि)। +* आउटपुट data का Conversion: Python data और प्रकारों से नेटवर्क data (JSON के रूप में) में: + * Python प्रकारों का conversion (`str`, `int`, `float`, `bool`, `list`, आदि)। * `datetime` ऑब्जेक्ट्स। * `UUID` ऑब्जेक्ट्स। - * डेटाबेस मॉडल्स। + * डेटाबेस models। * ...और बहुत कुछ। * स्वचालित इंटरैक्टिव API दस्तावेज़ीकरण, जिनमें 2 वैकल्पिक यूज़र इंटरफ़ेस शामिल हैं: * Swagger UI। @@ -430,22 +426,22 @@ item: Item पिछले कोड उदाहरण पर लौटते हुए, **FastAPI** यह करेगा: -* `GET` और `PUT` अनुरोधों के लिए path में `item_id` है, यह सत्यापित करेगा। -* `GET` और `PUT` अनुरोधों के लिए `item_id` का प्रकार `int` है, यह सत्यापित करेगा। +* `GET` और `PUT` requests के लिए path में `item_id` है, यह सत्यापित करेगा। +* `GET` और `PUT` requests के लिए `item_id` का प्रकार `int` है, यह सत्यापित करेगा। * यदि नहीं है, तो क्लाइंट को एक उपयोगी, स्पष्ट त्रुटि दिखाई देगी। -* `GET` अनुरोधों के लिए यह जाँच करेगा कि `q` नाम का एक वैकल्पिक query parameter है (जैसे `http://127.0.0.1:8000/items/foo?q=somequery`)। +* `GET` requests के लिए यह जाँच करेगा कि `q` नाम का एक वैकल्पिक query parameter है (जैसे `http://127.0.0.1:8000/items/foo?q=somequery`)। * क्योंकि `q` parameter `= None` के साथ घोषित है, यह वैकल्पिक है। - * `None` के बिना यह आवश्यक होता (जैसे `PUT` के मामले में body आवश्यक है)। -* `/items/{item_id}` पर `PUT` अनुरोधों के लिए, body को JSON के रूप में पढ़ेगा: - * यह जाँचेगा कि एक आवश्यक attribute `name` है जो `str` होना चाहिए। - * यह जाँचेगा कि एक आवश्यक attribute `price` है जो `float` होना चाहिए। + * `None` के बिना यह required होता (जैसे `PUT` के मामले में body required है)। +* `/items/{item_id}` पर `PUT` requests के लिए, body को JSON के रूप में पढ़ेगा: + * यह जाँचेगा कि एक required attribute `name` है जो `str` होना चाहिए। + * यह जाँचेगा कि एक required attribute `price` है जो `float` होना चाहिए। * यह जाँचेगा कि एक वैकल्पिक attribute `is_offer` है, जो यदि मौजूद है तो `bool` होना चाहिए। * यह सब गहराई से nested JSON objects के लिए भी काम करेगा। -* JSON से और JSON में स्वतः रूपांतरण। +* JSON से और JSON में स्वतः convert करेगा। * हर चीज़ को OpenAPI के साथ दस्तावेज़ित करेगा, जिसे निम्न द्वारा उपयोग किया जा सकता है: * इंटरैक्टिव दस्तावेज़ीकरण प्रणालियाँ। * कई भाषाओं के लिए स्वचालित क्लाइंट कोड जनरेशन प्रणालियाँ। -* सीधे 2 इंटरैक्टिव दस्तावेज़ीकरण वेब इंटरफेसेज़ प्रदान करेगा। +* सीधे 2 इंटरैक्टिव दस्तावेज़ीकरण web interfaces प्रदान करेगा। --- @@ -469,35 +465,35 @@ item: Item ... "item_price": item.price ... ``` -...और देखें कि आपका एडिटर attributes को कैसे auto-complete करेगा और उनके प्रकार जानेगा: +...और देखें कि आपका editor attributes को कैसे auto-complete करेगा और उनके प्रकार जानेगा: ![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) -अधिक फ़ीचर्स सहित एक अधिक सम्पूर्ण उदाहरण के लिए, ट्यूटोरियल - यूज़र गाइड देखें। +अधिक features सहित एक अधिक सम्पूर्ण उदाहरण के लिए, ट्यूटोरियल - यूज़र गाइड देखें। **स्पॉइलर अलर्ट**: ट्यूटोरियल - यूज़र गाइड में शामिल है: * विभिन्न स्थानों से **parameters** की घोषणा: **headers**, **cookies**, **form fields** और **files**। * `maximum_length` या `regex` जैसी **validation constraints** कैसे सेट करें। -* एक बहुत शक्तिशाली और उपयोग में आसान **डिपेंडेंसी इंजेक्शन** सिस्टम। +* एक बहुत शक्तिशाली और उपयोग में आसान **Dependency Injection** सिस्टम। * सुरक्षा और प्रमाणीकरण, जिसमें **OAuth2** के साथ **JWT tokens** और **HTTP Basic** auth का समर्थन शामिल है। -* **गहराई से nested JSON मॉडल्स** घोषित करने की अधिक उन्नत (पर समान रूप से आसान) तकनीकें (Pydantic की बदौलत)। +* **गहराई से nested JSON models** घोषित करने की अधिक उन्नत (पर समान रूप से आसान) तकनीकें (Pydantic की बदौलत)। * [Strawberry](https://strawberry.rocks) और अन्य लाइब्रेरीज़ के साथ **GraphQL** एकीकरण। -* कई अतिरिक्त फ़ीचर्स (Starlette की बदौलत) जैसे: +* कई अतिरिक्त features (Starlette की बदौलत) जैसे: * **WebSockets** * HTTPX और `pytest` पर आधारित अत्यंत आसान टेस्ट्स * **CORS** * **Cookie Sessions** * ...आदि। -### अपनी ऐप परिनियोजित करें (वैकल्पिक) { #deploy-your-app-optional } +### अपनी ऐप deploy करें (वैकल्पिक) { #deploy-your-app-optional } -आप वैकल्पिक रूप से अपनी FastAPI ऐप को [FastAPI Cloud](https://fastapicloud.com) पर एक ही कमांड से डिप्लॉय कर सकते हैं। 🚀 +आप वैकल्पिक रूप से अपनी FastAPI ऐप को [FastAPI Cloud](https://fastapicloud.com) पर एक ही कमांड से deploy कर सकते हैं। 🚀
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -508,31 +504,31 @@ Deploying to FastAPI Cloud...
-CLI आपकी FastAPI एप्लिकेशन को स्वतः पहचान लेगा और उसे क्लाउड पर डिप्लॉय करेगा। यदि आप logged in नहीं हैं, तो प्रमाणीकरण प्रक्रिया पूरी करने के लिए आपका ब्राउज़र खुलेगा। +CLI आपकी FastAPI application को स्वतः पहचान लेगा और उसे क्लाउड पर deploy करेगा। यदि आप logged in नहीं हैं, तो प्रमाणीकरण प्रक्रिया पूरी करने के लिए आपका ब्राउज़र खुलेगा। बस इतना ही! अब आप उस URL पर अपनी ऐप एक्सेस कर सकते हैं। ✨ #### FastAPI Cloud के बारे में { #about-fastapi-cloud } -**[FastAPI Cloud](https://fastapicloud.com)** को **FastAPI** के ही लेखक और टीम ने बनाया है। +**[FastAPI Cloud](https://fastapicloud.com)** को **FastAPI** के ही लेखक और team ने बनाया है। -यह न्यूनतम प्रयास में किसी API को **बनाने**, **डिप्लॉय** करने और **एक्सेस** करने की प्रक्रिया को सरल बनाता है। +यह न्यूनतम प्रयास में किसी API को **बनाने**, **deploy** करने और **एक्सेस** करने की प्रक्रिया को सरल बनाता है। -यह FastAPI के साथ ऐप्स बनाने के उसी **डेवलपर अनुभव** को उन्हें क्लाउड में **डिप्लॉय** करने तक लाता है। 🎉 +यह FastAPI के साथ ऐप्स बनाने के उसी **developer experience** को उन्हें क्लाउड में **deploy** करने तक लाता है। 🎉 -FastAPI Cloud, *FastAPI and friends* ओपन सोर्स प्रोजेक्ट्स के लिए मुख्य प्रायोजक और फंडिंग प्रदाता है। ✨ +FastAPI Cloud, *FastAPI and friends* ओपन सोर्स projects के लिए मुख्य प्रायोजक और फंडिंग प्रदाता है। ✨ -#### अन्य क्लाउड प्रदाताओं पर डिप्लॉय करें { #deploy-to-other-cloud-providers } +#### अन्य क्लाउड प्रदाताओं पर deploy करें { #deploy-to-other-cloud-providers } -FastAPI ओपन सोर्स है और मानकों पर आधारित है। आप FastAPI ऐप्स को किसी भी क्लाउड प्रदाता पर डिप्लॉय कर सकते हैं। +FastAPI ओपन सोर्स है और standards पर आधारित है। आप FastAPI ऐप्स को किसी भी क्लाउड प्रदाता पर deploy कर सकते हैं। -अपने क्लाउड प्रदाता के गाइड्स का पालन करें और उनके साथ FastAPI ऐप्स डिप्लॉय करें। 🤓 +अपने क्लाउड प्रदाता के गाइड्स का पालन करें और उनके साथ FastAPI ऐप्स deploy करें। 🤓 ## प्रदर्शन { #performance } -स्वतंत्र TechEmpower बेंचमार्क दिखाते हैं कि Uvicorn के तहत चलने वाले **FastAPI** एप्लीकेशन्स [उपलब्ध सबसे तेज़ Python फ़्रेमवर्क्स में से एक](https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7) हैं, केवल Starlette और Uvicorn (जो FastAPI द्वारा आंतरिक रूप से उपयोग किए जाते हैं) से नीचे। (*) +स्वतंत्र TechEmpower बेंचमार्क दिखाते हैं कि Uvicorn के तहत चलने वाले **FastAPI** applications [उपलब्ध सबसे तेज़ Python frameworks में से एक](https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7) हैं, केवल Starlette और Uvicorn (जो FastAPI द्वारा आंतरिक रूप से उपयोग किए जाते हैं) से नीचे। (*) -इसके बारे में अधिक समझने के लिए, [बेंचमार्क्स](https://fastapi.tiangolo.com/hi/benchmarks/) सेक्शन देखें। +इसके बारे में अधिक समझने के लिए, [बेंचमार्क्स](https://fastapi.tiangolo.com/hi/benchmarks/) section देखें। ## निर्भरताएँ { #dependencies } @@ -540,7 +536,7 @@ FastAPI, Pydantic और Starlette पर निर्भर करता है ### `standard` निर्भरताएँ { #standard-dependencies } -जब आप `pip install "fastapi[standard]"` के साथ FastAPI स्थापित करते हैं, तो यह `standard` समूह की वैकल्पिक निर्भरताओं के साथ आता है: +जब आप `uv add "fastapi[standard]"` के साथ FastAPI install करते हैं, तो यह `standard` समूह की वैकल्पिक निर्भरताओं के साथ आता है: Pydantic द्वारा उपयोग किया गया: @@ -548,38 +544,38 @@ Pydantic द्वारा उपयोग किया गया: Starlette द्वारा उपयोग किया गया: -* [`httpx`](https://www.python-httpx.org) - यदि आप `TestClient` का उपयोग करना चाहते हैं तो आवश्यक। -* [`jinja2`](https://jinja.palletsprojects.com) - यदि आप डिफ़ॉल्ट टेम्पलेट कॉन्फ़िगरेशन का उपयोग करना चाहते हैं तो आवश्यक। -* [`python-multipart`](https://github.com/Kludex/python-multipart) - यदि आप फॉर्म "पार्सिंग" का समर्थन करना चाहते हैं, `request.form()` के साथ, तो आवश्यक। +* [`httpx`](https://www.python-httpx.org) - यदि आप `TestClient` का उपयोग करना चाहते हैं तो required। +* [`jinja2`](https://jinja.palletsprojects.com) - यदि आप default टेम्पलेट कॉन्फ़िगरेशन का उपयोग करना चाहते हैं तो required। +* [`python-multipart`](https://github.com/Kludex/python-multipart) - यदि आप form "parsing" का समर्थन करना चाहते हैं, `request.form()` के साथ, तो required। FastAPI द्वारा उपयोग किया गया: -* [`uvicorn`](https://www.uvicorn.dev) - वह सर्वर जो आपकी एप्लिकेशन को लोड और सर्व करता है। इसमें `uvicorn[standard]` शामिल है, जिसमें उच्च-प्रदर्शन सर्विंग के लिए कुछ निर्भरताएँ (जैसे `uvloop`) शामिल हैं। +* [`uvicorn`](https://uvicorn.dev) - उस सर्वर के लिए जो आपकी application को लोड और सर्व करता है। इसमें `uvicorn[standard]` शामिल है, जिसमें high performance serving के लिए कुछ निर्भरताएँ (जैसे `uvloop`) शामिल हैं। * `fastapi-cli[standard]` - `fastapi` कमांड प्रदान करने के लिए। - * इसमें `fastapi-cloud-cli` शामिल है, जो आपको अपनी FastAPI एप्लिकेशन को [FastAPI Cloud](https://fastapicloud.com) पर डिप्लॉय करने की अनुमति देता है। + * इसमें `fastapi-cloud-cli` शामिल है, जो आपको अपनी FastAPI application को [FastAPI Cloud](https://fastapicloud.com) पर deploy करने की अनुमति देता है। ### `standard` निर्भरताओं के बिना { #without-standard-dependencies } -यदि आप `standard` वैकल्पिक निर्भरताओं को शामिल नहीं करना चाहते, तो आप `pip install fastapi` के साथ स्थापित कर सकते हैं, `pip install "fastapi[standard]"` के बजाय। +यदि आप `standard` वैकल्पिक निर्भरताओं को शामिल नहीं करना चाहते, तो आप `uv add "fastapi[standard]"` के बजाय `uv add fastapi` के साथ install कर सकते हैं। ### `fastapi-cloud-cli` के बिना { #without-fastapi-cloud-cli } -यदि आप standard निर्भरताओं के साथ लेकिन `fastapi-cloud-cli` के बिना FastAPI स्थापित करना चाहते हैं, तो `pip install "fastapi[standard-no-fastapi-cloud-cli]"` के साथ स्थापित कर सकते हैं। +यदि आप standard निर्भरताओं के साथ लेकिन `fastapi-cloud-cli` के बिना FastAPI install करना चाहते हैं, तो `uv add "fastapi[standard-no-fastapi-cloud-cli]"` के साथ install कर सकते हैं। ### अतिरिक्त वैकल्पिक निर्भरताएँ { #additional-optional-dependencies } -कुछ अतिरिक्त निर्भरताएँ हैं जिन्हें आप स्थापित करना चाहेंगे। +कुछ अतिरिक्त निर्भरताएँ हैं जिन्हें आप install करना चाहेंगे। अतिरिक्त वैकल्पिक Pydantic निर्भरताएँ: -* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - सेटिंग्स प्रबंधन के लिए। -* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - Pydantic के साथ उपयोग करने के लिए अतिरिक्त प्रकारों हेतु। +* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) - सेटिंग्स प्रबंधन के लिए। +* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) - Pydantic के साथ उपयोग करने के लिए अतिरिक्त प्रकारों हेतु। अतिरिक्त वैकल्पिक FastAPI निर्भरताएँ: -* [`orjson`](https://github.com/ijl/orjson) - यदि आप `ORJSONResponse` उपयोग करना चाहते हैं तो आवश्यक। -* [`ujson`](https://github.com/esnme/ultrajson) - यदि आप `UJSONResponse` उपयोग करना चाहते हैं तो आवश्यक। +* [`orjson`](https://github.com/ijl/orjson) - यदि आप `ORJSONResponse` उपयोग करना चाहते हैं तो required। +* [`ujson`](https://github.com/ultrajson/ultrajson) - यदि आप `UJSONResponse` उपयोग करना चाहते हैं तो required। ## लाइसेंस { #license } -यह प्रोजेक्ट MIT लाइसेंस की शर्तों के अंतर्गत लाइसेंस प्राप्त है। +यह project MIT license की शर्तों के अंतर्गत लाइसेंस प्राप्त है। diff --git a/docs/hi/docs/project-generation.md b/docs/hi/docs/project-generation.md index 747e4da..8aea5c9 100644 --- a/docs/hi/docs/project-generation.md +++ b/docs/hi/docs/project-generation.md @@ -4,13 +4,13 @@ Templates आम तौर पर एक विशिष्ट setup के स आप शुरू करने के लिए इस template का उपयोग कर सकते हैं, क्योंकि इसमें आपके लिए बहुत सा initial setup, security, database और कुछ API endpoints पहले से तैयार हैं। -GitHub Repository: [Full Stack FastAPI Template](https://github.com/tiangolo/full-stack-fastapi-template) +GitHub Repository: [Full Stack FastAPI Template](https://github.com/fastapi/full-stack-fastapi-template) ## Full Stack FastAPI Template - Technology Stack और Features { #full-stack-fastapi-template-technology-stack-and-features } - ⚡ Python backend API के लिए [**FastAPI**](https://fastapi.tiangolo.com/hi)। - 🧰 Python SQL database interactions (ORM) के लिए [SQLModel](https://sqlmodel.tiangolo.com)। - - 🔍 data validation और settings management के लिए [Pydantic](https://docs.pydantic.dev), जिसका उपयोग FastAPI करता है। + - 🔍 data validation और settings management के लिए [Pydantic](https://pydantic.dev/docs/), जिसका उपयोग FastAPI करता है। - 💾 SQL database के रूप में [PostgreSQL](https://www.postgresql.org)। - 🚀 frontend के लिए [React](https://react.dev)। - 💃 TypeScript, hooks, Vite, और modern frontend stack के अन्य parts का उपयोग। diff --git a/docs/hi/docs/python-types.md b/docs/hi/docs/python-types.md index 86522e1..2192c91 100644 --- a/docs/hi/docs/python-types.md +++ b/docs/hi/docs/python-types.md @@ -269,7 +269,7 @@ Types के बिना, इसे हासिल करना लगभग ## Pydantic models { #pydantic-models } -[Pydantic](https://docs.pydantic.dev/) data validation करने के लिए एक Python library है। +[Pydantic](https://pydantic.dev/docs/) data validation करने के लिए एक Python library है। आप data की "shape" को attributes वाली classes के रूप में declare करते हैं। @@ -285,7 +285,7 @@ Official Pydantic docs से एक उदाहरण: /// note | नोट -अधिक जानने के लिए [Pydantic, इसके docs देखें](https://docs.pydantic.dev/)। +अधिक जानने के लिए [Pydantic, इसके docs देखें](https://pydantic.dev/docs/)। /// diff --git a/docs/hi/docs/tutorial/background-tasks.md b/docs/hi/docs/tutorial/background-tasks.md index f1c6856..54adcd3 100644 --- a/docs/hi/docs/tutorial/background-tasks.md +++ b/docs/hi/docs/tutorial/background-tasks.md @@ -61,9 +61,9 @@ background task के रूप में चलाने के लिए ए और फिर *path operation function* पर generate हुआ एक और background task `email` path parameter का उपयोग करके एक message लिखेगा। -## Technical Details { #technical-details } +## तकनीकी विवरण { #technical-details } -class `BackgroundTasks` सीधे [`starlette.background`](https://www.starlette.dev/background/) से आती है। +class `BackgroundTasks` सीधे [`starlette.background`](https://starlette.dev/background/) से आती है। इसे सीधे FastAPI में import/include किया गया है ताकि आप इसे `fastapi` से import कर सकें और गलती से `starlette.background` से alternative `BackgroundTask` (अंत में `s` के बिना) import करने से बच सकें। @@ -71,7 +71,7 @@ class `BackgroundTasks` सीधे [`starlette.background`](https://www.starle FastAPI में अकेले `BackgroundTask` का उपयोग करना अभी भी संभव है, लेकिन आपको अपने code में object बनाना होगा और उसे शामिल करते हुए Starlette `Response` return करना होगा। -आप [Background Tasks के लिए Starlette के official docs](https://www.starlette.dev/background/) में अधिक details देख सकते हैं। +आप [Background Tasks के लिए Starlette के official docs](https://starlette.dev/background/) में अधिक details देख सकते हैं। ## सावधानी { #caveat } diff --git a/docs/hi/docs/tutorial/bigger-applications.md b/docs/hi/docs/tutorial/bigger-applications.md index 263a593..14ef93a 100644 --- a/docs/hi/docs/tutorial/bigger-applications.md +++ b/docs/hi/docs/tutorial/bigger-applications.md @@ -487,7 +487,7 @@ from app.main import app आप command को path भी pass कर सकते हैं, जैसे: ```console -$ fastapi dev app/main.py +$ uv run fastapi dev app/main.py ``` लेकिन हर बार `fastapi` command call करते समय आपको सही path pass करना याद रखना होगा। @@ -503,7 +503,7 @@ $ fastapi dev app/main.py
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/hi/docs/tutorial/body-nested-models.md b/docs/hi/docs/tutorial/body-nested-models.md index 04ac55b..4200381 100644 --- a/docs/hi/docs/tutorial/body-nested-models.md +++ b/docs/hi/docs/tutorial/body-nested-models.md @@ -96,7 +96,7 @@ Pydantic model के हर attribute का एक type होता है। `str`, `int`, `float`, आदि जैसे सामान्य singular types के अलावा, आप अधिक complex singular types उपयोग कर सकते हैं जो `str` से inherit करते हैं। -आपके पास मौजूद सभी options देखने के लिए, [Pydantic का Type Overview](https://docs.pydantic.dev/latest/concepts/types/) देखें। अगले chapter में आपको कुछ उदाहरण दिखेंगे। +आपके पास मौजूद सभी options देखने के लिए, [Pydantic का Type Overview](https://pydantic.dev/docs/validation/latest/concepts/types/) देखें। अगले chapter में आपको कुछ उदाहरण दिखेंगे। उदाहरण के लिए, जैसा कि `Image` model में हमारे पास एक `url` field है, हम इसे `str` के बजाय Pydantic के `HttpUrl` का instance declare कर सकते हैं: diff --git a/docs/hi/docs/tutorial/body.md b/docs/hi/docs/tutorial/body.md index dfccf37..51b1113 100644 --- a/docs/hi/docs/tutorial/body.md +++ b/docs/hi/docs/tutorial/body.md @@ -6,7 +6,7 @@ आपकी API को लगभग हमेशा **response** body भेजनी होती है। लेकिन clients को हर समय **request bodies** भेजने की ज़रूरत नहीं होती, कभी-कभी वे केवल एक path request करते हैं, शायद कुछ query parameters के साथ, लेकिन body नहीं भेजते। -**request** body घोषित करने के लिए, आप [Pydantic](https://docs.pydantic.dev/) models का उनकी पूरी शक्ति और लाभों के साथ उपयोग करते हैं। +**request** body घोषित करने के लिए, आप [Pydantic](https://pydantic.dev/docs/) models का उनकी पूरी शक्ति और लाभों के साथ उपयोग करते हैं। /// note | नोट diff --git a/docs/hi/docs/tutorial/debugging.md b/docs/hi/docs/tutorial/debugging.md index 0c214bb..c33b971 100644 --- a/docs/hi/docs/tutorial/debugging.md +++ b/docs/hi/docs/tutorial/debugging.md @@ -15,7 +15,7 @@
```console -$ python myapp.py +$ uv run python myapp.py ```
@@ -35,7 +35,7 @@ from myapp import app
```console -$ python myapp.py +$ uv run python myapp.py ```
diff --git a/docs/hi/docs/tutorial/extra-data-types.md b/docs/hi/docs/tutorial/extra-data-types.md index a157ea0..ba118d7 100644 --- a/docs/hi/docs/tutorial/extra-data-types.md +++ b/docs/hi/docs/tutorial/extra-data-types.md @@ -36,7 +36,7 @@ * `datetime.timedelta`: * एक Python `datetime.timedelta`. * requests और responses में इसे कुल seconds के `float` के रूप में दर्शाया जाएगा। - * Pydantic इसे "ISO 8601 time diff encoding" के रूप में दर्शाने की अनुमति भी देता है, [अधिक जानकारी के लिए docs देखें](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers). + * Pydantic इसे "ISO 8601 time diff encoding" के रूप में दर्शाने की अनुमति भी देता है, [अधिक जानकारी के लिए docs देखें](https://pydantic.dev/docs/validation/latest/concepts/serialization/#custom-serializers). * `frozenset`: * requests और responses में, इसे `set` जैसा ही माना जाता है: * requests में, एक list पढ़ी जाएगी, duplicates हटाए जाएँगे और उसे `set` में convert किया जाएगा। @@ -49,7 +49,7 @@ * `Decimal`: * Standard Python `Decimal`. * requests और responses में, इसे `float` जैसा ही handle किया जाएगा। -* आप सभी valid Pydantic data types यहाँ देख सकते हैं: [Pydantic data types](https://docs.pydantic.dev/latest/usage/types/types/). +* आप सभी valid Pydantic data types यहाँ देख सकते हैं: [Pydantic data types](https://pydantic.dev/docs/validation/latest/concepts/types/). ## उदाहरण { #example } diff --git a/docs/hi/docs/tutorial/extra-models.md b/docs/hi/docs/tutorial/extra-models.md index 93a4e91..2b4536f 100644 --- a/docs/hi/docs/tutorial/extra-models.md +++ b/docs/hi/docs/tutorial/extra-models.md @@ -1,4 +1,4 @@ -# Extra Models { #extra-models } +# अतिरिक्त Models { #extra-models } पिछले उदाहरण को आगे बढ़ाते हुए, एक से अधिक संबंधित model होना आम बात होगी। @@ -166,7 +166,7 @@ Code duplication कम करना **FastAPI** के core ideas में स /// note | नोट -[`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions) define करते समय, सबसे specific type को पहले include करें, उसके बाद कम specific type को। नीचे दिए गए उदाहरण में, अधिक specific `PlaneItem`, `Union[PlaneItem, CarItem]` में `CarItem` से पहले आता है। +[`Union`](https://pydantic.dev/docs/validation/latest/concepts/unions/) define करते समय, सबसे specific type को पहले include करें, उसके बाद कम specific type को। नीचे दिए गए उदाहरण में, अधिक specific `PlaneItem`, `Union[PlaneItem, CarItem]` में `CarItem` से पहले आता है। /// diff --git a/docs/hi/docs/tutorial/first-steps.md b/docs/hi/docs/tutorial/first-steps.md index aa6fd4e..423fa46 100644 --- a/docs/hi/docs/tutorial/first-steps.md +++ b/docs/hi/docs/tutorial/first-steps.md @@ -6,12 +6,18 @@ इसे `main.py` नाम की file में copy करें। +/// tip | सुझाव + +FastAPI के पास [VS Code के लिए official extension](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (और Cursor) है, जो बहुत सारे features प्रदान करता है, जिसमें path operation explorer, path operation search, tests में CodeLens navigation (tests से definition पर jump), और FastAPI Cloud deployment और logs शामिल हैं, सब आपके editor से। + +/// + live server चलाएँ:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -78,7 +84,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) और अब, [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) पर जाएँ। -आपको वैकल्पिक automatic documentation दिखेगी ([ReDoc](https://github.com/Rebilly/ReDoc) द्वारा प्रदान की गई): +आपको वैकल्पिक automatic documentation दिखेगी ([ReDoc](https://github.com/Redocly/redoc) द्वारा प्रदान की गई): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -185,13 +191,13 @@ from backend.main import app आप `fastapi dev` command को file path भी pass कर सकते हैं, और यह उपयोग करने के लिए FastAPI app object का अनुमान लगा लेगा: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` या, आप `fastapi dev` command को `--entrypoint` option भी pass कर सकते हैं: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` लेकिन हर बार `fastapi` command call करते समय आपको सही path\entrypoint pass करना याद रखना होगा। @@ -205,7 +211,7 @@ $ fastapi dev --entrypoint main:app
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -232,7 +238,7 @@ CLI आपकी FastAPI application को अपने आप detect करे `FastAPI` एक class है जो सीधे `Starlette` से inherit करती है। -आप `FastAPI` के साथ सारी [Starlette](https://www.starlette.dev/) functionality भी उपयोग कर सकते हैं। +आप `FastAPI` के साथ सारी [Starlette](https://starlette.dev/) functionality भी उपयोग कर सकते हैं। /// diff --git a/docs/hi/docs/tutorial/frontend.md b/docs/hi/docs/tutorial/frontend.md index bc8e188..ab07810 100644 --- a/docs/hi/docs/tutorial/frontend.md +++ b/docs/hi/docs/tutorial/frontend.md @@ -52,7 +52,7 @@ npm run build {* ../../docs_src/frontend/tutorial002_py310.py hl[5] *} -**FastAPI** इस fallback का उपयोग केवल उन `GET` और `HEAD` requests के लिए करता है जो browser navigation जैसी दिखती हैं। JavaScript, CSS, और images जैसी missing files अभी भी `404` लौटाती हैं। +**FastAPI** इस fallback का उपयोग केवल उन `GET` और `HEAD` requests के लिए करता है जो स्पष्ट रूप से `Accept: text/html` या `Accept: application/xhtml+xml` के साथ HTML accept करती हैं, जैसा browser navigation requests सामान्यतः करती हैं। JavaScript, CSS, और images जैसी missing files अभी भी `404` लौटाती हैं। अन्य methods वाली requests, जैसे `POST` या `PUT`, उन paths पर जो केवल frontend fallback से match करते हैं, वे भी `404` लौटाती हैं। नियमित **FastAPI** *path operations* की priority अभी भी frontend routes से अधिक होती है। @@ -106,9 +106,13 @@ Default रूप से, `app.frontend()` `fallback="auto"` का उपयो ## Directory जाँचें { #check-directory } -Default रूप से, `app.frontend()` app बनाते समय जाँचता है कि directory मौजूद है। +Default रूप से, `app.frontend()` `check_dir="auto"` का उपयोग करता है। -यह configuration errors को जल्दी पकड़ने में मदद करता है। उदाहरण के लिए, अगर frontend build output directory missing है, तो **FastAPI** startup पर error raise करेगा। +जब `FASTAPI_ENV` environment variable को `development` पर set किया जाता है, तो अगर frontend build output directory missing है तो **FastAPI** केवल एक warning दिखाता है। [`fastapi dev` command](https://github.com/fastapi/fastapi-cli#fastapi-dev) आपके लिए यह environment variable set करता है अगर यह पहले से set नहीं है। यह आपको development के दौरान frontend को build या start करने से पहले backend start करने देता है। + +किसी भी अन्य environment में, app बनाए जाने पर **FastAPI** error raise करता है। यह frontend files के बिना app deploy करने से पहले configuration errors को जल्दी पकड़ने में मदद करता है। + +आप app बनाए जाने पर हमेशा directory की जाँच करने के लिए `check_dir=True` भी set कर सकते हैं। अगर आपकी frontend files बाद में बनाई जाती हैं, उदाहरण के लिए app object बनने के बाद किसी अलग build step द्वारा, तो `check_dir=False` set करें: @@ -132,6 +136,8 @@ Frontend responses सामान्य **FastAPI** application के अं App से, `APIRouter` से, और `include_router()` से dependencies भी frontend responses पर लागू होती हैं। यह cookie authentication या इसी तरह से frontend को protect करने के लिए उपयोगी हो सकता है। +Dependencies response headers को modify भी कर सकती हैं और background tasks add कर सकती हैं, जैसे सामान्य *path operations* के साथ। + ## केवल Static Build Output { #static-build-output-only } `app.frontend()` आपके frontend build द्वारा पहले से generate की गई files serve करता है। diff --git a/docs/hi/docs/tutorial/handling-errors.md b/docs/hi/docs/tutorial/handling-errors.md index ee45707..1627e64 100644 --- a/docs/hi/docs/tutorial/handling-errors.md +++ b/docs/hi/docs/tutorial/handling-errors.md @@ -81,7 +81,7 @@ Client को errors वाली HTTP responses return करने के ल ## custom exception handlers install करें { #install-custom-exception-handlers } -आप [Starlette से वही exception utilities](https://www.starlette.dev/exceptions/) के साथ custom exception handlers जोड़ सकते हैं। +आप [Starlette से वही exception utilities](https://starlette.dev/exceptions/) के साथ custom exception handlers जोड़ सकते हैं। मान लीजिए आपके पास एक custom exception `UnicornException` है जिसे आप (या कोई library जिसका आप उपयोग करते हैं) `raise` कर सकते हैं। @@ -101,7 +101,7 @@ Client को errors वाली HTTP responses return करने के ल {"message": "Oops! yolo did something. There goes a rainbow..."} ``` -/// note | Technical Details +/// note | तकनीकी विवरण आप `from starlette.requests import Request` और `from starlette.responses import JSONResponse` का भी उपयोग कर सकते हैं। @@ -161,7 +161,7 @@ Field: ('path', 'item_id'), Error: Input should be a valid integer, unable to pa {* ../../docs_src/handling_errors/tutorial004_py310.py hl[3:4,9:11,25] *} -/// note | Technical Details +/// note | तकनीकी विवरण आप `from starlette.responses import PlainTextResponse` का भी उपयोग कर सकते हैं। diff --git a/docs/hi/docs/tutorial/index.md b/docs/hi/docs/tutorial/index.md index f5aff09..9978d28 100644 --- a/docs/hi/docs/tutorial/index.md +++ b/docs/hi/docs/tutorial/index.md @@ -10,12 +10,12 @@ सभी code blocks को copy करके सीधे उपयोग किया जा सकता है (वे वास्तव में tested Python files हैं)। -किसी भी example को चलाने के लिए, code को `main.py` file में copy करें, और `fastapi dev` शुरू करें: +किसी भी example को चलाने के लिए, code को `main.py` file में copy करें, और `uv run` के साथ `fastapi dev` शुरू करें:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -60,35 +60,75 @@ $ fastapi dev ## FastAPI install करें { #install-fastapi } -पहला step FastAPI install करना है। +पहला step अपने project को set up करना और FastAPI जोड़ना है। -सुनिश्चित करें कि आप एक [virtual environment](../virtual-environments.md) बनाएँ, उसे activate करें, और फिर **FastAPI install करें**: +[`uv`](https://docs.astral.sh/uv/getting-started/installation/) install करें, फिर एक project बनाएँ और FastAPI जोड़ें:
```console -$ pip install "fastapi[standard]" +$ uv init awesome-project --bare +$ cd awesome-project +$ uv add "fastapi[standard]" ---> 100% ```
+`uv add` project की virtual environment को `.venv` में बनाता है, FastAPI को `pyproject.toml` में जोड़ता है, और `uv.lock` बनाता है ताकि वही package versions बाद में install किए जा सकें। + +/// details | ये commands क्या करते हैं + +* `uv init`: एक नया Python project बनाएँ। +* `awesome-project`: इस नाम के साथ एक नई directory में project बनाएँ। +* `--bare`: sample `main.py`, `README.md`, या दूसरी files generate किए बिना, केवल minimal `pyproject.toml` file बनाएँ। आप इस tutorial के अगले steps में application files खुद बनाएँगे। + +फिर FastAPI जोड़ने से पहले `cd awesome-project` नई project directory में जाता है। + +`uv` आपके system पर पहले से install compatible Python version का उपयोग करेगा, या ज़रूरत होने पर एक download करेगा। + +जब आप `uv add` चलाते हैं, तो यह FastAPI और उन सभी packages के compatible versions चुनता है जिन पर FastAPI depend करता है। यह exact versions को `uv.lock` में record करता है, जिससे बाद में किसी दूसरे computer पर या application deploy करते समय वही package versions install करना संभव होता है। + +इस file को बनाना या update करना [project dependencies को **locking** करना](https://docs.astral.sh/uv/concepts/projects/sync/) कहलाता है। जब आप package जोड़ते हैं तो `uv` यह automatically करता है। + +/// + +/// details | FastAPI installation options + +जब आप `uv add "fastapi[standard]"` के साथ install करते हैं, तो यह कुछ default optional standard dependencies के साथ आता है, जिनमें `fastapi-cloud-cli` शामिल है, जो आपको [FastAPI Cloud](https://fastapicloud.com) पर deploy करने देता है। + +अगर आप वे optional dependencies नहीं चाहते, तो इसके बजाय आप `uv add fastapi` install कर सकते हैं। + +अगर आप standard dependencies install करना चाहते हैं लेकिन `fastapi-cloud-cli` के बिना, तो आप `uv add "fastapi[standard-no-fastapi-cloud-cli]"` के साथ install कर सकते हैं। + +/// + +/// details | इसके बजाय `pip` का उपयोग करना + +अगर आप virtual environment और packages को manually manage करना पसंद करते हैं, तो एक virtual environment बनाएँ और activate करें और फिर `pip install "fastapi[standard]"` के साथ FastAPI install करें। + +विस्तृत steps के लिए [Virtual Environments guide](https://tiangolo.com/guides/virtual-environments/) पढ़ें। + +/// + +## AI Agent Skills { #ai-agent-skills } + +FastAPI में AI coding agents के लिए एक official skill शामिल है। यह package के साथ bundled है, इसलिए इसका guidance आपके project में install FastAPI के version के साथ aligned रहता है और जब आप FastAPI update करते हैं तो update होता है। + +अपने project में FastAPI install करने के बाद, आप Library Skills के साथ skill install कर सकते हैं: + +```bash +uvx library-skills +``` + /// note | नोट -जब आप `pip install "fastapi[standard]"` के साथ install करते हैं, तो यह कुछ default optional standard dependencies के साथ आता है, जिनमें `fastapi-cloud-cli` शामिल है, जो आपको [FastAPI Cloud](https://fastapicloud.com) पर deploy करने देता है। - -अगर आप वे optional dependencies नहीं चाहते, तो इसके बजाय आप `pip install fastapi` install कर सकते हैं। - -अगर आप standard dependencies install करना चाहते हैं लेकिन `fastapi-cloud-cli` के बिना, तो आप `pip install "fastapi[standard-no-fastapi-cloud-cli]"` के साथ install कर सकते हैं। +`uvx` `uv tool run` के लिए एक alias है। यह Library Skills को एक temporary, isolated environment में चलाता है जबकि Library Skills आपके project में install packages को scan करता है। /// -/// tip | सुझाव - -FastAPI के पास [VS Code के लिए official extension](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (और Cursor) है, जो बहुत सारी features देता है, जिनमें path operation explorer, path operation search, tests में CodeLens navigation (tests से definition पर jump करना), और FastAPI Cloud deployment और logs शामिल हैं — सब कुछ आपके editor से। - -/// +यह skill Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Pi, OpenCode, और अधिकतर अन्य coding agents के साथ compatible है। Claude Code के लिए, जब पूछा जाए कि skill कहाँ install करना है तो `.claude/skills` चुनें। ## उन्नत उपयोगकर्ता गाइड { #advanced-user-guide } diff --git a/docs/hi/docs/tutorial/middleware.md b/docs/hi/docs/tutorial/middleware.md index 0fd2be7..8e27181 100644 --- a/docs/hi/docs/tutorial/middleware.md +++ b/docs/hi/docs/tutorial/middleware.md @@ -37,7 +37,7 @@ middleware function को मिलता है: ध्यान रखें कि custom proprietary headers को [`X-` prefix का उपयोग करके](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) जोड़ा जा सकता है। -लेकिन अगर आपके पास custom headers हैं जिन्हें आप browser में client को दिखाना चाहते हैं, तो आपको उन्हें अपने CORS configurations ([CORS (Cross-Origin Resource Sharing)](cors.md)) में `expose_headers` parameter का उपयोग करके जोड़ना होगा, जैसा कि [Starlette के CORS docs](https://www.starlette.dev/middleware/#corsmiddleware) में documented है। +लेकिन अगर आपके पास custom headers हैं जिन्हें आप browser में client को दिखाना चाहते हैं, तो आपको उन्हें अपने CORS configurations ([CORS (Cross-Origin Resource Sharing)](cors.md)) में `expose_headers` parameter का उपयोग करके जोड़ना होगा, जैसा कि [Starlette के CORS docs](https://starlette.dev/middleware/#corsmiddleware) में documented है। /// diff --git a/docs/hi/docs/tutorial/path-params.md b/docs/hi/docs/tutorial/path-params.md index 602ff12..b665dda 100644 --- a/docs/hi/docs/tutorial/path-params.md +++ b/docs/hi/docs/tutorial/path-params.md @@ -92,7 +92,7 @@ path parameter `item_id` की value आपके function को argument `ite ## Standard-आधारित लाभ, वैकल्पिक documentation { #standards-based-benefits-alternative-documentation } -और क्योंकि generate किया गया schema [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md) standard से है, इसलिए कई compatible tools हैं। +और क्योंकि generate किया गया schema [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) standard से है, इसलिए कई compatible tools हैं। इसी वजह से, **FastAPI** स्वयं एक वैकल्पिक API documentation प्रदान करता है (ReDoc का उपयोग करते हुए), जिसे आप [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) पर access कर सकते हैं: @@ -102,7 +102,7 @@ path parameter `item_id` की value आपके function को argument `ite ## Pydantic { #pydantic } -सारा data validation अंदरूनी तौर पर [Pydantic](https://docs.pydantic.dev/) द्वारा किया जाता है, इसलिए आपको इसके सभी लाभ मिलते हैं। और आप जानते हैं कि आप अच्छे हाथों में हैं। +सारा data validation अंदरूनी तौर पर [Pydantic](https://pydantic.dev/docs/) द्वारा किया जाता है, इसलिए आपको इसके सभी लाभ मिलते हैं। और आप जानते हैं कि आप अच्छे हाथों में हैं। आप `str`, `float`, `bool` और कई अन्य जटिल data types के साथ वही type declarations इस्तेमाल कर सकते हैं। diff --git a/docs/hi/docs/tutorial/query-params-str-validations.md b/docs/hi/docs/tutorial/query-params-str-validations.md index 05f2634..3320a9d 100644 --- a/docs/hi/docs/tutorial/query-params-str-validations.md +++ b/docs/hi/docs/tutorial/query-params-str-validations.md @@ -348,7 +348,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems अब मान लीजिए कि आपको यह parameter अब पसंद नहीं है। -आपको इसे कुछ समय के लिए वहीं छोड़ना होगा क्योंकि clients इसे use कर रहे हैं, लेकिन आप चाहते हैं कि docs इसे स्पष्ट रूप से deprecated के रूप में दिखाएँ। +आपको इसे कुछ समय के लिए वहीं छोड़ना होगा क्योंकि clients इसे use कर रहे हैं, लेकिन आप चाहते हैं कि docs इसे स्पष्ट रूप से deprecated के रूप में दिखाएँ। फिर parameter `deprecated=True` को `Query` में pass करें: @@ -370,15 +370,15 @@ generated OpenAPI schema से query parameter exclude करने के ल ऐसे cases में, आप एक **custom validator function** use कर सकते हैं जो normal validation के बाद apply होता है (जैसे value के `str` होने की validation के बाद)। -आप इसे `Annotated` के अंदर [Pydantic के `AfterValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator) का उपयोग करके हासिल कर सकते हैं। +आप इसे `Annotated` के अंदर [Pydantic के `AfterValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-after-validator) का उपयोग करके हासिल कर सकते हैं। /// tip | टिप -Pydantic में [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator) और अन्य भी हैं। 🤓 +Pydantic में [`BeforeValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-before-validator) और अन्य भी हैं। 🤓 /// -उदाहरण के लिए, यह custom validator check करता है कि item ID किसी ISBN book number के लिए `isbn-` से शुरू होती है या किसी IMDB movie URL ID के लिए `imdb-` से: +उदाहरण के लिए, यह custom validator check करता है कि item ID किसी ISBN book number के लिए `isbn-` से शुरू होती है या किसी IMDB movie URL ID के लिए `imdb-` से: {* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *} diff --git a/docs/hi/docs/tutorial/request-files.md b/docs/hi/docs/tutorial/request-files.md index 4a79ca2..20f8004 100644 --- a/docs/hi/docs/tutorial/request-files.md +++ b/docs/hi/docs/tutorial/request-files.md @@ -6,10 +6,10 @@ अपलोड की गई files प्राप्त करने के लिए, पहले [`python-multipart`](https://github.com/Kludex/python-multipart) install करें। -सुनिश्चित करें कि आप एक [virtual environment](../virtual-environments.md) बनाते हैं, उसे activate करते हैं, और फिर इसे install करते हैं, उदाहरण के लिए: +इसे अपने project में जोड़ें: ```console -$ pip install python-multipart +$ uv add python-multipart ``` ऐसा इसलिए है क्योंकि अपलोड की गई files "form data" के रूप में भेजी जाती हैं। diff --git a/docs/hi/docs/tutorial/request-form-models.md b/docs/hi/docs/tutorial/request-form-models.md index 98fc91a..3b4307c 100644 --- a/docs/hi/docs/tutorial/request-form-models.md +++ b/docs/hi/docs/tutorial/request-form-models.md @@ -6,10 +6,10 @@ forms का उपयोग करने के लिए, पहले [`python-multipart`](https://github.com/Kludex/python-multipart) install करें। -सुनिश्चित करें कि आप एक [virtual environment](../virtual-environments.md) बनाते हैं, उसे activate करते हैं, और फिर इसे install करते हैं, उदाहरण के लिए: +इसे अपने project में जोड़ें: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/hi/docs/tutorial/request-forms-and-files.md b/docs/hi/docs/tutorial/request-forms-and-files.md index c43edae..a1eec22 100644 --- a/docs/hi/docs/tutorial/request-forms-and-files.md +++ b/docs/hi/docs/tutorial/request-forms-and-files.md @@ -6,10 +6,10 @@ अपलोड की गई files और/या form data प्राप्त करने के लिए, पहले [`python-multipart`](https://github.com/Kludex/python-multipart) install करें। -सुनिश्चित करें कि आप एक [virtual environment](../virtual-environments.md) बनाएँ, उसे activate करें, और फिर इसे install करें, उदाहरण के लिए: +इसे अपने project में जोड़ें: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/hi/docs/tutorial/request-forms.md b/docs/hi/docs/tutorial/request-forms.md index 32488ec..ba5e528 100644 --- a/docs/hi/docs/tutorial/request-forms.md +++ b/docs/hi/docs/tutorial/request-forms.md @@ -6,10 +6,10 @@ forms का उपयोग करने के लिए, पहले [`python-multipart`](https://github.com/Kludex/python-multipart) install करें। -सुनिश्चित करें कि आप एक [virtual environment](../virtual-environments.md) बनाते हैं, उसे activate करते हैं, और फिर इसे install करते हैं, उदाहरण के लिए: +इसे अपने project में जोड़ें: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/hi/docs/tutorial/response-model.md b/docs/hi/docs/tutorial/response-model.md index 76f7ba4..5e0ab32 100644 --- a/docs/hi/docs/tutorial/response-model.md +++ b/docs/hi/docs/tutorial/response-model.md @@ -76,16 +76,16 @@ FastAPI इस `response_model` का उपयोग सभी data documentat `EmailStr` का उपयोग करने के लिए, पहले [`email-validator`](https://github.com/JoshData/python-email-validator) install करें। -सुनिश्चित करें कि आप एक [virtual environment](../virtual-environments.md) बनाते हैं, उसे activate करते हैं, और फिर इसे install करते हैं, उदाहरण के लिए: +इसे अपने project में जोड़ें: ```console -$ pip install email-validator +$ uv add email-validator ``` या इसके साथ: ```console -$ pip install "pydantic[email]" +$ uv add "pydantic[email]" ``` /// @@ -258,7 +258,7 @@ FastAPI internally Pydantic के साथ कई चीज़ें करत * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -जैसा कि `exclude_defaults` और `exclude_none` के लिए [Pydantic docs](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict) में बताया गया है। +जैसा कि `exclude_defaults` और `exclude_none` के लिए [Pydantic docs](https://pydantic.dev/docs/validation/latest/concepts/serialization/#excluding-and-including-fields-based-on-their-value) में बताया गया है। /// diff --git a/docs/hi/docs/tutorial/schema-extra-example.md b/docs/hi/docs/tutorial/schema-extra-example.md index dc8b29f..c7dbafa 100644 --- a/docs/hi/docs/tutorial/schema-extra-example.md +++ b/docs/hi/docs/tutorial/schema-extra-example.md @@ -12,7 +12,7 @@ वह अतिरिक्त जानकारी उस model के output **JSON Schema** में जैसी है वैसी ही जोड़ी जाएगी, और API docs में उपयोग की जाएगी। -आप `model_config` attribute का उपयोग कर सकते हैं, जो एक `dict` लेता है, जैसा कि [Pydantic के docs: Configuration](https://docs.pydantic.dev/latest/api/config/) में बताया गया है। +आप `model_config` attribute का उपयोग कर सकते हैं, जो एक `dict` लेता है, जैसा कि [Pydantic के docs: Configuration](https://pydantic.dev/docs/validation/latest/api/pydantic/config/) में बताया गया है। आप `"json_schema_extra"` को एक `dict` के साथ set कर सकते हैं जिसमें कोई भी अतिरिक्त data हो जिसे आप generated JSON Schema में दिखाना चाहते हैं, जिसमें `examples` भी शामिल हैं। @@ -169,7 +169,7 @@ OpenAPI ने specification के अन्य हिस्सों में और अब यह नया `examples` field पुराने single (और custom) `example` field पर precedence लेता है, जो अब deprecated है। -JSON Schema में यह नया `examples` field OpenAPI में अन्य जगहों (ऊपर वर्णित) की तरह अतिरिक्त metadata वाला dict नहीं है, यह **सिर्फ एक `list`** है। +JSON Schema में यह नया `examples` field OpenAPI में अन्य जगहों (ऊपर वर्णित) की तरह अतिरिक्त metadata वाला dict नहीं है, यह **सिर्फ examples की एक `list`** है। /// note | नोट diff --git a/docs/hi/docs/tutorial/security/first-steps.md b/docs/hi/docs/tutorial/security/first-steps.md index a7bf2e7..37477a9 100644 --- a/docs/hi/docs/tutorial/security/first-steps.md +++ b/docs/hi/docs/tutorial/security/first-steps.md @@ -26,14 +26,14 @@ /// note | नोट -[`python-multipart`](https://github.com/Kludex/python-multipart) package **FastAPI** के साथ अपने-आप install हो जाता है जब आप `pip install "fastapi[standard]"` command चलाते हैं। +[`python-multipart`](https://github.com/Kludex/python-multipart) package **FastAPI** के साथ अपने-आप install हो जाता है जब आप `uv add "fastapi[standard]"` command चलाते हैं। -हालाँकि, अगर आप `pip install fastapi` command का उपयोग करते हैं, तो `python-multipart` package default रूप से शामिल नहीं होता। +हालाँकि, अगर आप `uv add fastapi` command का उपयोग करते हैं, तो `python-multipart` package default रूप से शामिल नहीं होता। -इसे manually install करने के लिए, सुनिश्चित करें कि आप एक [virtual environment](../../virtual-environments.md) बनाएँ, उसे activate करें, और फिर इसे इस तरह install करें: +इसे manually install करने के लिए, इसे अपने project में इस तरह जोड़ें: ```console -$ pip install python-multipart +$ uv add python-multipart ``` ऐसा इसलिए है क्योंकि **OAuth2**, `username` और `password` भेजने के लिए "form data" का उपयोग करता है। @@ -45,7 +45,7 @@ $ pip install python-multipart
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/hi/docs/tutorial/security/oauth2-jwt.md b/docs/hi/docs/tutorial/security/oauth2-jwt.md index 2066d8f..ec1d786 100644 --- a/docs/hi/docs/tutorial/security/oauth2-jwt.md +++ b/docs/hi/docs/tutorial/security/oauth2-jwt.md @@ -30,12 +30,12 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4 Python में JWT tokens generate और verify करने के लिए हमें `PyJWT` install करना होगा। -सुनिश्चित करें कि आप एक [virtual environment](../../virtual-environments.md) बनाएँ, उसे activate करें, और फिर `pyjwt` install करें: +अपने project में `pyjwt` जोड़ें:
```console -$ pip install pyjwt +$ uv add pyjwt ---> 100% ``` @@ -72,12 +72,12 @@ pwdlib password hashes संभालने के लिए एक शान Recommended algorithm "Argon2" है। -सुनिश्चित करें कि आप एक [virtual environment](../../virtual-environments.md) बनाएँ, उसे activate करें, और फिर Argon2 के साथ pwdlib install करें: +अपने project में Argon2 के साथ `pwdlib` जोड़ें:
```console -$ pip install "pwdlib[argon2]" +$ uv add "pwdlib[argon2]" ---> 100% ``` diff --git a/docs/hi/docs/tutorial/sql-databases.md b/docs/hi/docs/tutorial/sql-databases.md index 041da16..5c1442e 100644 --- a/docs/hi/docs/tutorial/sql-databases.md +++ b/docs/hi/docs/tutorial/sql-databases.md @@ -34,12 +34,12 @@ ## `SQLModel` install करें { #install-sqlmodel } -सबसे पहले, सुनिश्चित करें कि आप अपना [virtual environment](../virtual-environments.md) बनाएँ, उसे activate करें, और फिर `sqlmodel` install करें: +`sqlmodel` को अपने project में जोड़ें:
```console -$ pip install sqlmodel +$ uv add sqlmodel ---> 100% ``` @@ -152,7 +152,7 @@ SQLModel में Alembic को wrap करने वाली migration utili
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -337,7 +337,7 @@ hero को **delete करना** लगभग पहले जैसा ह
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/hi/docs/tutorial/static-files.md b/docs/hi/docs/tutorial/static-files.md index 6a41c90..037b514 100644 --- a/docs/hi/docs/tutorial/static-files.md +++ b/docs/hi/docs/tutorial/static-files.md @@ -45,4 +45,4 @@ ## अधिक जानकारी { #more-info } -अधिक विवरण और options के लिए [Static Files के बारे में Starlette की docs](https://www.starlette.dev/staticfiles/) देखें। +अधिक विवरण और options के लिए [Static Files के बारे में Starlette की docs](https://starlette.dev/staticfiles/) देखें। diff --git a/docs/hi/docs/tutorial/testing.md b/docs/hi/docs/tutorial/testing.md index 3a05e79..88092fd 100644 --- a/docs/hi/docs/tutorial/testing.md +++ b/docs/hi/docs/tutorial/testing.md @@ -1,6 +1,6 @@ # Testing { #testing } -[Starlette](https://www.starlette.dev/testclient/) की बदौलत, **FastAPI** applications की testing आसान और आनंददायक है। +[Starlette](https://starlette.dev/testclient/) की बदौलत, **FastAPI** applications की testing आसान और आनंददायक है। यह [HTTPX](https://www.python-httpx.org) पर आधारित है, जो बदले में Requests के आधार पर design किया गया है, इसलिए यह बहुत परिचित और intuitive है। @@ -12,10 +12,10 @@ `TestClient` का उपयोग करने के लिए, पहले [`httpx`](https://www.python-httpx.org) install करें। -सुनिश्चित करें कि आप एक [virtual environment](../virtual-environments.md) बनाते हैं, उसे activate करते हैं, और फिर इसे install करते हैं, उदाहरण के लिए: +इसे अपने project में जोड़ें: ```console -$ pip install httpx +$ uv add httpx ``` /// @@ -156,12 +156,12 @@ backend को data कैसे pass करें (`httpx` या `TestClient` उसके बाद, आपको बस `pytest` install करना है। -सुनिश्चित करें कि आप एक [virtual environment](../virtual-environments.md) बनाते हैं, उसे activate करते हैं, और फिर इसे install करते हैं, उदाहरण के लिए: +इसे अपने project में जोड़ें:
```console -$ pip install pytest +$ uv add pytest ---> 100% ``` @@ -175,7 +175,7 @@ Tests चलाएँ:
```console -$ pytest +$ uv run pytest ================ test session starts ================ platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1 diff --git a/docs/hi/docs/virtual-environments.md b/docs/hi/docs/virtual-environments.md index cacadd0..e927dcb 100644 --- a/docs/hi/docs/virtual-environments.md +++ b/docs/hi/docs/virtual-environments.md @@ -1,864 +1,35 @@ # Virtual Environments { #virtual-environments } -जब आप Python projects पर काम करते हैं, तो संभवतः आपको हर project के लिए install किए जाने वाले packages को अलग रखने के लिए एक **virtual environment** (या कोई समान तरीका) इस्तेमाल करना चाहिए। +जब आप Python projects पर काम करते हैं, तो आपको हर project के लिए install किए गए packages को अलग रखने के लिए एक **virtual environment** का उपयोग करना चाहिए। -/// note | नोट - -अगर आप पहले से virtual environments के बारे में जानते हैं, उन्हें कैसे बनाना और इस्तेमाल करना है जानते हैं, तो आप इस section को छोड़ना चाह सकते हैं। 🤓 - -/// - -/// tip | सुझाव - -एक **virtual environment**, एक **environment variable** से अलग होता है। - -एक **environment variable** system में एक variable होता है जिसे programs इस्तेमाल कर सकते हैं। - -एक **virtual environment** एक directory होती है जिसमें कुछ files होती हैं। - -/// - -/// note | नोट - -यह पेज आपको **virtual environments** का उपयोग करना और वे कैसे काम करते हैं, सिखाएगा। - -अगर आप अपने लिए **सब कुछ manage करने वाला tool** अपनाने के लिए तैयार हैं (जिसमें Python install करना भी शामिल है), तो [uv](https://github.com/astral-sh/uv) आज़माएँ। - -/// +FastAPI projects के लिए, मैं project, उसकी dependencies, और उसके virtual environment को manage करने के लिए [uv](https://docs.astral.sh/uv/) उपयोग करने की सलाह देता हूँ। ## Project बनाएँ { #create-a-project } -सबसे पहले, अपने project के लिए एक directory बनाएँ। - -मैं सामान्यतः अपनी home/user directory के अंदर `code` नाम की एक directory बनाता हूँ। - -और उसके अंदर हर project के लिए एक directory बनाता हूँ। +[official installation guide](https://docs.astral.sh/uv/getting-started/installation/) का उपयोग करके `uv` install करें, और फिर एक project बनाएँ:
```console -// home directory में जाएँ -$ cd -// अपने सभी code projects के लिए एक directory बनाएँ -$ mkdir code -// उस code directory में जाएँ -$ cd code -// इस project के लिए एक directory बनाएँ -$ mkdir awesome-project -// उस project directory में जाएँ +$ uv init awesome-project --bare $ cd awesome-project +$ uv add "fastapi[standard]" ```
-## Virtual Environment बनाएँ { #create-a-virtual-environment } +`uv` project के लिए virtual environment automatically बनाता है। आपको खुद कोई बनाने या activate करने की ज़रूरत नहीं है। -जब आप किसी Python project पर **पहली बार** काम शुरू करते हैं, तो एक virtual environment **अपने project के अंदर** बनाएँ। - -/// tip | सुझाव - -आपको यह **हर project के लिए केवल एक बार** करना होता है, हर बार काम करते समय नहीं। - -/// - -//// tab | `venv` - -Virtual environment बनाने के लिए, आप Python के साथ आने वाले `venv` module का उपयोग कर सकते हैं। +Project environment के अंदर commands `uv run` से चलाएँ, उदाहरण के लिए:
```console -$ python -m venv .venv +$ uv run fastapi dev ```
-/// details | उस command का क्या अर्थ है +## और जानें { #learn-more } -* `python`: `python` नाम के program का उपयोग करें -* `-m`: किसी module को script की तरह call करें, अगला हम उसे बताएँगे कि कौन-सा module -* `venv`: `venv` नाम के module का उपयोग करें जो सामान्यतः Python के साथ install आता है -* `.venv`: नई directory `.venv` में virtual environment बनाएँ - -/// - -//// - -//// tab | `uv` - -अगर आपके पास [`uv`](https://github.com/astral-sh/uv) install है, तो आप इसका उपयोग virtual environment बनाने के लिए कर सकते हैं। - -
- -```console -$ uv venv -``` - -
- -/// tip | सुझाव - -Default रूप से, `uv` `.venv` नाम की directory में virtual environment बनाएगा। - -लेकिन आप directory नाम के साथ एक अतिरिक्त argument देकर इसे customize कर सकते हैं। - -/// - -//// - -वह command `.venv` नाम की directory में एक नया virtual environment बनाता है। - -/// details | `.venv` या कोई दूसरा नाम - -आप virtual environment को किसी दूसरी directory में बना सकते हैं, लेकिन इसे `.venv` कहने की एक convention है। - -/// - -## Virtual Environment activate करें { #activate-the-virtual-environment } - -नए virtual environment को activate करें ताकि आप जो भी Python command चलाएँ या जो package install करें, वह इसका उपयोग करे। - -/// tip | सुझाव - -Project पर काम करने के लिए **हर बार** जब आप एक **नया terminal session** शुरू करें, तो यह करें। - -/// - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -या अगर आप Windows के लिए Bash का उपयोग करते हैं (जैसे [Git Bash](https://gitforwindows.org/)): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -/// tip | सुझाव - -हर बार जब आप उस environment में कोई **नया package** install करें, तो environment को फिर से **activate** करें। - -यह सुनिश्चित करता है कि अगर आप उस package द्वारा install किया गया कोई **terminal (CLI) program** इस्तेमाल करते हैं, तो आप अपने virtual environment वाला ही उपयोग करें, कोई और नहीं जो global रूप से install हो सकता है, शायद आपकी ज़रूरत से अलग version के साथ। - -/// - -## जाँचें कि Virtual Environment Active है { #check-the-virtual-environment-is-active } - -जाँचें कि virtual environment active है (पिछली command ने काम किया)। - -/// tip | सुझाव - -यह **वैकल्पिक** है, लेकिन यह **जाँचने** का एक अच्छा तरीका है कि सब कुछ अपेक्षा के अनुसार काम कर रहा है और आप वही virtual environment इस्तेमाल कर रहे हैं जिसका आपने इरादा किया था। - -/// - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -अगर यह `.venv/bin/python` पर `python` binary दिखाता है, आपके project के अंदर (इस मामले में `awesome-project`), तो यह काम कर गया। 🎉 - -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -अगर यह `.venv\Scripts\python` पर `python` binary दिखाता है, आपके project के अंदर (इस मामले में `awesome-project`), तो यह काम कर गया। 🎉 - -//// - -## `pip` Upgrade करें { #upgrade-pip } - -/// tip | सुझाव - -अगर आप [`uv`](https://github.com/astral-sh/uv) का उपयोग करते हैं, तो आप चीजें install करने के लिए `pip` की बजाय उसी का उपयोग करेंगे, इसलिए आपको `pip` upgrade करने की ज़रूरत नहीं है। 😎 - -/// - -अगर आप packages install करने के लिए `pip` का उपयोग कर रहे हैं (यह Python के साथ default रूप से आता है), तो आपको इसे latest version में **upgrade** करना चाहिए। - -किसी package को install करते समय कई अजीब errors केवल पहले `pip` upgrade करने से हल हो जाते हैं। - -/// tip | सुझाव - -आप सामान्यतः यह **एक बार** करेंगे, virtual environment बनाने के ठीक बाद। - -/// - -सुनिश्चित करें कि virtual environment active है (ऊपर वाली command से) और फिर चलाएँ: - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip | सुझाव - -कभी-कभी, pip upgrade करने की कोशिश करते समय आपको **`No module named pip`** error मिल सकता है। - -अगर ऐसा होता है, तो नीचे दी गई command का उपयोग करके pip install और upgrade करें: - -
- -```console -$ python -m ensurepip --upgrade - ----> 100% -``` - -
- -यह command pip को install करेगी अगर वह पहले से install नहीं है और यह भी सुनिश्चित करेगी कि install किया गया pip का version कम से कम `ensurepip` में उपलब्ध version जितना नया हो। - -/// - -## `.gitignore` जोड़ें { #add-gitignore } - -अगर आप **Git** का उपयोग कर रहे हैं (आपको करना चाहिए), तो अपनी `.venv` की हर चीज़ को Git से exclude करने के लिए एक `.gitignore` file जोड़ें। - -/// tip | सुझाव - -अगर आपने virtual environment बनाने के लिए [`uv`](https://github.com/astral-sh/uv) का उपयोग किया है, तो यह आपके लिए पहले ही कर चुका है, आप यह step छोड़ सकते हैं। 😎 - -/// - -/// tip | सुझाव - -यह **एक बार** करें, virtual environment बनाने के ठीक बाद। - -/// - -
- -```console -$ echo "*" > .venv/.gitignore -``` - -
- -/// details | उस command का क्या अर्थ है - -* `echo "*"`: terminal में text `*` को "print" करेगा (अगला हिस्सा इसे थोड़ा बदल देता है) -* `>`: `>` के बाईं ओर वाली command द्वारा terminal में print की गई कोई भी चीज़ print नहीं होनी चाहिए, बल्कि `>` के दाईं ओर वाली file में लिखी जानी चाहिए -* `.gitignore`: उस file का नाम जहाँ text लिखा जाना चाहिए - -और Git के लिए `*` का मतलब "सब कुछ" होता है। इसलिए, यह `.venv` directory में सब कुछ ignore करेगा। - -वह command `.gitignore` file बनाएगी, इस content के साथ: - -```gitignore -* -``` - -/// - -## Packages install करें { #install-packages } - -Environment activate करने के बाद, आप उसमें packages install कर सकते हैं। - -/// tip | सुझाव - -जब आप अपने project के लिए required packages install या upgrade कर रहे हों, तो यह **एक बार** करें। - -अगर आपको किसी version को upgrade करना हो या कोई नया package जोड़ना हो, तो आप **यह फिर से करेंगे**। - -/// - -### सीधे Packages install करें { #install-packages-directly } - -अगर आप जल्दी में हैं और अपने project की package requirements declare करने के लिए कोई file इस्तेमाल नहीं करना चाहते, तो आप उन्हें सीधे install कर सकते हैं। - -/// tip | सुझाव - -आपके program को जिन packages और versions की ज़रूरत है, उन्हें एक file में रखना (बहुत) अच्छा विचार है (उदाहरण के लिए `requirements.txt` या `pyproject.toml`)। - -/// - -//// tab | `pip` - -
- -```console -$ pip install "fastapi[standard]" - ----> 100% -``` - -
- -//// - -//// tab | `uv` - -अगर आपके पास [`uv`](https://github.com/astral-sh/uv) है: - -
- -```console -$ uv pip install "fastapi[standard]" ----> 100% -``` - -
- -//// - -### `requirements.txt` से install करें { #install-from-requirements-txt } - -अगर आपके पास `requirements.txt` है, तो अब आप इसके packages install करने के लिए इसका उपयोग कर सकते हैं। - -//// tab | `pip` - -
- -```console -$ pip install -r requirements.txt ----> 100% -``` - -
- -//// - -//// tab | `uv` - -अगर आपके पास [`uv`](https://github.com/astral-sh/uv) है: - -
- -```console -$ uv pip install -r requirements.txt ----> 100% -``` - -
- -//// - -/// details | `requirements.txt` - -कुछ packages वाला `requirements.txt` ऐसा दिख सकता है: - -```requirements.txt -fastapi[standard]==0.113.0 -pydantic==2.8.0 -``` - -/// - -## अपना Program चलाएँ { #run-your-program } - -Virtual environment activate करने के बाद, आप अपना program चला सकते हैं, और यह आपके virtual environment के अंदर मौजूद Python का उपयोग करेगा, उन packages के साथ जिन्हें आपने वहाँ install किया है। - -
- -```console -$ python main.py - -Hello World -``` - -
- -## अपना Editor Configure करें { #configure-your-editor } - -आप शायद एक editor का उपयोग करेंगे, सुनिश्चित करें कि आप इसे उसी virtual environment का उपयोग करने के लिए configure करें जिसे आपने बनाया है (यह शायद इसे autodetect कर लेगा), ताकि आपको autocompletion और inline errors मिल सकें। - -उदाहरण के लिए: - -* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) -* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) - -/// tip | सुझाव - -आपको सामान्यतः यह केवल **एक बार** करना होता है, जब आप virtual environment बनाते हैं। - -/// - -## Virtual Environment deactivate करें { #deactivate-the-virtual-environment } - -जब आप अपने project पर काम कर लें, तो आप virtual environment को **deactivate** कर सकते हैं। - -
- -```console -$ deactivate -``` - -
- -इस तरह, जब आप `python` चलाएँगे, तो यह वहाँ install packages वाले उस virtual environment से इसे चलाने की कोशिश नहीं करेगा। - -## काम करने के लिए तैयार { #ready-to-work } - -अब आप अपने project पर काम शुरू करने के लिए तैयार हैं। - - - -/// tip | सुझाव - -क्या आप समझना चाहते हैं कि ऊपर की सारी चीज़ें क्या हैं? - -आगे पढ़ते रहें। 👇🤓 - -/// - -## Virtual Environments क्यों { #why-virtual-environments } - -FastAPI के साथ काम करने के लिए आपको [Python](https://www.python.org/) install करना होगा। - -उसके बाद, आपको FastAPI और कोई भी अन्य **packages** जिन्हें आप इस्तेमाल करना चाहते हैं, **install** करने होंगे। - -Packages install करने के लिए आप सामान्यतः Python के साथ आने वाली `pip` command (या समान alternatives) का उपयोग करेंगे। - -फिर भी, अगर आप सीधे `pip` का उपयोग करते हैं, तो packages आपके **global Python environment** (Python की global installation) में install हो जाएँगे। - -### समस्या { #the-problem } - -तो, global Python environment में packages install करने में समस्या क्या है? - -किसी समय, आप शायद कई अलग-अलग programs लिखेंगे जो **अलग-अलग packages** पर निर्भर करते हैं। और जिन projects पर आप काम करेंगे उनमें से कुछ उसी package के **अलग-अलग versions** पर निर्भर होंगे। 😱 - -उदाहरण के लिए, आप `philosophers-stone` नाम का एक project बना सकते हैं, यह program **`harry`, version `1`** नाम के किसी दूसरे package पर निर्भर करता है। इसलिए, आपको `harry` install करना होगा। - -```mermaid -flowchart LR - stone(philosophers-stone) -->|requires| harry-1[harry v1] -``` - -फिर, कुछ समय बाद, आप `prisoner-of-azkaban` नाम का दूसरा project बनाते हैं, और यह project भी `harry` पर निर्भर करता है, लेकिन इस project को **`harry` version `3`** चाहिए। - -```mermaid -flowchart LR - azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3] -``` - -लेकिन अब समस्या यह है कि अगर आप packages को local **virtual environment** में install करने के बजाय globally (global environment में) install करते हैं, तो आपको चुनना होगा कि `harry` का कौन-सा version install करना है। - -अगर आप `philosophers-stone` चलाना चाहते हैं, तो आपको पहले `harry` version `1` install करना होगा, उदाहरण के लिए: - -
- -```console -$ pip install "harry==1" -``` - -
- -और फिर आपके global Python environment में `harry` version `1` install हो जाएगा। - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -->|requires| harry-1 - end -``` - -लेकिन फिर अगर आप `prisoner-of-azkaban` चलाना चाहते हैं, तो आपको `harry` version `1` uninstall करके `harry` version `3` install करना होगा (या सिर्फ version `3` install करने से version `1` automatically uninstall हो जाएगा)। - -
- -```console -$ pip install "harry==3" -``` - -
- -और फिर आपके global Python environment में `harry` version `3` install हो जाएगा। - -और अगर आप `philosophers-stone` फिर से चलाने की कोशिश करते हैं, तो संभावना है कि यह **काम न करे** क्योंकि इसे `harry` version `1` चाहिए। - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - style harry-1 fill:#ccc,stroke-dasharray: 5 5 - harry-3[harry v3] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -.-x|⛔️| harry-1 - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --> |requires| harry-3 - end -``` - -/// tip | सुझाव - -Python packages में **नए versions** में **breaking changes से बचने** की पूरी कोशिश करना बहुत आम है, लेकिन सुरक्षित रहना बेहतर है, और नए versions को जानबूझकर तथा तब install करना बेहतर है जब आप tests चलाकर जाँच सकें कि सब कुछ सही तरीके से काम कर रहा है। - -/// - -अब, यही चीज़ उन **कई** अन्य **packages** के साथ कल्पना करें जिन पर आपके सभी **projects निर्भर करते हैं**। इसे manage करना बहुत कठिन है। और संभवतः आप कुछ projects को packages के कुछ **incompatible versions** के साथ चला देंगे, और यह नहीं जान पाएँगे कि कुछ काम क्यों नहीं कर रहा। - -साथ ही, आपके operating system (जैसे Linux, Windows, macOS) के आधार पर, उसमें Python पहले से install आया हो सकता है। और उस मामले में संभवतः कुछ packages कुछ specific versions के साथ pre-installed होंगे जो **आपके system के लिए required** हैं। अगर आप global Python environment में packages install करते हैं, तो आप अपने operating system के साथ आए कुछ programs को **break** कर सकते हैं। - -## Packages कहाँ install होते हैं { #where-are-packages-installed } - -जब आप Python install करते हैं, तो यह आपके computer पर कुछ files वाली कुछ directories बनाता है। - -इनमें से कुछ directories वे होती हैं जो आपके द्वारा install किए गए सभी packages को रखने की जिम्मेदार होती हैं। - -जब आप चलाते हैं: - -
- -```console -// इसे अभी न चलाएँ, यह केवल एक उदाहरण है 🤓 -$ pip install "fastapi[standard]" ----> 100% -``` - -
- -तो यह FastAPI code वाली एक compressed file download करेगा, सामान्यतः [PyPI](https://pypi.org/project/fastapi/) से। - -यह उन अन्य packages की files भी **download** करेगा जिन पर FastAPI निर्भर करता है। - -फिर यह उन सभी files को **extract** करेगा और उन्हें आपके computer की एक directory में रखेगा। - -Default रूप से, यह उन downloaded और extracted files को उस directory में रखेगा जो आपकी Python installation के साथ आती है, वही **global environment** है। - -## Virtual Environments क्या हैं { #what-are-virtual-environments } - -सभी packages को global environment में रखने की समस्याओं का समाधान है कि आप जिस भी project पर काम करते हैं उसके लिए **एक virtual environment** उपयोग करें। - -एक virtual environment एक **directory** है, global वाली के बहुत समान, जहाँ आप किसी project के लिए packages install कर सकते हैं। - -इस तरह, हर project का अपना virtual environment (`.venv` directory) होगा, अपने packages के साथ। - -```mermaid -flowchart TB - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) --->|requires| harry-1 - subgraph venv1[.venv] - harry-1[harry v1] - end - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --->|requires| harry-3 - subgraph venv2[.venv] - harry-3[harry v3] - end - end - stone-project ~~~ azkaban-project -``` - -## Virtual Environment activate करने का क्या मतलब है { #what-does-activating-a-virtual-environment-mean } - -जब आप किसी virtual environment को activate करते हैं, उदाहरण के लिए: - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -या अगर आप Windows के लिए Bash का उपयोग करते हैं (जैसे [Git Bash](https://gitforwindows.org/)): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -वह command कुछ [environment variables](environment-variables.md) बनाएगी या modify करेगी, जो अगली commands के लिए उपलब्ध होंगे। - -उन variables में से एक `PATH` variable है। - -/// tip | सुझाव - -आप [Environment Variables](environment-variables.md#path-environment-variable) section में `PATH` environment variable के बारे में और जान सकते हैं। - -/// - -Virtual environment activate करने से उसका path `.venv/bin` (Linux और macOS पर) या `.venv\Scripts` (Windows पर) `PATH` environment variable में जुड़ जाता है। - -मान लीजिए कि environment activate करने से पहले, `PATH` variable ऐसा दिखता था: - -//// tab | Linux, macOS - -```plaintext -/usr/bin:/bin:/usr/sbin:/sbin -``` - -इसका मतलब है कि system programs को इनमें खोजता: - -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Windows\System32 -``` - -इसका मतलब है कि system programs को इसमें खोजता: - -* `C:\Windows\System32` - -//// - -Virtual environment activate करने के बाद, `PATH` variable कुछ ऐसा दिखेगा: - -//// tab | Linux, macOS - -```plaintext -/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -इसका मतलब है कि system अब सबसे पहले programs को यहाँ खोजना शुरू करेगा: - -```plaintext -/home/user/code/awesome-project/.venv/bin -``` - -बाकी directories में देखने से पहले। - -तो, जब आप terminal में `python` type करते हैं, तो system Python program को यहाँ पाएगा - -```plaintext -/home/user/code/awesome-project/.venv/bin/python -``` - -और उसी का उपयोग करेगा। - -//// - -//// tab | Windows - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32 -``` - -इसका मतलब है कि system अब सबसे पहले programs को यहाँ खोजना शुरू करेगा: - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts -``` - -बाकी directories में देखने से पहले। - -तो, जब आप terminal में `python` type करते हैं, तो system Python program को यहाँ पाएगा - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -और उसी का उपयोग करेगा। - -//// - -एक महत्वपूर्ण detail यह है कि यह virtual environment path को `PATH` variable की **शुरुआत** में रखेगा। System इसे किसी भी अन्य उपलब्ध Python से **पहले** पाएगा। इस तरह, जब आप `python` चलाते हैं, तो यह किसी अन्य `python` (उदाहरण के लिए, global environment वाला `python`) के बजाय **virtual environment से** Python का उपयोग करेगा। - -Virtual environment activate करने से कुछ और चीजें भी बदलती हैं, लेकिन यह उसके द्वारा की जाने वाली सबसे महत्वपूर्ण चीज़ों में से एक है। - -## Virtual Environment की जाँच करना { #checking-a-virtual-environment } - -जब आप जाँचते हैं कि virtual environment active है या नहीं, उदाहरण के लिए: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -//// - -इसका मतलब है कि जो `python` program उपयोग किया जाएगा, वह **virtual environment में** मौजूद है। - -आप Linux और macOS में `which` और Windows PowerShell में `Get-Command` का उपयोग करते हैं। - -वह command जिस तरह काम करती है, वह यह है कि यह `PATH` environment variable में जाकर **हर path को क्रम से** check करेगी, `python` नाम के program को खोजते हुए। एक बार जब यह उसे ढूँढ लेती है, तो यह आपको उस program का **path दिखाएगी**। - -सबसे महत्वपूर्ण हिस्सा यह है कि जब आप `python` call करते हैं, तो वही exact "`python`" execute होगा। - -तो, आप confirm कर सकते हैं कि आप सही virtual environment में हैं या नहीं। - -/// tip | सुझाव - -एक virtual environment activate करना, एक Python पाना, और फिर **दूसरे project में चले जाना** आसान है। - -और दूसरा project **काम नहीं करेगा** क्योंकि आप **गलत Python** का उपयोग कर रहे हैं, जो किसी दूसरे project के virtual environment से है। - -यह check कर पाना उपयोगी है कि कौन-सा `python` उपयोग हो रहा है। 🤓 - -/// - -## Virtual Environment deactivate क्यों करें { #why-deactivate-a-virtual-environment } - -उदाहरण के लिए, आप `philosophers-stone` project पर काम कर रहे हो सकते हैं, **उस virtual environment को activate** करके, packages install करके और उस environment के साथ काम करके। - -और फिर आप **किसी दूसरे project** `prisoner-of-azkaban` पर काम करना चाहते हैं। - -आप उस project में जाते हैं: - -
- -```console -$ cd ~/code/prisoner-of-azkaban -``` - -
- -अगर आप `philosophers-stone` के लिए virtual environment को deactivate नहीं करते, तो जब आप terminal में `python` चलाएँगे, यह `philosophers-stone` से Python का उपयोग करने की कोशिश करेगा। - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -$ python main.py - -// sirius import करने में error, यह install नहीं है 😱 -Traceback (most recent call last): - File "main.py", line 1, in - import sirius -``` - -
- -लेकिन अगर आप virtual environment deactivate करके `prisoner-of-azkaban` के लिए नया वाला activate करते हैं, तो जब आप `python` चलाएँगे, यह `prisoner-of-azkaban` में मौजूद virtual environment से Python का उपयोग करेगा। - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -// deactivate करने के लिए आपको पुरानी directory में होने की ज़रूरत नहीं है, आप जहाँ भी हों वहाँ से कर सकते हैं, दूसरे project में जाने के बाद भी 😎 -$ deactivate - -// prisoner-of-azkaban/.venv में virtual environment activate करें 🚀 -$ source .venv/bin/activate - -// अब जब आप python चलाएँगे, तो यह इस virtual environment में install package sirius को पाएगा ✨ -$ python main.py - -I solemnly swear 🐺 -``` - -
- -## Alternatives { #alternatives } - -यह आपको शुरू करने और यह सिखाने के लिए एक सरल guide है कि सब कुछ **अंदर से** कैसे काम करता है। - -Virtual environments, package dependencies (requirements), projects को manage करने के कई **alternatives** हैं। - -जब आप तैयार हों और **पूरे project को manage** करने के लिए कोई tool उपयोग करना चाहें, package dependencies, virtual environments आदि सहित, तो मैं सुझाव दूँगा कि आप [uv](https://github.com/astral-sh/uv) आज़माएँ। - -`uv` बहुत सारी चीज़ें कर सकता है, यह कर सकता है: - -* आपके लिए **Python install** करना, अलग-अलग versions सहित -* आपके projects के लिए **virtual environment** manage करना -* **Packages** install करना -* आपके project के लिए package **dependencies और versions** manage करना -* सुनिश्चित करना कि आपके पास install करने के लिए packages और versions का **exact** set हो, उनकी dependencies सहित, ताकि आप सुनिश्चित हो सकें कि आप अपने project को production में ठीक उसी तरह चला सकते हैं जैसे development के दौरान अपने computer पर चलाते हैं, इसे **locking** कहा जाता है -* और कई अन्य चीज़ें - -## निष्कर्ष { #conclusion } - -अगर आपने यह सब पढ़ा और समझा है, तो अब **आप virtual environments के बारे में** वहाँ मौजूद कई developers से कहीं ज़्यादा जानते हैं। 🤓 - -इन details को जानना भविष्य में उस समय बहुत संभवतः उपयोगी होगा जब आप किसी ऐसी चीज़ को debug कर रहे होंगे जो complex लगती है, लेकिन आपको पता होगा कि **यह सब अंदर से कैसे काम करता है**। 😎 +Virtual environments अंदर से कैसे काम करते हैं, यह जानने के लिए [Virtual Environments guide](https://tiangolo.com/guides/virtual-environments/) पढ़ें, जिसमें activation और alternative `python -m venv` और `pip` workflow शामिल हैं। diff --git a/docs/ja/docs/advanced/additional-responses.md b/docs/ja/docs/advanced/additional-responses.md index ad0b1d4..908ee06 100644 --- a/docs/ja/docs/advanced/additional-responses.md +++ b/docs/ja/docs/advanced/additional-responses.md @@ -4,7 +4,7 @@ これは比較的高度なトピックです。 -FastAPI を使い始めたばかりであれば、これは不要かもしれません。 +**FastAPI** を使い始めたばかりであれば、これは不要かもしれません。 /// @@ -22,7 +22,7 @@ FastAPI を使い始めたばかりであれば、これは不要かもしれま それぞれのレスポンス `dict` には、`response_model` と同様に Pydantic モデルを格納する `model` キーを含められます。 -FastAPI はそのモデルから JSON Schema を生成し、OpenAPI の適切な場所に含めます。 +**FastAPI** はそのモデルから JSON Schema を生成し、OpenAPI の適切な場所に含めます。 例えば、ステータスコード `404` と Pydantic モデル `Message` を持つ別のレスポンスを宣言するには、次のように書けます: @@ -38,14 +38,14 @@ FastAPI はそのモデルから JSON Schema を生成し、OpenAPI の適切な `model` キーは OpenAPI の一部ではありません。 -FastAPI はそこから Pydantic モデルを取得して JSON Schema を生成し、適切な場所に配置します。 +**FastAPI** はそこから Pydantic モデルを取得して JSON Schema を生成し、適切な場所に配置します。 適切な場所は次のとおりです: - `content` キーの中。これは値として別の JSON オブジェクト（`dict`）を持ち、その中に次が含まれます: - メディアタイプ（例: `application/json`）をキーとし、値としてさらに別の JSON オブジェクトを持ち、その中に次が含まれます: - `schema` キー。値としてモデル由来の JSON Schema を持ち、ここが正しい配置場所です。 - - FastAPI はここに、スキーマを直接埋め込む代わりに OpenAPI 内のグローバルな JSON Schema への参照を追加します。これにより、他のアプリケーションやクライアントがそれらの JSON Schema を直接利用し、より良いコード生成ツール等を提供できます。 + - **FastAPI** はここに、スキーマを直接埋め込む代わりに OpenAPI 内のグローバルな JSON Schema への参照を追加します。これにより、他のアプリケーションやクライアントがそれらの JSON Schema を直接利用し、より良いコード生成ツール等を提供できます。 /// @@ -197,7 +197,7 @@ FastAPI はそこから Pydantic モデルを取得して JSON Schema を生成 `response_model` を宣言し、デフォルトのステータスコード `200`（必要なら任意のコード）を使い、その同じレスポンスに対する追加情報を `responses` で OpenAPI スキーマに直接記述できます。 -FastAPI は `responses` にある追加情報を保持し、モデルの JSON Schema と結合します。 +**FastAPI** は `responses` にある追加情報を保持し、モデルの JSON Schema と結合します。 例えば、Pydantic モデルを用い、独自の `description` を持つステータスコード `404` のレスポンスを宣言できます。 @@ -243,5 +243,5 @@ new_dict = {**old_dict, "new key": "new value"} レスポンスに正確に何を含められるかは、OpenAPI 仕様の次のセクションを参照してください: -- [OpenAPI の Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object)、ここには `Response Object` が含まれます。 -- [OpenAPI の Response Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object)、`responses` パラメータ内の各レスポンスに、ここで定義されている要素を直接含められます。`description`、`headers`、`content`（ここで異なるメディアタイプや JSON Schema を宣言します）、`links` など。 +- [OpenAPI の Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object)、ここには `Response Object` が含まれます。 +- [OpenAPI の Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object)、`responses` パラメータ内の各レスポンスに、ここで定義されている要素を直接含められます。`description`、`headers`、`content`（ここで異なるメディアタイプや JSON Schema を宣言します）、`links` など。 diff --git a/docs/ja/docs/advanced/async-tests.md b/docs/ja/docs/advanced/async-tests.md index da2968d..b07e15d 100644 --- a/docs/ja/docs/advanced/async-tests.md +++ b/docs/ja/docs/advanced/async-tests.md @@ -34,7 +34,7 @@ {* ../../docs_src/async_tests/app_a_py310/main.py *} -`test_main.py` は `main.py` のテストを持ち、次のようになります: +`test_main.py` は `main.py` のテストを持ち、今は次のようになります: {* ../../docs_src/async_tests/app_a_py310/test_main.py *} @@ -45,7 +45,7 @@
```console -$ pytest +$ uv run pytest ---> 100% ``` @@ -60,7 +60,7 @@ $ pytest /// tip | 豆知識 -`TestClient` を使っていたときと異なり、テスト関数は `async def` ではなく `def` になっている点に注意してください。 +`TestClient` を使っていたときのように単なる `def` ではなく、テスト関数は `async def` になっている点に注意してください。 /// diff --git a/docs/ja/docs/advanced/behind-a-proxy.md b/docs/ja/docs/advanced/behind-a-proxy.md index 108c437..bf0e899 100644 --- a/docs/ja/docs/advanced/behind-a-proxy.md +++ b/docs/ja/docs/advanced/behind-a-proxy.md @@ -33,7 +33,7 @@ FastAPI CLI を *CLI オプション* `--forwarded-allow-ips` 付きで起動し
```console -$ fastapi run --forwarded-allow-ips="*" +$ uv run fastapi run --forwarded-allow-ips="*" INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -170,7 +170,7 @@ IP `0.0.0.0` は、そのマシン/サーバーで利用可能なすべての IP
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -200,7 +200,7 @@ Hypercorn を使う場合も、同様に `--root-path` オプションがあり
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -253,7 +253,7 @@ Uvicorn は、プロキシが `http://127.0.0.1:8000/app` にアクセスして [Traefik](https://docs.traefik.io/) を使えば、パスプレフィックスを削除する構成をローカルで簡単に試せます。 -[Traefik をダウンロード](https://github.com/containous/traefik/releases) してください。単一バイナリなので、圧縮ファイルを展開して端末から直接実行できます。 +[Traefik をダウンロード](https://github.com/traefik/traefik/releases) してください。単一バイナリなので、圧縮ファイルを展開して端末から直接実行できます。 次の内容で `traefik.toml` というファイルを作成します: @@ -321,7 +321,7 @@ INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/ja/docs/advanced/dataclasses.md b/docs/ja/docs/advanced/dataclasses.md index 2cfe8e9..4aa736a 100644 --- a/docs/ja/docs/advanced/dataclasses.md +++ b/docs/ja/docs/advanced/dataclasses.md @@ -6,7 +6,7 @@ FastAPI は **Pydantic** の上に構築されており、これまでにリク {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -これは **Pydantic** によって引き続きサポートされています。Pydantic には [`dataclasses` の内部サポート](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel) があるためです。 +これは **Pydantic** によって引き続きサポートされています。Pydantic には [`dataclasses` の内部サポート](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/#usage-of-stdlib-dataclasses-with-basemodel) があるためです。 そのため、上記のように明示的に Pydantic を使っていないコードでも、FastAPI は標準の dataclass を Pydantic 独自の dataclass に変換するために Pydantic を使用しています。 @@ -88,7 +88,7 @@ dataclass は自動的に Pydantic の dataclass に変換されます。 `dataclasses` を他の Pydantic モデルと組み合わせたり、継承したり、自分のモデルに含めたりもできます。 -詳しくは、[dataclasses に関する Pydantic ドキュメント](https://docs.pydantic.dev/latest/concepts/dataclasses/) を参照してください。 +詳しくは、[dataclasses に関する Pydantic ドキュメント](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/) を参照してください。 ## バージョン { #version } diff --git a/docs/ja/docs/advanced/events.md b/docs/ja/docs/advanced/events.md index 12064f9..3fa5ce9 100644 --- a/docs/ja/docs/advanced/events.md +++ b/docs/ja/docs/advanced/events.md @@ -154,7 +154,7 @@ async with lifespan(app): /// note | 備考 -Starlette の `lifespan` ハンドラについては、[Starlette の Lifespan ドキュメント](https://www.starlette.dev/lifespan/)で詳しく読むことができます。 +Starlette の `lifespan` ハンドラについては、[Starlette の Lifespan ドキュメント](https://starlette.dev/lifespan/)で詳しく読むことができます。 コードの他の領域で使える lifespan の状態をどのように扱うかも含まれています。 diff --git a/docs/ja/docs/advanced/generate-clients.md b/docs/ja/docs/advanced/generate-clients.md index 196ec52..800c76b 100644 --- a/docs/ja/docs/advanced/generate-clients.md +++ b/docs/ja/docs/advanced/generate-clients.md @@ -12,7 +12,7 @@ **TypeScript クライアント**向けには、[Hey API](https://heyapi.dev/) が目的特化のソリューションで、TypeScript エコシステムに最適化された体験を提供します。 -他の SDK ジェネレータは [OpenAPI.Tools](https://openapi.tools/#sdk) でも見つけられます。 +他の SDK ジェネレータは [OpenAPI.Tools](https://openapi.tools/categories/sdk-generators) でも見つけられます。 /// tip | 豆知識 diff --git a/docs/ja/docs/advanced/middleware.md b/docs/ja/docs/advanced/middleware.md index 018e660..446068d 100644 --- a/docs/ja/docs/advanced/middleware.md +++ b/docs/ja/docs/advanced/middleware.md @@ -74,7 +74,7 @@ HTTP Host Header 攻撃を防ぐため、すべての受信リクエストに正 ## `GZipMiddleware` { #gzipmiddleware } -`Accept-Encoding` ヘッダーに "gzip" を含むリクエストに対して GZip レスポンスを処理します。 +`Accept-Encoding` ヘッダーに `"gzip"` を含むリクエストに対して GZip レスポンスを処理します。 このミドルウェアは、通常のレスポンスとストリーミングレスポンスの両方を処理します。 @@ -91,7 +91,7 @@ HTTP Host Header 攻撃を防ぐため、すべての受信リクエストに正 例えば: -- [Uvicorn の `ProxyHeadersMiddleware`](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) +- [Uvicorn の `ProxyHeadersMiddleware`](https://github.com/Kludex/uvicorn/blob/main/uvicorn/middleware/proxy_headers.py) - [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -他に利用可能なミドルウェアについては、[Starlette のミドルウェアドキュメント](https://www.starlette.dev/middleware/)や [ASGI Awesome List](https://github.com/florimondmanca/awesome-asgi) を参照してください。 +他に利用可能なミドルウェアについては、[Starlette のミドルウェアドキュメント](https://starlette.dev/middleware/)や [ASGI Awesome List](https://github.com/florimondmanca/awesome-asgi) を参照してください。 diff --git a/docs/ja/docs/advanced/openapi-callbacks.md b/docs/ja/docs/advanced/openapi-callbacks.md index e3ddeab..9dbc65c 100644 --- a/docs/ja/docs/advanced/openapi-callbacks.md +++ b/docs/ja/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ /// tip | 豆知識 -`callback_url` クエリパラメータは、Pydantic の [Url](https://docs.pydantic.dev/latest/api/networks/) 型を使用します。 +`callback_url` クエリパラメータは、Pydantic の [Url](https://pydantic.dev/docs/validation/latest/api/pydantic/networks/) 型を使用します。 /// @@ -106,11 +106,11 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) 通常の *path operation* と異なる主な点が 2 つあります: * 実際のコードは不要です。あなたのアプリはこのコードを決して呼びません。これは *外部 API* をドキュメント化するためだけに使われます。したがって、関数本体は `pass` で構いません。 -* *パス* には、*あなたの API* に送られた元のリクエストのパラメータや一部を変数として使える [OpenAPI 3 の式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)（後述）を含められます。 +* *パス* には、*あなたの API* に送られた元のリクエストのパラメータや一部を変数として使える [OpenAPI 3 の式](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression)（後述）を含められます。 ### コールバックのパス式 { #the-callback-path-expression } -コールバックの *パス* には、*あなたの API* に送られた元のリクエストの一部を含められる [OpenAPI 3 の式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)を使用できます。 +コールバックの *パス* には、*あなたの API* に送られた元のリクエストの一部を含められる [OpenAPI 3 の式](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression)を使用できます。 この例では、`str` は次のとおりです: diff --git a/docs/ja/docs/advanced/response-cookies.md b/docs/ja/docs/advanced/response-cookies.md index 9121815..cf39cba 100644 --- a/docs/ja/docs/advanced/response-cookies.md +++ b/docs/ja/docs/advanced/response-cookies.md @@ -1,6 +1,5 @@ # レスポンスの Cookie { #response-cookies } - ## `Response` パラメータを使う { #use-a-response-parameter } *path operation 関数*で `Response` 型のパラメータを宣言できます。 @@ -49,4 +48,4 @@ /// -利用可能なすべてのパラメータやオプションについては、[Starlette のドキュメント](https://www.starlette.dev/responses/#set-cookie)を参照してください。 +利用可能なすべてのパラメータやオプションについては、[Starlette のドキュメント](https://starlette.dev/responses/#set-cookie)を参照してください。 diff --git a/docs/ja/docs/advanced/response-headers.md b/docs/ja/docs/advanced/response-headers.md index d5f6f31..c5292de 100644 --- a/docs/ja/docs/advanced/response-headers.md +++ b/docs/ja/docs/advanced/response-headers.md @@ -1,6 +1,5 @@ # レスポンスヘッダー { #response-headers } - ## `Response` パラメータを使う { #use-a-response-parameter } （Cookie と同様に）*path operation 関数*で `Response` 型のパラメータを宣言できます。 @@ -39,4 +38,4 @@ 独自のカスタムヘッダーは、[`X-` プレフィックスを使って](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)追加できることに注意してください。 -ただし、ブラウザのクライアントに見えるようにしたいカスタムヘッダーがある場合は、CORS 設定にそれらを追加する必要があります（[CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md) を参照）。このとき、[Starlette の CORS ドキュメント](https://www.starlette.dev/middleware/#corsmiddleware)に記載の `expose_headers` パラメータを使用します。 +ただし、ブラウザのクライアントに見えるようにしたいカスタムヘッダーがある場合は、CORS 設定にそれらを追加する必要があります（[CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md) を参照）。このとき、[Starlette の CORS ドキュメント](https://starlette.dev/middleware/#corsmiddleware)に記載の `expose_headers` パラメータを使用します。 diff --git a/docs/ja/docs/advanced/settings.md b/docs/ja/docs/advanced/settings.md index b3fd89a..bc4fcfb 100644 --- a/docs/ja/docs/advanced/settings.md +++ b/docs/ja/docs/advanced/settings.md @@ -6,9 +6,13 @@ そのため、アプリケーションが読み取る環境変数で提供するのが一般的です。 +**環境変数**（**env var** とも呼ばれます）は、Python コードの外側、オペレーティングシステム内に存在する値で、アプリケーションや他のプログラムから読み取ることができます。 + +コマンドを実行するときに、そのコマンド用の環境変数を作成できます。プラットフォーム固有のコマンドは以下で確認できます。 + /// tip | 豆知識 -環境変数について理解するには、[環境変数](../environment-variables.md)を参照してください。 +環境変数の仕組みの詳細な説明については、[Environment Variables guide](https://tiangolo.com/guides/environment-variables/)を参照してください。 /// @@ -20,16 +24,16 @@ ## Pydantic の `Settings` { #pydantic-settings } -幸いなことに、Pydantic には環境変数から来る設定を扱うための優れたユーティリティがあり、[Pydantic: Settings management](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) で提供されています。 +幸いなことに、Pydantic には環境変数から来る設定を扱うための優れたユーティリティがあり、[Pydantic: Settings management](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) で提供されています。 ### `pydantic-settings` のインストール { #install-pydantic-settings } -まず、[仮想環境](../virtual-environments.md)を作成して有効化し、`pydantic-settings` パッケージをインストールします: +`pydantic-settings` パッケージをプロジェクトに追加します:
```console -$ pip install pydantic-settings +$ uv add pydantic-settings ---> 100% ``` @@ -40,7 +44,7 @@ $ pip install pydantic-settings
```console -$ pip install "fastapi[all]" +$ uv add "fastapi[all]" ---> 100% ``` @@ -76,19 +80,39 @@ Pydantic モデルと同様に、型アノテーションと（必要なら） 次に、設定を環境変数として渡してサーバーを実行します。たとえば、`ADMIN_EMAIL` と `APP_NAME` を次のように設定できます: +//// tab | Linux, macOS, Windows Bash +
```console -$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py +$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uv run fastapi run main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
+//// + +//// tab | Windows PowerShell + +
+ +```console +$ $Env:ADMIN_EMAIL = "deadpool@example.com" +$ $Env:APP_NAME = "ChimichangApp" +$ uv run fastapi run main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +//// + /// tip | 豆知識 -1つのコマンドに複数の環境変数を設定するには、スペースで区切ってコマンドの前に並べます。 +Bash で1つのコマンドに複数の環境変数を設定するには、スペースで区切ってコマンドの前に並べます。 /// @@ -172,11 +196,11 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p /// -Pydantic は外部ライブラリを使ってこの種のファイルからの読み込みをサポートしています。詳細は [Pydantic Settings: Dotenv (.env) support](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support) を参照してください。 +Pydantic は外部ライブラリを使ってこの種のファイルからの読み込みをサポートしています。詳細は [Pydantic Settings: Dotenv (.env) support](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#dotenv-env-support) を参照してください。 /// tip | 豆知識 -これを機能させるには、`pip install python-dotenv` が必要です。 +これを機能させるには、`uv add python-dotenv` で `python-dotenv` をプロジェクトに追加します。 /// @@ -197,7 +221,7 @@ APP_NAME="ChimichangApp" /// tip | 豆知識 -`model_config` 属性は Pydantic の設定専用です。詳しくは [Pydantic: Concepts: Configuration](https://docs.pydantic.dev/latest/concepts/config/) を参照してください。 +`model_config` 属性は Pydantic の設定専用です。詳しくは [Pydantic: Concepts: Configuration](https://pydantic.dev/docs/validation/latest/concepts/config/) を参照してください。 /// diff --git a/docs/ja/docs/advanced/sub-applications.md b/docs/ja/docs/advanced/sub-applications.md index e9b1703..ffe33e6 100644 --- a/docs/ja/docs/advanced/sub-applications.md +++ b/docs/ja/docs/advanced/sub-applications.md @@ -35,7 +35,7 @@
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/ja/docs/advanced/templates.md b/docs/ja/docs/advanced/templates.md index 5495b73..17b371c 100644 --- a/docs/ja/docs/advanced/templates.md +++ b/docs/ja/docs/advanced/templates.md @@ -8,12 +8,12 @@ Starlette によって提供され、**FastAPI** アプリで直接使える、 ## 依存関係のインストール { #install-dependencies } -[仮想環境](../virtual-environments.md) を作成して有効化し、`jinja2` をインストールします: +プロジェクトに `jinja2` を追加します:
```console -$ pip install jinja2 +$ uv add jinja2 ---> 100% ``` @@ -24,7 +24,7 @@ $ pip install jinja2 * `Jinja2Templates` をインポートします。 * 後で再利用できる `templates` オブジェクトを作成します。 -* テンプレートを返す path operation に `Request` パラメータを宣言します。 +* テンプレートを返す *path operation* に `Request` パラメータを宣言します。 * 作成した `templates` を使って `TemplateResponse` をレンダリングして返します。テンプレート名、リクエストオブジェクト、Jinja2 テンプレート内で使用するキーと値のペアからなる "context" の辞書を渡します。 {* ../../docs_src/templates/tutorial001_py310.py hl[4,11,15:18] *} @@ -85,7 +85,7 @@ Item ID: 42 ### テンプレートの `url_for` の引数 { #template-url-for-arguments } -テンプレート内でも `url_for()` を使用できます。引数には、対応する path operation 関数で使われるのと同じ引数を取ります。 +テンプレート内でも `url_for()` を使用できます。引数には、対応する *path operation 関数* で使われるのと同じ引数を取ります。 したがって、次の部分は: @@ -97,7 +97,7 @@ Item ID: 42 {% endraw %} -...path operation 関数 `read_item(id=id)` が処理するのと同じ URL へのリンクを生成します。 +...*path operation 関数* `read_item(id=id)` が処理するのと同じ URL へのリンクを生成します。 例えば、ID が `42` の場合は次のようにレンダリングされます: @@ -123,4 +123,4 @@ Item ID: 42 ## さらに詳しく { #more-details } -より詳しい内容（テンプレートのテスト方法など）については、[Starlette のテンプレートに関するドキュメント](https://www.starlette.dev/templates/)を参照してください。 +より詳しい内容（テンプレートのテスト方法など）については、[Starlette のテンプレートに関するドキュメント](https://starlette.dev/templates/)を参照してください。 diff --git a/docs/ja/docs/advanced/testing-events.md b/docs/ja/docs/advanced/testing-events.md index 98e97fe..089c8d9 100644 --- a/docs/ja/docs/advanced/testing-events.md +++ b/docs/ja/docs/advanced/testing-events.md @@ -4,7 +4,8 @@ {* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *} -より詳しい内容は、[公式 Starlette ドキュメントの「テストでの lifespan の実行」](https://www.starlette.dev/lifespan/#running-lifespan-in-tests) を参照してください。 + +[`公式 Starlette ドキュメントサイトの「テストでの lifespan の実行」`](https://starlette.dev/lifespan/#running-lifespan-in-tests) についての詳細を読むことができます。 非推奨の `startup` および `shutdown` イベントについては、次のように `TestClient` を使用できます: diff --git a/docs/ja/docs/advanced/testing-websockets.md b/docs/ja/docs/advanced/testing-websockets.md index 745e636..58d9221 100644 --- a/docs/ja/docs/advanced/testing-websockets.md +++ b/docs/ja/docs/advanced/testing-websockets.md @@ -8,6 +8,6 @@ WebSocket をテストするのにも同じ `TestClient` を使用できます /// note | 備考 -詳細については、Starlette のドキュメント「[WebSocket のテスト](https://www.starlette.dev/testclient/#testing-websocket-sessions)」を参照してください。 +詳細については、Starlette のドキュメント「[WebSocket のテスト](https://starlette.dev/testclient/#testing-websocket-sessions)」を参照してください。 /// diff --git a/docs/ja/docs/advanced/using-request-directly.md b/docs/ja/docs/advanced/using-request-directly.md index 59d7290..f2cf4c1 100644 --- a/docs/ja/docs/advanced/using-request-directly.md +++ b/docs/ja/docs/advanced/using-request-directly.md @@ -15,7 +15,7 @@ ## `Request` オブジェクトの詳細 { #details-about-the-request-object } -**FastAPI** は内部的には **Starlette** の上にいくつかのツール層を載せたものなので、必要に応じて Starlette の [`Request`](https://www.starlette.dev/requests/) オブジェクトを直接使えます。 +**FastAPI** は内部的には **Starlette** の上にいくつかのツール層を載せたものなので、必要に応じて Starlette の [`Request`](https://starlette.dev/requests/) オブジェクトを直接使えます。 また、`Request` オブジェクトから直接データ（例: ボディ）を取得する場合、そのデータは FastAPI によって検証・変換・ドキュメント化（OpenAPI による自動 API ユーザーインターフェース向け）されません。 @@ -25,13 +25,13 @@ ## `Request` オブジェクトを直接使う { #use-the-request-object-directly } -たとえば、path operation 関数内でクライアントの IP アドレス／ホストを取得したいとします。 +たとえば、*path operation 関数*内でクライアントの IP アドレス／ホストを取得したいとします。 そのためには、リクエストに直接アクセスする必要があります。 {* ../../docs_src/using_request_directly/tutorial001_py310.py hl[1,7:8] *} -path operation 関数の引数として `Request` 型のパラメータを宣言すると、**FastAPI** はその引数に `Request` を渡します。 +*path operation 関数*の引数として `Request` 型のパラメータを宣言すると、**FastAPI** はその引数に `Request` を渡します。 /// tip | 豆知識 @@ -45,7 +45,7 @@ path operation 関数の引数として `Request` 型のパラメータを宣言 ## `Request` のドキュメント { #request-documentation } -より詳しくは、[公式 Starlette ドキュメントサイトの `Request` オブジェクト](https://www.starlette.dev/requests/)を参照してください。 +より詳しくは、[公式 Starlette ドキュメントサイトの `Request` オブジェクト](https://starlette.dev/requests/)を参照してください。 /// note | 技術詳細 diff --git a/docs/ja/docs/advanced/websockets.md b/docs/ja/docs/advanced/websockets.md index b310adf..cd9cd12 100644 --- a/docs/ja/docs/advanced/websockets.md +++ b/docs/ja/docs/advanced/websockets.md @@ -4,12 +4,12 @@ ## `websockets`のインストール { #install-websockets } -[仮想環境](../virtual-environments.md)を作成し、それを有効化してから、「WebSocket」プロトコルを簡単に使えるようにするPythonライブラリの`websockets`をインストールしてください。 +「WebSocket」プロトコルを簡単に使えるようにするPythonライブラリの`websockets`をプロジェクトに追加します:
```console -$ pip install websockets +$ uv add websockets ---> 100% ``` @@ -36,19 +36,19 @@ $ pip install websockets 本番環境では、上記の方法のいずれかの選択肢を採用することになるでしょう。 -しかし、これはWebSocketsのサーバーサイドに焦点を当て、動作する例を示す最も簡単な方法です。 +しかし、これはWebSocketsのサーバーサイドに焦点を当て、動作する例を示す最も簡単な方法です: {* ../../docs_src/websockets_/tutorial001_py310.py hl[2,6:38,41:43] *} ## `websocket` を作成する { #create-a-websocket } -**FastAPI** アプリケーションで、`websocket` を作成します。 +**FastAPI** アプリケーションで、`websocket` を作成します: {* ../../docs_src/websockets_/tutorial001_py310.py hl[1,46:47] *} /// note | 技術詳細 -`from starlette.websockets import WebSocket` を使用しても構いません. +`from starlette.websockets import WebSocket` を使用しても構いません。 **FastAPI** は開発者の利便性のために、同じ `WebSocket` を提供します。しかし、こちらはStarletteから直接提供されるものです。 @@ -64,12 +64,12 @@ WebSocketルートでは、メッセージを待機して送信するために ` ## 試してみる { #try-it } -コードを `main.py` に入れて、アプリケーションを実行します。 +コードを `main.py` に入れて、アプリケーションを実行します:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -107,7 +107,7 @@ WebSocketエンドポイントでは、`fastapi` から以下をインポート * `Path` * `Query` -これらは、他のFastAPI エンドポイント/*path operations* の場合と同じように機能します。 +これらは、他のFastAPI エンドポイント/*path operations* の場合と同じように機能します: {* ../../docs_src/websockets_/tutorial002_an_py310.py hl[68:69,82] *} @@ -121,12 +121,12 @@ WebSocketエンドポイントでは、`fastapi` から以下をインポート ### 依存関係を用いてWebSocketsを試してみる { #try-the-websockets-with-dependencies } -アプリケーションを実行します。 +アプリケーションを実行します:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -146,7 +146,7 @@ $ fastapi dev /// -これにより、WebSocketに接続してメッセージを送受信できます。 +これにより、WebSocketに接続してメッセージを送受信できます: @@ -156,13 +156,13 @@ WebSocket接続が閉じられると、 `await websocket.receive_text()` は例 {* ../../docs_src/websockets_/tutorial003_py310.py hl[79:81] *} -試してみるには、 +試してみるには: * いくつかのブラウザタブでアプリを開きます。 * それらのタブでメッセージを記入してください。 * そして、タブのうち1つを閉じてください。 -これにより例外 `WebSocketDisconnect` が発生し、他のすべてのクライアントは次のようなメッセージを受信します。 +これにより例外 `WebSocketDisconnect` が発生し、他のすべてのクライアントは次のようなメッセージを受信します: ``` Client #1596980209979 left the chat @@ -182,5 +182,5 @@ FastAPIと簡単に統合できて、RedisやPostgreSQLなどでサポートさ オプションの詳細については、Starletteのドキュメントを確認してください。 -* [`WebSocket` クラス](https://www.starlette.dev/websockets/)。 -* [クラスベースのWebSocket処理](https://www.starlette.dev/endpoints/#websocketendpoint)。 +* [`WebSocket` クラス](https://starlette.dev/websockets/)。 +* [クラスベースのWebSocket処理](https://starlette.dev/endpoints/#websocketendpoint)。 diff --git a/docs/ja/docs/advanced/wsgi.md b/docs/ja/docs/advanced/wsgi.md index 4051139..f9806dd 100644 --- a/docs/ja/docs/advanced/wsgi.md +++ b/docs/ja/docs/advanced/wsgi.md @@ -9,7 +9,7 @@ /// note | 備考 -これには `a2wsgi` のインストールが必要です。例: `pip install a2wsgi`。 +これにはプロジェクトに `a2wsgi` を追加する必要があります。例: `uv add a2wsgi`。 /// diff --git a/docs/ja/docs/alternatives.md b/docs/ja/docs/alternatives.md index 3b3140e..aabe344 100644 --- a/docs/ja/docs/alternatives.md +++ b/docs/ja/docs/alternatives.md @@ -125,7 +125,7 @@ def read_url(): そして、標準に基づくユーザーインターフェースツールを統合しています。 * [Swagger UI](https://github.com/swagger-api/swagger-ui) -* [ReDoc](https://github.com/Rebilly/ReDoc) +* [ReDoc](https://github.com/Redocly/redoc) この二つは人気で安定したものとして選択されましたが、少し検索してみると、 (**FastAPI**と同時に使用できる) OpenAPIのための多くの代替となるツールを見つけることができます。 @@ -237,7 +237,7 @@ Flask-apispecはMarshmallowと同じ開発者により作成されました。 /// -### [NestJS](https://nestjs.com/) (と[Angular](https://angular.io/)) { #nestjs-and-angular } +### [NestJS](https://nestjs.com/) (と[Angular](https://angular.dev/)) { #nestjs-and-angular } NestJSはAngularにインスパイアされたJavaScript (TypeScript) NodeJSフレームワークで、Pythonですらありません。 @@ -337,7 +337,7 @@ OpenAPIやJSON Schemaのような標準に基づいたものではありませ /// note | 備考 -HugはTimothy Crosleyにより作成されました。彼は[`isort`](https://github.com/timothycrosley/isort)など、Pythonのファイル内のインポートの並び替えを自動的に行う素晴らしいツールの開発者です。 +HugはTimothy Crosleyにより作成されました。彼は[`isort`](https://github.com/PyCQA/isort)など、Pythonのファイル内のインポートの並び替えを自動的に行う素晴らしいツールの開発者です。 /// @@ -401,7 +401,7 @@ APIStarはTom Christieにより開発されました。以下の開発者でも ## **FastAPI**が利用しているもの { #used-by-fastapi } -### [Pydantic](https://docs.pydantic.dev/) { #pydantic } +### [Pydantic](https://pydantic.dev/docs/) { #pydantic } Pydanticは、Pythonの型ヒントを元にデータのバリデーション、シリアライゼーション、 (JSON Schemaを使用した) ドキュメントを定義するライブラリです。 @@ -417,7 +417,7 @@ Marshmallowに匹敵しますが、ベンチマークではMarshmallowよりも /// -### [Starlette](https://www.starlette.dev/) { #starlette } +### [Starlette](https://starlette.dev/) { #starlette } Starletteは、軽量なASGIフレームワーク/ツールキットで、高性能な非同期サービスの構築に最適です。 @@ -462,7 +462,7 @@ webに関するコアな部分を全て扱います。その上に機能を追 /// -### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn } +### [Uvicorn](https://uvicorn.dev) { #uvicorn } Uvicornは非常に高速なASGIサーバーで、uvloopとhttptoolsにより構成されています。 diff --git a/docs/ja/docs/deployment/docker.md b/docs/ja/docs/deployment/docker.md index 26e9d56..b4ae83d 100644 --- a/docs/ja/docs/deployment/docker.md +++ b/docs/ja/docs/deployment/docker.md @@ -105,36 +105,32 @@ FastAPI用の**Dockerイメージ**を、**公式Python**イメージに基づ ### パッケージ要件 { #package-requirements } -アプリケーションの**パッケージ要件**は通常、何らかのファイルに記述されているはずです。 +`uv` でプロジェクトを管理している場合、直接の依存関係は `pyproject.toml` に宣言され、正確に解決されたバージョンは `uv.lock` に保存されます。 -パッケージ要件は主に**インストール**するために使用するツールに依存するでしょう。 - -最も一般的な方法は、`requirements.txt` ファイルにパッケージ名とそのバージョンを 1 行ずつ書くことです。 - -もちろん、[FastAPI バージョンについて](versions.md)で読んだのと同じアイデアを使用して、バージョンの範囲を設定します。 - -例えば、`requirements.txt` は次のようになります： - -``` -fastapi[standard]>=0.113.0,<0.114.0 -pydantic>=2.7.0,<3.0.0 -``` - -そして通常、例えば `pip` を使ってこれらのパッケージの依存関係をインストールします： +アプリケーションに必要なパッケージは次のように追加できます：
```console -$ pip install -r requirements.txt +$ uv add "fastapi[standard]" pydantic ---> 100% -Successfully installed fastapi pydantic ```
/// note | 備考 -パッケージの依存関係を定義しインストールするためのフォーマットやツールは他にもあります。 +以下のDockerfileでは、コンテナ内で `pip` を使用します。uvプロジェクトからロックされた依存関係を、Dockerfileが想定する `requirements.txt` 形式にエクスポートできます： + +
+ +```console +$ uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt +``` + +
+ +生成された `requirements.txt` はコンテナビルド用のエクスポートです。依存関係の管理は `uv add` で続け、`uv.lock` が変更されたら再生成してください。 /// @@ -374,7 +370,7 @@ Dockerコンテナの[http://192.168.99.100/items/5?q=somequery](http://192.168. また、[http://192.168.99.100/redoc](http://192.168.99.100/redoc) や [http://127.0.0.1/redoc](http://127.0.0.1/redoc) (またはそれに相当するDockerホストを使用したもの）にもアクセスできます。 -代替の自動ドキュメント（[ReDoc](https://github.com/Rebilly/ReDoc)によって提供される）が表示されます： +代替の自動ドキュメント（[ReDoc](https://github.com/Redocly/redoc)によって提供される）が表示されます： ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -544,13 +540,9 @@ Docker Composeで**単一サーバ**（クラスタではない）にデプロ コンテナごとに**単一のプロセスを実行する**と、それらのコンテナ（レプリケートされている場合は1つ以上）によって消費される多かれ少なかれ明確に定義された、安定し制限された量のメモリを持つことになります。 -そして、コンテナ管理システム（**Kubernetes**など）の設定で、同じメモリ制限と要件を設定することができます。 +そして、コンテナ管理システム（**Kubernetes**など）の設定で、同じメモリ制限と要件を設定することができます。そうすれば、コンテナが必要とするメモリ量とクラスタ内のマシンで利用可能なメモリ量を考慮して、**利用可能なマシン**に**コンテナをレプリケート**できるようになります。 -そうすれば、コンテナが必要とするメモリ量とクラスタ内のマシンで利用可能なメモリ量を考慮して、**利用可能なマシン**に**コンテナ**をレプリケートできるようになります。 - -アプリケーションが**シンプル**なものであれば、これはおそらく**問題にはならない**でしょうし、ハードなメモリ制限を指定する必要はないかもしれないです。 - -しかし、**多くのメモリを使用**している場合（たとえば**機械学習**モデルなど）、どれだけのメモリを消費しているかを確認し、**各マシンで実行するコンテナの数**を調整する必要があります（そしておそらくクラスタにマシンを追加します）。 +アプリケーションが**シンプル**なものであれば、これはおそらく**問題にはならない**でしょうし、ハードなメモリ制限を指定する必要はないかもしれないです。しかし、**多くのメモリを使用**している場合（たとえば**機械学習**モデルなど）、どれだけのメモリを消費しているかを確認し、**各マシンで実行するコンテナの数**を調整する必要があります（そしておそらくクラスタにマシンを追加します）。 **コンテナごとに複数のプロセス**を実行する場合、起動するプロセスの数が**利用可能なメモリ以上に消費しない**ようにする必要があります。 diff --git a/docs/ja/docs/deployment/fastapicloud.md b/docs/ja/docs/deployment/fastapicloud.md index d8c1cb2..c0ebe2f 100644 --- a/docs/ja/docs/deployment/fastapicloud.md +++ b/docs/ja/docs/deployment/fastapicloud.md @@ -5,7 +5,7 @@
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... diff --git a/docs/ja/docs/deployment/manually.md b/docs/ja/docs/deployment/manually.md index 98cd485..2cbfd2e 100644 --- a/docs/ja/docs/deployment/manually.md +++ b/docs/ja/docs/deployment/manually.md @@ -52,7 +52,7 @@ FastAPI は、Python の Web フレームワークとサーバーのための標 他にもいくつかの選択肢があります: -* [Uvicorn](https://www.uvicorn.dev/): 高性能な ASGI サーバー。 +* [Uvicorn](https://uvicorn.dev): 高性能な ASGI サーバー。 * [Hypercorn](https://hypercorn.readthedocs.io/): HTTP/2 や Trio に対応する ASGI サーバーなど。 * [Daphne](https://github.com/django/daphne): Django Channels のために作られた ASGI サーバー。 * [Granian](https://github.com/emmett-framework/granian): Python アプリケーション向けの Rust 製 HTTP サーバー。 @@ -73,14 +73,14 @@ FastAPI をインストールすると、本番サーバーの Uvicorn が同梱 ただし、ASGI サーバーを手動でインストールすることもできます。 -[仮想環境](../virtual-environments.md)を作成して有効化し、サーバーアプリケーションをインストールしてください。 +サーバーアプリケーションをプロジェクトに追加してください。 例として、Uvicorn をインストールするには:
```console -$ pip install "uvicorn[standard]" +$ uv add "uvicorn[standard]" ---> 100% ``` @@ -95,7 +95,7 @@ $ pip install "uvicorn[standard]" その中には、`uvloop` も含まれます。これは `asyncio` の高性能なドロップイン代替で、大きな並行実行性能の向上をもたらします。 -`pip install "fastapi[standard]"` のように FastAPI をインストールした場合は、すでに `uvicorn[standard]` も含まれます。 +`uv add "fastapi[standard]"` のように FastAPI を追加した場合は、すでに `uvicorn[standard]` も含まれます。 /// @@ -106,7 +106,7 @@ ASGI サーバーを手動でインストールした場合、通常は FastAPI
```console -$ uvicorn main:app --host 0.0.0.0 --port 80 +$ uv run uvicorn main:app --host 0.0.0.0 --port 80 INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) ``` diff --git a/docs/ja/docs/deployment/server-workers.md b/docs/ja/docs/deployment/server-workers.md index 55cf2d2..f6febcf 100644 --- a/docs/ja/docs/deployment/server-workers.md +++ b/docs/ja/docs/deployment/server-workers.md @@ -17,7 +17,7 @@ ここでは、`fastapi` コマンド、または `uvicorn` コマンドを直接使って、**ワーカープロセス**付きの **Uvicorn** を使う方法を紹介します。 -/// note +/// note | 備考 DockerやKubernetesなどのコンテナを使用している場合は、次の章で詳しく説明します： [コンテナ内のFastAPI - Docker](docker.md)。 @@ -86,7 +86,7 @@ $ fastapi run --workers 4 ```console -$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 +$ uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit) INFO: Started parent process [27365] INFO: Started server process [27368] diff --git a/docs/ja/docs/environment-variables.md b/docs/ja/docs/environment-variables.md index eb20d3a..9d072b7 100644 --- a/docs/ja/docs/environment-variables.md +++ b/docs/ja/docs/environment-variables.md @@ -1,298 +1,11 @@ # 環境変数 { #environment-variables } -/// tip | 豆知識 +**環境変数**（**env var** とも呼ばれます）とは、Pythonコードの外側、つまりオペレーティングシステムに存在する値で、アプリケーションや他のプログラムから読み取れます。 -もし「環境変数」とは何か、それをどう使うかを既に知っている場合は、このセクションをスキップして構いません。 +FastAPIアプリケーションでは、データベースURL、メール認証情報、シークレットキーなどの設定に環境変数をよく使用します。 -/// +アプリケーション設定での使い方については、[設定と環境変数](advanced/settings.md)で学べます。 -環境変数（「**env var**」とも呼ばれます）とは、Pythonコードの**外側**、つまり**オペレーティングシステム**に存在する変数で、Pythonコード（または他のプログラム）から読み取れます。 +## 詳細 { #learn-more } -環境変数は、アプリケーションの**設定**の扱い、Pythonの**インストール**の一部などで役立ちます。 - -## 環境変数の作成と使用 { #create-and-use-env-vars } - -環境変数は、Pythonを必要とせず、**シェル（ターミナル）**で**作成**して使用できます。 - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// 環境変数 MY_NAME を作成する例 -$ export MY_NAME="Wade Wilson" - -// その後、他のプログラムで利用できます。例えば -$ echo "Hello $MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// 環境変数 MY_NAME を作成 -$ $Env:MY_NAME = "Wade Wilson" - -// 他のプログラムで利用、例えば -$ echo "Hello $Env:MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -## Pythonで環境変数を読み取る { #read-env-vars-in-python } - -環境変数はPythonの**外側**（ターミナル、またはその他の方法）で作成し、その後に**Pythonで読み取る**こともできます。 - -例えば、以下のような`main.py`ファイルを用意します: - -```Python hl_lines="3" -import os - -name = os.getenv("MY_NAME", "World") -print(f"Hello {name} from Python") -``` - -/// tip | 豆知識 - -[`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) の第2引数は、返されるデフォルト値です。 - -指定しない場合、デフォルトは`None`ですが、ここでは使用するデフォルト値として`"World"`を指定しています。 - -/// - -次に、このPythonプログラムを呼び出します。 - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// ここではまだ環境変数を設定していません -$ python main.py - -// 環境変数を設定していないため、デフォルト値が使われます - -Hello World from Python - -// しかし、先に環境変数を作成すると -$ export MY_NAME="Wade Wilson" - -// それからもう一度プログラムを実行すると -$ python main.py - -// すると環境変数を読み取れます - -Hello Wade Wilson from Python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// ここではまだ環境変数を設定していません -$ python main.py - -// 環境変数を設定していないため、デフォルト値が使われます - -Hello World from Python - -// しかし、先に環境変数を作成すると -$ $Env:MY_NAME = "Wade Wilson" - -// それからもう一度プログラムを実行すると -$ python main.py - -// すると環境変数を読み取れます - -Hello Wade Wilson from Python -``` - -
- -//// - -環境変数はコードの外側で設定でき、コードから読み取れ、他のファイルと一緒に（`git`に）保存（コミット）する必要がないため、設定や**settings**に使うのが一般的です。 - -また、**特定のプログラムの呼び出し**のためだけに、そのプログラムでのみ、実行中の間だけ利用できる環境変数を作成することもできます。 - -そのためには、同じ行で、プログラム自体の直前に作成してください。 - -
- -```console -// このプログラム呼び出し用に同じ行で環境変数 MY_NAME を作成 -$ MY_NAME="Wade Wilson" python main.py - -// これで環境変数を読み取れます - -Hello Wade Wilson from Python - -// その後は環境変数は存在しません -$ python main.py - -Hello World from Python -``` - -
- -/// tip | 豆知識 - -詳しくは [The Twelve-Factor App: 設定](https://12factor.net/config) を参照してください。 - -/// - -## 型とバリデーション { #types-and-validation } - -これらの環境変数が扱えるのは**テキスト文字列**のみです。環境変数はPythonの外部にあり、他のプログラムやシステム全体（Linux、Windows、macOSなど異なるオペレーティングシステム間も）との互換性が必要になるためです。 - -つまり、環境変数からPythonで読み取る**あらゆる値**は **`str`になり**、他の型への変換やバリデーションはコード内で行う必要があります。 - -環境変数を使って**アプリケーション設定**を扱う方法については、[高度なユーザーガイド - 設定と環境変数](./advanced/settings.md)で詳しく学べます。 - -## `PATH`環境変数 { #path-environment-variable } - -**`PATH`**という**特別な**環境変数があります。これはオペレーティングシステム（Linux、macOS、Windows）が実行するプログラムを見つけるために使用されます。 - -変数`PATH`の値は長い文字列で、LinuxとmacOSではコロン`:`、Windowsではセミコロン`;`で区切られたディレクトリで構成されます。 - -例えば、`PATH`環境変数は次のような文字列かもしれません: - -//// tab | Linux, macOS - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -これは、システムが次のディレクトリでプログラムを探すことを意味します: - -* `/usr/local/bin` -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32 -``` - -これは、システムが次のディレクトリでプログラムを探すことを意味します: - -* `C:\Program Files\Python312\Scripts` -* `C:\Program Files\Python312` -* `C:\Windows\System32` - -//// - -ターミナル上で**コマンド**を入力すると、オペレーティングシステムは`PATH`環境変数に記載された**それぞれのディレクトリ**の中からプログラムを**探し**ます。 - -例えば、ターミナルで`python`と入力すると、オペレーティングシステムはそのリストの**最初のディレクトリ**で`python`というプログラムを探します。 - -見つかればそれを**使用**します。見つからなければ、**他のディレクトリ**を探し続けます。 - -### Pythonのインストールと`PATH`の更新 { #installing-python-and-updating-the-path } - -Pythonのインストール時に、`PATH`環境変数を更新するかどうかを尋ねられるかもしれません。 - -//// tab | Linux, macOS - -Pythonをインストールして、その結果`/opt/custompython/bin`というディレクトリに配置されたとします。 - -`PATH`環境変数を更新することに同意すると、インストーラーは`PATH`環境変数に`/opt/custompython/bin`を追加します。 - -例えば次のようになります: - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin -``` - -このようにして、ターミナルで`python`と入力すると、システムは`/opt/custompython/bin`（最後のディレクトリ）にあるPythonプログラムを見つけ、それを使用します。 - -//// - -//// tab | Windows - -Pythonをインストールして、その結果`C:\opt\custompython\bin`というディレクトリに配置されたとします。 - -`PATH`環境変数を更新することに同意すると、インストーラーは`PATH`環境変数に`C:\opt\custompython\bin`を追加します。 - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin -``` - -このようにして、ターミナルで`python`と入力すると、システムは`C:\opt\custompython\bin`（最後のディレクトリ）にあるPythonプログラムを見つけ、それを使用します。 - -//// - -つまり、ターミナルで次のように入力すると: - -
- -```console -$ python -``` - -
- -//// tab | Linux, macOS - -システムは`/opt/custompython/bin`にある`python`プログラムを**見つけ**て実行します。 - -これは、次のように入力するのとおおむね同等です: - -
- -```console -$ /opt/custompython/bin/python -``` - -
- -//// - -//// tab | Windows - -システムは`C:\opt\custompython\bin\python`にある`python`プログラムを**見つけ**て実行します。 - -これは、次のように入力するのとおおむね同等です: - -
- -```console -$ C:\opt\custompython\bin\python -``` - -
- -//// - -この情報は、[仮想環境](virtual-environments.md)について学ぶ際にも役立ちます。 - -## まとめ { #conclusion } - -これで、**環境変数**とは何か、Pythonでどのように使用するかについて、基本的な理解が得られたはずです。 - -環境変数についての詳細は、[Wikipedia の環境変数](https://en.wikipedia.org/wiki/Environment_variable)も参照してください。 - -多くの場合、環境変数がどのように役立ち、すぐに適用できるのかはあまり明確ではありません。しかし、開発中のさまざまなシナリオで何度も登場するため、知っておくとよいでしょう。 - -例えば、次のセクションの[仮想環境](virtual-environments.md)でこの情報が必要になります。 +環境変数の作成方法や読み取り方法、`PATH`環境変数の仕組みなど、クロスプラットフォームでの詳しい説明については、[環境変数ガイド](https://tiangolo.com/guides/environment-variables/)を読んでください。 diff --git a/docs/ja/docs/fastapi-cli.md b/docs/ja/docs/fastapi-cli.md index 70bef6c..7c5277c 100644 --- a/docs/ja/docs/fastapi-cli.md +++ b/docs/ja/docs/fastapi-cli.md @@ -2,7 +2,7 @@ **FastAPI CLI** は、FastAPI アプリの提供、FastAPI プロジェクトの管理などに使用できるコマンドラインプログラムです。 -FastAPI をインストールすると（例: `pip install "fastapi[standard]"`）、ターミナルで実行できるコマンドラインプログラムが付属します。 +FastAPI をプロジェクトに追加すると（例: `uv add "fastapi[standard]"`）、ターミナルで実行できるコマンドラインプログラムが付属します。 開発用に FastAPI アプリを起動するには、`fastapi dev` コマンドを使用できます: @@ -52,7 +52,7 @@ $ fastapi dev /// -内部的には、**FastAPI CLI** は [Uvicorn](https://www.uvicorn.dev)（高性能で本番運用向けの ASGI サーバー）を使用します。😎 +内部的には、**FastAPI CLI** は [Uvicorn](https://uvicorn.dev)（高性能で本番運用向けの ASGI サーバー）を使用します。😎 `fastapi` CLI は、実行する FastAPI アプリを自動検出しようとします。既定では、`main.py` の中にある `app` という名前のオブジェクト（ほかにもいくつかの変種）であると仮定します。 @@ -100,13 +100,13 @@ from backend.main import app `fastapi dev` コマンドにファイルパスを渡すこともでき、使用する FastAPI アプリオブジェクトを推測します: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` または、`fastapi dev` コマンドに `--entrypoint` オプションを渡すこともできます: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` ただし、そのたびに `fastapi` コマンドを呼び出す際に正しいパスや entrypoint を渡す必要があります。 @@ -119,9 +119,13 @@ $ fastapi dev --entrypoint main:app デフォルトでは、**auto-reload** が有効です。コードを変更するとサーバーが自動で再読み込みされます。これはリソースを多く消費し、無効時より安定性が低くなる可能性があります。開発時のみに使用してください。また、IP アドレス `127.0.0.1`（マシン自身のみと通信するための IP、`localhost`）で待ち受けます。 +アプリを import する前に、`fastapi dev` は `FASTAPI_ENV` 環境変数を `development` に設定します。`FASTAPI_ENV` がすでに設定されている場合、既存の値は保持されます。これにより、アプリ固有の環境（`staging` など）を指定できるようにしつつ、アプリの起動コードが開発向けの動作を選択できます。 + +慣例的な `FASTAPI_ENV` の値は `development` と `production` です。`fastapi run` は現在 `FASTAPI_ENV` を変更しないため、アプリが本番モードを検出する必要がある場合は明示的に設定してください。 + ## `fastapi run` { #fastapi-run } -`fastapi run` を実行すると、デフォルトで本番モードで起動します。 +`fastapi run` を実行すると、本番モードで FastAPI を起動します。 デフォルトでは、**auto-reload** は無効です。また、IP アドレス `0.0.0.0`（利用可能なすべての IP アドレスを意味します）で待ち受けるため、そのマシンと通信できる任意のクライアントから公開アクセスが可能になります。これは、たとえばコンテナ内など、本番環境で一般的な実行方法です。 diff --git a/docs/ja/docs/features.md b/docs/ja/docs/features.md index 9309884..bb4871c 100644 --- a/docs/ja/docs/features.md +++ b/docs/ja/docs/features.md @@ -19,7 +19,7 @@ ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* [**ReDoc**](https://github.com/Rebilly/ReDoc) による代替の API ドキュメント。 +* [**ReDoc**](https://github.com/Redocly/redoc) による代替の API ドキュメント。 ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) @@ -159,7 +159,7 @@ FastAPI には、非常に使いやすく、かつ非常に強力な ORM、ODM など）も含まれます。 diff --git a/docs/ja/docs/help-fastapi.md b/docs/ja/docs/help-fastapi.md index 4a5e050..827f32c 100644 --- a/docs/ja/docs/help-fastapi.md +++ b/docs/ja/docs/help-fastapi.md @@ -46,20 +46,6 @@ GitHubでFastAPIを「Watch」できます（右上の「Watch」ボタンをク * [**Bluesky** の @tiangolo.com](https://bsky.app/profile/tiangolo.com) * [**LinkedIn** の @tiangolo](https://www.linkedin.com/in/tiangolo/)。 -## GitHubで質問に困っている人を助ける { #help-others-with-questions-in-github } - -[GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered) で、他の人の質問を手助けできます。 - -多くの場合、その質問の答えをすでに知っているかもしれません。🤓 - -多くの人の質問に答えて助けてくれたなら、あなたは公式の[FastAPI Expert](fastapi-people.md#fastapi-experts)になります。🎉 - -最も大事なポイントは「親切であること」を心がけることです。🤗 - -### 手助けの方法 { #how-to-help } - -こちらの[ヘルプの仕方ガイド](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github)に従ってください。 - ## 質問する { #ask-questions } GitHubレポジトリで[新しい質問](https://github.com/fastapi/fastapi/discussions/new?category=questions)を作成できます。例えば: @@ -69,7 +55,7 @@ GitHubレポジトリで[新しい質問](https://github.com/fastapi/fastapi/dis ## チャットに参加 { #join-the-chat } -👥 [Discord チャットサーバー](https://discord.gg/VQjSZaeJmf) 👥 に参加し、FastAPI コミュニティのみんなと交流しましょう。 +👥 [Discord チャットサーバー](https://discord.com/invite/VQjSZaeJmf) 👥 に参加し、FastAPI コミュニティのみんなと交流しましょう。 /// tip | 豆知識 @@ -86,3 +72,9 @@ GitHubレポジトリで[新しい質問](https://github.com/fastapi/fastapi/dis GitHub では、テンプレートが正しい形で質問を書くのを助けてくれるため、良い回答を得やすくなりますし、質問する前に自分で問題を解決できることもあります。 また、チャットの会話は GitHub ほど検索しやすくなく、流れてしまいます。 + +## FastAPI Cloud を試す { #try-fastapi-cloud } + +FastAPI とその仲間の主な資金源は、FastAPI アプリケーションをシンプルかつ高速に、単一のコマンド `fastapi deploy` でデプロイするためのプラットフォームである [**FastAPI Cloud**](https://fastapicloud.com) です。 + +FastAPI Cloud は FastAPI を支える同じチームによって構築されています。試してみて、あなたのプロジェクトでの利用を検討できます。 diff --git a/docs/ja/docs/history-design-future.md b/docs/ja/docs/history-design-future.md index 8364002..39d1dd9 100644 --- a/docs/ja/docs/history-design-future.md +++ b/docs/ja/docs/history-design-future.md @@ -54,11 +54,11 @@ ## 要件 { #requirements } -いくつかの代替手法を試したあと、私は[**Pydantic**](https://docs.pydantic.dev/)の強みを利用することを決めました。 +いくつかの代替手法を試したあと、私は[**Pydantic**](https://pydantic.dev/docs/)の強みを利用することを決めました。 そして、JSON Schemaに完全に準拠するようにしたり、制約宣言を定義するさまざまな方法をサポートしたり、いくつかのエディターでのテストに基づいてエディターのサポート (型チェック、自動補完) を改善するために貢献しました。 -開発中、もう1つの重要な鍵となる[**Starlette**](https://www.starlette.dev/)にも貢献しました。 +開発中、もう1つの重要な鍵となる[**Starlette**](https://starlette.dev/)にも貢献しました。 ## 開発 { #development } diff --git a/docs/ja/docs/how-to/custom-request-and-route.md b/docs/ja/docs/how-to/custom-request-and-route.md index 2043501..90feabb 100644 --- a/docs/ja/docs/how-to/custom-request-and-route.md +++ b/docs/ja/docs/how-to/custom-request-and-route.md @@ -66,7 +66,7 @@ gzip のリクエストを解凍するために、カスタムの `Request` サ そしてこの 2 つ（`scope` と `receive`）が、新しい `Request` インスタンスを作成するために必要なものです。 -`Request` について詳しくは、[Starlette の Requests に関するドキュメント](https://www.starlette.dev/requests/) を参照してください。 +`Request` について詳しくは、[Starlette の Requests に関するドキュメント](https://starlette.dev/requests/) を参照してください。 /// diff --git a/docs/ja/docs/how-to/extending-openapi.md b/docs/ja/docs/how-to/extending-openapi.md index 9b2fabc..478e101 100644 --- a/docs/ja/docs/how-to/extending-openapi.md +++ b/docs/ja/docs/how-to/extending-openapi.md @@ -10,7 +10,7 @@ `FastAPI` アプリケーション（インスタンス）には、OpenAPI スキーマを返すことが期待される `.openapi()` メソッドがあります。 -アプリケーションオブジェクトの作成時に、`/openapi.json`（または `openapi_url` に設定したパス）への path operation が登録されます。 +アプリケーションオブジェクトの作成時に、`/openapi.json`（または `openapi_url` に設定したパス）への *path operation* が登録されます。 これは単に、アプリケーションの `.openapi()` メソッドの結果を含む JSON レスポンスを返します。 @@ -25,9 +25,9 @@ - `openapi_version`: 使用する OpenAPI 仕様のバージョン。デフォルトは最新の `3.1.0`。 - `summary`: API の短い概要。 - `description`: API の説明。Markdown を含めることができ、ドキュメントに表示されます。 -- `routes`: アプリケーションのルート。`app.routes` から取得されます。FastAPI はこれらを使用して、登録済みの path operation（取り込んだルーター由来のものも含む）を収集します。 +- `routes`: アプリケーションのルート。`app.routes` から取得されます。FastAPI はこれらを使用して、登録済みの *path operation*（取り込んだルーター由来のものも含む）を収集します。 -/// tip | 技術詳細 +/// tip | 豆知識 `app.routes` はより低レベルなルートツリーです。最終的な `APIRoute` オブジェクトだけでなく、FastAPI が内部で使用する、取り込まれたルーター向けの候補ルートも含まれることがあります。 @@ -45,7 +45,7 @@ 上記の情報を使って、同じユーティリティ関数で OpenAPI スキーマを生成し、必要な部分を上書きできます。 -たとえば、[カスタムロゴを含めるための ReDoc の OpenAPI 拡張](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo)を追加してみましょう。 +たとえば、[カスタムロゴを含めるための ReDoc の OpenAPI 拡張](https://github.com/Redocly/redoc/blob/main/docs/redoc-vendor-extensions.md#x-logo)を追加してみましょう。 ### 通常の **FastAPI** { #normal-fastapi } diff --git a/docs/ja/docs/how-to/graphql.md b/docs/ja/docs/how-to/graphql.md index 8cc2f95..b60aba1 100644 --- a/docs/ja/docs/how-to/graphql.md +++ b/docs/ja/docs/how-to/graphql.md @@ -22,7 +22,7 @@ * [Strawberry](https://strawberry.rocks/) 🍓 * [FastAPI 向けドキュメント](https://strawberry.rocks/docs/integrations/fastapi)あり * [Ariadne](https://ariadnegraphql.org/) - * [FastAPI 向けドキュメント](https://ariadnegraphql.org/docs/fastapi-integration)あり + * [FastAPI 向けドキュメント](https://ariadnegraphql.org/server/Integrations/fastapi-integration)あり * [Tartiflette](https://tartiflette.io/) * ASGI 連携用の [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) あり * [Graphene](https://graphene-python.org/) diff --git a/docs/ja/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/ja/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index 1d93de5..3c5a470 100644 --- a/docs/ja/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/ja/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -24,7 +24,7 @@ Python の最新機能を使いたい場合は、Pydantic v2 を使用してい ## 公式ガイド { #official-guide } -Pydantic には v1 から v2 への公式の [移行ガイド](https://docs.pydantic.dev/latest/migration/) があります。 +Pydantic には v1 から v2 への公式の [移行ガイド](https://pydantic.dev/docs/validation/latest/get-started/migration/) があります。 変更点、検証がより正確で厳密になった点、注意事項などが含まれます。 diff --git a/docs/ja/docs/index.md b/docs/ja/docs/index.md index 97ee2f5..ac1e338 100644 --- a/docs/ja/docs/index.md +++ b/docs/ja/docs/index.md @@ -32,7 +32,7 @@ include_yaml: --- -**ドキュメント**: [https://fastapi.tiangolo.com/ja](https://fastapi.tiangolo.com/ja) +**ドキュメント**: [https://fastapi.tiangolo.com](https://fastapi.tiangolo.com/ja) **ソースコード**: [https://github.com/fastapi/fastapi](https://github.com/fastapi/fastapi) @@ -105,19 +105,19 @@ FastAPI は、Python の標準である型ヒントに基づいて Python で AP
-
「最近は **FastAPI** をたくさん使っています。実際、私のチームの **Microsoft の ML サービス** 全てで使用する予定です。そのいくつかはコアな **Windows** 製品や **Office** 製品に統合されつつあります。」
+
「最近は FastAPI をたくさん使っています。実際、私のチームの Microsoft の ML サービス 全てで使用する予定です。そのいくつかはコアな Windows 製品や Office 製品に統合されつつあります。」
— Kabir Khan, Microsoft (ref)
@@ -125,7 +125,7 @@ FastAPI は、Python の標準である型ヒントに基づいて Python で AP
-"_[...] 最近 **FastAPI** をたくさん使っています。 [...] 実際に私のチームの全ての **Microsoft の機械学習サービス** で使用する予定です。 そのうちのいくつかのコアな **Windows** 製品と **Office** 製品に統合されつつあります。_" +"_[...] 最近 **FastAPI** をたくさん使っています。 [...] 実際に私のチームの全ての **Microsoft の ML サービス** で使用する予定です。 そのうちのいくつかのコアな **Windows** 製品と **Office** 製品に統合されつつあります。_"
Kabir Khan - Microsoft (ref)
@@ -133,7 +133,7 @@ FastAPI は、Python の標準である型ヒントに基づいて Python で AP "_FastAPIライブラリを採用し、クエリで **予測値** を取得できる **REST** サーバを構築しました。 [for Ludwig]_" -
Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - Uber (ref)
+
Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - Uber (ref)
--- @@ -151,12 +151,6 @@ FastAPI は、Python の標準である型ヒントに基づいて Python で AP
-## FastAPI Conf { #fastapi-conf } - -[**FastAPI Conf '26**](https://fastapiconf.com) は **2026 年 10 月 28 日** に **オランダ・アムステルダム** で開催されます。FastAPI のすべてを、ソースから直接。🎤 - -FastAPI Conf '26 - 2026年10月28日 - オランダ・アムステルダム - ## FastAPI ミニドキュメンタリー { #fastapi-mini-documentary } 2025 年末に公開された [FastAPI ミニドキュメンタリー](https://www.youtube.com/watch?v=mpR8ngthqiE)があります。オンラインで視聴できます: @@ -173,19 +167,19 @@ Web API の代わりにターミナルで使用する ```console -$ pip install "fastapi[standard]" +$ uv add "fastapi[standard]" ---> 100% ``` @@ -194,6 +188,8 @@ $ pip install "fastapi[standard]" **注**: すべてのターミナルで動作するように、`"fastapi[standard]"` は必ずクォートで囲んでください。 +`pip` を使いたい場合は、仮想環境内で `fastapi[standard]` をインストールしてください。代替手順については、[インストールガイド](tutorial/#install-fastapi) を参照してください。 + ## アプリケーション例 { #example } ### 作成 { #create-it } @@ -250,7 +246,7 @@ async def read_item(item_id: int, q: str | None = None):
```console -$ fastapi dev +$ uv run fastapi dev ╭────────── FastAPI CLI - Development mode ───────────╮ │ │ @@ -277,7 +273,7 @@ INFO: Application startup complete.
fastapi dev コマンドについて... -`fastapi dev` コマンドは `main.py` ファイルを自動的に読み取り、その中の **FastAPI** アプリを検出し、[Uvicorn](https://www.uvicorn.dev) を使用してサーバーを起動します。 +`fastapi dev` コマンドは `main.py` ファイルを自動的に読み取り、その中の **FastAPI** アプリを検出し、[Uvicorn](https://uvicorn.dev) を使用してサーバーを起動します。 デフォルトでは、`fastapi dev` はローカル開発向けに自動リロードを有効にして起動します。 @@ -314,7 +310,7 @@ INFO: Application startup complete. 次に、[http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) にアクセスします。 -代替の自動ドキュメントが表示されます（[ReDoc](https://github.com/Rebilly/ReDoc) が提供しています）。 +代替の自動ドキュメントが表示されます（[ReDoc](https://github.com/Redocly/redoc) が提供しています）。 ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -492,12 +488,12 @@ item: Item ### アプリをデプロイ（任意） { #deploy-your-app-optional } -1 コマンドで FastAPI アプリを [FastAPI Cloud](https://fastapicloud.com) にデプロイできます。 🚀 +任意で、1 コマンドで FastAPI アプリを [FastAPI Cloud](https://fastapicloud.com) にデプロイできます。 🚀
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -540,7 +536,7 @@ FastAPI は Pydantic と Starlette に依存しています。 ### `standard` 依存関係 { #standard-dependencies } -FastAPI を `pip install "fastapi[standard]"` でインストールすると、`standard` グループのオプション依存関係が含まれます。 +FastAPI を `uv add "fastapi[standard]"` でインストールすると、`standard` グループのオプション依存関係が含まれます。 Pydantic によって使用されるもの: @@ -554,17 +550,17 @@ Starlette によって使用されるもの: FastAPI によって使用されるもの: -* [`uvicorn`](https://www.uvicorn.dev) - アプリケーションをロードして提供するサーバーのため。これには `uvicorn[standard]` も含まれ、高性能なサービングに必要な依存関係（例: `uvloop`）が含まれます。 +* [`uvicorn`](https://uvicorn.dev) - アプリケーションをロードして提供するサーバーのため。これには `uvicorn[standard]` も含まれ、高性能なサービングに必要な依存関係（例: `uvloop`）が含まれます。 * `fastapi-cli[standard]` - `fastapi` コマンドを提供します。 * これには `fastapi-cloud-cli` が含まれ、FastAPI アプリケーションを [FastAPI Cloud](https://fastapicloud.com) にデプロイできます。 ### `standard` 依存関係なし { #without-standard-dependencies } -`standard` のオプション依存関係を含めたくない場合は、`pip install "fastapi[standard]"` の代わりに `pip install fastapi` でインストールできます。 +`standard` のオプション依存関係を含めたくない場合は、`uv add "fastapi[standard]"` の代わりに `uv add fastapi` でインストールできます。 ### `fastapi-cloud-cli` なし { #without-fastapi-cloud-cli } -標準の依存関係を含めつつ `fastapi-cloud-cli` を除外して FastAPI をインストールしたい場合は、`pip install "fastapi[standard-no-fastapi-cloud-cli]"` でインストールできます。 +標準の依存関係を含めつつ `fastapi-cloud-cli` を除外して FastAPI をインストールしたい場合は、`uv add "fastapi[standard-no-fastapi-cloud-cli]"` でインストールできます。 ### 追加のオプション依存関係 { #additional-optional-dependencies } @@ -572,13 +568,13 @@ FastAPI によって使用されるもの: 追加のオプション Pydantic 依存関係: -* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - 設定管理のため。 -* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - Pydantic で使用する追加の型のため。 +* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) - 設定管理のため。 +* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) - Pydantic で使用する追加の型のため。 追加のオプション FastAPI 依存関係: * [`orjson`](https://github.com/ijl/orjson) - `ORJSONResponse` を使用したい場合に必要です。 -* [`ujson`](https://github.com/esnme/ultrajson) - `UJSONResponse` を使用したい場合に必要です。 +* [`ujson`](https://github.com/ultrajson/ultrajson) - `UJSONResponse` を使用したい場合に必要です。 ## ライセンス { #license } diff --git a/docs/ja/docs/project-generation.md b/docs/ja/docs/project-generation.md index 829d6a6..0ac2eb8 100644 --- a/docs/ja/docs/project-generation.md +++ b/docs/ja/docs/project-generation.md @@ -4,13 +4,13 @@ このテンプレートを使って開始できます。初期セットアップの多く、セキュリティ、データベース、いくつかのAPIエンドポイントがすでに用意されています。 -GitHubリポジトリ: [Full Stack FastAPI Template](https://github.com/tiangolo/full-stack-fastapi-template) +GitHubリポジトリ: [Full Stack FastAPI Template](https://github.com/fastapi/full-stack-fastapi-template) ## Full Stack FastAPI テンプレート - 技術スタックと機能 { #full-stack-fastapi-template-technology-stack-and-features } - ⚡ PythonバックエンドAPI向けの [**FastAPI**](https://fastapi.tiangolo.com/ja)。 - 🧰 PythonのSQLデータベース操作（ORM）向けの [SQLModel](https://sqlmodel.tiangolo.com)。 - - 🔍 FastAPIで使用される、データバリデーションと設定管理向けの [Pydantic](https://docs.pydantic.dev)。 + - 🔍 FastAPIで使用される、データバリデーションと設定管理向けの [Pydantic](https://pydantic.dev/docs/)。 - 💾 SQLデータベースとしての [PostgreSQL](https://www.postgresql.org)。 - 🚀 フロントエンド向けの [React](https://react.dev)。 - 💃 TypeScript、hooks、Vite、その他のモダンなフロントエンドスタックの各要素を使用。 diff --git a/docs/ja/docs/python-types.md b/docs/ja/docs/python-types.md index e6ff3c2..d57859c 100644 --- a/docs/ja/docs/python-types.md +++ b/docs/ja/docs/python-types.md @@ -269,7 +269,7 @@ def some_function(data: Any): ## Pydantic のモデル { #pydantic-models } -[Pydantic](https://docs.pydantic.dev/) はデータ検証を行うための Python ライブラリです。 +[Pydantic](https://pydantic.dev/docs/) はデータ検証を行うための Python ライブラリです。 データの「形」を属性付きのクラスとして宣言します。 @@ -285,7 +285,7 @@ Pydantic の公式ドキュメントからの例: /// note | 備考 -[Pydantic の詳細はドキュメントを参照してください](https://docs.pydantic.dev/)。 +[Pydantic の詳細はドキュメントを参照してください](https://pydantic.dev/docs/)。 /// diff --git a/docs/ja/docs/tutorial/background-tasks.md b/docs/ja/docs/tutorial/background-tasks.md index 0bacbb3..71d9f9e 100644 --- a/docs/ja/docs/tutorial/background-tasks.md +++ b/docs/ja/docs/tutorial/background-tasks.md @@ -63,7 +63,7 @@ ## 技術的な詳細 { #technical-details } -`BackgroundTasks` クラスは、[`starlette.background`](https://www.starlette.dev/background/) から直接取得されます。 +`BackgroundTasks` クラスは、[`starlette.background`](https://starlette.dev/background/) から直接取得されます。 これは、FastAPI に直接インポート/インクルードされるため、`fastapi` からインポートできる上に、`starlette.background`から別の `BackgroundTask` (末尾に `s` がない) を誤ってインポートすることを回避できます。 @@ -71,7 +71,7 @@ それでも、FastAPI で `BackgroundTask` を単独で使用することは可能ですが、コード内でオブジェクトを作成し、それを含むStarlette `Response` を返す必要があります。 -詳細については、[Starlette のバックグラウンドタスクに関する公式ドキュメント](https://www.starlette.dev/background/)を参照して下さい。 +詳細については、[Starlette のバックグラウンドタスクに関する公式ドキュメント](https://starlette.dev/background/)を参照して下さい。 ## 注意 { #caveat } diff --git a/docs/ja/docs/tutorial/bigger-applications.md b/docs/ja/docs/tutorial/bigger-applications.md index 51ea7be..ebed896 100644 --- a/docs/ja/docs/tutorial/bigger-applications.md +++ b/docs/ja/docs/tutorial/bigger-applications.md @@ -487,7 +487,7 @@ from app.main import app コマンドにパスを渡すこともできます。例えば: ```console -$ fastapi dev app/main.py +$ uv run fastapi dev app/main.py ``` しかし、そのたびに `fastapi` コマンドを呼ぶ際、正しいパスを渡すのを忘れないようにする必要があります。 @@ -503,7 +503,7 @@ $ fastapi dev app/main.py
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/ja/docs/tutorial/body-nested-models.md b/docs/ja/docs/tutorial/body-nested-models.md index d926189..c36068d 100644 --- a/docs/ja/docs/tutorial/body-nested-models.md +++ b/docs/ja/docs/tutorial/body-nested-models.md @@ -97,7 +97,7 @@ Pydanticモデルの各属性には型があります。 `str`や`int`、`float`などの通常の単数型の他にも、`str`を継承したより複雑な単数型を使うこともできます。 -すべてのオプションをみるには、[Pydantic の型の概要](https://docs.pydantic.dev/latest/concepts/types/)を確認してください。次の章でいくつかの例をみることができます。 +すべてのオプションをみるには、[Pydantic の型の概要](https://pydantic.dev/docs/validation/latest/concepts/types/)を確認してください。次の章でいくつかの例をみることができます。 例えば、`Image`モデルのように`url`フィールドがある場合、`str`の代わりにPydanticの`HttpUrl`のインスタンスとして宣言することができます: diff --git a/docs/ja/docs/tutorial/body.md b/docs/ja/docs/tutorial/body.md index c26198d..cda27b3 100644 --- a/docs/ja/docs/tutorial/body.md +++ b/docs/ja/docs/tutorial/body.md @@ -1,13 +1,12 @@ # リクエストボディ { #request-body } - クライアント（例えばブラウザ）からAPIにデータを送信する必要がある場合、**リクエストボディ**として送信します。 **リクエスト**ボディは、クライアントからAPIへ送信されるデータです。**レスポンス**ボディは、APIがクライアントに送信するデータです。 APIはほとんどの場合 **レスポンス** ボディを送信する必要があります。しかしクライアントは、常に **リクエストボディ** を送信する必要があるとは限りません。場合によっては、クエリパラメータ付きのパスだけをリクエストして、ボディを送信しないこともあります。 -**リクエスト**ボディを宣言するには、[Pydantic](https://docs.pydantic.dev/) モデルを使用し、その強力な機能とメリットをすべて利用します。 +**リクエスト**ボディを宣言するには、[Pydantic](https://pydantic.dev/docs/) モデルを使用し、その強力な機能とメリットをすべて利用します。 /// note | 備考 diff --git a/docs/ja/docs/tutorial/debugging.md b/docs/ja/docs/tutorial/debugging.md index 1a02e19..984fa28 100644 --- a/docs/ja/docs/tutorial/debugging.md +++ b/docs/ja/docs/tutorial/debugging.md @@ -15,7 +15,7 @@ FastAPIアプリケーション上で、`uvicorn` を直接インポートして
```console -$ python myapp.py +$ uv run python myapp.py ```
@@ -35,7 +35,7 @@ from myapp import app
```console -$ python myapp.py +$ uv run python myapp.py ```
diff --git a/docs/ja/docs/tutorial/extra-data-types.md b/docs/ja/docs/tutorial/extra-data-types.md index b63e3fe..dede182 100644 --- a/docs/ja/docs/tutorial/extra-data-types.md +++ b/docs/ja/docs/tutorial/extra-data-types.md @@ -37,7 +37,7 @@ * `datetime.timedelta`: * Pythonの`datetime.timedelta`です。 * リクエストとレスポンスでは合計秒数の`float`で表現されます。 - * Pydanticでは「ISO 8601 time diff encoding」として表現することも可能です。[詳細はドキュメントを参照してください](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers)。 + * Pydanticでは「ISO 8601 time diff encoding」として表現することも可能です。[詳細はドキュメントを参照してください](https://pydantic.dev/docs/validation/latest/concepts/serialization/#custom-serializers)。 * `frozenset`: * リクエストとレスポンスでは`set`と同じように扱われます: * リクエストでは、リストが読み込まれ、重複を排除して`set`に変換されます。 @@ -50,7 +50,7 @@ * `Decimal`: * Pythonの標準的な`Decimal`です。 * リクエストとレスポンスでは`float`と同じように扱われます。 -* 有効なPydanticのデータ型はここで確認できます: [Pydantic のデータ型](https://docs.pydantic.dev/latest/usage/types/types/)。 +* 有効なPydanticのデータ型はここで確認できます: [Pydantic のデータ型](https://pydantic.dev/docs/validation/latest/concepts/types/)。 ## 例 { #example } diff --git a/docs/ja/docs/tutorial/extra-models.md b/docs/ja/docs/tutorial/extra-models.md index d954850..1d64e95 100644 --- a/docs/ja/docs/tutorial/extra-models.md +++ b/docs/ja/docs/tutorial/extra-models.md @@ -166,7 +166,7 @@ OpenAPIでは`anyOf`で定義されます。 /// note | 備考 -[`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions)を定義する場合は、最も具体的な型を先に、その後により具体性の低い型を含めてください。以下の例では、より具体的な`PlaneItem`が`Union[PlaneItem, CarItem]`内で`CarItem`より前に来ています。 +[`Union`](https://pydantic.dev/docs/validation/latest/concepts/unions/)を定義する場合は、最も具体的な型を先に、その後により具体性の低い型を含めてください。以下の例では、より具体的な`PlaneItem`が`Union[PlaneItem, CarItem]`内で`CarItem`より前に来ています。 /// diff --git a/docs/ja/docs/tutorial/first-steps.md b/docs/ja/docs/tutorial/first-steps.md index ae0556d..2c611fa 100644 --- a/docs/ja/docs/tutorial/first-steps.md +++ b/docs/ja/docs/tutorial/first-steps.md @@ -6,12 +6,18 @@ これを`main.py`にコピーします。 +/// tip | 豆知識 + +FastAPIには[VS Code向けの公式拡張機能](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode)（およびCursor）があります。path operation explorer、path operation search、テスト内のCodeLensナビゲーション（テストから定義へジャンプ）、FastAPI Cloudへのデプロイとログなど、多くの機能をすべてエディタから利用できます。 + +/// + ライブサーバーを実行します:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -78,7 +84,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) 次に、[http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)にアクセスします。 -代替の自動生成ドキュメントが表示されます（[ReDoc](https://github.com/Rebilly/ReDoc)によって提供）: +代替の自動生成ドキュメントが表示されます（[ReDoc](https://github.com/Redocly/redoc)によって提供）: ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -185,13 +191,13 @@ from backend.main import app `fastapi dev`コマンドにファイルパスを渡すこともでき、使用すべきFastAPIのappオブジェクトを推測します: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` または、`fastapi dev`コマンドに`--entrypoint`オプションを渡すこともできます: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` ただし、その場合は毎回`fastapi`コマンドを呼ぶたびに正しいパスや`entrypoint`を渡すことを覚えておく必要があります。 @@ -205,7 +211,7 @@ $ fastapi dev --entrypoint main:app
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -232,7 +238,7 @@ CLIはFastAPIアプリケーションを自動検出してクラウドにデプ `FastAPI`は`Starlette`を直接継承するクラスです。 -`FastAPI`でも[Starlette](https://www.starlette.dev/)のすべての機能を利用可能です。 +`FastAPI`でも[Starlette](https://starlette.dev/)のすべての機能を利用可能です。 /// @@ -312,7 +318,7 @@ APIを構築するときは、通常、これらの特定のHTTPメソッドを `@app.get("/")`は直下の関数が下記のリクエストの処理を担当することを**FastAPI**に伝えます: * パス `/` -* get オペレーション +* get オペレーションを使用する /// note | `@decorator` 情報 diff --git a/docs/ja/docs/tutorial/frontend.md b/docs/ja/docs/tutorial/frontend.md index eb23d1e..a2aac44 100644 --- a/docs/ja/docs/tutorial/frontend.md +++ b/docs/ja/docs/tutorial/frontend.md @@ -52,7 +52,7 @@ npm run build {* ../../docs_src/frontend/tutorial002_py310.py hl[5] *} -**FastAPI** は、このフォールバックをブラウザのナビゲーションに見える `GET` および `HEAD` リクエストにのみ使用します。JavaScript、CSS、画像などの存在しないファイルは引き続き `404` を返します。 +**FastAPI** は、このフォールバックを、通常のブラウザナビゲーションリクエストのように `Accept: text/html` または `Accept: application/xhtml+xml` で明示的に HTML を受け付ける `GET` および `HEAD` リクエストにのみ使用します。JavaScript、CSS、画像などの存在しないファイルは引き続き `404` を返します。 `POST` や `PUT` など、他のメソッドのリクエストがフロントエンドのフォールバックにのみ一致するパスへ送られた場合も、`404` を返します。通常の **FastAPI** の *path operations* は、フロントエンドのルートよりも引き続き高い優先順位を持ちます。 @@ -106,11 +106,15 @@ npm run build ## ディレクトリのチェック { #check-directory } -デフォルトでは、`app.frontend()` はアプリ作成時にディレクトリが存在することをチェックします。 +デフォルトでは、`app.frontend()` は `check_dir="auto"` を使います。 -これにより、設定エラーを早期に検出できます。たとえば、フロントエンドのビルド出力ディレクトリが存在しない場合、**FastAPI** は起動時にエラーを発生させます。 +`FASTAPI_ENV` 環境変数が `development` に設定されている場合、フロントエンドのビルド出力ディレクトリが存在しなくても、**FastAPI** は警告を表示するだけです。[`fastapi dev` コマンド](https://github.com/fastapi/fastapi-cli#fastapi-dev) は、この環境変数がまだ設定されていない場合に設定してくれます。これにより、開発中にフロントエンドをビルドまたは起動する前にバックエンドを起動できます。 -アプリオブジェクトの作成後に別のビルドステップなどでフロントエンドファイルが作成される場合は、`check_dir=False` を設定します。 +それ以外の環境では、**FastAPI** はアプリ作成時にエラーを発生させます。これにより、フロントエンドファイルなしでアプリをデプロイする前に、設定エラーを早期に検出できます。 + +`check_dir=True` を設定して、アプリ作成時に常にディレクトリをチェックすることもできます。 + +フロントエンドファイルが後で作成される場合、たとえばアプリオブジェクトの作成後に別のビルドステップで作成される場合は、`check_dir=False` を設定します。 {* ../../docs_src/frontend/tutorial006_py310.py hl[5] *} @@ -132,6 +136,8 @@ npm run build アプリ、`APIRouter`、および `include_router()` からの依存関係もフロントエンドのレスポンスに適用されます。これは、cookie 認証などでフロントエンドを保護する場合に役立ちます。 +依存関係は、通常の *path operations* と同様に、レスポンスヘッダーを変更したりバックグラウンドタスクを追加したりすることもできます。 + ## 静的ビルド出力のみ { #static-build-output-only } `app.frontend()` は、フロントエンドのビルドで既に生成されたファイルを配信します。 diff --git a/docs/ja/docs/tutorial/handling-errors.md b/docs/ja/docs/tutorial/handling-errors.md index 491b72d..cc67ec1 100644 --- a/docs/ja/docs/tutorial/handling-errors.md +++ b/docs/ja/docs/tutorial/handling-errors.md @@ -82,7 +82,7 @@ Pythonの例外なので、`return`ではなく、`raise`です。 ## カスタム例外ハンドラのインストール { #install-custom-exception-handlers } -カスタム例外ハンドラは[Starletteと同じ例外ユーティリティ](https://www.starlette.dev/exceptions/)を使用して追加することができます。 +カスタム例外ハンドラは[Starletteと同じ例外ユーティリティ](https://starlette.dev/exceptions/)を使用して追加することができます。 あなた（または使用しているライブラリ）が`raise`するかもしれないカスタム例外`UnicornException`があるとしましょう。 diff --git a/docs/ja/docs/tutorial/index.md b/docs/ja/docs/tutorial/index.md index 42b0eb5..a29d100 100644 --- a/docs/ja/docs/tutorial/index.md +++ b/docs/ja/docs/tutorial/index.md @@ -1,6 +1,5 @@ # チュートリアル - ユーザーガイド { #tutorial-user-guide } - このチュートリアルでは、**FastAPI**のほとんどの機能を使う方法を段階的に紹介します。 各セクションは前のセクションを踏まえた内容になっています。しかし、トピックごとに分割されているので、特定のAPIのニーズを満たすために、任意の特定のトピックに直接進めるようになっています。 @@ -11,12 +10,12 @@ すべてのコードブロックをコピーして直接使用できます（実際にテストされたPythonファイルです）。 -いずれかの例を実行するには、コードを `main.py`ファイルにコピーし、次のように `fastapi dev` を起動します: +いずれかの例を実行するには、コードを `main.py`ファイルにコピーし、`uv run` で `fastapi dev` を起動します:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -61,35 +60,75 @@ $ fastapi dev ## FastAPIをインストールする { #install-fastapi } -最初のステップは、FastAPIのインストールです。 +最初のステップは、プロジェクトをセットアップして FastAPI を追加することです。 -[仮想環境](../virtual-environments.md) を作成して有効化し、それから **FastAPIをインストール** してください: +[`uv`](https://docs.astral.sh/uv/getting-started/installation/) をインストールし、プロジェクトを作成して FastAPI を追加します:
```console -$ pip install "fastapi[standard]" +$ uv init awesome-project --bare +$ cd awesome-project +$ uv add "fastapi[standard]" ---> 100% ```
+`uv add` はプロジェクトの仮想環境を `.venv` に作成し、FastAPI を `pyproject.toml` に追加し、後で同じパッケージバージョンをインストールできるように `uv.lock` を作成します。 + +/// details | これらのコマンドが行うこと + +* `uv init`: 新しい Python プロジェクトを作成します。 +* `awesome-project`: この名前の新しいディレクトリにプロジェクトを作成します。 +* `--bare`: サンプルの `main.py`、`README.md`、その他のファイルを生成せず、最小限の `pyproject.toml` ファイルだけを作成します。このチュートリアルの次のステップで、アプリケーションファイルは自分で作成します。 + +その後、FastAPI を追加する前に `cd awesome-project` で新しいプロジェクトディレクトリに入ります。 + +`uv` は、システムにすでにインストールされている互換性のある Python バージョンを使用するか、必要に応じてダウンロードします。 + +`uv add` を実行すると、FastAPI と FastAPI が依存するすべてのパッケージの互換性のあるバージョンが選択されます。正確なバージョンは `uv.lock` に記録されるため、後で別のコンピューターやアプリケーションをデプロイするときに同じパッケージバージョンをインストールできます。 + +このファイルを作成または更新することを、[プロジェクト依存関係を**ロック**すること](https://docs.astral.sh/uv/concepts/projects/sync/)と呼びます。`uv` はパッケージを追加するときにこれを自動的に行います。 + +/// + +/// details | FastAPI のインストールオプション + +`uv add "fastapi[standard]"` でインストールすると、`fastapi-cloud-cli` を含むいくつかのデフォルトのオプション標準依存関係が付属します。これにより、[FastAPI Cloud](https://fastapicloud.com) にデプロイできます。 + +これらのオプション依存関係が不要な場合は、代わりに `uv add fastapi` をインストールできます。 + +標準依存関係はインストールしたいが `fastapi-cloud-cli` は不要な場合は、`uv add "fastapi[standard-no-fastapi-cloud-cli]"` でインストールできます。 + +/// + +/// details | 代わりに `pip` を使用する + +仮想環境とパッケージを手動で管理したい場合は、仮想環境を作成して有効化し、それから `pip install "fastapi[standard]"` で FastAPI をインストールします。 + +詳しい手順は [仮想環境ガイド](https://tiangolo.com/guides/virtual-environments/) を読んでください。 + +/// + +## AI Agent Skills { #ai-agent-skills } + +FastAPI には、AI coding agents 向けの公式スキルが含まれています。これはパッケージに同梱されているため、そのガイダンスはプロジェクトにインストールされている FastAPI のバージョンと一致し、FastAPI を更新すると一緒に更新されます。 + +プロジェクトに FastAPI をインストールした後、Library Skills でスキルをインストールできます: + +```bash +uvx library-skills +``` + /// note | 備考 -`pip install "fastapi[standard]"` でインストールすると、`fastapi-cloud-cli` を含むいくつかのデフォルトのオプション標準依存関係が付属します。これにより、[FastAPI Cloud](https://fastapicloud.com) にデプロイできます。 - -これらのオプション依存関係が不要な場合は、代わりに `pip install fastapi` をインストールできます。 - -標準依存関係はインストールしたいが `fastapi-cloud-cli` は不要な場合は、`pip install "fastapi[standard-no-fastapi-cloud-cli]"` でインストールできます。 +`uvx` は `uv tool run` のエイリアスです。Library Skills がプロジェクトにインストールされたパッケージをスキャンする間、一時的で分離された環境で Library Skills を実行します。 /// -/// tip | 豆知識 - -FastAPI には [VS Code の公式拡張機能](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode)（および Cursor）があります。path operation エクスプローラー、path operation 検索、テスト内の CodeLens ナビゲーション（テストから定義へジャンプ）、そして FastAPI Cloud へのデプロイやログなど、さまざまな機能をエディターから利用できます。 - -/// +このスキルは Codex、Claude Code、Cursor、GitHub Copilot、Gemini CLI、Pi、OpenCode、およびその他ほとんどの coding agent と互換性があります。Claude Code の場合、スキルのインストール先を尋ねられたら `.claude/skills` を選択してください。 ## 高度なユーザーガイド { #advanced-user-guide } diff --git a/docs/ja/docs/tutorial/middleware.md b/docs/ja/docs/tutorial/middleware.md index 20192d0..c12c9a3 100644 --- a/docs/ja/docs/tutorial/middleware.md +++ b/docs/ja/docs/tutorial/middleware.md @@ -37,7 +37,7 @@ カスタムの独自ヘッダーは [`X-` プレフィックスを使用](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)して追加できる点に注意してください。 -ただし、ブラウザのクライアントに表示させたいカスタムヘッダーがある場合は、[CORS (Cross-Origin Resource Sharing)](cors.md) の設定に、[StarletteのCORSドキュメント](https://www.starlette.dev/middleware/#corsmiddleware)に記載されているパラメータ `expose_headers` を使用して、それらを追加する必要があります。 +ただし、ブラウザのクライアントに表示させたいカスタムヘッダーがある場合は、[CORS (Cross-Origin Resource Sharing)](cors.md) の設定に、[StarletteのCORSドキュメント](https://starlette.dev/middleware/#corsmiddleware)に記載されているパラメータ `expose_headers` を使用して、それらを追加する必要があります。 /// diff --git a/docs/ja/docs/tutorial/path-params.md b/docs/ja/docs/tutorial/path-params.md index ec47cbe..3b315e0 100644 --- a/docs/ja/docs/tutorial/path-params.md +++ b/docs/ja/docs/tutorial/path-params.md @@ -92,7 +92,7 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー ## 標準ベースのメリット、ドキュメンテーションの代替物 { #standards-based-benefits-alternative-documentation } -また、生成されたスキーマが [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md) 標準に従っているので、互換性のあるツールが多数あります。 +また、生成されたスキーマが [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) 標準に従っているので、互換性のあるツールが多数あります。 このため、**FastAPI**自体が代替のAPIドキュメントを提供します（ReDocを使用）。これは、 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) にアクセスすると確認できます。 @@ -102,7 +102,7 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー ## Pydantic { #pydantic } -すべてのデータバリデーションは [Pydantic](https://docs.pydantic.dev/) によって内部で実行されるため、Pydanticの全てのメリットが得られます。そして、安心して利用することができます。 +すべてのデータバリデーションは [Pydantic](https://pydantic.dev/docs/) によって内部で実行されるため、Pydanticの全てのメリットが得られます。そして、安心して利用することができます。 `str`、 `float` 、 `bool` および他の多くの複雑なデータ型を型宣言に使用できます。 diff --git a/docs/ja/docs/tutorial/query-params-str-validations.md b/docs/ja/docs/tutorial/query-params-str-validations.md index 38d2b5c..1391505 100644 --- a/docs/ja/docs/tutorial/query-params-str-validations.md +++ b/docs/ja/docs/tutorial/query-params-str-validations.md @@ -370,11 +370,11 @@ http://127.0.0.1:8000/items/?item-query=foobaritems その場合、通常のバリデーション（例: 値が `str` であることの検証）の後に適用される **カスタムバリデータ関数** を使えます。 -これを行うには、`Annotated` の中で [Pydantic の `AfterValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator) を使います。 +これを行うには、`Annotated` の中で [Pydantic の `AfterValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-after-validator) を使います。 /// tip | 豆知識 -Pydantic には [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator) などもあります。 🤓 +Pydantic には [`BeforeValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-before-validator) などもあります。 🤓 /// diff --git a/docs/ja/docs/tutorial/request-files.md b/docs/ja/docs/tutorial/request-files.md index f4bd231..531a126 100644 --- a/docs/ja/docs/tutorial/request-files.md +++ b/docs/ja/docs/tutorial/request-files.md @@ -7,10 +7,10 @@ アップロードされたファイルを受け取るには、まず [`python-multipart`](https://github.com/Kludex/python-multipart) をインストールします。 -[仮想環境](../virtual-environments.md)を作成して有効化し、次のようにインストールしてください: +プロジェクトに追加してください: ```console -$ pip install python-multipart +$ uv add python-multipart ``` アップロードされたファイルは「form data」として送信されるためです。 diff --git a/docs/ja/docs/tutorial/request-form-models.md b/docs/ja/docs/tutorial/request-form-models.md index 6a71c14..2230f8f 100644 --- a/docs/ja/docs/tutorial/request-form-models.md +++ b/docs/ja/docs/tutorial/request-form-models.md @@ -6,10 +6,10 @@ FastAPI では、フォームフィールドを宣言するために **Pydantic フォームを使うには、まず [`python-multipart`](https://github.com/Kludex/python-multipart) をインストールします。 -まず [仮想環境](../virtual-environments.md) を作成して有効化し、そのうえでインストールしてください。例えば: +プロジェクトに追加します: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// @@ -54,9 +54,9 @@ Pydantic のモデル設定で、`extra` フィールドを `forbid` にでき 例えば、クライアントが次のフォームフィールドを送ろうとした場合: -- `username`: `Rick` -- `password`: `Portal Gun` -- `extra`: `Mr. Poopybutthole` +* `username`: `Rick` +* `password`: `Portal Gun` +* `extra`: `Mr. Poopybutthole` フィールド `extra` は許可されていない旨のエラーレスポンスが返されます: diff --git a/docs/ja/docs/tutorial/request-forms-and-files.md b/docs/ja/docs/tutorial/request-forms-and-files.md index 4865f29..abb7901 100644 --- a/docs/ja/docs/tutorial/request-forms-and-files.md +++ b/docs/ja/docs/tutorial/request-forms-and-files.md @@ -4,12 +4,12 @@ /// note | 備考 -アップロードされたファイルやフォームデータを受信するには、まず[`python-multipart`](https://github.com/Kludex/python-multipart)をインストールします。 +アップロードされたファイルおよび/またはフォームデータを受信するには、まず[`python-multipart`](https://github.com/Kludex/python-multipart)をインストールします。 -[仮想環境](../virtual-environments.md)を作成し、それを有効化してから、例えば次のようにインストールしてください: +プロジェクトに追加します: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/ja/docs/tutorial/request-forms.md b/docs/ja/docs/tutorial/request-forms.md index 0478a54..64d98fb 100644 --- a/docs/ja/docs/tutorial/request-forms.md +++ b/docs/ja/docs/tutorial/request-forms.md @@ -6,10 +6,10 @@ JSONの代わりにフィールドを受け取る場合は、`Form`を使用し フォームを使うためには、まず[`python-multipart`](https://github.com/Kludex/python-multipart)をインストールします。 -必ず[仮想環境](../virtual-environments.md)を作成して有効化してから、例えば次のようにインストールしてください: +プロジェクトに追加します: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/ja/docs/tutorial/response-model.md b/docs/ja/docs/tutorial/response-model.md index 4b38e6d..2626ab1 100644 --- a/docs/ja/docs/tutorial/response-model.md +++ b/docs/ja/docs/tutorial/response-model.md @@ -76,16 +76,16 @@ FastAPIはこの `response_model` を使って、データのドキュメント `EmailStr` を使用するには、最初に [`email-validator`](https://github.com/JoshData/python-email-validator) をインストールしてください。 -[仮想環境](../virtual-environments.md)を作成して有効化してから、例えば次のようにインストールしてください: +プロジェクトに追加してください: ```console -$ pip install email-validator +$ uv add email-validator ``` または次のようにします: ```console -$ pip install "pydantic[email]" +$ uv add "pydantic[email]" ``` /// @@ -258,7 +258,7 @@ Pydanticフィールドとして有効ではないものを返し、ツール（ * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -`exclude_defaults` と `exclude_none` については、[Pydanticのドキュメント](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict)で説明されている通りです。 +`exclude_defaults` と `exclude_none` については、[Pydanticのドキュメント](https://pydantic.dev/docs/validation/latest/concepts/serialization/#excluding-and-including-fields-based-on-their-value)で説明されている通りです。 /// diff --git a/docs/ja/docs/tutorial/schema-extra-example.md b/docs/ja/docs/tutorial/schema-extra-example.md index e44e247..1dfbb92 100644 --- a/docs/ja/docs/tutorial/schema-extra-example.md +++ b/docs/ja/docs/tutorial/schema-extra-example.md @@ -13,7 +13,7 @@ その追加情報は、そのモデルの出力**JSON Schema**にそのまま追加され、APIドキュメントで使用されます。 -[Pydanticのドキュメント: Configuration](https://docs.pydantic.dev/latest/api/config/)で説明されているように、`dict`を受け取る属性`model_config`を使用できます。 +[Pydanticのドキュメント: Configuration](https://pydantic.dev/docs/validation/latest/api/pydantic/config/)で説明されているように、`dict`を受け取る属性`model_config`を使用できます。 生成されるJSON Schemaに表示したい追加データ（`examples`を含む）を含む`dict`を使って、`"json_schema_extra"`を設定できます。 diff --git a/docs/ja/docs/tutorial/security/first-steps.md b/docs/ja/docs/tutorial/security/first-steps.md index e5d7c58..efe36b0 100644 --- a/docs/ja/docs/tutorial/security/first-steps.md +++ b/docs/ja/docs/tutorial/security/first-steps.md @@ -26,14 +26,14 @@ /// note | 備考 -[`python-multipart`](https://github.com/Kludex/python-multipart) パッケージは、`pip install "fastapi[standard]"` コマンドを実行すると **FastAPI** と一緒に自動的にインストールされます。 +[`python-multipart`](https://github.com/Kludex/python-multipart) パッケージは、`uv add "fastapi[standard]"` コマンドを実行すると **FastAPI** と一緒に自動的にインストールされます。 -しかし、`pip install fastapi` コマンドを使用する場合、`python-multipart` パッケージはデフォルトでは含まれません。 +しかし、`uv add fastapi` コマンドを使用する場合、`python-multipart` パッケージはデフォルトでは含まれません。 -手動でインストールするには、[仮想環境](../../virtual-environments.md)を作成して有効化し、次のコマンドでインストールしてください: +手動でインストールするには、次のコマンドでプロジェクトに追加してください: ```console -$ pip install python-multipart +$ uv add python-multipart ``` これは、**OAuth2**が `username` と `password` を送信するために、「フォームデータ」を使うからです。 @@ -45,7 +45,7 @@ $ pip install python-multipart
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/ja/docs/tutorial/security/oauth2-jwt.md b/docs/ja/docs/tutorial/security/oauth2-jwt.md index 40cefad..a8147b3 100644 --- a/docs/ja/docs/tutorial/security/oauth2-jwt.md +++ b/docs/ja/docs/tutorial/security/oauth2-jwt.md @@ -30,12 +30,12 @@ JWT トークンを使って遊んでみたいという方は、[https://jwt.io] PythonでJWTトークンの生成と検証を行うために、`PyJWT`をインストールする必要があります。 -[仮想環境](../../virtual-environments.md)を作成し、アクティベートしてから、`pyjwt`をインストールしてください。 +プロジェクトに`pyjwt`を追加してください：
```console -$ pip install pyjwt +$ uv add pyjwt ---> 100% ``` @@ -72,12 +72,12 @@ pwdlib は、パスワードのハッシュを処理するための優れたPyth 推奨されるアルゴリズムは「Argon2」です。 -[仮想環境](../../virtual-environments.md)を作成し、アクティベートしてから、Argon2付きでpwdlibをインストールしてください。 +プロジェクトにArgon2付きで`pwdlib`を追加してください：
```console -$ pip install "pwdlib[argon2]" +$ uv add "pwdlib[argon2]" ---> 100% ``` diff --git a/docs/ja/docs/tutorial/sql-databases.md b/docs/ja/docs/tutorial/sql-databases.md index 190eedb..b2a292e 100644 --- a/docs/ja/docs/tutorial/sql-databases.md +++ b/docs/ja/docs/tutorial/sql-databases.md @@ -1,11 +1,10 @@ # SQL（リレーショナル）データベース { #sql-relational-databases } - -FastAPI は SQL（リレーショナル）データベースの使用を必須にはしません。必要であれば、任意のデータベースを使用できます。 +**FastAPI** は SQL（リレーショナル）データベースの使用を必須にはしません。必要であれば、**任意のデータベース**を使用できます。 ここでは [SQLModel](https://sqlmodel.tiangolo.com/) を使った例を見ていきます。 -SQLModel は [SQLAlchemy](https://www.sqlalchemy.org/) と Pydantic の上に構築されています。FastAPI と同じ作者により、SQL データベースを使う必要がある FastAPI アプリに最適になるように作られています。 +**SQLModel** は [SQLAlchemy](https://www.sqlalchemy.org/) と Pydantic の上に構築されています。**FastAPI** と同じ作者により、**SQL データベース**を使う必要がある FastAPI アプリに最適になるように作られています。 /// tip | 豆知識 @@ -13,7 +12,7 @@ SQLModel は [SQLAlchemy](https://www.sqlalchemy.org/) と Pydantic の上に構 /// -SQLModel は SQLAlchemy をベースにしているため、SQLAlchemy がサポートする任意のデータベース（SQLModel からもサポートされます）を簡単に使えます。例えば: +SQLModel は SQLAlchemy をベースにしているため、SQLAlchemy が**サポートする任意のデータベース**（SQLModel からもサポートされます）を簡単に使えます。例えば: * PostgreSQL * MySQL @@ -21,26 +20,26 @@ SQLModel は SQLAlchemy をベースにしているため、SQLAlchemy がサポ * Oracle * Microsoft SQL Server など -この例では、単一ファイルで動作し、Python に統合サポートがあるため、SQLite を使います。つまり、この例をそのままコピーして実行できます。 +この例では、単一ファイルで動作し、Python に統合サポートがあるため、**SQLite** を使います。つまり、この例をそのままコピーして実行できます。 -本番アプリでは、PostgreSQL のようなデータベースサーバーを使いたくなるかもしれません。 +本番アプリでは、**PostgreSQL** のようなデータベースサーバーを使いたくなるかもしれません。 /// tip | 豆知識 -フロントエンドやその他のツールを含む、FastAPI と PostgreSQL の公式プロジェクトジェネレーターがあります: [https://github.com/fastapi/full-stack-fastapi-template](https://github.com/fastapi/full-stack-fastapi-template) +フロントエンドやその他のツールを含む、**FastAPI** と **PostgreSQL** の公式プロジェクトジェネレーターがあります: [https://github.com/fastapi/full-stack-fastapi-template](https://github.com/fastapi/full-stack-fastapi-template) /// -これはとてもシンプルで短いチュートリアルです。データベースや SQL、より高度な機能について学びたい場合は、[SQLModel のドキュメント](https://sqlmodel.tiangolo.com/)をご覧ください。 +これはとてもシンプルで短いチュートリアルです。データベース一般や SQL、より高度な機能について学びたい場合は、[SQLModel のドキュメント](https://sqlmodel.tiangolo.com/)をご覧ください。 ## `SQLModel` のインストール { #install-sqlmodel } -まずは [仮想環境](../virtual-environments.md) を作成・有効化し、`sqlmodel` をインストールします: +`sqlmodel` をプロジェクトに追加します:
```console -$ pip install sqlmodel +$ uv add sqlmodel ---> 100% ``` @@ -48,9 +47,9 @@ $ pip install sqlmodel ## 単一モデルでアプリ作成 { #create-the-app-with-a-single-model } -まずは最も簡単な、単一の SQLModel モデルだけを使うバージョンを作ります。 +まずは最も簡単な、単一の **SQLModel** モデルだけを使うバージョンを作ります。 -後で、下記のとおり複数モデルにしてセキュリティと汎用性を高めます。🤓 +後で、下記のとおり**複数モデル**にしてセキュリティと汎用性を高めます。🤓 ### モデルの作成 { #create-models } @@ -58,43 +57,43 @@ $ pip install sqlmodel {* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[1:11] hl[7:11] *} -`Hero` クラスは Pydantic モデルによく似ています（実際には内部的に Pydantic モデルでもあります）。 +`Hero` クラスは Pydantic モデルによく似ています（実際には内部的に*Pydantic モデルでもあります*）。 いくつかの違いがあります: -* `table=True` は SQLModel に対して「これはテーブルモデルであり、SQL データベースのテーブルを表す。単なるデータモデル（通常の Pydantic クラス）ではない」と伝えます。 +* `table=True` は SQLModel に対して「これは*テーブルモデル*であり、SQL データベースの**テーブル**を表す。単なる*データモデル*（通常の Pydantic クラス）ではない」と伝えます。 -* `Field(primary_key=True)` は `id` が SQL データベースのプライマリキーであることを SQLModel に伝えます（SQL のプライマリキーについては SQLModel ドキュメントを参照してください）。 +* `Field(primary_key=True)` は `id` が SQL データベースの**プライマリキー**であることを SQLModel に伝えます（SQL のプライマリキーについては SQLModel ドキュメントを参照してください）。 - 注: プライマリキーのフィールドには `int | None` を使っています。これは Python コード内で `id=None` のように「`id` なしでオブジェクトを作成」し、保存時にデータベースが生成することを想定するためです。SQLModel はデータベースが `id` を提供することを理解し、スキーマでは「NULL 不可の `INTEGER` 列」を定義します。詳細は [SQLModel のプライマリキーに関するドキュメント](https://sqlmodel.tiangolo.com/tutorial/create-db-and-table/#primary-key-id) を参照してください。 + **注:** プライマリキーのフィールドには `int | None` を使っています。これは Python コード内で `id=None` のように「`id` なしでオブジェクトを作成」し、保存時にデータベースが生成することを想定するためです。SQLModel はデータベースが `id` を提供することを理解し、スキーマでは「NULL 不可の `INTEGER` 列」を定義します。詳細は [SQLModel のプライマリキーに関するドキュメント](https://sqlmodel.tiangolo.com/tutorial/create-db-and-table/#primary-key-id) を参照してください。 -* `Field(index=True)` は、この列に対して SQL のインデックスを作成するよう SQLModel に指示します。これにより、この列でフィルタしてデータを読む場合に検索が高速になります。 +* `Field(index=True)` は、この列に対して **SQL インデックス**を作成するよう SQLModel に指示します。これにより、この列でフィルタしてデータを読む場合に検索が高速になります。 `str` と宣言されたものは、SQL の `TEXT`（データベースによっては `VARCHAR`）型の列になることを SQLModel は理解します。 ### Engine の作成 { #create-an-engine } -SQLModel の `engine`（内部的には SQLAlchemy の `engine`）は、データベースへの接続を保持します。 +SQLModel の `engine`（内部的には SQLAlchemy の `engine`）は、データベースへの**接続を保持**します。 -同じデータベースに接続するために、コード全体で 1 つの `engine` オブジェクトを共有します。 +同じデータベースに接続するために、コード全体で**単一の `engine` オブジェクト**を共有します。 {* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[14:18] hl[14:15,17:18] *} -`check_same_thread=False` を使うと、FastAPI が異なるスレッドで同じ SQLite データベースを使えるようになります。これは、依存関係などにより 1 つのリクエストが複数スレッドを使う可能性があるため、必要です。 +`check_same_thread=False` を使うと、FastAPI が異なるスレッドで同じ SQLite データベースを使えるようになります。これは、**1 つのリクエスト**が**複数スレッド**を使う可能性があるため（例えば依存関係で）、必要です。 -心配はいりません。このコードの構成では、後で「1 リクエストにつき 1 つの SQLModel セッション」を確実に使うようにします。実際、`check_same_thread` はそれを実現しようとしています。 +心配はいりません。このコードの構成では、後で**1 リクエストにつき 1 つの SQLModel *session***を確実に使うようにします。実際、`check_same_thread` はそれを実現しようとしています。 ### テーブルの作成 { #create-the-tables } -`SQLModel.metadata.create_all(engine)` を使って、すべてのテーブルモデルのテーブルを作成する関数を追加します。 +`SQLModel.metadata.create_all(engine)` を使って、すべての*テーブルモデル*の**テーブルを作成**する関数を追加します。 {* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[21:22] hl[21:22] *} ### Session 依存関係の作成 { #create-a-session-dependency } -`Session` は、メモリ上でオブジェクトを保持して変更を追跡し、`engine` を使ってデータベースと通信します。 +**`Session`** は、**メモリ上でオブジェクトを保持**してデータに必要な変更を追跡し、`engine` を使ってデータベースと通信します。 -各リクエストごとに新しい `Session` を提供する、`yield` を使った FastAPI の依存関係を作成します。これにより、1 リクエストにつき 1 つのセッションを使うことが保証されます。🤓 +各リクエストごとに新しい `Session` を提供する、`yield` を使った FastAPI の**依存関係**を作成します。これにより、1 リクエストにつき 1 つのセッションを使うことが保証されます。🤓 続いて、この依存関係を使うコードを簡潔にするために、`Annotated` による依存関係 `SessionDep` を作成します。 @@ -118,11 +117,11 @@ SQLModel は Alembic をラップしたマイグレーションユーティリ ### Hero の作成 { #create-a-hero } -各 SQLModel モデルは Pydantic モデルでもあるため、Pydantic モデルと同じように型アノテーションで使えます。 +各 SQLModel モデルは Pydantic モデルでもあるため、Pydantic モデルと同じ**型アノテーション**で使えます。 -例えば、`Hero` 型のパラメータを宣言すると、JSON ボディから読み込まれます。 +例えば、`Hero` 型のパラメータを宣言すると、**JSON ボディ**から読み込まれます。 -同様に、関数の戻り値の型として宣言すると、そのデータ形状が自動 API ドキュメントの UI に表示されます。 +同様に、関数の**戻り値の型**として宣言すると、そのデータ形状が自動 API ドキュメントの UI に表示されます。 {* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[40:45] hl[40:45] *} @@ -130,37 +129,37 @@ SQLModel は Alembic をラップしたマイグレーションユーティリ ### Hero の取得 { #read-heroes } -`select()` を使ってデータベースから `Hero` を取得できます。結果のページネーションのために `limit` と `offset` を含められます。 +`select()` を使ってデータベースから `Hero` を**取得**できます。結果のページネーションのために `limit` と `offset` を含められます。 {* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[48:55] hl[51:52,54] *} ### 単一の Hero を取得 { #read-one-hero } -単一の `Hero` を取得できます。 +単一の `Hero` を**取得**できます。 {* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[58:63] hl[60] *} ### Hero の削除 { #delete-a-hero } -`Hero` を削除することもできます。 +`Hero` を**削除**することもできます。 {* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[66:73] hl[71] *} ### アプリの起動 { #run-the-app } -アプリを起動します: +アプリを起動できます:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
-その後 `/docs` の UI にアクセスすると、FastAPI がこれらのモデルを使って API をドキュメント化し、同時にデータのシリアライズとバリデーションにも使っていることがわかります。 +その後 `/docs` の UI にアクセスすると、**FastAPI** がこれらの**モデル**を使って API を**ドキュメント化**し、同時にデータの**シリアライズ**と**バリデーション**にも使っていることがわかります。
@@ -168,41 +167,41 @@ $ fastapi dev ## 複数モデルでアプリを更新 { #update-the-app-with-multiple-models } -ここで、少しリファクタリングしてセキュリティと汎用性を高めましょう。 +ここで、少し**リファクタリング**して**セキュリティ**と**汎用性**を高めましょう。 -前のアプリでは、UI 上でクライアントが作成する `Hero` の `id` を自分で決められてしまいます。😱 +前のアプリを確認すると、UI 上で、現時点ではクライアントが作成する `Hero` の `id` を自分で決められてしまうことがわかります。😱 -それは許可すべきではありません。すでに DB で割り当て済みの `id` を上書きされる可能性があります。`id` の決定はクライアントではなく、バックエンドまたはデータベースが行うべきです。 +それは許可すべきではありません。すでに DB で割り当て済みの `id` を上書きされる可能性があります。`id` の決定は**クライアントではなく**、**バックエンド**または**データベース**が行うべきです。 -さらに、`secret_name` を作っていますが、現状ではそれをどこでも返してしまっています。これではあまり「シークレット」ではありません... 😅 +さらに、ヒーローの `secret_name` を作っていますが、現状ではそれをどこでも返してしまっています。これではあまり**シークレット**ではありません... 😅 -これらを、いくつかの追加モデルで修正します。ここで SQLModel の真価が発揮されます。✨ +これらを、いくつかの**追加モデル**で修正します。ここで SQLModel の真価が発揮されます。✨ ### 複数モデルの作成 { #create-multiple-models } -SQLModel では、`table=True` のあるモデルクラスがテーブルモデルです。 +**SQLModel** では、`table=True` のあるモデルクラスが**テーブルモデル**です。 -`table=True` のないモデルクラスはデータモデルで、実体は（小さな機能がいくつか追加された）Pydantic モデルです。🤓 +`table=True` のないモデルクラスは**データモデル**で、実体は（小さな機能がいくつか追加された）Pydantic モデルです。🤓 -SQLModel では継承を使って、あらゆるケースでフィールドの重複を避けられます。 +SQLModel では**継承**を使って、あらゆるケースでフィールドの**重複を避けられます**。 #### `HeroBase` - ベースクラス { #herobase-the-base-class } -まず、すべてのモデルで共有されるフィールドを持つ `HeroBase` モデルを作ります: +まず、すべてのモデルで**共有されるフィールド**を持つ `HeroBase` モデルを作ります: * `name` * `age` {* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:9] hl[7:9] *} -#### `Hero` - テーブルモデル { #hero-the-table-model } +#### `Hero` - *テーブルモデル* { #hero-the-table-model } -次に、実際のテーブルモデルである `Hero` を作ります。他のモデルには常に含まれない追加フィールドを持ちます: +次に、実際の*テーブルモデル*である `Hero` を作ります。他のモデルには常に含まれない**追加フィールド**を持ちます: * `id` * `secret_name` -`Hero` は `HeroBase` を継承しているため、`HeroBase` で宣言されたフィールドも持ちます。つまり、`Hero` の全フィールドは次のとおりです: +`Hero` は `HeroBase` を継承しているため、`HeroBase` で宣言された**フィールド**も持ちます。つまり、`Hero` の全フィールドは次のとおりです: * `id` * `name` @@ -211,21 +210,21 @@ SQLModel では継承を使って、あらゆるケースでフィールドの {* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:14] hl[12:14] *} -#### `HeroPublic` - 公開用データモデル { #heropublic-the-public-data-model } +#### `HeroPublic` - 公開用*データモデル* { #heropublic-the-public-data-model } -次に、API のクライアントに返す `HeroPublic` モデルを作ります。 +次に、API のクライアントに**返す** `HeroPublic` モデルを作ります。 これは `HeroBase` と同じフィールドを持つため、`secret_name` は含みません。 これでヒーローの正体は守られます！🥷 -また、`id: int` を再宣言します。これにより、API クライアントとの間で「常に `id` が存在し、`int` である（`None` にはならない）」という契約を結びます。 +また、`id: int` を再宣言します。これにより、API クライアントとの間で「常に `id` が存在し、`int` である（`None` にはならない）」という**契約**を結びます。 /// tip | 豆知識 戻り値のモデルで、値が常に存在し常に `int`（`None` ではない）であることを保証すると、API クライアント側のコードははるかにシンプルに書けます。 -加えて、自動生成クライアントのインターフェースも簡潔になり、あなたの API とやり取りする開発者体験が向上します。😎 +加えて、**自動生成クライアント**のインターフェースも簡潔になり、あなたの API とやり取りする開発者体験が向上します。😎 /// @@ -237,19 +236,19 @@ SQLModel では継承を使って、あらゆるケースでフィールドの {* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:18] hl[17:18] *} -#### `HeroCreate` - 作成用データモデル { #herocreate-the-data-model-to-create-a-hero } +#### `HeroCreate` - 作成用*データモデル* { #herocreate-the-data-model-to-create-a-hero } -次に、クライアントからのデータをバリデートする `HeroCreate` モデルを作ります。 +次に、クライアントからのデータを**バリデート**する `HeroCreate` モデルを作ります。 これは `HeroBase` と同じフィールドに加え、`secret_name` も持ちます。 -これで、クライアントが新しいヒーローを作成する際に `secret_name` を送信し、データベースに保存されますが、そのシークレット名は API ではクライアントに返されません。 +これで、クライアントが**新しいヒーローを作成**する際に `secret_name` を送信し、データベースに保存されますが、そのシークレット名は API ではクライアントに返されません。 /// tip | 豆知識 -これはパスワードを扱う際の方法と同じです。受け取りますが、API では返しません。 +これは**パスワード**を扱う際の方法と同じです。受け取りますが、API では返しません。 -また、保存前にパスワードの値はハッシュ化し、平文のまま保存しないでください。 +また、保存前にパスワードの値は**ハッシュ化**し、**平文のまま保存しないでください**。 /// @@ -261,13 +260,13 @@ SQLModel では継承を使って、あらゆるケースでフィールドの {* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:22] hl[21:22] *} -#### `HeroUpdate` - 更新用データモデル { #heroupdate-the-data-model-to-update-a-hero } +#### `HeroUpdate` - 更新用*データモデル* { #heroupdate-the-data-model-to-update-a-hero } -前のバージョンのアプリにはヒーローを更新する方法がありませんでしたが、複数モデルを使えば可能です。🎉 +前のバージョンのアプリには**ヒーローを更新する**方法がありませんでしたが、**複数モデル**を使えば可能です。🎉 -`HeroUpdate` データモデルは少し特殊で、新しいヒーローを作成するのに必要なフィールドと同じフィールドをすべて持ちますが、すべてのフィールドがオプショナル（デフォルト値を持つ）です。これにより、更新時には変更したいフィールドだけを送れます。 +`HeroUpdate` *データモデル*は少し特殊で、新しいヒーローを作成するのに必要なフィールドと**同じフィールドをすべて**持ちますが、すべてのフィールドが**オプショナル**（デフォルト値を持つ）です。これにより、更新時には変更したいフィールドだけを送れます。 -すべてのフィールドの型が実質的に変わる（`None` を含み、デフォルト値が `None` になる）ため、フィールドは再宣言する必要があります。 +すべての**フィールドが実質的に変わる**（`None` を含み、デフォルト値が `None` になる）ため、フィールドは**再宣言**する必要があります。 すべてのフィールドを再宣言するので、厳密には `HeroBase` を継承する必要はありません。一貫性のためにここでは継承していますが、必須ではありません。好みの問題です。🤷 @@ -283,41 +282,41 @@ SQLModel では継承を使って、あらゆるケースでフィールドの 複数モデルが用意できたので、それらを使うようにアプリの部分を更新します。 -リクエストでは `HeroCreate` データモデルを受け取り、そこから `Hero` テーブルモデルを作成します。 +リクエストでは `HeroCreate` *データモデル*を受け取り、そこから `Hero` *テーブルモデル*を作成します。 -この新しいテーブルモデル `Hero` は、クライアントから送られたフィールドを持ち、データベースによって生成された `id` も持ちます。 +この新しい*テーブルモデル* `Hero` は、クライアントから送られたフィールドを持ち、データベースによって生成された `id` も持ちます。 -関数からはこのテーブルモデル `Hero` をそのまま返します。しかし `response_model` に `HeroPublic` データモデルを指定しているため、FastAPI が `HeroPublic` を使ってデータをバリデート・シリアライズします。 +関数からはこの*テーブルモデル* `Hero` をそのまま返します。しかし `response_model` に `HeroPublic` *データモデル*を指定しているため、**FastAPI** が `HeroPublic` を使ってデータをバリデート・シリアライズします。 {* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[56:62] hl[56:58] *} /// tip | 豆知識 -今回は返却値の型アノテーション `-> HeroPublic` の代わりに `response_model=HeroPublic` を使います。返している値は実際には `HeroPublic` ではないためです。 +今回は**返却値の型アノテーション** `-> HeroPublic` の代わりに `response_model=HeroPublic` を使います。返している値は実際には `HeroPublic` ではないためです。 もし `-> HeroPublic` と宣言すると、エディタや Linter は（正しく）「`HeroPublic` ではなく `Hero` を返している」と警告します。 -`response_model` に指定することで、型アノテーションやエディタ等の補助を崩さずに、FastAPI にシリアライズの仕事を任せられます。 +`response_model` に指定することで、型アノテーションやエディタ等の補助を崩さずに、**FastAPI** にシリアライズの仕事を任せられます。 /// ### `HeroPublic` で Hero を取得 { #read-heroes-with-heropublic } -前と同様に `Hero` を取得できます。再び `response_model=list[HeroPublic]` を使って、データが正しくバリデート・シリアライズされることを保証します。 +前と同様に `Hero` を**取得**できます。再び `response_model=list[HeroPublic]` を使って、データが正しくバリデート・シリアライズされることを保証します。 {* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[65:72] hl[65] *} ### `HeroPublic` で単一の Hero を取得 { #read-one-hero-with-heropublic } -単一のヒーローを取得します: +単一のヒーローを**取得**します: {* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[75:80] hl[77] *} ### `HeroUpdate` で Hero を更新 { #update-a-hero-with-heroupdate } -ヒーローを更新できます。ここでは HTTP の `PATCH` を使います。 +ヒーローを**更新**できます。ここでは HTTP の `PATCH` operation を使います。 -コードでは、クライアントが送ったデータのみ（デフォルト値として入ってくる値は除外）を持つ `dict` を取得します。これには `exclude_unset=True` を使います。これが主なコツです。🪄 +コードでは、クライアントが送ったすべてのデータ、つまり**クライアントが送ったデータのみ**（デフォルト値として入ってくる値は除外）を持つ `dict` を取得します。これには `exclude_unset=True` を使います。これが主なコツです。🪄 その後、`hero_db.sqlmodel_update(hero_data)` を使って、`hero_db` を `hero_data` の内容で更新します。 @@ -325,7 +324,7 @@ SQLModel では継承を使って、あらゆるケースでフィールドの ### 再度 Hero を削除 { #delete-a-hero-again } -ヒーローの削除はほとんど変わりません。 +ヒーローの**削除**はほとんど変わりません。 ここはリファクタリング欲求を満たさないままにしておきます。😅 @@ -333,12 +332,12 @@ SQLModel では継承を使って、あらゆるケースでフィールドの ### アプリの再起動 { #run-the-app-again } -アプリを再度起動します: +アプリを再度起動できます:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -353,6 +352,6 @@ $ fastapi dev ## まとめ { #recap } -[SQLModel](https://sqlmodel.tiangolo.com/) を使って SQL データベースとやり取りし、データモデルとテーブルモデルでコードを簡潔にできます。 +[**SQLModel**](https://sqlmodel.tiangolo.com/) を使って SQL データベースとやり取りし、*データモデル*と*テーブルモデル*でコードを簡潔にできます。 -さらに多くを学ぶには SQLModel のドキュメントをご覧ください。[FastAPI と SQLModel を使うチュートリアル](https://sqlmodel.tiangolo.com/tutorial/fastapi/) もあります。🚀 +さらに多くを学ぶには **SQLModel** のドキュメントをご覧ください。[**FastAPI** と SQLModel を使うチュートリアル](https://sqlmodel.tiangolo.com/tutorial/fastapi/) もあります。🚀 diff --git a/docs/ja/docs/tutorial/static-files.md b/docs/ja/docs/tutorial/static-files.md index fd0d47e..8f21935 100644 --- a/docs/ja/docs/tutorial/static-files.md +++ b/docs/ja/docs/tutorial/static-files.md @@ -45,4 +45,4 @@ ## より詳しい情報 { #more-info } -詳細とオプションについては、[Starletteの静的ファイルに関するドキュメント](https://www.starlette.dev/staticfiles/)を確認してください。 +詳細とオプションについては、[Starletteの静的ファイルに関するドキュメント](https://starlette.dev/staticfiles/)を確認してください。 diff --git a/docs/ja/docs/tutorial/testing.md b/docs/ja/docs/tutorial/testing.md index e82fc26..c44a101 100644 --- a/docs/ja/docs/tutorial/testing.md +++ b/docs/ja/docs/tutorial/testing.md @@ -1,6 +1,6 @@ # テスト { #testing } -[Starlette](https://www.starlette.dev/testclient/) のおかげで、**FastAPI** アプリケーションのテストは簡単で楽しいものになっています。 +[Starlette](https://starlette.dev/testclient/) のおかげで、**FastAPI** アプリケーションのテストは簡単で楽しいものになっています。 [HTTPX](https://www.python-httpx.org) がベースで、さらにその設計は Requests をベースにしているため、とても馴染みがあり直感的です。 @@ -12,10 +12,10 @@ `TestClient` を使用するには、まず [`httpx`](https://www.python-httpx.org) をインストールします。 -[仮想環境](../virtual-environments.md) を作成し、それを有効化してから、例えば以下のようにインストールしてください: +プロジェクトに追加します: ```console -$ pip install httpx +$ uv add httpx ``` /// @@ -156,12 +156,12 @@ FastAPIアプリケーションへのリクエストの送信とは別に、テ その後、`pytest` をインストールするだけです。 -[仮想環境](../virtual-environments.md) を作成し、それを有効化してから、例えば以下のようにインストールしてください: +プロジェクトに追加します:
```console -$ pip install pytest +$ uv add pytest ---> 100% ``` @@ -175,7 +175,7 @@ $ pip install pytest
```console -$ pytest +$ uv run pytest ================ test session starts ================ platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1 diff --git a/docs/ja/docs/virtual-environments.md b/docs/ja/docs/virtual-environments.md index 19325fa..2a660aa 100644 --- a/docs/ja/docs/virtual-environments.md +++ b/docs/ja/docs/virtual-environments.md @@ -1,854 +1,35 @@ # 仮想環境 { #virtual-environments } -Pythonプロジェクトの作業では、**仮想環境**（または類似の仕組み）を使用し、プロジェクトごとにインストールするパッケージを分離するべきでしょう。 +Pythonプロジェクトで作業する際は、プロジェクトごとにインストールされるパッケージを分離するために**仮想環境**を使用するべきです。 -/// note | 備考 - -もし、仮想環境の概要や作成方法、使用方法について既にご存知なら、このセクションをスキップした方がよいかもしれません。🤓 - -/// - -/// tip | 豆知識 - -**仮想環境**は、**環境変数**とは異なります。 - -**環境変数**は、プログラムが使用できるシステム内の変数です。 - -**仮想環境**は、ファイルをまとめたディレクトリのことです。 - -/// - -/// note | 備考 - -このページでは、**仮想環境**の使用方法と、そのはたらきについて説明します。 - -もし**すべてを管理するツール**（Pythonのインストールも含む）を導入する準備ができているなら、[uv](https://github.com/astral-sh/uv) をお試しください。 - -/// +FastAPIプロジェクトでは、プロジェクト、その依存関係、仮想環境を管理するために [uv](https://docs.astral.sh/uv/) を使用することをおすすめします。 ## プロジェクトの作成 { #create-a-project } -まず、プロジェクト用のディレクトリを作成します。 - -私は通常 home/user ディレクトリの中に `code` というディレクトリを用意していて、プロジェクトごとに1つのディレクトリをその中に作成しています。 +[公式インストールガイド](https://docs.astral.sh/uv/getting-started/installation/)に従って `uv` をインストールし、プロジェクトを作成します:
```console -// ホームディレクトリに移動 -$ cd -// すべてのコードプロジェクト用のディレクトリを作成 -$ mkdir code -// その code ディレクトリに入る -$ cd code -// このプロジェクト用のディレクトリを作成 -$ mkdir awesome-project -// そのプロジェクトディレクトリに入る +$ uv init awesome-project --bare $ cd awesome-project +$ uv add "fastapi[standard]" ```
-## 仮想環境の作成 { #create-a-virtual-environment } +`uv` はプロジェクトの仮想環境を自動的に作成します。自分で作成したり有効化したりする必要はありません。 -Pythonプロジェクトでの**初めての**作業を開始する際には、**プロジェクト内**に仮想環境を作成してください。 - -/// tip | 豆知識 - -これを行うのは、**プロジェクトごとに1回だけ**です。作業のたびに行う必要はありません。 - -/// - -//// tab | `venv` - -仮想環境を作成するには、Pythonに付属している `venv` モジュールを使用できます。 +プロジェクト環境内でコマンドを実行するには、例えば次のように `uv run` を使用します:
```console -$ python -m venv .venv +$ uv run fastapi dev ```
-/// details | このコマンドの意味 +## さらに学ぶ { #learn-more } -* `python`: `python` というプログラムを呼び出します -* `-m`: モジュールをスクリプトとして呼び出します。どのモジュールを呼び出すのか、この次に指定します -* `venv`: 通常Pythonに付随してインストールされる `venv`モジュールを使用します -* `.venv`: 仮想環境を`.venv`という新しいディレクトリに作成します - -/// - -//// - -//// tab | `uv` - -もし [`uv`](https://github.com/astral-sh/uv) をインストール済みなら、仮想環境を作成するために `uv` を使うこともできます。 - -
- -```console -$ uv venv -``` - -
- -/// tip | 豆知識 - -デフォルトでは、 `uv` は `.venv` というディレクトリに仮想環境を作成します。 - -ただし、追加の引数にディレクトリ名を与えてカスタマイズすることもできます。 - -/// - -//// - -このコマンドは `.venv` というディレクトリに新しい仮想環境を作成します。 - -/// details | `.venv` またはその他の名前 - -仮想環境を別のディレクトリに作成することも可能ですが、 `.venv` と名付けるのが一般的な慣習です。 - -/// - -## 仮想環境の有効化 { #activate-the-virtual-environment } - -実行されるPythonコマンドやインストールされるパッケージが新しく作成した仮想環境を使用するよう、その仮想環境を有効化しましょう。 - -/// tip | 豆知識 - -そのプロジェクトの作業で**新しいターミナルセッション**を開始する際には、**毎回**有効化してください。 - -/// - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -もしWindowsでBashを使用している場合 ([Git Bash](https://gitforwindows.org/)など): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -/// tip | 豆知識 - -**新しいパッケージ**を仮想環境にインストールするたびに、環境をもう一度**有効化**してください。 - -こうすることで、そのパッケージがインストールした**ターミナル（CLI）プログラム**を使用する場合に、仮想環境内のものが確実に使われ、グローバル環境にインストールされている別のもの（おそらく必要なものとは異なるバージョン）を誤って使用することを防ぎます。 - -/// - -## 仮想環境が有効であることを確認する { #check-the-virtual-environment-is-active } - -仮想環境が有効である（前のコマンドが正常に機能した）ことを確認します。 - -/// tip | 豆知識 - -これは**任意**ですが、すべてが期待通りに機能し、意図した仮想環境を使用していることを**確認する**良い方法です。 - -/// - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -`.venv/bin/python` にある `python` バイナリが、プロジェクト（この場合は `awesome-project` ）内に表示されていれば、正常に動作しています 🎉。 - -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -`.venv\Scripts\python` にある `python` バイナリが、プロジェクト（この場合は `awesome-project` ）内に表示されていれば、正常に動作しています 🎉。 - -//// - -## `pip` をアップグレードする { #upgrade-pip } - -/// tip | 豆知識 - -もし [`uv`](https://github.com/astral-sh/uv) を使用している場合は、 `pip` の代わりに `uv` を使ってインストールを行うため、 `pip` をアップグレードする必要はありません 😎。 - -/// - -もしパッケージのインストールに `pip`（Pythonに標準で付属しています）を使用しているなら、 `pip` を最新バージョンに**アップグレード**しましょう。 - -パッケージのインストール中に発生する想定外のエラーの多くは、最初に `pip` をアップグレードしておくだけで解決されます。 - -/// tip | 豆知識 - -通常、これは仮想環境を作成した直後に**一度だけ**実行します。 - -/// - -仮想環境が有効であることを（上で説明したコマンドで）確認し、アップグレードを実行しましょう： - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip | 豆知識 - -ときどき、pip をアップグレードしようとすると **`No module named pip`** エラーが表示されることがあります。 - -その場合は、以下のコマンドで pip をインストールしてアップグレードしてください: - -
- -```console -$ python -m ensurepip --upgrade - ----> 100% -``` - -
- -このコマンドは、pip がまだインストールされていなければ pip をインストールし、また、インストールされる pip のバージョンが `ensurepip` で利用可能なもの以上に新しいことも保証します。 - -/// - -## `.gitignore` を追加する { #add-gitignore } - -**Git**を使用している場合（使用するべきでしょう）、 `.gitignore` ファイルを追加して、 `.venv` 内のあらゆるファイルをGitの管理対象から除外します。 - -/// tip | 豆知識 - -もし [`uv`](https://github.com/astral-sh/uv) を使用して仮想環境を作成した場合、すでにこの作業は済んでいるので、この手順をスキップできます 😎。 - -/// - -/// tip | 豆知識 - -これも、仮想環境を作成した直後に**一度だけ**実行します。 - -/// - -
- -```console -$ echo "*" > .venv/.gitignore -``` - -
- -/// details | このコマンドの意味 - -* `echo "*"`: ターミナルに `*` というテキストを「表示」しようとします。（次の部分によってその動作が少し変わります） -* `>`: `>` の左側のコマンドがターミナルに表示しようとする内容を、ターミナルには表示せず、 `>` の右側のファイルに書き込みます。 -* `.gitignore`: `*` を書き込むファイル名。 - -ここで、Gitにおける `*` は「すべて」を意味するので、このコマンドによって `.venv` ディレクトリ内のすべてがGitに無視されるようになります。 - -このコマンドは以下のテキストを持つ `.gitignore` ファイルを作成します： - -```gitignore -* -``` - -/// - -## パッケージのインストール { #install-packages } - -仮想環境を有効化した後、その中でパッケージをインストールできます。 - -/// tip | 豆知識 - -プロジェクトに必要なパッケージをインストールまたはアップグレードする場合、これを**一度**実行します。 - -もし新しいパッケージを追加したり、バージョンをアップグレードする必要がある場合は、もう**一度この手順を繰り返し**ます。 - -/// - -### パッケージを直接インストールする { #install-packages-directly } - -急いでいて、プロジェクトのパッケージ要件を宣言するファイルを使いたくない場合、パッケージを直接インストールできます。 - -/// tip | 豆知識 - -プログラムが必要とするパッケージとバージョンをファイル（例えば `requirements.txt` や `pyproject.toml` ）に記載しておくのは、（とても）良い考えです。 - -/// - -//// tab | `pip` - -
- -```console -$ pip install "fastapi[standard]" - ----> 100% -``` - -
- -//// - -//// tab | `uv` - -もし [`uv`](https://github.com/astral-sh/uv) を使用できるなら: - -
- -```console -$ uv pip install "fastapi[standard]" ----> 100% -``` - -
- -//// - -### `requirements.txt` からインストールする { #install-from-requirements-txt } - -もし `requirements.txt` があるなら、パッケージのインストールに使用できます。 - -//// tab | `pip` - -
- -```console -$ pip install -r requirements.txt ----> 100% -``` - -
- -//// - -//// tab | `uv` - -もし [`uv`](https://github.com/astral-sh/uv) を使用できるなら: - -
- -```console -$ uv pip install -r requirements.txt ----> 100% -``` - -
- -//// - -/// details | `requirements.txt` - -パッケージが記載された `requirements.txt` は以下のようになっています: - -```requirements.txt -fastapi[standard]==0.113.0 -pydantic==2.8.0 -``` - -/// - -## プログラムを実行する { #run-your-program } - -仮想環境を有効化した後、プログラムを実行できます。この際、仮想環境内のPythonと、そこにインストールしたパッケージが使用されます。 - -
- -```console -$ python main.py - -Hello World -``` - -
- -## エディタの設定 { #configure-your-editor } - -プロジェクトではおそらくエディタを使用するでしょう。コード補完やインラインエラーの表示ができるように、作成した仮想環境をエディタでも使えるよう設定してください。（多くの場合、自動検出されます） - -設定例: - -* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) -* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) - -/// tip | 豆知識 - -この設定は通常、仮想環境を作成した際に**一度だけ**行います。 - -/// - -## 仮想環境の無効化 { #deactivate-the-virtual-environment } - -プロジェクトの作業が終了したら、その仮想環境を**無効化**できます。 - -
- -```console -$ deactivate -``` - -
- -これにより、 `python` コマンドを実行しても、そのプロジェクト用（のパッケージがインストールされた）仮想環境から `python` プログラムを呼び出そうとはしなくなります。 - -## 作業準備完了 { #ready-to-work } - -これで、プロジェクトの作業を始める準備が整いました。 - - - -/// tip | 豆知識 - -上記の内容を理解したいですか？ - -もしそうなら、以下を読み進めてください。👇🤓 - -/// - -## なぜ仮想環境？ { #why-virtual-environments } - -FastAPIを使った作業をするには、[Python](https://www.python.org/) のインストールが必要です。 - -それから、FastAPIや、使用したいその他の**パッケージ**を**インストール**する必要があります。 - -パッケージをインストールするには、通常、Python に付属する `pip` コマンド (または同様の代替コマンド) を使用します。 - -ただし、`pip` を直接使用すると、パッケージは**グローバルなPython環境**（OS全体にインストールされたPython環境）にインストールされます。 - -### 問題点 { #the-problem } - -では、グローバルPython環境にパッケージをインストールすることの問題点は何でしょうか？ - -ある時点で、あなたは**異なるパッケージ**に依存する多くのプログラムを書くことになるでしょう。そして、これらの中には同じパッケージの**異なるバージョン**に依存するものも出てくるでしょう。😱 - -例えば、 `philosophers-stone` （賢者の石）というプロジェクトを作成するとします。このプログラムは **`harry` （ハリー）というパッケージのバージョン `1`**に依存しています。そのため、 `harry` （ハリー）をインストールする必要があります。 - -```mermaid -flowchart LR - stone(philosophers-stone) -->|requires| harry-1[harry v1] -``` - -それから、 `prisoner-of-azkaban` （アズカバンの囚人）という別のプロジェクトを作成したとします。このプロジェクトも `harry` （ハリー）に依存していますが、**`harry` （ハリー）のバージョン `3`**が必要です。 - -```mermaid -flowchart LR - azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3] -``` - -しかし、ここで問題になるのは、もしローカルの**仮想環境**ではなくグローバル（環境）にパッケージをインストールするなら、 `harry` （ハリー）のどのバージョンをインストールするか選ばないといけないことです。 - -例えば、 `philosophers-stone` （賢者の石）を実行するには、まず `harry` （ハリー）のバージョン `1` をインストールする必要があります： - -
- -```console -$ pip install "harry==1" -``` - -
- -これにより、`harry` （ハリー）バージョン1がグローバルなPython環境にインストールされます。 - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -->|requires| harry-1 - end -``` - -しかし、 `prisoner-of-azkaban` （アズカバンの囚人）を実行したい場合は、`harry` （ハリー）のバージョン `1` をアンインストールし、`harry` （ハリー）のバージョン `3` をインストールし直す必要があります。（あるいは、単に`harry` （ハリー）のバージョン `3` をインストールすることで、自動的にバージョン `1` がアンインストールされます） - -
- -```console -$ pip install "harry==3" -``` - -
- -このようにして、グローバル環境への `harry` （ハリー）のバージョン `3` のインストールが完了します。 - -それから、 `philosophers-stone` （賢者の石）を再び実行しようとすると、このプログラムは `harry` （ハリー）のバージョン `1` が必要なため、**動作しなくなる**可能性があります。 - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - style harry-1 fill:#ccc,stroke-dasharray: 5 5 - harry-3[harry v3] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -.-x|⛔️| harry-1 - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --> |requires| harry-3 - end -``` - -/// tip | 豆知識 - -Pythonのパッケージでは、**新しいバージョン**で**互換性を損なう変更を避ける**よう努めるのが一般的ですが、それでも注意が必要です。すべてが正常に動作することをテストで確認してから、意図的に指定して新しいバージョンをインストールするのが良いでしょう。 - -/// - -あなたのすべての**プロジェクトが依存している**、**多数の**他の**パッケージ**が上記の問題を抱えていると想像してください。これは管理が非常に困難です。そして、**互換性のないバージョン**のパッケージを使ってプロジェクトを実行し、なぜ動作しないのか分からなくなるでしょう。 - -また、使用しているOS（Linux、Windows、macOS など）によっては、Pythonがすでにインストールされていることがあります。この場合、特定のバージョンのパッケージが**OSの動作に必要である**ことがあります。グローバル環境にパッケージをインストールすると、OSに付属するプログラムを**壊してしまう**可能性があります。 - -## パッケージのインストール先 { #where-are-packages-installed } - -Pythonをインストールしたとき、ファイルを含んだいくつかのディレクトリが作成されます。 - -これらの中には、インストールされたパッケージを保存するためのものもあります。 - -以下のコマンドを実行したとき： - -
- -```console -// 今は実行しないでください。これは単なる例です 🤓 -$ pip install "fastapi[standard]" ----> 100% -``` - -
- -FastAPIのコードを含む圧縮ファイルが、通常は [PyPI](https://pypi.org/project/fastapi/) からダウンロードされます。 - -また、FastAPIが依存する他のパッケージも**ダウンロード**されます。 - -それから、これらのファイルは**解凍**され、コンピュータのあるディレクトリに配置されます。 - -デフォルトでは、これらのファイルはPythonのインストール時に作成されるディレクトリ、つまり**グローバル環境**に配置されます。 - -## 仮想環境とは { #what-are-virtual-environments } - -すべてのパッケージをグローバル環境に配置することによって生じる問題の解決策は、作業する**プロジェクトごとの仮想環境**を使用することです。 - -仮想環境は**ディレクトリ**であり、グローバル環境と非常に似ていて、一つのプロジェクトで使う特定のパッケージ群をインストールできる場所です。 - -このようにして、それぞれのプロジェクトが独自の仮想環境（`.venv` ディレクトリ）に独自のパッケージ群を持つことができます。 - -```mermaid -flowchart TB - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) --->|requires| harry-1 - subgraph venv1[.venv] - harry-1[harry v1] - end - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --->|requires| harry-3 - subgraph venv2[.venv] - harry-3[harry v3] - end - end - stone-project ~~~ azkaban-project -``` - -## 仮想環境の有効化とは { #what-does-activating-a-virtual-environment-mean } - -仮想環境を有効にしたとき、例えば次のコマンドを実行した場合を考えます： - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -あるいは、WindowsでBashを使用している場合 ([Git Bash](https://gitforwindows.org/)など): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -これによって、いくつかの [環境変数](environment-variables.md) が作成・修正され、次に実行されるコマンドで使用できるようになります。 - -これらの環境変数のひとつに、 `PATH` 変数があります。 - -/// tip | 豆知識 - -`PATH` 変数についての詳細は [環境変数](environment-variables.md#path-environment-variable) を参照してください。 - -/// - -仮想環境を有効にすると、その仮想環境のパス `.venv/bin` （LinuxとmacOS）、あるいは `.venv\Scripts` （Windows）が `PATH` 変数に追加されます。 - -その環境を有効にする前の `PATH` 変数が次のようになっているとします。 - -//// tab | Linux, macOS - -```plaintext -/usr/bin:/bin:/usr/sbin:/sbin -``` - -これは、OSが以下のディレクトリ中でプログラムを探すことを意味します： - -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Windows\System32 -``` - -これは、OSが以下のディレクトリ中でプログラムを探すことを意味します： - -* `C:\Windows\System32` - -//// - -仮想環境を有効にすると、 `PATH` 変数は次のようになります。 - -//// tab | Linux, macOS - -```plaintext -/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -これは、OSが他のディレクトリを探すより前に、最初に以下のディレクトリ中でプログラムを探し始めることを意味します： - -```plaintext -/home/user/code/awesome-project/.venv/bin -``` - -そのため、ターミナルで `python` と入力した際に、OSはPythonプログラムを以下のパスで発見し、使用します。 - -```plaintext -/home/user/code/awesome-project/.venv/bin/python -``` - -//// - -//// tab | Windows - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32 -``` - -これは、OSが他のディレクトリを探すより前に、最初に以下のディレクトリ中でプログラムを探し始めることを意味します： - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts -``` - -そのため、ターミナルで `python` と入力した際に、OSはPythonプログラムを以下のパスで発見し、使用します。 - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -//// - -重要な点は、仮想環境のパスを `PATH` 変数の**先頭**に配置することです。OSは利用可能な他のPythonを見つけるより**前に**、この仮想環境のPythonを見つけるようになります。このようにして、 `python` を実行したときに、他の `python` （例えばグローバル環境の `python` ）ではなく、**その仮想環境の**Pythonを使用するようになります。 - -仮想環境を有効にして変更されることは他にもありますが、これが最も重要な変更のひとつです。 - -## 仮想環境の確認 { #checking-a-virtual-environment } - -仮想環境が有効かどうか、例えば次のように確認できます。： - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -//// - -これは、使用される `python` プログラムが**その仮想環境の**ものであることを意味します。 - -LinuxやmacOSでは `which` を、Windows PowerShellでは `Get-Command` を使用します。 - -このコマンドの動作は、 `PATH`変数に設定された**それぞれのパスを順に**確認していき、呼ばれている `python` プログラムを探します。そして、見つかり次第そのプログラムへの**パスを表示します**。 - -最も重要なことは、 `python` が呼ばれたときに、まさにこのコマンドで確認した "`python`" が実行されることです。 - -こうして、自分が想定通りの仮想環境にいるかを確認できます。 - -/// tip | 豆知識 - -ある仮想環境を有効にし、そのPythonを使用したまま**他のプロジェクトに移動して**しまうことは簡単に起こり得ます。 - -そして、その第二のプロジェクトは動作しないでしょう。なぜなら別のプロジェクトの仮想環境の**誤ったPython**を使用しているからです。 - -そのため、どの `python` が使用されているのか確認できることは役立ちます。🤓 - -/// - -## なぜ仮想環境を無効化するのか { #why-deactivate-a-virtual-environment } - -例えば、`philosophers-stone` （賢者の石）というプロジェクトで作業をしていて、**その仮想環境を有効にし**、必要なパッケージをインストールしてその環境内で作業を進めているとします。 - -それから、**別のプロジェクト**、 `prisoner-of-azkaban` （アズカバンの囚人）に取り掛かろうとします。 - -そのプロジェクトディレクトリへ移動します： - -
- -```console -$ cd ~/code/prisoner-of-azkaban -``` - -
- -もし `philosophers-stone` （賢者の石）の仮想環境を無効化していないと、`python` を実行したとき、 ターミナルは `philosophers-stone` （賢者の石）のPythonを使用しようとします。 - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -$ python main.py - -// sirius のインポートエラー。インストールされていません 😱 -Traceback (most recent call last): - File "main.py", line 1, in - import sirius -``` - -
- -しかし、その仮想環境を無効化し、 `prisoner-of-azkaban` のための新しい仮想環境を有効にすれば、 `python` を実行したときに `prisoner-of-azkaban` （アズカバンの囚人）の仮想環境の Python が使用されるようになります。 - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -// 無効化のために古いディレクトリにいる必要はありません。どこにいても、他のプロジェクトに移動した後でも実行できます 😎 -$ deactivate - -// prisoner-of-azkaban/.venv の仮想環境を有効化する 🚀 -$ source .venv/bin/activate - -// これで python を実行すると、この仮想環境にインストールされた sirius パッケージが見つかります ✨ -$ python main.py - -I solemnly swear 🐺 -``` - -
- -## 代替手段 { #alternatives } - -これは、あらゆる仕組みを**根本から**学ぶためのシンプルな入門ガイドです。 - -仮想環境、パッケージの依存関係（requirements）、プロジェクトの管理には、多くの**代替手段**があります。 - -準備が整い、パッケージの依存関係、仮想環境など**プロジェクト全体の管理**ツールを使いたいと考えたら、[uv](https://github.com/astral-sh/uv) を試してみることをおすすめします。 - -`uv` では以下のような多くのことができます： - -* 異なるバージョンも含めた**Python のインストール** -* プロジェクトごとの**仮想環境**の管理 -* **パッケージ**のインストール -* プロジェクトのパッケージの**依存関係やバージョン**の管理 -* パッケージとそのバージョンの、依存関係を含めた**厳密な**組み合わせを保持し、これによって、本番環境で、開発環境と全く同じようにプロジェクトを実行できる（これは**locking**と呼ばれます） -* その他のさまざまな機能 - -## まとめ { #conclusion } - -ここまで読みすべて理解したなら、世間の多くの開発者と比べて、仮想環境について**あなたはより多くのことを知っています**。🤓 - -これらの詳細を知ることは、将来、複雑に見える何かのデバッグにきっと役立つでしょう。しかし、その頃には、あなたは**そのすべての動作を根本から**理解しているでしょう。😎 +仮想環境の内部的な仕組み（有効化や、代替となる `python -m venv` と `pip` のワークフローを含む）については、[仮想環境ガイド](https://tiangolo.com/guides/virtual-environments/)を読んでください。 diff --git a/docs/ko/docs/advanced/additional-responses.md b/docs/ko/docs/advanced/additional-responses.md index 8786694..fcddff9 100644 --- a/docs/ko/docs/advanced/additional-responses.md +++ b/docs/ko/docs/advanced/additional-responses.md @@ -243,5 +243,5 @@ new_dict = {**old_dict, "new key": "new value"} 응답에 정확히 무엇을 포함할 수 있는지 보려면, OpenAPI 사양의 다음 섹션을 확인하세요: -* [OpenAPI Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object): `Response Object`를 포함합니다. -* [OpenAPI Response Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object): `responses` 파라미터 안의 각 응답에 이것의 어떤 항목이든 직접 포함할 수 있습니다. `description`, `headers`, `content`(여기에서 서로 다른 미디어 타입과 JSON Schema를 선언합니다), `links` 등을 포함할 수 있습니다. +* [OpenAPI Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object): `Response Object`를 포함합니다. +* [OpenAPI Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object): `responses` 파라미터 안의 각 응답에 이것의 어떤 항목이든 직접 포함할 수 있습니다. `description`, `headers`, `content`(여기에서 서로 다른 미디어 타입과 JSON Schema를 선언합니다), `links` 등을 포함할 수 있습니다. diff --git a/docs/ko/docs/advanced/async-tests.md b/docs/ko/docs/advanced/async-tests.md index b477c6c..75c21eb 100644 --- a/docs/ko/docs/advanced/async-tests.md +++ b/docs/ko/docs/advanced/async-tests.md @@ -45,7 +45,7 @@
```console -$ pytest +$ uv run pytest ---> 100% ``` diff --git a/docs/ko/docs/advanced/behind-a-proxy.md b/docs/ko/docs/advanced/behind-a-proxy.md index d5f42dd..500c91d 100644 --- a/docs/ko/docs/advanced/behind-a-proxy.md +++ b/docs/ko/docs/advanced/behind-a-proxy.md @@ -33,7 +33,7 @@ FastAPI CLI를 *CLI 옵션* `--forwarded-allow-ips`로 실행하고, 전달 헤
```console -$ fastapi run --forwarded-allow-ips="*" +$ uv run fastapi run --forwarded-allow-ips="*" INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -161,7 +161,7 @@ IP `0.0.0.0`은 보통 해당 머신/서버에서 사용 가능한 모든 IP에 } ``` -이 예시에서 "Proxy"는 **Traefik** 같은 것이고, 서버는 **Uvicorn**으로 실행되는 FastAPI CLI처럼, FastAPI 애플리케이션을 실행하는 구성일 수 있습니다. +이 예시에서 "Proxy"는 **Traefik** 같은 것이고, 서버는 **Uvicorn**을 사용하는 FastAPI CLI처럼, FastAPI 애플리케이션을 실행하는 구성일 수 있습니다. ### `root_path` 제공하기 { #providing-the-root-path } @@ -170,7 +170,7 @@ IP `0.0.0.0`은 보통 해당 머신/서버에서 사용 가능한 모든 IP에
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -200,7 +200,7 @@ ASGI 사양은 이 사용 사례를 위해 `root_path`를 정의합니다.
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -253,7 +253,7 @@ Uvicorn은 프록시가 `http://127.0.0.1:8000/app`에서 Uvicorn에 접근할 [Traefik](https://docs.traefik.io/)을 사용하면, 경로 접두사가 제거되는 구성을 로컬에서 쉽게 실험할 수 있습니다. -[Traefik 다운로드](https://github.com/containous/traefik/releases)는 단일 바이너리이며, 압축 파일을 풀고 터미널에서 바로 실행할 수 있습니다. +[Traefik 다운로드](https://github.com/traefik/traefik/releases)는 단일 바이너리이며, 압축 파일을 풀고 터미널에서 바로 실행할 수 있습니다. 그 다음 다음 내용을 가진 `traefik.toml` 파일을 생성하세요: @@ -321,7 +321,7 @@ INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -394,7 +394,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 기본적으로 **FastAPI**는 OpenAPI 스키마에서 `root_path`의 URL로 `server`를 생성합니다. -하지만 예를 들어 동일한 docs UI가 스테이징과 프로덕션 환경 모두와 상호작용하도록 하려면, 다른 대안 `servers`를 제공할 수도 있습니다. +하지만 예를 들어 *동일한* docs UI가 스테이징과 프로덕션 환경 모두와 상호작용하도록 하려면, 다른 대안 `servers`를 제공할 수도 있습니다. 사용자 정의 `servers` 리스트를 전달했고 `root_path`(API가 프록시 뒤에 있기 때문)가 있다면, **FastAPI**는 리스트의 맨 앞에 이 `root_path`를 가진 "server"를 삽입합니다. diff --git a/docs/ko/docs/advanced/dataclasses.md b/docs/ko/docs/advanced/dataclasses.md index 609cb6c..3d3a8bf 100644 --- a/docs/ko/docs/advanced/dataclasses.md +++ b/docs/ko/docs/advanced/dataclasses.md @@ -6,7 +6,7 @@ FastAPI는 **Pydantic** 위에 구축되어 있으며, 지금까지는 Pydantic {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -이는 **Pydantic** 덕분에 여전히 지원되는데, Pydantic이 [`dataclasses`에 대한 내부 지원](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel)을 제공하기 때문입니다. +이는 **Pydantic** 덕분에 여전히 지원되는데, Pydantic이 [`dataclasses`에 대한 내부 지원](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/#usage-of-stdlib-dataclasses-with-basemodel)을 제공하기 때문입니다. 따라서 위 코드처럼 Pydantic을 명시적으로 사용하지 않더라도, FastAPI는 Pydantic을 사용해 표준 dataclasses를 Pydantic의 dataclasses 변형으로 변환합니다. @@ -88,7 +88,7 @@ dataclass는 자동으로 Pydantic dataclass로 변환됩니다. `dataclasses`를 다른 Pydantic 모델과 조합하거나, 이를 상속하거나, 여러분의 모델에 포함하는 등의 작업도 할 수 있습니다. -자세한 내용은 [dataclasses에 관한 Pydantic 문서](https://docs.pydantic.dev/latest/concepts/dataclasses/)를 참고하세요. +자세한 내용은 [dataclasses에 관한 Pydantic 문서](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/)를 참고하세요. ## 버전 { #version } diff --git a/docs/ko/docs/advanced/events.md b/docs/ko/docs/advanced/events.md index 13db29e..c398314 100644 --- a/docs/ko/docs/advanced/events.md +++ b/docs/ko/docs/advanced/events.md @@ -154,7 +154,7 @@ async with lifespan(app): /// note | 참고 -Starlette `lifespan` 핸들러에 대해서는 [Starlette의 Lifespan 문서](https://www.starlette.dev/lifespan/)에서 더 읽어볼 수 있습니다. +Starlette `lifespan` 핸들러에 대해서는 [Starlette의 Lifespan 문서](https://starlette.dev/lifespan/)에서 더 읽어볼 수 있습니다. 또한 코드의 다른 영역에서 사용할 수 있는 lifespan 상태를 처리하는 방법도 포함되어 있습니다. diff --git a/docs/ko/docs/advanced/generate-clients.md b/docs/ko/docs/advanced/generate-clients.md index 9cbe46f..0fc267e 100644 --- a/docs/ko/docs/advanced/generate-clients.md +++ b/docs/ko/docs/advanced/generate-clients.md @@ -12,7 +12,7 @@ **TypeScript 클라이언트**의 경우 [Hey API](https://heyapi.dev/)는 TypeScript 생태계에 최적화된 경험을 제공하는 목적에 맞게 설계된 솔루션입니다. -더 많은 SDK 생성기는 [OpenAPI.Tools](https://openapi.tools/#sdk)에서 확인할 수 있습니다. +더 많은 SDK 생성기는 [OpenAPI.Tools](https://openapi.tools/categories/sdk-generators)에서 확인할 수 있습니다. /// tip | 팁 diff --git a/docs/ko/docs/advanced/middleware.md b/docs/ko/docs/advanced/middleware.md index 7443cf4..1354d18 100644 --- a/docs/ko/docs/advanced/middleware.md +++ b/docs/ko/docs/advanced/middleware.md @@ -91,7 +91,7 @@ HTTP Host Header 공격을 방어하기 위해, 들어오는 모든 요청에 예를 들어: -* [Uvicorn의 `ProxyHeadersMiddleware`](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) +* [Uvicorn의 `ProxyHeadersMiddleware`](https://github.com/Kludex/uvicorn/blob/main/uvicorn/middleware/proxy_headers.py) * [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -사용 가능한 다른 middleware를 보려면 [Starlette의 Middleware 문서](https://www.starlette.dev/middleware/)와 [ASGI Awesome List](https://github.com/florimondmanca/awesome-asgi)를 확인하세요. +사용 가능한 다른 middleware를 보려면 [Starlette의 Middleware 문서](https://starlette.dev/middleware/)와 [ASGI Awesome List](https://github.com/florimondmanca/awesome-asgi)를 확인하세요. diff --git a/docs/ko/docs/advanced/openapi-callbacks.md b/docs/ko/docs/advanced/openapi-callbacks.md index a44997b..92ef02e 100644 --- a/docs/ko/docs/advanced/openapi-callbacks.md +++ b/docs/ko/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ /// tip | 팁 -`callback_url` 쿼리 파라미터는 Pydantic의 [Url](https://docs.pydantic.dev/latest/api/networks/) 타입을 사용합니다. +`callback_url` 쿼리 파라미터는 Pydantic의 [Url](https://pydantic.dev/docs/validation/latest/api/pydantic/networks/) 타입을 사용합니다. /// @@ -106,11 +106,11 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) 일반적인 *경로 처리*와의 주요 차이점은 2가지입니다: * 실제 코드를 가질 필요가 없습니다. 여러분의 앱은 이 코드를 절대 호출하지 않기 때문입니다. 이는 *external API*를 문서화하는 데만 사용됩니다. 따라서 함수는 그냥 `pass`만 있어도 됩니다. -* *path*에는 [OpenAPI 3 표현식](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)(자세한 내용은 아래 참고)이 포함될 수 있으며, 이를 통해 *여러분의 API*로 보내진 원래 요청의 파라미터와 일부 값을 변수로 사용할 수 있습니다. +* *path*에는 [OpenAPI 3 표현식](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression)(자세한 내용은 아래 참고)이 포함될 수 있으며, 이를 통해 *여러분의 API*로 보내진 원래 요청의 파라미터와 일부 값을 변수로 사용할 수 있습니다. ### 콜백 경로 표현식 { #the-callback-path-expression } -콜백 *path*는 *여러분의 API*로 보내진 원래 요청의 일부를 포함할 수 있는 [OpenAPI 3 표현식](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)을 가질 수 있습니다. +콜백 *path*는 *여러분의 API*로 보내진 원래 요청의 일부를 포함할 수 있는 [OpenAPI 3 표현식](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression)을 가질 수 있습니다. 이 경우, 다음 `str`입니다: diff --git a/docs/ko/docs/advanced/response-cookies.md b/docs/ko/docs/advanced/response-cookies.md index f17046e..44bee5c 100644 --- a/docs/ko/docs/advanced/response-cookies.md +++ b/docs/ko/docs/advanced/response-cookies.md @@ -48,4 +48,4 @@ /// -사용 가능한 모든 매개변수와 옵션은 [Starlette의 문서](https://www.starlette.dev/responses/#set-cookie)에서 확인할 수 있습니다. +사용 가능한 모든 매개변수와 옵션은 [Starlette의 문서](https://starlette.dev/responses/#set-cookie)에서 확인할 수 있습니다. diff --git a/docs/ko/docs/advanced/response-headers.md b/docs/ko/docs/advanced/response-headers.md index 7699729..d8eebc2 100644 --- a/docs/ko/docs/advanced/response-headers.md +++ b/docs/ko/docs/advanced/response-headers.md @@ -1,6 +1,5 @@ # 응답 헤더 { #response-headers } - ## `Response` 매개변수 사용하기 { #use-a-response-parameter } 여러분은 *경로 처리 함수*에서 `Response` 타입의 매개변수를 선언할 수 있습니다 (쿠키와 같이 사용할 수 있습니다). @@ -39,4 +38,4 @@ 커스텀 사설 헤더는 [`X-` 접두어를 사용하여](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) 추가할 수 있다는 점을 기억하세요. -하지만, 여러분이 브라우저에서 클라이언트가 볼 수 있기를 원하는 커스텀 헤더가 있는 경우, CORS 설정에 이를 추가해야 합니다([CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)에서 자세히 알아보세요). [Starlette의 CORS 문서](https://www.starlette.dev/middleware/#corsmiddleware)에 문서화된 `expose_headers` 매개변수를 사용하세요. +하지만, 여러분이 브라우저에서 클라이언트가 볼 수 있기를 원하는 커스텀 헤더가 있는 경우, CORS 설정에 이를 추가해야 합니다([CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)에서 자세히 알아보세요). [Starlette의 CORS 문서](https://starlette.dev/middleware/#corsmiddleware)에 문서화된 `expose_headers` 매개변수를 사용하세요. diff --git a/docs/ko/docs/advanced/settings.md b/docs/ko/docs/advanced/settings.md index f7e8c20..c288ba7 100644 --- a/docs/ko/docs/advanced/settings.md +++ b/docs/ko/docs/advanced/settings.md @@ -1,15 +1,18 @@ # 설정과 환경 변수 { #settings-and-environment-variables } - 많은 경우 애플리케이션에는 외부 설정이나 구성(예: secret key, 데이터베이스 자격 증명, 이메일 서비스 자격 증명 등)이 필요할 수 있습니다. 이러한 설정 대부분은 데이터베이스 URL처럼 변동 가능(변경될 수 있음)합니다. 그리고 많은 설정은 secret처럼 민감할 수 있습니다. 이 때문에 보통 애플리케이션이 읽어들이는 환경 변수로 이를 제공하는 것이 일반적입니다. +**환경 변수**(**env var**라고도 함)는 Python 코드 외부, 운영체제에 존재하는 값이며, 애플리케이션과 다른 프로그램에서 읽을 수 있습니다. + +명령어를 실행할 때 해당 명령어를 위한 환경 변수를 만들 수 있습니다. 아래에서 플랫폼별 명령어를 볼 수 있습니다. + /// tip | 팁 -환경 변수를 이해하려면 [환경 변수](../environment-variables.md)를 읽어보세요. +환경 변수가 어떻게 동작하는지 자세히 설명한 [환경 변수 가이드](https://tiangolo.com/guides/environment-variables/)를 읽어보세요. /// @@ -21,16 +24,16 @@ ## Pydantic `Settings` { #pydantic-settings } -다행히 Pydantic은 환경 변수에서 오는 이러한 설정을 처리할 수 있는 훌륭한 유틸리티를 [Pydantic: Settings 관리](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)로 제공합니다. +다행히 Pydantic은 환경 변수에서 오는 이러한 설정을 처리할 수 있는 훌륭한 유틸리티를 [Pydantic: Settings 관리](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/)로 제공합니다. ### `pydantic-settings` 설치하기 { #install-pydantic-settings } -먼저 [가상 환경](../virtual-environments.md)을 만들고 활성화한 다음, `pydantic-settings` 패키지를 설치하세요: +프로젝트에 `pydantic-settings` 패키지를 추가하세요:
```console -$ pip install pydantic-settings +$ uv add pydantic-settings ---> 100% ``` @@ -41,7 +44,7 @@ $ pip install pydantic-settings
```console -$ pip install "fastapi[all]" +$ uv add "fastapi[all]" ---> 100% ``` @@ -77,19 +80,39 @@ Pydantic 모델과 같은 방식으로, 타입 어노테이션(그리고 필요 다음으로 환경 변수를 통해 구성을 전달하면서 서버를 실행합니다. 예를 들어 다음처럼 `ADMIN_EMAIL`과 `APP_NAME`을 설정할 수 있습니다: +//// tab | Linux, macOS, Windows Bash +
```console -$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py +$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uv run fastapi run main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
+//// + +//// tab | Windows PowerShell + +
+ +```console +$ $Env:ADMIN_EMAIL = "deadpool@example.com" +$ $Env:APP_NAME = "ChimichangApp" +$ uv run fastapi run main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +//// + /// tip | 팁 -하나의 명령에 여러 env var를 설정하려면 공백으로 구분하고, 모두 명령 앞에 두세요. +Bash에서 하나의 명령에 여러 env var를 설정하려면 공백으로 구분하고, 모두 명령 앞에 두세요. /// @@ -173,11 +196,11 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p /// -Pydantic은 외부 라이브러리를 사용해 이런 유형의 파일에서 읽는 기능을 지원합니다. 자세한 내용은 [Pydantic Settings: Dotenv (.env) 지원](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support)을 참고하세요. +Pydantic은 외부 라이브러리를 사용해 이런 유형의 파일에서 읽는 기능을 지원합니다. 자세한 내용은 [Pydantic Settings: Dotenv (.env) 지원](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#dotenv-env-support)을 참고하세요. /// tip | 팁 -이를 사용하려면 `pip install python-dotenv`가 필요합니다. +이를 사용하려면 `uv add python-dotenv`로 프로젝트에 `python-dotenv`를 추가하세요. /// @@ -198,7 +221,7 @@ APP_NAME="ChimichangApp" /// tip | 팁 -`model_config` 속성은 Pydantic 설정을 위한 것입니다. 자세한 내용은 [Pydantic: 개념: 구성](https://docs.pydantic.dev/latest/concepts/config/)을 참고하세요. +`model_config` 속성은 Pydantic 설정을 위한 것입니다. 자세한 내용은 [Pydantic: 개념: 구성](https://pydantic.dev/docs/validation/latest/concepts/config/)을 참고하세요. /// diff --git a/docs/ko/docs/advanced/sub-applications.md b/docs/ko/docs/advanced/sub-applications.md index b592c0a..8b4c215 100644 --- a/docs/ko/docs/advanced/sub-applications.md +++ b/docs/ko/docs/advanced/sub-applications.md @@ -1,6 +1,6 @@ # 하위 애플리케이션 - 마운트 { #sub-applications-mounts } -각각의 독립적인 OpenAPI와 문서 UI를 갖는 두 개의 독립적인 FastAPI 애플리케이션이 필요하다면, 메인 앱을 두고 하나(또는 그 이상)의 하위 애플리케이션을 "마운트"할 수 있습니다. +각각의 독립적인 OpenAPI와 문서 UI를 갖는 두 개의 독립적인 FastAPI 애플리케이션이 필요하다면, 메인 애플리케이션을 두고 하나(또는 그 이상)의 하위 애플리케이션을 "마운트"할 수 있습니다. ## **FastAPI** 애플리케이션 마운트 { #mounting-a-fastapi-application } @@ -35,7 +35,7 @@
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -44,7 +44,7 @@ $ fastapi dev 그리고 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)에서 문서를 여세요. -메인 앱의 자동 API 문서를 보게 될 것이며, 메인 앱 자체의 _경로 처리_만 포함됩니다: +메인 애플리케이션의 자동 API 문서를 보게 될 것이며, 메인 애플리케이션 자체의 _경로 처리_만 포함됩니다: @@ -54,7 +54,7 @@ $ fastapi dev -두 사용자 인터페이스 중 어느 것과 상호작용을 시도하더라도 올바르게 동작할 것입니다. 브라우저가 각 특정 앱 또는 하위 앱과 통신할 수 있기 때문입니다. +두 사용자 인터페이스 중 어느 것과 상호작용을 시도하더라도 올바르게 동작할 것입니다. 브라우저가 각 특정 애플리케이션 또는 하위 애플리케이션과 통신할 수 있기 때문입니다. ### 기술적 세부사항: `root_path` { #technical-details-root-path } @@ -62,6 +62,6 @@ $ fastapi dev 이렇게 하면 하위 애플리케이션은 문서 UI를 위해 해당 경로 접두사를 사용해야 한다는 것을 알게 됩니다. -또한 하위 애플리케이션도 자체적으로 하위 앱을 마운트할 수 있으며, FastAPI가 이 모든 `root_path`를 자동으로 처리하기 때문에 모든 것이 올바르게 동작합니다. +또한 하위 애플리케이션도 자체적으로 하위 애플리케이션을 마운트할 수 있으며, FastAPI가 이 모든 `root_path`를 자동으로 처리하기 때문에 모든 것이 올바르게 동작합니다. `root_path`와 이를 명시적으로 사용하는 방법에 대해서는 [프록시 뒤](behind-a-proxy.md) 섹션에서 더 알아볼 수 있습니다. diff --git a/docs/ko/docs/advanced/templates.md b/docs/ko/docs/advanced/templates.md index 9c33f37..8fef889 100644 --- a/docs/ko/docs/advanced/templates.md +++ b/docs/ko/docs/advanced/templates.md @@ -8,12 +8,12 @@ ## 의존성 설치 { #install-dependencies } -[가상 환경](../virtual-environments.md)을 생성하고, 활성화한 후 `jinja2`를 설치해야 합니다: +프로젝트에 `jinja2`를 추가합니다:
```console -$ pip install jinja2 +$ uv add jinja2 ---> 100% ``` @@ -123,4 +123,4 @@ Item ID: 42 ## 더 많은 세부 사항 { #more-details } -템플릿 테스트를 포함한 더 많은 세부 사항은 [Starlette의 템플릿 문서](https://www.starlette.dev/templates/)를 확인하세요. +템플릿 테스트를 포함한 더 많은 세부 사항은 [Starlette의 템플릿 문서](https://starlette.dev/templates/)를 확인하세요. diff --git a/docs/ko/docs/advanced/testing-events.md b/docs/ko/docs/advanced/testing-events.md index a1a7daf..6f480d6 100644 --- a/docs/ko/docs/advanced/testing-events.md +++ b/docs/ko/docs/advanced/testing-events.md @@ -5,7 +5,7 @@ {* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *} -["공식 Starlette 문서 사이트에서 테스트에서 라이프스팬 실행하기."](https://www.starlette.dev/lifespan/#running-lifespan-in-tests)에 대한 자세한 내용을 더 읽을 수 있습니다. +["공식 Starlette 문서 사이트에서 테스트에서 라이프스팬 실행하기."](https://starlette.dev/lifespan/#running-lifespan-in-tests)에 대한 자세한 내용을 더 읽을 수 있습니다. 더 이상 권장되지 않는 `startup` 및 `shutdown` 이벤트의 경우, 다음과 같이 `TestClient`를 사용할 수 있습니다: diff --git a/docs/ko/docs/advanced/testing-websockets.md b/docs/ko/docs/advanced/testing-websockets.md index 28f131c..3b83673 100644 --- a/docs/ko/docs/advanced/testing-websockets.md +++ b/docs/ko/docs/advanced/testing-websockets.md @@ -6,8 +6,8 @@ {* ../../docs_src/app_testing/tutorial002_py310.py hl[27:31] *} -/// note +/// note | 참고 -자세한 내용은 Starlette의 [WebSocket 테스트](https://www.starlette.dev/testclient/#testing-websocket-sessions) 문서를 확인하세요. +자세한 내용은 Starlette의 [WebSocket 테스트](https://starlette.dev/testclient/#testing-websocket-sessions) 문서를 확인하세요. /// diff --git a/docs/ko/docs/advanced/using-request-directly.md b/docs/ko/docs/advanced/using-request-directly.md index 7456d2a..3204688 100644 --- a/docs/ko/docs/advanced/using-request-directly.md +++ b/docs/ko/docs/advanced/using-request-directly.md @@ -15,7 +15,7 @@ ## `Request` 객체에 대한 세부 사항 { #details-about-the-request-object } -**FastAPI**는 실제로 내부에 **Starlette**을 사용하며, 그 위에 여러 도구를 덧붙인 구조입니다. 따라서 여러분이 필요할 때 Starlette의 [`Request`](https://www.starlette.dev/requests/) 객체를 직접 사용할 수 있습니다. +**FastAPI**는 실제로 내부에 **Starlette**을 사용하며, 그 위에 여러 도구를 덧붙인 구조입니다. 따라서 여러분이 필요할 때 Starlette의 [`Request`](https://starlette.dev/requests/) 객체를 직접 사용할 수 있습니다. 또한 이는 `Request` 객체에서 데이터를 직접 가져오는 경우(예: 본문을 읽기) FastAPI가 해당 데이터를 검증하거나 변환하지 않으며, 문서화(OpenAPI를 통한 자동 API 사용자 인터페이스용)도 되지 않는다는 의미이기도 합니다. @@ -45,7 +45,7 @@ ## `Request` 설명서 { #request-documentation } -여러분은 [`Request` 객체에 대한 공식 Starlette 설명서 사이트](https://www.starlette.dev/requests/)에 대한 더 자세한 내용을 읽어볼 수 있습니다. +여러분은 [`Request` 객체에 대한 공식 Starlette 설명서 사이트](https://starlette.dev/requests/)에 대한 더 자세한 내용을 읽어볼 수 있습니다. /// note | 기술 세부사항 diff --git a/docs/ko/docs/advanced/websockets.md b/docs/ko/docs/advanced/websockets.md index b37d938..7c4113d 100644 --- a/docs/ko/docs/advanced/websockets.md +++ b/docs/ko/docs/advanced/websockets.md @@ -4,12 +4,12 @@ ## `websockets` 설치 { #install-websockets } -[가상 환경](../virtual-environments.md)을 생성하고 활성화한 다음, `websockets`("WebSocket" 프로토콜을 쉽게 사용할 수 있게 해주는 Python 라이브러리)를 설치하세요: +프로젝트에 `websockets`("WebSocket" 프로토콜을 쉽게 사용할 수 있게 해주는 Python 라이브러리)를 추가하세요:
```console -$ pip install websockets +$ uv add websockets ---> 100% ``` @@ -69,7 +69,7 @@ WebSocket 경로에서 메시지를 대기(`await`)하고 전송할 수 있습
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -126,7 +126,7 @@ WebSocket이기 때문에 `HTTPException`을 발생시키는 것은 적절하지
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -182,5 +182,5 @@ FastAPI와 쉽게 통합할 수 있으면서 더 견고하고 Redis, PostgreSQL 다음 옵션에 대해 더 알아보려면 Starlette의 문서를 확인하세요: -* [`WebSocket` 클래스](https://www.starlette.dev/websockets/). -* [클래스 기반 WebSocket 처리](https://www.starlette.dev/endpoints/#websocketendpoint). +* [`WebSocket` 클래스](https://starlette.dev/websockets/). +* [클래스 기반 WebSocket 처리](https://starlette.dev/endpoints/#websocketendpoint). diff --git a/docs/ko/docs/advanced/wsgi.md b/docs/ko/docs/advanced/wsgi.md index 2b3012a..2104764 100644 --- a/docs/ko/docs/advanced/wsgi.md +++ b/docs/ko/docs/advanced/wsgi.md @@ -8,7 +8,7 @@ /// note | 참고 -이를 사용하려면 `a2wsgi`를 설치해야 합니다. 예: `pip install a2wsgi` +이를 사용하려면 프로젝트에 `a2wsgi`를 추가해야 합니다. 예: `uv add a2wsgi` /// diff --git a/docs/ko/docs/alternatives.md b/docs/ko/docs/alternatives.md index 1bd0ba5..6fe6c72 100644 --- a/docs/ko/docs/alternatives.md +++ b/docs/ko/docs/alternatives.md @@ -125,7 +125,7 @@ def read_url(): 또한 표준 기반의 사용자 인터페이스 도구를 통합하기: * [Swagger UI](https://github.com/swagger-api/swagger-ui) -* [ReDoc](https://github.com/Rebilly/ReDoc) +* [ReDoc](https://github.com/Redocly/redoc) 이 두 가지는 꽤 대중적이고 안정적이기 때문에 선택되었습니다. 하지만 간단히 검색해보면 OpenAPI를 위한 대안 UI가 수십 가지나 있다는 것을 알 수 있습니다(**FastAPI**와 함께 사용할 수 있습니다). @@ -237,7 +237,7 @@ serialization과 validation을 정의하는 동일한 코드로부터 OpenAPI sc /// -### [NestJS](https://nestjs.com/) (그리고 [Angular](https://angular.io/)) { #nestjs-and-angular } +### [NestJS](https://nestjs.com/) (그리고 [Angular](https://angular.dev/)) { #nestjs-and-angular } 이건 Python도 아닙니다. NestJS는 Angular에서 영감을 받은 JavaScript(TypeScript) NodeJS framework입니다. @@ -337,7 +337,7 @@ OpenAPI나 JSON Schema 같은 표준을 기반으로 하지 않았기 때문에 /// note | 참고 -Hug는 Timothy Crosley가 만들었습니다. Python 파일에서 import를 자동으로 정렬하는 훌륭한 도구인 [`isort`](https://github.com/timothycrosley/isort)의 제작자이기도 합니다. +Hug는 Timothy Crosley가 만들었습니다. Python 파일에서 import를 자동으로 정렬하는 훌륭한 도구인 [`isort`](https://github.com/PyCQA/isort)의 제작자이기도 합니다. /// @@ -401,7 +401,7 @@ APIStar는 Tom Christie가 만들었습니다. 다음을 만든 사람과 동일 ## **FastAPI**가 사용하는 것 { #used-by-fastapi } -### [Pydantic](https://docs.pydantic.dev/) { #pydantic } +### [Pydantic](https://pydantic.dev/docs/) { #pydantic } Pydantic은 Python type hints를 기반으로 데이터 검증, serialization, 문서화(JSON Schema 사용)를 정의하는 라이브러리입니다. @@ -417,7 +417,7 @@ Marshmallow와 비교할 수 있습니다. 다만 benchmark에서 Marshmallow보 /// -### [Starlette](https://www.starlette.dev/) { #starlette } +### [Starlette](https://starlette.dev/) { #starlette } Starlette는 경량 ASGI framework/toolkit으로, 고성능 asyncio 서비스를 만들기에 이상적입니다. @@ -462,7 +462,7 @@ ASGI는 Django 코어 팀 멤버들이 개발 중인 새로운 "표준"입니다 /// -### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn } +### [Uvicorn](https://uvicorn.dev) { #uvicorn } Uvicorn은 uvloop과 httptools로 구축된 초고속 ASGI 서버입니다. diff --git a/docs/ko/docs/deployment/docker.md b/docs/ko/docs/deployment/docker.md index db166bf..6e21231 100644 --- a/docs/ko/docs/deployment/docker.md +++ b/docs/ko/docs/deployment/docker.md @@ -105,36 +105,32 @@ Docker나 Kubernetes 같은 모든 컨테이너 관리 시스템에는 이러한 ### 패키지 요구사항 { #package-requirements } -보통 애플리케이션의 **패키지 요구사항**을 어떤 파일에 적어 둡니다. +`uv`로 프로젝트를 관리할 때는 직접 의존성이 `pyproject.toml`에 선언되고, 정확히 해결된 버전은 `uv.lock`에 저장됩니다. -이는 주로 그 요구사항을 **설치**하는 데 사용하는 도구에 따라 달라집니다. - -가장 일반적인 방법은 패키지 이름과 버전을 한 줄에 하나씩 적어 둔 `requirements.txt` 파일을 사용하는 것입니다. - -버전 범위를 설정할 때는 [FastAPI 버전들에 대하여](versions.md)에서 읽은 것과 같은 아이디어를 사용하면 됩니다. - -예를 들어 `requirements.txt`는 다음과 같을 수 있습니다: - -``` -fastapi[standard]>=0.113.0,<0.114.0 -pydantic>=2.7.0,<3.0.0 -``` - -그리고 보통 `pip`로 패키지 의존성을 설치합니다. 예를 들면: +애플리케이션에 필요한 패키지를 다음으로 추가할 수 있습니다:
```console -$ pip install -r requirements.txt +$ uv add "fastapi[standard]" pydantic ---> 100% -Successfully installed fastapi pydantic ```
/// note | 참고 -패키지 의존성을 정의하고 설치하는 다른 형식과 도구도 있습니다. +아래 Dockerfile은 컨테이너 내부에서 `pip`를 사용합니다. uv 프로젝트에서 잠긴 의존성을 Dockerfile이 기대하는 `requirements.txt` 형식으로 내보낼 수 있습니다: + +
+ +```console +$ uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt +``` + +
+ +생성된 `requirements.txt`는 컨테이너 빌드를 위한 내보내기 결과입니다. 의존성 관리는 계속 `uv add`로 하고, `uv.lock`이 변경될 때 다시 생성하세요. /// @@ -372,7 +368,7 @@ Docker 컨테이너의 URL에서 확인할 수 있어야 합니다. 예를 들 또한 [http://192.168.99.100/redoc](http://192.168.99.100/redoc) 또는 [http://127.0.0.1/redoc](http://127.0.0.1/redoc)(또는 Docker 호스트를 사용해 동등하게 접근)로 이동할 수도 있습니다. -대안 자동 문서([ReDoc](https://github.com/Rebilly/ReDoc) 제공)를 볼 수 있습니다: +대안 자동 문서([ReDoc](https://github.com/Redocly/redoc) 제공)를 볼 수 있습니다: ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) diff --git a/docs/ko/docs/deployment/fastapicloud.md b/docs/ko/docs/deployment/fastapicloud.md index 5fe057f..9b43bb1 100644 --- a/docs/ko/docs/deployment/fastapicloud.md +++ b/docs/ko/docs/deployment/fastapicloud.md @@ -1,11 +1,11 @@ # FastAPI Cloud { #fastapi-cloud } -**한 번의 명령**으로 FastAPI 앱을 [FastAPI Cloud](https://fastapicloud.com)에 배포할 수 있습니다. 🚀 +**한 번의 명령어**만으로 FastAPI 애플리케이션을 [FastAPI Cloud](https://fastapicloud.com)에 배포할 수 있습니다. 🚀
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -18,7 +18,7 @@ Deploying to FastAPI Cloud... CLI가 FastAPI 애플리케이션을 자동으로 감지하여 클라우드에 배포합니다. 로그인되어 있지 않다면, 인증을 완료할 수 있도록 브라우저가 자동으로 열립니다. -이게 전부입니다! 이제 해당 URL에서 앱에 접근할 수 있습니다. ✨ +이게 전부입니다! 이제 해당 URL에서 애플리케이션에 접근할 수 있습니다. ✨ ## FastAPI Cloud 소개 { #about-fastapi-cloud } @@ -26,9 +26,9 @@ CLI가 FastAPI 애플리케이션을 자동으로 감지하여 클라우드에 최소한의 노력으로 API를 **구축**, **배포**, **접근**하는 과정을 간소화합니다. -FastAPI로 앱을 만들 때의 동일한 **개발자 경험**을, 클라우드에 **배포**할 때도 제공합니다. 🎉 +FastAPI로 애플리케이션을 만들 때의 동일한 **개발자 경험**을, 클라우드에 **배포**할 때도 제공합니다. 🎉 -또한 앱을 배포할 때 보통 필요한 대부분의 것들도 처리해 줍니다. 예를 들면: +또한 애플리케이션을 배포할 때 보통 필요한 대부분의 것들도 처리해 줍니다. 예를 들면: * HTTPS * 요청을 기반으로 자동 스케일링하는 복제(Replication) @@ -38,10 +38,10 @@ FastAPI Cloud는 *FastAPI and friends* 오픈 소스 프로젝트의 주요 스 ## 다른 클라우드 제공업체에 배포하기 { #deploy-to-other-cloud-providers } -FastAPI는 오픈 소스이며 표준을 기반으로 합니다. 원하는 어떤 클라우드 제공업체에도 FastAPI 앱을 배포할 수 있습니다. +FastAPI는 오픈 소스이며 표준을 기반으로 합니다. 원하는 어떤 클라우드 제공업체에도 FastAPI 애플리케이션을 배포할 수 있습니다. -해당 클라우드 제공업체의 가이드를 따라 FastAPI 앱을 배포하세요. 🤓 +해당 클라우드 제공업체의 가이드를 따라 FastAPI 애플리케이션을 배포하세요. 🤓 ## 자체 서버에 배포하기 { #deploy-your-own-server } -또한 이 **Deployment** 가이드에서 이후에 모든 세부사항을 알려드릴 거예요. 그래서 무슨 일이 일어나고 있는지, 무엇이 필요하며, 본인의 서버를 포함해 직접 FastAPI 앱을 어떻게 배포하는지까지 이해할 수 있게 될 것입니다. 🤓 +또한 이 **Deployment** 가이드에서 이후에 모든 세부사항을 알려드릴 거예요. 그래서 무슨 일이 일어나고 있는지, 무엇이 필요하며, 본인의 서버를 포함해 직접 FastAPI 애플리케이션을 어떻게 배포하는지까지 이해할 수 있게 될 것입니다. 🤓 diff --git a/docs/ko/docs/deployment/manually.md b/docs/ko/docs/deployment/manually.md index fbac816..db3198b 100644 --- a/docs/ko/docs/deployment/manually.md +++ b/docs/ko/docs/deployment/manually.md @@ -52,7 +52,7 @@ FastAPI는 ```console -$ pip install "uvicorn[standard]" +$ uv add "uvicorn[standard]" ---> 100% ``` @@ -95,7 +95,7 @@ $ pip install "uvicorn[standard]" 여기에는 `uvloop`가 포함되며, 이는 `asyncio`를 고성능으로 대체할 수 있는 드롭인 대체재로, 큰 동시성 성능 향상을 제공합니다. -`pip install "fastapi[standard]"` 같은 방식으로 FastAPI를 설치하면 `uvicorn[standard]`도 함께 설치됩니다. +`uv add "fastapi[standard]"` 같은 방식으로 FastAPI를 추가하면 `uvicorn[standard]`도 함께 설치됩니다. /// @@ -106,7 +106,7 @@ ASGI 서버를 수동으로 설치했다면, 보통 FastAPI 애플리케이션
```console -$ uvicorn main:app --host 0.0.0.0 --port 80 +$ uv run uvicorn main:app --host 0.0.0.0 --port 80 INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) ``` diff --git a/docs/ko/docs/deployment/server-workers.md b/docs/ko/docs/deployment/server-workers.md index a9d0624..8ed07ab 100644 --- a/docs/ko/docs/deployment/server-workers.md +++ b/docs/ko/docs/deployment/server-workers.md @@ -86,7 +86,7 @@ $ fastapi run --workers 4 ```console -$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 +$ uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit) INFO: Started parent process [27365] INFO: Started server process [27368] diff --git a/docs/ko/docs/environment-variables.md b/docs/ko/docs/environment-variables.md index d807f7f..9abf70b 100644 --- a/docs/ko/docs/environment-variables.md +++ b/docs/ko/docs/environment-variables.md @@ -1,299 +1,11 @@ # 환경 변수 { #environment-variables } +**환경 변수**(또는 **env var**라고도 합니다)는 파이썬 코드의 바깥인 운영 체제에 존재하는 값이며, 애플리케이션과 다른 프로그램에서 읽을 수 있습니다. -/// tip | 팁 +FastAPI 애플리케이션은 데이터베이스 URL, 이메일 자격 증명, 비밀 키와 같은 설정에 환경 변수를 흔히 사용합니다. -만약 "환경 변수"가 무엇이고, 어떻게 사용하는지 알고 계시다면, 이 챕터를 스킵하셔도 좋습니다. +[설정 및 환경 변수](advanced/settings.md)에서 애플리케이션 설정에 환경 변수를 사용하는 방법을 배우게 됩니다. -/// +## 더 알아보기 { #learn-more } -환경 변수(또는 "**env var**"라고도 합니다)는 파이썬 코드의 **바깥**인, **운영 체제**에 존재하는 변수이며, 파이썬 코드(또는 다른 프로그램에서도)에서 읽을 수 있습니다. - -환경 변수는 애플리케이션 **설정**을 처리하거나, 파이썬의 **설치** 과정의 일부로 유용할 수 있습니다. - -## 환경 변수를 만들고 사용하기 { #create-and-use-env-vars } - -파이썬 없이도, **셸 (터미널)** 에서 환경 변수를 **생성** 하고 사용할 수 있습니다. - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// 환경 변수 MY_NAME을 다음과 같이 생성할 수 있습니다 -$ export MY_NAME="Wade Wilson" - -// 그런 다음 다른 프로그램과 함께 사용할 수 있습니다. 예: -$ echo "Hello $MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// 환경 변수 MY_NAME 생성 -$ $Env:MY_NAME = "Wade Wilson" - -// 다른 프로그램과 함께 사용하기. 예: -$ echo "Hello $Env:MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -## 파이썬에서 env var 읽기 { #read-env-vars-in-python } - -파이썬 **바깥**인 터미널에서(또는 다른 어떤 방법으로든) 환경 변수를 만들고, 그런 다음 **파이썬에서 읽을 수 있습니다**. - -예를 들어 다음과 같은 `main.py` 파일이 있다고 합시다: - -```Python hl_lines="3" -import os - -name = os.getenv("MY_NAME", "World") -print(f"Hello {name} from Python") -``` - -/// tip | 팁 - -[`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) 의 두 번째 인자는 반환할 기본값입니다. - -제공하지 않으면 기본값은 `None`이며, 여기서는 사용할 기본값으로 `"World"`를 제공합니다. - -/// - -그러면 해당 파이썬 프로그램을 다음과 같이 호출할 수 있습니다: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// 여기서는 아직 환경 변수를 설정하지 않습니다 -$ python main.py - -// 환경 변수를 설정하지 않았으므로 기본값이 사용됩니다 - -Hello World from Python - -// 하지만 먼저 환경 변수를 생성하면 -$ export MY_NAME="Wade Wilson" - -// 그리고 프로그램을 다시 실행하면 -$ python main.py - -// 이제 환경 변수를 읽을 수 있습니다 - -Hello Wade Wilson from Python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// 여기서는 아직 환경 변수를 설정하지 않습니다 -$ python main.py - -// 환경 변수를 설정하지 않았으므로 기본값이 사용됩니다 - -Hello World from Python - -// 하지만 먼저 환경 변수를 생성하면 -$ $Env:MY_NAME = "Wade Wilson" - -// 그리고 프로그램을 다시 실행하면 -$ python main.py - -// 이제 환경 변수를 읽을 수 있습니다 - -Hello Wade Wilson from Python -``` - -
- -//// - -환경변수는 코드 바깥에서 설정될 수 있지만, 코드에서 읽을 수 있고, 나머지 파일과 함께 저장(`git`에 커밋)할 필요가 없으므로, 구성이나 **설정** 에 사용하는 것이 일반적입니다. - -또한 **특정 프로그램 호출**에 대해서만 사용할 수 있는 환경 변수를 만들 수도 있는데, 해당 프로그램에서만 사용할 수 있고, 해당 프로그램이 실행되는 동안만 사용할 수 있습니다. - -그렇게 하려면 프로그램 바로 앞, 같은 줄에 환경 변수를 만들어야 합니다: - -
- -```console -// 이 프로그램 호출을 위해 같은 줄에서 환경 변수 MY_NAME 생성 -$ MY_NAME="Wade Wilson" python main.py - -// 이제 환경 변수를 읽을 수 있습니다 - -Hello Wade Wilson from Python - -// 이후에는 해당 환경 변수가 존재하지 않습니다 -$ python main.py - -Hello World from Python -``` - -
- -/// tip | 팁 - -[The Twelve-Factor App: Config](https://12factor.net/config) 에서 좀 더 자세히 알아볼 수 있습니다. - -/// - -## 타입과 검증 { #types-and-validation } - -이 환경변수들은 오직 **텍스트 문자열**로만 처리할 수 있습니다. 텍스트 문자열은 파이썬 외부에 있으며 다른 프로그램 및 나머지 시스템(그리고 Linux, Windows, macOS 같은 서로 다른 운영 체제에서도)과 호환되어야 합니다. - -즉, 파이썬에서 환경 변수로부터 읽은 **모든 값**은 **`str`**이 되고, 다른 타입으로의 변환이나 검증은 코드에서 수행해야 합니다. - -**애플리케이션 설정**을 처리하기 위한 환경 변수 사용에 대한 자세한 내용은 [고급 사용자 가이드 - 설정 및 환경 변수](./advanced/settings.md) 에서 확인할 수 있습니다. - -## `PATH` 환경 변수 { #path-environment-variable } - -**`PATH`**라고 불리는, **특별한** 환경변수가 있습니다. 운영체제(Linux, macOS, Windows)에서 실행할 프로그램을 찾기위해 사용됩니다. - -변수 `PATH`의 값은 Linux와 macOS에서는 콜론 `:`, Windows에서는 세미콜론 `;`으로 구분된 디렉토리로 구성된 긴 문자열입니다. - -예를 들어, `PATH` 환경 변수는 다음과 같습니다: - -//// tab | Linux, macOS - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -이는 시스템이 다음 디렉토리에서 프로그램을 찾아야 함을 의미합니다: - -* `/usr/local/bin` -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32 -``` - -이는 시스템이 다음 디렉토리에서 프로그램을 찾아야 함을 의미합니다: - -* `C:\Program Files\Python312\Scripts` -* `C:\Program Files\Python312` -* `C:\Windows\System32` - -//// - -터미널에 **명령어**를 입력하면 운영 체제는 `PATH` 환경 변수에 나열된 **각 디렉토리**에서 프로그램을 **찾습니다.** - -예를 들어 터미널에 `python`을 입력하면 운영 체제는 해당 목록의 **첫 번째 디렉토리**에서 `python`이라는 프로그램을 찾습니다. - -찾으면 **사용합니다**. 그렇지 않으면 **다른 디렉토리**에서 계속 찾습니다. - -### 파이썬 설치와 `PATH` 업데이트 { #installing-python-and-updating-the-path } - -파이썬을 설치할 때, 아마 `PATH` 환경 변수를 업데이트 할 것이냐고 물어봤을 겁니다. - -//// tab | Linux, macOS - -파이썬을 설치하고 그것이 `/opt/custompython/bin` 디렉토리에 있다고 가정해 보겠습니다. - -`PATH` 환경 변수를 업데이트하도록 "예"라고 하면 설치 관리자가 `/opt/custompython/bin`을 `PATH` 환경 변수에 추가합니다. - -다음과 같이 보일 수 있습니다: - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin -``` - -이렇게 하면 터미널에 `python`을 입력할 때, 시스템이 `/opt/custompython/bin`(마지막 디렉토리)에서 파이썬 프로그램을 찾아 사용합니다. - -//// - -//// tab | Windows - -파이썬을 설치하고 그것이 `C:\opt\custompython\bin` 디렉토리에 있다고 가정해 보겠습니다. - -`PATH` 환경 변수를 업데이트하도록 "예"라고 하면 설치 관리자가 `C:\opt\custompython\bin`을 `PATH` 환경 변수에 추가합니다. - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin -``` - -이렇게 하면 터미널에 `python`을 입력할 때, 시스템이 `C:\opt\custompython\bin`(마지막 디렉토리)에서 파이썬 프로그램을 찾아 사용합니다. - -//// - -그래서, 다음과 같이 입력한다면: - -
- -```console -$ python -``` - -
- -//// tab | Linux, macOS - -시스템은 `/opt/custompython/bin`에서 `python` 프로그램을 **찾아** 실행합니다. - -다음과 같이 입력하는 것과 거의 같습니다: - -
- -```console -$ /opt/custompython/bin/python -``` - -
- -//// - -//// tab | Windows - -시스템은 `C:\opt\custompython\bin\python`에서 `python` 프로그램을 **찾아** 실행합니다. - -다음과 같이 입력하는 것과 거의 같습니다: - -
- -```console -$ C:\opt\custompython\bin\python -``` - -
- -//// - -이 정보는 [가상 환경](virtual-environments.md) 에 대해 알아볼 때 유용할 것입니다. - -## 결론 { #conclusion } - -이 문서를 통해 **환경 변수**가 무엇이고 파이썬에서 어떻게 사용하는지 기본적으로 이해하셨을 겁니다. - -또한 [환경 변수에 대한 위키피디아](https://en.wikipedia.org/wiki/Environment_variable)에서 이에 대해 자세히 알아볼 수 있습니다. - -많은 경우에서, 환경 변수가 어떻게 유용하고 적용 가능한지 바로 명확하게 알 수는 없습니다. 하지만 개발할 때 다양한 시나리오에서 계속 나타나므로 이에 대해 아는 것이 좋습니다. - -예를 들어, 다음 섹션인 [가상 환경](virtual-environments.md)에서 이 정보가 필요합니다. +환경 변수를 만들고 읽는 방법과 `PATH` 환경 변수가 어떻게 동작하는지까지 포함한 자세한 크로스 플랫폼 설명은 [환경 변수 가이드](https://tiangolo.com/guides/environment-variables/)를 읽어보세요. diff --git a/docs/ko/docs/fastapi-cli.md b/docs/ko/docs/fastapi-cli.md index 9b637af..6f1f2ca 100644 --- a/docs/ko/docs/fastapi-cli.md +++ b/docs/ko/docs/fastapi-cli.md @@ -2,7 +2,7 @@ **FastAPI CLI**는 FastAPI 애플리케이션을 서빙하고, FastAPI 프로젝트를 관리하는 등 다양한 작업에 사용할 수 있는 커맨드 라인 프로그램입니다. -FastAPI를 설치하면(예: `pip install "fastapi[standard]"`) 터미널에서 실행할 수 있는 커맨드 라인 프로그램이 함께 제공됩니다. +프로젝트에 FastAPI를 추가하면(예: `uv add "fastapi[standard]"`) 터미널에서 실행할 수 있는 명령줄 프로그램이 함께 제공됩니다. 개발용으로 FastAPI 애플리케이션을 실행하려면 `fastapi dev` 명령어를 사용할 수 있습니다: @@ -52,7 +52,7 @@ $ fastapi dev /// -내부적으로 **FastAPI CLI**는 고성능의, 프로덕션에 적합한 ASGI 서버인 [Uvicorn](https://www.uvicorn.dev)을 사용합니다. 😎 +내부적으로 **FastAPI CLI**는 고성능의, 프로덕션에 적합한 ASGI 서버인 [Uvicorn](https://uvicorn.dev)을 사용합니다. 😎 `fastapi` CLI는 기본적으로 실행할 FastAPI 앱을 자동으로 감지하려고 시도합니다. `main.py` 파일 안의 `app`이라는 객체(또는 몇 가지 변형)가 있다고 가정합니다. @@ -100,13 +100,13 @@ from backend.main import app `fastapi dev` 명령어에 파일 경로를 전달할 수도 있으며, 그러면 사용할 FastAPI 앱 객체를 추정합니다: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` 또는, `fastapi dev` 명령어에 `--entrypoint` 옵션을 전달할 수도 있습니다: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` 하지만 매번 `fastapi` 명령어를 호출할 때 올바른 경로\entrypoint를 전달하는 것을 기억해야 합니다. @@ -119,6 +119,10 @@ $ fastapi dev --entrypoint main:app 기본적으로 **auto-reload**가 활성화되어 코드에 변경이 생기면 서버를 자동으로 다시 로드합니다. 이는 리소스를 많이 사용하며, 비활성화했을 때보다 안정성이 떨어질 수 있습니다. 개발 환경에서만 사용해야 합니다. 또한 컴퓨터가 자신과만 통신하기 위한(`localhost`) IP인 `127.0.0.1`에서 연결을 대기합니다. +앱을 임포트하기 전에 `fastapi dev`는 `FASTAPI_ENV` 환경 변수를 `development`로 설정합니다. `FASTAPI_ENV`가 이미 설정되어 있다면 기존 값이 유지됩니다. 이를 통해 앱 시작 코드는 개발에 친화적인 동작을 선택할 수 있으며, 동시에 `staging` 같은 앱별 환경을 제공할 수 있습니다. + +일반적인 `FASTAPI_ENV` 값은 `development`와 `production`입니다. 현재 `fastapi run`은 `FASTAPI_ENV`를 변경하지 않으므로, 앱에서 프로덕션 모드를 감지해야 한다면 명시적으로 설정하세요. + ## `fastapi run` { #fastapi-run } `fastapi run`을 실행하면 프로덕션 모드로 FastAPI가 시작됩니다. diff --git a/docs/ko/docs/help-fastapi.md b/docs/ko/docs/help-fastapi.md index 9e944d7..9ac10e6 100644 --- a/docs/ko/docs/help-fastapi.md +++ b/docs/ko/docs/help-fastapi.md @@ -46,20 +46,6 @@ FastAPI와 friends에 대한 소식을 공유할 때 알림을 받으려면, 개 * [**Bluesky**의 @tiangolo.com](https://bsky.app/profile/tiangolo.com) * [**LinkedIn**의 @tiangolo](https://www.linkedin.com/in/tiangolo/). -## GitHub에서 질문으로 다른 사람 돕기 { #help-others-with-questions-in-github } - -[GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered)에서 다른 사람들의 질문에 도움을 줄 수 있습니다. - -많은 경우, 이미 그 질문에 대한 답을 알고 있을 수 있습니다. 🤓 - -많은 사람들의 질문을 도와주면, 공식 [FastAPI 전문가](fastapi-people.md#fastapi-experts)가 됩니다. 🎉 - -가장 중요한 점은: 친절하려고 노력하는 것입니다. 🤗 - -### 도움 주는 방법 { #how-to-help } - -여기 있는 [도움 주는 방법 가이드](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github)를 따라 주세요. - ## 질문하기 { #ask-questions } GitHub 저장소에서 [새 질문을 생성](https://github.com/fastapi/fastapi/discussions/new?category=questions)할 수 있습니다. 예를 들면: @@ -69,7 +55,7 @@ GitHub 저장소에서 [새 질문을 생성](https://github.com/fastapi/fastapi ## 채팅에 참여하기 { #join-the-chat } -👥 [Discord 채팅 서버](https://discord.gg/VQjSZaeJmf) 👥 에 참여해서 FastAPI 커뮤니티의 다른 사람들과 어울리세요. +👥 [Discord 채팅 서버](https://discord.com/invite/VQjSZaeJmf) 👥 에 참여해서 FastAPI 커뮤니티의 다른 사람들과 어울리세요. /// tip | 팁 @@ -86,3 +72,9 @@ GitHub 저장소에서 [새 질문을 생성](https://github.com/fastapi/fastapi GitHub에서는 템플릿이 올바른 질문을 작성하도록 안내하여, 더 쉽게 좋은 답변을 받거나 심지어 질문하기 전에 스스로 문제를 해결할 수 있습니다. 또한 채팅 시스템의 대화는 GitHub만큼 검색이 쉽지 않아, 대화 속에 묻히곤 합니다. + +## FastAPI Cloud 사용해 보기 { #try-fastapi-cloud } + +FastAPI와 friends의 주요 자금은 FastAPI 애플리케이션을 간단하고 빠르게, 단일 명령어 `fastapi deploy`로 배포할 수 있는 플랫폼인 [**FastAPI Cloud**](https://fastapicloud.com)에서 나옵니다. + +FastAPI Cloud는 FastAPI를 만든 같은 팀이 구축했습니다. 사용해 보고 여러분의 프로젝트에 고려해 볼 수 있습니다. diff --git a/docs/ko/docs/how-to/custom-request-and-route.md b/docs/ko/docs/how-to/custom-request-and-route.md index 45e3cf7..734f770 100644 --- a/docs/ko/docs/how-to/custom-request-and-route.md +++ b/docs/ko/docs/how-to/custom-request-and-route.md @@ -1,6 +1,5 @@ # 커스텀 Request 및 APIRoute 클래스 { #custom-request-and-apiroute-class } - 일부 경우에는 `Request`와 `APIRoute` 클래스에서 사용되는 로직을 오버라이드하고 싶을 수 있습니다. 특히, 이는 middleware에 있는 로직의 좋은 대안이 될 수 있습니다. @@ -67,7 +66,7 @@ 그리고 이 두 가지, `scope`와 `receive`가 새로운 `Request` 인스턴스를 만드는 데 필요한 것들입니다. -`Request`에 대해 더 알아보려면 [Starlette의 Requests 문서](https://www.starlette.dev/requests/)를 확인하세요. +`Request`에 대해 더 알아보려면 [Starlette의 Requests 문서](https://starlette.dev/requests/)를 확인하세요. /// diff --git a/docs/ko/docs/how-to/extending-openapi.md b/docs/ko/docs/how-to/extending-openapi.md index cdfa89d..b3008a3 100644 --- a/docs/ko/docs/how-to/extending-openapi.md +++ b/docs/ko/docs/how-to/extending-openapi.md @@ -45,7 +45,7 @@ 위 정보를 바탕으로, 동일한 유틸리티 함수를 사용해 OpenAPI 스키마를 생성하고 필요한 각 부분을 덮어쓸 수 있습니다. -예를 들어, [커스텀 로고를 포함하기 위한 ReDoc의 OpenAPI 확장](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo)을 추가해 보겠습니다. +예를 들어, [커스텀 로고를 포함하기 위한 ReDoc의 OpenAPI 확장](https://github.com/Redocly/redoc/blob/main/docs/redoc-vendor-extensions.md#x-logo)을 추가해 보겠습니다. ### 일반적인 **FastAPI** { #normal-fastapi } diff --git a/docs/ko/docs/how-to/graphql.md b/docs/ko/docs/how-to/graphql.md index 3e8a2eb..aa71df9 100644 --- a/docs/ko/docs/how-to/graphql.md +++ b/docs/ko/docs/how-to/graphql.md @@ -21,7 +21,7 @@ * [Strawberry](https://strawberry.rocks/) 🍓 * [FastAPI용 문서](https://strawberry.rocks/docs/integrations/fastapi) 제공 * [Ariadne](https://ariadnegraphql.org/) - * [FastAPI용 문서](https://ariadnegraphql.org/docs/fastapi-integration) 제공 + * [FastAPI용 문서](https://ariadnegraphql.org/server/Integrations/fastapi-integration) 제공 * [Tartiflette](https://tartiflette.io/) * ASGI 통합을 제공하기 위해 [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) 사용 * [Graphene](https://graphene-python.org/) diff --git a/docs/ko/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/ko/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index 86394f1..4007209 100644 --- a/docs/ko/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/ko/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -24,7 +24,7 @@ Pydantic v1을 사용하는 오래된 FastAPI 앱이 있다면, 여기서는 이 ## 공식 가이드 { #official-guide } -Pydantic에는 v1에서 v2로의 공식 [마이그레이션 가이드](https://docs.pydantic.dev/latest/migration/)가 있습니다. +Pydantic에는 v1에서 v2로의 공식 [마이그레이션 가이드](https://pydantic.dev/docs/validation/latest/get-started/migration/)가 있습니다. 여기에는 무엇이 바뀌었는지, 검증이 이제 어떻게 더 정확하고 엄격해졌는지, 가능한 주의사항 등도 포함되어 있습니다. diff --git a/docs/ko/docs/index.md b/docs/ko/docs/index.md index f839c82..126b451 100644 --- a/docs/ko/docs/index.md +++ b/docs/ko/docs/index.md @@ -110,7 +110,7 @@ FastAPI는 현대적이고, 빠르며(고성능), 파이썬 표준 타입 힌트
-## FastAPI Conf { #fastapi-conf } - -[**FastAPI Conf '26**](https://fastapiconf.com)은 **2026년 10월 28일**, **네덜란드 암스테르담**에서 열립니다. FastAPI에 관한 모든 것, 바로 출처에서. 🎤 - -FastAPI Conf '26 - October 28, 2026 - Amsterdam, NL - ## FastAPI 미니 다큐멘터리 { #fastapi-mini-documentary } 2025년 말에 공개된 [FastAPI 미니 다큐멘터리](https://www.youtube.com/watch?v=mpR8ngthqiE)가 있습니다. 온라인에서 시청할 수 있습니다: @@ -175,17 +169,17 @@ FastAPI는 현대적이고, 빠르며(고성능), 파이썬 표준 타입 힌트 FastAPI는 거인들의 어깨 위에 서 있습니다: -* [Starlette](https://www.starlette.dev/) — 웹 부분을 담당합니다. -* [Pydantic](https://docs.pydantic.dev/) — 데이터 부분을 담당합니다. +* [Starlette](https://starlette.dev/) — 웹 부분을 담당합니다. +* [Pydantic](https://pydantic.dev/docs/) — 데이터 부분을 담당합니다. ## 설치 { #installation } -[가상 환경](https://fastapi.tiangolo.com/ko/virtual-environments/)을 생성하고 활성화한 다음 FastAPI를 설치하세요: +먼저, [`uv`를 설치](https://docs.astral.sh/uv/getting-started/installation/)한 다음 프로젝트에 FastAPI를 추가하세요:
```console -$ pip install "fastapi[standard]" +$ uv add "fastapi[standard]" ---> 100% ``` @@ -194,6 +188,8 @@ $ pip install "fastapi[standard]" **참고**: 모든 터미널에서 동작하도록 `"fastapi[standard]"`를 따옴표로 감싸 넣었는지 확인하세요. +`pip`를 사용하는 것을 선호한다면, 가상 환경 안에 `fastapi[standard]`를 설치하세요. 대안 단계는 [설치 가이드](tutorial/#install-fastapi)를 참고하세요. + ## 예제 { #example } ### 만들기 { #create-it } @@ -250,7 +246,7 @@ async def read_item(item_id: int, q: str | None = None):
```console -$ fastapi dev +$ uv run fastapi dev ╭────────── FastAPI CLI - Development mode ───────────╮ │ │ @@ -277,7 +273,7 @@ INFO: Application startup complete.
fastapi dev 명령에 관하여... -`fastapi dev` 명령은 여러분의 `main.py` 파일을 자동으로 읽고, 그 안의 **FastAPI** 앱을 감지한 다음, [Uvicorn](https://www.uvicorn.dev)을 사용해 서버를 시작합니다. +`fastapi dev` 명령은 여러분의 `main.py` 파일을 자동으로 읽고, 그 안의 **FastAPI** 앱을 감지한 다음, [Uvicorn](https://uvicorn.dev)을 사용해 서버를 시작합니다. 기본적으로 `fastapi dev`는 로컬 개발을 위해 auto-reload가 활성화된 상태로 시작됩니다. @@ -314,7 +310,7 @@ INFO: Application startup complete. 그리고 이제 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)로 가봅시다. -다른 자동 문서를 볼 수 있습니다([ReDoc](https://github.com/Rebilly/ReDoc) 제공): +다른 자동 문서를 볼 수 있습니다([ReDoc](https://github.com/Redocly/redoc) 제공): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -497,7 +493,7 @@ item: Item
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -540,7 +536,7 @@ FastAPI는 Pydantic과 Starlette에 의존합니다. ### `standard` 의존성 { #standard-dependencies } -`pip install "fastapi[standard]"`로 FastAPI를 설치하면 `standard` 그룹의 선택적 의존성이 함께 설치됩니다. +`uv add "fastapi[standard]"`로 FastAPI를 설치하면 `standard` 그룹의 선택적 의존성이 함께 설치됩니다. Pydantic이 사용하는: @@ -554,17 +550,17 @@ Starlette이 사용하는: FastAPI가 사용하는: -* [`uvicorn`](https://www.uvicorn.dev) - 애플리케이션을 로드하고 제공하는 서버를 위한 것입니다. 여기에는 고성능 서빙에 필요한 일부 의존성(예: `uvloop`)이 포함된 `uvicorn[standard]`가 포함됩니다. +* [`uvicorn`](https://uvicorn.dev) - 애플리케이션을 로드하고 제공하는 서버를 위한 것입니다. 여기에는 고성능 서빙에 필요한 일부 의존성(예: `uvloop`)이 포함된 `uvicorn[standard]`가 포함됩니다. * `fastapi-cli[standard]` - `fastapi` 명령을 제공하기 위한 것입니다. * 여기에는 [FastAPI Cloud](https://fastapicloud.com)에 FastAPI 애플리케이션을 배포할 수 있게 해주는 `fastapi-cloud-cli`가 포함됩니다. ### `standard` 의존성 없이 { #without-standard-dependencies } -`standard` 선택적 의존성을 포함하고 싶지 않다면, `pip install "fastapi[standard]"` 대신 `pip install fastapi`로 설치할 수 있습니다. +`standard` 선택적 의존성을 포함하고 싶지 않다면, `uv add "fastapi[standard]"` 대신 `uv add fastapi`로 설치할 수 있습니다. ### `fastapi-cloud-cli` 없이 { #without-fastapi-cloud-cli } -표준 의존성과 함께 FastAPI를 설치하되 `fastapi-cloud-cli` 없이 설치하고 싶다면, `pip install "fastapi[standard-no-fastapi-cloud-cli]"`로 설치할 수 있습니다. +표준 의존성과 함께 FastAPI를 설치하되 `fastapi-cloud-cli` 없이 설치하고 싶다면, `uv add "fastapi[standard-no-fastapi-cloud-cli]"`로 설치할 수 있습니다. ### 추가 선택적 의존성 { #additional-optional-dependencies } @@ -572,13 +568,13 @@ FastAPI가 사용하는: 추가 선택적 Pydantic 의존성: -* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - 설정 관리를 위한 것입니다. -* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - Pydantic에서 사용할 추가 타입을 위한 것입니다. +* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) - 설정 관리를 위한 것입니다. +* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) - Pydantic에서 사용할 추가 타입을 위한 것입니다. 추가 선택적 FastAPI 의존성: * [`orjson`](https://github.com/ijl/orjson) - `ORJSONResponse`를 사용하려면 필요. -* [`ujson`](https://github.com/esnme/ultrajson) - `UJSONResponse`를 사용하려면 필요. +* [`ujson`](https://github.com/ultrajson/ultrajson) - `UJSONResponse`를 사용하려면 필요. ## 라이센스 { #license } diff --git a/docs/ko/docs/project-generation.md b/docs/ko/docs/project-generation.md index 3a5a9b9..4f7b9f7 100644 --- a/docs/ko/docs/project-generation.md +++ b/docs/ko/docs/project-generation.md @@ -1,24 +1,23 @@ # Full Stack FastAPI 템플릿 { #full-stack-fastapi-template } - 템플릿은 일반적으로 특정 설정과 함께 제공되지만, 유연하고 커스터마이징이 가능하게 디자인 되었습니다. 이 특성들은 여러분이 프로젝트의 요구사항에 맞춰 수정, 적용을 할 수 있게 해주고, 템플릿이 완벽한 시작점이 되게 해줍니다. 🏁 많은 초기 설정, 보안, 데이터베이스 및 일부 API 엔드포인트가 이미 준비되어 있으므로, 여러분은 이 템플릿을 시작하는 데 사용할 수 있습니다. -GitHub 저장소: [Full Stack FastAPI 템플릿](https://github.com/tiangolo/full-stack-fastapi-template) +GitHub 저장소: [Full Stack FastAPI 템플릿](https://github.com/fastapi/full-stack-fastapi-template) ## Full Stack FastAPI 템플릿 - 기술 스택과 기능들 { #full-stack-fastapi-template-technology-stack-and-features } - ⚡ Python 백엔드 API를 위한 [**FastAPI**](https://fastapi.tiangolo.com/ko). - - 🧰 Python SQL 데이터베이스 상호작용을 위한 [SQLModel](https://sqlmodel.tiangolo.com) (ORM). - - 🔍 FastAPI에 의해 사용되는, 데이터 검증과 설정 관리를 위한 [Pydantic](https://docs.pydantic.dev). - - 💾 SQL 데이터베이스로서의 [PostgreSQL](https://www.postgresql.org). + - 🧰 Python SQL 데이터베이스 상호작용을 위한 [SQLModel](https://sqlmodel.tiangolo.com) (ORM). + - 🔍 FastAPI에 의해 사용되는, 데이터 검증과 설정 관리를 위한 [Pydantic](https://pydantic.dev/docs/). + - 💾 SQL 데이터베이스로서의 [PostgreSQL](https://www.postgresql.org). - 🚀 프론트엔드를 위한 [React](https://react.dev). - - 💃 TypeScript, hooks, Vite 및 기타 현대적인 프론트엔드 스택을 사용. - - 🎨 프론트엔드 컴포넌트를 위한 [Tailwind CSS](https://tailwindcss.com) 및 [shadcn/ui](https://ui.shadcn.com). - - 🤖 자동으로 생성된 프론트엔드 클라이언트. - - 🧪 End-to-End 테스트를 위한 [Playwright](https://playwright.dev). - - 🦇 다크 모드 지원. + - 💃 TypeScript, hooks, Vite 및 기타 현대적인 프론트엔드 스택을 사용. + - 🎨 프론트엔드 컴포넌트를 위한 [Tailwind CSS](https://tailwindcss.com) 및 [shadcn/ui](https://ui.shadcn.com). + - 🤖 자동으로 생성된 프론트엔드 클라이언트. + - 🧪 End-to-End 테스트를 위한 [Playwright](https://playwright.dev). + - 🦇 다크 모드 지원. - 🐋 개발 환경과 프로덕션(운영)을 위한 [Docker Compose](https://www.docker.com). - 🔒 기본으로 지원되는 안전한 비밀번호 해싱. - 🔑 JWT (JSON Web Token) 인증. diff --git a/docs/ko/docs/python-types.md b/docs/ko/docs/python-types.md index a0216cd..7efd38e 100644 --- a/docs/ko/docs/python-types.md +++ b/docs/ko/docs/python-types.md @@ -271,7 +271,7 @@ def some_function(data: Any): ## Pydantic 모델 { #pydantic-models } -[Pydantic](https://docs.pydantic.dev/)은 데이터 검증을 수행하는 파이썬 라이브러리입니다. +[Pydantic](https://pydantic.dev/docs/)은 데이터 검증을 수행하는 파이썬 라이브러리입니다. 속성을 가진 클래스 형태로 데이터의 "모양(shape)"을 선언합니다. @@ -287,7 +287,7 @@ Pydantic 공식 문서의 예시: /// note | 참고 -더 알아보려면 [Pydantic 문서를 확인하세요](https://docs.pydantic.dev/). +더 알아보려면 [Pydantic 문서를 확인하세요](https://pydantic.dev/docs/). /// diff --git a/docs/ko/docs/tutorial/background-tasks.md b/docs/ko/docs/tutorial/background-tasks.md index 1f04282..d664afb 100644 --- a/docs/ko/docs/tutorial/background-tasks.md +++ b/docs/ko/docs/tutorial/background-tasks.md @@ -1,6 +1,6 @@ # 백그라운드 작업 { #background-tasks } -FastAPI에서는 응답을 반환한 *후에* 실행할 백그라운드 작업을 정의할 수 있습니다. +응답을 반환한 *후에* 실행할 백그라운드 작업을 정의할 수 있습니다. 백그라운드 작업은 요청 후에 발생해야 하지만, 클라이언트가 응답을 받기 전에 작업이 완료될 때까지 기다릴 필요가 없는 작업에 유용합니다. @@ -63,7 +63,7 @@ FastAPI에서는 응답을 반환한 *후에* 실행할 백그라운드 작업 ## 기술적 세부사항 { #technical-details } -`BackgroundTasks` 클래스는 [`starlette.background`](https://www.starlette.dev/background/)에서 직접 가져옵니다. +`BackgroundTasks` 클래스는 [`starlette.background`](https://starlette.dev/background/)에서 직접 가져옵니다. FastAPI에 직접 임포트/포함되어 있으므로 `fastapi`에서 임포트할 수 있고, 실수로 `starlette.background`에서 대안인 `BackgroundTask`(끝에 `s`가 없음)를 임포트하는 것을 피할 수 있습니다. @@ -71,7 +71,7 @@ FastAPI에 직접 임포트/포함되어 있으므로 `fastapi`에서 임포트 FastAPI에서 `BackgroundTask`만 단독으로 사용하는 것도 가능하지만, 코드에서 객체를 생성하고 이를 포함하는 Starlette `Response`를 반환해야 합니다. -더 자세한 내용은 [Starlette의 Background Tasks 공식 문서](https://www.starlette.dev/background/)에서 확인할 수 있습니다. +더 자세한 내용은 [Starlette의 Background Tasks 공식 문서](https://starlette.dev/background/)에서 확인할 수 있습니다. ## 주의사항 { #caveat } diff --git a/docs/ko/docs/tutorial/bigger-applications.md b/docs/ko/docs/tutorial/bigger-applications.md index bb3637f..52ca3f9 100644 --- a/docs/ko/docs/tutorial/bigger-applications.md +++ b/docs/ko/docs/tutorial/bigger-applications.md @@ -58,17 +58,17 @@ from app.routers import items ```bash . -├── app # 'app'은 Python 패키지입니다 -│   ├── __init__.py # 이 파일로 'app'이 'Python 패키지'가 됩니다 -│   ├── main.py # 'main' 모듈, 예: import app.main -│   ├── dependencies.py # 'dependencies' 모듈, 예: import app.dependencies -│   └── routers # 'routers'는 'Python 하위 패키지'입니다 -│   │ ├── __init__.py # 이 파일로 'routers'가 'Python 하위 패키지'가 됩니다 -│   │ ├── items.py # 'items' 서브모듈, 예: import app.routers.items -│   │ └── users.py # 'users' 서브모듈, 예: import app.routers.users -│   └── internal # 'internal'은 'Python 하위 패키지'입니다 -│   ├── __init__.py # 이 파일로 'internal'이 'Python 하위 패키지'가 됩니다 -│   └── admin.py # 'admin' 서브모듈, 예: import app.internal.admin +├── app # "app"은 Python 패키지입니다 +│   ├── __init__.py # 이 파일로 "app"이 "Python 패키지"가 됩니다 +│   ├── main.py # "main" 모듈, 예: import app.main +│   ├── dependencies.py # "dependencies" 모듈, 예: import app.dependencies +│   └── routers # "routers"는 "Python 하위 패키지"입니다 +│   │ ├── __init__.py # 이 파일로 "routers"가 "Python 하위 패키지"가 됩니다 +│   │ ├── items.py # "items" 서브모듈, 예: import app.routers.items +│   │ └── users.py # "users" 서브모듈, 예: import app.routers.users +│   └── internal # "internal"은 "Python 하위 패키지"입니다 +│   ├── __init__.py # 이 파일로 "internal"이 "Python 하위 패키지"가 됩니다 +│   └── admin.py # "admin" 서브모듈, 예: import app.internal.admin ``` ## `APIRouter` { #apirouter } @@ -487,7 +487,7 @@ from app.main import app 명령어에 경로를 직접 전달할 수도 있습니다: ```console -$ fastapi dev app/main.py +$ uv run fastapi dev app/main.py ``` 하지만 `fastapi` 명령어를 실행할 때마다 올바른 경로를 기억해 전달해야 합니다. @@ -503,7 +503,7 @@ $ fastapi dev app/main.py
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/ko/docs/tutorial/body-nested-models.md b/docs/ko/docs/tutorial/body-nested-models.md index 7ca6305..0f59b4a 100644 --- a/docs/ko/docs/tutorial/body-nested-models.md +++ b/docs/ko/docs/tutorial/body-nested-models.md @@ -96,7 +96,7 @@ Pydantic 모델의 각 어트리뷰트는 타입을 갖습니다. `str`, `int`, `float` 등과 같은 일반적인 단일 타입과는 별개로, `str`을 상속하는 더 복잡한 단일 타입을 사용할 수 있습니다. -사용할 수 있는 모든 옵션을 보려면 [Pydantic의 Type Overview](https://docs.pydantic.dev/latest/concepts/types/)를 확인하세요. 다음 장에서 몇 가지 예제를 볼 수 있습니다. +사용할 수 있는 모든 옵션을 보려면 [Pydantic의 Type Overview](https://pydantic.dev/docs/validation/latest/concepts/types/)를 확인하세요. 다음 장에서 몇 가지 예제를 볼 수 있습니다. 예를 들어 `Image` 모델에는 `url` 필드가 있으므로, 이를 `str` 대신 Pydantic의 `HttpUrl` 인스턴스로 선언할 수 있습니다: diff --git a/docs/ko/docs/tutorial/body.md b/docs/ko/docs/tutorial/body.md index dde0708..f268c94 100644 --- a/docs/ko/docs/tutorial/body.md +++ b/docs/ko/docs/tutorial/body.md @@ -6,7 +6,7 @@ 여러분의 API는 대부분의 경우 **응답** 본문을 보내야 합니다. 하지만 클라이언트는 항상 **요청 본문**을 보낼 필요는 없고, 때로는 (쿼리 매개변수와 함께) 어떤 경로만 요청하고 본문은 보내지 않을 수도 있습니다. -**요청** 본문을 선언하기 위해서 모든 강력함과 이점을 갖춘 [Pydantic](https://docs.pydantic.dev/) 모델을 사용합니다. +**요청** 본문을 선언하기 위해서 모든 강력함과 이점을 갖춘 [Pydantic](https://pydantic.dev/docs/) 모델을 사용합니다. /// note | 참고 diff --git a/docs/ko/docs/tutorial/debugging.md b/docs/ko/docs/tutorial/debugging.md index c3d06c0..4031932 100644 --- a/docs/ko/docs/tutorial/debugging.md +++ b/docs/ko/docs/tutorial/debugging.md @@ -15,7 +15,7 @@ FastAPI 애플리케이션에서 `uvicorn`을 직접 임포트하여 실행합
```console -$ python myapp.py +$ uv run python myapp.py ```
@@ -35,7 +35,7 @@ from myapp import app
```console -$ python myapp.py +$ uv run python myapp.py ```
diff --git a/docs/ko/docs/tutorial/extra-data-types.md b/docs/ko/docs/tutorial/extra-data-types.md index 6583cd6..39cc8a8 100644 --- a/docs/ko/docs/tutorial/extra-data-types.md +++ b/docs/ko/docs/tutorial/extra-data-types.md @@ -1,6 +1,5 @@ # 추가 데이터 자료형 { #extra-data-types } - 지금까지 일반적인 데이터 자료형을 사용했습니다. 예를 들면 다음과 같습니다: * `int` @@ -37,7 +36,7 @@ * `datetime.timedelta`: * 파이썬의 `datetime.timedelta`. * 요청과 응답에서 전체 초(seconds)의 `float`로 표현됩니다. - * Pydantic은 "ISO 8601 time diff encoding"으로 표현하는 것 또한 허용합니다. [더 많은 정보는 문서를 확인하세요](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers). + * Pydantic은 "ISO 8601 time diff encoding"으로 표현하는 것 또한 허용합니다. [더 많은 정보는 문서를 확인하세요](https://pydantic.dev/docs/validation/latest/concepts/serialization/#custom-serializers). * `frozenset`: * 요청과 응답에서 `set`와 동일하게 취급됩니다: * 요청 시, 리스트를 읽어 중복을 제거하고 `set`로 변환합니다. @@ -50,7 +49,7 @@ * `Decimal`: * 표준 파이썬의 `Decimal`. * 요청과 응답에서 `float`와 동일하게 다뤄집니다. -* 여기에서 모든 유효한 Pydantic 데이터 자료형을 확인할 수 있습니다: [Pydantic 데이터 자료형](https://docs.pydantic.dev/latest/usage/types/types/). +* 여기에서 모든 유효한 Pydantic 데이터 자료형을 확인할 수 있습니다: [Pydantic 데이터 자료형](https://pydantic.dev/docs/validation/latest/concepts/types/). ## 예시 { #example } diff --git a/docs/ko/docs/tutorial/extra-models.md b/docs/ko/docs/tutorial/extra-models.md index c33abc1..abfb581 100644 --- a/docs/ko/docs/tutorial/extra-models.md +++ b/docs/ko/docs/tutorial/extra-models.md @@ -166,7 +166,7 @@ OpenAPI에서는 이를 `anyOf`로 정의합니다. /// note | 참고 -[`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions)을 정의할 때는 더 구체적인 타입을 먼저 포함하고, 덜 구체적인 타입을 그 뒤에 나열해야 합니다. 아래 예제에서는 `Union[PlaneItem, CarItem]`에서 더 구체적인 `PlaneItem`이 `CarItem`보다 앞에 위치합니다. +[`Union`](https://pydantic.dev/docs/validation/latest/concepts/unions/)을 정의할 때는 더 구체적인 타입을 먼저 포함하고, 덜 구체적인 타입을 그 뒤에 나열해야 합니다. 아래 예제에서는 `Union[PlaneItem, CarItem]`에서 더 구체적인 `PlaneItem`이 `CarItem`보다 앞에 위치합니다. /// diff --git a/docs/ko/docs/tutorial/first-steps.md b/docs/ko/docs/tutorial/first-steps.md index 7aca4a1..bd8b88e 100644 --- a/docs/ko/docs/tutorial/first-steps.md +++ b/docs/ko/docs/tutorial/first-steps.md @@ -6,12 +6,18 @@ 위 코드를 `main.py`에 복사합니다. +/// tip | 팁 + +FastAPI에는 VS Code(및 Cursor)를 위한 [공식 확장](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode)이 있으며, 에디터에서 바로 경로 처리 탐색기, 경로 처리 검색, 테스트에서의 CodeLens 탐색(테스트에서 정의로 이동), FastAPI Cloud 배포와 로그를 포함한 많은 기능을 제공합니다. + +/// + 라이브 서버를 실행합니다:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -78,7 +84,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) 그리고 이제, [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)로 가봅니다. -대안 자동 문서를 볼 수 있습니다 ([ReDoc](https://github.com/Rebilly/ReDoc) 제공): +대안 자동 문서를 볼 수 있습니다 ([ReDoc](https://github.com/Redocly/redoc) 제공): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -185,13 +191,13 @@ from backend.main import app `fastapi dev` 명령어에 파일 경로를 전달할 수도 있으며, 그러면 사용할 FastAPI 애플리케이션 객체를 추정합니다: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` 또는 `fastapi dev` 명령어에 `--entrypoint` 옵션을 전달할 수도 있습니다: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` 하지만 매번 `fastapi` 명령어를 호출할 때마다 올바른 path\entrypoint를 전달해야 합니다. @@ -205,7 +211,7 @@ $ fastapi dev --entrypoint main:app
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -232,7 +238,7 @@ CLI가 여러분의 FastAPI 애플리케이션을 자동으로 감지하고 클 `FastAPI`는 `Starlette`를 직접 상속하는 클래스입니다. -`FastAPI`로 [Starlette](https://www.starlette.dev/)의 모든 기능을 사용할 수 있습니다. +`FastAPI`로 [Starlette](https://starlette.dev/)의 모든 기능을 사용할 수 있습니다. /// diff --git a/docs/ko/docs/tutorial/frontend.md b/docs/ko/docs/tutorial/frontend.md index 452aed0..b163621 100644 --- a/docs/ko/docs/tutorial/frontend.md +++ b/docs/ko/docs/tutorial/frontend.md @@ -52,7 +52,7 @@ npm run build {* ../../docs_src/frontend/tutorial002_py310.py hl[5] *} -**FastAPI**는 브라우저 탐색처럼 보이는 `GET` 및 `HEAD` 요청에만 이 fallback을 사용합니다. JavaScript, CSS, 이미지처럼 누락된 파일은 여전히 `404`를 반환합니다. +**FastAPI**는 브라우저 탐색 요청이 보통 그러하듯 `Accept: text/html` 또는 `Accept: application/xhtml+xml`로 HTML을 명시적으로 허용하는 `GET` 및 `HEAD` 요청에만 이 fallback을 사용합니다. JavaScript, CSS, 이미지처럼 누락된 파일은 여전히 `404`를 반환합니다. `POST`나 `PUT` 같은 다른 메서드의 요청이 프론트엔드 fallback에만 매칭되는 경로로 들어와도 `404`를 반환합니다. 일반 **FastAPI** *경로 처리*는 여전히 프론트엔드 라우트보다 높은 우선순위를 가집니다. @@ -106,9 +106,13 @@ npm run build ## 디렉터리 확인하기 { #check-directory } -기본적으로 `app.frontend()`는 애플리케이션이 생성될 때 디렉터리가 존재하는지 확인합니다. +기본적으로 `app.frontend()`는 `check_dir="auto"`를 사용합니다. -이는 설정 오류를 일찍 발견하는 데 도움이 됩니다. 예를 들어 프론트엔드 빌드 출력 디렉터리가 없다면 **FastAPI**는 시작 시 오류를 발생시킵니다. +`FASTAPI_ENV` 환경 변수가 `development`로 설정되어 있으면, 프론트엔드 빌드 출력 디렉터리가 없을 때 **FastAPI**는 경고만 표시합니다. [`fastapi dev` 명령어](https://github.com/fastapi/fastapi-cli#fastapi-dev)는 이 환경 변수가 아직 설정되어 있지 않다면 대신 설정해 줍니다. 이를 통해 개발 중에 프론트엔드를 빌드하거나 시작하기 전에 백엔드를 시작할 수 있습니다. + +다른 모든 환경에서는 애플리케이션이 생성될 때 **FastAPI**가 오류를 발생시킵니다. 이는 프론트엔드 파일 없이 애플리케이션을 배포하기 전에 설정 오류를 일찍 발견하는 데 도움이 됩니다. + +애플리케이션이 생성될 때 항상 디렉터리를 확인하도록 `check_dir=True`를 설정할 수도 있습니다. 프론트엔드 파일이 나중에 생성된다면, 예를 들어 애플리케이션 객체가 생성된 후 별도의 빌드 단계에서 생성된다면, `check_dir=False`를 설정합니다: @@ -132,6 +136,8 @@ npm run build 애플리케이션, `APIRouter`, `include_router()`의 의존성도 프론트엔드 응답에 적용됩니다. 이는 쿠키 인증 등으로 프론트엔드를 보호하는 데 유용할 수 있습니다. +의존성은 일반 *경로 처리*에서처럼 응답 헤더를 수정하고 백그라운드 작업을 추가할 수도 있습니다. + ## 정적 빌드 출력만 사용하기 { #static-build-output-only } `app.frontend()`는 프론트엔드 빌드에서 이미 생성된 파일을 제공합니다. diff --git a/docs/ko/docs/tutorial/handling-errors.md b/docs/ko/docs/tutorial/handling-errors.md index 94c4c94..75744c7 100644 --- a/docs/ko/docs/tutorial/handling-errors.md +++ b/docs/ko/docs/tutorial/handling-errors.md @@ -82,7 +82,7 @@ HTTP 오류에 커스텀 헤더를 추가할 수 있으면 유용한 상황이 ## 커스텀 예외 핸들러 설치하기 { #install-custom-exception-handlers } -[Starlette의 동일한 예외 유틸리티](https://www.starlette.dev/exceptions/)를 사용해 커스텀 예외 핸들러를 추가할 수 있습니다. +[Starlette의 동일한 예외 유틸리티](https://starlette.dev/exceptions/)를 사용해 커스텀 예외 핸들러를 추가할 수 있습니다. 여러분(또는 사용하는 라이브러리)이 `raise`할 수 있는 커스텀 예외 `UnicornException`이 있다고 가정해 봅시다. diff --git a/docs/ko/docs/tutorial/index.md b/docs/ko/docs/tutorial/index.md index c4303ed..e284491 100644 --- a/docs/ko/docs/tutorial/index.md +++ b/docs/ko/docs/tutorial/index.md @@ -1,6 +1,5 @@ # 자습서 - 사용자 안내서 { #tutorial-user-guide } - 이 자습서는 **FastAPI**의 대부분의 기능을 단계별로 사용하는 방법을 보여줍니다. 각 섹션은 이전 섹션을 바탕으로 점진적으로 구성되지만, 주제를 분리한 구조로 되어 있어 특정 API 요구사항을 해결하기 위해 원하는 섹션으로 바로 이동할 수 있습니다. @@ -11,12 +10,12 @@ 모든 코드 블록은 복사해서 바로 사용할 수 있습니다(실제로 테스트된 Python 파일입니다). -예제 중 어떤 것이든 실행하려면, 코드를 `main.py` 파일에 복사하고 다음으로 `fastapi dev`를 시작하세요: +예제 중 어떤 것이든 실행하려면, 코드를 `main.py` 파일에 복사하고 `uv run`으로 `fastapi dev`를 시작하세요:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -61,35 +60,75 @@ $ fastapi dev ## FastAPI 설치 { #install-fastapi } -첫 단계는 FastAPI를 설치하는 것입니다. +첫 단계는 프로젝트를 설정하고 FastAPI를 추가하는 것입니다. -[가상 환경](../virtual-environments.md)을 생성하고 활성화한 다음, **FastAPI를 설치**하세요: +[`uv`](https://docs.astral.sh/uv/getting-started/installation/)를 설치한 다음, 프로젝트를 생성하고 FastAPI를 추가하세요:
```console -$ pip install "fastapi[standard]" +$ uv init awesome-project --bare +$ cd awesome-project +$ uv add "fastapi[standard]" ---> 100% ```
+`uv add`는 프로젝트의 가상 환경을 `.venv`에 생성하고, FastAPI를 `pyproject.toml`에 추가하며, 나중에 동일한 패키지 버전을 설치할 수 있도록 `uv.lock`을 생성합니다. + +/// details | 이 명령어들이 하는 일 + +* `uv init`: 새 Python 프로젝트를 생성합니다. +* `awesome-project`: 이 이름의 새 디렉터리에 프로젝트를 생성합니다. +* `--bare`: 샘플 `main.py`, `README.md` 또는 다른 파일을 생성하지 않고, 최소한의 `pyproject.toml` 파일만 생성합니다. 이 자습서의 다음 단계에서 애플리케이션 파일을 직접 생성하게 됩니다. + +그런 다음 `cd awesome-project`는 FastAPI를 추가하기 전에 새 프로젝트 디렉터리로 들어갑니다. + +`uv`는 시스템에 이미 설치된 호환되는 Python 버전을 사용하거나, 필요한 경우 다운로드합니다. + +`uv add`를 실행하면 FastAPI와 FastAPI가 의존하는 모든 패키지의 호환되는 버전을 선택합니다. 정확한 버전을 `uv.lock`에 기록하여, 나중에 다른 컴퓨터에서나 애플리케이션을 배포할 때 동일한 패키지 버전을 설치할 수 있게 합니다. + +이 파일을 생성하거나 업데이트하는 것을 프로젝트 의존성 [**locking**](https://docs.astral.sh/uv/concepts/projects/sync/)이라고 합니다. `uv`는 패키지를 추가할 때 이 작업을 자동으로 수행합니다. + +/// + +/// details | FastAPI 설치 옵션 + +`uv add "fastapi[standard]"`로 설치하면 `fastapi-cloud-cli`를 포함한 몇 가지 기본 선택적 standard 의존성이 함께 설치되며, 이를 사용해 [FastAPI Cloud](https://fastapicloud.com)에 배포할 수 있습니다. + +이러한 선택적 의존성이 필요 없다면 `uv add fastapi`로 대신 설치할 수 있습니다. + +standard 의존성은 설치하되 `fastapi-cloud-cli` 없이 설치하려면 `uv add "fastapi[standard-no-fastapi-cloud-cli]"`로 설치할 수 있습니다. + +/// + +/// details | 대신 `pip` 사용하기 + +가상 환경과 패키지를 수동으로 관리하는 것을 선호한다면, 가상 환경을 생성하고 활성화한 다음 `pip install "fastapi[standard]"`로 FastAPI를 설치하세요. + +자세한 단계는 [가상 환경 안내서](https://tiangolo.com/guides/virtual-environments/)를 읽어보세요. + +/// + +## AI Agent Skills { #ai-agent-skills } + +FastAPI에는 AI coding agent를 위한 공식 skill이 포함되어 있습니다. 패키지에 함께 포함되어 있으므로, 그 안내는 프로젝트에 설치된 FastAPI 버전과 계속 일치하며 FastAPI를 업데이트할 때 함께 업데이트됩니다. + +프로젝트에 FastAPI를 설치한 뒤에는 Library Skills로 skill을 설치할 수 있습니다: + +```bash +uvx library-skills +``` + /// note | 참고 -`pip install "fastapi[standard]"`로 설치하면 `fastapi-cloud-cli`를 포함한 몇 가지 기본 선택적 standard 의존성이 함께 설치되며, 이를 사용해 [FastAPI Cloud](https://fastapicloud.com)에 배포할 수 있습니다. - -이러한 선택적 의존성이 필요 없다면 `pip install fastapi`로 대신 설치할 수 있습니다. - -standard 의존성은 설치하되 `fastapi-cloud-cli` 없이 설치하려면 `pip install "fastapi[standard-no-fastapi-cloud-cli]"`로 설치할 수 있습니다. +`uvx`는 `uv tool run`의 alias입니다. Library Skills가 프로젝트에 설치된 패키지를 스캔하는 동안, 임시로 격리된 환경에서 Library Skills를 실행합니다. /// -/// tip | 팁 - -FastAPI는 VS Code(및 Cursor)용 [공식 확장 프로그램](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode)이 있습니다. 경로 처리 탐색기, 경로 처리 검색, 테스트에서의 CodeLens 탐색(테스트에서 정의로 바로 이동), FastAPI Cloud 배포와 로그 등 많은 기능을 에디터에서 바로 제공합니다. - -/// +이 skill은 Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Pi, OpenCode 및 대부분의 다른 coding agent와 호환됩니다. Claude Code의 경우 skill을 설치할 위치를 묻는 메시지가 표시되면 `.claude/skills`를 선택하세요. ## 고급 사용자 안내서 { #advanced-user-guide } diff --git a/docs/ko/docs/tutorial/middleware.md b/docs/ko/docs/tutorial/middleware.md index b459f64..c549b3f 100644 --- a/docs/ko/docs/tutorial/middleware.md +++ b/docs/ko/docs/tutorial/middleware.md @@ -37,7 +37,7 @@ 사용자 정의 독점 헤더는 [`X-` 접두사를 사용](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)하여 추가할 수 있다는 점을 기억하세요. -하지만 브라우저에서 클라이언트가 볼 수 있게 하려는 사용자 정의 헤더가 있다면, [CORS (Cross-Origin Resource Sharing)](cors.md) 설정에 [Starlette의 CORS 문서](https://www.starlette.dev/middleware/#corsmiddleware)에 문서화된 `expose_headers` 매개변수를 사용해 추가해야 합니다. +하지만 브라우저에서 클라이언트가 볼 수 있게 하려는 사용자 정의 헤더가 있다면, [CORS (Cross-Origin Resource Sharing)](cors.md) 설정에 [Starlette의 CORS 문서](https://starlette.dev/middleware/#corsmiddleware)에 문서화된 `expose_headers` 매개변수를 사용해 추가해야 합니다. /// diff --git a/docs/ko/docs/tutorial/path-params.md b/docs/ko/docs/tutorial/path-params.md index 0f1c8ee..34475a3 100644 --- a/docs/ko/docs/tutorial/path-params.md +++ b/docs/ko/docs/tutorial/path-params.md @@ -92,7 +92,7 @@ ## 표준 기반의 이점, 대체 문서 { #standards-based-benefits-alternative-documentation } -그리고 생성된 스키마는 [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md) 표준에서 나온 것이기 때문에 호환되는 도구가 많이 있습니다. +그리고 생성된 스키마는 [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) 표준에서 나온 것이기 때문에 호환되는 도구가 많이 있습니다. 이 덕분에 **FastAPI** 자체에서 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)로 접속할 수 있는 (ReDoc을 사용하는) 대체 API 문서를 제공합니다: @@ -102,7 +102,7 @@ ## Pydantic { #pydantic } -모든 데이터 검증은 [Pydantic](https://docs.pydantic.dev/)에 의해 내부적으로 수행되므로 이로 인한 이점을 모두 얻을 수 있습니다. 여러분은 관리를 잘 받고 있음을 느낄 수 있습니다. +모든 데이터 검증은 [Pydantic](https://pydantic.dev/docs/)에 의해 내부적으로 수행되므로 이로 인한 이점을 모두 얻을 수 있습니다. 여러분은 관리를 잘 받고 있음을 느낄 수 있습니다. `str`, `float`, `bool`, 그리고 다른 여러 복잡한 데이터 타입 선언을 할 수 있습니다. diff --git a/docs/ko/docs/tutorial/query-params-str-validations.md b/docs/ko/docs/tutorial/query-params-str-validations.md index 3c55cac..1e40b2e 100644 --- a/docs/ko/docs/tutorial/query-params-str-validations.md +++ b/docs/ko/docs/tutorial/query-params-str-validations.md @@ -370,11 +370,11 @@ http://127.0.0.1:8000/items/?item-query=foobaritems 그런 경우에는 일반적인 검증(예: 값이 `str`인지 검증한 뒤) 이후에 적용되는 **커스텀 검증 함수**를 사용할 수 있습니다. -`Annotated` 안에서 [Pydantic의 `AfterValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator)를 사용하면 이를 구현할 수 있습니다. +`Annotated` 안에서 [Pydantic의 `AfterValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-after-validator)를 사용하면 이를 구현할 수 있습니다. /// tip | 팁 -Pydantic에는 [BeforeValidator](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator)와 같은 다른 것들도 있습니다. 🤓 +Pydantic에는 [`BeforeValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-before-validator)와 같은 다른 것들도 있습니다. 🤓 /// diff --git a/docs/ko/docs/tutorial/request-files.md b/docs/ko/docs/tutorial/request-files.md index b190a51..21001d9 100644 --- a/docs/ko/docs/tutorial/request-files.md +++ b/docs/ko/docs/tutorial/request-files.md @@ -6,10 +6,10 @@ 업로드된 파일을 전달받기 위해 먼저 [`python-multipart`](https://github.com/Kludex/python-multipart)를 설치해야합니다. -[가상 환경](../virtual-environments.md)을 생성하고, 활성화한 다음, 예를 들어 다음과 같이 설치하세요: +프로젝트에 추가하세요: ```console -$ pip install python-multipart +$ uv add python-multipart ``` 업로드된 파일들은 "폼 데이터"의 형태로 전송되기 때문에 이 작업이 필요합니다. diff --git a/docs/ko/docs/tutorial/request-form-models.md b/docs/ko/docs/tutorial/request-form-models.md index 351067d..87c867b 100644 --- a/docs/ko/docs/tutorial/request-form-models.md +++ b/docs/ko/docs/tutorial/request-form-models.md @@ -6,10 +6,10 @@ FastAPI에서 **Pydantic 모델**을 이용하여 **폼 필드**를 선언할 폼을 사용하려면, 먼저 [`python-multipart`](https://github.com/Kludex/python-multipart)를 설치하세요. -[가상 환경](../virtual-environments.md)을 생성하고 활성화한 다음, 예를 들어 아래와 같이 설치하세요: +프로젝트에 추가하세요: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/ko/docs/tutorial/request-forms-and-files.md b/docs/ko/docs/tutorial/request-forms-and-files.md index 644bd0c..786e514 100644 --- a/docs/ko/docs/tutorial/request-forms-and-files.md +++ b/docs/ko/docs/tutorial/request-forms-and-files.md @@ -2,14 +2,14 @@ `File` 과 `Form` 을 사용하여 파일과 폼 필드를 동시에 정의할 수 있습니다. -/// note +/// note | 참고 업로드된 파일 및/또는 폼 데이터를 받으려면 먼저 [`python-multipart`](https://github.com/Kludex/python-multipart)를 설치해야 합니다. -[가상 환경](../virtual-environments.md)을 생성하고, 활성화한 다음 설치해야 합니다. 예: +프로젝트에 추가하세요: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// @@ -28,7 +28,7 @@ $ pip install python-multipart 또한 일부 파일은 `bytes`로, 일부 파일은 `UploadFile`로 선언할 수 있습니다. -/// warning +/// warning | 경고 다수의 `File`과 `Form` 매개변수를 한 *경로 처리*에 선언하는 것이 가능하지만, 요청의 본문이 `application/json`가 아닌 `multipart/form-data`로 인코딩되기 때문에 JSON으로 받기를 기대하는 `Body` 필드를 함께 선언할 수는 없습니다. diff --git a/docs/ko/docs/tutorial/request-forms.md b/docs/ko/docs/tutorial/request-forms.md index 4f678ba..342554c 100644 --- a/docs/ko/docs/tutorial/request-forms.md +++ b/docs/ko/docs/tutorial/request-forms.md @@ -7,10 +7,10 @@ JSON 대신 폼 필드를 받아야 하는 경우 `Form`을 사용할 수 있습 폼을 사용하려면, 먼저 [`python-multipart`](https://github.com/Kludex/python-multipart)를 설치하세요. -[가상 환경](../virtual-environments.md)을 생성하고 활성화한 다음, 예를 들어 다음과 같이 설치하세요: +프로젝트에 추가하세요: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/ko/docs/tutorial/response-model.md b/docs/ko/docs/tutorial/response-model.md index bdd8cec..49de5b7 100644 --- a/docs/ko/docs/tutorial/response-model.md +++ b/docs/ko/docs/tutorial/response-model.md @@ -76,16 +76,16 @@ FastAPI는 이 `response_model`을 사용해 데이터 문서화, 검증 등을 `EmailStr`을 사용하려면 먼저 [`email-validator`](https://github.com/JoshData/python-email-validator)를 설치하세요. -[가상 환경](../virtual-environments.md)을 생성하고, 활성화한 다음 설치해야 합니다. 예를 들어: +프로젝트에 추가하세요: ```console -$ pip install email-validator +$ uv add email-validator ``` 또는 다음과 같이: ```console -$ pip install "pydantic[email]" +$ uv add "pydantic[email]" ``` /// @@ -258,7 +258,7 @@ FastAPI는 Pydantic을 내부적으로 여러 방식으로 사용하여, 클래 * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -`exclude_defaults` 및 `exclude_none`에 대해 [Pydantic 문서](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict)에 설명된 대로 사용할 수 있습니다. +`exclude_defaults` 및 `exclude_none`에 대해 [Pydantic 문서](https://pydantic.dev/docs/validation/latest/concepts/serialization/#excluding-and-including-fields-based-on-their-value)에 설명된 대로 사용할 수 있습니다. /// diff --git a/docs/ko/docs/tutorial/schema-extra-example.md b/docs/ko/docs/tutorial/schema-extra-example.md index 039bee0..e270b2f 100644 --- a/docs/ko/docs/tutorial/schema-extra-example.md +++ b/docs/ko/docs/tutorial/schema-extra-example.md @@ -12,7 +12,7 @@ 추가 정보는 있는 그대로 해당 모델의 **JSON 스키마** 결과에 추가되고, API 문서에서 사용합니다. -[Pydantic 문서: Configuration](https://docs.pydantic.dev/latest/api/config/)에 설명된 것처럼 `dict`를 받는 `model_config` 어트리뷰트를 사용할 수 있습니다. +[Pydantic 문서: Configuration](https://pydantic.dev/docs/validation/latest/api/pydantic/config/)에 설명된 것처럼 `dict`를 받는 `model_config` 어트리뷰트를 사용할 수 있습니다. `"json_schema_extra"`를 생성된 JSON 스키마에서 보여주고 싶은 별도의 데이터와 `examples`를 포함하는 `dict`으로 설정할 수 있습니다. diff --git a/docs/ko/docs/tutorial/security/first-steps.md b/docs/ko/docs/tutorial/security/first-steps.md index d805096..0215e18 100644 --- a/docs/ko/docs/tutorial/security/first-steps.md +++ b/docs/ko/docs/tutorial/security/first-steps.md @@ -27,14 +27,14 @@ /// note | 참고 -[`python-multipart`](https://github.com/Kludex/python-multipart) 패키지는 `pip install "fastapi[standard]"` 명령을 실행하면 **FastAPI**와 함께 자동으로 설치됩니다. +[`python-multipart`](https://github.com/Kludex/python-multipart) 패키지는 `uv add "fastapi[standard]"` 명령을 실행하면 **FastAPI**와 함께 자동으로 설치됩니다. -하지만 `pip install fastapi` 명령을 사용하면 `python-multipart` 패키지가 기본으로 포함되지 않습니다. +하지만 `uv add fastapi` 명령을 사용하면 `python-multipart` 패키지가 기본으로 포함되지 않습니다. -수동으로 설치하려면, [가상 환경](../../virtual-environments.md)을 만들고 활성화한 다음, 아래로 설치하세요: +수동으로 설치하려면, 프로젝트에 아래로 추가하세요: ```console -$ pip install python-multipart +$ uv add python-multipart ``` 이는 **OAuth2**가 `username`과 `password`를 보내기 위해 "form data"를 사용하기 때문입니다. @@ -46,7 +46,7 @@ $ pip install python-multipart
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/ko/docs/tutorial/security/oauth2-jwt.md b/docs/ko/docs/tutorial/security/oauth2-jwt.md index f0b0176..b34f31f 100644 --- a/docs/ko/docs/tutorial/security/oauth2-jwt.md +++ b/docs/ko/docs/tutorial/security/oauth2-jwt.md @@ -31,12 +31,12 @@ JWT 토큰을 직접 다뤄보고 동작 방식을 확인해보고 싶다면 [ht Python에서 JWT 토큰을 생성하고 검증하려면 `PyJWT`를 설치해야 합니다. -[가상환경](../../virtual-environments.md)을 만들고 활성화한 다음 `pyjwt`를 설치하십시오: +프로젝트에 `pyjwt`를 추가하십시오:
```console -$ pip install pyjwt +$ uv add pyjwt ---> 100% ``` @@ -73,12 +73,12 @@ pwdlib는 패스워드 해시를 다루기 위한 훌륭한 Python 패키지입 추천 알고리즘은 "Argon2"입니다. -[가상환경](../../virtual-environments.md)을 만들고 활성화한 다음 Argon2와 함께 pwdlib를 설치하십시오: +프로젝트에 Argon2와 함께 `pwdlib`를 추가하십시오:
```console -$ pip install "pwdlib[argon2]" +$ uv add "pwdlib[argon2]" ---> 100% ``` @@ -135,7 +135,7 @@ pwdlib는 bcrypt 해싱 알고리즘도 지원하지만 레거시 알고리즘 JWT 토큰을 서명하는 데 사용할 임의의 비밀 키를 생성합니다. -안전한 임의의 비밀 키를 생성하려면 다음 명령을 사용하십시오: +안전한 임의의 비밀 키를 생성하려면 다음 명령어를 사용하십시오:
diff --git a/docs/ko/docs/tutorial/sql-databases.md b/docs/ko/docs/tutorial/sql-databases.md index 6a48e30..e3f0465 100644 --- a/docs/ko/docs/tutorial/sql-databases.md +++ b/docs/ko/docs/tutorial/sql-databases.md @@ -35,12 +35,12 @@ SQLModel은 SQLAlchemy를 기반으로 하므로, SQLAlchemy에서 **지원하 ## `SQLModel` 설치하기 { #install-sqlmodel } -먼저, [가상 환경](../virtual-environments.md)을 생성하고 활성화한 다음, `sqlmodel`을 설치하세요: +프로젝트에 `sqlmodel`을 추가하세요:
```console -$ pip install sqlmodel +$ uv add sqlmodel ---> 100% ``` @@ -153,7 +153,7 @@ SQLModel은 Alembic을 감싸는 마이그레이션 유틸리티를 제공할
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -338,7 +338,7 @@ hero **삭제**는 이전과 거의 동일합니다.
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/ko/docs/tutorial/static-files.md b/docs/ko/docs/tutorial/static-files.md index b6f5bb9..8387d70 100644 --- a/docs/ko/docs/tutorial/static-files.md +++ b/docs/ko/docs/tutorial/static-files.md @@ -45,4 +45,4 @@ ## 추가 정보 { #more-info } -자세한 내용과 옵션은 [Starlette의 정적 파일 문서](https://www.starlette.dev/staticfiles/)를 확인하세요. +자세한 내용과 옵션은 [Starlette의 정적 파일 문서](https://starlette.dev/staticfiles/)를 확인하세요. diff --git a/docs/ko/docs/tutorial/testing.md b/docs/ko/docs/tutorial/testing.md index d6c627f..234bf31 100644 --- a/docs/ko/docs/tutorial/testing.md +++ b/docs/ko/docs/tutorial/testing.md @@ -1,6 +1,6 @@ # 테스팅 { #testing } -[Starlette](https://www.starlette.dev/testclient/) 덕분에 **FastAPI** 애플리케이션을 테스트하는 일은 쉽고 즐거운 일이 되었습니다. +[Starlette](https://starlette.dev/testclient/) 덕분에 **FastAPI** 애플리케이션을 테스트하는 일은 쉽고 즐거운 일이 되었습니다. 이는 [HTTPX](https://www.python-httpx.org)를 기반으로 하며, 이는 Requests를 기반으로 설계되었기 때문에 매우 친숙하고 직관적입니다. @@ -12,10 +12,10 @@ `TestClient` 사용하려면, 우선 [`httpx`](https://www.python-httpx.org)를 설치해야 합니다. -[가상 환경](../virtual-environments.md)을 만들고, 활성화한 뒤 설치하세요. 예시: +프로젝트에 추가하세요: ```console -$ pip install httpx +$ uv add httpx ``` /// @@ -156,12 +156,12 @@ FastAPI 애플리케이션에 요청을 보내는 것 외에도 테스트에서 그 후에는 `pytest`를 설치하기만 하면 됩니다. -[가상 환경](../virtual-environments.md)을 만들고, 활성화 시킨 뒤에 설치하세요. 예시: +프로젝트에 추가하세요:
```console -$ pip install pytest +$ uv add pytest ---> 100% ``` @@ -175,7 +175,7 @@ $ pip install pytest
```console -$ pytest +$ uv run pytest ================ test session starts ================ platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1 diff --git a/docs/ko/docs/virtual-environments.md b/docs/ko/docs/virtual-environments.md index d2bf72a..2bfe522 100644 --- a/docs/ko/docs/virtual-environments.md +++ b/docs/ko/docs/virtual-environments.md @@ -1,865 +1,35 @@ # 가상 환경 { #virtual-environments } +Python 프로젝트를 작업할 때는 각 프로젝트마다 설치하는 패키지를 분리하기 위해 **가상 환경**을 사용해야 합니다. -Python 프로젝트를 작업할 때는 **가상 환경**(또는 이와 유사한 메커니즘)을 사용해 각 프로젝트마다 설치하는 패키지를 분리하는 것이 좋습니다. - -/// note | 참고 - -이미 가상 환경에 대해 알고 있고, 어떻게 생성하고 사용하는지도 알고 있다면, 이 섹션은 건너뛰어도 괜찮습니다. 🤓 - -/// - -/// tip | 팁 - -**가상 환경**은 **환경 변수**와 다릅니다. - -**환경 변수**는 시스템에 존재하며, 프로그램이 사용할 수 있는 변수입니다. - -**가상 환경**은 몇몇 파일로 구성된 하나의 디렉터리입니다. - -/// - -/// note | 참고 - -이 페이지에서는 **가상 환경**을 사용하는 방법과 작동 방식을 알려드립니다. - -Python 설치까지 포함해 **모든 것을 관리해주는 도구**를 도입할 준비가 되었다면 [uv](https://github.com/astral-sh/uv)를 사용해 보세요. - -/// +FastAPI 프로젝트에서는 [uv](https://docs.astral.sh/uv/)를 사용해 프로젝트, 의존성, 가상 환경을 관리하는 것을 권장합니다. ## 프로젝트 생성 { #create-a-project } -먼저, 프로젝트를 위한 디렉터리를 하나 생성합니다. - -제가 보통 하는 방법은 사용자 홈/유저 디렉터리 안에 `code`라는 디렉터리를 만드는 것입니다. - -그리고 그 안에 프로젝트마다 디렉터리를 하나씩 만듭니다. +[공식 설치 가이드](https://docs.astral.sh/uv/getting-started/installation/)를 사용해 `uv`를 설치한 다음, 프로젝트를 생성하세요:
```console -// 홈 디렉터리로 이동 -$ cd -// 모든 코드 프로젝트를 위한 디렉터리 생성 -$ mkdir code -// 그 code 디렉터리로 이동 -$ cd code -// 이 프로젝트를 위한 디렉터리 생성 -$ mkdir awesome-project -// 그 프로젝트 디렉터리로 이동 +$ uv init awesome-project --bare $ cd awesome-project +$ uv add "fastapi[standard]" ```
-## 가상 환경 생성 { #create-a-virtual-environment } +`uv`는 프로젝트를 위한 가상 환경을 자동으로 생성합니다. 직접 만들거나 활성화할 필요가 없습니다. -Python 프로젝트를 **처음 시작할 때**, 가상 환경을 **프로젝트 내부**에 생성하세요. - -/// tip | 팁 - -이 작업은 **프로젝트당 한 번만** 하면 되며, 작업할 때마다 할 필요는 없습니다. - -/// - -//// tab | `venv` - -가상 환경을 만들려면 Python에 포함된 `venv` 모듈을 사용할 수 있습니다. +프로젝트 환경 안에서 명령어를 실행하려면 `uv run`을 사용하세요. 예를 들면:
```console -$ python -m venv .venv +$ uv run fastapi dev ```
-/// details | 명령어 의미 +## 더 알아보기 { #learn-more } -* `python`: `python`이라는 프로그램을 사용합니다 -* `-m`: 모듈을 스크립트로 호출합니다. 다음에 어떤 모듈인지 지정합니다 -* `venv`: 보통 Python에 기본으로 설치되어 있는 `venv` 모듈을 사용합니다 -* `.venv`: 새 디렉터리인 `.venv`에 가상 환경을 생성합니다 - -/// - -//// - -//// tab | `uv` - -[`uv`](https://github.com/astral-sh/uv)가 설치되어 있다면, 이를 사용해 가상 환경을 생성할 수 있습니다. - -
- -```console -$ uv venv -``` - -
- -/// tip | 팁 - -기본적으로 `uv`는 `.venv`라는 디렉터리에 가상 환경을 생성합니다. - -하지만 디렉터리 이름을 추가 인자로 전달해 이를 커스터마이즈할 수 있습니다. - -/// - -//// - -해당 명령어는 `.venv`라는 디렉터리에 새로운 가상 환경을 생성합니다. - -/// details | `.venv` 또는 다른 이름 - -가상 환경을 다른 디렉터리에 생성할 수도 있지만, 관례적으로 `.venv`라는 이름을 사용합니다. - -/// - -## 가상 환경 활성화 { #activate-the-virtual-environment } - -이후 실행하는 Python 명령어와 설치하는 패키지가 새 가상 환경을 사용하도록, 새 가상 환경을 활성화하세요. - -/// tip | 팁 - -프로젝트 작업을 위해 **새 터미널 세션**을 시작할 때마다 **매번** 이 작업을 하세요. - -/// - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -또는 Windows에서 Bash(예: [Git Bash](https://gitforwindows.org/))를 사용하는 경우: - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -/// tip | 팁 - -해당 환경에 **새 패키지**를 설치할 때마다, 환경을 다시 **활성화**하세요. - -이렇게 하면 해당 패키지가 설치한 **터미널(CLI) 프로그램**을 사용할 때, 전역으로 설치되어 있을 수도 있는(아마 필요한 버전과는 다른 버전인) 다른 프로그램이 아니라 가상 환경에 있는 것을 사용하게 됩니다. - -/// - -## 가상 환경 활성화 여부 확인 { #check-the-virtual-environment-is-active } - -가상 환경이 활성화되어 있는지(이전 명령어가 작동했는지) 확인합니다. - -/// tip | 팁 - -이 단계는 **선택 사항**이지만, 모든 것이 예상대로 작동하고 있는지, 그리고 의도한 가상 환경을 사용하고 있는지 **확인**하는 좋은 방법입니다. - -/// - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -프로젝트 내부(이 경우 `awesome-project`)의 `.venv/bin/python`에 있는 `python` 바이너리가 표시된다면, 정상적으로 작동한 것입니다. 🎉 - -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -프로젝트 내부(이 경우 `awesome-project`)의 `.venv\Scripts\python`에 있는 `python` 바이너리가 표시된다면, 정상적으로 작동한 것입니다. 🎉 - -//// - -## `pip` 업그레이드 { #upgrade-pip } - -/// tip | 팁 - -[`uv`](https://github.com/astral-sh/uv)를 사용한다면, `pip` 대신 `uv`로 설치하게 되므로 `pip`을 업그레이드할 필요가 없습니다. 😎 - -/// - -`pip`로 패키지를 설치한다면(Python에 기본으로 포함되어 있습니다) 최신 버전으로 **업그레이드**하는 것이 좋습니다. - -패키지 설치 중 발생하는 다양한 특이한 오류는 먼저 `pip`를 업그레이드하는 것만으로 해결되는 경우가 많습니다. - -/// tip | 팁 - -보통 이 작업은 가상 환경을 만든 직후 **한 번만** 하면 됩니다. - -/// - -가상 환경이 활성화된 상태인지 확인한 다음(위의 명령어 사용) 아래를 실행하세요: - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip | 팁 - -때로는 pip를 업그레이드하려고 할 때 **`No module named pip`** 오류가 발생할 수 있습니다. - -이 경우 아래 명령어로 pip를 설치하고 업그레이드하세요: - -
- -```console -$ python -m ensurepip --upgrade - ----> 100% -``` - -
- -이 명령어는 pip가 아직 설치되어 있지 않다면 설치하며, 설치된 pip 버전이 `ensurepip`에서 제공 가능한 버전만큼 최신임을 보장합니다. - -/// - -## `.gitignore` 추가하기 { #add-gitignore } - -**Git**을 사용하고 있다면(사용하는 것이 좋습니다), `.venv`의 모든 내용을 Git에서 제외하도록 `.gitignore` 파일을 추가하세요. - -/// tip | 팁 - -[`uv`](https://github.com/astral-sh/uv)로 가상 환경을 만들었다면, 이미 자동으로 처리되어 있으므로 이 단계는 건너뛰어도 됩니다. 😎 - -/// - -/// tip | 팁 - -가상 환경을 만든 직후 **한 번만** 하면 됩니다. - -/// - -
- -```console -$ echo "*" > .venv/.gitignore -``` - -
- -/// details | 명령어 의미 - -* `echo "*"`: 터미널에 `*` 텍스트를 "출력"합니다(다음 부분이 이를 약간 변경합니다) -* `>`: `>` 왼쪽 명령어가 터미널에 출력한 내용을 터미널에 출력하지 않고, `>` 오른쪽에 있는 파일에 기록하라는 의미입니다 -* `.gitignore`: 텍스트가 기록될 파일 이름입니다 - -그리고 Git에서 `*`는 "모든 것"을 의미합니다. 따라서 `.venv` 디렉터리 안의 모든 것을 무시합니다. - -이 명령어는 다음 내용을 가진 `.gitignore` 파일을 생성합니다: - -```gitignore -* -``` - -/// - -## 패키지 설치 { #install-packages } - -환경을 활성화한 뒤, 그 안에 패키지를 설치할 수 있습니다. - -/// tip | 팁 - -프로젝트에 필요한 패키지를 설치하거나 업그레이드할 때는 **한 번**만 하면 됩니다. - -버전을 업그레이드하거나 새 패키지를 추가해야 한다면 **다시 이 작업을** 하게 됩니다. - -/// - -### 패키지 직접 설치 { #install-packages-directly } - -급하게 작업 중이고 프로젝트의 패키지 요구사항을 선언하는 파일을 사용하고 싶지 않다면, 패키지를 직접 설치할 수 있습니다. - -/// tip | 팁 - -프로그램에 필요한 패키지와 버전을 파일(예: `requirements.txt` 또는 `pyproject.toml`)에 적어두는 것은 (매우) 좋은 생각입니다. - -/// - -//// tab | `pip` - -
- -```console -$ pip install "fastapi[standard]" - ----> 100% -``` - -
- -//// - -//// tab | `uv` - -[`uv`](https://github.com/astral-sh/uv)가 있다면: - -
- -```console -$ uv pip install "fastapi[standard]" ----> 100% -``` - -
- -//// - -### `requirements.txt`에서 설치 { #install-from-requirements-txt } - -`requirements.txt`가 있다면, 이제 이를 사용해 그 안의 패키지를 설치할 수 있습니다. - -//// tab | `pip` - -
- -```console -$ pip install -r requirements.txt ----> 100% -``` - -
- -//// - -//// tab | `uv` - -[`uv`](https://github.com/astral-sh/uv)가 있다면: - -
- -```console -$ uv pip install -r requirements.txt ----> 100% -``` - -
- -//// - -/// details | `requirements.txt` - -일부 패키지가 있는 `requirements.txt`는 다음과 같이 생겼을 수 있습니다: - -```requirements.txt -fastapi[standard]==0.113.0 -pydantic==2.8.0 -``` - -/// - -## 프로그램 실행 { #run-your-program } - -가상 환경을 활성화한 뒤에는 프로그램을 실행할 수 있으며, 설치한 패키지가 들어있는 가상 환경 내부의 Python을 사용하게 됩니다. - -
- -```console -$ python main.py - -Hello World -``` - -
- -## 에디터 설정 { #configure-your-editor } - -아마 에디터를 사용할 텐데, 자동 완성과 인라인 오류 표시를 받을 수 있도록 생성한 가상 환경을 사용하도록 설정하세요(대부분 자동 감지합니다). - -예를 들면: - -* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) -* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) - -/// tip | 팁 - -보통 이 설정은 가상 환경을 만들 때 **한 번만** 하면 됩니다. - -/// - -## 가상 환경 비활성화 { #deactivate-the-virtual-environment } - -프로젝트 작업을 마쳤다면 가상 환경을 **비활성화**할 수 있습니다. - -
- -```console -$ deactivate -``` - -
- -이렇게 하면 `python`을 실행할 때, 해당 가상 환경과 그 안에 설치된 패키지에서 실행하려고 하지 않습니다. - -## 작업할 준비 완료 { #ready-to-work } - -이제 프로젝트 작업을 시작할 준비가 되었습니다. - - - -/// tip | 팁 - -위의 내용이 무엇인지 더 이해하고 싶으신가요? - -계속 읽어보세요. 👇🤓 - -/// - -## 가상 환경을 왜 사용하나요 { #why-virtual-environments } - -FastAPI로 작업하려면 [Python](https://www.python.org/)을 설치해야 합니다. - -그 다음 FastAPI와 사용하려는 다른 **패키지**를 **설치**해야 합니다. - -패키지를 설치할 때는 보통 Python에 포함된 `pip` 명령어(또는 유사한 대안)를 사용합니다. - -하지만 `pip`를 그대로 직접 사용하면, 패키지는 **전역 Python 환경**(전역 Python 설치)에 설치됩니다. - -### 문제점 { #the-problem } - -그렇다면, 전역 Python 환경에 패키지를 설치하면 어떤 문제가 있을까요? - -어느 시점이 되면 **서로 다른 패키지**에 의존하는 다양한 프로그램을 작성하게 될 것입니다. 그리고 작업하는 프로젝트 중 일부는 같은 패키지의 **서로 다른 버전**에 의존할 수도 있습니다. 😱 - -예를 들어 `philosophers-stone`이라는 프로젝트를 만들 수 있습니다. 이 프로그램은 **`harry`라는 다른 패키지의 버전 `1`**에 의존합니다. 그래서 `harry`를 설치해야 합니다. - -```mermaid -flowchart LR - stone(philosophers-stone) -->|requires| harry-1[harry v1] -``` - -그다음, 나중에 `prisoner-of-azkaban`이라는 또 다른 프로젝트를 만들고, 이 프로젝트도 `harry`에 의존하지만, 이 프로젝트는 **`harry` 버전 `3`**이 필요합니다. - -```mermaid -flowchart LR - azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3] -``` - -하지만 이제 문제가 생깁니다. 로컬 **가상 환경**이 아니라 전역(전역 환경)에 패키지를 설치한다면, 어떤 버전의 `harry`를 설치할지 선택해야 합니다. - -`philosophers-stone`을 실행하고 싶다면, 먼저 `harry` 버전 `1`을 다음과 같이 설치해야 합니다: - -
- -```console -$ pip install "harry==1" -``` - -
- -그리고 전역 Python 환경에 `harry` 버전 `1`이 설치된 상태가 됩니다. - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -->|requires| harry-1 - end -``` - -하지만 `prisoner-of-azkaban`을 실행하려면 `harry` 버전 `1`을 제거하고 `harry` 버전 `3`을 설치해야 합니다(또는 버전 `3`을 설치하기만 해도 버전 `1`이 자동으로 제거됩니다). - -
- -```console -$ pip install "harry==3" -``` - -
- -그러면 전역 Python 환경에 `harry` 버전 `3`이 설치된 상태가 됩니다. - -그리고 `philosophers-stone`을 다시 실행하려고 하면, `harry` 버전 `1`이 필요하기 때문에 **작동하지 않을** 가능성이 있습니다. - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - style harry-1 fill:#ccc,stroke-dasharray: 5 5 - harry-3[harry v3] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -.-x|⛔️| harry-1 - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --> |requires| harry-3 - end -``` - -/// tip | 팁 - -Python 패키지에서는 **새 버전**에서 **호환성을 깨뜨리는 변경(breaking changes)**을 **피하려고** 최선을 다하는 것이 매우 일반적이지만, 안전을 위해 더 최신 버전은 의도적으로 설치하고, 테스트를 실행해 모든 것이 올바르게 작동하는지 확인할 수 있을 때 설치하는 것이 좋습니다. - -/// - -이제 이런 일이 여러분의 **모든 프로젝트가 의존하는** **많은** 다른 **패키지**에서도 일어난다고 상상해 보세요. 이는 관리하기가 매우 어렵습니다. 그리고 결국 일부 프로젝트는 패키지의 **호환되지 않는 버전**으로 실행하게 될 가능성이 높으며, 왜 무언가가 작동하지 않는지 알지 못하게 될 수 있습니다. - -또한 운영체제(Linux, Windows, macOS 등)에 따라 Python이 이미 설치되어 있을 수도 있습니다. 그런 경우에는 시스템에 **필요한 특정 버전**의 패키지가 일부 미리 설치되어 있을 가능성이 큽니다. 전역 Python 환경에 패키지를 설치하면, 운영체제에 포함된 프로그램 일부가 **깨질** 수 있습니다. - -## 패키지는 어디에 설치되나요 { #where-are-packages-installed } - -Python을 설치하면 컴퓨터에 몇몇 파일이 들어 있는 디렉터리가 생성됩니다. - -이 디렉터리 중 일부는 설치한 모든 패키지를 담는 역할을 합니다. - -다음을 실행하면: - -
- -```console -// 지금은 실행하지 마세요, 예시일 뿐입니다 🤓 -$ pip install "fastapi[standard]" ----> 100% -``` - -
- -FastAPI 코드를 담은 압축 파일을 다운로드합니다. 보통 [PyPI](https://pypi.org/project/fastapi/)에서 받습니다. - -또한 FastAPI가 의존하는 다른 패키지들의 파일도 **다운로드**합니다. - -그 다음 모든 파일을 **압축 해제**하고 컴퓨터의 한 디렉터리에 넣습니다. - -기본적으로, 다운로드하고 압축 해제한 파일들은 Python 설치와 함께 제공되는 디렉터리, 즉 **전역 환경**에 저장됩니다. - -## 가상 환경이란 무엇인가요 { #what-are-virtual-environments } - -전역 환경에 모든 패키지를 두는 문제에 대한 해결책은 작업하는 **각 프로젝트마다 가상 환경**을 사용하는 것입니다. - -가상 환경은 전역 환경과 매우 유사한 하나의 **디렉터리**이며, 프로젝트의 패키지를 설치할 수 있습니다. - -이렇게 하면 각 프로젝트는 자체 가상 환경(`.venv` 디렉터리)과 자체 패키지를 갖게 됩니다. - -```mermaid -flowchart TB - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) --->|requires| harry-1 - subgraph venv1[.venv] - harry-1[harry v1] - end - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --->|requires| harry-3 - subgraph venv2[.venv] - harry-3[harry v3] - end - end - stone-project ~~~ azkaban-project -``` - -## 가상 환경을 활성화한다는 것은 무엇을 의미하나요 { #what-does-activating-a-virtual-environment-mean } - -가상 환경을 활성화한다는 것은, 예를 들어 다음과 같은 명령어로: - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -또는 Windows에서 Bash(예: [Git Bash](https://gitforwindows.org/))를 사용하는 경우: - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -다음 명령어들에서 사용할 수 있는 몇몇 [환경 변수](environment-variables.md)를 생성하거나 수정하는 것을 의미합니다. - -그 변수 중 하나가 `PATH` 변수입니다. - -/// tip | 팁 - -`PATH` 환경 변수에 대해 더 알아보려면 [환경 변수](environment-variables.md#path-environment-variable) 섹션을 참고하세요. - -/// - -가상 환경을 활성화하면 가상 환경의 경로인 `.venv/bin`(Linux와 macOS) 또는 `.venv\Scripts`(Windows)를 `PATH` 환경 변수에 추가합니다. - -가령 환경을 활성화하기 전에는 `PATH` 변수가 다음과 같았다고 해보겠습니다: - -//// tab | Linux, macOS - -```plaintext -/usr/bin:/bin:/usr/sbin:/sbin -``` - -이는 시스템이 다음 위치에서 프로그램을 찾는다는 뜻입니다: - -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Windows\System32 -``` - -이는 시스템이 다음 위치에서 프로그램을 찾는다는 뜻입니다: - -* `C:\Windows\System32` - -//// - -가상 환경을 활성화한 뒤에는 `PATH` 변수가 다음과 같이 보일 수 있습니다: - -//// tab | Linux, macOS - -```plaintext -/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -이는 시스템이 이제 다음 위치에서 프로그램을 가장 먼저 찾기 시작한다는 뜻입니다: - -```plaintext -/home/user/code/awesome-project/.venv/bin -``` - -그리고 나서 다른 디렉터리들을 탐색합니다. - -따라서 터미널에 `python`을 입력하면, 시스템은 다음 위치에서 Python 프로그램을 찾고: - -```plaintext -/home/user/code/awesome-project/.venv/bin/python -``` - -그것을 사용하게 됩니다. - -//// - -//// tab | Windows - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32 -``` - -이는 시스템이 이제 다음 위치에서 프로그램을 가장 먼저 찾기 시작한다는 뜻입니다: - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts -``` - -그리고 나서 다른 디렉터리들을 탐색합니다. - -따라서 터미널에 `python`을 입력하면, 시스템은 다음 위치에서 Python 프로그램을 찾고: - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -그것을 사용하게 됩니다. - -//// - -중요한 세부 사항은 가상 환경 경로가 `PATH` 변수의 **맨 앞**에 들어간다는 점입니다. 시스템은 다른 어떤 Python보다도 **먼저** 이를 찾게 됩니다. 이렇게 하면 `python`을 실행할 때, 다른 어떤 `python`(예: 전역 환경의 `python`)이 아니라 **가상 환경의 Python**을 사용하게 됩니다. - -가상 환경을 활성화하면 다른 몇 가지도 변경되지만, 이것이 그중 가장 중요한 것 중 하나입니다. - -## 가상 환경 확인하기 { #checking-a-virtual-environment } - -가상 환경이 활성화되어 있는지 확인할 때는, 예를 들어 다음을 사용합니다: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -//// - -이는 사용될 `python` 프로그램이 **가상 환경 내부에 있는 것**이라는 뜻입니다. - -Linux와 macOS에서는 `which`, Windows PowerShell에서는 `Get-Command`를 사용합니다. - -이 명령어는 `PATH` 환경 변수에 있는 경로를 **순서대로** 확인하면서 `python`이라는 프로그램을 찾습니다. 찾는 즉시, 그 프로그램의 **경로를 보여줍니다**. - -가장 중요한 부분은 `python`을 호출했을 때, 실행될 정확한 "`python`"이 무엇인지 알 수 있다는 점입니다. - -따라서 올바른 가상 환경에 있는지 확인할 수 있습니다. - -/// tip | 팁 - -가상 환경을 하나 활성화해서 Python을 사용한 다음, **다른 프로젝트로 이동**하기 쉽습니다. - -그리고 두 번째 프로젝트는 다른 프로젝트의 가상 환경에서 온 **잘못된 Python**을 사용하고 있기 때문에 **작동하지 않을** 수 있습니다. - -어떤 `python`이 사용되고 있는지 확인할 수 있으면 유용합니다. 🤓 - -/// - -## 가상 환경을 왜 비활성화하나요 { #why-deactivate-a-virtual-environment } - -예를 들어 `philosophers-stone` 프로젝트에서 작업하면서, **그 가상 환경을 활성화**하고, 패키지를 설치하고, 그 환경으로 작업하고 있다고 해보겠습니다. - -그런데 이제 **다른 프로젝트**인 `prisoner-of-azkaban`에서 작업하고 싶습니다. - -해당 프로젝트로 이동합니다: - -
- -```console -$ cd ~/code/prisoner-of-azkaban -``` - -
- -`philosophers-stone`의 가상 환경을 비활성화하지 않으면, 터미널에서 `python`을 실행할 때 `philosophers-stone`의 Python을 사용하려고 할 것입니다. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -$ python main.py - -// sirius 임포트 오류, 설치되어 있지 않습니다 😱 -Traceback (most recent call last): - File "main.py", line 1, in - import sirius -``` - -
- -하지만 가상 환경을 비활성화하고 `prisoner-of-azkaban`에 대한 새 가상 환경을 활성화하면, `python`을 실행할 때 `prisoner-of-azkaban`의 가상 환경에 있는 Python을 사용하게 됩니다. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -// 비활성화를 위해 이전 디렉터리에 있을 필요는 없습니다. 어디서든, 다른 프로젝트로 이동한 뒤에도 할 수 있습니다 😎 -$ deactivate - -// prisoner-of-azkaban/.venv의 가상 환경을 활성화하세요 🚀 -$ source .venv/bin/activate - -// 이제 python을 실행하면, 이 가상 환경에 설치된 sirius 패키지를 찾습니다 ✨ -$ python main.py - -I solemnly swear 🐺 -``` - -
- -## 대안들 { #alternatives } - -이 문서는 시작을 돕고, 내부에서 모든 것이 어떻게 작동하는지 알려주는 간단한 가이드입니다. - -가상 환경, 패키지 의존성(requirements), 프로젝트를 관리하는 방법에는 많은 **대안**이 있습니다. - -준비가 되었고 **프로젝트 전체**, 패키지 의존성, 가상 환경 등을 **관리**하는 도구를 사용하고 싶다면 [uv](https://github.com/astral-sh/uv)를 사용해 보시길 권합니다. - -`uv`는 많은 일을 할 수 있습니다. 예를 들어: - -* 여러 버전을 포함해 **Python을 설치** -* 프로젝트의 **가상 환경** 관리 -* **패키지** 설치 -* 프로젝트의 패키지 **의존성과 버전** 관리 -* 의존성을 포함해 설치할 패키지와 버전의 **정확한** 세트를 보장하여, 개발 중인 컴퓨터와 동일하게 프로덕션에서 실행할 수 있도록 합니다. 이를 **locking**이라고 합니다 -* 그 외에도 많은 기능이 있습니다 - -## 결론 { #conclusion } - -여기까지 모두 읽고 이해했다면, 이제 많은 개발자들보다 가상 환경에 대해 **훨씬 더 많이** 알게 된 것입니다. 🤓 - -이 세부 사항을 알고 있으면, 나중에 복잡해 보이는 무언가를 디버깅할 때 아마도 도움이 될 것입니다. **내부에서 어떻게 작동하는지** 알고 있기 때문입니다. 😎 +가상 환경이 내부에서 어떻게 작동하는지, 활성화와 대안인 `python -m venv` 및 `pip` 워크플로를 포함해 알아보려면 [가상 환경 가이드](https://tiangolo.com/guides/virtual-environments/)를 읽어보세요. diff --git a/docs/pt/docs/advanced/additional-responses.md b/docs/pt/docs/advanced/additional-responses.md index 1e68134..2d2d8a0 100644 --- a/docs/pt/docs/advanced/additional-responses.md +++ b/docs/pt/docs/advanced/additional-responses.md @@ -1,4 +1,4 @@ -# Retornos Adicionais no OpenAPI { #additional-responses-in-openapi } +# Respostas Adicionais no OpenAPI { #additional-responses-in-openapi } /// warning | Atenção @@ -8,23 +8,23 @@ Se você está começando com o **FastAPI**, provavelmente você não precisa di /// -Você pode declarar retornos adicionais, com códigos de status adicionais, media types, descrições, etc. +Você pode declarar respostas adicionais, com códigos de status adicionais, media types, descrições, etc. Essas respostas adicionais serão incluídas no esquema do OpenAPI, e também aparecerão na documentação da API. -Porém para as respostas adicionais, você deve garantir que está retornando um `Response` como por exemplo o `JSONResponse` diretamente, junto com o código de status e o conteúdo. +Porém para essas respostas adicionais, você deve garantir que está retornando um `Response` como por exemplo o `JSONResponse` diretamente, junto com o código de status e o conteúdo. -## Retorno Adicional com `model` { #additional-response-with-model } +## Resposta Adicional com `model` { #additional-response-with-model } -Você pode fornecer o parâmetro `responses` aos seus *decoradores de caminho*. +Você pode fornecer o parâmetro `responses` aos seus *decoradores de operação de rota*. -Este parâmetro recebe um `dict`, as chaves são os códigos de status para cada retorno, como por exemplo `200`, e os valores são um outro `dict` com a informação de cada um deles. +Este parâmetro recebe um `dict`: as chaves são os códigos de status para cada resposta, como por exemplo `200`, e os valores são outros `dict`s com a informação de cada um deles. -Cada um desses `dict` de retorno pode ter uma chave `model`, contendo um modelo do Pydantic, assim como o `response_model`. +Cada um desses `dict`s de resposta pode ter uma chave `model`, contendo um modelo do Pydantic, assim como o `response_model`. -O **FastAPI** pegará este modelo, gerará o esquema JSON dele e incluirá no local correto do OpenAPI. +O **FastAPI** pegará este modelo, gerará seu JSON Schema e incluirá no local correto do OpenAPI. -Por exemplo, para declarar um outro retorno com o status code `404` e um modelo do Pydantic chamado `Message`, você pode escrever: +Por exemplo, para declarar outra resposta com o código de status `404` e um modelo do Pydantic chamado `Message`, você pode escrever: {* ../../docs_src/additional_responses/tutorial001_py310.py hl[18,22] *} @@ -38,18 +38,18 @@ Lembre-se que você deve retornar o `JSONResponse` diretamente. A chave `model` não é parte do OpenAPI. -O **FastAPI** pegará o modelo do Pydantic, gerará o `JSON Schema`, e adicionará no local correto. +O **FastAPI** pegará o modelo do Pydantic, gerará o JSON Schema, e adicionará no local correto. O local correto é: -* Na chave `content`, que tem como valor um outro objeto JSON (`dict`) que contém: - * Uma chave com o media type, como por exemplo `application/json`, que contém como valor um outro objeto JSON, contendo:: - * Uma chave `schema`, que contém como valor o JSON Schema do modelo, sendo este o local correto. - * O **FastAPI** adiciona aqui a referência dos esquemas JSON globais que estão localizados em outro lugar, ao invés de incluí-lo diretamente. Deste modo, outras aplicações e clientes podem utilizar estes esquemas JSON diretamente, fornecer melhores ferramentas de geração de código, etc. +* Na chave `content`, que tem como valor outro objeto JSON (`dict`) que contém: + * Uma chave com o media type, como por exemplo `application/json`, que contém como valor outro objeto JSON, que contém: + * Uma chave `schema`, que tem como valor o JSON Schema do modelo, sendo este o local correto. + * O **FastAPI** adiciona aqui a referência aos JSON Schemas globais que estão localizados em outro lugar no seu OpenAPI, ao invés de incluí-lo diretamente. Deste modo, outras aplicações e clientes podem utilizar estes JSON Schemas diretamente, fornecer melhores ferramentas de geração de código, etc. /// -O retorno gerado no OpenAPI para esta *operação de rota* será: +As respostas geradas no OpenAPI para esta *operação de rota* serão: ```JSON hl_lines="3-12" { @@ -169,9 +169,9 @@ Os esquemas são referenciados em outro local dentro do esquema OpenAPI: } ``` -## Media types adicionais para o retorno principal { #additional-media-types-for-the-main-response } +## Media types adicionais para a resposta principal { #additional-media-types-for-the-main-response } -Você pode utilizar o mesmo parâmetro `responses` para adicionar diferentes media types para o mesmo retorno principal. +Você pode utilizar o mesmo parâmetro `responses` para adicionar diferentes media types para a mesma resposta principal. Por exemplo, você pode adicionar um media type adicional de `image/png`, declarando que a sua *operação de rota* pode retornar um objeto JSON (com o media type `application/json`) ou uma imagem PNG: @@ -185,33 +185,33 @@ Note que você deve retornar a imagem utilizando um `FileResponse` diretamente. /// note | Nota -A menos que você especifique um media type diferente explicitamente em seu parâmetro `responses`, o FastAPI assumirá que o retorno possui o mesmo media type contido na classe principal de retorno (padrão `application/json`). +A menos que você especifique um media type diferente explicitamente em seu parâmetro `responses`, o FastAPI assumirá que a resposta possui o mesmo media type contido na classe principal de resposta (padrão `application/json`). -Porém se você especificou uma classe de retorno com o valor `None` como media type, o FastAPI utilizará `application/json` para qualquer retorno adicional que possui um modelo associado. +Porém se você especificou uma classe de resposta personalizada com o valor `None` como media type, o FastAPI utilizará `application/json` para qualquer resposta adicional que possui um modelo associado. /// ## Combinando informações { #combining-information } -Você também pode combinar informações de diferentes lugares, incluindo os parâmetros `response_model`, `status_code`, e `responses`. +Você também pode combinar informações de resposta de diferentes lugares, incluindo os parâmetros `response_model`, `status_code`, e `responses`. -Você pode declarar um `response_model`, utilizando o código de status padrão `200` (ou um customizado caso você precise), e depois adicionar informações adicionais para esse mesmo retorno em `responses`, diretamente no esquema OpenAPI. +Você pode declarar um `response_model`, utilizando o código de status padrão `200` (ou um personalizado caso você precise), e depois adicionar informações adicionais para essa mesma resposta em `responses`, diretamente no esquema OpenAPI. -O **FastAPI** manterá as informações adicionais do `responses`, e combinará com o esquema JSON do seu modelo. +O **FastAPI** manterá as informações adicionais do `responses`, e combinará com o JSON Schema do seu modelo. -Por exemplo, você pode declarar um retorno com o código de status `404` que utiliza um modelo do Pydantic e tem uma `description` customizada. +Por exemplo, você pode declarar uma resposta com o código de status `404` que utiliza um modelo do Pydantic e tem uma `description` personalizada. -E um retorno com o código de status `200` que utiliza o seu `response_model`, porém inclui um `example` customizado: +E uma resposta com o código de status `200` que utiliza o seu `response_model`, porém inclui um `example` personalizado: {* ../../docs_src/additional_responses/tutorial003_py310.py hl[20:31] *} -Isso será combinado e incluído em seu OpenAPI, e disponibilizado na documentação da sua API: +Isso será combinado e incluído em seu OpenAPI, e mostrado na documentação da API: -## Combinar retornos predefinidos e personalizados { #combine-predefined-responses-and-custom-ones } +## Combinar respostas predefinidas e personalizadas { #combine-predefined-responses-and-custom-ones } -Você pode querer possuir alguns retornos predefinidos que são aplicados para diversas *operações de rota*, porém você deseja combinar com retornos personalizados que são necessários para cada *operação de rota*. +Você pode querer possuir algumas respostas predefinidas que são aplicadas para diversas *operações de rota*, porém deseja combinar com respostas personalizadas que são necessárias para cada *operação de rota*. Para estes casos, você pode utilizar a técnica do Python de "desempacotamento" de um `dict` utilizando `**dict_to_unpack`: @@ -233,15 +233,15 @@ Aqui, o `new_dict` terá todos os pares de chave-valor do `old_dict` mais o novo } ``` -Você pode utilizar essa técnica para reutilizar alguns retornos predefinidos nas suas *operações de rota* e combiná-las com personalizações adicionais. +Você pode utilizar essa técnica para reutilizar algumas respostas predefinidas nas suas *operações de rota* e combiná-las com personalizações adicionais. Por exemplo: {* ../../docs_src/additional_responses/tutorial004_py310.py hl[11:15,24] *} -## Mais informações sobre retornos OpenAPI { #more-information-about-openapi-responses } +## Mais informações sobre respostas OpenAPI { #more-information-about-openapi-responses } -Para verificar exatamente o que você pode incluir nos retornos, você pode conferir estas seções na especificação do OpenAPI: +Para verificar exatamente o que você pode incluir nas respostas, você pode conferir estas seções na especificação do OpenAPI: -* [Objeto de Retornos do OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object), inclui o `Response Object`. -* [Objeto de Retorno do OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object), você pode incluir qualquer coisa dele diretamente em cada retorno dentro do seu parâmetro `responses`. Incluindo `description`, `headers`, `content` (dentro dele que você declara diferentes media types e esquemas JSON), e `links`. +* [Objeto de Respostas do OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object), inclui o `Response Object`. +* [Objeto de Resposta do OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object), você pode incluir qualquer coisa dele diretamente em cada resposta dentro do seu parâmetro `responses`. Incluindo `description`, `headers`, `content` (dentro dele que você declara diferentes media types e JSON Schemas), e `links`. diff --git a/docs/pt/docs/advanced/async-tests.md b/docs/pt/docs/advanced/async-tests.md index 9dfadc3..de4ecf9 100644 --- a/docs/pt/docs/advanced/async-tests.md +++ b/docs/pt/docs/advanced/async-tests.md @@ -2,7 +2,7 @@ Você já viu como testar as suas aplicações **FastAPI** utilizando o `TestClient` que é fornecido. Até agora, você viu apenas como escrever testes síncronos, sem utilizar funções `async`. -Ser capaz de utilizar funções assíncronas em seus testes pode ser útil, por exemplo, quando você está realizando uma consulta em seu banco de dados de maneira assíncrona. Imagine que você deseja testar realizando requisições para a sua aplicação FastAPI e depois verificar que a sua aplicação inseriu corretamente as informações no banco de dados, ao utilizar uma biblioteca assíncrona para banco de dados. +Ser capaz de utilizar funções assíncronas em seus testes pode ser útil, por exemplo, quando você está realizando uma consulta em seu banco de dados de maneira assíncrona. Imagine que você deseja testar enviando requisições para a sua aplicação FastAPI e depois verificar que o seu backend gravou com sucesso os dados corretos no banco de dados, ao utilizar uma biblioteca assíncrona para banco de dados. Vamos ver como nós podemos fazer isso funcionar. @@ -20,7 +20,7 @@ O `TestClient` é baseado no [HTTPX](https://www.python-httpx.org), e felizmente ## Exemplo { #example } -Para um exemplos simples, vamos considerar uma estrutura de arquivos semelhante ao descrito em [Aplicações Maiores](../tutorial/bigger-applications.md) e [Testes](../tutorial/testing.md): +Para um exemplo simples, vamos considerar uma estrutura de arquivos semelhante à descrita em [Aplicações Maiores](../tutorial/bigger-applications.md) e [Testes](../tutorial/testing.md): ``` . @@ -34,7 +34,7 @@ O arquivo `main.py` teria: {* ../../docs_src/async_tests/app_a_py310/main.py *} -O arquivo `test_main.py` teria os testes para para o arquivo `main.py`, ele poderia ficar assim: +O arquivo `test_main.py` teria os testes para o arquivo `main.py`, ele poderia ficar assim agora: {* ../../docs_src/async_tests/app_a_py310/test_main.py *} @@ -45,7 +45,7 @@ Você pode executar os seus testes normalmente via:
```console -$ pytest +$ uv run pytest ---> 100% ``` @@ -94,6 +94,6 @@ Como a função de teste agora é assíncrona, você pode chamar (e `await`) out /// tip | Dica -Se você se deparar com um `RuntimeError: Task attached to a different loop` ao integrar funções assíncronas em seus testes (e.g. ao utilizar o [MotorClient do MongoDB](https://stackoverflow.com/questions/41584243/runtimeerror-task-attached-to-a-different-loop)) Lembre-se de instanciar objetos que precisam de um loop de eventos (*event loop*) apenas em funções assíncronas, e.g. um callback `@app.on_event("startup")`. +Se você se deparar com um `RuntimeError: Task attached to a different loop` ao integrar chamadas de funções assíncronas em seus testes (e.g. ao utilizar o [MotorClient do MongoDB](https://stackoverflow.com/questions/41584243/runtimeerror-task-attached-to-a-different-loop)), lembre-se de instanciar objetos que precisam de um loop de eventos apenas em funções async, e.g. um callback `@app.on_event("startup")`. /// diff --git a/docs/pt/docs/advanced/behind-a-proxy.md b/docs/pt/docs/advanced/behind-a-proxy.md index 4dcdcc9..1bfe0bc 100644 --- a/docs/pt/docs/advanced/behind-a-proxy.md +++ b/docs/pt/docs/advanced/behind-a-proxy.md @@ -22,9 +22,9 @@ Os headers do proxy são: /// -### Ativar headers encaminhados pelo proxy { #enable-proxy-forwarded-headers } +### Ative os headers encaminhados pelo proxy { #enable-proxy-forwarded-headers } -Você pode iniciar a CLI do FastAPI com a opção de linha de comando `--forwarded-allow-ips` e informar os endereços IP que devem ser confiáveis para ler esses headers encaminhados. +Você pode iniciar a CLI do FastAPI com a *Opção de CLI* `--forwarded-allow-ips` e informar os endereços IP que devem ser confiáveis para ler esses headers encaminhados. Se você definir como `--forwarded-allow-ips="*"`, ele confiará em todos os IPs de entrada. @@ -33,7 +33,7 @@ Se o seu **servidor** estiver atrás de um **proxy** confiável e somente o prox
```console -$ fastapi run --forwarded-allow-ips="*" +$ uv run fastapi run --forwarded-allow-ips="*" INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -48,7 +48,7 @@ Por exemplo, suponha que você defina uma *operação de rota* `/items/`: Se o cliente tentar ir para `/items`, por padrão, ele seria redirecionado para `/items/`. -Mas antes de definir a opção de linha de comando `--forwarded-allow-ips`, poderia redirecionar para `http://localhost:8000/items/`. +Mas antes de definir a *Opção de CLI* `--forwarded-allow-ips`, poderia redirecionar para `http://localhost:8000/items/`. Mas talvez sua aplicação esteja hospedada em `https://mysuperapp.com`, e o redirecionamento deveria ser para `https://mysuperapp.com/items/`. @@ -87,7 +87,7 @@ sequenceDiagram Proxy->>Client: HTTPS Response ``` -O **proxy** intercepta a requisição original do cliente e adiciona os headers especiais de encaminhamento (`X-Forwarded-*`) antes de repassar a requisição para o **servidor da aplicação**. +O **proxy** intercepta a requisição original do cliente e adiciona os headers especiais *encaminhados* (`X-Forwarded-*`) antes de repassar a requisição para o **servidor da aplicação**. Esses headers preservam informações sobre a requisição original que, de outra forma, seriam perdidas: @@ -117,7 +117,7 @@ Embora todo o seu código esteja escrito assumindo que existe apenas `/app`. {* ../../docs_src/behind_a_proxy/tutorial001_py310.py hl[6] *} -E o proxy estaria **"removendo"** o **prefixo de path** dinamicamente antes de transmitir a solicitação para o servidor da aplicação (provavelmente Uvicorn via CLI do FastAPI), mantendo sua aplicação convencida de que está sendo servida em `/app`, para que você não precise atualizar todo o seu código para incluir o prefixo `/api/v1`. +E o proxy estaria **"removendo"** o **prefixo de path** dinamicamente antes de transmitir a requisição para o servidor da aplicação (provavelmente Uvicorn via CLI do FastAPI), mantendo sua aplicação convencida de que está sendo servida em `/app`, para que você não precise atualizar todo o seu código para incluir o prefixo `/api/v1`. Até aqui, tudo funcionaria normalmente. @@ -170,7 +170,7 @@ Para conseguir isso, você pode usar a opção de linha de comando `--root-path`
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -189,7 +189,7 @@ E a opção de linha de comando `--root-path` fornece esse `root_path`. ### Verificando o `root_path` atual { #checking-the-current-root-path } -Você pode obter o `root_path` atual usado pela sua aplicação para cada solicitação, ele faz parte do dicionário `scope` (que faz parte da especificação ASGI). +Você pode obter o `root_path` atual usado pela sua aplicação para cada requisição, ele faz parte do dicionário `scope` (que faz parte da especificação ASGI). Aqui estamos incluindo-o na mensagem apenas para fins de demonstração. @@ -200,7 +200,7 @@ Então, se você iniciar o Uvicorn com:
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -253,7 +253,7 @@ Em um caso como esse (sem um prefixo de path removido), o proxy escutaria em alg Você pode facilmente executar o experimento localmente com um prefixo de path removido usando [Traefik](https://docs.traefik.io/). -[Faça o download do Traefik](https://github.com/containous/traefik/releases), ele é um único binário, você pode extrair o arquivo compactado e executá-lo diretamente do terminal. +[Faça o download do Traefik](https://github.com/traefik/traefik/releases), ele é um único binário, você pode extrair o arquivo compactado e executá-lo diretamente do terminal. Então, crie um arquivo `traefik.toml` com: @@ -302,7 +302,7 @@ Agora crie esse outro arquivo `routes.toml`: Esse arquivo configura o Traefik para usar o prefixo de path `/api/v1`. -E então o Traefik redirecionará suas solicitações para seu Uvicorn rodando em `http://127.0.0.1:8000`. +E então o Traefik redirecionará suas requisições para seu Uvicorn rodando em `http://127.0.0.1:8000`. Agora inicie o Traefik: @@ -321,7 +321,7 @@ E agora inicie sua aplicação, usando a opção `--root-path`:
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -394,7 +394,7 @@ Este é um caso de uso mais avançado. Sinta-se à vontade para pular. Por padrão, o **FastAPI** criará um `server` no OpenAPI schema com o URL para o `root_path`. -Mas você também pode fornecer outros `servers` alternativos, por exemplo, se quiser que a mesma interface de documentação interaja com ambientes de staging e produção. +Mas você também pode fornecer outros `servers` alternativos, por exemplo, se quiser que *a mesma* interface de documentação interaja com ambientes de staging e produção. Se você passar uma lista personalizada de `servers` e houver um `root_path` (porque sua API está atrás de um proxy), o **FastAPI** inserirá um "server" com esse `root_path` no início da lista. @@ -451,7 +451,7 @@ Se você não especificar o parâmetro `servers` e `root_path` for igual a `/`, /// -### Desabilitar servidor automático de `root_path` { #disable-automatic-server-from-root-path } +### Desabilite o servidor automático de `root_path` { #disable-automatic-server-from-root-path } Se você não quiser que o **FastAPI** inclua um servidor automático usando o `root_path`, você pode usar o parâmetro `root_path_in_servers=False`: diff --git a/docs/pt/docs/advanced/dataclasses.md b/docs/pt/docs/advanced/dataclasses.md index f1cc5a0..2c1b08d 100644 --- a/docs/pt/docs/advanced/dataclasses.md +++ b/docs/pt/docs/advanced/dataclasses.md @@ -6,7 +6,7 @@ Mas o FastAPI também suporta o uso de [`dataclasses`](https://docs.python.org/3 {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -Isso ainda é suportado graças ao **Pydantic**, pois ele tem [suporte interno para `dataclasses`](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel). +Isso ainda é suportado graças ao **Pydantic**, pois ele tem [suporte interno para `dataclasses`](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/#usage-of-stdlib-dataclasses-with-basemodel). Então, mesmo com o código acima que não usa Pydantic explicitamente, o FastAPI está usando Pydantic para converter essas dataclasses padrão para a própria versão de dataclasses do Pydantic. @@ -88,7 +88,7 @@ Confira as dicas de anotação no código acima para ver mais detalhes específi Você também pode combinar `dataclasses` com outros modelos Pydantic, herdar deles, incluí-los em seus próprios modelos, etc. -Para saber mais, confira a [documentação do Pydantic sobre dataclasses](https://docs.pydantic.dev/latest/concepts/dataclasses/). +Para saber mais, confira a [documentação do Pydantic sobre dataclasses](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/). ## Versão { #version } diff --git a/docs/pt/docs/advanced/events.md b/docs/pt/docs/advanced/events.md index eee4dc8..50fd900 100644 --- a/docs/pt/docs/advanced/events.md +++ b/docs/pt/docs/advanced/events.md @@ -1,6 +1,5 @@ # Eventos de lifespan { #lifespan-events } - Você pode definir a lógica (código) que deve ser executada antes da aplicação **inicializar**. Isso significa que esse código será executado **uma vez**, **antes** de a aplicação **começar a receber requisições**. Da mesma forma, você pode definir a lógica (código) que deve ser executada quando a aplicação estiver **encerrando**. Nesse caso, esse código será executado **uma vez**, **depois** de possivelmente ter tratado **várias requisições**. @@ -155,7 +154,7 @@ Por baixo, na especificação técnica do ASGI, isso é parte do [Protocolo Life /// note | Nota -Você pode ler mais sobre os manipuladores de `lifespan` do Starlette na [Documentação do Lifespan do Starlette](https://www.starlette.dev/lifespan/). +Você pode ler mais sobre os manipuladores de `lifespan` do Starlette na [Documentação do Lifespan do Starlette](https://starlette.dev/lifespan/). Incluindo como lidar com estado do lifespan que pode ser usado em outras áreas do seu código. diff --git a/docs/pt/docs/advanced/generate-clients.md b/docs/pt/docs/advanced/generate-clients.md index 975fb90..c007d35 100644 --- a/docs/pt/docs/advanced/generate-clients.md +++ b/docs/pt/docs/advanced/generate-clients.md @@ -12,7 +12,7 @@ Uma opção versátil é o [OpenAPI Generator](https://openapi-generator.tech/), Para **clientes TypeScript**, o [Hey API](https://heyapi.dev/) é uma solução feita sob medida, oferecendo uma experiência otimizada para o ecossistema TypeScript. -Você pode descobrir mais geradores de SDK em [OpenAPI.Tools](https://openapi.tools/#sdk). +Você pode descobrir mais geradores de SDK em [OpenAPI.Tools](https://openapi.tools/categories/sdk-generators). /// tip | Dica diff --git a/docs/pt/docs/advanced/middleware.md b/docs/pt/docs/advanced/middleware.md index 1f269da..5cfa093 100644 --- a/docs/pt/docs/advanced/middleware.md +++ b/docs/pt/docs/advanced/middleware.md @@ -8,7 +8,7 @@ Nesta seção, veremos como usar outros middlewares. ## Adicionando middlewares ASGI { #adding-asgi-middlewares } -Como o **FastAPI** é baseado no Starlette e implementa a especificação ASGI, você pode usar qualquer middleware ASGI. +Como o **FastAPI** é baseado no Starlette e implementa a especificação ASGI, você pode usar qualquer middleware ASGI. O middleware não precisa ser feito para o FastAPI ou Starlette para funcionar, desde que siga a especificação ASGI. @@ -91,7 +91,7 @@ Há muitos outros middlewares ASGI. Por exemplo: -* [`ProxyHeadersMiddleware` do Uvicorn](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) +* [`ProxyHeadersMiddleware` do Uvicorn](https://github.com/Kludex/uvicorn/blob/main/uvicorn/middleware/proxy_headers.py) * [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -Para checar outros middlewares disponíveis, confira [Documentação de Middlewares do Starlette](https://www.starlette.dev/middleware/) e a [Lista Incrível do ASGI](https://github.com/florimondmanca/awesome-asgi). +Para checar outros middlewares disponíveis, confira [Documentação de Middlewares do Starlette](https://starlette.dev/middleware/) e a [Lista Incrível do ASGI](https://github.com/florimondmanca/awesome-asgi). diff --git a/docs/pt/docs/advanced/openapi-callbacks.md b/docs/pt/docs/advanced/openapi-callbacks.md index 08877e4..be50458 100644 --- a/docs/pt/docs/advanced/openapi-callbacks.md +++ b/docs/pt/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ Essa parte é bastante normal, a maior parte do código provavelmente já é fam /// tip | Dica -O parâmetro de consulta `callback_url` usa um tipo Pydantic [Url](https://docs.pydantic.dev/latest/api/networks/). +O parâmetro de consulta `callback_url` usa um tipo Pydantic [Url](https://pydantic.dev/docs/validation/latest/api/pydantic/networks/). /// @@ -106,11 +106,11 @@ Ela deve parecer exatamente como uma *operação de rota* normal do FastAPI: Há 2 diferenças principais de uma *operação de rota* normal: * Ela não necessita ter nenhum código real, porque sua aplicação nunca chamará esse código. Ele é usado apenas para documentar a *API externa*. Então, a função poderia ter apenas `pass`. -* O *path* pode conter uma [expressão OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) (veja mais abaixo) em que pode usar variáveis com parâmetros e partes do request original enviado para *sua API*. +* O *path* pode conter uma [expressão OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression) (veja mais abaixo) em que pode usar variáveis com parâmetros e partes do request original enviado para *sua API*. ### A expressão do path do callback { #the-callback-path-expression } -O *path* do callback pode ter uma [expressão OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) que pode conter partes do request original enviado para *sua API*. +O *path* do callback pode ter uma [expressão OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression) que pode conter partes do request original enviado para *sua API*. Nesse caso, é a `str`: diff --git a/docs/pt/docs/advanced/response-cookies.md b/docs/pt/docs/advanced/response-cookies.md index e775027..2ccf5e1 100644 --- a/docs/pt/docs/advanced/response-cookies.md +++ b/docs/pt/docs/advanced/response-cookies.md @@ -48,4 +48,4 @@ E como o `Response` pode ser usado frequentemente para definir cabeçalhos e coo /// -Para ver todos os parâmetros e opções disponíveis, verifique a [documentação no Starlette](https://www.starlette.dev/responses/#set-cookie). +Para ver todos os parâmetros e opções disponíveis, verifique a [documentação no Starlette](https://starlette.dev/responses/#set-cookie). diff --git a/docs/pt/docs/advanced/response-headers.md b/docs/pt/docs/advanced/response-headers.md index 08a1b67..5592c61 100644 --- a/docs/pt/docs/advanced/response-headers.md +++ b/docs/pt/docs/advanced/response-headers.md @@ -1,6 +1,5 @@ # Cabeçalhos de resposta { #response-headers } - ## Use um parâmetro `Response` { #use-a-response-parameter } Você pode declarar um parâmetro do tipo `Response` na sua *função de operação de rota* (assim como você pode fazer para cookies). @@ -39,4 +38,4 @@ E como a `Response` pode ser usada frequentemente para definir cabeçalhos e coo Tenha em mente que cabeçalhos personalizados proprietários podem ser adicionados [usando o prefixo `X-`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). -Porém, se você tiver cabeçalhos personalizados que deseja que um cliente no navegador possa ver, você precisa adicioná-los às suas configurações de CORS (saiba mais em [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)), usando o parâmetro `expose_headers` descrito na [documentação de CORS do Starlette](https://www.starlette.dev/middleware/#corsmiddleware). +Porém, se você tiver cabeçalhos personalizados que deseja que um cliente no navegador possa ver, você precisa adicioná-los às suas configurações de CORS (saiba mais em [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)), usando o parâmetro `expose_headers` descrito na [documentação de CORS do Starlette](https://starlette.dev/middleware/#corsmiddleware). diff --git a/docs/pt/docs/advanced/settings.md b/docs/pt/docs/advanced/settings.md index 029290a..7224a8e 100644 --- a/docs/pt/docs/advanced/settings.md +++ b/docs/pt/docs/advanced/settings.md @@ -1,36 +1,39 @@ # Configurações e Variáveis de Ambiente { #settings-and-environment-variables } - Em muitos casos, sua aplicação pode precisar de configurações externas, por exemplo chaves secretas, credenciais de banco de dados, credenciais para serviços de e-mail, etc. A maioria dessas configurações é variável (pode mudar), como URLs de banco de dados. E muitas podem ser sensíveis, como segredos. Por esse motivo, é comum fornecê-las em variáveis de ambiente lidas pela aplicação. +Uma **variável de ambiente** (também conhecida como **env var**) é um valor que existe fora do código Python, no sistema operacional, e pode ser lido pela sua aplicação e por outros programas. + +Você pode criar uma variável de ambiente para um comando ao executá-lo. Você verá os comandos específicos de cada plataforma abaixo. + /// tip | Dica -Para entender variáveis de ambiente, você pode ler [Variáveis de Ambiente](../environment-variables.md). +Leia o [guia de Variáveis de Ambiente](https://tiangolo.com/guides/environment-variables/) para uma explicação detalhada de como variáveis de ambiente funcionam. /// ## Tipagem e validação { #types-and-validation } -Essas variáveis de ambiente só conseguem lidar com strings de texto, pois são externas ao Python e precisam ser compatíveis com outros programas e com o resto do sistema (e até com diferentes sistemas operacionais, como Linux, Windows, macOS). +Essas variáveis de ambiente só conseguem lidar com strings de texto, pois são externas ao Python e precisam ser compatíveis com outros programas e com o resto do sistema (e até com diferentes sistemas operacionais, como Linux, Windows e macOS). Isso significa que qualquer valor lido em Python a partir de uma variável de ambiente será uma `str`, e qualquer conversão para um tipo diferente ou validação precisa ser feita em código. ## Pydantic `Settings` { #pydantic-settings } -Felizmente, o Pydantic fornece uma ótima utilidade para lidar com essas configurações vindas de variáveis de ambiente com [Pydantic: Settings management](https://docs.pydantic.dev/latest/concepts/pydantic_settings/). +Felizmente, o Pydantic fornece uma ótima utilidade para lidar com essas configurações vindas de variáveis de ambiente com [Pydantic: Settings management](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/). ### Instalar `pydantic-settings` { #install-pydantic-settings } -Primeiro, certifique-se de criar seu [ambiente virtual](../virtual-environments.md), ativá-lo e então instalar o pacote `pydantic-settings`: +Adicione o pacote `pydantic-settings` ao seu projeto:
```console -$ pip install pydantic-settings +$ uv add pydantic-settings ---> 100% ``` @@ -41,7 +44,7 @@ Ele também vem incluído quando você instala os extras `all` com:
```console -$ pip install "fastapi[all]" +$ uv add "fastapi[all]" ---> 100% ``` @@ -77,19 +80,39 @@ Depois você pode usar o novo objeto `settings` na sua aplicação: Em seguida, você executaria o servidor passando as configurações como variáveis de ambiente, por exemplo, você poderia definir `ADMIN_EMAIL` e `APP_NAME` com: +//// tab | Linux, macOS, Windows Bash +
```console -$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py +$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uv run fastapi run main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
+//// + +//// tab | Windows PowerShell + +
+ +```console +$ $Env:ADMIN_EMAIL = "deadpool@example.com" +$ $Env:APP_NAME = "ChimichangApp" +$ uv run fastapi run main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +//// + /// tip | Dica -Para definir várias variáveis de ambiente para um único comando, basta separá-las com espaço e colocá-las todas antes do comando. +No Bash, para definir várias env vars para um único comando, separe-as com espaço e coloque todas antes do comando. /// @@ -173,11 +196,11 @@ Mas um arquivo dotenv não precisa ter exatamente esse nome de arquivo. /// -O Pydantic tem suporte para leitura desses tipos de arquivos usando uma biblioteca externa. Você pode ler mais em [Pydantic Settings: Dotenv (.env) support](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support). +O Pydantic tem suporte para leitura desses tipos de arquivos usando uma biblioteca externa. Você pode ler mais em [Pydantic Settings: suporte a Dotenv (.env)](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#dotenv-env-support). /// tip | Dica -Para isso funcionar, você precisa executar `pip install python-dotenv`. +Para isso funcionar, adicione `python-dotenv` ao seu projeto com `uv add python-dotenv`. /// @@ -198,7 +221,7 @@ E então atualizar seu `config.py` com: /// tip | Dica -O atributo `model_config` é usado apenas para configuração do Pydantic. Você pode ler mais em [Pydantic: Concepts: Configuration](https://docs.pydantic.dev/latest/concepts/config/). +O atributo `model_config` é usado apenas para configuração do Pydantic. Você pode ler mais em [Pydantic: Conceitos: Configuração](https://pydantic.dev/docs/validation/latest/concepts/config/). /// @@ -296,7 +319,7 @@ Dessa forma, ela se comporta quase como se fosse apenas uma variável global. Ma ## Recapitulando { #recap } -Você pode usar Pydantic Settings para lidar com as configurações da sua aplicação, com todo o poder dos modelos Pydantic. +Você pode usar Pydantic Settings para lidar com as definições ou configurações da sua aplicação, com todo o poder dos modelos Pydantic. * Usando uma dependência você pode simplificar os testes. * Você pode usar arquivos `.env` com ele. diff --git a/docs/pt/docs/advanced/sub-applications.md b/docs/pt/docs/advanced/sub-applications.md index 1a82b02..c5a393c 100644 --- a/docs/pt/docs/advanced/sub-applications.md +++ b/docs/pt/docs/advanced/sub-applications.md @@ -35,7 +35,7 @@ Agora, execute o comando `fastapi`:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/pt/docs/advanced/templates.md b/docs/pt/docs/advanced/templates.md index d3a8ad9..dd71f59 100644 --- a/docs/pt/docs/advanced/templates.md +++ b/docs/pt/docs/advanced/templates.md @@ -8,12 +8,12 @@ Existem utilitários para configurá-lo facilmente que você pode usar diretamen ## Instalar dependências { #install-dependencies } -Certifique-se de criar um [ambiente virtual](../virtual-environments.md), ativá-lo e instalar `jinja2`: +Adicione `jinja2` ao seu projeto:
```console -$ pip install jinja2 +$ uv add jinja2 ---> 100% ``` @@ -24,22 +24,22 @@ $ pip install jinja2 * Importe `Jinja2Templates`. * Crie um objeto `templates` que você possa reutilizar posteriormente. -* Declare um parâmetro `Request` no *path operation* que retornará um template. -* Use o `templates` que você criou para renderizar e retornar uma `TemplateResponse`, passe o nome do template, o objeto `request` e um dicionário "context" com pares chave-valor a serem usados dentro do template do Jinja2. +* Declare um parâmetro `Request` na *operação de rota* que retornará um template. +* Use o `templates` que você criou para renderizar e retornar uma `TemplateResponse`, passe o nome do template, o objeto request e um dicionário "context" com pares chave-valor a serem usados dentro do template do Jinja2. {* ../../docs_src/templates/tutorial001_py310.py hl[4,11,15:18] *} /// note | Nota -Antes do FastAPI 0.108.0, Starlette 0.29.0, `name` era o primeiro parâmetro. +Antes do FastAPI 0.108.0, Starlette 0.29.0, o `name` era o primeiro parâmetro. -Além disso, em versões anteriores, o objeto `request` era passado como parte dos pares chave-valor no "context" dict para o Jinja2. +Além disso, antes disso, em versões anteriores, o objeto `request` era passado como parte dos pares chave-valor no context para o Jinja2. /// /// tip | Dica -Ao declarar `response_class=HTMLResponse`, a documentação entenderá que a resposta será HTML. +Ao declarar `response_class=HTMLResponse`, a interface da documentação poderá saber que a resposta será HTML. /// @@ -53,7 +53,7 @@ Você também poderia usar `from starlette.templating import Jinja2Templates`. ## Escrevendo templates { #writing-templates } -Então você pode escrever um template em `templates/item.html`, por exemplo: +Então você pode escrever um template em `templates/item.html` com, por exemplo: ```jinja hl_lines="7" {!../../docs_src/templates/templates/item.html!} @@ -77,7 +77,7 @@ Item ID: {{ id }} {"id": id} ``` -Por exemplo, dado um ID de valor `42`, aparecerá: +Por exemplo, com um ID de `42`, isso renderizará: ```html Item ID: 42 @@ -85,7 +85,7 @@ Item ID: 42 ### Argumentos do `url_for` no template { #template-url-for-arguments } -Você também pode usar `url_for()` dentro do template, ele recebe como argumentos os mesmos argumentos que seriam usados pela sua *path operation function*. +Você também pode usar `url_for()` dentro do template, ele recebe como argumentos os mesmos argumentos que seriam usados pela sua *função de operação de rota*. Logo, a seção com: @@ -97,7 +97,7 @@ Logo, a seção com: {% endraw %} -...irá gerar um link para a mesma URL que será tratada pela *path operation function* `read_item(id=id)`. +...irá gerar um link para a mesma URL que será tratada pela *função de operação de rota* `read_item(id=id)`. Por exemplo, com um ID de `42`, isso renderizará: @@ -123,4 +123,4 @@ E como você está usando `StaticFiles`, este arquivo CSS será automaticamente ## Mais detalhes { #more-details } -Para obter mais detalhes, incluindo como testar templates, consulte a [documentação da Starlette sobre templates](https://www.starlette.dev/templates/). +Para obter mais detalhes, incluindo como testar templates, consulte a [documentação da Starlette sobre templates](https://starlette.dev/templates/). diff --git a/docs/pt/docs/advanced/testing-events.md b/docs/pt/docs/advanced/testing-events.md index 56c5d45..d2e6b53 100644 --- a/docs/pt/docs/advanced/testing-events.md +++ b/docs/pt/docs/advanced/testing-events.md @@ -4,7 +4,8 @@ Quando você precisa que o `lifespan` seja executado em seus testes, você pode {* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *} -Você pode ler mais detalhes sobre o ["Executando lifespan em testes no site oficial da documentação do Starlette."](https://www.starlette.dev/lifespan/#running-lifespan-in-tests) + +Você pode ler mais detalhes sobre o ["Executando lifespan em testes no site oficial da documentação do Starlette."](https://starlette.dev/lifespan/#running-lifespan-in-tests) Para os eventos `startup` e `shutdown` descontinuados, você pode usar o `TestClient` da seguinte forma: diff --git a/docs/pt/docs/advanced/testing-websockets.md b/docs/pt/docs/advanced/testing-websockets.md index f562372..6ac6f2d 100644 --- a/docs/pt/docs/advanced/testing-websockets.md +++ b/docs/pt/docs/advanced/testing-websockets.md @@ -8,6 +8,6 @@ Para isso, você utiliza o `TestClient` dentro de uma instrução `with`, conect /// note | Nota -Para mais detalhes, confira a documentação do Starlette para [testar WebSockets](https://www.starlette.dev/testclient/#testing-websocket-sessions). +Para mais detalhes, confira a documentação do Starlette para [testar WebSockets](https://starlette.dev/testclient/#testing-websocket-sessions). /// diff --git a/docs/pt/docs/advanced/using-request-directly.md b/docs/pt/docs/advanced/using-request-directly.md index 14eac2b..e443daa 100644 --- a/docs/pt/docs/advanced/using-request-directly.md +++ b/docs/pt/docs/advanced/using-request-directly.md @@ -15,13 +15,13 @@ Porém há situações em que você possa precisar acessar o objeto `Request` di ## Detalhes sobre o objeto `Request` { #details-about-the-request-object } -Como o **FastAPI** é na verdade o **Starlette** por baixo, com camadas de diversas funcionalidades por cima, você pode utilizar o objeto [`Request`](https://www.starlette.dev/requests/) do Starlette diretamente quando precisar. +Como o **FastAPI** é na verdade o **Starlette** por baixo, com camadas de diversas funcionalidades por cima, você pode utilizar o objeto [`Request`](https://starlette.dev/requests/) do Starlette diretamente quando precisar. Isso significaria também que se você obtiver informações do objeto `Request` diretamente (ler o corpo da requisição por exemplo), as informações não serão validadas, convertidas ou documentadas (com o OpenAPI, para a interface de usuário automática da API) pelo FastAPI. Embora qualquer outro parâmetro declarado normalmente (o corpo da requisição com um modelo Pydantic, por exemplo) ainda seria validado, convertido, anotado, etc. -Mas há situações específicas onde é útil utilizar o objeto `Request`. +Mas há situações específicas onde é útil obter o objeto `Request`. ## Utilize o objeto `Request` diretamente { #use-the-request-object-directly } @@ -45,7 +45,7 @@ Do mesmo jeito, você pode declarar qualquer outro parâmetro normalmente, e al ## Documentação do `Request` { #request-documentation } -Você pode ler mais sobre os detalhes do [objeto `Request` no site da documentação oficial do Starlette](https://www.starlette.dev/requests/). +Você pode ler mais sobre os detalhes do [objeto `Request` no site da documentação oficial do Starlette](https://starlette.dev/requests/). /// note | Detalhes Técnicos diff --git a/docs/pt/docs/advanced/websockets.md b/docs/pt/docs/advanced/websockets.md index 5367a91..f0ed9df 100644 --- a/docs/pt/docs/advanced/websockets.md +++ b/docs/pt/docs/advanced/websockets.md @@ -4,12 +4,12 @@ Você pode usar [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/We ## Instale `websockets` { #install-websockets } -Garanta que você criou um [ambiente virtual](../virtual-environments.md), o ativou e instalou o `websockets` (uma biblioteca Python que facilita o uso do protocolo "WebSocket"): +Adicione `websockets` (uma biblioteca Python que facilita o uso do protocolo "WebSocket") ao seu projeto:
```console -$ pip install websockets +$ uv add websockets ---> 100% ``` @@ -69,7 +69,7 @@ Coloque seu código em um arquivo `main.py` e então execute sua aplicação:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -126,7 +126,7 @@ Execute sua aplicação:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -182,5 +182,5 @@ Se você precisa de algo fácil de integrar com o FastAPI, mas que seja mais rob Para aprender mais sobre as opções, verifique a documentação do Starlette para: -* [A classe `WebSocket`](https://www.starlette.dev/websockets/). -* [Manipulação de WebSockets baseada em classes](https://www.starlette.dev/endpoints/#websocketendpoint). +* [A classe `WebSocket`](https://starlette.dev/websockets/). +* [Manipulação de WebSockets baseada em classes](https://starlette.dev/endpoints/#websocketendpoint). diff --git a/docs/pt/docs/advanced/wsgi.md b/docs/pt/docs/advanced/wsgi.md index fafa147..b6ca598 100644 --- a/docs/pt/docs/advanced/wsgi.md +++ b/docs/pt/docs/advanced/wsgi.md @@ -1,4 +1,4 @@ -# Adicionando WSGI - Flask, Django, entre outros { #including-wsgi-flask-django-others } +# Incluindo WSGI - Flask, Django, entre outros { #including-wsgi-flask-django-others } Como você viu em [Subaplicações - Montagens](sub-applications.md) e [Atrás de um Proxy](behind-a-proxy.md), você pode montar aplicações WSGI. @@ -9,7 +9,7 @@ Para isso, você pode utilizar o `WSGIMiddleware` para encapsular a sua aplicaç /// note | Nota -Isso requer instalar `a2wsgi`, por exemplo com `pip install a2wsgi`. +Isso requer adicionar `a2wsgi` ao seu projeto, por exemplo com `uv add a2wsgi`. /// @@ -37,13 +37,13 @@ Agora, todas as requisições sob o path `/v1/` serão manipuladas pela aplicaç E o resto será manipulado pelo **FastAPI**. -Se você rodar a aplicação e ir até [http://localhost:8000/v1/](http://localhost:8000/v1/), você verá o retorno do Flask: +Se você rodar a aplicação e ir até [http://localhost:8000/v1/](http://localhost:8000/v1/) você verá o retorno do Flask: ```txt Hello, World from Flask! ``` -E se você for até [http://localhost:8000/v2](http://localhost:8000/v2), você verá o retorno do FastAPI: +E se você for até [http://localhost:8000/v2](http://localhost:8000/v2) você verá o retorno do FastAPI: ```JSON { diff --git a/docs/pt/docs/alternatives.md b/docs/pt/docs/alternatives.md index 8a63a30..1cc1afd 100644 --- a/docs/pt/docs/alternatives.md +++ b/docs/pt/docs/alternatives.md @@ -68,11 +68,11 @@ Ter um sistema de roteamento simples e fácil de usar. **FastAPI** na verdade não é uma alternativa ao **Requests**. O escopo deles é muito diferente. -Na verdade, é comum utilizar Requests dentro de uma aplicação FastAPI. +Na verdade, é comum utilizar Requests *dentro* de uma aplicação FastAPI. Ainda assim, o FastAPI tirou bastante inspiração do Requests. -**Requests** é uma biblioteca para interagir com APIs (como um cliente), enquanto **FastAPI** é uma biblioteca para construir APIs (como um servidor). +**Requests** é uma biblioteca para *interagir* com APIs (como um cliente), enquanto **FastAPI** é uma biblioteca para *construir* APIs (como um servidor). Eles estão, mais ou menos, em pontas opostas, complementando-se. @@ -125,7 +125,7 @@ Adotar e usar um padrão aberto para especificações de API, em vez de um schem E integrar ferramentas de interface para usuários baseadas nos padrões: * [Swagger UI](https://github.com/swagger-api/swagger-ui) -* [ReDoc](https://github.com/Rebilly/ReDoc) +* [ReDoc](https://github.com/Redocly/redoc) Essas duas foram escolhidas por serem bem populares e estáveis, mas fazendo uma pesquisa rápida, você pode encontrar dúzias de interfaces alternativas adicionais para OpenAPI (que você pode utilizar com **FastAPI**). @@ -237,7 +237,7 @@ Gerar o schema OpenAPI automaticamente, a partir do mesmo código que define ser /// -### [NestJS](https://nestjs.com/) (e [Angular](https://angular.io/)) { #nestjs-and-angular } +### [NestJS](https://nestjs.com/) (e [Angular](https://angular.dev/)) { #nestjs-and-angular } Isso nem é Python, NestJS é um framework NodeJS em JavaScript (TypeScript) inspirado pelo Angular. @@ -337,7 +337,7 @@ Como é baseado no padrão anterior para frameworks web Python síncronos (WSGI) /// note | Nota -Hug foi criado por Timothy Crosley, o mesmo criador do [`isort`](https://github.com/timothycrosley/isort), uma ótima ferramenta para ordenar automaticamente imports em arquivos Python. +Hug foi criado por Timothy Crosley, o mesmo criador do [`isort`](https://github.com/PyCQA/isort), uma ótima ferramenta para ordenar automaticamente imports em arquivos Python. /// @@ -401,7 +401,7 @@ Eu considero o **FastAPI** um "sucessor espiritual" do APIStar, enquanto aprimor ## Usados por **FastAPI** { #used-by-fastapi } -### [Pydantic](https://docs.pydantic.dev/) { #pydantic } +### [Pydantic](https://pydantic.dev/docs/) { #pydantic } Pydantic é uma biblioteca para definir validação de dados, serialização e documentação (usando JSON Schema) com base nas anotações de tipo do Python. @@ -417,7 +417,7 @@ Controlar toda a validação de dados, serialização de dados e documentação /// -### [Starlette](https://www.starlette.dev/) { #starlette } +### [Starlette](https://starlette.dev/) { #starlette } Starlette é um framework/caixa de ferramentas ASGI leve, o que é ideal para construir serviços asyncio de alta performance. @@ -462,7 +462,7 @@ Então, qualquer coisa que você pode fazer com Starlette, você pode fazer dire /// -### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn } +### [Uvicorn](https://uvicorn.dev) { #uvicorn } Uvicorn é um servidor ASGI extremamente rápido, construído com uvloop e httptools. diff --git a/docs/pt/docs/deployment/docker.md b/docs/pt/docs/deployment/docker.md index f687848..b179104 100644 --- a/docs/pt/docs/deployment/docker.md +++ b/docs/pt/docs/deployment/docker.md @@ -105,36 +105,32 @@ Isso é o que você quer fazer na **maioria dos casos**, por exemplo: ### Requisitos de Pacotes { #package-requirements } -Você normalmente teria os **requisitos de pacotes** da sua aplicação em algum arquivo. +Quando você gerencia seu projeto com `uv`, suas dependências diretas são declaradas em `pyproject.toml` e as versões resolvidas exatas são armazenadas em `uv.lock`. -Isso pode depender principalmente da ferramenta que você usa para **instalar** esses requisitos. - -A forma mais comum de fazer isso é ter um arquivo `requirements.txt` com os nomes dos pacotes e suas versões, um por linha. - -Você, naturalmente, usaria as mesmas ideias que você leu em [Sobre versões do FastAPI](versions.md) para definir os intervalos de versões. - -Por exemplo, seu `requirements.txt` poderia parecer com: - -``` -fastapi[standard]>=0.113.0,<0.114.0 -pydantic>=2.7.0,<3.0.0 -``` - -E você normalmente instalaria essas dependências de pacote com `pip`, por exemplo: +Você pode adicionar os pacotes de que sua aplicação precisa com:
```console -$ pip install -r requirements.txt +$ uv add "fastapi[standard]" pydantic ---> 100% -Successfully installed fastapi pydantic ```
/// note | Nota -Há outros formatos e ferramentas para definir e instalar dependências de pacotes. +O Dockerfile abaixo usa `pip` dentro do contêiner. Você pode exportar as dependências bloqueadas do seu projeto uv para o formato `requirements.txt` esperado por ele: + +
+ +```console +$ uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt +``` + +
+ +O `requirements.txt` gerado é uma exportação para a construção do contêiner. Continue gerenciando dependências com `uv add` e gere-o novamente quando `uv.lock` mudar. /// @@ -372,7 +368,7 @@ Você verá a documentação interativa automática da API (fornecida pelo [Swag E você também pode ir para [http://192.168.99.100/redoc](http://192.168.99.100/redoc) ou [http://127.0.0.1/redoc](http://127.0.0.1/redoc) (ou equivalente, usando seu host Docker). -Você verá a documentação alternativa automática (fornecida pelo [ReDoc](https://github.com/Rebilly/ReDoc)): +Você verá a documentação alternativa automática (fornecida pelo [ReDoc](https://github.com/Redocly/redoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) diff --git a/docs/pt/docs/deployment/fastapicloud.md b/docs/pt/docs/deployment/fastapicloud.md index 0504a44..2bf9b3d 100644 --- a/docs/pt/docs/deployment/fastapicloud.md +++ b/docs/pt/docs/deployment/fastapicloud.md @@ -5,7 +5,7 @@ Você pode implantar sua aplicação FastAPI no [FastAPI Cloud](https://fastapic
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... diff --git a/docs/pt/docs/deployment/manually.md b/docs/pt/docs/deployment/manually.md index 0c8db16..1b6878e 100644 --- a/docs/pt/docs/deployment/manually.md +++ b/docs/pt/docs/deployment/manually.md @@ -48,13 +48,13 @@ Vamos nos aprofundar um pouco mais em detalhes. FastAPI utiliza um padrão para construir frameworks e servidores web em Python chamado ASGI. FastAPI é um framework web ASGI. -A principal coisa que você precisa para executar uma aplicação **FastAPI** (ou qualquer outra aplicação ASGI) em uma máquina de servidor remoto é um programa de servidor ASGI como o **Uvicorn**, que é o que vem por padrão no comando `fastapi`. +A principal coisa que você precisa para executar uma aplicação **FastAPI** (ou qualquer outra aplicação ASGI) em uma máquina de servidor remoto é um programa de servidor ASGI como o **Uvicorn**, este é o que vem por padrão no comando `fastapi`. Existem diversas alternativas, incluindo: -* [Uvicorn](https://www.uvicorn.dev/): um servidor ASGI de alta performance. -* [Hypercorn](https://hypercorn.readthedocs.io/): um servidor ASGI compatível com HTTP/2, Trio e outras funcionalidades. -* [Daphne](https://github.com/django/daphne): servidor ASGI construído para Django Channels. +* [Uvicorn](https://uvicorn.dev): um servidor ASGI de alta performance. +* [Hypercorn](https://hypercorn.readthedocs.io/): um servidor ASGI compatível com HTTP/2 e Trio, entre outras funcionalidades. +* [Daphne](https://github.com/django/daphne): o servidor ASGI construído para Django Channels. * [Granian](https://github.com/emmett-framework/granian): um servidor HTTP Rust para aplicações Python. ## Máquina Servidora e Programa Servidor { #server-machine-and-server-program } @@ -73,14 +73,14 @@ Quando você instala o FastAPI, ele vem com um servidor de produção, o Uvicorn Mas você também pode instalar um servidor ASGI manualmente. -Certifique-se de criar um [ambiente virtual](../virtual-environments.md), ativá-lo e, em seguida, você pode instalar a aplicação do servidor. +Adicione a aplicação do servidor ao seu projeto. Por exemplo, para instalar o Uvicorn:
```console -$ pip install "uvicorn[standard]" +$ uv add "uvicorn[standard]" ---> 100% ``` @@ -95,7 +95,7 @@ Adicionando o `standard`, o Uvicorn instalará e usará algumas dependências ex Isso inclui o `uvloop`, a substituição de alto desempenho para `asyncio`, que fornece um grande aumento de desempenho de concorrência. -Quando você instala o FastAPI com algo como `pip install "fastapi[standard]"`, você já obtém `uvicorn[standard]` também. +Quando você adiciona o FastAPI com algo como `uv add "fastapi[standard]"`, você já obtém `uvicorn[standard]` também. /// @@ -106,7 +106,7 @@ Se você instalou um servidor ASGI manualmente, normalmente precisará passar um
```console -$ uvicorn main:app --host 0.0.0.0 --port 80 +$ uv run uvicorn main:app --host 0.0.0.0 --port 80 INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) ``` diff --git a/docs/pt/docs/deployment/server-workers.md b/docs/pt/docs/deployment/server-workers.md index 4d70de9..f12c63a 100644 --- a/docs/pt/docs/deployment/server-workers.md +++ b/docs/pt/docs/deployment/server-workers.md @@ -9,9 +9,9 @@ Vamos rever os conceitos de implantação anteriores: * Memória * Etapas anteriores antes de iniciar -Até este ponto, com todos os tutoriais nos documentos, você provavelmente estava executando um **programa de servidor**, por exemplo, usando o comando `fastapi`, que executa o Uvicorn, executando um **único processo**. +Até este ponto, com todos os tutoriais na documentação, você provavelmente estava executando um **programa de servidor**, por exemplo, usando o comando `fastapi`, que executa o Uvicorn, executando um **único processo**. -Ao implantar aplicativos, você provavelmente desejará ter alguma **replicação de processos** para aproveitar **vários núcleos** e poder lidar com mais solicitações. +Ao implantar aplicativos, você provavelmente desejará ter alguma **replicação de processos** para aproveitar **vários núcleos** e poder lidar com mais requests. Como você viu no capítulo anterior sobre [Conceitos de implantação](concepts.md), há várias estratégias que você pode usar. @@ -21,7 +21,7 @@ Aqui mostrarei como usar o **Uvicorn** com **processos de trabalho** usando o co Se você estiver usando contêineres, por exemplo com Docker ou Kubernetes, falarei mais sobre isso no próximo capítulo: [FastAPI em contêineres - Docker](docker.md). -Em particular, ao executar no **Kubernetes** você provavelmente **não** vai querer usar vários trabalhadores e, em vez disso, executar **um único processo Uvicorn por contêiner**, mas falarei sobre isso mais adiante neste capítulo. +Em particular, ao executar no **Kubernetes** você provavelmente **não** vai querer usar trabalhadores e, em vez disso, executar **um único processo Uvicorn por contêiner**, mas falarei sobre isso mais adiante naquele capítulo. /// @@ -86,7 +86,7 @@ Se você preferir usar o comando `uvicorn` diretamente:
```console -$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 +$ uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit) INFO: Started parent process [27365] INFO: Started server process [27368] @@ -113,7 +113,7 @@ Você também pode ver que ele mostra o **PID** de cada processo, `27365` para o ## Conceitos de Implantação { #deployment-concepts } -Aqui você viu como usar vários **trabalhadores** para **paralelizar** a execução do aplicativo, aproveitar **vários núcleos** na CPU e conseguir atender **mais solicitações**. +Aqui você viu como usar vários **trabalhadores** para **paralelizar** a execução do aplicativo, aproveitar **vários núcleos** na CPU e conseguir atender **mais requests**. Da lista de conceitos de implantação acima, o uso de trabalhadores ajudaria principalmente com a parte da **replicação** e um pouco com as **reinicializações**, mas você ainda precisa cuidar dos outros: diff --git a/docs/pt/docs/environment-variables.md b/docs/pt/docs/environment-variables.md index ebf037f..07f1611 100644 --- a/docs/pt/docs/environment-variables.md +++ b/docs/pt/docs/environment-variables.md @@ -1,298 +1,11 @@ # Variáveis de Ambiente { #environment-variables } -/// tip | Dica +Uma **variável de ambiente** (também conhecida como **env var**) é um valor que existe fora do seu código Python, no sistema operacional, e pode ser lido pela sua aplicação e por outros programas. -Se você já sabe o que são "variáveis de ambiente" e como usá-las, pode pular esta seção. +Aplicações FastAPI normalmente usam variáveis de ambiente para configuração, como URLs de bancos de dados, credenciais de email e chaves secretas. -/// +Você aprenderá como usá-las para configuração da aplicação em [Configurações e Variáveis de Ambiente](advanced/settings.md). -Uma variável de ambiente (também conhecida como "**env var**") é uma variável que existe **fora** do código Python, no **sistema operacional**, e pode ser lida pelo seu código Python (ou por outros programas também). +## Saiba Mais { #learn-more } -Variáveis de ambiente podem ser úteis para lidar com **configurações** do aplicativo, como parte da **instalação** do Python, etc. - -## Criar e Usar Variáveis de Ambiente { #create-and-use-env-vars } - -Você pode **criar** e usar variáveis de ambiente no **shell (terminal)**, sem precisar do Python: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// Você pode criar uma variável de ambiente MY_NAME com -$ export MY_NAME="Wade Wilson" - -// Então você pode usá-la com outros programas, como -$ echo "Hello $MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// Criar uma variável de ambiente MY_NAME -$ $Env:MY_NAME = "Wade Wilson" - -// Usá-la com outros programas, como -$ echo "Hello $Env:MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -## Ler Variáveis de Ambiente no Python { #read-env-vars-in-python } - -Você também pode criar variáveis de ambiente **fora** do Python, no terminal (ou com qualquer outro método) e depois **lê-las no Python**. - -Por exemplo, você poderia ter um arquivo `main.py` com: - -```Python hl_lines="3" -import os - -name = os.getenv("MY_NAME", "World") -print(f"Hello {name} from Python") -``` - -/// tip | Dica - -O segundo argumento para [`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) é o valor padrão a ser retornado. - -Se não for fornecido, é `None` por padrão, Aqui fornecemos `"World"` como o valor padrão a ser usado. - -/// - -Então você poderia chamar esse programa Python: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// Aqui ainda não definimos a variável de ambiente -$ python main.py - -// Como não definimos a variável de ambiente, obtemos o valor padrão - -Hello World from Python - -// Mas se criarmos uma variável de ambiente primeiro -$ export MY_NAME="Wade Wilson" - -// E então chamar o programa novamente -$ python main.py - -// Agora ele pode ler a variável de ambiente - -Hello Wade Wilson from Python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// Aqui ainda não definimos a variável de ambiente -$ python main.py - -// Como não definimos a variável de ambiente, obtemos o valor padrão - -Hello World from Python - -// Mas se criarmos uma variável de ambiente primeiro -$ $Env:MY_NAME = "Wade Wilson" - -// E então chamar o programa novamente -$ python main.py - -// Agora ele pode ler a variável de ambiente - -Hello Wade Wilson from Python -``` - -
- -//// - -Como as variáveis de ambiente podem ser definidas fora do código, mas podem ser lidas pelo código e não precisam ser armazenadas (com versão no `git`) com o restante dos arquivos, é comum usá-las para configurações ou **definições**. - -Você também pode criar uma variável de ambiente apenas para uma **invocação específica do programa**, que só está disponível para aquele programa e apenas pela duração dele. - -Para fazer isso, crie-a na mesma linha, antes do próprio programa: - -
- -```console -// Criar uma variável de ambiente MY_NAME para esta chamada de programa -$ MY_NAME="Wade Wilson" python main.py - -// Agora ele pode ler a variável de ambiente - -Hello Wade Wilson from Python - -// A variável de ambiente não existe mais depois -$ python main.py - -Hello World from Python -``` - -
- -/// tip | Dica - -Você pode ler mais sobre isso em [The Twelve-Factor App: Config](https://12factor.net/config). - -/// - -## Tipos e Validação { #types-and-validation } - -Essas variáveis de ambiente só podem lidar com **strings de texto**, pois são externas ao Python e precisam ser compatíveis com outros programas e com o resto do sistema (e até mesmo com diferentes sistemas operacionais, como Linux, Windows, macOS). - -Isso significa que **qualquer valor** lido em Python de uma variável de ambiente **será uma `str`**, e qualquer conversão para um tipo diferente ou qualquer validação precisa ser feita no código. - -Você aprenderá mais sobre como usar variáveis de ambiente para lidar com **configurações do aplicativo** no [Guia do Usuário Avançado - Configurações e Variáveis de Ambiente](./advanced/settings.md). - -## Variável de Ambiente `PATH` { #path-environment-variable } - -Existe uma variável de ambiente **especial** chamada **`PATH`** que é usada pelos sistemas operacionais (Linux, macOS, Windows) para encontrar programas para executar. - -O valor da variável `PATH` é uma longa string composta por diretórios separados por dois pontos `:` no Linux e macOS, e por ponto e vírgula `;` no Windows. - -Por exemplo, a variável de ambiente `PATH` poderia ter esta aparência: - -//// tab | Linux, macOS - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -Isso significa que o sistema deve procurar programas nos diretórios: - -* `/usr/local/bin` -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32 -``` - -Isso significa que o sistema deve procurar programas nos diretórios: - -* `C:\Program Files\Python312\Scripts` -* `C:\Program Files\Python312` -* `C:\Windows\System32` - -//// - -Quando você digita um **comando** no terminal, o sistema operacional **procura** o programa em **cada um dos diretórios** listados na variável de ambiente `PATH`. - -Por exemplo, quando você digita `python` no terminal, o sistema operacional procura um programa chamado `python` no **primeiro diretório** dessa lista. - -Se ele o encontrar, então ele o **usará**. Caso contrário, ele continua procurando nos **outros diretórios**. - -### Instalando o Python e Atualizando o `PATH` { #installing-python-and-updating-the-path } - -Durante a instalação do Python, você pode ser questionado sobre a atualização da variável de ambiente `PATH`. - -//// tab | Linux, macOS - -Vamos supor que você instale o Python e ele fique em um diretório `/opt/custompython/bin`. - -Se você concordar em atualizar a variável de ambiente `PATH`, o instalador adicionará `/opt/custompython/bin` para a variável de ambiente `PATH`. - -Poderia parecer assim: - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin -``` - -Dessa forma, ao digitar `python` no terminal, o sistema encontrará o programa Python em `/opt/custompython/bin` (último diretório) e o utilizará. - -//// - -//// tab | Windows - -Digamos que você instala o Python e ele acaba em um diretório `C:\opt\custompython\bin`. - -Se você disser sim para atualizar a variável de ambiente `PATH`, o instalador adicionará `C:\opt\custompython\bin` à variável de ambiente `PATH`. - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin -``` - -Dessa forma, quando você digitar `python` no terminal, o sistema encontrará o programa Python em `C:\opt\custompython\bin` (o último diretório) e o utilizará. - -//// - -Então, se você digitar: - -
- -```console -$ python -``` - -
- -//// tab | Linux, macOS - -O sistema **encontrará** o programa `python` em `/opt/custompython/bin` e o executará. - -Seria aproximadamente equivalente a digitar: - -
- -```console -$ /opt/custompython/bin/python -``` - -
- -//// - -//// tab | Windows - -O sistema **encontrará** o programa `python` em `C:\opt\custompython\bin\python` e o executará. - -Seria aproximadamente equivalente a digitar: - -
- -```console -$ C:\opt\custompython\bin\python -``` - -
- -//// - -Essas informações serão úteis ao aprender sobre [Ambientes Virtuais](virtual-environments.md). - -## Conclusão { #conclusion } - -Com isso, você deveria ter uma compreensão básica do que são **variáveis ​​de ambiente** e como usá-las em Python. - -Você também pode ler mais sobre elas na [Wikipedia para Variáveis ​​de Ambiente](https://en.wikipedia.org/wiki/Environment_variable). - -Em muitos casos, não é muito óbvio como as variáveis ​​de ambiente seriam úteis e aplicáveis ​​imediatamente. Mas elas continuam aparecendo em muitos cenários diferentes quando você está desenvolvendo, então é bom saber sobre elas. - -Por exemplo, você precisará dessas informações na próxima seção, sobre [Ambientes Virtuais](virtual-environments.md). +Leia o [guia de Variáveis de Ambiente](https://tiangolo.com/guides/environment-variables/) para uma explicação detalhada e multiplataforma, incluindo como criar e ler variáveis de ambiente e como a variável de ambiente `PATH` funciona. diff --git a/docs/pt/docs/fastapi-cli.md b/docs/pt/docs/fastapi-cli.md index 1061152..2e4b762 100644 --- a/docs/pt/docs/fastapi-cli.md +++ b/docs/pt/docs/fastapi-cli.md @@ -2,7 +2,7 @@ **FastAPI CLI** é um programa de linha de comando que você pode usar para servir sua aplicação FastAPI, gerenciar seu projeto FastAPI e muito mais. -Quando você instala o FastAPI (por exemplo, com `pip install "fastapi[standard]"`), ele vem com um programa de linha de comando que você pode executar no terminal. +Quando você adiciona o FastAPI ao seu projeto (por exemplo, com `uv add "fastapi[standard]"`), ele vem com um programa de linha de comando que você pode executar no terminal. Para executar sua aplicação FastAPI durante o desenvolvimento, você pode usar o comando `fastapi dev`: @@ -52,7 +52,7 @@ Em produção, você usaria `fastapi run` em vez de `fastapi dev`. 🚀 /// -Internamente, o **FastAPI CLI** usa o [Uvicorn](https://www.uvicorn.dev), um servidor ASGI de alta performance e pronto para produção. 😎 +Internamente, o **FastAPI CLI** usa o [Uvicorn](https://uvicorn.dev), um servidor ASGI de alta performance e pronto para produção. 😎 O CLI `fastapi` tentará detectar automaticamente a aplicação FastAPI a ser executada, assumindo que seja um objeto chamado `app` em um arquivo `main.py` (ou algumas outras variantes). @@ -100,13 +100,13 @@ from backend.main import app Você também pode passar o caminho do arquivo para o comando `fastapi dev`, e ele deduzirá o objeto da aplicação FastAPI a usar: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` Ou, você também pode passar a opção `--entrypoint` para o comando `fastapi dev`: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` Mas você teria que lembrar de passar o caminho\entrypoint correto toda vez que chamar o comando `fastapi`. @@ -119,13 +119,17 @@ Executar `fastapi dev` inicia o modo de desenvolvimento. Por padrão, o **recarregamento automático** está ativado, recarregando o servidor automaticamente quando você faz mudanças no seu código. Isso consome muitos recursos e pode ser menos estável do que quando está desativado. Você deveria usá-lo apenas no desenvolvimento. Ele também escuta no endereço IP `127.0.0.1`, que é o IP para a sua máquina se comunicar apenas consigo mesma (`localhost`). +Antes de importar sua aplicação, `fastapi dev` define a variável de ambiente `FASTAPI_ENV` como `development`. Se `FASTAPI_ENV` já estiver definida, seu valor existente é preservado. Isso permite que o código de inicialização da aplicação escolha um comportamento adequado para desenvolvimento, ao mesmo tempo que permite fornecer um ambiente específico da aplicação, como `staging`. + +Os valores convencionais de `FASTAPI_ENV` são `development` e `production`. Atualmente, `fastapi run` deixa `FASTAPI_ENV` inalterada, então defina-a explicitamente se sua aplicação precisar detectar o modo de produção. + ## `fastapi run` { #fastapi-run } Executar `fastapi run` inicia o FastAPI em modo de produção. -Por padrão, o **recarregamento automático** está desativado. Ele também escuta no endereço IP `0.0.0.0`, o que significa todos os endereços IP disponíveis; dessa forma, ficará acessível publicamente para qualquer pessoa que consiga se comunicar com a máquina. É assim que você normalmente o executaria em produção, por exemplo, em um contêiner. +Por padrão, **auto-reload** está desativado. Ele também escuta no endereço IP `0.0.0.0`, o que significa todos os endereços IP disponíveis; dessa forma, ficará acessível publicamente para qualquer pessoa que consiga se comunicar com a máquina. É assim que você normalmente o executaria em produção, por exemplo, em um contêiner. -Na maioria dos casos, você teria (e você deveria ter) um "proxy de terminação" tratando o HTTPS por cima; isso dependerá de como você faz o deploy da sua aplicação, seu provedor pode fazer isso por você ou talvez seja necessário que você configure isso por conta própria. +Na maioria dos casos, você teria (e deveria ter) um "proxy de terminação" tratando o HTTPS por cima; isso dependerá de como você faz o deploy da sua aplicação, seu provedor pode fazer isso por você ou talvez seja necessário que você configure por conta própria. /// tip | Dica diff --git a/docs/pt/docs/features.md b/docs/pt/docs/features.md index 846bc7f..d010fc0 100644 --- a/docs/pt/docs/features.md +++ b/docs/pt/docs/features.md @@ -19,7 +19,7 @@ Documentação interativa da API e navegação web da interface de usuário. Com ![Interação Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* Documentação alternativa da API com [**ReDoc**](https://github.com/Rebilly/ReDoc). +* Documentação alternativa da API com [**ReDoc**](https://github.com/Redocly/redoc). ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) @@ -159,7 +159,7 @@ Qualquer integração é projetada para ser tão simples de usar (com dependênc ## Funcionalidades do Starlette { #starlette-features } -**FastAPI** é totalmente compatível com (e baseado no) [**Starlette**](https://www.starlette.dev/). Então, qualquer código adicional Starlette que você tiver, também funcionará. +**FastAPI** é totalmente compatível com (e baseado no) [**Starlette**](https://starlette.dev/). Então, qualquer código adicional Starlette que você tiver, também funcionará. `FastAPI` é na verdade uma sub-classe do `Starlette`. Então, se você já conhece ou usa Starlette, a maioria das funcionalidades se comportará da mesma forma. @@ -177,7 +177,7 @@ Com **FastAPI**, você terá todas as funcionalidades do **Starlette** (já que ## Funcionalidades do Pydantic { #pydantic-features } -**FastAPI** é totalmente compatível com (e baseado no) [**Pydantic**](https://docs.pydantic.dev/). Então, qualquer código Pydantic adicional que você tiver, também funcionará. +**FastAPI** é totalmente compatível com (e baseado no) [**Pydantic**](https://pydantic.dev/docs/). Então, qualquer código Pydantic adicional que você tiver, também funcionará. Incluindo bibliotecas externas também baseadas no Pydantic, como ORMs e ODMs para bancos de dados. diff --git a/docs/pt/docs/help-fastapi.md b/docs/pt/docs/help-fastapi.md index 0091d4c..92be279 100644 --- a/docs/pt/docs/help-fastapi.md +++ b/docs/pt/docs/help-fastapi.md @@ -45,20 +45,6 @@ Você pode seguir [a mim (Sebastián Ramírez / `tiangolo`)](https://tiangolo.co * [@tiangolo.com no **Bluesky**](https://bsky.app/profile/tiangolo.com) * [@tiangolo no **LinkedIn**](https://www.linkedin.com/in/tiangolo/). -## Ajude outras pessoas com perguntas no GitHub { #help-others-with-questions-in-github } - -Você pode tentar ajudar outras pessoas com suas perguntas no [GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered). - -Em muitos casos você já pode saber a resposta para aquelas perguntas. 🤓 - -Se você estiver ajudando muitas pessoas com suas perguntas, você se tornará um(a) [Especialista em FastAPI](fastapi-people.md#fastapi-experts) oficial. 🎉 - -Apenas lembre-se, o ponto mais importante é: tente ser gentil. 🤗 - -### Como ajudar { #how-to-help } - -Siga o [guia sobre como ajudar](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github) aqui. - ## Faça perguntas { #ask-questions } Você pode [criar uma nova pergunta](https://github.com/fastapi/fastapi/discussions/new?category=questions) no repositório do GitHub, por exemplo para: @@ -68,7 +54,7 @@ Você pode [criar uma nova pergunta](https://github.com/fastapi/fastapi/discussi ## Entre no chat { #join-the-chat } -Entre no 👥 [servidor de chat do Discord](https://discord.gg/VQjSZaeJmf) 👥 e converse com outras pessoas da comunidade FastAPI. +Entre no 👥 [servidor de chat do Discord](https://discord.com/invite/VQjSZaeJmf) 👥 e converse com outras pessoas da comunidade FastAPI. /// tip | Dica @@ -85,3 +71,9 @@ Tenha em mente que, como os chats permitem uma “conversa mais livre”, é fá No GitHub, o template vai orientar você a escrever a pergunta certa para que você consiga obter uma boa resposta com mais facilidade, ou até resolver o problema sozinho antes de perguntar. As conversas nos sistemas de chat também não são tão fáceis de pesquisar quanto no GitHub; elas se perdem. + +## Experimente o FastAPI Cloud { #try-fastapi-cloud } + +O financiamento principal do FastAPI e amigos vem do [**FastAPI Cloud**](https://fastapicloud.com), uma plataforma para fazer deploy de aplicações FastAPI de forma simples e rápida, com um único comando, `fastapi deploy`. + +O FastAPI Cloud é criado pela mesma equipe por trás do FastAPI. Você pode experimentá-lo e considerá-lo para seus projetos. diff --git a/docs/pt/docs/history-design-future.md b/docs/pt/docs/history-design-future.md index 7d59495..b25642b 100644 --- a/docs/pt/docs/history-design-future.md +++ b/docs/pt/docs/history-design-future.md @@ -8,7 +8,7 @@ Aqui está um pouco dessa história. ## Alternativas { #alternatives } -Eu tenho criado APIs com requisitos complexos por vários anos (Aprendizado de Máquina, sistemas distribuídos, tarefas assíncronas, banco de dados NoSQL etc.), liderando vários times de desenvolvedores. +Eu tenho criado APIs com requisitos complexos por vários anos (Aprendizado de Máquina, sistemas distribuídos, tarefas assíncronas, bancos de dados NoSQL etc.), liderando vários times de desenvolvedores. Como parte disso, eu precisava investigar, testar e usar muitas alternativas. @@ -22,9 +22,9 @@ Como dito na seção [Alternativas](alternatives.md): Há muitas ferramentas criadas antes que ajudaram a inspirar sua criação. -Eu estive evitando a criação de um novo _framework_ por vários anos. Primeiro tentei resolver todas as funcionalidades cobertas por **FastAPI** usando muitos _frameworks_, _plug-ins_ e ferramentas diferentes. +Eu estive evitando a criação de um novo framework por vários anos. Primeiro tentei resolver todas as funcionalidades cobertas por **FastAPI** usando muitos frameworks, plug-ins e ferramentas diferentes. -Mas em algum ponto, não havia outra opção senão criar algo que oferecia todas as funcionalidades, aproveitando as melhores ideias de ferramentas anteriores, e combinando-as da melhor maneira possível, usando funcionalidades da linguagem que nem estavam disponíveis antes (anotações de tipo do Python 3.6+). +Mas em algum ponto, não havia outra opção senão criar algo que oferecia todas essas funcionalidades, aproveitando as melhores ideias de ferramentas anteriores, e combinando-as da melhor maneira possível, usando funcionalidades da linguagem que nem estavam disponíveis antes (anotações de tipo do Python 3.6+). @@ -36,7 +36,7 @@ Por exemplo, estava claro que idealmente ele deveria ser baseado nas anotações Também, a melhor abordagem era usar padrões já existentes. -Então, antes mesmo de começar a codificar o **FastAPI**, eu investi vários meses estudando as especificações do OpenAPI, JSON Schema, OAuth2 etc. Entendendo suas relações, sobreposições e diferenças. +Então, antes mesmo de começar a codificar o **FastAPI**, eu investi vários meses estudando as especificações do OpenAPI, JSON Schema, OAuth2 etc. Entendendo sua relação, sobreposições e diferenças. ## Design { #design } @@ -54,11 +54,11 @@ Tudo de uma forma que oferecesse a melhor experiência de desenvolvimento para t ## Requisitos { #requirements } -Após testar várias alternativas, eu decidi que usaria o [**Pydantic**](https://docs.pydantic.dev/) por suas vantagens. +Após testar várias alternativas, eu decidi que usaria o [**Pydantic**](https://pydantic.dev/docs/) por suas vantagens. Então eu contribuí com ele, para deixá-lo completamente de acordo com o JSON Schema, para dar suporte a diferentes maneiras de definir declarações de restrições, e melhorar o suporte a editores (conferências de tipos, preenchimento automático) baseado nos testes em vários editores. -Durante o desenvolvimento, eu também contribuí com o [**Starlette**](https://www.starlette.dev/), outro requisito chave. +Durante o desenvolvimento, eu também contribuí com o [**Starlette**](https://starlette.dev/), o outro requisito chave. ## Desenvolvimento { #development } diff --git a/docs/pt/docs/how-to/custom-request-and-route.md b/docs/pt/docs/how-to/custom-request-and-route.md index 070e635..5a920fb 100644 --- a/docs/pt/docs/how-to/custom-request-and-route.md +++ b/docs/pt/docs/how-to/custom-request-and-route.md @@ -66,7 +66,7 @@ O dicionário `scope` e a função `receive` são ambos parte da especificação E essas duas coisas, `scope` e `receive`, são o que é necessário para criar uma nova instância de `Request`. -Para aprender mais sobre o `Request` confira a [documentação do Starlette sobre Requests](https://www.starlette.dev/requests/). +Para aprender mais sobre o `Request` confira a [documentação do Starlette sobre Requests](https://starlette.dev/requests/). /// diff --git a/docs/pt/docs/how-to/extending-openapi.md b/docs/pt/docs/how-to/extending-openapi.md index 86b53ac..1dedcc2 100644 --- a/docs/pt/docs/how-to/extending-openapi.md +++ b/docs/pt/docs/how-to/extending-openapi.md @@ -6,7 +6,7 @@ Nesta seção, você verá como fazer isso. ## O processo normal { #the-normal-process } -O processo normal (padrão) é o seguinte: +O processo normal (padrão) é o seguinte. Uma aplicação (instância) do `FastAPI` possui um método `.openapi()` que deve retornar o esquema OpenAPI. @@ -45,9 +45,9 @@ O parâmetro `summary` está disponível no OpenAPI 3.1.0 e superior, suportado Com as informações acima, você pode usar a mesma função utilitária para gerar o esquema OpenAPI e sobrescrever cada parte que precisar. -Por exemplo, vamos adicionar [Extensão OpenAPI do ReDoc para incluir um logo personalizado](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo). +Por exemplo, vamos adicionar [Extensão OpenAPI do ReDoc para incluir um logo personalizado](https://github.com/Redocly/redoc/blob/main/docs/redoc-vendor-extensions.md#x-logo). -### **FastAPI** Normal { #normal-fastapi } +### Normal **FastAPI** { #normal-fastapi } Primeiro, escreva toda a sua aplicação **FastAPI** normalmente: @@ -81,7 +81,7 @@ Agora, você pode substituir o método `.openapi()` pela sua nova função. {* ../../docs_src/extending_openapi/tutorial001_py310.py hl[29] *} -### Verificar { #check-it } +### Verifique { #check-it } Uma vez que você acessar [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc), verá que está usando seu logo personalizado (neste exemplo, o logo do **FastAPI**): diff --git a/docs/pt/docs/how-to/graphql.md b/docs/pt/docs/how-to/graphql.md index 081c3cf..67e6fbe 100644 --- a/docs/pt/docs/how-to/graphql.md +++ b/docs/pt/docs/how-to/graphql.md @@ -22,7 +22,7 @@ Aqui estão algumas das bibliotecas **GraphQL** que têm suporte **ASGI**. Você * [Strawberry](https://strawberry.rocks/) 🍓 * Com [documentação para FastAPI](https://strawberry.rocks/docs/integrations/fastapi) * [Ariadne](https://ariadnegraphql.org/) - * Com [documentação para FastAPI](https://ariadnegraphql.org/docs/fastapi-integration) + * Com [documentação para FastAPI](https://ariadnegraphql.org/server/Integrations/fastapi-integration) * [Tartiflette](https://tartiflette.io/) * Com [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) para fornecer integração ASGI * [Graphene](https://graphene-python.org/) diff --git a/docs/pt/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/pt/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index e03deb4..460a590 100644 --- a/docs/pt/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/pt/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -24,7 +24,7 @@ Se você tem uma aplicação FastAPI antiga com Pydantic v1, aqui vou mostrar co ## Guia oficial { #official-guide } -O Pydantic tem um [Guia de Migração](https://docs.pydantic.dev/latest/migration/) oficial do v1 para o v2. +O Pydantic tem um [Guia de Migração](https://pydantic.dev/docs/validation/latest/get-started/migration/) oficial do v1 para o v2. Ele também inclui o que mudou, como as validações agora são mais corretas e rigorosas, possíveis ressalvas, etc. diff --git a/docs/pt/docs/index.md b/docs/pt/docs/index.md index fbd93ed..03bb006 100644 --- a/docs/pt/docs/index.md +++ b/docs/pt/docs/index.md @@ -110,14 +110,14 @@ Os recursos chave são:
@@ -133,7 +133,7 @@ Os recursos chave são: "_Nós adotamos a biblioteca **FastAPI** para iniciar um servidor **REST** que pode ser consultado para obter **previsões**. [para o Ludwig]_" -
Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - Uber (ref)
+
Piero Molino, Yaroslav Dudin, e Sai Sumanth Miryala - Uber (ref)
--- @@ -151,12 +151,6 @@ Os recursos chave são:
-## FastAPI Conf { #fastapi-conf } - -[**FastAPI Conf '26**](https://fastapiconf.com) acontece em **28 de outubro de 2026** em **Amsterdã, NL**. Tudo sobre FastAPI, direto da fonte. 🎤 - -FastAPI Conf '26 - October 28, 2026 - Amsterdam, NL - ## Mini documentário do FastAPI { #fastapi-mini-documentary } Há um [mini documentário do FastAPI](https://www.youtube.com/watch?v=mpR8ngthqiE) lançado no fim de 2025, você pode assisti-lo online: @@ -175,17 +169,17 @@ Se você estiver construindo uma aplicação ```console -$ pip install "fastapi[standard]" +$ uv add "fastapi[standard]" ---> 100% ``` @@ -194,6 +188,8 @@ $ pip install "fastapi[standard]" **Nota**: Certifique-se de que você colocou `"fastapi[standard]"` com aspas, para garantir que funcione em todos os terminais. +Se você preferir usar `pip`, instale `fastapi[standard]` dentro de um ambiente virtual. Veja o [guia de instalação](tutorial/#install-fastapi) para os passos alternativos. + ## Exemplo { #example } ### Crie { #create-it } @@ -250,7 +246,7 @@ Rode o servidor com:
```console -$ fastapi dev +$ uv run fastapi dev ╭────────── FastAPI CLI - Development mode ───────────╮ │ │ @@ -277,7 +273,7 @@ INFO: Application startup complete.
Sobre o comando fastapi dev... -O comando `fastapi dev` lê automaticamente o seu arquivo `main.py`, detecta a aplicação **FastAPI** nele e inicia um servidor usando o [Uvicorn](https://www.uvicorn.dev). +O comando `fastapi dev` lê automaticamente o seu arquivo `main.py`, detecta a aplicação **FastAPI** nele e inicia um servidor usando o [Uvicorn](https://uvicorn.dev). Por padrão, o `fastapi dev` iniciará com auto-reload habilitado para desenvolvimento local. @@ -314,7 +310,7 @@ Você verá a documentação automática interativa da API (fornecida por [Swagg E agora, vá para [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc). -Você verá a documentação automática alternativa (fornecida por [ReDoc](https://github.com/Rebilly/ReDoc)): +Você verá a documentação automática alternativa (fornecida por [ReDoc](https://github.com/Redocly/redoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -497,7 +493,7 @@ Você pode opcionalmente implantar sua aplicação FastAPI na [FastAPI Cloud](ht
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -520,7 +516,7 @@ Ela simplifica o processo de **construir**, **implantar** e **acessar** uma API Traz a mesma **experiência do desenvolvedor** de construir aplicações com FastAPI para **implantá-las** na nuvem. 🎉 -A FastAPI Cloud é a principal patrocinadora e financiadora dos projetos open source do ecossistema *FastAPI and friends*. ✨ +A FastAPI Cloud é a principal patrocinadora e financiadora dos projetos open source *FastAPI and friends*. ✨ #### Implante em outros provedores de nuvem { #deploy-to-other-cloud-providers } @@ -540,7 +536,7 @@ O FastAPI depende do Pydantic e do Starlette. ### Dependências `standard` { #standard-dependencies } -Quando você instala o FastAPI com `pip install "fastapi[standard]"`, ele vem com o grupo `standard` de dependências opcionais: +Quando você instala o FastAPI com `uv add "fastapi[standard]"`, ele vem com o grupo `standard` de dependências opcionais: Utilizado pelo Pydantic: @@ -554,17 +550,17 @@ Utilizado pelo Starlette: Utilizado pelo FastAPI: -* [`uvicorn`](https://www.uvicorn.dev) - para o servidor que carrega e serve a sua aplicação. Isto inclui `uvicorn[standard]`, que inclui algumas dependências (e.g. `uvloop`) necessárias para servir em alta performance. +* [`uvicorn`](https://uvicorn.dev) - para o servidor que carrega e serve a sua aplicação. Isto inclui `uvicorn[standard]`, que inclui algumas dependências (e.g. `uvloop`) necessárias para servir em alta performance. * `fastapi-cli[standard]` - que disponibiliza o comando `fastapi`. * Isso inclui `fastapi-cloud-cli`, que permite implantar sua aplicação FastAPI na [FastAPI Cloud](https://fastapicloud.com). ### Sem as dependências `standard` { #without-standard-dependencies } -Se você não deseja incluir as dependências opcionais `standard`, você pode instalar utilizando `pip install fastapi` ao invés de `pip install "fastapi[standard]"`. +Se você não deseja incluir as dependências opcionais `standard`, você pode instalar utilizando `uv add fastapi` ao invés de `uv add "fastapi[standard]"`. ### Sem o `fastapi-cloud-cli` { #without-fastapi-cloud-cli } -Se você quiser instalar o FastAPI com as dependências padrão, mas sem o `fastapi-cloud-cli`, você pode instalar com `pip install "fastapi[standard-no-fastapi-cloud-cli]"`. +Se você quiser instalar o FastAPI com as dependências padrão, mas sem o `fastapi-cloud-cli`, você pode instalar com `uv add "fastapi[standard-no-fastapi-cloud-cli]"`. ### Dependências opcionais adicionais { #additional-optional-dependencies } @@ -572,13 +568,13 @@ Existem algumas dependências adicionais que você pode querer instalar. Dependências opcionais adicionais do Pydantic: -* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - para gerenciamento de configurações. -* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - para tipos extras a serem utilizados com o Pydantic. +* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) - para gerenciamento de configurações. +* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) - para tipos extras a serem utilizados com o Pydantic. Dependências opcionais adicionais do FastAPI: * [`orjson`](https://github.com/ijl/orjson) - Obrigatório se você deseja utilizar o `ORJSONResponse`. -* [`ujson`](https://github.com/esnme/ultrajson) - Obrigatório se você deseja utilizar o `UJSONResponse`. +* [`ujson`](https://github.com/ultrajson/ultrajson) - Obrigatório se você deseja utilizar o `UJSONResponse`. ## Licença { #license } diff --git a/docs/pt/docs/project-generation.md b/docs/pt/docs/project-generation.md index 967f1f5..bd60411 100644 --- a/docs/pt/docs/project-generation.md +++ b/docs/pt/docs/project-generation.md @@ -4,13 +4,13 @@ Templates, embora tipicamente venham com alguma configuração específica, são Você pode usar esse template para começar, já que ele inclui várias configurações iniciais, segurança, banco de dados e alguns endpoints de API já feitos para você. -Repositório GitHub: [Full Stack FastAPI Template](https://github.com/tiangolo/full-stack-fastapi-template) +Repositório GitHub: [Full Stack FastAPI Template](https://github.com/fastapi/full-stack-fastapi-template) ## Full Stack FastAPI Template - Pilha de Tecnologias e Recursos { #full-stack-fastapi-template-technology-stack-and-features } - ⚡ [**FastAPI**](https://fastapi.tiangolo.com/pt) para a API do backend em Python. - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) para as interações do Python com bancos de dados SQL (ORM). - - 🔍 [Pydantic](https://docs.pydantic.dev), usado pelo FastAPI, para validação de dados e gerenciamento de configurações. + - 🔍 [Pydantic](https://pydantic.dev/docs/), usado pelo FastAPI, para validação de dados e gerenciamento de configurações. - 💾 [PostgreSQL](https://www.postgresql.org) como banco de dados SQL. - 🚀 [React](https://react.dev) para o frontend. - 💃 Usando TypeScript, hooks, Vite, e outras partes de uma stack frontend moderna. diff --git a/docs/pt/docs/python-types.md b/docs/pt/docs/python-types.md index d4ba537..daf92ee 100644 --- a/docs/pt/docs/python-types.md +++ b/docs/pt/docs/python-types.md @@ -269,7 +269,7 @@ Isso não significa que "`one_person` é a **classe** chamada `Person`". ## Modelos Pydantic { #pydantic-models } -[Pydantic](https://docs.pydantic.dev/) é uma biblioteca Python para executar a validação de dados. +[Pydantic](https://pydantic.dev/docs/) é uma biblioteca Python para executar a validação de dados. Você declara a "forma" dos dados como classes com atributos. @@ -285,7 +285,7 @@ Um exemplo da documentação oficial do Pydantic: /// note | Nota -Para saber mais sobre [Pydantic, verifique a documentação](https://docs.pydantic.dev/). +Para saber mais sobre [Pydantic, verifique a documentação](https://pydantic.dev/docs/). /// diff --git a/docs/pt/docs/tutorial/background-tasks.md b/docs/pt/docs/tutorial/background-tasks.md index 20152d9..12ce08f 100644 --- a/docs/pt/docs/tutorial/background-tasks.md +++ b/docs/pt/docs/tutorial/background-tasks.md @@ -54,6 +54,7 @@ O **FastAPI** sabe o que fazer em cada caso e como reutilizar o mesmo objeto, de {* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *} + Neste exemplo, as mensagens serão escritas no arquivo `log.txt` *após* o envio da resposta. Se houver uma query na request, ela será registrada em uma tarefa em segundo plano. @@ -62,7 +63,7 @@ E então outra tarefa em segundo plano gerada na *função de operação de rota ## Detalhes técnicos { #technical-details } -A classe `BackgroundTasks` vem diretamente de [`starlette.background`](https://www.starlette.dev/background/). +A classe `BackgroundTasks` vem diretamente de [`starlette.background`](https://starlette.dev/background/). Ela é importada/incluída diretamente no FastAPI para que você possa importá-la de `fastapi` e evitar importar acidentalmente a alternativa `BackgroundTask` (sem o `s` no final) de `starlette.background`. @@ -70,7 +71,7 @@ Usando apenas `BackgroundTasks` (e não `BackgroundTask`), é possível usá-la Ainda é possível usar `BackgroundTask` sozinho no FastAPI, mas você precisa criar o objeto no seu código e retornar uma `Response` da Starlette incluindo-o. -Você pode ver mais detalhes na [documentação oficial da Starlette para tarefas em segundo plano](https://www.starlette.dev/background/). +Você pode ver mais detalhes na [documentação oficial da Starlette para tarefas em segundo plano](https://starlette.dev/background/). ## Ressalva { #caveat } diff --git a/docs/pt/docs/tutorial/bigger-applications.md b/docs/pt/docs/tutorial/bigger-applications.md index 4f9823d..0eca9e8 100644 --- a/docs/pt/docs/tutorial/bigger-applications.md +++ b/docs/pt/docs/tutorial/bigger-applications.md @@ -186,7 +186,7 @@ O resultado final é que os paths dos itens agora são: * Todas essas *operações de rota* terão a list de `dependencies` avaliada/executada antes delas. * Se você também declarar dependências em uma *operação de rota* específica, **elas também serão executadas**. * As dependências do router são executadas primeiro, depois as [`dependencies` no decorador](dependencies/dependencies-in-path-operation-decorators.md) e, em seguida, as dependências de parâmetros normais. - * Você também pode adicionar [dependências de `Segurança` com `scopes`](../advanced/security/oauth2-scopes.md). + * Você também pode adicionar [dependências de `Security` com `scopes`](../advanced/security/oauth2-scopes.md). /// tip | Dica @@ -487,7 +487,7 @@ Dessa forma o comando `fastapi` saberá onde encontrar sua aplicação. Você também poderia passar o path para o comando, como: ```console -$ fastapi dev app/main.py +$ uv run fastapi dev app/main.py ``` Mas você teria que lembrar de passar o path correto toda vez que chamar o comando `fastapi`. @@ -503,7 +503,7 @@ Agora, execute sua aplicação:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/pt/docs/tutorial/body-nested-models.md b/docs/pt/docs/tutorial/body-nested-models.md index e2a59f9..7981962 100644 --- a/docs/pt/docs/tutorial/body-nested-models.md +++ b/docs/pt/docs/tutorial/body-nested-models.md @@ -96,7 +96,7 @@ Novamente, apenas fazendo essa declaração, com o **FastAPI**, você ganha: Além dos tipos singulares normais como `str`, `int`, `float`, etc. Você também pode usar tipos singulares mais complexos que herdam de `str`. -Para ver todas as opções possíveis, consulte a [Visão geral dos tipos do Pydantic](https://docs.pydantic.dev/latest/concepts/types/). Você verá alguns exemplos no próximo capítulo. +Para ver todas as opções possíveis, consulte a [Visão geral dos tipos do Pydantic](https://pydantic.dev/docs/validation/latest/concepts/types/). Você verá alguns exemplos no próximo capítulo. Por exemplo, no modelo `Image` nós temos um campo `url`, nós podemos declará-lo como um `HttpUrl` do Pydantic em vez de como uma `str`: @@ -182,7 +182,7 @@ Mas você também não precisa se preocupar com eles, os dicts de entrada são c Você também pode declarar um corpo como um `dict` com chaves de algum tipo e valores de outro tipo. -Sem ter que saber de antemão quais são os nomes de campos/atributos válidos (como seria o caso dos modelos Pydantic). +Dessa forma, você não precisa saber de antemão quais são os nomes de campos/atributos válidos (como seria o caso dos modelos Pydantic). Isso seria útil se você deseja receber chaves que ainda não conhece. diff --git a/docs/pt/docs/tutorial/body.md b/docs/pt/docs/tutorial/body.md index 6aea063..1580cd4 100644 --- a/docs/pt/docs/tutorial/body.md +++ b/docs/pt/docs/tutorial/body.md @@ -7,7 +7,7 @@ O corpo da **requisição** é a informação enviada pelo cliente para sua API. Sua API quase sempre precisa enviar um corpo na **resposta**. Mas os clientes não necessariamente precisam enviar **corpos de requisição** o tempo todo, às vezes eles apenas requisitam um path, talvez com alguns parâmetros de consulta, mas não enviam um corpo. -Para declarar um corpo da **requisição**, você utiliza os modelos do [Pydantic](https://docs.pydantic.dev/) com todos os seus poderes e benefícios. +Para declarar um corpo da **requisição**, você utiliza os modelos do [Pydantic](https://pydantic.dev/docs/) com todos os seus poderes e benefícios. /// note | Nota diff --git a/docs/pt/docs/tutorial/debugging.md b/docs/pt/docs/tutorial/debugging.md index 7b98199..4d7ad30 100644 --- a/docs/pt/docs/tutorial/debugging.md +++ b/docs/pt/docs/tutorial/debugging.md @@ -15,7 +15,7 @@ O objetivo principal de `__name__ == "__main__"` é ter algum código que seja e
```console -$ python myapp.py +$ uv run python myapp.py ```
@@ -35,7 +35,7 @@ Se você executá-lo com:
```console -$ python myapp.py +$ uv run python myapp.py ```
diff --git a/docs/pt/docs/tutorial/extra-data-types.md b/docs/pt/docs/tutorial/extra-data-types.md index dbfeb8d..ce631c9 100644 --- a/docs/pt/docs/tutorial/extra-data-types.md +++ b/docs/pt/docs/tutorial/extra-data-types.md @@ -36,7 +36,7 @@ Aqui estão alguns dos tipos de dados adicionais que você pode usar: * `datetime.timedelta`: * O `datetime.timedelta` do Python. * Em requisições e respostas será representado como um `float` de segundos totais. - * O Pydantic também permite representá-lo como uma "codificação de diferença de tempo ISO 8601", [veja a documentação para mais informações](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers). + * O Pydantic também permite representá-lo como uma "codificação de diferença de tempo ISO 8601", [veja a documentação para mais informações](https://pydantic.dev/docs/validation/latest/concepts/serialization/#custom-serializers). * `frozenset`: * Em requisições e respostas, será tratado da mesma forma que um `set`: * Nas requisições, uma list será lida, eliminando duplicadas e convertendo-a em um `set`. @@ -49,7 +49,7 @@ Aqui estão alguns dos tipos de dados adicionais que você pode usar: * `Decimal`: * O `Decimal` padrão do Python. * Em requisições e respostas, tratado da mesma forma que um `float`. -* Você pode checar todos os tipos de dados válidos do Pydantic aqui: [Tipos de dados do Pydantic](https://docs.pydantic.dev/latest/usage/types/types/). +* Você pode checar todos os tipos de dados válidos do Pydantic aqui: [Tipos de dados do Pydantic](https://pydantic.dev/docs/validation/latest/concepts/types/). ## Exemplo { #example } diff --git a/docs/pt/docs/tutorial/extra-models.md b/docs/pt/docs/tutorial/extra-models.md index 19913ca..5fec38c 100644 --- a/docs/pt/docs/tutorial/extra-models.md +++ b/docs/pt/docs/tutorial/extra-models.md @@ -166,7 +166,7 @@ Para fazer isso, use a anotação de tipo padrão do Python [`typing.Union`](htt /// note | Nota -Ao definir um [`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions), inclua o tipo mais específico primeiro, seguido pelo tipo menos específico. No exemplo abaixo, o tipo mais específico `PlaneItem` vem antes de `CarItem` em `Union[PlaneItem, CarItem]`. +Ao definir um [`Union`](https://pydantic.dev/docs/validation/latest/concepts/unions/), inclua o tipo mais específico primeiro, seguido pelo tipo menos específico. No exemplo abaixo, o tipo mais específico `PlaneItem` vem antes de `CarItem` em `Union[PlaneItem, CarItem]`. /// diff --git a/docs/pt/docs/tutorial/first-steps.md b/docs/pt/docs/tutorial/first-steps.md index 97bbfe0..e60cee8 100644 --- a/docs/pt/docs/tutorial/first-steps.md +++ b/docs/pt/docs/tutorial/first-steps.md @@ -6,12 +6,18 @@ O arquivo FastAPI mais simples pode se parecer com: Copie o conteúdo para um arquivo `main.py`. +/// tip | Dica + +FastAPI tem uma [extensão oficial para VS Code](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (e Cursor), que fornece muitas funcionalidades, incluindo um explorador de operações de rota, busca de operações de rota, navegação CodeLens em testes (ir para a definição a partir dos testes), e deploy e logs da FastAPI Cloud, tudo a partir do seu editor. + +/// + Execute o servidor ao vivo:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -78,7 +84,7 @@ Você verá a documentação interativa automática da API (fornecida por [Swagg E agora, vá para [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc). -Você verá a documentação alternativa automática (fornecida por [ReDoc](https://github.com/Rebilly/ReDoc)): +Você verá a documentação alternativa automática (fornecida por [ReDoc](https://github.com/Redocly/redoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -185,13 +191,13 @@ from backend.main import app Você também pode passar o path do arquivo para o comando `fastapi dev`, e ele vai deduzir o objeto de aplicação FastAPI a ser usado: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` Ou você também pode passar a opção `--entrypoint` para o comando `fastapi dev`: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` Mas você teria que lembrar de passar o path\entrypoint correto toda vez que chamar o comando `fastapi`. @@ -205,7 +211,7 @@ Você pode, opcionalmente, fazer o deploy da sua aplicação FastAPI na [FastAPI
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -232,7 +238,7 @@ A CLI detectará automaticamente sua aplicação FastAPI e a fará o deploy na n `FastAPI` é uma classe que herda diretamente de `Starlette`. -Você pode usar todas as funcionalidades do [Starlette](https://www.starlette.dev/) com `FastAPI` também. +Você pode usar todas as funcionalidades do [Starlette](https://starlette.dev/) com `FastAPI` também. /// diff --git a/docs/pt/docs/tutorial/frontend.md b/docs/pt/docs/tutorial/frontend.md index f0d08ce..bbc18cf 100644 --- a/docs/pt/docs/tutorial/frontend.md +++ b/docs/pt/docs/tutorial/frontend.md @@ -52,7 +52,7 @@ Para isso, use `fallback="index.html"`: {* ../../docs_src/frontend/tutorial002_py310.py hl[5] *} -**FastAPI** usa esse fallback somente para requests `GET` e `HEAD` que parecem navegação do navegador. Arquivos ausentes como JavaScript, CSS e imagens ainda retornam `404`. +**FastAPI** usa esse fallback somente para requests `GET` e `HEAD` que aceitam HTML explicitamente com `Accept: text/html` ou `Accept: application/xhtml+xml`, como requests de navegação do navegador normalmente fazem. Arquivos ausentes como JavaScript, CSS e imagens ainda retornam `404`. Requests com outros métodos, como `POST` ou `PUT`, para paths que correspondem apenas ao fallback do frontend também retornam `404`. *Operações de rota* regulares do **FastAPI** ainda têm prioridade maior que rotas de frontend. @@ -106,9 +106,13 @@ Então paths de frontend ausentes retornam o `404` normal. ## Verifique o Diretório { #check-directory } -Por padrão, `app.frontend()` verifica se o diretório existe quando a aplicação é criada. +Por padrão, `app.frontend()` usa `check_dir="auto"`. -Isso ajuda a identificar erros de configuração cedo. Por exemplo, se o diretório de saída do build do frontend estiver ausente, **FastAPI** gerará um erro na inicialização. +Quando a variável de ambiente `FASTAPI_ENV` é definida como `development`, **FastAPI** mostra apenas um aviso se o diretório de saída do build do frontend estiver ausente. O [comando `fastapi dev`](https://github.com/fastapi/fastapi-cli#fastapi-dev) define essa variável de ambiente para você se ela ainda não estiver definida. Isso permite iniciar o backend antes de fazer o build ou iniciar o frontend durante o desenvolvimento. + +Em qualquer outro ambiente, **FastAPI** gera um erro quando a aplicação é criada. Isso ajuda a identificar erros de configuração cedo, antes de fazer deploy de uma aplicação sem seus arquivos de frontend. + +Você também pode definir `check_dir=True` para sempre verificar o diretório quando a aplicação for criada. Se seus arquivos de frontend forem criados depois, por exemplo por uma etapa de build separada após o objeto da aplicação ser criado, defina `check_dir=False`: @@ -132,6 +136,8 @@ Responses de frontend são executadas dentro da aplicação **FastAPI** normal, Dependências da aplicação, de um `APIRouter` e de `include_router()` também se aplicam a responses de frontend. Isso pode ser útil para proteger um frontend com autenticação por cookie ou similar. +Dependências também podem modificar headers de response e adicionar tarefas em segundo plano, como em *operações de rota* normais. + ## Apenas Saída de Build Estático { #static-build-output-only } `app.frontend()` serve arquivos já gerados pelo build do seu frontend. diff --git a/docs/pt/docs/tutorial/handling-errors.md b/docs/pt/docs/tutorial/handling-errors.md index 9c7abf0..10da3b1 100644 --- a/docs/pt/docs/tutorial/handling-errors.md +++ b/docs/pt/docs/tutorial/handling-errors.md @@ -81,7 +81,7 @@ Mas caso precise em um cenário avançado, você pode adicionar headers customiz ## Instale manipuladores de exceções customizados { #install-custom-exception-handlers } -Você pode adicionar manipuladores de exceção customizados com [as mesmas utilidades de exceção do Starlette](https://www.starlette.dev/exceptions/). +Você pode adicionar manipuladores de exceção customizados com [as mesmas utilidades de exceção do Starlette](https://starlette.dev/exceptions/). Digamos que você tenha uma exceção customizada `UnicornException` que você (ou uma biblioteca que você usa) possa lançar com `raise`. diff --git a/docs/pt/docs/tutorial/index.md b/docs/pt/docs/tutorial/index.md index 57396e2..056e2d1 100644 --- a/docs/pt/docs/tutorial/index.md +++ b/docs/pt/docs/tutorial/index.md @@ -10,12 +10,12 @@ Ele também foi construído para servir como uma referência futura, então voc Todos os blocos de código podem ser copiados e utilizados diretamente (eles são, na verdade, arquivos Python testados). -Para executar qualquer um dos exemplos, copie o código para um arquivo `main.py`, e inicie o `fastapi dev`: +Para executar qualquer um dos exemplos, copie o código para um arquivo `main.py`, e inicie o `fastapi dev` com `uv run`:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -60,35 +60,75 @@ Usá-lo em seu editor é o que realmente mostra os benefícios do FastAPI, vendo ## Instale o FastAPI { #install-fastapi } -O primeiro passo é instalar o FastAPI. +O primeiro passo é configurar seu projeto e adicionar o FastAPI. -Certifique-se de criar um [ambiente virtual](../virtual-environments.md), ativá-lo e então **instalar o FastAPI**: +Instale o [`uv`](https://docs.astral.sh/uv/getting-started/installation/), então crie um projeto e adicione o FastAPI:
```console -$ pip install "fastapi[standard]" +$ uv init awesome-project --bare +$ cd awesome-project +$ uv add "fastapi[standard]" ---> 100% ```
+`uv add` cria o ambiente virtual do projeto em `.venv`, adiciona o FastAPI ao `pyproject.toml` e cria `uv.lock` para que as mesmas versões dos pacotes possam ser instaladas posteriormente. + +/// details | O que estes comandos fazem + +* `uv init`: cria um novo projeto Python. +* `awesome-project`: cria o projeto em um novo diretório com este nome. +* `--bare`: cria apenas o arquivo `pyproject.toml` mínimo, sem gerar um `main.py`, `README.md` ou outros arquivos de exemplo. Você criará os arquivos da aplicação nos próximos passos deste tutorial. + +Então `cd awesome-project` entra no novo diretório do projeto antes de adicionar o FastAPI. + +`uv` usará uma versão compatível do Python já instalada em seu sistema, ou baixará uma se necessário. + +Quando você executa `uv add`, ele seleciona versões compatíveis do FastAPI e de todos os pacotes dos quais o FastAPI depende. Ele registra as versões exatas em `uv.lock`, tornando possível instalar as mesmas versões dos pacotes posteriormente em outro computador ou ao fazer deploy da aplicação. + +Criar ou atualizar este arquivo é chamado de [**locking** das dependências do projeto](https://docs.astral.sh/uv/concepts/projects/sync/). O `uv` faz isso automaticamente quando você adiciona um pacote. + +/// + +/// details | Opções de instalação do FastAPI + +Quando você instala com `uv add "fastapi[standard]"`, ele vem com algumas dependências opcionais padrão, incluindo `fastapi-cloud-cli`, que permite fazer deploy na [FastAPI Cloud](https://fastapicloud.com). + +Se você não quiser ter essas dependências opcionais, pode instalar `uv add fastapi` em vez disso. + +Se você quiser instalar as dependências padrão, mas sem o `fastapi-cloud-cli`, você pode instalar com `uv add "fastapi[standard-no-fastapi-cloud-cli]"`. + +/// + +/// details | Usando `pip` em vez disso + +Se você preferir gerenciar um ambiente virtual e pacotes manualmente, crie e ative um ambiente virtual e então instale o FastAPI com `pip install "fastapi[standard]"`. + +Leia o [guia de Ambientes Virtuais](https://tiangolo.com/guides/virtual-environments/) para os passos detalhados. + +/// + +## Habilidades de Agentes de IA { #ai-agent-skills } + +O FastAPI inclui uma skill oficial para agentes de codificação de IA. Ela é incluída no pacote, então sua orientação permanece alinhada com a versão do FastAPI instalada no seu projeto e é atualizada quando você atualiza o FastAPI. + +Depois de instalar o FastAPI no seu projeto, você pode instalar a skill com Library Skills: + +```bash +uvx library-skills +``` + /// note | Nota -Quando você instala com `pip install "fastapi[standard]"`, ele vem com algumas dependências opcionais padrão, incluindo `fastapi-cloud-cli`, que permite fazer deploy na [FastAPI Cloud](https://fastapicloud.com). - -Se você não quiser ter essas dependências opcionais, pode instalar `pip install fastapi` em vez disso. - -Se você quiser instalar as dependências padrão, mas sem o `fastapi-cloud-cli`, você pode instalar com `pip install "fastapi[standard-no-fastapi-cloud-cli]"`. +`uvx` é um alias para `uv tool run`. Ele executa Library Skills em um ambiente temporário e isolado enquanto Library Skills verifica os pacotes instalados no seu projeto. /// -/// tip | Dica - -O FastAPI tem uma [extensão oficial para o VS Code](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (e para o Cursor), que fornece vários recursos, incluindo um explorador de operações de rota, busca de operações de rota, navegação CodeLens em testes (ir para a definição a partir dos testes) e deploy e logs da FastAPI Cloud, tudo direto do seu editor. - -/// +A skill é compatível com Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Pi, OpenCode e a maioria dos outros agentes de codificação. Para Claude Code, selecione `.claude/skills` quando for perguntado onde instalar a skill. ## Guia Avançado de Usuário { #advanced-user-guide } diff --git a/docs/pt/docs/tutorial/middleware.md b/docs/pt/docs/tutorial/middleware.md index 5ae5854..60d88d6 100644 --- a/docs/pt/docs/tutorial/middleware.md +++ b/docs/pt/docs/tutorial/middleware.md @@ -1,6 +1,6 @@ # Middleware { #middleware } -Você pode adicionar middleware à suas aplicações **FastAPI**. +Você pode adicionar middleware às aplicações **FastAPI**. Um "middleware" é uma função que manipula cada **requisição** antes de ser processada por qualquer *operação de rota* específica. E também cada **resposta** antes de retorná-la. @@ -37,7 +37,7 @@ A função middleware recebe: Tenha em mente que cabeçalhos proprietários personalizados podem ser adicionados [usando o prefixo `X-`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). -Mas se você tiver cabeçalhos personalizados desejando que um cliente em um navegador esteja apto a ver, você precisa adicioná-los às suas configurações CORS ([CORS (Cross-Origin Resource Sharing)](cors.md)) usando o parâmetro `expose_headers` documentado na [Documentação CORS da Starlette](https://www.starlette.dev/middleware/#corsmiddleware). +Mas se você tiver cabeçalhos personalizados desejando que um cliente em um navegador esteja apto a ver, você precisa adicioná-los às suas configurações CORS ([CORS (Cross-Origin Resource Sharing)](cors.md)) usando o parâmetro `expose_headers` documentado na [Documentação CORS da Starlette](https://starlette.dev/middleware/#corsmiddleware). /// @@ -55,7 +55,7 @@ Você pode adicionar código para ser executado com a `request`, antes que qualq E também depois que a `response` é gerada, antes de retorná-la. -Por exemplo, você pode adicionar um cabeçalho personalizado `X-Process-Time` contendo o tempo em segundos que levou para processar a solicitação e gerar uma resposta: +Por exemplo, você pode adicionar um cabeçalho personalizado `X-Process-Time` contendo o tempo em segundos que levou para processar a requisição e gerar uma resposta: {* ../../docs_src/middleware/tutorial001_py310.py hl[10,12:13] *} @@ -67,9 +67,9 @@ Aqui usamos [`time.perf_counter()`](https://docs.python.org/3/library/time.html# ## Ordem de execução de múltiplos middlewares { #multiple-middleware-execution-order } -Quando você adiciona múltiplos middlewares usando o decorador `@app.middleware()` ou o método `app.add_middleware()`, cada novo middleware envolve a aplicação, formando uma pilha. O último middleware adicionado é o mais externo, e o primeiro é o mais interno. +Quando você adiciona múltiplos middlewares usando o decorador `@app.middleware()` ou o método `app.add_middleware()`, cada novo middleware envolve a aplicação, formando uma pilha. O último middleware adicionado é o *mais externo*, e o primeiro é o *mais interno*. -No caminho da requisição, o middleware mais externo roda primeiro. +No caminho da requisição, o middleware *mais externo* roda primeiro. No caminho da resposta, ele roda por último. diff --git a/docs/pt/docs/tutorial/path-params.md b/docs/pt/docs/tutorial/path-params.md index 3025197..fe5d10f 100644 --- a/docs/pt/docs/tutorial/path-params.md +++ b/docs/pt/docs/tutorial/path-params.md @@ -21,7 +21,9 @@ Você pode declarar o tipo de um parâmetro de path na função, usando as anota Neste caso, `item_id` é declarado como um `int`. /// tip | Dica + Isso fornecerá suporte do editor dentro da sua função, com verificações de erros, preenchimento automático, etc. + /// ## Dados conversão { #data-conversion } @@ -33,9 +35,11 @@ Se você executar este exemplo e abrir seu navegador em [http://127.0.0.1:8000/i ``` /// tip | Dica + Perceba que o valor que sua função recebeu (e retornou) é `3`, como um `int` do Python, não uma string `"3"`. Então, com essa declaração de tipo, o **FastAPI** fornece "parsing" automático do request. + /// ## Validação de dados { #data-validation } @@ -63,11 +67,13 @@ porque o parâmetro de path `item_id` tinha o valor `"foo"`, que não é um `int O mesmo erro apareceria se você fornecesse um `float` em vez de um `int`, como em: [http://127.0.0.1:8000/items/4.2](http://127.0.0.1:8000/items/4.2) /// tip | Dica + Então, com a mesma declaração de tipo do Python, o **FastAPI** fornece validação de dados. Observe que o erro também declara claramente exatamente o ponto onde a validação não passou. Isso é incrivelmente útil ao desenvolver e depurar código que interage com sua API. + /// ## Documentação { #documentation } @@ -77,14 +83,16 @@ E quando você abrir seu navegador em [http://127.0.0.1:8000/docs](http://127.0. /// tip | Dica + Novamente, apenas com a mesma declaração de tipo do Python, o **FastAPI** fornece documentação automática e interativa (integrando o Swagger UI). Observe que o parâmetro de path está declarado como um inteiro. + /// ## Benefícios baseados em padrões, documentação alternativa { #standards-based-benefits-alternative-documentation } -E como o schema gerado é do padrão [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md), existem muitas ferramentas compatíveis. +E como o schema gerado é do padrão [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md), existem muitas ferramentas compatíveis. Por causa disso, o próprio **FastAPI** fornece uma documentação alternativa da API (usando ReDoc), que você pode acessar em [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc): @@ -94,7 +102,7 @@ Da mesma forma, existem muitas ferramentas compatíveis. Incluindo ferramentas d ## Pydantic { #pydantic } -Toda a validação de dados é realizada nos bastidores pelo [Pydantic](https://docs.pydantic.dev/), então você recebe todos os benefícios disso. E você sabe que está em boas mãos. +Toda a validação de dados é realizada nos bastidores pelo [Pydantic](https://pydantic.dev/docs/), então você recebe todos os benefícios disso. E você sabe que está em boas mãos. Você pode usar as mesmas declarações de tipo com `str`, `float`, `bool` e muitos outros tipos de dados complexos. @@ -135,7 +143,9 @@ Em seguida, crie atributos de classe com valores fixos, que serão os valores v {* ../../docs_src/path_params/tutorial005_py310.py hl[1,6:9] *} /// tip | Dica + Se você está se perguntando, "AlexNet", "ResNet" e "LeNet" são apenas nomes de modelos de Aprendizado de Máquina modelos. + /// ### Declare um parâmetro de path { #declare-a-path-parameter } @@ -167,7 +177,9 @@ Você pode obter o valor real (um `str` neste caso) usando `model_name.value`, o {* ../../docs_src/path_params/tutorial005_py310.py hl[20] *} /// tip | Dica + Você também pode acessar o valor `"lenet"` com `ModelName.lenet.value`. + /// #### Retorne membros de enumeração { #return-enumeration-members } @@ -218,19 +230,21 @@ Então, você pode usá-lo com: {* ../../docs_src/path_params/tutorial004_py310.py hl[6] *} /// tip | Dica + Você pode precisar que o parâmetro contenha `/home/johndoe/myfile.txt`, com uma barra inicial (`/`). Nesse caso, a URL seria: `/files//home/johndoe/myfile.txt`, com uma barra dupla (`//`) entre `files` e `home`. + /// ## Recapitulação { #recap } Com o **FastAPI**, ao usar declarações de tipo do Python curtas, intuitivas e padrão, você obtém: -- Suporte no editor: verificações de erro, preenchimento automático, etc. -- "parsing" de dados -- Validação de dados -- Anotação da API e documentação automática +* Suporte no editor: verificações de erro, preenchimento automático, etc. +* "parsing" de dados +* Validação de dados +* Anotação da API e documentação automática E você só precisa declará-los uma vez. diff --git a/docs/pt/docs/tutorial/query-params-str-validations.md b/docs/pt/docs/tutorial/query-params-str-validations.md index d37db28..73171d3 100644 --- a/docs/pt/docs/tutorial/query-params-str-validations.md +++ b/docs/pt/docs/tutorial/query-params-str-validations.md @@ -370,11 +370,11 @@ Podem existir casos em que você precise fazer alguma **validação personalizad Nesses casos, você pode usar uma **função validadora personalizada** que é aplicada após a validação normal (por exemplo, depois de validar que o valor é uma `str`). -Você pode fazer isso usando o [`AfterValidator` do Pydantic](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator) dentro de `Annotated`. +Você pode fazer isso usando o [`AfterValidator` do Pydantic](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-after-validator) dentro de `Annotated`. /// tip | Dica -O Pydantic também tem [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator) e outros. 🤓 +O Pydantic também tem [`BeforeValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-before-validator) e outros. 🤓 /// diff --git a/docs/pt/docs/tutorial/request-files.md b/docs/pt/docs/tutorial/request-files.md index 8b34630..ec66aaf 100644 --- a/docs/pt/docs/tutorial/request-files.md +++ b/docs/pt/docs/tutorial/request-files.md @@ -6,10 +6,10 @@ Você pode definir arquivos para serem enviados pelo cliente usando `File`. Para receber arquivos enviados, primeiro instale [`python-multipart`](https://github.com/Kludex/python-multipart). -Garanta que você criou um [ambiente virtual](../virtual-environments.md), o ativou e então o instalou, por exemplo: +Adicione-o ao seu projeto: ```console -$ pip install python-multipart +$ uv add python-multipart ``` Isso é necessário, visto que os arquivos enviados são enviados como "dados de formulário". diff --git a/docs/pt/docs/tutorial/request-form-models.md b/docs/pt/docs/tutorial/request-form-models.md index 8e265d6..f06769b 100644 --- a/docs/pt/docs/tutorial/request-form-models.md +++ b/docs/pt/docs/tutorial/request-form-models.md @@ -6,10 +6,10 @@ Você pode utilizar **Modelos Pydantic** para declarar **campos de formulários* Para utilizar formulários, instale primeiramente o [`python-multipart`](https://github.com/Kludex/python-multipart). -Certifique-se de criar um [ambiente virtual](../virtual-environments.md), ativá-lo, e então instalar. Por exemplo: +Adicione-o ao seu projeto: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/pt/docs/tutorial/request-forms-and-files.md b/docs/pt/docs/tutorial/request-forms-and-files.md index 45d6f5c..461c2bc 100644 --- a/docs/pt/docs/tutorial/request-forms-and-files.md +++ b/docs/pt/docs/tutorial/request-forms-and-files.md @@ -6,10 +6,10 @@ Você pode definir arquivos e campos de formulário ao mesmo tempo usando `File` Para receber arquivos carregados e/ou dados de formulário, primeiro instale [`python-multipart`](https://github.com/Kludex/python-multipart). -Certifique-se de criar um [ambiente virtual](../virtual-environments.md), ativá-lo e então instalar, por exemplo: +Adicione-o ao seu projeto: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/pt/docs/tutorial/request-forms.md b/docs/pt/docs/tutorial/request-forms.md index bfca356..f055157 100644 --- a/docs/pt/docs/tutorial/request-forms.md +++ b/docs/pt/docs/tutorial/request-forms.md @@ -6,10 +6,10 @@ Quando você precisar receber campos de formulário em vez de JSON, você pode u Para usar formulários, primeiro instale [`python-multipart`](https://github.com/Kludex/python-multipart). -Certifique-se de criar um [ambiente virtual](../virtual-environments.md), ativá-lo e então instalá-lo, por exemplo: +Adicione-o ao seu projeto: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/pt/docs/tutorial/response-model.md b/docs/pt/docs/tutorial/response-model.md index 1753f9d..2cbc50c 100644 --- a/docs/pt/docs/tutorial/response-model.md +++ b/docs/pt/docs/tutorial/response-model.md @@ -76,16 +76,16 @@ Aqui estamos declarando um modelo `UserIn`, ele conterá uma senha em texto simp Para usar `EmailStr`, primeiro instale [`email-validator`](https://github.com/JoshData/python-email-validator). -Certifique-se de criar um [ambiente virtual](../virtual-environments.md), ative-o e então instale-o, por exemplo: +Adicione-o ao seu projeto: ```console -$ pip install email-validator +$ uv add email-validator ``` ou com: ```console -$ pip install "pydantic[email]" +$ uv add "pydantic[email]" ``` /// @@ -202,7 +202,7 @@ Isso também funcionará porque `RedirectResponse` é uma subclasse de `Response Mas quando você retorna algum outro objeto arbitrário que não é um tipo Pydantic válido (por exemplo, um objeto de banco de dados) e você o anota dessa forma na função, o FastAPI tentará criar um modelo de resposta Pydantic a partir dessa anotação de tipo e falhará. -O mesmo aconteceria se você tivesse algo como uma união entre tipos diferentes onde um ou mais deles não são tipos Pydantic válidos, por exemplo, isso falharia 💥: +O mesmo aconteceria se você tivesse algo como uma união entre tipos diferentes onde um ou mais deles não são tipos Pydantic válidos, por exemplo, isso falharia 💥: {* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *} @@ -218,7 +218,7 @@ Neste caso, você pode desabilitar a geração do modelo de resposta definindo ` {* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *} -Isso fará com que o FastAPI pule a geração do modelo de resposta e, dessa forma, você pode ter quaisquer anotações de tipo de retorno que precisar sem afetar seu aplicativo FastAPI. 🤓 +Isso fará com que o FastAPI pule a geração do modelo de resposta e, dessa forma, você pode ter quaisquer anotações de tipo de retorno que precisar sem afetar sua aplicação FastAPI. 🤓 ## Parâmetros de codificação do modelo de resposta { #response-model-encoding-parameters } @@ -242,7 +242,7 @@ Você pode definir o parâmetro `response_model_exclude_unset=True` do *decorado e esses valores padrão não serão incluídos na resposta, apenas os valores realmente definidos. -Então, se você enviar uma solicitação para essa *operação de rota* para o item com ID `foo`, a resposta (sem incluir valores padrão) será: +Então, se você enviar uma request para essa *operação de rota* para o item com ID `foo`, a resposta (sem incluir valores padrão) será: ```JSON { @@ -258,7 +258,7 @@ Você também pode usar: * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -conforme descrito na [documentação do Pydantic](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict) para `exclude_defaults` e `exclude_none`. +conforme descrito na [documentação do Pydantic](https://pydantic.dev/docs/validation/latest/concepts/serialization/#excluding-and-including-fields-based-on-their-value) para `exclude_defaults` e `exclude_none`. /// @@ -291,7 +291,7 @@ Se os dados tiverem os mesmos valores que os padrões, como o item com ID `baz`: } ``` -O FastAPI é inteligente o suficiente (na verdade, o Pydantic é inteligente o suficiente) para perceber que, embora `description`, `tax` e `tags` tenham os mesmos valores que os padrões, eles foram definidos explícita e diretamente (em vez de retirados dos padrões). +O FastAPI é inteligente o suficiente (na verdade, o Pydantic é inteligente o suficiente) para perceber que, embora `description`, `tax` e `tags` tenham os mesmos valores que os padrões, eles foram definidos explicitamente (em vez de retirados dos padrões). Portanto, eles serão incluídos na resposta JSON. diff --git a/docs/pt/docs/tutorial/schema-extra-example.md b/docs/pt/docs/tutorial/schema-extra-example.md index 6e10c58..941212f 100644 --- a/docs/pt/docs/tutorial/schema-extra-example.md +++ b/docs/pt/docs/tutorial/schema-extra-example.md @@ -13,7 +13,7 @@ Você pode declarar `examples` para um modelo Pydantic que serão adicionados ao Essas informações extras serão adicionadas como estão ao **JSON Schema** de saída para esse modelo e serão usadas na documentação da API. -Você pode usar o atributo `model_config`, que recebe um `dict`, conforme descrito na [documentação do Pydantic: Configuration](https://docs.pydantic.dev/latest/api/config/). +Você pode usar o atributo `model_config`, que recebe um `dict`, conforme descrito na [documentação do Pydantic: Configuration](https://pydantic.dev/docs/validation/latest/api/pydantic/config/). Você pode definir `"json_schema_extra"` com um `dict` contendo quaisquer dados adicionais que você queira que apareçam no JSON Schema gerado, incluindo `examples`. diff --git a/docs/pt/docs/tutorial/security/first-steps.md b/docs/pt/docs/tutorial/security/first-steps.md index 9780f8a..f460f32 100644 --- a/docs/pt/docs/tutorial/security/first-steps.md +++ b/docs/pt/docs/tutorial/security/first-steps.md @@ -16,7 +16,7 @@ Vamos usar as ferramentas fornecidas pelo **FastAPI** para lidar com segurança. Vamos primeiro usar o código e ver como funciona, e depois voltaremos para entender o que está acontecendo. -## Crie um `main.py` { #create-main-py } +## Crie `main.py` { #create-main-py } Copie o exemplo em um arquivo `main.py`: @@ -26,14 +26,14 @@ Copie o exemplo em um arquivo `main.py`: /// note | Nota -O pacote [`python-multipart`](https://github.com/Kludex/python-multipart) é instalado automaticamente com o **FastAPI** quando você executa o comando `pip install "fastapi[standard]"`. +O pacote [`python-multipart`](https://github.com/Kludex/python-multipart) é instalado automaticamente com o **FastAPI** quando você executa o comando `uv add "fastapi[standard]"`. -Entretanto, se você usar o comando `pip install fastapi`, o pacote `python-multipart` não é incluído por padrão. +Entretanto, se você usar o comando `uv add fastapi`, o pacote `python-multipart` não é incluído por padrão. -Para instalá-lo manualmente, certifique-se de criar um [ambiente virtual](../../virtual-environments.md), ativá-lo e então instalá-lo com: +Para instalá-lo manualmente, adicione-o ao seu projeto com: ```console -$ pip install python-multipart +$ uv add python-multipart ``` Isso ocorre porque o **OAuth2** usa "form data" para enviar o `username` e o `password`. @@ -45,7 +45,7 @@ Execute o exemplo com:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -172,7 +172,7 @@ Agora você pode passar esse `oauth2_scheme` em uma dependência com `Depends`. {* ../../docs_src/security/tutorial001_an_py310.py hl[12] *} -Essa dependência fornecerá uma `str` que é atribuída ao parâmetro `token` da função de operação de rota. +Essa dependência fornecerá uma `str` que é atribuída ao parâmetro `token` da *função de operação de rota*. O **FastAPI** saberá que pode usar essa dependência para definir um "esquema de segurança" no esquema OpenAPI (e na documentação automática da API). diff --git a/docs/pt/docs/tutorial/security/oauth2-jwt.md b/docs/pt/docs/tutorial/security/oauth2-jwt.md index dbbbdc7..05ed450 100644 --- a/docs/pt/docs/tutorial/security/oauth2-jwt.md +++ b/docs/pt/docs/tutorial/security/oauth2-jwt.md @@ -28,14 +28,14 @@ Se você quiser brincar com tokens JWT e ver como eles funcionam, visite [https: ## Instalar `PyJWT` { #install-pyjwt } -Nós precisamos instalar o `PyJWT` para criar e verificar os tokens JWT em Python. +Nós precisamos instalar o `PyJWT` para gerar e verificar os tokens JWT em Python. -Certifique-se de criar um [ambiente virtual](../../virtual-environments.md), ativá-lo e então instalar o `pyjwt`: +Adicione `pyjwt` ao seu projeto:
```console -$ pip install pyjwt +$ uv add pyjwt ---> 100% ``` @@ -62,9 +62,9 @@ Mas não é possível converter os caracteres sem sentido de volta para a senha Se o seu banco de dados for roubado, o invasor não terá as senhas em texto puro dos seus usuários, apenas os hashes. -Então, o invasor não poderá tentar usar essas senhas em outro sistema (como muitos usuários utilizam a mesma senha em vários lugares, isso seria perigoso). +Então, o invasor não poderá tentar usar essa senha em outro sistema (como muitos usuários utilizam a mesma senha em vários lugares, isso seria perigoso). -## Instalar o `pwdlib` { #install-pwdlib } +## Instalar `pwdlib` { #install-pwdlib } pwdlib é um excelente pacote Python para lidar com hashes de senhas. @@ -72,12 +72,12 @@ Ele suporta muitos algoritmos de hashing seguros e utilitários para trabalhar c O algoritmo recomendado é o "Argon2". -Certifique-se de criar um [ambiente virtual](../../virtual-environments.md), ativá-lo e então instalar o pwdlib com Argon2: +Adicione `pwdlib` com Argon2 ao seu projeto:
```console -$ pip install "pwdlib[argon2]" +$ uv add "pwdlib[argon2]" ---> 100% ``` @@ -215,7 +215,7 @@ Password: `secret` /// tip | Dica -Observe que em nenhuma parte do código está a senha em texto puro "`secret`", nós temos apenas o hash. +Observe que em nenhuma parte do código está a senha em texto puro "`secret`", nós temos apenas a versão com hash. /// @@ -234,7 +234,7 @@ Chame o endpoint `/users/me/`, você receberá o retorno como: -Se você abrir as ferramentas de desenvolvedor, poderá ver que os dados enviados incluem apenas o token. A senha é enviada apenas na primeira requisição para autenticar o usuário e obter o token de acesso, mas não é enviada nas próximas requisições: +Se você abrir as ferramentas de desenvolvedor, poderá ver que os dados enviados incluem apenas o token. A senha é enviada apenas na primeira requisição para autenticar o usuário e obter o token de acesso, mas não depois: diff --git a/docs/pt/docs/tutorial/sql-databases.md b/docs/pt/docs/tutorial/sql-databases.md index e715007..dd27ccf 100644 --- a/docs/pt/docs/tutorial/sql-databases.md +++ b/docs/pt/docs/tutorial/sql-databases.md @@ -34,12 +34,12 @@ Este é um tutorial muito simples e curto, se você quiser aprender sobre bancos ## Instale o `SQLModel` { #install-sqlmodel } -Primeiro, certifique-se de criar seu [ambiente virtual](../virtual-environments.md), ativá-lo e, em seguida, instalar o `sqlmodel`: +Adicione `sqlmodel` ao seu projeto:
```console -$ pip install sqlmodel +$ uv add sqlmodel ---> 100% ``` @@ -152,7 +152,7 @@ Você pode executar o app:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -337,7 +337,7 @@ Você pode executar o app novamente:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/pt/docs/tutorial/static-files.md b/docs/pt/docs/tutorial/static-files.md index 4e8d431..e3e59dc 100644 --- a/docs/pt/docs/tutorial/static-files.md +++ b/docs/pt/docs/tutorial/static-files.md @@ -45,4 +45,4 @@ Todos esses parâmetros podem ser diferentes de "`static`", ajuste-os de acordo ## Mais informações { #more-info } -Para mais detalhes e opções, consulte [a documentação da Starlette sobre Arquivos Estáticos](https://www.starlette.dev/staticfiles/). +Para mais detalhes e opções, consulte [a documentação da Starlette sobre Arquivos Estáticos](https://starlette.dev/staticfiles/). diff --git a/docs/pt/docs/tutorial/testing.md b/docs/pt/docs/tutorial/testing.md index 9d94cdd..f72b351 100644 --- a/docs/pt/docs/tutorial/testing.md +++ b/docs/pt/docs/tutorial/testing.md @@ -1,6 +1,6 @@ # Testando { #testing } -Graças ao [Starlette](https://www.starlette.dev/testclient/), testar aplicações **FastAPI** é fácil e agradável. +Graças ao [Starlette](https://starlette.dev/testclient/), testar aplicações **FastAPI** é fácil e agradável. Ele é baseado no [HTTPX](https://www.python-httpx.org), que por sua vez é projetado com base em Requests, por isso é muito familiar e intuitivo. @@ -12,10 +12,10 @@ Com ele, você pode usar o [pytest](https://docs.pytest.org/) diretamente com ** Para usar o `TestClient`, primeiro instale [`httpx`](https://www.python-httpx.org). -Certifique-se de criar um [ambiente virtual](../virtual-environments.md), ativá-lo e instalá-lo, por exemplo: +Adicione-o ao seu projeto: ```console -$ pip install httpx +$ uv add httpx ``` /// @@ -156,12 +156,12 @@ Se você tiver um modelo Pydantic em seu teste e quiser enviar seus dados para a Depois disso, você só precisa instalar o `pytest`. -Certifique-se de criar um [ambiente virtual](../virtual-environments.md), ativá-lo e instalá-lo, por exemplo: +Adicione-o ao seu projeto:
```console -$ pip install pytest +$ uv add pytest ---> 100% ``` @@ -175,7 +175,7 @@ Execute os testes com:
```console -$ pytest +$ uv run pytest ================ test session starts ================ platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1 diff --git a/docs/pt/docs/virtual-environments.md b/docs/pt/docs/virtual-environments.md index 121032d..3442a05 100644 --- a/docs/pt/docs/virtual-environments.md +++ b/docs/pt/docs/virtual-environments.md @@ -1,864 +1,35 @@ # Ambientes Virtuais { #virtual-environments } -Ao trabalhar em projetos Python, você provavelmente deveria usar um **ambiente virtual** (ou um mecanismo similar) para isolar os pacotes que você instala para cada projeto. +Ao trabalhar com projetos Python, você deveria usar um **ambiente virtual** para isolar os pacotes instalados para cada projeto. -/// note | Nota - -Se você já sabe sobre ambientes virtuais, como criá-los e usá-los, talvez seja melhor pular esta seção. 🤓 - -/// - -/// tip | Dica - -Um **ambiente virtual** é diferente de uma **variável de ambiente**. - -Uma **variável de ambiente** é uma variável no sistema que pode ser usada por programas. - -Um **ambiente virtual** é um diretório com alguns arquivos. - -/// - -/// note | Nota - -Esta página lhe ensinará como usar **ambientes virtuais** e como eles funcionam. - -Se você estiver pronto para adotar uma **ferramenta que gerencia tudo** para você (incluindo a instalação do Python), experimente [uv](https://github.com/astral-sh/uv). - -/// +Para projetos FastAPI, recomendo usar [uv](https://docs.astral.sh/uv/) para gerenciar o projeto, suas dependências e seu ambiente virtual. ## Crie um Projeto { #create-a-project } -Primeiro, crie um diretório para seu projeto. - -O que normalmente faço é criar um diretório chamado `code` dentro do meu diretório home/user. - -E dentro disso eu crio um diretório por projeto. +Instale `uv` usando o [guia oficial de instalação](https://docs.astral.sh/uv/getting-started/installation/) e então crie um projeto:
```console -// Vá para o diretório inicial -$ cd -// Crie um diretório para todos os seus projetos de código -$ mkdir code -// Entre nesse diretório de código -$ cd code -// Crie um diretório para este projeto -$ mkdir awesome-project -// Entre no diretório do projeto +$ uv init awesome-project --bare $ cd awesome-project +$ uv add "fastapi[standard]" ```
-## Crie um ambiente virtual { #create-a-virtual-environment } +`uv` cria um ambiente virtual para o projeto automaticamente. Você não precisa criar ou ativar um por conta própria. -Ao começar a trabalhar em um projeto Python **pela primeira vez**, crie um ambiente virtual **dentro do seu projeto**. - -/// tip | Dica - -Você só precisa fazer isso **uma vez por projeto**, não toda vez que trabalhar. - -/// - -//// tab | `venv` - -Para criar um ambiente virtual, você pode usar o módulo `venv` que vem com o Python. +Execute comandos dentro do ambiente do projeto com `uv run`, por exemplo:
```console -$ python -m venv .venv +$ uv run fastapi dev ```
-/// details | O que esse comando significa +## Saiba Mais { #learn-more } -* `python`: usa o programa chamado `python` -* `-m`: chama um módulo como um script, nós diremos a ele qual módulo vem em seguida -* `venv`: usa o módulo chamado `venv` que normalmente vem instalado com o Python -* `.venv`: cria o ambiente virtual no novo diretório `.venv` - -/// - -//// - -//// tab | `uv` - -Se você tiver [`uv`](https://github.com/astral-sh/uv) instalado, poderá usá-lo para criar um ambiente virtual. - -
- -```console -$ uv venv -``` - -
- -/// tip | Dica - -Por padrão, `uv` criará um ambiente virtual em um diretório chamado `.venv`. - -Mas você pode personalizá-lo passando um argumento adicional com o nome do diretório. - -/// - -//// - -Esse comando cria um novo ambiente virtual em um diretório chamado `.venv`. - -/// details | `.venv` ou outro nome - -Você pode criar o ambiente virtual em um diretório diferente, mas há uma convenção para chamá-lo de `.venv`. - -/// - -## Ative o ambiente virtual { #activate-the-virtual-environment } - -Ative o novo ambiente virtual para que qualquer comando Python que você executar ou pacote que você instalar o utilize. - -/// tip | Dica - -Faça isso **toda vez** que iniciar uma **nova sessão de terminal** para trabalhar no projeto. - -/// - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Ou se você usa o Bash para Windows (por exemplo, [Git Bash](https://gitforwindows.org/)): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -/// tip | Dica - -Toda vez que você instalar um **novo pacote** naquele ambiente, **ative** o ambiente novamente. - -Isso garante que, se você usar um **programa de terminal (CLI)** instalado por esse pacote, você usará aquele do seu ambiente virtual e não qualquer outro que possa ser instalado globalmente, provavelmente com uma versão diferente do que você precisa. - -/// - -## Verifique se o ambiente virtual está ativo { #check-the-virtual-environment-is-active } - -Verifique se o ambiente virtual está ativo (o comando anterior funcionou). - -/// tip | Dica - -Isso é **opcional**, mas é uma boa maneira de **verificar** se tudo está funcionando conforme o esperado e se você está usando o ambiente virtual pretendido. - -/// - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -Se ele mostrar o binário `python` em `.venv/bin/python`, dentro do seu projeto (neste caso `awesome-project`), então funcionou. 🎉 - -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -Se ele mostrar o binário `python` em `.venv\Scripts\python`, dentro do seu projeto (neste caso `awesome-project`), então funcionou. 🎉 - -//// - -## Atualize `pip` { #upgrade-pip } - -/// tip | Dica - -Se você usar [`uv`](https://github.com/astral-sh/uv), você o usará para instalar coisas em vez do `pip`, então não precisará atualizar o `pip`. 😎 - -/// - -Se você estiver usando `pip` para instalar pacotes (ele vem por padrão com o Python), você deveria **atualizá-lo** para a versão mais recente. - -Muitos erros exóticos durante a instalação de um pacote são resolvidos apenas atualizando o `pip` primeiro. - -/// tip | Dica - -Normalmente, você faria isso **uma vez**, logo após criar o ambiente virtual. - -/// - -Certifique-se de que o ambiente virtual esteja ativo (com o comando acima) e execute: - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip | Dica - -Às vezes, você pode receber um erro **`No module named pip`** ao tentar atualizar o pip. - -Se isso acontecer, instale e atualize o pip usando o comando abaixo: - -
- -```console -$ python -m ensurepip --upgrade - ----> 100% -``` - -
- -Esse comando instalará o pip caso ele ainda não esteja instalado e também garante que a versão instalada do pip seja pelo menos tão recente quanto a disponível em `ensurepip`. - -/// - -## Adicione `.gitignore` { #add-gitignore } - -Se você estiver usando **Git** (você deveria), adicione um arquivo `.gitignore` para excluir tudo em seu `.venv` do Git. - -/// tip | Dica - -Se você usou [`uv`](https://github.com/astral-sh/uv) para criar o ambiente virtual, ele já fez isso para você, você pode pular esta etapa. 😎 - -/// - -/// tip | Dica - -Faça isso **uma vez**, logo após criar o ambiente virtual. - -/// - -
- -```console -$ echo "*" > .venv/.gitignore -``` - -
- -/// details | O que esse comando significa - -* `echo "*"`: irá "imprimir" o texto `*` no terminal (a próxima parte muda isso um pouco) -* `>`: qualquer coisa impressa no terminal pelo comando à esquerda de `>` não deve ser impressa, mas sim escrita no arquivo que vai à direita de `>` -* `.gitignore`: o nome do arquivo onde o texto deve ser escrito - -E `*` para Git significa "tudo". Então, ele ignorará tudo no diretório `.venv`. - -Esse comando criará um arquivo `.gitignore` com o conteúdo: - -```gitignore -* -``` - -/// - -## Instale Pacotes { #install-packages } - -Após ativar o ambiente, você pode instalar pacotes nele. - -/// tip | Dica - -Faça isso **uma vez** ao instalar ou atualizar os pacotes que seu projeto precisa. - -Se precisar atualizar uma versão ou adicionar um novo pacote, você **fará isso novamente**. - -/// - -### Instale pacotes diretamente { #install-packages-directly } - -Se estiver com pressa e não quiser usar um arquivo para declarar os requisitos de pacote do seu projeto, você pode instalá-los diretamente. - -/// tip | Dica - -É uma (muito) boa ideia colocar os pacotes e versões que seu programa precisa em um arquivo (por exemplo `requirements.txt` ou `pyproject.toml`). - -/// - -//// tab | `pip` - -
- -```console -$ pip install "fastapi[standard]" - ----> 100% -``` - -
- -//// - -//// tab | `uv` - -Se você tem o [`uv`](https://github.com/astral-sh/uv): - -
- -```console -$ uv pip install "fastapi[standard]" ----> 100% -``` - -
- -//// - -### Instale a partir de `requirements.txt` { #install-from-requirements-txt } - -Se você tiver um `requirements.txt`, agora poderá usá-lo para instalar seus pacotes. - -//// tab | `pip` - -
- -```console -$ pip install -r requirements.txt ----> 100% -``` - -
- -//// - -//// tab | `uv` - -Se você tem o [`uv`](https://github.com/astral-sh/uv): - -
- -```console -$ uv pip install -r requirements.txt ----> 100% -``` - -
- -//// - -/// details | `requirements.txt` - -Um `requirements.txt` com alguns pacotes poderia se parecer com: - -```requirements.txt -fastapi[standard]==0.113.0 -pydantic==2.8.0 -``` - -/// - -## Execute seu programa { #run-your-program } - -Depois de ativar o ambiente virtual, você pode executar seu programa, e ele usará o Python dentro do seu ambiente virtual com os pacotes que você instalou lá. - -
- -```console -$ python main.py - -Hello World -``` - -
- -## Configure seu editor { #configure-your-editor } - -Você provavelmente usaria um editor. Certifique-se de configurá-lo para usar o mesmo ambiente virtual que você criou (ele provavelmente o detectará automaticamente) para que você possa obter preenchimento automático e erros em linha. - -Por exemplo: - -* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) -* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) - -/// tip | Dica - -Normalmente, você só precisa fazer isso **uma vez**, ao criar o ambiente virtual. - -/// - -## Desative o ambiente virtual { #deactivate-the-virtual-environment } - -Quando terminar de trabalhar no seu projeto, você pode **desativar** o ambiente virtual. - -
- -```console -$ deactivate -``` - -
- -Dessa forma, quando você executar `python`, ele não tentará executá-lo naquele ambiente virtual com os pacotes instalados nele. - -## Pronto para trabalhar { #ready-to-work } - -Agora você está pronto para começar a trabalhar no seu projeto. - - - -/// tip | Dica - -Você quer entender o que é tudo isso acima? - -Continue lendo. 👇🤓 - -/// - -## Por que ambientes virtuais { #why-virtual-environments } - -Para trabalhar com o FastAPI, você precisa instalar o [Python](https://www.python.org/). - -Depois disso, você precisará **instalar** o FastAPI e quaisquer outros **pacotes** que queira usar. - -Para instalar pacotes, você normalmente usaria o comando `pip` que vem com o Python (ou alternativas semelhantes). - -No entanto, se você usar `pip` diretamente, os pacotes serão instalados no seu **ambiente Python global** (a instalação global do Python). - -### O Problema { #the-problem } - -Então, qual é o problema em instalar pacotes no ambiente global do Python? - -Em algum momento, você provavelmente acabará escrevendo muitos programas diferentes que dependem de **pacotes diferentes**. E alguns desses projetos em que você trabalha dependerão de **versões diferentes** do mesmo pacote. 😱 - -Por exemplo, você pode criar um projeto chamado `philosophers-stone`, este programa depende de outro pacote chamado **`harry`, usando a versão `1`**. Então, você precisa instalar `harry`. - -```mermaid -flowchart LR - stone(philosophers-stone) -->|requires| harry-1[harry v1] -``` - -Então, em algum momento depois, você cria outro projeto chamado `prisoner-of-azkaban`, e esse projeto também depende de `harry`, mas esse projeto precisa do **`harry` versão `3`**. - -```mermaid -flowchart LR - azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3] -``` - -Mas agora o problema é que, se você instalar os pacotes globalmente (no ambiente global) em vez de em um **ambiente virtual** local, você terá que escolher qual versão do `harry` instalar. - -Se você quiser executar `philosophers-stone`, precisará primeiro instalar `harry` versão `1`, por exemplo com: - -
- -```console -$ pip install "harry==1" -``` - -
- -E então você acabaria com `harry` versão `1` instalado em seu ambiente Python global. - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -->|requires| harry-1 - end -``` - -Mas se você quiser executar `prisoner-of-azkaban`, você precisará desinstalar `harry` versão `1` e instalar `harry` versão `3` (ou apenas instalar a versão `3` desinstalaria automaticamente a versão `1`). - -
- -```console -$ pip install "harry==3" -``` - -
- -E então você acabaria com `harry` versão `3` instalado em seu ambiente Python global. - -E se você tentar executar `philosophers-stone` novamente, há uma chance de que **não funcione** porque ele precisa de `harry` versão `1`. - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - style harry-1 fill:#ccc,stroke-dasharray: 5 5 - harry-3[harry v3] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -.-x|⛔️| harry-1 - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --> |requires| harry-3 - end -``` - -/// tip | Dica - -É muito comum em pacotes Python tentar ao máximo **evitar alterações drásticas** em **novas versões**, mas é melhor prevenir do que remediar e instalar versões mais recentes intencionalmente e, quando possível, executar os testes para verificar se tudo está funcionando corretamente. - -/// - -Agora, imagine isso com **muitos** outros **pacotes** dos quais todos os seus **projetos dependem**. Isso é muito difícil de gerenciar. E você provavelmente acabaria executando alguns projetos com algumas **versões incompatíveis** dos pacotes, e não saberia por que algo não está funcionando. - -Além disso, dependendo do seu sistema operacional (por exemplo, Linux, Windows, macOS), ele pode ter vindo com o Python já instalado. E, nesse caso, provavelmente tinha alguns pacotes pré-instalados com algumas versões específicas **necessárias para o seu sistema**. Se você instalar pacotes no ambiente global do Python, poderá acabar **quebrando** alguns dos programas que vieram com seu sistema operacional. - -## Onde os pacotes são instalados { #where-are-packages-installed } - -Quando você instala o Python, ele cria alguns diretórios com alguns arquivos no seu computador. - -Alguns desses diretórios são os responsáveis ​​por ter todos os pacotes que você instala. - -Quando você executa: - -
- -```console -// Não execute isso agora, é apenas um exemplo 🤓 -$ pip install "fastapi[standard]" ----> 100% -``` - -
- -Isso fará o download de um arquivo compactado com o código FastAPI, normalmente do [PyPI](https://pypi.org/project/fastapi/). - -Ele também fará o **download** de arquivos para outros pacotes dos quais o FastAPI depende. - -Em seguida, ele **extrairá** todos esses arquivos e os colocará em um diretório no seu computador. - -Por padrão, ele colocará os arquivos baixados e extraídos no diretório que vem com a instalação do Python, que é o **ambiente global**. - -## O que são ambientes virtuais { #what-are-virtual-environments } - -A solução para os problemas de ter todos os pacotes no ambiente global é usar um **ambiente virtual para cada projeto** em que você trabalha. - -Um ambiente virtual é um **diretório**, muito semelhante ao global, onde você pode instalar os pacotes para um projeto. - -Dessa forma, cada projeto terá seu próprio ambiente virtual (diretório `.venv`) com seus próprios pacotes. - -```mermaid -flowchart TB - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) --->|requires| harry-1 - subgraph venv1[.venv] - harry-1[harry v1] - end - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --->|requires| harry-3 - subgraph venv2[.venv] - harry-3[harry v3] - end - end - stone-project ~~~ azkaban-project -``` - -## O que significa ativar um ambiente virtual { #what-does-activating-a-virtual-environment-mean } - -Quando você ativa um ambiente virtual, por exemplo com: - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Ou se você usa o Bash para Windows (por exemplo, [Git Bash](https://gitforwindows.org/)): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -Esse comando criará ou modificará algumas [variáveis ​​de ambiente](environment-variables.md) que estarão disponíveis para os próximos comandos. - -Uma dessas variáveis ​​é a variável `PATH`. - -/// tip | Dica - -Você pode aprender mais sobre a variável de ambiente `PATH` na seção [Variáveis ​​de ambiente](environment-variables.md#path-environment-variable). - -/// - -A ativação de um ambiente virtual adiciona seu caminho `.venv/bin` (no Linux e macOS) ou `.venv\Scripts` (no Windows) à variável de ambiente `PATH`. - -Digamos que antes de ativar o ambiente, a variável `PATH` estava assim: - -//// tab | Linux, macOS - -```plaintext -/usr/bin:/bin:/usr/sbin:/sbin -``` - -Isso significa que o sistema procuraria programas em: - -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Windows\System32 -``` - -Isso significa que o sistema procuraria programas em: - -* `C:\Windows\System32` - -//// - -Após ativar o ambiente virtual, a variável `PATH` ficaria mais ou menos assim: - -//// tab | Linux, macOS - -```plaintext -/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -Isso significa que o sistema agora começará a procurar primeiro por programas em: - -```plaintext -/home/user/code/awesome-project/.venv/bin -``` - -antes de procurar nos outros diretórios. - -Então, quando você digita `python` no terminal, o sistema encontrará o programa Python em - -```plaintext -/home/user/code/awesome-project/.venv/bin/python -``` - -e usa esse. - -//// - -//// tab | Windows - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32 -``` - -Isso significa que o sistema agora começará a procurar primeiro por programas em: - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts -``` - -antes de procurar nos outros diretórios. - -Então, quando você digita `python` no terminal, o sistema encontrará o programa Python em - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -e usa esse. - -//// - -Um detalhe importante é que ele colocará o caminho do ambiente virtual no **início** da variável `PATH`. O sistema o encontrará **antes** de encontrar qualquer outro Python disponível. Dessa forma, quando você executar `python`, ele usará o Python **do ambiente virtual** em vez de qualquer outro `python` (por exemplo, um `python` de um ambiente global). - -Ativar um ambiente virtual também muda algumas outras coisas, mas esta é uma das mais importantes. - -## Verificando um ambiente virtual { #checking-a-virtual-environment } - -Ao verificar se um ambiente virtual está ativo, por exemplo com: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -//// - -Isso significa que o programa `python` que será usado é aquele **no ambiente virtual**. - -Você usa `which` no Linux e macOS e `Get-Command` no Windows PowerShell. - -A maneira como esse comando funciona é que ele vai e verifica na variável de ambiente `PATH`, passando por **cada caminho em ordem**, procurando pelo programa chamado `python`. Uma vez que ele o encontre, ele **mostrará o caminho** para esse programa. - -A parte mais importante é que quando você chama `python`, esse é exatamente o "`python`" que será executado. - -Assim, você pode confirmar se está no ambiente virtual correto. - -/// tip | Dica - -É fácil ativar um ambiente virtual, obter um Python e então **ir para outro projeto**. - -E o segundo projeto **não funcionaria** porque você está usando o **Python incorreto**, de um ambiente virtual para outro projeto. - -É útil poder verificar qual `python` está sendo usado. 🤓 - -/// - -## Por que desativar um ambiente virtual { #why-deactivate-a-virtual-environment } - -Por exemplo, você pode estar trabalhando em um projeto `philosophers-stone`, **ativar esse ambiente virtual**, instalar pacotes e trabalhar com esse ambiente. - -E então você quer trabalhar em **outro projeto** `prisoner-of-azkaban`. - -Você vai para aquele projeto: - -
- -```console -$ cd ~/code/prisoner-of-azkaban -``` - -
- -Se você não desativar o ambiente virtual para `philosophers-stone`, quando você executar `python` no terminal, ele tentará usar o Python de `philosophers-stone`. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -$ python main.py - -// Erro ao importar sirius, ele não está instalado 😱 -Traceback (most recent call last): - File "main.py", line 1, in - import sirius -``` - -
- -Mas se você desativar o ambiente virtual e ativar o novo para `prisoner-of-azkaban`, quando você executar `python`, ele usará o Python do ambiente virtual em `prisoner-of-azkaban`. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -// Você não precisa estar no diretório antigo para desativar, você pode fazer isso de onde estiver, mesmo depois de ir para o outro projeto 😎 -$ deactivate - -// Ative o ambiente virtual em prisoner-of-azkaban/.venv 🚀 -$ source .venv/bin/activate - -// Agora, quando você executar o python, ele encontrará o pacote sirius instalado neste ambiente virtual ✨ -$ python main.py - -I solemnly swear 🐺 -``` - -
- -## Alternativas { #alternatives } - -Este é um guia simples para você começar e lhe ensinar como tudo funciona **por baixo**. - -Existem muitas **alternativas** para gerenciar ambientes virtuais, dependências de pacotes (requisitos) e projetos. - -Quando estiver pronto e quiser usar uma ferramenta para **gerenciar todo o projeto**, dependências de pacotes, ambientes virtuais, etc., sugiro que você experimente o [uv](https://github.com/astral-sh/uv). - -`uv` pode fazer muitas coisas, ele pode: - -* **Instalar o Python** para você, incluindo versões diferentes -* Gerenciar o **ambiente virtual** para seus projetos -* Instalar **pacotes** -* Gerenciar **dependências e versões** de pacotes para seu projeto -* Certificar-se de que você tenha um conjunto **exato** de pacotes e versões para instalar, incluindo suas dependências, para que você possa ter certeza de que pode executar seu projeto em produção exatamente da mesma forma que em seu computador durante o desenvolvimento, isso é chamado de **bloqueio** -* E muitas outras coisas - -## Conclusão { #conclusion } - -Se você leu e entendeu tudo isso, agora **você sabe muito mais** sobre ambientes virtuais do que muitos desenvolvedores por aí. 🤓 - -Saber esses detalhes provavelmente será útil no futuro, quando você estiver depurando algo que parece complexo, mas você saberá **como tudo funciona por baixo**. 😎 +Leia o [guia de Ambientes Virtuais](https://tiangolo.com/guides/virtual-environments/) para aprender como ambientes virtuais funcionam por baixo, incluindo ativação e o fluxo de trabalho alternativo com `python -m venv` e `pip`. diff --git a/docs/ru/docs/advanced/additional-responses.md b/docs/ru/docs/advanced/additional-responses.md index ef9d3f2..d09672a 100644 --- a/docs/ru/docs/advanced/additional-responses.md +++ b/docs/ru/docs/advanced/additional-responses.md @@ -16,7 +16,7 @@ ## Дополнительный ответ с `model` { #additional-response-with-model } -Вы можете передать вашим декораторам операции пути параметр `responses`. +Вы можете передать вашим *декораторам операций пути* параметр `responses`. Он принимает `dict`: ключи — это статус-коды для каждого ответа (например, `200`), а значения — другие `dict` с информацией для каждого из них. @@ -49,7 +49,7 @@ /// -Сгенерированные в OpenAPI ответы для этой операции пути будут такими: +Сгенерированные в OpenAPI ответы для этой *операции пути* будут такими: ```JSON hl_lines="3-12" { @@ -173,7 +173,7 @@ Вы можете использовать этот же параметр `responses`, чтобы добавить разные типы содержимого для того же основного ответа. -Например, вы можете добавить дополнительный тип содержимого `image/png`, объявив, что ваша операция пути может возвращать JSON‑объект (с типом содержимого `application/json`) или PNG‑изображение: +Например, вы можете добавить дополнительный тип содержимого `image/png`, объявив, что ваша *операция пути* может возвращать JSON‑объект (с типом содержимого `application/json`) или PNG‑изображение: {* ../../docs_src/additional_responses/tutorial002_py310.py hl[17:22,26] *} @@ -211,7 +211,7 @@ ## Комбинирование предопределённых и пользовательских ответов { #combine-predefined-responses-and-custom-ones } -Возможно, вы хотите иметь некоторые предопределённые ответы, применимые ко многим операциям пути, но при этом комбинировать их с пользовательскими ответами, необходимыми для каждой конкретной операции пути. +Возможно, вы хотите иметь некоторые предопределённые ответы, применимые ко многим *операциям пути*, но при этом комбинировать их с пользовательскими ответами, необходимыми для каждой конкретной *операции пути*. В таких случаях вы можете использовать приём Python «распаковки» `dict` с помощью `**dict_to_unpack`: @@ -233,7 +233,7 @@ new_dict = {**old_dict, "new key": "new value"} } ``` -Вы можете использовать этот приём, чтобы переиспользовать некоторые предопределённые ответы в ваших операциях пути и комбинировать их с дополнительными пользовательскими. +Вы можете использовать этот приём, чтобы переиспользовать некоторые предопределённые ответы в ваших *операциях пути* и комбинировать их с дополнительными пользовательскими. Например: @@ -243,5 +243,5 @@ new_dict = {**old_dict, "new key": "new value"} Чтобы увидеть, что именно можно включать в ответы, посмотрите эти разделы спецификации OpenAPI: -* [Объект Responses OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object), он включает `Response Object`. -* [Объект Response OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object), вы можете включить всё из этого объекта напрямую в каждый ответ внутри вашего параметра `responses`. Включая `description`, `headers`, `content` (внутри него вы объявляете разные типы содержимого и JSON‑схемы) и `links`. +* [Объект Responses OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object), он включает `Response Object`. +* [Объект Response OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object), вы можете включить всё из этого объекта напрямую в каждый ответ внутри вашего параметра `responses`. Включая `description`, `headers`, `content` (внутри него вы объявляете разные типы содержимого и JSON‑схемы) и `links`. diff --git a/docs/ru/docs/advanced/async-tests.md b/docs/ru/docs/advanced/async-tests.md index 1c0b888..004183b 100644 --- a/docs/ru/docs/advanced/async-tests.md +++ b/docs/ru/docs/advanced/async-tests.md @@ -1,8 +1,8 @@ # Асинхронное тестирование { #async-tests } -Вы уже видели как тестировать **FastAPI** приложение, используя имеющийся класс `TestClient`. К этому моменту вы видели только как писать тесты в синхронном стиле без использования `async` функций. +Вы уже видели, как тестировать **FastAPI** приложение, используя имеющийся класс `TestClient`. К этому моменту вы видели только, как писать тесты в синхронном стиле без использования `async` функций. -Возможность использования асинхронных функций в ваших тестах может быть полезнa, когда, например, вы асинхронно обращаетесь к вашей базе данных. Представьте, что вы хотите отправить запросы в ваше FastAPI приложение, а затем при помощи асинхронной библиотеки для работы с базой данных удостовериться, что ваш бекэнд корректно записал данные в базу данных. +Возможность использования асинхронных функций в ваших тестах может быть полезна, когда, например, вы асинхронно обращаетесь к вашей базе данных. Представьте, что вы хотите отправить запросы в ваше FastAPI приложение, а затем при помощи асинхронной библиотеки для работы с базой данных удостовериться, что ваш бекэнд корректно записал данные в базу данных. Давайте рассмотрим, как мы можем это реализовать. @@ -45,7 +45,7 @@
```console -$ pytest +$ uv run pytest ---> 100% ``` @@ -78,7 +78,7 @@ response = client.get('/') /// tip | Подсказка -Обратите внимание, что мы используем async/await с `AsyncClient` - запрос асинхронный. +Обратите внимание, что мы используем async/await с новым `AsyncClient` - запрос асинхронный. /// @@ -90,10 +90,10 @@ response = client.get('/') ## Вызов других асинхронных функций { #other-asynchronous-function-calls } -Теперь тестовая функция стала асинхронной, поэтому внутри нее вы можете вызывать также и другие `async` функции, не связанные с отправлением запросов в ваше FastAPI приложение. Как если бы вы вызывали их в любом другом месте вашего кода. +Теперь тестовая функция стала асинхронной, поэтому внутри нее вы можете вызывать (и использовать `await` для) другие `async` функции, помимо отправки запросов в ваше FastAPI приложение в ваших тестах. Как если бы вы вызывали их в любом другом месте вашего кода. /// tip | Подсказка -Если вы столкнулись с `RuntimeError: Task attached to a different loop` при вызове асинхронных функций в ваших тестах (например, при использовании [MongoDB's MotorClient](https://stackoverflow.com/questions/41584243/runtimeerror-task-attached-to-a-different-loop)), то не забывайте создавать экземпляры объектов, которым нужен цикл событий (event loop), только внутри асинхронных функций, например, в `@app.on_event("startup")` callback. +Если вы столкнулись с `RuntimeError: Task attached to a different loop` при вызове асинхронных функций в ваших тестах (например, при использовании [MongoDB's MotorClient](https://stackoverflow.com/questions/41584243/runtimeerror-task-attached-to-a-different-loop)), то не забывайте создавать экземпляры объектов, которым нужен цикл событий, только внутри асинхронных функций, например, в `@app.on_event("startup")` callback. /// diff --git a/docs/ru/docs/advanced/behind-a-proxy.md b/docs/ru/docs/advanced/behind-a-proxy.md index 4f21286..ef2d8c8 100644 --- a/docs/ru/docs/advanced/behind-a-proxy.md +++ b/docs/ru/docs/advanced/behind-a-proxy.md @@ -33,7 +33,7 @@
```console -$ fastapi run --forwarded-allow-ips="*" +$ uv run fastapi run --forwarded-allow-ips="*" INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -80,7 +80,7 @@ sequenceDiagram Proxy->>Server: HTTP-запрос
X-Forwarded-For: [client IP]
X-Forwarded-Proto: https
X-Forwarded-Host: mysuperapp.com
Path: /items - Note over Server: Server интерпретирует HTTP-заголовки
(если --forwarded-allow-ips установлен) + Note over Server: Сервер интерпретирует HTTP-заголовки
(если --forwarded-allow-ips установлен) Server->>Proxy: HTTP-ответ
с верными HTTPS URLs @@ -170,7 +170,7 @@ IP `0.0.0.0` обычно означает, что программа слуша
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -200,7 +200,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -253,7 +253,7 @@ Uvicorn ожидает, что прокси обратится к нему по Вы можете легко поэкспериментировать локально с функцией удаления префикса пути, используя [Traefik](https://docs.traefik.io/). -[Скачайте Traefik](https://github.com/containous/traefik/releases) — это один бинарный файл; распакуйте архив и запустите его прямо из терминала. +[Скачайте Traefik](https://github.com/traefik/traefik/releases) — это один бинарный файл; распакуйте архив и запустите его прямо из терминала. Затем создайте файл `traefik.toml` со следующим содержимым: @@ -321,7 +321,7 @@ INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -358,7 +358,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 но уже по URL с префиксом, который добавляет прокси: `/api/v1`. -Разумеется, задумывается, что все будут обращаться к приложению через прокси, поэтому вариант с префиксом пути `/api/v1` является «правильным». +Разумеется, идея здесь в том, что все будут обращаться к приложению через прокси, поэтому вариант с префиксом пути `/api/v1` является «правильным». А вариант без префикса (`http://127.0.0.1:8000/app`), выдаваемый напрямую Uvicorn, предназначен исключительно для того, чтобы прокси (Traefik) мог к нему обращаться. diff --git a/docs/ru/docs/advanced/dataclasses.md b/docs/ru/docs/advanced/dataclasses.md index 5388e98..5683fce 100644 --- a/docs/ru/docs/advanced/dataclasses.md +++ b/docs/ru/docs/advanced/dataclasses.md @@ -6,7 +6,7 @@ FastAPI построен поверх **Pydantic**, и я показывал в {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -Это по-прежнему поддерживается благодаря **Pydantic**, так как в нём есть [встроенная поддержка `dataclasses`](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel). +Это по-прежнему поддерживается благодаря **Pydantic**, так как в нём есть [встроенная поддержка `dataclasses`](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/#usage-of-stdlib-dataclasses-with-basemodel). Так что даже если в коде выше Pydantic не используется явно, FastAPI использует Pydantic, чтобы конвертировать стандартные dataclasses в собственный вариант dataclasses от Pydantic. @@ -88,7 +88,7 @@ FastAPI построен поверх **Pydantic**, и я показывал в Вы также можете комбинировать `dataclasses` с другими Pydantic-моделями, наследоваться от них, включать их в свои модели и т.д. -Чтобы узнать больше, посмотрите [документацию Pydantic о dataclasses](https://docs.pydantic.dev/latest/concepts/dataclasses/). +Чтобы узнать больше, посмотрите [документацию Pydantic о dataclasses](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/). ## Версия { #version } diff --git a/docs/ru/docs/advanced/events.md b/docs/ru/docs/advanced/events.md index 0031957..7027f8a 100644 --- a/docs/ru/docs/advanced/events.md +++ b/docs/ru/docs/advanced/events.md @@ -154,7 +154,7 @@ async with lifespan(app): /// note | Примечание -Вы можете прочитать больше про обработчики `lifespan` в Starlette в [документации Starlette по Lifespan](https://www.starlette.dev/lifespan/). +Вы можете прочитать больше про обработчики `lifespan` в Starlette в [документации Starlette по Lifespan](https://starlette.dev/lifespan/). Включая то, как работать с состоянием lifespan, которое можно использовать в других частях вашего кода. diff --git a/docs/ru/docs/advanced/generate-clients.md b/docs/ru/docs/advanced/generate-clients.md index 04e8e88..47005cc 100644 --- a/docs/ru/docs/advanced/generate-clients.md +++ b/docs/ru/docs/advanced/generate-clients.md @@ -12,7 +12,7 @@ Для **TypeScript‑клиентов** [Hey API](https://heyapi.dev/) — специализированное решение, обеспечивающее оптимальный опыт для экосистемы TypeScript. -Больше генераторов SDK можно найти на [OpenAPI.Tools](https://openapi.tools/#sdk). +Больше генераторов SDK можно найти на [OpenAPI.Tools](https://openapi.tools/categories/sdk-generators). /// tip | Совет diff --git a/docs/ru/docs/advanced/middleware.md b/docs/ru/docs/advanced/middleware.md index 8058664..0ae54d4 100644 --- a/docs/ru/docs/advanced/middleware.md +++ b/docs/ru/docs/advanced/middleware.md @@ -8,7 +8,7 @@ ## Добавление ASGI middleware { #adding-asgi-middlewares } -Так как **FastAPI** основан на Starlette и реализует спецификацию ASGI, вы можете использовать любое ASGI middleware. +Так как **FastAPI** основан на Starlette и реализует спецификацию ASGI, вы можете использовать любое ASGI middleware. Middleware не обязательно должно быть сделано специально для FastAPI или Starlette — достаточно, чтобы оно соответствовало спецификации ASGI. @@ -24,7 +24,7 @@ app = SomeASGIApp() new_app = UnicornMiddleware(app, some_config="rainbow") ``` -Но FastAPI (точнее, Starlette) предоставляет более простой способ, который гарантирует корректную обработку внутренних ошибок сервера и корректную работу пользовательских обработчиков исключений. +Но FastAPI (точнее, Starlette) предоставляет более простой способ, который гарантирует, что внутренние middleware обрабатывают ошибки сервера, а пользовательские обработчики исключений работают корректно. Для этого используйте `app.add_middleware()` (как в примере с CORS). @@ -53,37 +53,37 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") ## `HTTPSRedirectMiddleware` { #httpsredirectmiddleware } -Гарантирует, что все входящие запросы должны использовать либо `https`, либо `wss`. +Гарантирует, что все входящие HTTP-запросы должны использовать либо `https`, либо `wss`. -Любой входящий запрос по `http` или `ws` будет перенаправлен на безопасную схему. +Любой входящий HTTP-запрос по `http` или `ws` будет перенаправлен на безопасную схему. {* ../../docs_src/advanced_middleware/tutorial001_py310.py hl[2,6] *} ## `TrustedHostMiddleware` { #trustedhostmiddleware } -Гарантирует, что во всех входящих запросах корректно установлен `Host`‑заголовок, чтобы защититься от атак на HTTP‑заголовок Host. +Гарантирует, что во всех входящих HTTP-запросах корректно установлен `Host` HTTP-заголовок, чтобы защититься от атак на HTTP-заголовок Host. {* ../../docs_src/advanced_middleware/tutorial002_py310.py hl[2,6:8] *} Поддерживаются следующие аргументы: -- `allowed_hosts` — список доменных имён, которые следует разрешить как имена хостов. Подстановки вида `*.example.com` поддерживаются для сопоставления поддоменов. Чтобы разрешить любой хост, используйте либо `allowed_hosts=["*"]`, либо не добавляйте это middleware. -- `www_redirect` — если установлено в True, запросы к не‑www версиям разрешённых хостов будут перенаправляться на их www‑аналоги. По умолчанию — `True`. +* `allowed_hosts` - список доменных имён, которые следует разрешить как имена хостов. Подстановки вида `*.example.com` поддерживаются для сопоставления поддоменов. Чтобы разрешить любой хост, используйте либо `allowed_hosts=["*"]`, либо не добавляйте это middleware. +* `www_redirect` - если установлено в True, запросы к не‑www версиям разрешённых хостов будут перенаправляться на их www‑аналоги. По умолчанию — `True`. -Если входящий запрос не проходит валидацию, будет отправлен ответ `400`. +Если входящий HTTP-запрос не проходит валидацию, будет отправлен HTTP-ответ `400`. ## `GZipMiddleware` { #gzipmiddleware } -Обрабатывает GZip‑ответы для любых запросов, которые включают `"gzip"` в заголовке `Accept-Encoding`. +Обрабатывает GZip‑ответы для любого HTTP-запроса, который включает `"gzip"` в HTTP-заголовке `Accept-Encoding`. -Это middleware обрабатывает как обычные, так и потоковые ответы. +Это middleware обрабатывает как обычные, так и потоковые HTTP-ответы. {* ../../docs_src/advanced_middleware/tutorial003_py310.py hl[2,6] *} Поддерживаются следующие аргументы: -- `minimum_size` — не сжимать GZip‑ом ответы, размер которых меньше этого минимального значения в байтах. По умолчанию — `500`. -- `compresslevel` — уровень GZip‑сжатия. Целое число от 1 до 9. По умолчанию — `9`. Более низкое значение — быстрее сжатие, но больший размер файла; более высокое значение — более медленное сжатие, но меньший размер файла. +* `minimum_size` - не сжимать GZip‑ом HTTP-ответы, размер которых меньше этого минимального значения в байтах. По умолчанию — `500`. +* `compresslevel` - уровень GZip‑сжатия. Целое число от 1 до 9. По умолчанию — `9`. Более низкое значение — быстрее сжатие, но больший размер файла; более высокое значение — более медленное сжатие, но меньший размер файла. ## Другие middleware { #other-middlewares } @@ -91,7 +91,7 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") Например: -- [`ProxyHeadersMiddleware` от Uvicorn](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) -- [MessagePack](https://github.com/florimondmanca/msgpack-asgi) +* [`ProxyHeadersMiddleware` от Uvicorn](https://github.com/Kludex/uvicorn/blob/main/uvicorn/middleware/proxy_headers.py) +* [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -Чтобы увидеть другие доступные middleware, посмотрите [документацию по middleware в Starlette](https://www.starlette.dev/middleware/) и [список ASGI Awesome](https://github.com/florimondmanca/awesome-asgi). +Чтобы увидеть другие доступные middleware, посмотрите [документацию по middleware в Starlette](https://starlette.dev/middleware/) и [список ASGI Awesome](https://github.com/florimondmanca/awesome-asgi). diff --git a/docs/ru/docs/advanced/openapi-callbacks.md b/docs/ru/docs/advanced/openapi-callbacks.md index 002b69c..8ab1fd9 100644 --- a/docs/ru/docs/advanced/openapi-callbacks.md +++ b/docs/ru/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ /// tip | Совет -Query-параметр `callback_url` использует тип Pydantic [Url](https://docs.pydantic.dev/latest/api/networks/). +Query-параметр `callback_url` использует тип Pydantic [Url](https://pydantic.dev/docs/validation/latest/api/pydantic/networks/). /// @@ -106,11 +106,11 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) Есть 2 основных отличия от обычной *операции пути*: * Ей не нужен реальный код, потому что ваше приложение никогда не будет вызывать эту функцию. Она используется только для документирования *внешнего API*. Поэтому в функции может быть просто `pass`. -* *Путь* может содержать [выражение OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) (подробнее ниже), где можно использовать переменные с параметрами и части исходного HTTP-запроса, отправленного *вашему API*. +* *Путь* может содержать [выражение OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression) (подробнее ниже), где можно использовать переменные с параметрами и части исходного HTTP-запроса, отправленного *вашему API*. ### Выражение пути для обратного вызова { #the-callback-path-expression } -*Путь* обратного вызова может содержать [выражение OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression), которое может включать части исходного запроса, отправленного *вашему API*. +*Путь* обратного вызова может содержать [выражение OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression), которое может включать части исходного запроса, отправленного *вашему API*. В нашем случае это `str`: diff --git a/docs/ru/docs/advanced/response-cookies.md b/docs/ru/docs/advanced/response-cookies.md index 3e16fe8..2080d13 100644 --- a/docs/ru/docs/advanced/response-cookies.md +++ b/docs/ru/docs/advanced/response-cookies.md @@ -1,6 +1,5 @@ # Cookies в ответе { #response-cookies } - ## Использование параметра `Response` { #use-a-response-parameter } Вы можете объявить параметр типа `Response` в вашей функции-обработчике пути. @@ -19,7 +18,7 @@ ## Возвращение `Response` напрямую { #return-a-response-directly } -Вы также можете установить Cookies, если возвращаете `Response` напрямую в вашем коде. +Вы также можете создать cookies, если возвращаете `Response` напрямую в вашем коде. Для этого создайте объект `Response`, как описано в разделе [Возвращение ответа напрямую](response-directly.md). @@ -49,4 +48,4 @@ /// -Чтобы увидеть все доступные параметры и настройки, ознакомьтесь с [документацией Starlette](https://www.starlette.dev/responses/#set-cookie). +Чтобы увидеть все доступные параметры и настройки, ознакомьтесь с [документацией Starlette](https://starlette.dev/responses/#set-cookie). diff --git a/docs/ru/docs/advanced/response-headers.md b/docs/ru/docs/advanced/response-headers.md index e0cfa66..4d50812 100644 --- a/docs/ru/docs/advanced/response-headers.md +++ b/docs/ru/docs/advanced/response-headers.md @@ -38,4 +38,4 @@ Помните, что собственные проприетарные HTTP-заголовки можно добавлять, [используя префикс `X-`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). -Но если у вас есть пользовательские HTTP-заголовки, которые вы хотите показывать клиенту в браузере, вам нужно добавить их в настройки CORS (подробнее см. в [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)), используя параметр `expose_headers`, описанный в [документации Starlette по CORS](https://www.starlette.dev/middleware/#corsmiddleware). +Но если у вас есть пользовательские HTTP-заголовки, которые вы хотите показывать клиенту в браузере, вам нужно добавить их в настройки CORS (подробнее см. в [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)), используя параметр `expose_headers`, описанный в [документации Starlette по CORS](https://starlette.dev/middleware/#corsmiddleware). diff --git a/docs/ru/docs/advanced/settings.md b/docs/ru/docs/advanced/settings.md index b85aa39..7bd1648 100644 --- a/docs/ru/docs/advanced/settings.md +++ b/docs/ru/docs/advanced/settings.md @@ -6,41 +6,45 @@ По этой причине обычно их передают через переменные окружения, которые считываются приложением. +**Переменная окружения** (также известная как **env var**) — это значение, которое существует вне Python-кода, в операционной системе, и может быть прочитано вашим приложением и другими программами. + +Вы можете создать переменную окружения для команды при её запуске. Ниже вы увидите команды, специфичные для разных платформ. + /// tip | Совет -Чтобы понять, что такое переменные окружения, вы можете прочитать [Переменные окружения](../environment-variables.md). +Прочитайте [руководство по переменным окружения](https://tiangolo.com/guides/environment-variables/) для подробного объяснения того, как работают переменные окружения. /// ## Типы и валидация { #types-and-validation } -Переменные окружения могут содержать только текстовые строки, так как они внешние по отношению к Python и должны быть совместимы с другими программами и остальной системой (и даже с разными операционными системами, такими как Linux, Windows, macOS). +Эти переменные окружения могут содержать только текстовые строки, так как они внешние по отношению к Python и должны быть совместимы с другими программами и остальной системой (и даже с разными операционными системами, такими как Linux, Windows и macOS). Это означает, что любое значение, прочитанное в Python из переменной окружения, будет `str`, а любые преобразования к другим типам или любая валидация должны выполняться в коде. ## Pydantic `Settings` { #pydantic-settings } -К счастью, Pydantic предоставляет отличную утилиту для работы с этими настройками, поступающими из переменных окружения, — [Pydantic: управление настройками](https://docs.pydantic.dev/latest/concepts/pydantic_settings/). +К счастью, Pydantic предоставляет отличную утилиту для работы с этими настройками, поступающими из переменных окружения, — [Pydantic: управление настройками](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/). ### Установка `pydantic-settings` { #install-pydantic-settings } -Сначала убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его, а затем установили пакет `pydantic-settings`: +Добавьте пакет `pydantic-settings` в ваш проект:
```console -$ pip install pydantic-settings +$ uv add pydantic-settings ---> 100% ```
-Он также включен при установке набора `all` с: +Он также включен при установке дополнительных зависимостей `all` с:
```console -$ pip install "fastapi[all]" +$ uv add "fastapi[all]" ---> 100% ``` @@ -76,19 +80,39 @@ $ pip install "fastapi[all]" Далее вы можете запустить сервер, передав конфигурации через переменные окружения. Например, можно задать `ADMIN_EMAIL` и `APP_NAME` так: +//// tab | Linux, macOS, Windows Bash +
```console -$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py +$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uv run fastapi run main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
+//// + +//// tab | Windows PowerShell + +
+ +```console +$ $Env:ADMIN_EMAIL = "deadpool@example.com" +$ $Env:APP_NAME = "ChimichangApp" +$ uv run fastapi run main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +//// + /// tip | Совет -Чтобы задать несколько переменных окружения для одной команды, просто разделяйте их пробелами и укажите все перед командой. +В Bash, чтобы задать несколько переменных окружения для одной команды, разделяйте их пробелами и укажите все перед командой. /// @@ -172,11 +196,11 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p /// -Pydantic поддерживает чтение таких файлов с помощью внешней библиотеки. Подробнее вы можете прочитать здесь: [Pydantic Settings: поддержка Dotenv (.env)](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support). +Pydantic поддерживает чтение таких файлов с помощью внешней библиотеки. Подробнее вы можете прочитать здесь: [Pydantic Settings: поддержка Dotenv (.env)](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#dotenv-env-support). /// tip | Совет -Чтобы это работало, вам нужно `pip install python-dotenv`. +Чтобы это работало, добавьте `python-dotenv` в ваш проект с помощью `uv add python-dotenv`. /// @@ -197,7 +221,7 @@ APP_NAME="ChimichangApp" /// tip | Совет -Атрибут `model_config` используется только для конфигурации Pydantic. Подробнее см. [Pydantic: Concepts: Configuration](https://docs.pydantic.dev/latest/concepts/config/). +Атрибут `model_config` используется только для конфигурации Pydantic. Подробнее см. [Pydantic: Concepts: Configuration](https://pydantic.dev/docs/validation/latest/concepts/config/). /// diff --git a/docs/ru/docs/advanced/sub-applications.md b/docs/ru/docs/advanced/sub-applications.md index 37257e0..53350e4 100644 --- a/docs/ru/docs/advanced/sub-applications.md +++ b/docs/ru/docs/advanced/sub-applications.md @@ -35,7 +35,7 @@
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/ru/docs/advanced/templates.md b/docs/ru/docs/advanced/templates.md index 5fc938e..4e1dcbd 100644 --- a/docs/ru/docs/advanced/templates.md +++ b/docs/ru/docs/advanced/templates.md @@ -8,12 +8,12 @@ ## Установка зависимостей { #install-dependencies } -Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его и установили `jinja2`: +Добавьте `jinja2` в ваш проект:
```console -$ pip install jinja2 +$ uv add jinja2 ---> 100% ``` @@ -22,10 +22,10 @@ $ pip install jinja2 ## Использование `Jinja2Templates` { #using-jinja2templates } -- Импортируйте `Jinja2Templates`. -- Создайте объект `templates`, который сможете переиспользовать позже. -- Объявите параметр `Request` в *операции пути*, которая будет возвращать шаблон. -- Используйте созданный `templates`, чтобы отрендерить и вернуть `TemplateResponse`; передайте имя шаблона, объект `request` и словарь «context» с парами ключ-значение для использования внутри шаблона Jinja2. +* Импортируйте `Jinja2Templates`. +* Создайте объект `templates`, который сможете переиспользовать позже. +* Объявите параметр `Request` в *операции пути*, которая будет возвращать шаблон. +* Используйте созданный `templates`, чтобы отрендерить и вернуть `TemplateResponse`; передайте имя шаблона, объект request и словарь «context» с парами ключ-значение для использования внутри шаблона Jinja2. {* ../../docs_src/templates/tutorial001_py310.py hl[4,11,15:18] *} @@ -123,4 +123,4 @@ Item ID: 42 ## Подробнее { #more-details } -Больше подробностей, включая то, как тестировать шаблоны, смотрите в [документации Starlette по шаблонам](https://www.starlette.dev/templates/). +Больше подробностей, включая то, как тестировать шаблоны, смотрите в [документации Starlette по шаблонам](https://starlette.dev/templates/). diff --git a/docs/ru/docs/advanced/testing-events.md b/docs/ru/docs/advanced/testing-events.md index 452342c..80b581d 100644 --- a/docs/ru/docs/advanced/testing-events.md +++ b/docs/ru/docs/advanced/testing-events.md @@ -5,7 +5,7 @@ {* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *} -Вы можете узнать больше подробностей в статье [Запуск lifespan в тестах на официальном сайте документации Starlette.](https://www.starlette.dev/lifespan/#running-lifespan-in-tests) +Вы можете узнать больше подробностей в статье [Запуск lifespan в тестах на официальном сайте документации Starlette.](https://starlette.dev/lifespan/#running-lifespan-in-tests) Для устаревших событий `startup` и `shutdown` вы можете использовать `TestClient` следующим образом: diff --git a/docs/ru/docs/advanced/testing-websockets.md b/docs/ru/docs/advanced/testing-websockets.md index 6ab395f..bb95d76 100644 --- a/docs/ru/docs/advanced/testing-websockets.md +++ b/docs/ru/docs/advanced/testing-websockets.md @@ -8,6 +8,6 @@ /// note | Примечание -Подробности смотрите в документации Starlette по [тестированию WebSocket](https://www.starlette.dev/testclient/#testing-websocket-sessions). +Подробности смотрите в документации Starlette по [тестированию WebSocket](https://starlette.dev/testclient/#testing-websocket-sessions). /// diff --git a/docs/ru/docs/advanced/using-request-directly.md b/docs/ru/docs/advanced/using-request-directly.md index 99074bf..e043b8b 100644 --- a/docs/ru/docs/advanced/using-request-directly.md +++ b/docs/ru/docs/advanced/using-request-directly.md @@ -4,9 +4,9 @@ Извлекая данные из: -* пути (как параметров), -* HTTP-заголовков, -* Cookie, +* пути как параметров. +* HTTP-заголовков. +* Cookie. * и т.д. Тем самым **FastAPI** валидирует эти данные, преобразует их и автоматически генерирует документацию для вашего API. @@ -15,7 +15,7 @@ ## Подробности об объекте `Request` { #details-about-the-request-object } -Так как под капотом **FastAPI** — это **Starlette** с дополнительным слоем инструментов, вы можете при необходимости напрямую использовать объект [`Request`](https://www.starlette.dev/requests/) из Starlette. +Так как под капотом **FastAPI** — это **Starlette** с дополнительным слоем инструментов, вы можете при необходимости напрямую использовать объект [`Request`](https://starlette.dev/requests/) из Starlette. Это также означает, что если вы получаете данные напрямую из объекта `Request` (например, читаете тело запроса), то они не будут валидироваться, конвертироваться или документироваться (с OpenAPI, для автоматического пользовательского интерфейса API) средствами FastAPI. @@ -45,7 +45,7 @@ ## Документация по `Request` { #request-documentation } -Подробнее об [объекте `Request` на официальном сайте документации Starlette](https://www.starlette.dev/requests/). +Подробнее об [объекте `Request` на официальном сайте документации Starlette](https://starlette.dev/requests/). /// note | Технические детали diff --git a/docs/ru/docs/advanced/websockets.md b/docs/ru/docs/advanced/websockets.md index 0f69f57..baa34ee 100644 --- a/docs/ru/docs/advanced/websockets.md +++ b/docs/ru/docs/advanced/websockets.md @@ -4,12 +4,12 @@ ## Установка `websockets` { #install-websockets } -Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его и установили `websockets` (библиотека Python, упрощающая работу с протоколом "WebSocket"): +Добавьте `websockets` (библиотека Python, упрощающая работу с протоколом "WebSocket") в ваш проект:
```console -$ pip install websockets +$ uv add websockets ---> 100% ``` @@ -36,13 +36,13 @@ $ pip install websockets В продакшн у вас был бы один из вариантов выше. -Для примера нам нужен наиболее простой способ, который позволит сосредоточиться на серверной части веб‑сокетов и получить рабочий код: +Но это самый простой способ сосредоточиться на серверной части веб‑сокетов и получить рабочий пример: {* ../../docs_src/websockets_/tutorial001_py310.py hl[2,6:38,41:43] *} ## Создание `websocket` { #create-a-websocket } -Создайте `websocket` в своем **FastAPI** приложении: +В вашем **FastAPI** приложении создайте `websocket`: {* ../../docs_src/websockets_/tutorial001_py310.py hl[1,46:47] *} @@ -50,13 +50,13 @@ $ pip install websockets Вы также можете использовать `from starlette.websockets import WebSocket`. -**FastAPI** напрямую предоставляет тот же самый `WebSocket` просто для удобства. На самом деле это `WebSocket` из Starlette. +**FastAPI** напрямую предоставляет тот же самый `WebSocket` просто для удобства вас, разработчика. Но на самом деле это `WebSocket` из Starlette. /// ## Ожидание и отправка сообщений { #await-for-messages-and-send-messages } -Через эндпоинт веб-сокета вы можете получать и отправлять сообщения. +В вашем WebSocket-маршруте вы можете `await` сообщения и отправлять сообщения. {* ../../docs_src/websockets_/tutorial001_py310.py hl[48:52] *} @@ -69,7 +69,7 @@ $ pip install websockets
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -90,15 +90,15 @@ $ fastapi dev -Вы можете отправлять и получать множество сообщений: +Вы можете отправлять (и получать) множество сообщений: -И все они будут использовать одно и то же веб-сокет соединение. +И все они будут использовать одно и то же WebSocket-соединение. ## Использование `Depends` и не только { #using-depends-and-others } -Вы можете импортировать из `fastapi` и использовать в эндпоинте вебсокета: +В WebSocket-эндпоинтах вы можете импортировать из `fastapi` и использовать: * `Depends` * `Security` @@ -113,7 +113,7 @@ $ fastapi dev /// note | Примечание -В веб-сокете вызывать `HTTPException` не имеет смысла. Вместо этого нужно использовать `WebSocketException`. +Поскольку это WebSocket, вызывать `HTTPException` на самом деле не имеет смысла, вместо этого мы вызываем `WebSocketException`. Вы можете использовать код закрытия из [допустимых кодов, определённых в спецификации](https://tools.ietf.org/html/rfc6455#section-7.4.1). @@ -126,7 +126,7 @@ $ fastapi dev
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -142,17 +142,17 @@ $ fastapi dev /// tip | Подсказка -Обратите внимание, что query-параметр `token` будет обработан в зависимости. +Обратите внимание, что query `token` будет обработан в зависимости. /// -Теперь вы можете подключиться к веб-сокету и начинать отправку и получение сообщений: +После этого вы можете подключиться к веб-сокету, а затем отправлять и получать сообщения: ## Обработка отключений и работа с несколькими клиентами { #handling-disconnections-and-multiple-clients } -Если веб-сокет соединение закрыто, то `await websocket.receive_text()` вызовет исключение `WebSocketDisconnect`, которое можно поймать и обработать как в этом примере. +Когда WebSocket-соединение закрыто, `await websocket.receive_text()` вызовет исключение `WebSocketDisconnect`, которое можно поймать и обработать как в этом примере. {* ../../docs_src/websockets_/tutorial003_py310.py hl[79:81] *} @@ -170,9 +170,9 @@ Client #1596980209979 left the chat /// tip | Подсказка -Приложение выше - это всего лишь простой минимальный пример, демонстрирующий обработку и передачу сообщений нескольким веб-сокет соединениям. +Приложение выше - это минимальный и простой пример, демонстрирующий обработку и рассылку сообщений нескольким WebSocket-соединениям. -Но имейте в виду, что это будет работать только в одном процессе и только пока он активен, так как всё обрабатывается в простом списке в оперативной памяти. +Но имейте в виду, что, так как всё обрабатывается в памяти, в простом списке, это будет работать только пока процесс запущен и только с одним процессом. Если нужно что-то легко интегрируемое с FastAPI, но более надежное и с поддержкой Redis, PostgreSQL или другого, то можно воспользоваться [encode/broadcaster](https://github.com/encode/broadcaster). @@ -180,7 +180,7 @@ Client #1596980209979 left the chat ## Дополнительная информация { #more-info } -Для более глубокого изучения темы воспользуйтесь документацией Starlette: +Для более глубокого изучения возможностей воспользуйтесь документацией Starlette: -* [Класс `WebSocket`](https://www.starlette.dev/websockets/). -* [Обработка WebSocket на основе классов](https://www.starlette.dev/endpoints/#websocketendpoint). +* [Класс `WebSocket`](https://starlette.dev/websockets/). +* [Обработка WebSocket на основе классов](https://starlette.dev/endpoints/#websocketendpoint). diff --git a/docs/ru/docs/advanced/wsgi.md b/docs/ru/docs/advanced/wsgi.md index 99ba509..96d7521 100644 --- a/docs/ru/docs/advanced/wsgi.md +++ b/docs/ru/docs/advanced/wsgi.md @@ -8,7 +8,7 @@ /// note | Примечание -Для этого требуется установить `a2wsgi`, например с помощью `pip install a2wsgi`. +Для этого требуется добавить `a2wsgi` в ваш проект, например с помощью `uv add a2wsgi`. /// diff --git a/docs/ru/docs/alternatives.md b/docs/ru/docs/alternatives.md index e1b8e27..765f04b 100644 --- a/docs/ru/docs/alternatives.md +++ b/docs/ru/docs/alternatives.md @@ -70,7 +70,7 @@ Flask — это «микрофреймворк», он не включает и Обычно Requests используют даже внутри приложения FastAPI. -И всё же **FastAPI** во многом вдохновлялся Requests. +И всё же FastAPI во многом вдохновлялся Requests. **Requests** — это библиотека для взаимодействия с API (как клиент), а **FastAPI** — библиотека для создания API (как сервер). @@ -120,12 +120,12 @@ def read_url(): /// tip | Вдохновило **FastAPI** на -Использовать открытый стандарт для спецификаций API вместо самодельной схемы. +Начать использовать открытый стандарт для спецификаций API вместо самодельной схемы. И интегрировать основанные на стандартах инструменты пользовательского интерфейса: * [Swagger UI](https://github.com/swagger-api/swagger-ui) -* [ReDoc](https://github.com/Rebilly/ReDoc) +* [ReDoc](https://github.com/Redocly/redoc) Эти два инструмента выбраны за популярность и стабильность, но даже при беглом поиске можно найти десятки альтернативных интерфейсов для OpenAPI (которые можно использовать с **FastAPI**). @@ -237,7 +237,7 @@ Flask-apispec был создан теми же разработчиками, ч /// -### [NestJS](https://nestjs.com/) (и [Angular](https://angular.io/)) { #nestjs-and-angular } +### [NestJS](https://nestjs.com/) (и [Angular](https://angular.dev/)) { #nestjs-and-angular } Это даже не Python. NestJS — это JavaScript/TypeScript-фреймворк на NodeJS, вдохновлённый Angular. @@ -337,7 +337,7 @@ Hug был одним из первых фреймворков, реализов /// note | Заметка -Hug был создан Тимоти Кросли, тем же автором [`isort`](https://github.com/timothycrosley/isort), отличного инструмента для автоматической сортировки импортов в файлах Python. +Hug был создан Тимоти Кросли, тем же автором [`isort`](https://github.com/PyCQA/isort), отличного инструмента для автоматической сортировки импортов в файлах Python. /// @@ -401,7 +401,7 @@ APIStar был создан Томом Кристи. Тем самым чело ## Что используется в **FastAPI** { #used-by-fastapi } -### [Pydantic](https://docs.pydantic.dev/) { #pydantic } +### [Pydantic](https://pydantic.dev/docs/) { #pydantic } Pydantic — это библиотека для определения валидации данных, сериализации и документации (с использованием JSON Schema) на основе аннотаций типов Python. @@ -417,7 +417,7 @@ Pydantic — это библиотека для определения вали /// -### [Starlette](https://www.starlette.dev/) { #starlette } +### [Starlette](https://starlette.dev/) { #starlette } Starlette — это лёгкий ASGI фреймворк/набор инструментов, идеально подходящий для создания высокопроизводительных asyncio‑сервисов. @@ -462,7 +462,7 @@ ASGI — это новый «стандарт», разрабатываемый /// -### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn } +### [Uvicorn](https://uvicorn.dev) { #uvicorn } Uvicorn — молниеносный ASGI-сервер, построенный на uvloop и httptools. diff --git a/docs/ru/docs/deployment/docker.md b/docs/ru/docs/deployment/docker.md index 1a7586f..01b615a 100644 --- a/docs/ru/docs/deployment/docker.md +++ b/docs/ru/docs/deployment/docker.md @@ -105,36 +105,32 @@ Docker — один из основных инструментов для соз ### Зависимости пакетов { #package-requirements } -Обычно **зависимости** вашего приложения описаны в каком-то файле. +Когда вы управляете проектом с помощью `uv`, его прямые зависимости объявляются в `pyproject.toml`, а точные разрешённые версии хранятся в `uv.lock`. -Конкретный формат зависит в основном от инструмента, которым вы **устанавливаете** эти зависимости. - -Чаще всего используется файл `requirements.txt` с именами пакетов и их версиями по одному на строку. - -Разумеется, вы будете придерживаться тех же идей, что описаны здесь: [О версиях FastAPI](versions.md), чтобы задать диапазоны версий. - -Например, ваш `requirements.txt` может выглядеть так: - -``` -fastapi[standard]>=0.113.0,<0.114.0 -pydantic>=2.7.0,<3.0.0 -``` - -И обычно вы установите эти зависимости командой `pip`, например: +Вы можете добавить пакеты, необходимые вашему приложению, так:
```console -$ pip install -r requirements.txt +$ uv add "fastapi[standard]" pydantic ---> 100% -Successfully installed fastapi pydantic ```
/// note | Заметка -Существуют и другие форматы и инструменты для описания и установки зависимостей. +В Dockerfile ниже внутри контейнера используется `pip`. Вы можете экспортировать зафиксированные зависимости из вашего uv-проекта в ожидаемый им формат `requirements.txt`: + +
+ +```console +$ uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt +``` + +
+ +Сгенерированный `requirements.txt` — это экспорт для сборки контейнера. Продолжайте управлять зависимостями с помощью `uv add` и пересоздавайте его, когда меняется `uv.lock`. /// @@ -372,7 +368,7 @@ $ docker run -d --name mycontainer -p 80:80 myimage Также можно открыть [http://192.168.99.100/redoc](http://192.168.99.100/redoc) или [http://127.0.0.1/redoc](http://127.0.0.1/redoc) (или аналогичный URL вашего Docker-хоста). -Вы увидите альтернативную автоматическую документацию (на базе [ReDoc](https://github.com/Rebilly/ReDoc)): +Вы увидите альтернативную автоматическую документацию (на базе [ReDoc](https://github.com/Redocly/redoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) diff --git a/docs/ru/docs/deployment/fastapicloud.md b/docs/ru/docs/deployment/fastapicloud.md index fa31605..ad8fb4b 100644 --- a/docs/ru/docs/deployment/fastapicloud.md +++ b/docs/ru/docs/deployment/fastapicloud.md @@ -5,7 +5,7 @@
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... diff --git a/docs/ru/docs/deployment/manually.md b/docs/ru/docs/deployment/manually.md index e6408c9..ff8d85b 100644 --- a/docs/ru/docs/deployment/manually.md +++ b/docs/ru/docs/deployment/manually.md @@ -52,7 +52,7 @@ FastAPI использует стандарт для построения Python Есть несколько альтернатив, например: -* [Uvicorn](https://www.uvicorn.dev/): высокопроизводительный ASGI‑сервер. +* [Uvicorn](https://uvicorn.dev): высокопроизводительный ASGI‑сервер. * [Hypercorn](https://hypercorn.readthedocs.io/): ASGI‑сервер, среди прочего совместимый с HTTP/2 и Trio. * [Daphne](https://github.com/django/daphne): ASGI‑сервер, созданный для Django Channels. * [Granian](https://github.com/emmett-framework/granian): HTTP‑сервер на Rust для Python‑приложений. @@ -73,21 +73,21 @@ FastAPI использует стандарт для построения Python Но вы также можете установить ASGI‑сервер вручную. -Создайте [виртуальное окружение](../virtual-environments.md), активируйте его и затем установите серверное приложение. +Добавьте серверное приложение в ваш проект. Например, чтобы установить Uvicorn:
```console -$ pip install "uvicorn[standard]" +$ uv add "uvicorn[standard]" ---> 100% ```
-Аналогично устанавливаются и другие ASGI‑серверы. +Похожий процесс применим к любой другой программе ASGI‑сервера. /// tip | Совет @@ -95,7 +95,7 @@ $ pip install "uvicorn[standard]" В их числе `uvloop` — высокопроизводительная замена `asyncio`, дающая серьёзный прирост производительности при параллельной работе. -Если вы устанавливаете FastAPI, например так: `pip install "fastapi[standard]"`, вы уже получаете и `uvicorn[standard]`. +Когда вы добавляете FastAPI примерно так: `uv add "fastapi[standard]"`, вы уже получаете и `uvicorn[standard]`. /// @@ -106,7 +106,7 @@ $ pip install "uvicorn[standard]"
```console -$ uvicorn main:app --host 0.0.0.0 --port 80 +$ uv run uvicorn main:app --host 0.0.0.0 --port 80 INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) ``` diff --git a/docs/ru/docs/deployment/server-workers.md b/docs/ru/docs/deployment/server-workers.md index 8d4bd33..7584edd 100644 --- a/docs/ru/docs/deployment/server-workers.md +++ b/docs/ru/docs/deployment/server-workers.md @@ -86,7 +86,7 @@ $ fastapi run --workers 4 ```console -$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 +$ uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit) INFO: Started parent process [27365] INFO: Started server process [27368] diff --git a/docs/ru/docs/environment-variables.md b/docs/ru/docs/environment-variables.md index 3cd0bc7..fe681ed 100644 --- a/docs/ru/docs/environment-variables.md +++ b/docs/ru/docs/environment-variables.md @@ -1,298 +1,11 @@ # Переменные окружения { #environment-variables } -/// tip | Совет +**Переменная окружения** (также известная как **env var**) — это значение, которое живет вне вашего кода Python, в операционной системе, и может быть прочитано вашим приложением и другими программами. -Если вы уже знаете, что такое «переменные окружения» и как их использовать, можете пропустить это. +Приложения FastAPI часто используют переменные окружения для конфигурации, например URL-адресов баз данных, учетных данных электронной почты и секретных ключей. -/// +Вы узнаете, как использовать их для конфигурации приложения, в разделе [Настройки и переменные окружения](advanced/settings.md). -Переменная окружения (также известная как «**env var**») - это переменная, которая живет **вне** кода Python, в **операционной системе**, и может быть прочитана вашим кодом Python (или другими программами). +## Подробнее { #learn-more } -Переменные окружения могут быть полезны для работы с **настройками** приложений, как часть **установки** Python и т.д. - -## Создание и использование переменных окружения { #create-and-use-env-vars } - -Можно **создавать** и использовать переменные окружения в **оболочке (терминале)**, не прибегая к помощи Python: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// Вы можете создать переменную окружения MY_NAME с помощью -$ export MY_NAME="Wade Wilson" - -// Затем её можно использовать в других программах, например -$ echo "Hello $MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// Создайте переменную окружения MY_NAME -$ $Env:MY_NAME = "Wade Wilson" - -// Используйте её с другими программами, например -$ echo "Hello $Env:MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -## Чтение переменных окружения в Python { #read-env-vars-in-python } - -Также существует возможность создания переменных окружения **вне** Python, в терминале (или любым другим способом), а затем **чтения их в Python**. - -Например, у вас есть файл `main.py`: - -```Python hl_lines="3" -import os - -name = os.getenv("MY_NAME", "World") -print(f"Hello {name} from Python") -``` - -/// tip | Совет - -Второй аргумент [`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) - это возвращаемое по умолчанию значение. - -Если значение не указано, то по умолчанию оно равно `None`. В данном случае мы указываем `"World"` в качестве значения по умолчанию. - -/// - -Затем можно запустить эту программу на Python: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// Здесь мы еще не устанавливаем переменную окружения -$ python main.py - -// Поскольку мы не задали переменную окружения, мы получим значение по умолчанию - -Hello World from Python - -// Но если мы сначала создадим переменную окружения -$ export MY_NAME="Wade Wilson" - -// А затем снова запустим программу -$ python main.py - -// Теперь она прочитает переменную окружения - -Hello Wade Wilson from Python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// Здесь мы еще не устанавливаем переменную окружения -$ python main.py - -// Поскольку мы не задали переменную окружения, мы получим значение по умолчанию - -Hello World from Python - -// Но если мы сначала создадим переменную окружения -$ $Env:MY_NAME = "Wade Wilson" - -// А затем снова запустим программу -$ python main.py - -// Теперь она может прочитать переменную окружения - -Hello Wade Wilson from Python -``` - -
- -//// - -Поскольку переменные окружения могут быть установлены вне кода, но могут быть прочитаны кодом, и их не нужно хранить (фиксировать в `git`) вместе с остальными файлами, их принято использовать для конфигураций или **настроек**. - -Вы также можете создать переменную окружения только для **конкретного вызова программы**, которая будет доступна только для этой программы и только на время ее выполнения. - -Для этого создайте её непосредственно перед самой программой, в той же строке: - -
- -```console -// Создайте переменную окружения MY_NAME в строке для этого вызова программы -$ MY_NAME="Wade Wilson" python main.py - -// Теперь она может прочитать переменную окружения - -Hello Wade Wilson from Python - -// После этого переменная окружения больше не существует -$ python main.py - -Hello World from Python -``` - -
- -/// tip | Совет - -Подробнее об этом можно прочитать на сайте [The Twelve-Factor App: Config](https://12factor.net/config). - -/// - -## Типы и валидация { #types-and-validation } - -Эти переменные окружения могут работать только с **текстовыми строками**, поскольку они являются внешними по отношению к Python и должны быть совместимы с другими программами и остальной системой (и даже с различными операционными системами, такими как Linux, Windows, macOS). - -Это означает, что **любое значение**, считанное в Python из переменной окружения, **будет `str`**, и любое преобразование к другому типу или любая валидация должны быть выполнены в коде. - -Подробнее об использовании переменных окружения для работы с **настройками приложения** вы узнаете в [Расширенном руководстве пользователя - Настройки и переменные окружения](./advanced/settings.md). - -## Переменная окружения `PATH` { #path-environment-variable } - -Существует **специальная** переменная окружения **`PATH`**, которая используется операционными системами (Linux, macOS, Windows) для поиска программ для запуска. - -Значение переменной `PATH` - это длинная строка, состоящая из каталогов, разделенных двоеточием `:` в Linux и macOS, и точкой с запятой `;` в Windows. - -Например, переменная окружения `PATH` может выглядеть следующим образом: - -//// tab | Linux, macOS - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -Это означает, что система должна искать программы в каталогах: - -* `/usr/local/bin` -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32 -``` - -Это означает, что система должна искать программы в каталогах: - -* `C:\Program Files\Python312\Scripts` -* `C:\Program Files\Python312` -* `C:\Windows\System32` - -//// - -Когда вы вводите **команду** в терминале, операционная система **ищет** программу в **каждой из тех директорий**, которые перечислены в переменной окружения `PATH`. - -Например, когда вы вводите `python` в терминале, операционная система ищет программу под названием `python` в **первой директории** в этом списке. - -Если она ее находит, то **использует ее**. В противном случае она продолжает искать в **других каталогах**. - -### Установка Python и обновление `PATH` { #installing-python-and-updating-the-path } - -При установке Python вас могут спросить, нужно ли обновить переменную окружения `PATH`. - -//// tab | Linux, macOS - -Допустим, вы устанавливаете Python, и он оказывается в каталоге `/opt/custompython/bin`. - -Если вы скажете «да», чтобы обновить переменную окружения `PATH`, то программа установки добавит `/opt/custompython/bin` в переменную окружения `PATH`. - -Это может выглядеть следующим образом: - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin -``` - -Таким образом, когда вы набираете `python` в терминале, система найдет программу Python в `/opt/custompython/bin` (последний каталог) и использует ее. - -//// - -//// tab | Windows - -Допустим, вы устанавливаете Python, и он оказывается в каталоге `C:\opt\custompython\bin`. - -Если вы согласитесь обновить переменную окружения `PATH`, то программа установки добавит `C:\opt\custompython\bin` в переменную окружения `PATH`. - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin -``` - -Таким образом, когда вы набираете `python` в терминале, система найдет программу Python в `C:\opt\custompython\bin` (последний каталог) и использует ее. - -//// - -Итак, если вы напечатаете: - -
- -```console -$ python -``` - -
- -//// tab | Linux, macOS - -Система **найдет** программу `python` в `/opt/custompython/bin` и запустит ее. - -Это примерно эквивалентно набору текста: - -
- -```console -$ /opt/custompython/bin/python -``` - -
- -//// - -//// tab | Windows - -Система **найдет** программу `python` в каталоге `C:\opt\custompython\bin\python` и запустит ее. - -Это примерно эквивалентно набору текста: - -
- -```console -$ C:\opt\custompython\bin\python -``` - -
- -//// - -Эта информация будет полезна при изучении [виртуальных окружений](virtual-environments.md). - -## Вывод { #conclusion } - -Благодаря этому вы должны иметь базовое представление о том, что такое **переменные окружения** и как использовать их в Python. - -Подробнее о них вы также можете прочитать в [статье о переменных окружения на Википедии](https://en.wikipedia.org/wiki/Environment_variable). - -Во многих случаях не всегда очевидно, как переменные окружения могут быть полезны и применимы. Но они постоянно появляются в различных сценариях разработки, поэтому знать о них полезно. - -Например, эта информация понадобится вам в следующем разделе, посвященном [виртуальным окружениям](virtual-environments.md). +Прочитайте [руководство по переменным окружения](https://tiangolo.com/guides/environment-variables/) с подробным кроссплатформенным объяснением, включая то, как создавать и читать переменные окружения и как работает переменная окружения `PATH`. diff --git a/docs/ru/docs/fastapi-cli.md b/docs/ru/docs/fastapi-cli.md index 07d2720..f2bda2d 100644 --- a/docs/ru/docs/fastapi-cli.md +++ b/docs/ru/docs/fastapi-cli.md @@ -2,7 +2,7 @@ **FastAPI CLI** - это программа командной строки, которую вы можете использовать, чтобы предоставлять доступ к вашему приложению FastAPI, управлять проектом FastAPI и т.д. -При установке FastAPI (например, с помощью `pip install "fastapi[standard]"`) вместе с ним устанавливается программа командной строки, которую можно запускать в терминале. +Когда вы добавляете FastAPI в свой проект (например, с помощью `uv add "fastapi[standard]"`), вместе с ним устанавливается программа командной строки, которую можно запускать в терминале. Чтобы запустить ваше приложение FastAPI в режиме разработки, используйте команду `fastapi dev`: @@ -52,7 +52,7 @@ $ fastapi dev /// -Внутри **FastAPI CLI** используется [Uvicorn](https://www.uvicorn.dev), высокопроизводительный, готовый к работе в продакшн ASGI-сервер. 😎 +Внутри **FastAPI CLI** используется [Uvicorn](https://uvicorn.dev), высокопроизводительный, готовый к работе в продакшн ASGI-сервер. 😎 Инструмент командной строки `fastapi` попытается автоматически обнаружить приложение FastAPI для запуска, предполагая, что это объект с именем `app` в файле `main.py` (или в некоторых других вариантах). @@ -100,13 +100,13 @@ from backend.main import app Вы также можете передать путь к файлу команде `fastapi dev`, и она постарается определить объект приложения FastAPI: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` Или вы можете передать опцию `--entrypoint` команде `fastapi dev`: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` Но тогда вам придется каждый раз не забывать передавать правильный путь\entrypoint при вызове команды `fastapi`. @@ -119,11 +119,15 @@ $ fastapi dev --entrypoint main:app По умолчанию включена авто-перезагрузка (**auto-reload**), благодаря этому при изменении кода происходит перезагрузка сервера приложения. Эта установка требует значительных ресурсов и делает систему менее стабильной. Используйте её только при разработке. Приложение слушает входящие подключения на IP `127.0.0.1`. Это IP адрес вашей машины, предназначенный для внутренних коммуникаций (`localhost`). +Перед импортом вашего приложения `fastapi dev` устанавливает переменную окружения `FASTAPI_ENV` в значение `development`. Если `FASTAPI_ENV` уже задана, её существующее значение сохраняется. Это позволяет коду запуска приложения выбирать поведение, удобное для разработки, при этом давая вам возможность указать окружение, специфичное для приложения, например `staging`. + +Принятые значения `FASTAPI_ENV` — `development` и `production`. Сейчас `fastapi run` оставляет `FASTAPI_ENV` без изменений, поэтому задайте её явно, если вашему приложению нужно определять режим продакшн. + ## `fastapi run` { #fastapi-run } Вызов `fastapi run` по умолчанию запускает FastAPI в режиме продакшн. -По умолчанию авто-перезагрузка (**auto-reload**) отключена. Приложение слушает входящие подключения на IP `0.0.0.0`, т.е. на всех доступных адресах компьютера. Таким образом, приложение будет находиться в публичном доступе для любого, кто может подсоединиться к вашей машине. Продуктовые приложения запускаются именно так, например, с помощью контейнеров. +По умолчанию авто-перезагрузка (**auto-reload**) отключена. Приложение слушает входящие подключения на IP `0.0.0.0`, т.е. на всех доступных адресах компьютера. Таким образом, приложение будет находиться в публичном доступе для любого, кто может подсоединиться к вашей машине. Именно так обычно запускают приложение в продакшн, например, в контейнере. В большинстве случаев вы будете (и должны) использовать прокси-сервер ("termination proxy"), который будет поддерживать HTTPS поверх вашего приложения. Всё будет зависеть от того, как вы развертываете приложение: за вас это либо сделает ваш провайдер, либо вам придется сделать настройки самостоятельно. diff --git a/docs/ru/docs/features.md b/docs/ru/docs/features.md index 25bbe85..c63f5c4 100644 --- a/docs/ru/docs/features.md +++ b/docs/ru/docs/features.md @@ -19,7 +19,7 @@ ![Взаимодействие со Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* Альтернативная документация API в [**ReDoc**](https://github.com/Rebilly/ReDoc). +* Альтернативная документация API в [**ReDoc**](https://github.com/Redocly/redoc). ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) @@ -159,7 +159,7 @@ FastAPI включает в себя чрезвычайно простую в и ## Возможности Starlette { #starlette-features } -**FastAPI** основан на [**Starlette**](https://www.starlette.dev/) и полностью совместим с ним. Так что любой дополнительный код Starlette, который у вас есть, также будет работать. +**FastAPI** основан на [**Starlette**](https://starlette.dev/) и полностью совместим с ним. Так что любой дополнительный код Starlette, который у вас есть, также будет работать. На самом деле, `FastAPI` — это подкласс `Starlette`. Таким образом, если вы уже знаете или используете Starlette, большая часть функционала будет работать так же. @@ -177,7 +177,7 @@ FastAPI включает в себя чрезвычайно простую в и ## Возможности Pydantic { #pydantic-features } -**FastAPI** полностью совместим с (и основан на) [**Pydantic**](https://docs.pydantic.dev/). Поэтому любой дополнительный код Pydantic, который у вас есть, также будет работать. +**FastAPI** полностью совместим с (и основан на) [**Pydantic**](https://pydantic.dev/docs/). Поэтому любой дополнительный код Pydantic, который у вас есть, также будет работать. Включая внешние библиотеки, также основанные на Pydantic, такие как ORM’ы, ODM’ы для баз данных. diff --git a/docs/ru/docs/help-fastapi.md b/docs/ru/docs/help-fastapi.md index ff47b93..3922006 100644 --- a/docs/ru/docs/help-fastapi.md +++ b/docs/ru/docs/help-fastapi.md @@ -45,20 +45,6 @@ * [@tiangolo.com в **Bluesky**](https://bsky.app/profile/tiangolo.com) * [@tiangolo в **LinkedIn**](https://www.linkedin.com/in/tiangolo/). -## Помогать другим с вопросами на GitHub { #help-others-with-questions-in-github } - -Вы можете попробовать помогать другим с их вопросами в [GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered). - -Во многих случаях вы уже можете знать ответы на эти вопросы. 🤓 - -Если вы помогаете многим людям с их вопросами, вы станете официальным [Экспертом FastAPI](fastapi-people.md#fastapi-experts). 🎉 - -Только помните, самое важное — старайтесь быть добрыми. 🤗 - -### Как помогать { #how-to-help } - -Следуйте [руководству по тому, как помогать](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github) здесь. - ## Задать вопросы { #ask-questions } Вы можете [создать новый вопрос](https://github.com/fastapi/fastapi/discussions/new?category=questions) в репозитории GitHub, например, чтобы: @@ -68,7 +54,7 @@ ## Присоединиться к чату { #join-the-chat } -Присоединяйтесь к 👥 [чат-серверу в Discord](https://discord.gg/VQjSZaeJmf) 👥 и общайтесь с другими участниками сообщества FastAPI. +Присоединяйтесь к 👥 [чат-серверу в Discord](https://discord.com/invite/VQjSZaeJmf) 👥 и общайтесь с другими участниками сообщества FastAPI. /// tip | Совет @@ -85,3 +71,9 @@ На GitHub шаблон подскажет, как сформулировать правильный вопрос, чтобы вам было проще получить хороший ответ или даже решить проблему самостоятельно ещё до того, как спросить. Кроме того, переписки в чатах хуже ищутся, чем на GitHub, и быстро теряются. + +## Попробовать FastAPI Cloud { #try-fastapi-cloud } + +Основное финансирование FastAPI и друзей поступает от [**FastAPI Cloud**](https://fastapicloud.com), платформы для простого и быстрого развертывания приложений FastAPI с помощью одной команды, `fastapi deploy`. + +FastAPI Cloud создаётся той же командой, которая стоит за FastAPI. Вы можете попробовать его и рассмотреть для своих проектов. diff --git a/docs/ru/docs/history-design-future.md b/docs/ru/docs/history-design-future.md index 0096946..a4d0464 100644 --- a/docs/ru/docs/history-design-future.md +++ b/docs/ru/docs/history-design-future.md @@ -1,79 +1,79 @@ # История, проектирование и будущее { #history-design-and-future } -Однажды, [один из пользователей **FastAPI** задал вопрос](https://github.com/fastapi/fastapi/issues/3#issuecomment-454956920): +Некоторое время назад [один пользователь **FastAPI** спросил](https://github.com/fastapi/fastapi/issues/3#issuecomment-454956920): -> Какова история этого проекта? Создаётся впечатление, что он явился из ниоткуда и завоевал мир за несколько недель [...] +> Какова история этого проекта? Кажется, что он из ниоткуда стал потрясающим за несколько недель [...] -Что ж, вот небольшая часть истории проекта. +Вот небольшая часть этой истории. ## Альтернативы { #alternatives } -В течение нескольких лет я, возглавляя различные команды разработчиков, создавал довольно сложные API для машинного обучения, распределённых систем, асинхронных задач, баз данных NoSQL и т.д. +Я несколько лет создавал API со сложными требованиями (Машинное обучение, распределённые системы, асинхронные задачи, базы данных NoSQL и т.д.), возглавляя несколько команд разработчиков. -В рамках работы над этими проектами я исследовал, проверял и использовал многие фреймворки. +В рамках этой работы мне нужно было исследовать, тестировать и использовать многие альтернативы. -Во многом история **FastAPI** - история его предшественников. +Во многом история **FastAPI** — это история его предшественников. Как написано в разделе [Альтернативы](alternatives.md):
-**FastAPI** не существовал бы, если б не было более ранних работ других людей. +**FastAPI** не существовал бы, если бы не предыдущая работа других людей. -Они создали большое количество инструментов, которые и вдохновили меня на создание **FastAPI**. +Ещё до него было создано много инструментов, которые помогли вдохновить его создание. -Я всячески избегал создания нового фреймворка в течение нескольких лет. Сначала я пытался собрать все нужные возможности, которые ныне есть в **FastAPI**, используя множество различных фреймворков, плагинов и инструментов. +Я всячески избегал создания нового фреймворка в течение нескольких лет. Сначала я пытался реализовать все возможности, покрываемые **FastAPI**, используя множество различных фреймворков, плагинов и инструментов. -Но в какой-то момент не осталось другого выбора, кроме как создать что-то, что предоставляло бы все эти возможности сразу. Взять самые лучшие идеи из предыдущих инструментов и, используя введённые в Python аннотации типов (которых не было до версии 3.6), объединить их. +Но в какой-то момент не осталось другого выбора, кроме как создать что-то, что предоставляло бы все эти возможности сразу, взяв лучшие идеи из предыдущих инструментов и объединив их наилучшим возможным образом, используя возможности языка, которые раньше были недоступны (аннотации типов Python 3.6+).
## Исследования { #investigation } -Используя все существовавшие ранее альтернативы, я получил возможность у каждой из них чему-то научиться, позаимствовать идеи и объединить их наилучшим образом для себя и для команд разработчиков, с которыми я работал. +Используя все предыдущие альтернативы, я получил возможность учиться у каждой из них, брать идеи и объединять их наилучшим образом, который смог найти для себя и команд разработчиков, с которыми я работал. -Например, стало ясно, что необходимо брать за основу стандартные аннотации типов Python. +Например, было ясно, что в идеале всё должно основываться на стандартных аннотациях типов Python. -Также наилучшим подходом является использование уже существующих стандартов. +Также наилучшим подходом было использовать уже существующие стандарты. -Итак, прежде чем приступить к написанию **FastAPI**, я потратил несколько месяцев на изучение OpenAPI, JSON Schema, OAuth2, и т.п. для понимания их взаимосвязей, совпадений и различий. +Итак, ещё до того как начать писать код **FastAPI**, я потратил несколько месяцев на изучение спецификаций OpenAPI, JSON Schema, OAuth2 и т.п., чтобы понять их взаимосвязи, пересечения и различия. ## Проектирование { #design } -Затем я потратил некоторое время на придумывание "API" разработчика, который я хотел иметь как пользователь (как разработчик, использующий FastAPI). +Затем я потратил некоторое время на проектирование "API" разработчика, который я хотел иметь как пользователь (как разработчик, использующий FastAPI). -Я проверил несколько идей на самых популярных редакторах кода: PyCharm, VS Code, редакторы на базе Jedi. +Я проверил несколько идей в самых популярных редакторах кода Python: PyCharm, VS Code, редакторах на базе Jedi. Согласно последнему [опросу Python-разработчиков](https://www.jetbrains.com/research/python-developers-survey-2018/#development-tools), который охватывает около 80% пользователей. -Это означает, что **FastAPI** был специально проверен на редакторах, используемых 80% Python-разработчиками. И поскольку большинство других редакторов, как правило, работают аналогичным образом, все его преимущества должны работать практически для всех редакторов. +Это означает, что **FastAPI** был специально протестирован с редакторами кода, которыми пользуются 80% Python-разработчиков. И поскольку большинство других редакторов кода, как правило, работают аналогичным образом, все его преимущества должны работать практически для всех редакторов кода. -Таким образом, я смог найти наилучшие способы сократить дублирование кода, обеспечить повсеместное автозавершение, проверку типов и ошибок и т.д. +Таким образом, я смог найти наилучшие способы максимально сократить дублирование кода, обеспечить автозавершение везде, проверки типов и ошибок и т.д. -И все это, чтобы все разработчики могли получать наилучший опыт разработки. +И всё это таким образом, чтобы предоставить всем разработчикам наилучший опыт разработки. ## Зависимости { #requirements } -Протестировав несколько вариантов, я решил, что в качестве основы буду использовать [**Pydantic**](https://docs.pydantic.dev/) и его преимущества. +Протестировав несколько альтернатив, я решил, что буду использовать [**Pydantic**](https://pydantic.dev/docs/) из-за его преимуществ. -По моим предложениям был изменён код этого фреймворка, чтобы сделать его полностью совместимым с JSON Schema, поддержать различные способы определения ограничений и улучшить поддержку в редакторах кода (проверки типов, автозавершение) на основе тестов в нескольких редакторах. +Затем я внес в него вклад, чтобы сделать его полностью совместимым с JSON Schema, поддержать разные способы определения объявлений ограничений и улучшить поддержку редакторов кода (проверки типов, автозавершение) на основе тестов в нескольких редакторах кода. -Во время разработки я также внес вклад в [**Starlette**](https://www.starlette.dev/), другую ключевую зависимость. +Во время разработки я также внес вклад в [**Starlette**](https://starlette.dev/), другую ключевую зависимость. ## Разработка { #development } -К тому времени, когда я начал создавать **FastAPI**, большинство необходимых деталей уже существовало, дизайн был определён, зависимости и прочие инструменты были готовы, а знания о стандартах и спецификациях были четкими и свежими. +К тому времени, когда я начал создавать сам **FastAPI**, большинство деталей уже было на своих местах, дизайн был определён, зависимости и инструменты были готовы, а знания о стандартах и спецификациях были чёткими и свежими. ## Будущее { #future } -Сейчас уже ясно, что **FastAPI** со своими идеями стал полезен многим людям. +На этом этапе уже ясно, что **FastAPI** со своими идеями полезен многим людям. -При сравнении с альтернативами, выбор падает на него, поскольку он лучше подходит для множества вариантов использования. +Его выбирают вместо предыдущих альтернатив, потому что он лучше подходит для многих вариантов использования. -Многие разработчики и команды уже используют **FastAPI** в своих проектах (включая меня и мою команду). +Многие разработчики и команды уже полагаются на **FastAPI** в своих проектах (включая меня и мою команду). -Но, тем не менее, грядёт добавление ещё многих улучшений и возможностей. +Но всё ещё впереди много улучшений и возможностей. -У **FastAPI** великое будущее. +У **FastAPI** отличное будущее. И [ваша помощь](help-fastapi.md) очень ценится. diff --git a/docs/ru/docs/how-to/custom-request-and-route.md b/docs/ru/docs/how-to/custom-request-and-route.md index 6a7ecbc..8deed22 100644 --- a/docs/ru/docs/how-to/custom-request-and-route.md +++ b/docs/ru/docs/how-to/custom-request-and-route.md @@ -66,7 +66,7 @@ Именно этих двух компонентов — `scope` и `receive` — достаточно, чтобы создать новый экземпляр `Request`. -Чтобы узнать больше о `Request`, см. [документацию Starlette о запросах](https://www.starlette.dev/requests/). +Чтобы узнать больше о `Request`, см. [документацию Starlette о запросах](https://starlette.dev/requests/). /// diff --git a/docs/ru/docs/how-to/extending-openapi.md b/docs/ru/docs/how-to/extending-openapi.md index 4a0a91b..dad7426 100644 --- a/docs/ru/docs/how-to/extending-openapi.md +++ b/docs/ru/docs/how-to/extending-openapi.md @@ -45,7 +45,7 @@ Используя информацию выше, вы можете той же вспомогательной функцией сгенерировать схему OpenAPI и переопределить любые нужные части. -Например, добавим [расширение OpenAPI ReDoc для включения собственного логотипа](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo). +Например, добавим [расширение OpenAPI ReDoc для включения собственного логотипа](https://github.com/Redocly/redoc/blob/main/docs/redoc-vendor-extensions.md#x-logo). ### Обычный **FastAPI** { #normal-fastapi } diff --git a/docs/ru/docs/how-to/graphql.md b/docs/ru/docs/how-to/graphql.md index 880fca2..2283364 100644 --- a/docs/ru/docs/how-to/graphql.md +++ b/docs/ru/docs/how-to/graphql.md @@ -22,7 +22,7 @@ * [Strawberry](https://strawberry.rocks/) 🍓 * С [документацией для FastAPI](https://strawberry.rocks/docs/integrations/fastapi) * [Ariadne](https://ariadnegraphql.org/) - * С [документацией для FastAPI](https://ariadnegraphql.org/docs/fastapi-integration) + * С [документацией для FastAPI](https://ariadnegraphql.org/server/Integrations/fastapi-integration) * [Tartiflette](https://tartiflette.io/) * С [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) для интеграции с ASGI * [Graphene](https://graphene-python.org/) diff --git a/docs/ru/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/ru/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index e321926..f650590 100644 --- a/docs/ru/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/ru/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -24,7 +24,7 @@ FastAPI 0.128.0 также убрал поддержку `pydantic.v1`, так ## Официальное руководство { #official-guide } -У Pydantic есть официальное [руководство по миграции](https://docs.pydantic.dev/latest/migration/) с v1 на v2. +У Pydantic есть официальное [руководство по миграции](https://pydantic.dev/docs/validation/latest/get-started/migration/) с v1 на v2. Там также описано, что изменилось, как валидации стали более корректными и строгими, возможные нюансы и т.д. diff --git a/docs/ru/docs/index.md b/docs/ru/docs/index.md index 717d5d7..c8005fe 100644 --- a/docs/ru/docs/index.md +++ b/docs/ru/docs/index.md @@ -110,7 +110,7 @@ FastAPI — это современный, быстрый (высокопрои
-## FastAPI Conf { #fastapi-conf } - -[**FastAPI Conf '26**](https://fastapiconf.com) пройдёт **28 октября 2026** в **Амстердаме, Нидерланды**. Всё о FastAPI — из первых рук. 🎤 - -FastAPI Conf '26 — 28 октября 2026 — Амстердам, Нидерланды - ## Мини-документальный фильм о FastAPI { #fastapi-mini-documentary } В конце 2025 года вышел [мини-документальный фильм о FastAPI](https://www.youtube.com/watch?v=mpR8ngthqiE), вы можете посмотреть его онлайн: @@ -175,17 +169,17 @@ FastAPI — это современный, быстрый (высокопрои FastAPI стоит на плечах гигантов: -* [Starlette](https://www.starlette.dev/) для части, связанной с вебом. -* [Pydantic](https://docs.pydantic.dev/) для части, связанной с данными. +* [Starlette](https://starlette.dev/) для части, связанной с вебом. +* [Pydantic](https://pydantic.dev/docs/) для части, связанной с данными. ## Установка { #installation } -Создайте и активируйте [виртуальное окружение](https://fastapi.tiangolo.com/ru/virtual-environments/), затем установите FastAPI: +Сначала [установите `uv`](https://docs.astral.sh/uv/getting-started/installation/), а затем добавьте FastAPI в ваш проект:
```console -$ pip install "fastapi[standard]" +$ uv add "fastapi[standard]" ---> 100% ``` @@ -194,6 +188,8 @@ $ pip install "fastapi[standard]" **Примечание**: Обязательно заключите `"fastapi[standard]"` в кавычки, чтобы это работало во всех терминалах. +Если вы предпочитаете использовать `pip`, установите `fastapi[standard]` внутри виртуального окружения. См. [руководство по установке](tutorial/#install-fastapi) для альтернативных шагов. + ## Пример { #example } ### Создание { #create-it } @@ -250,7 +246,7 @@ async def read_item(item_id: int, q: str | None = None):
```console -$ fastapi dev +$ uv run fastapi dev ╭────────── FastAPI CLI - Development mode ───────────╮ │ │ @@ -277,7 +273,7 @@ INFO: Application startup complete.
О команде fastapi dev... -Команда `fastapi dev` читает ваш файл `main.py`, находит в нём приложение **FastAPI** и запускает сервер с помощью [Uvicorn](https://www.uvicorn.dev). +Команда `fastapi dev` читает ваш файл `main.py`, находит в нём приложение **FastAPI** и запускает сервер с помощью [Uvicorn](https://uvicorn.dev). По умолчанию `fastapi dev` запускается с включённой авто-перезагрузкой для локальной разработки. @@ -314,7 +310,7 @@ INFO: Application startup complete. Теперь откройте [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc). -Вы увидите альтернативную автоматическую документацию (предоставлена [ReDoc](https://github.com/Rebilly/ReDoc)): +Вы увидите альтернативную автоматическую документацию (предоставлена [ReDoc](https://github.com/Redocly/redoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -497,7 +493,7 @@ item: Item
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -540,7 +536,7 @@ FastAPI зависит от Pydantic и Starlette. ### Зависимости `standard` { #standard-dependencies } -Когда вы устанавливаете FastAPI с помощью `pip install "fastapi[standard]"`, он идёт с группой опциональных зависимостей `standard`: +Когда вы устанавливаете FastAPI с помощью `uv add "fastapi[standard]"`, он идёт с группой опциональных зависимостей `standard`: Используется Pydantic: @@ -554,17 +550,17 @@ FastAPI зависит от Pydantic и Starlette. Используется FastAPI: -* [`uvicorn`](https://www.uvicorn.dev) — сервер, который загружает и «отдаёт» ваше приложение. Включает `uvicorn[standard]`, содержащий некоторые зависимости (например, `uvloop`), нужные для высокой производительности. +* [`uvicorn`](https://uvicorn.dev) — сервер, который загружает и «отдаёт» ваше приложение. Включает `uvicorn[standard]`, содержащий некоторые зависимости (например, `uvloop`), нужные для высокой производительности. * `fastapi-cli[standard]` — чтобы предоставить команду `fastapi`. * Включает `fastapi-cloud-cli`, который позволяет развернуть ваше приложение FastAPI в [FastAPI Cloud](https://fastapicloud.com). ### Без зависимостей `standard` { #without-standard-dependencies } -Если вы не хотите включать опциональные зависимости `standard`, можно установить `pip install fastapi` вместо `pip install "fastapi[standard]"`. +Если вы не хотите включать опциональные зависимости `standard`, можно установить `uv add fastapi` вместо `uv add "fastapi[standard]"`. ### Без `fastapi-cloud-cli` { #without-fastapi-cloud-cli } -Если вы хотите установить FastAPI со стандартными зависимостями, но без `fastapi-cloud-cli`, установите `pip install "fastapi[standard-no-fastapi-cloud-cli]"`. +Если вы хотите установить FastAPI со стандартными зависимостями, но без `fastapi-cloud-cli`, установите `uv add "fastapi[standard-no-fastapi-cloud-cli]"`. ### Дополнительные опциональные зависимости { #additional-optional-dependencies } @@ -572,13 +568,13 @@ FastAPI зависит от Pydantic и Starlette. Дополнительные опциональные зависимости Pydantic: -* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) — для управления настройками. -* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) — дополнительные типы для использования с Pydantic. +* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) — для управления настройками. +* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) — дополнительные типы для использования с Pydantic. Дополнительные опциональные зависимости FastAPI: * [`orjson`](https://github.com/ijl/orjson) — обязателен, если вы хотите использовать `ORJSONResponse`. -* [`ujson`](https://github.com/esnme/ultrajson) — обязателен, если вы хотите использовать `UJSONResponse`. +* [`ujson`](https://github.com/ultrajson/ultrajson) — обязателен, если вы хотите использовать `UJSONResponse`. ## Лицензия { #license } diff --git a/docs/ru/docs/project-generation.md b/docs/ru/docs/project-generation.md index abcc78e..e064a21 100644 --- a/docs/ru/docs/project-generation.md +++ b/docs/ru/docs/project-generation.md @@ -4,13 +4,13 @@ Вы можете использовать этот шаблон для старта: в нём уже сделана значительная часть начальной настройки, безопасность, база данных и несколько эндпоинтов API. -Репозиторий GitHub: [Full Stack FastAPI Template](https://github.com/tiangolo/full-stack-fastapi-template) +Репозиторий GitHub: [Full Stack FastAPI Template](https://github.com/fastapi/full-stack-fastapi-template) ## Шаблон Full Stack FastAPI — Технологический стек и возможности { #full-stack-fastapi-template-technology-stack-and-features } - ⚡ [**FastAPI**](https://fastapi.tiangolo.com/ru) для бэкенд‑API на Python. - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) для взаимодействия с SQL‑базой данных на Python (ORM). - - 🔍 [Pydantic](https://docs.pydantic.dev), используется FastAPI, для валидации данных и управления настройками. + - 🔍 [Pydantic](https://pydantic.dev/docs/), используется FastAPI, для валидации данных и управления настройками. - 💾 [PostgreSQL](https://www.postgresql.org) в качестве SQL‑базы данных. - 🚀 [React](https://react.dev) для фронтенда. - 💃 Используются TypeScript, хуки, Vite и другие части современного фронтенд‑стека. diff --git a/docs/ru/docs/python-types.md b/docs/ru/docs/python-types.md index 4791899..8df2d59 100644 --- a/docs/ru/docs/python-types.md +++ b/docs/ru/docs/python-types.md @@ -269,7 +269,7 @@ def some_function(data: Any): ## Pydantic-модели { #pydantic-models } -[Pydantic](https://docs.pydantic.dev/) — это библиотека Python для валидации данных. +[Pydantic](https://pydantic.dev/docs/) — это библиотека Python для валидации данных. Вы объявляете «форму» данных как классы с атрибутами. @@ -285,7 +285,7 @@ def some_function(data: Any): /// note | Примечание -Чтобы узнать больше о [Pydantic, ознакомьтесь с его документацией](https://docs.pydantic.dev/). +Чтобы узнать больше о [Pydantic, ознакомьтесь с его документацией](https://pydantic.dev/docs/). /// diff --git a/docs/ru/docs/tutorial/background-tasks.md b/docs/ru/docs/tutorial/background-tasks.md index 22827b6..e7f9c2d 100644 --- a/docs/ru/docs/tutorial/background-tasks.md +++ b/docs/ru/docs/tutorial/background-tasks.md @@ -1,19 +1,19 @@ # Фоновые задачи { #background-tasks } -Вы можете создавать фоновые задачи, которые будут выполняться после возврата ответа. +Вы можете создавать фоновые задачи, которые будут выполняться *после* возврата HTTP-ответа. -Это полезно для операций, которые должны произойти после HTTP-запроса, но клиенту не обязательно ждать их завершения, чтобы получить ответ. +Это полезно для операций, которые должны произойти после HTTP-запроса, но клиенту не обязательно ждать их завершения, прежде чем получить HTTP-ответ. -Например: +Сюда входят, например: * Уведомления по электронной почте, отправляемые после выполнения действия: - * Так как подключение к почтовому серверу и отправка письма обычно «медленные» (несколько секунд), вы можете сразу вернуть ответ, а отправку уведомления выполнить в фоне. + * Так как подключение к почтовому серверу и отправка письма обычно «медленные» (несколько секунд), вы можете сразу вернуть HTTP-ответ, а отправку уведомления выполнить в фоне. * Обработка данных: - * Например, если вы получаете файл, который должен пройти через медленный процесс, вы можете вернуть ответ «Accepted» (HTTP 202) и обработать файл в фоне. + * Например, если вы получаете файл, который должен пройти через медленный процесс, вы можете вернуть HTTP-ответ «Accepted» (HTTP 202) и обработать файл в фоне. ## Использование `BackgroundTasks` { #using-backgroundtasks } -Сначала импортируйте `BackgroundTasks` и объявите параметр в вашей функции‑обработчике пути с типом `BackgroundTasks`: +Сначала импортируйте `BackgroundTasks` и объявите параметр в вашей *функции‑обработчике пути* с типом `BackgroundTasks`: {* ../../docs_src/background_tasks/tutorial001_py310.py hl[1,13] *} @@ -35,7 +35,7 @@ ## Добавление фоновой задачи { #add-the-background-task } -Внутри вашей функции‑обработчика пути передайте функцию задачи объекту фоновых задач методом `.add_task()`: +Внутри вашей *функции‑обработчика пути* передайте функцию задачи объекту *фоновых задач* методом `.add_task()`: {* ../../docs_src/background_tasks/tutorial001_py310.py hl[14] *} @@ -47,29 +47,31 @@ ## Встраивание зависимостей { #dependency-injection } -Использование `BackgroundTasks` также работает с системой встраивания зависимостей, вы можете объявить параметр типа `BackgroundTasks` на нескольких уровнях: в функции‑обработчике пути, в зависимости (dependable), в подзависимости и т.д. +Использование `BackgroundTasks` также работает с системой встраивания зависимостей, вы можете объявить параметр типа `BackgroundTasks` на нескольких уровнях: в *функции‑обработчике пути*, в зависимости (dependable), в подзависимости и т.д. **FastAPI** знает, что делать в каждом случае и как переиспользовать один и тот же объект, так чтобы все фоновые задачи были объединены и затем выполнены в фоне: + {* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *} -В этом примере сообщения будут записаны в файл `log.txt` после отправки ответа. -Если в запросе была строка запроса (query), она будет записана в лог фоновой задачей. +В этом примере сообщения будут записаны в файл `log.txt` *после* отправки HTTP-ответа. -Затем другая фоновая задача, созданная в функции‑обработчике пути, запишет сообщение, используя path‑параметр `email`. +Если в HTTP-запросе была строка запроса (query), она будет записана в лог фоновой задачей. + +Затем другая фоновая задача, созданная в *функции‑обработчике пути*, запишет сообщение, используя path‑параметр `email`. ## Технические детали { #technical-details } -Класс `BackgroundTasks` приходит напрямую из [`starlette.background`](https://www.starlette.dev/background/). +Класс `BackgroundTasks` приходит напрямую из [`starlette.background`](https://starlette.dev/background/). Он импортируется/включается прямо в FastAPI, чтобы вы могли импортировать его из `fastapi` и избежать случайного импорта альтернативного `BackgroundTask` (без `s` на конце) из `starlette.background`. -Используя только `BackgroundTasks` (а не `BackgroundTask`), его можно применять как параметр функции‑обработчика пути, и **FastAPI** сделает остальное за вас, как при использовании объекта `Request` напрямую. +Используя только `BackgroundTasks` (а не `BackgroundTask`), его можно применять как параметр *функции‑обработчика пути*, и **FastAPI** сделает остальное за вас, как при использовании объекта `Request` напрямую. По‑прежнему можно использовать один `BackgroundTask` в FastAPI, но тогда вам нужно создать объект в своём коде и вернуть Starlette `Response`, включающий его. -Подробнее см. в [официальной документации Starlette по фоновым задачам](https://www.starlette.dev/background/). +Подробнее см. в [официальной документации Starlette по фоновым задачам](https://starlette.dev/background/). ## Предостережение { #caveat } @@ -81,4 +83,4 @@ ## Резюме { #recap } -Импортируйте и используйте `BackgroundTasks` с параметрами в функциях‑обработчиках пути и зависимостях, чтобы добавлять фоновые задачи. +Импортируйте и используйте `BackgroundTasks` с параметрами в *функциях‑обработчиках пути* и зависимостях, чтобы добавлять фоновые задачи. diff --git a/docs/ru/docs/tutorial/bigger-applications.md b/docs/ru/docs/tutorial/bigger-applications.md index 038777b..3509d48 100644 --- a/docs/ru/docs/tutorial/bigger-applications.md +++ b/docs/ru/docs/tutorial/bigger-applications.md @@ -487,7 +487,7 @@ from app.main import app Вы также можете передать путь в команду, например: ```console -$ fastapi dev app/main.py +$ uv run fastapi dev app/main.py ``` Но вам придётся каждый раз помнить и указывать корректный путь при вызове команды `fastapi`. @@ -503,7 +503,7 @@ $ fastapi dev app/main.py
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/ru/docs/tutorial/body-nested-models.md b/docs/ru/docs/tutorial/body-nested-models.md index 5dc06d2..dd28954 100644 --- a/docs/ru/docs/tutorial/body-nested-models.md +++ b/docs/ru/docs/tutorial/body-nested-models.md @@ -1,4 +1,4 @@ -# Body - Вложенные модели { #body-nested-models } +# Тело запроса - Вложенные модели { #body-nested-models } С помощью **FastAPI** вы можете определять, валидировать, документировать и использовать модели произвольной глубины вложенности (благодаря Pydantic). @@ -96,7 +96,7 @@ my_list: list[str] Помимо обычных простых типов, таких как `str`, `int`, `float` и т.д., вы можете использовать более сложные простые типы, которые наследуются от `str`. -Чтобы увидеть все варианты, которые у вас есть, ознакомьтесь с [обзором типов Pydantic](https://docs.pydantic.dev/latest/concepts/types/). Вы увидите некоторые примеры в следующей главе. +Чтобы увидеть все варианты, которые у вас есть, ознакомьтесь с [обзором типов Pydantic](https://pydantic.dev/docs/validation/latest/concepts/types/). Вы увидите некоторые примеры в следующей главе. Например, так как в модели `Image` у нас есть поле `url`, то мы можем объявить его как тип `HttpUrl` из Pydantic вместо типа `str`: diff --git a/docs/ru/docs/tutorial/body.md b/docs/ru/docs/tutorial/body.md index f1b76cb..77147ec 100644 --- a/docs/ru/docs/tutorial/body.md +++ b/docs/ru/docs/tutorial/body.md @@ -6,7 +6,7 @@ Ваш API почти всегда должен отправлять тело **ответа**. Но клиентам не обязательно всегда отправлять **тело запроса**: иногда они запрашивают только путь, возможно с некоторыми параметрами запроса, но без тела. -Чтобы объявить тело **запроса**, используйте модели [Pydantic](https://docs.pydantic.dev/), со всей их мощью и преимуществами. +Чтобы объявить тело **запроса**, используйте модели [Pydantic](https://pydantic.dev/docs/), со всей их мощью и преимуществами. /// note | Заметка @@ -70,7 +70,7 @@ * Считает тело запроса как JSON. * Приведёт данные к соответствующим типам (если потребуется). * Проведёт валидацию данных. - * Если данные некорректны, вернёт понятную и наглядную ошибку, указывающую, где именно and что было некорректно. + * Если данные некорректны, вернёт понятную и наглядную ошибку, указывающую, где именно и что было некорректно. * Передаст полученные данные в параметр `item`. * Поскольку внутри функции вы объявили его с типом `Item`, у вас будет поддержка со стороны редактора кода (автозавершение и т.п.) для всех атрибутов и их типов. * Сгенерирует определения [JSON Schema](https://json-schema.org) для вашей модели; вы можете использовать их и в других местах, если это имеет смысл для вашего проекта. diff --git a/docs/ru/docs/tutorial/debugging.md b/docs/ru/docs/tutorial/debugging.md index 5a58085..d2faef4 100644 --- a/docs/ru/docs/tutorial/debugging.md +++ b/docs/ru/docs/tutorial/debugging.md @@ -15,7 +15,7 @@
```console -$ python myapp.py +$ uv run python myapp.py ```
@@ -35,7 +35,7 @@ from myapp import app
```console -$ python myapp.py +$ uv run python myapp.py ```
diff --git a/docs/ru/docs/tutorial/extra-data-types.md b/docs/ru/docs/tutorial/extra-data-types.md index d05a00e..201af19 100644 --- a/docs/ru/docs/tutorial/extra-data-types.md +++ b/docs/ru/docs/tutorial/extra-data-types.md @@ -25,31 +25,31 @@ * Стандартный "Универсальный уникальный идентификатор", используемый в качестве идентификатора во многих базах данных и системах. * В HTTP-запросах и HTTP-ответах будет представлен как `str`. * `datetime.datetime`: - * Встроенный в Python `datetime.datetime`. + * Python `datetime.datetime`. * В HTTP-запросах и HTTP-ответах будет представлен как `str` в формате ISO 8601, например: `2008-09-15T15:53:00+05:00`. * `datetime.date`: - * Встроенный в Python `datetime.date`. + * Python `datetime.date`. * В HTTP-запросах и HTTP-ответах будет представлен как `str` в формате ISO 8601, например: `2008-09-15`. * `datetime.time`: - * Встроенный в Python `datetime.time`. + * Python `datetime.time`. * В HTTP-запросах и HTTP-ответах будет представлен как `str` в формате ISO 8601, например: `14:23:55.003`. * `datetime.timedelta`: - * Встроенный в Python `datetime.timedelta`. + * Python `datetime.timedelta`. * В HTTP-запросах и HTTP-ответах будет представлен в виде общего количества секунд типа `float`. - * Pydantic также позволяет представить его как "Кодировку разницы во времени ISO 8601", [см. документацию для получения дополнительной информации](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers). + * Pydantic также позволяет представить его как "кодировку разницы во времени ISO 8601", [см. документацию для получения дополнительной информации](https://pydantic.dev/docs/validation/latest/concepts/serialization/#custom-serializers). * `frozenset`: * В HTTP-запросах и HTTP-ответах обрабатывается так же, как и `set`: * В HTTP-запросах будет прочитан список, исключены дубликаты и преобразован в `set`. * В HTTP-ответах `set` будет преобразован в `list`. * В сгенерированной схеме будет указано, что значения `set` уникальны (с помощью JSON-схемы `uniqueItems`). * `bytes`: - * Встроенный в Python `bytes`. + * Стандартный Python `bytes`. * В HTTP-запросах и HTTP-ответах будет рассматриваться как `str`. * В сгенерированной схеме будет указано, что это `str` в "формате" `binary`. * `Decimal`: - * Встроенный в Python `Decimal`. + * Стандартный Python `Decimal`. * В HTTP-запросах и HTTP-ответах обрабатывается так же, как и `float`. -* Вы можете проверить все допустимые типы данных Pydantic здесь: [Типы данных Pydantic](https://docs.pydantic.dev/latest/usage/types/types/). +* Вы можете проверить все допустимые типы данных Pydantic здесь: [Типы данных Pydantic](https://pydantic.dev/docs/validation/latest/concepts/types/). ## Пример { #example } diff --git a/docs/ru/docs/tutorial/extra-models.md b/docs/ru/docs/tutorial/extra-models.md index cec61ed..e66a66b 100644 --- a/docs/ru/docs/tutorial/extra-models.md +++ b/docs/ru/docs/tutorial/extra-models.md @@ -166,7 +166,7 @@ UserInDB( /// note | Примечание -При объявлении [`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions) сначала указывайте наиболее специфичный тип, затем менее специфичный. В примере ниже более специфичный `PlaneItem` стоит перед `CarItem` в `Union[PlaneItem, CarItem]`. +При объявлении [`Union`](https://pydantic.dev/docs/validation/latest/concepts/unions/) сначала указывайте наиболее специфичный тип, затем менее специфичный. В примере ниже более специфичный `PlaneItem` стоит перед `CarItem` в `Union[PlaneItem, CarItem]`. /// diff --git a/docs/ru/docs/tutorial/first-steps.md b/docs/ru/docs/tutorial/first-steps.md index 8841a90..d3953f6 100644 --- a/docs/ru/docs/tutorial/first-steps.md +++ b/docs/ru/docs/tutorial/first-steps.md @@ -6,12 +6,18 @@ Скопируйте это в файл `main.py`. +/// tip | Подсказка + +У FastAPI есть [официальное расширение для VS Code](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (и Cursor), которое предоставляет множество функций, включая обозреватель операций пути, поиск операций пути, навигацию CodeLens в тестах (переход к определению из тестов), а также развертывание и логи FastAPI Cloud — всё из вашего редактора кода. + +/// + Запустите сервер в режиме реального времени:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -78,7 +84,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) И теперь перейдите по адресу [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc). -Вы увидите альтернативную автоматически сгенерированную документацию (предоставлено [ReDoc](https://github.com/Rebilly/ReDoc)): +Вы увидите альтернативную автоматически сгенерированную документацию (предоставлено [ReDoc](https://github.com/Redocly/redoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -185,13 +191,13 @@ from backend.main import app Вы также можете передать путь к файлу в команду `fastapi dev`, и она попытается определить объект приложения FastAPI для использования: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` Или вы можете передать опцию `--entrypoint` команде `fastapi dev`: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` Но в этом случае вам придётся каждый раз помнить о передаче корректного пути/entrypoint при вызове команды `fastapi`. @@ -205,7 +211,7 @@ $ fastapi dev --entrypoint main:app
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -232,7 +238,7 @@ CLI автоматически определит ваше приложение `FastAPI` — это класс, который напрямую наследуется от `Starlette`. -Вы можете использовать весь функционал [Starlette](https://www.starlette.dev/) и в `FastAPI`. +Вы можете использовать весь функционал [Starlette](https://starlette.dev/) и в `FastAPI`. /// diff --git a/docs/ru/docs/tutorial/frontend.md b/docs/ru/docs/tutorial/frontend.md index b7f4dc0..61a10ac 100644 --- a/docs/ru/docs/tutorial/frontend.md +++ b/docs/ru/docs/tutorial/frontend.md @@ -52,7 +52,7 @@ npm run build {* ../../docs_src/frontend/tutorial002_py310.py hl[5] *} -**FastAPI** использует этот fallback только для запросов `GET` и `HEAD`, которые похожи на навигацию в браузере. Отсутствующие файлы, такие как JavaScript, CSS и изображения, по-прежнему возвращают `404`. +**FastAPI** использует этот fallback только для HTTP-запросов `GET` и `HEAD`, которые явно принимают HTML с `Accept: text/html` или `Accept: application/xhtml+xml`, как обычно делают запросы навигации в браузере. Отсутствующие файлы, такие как JavaScript, CSS и изображения, по-прежнему возвращают `404`. Запросы с другими методами, например `POST` или `PUT`, к путям, которые совпадают только с fallback фронтенда, также возвращают `404`. Обычные *операции пути* **FastAPI** по-прежнему имеют более высокий приоритет, чем маршруты фронтенда. @@ -106,9 +106,13 @@ npm run build ## Проверка директории { #check-directory } -По умолчанию `app.frontend()` проверяет, что директория существует, при создании приложения. +По умолчанию `app.frontend()` использует `check_dir="auto"`. -Это помогает рано обнаруживать ошибки конфигурации. Например, если отсутствует директория с результатом сборки фронтенда, **FastAPI** вызовет ошибку при запуске. +Когда переменная окружения `FASTAPI_ENV` установлена в `development`, **FastAPI** только отображает предупреждение, если директория с результатом сборки фронтенда отсутствует. Команда [`fastapi dev`](https://github.com/fastapi/fastapi-cli#fastapi-dev) устанавливает эту переменную окружения за вас, если она ещё не установлена. Это позволяет запускать backend до сборки или запуска frontend во время разработки. + +В любом другом окружении **FastAPI** вызывает ошибку при создании приложения. Это помогает рано обнаруживать ошибки конфигурации до развертывания приложения без его фронтенд-файлов. + +Вы также можете установить `check_dir=True`, чтобы всегда проверять директорию при создании приложения. Если ваши фронтенд-файлы создаются позже, например отдельным этапом сборки после создания объекта приложения, установите `check_dir=False`: @@ -132,6 +136,8 @@ HTTP-ответы фронтенда выполняются внутри обы Зависимости из приложения, из `APIRouter` и из `include_router()` также применяются к HTTP-ответам фронтенда. Это может быть полезно для защиты фронтенда с помощью аутентификации на основе cookie или похожего механизма. +Зависимости также могут изменять HTTP-заголовки ответа и добавлять фоновые задачи, как и в обычных *операциях пути*. + ## Только статический результат сборки { #static-build-output-only } `app.frontend()` отдаёт файлы, уже сгенерированные сборкой вашего фронтенда. diff --git a/docs/ru/docs/tutorial/handling-errors.md b/docs/ru/docs/tutorial/handling-errors.md index 9676ac7..7ff882b 100644 --- a/docs/ru/docs/tutorial/handling-errors.md +++ b/docs/ru/docs/tutorial/handling-errors.md @@ -81,7 +81,7 @@ HTTP статус-коды в диапазоне 400 означают, что п ## Установка пользовательских обработчиков исключений { #install-custom-exception-handlers } -Вы можете добавить пользовательские обработчики исключений с помощью [тех же утилит обработки исключений из Starlette](https://www.starlette.dev/exceptions/). +Вы можете добавить пользовательские обработчики исключений с помощью [тех же утилит обработки исключений из Starlette](https://starlette.dev/exceptions/). Допустим, у вас есть пользовательское исключение `UnicornException`, которое вы (или используемая вами библиотека) можете вызвать с помощью `raise`. diff --git a/docs/ru/docs/tutorial/index.md b/docs/ru/docs/tutorial/index.md index b843515..998413f 100644 --- a/docs/ru/docs/tutorial/index.md +++ b/docs/ru/docs/tutorial/index.md @@ -1,7 +1,6 @@ # Учебник - Руководство пользователя { #tutorial-user-guide } - -В этом руководстве шаг за шагом показано, как использовать **FastAPI** с большинством его функций. +This tutorial shows you how to use **FastAPI** with most of its features, step by step. Каждый раздел постепенно основывается на предыдущих, но структура разделяет темы, так что вы можете сразу перейти к нужной теме для решения ваших конкретных задач по API. @@ -11,12 +10,12 @@ Все блоки кода можно копировать и использовать напрямую (это действительно протестированные файлы Python). -Чтобы запустить любой из примеров, скопируйте код в файл `main.py` и запустите `fastapi dev`: +Чтобы запустить любой из примеров, скопируйте код в файл `main.py` и запустите `fastapi dev` с помощью `uv run`:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -61,35 +60,75 @@ $ fastapi dev ## Установка FastAPI { #install-fastapi } -Первый шаг — установить FastAPI. +Первый шаг — настроить ваш проект и добавить FastAPI. -Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его, и затем **установите FastAPI**: +Установите [`uv`](https://docs.astral.sh/uv/getting-started/installation/), затем создайте проект и добавьте FastAPI:
```console -$ pip install "fastapi[standard]" +$ uv init awesome-project --bare +$ cd awesome-project +$ uv add "fastapi[standard]" ---> 100% ```
+`uv add` создаёт виртуальное окружение проекта в `.venv`, добавляет FastAPI в `pyproject.toml` и создаёт `uv.lock`, чтобы те же версии пакетов можно было установить позже. + +/// details | Что делают эти команды + +* `uv init`: создаёт новый Python-проект. +* `awesome-project`: создаёт проект в новой директории с этим именем. +* `--bare`: создаёт только минимальный файл `pyproject.toml`, без генерации примерного `main.py`, `README.md` или других файлов. Файлы приложения вы создадите самостоятельно на следующих этапах этого руководства. + +Затем `cd awesome-project` переходит в директорию нового проекта перед добавлением FastAPI. + +`uv` будет использовать совместимую версию Python, уже установленную в вашей системе, или скачает её при необходимости. + +Когда вы запускаете `uv add`, он выбирает совместимые версии FastAPI и всех пакетов, от которых зависит FastAPI. Он записывает точные версии в `uv.lock`, что позволяет позже установить те же версии пакетов на другом компьютере или при развертывании приложения. + +Создание или обновление этого файла называется [**закреплением** зависимостей проекта](https://docs.astral.sh/uv/concepts/projects/sync/). `uv` делает это автоматически, когда вы добавляете пакет. + +/// + +/// details | Варианты установки FastAPI + +При установке с помощью `uv add "fastapi[standard]"` добавляются некоторые стандартные необязательные зависимости по умолчанию, включая `fastapi-cloud-cli`, который позволяет развернуть приложение на [FastAPI Cloud](https://fastapicloud.com). + +Если вы не хотите иметь эти необязательные зависимости, вместо этого можно установить `uv add fastapi`. + +Если вы хотите установить стандартные зависимости, но без `fastapi-cloud-cli`, можно установить с помощью `uv add "fastapi[standard-no-fastapi-cloud-cli]"`. + +/// + +/// details | Использование `pip` как альтернативы + +Если вы предпочитаете управлять виртуальным окружением и пакетами вручную, создайте и активируйте виртуальное окружение, а затем установите FastAPI с помощью `pip install "fastapi[standard]"`. + +Подробные шаги читайте в [руководстве по виртуальным окружениям](https://tiangolo.com/guides/virtual-environments/). + +/// + +## Навыки AI-агента { #ai-agent-skills } + +FastAPI включает официальный навык для AI-агентов для написания кода. Он поставляется вместе с пакетом, поэтому его рекомендации остаются согласованными с версией FastAPI, установленной в вашем проекте, и обновляются при обновлении FastAPI. + +После установки FastAPI в вашем проекте вы можете установить навык с помощью Library Skills: + +```bash +uvx library-skills +``` + /// note | Примечание -При установке с помощью `pip install "fastapi[standard]"` добавляются некоторые стандартные необязательные зависимости по умолчанию, включая `fastapi-cloud-cli`, который позволяет развернуть приложение на [FastAPI Cloud](https://fastapicloud.com). - -Если вы не хотите иметь эти необязательные зависимости, установите просто `pip install fastapi`. - -Если вы хотите установить стандартные зависимости, но без `fastapi-cloud-cli`, установите `pip install "fastapi[standard-no-fastapi-cloud-cli]"`. +`uvx` — это псевдоним для `uv tool run`. Он запускает Library Skills во временном изолированном окружении, пока Library Skills сканирует пакеты, установленные в вашем проекте. /// -/// tip | Совет - -У FastAPI есть [официальное расширение для VS Code](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (и Cursor), которое предоставляет множество функций, включая обзор операций пути, поиск операций пути, навигацию CodeLens в тестах (переход к определению из тестов), а также развертывание в FastAPI Cloud и просмотр логов - всё прямо из вашего редактора кода. - -/// +Навык совместим с Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Pi, OpenCode и большинством других агентов для написания кода. Для Claude Code выберите `.claude/skills`, когда вас спросят, куда установить навык. ## Продвинутое руководство пользователя { #advanced-user-guide } diff --git a/docs/ru/docs/tutorial/middleware.md b/docs/ru/docs/tutorial/middleware.md index 8114005..f296f82 100644 --- a/docs/ru/docs/tutorial/middleware.md +++ b/docs/ru/docs/tutorial/middleware.md @@ -1,15 +1,15 @@ -# Middleware (Промежуточный слой) { #middleware } +# Middleware { #middleware } -Вы можете добавить middleware (промежуточный слой) в **FastAPI** приложение. +Вы можете добавить middleware в приложения **FastAPI**. -"Middleware" - это функция, которая выполняется с каждым **запросом** до его обработки какой-либо конкретной *операцией пути*. А также с каждым **ответом** перед его возвращением. +"Middleware" - это функция, которая работает с каждым **HTTP-запросом** до его обработки какой-либо конкретной *операцией пути*. А также с каждым **HTTP-ответом** перед его возвращением. -* Она принимает каждый поступающий **запрос**. -* Может что-то сделать с этим **запросом** или выполнить любой нужный код. -* Затем передает **запрос** для последующей обработки (какой-либо *операцией пути*). -* Получает **ответ** (от *операции пути*). -* Может что-то сделать с этим **ответом** или выполнить любой нужный код. -* И возвращает **ответ**. +* Она принимает каждый **HTTP-запрос**, который поступает в ваше приложение. +* Затем может что-то сделать с этим **HTTP-запросом** или выполнить любой нужный код. +* Затем передаёт **HTTP-запрос** на обработку остальной части приложения (какой-либо *операцией пути*). +* Затем принимает **HTTP-ответ**, сгенерированный приложением (какой-либо *операцией пути*). +* Может что-то сделать с этим **HTTP-ответом** или выполнить любой нужный код. +* Затем возвращает **HTTP-ответ**. /// note | Технические детали @@ -25,19 +25,19 @@ Функция middleware получает: -* `request`. -* Функцию `call_next`, которая получает `request` в качестве параметра. - * Эта функция передаёт `request` соответствующей *операции пути*. +* Объект `request`. +* Функцию `call_next`, которая получит `request` в качестве параметра. + * Эта функция передаст `request` соответствующей *операции пути*. * Затем она возвращает `response`, сгенерированный соответствующей *операцией пути*. -* Также имеется возможность видоизменить `response` перед тем как его вернуть. +* Затем вы можете дополнительно изменить `response` перед тем как его вернуть. {* ../../docs_src/middleware/tutorial001_py310.py hl[8:9,11,14] *} /// tip | Совет -Имейте в виду, что можно добавлять проприетарные HTTP-заголовки [с префиксом `X-`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). +Имейте в виду, что пользовательские проприетарные HTTP-заголовки можно добавлять [с префиксом `X-`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). -Но если вы хотите, чтобы клиент в браузере мог видеть ваши пользовательские заголовки, необходимо добавить их в настройки CORS ([CORS (Cross-Origin Resource Sharing)](cors.md)), используя параметр `expose_headers`, описанный в [документации по CORS Starlette](https://www.starlette.dev/middleware/#corsmiddleware). +Но если у вас есть пользовательские HTTP-заголовки, которые клиент в браузере должен иметь возможность видеть, необходимо добавить их в настройки CORS ([CORS (Cross-Origin Resource Sharing)](cors.md)), используя параметр `expose_headers`, описанный в [документации по CORS Starlette](https://starlette.dev/middleware/#corsmiddleware). /// @@ -51,17 +51,17 @@ ### До и после `response` { #before-and-after-the-response } -Вы можете добавить код, использующий `request`, до передачи его какой-либо *операции пути*. +Вы можете добавить код, который будет выполняться с `request`, до того как его получит какая-либо *операция пути*. А также после формирования `response`, до того, как вы его вернёте. -Например, вы можете добавить собственный заголовок `X-Process-Time`, содержащий время в секундах, необходимое для обработки запроса и генерации ответа: +Например, вы можете добавить собственный заголовок `X-Process-Time`, содержащий время в секундах, необходимое для обработки HTTP-запроса и генерации HTTP-ответа: {* ../../docs_src/middleware/tutorial001_py310.py hl[10,12:13] *} /// tip | Совет -Мы используем [`time.perf_counter()`](https://docs.python.org/3/library/time.html#time.perf_counter) вместо `time.time()` для обеспечения большей точности в таких случаях. 🤓 +Здесь мы используем [`time.perf_counter()`](https://docs.python.org/3/library/time.html#time.perf_counter) вместо `time.time()` потому, что он может быть более точным для таких случаев. 🤓 /// @@ -69,9 +69,9 @@ Когда вы добавляете несколько middleware с помощью декоратора `@app.middleware()` или метода `app.add_middleware()`, каждое новое middleware оборачивает приложение, формируя стек. Последнее добавленное middleware — самое внешнее (*outermost*), а первое — самое внутреннее (*innermost*). -На пути обработки запроса сначала выполняется самое внешнее middleware. +На пути обработки HTTP-запроса сначала выполняется самое внешнее middleware. -На пути формирования ответа оно выполняется последним. +На пути формирования HTTP-ответа оно выполняется последним. Например: @@ -82,14 +82,14 @@ app.add_middleware(MiddlewareB) Это приводит к следующему порядку выполнения: -* **Запрос**: MiddlewareB → MiddlewareA → маршрут +* **HTTP-запрос**: MiddlewareB → MiddlewareA → маршрут -* **Ответ**: маршрут → MiddlewareA → MiddlewareB +* **HTTP-ответ**: маршрут → MiddlewareA → MiddlewareB Такое стековое поведение обеспечивает предсказуемый и управляемый порядок выполнения middleware. ## Другие middleware { #other-middlewares } -О других middleware вы можете узнать больше в разделе [Расширенное руководство пользователя: Продвинутое middleware](../advanced/middleware.md). +О других middleware вы можете узнать больше позже в разделе [Расширенное руководство пользователя: Продвинутое middleware](../advanced/middleware.md). -В следующем разделе вы можете прочитать, как настроить CORS с помощью middleware. +В следующем разделе вы прочитаете, как обрабатывать CORS с помощью middleware. diff --git a/docs/ru/docs/tutorial/path-params.md b/docs/ru/docs/tutorial/path-params.md index cfc9618..ecd2d32 100644 --- a/docs/ru/docs/tutorial/path-params.md +++ b/docs/ru/docs/tutorial/path-params.md @@ -4,7 +4,7 @@ {* ../../docs_src/path_params/tutorial001_py310.py hl[6:7] *} -Значение параметра пути `item_id` будет передано в функцию в качестве аргумента `item_id`. +Значение path-параметра `item_id` будет передано в функцию в качестве аргумента `item_id`. Если запустите этот пример и перейдёте по адресу: [http://127.0.0.1:8000/items/foo](http://127.0.0.1:8000/items/foo), то увидите ответ: @@ -12,9 +12,9 @@ {"item_id":"foo"} ``` -## Параметры пути с типами { #path-parameters-with-types } +## Path-параметры с типами { #path-parameters-with-types } -Вы можете объявить тип параметра пути в функции, используя стандартные аннотации типов Python: +Вы можете объявить тип path-параметра в функции, используя стандартные аннотации типов Python: {* ../../docs_src/path_params/tutorial002_py310.py hl[7] *} @@ -38,7 +38,7 @@ Обратите внимание на значение `3`, которое получила (и вернула) функция. Это целочисленный Python `int`, а не строка `"3"`. -Используя такое объявление типов, **FastAPI** выполняет автоматический HTTP-запрос "парсинг". +Используя такое объявление типов, **FastAPI** выполняет автоматический парсинг HTTP-запроса "парсинг". /// @@ -62,7 +62,7 @@ } ``` -из-за того, что параметр пути `item_id` имеет значение `"foo"`, которое не является типом `int`. +из-за того, что path-параметр `item_id` имеет значение `"foo"`, которое не является типом `int`. Та же ошибка возникнет, если вместо `int` передать `float`, например: [http://127.0.0.1:8000/items/4.2](http://127.0.0.1:8000/items/4.2) @@ -86,13 +86,13 @@ Ещё раз, просто используя определения типов, **FastAPI** обеспечивает автоматическую интерактивную документацию (с интеграцией Swagger UI). -Обратите внимание, что параметр пути объявлен целочисленным. +Обратите внимание, что path-параметр объявлен целочисленным. /// ## Преимущества стандартизации, альтернативная документация { #standards-based-benefits-alternative-documentation } -Поскольку сгенерированная схема соответствует стандарту [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md), её можно использовать со множеством совместимых инструментов. +Поскольку сгенерированная схема соответствует стандарту [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md), её можно использовать со множеством совместимых инструментов. Именно поэтому, **FastAPI** сам предоставляет альтернативную документацию API (используя ReDoc), которую можно получить по адресу: [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc). @@ -102,7 +102,7 @@ ## Pydantic { #pydantic } -Вся проверка данных выполняется под капотом с помощью [Pydantic](https://docs.pydantic.dev/), поэтому вы получаете все его преимущества. И вы можете быть уверены, что находитесь в надёжных руках. +Вся валидация данных выполняется под капотом с помощью [Pydantic](https://pydantic.dev/docs/), поэтому вы получаете все его преимущества. И вы можете быть уверены, что находитесь в надёжных руках. Вы можете использовать в аннотациях как простые типы данных, вроде `str`, `float`, `bool`, так и более сложные типы. @@ -122,7 +122,7 @@ Иначе путь для `/users/{user_id}` также будет соответствовать `/users/me`, "подразумевая", что он получает параметр `user_id` со значением `"me"`. -Аналогично, вы не можете переопределить операцию с путем: +Аналогично, вы не можете переопределить операцию пути: {* ../../docs_src/path_params/tutorial003b_py310.py hl[6,11] *} @@ -130,7 +130,7 @@ ## Предопределенные значения { #predefined-values } -Что если нам нужно заранее определить допустимые *параметры пути*, которые *операция пути* может принимать? В таком случае можно использовать стандартное перечисление `Enum` Python. +Что если нам нужно заранее определить допустимые *path-параметры*, которые *операция пути* может принимать? В таком случае можно использовать стандартное перечисление `Enum` Python. ### Создание класса `Enum` { #create-an-enum-class } @@ -144,25 +144,25 @@ /// tip | Подсказка -Если интересно, то "AlexNet", "ResNet" и "LeNet" - это названия моделей Машинного обучения. +Если интересно, то "AlexNet", "ResNet" и "LeNet" - это названия моделей Машинного обучения. /// -### Определение *параметра пути* { #declare-a-path-parameter } +### Объявление *path-параметра* { #declare-a-path-parameter } -Определите *параметр пути*, используя в аннотации типа класс перечисления (`ModelName`), созданный ранее: +Определите *path-параметр*, используя в аннотации типа класс перечисления (`ModelName`), созданный ранее: {* ../../docs_src/path_params/tutorial005_py310.py hl[16] *} ### Проверьте документацию { #check-the-docs } -Поскольку доступные значения *параметра пути* определены заранее, интерактивная документация может наглядно их отображать: +Поскольку доступные значения *path-параметра* определены заранее, интерактивная документация может наглядно их отображать: ### Работа с *перечислениями* в Python { #working-with-python-enumerations } -Значение *параметра пути* будет *элементом перечисления*. +Значение *path-параметра* будет *элементом перечисления*. #### Сравнение *элементов перечисления* { #compare-enumeration-members } @@ -189,6 +189,7 @@ Они будут преобразованы в соответствующие значения (в данном случае - строки) перед их возвратом клиенту: {* ../../docs_src/path_params/tutorial005_py310.py hl[18,21,23] *} + На стороне клиента вы получите такой JSON-ответ: ```JSON @@ -208,7 +209,7 @@ ### Поддержка OpenAPI { #openapi-support } -OpenAPI не поддерживает способов объявления *параметра пути*, содержащего внутри *путь*, так как это может привести к сценариям, которые сложно определять и тестировать. +OpenAPI не поддерживает способа объявления *path-параметра*, содержащего внутри *путь*, так как это может привести к сценариям, которые сложно определять и тестировать. Тем не менее это можно сделать в **FastAPI**, используя один из внутренних инструментов Starlette. @@ -216,7 +217,7 @@ OpenAPI не поддерживает способов объявления *п ### Конвертер пути { #path-convertor } -Благодаря одной из опций Starlette, можете объявить *параметр пути*, содержащий *путь*, используя URL вроде: +Благодаря одной из опций Starlette, можете объявить *path-параметр*, содержащий *путь*, используя URL вроде: ``` /files/{file_path:path} diff --git a/docs/ru/docs/tutorial/query-params-str-validations.md b/docs/ru/docs/tutorial/query-params-str-validations.md index 5783b0c..d81c89d 100644 --- a/docs/ru/docs/tutorial/query-params-str-validations.md +++ b/docs/ru/docs/tutorial/query-params-str-validations.md @@ -369,11 +369,11 @@ http://127.0.0.1:8000/items/?item-query=foobaritems В таких случаях можно использовать **кастомную функцию-валидатор**, которая применяется после обычной валидации (например, после проверки, что значение — это `str`). -Этого можно добиться, используя [Pydantic `AfterValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator) внутри `Annotated`. +Этого можно добиться, используя [Pydantic `AfterValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-after-validator) внутри `Annotated`. /// tip | Совет -В Pydantic также есть [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator) и другие. 🤓 +В Pydantic также есть [`BeforeValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-before-validator) и другие. 🤓 /// diff --git a/docs/ru/docs/tutorial/request-files.md b/docs/ru/docs/tutorial/request-files.md index 6d40aaa..26790a1 100644 --- a/docs/ru/docs/tutorial/request-files.md +++ b/docs/ru/docs/tutorial/request-files.md @@ -6,10 +6,10 @@ Чтобы получать загруженные файлы, сначала установите [`python-multipart`](https://github.com/Kludex/python-multipart). -Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его, а затем установили пакет, например: +Добавьте его в свой проект: ```console -$ pip install python-multipart +$ uv add python-multipart ``` Это связано с тем, что загружаемые файлы передаются как "данные формы". @@ -42,7 +42,7 @@ $ pip install python-multipart /// -Файлы будут загружены как данные формы. +Файлы будут загружены как "данные формы". Если вы объявите тип параметра у *функции-обработчика пути* как `bytes`, то **FastAPI** прочитает файл за вас, и вы получите его содержимое в виде `bytes`. @@ -149,13 +149,13 @@ contents = myfile.file.read() Можно одновременно загружать несколько файлов. -Они будут связаны с одним и тем же "полем формы", отправляемым с помощью данных формы. +Они будут связаны с одним и тем же "полем формы", отправляемым с помощью "данных формы". Для этого необходимо объявить список `bytes` или `UploadFile`: {* ../../docs_src/request_files/tutorial002_an_py310.py hl[10,15] *} -Вы получите, как и было объявлено, список `list` из `bytes` или `UploadFile`. +Вы получите, как и было объявлено, список `list` из `bytes` или объектов `UploadFile`. /// note | Технические детали diff --git a/docs/ru/docs/tutorial/request-form-models.md b/docs/ru/docs/tutorial/request-form-models.md index 3852e3a..70e8c59 100644 --- a/docs/ru/docs/tutorial/request-form-models.md +++ b/docs/ru/docs/tutorial/request-form-models.md @@ -6,10 +6,10 @@ Чтобы использовать формы, сначала установите [`python-multipart`](https://github.com/Kludex/python-multipart). -Убедитесь, что вы создали и активировали [виртуальное окружение](../virtual-environments.md), а затем установите пакет, например: +Добавьте его в ваш проект: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// @@ -50,7 +50,7 @@ $ pip install python-multipart {* ../../docs_src/request_form_models/tutorial002_an_py310.py hl[12] *} -Если клиент попробует отправить дополнительные данные, то в ответ он получит **ошибку**. +Если клиент попробует отправить дополнительные данные, то в ответ он получит ответ с **ошибкой**. Например, если клиент попытается отправить поля формы: @@ -58,7 +58,7 @@ $ pip install python-multipart * `password`: `Portal Gun` * `extra`: `Mr. Poopybutthole` -То в ответ он получит **ошибку**, сообщающую ему, что поле `extra` не разрешено: +Он получит ответ с ошибкой, сообщающий ему, что поле `extra` не разрешено: ```json { diff --git a/docs/ru/docs/tutorial/request-forms-and-files.md b/docs/ru/docs/tutorial/request-forms-and-files.md index 347818a..ba5bc98 100644 --- a/docs/ru/docs/tutorial/request-forms-and-files.md +++ b/docs/ru/docs/tutorial/request-forms-and-files.md @@ -6,10 +6,10 @@ Чтобы получать загруженные файлы и/или данные форм, сначала установите [`python-multipart`](https://github.com/Kludex/python-multipart). -Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его, а затем установили пакет, например: +Добавьте его в ваш проект: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// @@ -30,7 +30,7 @@ $ pip install python-multipart /// warning | Внимание -Вы можете объявить несколько параметров `File` и `Form` в операции пути, но вы не можете также объявить поля `Body`, которые вы ожидаете получить в виде JSON, так как запрос будет иметь тело, закодированное с помощью `multipart/form-data` вместо `application/json`. +Вы можете объявить несколько параметров `File` и `Form` в *операции пути*, но вы не можете также объявить поля `Body`, которые вы ожидаете получить в виде JSON, так как запрос будет иметь тело, закодированное с помощью `multipart/form-data` вместо `application/json`. Это не ограничение **FastAPI**, это часть протокола HTTP. diff --git a/docs/ru/docs/tutorial/request-forms.md b/docs/ru/docs/tutorial/request-forms.md index 2067195..046e1e1 100644 --- a/docs/ru/docs/tutorial/request-forms.md +++ b/docs/ru/docs/tutorial/request-forms.md @@ -1,16 +1,15 @@ # Данные формы { #form-data } - Когда вам нужно получить поля формы вместо JSON, вы можете использовать `Form`. /// note | Примечание Чтобы использовать формы, сначала установите [`python-multipart`](https://github.com/Kludex/python-multipart). -Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его, а затем установили пакет, например: +Добавьте его в свой проект: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// @@ -41,7 +40,7 @@ $ pip install python-multipart /// tip | Подсказка -Чтобы объявлять данные формы, вам нужно явно использовать `Form`, иначе параметры будут интерпретированы как параметры запроса или параметры тела (JSON). +Чтобы объявлять тела формы, вам нужно явно использовать `Form`, иначе параметры будут интерпретированы как параметры запроса или параметры тела (JSON). /// diff --git a/docs/ru/docs/tutorial/response-model.md b/docs/ru/docs/tutorial/response-model.md index bf0a6fc..30baa94 100644 --- a/docs/ru/docs/tutorial/response-model.md +++ b/docs/ru/docs/tutorial/response-model.md @@ -76,16 +76,16 @@ FastAPI будет использовать этот `response_model` для д Чтобы использовать `EmailStr`, сначала установите [`email-validator`](https://github.com/JoshData/python-email-validator). -Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его, а затем установили пакет, например: +Добавьте его в свой проект: ```console -$ pip install email-validator +$ uv add email-validator ``` или так: ```console -$ pip install "pydantic[email]" +$ uv add "pydantic[email]" ``` /// @@ -178,7 +178,7 @@ FastAPI делает несколько вещей внутри вместе с ## Другие аннотации возвращаемых типов { #other-return-type-annotations } -Бывают случаи, когда вы возвращаете что-то, что не является валидным полем Pydantic, и аннотируете это в функции только ради поддержки инструментов (редактор коды, mypy и т.д.). +Бывают случаи, когда вы возвращаете что-то, что не является валидным полем Pydantic, и аннотируете это в функции только ради поддержки инструментов (редактор кода, mypy и т.д.). ### Возврат Response напрямую { #return-a-response-directly } @@ -202,7 +202,7 @@ FastAPI делает несколько вещей внутри вместе с Но когда вы возвращаете произвольный объект, не являющийся валидным типом Pydantic (например, объект базы данных), и аннотируете его таким образом в функции, FastAPI попытается создать модель ответа Pydantic из этой аннотации типа и потерпит неудачу. -То же произойдёт, если у вас будет что-то вроде объединение разных типов, где один или несколько не являются валидными типами Pydantic, например, это приведёт к ошибке 💥: +То же произойдёт, если у вас будет что-то вроде объединения разных типов, где один или несколько не являются валидными типами Pydantic, например, это приведёт к ошибке 💥: {* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *} @@ -258,7 +258,7 @@ FastAPI делает несколько вещей внутри вместе с * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -как описано в [документации Pydantic](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict) для `exclude_defaults` и `exclude_none`. +как описано в [документации Pydantic](https://pydantic.dev/docs/validation/latest/concepts/serialization/#excluding-and-including-fields-based-on-their-value) для `exclude_defaults` и `exclude_none`. /// diff --git a/docs/ru/docs/tutorial/schema-extra-example.md b/docs/ru/docs/tutorial/schema-extra-example.md index 917e808..2906f36 100644 --- a/docs/ru/docs/tutorial/schema-extra-example.md +++ b/docs/ru/docs/tutorial/schema-extra-example.md @@ -12,7 +12,7 @@ Эта дополнительная информация будет добавлена как есть в выходную **JSON Schema** этой модели и будет использоваться в документации API. -Вы можете использовать атрибут `model_config`, который принимает `dict`, как описано в [документации Pydantic: Конфигурация](https://docs.pydantic.dev/latest/api/config/). +Вы можете использовать атрибут `model_config`, который принимает `dict`, как описано в [документации Pydantic: Конфигурация](https://pydantic.dev/docs/validation/latest/api/pydantic/config/). Вы можете задать `"json_schema_extra"` с `dict`, содержащим любые дополнительные данные, которые вы хотите видеть в сгенерированной JSON Schema, включая `examples`. diff --git a/docs/ru/docs/tutorial/security/first-steps.md b/docs/ru/docs/tutorial/security/first-steps.md index 35d63c8..f999779 100644 --- a/docs/ru/docs/tutorial/security/first-steps.md +++ b/docs/ru/docs/tutorial/security/first-steps.md @@ -26,14 +26,14 @@ /// note | Примечание -Пакет [`python-multipart`](https://github.com/Kludex/python-multipart) автоматически устанавливается вместе с **FastAPI**, если вы запускаете команду `pip install "fastapi[standard]"`. +Пакет [`python-multipart`](https://github.com/Kludex/python-multipart) автоматически устанавливается вместе с **FastAPI**, когда вы запускаете команду `uv add "fastapi[standard]"`. -Однако, если вы используете команду `pip install fastapi`, пакет `python-multipart` по умолчанию не включается. +Однако, если вы используете команду `uv add fastapi`, пакет `python-multipart` по умолчанию не включается. -Чтобы установить его вручную, убедитесь, что вы создали [виртуальное окружение](../../virtual-environments.md), активировали его и затем установили пакет: +Чтобы установить его вручную, добавьте его в ваш проект с помощью: ```console -$ pip install python-multipart +$ uv add python-multipart ``` Это связано с тем, что **OAuth2** использует «данные формы» для отправки `username` и `password`. @@ -45,7 +45,7 @@ $ pip install python-multipart
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/ru/docs/tutorial/security/oauth2-jwt.md b/docs/ru/docs/tutorial/security/oauth2-jwt.md index 63492e6..ef79031 100644 --- a/docs/ru/docs/tutorial/security/oauth2-jwt.md +++ b/docs/ru/docs/tutorial/security/oauth2-jwt.md @@ -18,7 +18,7 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4 Он не зашифрован, поэтому любой человек может восстановить информацию из его содержимого. -Но он подписан. Следовательно, когда вы получаете токен, который вы эмитировали (выдавали), вы можете убедиться, что это именно вы его эмитировали. +Но он подписан. Следовательно, когда вы получете токен, который вы эмитировали (выдавали), вы можете убедиться, что это именно вы его эмитировали. Таким образом, можно создать токен со сроком действия, скажем, 1 неделя. А когда пользователь вернется на следующий день с тем же токеном, вы будете знать, что он все еще авторизован в вашей системе. @@ -30,12 +30,12 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4 Нам необходимо установить `PyJWT` для генерации и проверки JWT-токенов на языке Python. -Убедитесь, что вы создали [виртуальное окружение](../../virtual-environments.md), активируйте его, а затем установите `pyjwt`: +Добавьте `pyjwt` в свой проект:
```console -$ pip install pyjwt +$ uv add pyjwt ---> 100% ``` @@ -72,12 +72,12 @@ pwdlib — это отличный пакет Python для работы с хэ Рекомендуемый алгоритм — "Argon2". -Убедитесь, что вы создали [виртуальное окружение](../../virtual-environments.md), активируйте его, и затем установите pwdlib вместе с Argon2: +Добавьте `pwdlib` с Argon2 в свой проект:
```console -$ pip install "pwdlib[argon2]" +$ uv add "pwdlib[argon2]" ---> 100% ``` @@ -246,7 +246,7 @@ Password: `secret` ## Продвинутое использование `scopes` { #advanced-usage-with-scopes } -В OAuth2 существует понятие "диапазоны" ("`scopes`"). +В OAuth2 существует понятие "`scopes`" (области). С их помощью можно добавить определенный набор разрешений к JWT-токену. @@ -274,4 +274,4 @@ Password: `secret` При этом вы можете использовать и реализовывать безопасные стандартные протоколы, такие как OAuth2, относительно простым способом. -В **Расширенном руководстве пользователя** вы можете узнать больше о том, как использовать "диапазоны" ("`scopes`") OAuth2 для создания более точно настроенной системы разрешений в соответствии с теми же стандартами. OAuth2 с диапазонами — это механизм, используемый многими крупными провайдерами сервиса аутентификации, такими как Facebook, Google, GitHub, Microsoft, X (Twitter) и др., для авторизации сторонних приложений на взаимодействие с их API от имени их пользователей. +В **Расширенном руководстве пользователя** вы можете узнать больше о том, как использовать OAuth2 "`scopes`" (области) для создания более точно настроенной системы разрешений в соответствии с теми же стандартами. OAuth2 со scopes — это механизм, используемый многими крупными провайдерами сервиса аутентификации, такими как Facebook, Google, GitHub, Microsoft, X (Twitter) и др., для авторизации сторонних приложений на взаимодействие с их API от имени их пользователей. diff --git a/docs/ru/docs/tutorial/sql-databases.md b/docs/ru/docs/tutorial/sql-databases.md index bf2e16f..80cae48 100644 --- a/docs/ru/docs/tutorial/sql-databases.md +++ b/docs/ru/docs/tutorial/sql-databases.md @@ -34,12 +34,12 @@ ## Установка `SQLModel` { #install-sqlmodel } -Сначала убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его и затем установили `sqlmodel`: +Добавьте `sqlmodel` в свой проект:
```console -$ pip install sqlmodel +$ uv add sqlmodel ---> 100% ``` @@ -152,7 +152,7 @@ $ pip install sqlmodel
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -337,7 +337,7 @@ $ fastapi dev
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/ru/docs/tutorial/static-files.md b/docs/ru/docs/tutorial/static-files.md index 84084ff..76f0ebe 100644 --- a/docs/ru/docs/tutorial/static-files.md +++ b/docs/ru/docs/tutorial/static-files.md @@ -1,4 +1,4 @@ -# Статические Файлы { #static-files } +# Статические файлы { #static-files } Вы можете предоставлять статические файлы автоматически из директории, используя `StaticFiles`. @@ -21,11 +21,11 @@ Вы также можете использовать `from starlette.staticfiles import StaticFiles`. -**FastAPI** предоставляет `starlette.staticfiles` под псевдонимом `fastapi.staticfiles`, просто для вашего удобства, как разработчика. Но на самом деле это берётся напрямую из библиотеки Starlette. +**FastAPI** предоставляет `starlette.staticfiles` как `fastapi.staticfiles`, просто для вашего удобства, как разработчика. Но на самом деле это берётся напрямую из библиотеки Starlette. /// -### Что такое "Монтирование" { #what-is-mounting } +### Что такое "монтирование" { #what-is-mounting } "Монтирование" означает добавление полноценного "независимого" приложения на определённый путь, которое затем обрабатывает все подпути. @@ -35,7 +35,7 @@ ## Детали { #details } -Первый параметр `"/static"` относится к подпути, по которому это "подприложение" будет "примонтировано". Таким образом, любой путь начинающийся со `"/static"` будет обработан этим приложением. +Первый параметр `"/static"` относится к подпути, по которому это "подприложение" будет "примонтировано". Таким образом, любой путь, начинающийся со `"/static"`, будет обработан этим приложением. Параметр `directory="static"` относится к имени директории, которая содержит ваши статические файлы. @@ -45,4 +45,4 @@ ## Больше информации { #more-info } -Для получения дополнительной информации о деталях и настройках ознакомьтесь с [документацией Starlette о статических файлах](https://www.starlette.dev/staticfiles/). +Для получения дополнительной информации о деталях и настройках ознакомьтесь с [документацией Starlette о статических файлах](https://starlette.dev/staticfiles/). diff --git a/docs/ru/docs/tutorial/testing.md b/docs/ru/docs/tutorial/testing.md index d6038a3..699b249 100644 --- a/docs/ru/docs/tutorial/testing.md +++ b/docs/ru/docs/tutorial/testing.md @@ -1,21 +1,21 @@ # Тестирование { #testing } -Благодаря [Starlette](https://www.starlette.dev/testclient/), тестировать приложения **FastAPI** легко и приятно. +Благодаря [Starlette](https://starlette.dev/testclient/), тестировать приложения **FastAPI** легко и приятно. Тестирование основано на библиотеке [HTTPX](https://www.python-httpx.org), которая в свою очередь основана на библиотеке Requests, так что все действия знакомы и интуитивно понятны. Используя эти инструменты, Вы можете напрямую задействовать [pytest](https://docs.pytest.org/) с **FastAPI**. -## Использование класса `TestClient` { #using-testclient } +## Использование `TestClient` { #using-testclient } /// note | Примечание -Для использования класса `TestClient` сначала установите [`httpx`](https://www.python-httpx.org). +Для использования `TestClient` сначала установите [`httpx`](https://www.python-httpx.org). -Убедитесь, что Вы создали [виртуальное окружение](../virtual-environments.md), активировали его, а затем установили пакет, например: +Добавьте его в Ваш проект: ```console -$ pip install httpx +$ uv add httpx ``` /// @@ -52,7 +52,7 @@ $ pip install httpx /// tip | Подсказка -Если для тестирования Вам, помимо запросов к приложению FastAPI, необходимо вызывать асинхронные функции (например, для подключения к базе данных с помощью асинхронного драйвера), то ознакомьтесь со страницей [Асинхронное тестирование](../advanced/async-tests.md) в расширенном руководстве. +Если для тестирования Вам, помимо отправки запросов к приложению FastAPI, необходимо вызывать асинхронные функции (например, асинхронные функции базы данных), то ознакомьтесь со страницей [Асинхронное тестирование](../advanced/async-tests.md) в расширенном руководстве. /// @@ -137,7 +137,7 @@ $ pip install httpx Например: * Чтобы передать *path*-параметр или *query*-параметр, добавьте его непосредственно в URL. -* Передаёте JSON в теле запроса, передав Python-объект (например: `dict`) через именованный параметр `json`. +* Чтобы передать тело запроса JSON, передайте Python-объект (например: `dict`) через именованный параметр `json`. * Если же Вам необходимо отправить *данные формы* вместо JSON, то используйте параметр `data` вместо `json`. * Для передачи *HTTP-заголовков*, передайте объект `dict` через параметр `headers`. * Для передачи *cookies* также передайте `dict`, но через параметр `cookies`. @@ -148,7 +148,7 @@ $ pip install httpx Обратите внимание, что `TestClient` принимает данные, которые можно конвертировать в JSON, но не модели Pydantic. -Если в Ваших тестах есть модели Pydantic и Вы хотите отправить их в тестируемое приложение, то можете использовать функцию `jsonable_encoder`, описанную на странице [Кодировщик совместимый с JSON](encoder.md). +Если в Ваших тестах есть модель Pydantic и Вы хотите отправить её данные в приложение во время тестирования, то можете использовать функцию `jsonable_encoder`, описанную на странице [Кодировщик совместимый с JSON](encoder.md). /// @@ -156,12 +156,12 @@ $ pip install httpx Далее Вам нужно установить `pytest`. -Убедитесь, что Вы создали [виртуальное окружение](../virtual-environments.md), активировали его, а затем установили пакет, например: +Добавьте его в Ваш проект:
```console -$ pip install pytest +$ uv add pytest ---> 100% ``` @@ -170,12 +170,12 @@ $ pip install pytest Он автоматически найдёт все файлы и тесты, выполнит их и предоставит Вам отчёт о результатах тестирования. -Запустите тесты: +Запустите тесты с помощью:
```console -$ pytest +$ uv run pytest ================ test session starts ================ platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1 diff --git a/docs/ru/docs/virtual-environments.md b/docs/ru/docs/virtual-environments.md index b7c7508..171d196 100644 --- a/docs/ru/docs/virtual-environments.md +++ b/docs/ru/docs/virtual-environments.md @@ -1,864 +1,35 @@ # Виртуальные окружения { #virtual-environments } -При работе с проектами на Python рекомендуется использовать **виртуальное окружение** (или похожий механизм), чтобы изолировать пакеты, которые вы устанавливаете для каждого проекта. +При работе с проектами на Python рекомендуется использовать **виртуальное окружение**, чтобы изолировать пакеты, установленные для каждого проекта. -/// note | Примечание - -Если вы уже знакомы с виртуальными окружениями, знаете, как их создавать и использовать, вы можете пропустить этот раздел. 🤓 - -/// - -/// tip | Подсказка - -**Виртуальное окружение** — это не то же самое, что **переменная окружения**. - -**Переменная окружения** — это переменная в системе, которую могут использовать программы. - -**Виртуальное окружение** — это директория с файлами внутри. - -/// - -/// note | Примечание - -На этой странице вы узнаете, как пользоваться **виртуальными окружениями** и как они работают. - -Если вы готовы начать использовать **инструмент, который управляет всем** за вас (включая установку Python), попробуйте [uv](https://github.com/astral-sh/uv). - -/// +Для проектов FastAPI я рекомендую использовать [uv](https://docs.astral.sh/uv/) для управления проектом, его зависимостями и виртуальным окружением. ## Создание проекта { #create-a-project } -Сначала создайте директорию для вашего проекта. - -Обычно я создаю папку с именем `code` в моем домашнем каталоге. - -А внутри неё создаю отдельную директорию для каждого проекта. +Установите `uv`, используя [официальное руководство по установке](https://docs.astral.sh/uv/getting-started/installation/), а затем создайте проект:
```console -// Перейдите в домашний каталог -$ cd -// Создайте директорию для всех ваших проектов с кодом -$ mkdir code -// Перейдите в эту директорию code -$ cd code -// Создайте директорию для этого проекта -$ mkdir awesome-project -// Перейдите в директорию проекта +$ uv init awesome-project --bare $ cd awesome-project +$ uv add "fastapi[standard]" ```
-## Создание виртуального окружения { #create-a-virtual-environment } +`uv` автоматически создаёт виртуальное окружение для проекта. Вам не нужно создавать или активировать его самостоятельно. -Когда вы начинаете работать над Python‑проектом **впервые**, создайте виртуальное окружение **внутри вашего проекта**. - -/// tip | Подсказка - -Делать это нужно **один раз на проект**, не каждый раз, когда вы работаете. - -/// - -//// tab | `venv` - -Для создания виртуального окружения вы можете использовать модуль `venv`, который поставляется вместе с Python. +Запускайте команды внутри окружения проекта с помощью `uv run`, например:
```console -$ python -m venv .venv +$ uv run fastapi dev ```
-/// details | Что делает эта команда? +## Узнать больше { #learn-more } -* `python`: использовать программу под названием `python` -* `-m`: вызвать модуль как скрипт, далее мы укажем, какой модуль вызвать -* `venv`: использовать модуль `venv`, который обычно устанавливается вместе с Python -* `.venv`: создать виртуальное окружение в новой директории `.venv` - -/// - -//// - -//// tab | `uv` - -Если у вас установлен [`uv`](https://github.com/astral-sh/uv), вы можете использовать его для создания виртуального окружения. - -
- -```console -$ uv venv -``` - -
- -/// tip | Подсказка - -По умолчанию `uv` создаст виртуальное окружение в директории с именем `.venv`. - -Но вы можете переопределить это, передав дополнительный аргумент с именем директории. - -/// - -//// - -Эта команда создаст новое виртуальное окружение в директории `.venv`. - -/// details | `.venv` или другое имя? - -Вы можете создать виртуальное окружение в другой директории, но по соглашению его называют `.venv`. - -/// - -## Активация виртуального окружения { #activate-the-virtual-environment } - -Активируйте новое виртуальное окружение, чтобы все команды Python и устанавливаемые пакеты использовали именно его. - -/// tip | Подсказка - -Делайте это **каждый раз**, когда вы начинаете **новую сессию терминала** для работы над проектом. - -/// - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Или если вы используете Bash для Windows (например, [Git Bash](https://gitforwindows.org/)): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -/// tip | Подсказка - -Каждый раз, когда вы устанавливаете **новый пакет** в это окружение, **активируйте** окружение снова. - -Это гарантирует, что если вы используете **программу терминала (CLI)**, установленную этим пакетом, вы будете использовать именно ту, что из вашего виртуального окружения, а не какую‑то глобально установленную, возможно другой версии, чем вам нужна. - -/// - -## Проверка, что виртуальное окружение активно { #check-the-virtual-environment-is-active } - -Проверьте, что виртуальное окружение активно (предыдущая команда сработала). - -/// tip | Подсказка - -Это **необязательно**, но это хороший способ **проверить**, что всё работает как ожидается и вы используете запланированное виртуальное окружение. - -/// - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -Если отображается исполняемый файл `python` по пути `.venv/bin/python` внутри вашего проекта (в нашем случае `awesome-project`), значит всё сработало. 🎉 - -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -Если отображается исполняемый файл `python` по пути `.venv\Scripts\python` внутри вашего проекта (в нашем случае `awesome-project`), значит всё сработало. 🎉 - -//// - -## Обновление `pip` { #upgrade-pip } - -/// tip | Подсказка - -Если вы используете [`uv`](https://github.com/astral-sh/uv), то для установки вы будете использовать его вместо `pip`, поэтому обновлять `pip` не нужно. 😎 - -/// - -Если для установки пакетов вы используете `pip` (он идёт по умолчанию вместе с Python), вам стоит **обновить** его до последней версии. - -Многие экзотические ошибки при установке пакетов решаются простым предварительным обновлением `pip`. - -/// tip | Подсказка - -Обычно это делается **один раз**, сразу после создания виртуального окружения. - -/// - -Убедитесь, что виртуальное окружение активно (см. команду выше) и запустите: - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip | Подсказка - -Иногда при попытке обновить pip вы можете получить ошибку **`No module named pip`**. - -Если это произошло, установите и обновите pip с помощью команды ниже: - -
- -```console -$ python -m ensurepip --upgrade - ----> 100% -``` - -
- -Эта команда установит pip, если он ещё не установлен, а также гарантирует, что установленная версия pip будет не старее, чем версия, доступная в `ensurepip`. - -/// - -## Добавление `.gitignore` { #add-gitignore } - -Если вы используете **Git** (а вам стоит его использовать), добавьте файл `.gitignore`, чтобы исключить из Git всё, что находится в вашей `.venv`. - -/// tip | Подсказка - -Если вы использовали [`uv`](https://github.com/astral-sh/uv) для создания виртуального окружения, он уже сделал это за вас — можно пропустить этот шаг. 😎 - -/// - -/// tip | Подсказка - -Сделайте это **один раз**, сразу после создания виртуального окружения. - -/// - -
- -```console -$ echo "*" > .venv/.gitignore -``` - -
- -/// details | Что делает эта команда? - -* `echo "*"`: «напечатать» в терминале текст `*` (следующая часть немного меняет поведение) -* `>`: всё, что команда слева от `>` выводит в терминал, вместо печати нужно записать в файл, указанный справа от `>` -* `.gitignore`: имя файла, в который нужно записать текст - -А `*` в Git означает «всё». То есть будет игнорироваться всё в директории `.venv`. - -Эта команда создаст файл `.gitignore` со следующим содержимым: - -```gitignore -* -``` - -/// - -## Установка пакетов { #install-packages } - -После активации окружения вы можете устанавливать в него пакеты. - -/// tip | Подсказка - -Сделайте это **один раз** при установке или обновлении пакетов, необходимых вашему проекту. - -Если вам нужно обновить версию или добавить новый пакет, вы **сделаете это снова**. - -/// - -### Установка пакетов напрямую { #install-packages-directly } - -Если вы торопитесь и не хотите объявлять зависимости проекта в отдельном файле, вы можете установить их напрямую. - -/// tip | Подсказка - -Очень хорошая идея — указать используемые вашим проектом пакеты и их версии в файле (например, `requirements.txt` или `pyproject.toml`). - -/// - -//// tab | `pip` - -
- -```console -$ pip install "fastapi[standard]" - ----> 100% -``` - -
- -//// - -//// tab | `uv` - -Если у вас установлен [`uv`](https://github.com/astral-sh/uv): - -
- -```console -$ uv pip install "fastapi[standard]" ----> 100% -``` - -
- -//// - -### Установка из `requirements.txt` { #install-from-requirements-txt } - -Если у вас есть `requirements.txt`, вы можете использовать его для установки пакетов. - -//// tab | `pip` - -
- -```console -$ pip install -r requirements.txt ----> 100% -``` - -
- -//// - -//// tab | `uv` - -Если у вас установлен [`uv`](https://github.com/astral-sh/uv): - -
- -```console -$ uv pip install -r requirements.txt ----> 100% -``` - -
- -//// - -/// details | `requirements.txt` - -`requirements.txt` с некоторыми пакетами может выглядеть так: - -```requirements.txt -fastapi[standard]==0.113.0 -pydantic==2.8.0 -``` - -/// - -## Запуск вашей программы { #run-your-program } - -После активации виртуального окружения вы можете запустить свою программу, и она будет использовать Python из вашего виртуального окружения вместе с установленными там пакетами. - -
- -```console -$ python main.py - -Hello World -``` - -
- -## Настройка вашего редактора кода { #configure-your-editor } - -Скорее всего, вы будете использовать редактор кода. Убедитесь, что вы настроили его на использование того же виртуального окружения, которое вы создали (обычно он определяет его автоматически), чтобы получить автозавершение и подсветку ошибок. - -Например: - -* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) -* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) - -/// tip | Подсказка - -Обычно это нужно сделать только **один раз**, при создании виртуального окружения. - -/// - -## Деактивация виртуального окружения { #deactivate-the-virtual-environment } - -Когда закончите работу над проектом, вы можете **деактивировать** виртуальное окружение. - -
- -```console -$ deactivate -``` - -
- -Таким образом, при запуске `python` он не будет пытаться запускаться из этого виртуального окружения с установленными там пакетами. - -## Готово к работе { #ready-to-work } - -Теперь вы готовы начать работать над своим проектом. - - - -/// tip | Подсказка - -Хотите понять, что это всё было выше? - -Продолжайте читать. 👇🤓 - -/// - -## Зачем нужны виртуальные окружения { #why-virtual-environments } - -Чтобы работать с FastAPI, вам нужно установить [Python](https://www.python.org/). - -После этого вам нужно будет **установить** FastAPI и другие **пакеты**, которые вы хотите использовать. - -Для установки пакетов обычно используют команду `pip`, которая идет вместе с Python (или альтернативные инструменты). - -Тем не менее, если просто использовать `pip` напрямую, пакеты будут установлены в **глобальное окружение Python** (глобально установленный Python). - -### Проблема { #the-problem } - -Так в чём проблема установки пакетов в глобальное окружение Python? - -Со временем вы, вероятно, будете писать много разных программ, зависящих от **разных пакетов**. И некоторые из ваших проектов будут зависеть от **разных версий** одного и того же пакета. 😱 - -Например, вы можете создать проект `philosophers-stone`, который зависит от пакета **`harry` версии `1`**. Значит, нужно установить `harry`. - -```mermaid -flowchart LR - stone(philosophers-stone) -->|requires| harry-1[harry v1] -``` - -Затем вы создаёте другой проект `prisoner-of-azkaban`, который тоже зависит от `harry`, но ему нужен **`harry` версии `3`**. - -```mermaid -flowchart LR - azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3] -``` - -Проблема в том, что если устанавливать пакеты глобально (в глобальное окружение), а не в локальное **виртуальное окружение**, вам придётся выбирать, какую версию `harry` установить. - -Если вы хотите запустить `philosophers-stone`, сначала нужно установить `harry` версии `1`, например так: - -
- -```console -$ pip install "harry==1" -``` - -
- -Тогда у вас в глобальном окружении Python будет установлен `harry` версии `1`: - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -->|requires| harry-1 - end -``` - -Но если затем вы захотите запустить `prisoner-of-azkaban`, вам нужно будет удалить `harry` версии `1` и установить `harry` версии `3` (или просто установка версии `3` автоматически удалит версию `1`). - -
- -```console -$ pip install "harry==3" -``` - -
- -В итоге у вас будет установлен `harry` версии `3` в глобальном окружении Python. - -А если вы снова попробуете запустить `philosophers-stone`, есть шанс, что он **не будет работать**, так как ему нужен `harry` версии `1`. - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - style harry-1 fill:#ccc,stroke-dasharray: 5 5 - harry-3[harry v3] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -.-x|⛔️| harry-1 - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --> |requires| harry-3 - end -``` - -/// tip | Подсказка - -В Python-пакетах часто стараются изо всех сил **избегать ломающих изменений** в **новых версиях**, но лучше действовать осторожно: устанавливать новые версии осознанно и тогда, когда вы можете прогнать тесты и убедиться, что всё работает корректно. - -/// - -Теперь представьте то же самое с **многими** другими **пакетами**, от которых зависят все ваши **проекты**. Этим очень сложно управлять. И вы, скорее всего, в какой‑то момент будете запускать проекты с **несовместимыми версиями** пакетов и не понимать, почему что‑то не работает. - -Кроме того, в зависимости от ОС (например, Linux, Windows, macOS), она может поставляться с уже установленным Python. И тогда, вероятно, в системе уже есть предустановленные пакеты определённых версий, **нужные вашей системе**. Если вы устанавливаете пакеты в глобальное окружение Python, вы можете в итоге **сломать** некоторые системные программы. - -## Куда устанавливаются пакеты { #where-are-packages-installed } - -Когда вы устанавливаете Python, на вашем компьютере создаются некоторые директории с файлами. - -Часть этих директорий отвечает за хранение всех устанавливаемых вами пакетов. - -Когда вы запускаете: - -
- -```console -// Не запускайте это сейчас, это просто пример 🤓 -$ pip install "fastapi[standard]" ----> 100% -``` - -
- -Будет загружен сжатый файл с кодом FastAPI, обычно с [PyPI](https://pypi.org/project/fastapi/). - -Также будут **загружены** файлы для других пакетов, от которых зависит FastAPI. - -Затем все эти файлы будут **распакованы** и помещены в директорию на вашем компьютере. - -По умолчанию они попадут в директорию из вашей установки Python — это **глобальное окружение**. - -## Что такое виртуальные окружения { #what-are-virtual-environments } - -Решение проблемы с пакетами в глобальном окружении — использовать **виртуальное окружение для каждого проекта**, над которым вы работаете. - -Виртуальное окружение — это **директория**, очень похожая на глобальную, куда вы можете устанавливать пакеты для конкретного проекта. - -Таким образом, у каждого проекта будет своё виртуальное окружение (директория `.venv`) со своими пакетами. - -```mermaid -flowchart TB - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) --->|requires| harry-1 - subgraph venv1[.venv] - harry-1[harry v1] - end - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --->|requires| harry-3 - subgraph venv2[.venv] - harry-3[harry v3] - end - end - stone-project ~~~ azkaban-project -``` - -## Что означает активация виртуального окружения { #what-does-activating-a-virtual-environment-mean } - -Когда вы активируете виртуальное окружение, например так: - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Или если вы используете Bash для Windows (например, [Git Bash](https://gitforwindows.org/)): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -Эта команда создаст или изменит некоторые [переменные окружения](environment-variables.md), которые будут доступны для следующих команд. - -Одна из таких переменных — `PATH`. - -/// tip | Подсказка - -Вы можете узнать больше о переменной окружения `PATH` в разделе [Переменные окружения](environment-variables.md#path-environment-variable). - -/// - -Активация виртуального окружения добавляет его путь `.venv/bin` (на Linux и macOS) или `.venv\Scripts` (на Windows) в переменную окружения `PATH`. - -Предположим, что до активации окружения переменная `PATH` выглядела так: - -//// tab | Linux, macOS - -```plaintext -/usr/bin:/bin:/usr/sbin:/sbin -``` - -Это означает, что система будет искать программы в: - -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Windows\System32 -``` - -Это означает, что система будет искать программы в: - -* `C:\Windows\System32` - -//// - -После активации виртуального окружения переменная `PATH` будет выглядеть примерно так: - -//// tab | Linux, macOS - -```plaintext -/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -Это означает, что теперь система в первую очередь будет искать программы в: - -```plaintext -/home/user/code/awesome-project/.venv/bin -``` - -прежде чем искать в других директориях. - -Поэтому, когда вы введёте в терминале `python`, система найдёт программу Python по пути - -```plaintext -/home/user/code/awesome-project/.venv/bin/python -``` - -и использует именно её. - -//// - -//// tab | Windows - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32 -``` - -Это означает, что теперь система в первую очередь будет искать программы в: - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts -``` - -прежде чем искать в других директориях. - -Поэтому, когда вы введёте в терминале `python`, система найдёт программу Python по пути - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -и использует именно её. - -//// - -Важная деталь: путь к виртуальному окружению будет добавлен в самое **начало** переменной `PATH`. Система найдёт его **раньше**, чем любой другой установленный Python. Таким образом, при запуске `python` будет использоваться Python **из виртуального окружения**, а не какой‑то другой `python` (например, из глобального окружения). - -Активация виртуального окружения также меняет ещё несколько вещей, но это — одна из важнейших. - -## Проверка виртуального окружения { #checking-a-virtual-environment } - -Когда вы проверяете, активно ли виртуальное окружение, например, так: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -//// - -Это означает, что будет использоваться программа `python` **из виртуального окружения**. - -На Linux и macOS используется `which`, а в Windows PowerShell — `Get-Command`. - -Как работает эта команда: она проходит по переменной окружения `PATH`, идя **по каждому пути по порядку**, и ищет программу с именем `python`. Как только находит — **показывает путь** к этой программе. - -Самое важное — при вызове `python` именно этот «`python`» и будет выполняться. - -Так вы можете подтвердить, что находитесь в правильном виртуальном окружении. - -/// tip | Подсказка - -Легко активировать одно виртуальное окружение, получить один Python, а затем **перейти к другому проекту**. - -И второй проект **не будет работать**, потому что вы используете **не тот Python**, из виртуального окружения другого проекта. - -Полезно уметь проверить, какой именно `python` используется. 🤓 - -/// - -## Зачем деактивировать виртуальное окружение { #why-deactivate-a-virtual-environment } - -Например, вы работаете над проектом `philosophers-stone`, **активируете виртуальное окружение**, устанавливаете пакеты и работаете с ним. - -Затем вы хотите поработать над **другим проектом** `prisoner-of-azkaban`. - -Вы переходите в этот проект: - -
- -```console -$ cd ~/code/prisoner-of-azkaban -``` - -
- -Если вы не деактивируете виртуальное окружение `philosophers-stone`, при запуске `python` в терминале он попытается использовать Python из `philosophers-stone`. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -$ python main.py - -// Ошибка при импорте sirius, он не установлен 😱 -Traceback (most recent call last): - File "main.py", line 1, in - import sirius -``` - -
- -Но если вы деактивируете виртуальное окружение и активируете новое для `prisoner-of-azkaban`, тогда при запуске `python` он будет использовать Python из виртуального окружения `prisoner-of-azkaban`. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -// Вам не нужно находиться в старой директории, чтобы деактивировать окружение, вы можете сделать это где угодно, даже после перехода в другой проект 😎 -$ deactivate - -// Активируйте виртуальное окружение в prisoner-of-azkaban/.venv 🚀 -$ source .venv/bin/activate - -// Теперь при запуске python он найдёт пакет sirius, установленный в этом виртуальном окружении ✨ -$ python main.py - -I solemnly swear 🐺 -``` - -
- -## Альтернативы { #alternatives } - -Это простое руководство, чтобы вы начали и поняли, как всё работает **под капотом**. - -Существует много **альтернатив** для управления виртуальными окружениями, зависимостями (requirements), проектами. - -Когда вы будете готовы и захотите использовать инструмент для **управления всем проектом** — зависимостями пакетов, виртуальными окружениями и т.п., я бы предложил попробовать [uv](https://github.com/astral-sh/uv). - -`uv` может многое: - -* **Устанавливать Python**, включая разные версии -* Управлять **виртуальным окружением** ваших проектов -* Устанавливать **пакеты** -* Управлять **зависимостями и версиями** пакетов вашего проекта -* Обеспечивать наличие **точного** набора пакетов и версий к установке, включая их зависимости, чтобы вы были уверены, что сможете запускать проект в продакшн точно так же, как и на компьютере при разработке — это называется **locking** -* И многое другое - -## Заключение { #conclusion } - -Если вы прочитали и поняли всё это, теперь **вы знаете гораздо больше** о виртуальных окружениях, чем многие разработчики. 🤓 - -Знание этих деталей, скорее всего, пригодится вам в будущем, когда вы будете отлаживать что‑то сложное: вы будете понимать, **как всё работает под капотом**. 😎 +Прочитайте [руководство по виртуальным окружениям](https://tiangolo.com/guides/virtual-environments/), чтобы узнать, как виртуальные окружения работают под капотом, включая активацию и альтернативный workflow с `python -m venv` и `pip`. diff --git a/docs/tr/docs/advanced/additional-responses.md b/docs/tr/docs/advanced/additional-responses.md index 8bf1ea7..025279e 100644 --- a/docs/tr/docs/advanced/additional-responses.md +++ b/docs/tr/docs/advanced/additional-responses.md @@ -243,5 +243,5 @@ Bu tekniği, *path operation*'larınızda bazı ön tanımlı response'ları yen Response'ların içine tam olarak neleri dahil edebileceğinizi görmek için OpenAPI spesifikasyonundaki şu bölümlere bakabilirsiniz: -* [OpenAPI Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object), `Response Object`'i içerir. -* [OpenAPI Response Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object), buradaki her şeyi `responses` parametreniz içinde, her bir response'un içine doğrudan ekleyebilirsiniz. Buna `description`, `headers`, `content` (bunun içinde farklı media type'lar ve JSON Schema'lar tanımlarsınız) ve `links` dahildir. +* [OpenAPI Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object), `Response Object`'i içerir. +* [OpenAPI Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object), buradaki her şeyi `responses` parametreniz içinde, her bir response'un içine doğrudan ekleyebilirsiniz. Buna `description`, `headers`, `content` (bunun içinde farklı media type'lar ve JSON Schema'lar tanımlarsınız) ve `links` dahildir. diff --git a/docs/tr/docs/advanced/async-tests.md b/docs/tr/docs/advanced/async-tests.md index 99951a8..8633d76 100644 --- a/docs/tr/docs/advanced/async-tests.md +++ b/docs/tr/docs/advanced/async-tests.md @@ -45,7 +45,7 @@ Testlerinizi her zamanki gibi şu şekilde çalıştırabilirsiniz:
```console -$ pytest +$ uv run pytest ---> 100% ``` diff --git a/docs/tr/docs/advanced/behind-a-proxy.md b/docs/tr/docs/advanced/behind-a-proxy.md index ed0730e..c49164e 100644 --- a/docs/tr/docs/advanced/behind-a-proxy.md +++ b/docs/tr/docs/advanced/behind-a-proxy.md @@ -33,7 +33,7 @@ Bunu `--forwarded-allow-ips="*"` olarak ayarlarsanız, gelen tüm IP'lere güven
```console -$ fastapi run --forwarded-allow-ips="*" +$ uv run fastapi run --forwarded-allow-ips="*" INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -170,7 +170,7 @@ Bunu yapmak için `--root-path` komut satırı seçeneğini şöyle kullanabilir
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -200,7 +200,7 @@ Ardından Uvicorn'u şu şekilde başlatırsanız:
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -253,7 +253,7 @@ Böyle bir durumda (stripped path prefix olmadan), proxy `https://myawesomeapp.c [Traefik](https://docs.traefik.io/) kullanarak, stripped path prefix'li deneyi local'de kolayca çalıştırabilirsiniz. -[Traefik'i indirin](https://github.com/containous/traefik/releases); tek bir binary'dir, sıkıştırılmış dosyayı çıkarıp doğrudan terminalden çalıştırabilirsiniz. +[Traefik'i indirin](https://github.com/traefik/traefik/releases); tek bir binary'dir, sıkıştırılmış dosyayı çıkarıp doğrudan terminalden çalıştırabilirsiniz. Ardından `traefik.toml` adında bir dosya oluşturup şunu yazın: @@ -321,7 +321,7 @@ Ve şimdi uygulamanızı `--root-path` seçeneğiyle başlatın:
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/tr/docs/advanced/dataclasses.md b/docs/tr/docs/advanced/dataclasses.md index 9f79a6c..dd8ff8b 100644 --- a/docs/tr/docs/advanced/dataclasses.md +++ b/docs/tr/docs/advanced/dataclasses.md @@ -7,7 +7,7 @@ Ancak FastAPI, [`dataclasses`](https://docs.python.org/3/library/dataclasses.htm {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -Bu destek hâlâ **Pydantic** sayesinde vardır; çünkü Pydantic, [`dataclasses` için dahili destek](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel) sunar. +Bu destek hâlâ **Pydantic** sayesinde vardır; çünkü Pydantic, [`dataclasses` için dahili destek](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/#usage-of-stdlib-dataclasses-with-basemodel) sunar. Yani yukarıdaki kod Pydantic'i doğrudan kullanmasa bile, FastAPI bu standart dataclass'ları Pydantic'in kendi dataclass biçimine dönüştürmek için Pydantic'i kullanmaktadır. @@ -89,7 +89,7 @@ Daha spesifik ayrıntılar için yukarıdaki kod içi annotation ipuçlarına ba `dataclasses`'ı diğer Pydantic model'leriyle de birleştirebilir, onlardan kalıtım alabilir, kendi model'lerinize dahil edebilirsiniz, vb. -Daha fazlası için [Pydantic'in dataclasses dokümantasyonuna](https://docs.pydantic.dev/latest/concepts/dataclasses/) bakın. +Daha fazlası için [Pydantic'in dataclasses dokümantasyonuna](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/) bakın. ## Sürüm { #version } diff --git a/docs/tr/docs/advanced/events.md b/docs/tr/docs/advanced/events.md index 4c96b22..7477065 100644 --- a/docs/tr/docs/advanced/events.md +++ b/docs/tr/docs/advanced/events.md @@ -154,7 +154,7 @@ Altta, ASGI teknik spesifikasyonunda bu, [Lifespan Protokolü](https://asgi.read /// note | Not -Starlette `lifespan` handler’ları hakkında daha fazlasını [Starlette Lifespan dokümanları](https://www.starlette.dev/lifespan/) içinde okuyabilirsiniz. +Starlette `lifespan` handler’ları hakkında daha fazlasını [Starlette Lifespan dokümanları](https://starlette.dev/lifespan/) içinde okuyabilirsiniz. Ayrıca kodunuzun başka bölgelerinde de kullanılabilecek lifespan state’i nasıl yöneteceğinizi de kapsar. diff --git a/docs/tr/docs/advanced/generate-clients.md b/docs/tr/docs/advanced/generate-clients.md index 6e12efe..684b7ff 100644 --- a/docs/tr/docs/advanced/generate-clients.md +++ b/docs/tr/docs/advanced/generate-clients.md @@ -12,7 +12,7 @@ Esnek bir seçenek olan [OpenAPI Generator](https://openapi-generator.tech/), ** **TypeScript client**'lar için [Hey API](https://heyapi.dev/), TypeScript ekosistemi için özel olarak tasarlanmış, optimize bir deneyim sunan bir çözümdür. -Daha fazla SDK üretecini [OpenAPI.Tools](https://openapi.tools/#sdk) üzerinde keşfedebilirsiniz. +Daha fazla SDK üretecini [OpenAPI.Tools](https://openapi.tools/categories/sdk-generators) üzerinde keşfedebilirsiniz. /// tip | İpucu diff --git a/docs/tr/docs/advanced/middleware.md b/docs/tr/docs/advanced/middleware.md index 777ef80..b0035db 100644 --- a/docs/tr/docs/advanced/middleware.md +++ b/docs/tr/docs/advanced/middleware.md @@ -91,7 +91,7 @@ Başka birçok ASGI middleware'i vardır. Örneğin: -* [Uvicorn'un `ProxyHeadersMiddleware`'i](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) +* [Uvicorn'un `ProxyHeadersMiddleware`'i](https://github.com/Kludex/uvicorn/blob/main/uvicorn/middleware/proxy_headers.py) * [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -Diğer mevcut middleware'leri görmek için [Starlette'in Middleware dokümanlarına](https://www.starlette.dev/middleware/) ve [ASGI Awesome List](https://github.com/florimondmanca/awesome-asgi) listesine bakın. +Diğer mevcut middleware'leri görmek için [Starlette'in Middleware dokümanlarına](https://starlette.dev/middleware/) ve [ASGI Awesome List](https://github.com/florimondmanca/awesome-asgi) listesine bakın. diff --git a/docs/tr/docs/advanced/openapi-callbacks.md b/docs/tr/docs/advanced/openapi-callbacks.md index 91ff844..7b7830b 100644 --- a/docs/tr/docs/advanced/openapi-callbacks.md +++ b/docs/tr/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ Bu kısım oldukça standart; kodun çoğu muhtemelen size zaten tanıdık gelec /// tip | İpucu -`callback_url` query parametresi, Pydantic'in [Url](https://docs.pydantic.dev/latest/api/networks/) tipini kullanır. +`callback_url` query parametresi, Pydantic'in [Url](https://pydantic.dev/docs/validation/latest/api/pydantic/networks/) tipini kullanır. /// @@ -106,11 +106,11 @@ Normal bir FastAPI *path operation*'ı gibi görünmelidir: Normal bir *path operation*'dan 2 temel farkı vardır: * Gerçek bir koda ihtiyaç duymaz; çünkü uygulamanız bu kodu asla çağırmayacak. Bu yalnızca *external API*'yi dokümante etmek için kullanılır. Yani fonksiyon sadece `pass` içerebilir. -* *path*, bir [OpenAPI 3 expression](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) (aşağıda daha fazlası) içerebilir; böylece parametreler ve sizin API'nize gönderilen orijinal request'in bazı parçalarıyla değişkenler kullanılabilir. +* *path*, bir [OpenAPI 3 expression](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression) (aşağıda daha fazlası) içerebilir; böylece parametreler ve sizin API'nize gönderilen orijinal request'in bazı parçalarıyla değişkenler kullanılabilir. ### Callback path ifadesi { #the-callback-path-expression } -Callback *path*'i, sizin API'nize gönderilen orijinal request'in bazı parçalarını içerebilen bir [OpenAPI 3 expression](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) barındırabilir. +Callback *path*'i, sizin API'nize gönderilen orijinal request'in bazı parçalarını içerebilen bir [OpenAPI 3 expression](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression) barındırabilir. Bu örnekte, bu bir `str`: diff --git a/docs/tr/docs/advanced/response-cookies.md b/docs/tr/docs/advanced/response-cookies.md index a33d4ef..9ffe86e 100644 --- a/docs/tr/docs/advanced/response-cookies.md +++ b/docs/tr/docs/advanced/response-cookies.md @@ -48,4 +48,4 @@ Ve `Response`, header ve cookie set etmek için sık kullanıldığından, **Fas /// -Mevcut tüm parametreleri ve seçenekleri görmek için [Starlette dokümantasyonu](https://www.starlette.dev/responses/#set-cookie)'na bakın. +Mevcut tüm parametreleri ve seçenekleri görmek için [Starlette dokümantasyonu](https://starlette.dev/responses/#set-cookie)'na bakın. diff --git a/docs/tr/docs/advanced/response-headers.md b/docs/tr/docs/advanced/response-headers.md index c4a6547..2e4aea9 100644 --- a/docs/tr/docs/advanced/response-headers.md +++ b/docs/tr/docs/advanced/response-headers.md @@ -1,6 +1,5 @@ # Response Header'ları { #response-headers } - ## Bir `Response` parametresi kullanın { #use-a-response-parameter } *Path operation function* içinde (cookie'lerde yapabildiğiniz gibi) tipi `Response` olan bir parametre tanımlayabilirsiniz. @@ -39,4 +38,4 @@ Ayrıca `Response` header ve cookie ayarlamak için sık kullanıldığından, * Özel/proprietary header'ların [`X-` prefix'i kullanılarak](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) eklenebileceğini unutmayın. -Ancak tarayıcıdaki bir client'ın görebilmesini istediğiniz özel header'larınız varsa, bunları CORS ayarlarınıza eklemeniz gerekir ([CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md) bölümünde daha fazla bilgi), bunun için [Starlette'in CORS dokümanında](https://www.starlette.dev/middleware/#corsmiddleware) açıklanan `expose_headers` parametresini kullanın. +Ancak tarayıcıdaki bir client'ın görebilmesini istediğiniz özel header'larınız varsa, bunları CORS ayarlarınıza eklemeniz gerekir ([CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md) bölümünde daha fazla bilgi), bunun için [Starlette'in CORS dokümanında](https://starlette.dev/middleware/#corsmiddleware) açıklanan `expose_headers` parametresini kullanın. diff --git a/docs/tr/docs/advanced/settings.md b/docs/tr/docs/advanced/settings.md index 5734387..c09dd33 100644 --- a/docs/tr/docs/advanced/settings.md +++ b/docs/tr/docs/advanced/settings.md @@ -1,15 +1,18 @@ # Ayarlar ve Ortam Değişkenleri { #settings-and-environment-variables } - Birçok durumda uygulamanızın bazı harici ayarlara veya konfigürasyonlara ihtiyacı olabilir; örneğin secret key'ler, veritabanı kimlik bilgileri, e-posta servisleri için kimlik bilgileri vb. Bu ayarların çoğu değişkendir (değişebilir); örneğin veritabanı URL'leri. Ayrıca birçoğu hassas olabilir; örneğin secret'lar. Bu nedenle bunları, uygulama tarafından okunan environment variable'lar ile sağlamak yaygındır. +Bir **environment variable** (**env var** olarak da bilinir), Python kodunun dışında, işletim sisteminde yaşayan ve uygulamanız ile diğer programlar tarafından okunabilen bir değerdir. + +Bir komutu çalıştırırken o komut için bir environment variable oluşturabilirsiniz. Platforma özel komutları aşağıda göreceksiniz. + /// tip | İpucu -Environment variable'ları anlamak için [Ortam Değişkenleri](../environment-variables.md) dokümanını okuyabilirsiniz. +Environment variable'ların nasıl çalıştığına dair ayrıntılı bir açıklama için [Environment Variables rehberini](https://tiangolo.com/guides/environment-variables/) okuyabilirsiniz. /// @@ -21,16 +24,16 @@ Bu da, Python içinde bir environment variable'dan okunan herhangi bir değerin ## Pydantic `Settings` { #pydantic-settings } -Neyse ki Pydantic, environment variable'lardan gelen bu ayarları yönetmek için [Pydantic: Settings yönetimi](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) ile çok iyi bir yardımcı araç sunar. +Neyse ki Pydantic, environment variable'lardan gelen bu ayarları yönetmek için [Pydantic: Settings yönetimi](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) ile çok iyi bir yardımcı araç sunar. ### `pydantic-settings`'i kurun { #install-pydantic-settings } -Önce, [Sanal ortam](../virtual-environments.md) oluşturduğunuzdan, aktive ettiğinizden emin olun ve ardından `pydantic-settings` paketini kurun: +`pydantic-settings` paketini projenize ekleyin:
```console -$ pip install pydantic-settings +$ uv add pydantic-settings ---> 100% ``` @@ -41,7 +44,7 @@ Ayrıca `all` extras'ını şu şekilde kurduğunuzda da dahil gelir:
```console -$ pip install "fastapi[all]" +$ uv add "fastapi[all]" ---> 100% ``` @@ -77,19 +80,39 @@ Daha sonra uygulamanızda yeni `settings` nesnesini kullanabilirsiniz: Sonraki adımda server'ı çalıştırırken konfigürasyonları environment variable olarak geçersiniz; örneğin `ADMIN_EMAIL` ve `APP_NAME` şu şekilde ayarlanabilir: +//// tab | Linux, macOS, Windows Bash +
```console -$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py +$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uv run fastapi run main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
+//// + +//// tab | Windows PowerShell + +
+ +```console +$ $Env:ADMIN_EMAIL = "deadpool@example.com" +$ $Env:APP_NAME = "ChimichangApp" +$ uv run fastapi run main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +//// + /// tip | İpucu -Tek bir komut için birden fazla env var ayarlamak istiyorsanız aralarına boşluk koyun ve hepsini komuttan önce yazın. +Bash'te, tek bir komut için birden fazla env var ayarlamak istiyorsanız aralarına boşluk koyun ve hepsini komuttan önce yazın. /// @@ -173,11 +196,11 @@ Ancak dotenv dosyasının mutlaka bu dosya adına sahip olması gerekmez. /// -Pydantic, harici bir kütüphane kullanarak bu tür dosyalardan okuma desteğine sahiptir. Daha fazlası için: [Pydantic Settings: Dotenv (.env) desteği](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support). +Pydantic, harici bir kütüphane kullanarak bu tür dosyalardan okuma desteğine sahiptir. Daha fazlası için: [Pydantic Settings: Dotenv (.env) desteği](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#dotenv-env-support). /// tip | İpucu -Bunun çalışması için `pip install python-dotenv` yapmanız gerekir. +Bunun çalışması için `uv add python-dotenv` ile `python-dotenv` paketini projenize ekleyin. /// @@ -198,7 +221,7 @@ Ardından `config.py` dosyanızı şöyle güncelleyin: /// tip | İpucu -`model_config` attribute'u yalnızca Pydantic konfigürasyonu içindir. Daha fazlası için [Pydantic: Kavramlar: Konfigürasyon](https://docs.pydantic.dev/latest/concepts/config/). +`model_config` attribute'u yalnızca Pydantic konfigürasyonu içindir. Daha fazlası için [Pydantic: Kavramlar: Konfigürasyon](https://pydantic.dev/docs/validation/latest/concepts/config/). /// diff --git a/docs/tr/docs/advanced/sub-applications.md b/docs/tr/docs/advanced/sub-applications.md index 8586484..cd3da41 100644 --- a/docs/tr/docs/advanced/sub-applications.md +++ b/docs/tr/docs/advanced/sub-applications.md @@ -35,7 +35,7 @@ Bu örnekte `/subapi` path’ine mount edilecektir:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/tr/docs/advanced/templates.md b/docs/tr/docs/advanced/templates.md index 443a527..f37eadf 100644 --- a/docs/tr/docs/advanced/templates.md +++ b/docs/tr/docs/advanced/templates.md @@ -8,12 +8,12 @@ Bunu kolayca yapılandırmak için, doğrudan **FastAPI** uygulamanızda kullana ## Bağımlılıkları Yükleme { #install-dependencies } -Bir [sanal ortam](../virtual-environments.md) oluşturduğunuzdan, etkinleştirdiğinizden ve `jinja2`'yi yüklediğinizden emin olun: +Projenize `jinja2` ekleyin:
```console -$ pip install jinja2 +$ uv add jinja2 ---> 100% ``` @@ -123,4 +123,4 @@ Ve `StaticFiles` kullandığınız için, bu CSS dosyası **FastAPI** uygulaman ## Daha fazla detay { #more-details } -Template'leri nasıl test edeceğiniz dahil daha fazla detay için [Starlette'in template dokümantasyonuna](https://www.starlette.dev/templates/) bakın. +Template'leri nasıl test edeceğiniz dahil daha fazla detay için [Starlette'in template dokümantasyonuna](https://starlette.dev/templates/) bakın. diff --git a/docs/tr/docs/advanced/testing-events.md b/docs/tr/docs/advanced/testing-events.md index 58c3e9e..9c2e5b5 100644 --- a/docs/tr/docs/advanced/testing-events.md +++ b/docs/tr/docs/advanced/testing-events.md @@ -5,7 +5,7 @@ Test'lerinizde `lifespan`'ın çalışması gerektiğinde, `TestClient`'ı bir ` {* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *} -Bu konuda daha fazla ayrıntıyı resmi Starlette dokümantasyon sitesindeki ["Testlerde lifespan'ı çalıştırma"](https://www.starlette.dev/lifespan/#running-lifespan-in-tests) bölümünde okuyabilirsiniz. +["Resmi Starlette dokümantasyon sitesinde testlerde lifespan'ı çalıştırma."](https://starlette.dev/lifespan/#running-lifespan-in-tests) hakkında daha fazla ayrıntı okuyabilirsiniz. Kullanımdan kaldırılmış `startup` ve `shutdown` event'leri için ise `TestClient`'ı aşağıdaki gibi kullanabilirsiniz: diff --git a/docs/tr/docs/advanced/testing-websockets.md b/docs/tr/docs/advanced/testing-websockets.md index a9afbc6..97ca52f 100644 --- a/docs/tr/docs/advanced/testing-websockets.md +++ b/docs/tr/docs/advanced/testing-websockets.md @@ -8,6 +8,6 @@ Bunun için `TestClient`'ı bir `with` ifadesinde kullanarak WebSocket'e bağlan /// note | Not -Daha fazla detay için Starlette'in [WebSockets'i test etme](https://www.starlette.dev/testclient/#testing-websocket-sessions) dokümantasyonuna bakın. +Daha fazla detay için Starlette'in [WebSockets'i test etme](https://starlette.dev/testclient/#testing-websocket-sessions) dokümantasyonuna bakın. /// diff --git a/docs/tr/docs/advanced/using-request-directly.md b/docs/tr/docs/advanced/using-request-directly.md index 9690710..9f67586 100644 --- a/docs/tr/docs/advanced/using-request-directly.md +++ b/docs/tr/docs/advanced/using-request-directly.md @@ -15,7 +15,7 @@ Ancak bazı durumlarda `Request` nesnesine doğrudan erişmeniz gerekebilir. ## `Request` nesnesi hakkında detaylar { #details-about-the-request-object } -**FastAPI** aslında altta **Starlette** çalıştırır ve üstüne çeşitli araçlardan oluşan bir katman ekler. Bu yüzden gerektiğinde Starlette'in [`Request`](https://www.starlette.dev/requests/) nesnesini doğrudan kullanabilirsiniz. +**FastAPI** aslında altta **Starlette** çalıştırır ve üstüne çeşitli araçlardan oluşan bir katman ekler. Bu yüzden gerektiğinde Starlette'in [`Request`](https://starlette.dev/requests/) nesnesini doğrudan kullanabilirsiniz. Bu ayrıca şu anlama gelir: `Request` nesnesinden veriyi doğrudan alırsanız (örneğin body'yi okursanız) FastAPI bu veriyi doğrulamaz, dönüştürmez veya dokümante etmez (otomatik API arayüzü için OpenAPI ile). @@ -45,7 +45,7 @@ Aynı şekilde, diğer parameter'ları normal biçimde tanımlamaya devam edip b ## `Request` dokümantasyonu { #request-documentation } -[Resmi Starlette dokümantasyon sitesinde `Request` nesnesiyle ilgili daha fazla detayı](https://www.starlette.dev/requests/) okuyabilirsiniz. +[Resmi Starlette dokümantasyon sitesinde `Request` nesnesiyle ilgili daha fazla detayı](https://starlette.dev/requests/) okuyabilirsiniz. /// note | Teknik Detaylar diff --git a/docs/tr/docs/advanced/websockets.md b/docs/tr/docs/advanced/websockets.md index 103a0aa..962eb37 100644 --- a/docs/tr/docs/advanced/websockets.md +++ b/docs/tr/docs/advanced/websockets.md @@ -4,12 +4,12 @@ ## `websockets` Kurulumu { #install-websockets } -Bir [sanal ortam](../virtual-environments.md) oluşturduğunuzdan, onu aktive ettiğinizden ve `websockets`'i ("WebSocket" protokolünü kullanmayı kolaylaştıran bir Python kütüphanesi) kurduğunuzdan emin olun: +Projenize `websockets`'i ("WebSocket" protokolünü kullanmayı kolaylaştıran bir Python kütüphanesi) ekleyin:
```console -$ pip install websockets +$ uv add websockets ---> 100% ``` @@ -69,7 +69,7 @@ Kodunuzu `main.py` dosyasına koyun ve ardından uygulamanızı çalıştırın:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -111,7 +111,7 @@ Diğer FastAPI endpoint'leri/*path operations* ile aynı şekilde çalışırlar {* ../../docs_src/websockets_/tutorial002_an_py310.py hl[68:69,82] *} -/// note +/// note | Not Bu bir WebSocket olduğu için `HTTPException` raise etmek pek anlamlı değildir; bunun yerine `WebSocketException` raise ederiz. @@ -126,7 +126,7 @@ Uygulamanızı çalıştırın:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -140,7 +140,7 @@ Burada şunları ayarlayabilirsiniz: * path'te kullanılan "Item ID". * query parametresi olarak kullanılan "Token". -/// tip +/// tip | İpucu query'deki `token` değerinin bir dependency tarafından ele alınacağına dikkat edin. @@ -168,7 +168,7 @@ Bu, `WebSocketDisconnect` exception'ını raise eder ve diğer tüm client'lar Client #1596980209979 left the chat ``` -/// tip +/// tip | İpucu Yukarıdaki uygulama, birden fazla WebSocket bağlantısına mesajları nasıl yönetip broadcast edeceğinizi göstermek için minimal ve basit bir örnektir. @@ -182,5 +182,5 @@ FastAPI ile kolay entegre olan ama Redis, PostgreSQL vb. tarafından desteklenen Seçenekler hakkında daha fazlasını öğrenmek için Starlette dokümantasyonunda şunlara bakın: -* [`WebSocket` class'ı](https://www.starlette.dev/websockets/). -* [Class tabanlı WebSocket yönetimi](https://www.starlette.dev/endpoints/#websocketendpoint). +* [`WebSocket` class'ı](https://starlette.dev/websockets/). +* [Class tabanlı WebSocket yönetimi](https://starlette.dev/endpoints/#websocketendpoint). diff --git a/docs/tr/docs/advanced/wsgi.md b/docs/tr/docs/advanced/wsgi.md index 6e61aff..387ae82 100644 --- a/docs/tr/docs/advanced/wsgi.md +++ b/docs/tr/docs/advanced/wsgi.md @@ -1,6 +1,5 @@ # WSGI'yi Dahil Etme - Flask, Django ve Diğerleri { #including-wsgi-flask-django-others } - WSGI uygulamalarını [Alt Uygulamalar - Mount Etme](sub-applications.md), [Bir Proxy Arkasında](behind-a-proxy.md) bölümlerinde gördüğünüz gibi mount edebilirsiniz. Bunun için `WSGIMiddleware`'ı kullanabilir ve bunu WSGI uygulamanızı (örneğin Flask, Django vb.) sarmalamak için kullanabilirsiniz. @@ -9,7 +8,7 @@ Bunun için `WSGIMiddleware`'ı kullanabilir ve bunu WSGI uygulamanızı (örne /// note | Not -Bunun için `a2wsgi` kurulmalıdır; örneğin `pip install a2wsgi` ile. +Bunun için projenize `a2wsgi` eklemeniz gerekir; örneğin `uv add a2wsgi` ile. /// diff --git a/docs/tr/docs/alternatives.md b/docs/tr/docs/alternatives.md index e214907..dcfafa7 100644 --- a/docs/tr/docs/alternatives.md +++ b/docs/tr/docs/alternatives.md @@ -125,7 +125,7 @@ API spesifikasyonları için özel bir şema yerine açık bir standart benimsem Ve standartlara dayalı kullanıcı arayüzü araçlarını entegre etmek: * [Swagger UI](https://github.com/swagger-api/swagger-ui) -* [ReDoc](https://github.com/Rebilly/ReDoc) +* [ReDoc](https://github.com/Redocly/redoc) Bu ikisi oldukça popüler ve istikrarlı oldukları için seçildi; hızlı bir aramayla OpenAPI için onlarca alternatif kullanıcı arayüzü bulabilirsiniz (**FastAPI** ile de kullanabilirsiniz). @@ -237,7 +237,7 @@ Serileştirme ve doğrulamayı tanımlayan aynı koddan, OpenAPI şemasını oto /// -### [NestJS](https://nestjs.com/) (ve [Angular](https://angular.io/)) { #nestjs-and-angular } +### [NestJS](https://nestjs.com/) (ve [Angular](https://angular.dev/)) { #nestjs-and-angular } Bu Python bile değil; NestJS, Angular’dan ilham alan bir JavaScript (TypeScript) NodeJS framework’üdür. @@ -337,7 +337,7 @@ Senkron Python web framework’leri için önceki standart olan WSGI’ye dayand /// note | Not -Hug, Python dosyalarındaki import’ları otomatik sıralayan harika bir araç olan [`isort`](https://github.com/timothycrosley/isort)’un geliştiricisi Timothy Crosley tarafından geliştirildi. +Hug, Python dosyalarındaki import’ları otomatik sıralayan harika bir araç olan [`isort`](https://github.com/PyCQA/isort)’un geliştiricisi Timothy Crosley tarafından geliştirildi. /// @@ -380,7 +380,7 @@ Artık bir API web framework’ü değildi; geliştirici Starlette’e odaklanma APIStar, aşağıdakilerin de yaratıcısı olan Tom Christie tarafından geliştirildi: * Django REST Framework -* **FastAPI**’ın üzerine kurulu Starlette +* **FastAPI**’nin temel aldığı Starlette * Starlette ve **FastAPI** tarafından kullanılan Uvicorn /// @@ -401,7 +401,7 @@ Sonra APIStar bir sunucu olarak var olmaktan çıktı ve Starlette oluşturuldu; ## **FastAPI** Tarafından Kullanılanlar { #used-by-fastapi } -### [Pydantic](https://docs.pydantic.dev/) { #pydantic } +### [Pydantic](https://pydantic.dev/docs/) { #pydantic } Pydantic, Python tip belirteçlerine dayalı olarak veri doğrulama, serileştirme ve dökümantasyon (JSON Schema kullanarak) tanımlamak için bir kütüphanedir. @@ -417,7 +417,7 @@ Tüm veri doğrulama, veri serileştirme ve JSON Schema tabanlı otomatik model /// -### [Starlette](https://www.starlette.dev/) { #starlette } +### [Starlette](https://starlette.dev/) { #starlette } Starlette, yüksek performanslı asyncio servisleri oluşturmak için ideal, hafif bir ASGI framework’ü/araç takımıdır. @@ -462,7 +462,7 @@ Dolayısıyla Starlette ile yapabildiğiniz her şeyi, adeta “turbo şarjlı S /// -### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn } +### [Uvicorn](https://uvicorn.dev) { #uvicorn } Uvicorn, uvloop ve httptools üzerinde inşa edilmiş, ışık hızında bir ASGI sunucusudur. diff --git a/docs/tr/docs/deployment/docker.md b/docs/tr/docs/deployment/docker.md index aebde76..7adf91a 100644 --- a/docs/tr/docs/deployment/docker.md +++ b/docs/tr/docs/deployment/docker.md @@ -105,36 +105,32 @@ Bu, örneğin şu durumlarda **çoğu zaman** yapmak isteyeceğiniz şeydir: ### Paket Gereksinimleri { #package-requirements } -Uygulamanızın **paket gereksinimleri** genelde bir dosyada yer alır. +Projenizi `uv` ile yönetiyorsanız, doğrudan bağımlılıkları `pyproject.toml` içinde tanımlanır ve çözümlenen kesin versiyonlar `uv.lock` içinde saklanır. -Bu, gereksinimleri **yüklemek** için kullandığınız araca göre değişir. - -En yaygın yöntem, paket adları ve versiyonlarının satır satır yazıldığı bir `requirements.txt` dosyasına sahip olmaktır. - -Versiyon aralıklarını belirlemek için elbette [FastAPI sürümleri hakkında](versions.md) bölümünde okuduğunuz fikirleri kullanırsınız. - -Örneğin `requirements.txt` şöyle görünebilir: - -``` -fastapi[standard]>=0.113.0,<0.114.0 -pydantic>=2.7.0,<3.0.0 -``` - -Ve bu bağımlılıkları normalde `pip` ile yüklersiniz, örneğin: +Uygulamanızın ihtiyaç duyduğu paketleri şu şekilde ekleyebilirsiniz:
```console -$ pip install -r requirements.txt +$ uv add "fastapi[standard]" pydantic ---> 100% -Successfully installed fastapi pydantic ```
/// note | Not -Paket bağımlılıklarını tanımlamak ve yüklemek için başka formatlar ve araçlar da vardır. +Aşağıdaki Dockerfile, container içinde `pip` kullanır. uv projenizdeki kilitlenmiş bağımlılıkları, beklediği `requirements.txt` formatına export edebilirsiniz: + +
+ +```console +$ uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt +``` + +
+ +Oluşturulan `requirements.txt`, container build'i için bir export'tur. Bağımlılıkları `uv add` ile yönetmeye devam edin ve `uv.lock` değiştiğinde bu dosyayı yeniden oluşturun. /// @@ -372,7 +368,7 @@ Otomatik etkileşimli API dokümantasyonunu görürsünüz ( [Swagger UI](https: Ayrıca [http://192.168.99.100/redoc](http://192.168.99.100/redoc) veya [http://127.0.0.1/redoc](http://127.0.0.1/redoc) adresine de gidebilirsiniz (ya da Docker host'unuzla eşdeğeri). -Alternatif otomatik dokümantasyonu görürsünüz ([ReDoc](https://github.com/Rebilly/ReDoc) tarafından sağlanır): +Alternatif otomatik dokümantasyonu görürsünüz ([ReDoc](https://github.com/Redocly/redoc) tarafından sağlanır): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) diff --git a/docs/tr/docs/deployment/fastapicloud.md b/docs/tr/docs/deployment/fastapicloud.md index eecf25d..f1664f6 100644 --- a/docs/tr/docs/deployment/fastapicloud.md +++ b/docs/tr/docs/deployment/fastapicloud.md @@ -5,7 +5,7 @@ FastAPI uygulamanızı [FastAPI Cloud](https://fastapicloud.com)'a yalnızca **t
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... diff --git a/docs/tr/docs/deployment/manually.md b/docs/tr/docs/deployment/manually.md index 2a2b168..60206f3 100644 --- a/docs/tr/docs/deployment/manually.md +++ b/docs/tr/docs/deployment/manually.md @@ -1,6 +1,5 @@ # Bir Sunucuyu Manuel Olarak Çalıştırın { #run-a-server-manually } - ## `fastapi run` Komutunu Kullanın { #use-the-fastapi-run-command } Kısacası, FastAPI uygulamanızı sunmak için `fastapi run` kullanın: @@ -53,7 +52,7 @@ Uzak bir sunucu makinesinde **FastAPI** uygulamasını (veya herhangi bir ASGI u Buna alternatif birkaç seçenek daha vardır, örneğin: -* [Uvicorn](https://www.uvicorn.dev/): yüksek performanslı bir ASGI server. +* [Uvicorn](https://uvicorn.dev): yüksek performanslı bir ASGI server. * [Hypercorn](https://hypercorn.readthedocs.io/): diğer özelliklerin yanında HTTP/2 ve Trio ile uyumlu bir ASGI server. * [Daphne](https://github.com/django/daphne): Django Channels için geliştirilmiş ASGI server. * [Granian](https://github.com/emmett-framework/granian): Python uygulamaları için bir Rust HTTP server. @@ -74,14 +73,14 @@ FastAPI'yi kurduğunuzda, production sunucusu olarak Uvicorn da beraberinde geli Ancak bir ASGI server'ı manuel olarak da kurabilirsiniz. -Bir [sanal ortam](../virtual-environments.md) oluşturduğunuzdan, etkinleştirdiğinizden emin olun; ardından server uygulamasını kurabilirsiniz. +Server uygulamasını projenize ekleyin. Örneğin Uvicorn'u kurmak için:
```console -$ pip install "uvicorn[standard]" +$ uv add "uvicorn[standard]" ---> 100% ``` @@ -96,7 +95,7 @@ Benzer bir süreç, diğer ASGI server programlarının tamamı için de geçerl Bunlara, `asyncio` için yüksek performanslı bir drop-in replacement olan ve concurrency performansını ciddi şekilde artıran `uvloop` da dahildir. -FastAPI'yi `pip install "fastapi[standard]"` gibi bir şekilde kurduğunuzda `uvicorn[standard]` da zaten kurulmuş olur. +FastAPI'yi `uv add "fastapi[standard]"` gibi bir şekilde eklediğinizde `uvicorn[standard]` da zaten kurulmuş olur. /// @@ -107,7 +106,7 @@ Bir ASGI server'ı manuel olarak kurduysanız, FastAPI uygulamanızı import ede
```console -$ uvicorn main:app --host 0.0.0.0 --port 80 +$ uv run uvicorn main:app --host 0.0.0.0 --port 80 INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) ``` diff --git a/docs/tr/docs/deployment/server-workers.md b/docs/tr/docs/deployment/server-workers.md index 878048e..1e0f57a 100644 --- a/docs/tr/docs/deployment/server-workers.md +++ b/docs/tr/docs/deployment/server-workers.md @@ -9,19 +9,19 @@ * Bellek * Başlatmadan önceki adımlar -Bu noktaya kadar, dokümantasyondaki tüm tutorial'larla muhtemelen bir server programı çalıştırıyordunuz; örneğin Uvicorn'u çalıştıran `fastapi` komutunu kullanarak ve tek bir process ile. +Bu noktaya kadar, dokümantasyondaki tüm tutorial'larla muhtemelen bir **server programı** çalıştırıyordunuz; örneğin Uvicorn'u çalıştıran `fastapi` komutunu kullanarak ve **tek bir process** ile. -Uygulamaları deploy ederken, çok çekirdekten (multiple cores) faydalanmak ve daha fazla request'i karşılayabilmek için büyük olasılıkla process replikasyonu (birden fazla process) isteyeceksiniz. +Uygulamaları deploy ederken, çok çekirdekten (multiple cores) faydalanmak ve daha fazla request'i karşılayabilmek için büyük olasılıkla **process replikasyonu (birden fazla process)** isteyeceksiniz. [Daha önceki Deployment Concepts](concepts.md) bölümünde gördüğünüz gibi, kullanabileceğiniz birden fazla strateji var. -Burada, `fastapi` komutunu kullanarak ya da `uvicorn` komutunu doğrudan çalıştırarak worker process'lerle Uvicorn'u nasıl kullanacağınızı göstereceğim. +Burada, `fastapi` komutunu kullanarak ya da `uvicorn` komutunu doğrudan çalıştırarak **worker process**'lerle **Uvicorn**'u nasıl kullanacağınızı göstereceğim. /// note | Not Container kullanıyorsanız (örneğin Docker veya Kubernetes ile), bununla ilgili daha fazlasını bir sonraki bölümde anlatacağım: [Container'larda FastAPI - Docker](docker.md). -Özellikle Kubernetes üzerinde çalıştırırken, büyük olasılıkla worker kullanmak istemeyeceksiniz; bunun yerine container başına tek bir Uvicorn process çalıştırmak daha uygundur. Ancak bunu da o bölümde detaylandıracağım. +Özellikle **Kubernetes** üzerinde çalıştırırken, büyük olasılıkla worker kullanmak istemeyeceksiniz; bunun yerine **container başına tek bir Uvicorn process** çalıştırmak daha uygundur. Ancak bunu da o bölümde detaylandıracağım. /// @@ -86,7 +86,7 @@ $ fastapi run --workers 4 ```console -$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 +$ uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit) INFO: Started parent process [27365] INFO: Started server process [27368] @@ -109,13 +109,13 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 Buradaki tek yeni seçenek `--workers`; bu seçenek Uvicorn'a 4 adet worker process başlatmasını söyler. -Ayrıca her process'in PID'inin gösterildiğini de görebilirsiniz: parent process için `27365` (bu process manager), her worker process için de bir PID: `27368`, `27369`, `27370` ve `27367`. +Ayrıca her process'in **PID**'inin gösterildiğini de görebilirsiniz: parent process için `27365` (bu **process manager**), her worker process için de bir PID: `27368`, `27369`, `27370` ve `27367`. ## Deployment Kavramları { #deployment-concepts } -Burada, uygulamanın çalışmasını paralelleştirmek, CPU'daki çok çekirdekten yararlanmak ve daha fazla request karşılayabilmek için birden fazla worker'ı nasıl kullanacağınızı gördünüz. +Burada, uygulamanın çalışmasını **paralelleştirmek**, CPU'daki **çok çekirdekten** yararlanmak ve **daha fazla request** karşılayabilmek için birden fazla **worker**'ı nasıl kullanacağınızı gördünüz. -Yukarıdaki deployment kavramları listesinden, worker kullanımı ağırlıklı olarak replikasyon kısmına yardımcı olur, ayrıca yeniden başlatmalar konusunda da az da olsa katkı sağlar. Ancak diğerlerini yine sizin yönetmeniz gerekir: +Yukarıdaki deployment kavramları listesinden, worker kullanımı ağırlıklı olarak **replikasyon** kısmına yardımcı olur, ayrıca **yeniden başlatmalar** konusunda da az da olsa katkı sağlar. Ancak diğerlerini yine sizin yönetmeniz gerekir: * **Güvenlik - HTTPS** * **Başlangıçta çalıştırma** @@ -126,14 +126,14 @@ Yukarıdaki deployment kavramları listesinden, worker kullanımı ağırlıklı ## Container'lar ve Docker { #containers-and-docker } -Bir sonraki bölümde, [Container'larda FastAPI - Docker](docker.md) üzerinden diğer deployment kavramlarını ele almak için kullanabileceğiniz bazı stratejileri anlatacağım. +Bir sonraki bölümde, [Container'larda FastAPI - Docker](docker.md) üzerinden diğer **deployment kavramlarını** ele almak için kullanabileceğiniz bazı stratejileri anlatacağım. -Tek bir Uvicorn process çalıştıracak şekilde sıfırdan kendi image'ınızı oluşturmayı göstereceğim. Bu oldukça basit bir süreçtir ve Kubernetes gibi dağıtık bir container yönetim sistemi kullanırken büyük olasılıkla yapmak isteyeceğiniz şey de budur. +Tek bir Uvicorn process çalıştıracak şekilde **sıfırdan kendi image'ınızı oluşturmayı** göstereceğim. Bu oldukça basit bir süreçtir ve **Kubernetes** gibi dağıtık bir container yönetim sistemi kullanırken büyük olasılıkla yapmak isteyeceğiniz şey de budur. ## Özet { #recap } -Çok çekirdekli CPU'lardan faydalanmak ve birden fazla process'i paralel çalıştırmak için `fastapi` veya `uvicorn` komutlarıyla `--workers` CLI seçeneğini kullanarak birden fazla worker process çalıştırabilirsiniz. +Çok çekirdekli CPU'lardan faydalanmak ve **birden fazla process'i paralel çalıştırmak** için `fastapi` veya `uvicorn` komutlarıyla `--workers` CLI seçeneğini kullanarak birden fazla worker process çalıştırabilirsiniz. -Diğer deployment kavramlarını da kendiniz ele alarak kendi deployment sisteminizi kuruyorsanız, bu araçları ve fikirleri kullanabilirsiniz. +Diğer deployment kavramlarını da kendiniz ele alarak **kendi deployment sisteminizi** kuruyorsanız, bu araçları ve fikirleri kullanabilirsiniz. -Container'larla (örn. Docker ve Kubernetes) FastAPI'yi öğrenmek için bir sonraki bölüme göz atın. Bu araçların, diğer deployment kavramlarını çözmek için de basit yöntemleri olduğunu göreceksiniz. ✨ +Container'larla (örn. Docker ve Kubernetes) **FastAPI**'yi öğrenmek için bir sonraki bölüme göz atın. Bu araçların, diğer **deployment kavramlarını** çözmek için de basit yöntemleri olduğunu göreceksiniz. ✨ diff --git a/docs/tr/docs/environment-variables.md b/docs/tr/docs/environment-variables.md index b54e1cb..0336540 100644 --- a/docs/tr/docs/environment-variables.md +++ b/docs/tr/docs/environment-variables.md @@ -1,298 +1,11 @@ # Ortam Değişkenleri { #environment-variables } -/// tip | İpucu +**Ortam değişkeni** (**env var** olarak da bilinir), Python kodunuzun dışında, işletim sisteminde bulunan ve uygulamanız ile diğer programlar tarafından okunabilen bir değerdir. -"Ortam değişkenleri"nin ne olduğunu ve nasıl kullanılacağını zaten biliyorsanız, bu bölümü atlayabilirsiniz. +FastAPI uygulamaları; database URL'leri, email kimlik bilgileri ve secret key'ler gibi konfigürasyonlar için ortam değişkenlerini yaygın olarak kullanır. -/// +Bunları uygulama konfigürasyonu için nasıl kullanacağınızı [Ayarlar ve Ortam Değişkenleri](advanced/settings.md) bölümünde öğreneceksiniz. -Ortam değişkeni (genelde "**env var**" olarak da anılır), Python kodunun **dışında**, **işletim sistemi** seviyesinde bulunan ve Python kodunuz (veya diğer programlar) tarafından okunabilen bir değişkendir. +## Daha Fazla Bilgi Edinin { #learn-more } -Ortam değişkenleri; uygulama **ayarları**nı yönetmek, Python’un **kurulumu**nun bir parçası olarak konfigürasyon yapmak vb. durumlarda işe yarar. - -## Env Var Oluşturma ve Kullanma { #create-and-use-env-vars } - -Python’a ihtiyaç duymadan, **shell (terminal)** içinde ortam değişkenleri **oluşturabilir** ve kullanabilirsiniz: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// MY_NAME adlı bir env var'ı şöyle oluşturabilirsiniz -$ export MY_NAME="Wade Wilson" - -// Sonra bunu diğer programlarla şöyle kullanabilirsiniz -$ echo "Hello $MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// MY_NAME adlı bir env var oluşturun -$ $Env:MY_NAME = "Wade Wilson" - -// Bunu diğer programlarla şöyle kullanın -$ echo "Hello $Env:MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -## Python’da Env Var Okuma { #read-env-vars-in-python } - -Ortam değişkenlerini Python’un **dışında** (terminalde veya başka bir yöntemle) oluşturup daha sonra **Python’da okuyabilirsiniz**. - -Örneğin `main.py` adında bir dosyanız şöyle olabilir: - -```Python hl_lines="3" -import os - -name = os.getenv("MY_NAME", "World") -print(f"Hello {name} from Python") -``` - -/// tip | İpucu - -[`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) fonksiyonunun ikinci argümanı, bulunamadığında döndürülecek varsayılan (default) değerdir. - -Verilmezse varsayılan olarak `None` olur; burada varsayılan değer olarak `"World"` verdik. - -/// - -Sonrasında bu Python programını çalıştırabilirsiniz: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// Burada env var'ı henüz ayarlamıyoruz -$ python main.py - -// Env var'ı ayarlamadığımız için varsayılan değeri alırız - -Hello World from Python - -// Ama önce bir ortam değişkeni oluşturursak -$ export MY_NAME="Wade Wilson" - -// Sonra programı tekrar çağırırsak -$ python main.py - -// Artık ortam değişkenini okuyabilir - -Hello Wade Wilson from Python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// Burada env var'ı henüz ayarlamıyoruz -$ python main.py - -// Env var'ı ayarlamadığımız için varsayılan değeri alırız - -Hello World from Python - -// Ama önce bir ortam değişkeni oluşturursak -$ $Env:MY_NAME = "Wade Wilson" - -// Sonra programı tekrar çağırırsak -$ python main.py - -// Artık ortam değişkenini okuyabilir - -Hello Wade Wilson from Python -``` - -
- -//// - -Ortam değişkenleri kodun dışında ayarlanabildiği, ama kod tarafından okunabildiği ve dosyalarla birlikte saklanmasının (ör. `git`’e commit edilmesinin) gerekmediği için, konfigürasyon veya **ayarlar** için sıkça kullanılır. - -Ayrıca, bir ortam değişkenini yalnızca **belirli bir program çalıştırımı** için oluşturabilirsiniz; bu değişken sadece o program tarafından, sadece o çalıştırma süresince kullanılabilir. - -Bunu yapmak için, program komutunun hemen öncesinde ve aynı satırda tanımlayın: - -
- -```console -// Bu program çağrısı için aynı satırda MY_NAME adlı bir env var oluşturun -$ MY_NAME="Wade Wilson" python main.py - -// Artık ortam değişkenini okuyabilir - -Hello Wade Wilson from Python - -// Sonrasında env var artık mevcut değildir -$ python main.py - -Hello World from Python -``` - -
- -/// tip | İpucu - -Bu konuyla ilgili daha fazlasını [Twelve-Factor Uygulaması: Config](https://12factor.net/config) bölümünde okuyabilirsiniz. - -/// - -## Türler ve Doğrulama { #types-and-validation } - -Bu ortam değişkenleri yalnızca **metin string**’lerini taşıyabilir. Çünkü Python’un dışındadırlar ve diğer programlarla, sistemin geri kalanıyla (hatta Linux, Windows, macOS gibi farklı işletim sistemleriyle) uyumlu olmak zorundadırlar. - -Bu, Python’da bir ortam değişkeninden okunan **her değerin `str` olacağı** anlamına gelir. Farklı bir tipe dönüştürme veya doğrulama işlemleri kod içinde yapılmalıdır. - -Uygulama **ayarları**nı yönetmek için ortam değişkenlerini kullanmayı, [İleri Seviye Kullanıcı Rehberi - Ayarlar ve Ortam Değişkenleri](./advanced/settings.md) bölümünde daha detaylı öğreneceksiniz. - -## `PATH` Ortam Değişkeni { #path-environment-variable } - -İşletim sistemlerinin (Linux, macOS, Windows) çalıştırılacak programları bulmak için kullandığı **özel** bir ortam değişkeni vardır: **`PATH`**. - -`PATH` değişkeninin değeri uzun bir string’dir; Linux ve macOS’te dizinler iki nokta üst üste `:` ile, Windows’ta ise noktalı virgül `;` ile ayrılır. - -Örneğin `PATH` ortam değişkeni şöyle görünebilir: - -//// tab | Linux, macOS - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -Bu, sistemin şu dizinlerde program araması gerektiği anlamına gelir: - -* `/usr/local/bin` -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32 -``` - -Bu, sistemin şu dizinlerde program araması gerektiği anlamına gelir: - -* `C:\Program Files\Python312\Scripts` -* `C:\Program Files\Python312` -* `C:\Windows\System32` - -//// - -Terminalde bir **komut** yazdığınızda, işletim sistemi `PATH` ortam değişkeninde listelenen **bu dizinlerin her birinde** programı **arar**. - -Örneğin terminalde `python` yazdığınızda, işletim sistemi bu listedeki **ilk dizinde** `python` adlı bir program arar. - -Bulursa **onu kullanır**. Bulamazsa **diğer dizinlerde** aramaya devam eder. - -### Python Kurulumu ve `PATH`’in Güncellenmesi { #installing-python-and-updating-the-path } - -Python’u kurarken, `PATH` ortam değişkenini güncellemek isteyip istemediğiniz sorulabilir. - -//// tab | Linux, macOS - -Diyelim ki Python’u kurdunuz ve `/opt/custompython/bin` dizinine yüklendi. - -`PATH` ortam değişkenini güncellemeyi seçerseniz, kurulum aracı `/opt/custompython/bin` yolunu `PATH` ortam değişkenine ekler. - -Şöyle görünebilir: - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin -``` - -Böylece terminalde `python` yazdığınızda, sistem `/opt/custompython/bin` (son dizin) içindeki Python programını bulur ve onu kullanır. - -//// - -//// tab | Windows - -Diyelim ki Python’u kurdunuz ve `C:\opt\custompython\bin` dizinine yüklendi. - -`PATH` ortam değişkenini güncellemeyi seçerseniz, kurulum aracı `C:\opt\custompython\bin` yolunu `PATH` ortam değişkenine ekler. - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin -``` - -Böylece terminalde `python` yazdığınızda, sistem `C:\opt\custompython\bin` (son dizin) içindeki Python programını bulur ve onu kullanır. - -//// - -Yani şunu yazarsanız: - -
- -```console -$ python -``` - -
- -//// tab | Linux, macOS - -Sistem `python` programını `/opt/custompython/bin` içinde **bulur** ve çalıştırır. - -Bu, kabaca şunu yazmaya denktir: - -
- -```console -$ /opt/custompython/bin/python -``` - -
- -//// - -//// tab | Windows - -Sistem `python` programını `C:\opt\custompython\bin\python` içinde **bulur** ve çalıştırır. - -Bu, kabaca şunu yazmaya denktir: - -
- -```console -$ C:\opt\custompython\bin\python -``` - -
- -//// - -Bu bilgiler, [Sanal Ortamlar](virtual-environments.md) konusunu öğrenirken işinize yarayacak. - -## Sonuç { #conclusion } - -Buraya kadar **ortam değişkenleri**nin ne olduğuna ve Python’da nasıl kullanılacağına dair temel bir fikir edinmiş olmalısınız. - -Ayrıca [Ortam Değişkeni için Wikipedia](https://en.wikipedia.org/wiki/Environment_variable) sayfasından daha fazlasını da okuyabilirsiniz. - -Çoğu zaman ortam değişkenlerinin hemen nasıl işe yarayacağı ilk bakışta çok net olmayabilir. Ancak geliştirme yaparken birçok farklı senaryoda tekrar tekrar karşınıza çıkarlar; bu yüzden bunları bilmek faydalıdır. - -Örneğin bir sonraki bölümde, [Sanal Ortamlar](virtual-environments.md) konusunda bu bilgilere ihtiyaç duyacaksınız. +Ortam değişkenlerini nasıl oluşturup okuyacağınızı ve `PATH` ortam değişkeninin nasıl çalıştığını da içeren detaylı, platformlar arası bir açıklama için [Ortam Değişkenleri rehberini](https://tiangolo.com/guides/environment-variables/) okuyun. diff --git a/docs/tr/docs/fastapi-cli.md b/docs/tr/docs/fastapi-cli.md index a8d7839..807c4bf 100644 --- a/docs/tr/docs/fastapi-cli.md +++ b/docs/tr/docs/fastapi-cli.md @@ -2,7 +2,7 @@ **FastAPI CLI**, FastAPI uygulamanızı servis etmek, FastAPI projenizi yönetmek ve daha fazlası için kullanabileceğiniz bir komut satırı programıdır. -FastAPI'yi kurduğunuzda (ör. `pip install "fastapi[standard]"`), terminalde çalıştırabileceğiniz bir komut satırı programı birlikte gelir. +FastAPI'yi projenize eklediğinizde (ör. `uv add "fastapi[standard]"` ile), terminalde çalıştırabileceğiniz bir komut satırı programı birlikte gelir. FastAPI uygulamanızı geliştirme için çalıştırmak üzere `fastapi dev` komutunu kullanabilirsiniz: @@ -52,7 +52,7 @@ Production için `fastapi dev` yerine `fastapi run` kullanırsınız. 🚀 /// -İçeride, **FastAPI CLI**, yüksek performanslı, production'a hazır bir ASGI server olan [Uvicorn](https://www.uvicorn.dev)'u kullanır. 😎 +İçeride, **FastAPI CLI**, yüksek performanslı, production'a hazır bir ASGI server olan [Uvicorn](https://uvicorn.dev)'u kullanır. 😎 `fastapi` CLI, çalıştırılacak FastAPI app'ini otomatik olarak tespit etmeye çalışır; `main.py` dosyasında `app` adlı bir nesne olduğunu varsayar (veya birkaç başka varyant). @@ -95,21 +95,21 @@ Bu da şu koda eşdeğerdir: from backend.main import app ``` -### path veya `--entrypoint` CLI seçeneği ile `fastapi dev` { #fastapi-dev-with-path-or-with-entrypoint-cli-option } +### path ile veya `--entrypoint` CLI seçeneği ile `fastapi dev` { #fastapi-dev-with-path-or-with-entrypoint-cli-option } Ayrıca `fastapi dev` komutuna dosya path'ini de verebilirsiniz; hangi FastAPI app nesnesinin kullanılacağını tahmin eder: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` Ya da `fastapi dev` komutuna `--entrypoint` seçeneğini de verebilirsiniz: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` -Ancak `fastapi` komutunu her çağırdığınızda doğru path'i veya entrypoint'i geçmeyi hatırlamanız gerekir. +Ancak `fastapi` komutunu her çağırdığınızda doğru path'i/entrypoint'i geçmeyi hatırlamanız gerekir. Ayrıca, [VS Code Extension](editor-support.md) veya [FastAPI Cloud](https://fastapicloud.com) gibi diğer araçlar da bunu bulamayabilir; bu yüzden `pyproject.toml` içindeki `entrypoint`'i kullanmanız önerilir. @@ -119,9 +119,13 @@ Ayrıca, [VS Code Extension](editor-support.md) veya [FastAPI Cloud](https://fas Varsayılan olarak **auto-reload** etkindir; kodunuzda değişiklik yaptığınızda server'ı otomatik olarak yeniden yükler. Bu, kaynak tüketimi yüksek bir özelliktir ve kapalı olduğuna kıyasla daha az stabil olabilir. Sadece geliştirme sırasında kullanmalısınız. Ayrıca yalnızca `127.0.0.1` IP adresini dinler; bu, makinenizin sadece kendisiyle iletişim kurması için kullanılan IP'dir (`localhost`). +App'inizi import etmeden önce `fastapi dev`, `FASTAPI_ENV` ortam değişkenini `development` olarak ayarlar. `FASTAPI_ENV` zaten ayarlanmışsa mevcut değeri korunur. Bu, app başlangıç kodunun geliştirme dostu davranış seçebilmesini sağlar ve aynı zamanda `staging` gibi app'e özel bir ortam sağlamanıza izin verir. + +Geleneksel `FASTAPI_ENV` değerleri `development` ve `production` şeklindedir. `fastapi run` şu anda `FASTAPI_ENV` değerini değiştirmez; bu yüzden app'inizin production modunu tespit etmesi gerekiyorsa bunu açıkça ayarlayın. + ## `fastapi run` { #fastapi-run } -`fastapi run` çalıştırmak, varsayılan olarak FastAPI'yi production modunda başlatır. +`fastapi run` komutunu çalıştırmak, FastAPI'yi production modunda başlatır. Varsayılan olarak **auto-reload** kapalıdır. Ayrıca `0.0.0.0` IP adresini dinler; bu, kullanılabilir tüm IP adresleri anlamına gelir. Böylece makineyle iletişim kurabilen herkes tarafından genel erişime açık olur. Bu, normalde production'da çalıştırma şeklidir; örneğin bir container içinde. diff --git a/docs/tr/docs/features.md b/docs/tr/docs/features.md index 9a85863..fd95c04 100644 --- a/docs/tr/docs/features.md +++ b/docs/tr/docs/features.md @@ -19,7 +19,7 @@ Etkileşimli API dokümantasyonu ve keşif için web arayüzleri. Framework Open ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* [**ReDoc**](https://github.com/Rebilly/ReDoc) ile alternatif API dokümantasyonu. +* [**ReDoc**](https://github.com/Redocly/redoc) ile alternatif API dokümantasyonu. ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) @@ -159,7 +159,7 @@ Her entegrasyon (bağımlılıklar ile) o kadar basit olacak şekilde tasarlanm ## Starlette Özellikleri { #starlette-features } -**FastAPI**, [**Starlette**](https://www.starlette.dev/) ile tamamen uyumludur (ve onun üzerine kuruludur). Dolayısıyla elinizdeki ek Starlette kodları da çalışır. +**FastAPI**, [**Starlette**](https://starlette.dev/) ile tamamen uyumludur (ve onun üzerine kuruludur). Dolayısıyla elinizdeki ek Starlette kodları da çalışır. `FastAPI` aslında `Starlette`’in bir alt sınıfıdır. Starlette’i zaten biliyor veya kullanıyorsanız, işlevlerin çoğu aynı şekilde çalışır. @@ -171,13 +171,13 @@ Her entegrasyon (bağımlılıklar ile) o kadar basit olacak şekilde tasarlanm * Başlatma ve kapatma olayları. * HTTPX üzerine kurulu test istemcisi. * **CORS**, GZip, Static Files, Streaming response’lar. -* **Session** ve **Cookie** desteği. +* **Session ve Cookie** desteği. * %100 test kapsayıcılığı. * %100 type annotated kod tabanı. ## Pydantic Özellikleri { #pydantic-features } -**FastAPI**, [**Pydantic**](https://docs.pydantic.dev/) ile tamamen uyumludur (ve onun üzerine kuruludur). Dolayısıyla elinizdeki ek Pydantic kodları da çalışır. +**FastAPI**, [**Pydantic**](https://pydantic.dev/docs/) ile tamamen uyumludur (ve onun üzerine kuruludur). Dolayısıyla elinizdeki ek Pydantic kodları da çalışır. Pydantic’e dayanan harici kütüphaneler de dâhildir; veritabanları için ORM’ler, ODM’ler gibi. diff --git a/docs/tr/docs/help-fastapi.md b/docs/tr/docs/help-fastapi.md index 07a17c3..4c20803 100644 --- a/docs/tr/docs/help-fastapi.md +++ b/docs/tr/docs/help-fastapi.md @@ -45,20 +45,6 @@ FastAPI ve friends hakkında paylaşacak haberlerim olduğunda duymak için, yaz * [**Bluesky**'de @tiangolo.com](https://bsky.app/profile/tiangolo.com) * [**LinkedIn**'de @tiangolo](https://www.linkedin.com/in/tiangolo/). -## GitHub'da Sorularla Başkalarına Yardım Edin { #help-others-with-questions-in-github } - -[GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered) içindeki sorularda başkalarına yardımcı olmayı deneyebilirsiniz. - -Birçok durumda bu soruların cevabını zaten biliyor olabilirsiniz. 🤓 - -Eğer insanların sorularına çok yardım ederseniz, resmi bir [FastAPI Expert](fastapi-people.md#fastapi-experts) olursunuz. 🎉 - -Şunu unutmayın: en önemli nokta, nazik olmaya çalışmak. 🤗 - -### Nasıl Yardım Edebilirsiniz { #how-to-help } - -[Nasıl yardım edileceğine dair rehberi](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github) izleyin. - ## Soru Sorun { #ask-questions } GitHub repository'sinde örneğin şunlar için [yeni bir soru oluşturabilirsiniz](https://github.com/fastapi/fastapi/discussions/new?category=questions): @@ -68,7 +54,7 @@ GitHub repository'sinde örneğin şunlar için [yeni bir soru oluşturabilirsin ## Sohbete Katılın { #join-the-chat } -👥 [Discord sohbet sunucusuna](https://discord.gg/VQjSZaeJmf) 👥 katılın ve FastAPI topluluğundaki diğer kişilerle takılın. +👥 [Discord sohbet sunucusuna](https://discord.com/invite/VQjSZaeJmf) 👥 katılın ve FastAPI topluluğundaki diğer kişilerle takılın. /// tip | İpucu @@ -85,3 +71,9 @@ Chat sistemleri daha "serbest sohbet"e izin verdiği için, çok genel ve yanıt GitHub'da şablon (template) doğru soruyu yazmanız için sizi yönlendirir; böylece daha kolay iyi bir cevap alabilir, hatta bazen sormadan önce problemi kendiniz çözebilirsiniz. Ayrıca chat sistemlerindeki konuşmalar GitHub kadar kolay aranabilir değildir; sohbet içinde kaybolurlar. + +## FastAPI Cloud'u Deneyin { #try-fastapi-cloud } + +FastAPI ve friends için ana finansman, FastAPI uygulamalarını tek bir komutla, `fastapi deploy`, basit ve hızlı bir şekilde deploy etmeye yarayan bir platform olan [**FastAPI Cloud**](https://fastapicloud.com)'dan gelir. + +FastAPI Cloud, FastAPI'nin arkasındaki aynı ekip tarafından geliştirilmektedir. Deneyebilir ve projeleriniz için değerlendirebilirsiniz. diff --git a/docs/tr/docs/history-design-future.md b/docs/tr/docs/history-design-future.md index 65ecdd3..5a041d4 100644 --- a/docs/tr/docs/history-design-future.md +++ b/docs/tr/docs/history-design-future.md @@ -54,11 +54,11 @@ Hepsi, tüm geliştiriciler için en iyi geliştirme deneyimini sağlayacak şek ## Gereksinimler { #requirements } -Çeşitli alternatifleri test ettikten sonra, avantajlarından dolayı [**Pydantic**](https://docs.pydantic.dev/)'i kullanmaya karar verdim. +Çeşitli alternatifleri test ettikten sonra, avantajlarından dolayı [**Pydantic**](https://pydantic.dev/docs/)'i kullanmaya karar verdim. Sonra, JSON Schema ile tamamen uyumlu olmasını sağlamak, kısıtlama bildirimlerini tanımlamanın farklı yollarını desteklemek ve birkaç editördeki testlere dayanarak editör desteğini (tip kontrolleri, otomatik tamamlama) geliştirmek için katkıda bulundum. -Geliştirme sırasında, diğer ana gereksinim olan [**Starlette**](https://www.starlette.dev/)'e de katkıda bulundum. +Geliştirme sırasında, diğer ana gereksinim olan [**Starlette**](https://starlette.dev/)'e de katkıda bulundum. ## Geliştirme { #development } @@ -70,7 +70,7 @@ Geliştirme sırasında, diğer ana gereksinim olan [**Starlette**](https://www. Birçok kullanım durumuna daha iyi uyduğu için, önceki alternatiflerin yerine seçiliyor. -Ben ve ekibim dahil, birçok geliştirici ve ekip projelerinde **FastAPI**'ya bağlı. +Ben ve ekibim dahil, birçok geliştirici ve ekip projelerinde **FastAPI**'a bağlı. Tabi, geliştirilecek birçok özellik ve iyileştirme mevcut. diff --git a/docs/tr/docs/how-to/custom-request-and-route.md b/docs/tr/docs/how-to/custom-request-and-route.md index a469851..4ab5415 100644 --- a/docs/tr/docs/how-to/custom-request-and-route.md +++ b/docs/tr/docs/how-to/custom-request-and-route.md @@ -67,7 +67,7 @@ Bir `Request` ayrıca `request.receive` içerir; bu, request'in body'sini "almak Ve bu iki şey, `scope` ve `receive`, yeni bir `Request` instance'ı oluşturmak için gerekenlerdir. -`Request` hakkında daha fazla bilgi için [Starlette'ın Request dokümantasyonu](https://www.starlette.dev/requests/) bölümüne bakın. +`Request` hakkında daha fazla bilgi için [Starlette'ın Request dokümantasyonu](https://starlette.dev/requests/) bölümüne bakın. /// diff --git a/docs/tr/docs/how-to/extending-openapi.md b/docs/tr/docs/how-to/extending-openapi.md index bbda88c..dabaa40 100644 --- a/docs/tr/docs/how-to/extending-openapi.md +++ b/docs/tr/docs/how-to/extending-openapi.md @@ -35,7 +35,7 @@ Yine de `app.routes`'i `get_openapi()`'ye geçebilirsiniz. FastAPI, etkili path /// -/// note | Bilgi +/// note | Not `summary` parametresi OpenAPI 3.1.0 ve üzeri sürümlerde vardır; FastAPI 0.99.0 ve üzeri tarafından desteklenmektedir. @@ -45,7 +45,7 @@ Yine de `app.routes`'i `get_openapi()`'ye geçebilirsiniz. FastAPI, etkili path Yukarıdaki bilgileri kullanarak aynı yardımcı fonksiyonla OpenAPI şemasını üretebilir ve ihtiyacınız olan her parçayı override edebilirsiniz. -Örneğin, [özel bir logo eklemek için ReDoc'un OpenAPI extension'ını](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo) ekleyelim. +Örneğin, [özel bir logo eklemek için ReDoc'un OpenAPI extension'ını](https://github.com/Redocly/redoc/blob/main/docs/redoc-vendor-extensions.md#x-logo) ekleyelim. ### Normal **FastAPI** { #normal-fastapi } diff --git a/docs/tr/docs/how-to/graphql.md b/docs/tr/docs/how-to/graphql.md index 8cc27a6..6d03b0d 100644 --- a/docs/tr/docs/how-to/graphql.md +++ b/docs/tr/docs/how-to/graphql.md @@ -1,6 +1,5 @@ # GraphQL { #graphql } - **FastAPI**, **ASGI** standardını temel aldığı için ASGI ile uyumlu herhangi bir **GraphQL** kütüphanesini entegre etmek oldukça kolaydır. Aynı uygulama içinde normal FastAPI *path operation*'larını GraphQL ile birlikte kullanabilirsiniz. @@ -22,7 +21,7 @@ Aşağıda **ASGI** desteği olan bazı **GraphQL** kütüphaneleri var. Bunlar * [Strawberry](https://strawberry.rocks/) 🍓 * [FastAPI dokümantasyonu](https://strawberry.rocks/docs/integrations/fastapi) ile * [Ariadne](https://ariadnegraphql.org/) - * [FastAPI dokümantasyonu](https://ariadnegraphql.org/docs/fastapi-integration) ile + * [FastAPI dokümantasyonu](https://ariadnegraphql.org/server/Integrations/fastapi-integration) ile * [Tartiflette](https://tartiflette.io/) * ASGI entegrasyonu sağlamak için [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) ile * [Graphene](https://graphene-python.org/) diff --git a/docs/tr/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/tr/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index e940a3b..3e660b2 100644 --- a/docs/tr/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/tr/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -24,7 +24,7 @@ Pydantic v1 kullanan eski bir FastAPI uygulamanız varsa, burada onu Pydantic v2 ## Resmi Kılavuz { #official-guide } -Pydantic'in v1'den v2'ye resmi bir [Migration Guide](https://docs.pydantic.dev/latest/migration/)'ı vardır. +Pydantic'in v1'den v2'ye resmi bir [Geçiş Kılavuzu](https://pydantic.dev/docs/validation/latest/get-started/migration/) vardır. Ayrıca nelerin değiştiğini, validasyonların artık nasıl daha doğru ve katı olduğunu, olası dikkat edilmesi gereken noktaları (caveat) vb. de içerir. diff --git a/docs/tr/docs/index.md b/docs/tr/docs/index.md index 65ac920..cfd3205 100644 --- a/docs/tr/docs/index.md +++ b/docs/tr/docs/index.md @@ -26,7 +26,7 @@ include_yaml: Package version - Supported Python versions + Supported Python versions

@@ -110,7 +110,7 @@ Temel özellikleri şunlardır:
-## FastAPI Conf { #fastapi-conf } - -[**FastAPI Conf '26**](https://fastapiconf.com) **28 Ekim 2026**'da **Amsterdam, NL**'de gerçekleşiyor. Kaynağından, bütünüyle FastAPI. 🎤 - -FastAPI Conf '26 - 28 Ekim 2026 - Amsterdam, NL - ## FastAPI mini belgeseli { #fastapi-mini-documentary } 2025'in sonunda yayınlanan bir [FastAPI mini belgeseli](https://www.youtube.com/watch?v=mpR8ngthqiE) var, online olarak izleyebilirsiniz: @@ -175,17 +169,17 @@ Web API yerine terminalde kullanılacak bir ```console -$ pip install "fastapi[standard]" +$ uv add "fastapi[standard]" ---> 100% ``` @@ -194,6 +188,8 @@ $ pip install "fastapi[standard]" **Not**: Tüm terminallerde çalıştığından emin olmak için `"fastapi[standard]"` ifadesini tırnak içinde yazdığınızdan emin olun. +`pip` kullanmayı tercih ediyorsanız, `fastapi[standard]` paketini bir virtual environment içinde kurun. Alternatif adımlar için [kurulum rehberine](tutorial/#install-fastapi) bakın. + ## Örnek { #example } ### Oluşturalım { #create-it } @@ -250,7 +246,7 @@ Sunucuyu şu komutla çalıştıralım:
```console -$ fastapi dev +$ uv run fastapi dev ╭────────── FastAPI CLI - Development mode ───────────╮ │ │ @@ -277,7 +273,7 @@ INFO: Application startup complete.
fastapi dev komutu hakkında... -`fastapi dev` komutu, `main.py` dosyanızı okur, içindeki **FastAPI** uygulamasını algılar ve [Uvicorn](https://www.uvicorn.dev) kullanarak bir server başlatır. +`fastapi dev` komutu, `main.py` dosyanızı okur, içindeki **FastAPI** uygulamasını algılar ve [Uvicorn](https://uvicorn.dev) kullanarak bir server başlatır. Varsayılan olarak `fastapi dev`, local geliştirme için auto-reload etkin şekilde başlar. @@ -314,7 +310,7 @@ Otomatik etkileşimli API dokümantasyonunu göreceksiniz ([Swagger UI](https:// Ve şimdi [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) adresine gidin. -Alternatif otomatik dokümantasyonu göreceksiniz ([ReDoc](https://github.com/Rebilly/ReDoc) tarafından sağlanır): +Alternatif otomatik dokümantasyonu göreceksiniz ([ReDoc](https://github.com/Redocly/redoc) tarafından sağlanır): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -492,12 +488,12 @@ Daha fazla özellik içeren daha kapsamlı bir örnek için ```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -540,7 +536,7 @@ FastAPI, Pydantic ve Starlette'a bağımlıdır. ### `standard` Bağımlılıkları { #standard-dependencies } -FastAPI'ı `pip install "fastapi[standard]"` ile yüklediğinizde, opsiyonel bağımlılıkların `standard` grubuyla birlikte gelir: +FastAPI'ı `uv add "fastapi[standard]"` ile yüklediğinizde, opsiyonel bağımlılıkların `standard` grubuyla birlikte gelir: Pydantic tarafından kullanılanlar: @@ -554,17 +550,17 @@ Starlette tarafından kullanılanlar: FastAPI tarafından kullanılanlar: -* [`uvicorn`](https://www.uvicorn.dev) - uygulamanızı yükleyen ve servis eden server için. Buna, yüksek performanslı servis için gereken bazı bağımlılıkları (örn. `uvloop`) içeren `uvicorn[standard]` dahildir. +* [`uvicorn`](https://uvicorn.dev) - uygulamanızı yükleyen ve servis eden server için. Buna, yüksek performanslı servis için gereken bazı bağımlılıkları (örn. `uvloop`) içeren `uvicorn[standard]` dahildir. * `fastapi-cli[standard]` - `fastapi` komutunu sağlamak için. * Buna, FastAPI uygulamanızı [FastAPI Cloud](https://fastapicloud.com)'a deploy etmenizi sağlayan `fastapi-cloud-cli` dahildir. ### `standard` Bağımlılıkları Olmadan { #without-standard-dependencies } -`standard` opsiyonel bağımlılıklarını dahil etmek istemiyorsanız, `pip install fastapi` ile kurabilirsiniz. +`standard` opsiyonel bağımlılıklarını dahil etmek istemiyorsanız, `uv add "fastapi[standard]"` yerine `uv add fastapi` ile kurabilirsiniz. ### `fastapi-cloud-cli` Olmadan { #without-fastapi-cloud-cli } -FastAPI'ı standard bağımlılıklarla ama `fastapi-cloud-cli` olmadan kurmak istiyorsanız, `pip install "fastapi[standard-no-fastapi-cloud-cli]"` ile yükleyebilirsiniz. +FastAPI'ı standard bağımlılıklarla ama `fastapi-cloud-cli` olmadan kurmak istiyorsanız, `uv add "fastapi[standard-no-fastapi-cloud-cli]"` ile yükleyebilirsiniz. ### Ek Opsiyonel Bağımlılıklar { #additional-optional-dependencies } @@ -572,13 +568,13 @@ Yüklemek isteyebileceğiniz bazı ek bağımlılıklar da vardır. Ek opsiyonel Pydantic bağımlılıkları: -* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - ayar yönetimi için. -* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - Pydantic ile kullanılacak ek type'lar için. +* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) - ayar yönetimi için. +* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) - Pydantic ile kullanılacak ek type'lar için. Ek opsiyonel FastAPI bağımlılıkları: * [`orjson`](https://github.com/ijl/orjson) - `ORJSONResponse` kullanmak istiyorsanız gereklidir. -* [`ujson`](https://github.com/esnme/ultrajson) - `UJSONResponse` kullanmak istiyorsanız gereklidir. +* [`ujson`](https://github.com/ultrajson/ultrajson) - `UJSONResponse` kullanmak istiyorsanız gereklidir. ## Lisans { #license } diff --git a/docs/tr/docs/project-generation.md b/docs/tr/docs/project-generation.md index 3dfe7a9..00523db 100644 --- a/docs/tr/docs/project-generation.md +++ b/docs/tr/docs/project-generation.md @@ -1,17 +1,16 @@ # Full Stack FastAPI Şablonu { #full-stack-fastapi-template } - Şablonlar genellikle belirli bir kurulumla gelir, ancak esnek ve özelleştirilebilir olacak şekilde tasarlanırlar. Bu sayede şablonu projenizin gereksinimlerine göre değiştirip uyarlayabilir, çok iyi bir başlangıç noktası olarak kullanabilirsiniz. 🏁 Bu şablonu başlangıç için kullanabilirsiniz; çünkü ilk kurulumun, güvenliğin, veritabanının ve bazı API endpoint'lerinin önemli bir kısmı sizin için zaten hazırlanmıştır. -GitHub Repository: [Full Stack FastAPI Şablonu](https://github.com/tiangolo/full-stack-fastapi-template) +GitHub Repository: [Full Stack FastAPI Şablonu](https://github.com/fastapi/full-stack-fastapi-template) ## Full Stack FastAPI Şablonu - Teknoloji Yığını ve Özellikler { #full-stack-fastapi-template-technology-stack-and-features } - ⚡ Python backend API için [**FastAPI**](https://fastapi.tiangolo.com/tr). - 🧰 Python SQL veritabanı etkileşimleri (ORM) için [SQLModel](https://sqlmodel.tiangolo.com). - - 🔍 FastAPI'nin kullandığı; veri doğrulama ve ayarlar yönetimi için [Pydantic](https://docs.pydantic.dev). + - 🔍 FastAPI'nin kullandığı; veri doğrulama ve ayarlar yönetimi için [Pydantic](https://pydantic.dev/docs/). - 💾 SQL veritabanı olarak [PostgreSQL](https://www.postgresql.org). - 🚀 frontend için [React](https://react.dev). - 💃 TypeScript, hooks, Vite ve modern bir frontend stack'inin diğer parçalarını kullanır. diff --git a/docs/tr/docs/python-types.md b/docs/tr/docs/python-types.md index 69f256d..60b7bfe 100644 --- a/docs/tr/docs/python-types.md +++ b/docs/tr/docs/python-types.md @@ -270,7 +270,7 @@ Bunun "`one_person`, `Person` sınıfının bir **instance**'ıdır" anlamına g ## Pydantic modelleri { #pydantic-models } -[Pydantic](https://docs.pydantic.dev/), data validation yapmak için bir Python kütüphanesidir. +[Pydantic](https://pydantic.dev/docs/) is a Python kütüphanesidir. Verinin "shape"'ini attribute'lara sahip sınıflar olarak tanımlarsınız. @@ -286,7 +286,7 @@ Resmî Pydantic dokümanlarından bir örnek: /// note | Not -Daha fazlasını öğrenmek için [Pydantic'in dokümanlarına bakın](https://docs.pydantic.dev/). +Daha fazlasını öğrenmek için [Pydantic'in dokümanlarına bakın](https://pydantic.dev/docs/). /// diff --git a/docs/tr/docs/tutorial/background-tasks.md b/docs/tr/docs/tutorial/background-tasks.md index 46e0efb..3d9e5de 100644 --- a/docs/tr/docs/tutorial/background-tasks.md +++ b/docs/tr/docs/tutorial/background-tasks.md @@ -51,8 +51,10 @@ Ve yazma işlemi `async` ve `await` kullanmadığı için fonksiyonu normal `def **FastAPI** her durumda ne yapılacağını ve aynı objenin nasıl yeniden kullanılacağını bilir; böylece tüm arka plan görevleri birleştirilir ve sonrasında arka planda çalıştırılır: + {* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *} + Bu örnekte, response gönderildikten *sonra* mesajlar `log.txt` dosyasına yazılacaktır. Request’te bir query varsa, log’a bir arka plan göreviyle yazılır. @@ -61,7 +63,7 @@ Ardından *path operation function* içinde oluşturulan başka bir arka plan g ## Teknik Detaylar { #technical-details } -`BackgroundTasks` sınıfı doğrudan [`starlette.background`](https://www.starlette.dev/background/)’dan gelir. +`BackgroundTasks` sınıfı doğrudan [`starlette.background`](https://starlette.dev/background/)’dan gelir. `fastapi` üzerinden import edebilmeniz ve yanlışlıkla `starlette.background` içindeki alternatif `BackgroundTask`’i (sonunda `s` olmadan) import etmemeniz için FastAPI’nin içine doğrudan import/eklenmiştir. @@ -69,7 +71,7 @@ Sadece `BackgroundTasks` (ve `BackgroundTask` değil) kullanarak, bunu bir *path FastAPI’de `BackgroundTask`’i tek başına kullanmak hâlâ mümkündür; ancak bu durumda objeyi kendi kodunuzda oluşturmanız ve onu içeren bir Starlette `Response` döndürmeniz gerekir. -Daha fazla detayı [Starlette’in Background Tasks için resmi dokümantasyonunda](https://www.starlette.dev/background/) görebilirsiniz. +Daha fazla detayı [Starlette’in Background Tasks için resmi dokümantasyonunda](https://starlette.dev/background/) görebilirsiniz. ## Dikkat Edilmesi Gerekenler { #caveat } diff --git a/docs/tr/docs/tutorial/bigger-applications.md b/docs/tr/docs/tutorial/bigger-applications.md index 81866e8..a0af787 100644 --- a/docs/tr/docs/tutorial/bigger-applications.md +++ b/docs/tr/docs/tutorial/bigger-applications.md @@ -453,7 +453,7 @@ ve `app.include_router()` ile eklenen diğer tüm *path operation*’larla birli /// note | Çok Teknik Detaylar -Not: Bu, muhtemelen doğrudan atlayabileceğiniz oldukça teknik bir detaydır. +**Not**: Bu, muhtemelen **doğrudan atlayabileceğiniz** oldukça teknik bir detaydır. --- @@ -461,7 +461,7 @@ Not: Bu, muhtemelen doğrudan atlayabileceğiniz oldukça teknik bir detaydır. Bunun nedeni, onların *path operation*’larını OpenAPI şemasına ve kullanıcı arayüzlerine dahil etmek istememizdir. -FastAPI, orijinal router’ları ve *path operation*’ları etkin tutar; istekleri işlerken ve OpenAPI üretirken router prefix’lerini, dependency’leri, tag’leri, responses’ları ve diğer metaverileri birleştirir. +FastAPI, orijinal router’ları ve *path operation*’ları etkin tutar; request'leri işlerken ve OpenAPI üretirken router prefix’lerini, dependency’leri, tag’leri, response’ları ve diğer metaverileri birleştirir. /// @@ -487,7 +487,7 @@ Böylece `fastapi` komutu uygulamanızı nerede bulacağını bilir. Komuta dosya yolunu da verebilirsiniz, örneğin: ```console -$ fastapi dev app/main.py +$ uv run fastapi dev app/main.py ``` Ancak o zaman her `fastapi` komutunu çalıştırdığınızda doğru yolu hatırlayıp geçirmeniz gerekir. @@ -503,7 +503,7 @@ Ayrıca, diğer araçlar uygulamayı bulamayabilir; örneğin [VS Code Eklentisi
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/tr/docs/tutorial/body-nested-models.md b/docs/tr/docs/tutorial/body-nested-models.md index d9f30c8..7582a8e 100644 --- a/docs/tr/docs/tutorial/body-nested-models.md +++ b/docs/tr/docs/tutorial/body-nested-models.md @@ -96,7 +96,7 @@ Yine, sadece bu tanımı yaparak **FastAPI** ile şunları elde edersiniz: `str`, `int`, `float` vb. normal tekil tiplerin yanında, `str`’den türeyen daha karmaşık tekil tipleri de kullanabilirsiniz. -Tüm seçenekleri görmek için [Pydantic Türlerine Genel Bakış](https://docs.pydantic.dev/latest/concepts/types/) sayfasına göz atın. Sonraki bölümde bazı örnekleri göreceksiniz. +Tüm seçenekleri görmek için [Pydantic Türlerine Genel Bakış](https://pydantic.dev/docs/validation/latest/concepts/types/) sayfasına göz atın. Sonraki bölümde bazı örnekleri göreceksiniz. Örneğin `Image` modelinde bir `url` alanımız olduğuna göre, bunu `str` yerine Pydantic’in `HttpUrl` tipinden bir instance olacak şekilde tanımlayabiliriz: @@ -150,7 +150,7 @@ Bu, aşağıdaki gibi bir JSON body bekler (dönüştürür, doğrular, doküman /// note | Not -`Offer`’ın bir `Item` list’i olduğuna, `Item`’ların da opsiyonel bir `Image` list’ine sahip olduğuna dikkat edin. +`Offer`’ın bir `Item` list’i olduğuna, `Item`’ların da opsiyonel bir `Image` list’ine sahip olduğuna dikkat edin /// diff --git a/docs/tr/docs/tutorial/body.md b/docs/tr/docs/tutorial/body.md index d05bd54..8adb3ea 100644 --- a/docs/tr/docs/tutorial/body.md +++ b/docs/tr/docs/tutorial/body.md @@ -7,7 +7,7 @@ Bir **request** body, client'in API'nize gönderdiği veridir. Bir **response** API'niz neredeyse her zaman bir **response** body göndermek zorundadır. Ancak client'lerin her zaman **request body** göndermesi gerekmez; bazen sadece bir path isterler, belki birkaç query parametresiyle birlikte, ama body göndermezler. -Bir **request** body tanımlamak için, tüm gücü ve avantajlarıyla [Pydantic](https://docs.pydantic.dev/) modellerini kullanırsınız. +Bir **request** body tanımlamak için, tüm gücü ve avantajlarıyla [Pydantic](https://pydantic.dev/docs/) modellerini kullanırsınız. /// note | Not diff --git a/docs/tr/docs/tutorial/debugging.md b/docs/tr/docs/tutorial/debugging.md index b73d651..b2e595c 100644 --- a/docs/tr/docs/tutorial/debugging.md +++ b/docs/tr/docs/tutorial/debugging.md @@ -15,7 +15,7 @@ FastAPI uygulamanızda `uvicorn`'ı import edip doğrudan çalıştırın:
```console -$ python myapp.py +$ uv run python myapp.py ```
@@ -35,7 +35,7 @@ Dosyanızın adının `myapp.py` olduğunu varsayalım.
```console -$ python myapp.py +$ uv run python myapp.py ```
diff --git a/docs/tr/docs/tutorial/extra-data-types.md b/docs/tr/docs/tutorial/extra-data-types.md index da0aab0..1874404 100644 --- a/docs/tr/docs/tutorial/extra-data-types.md +++ b/docs/tr/docs/tutorial/extra-data-types.md @@ -36,7 +36,7 @@ Kullanabileceğiniz ek veri tiplerinden bazıları şunlardır: * `datetime.timedelta`: * Python `datetime.timedelta`. * request'lerde ve response'larda toplam saniye sayısını ifade eden bir `float` olarak temsil edilir. - * Pydantic, bunu ayrıca bir "ISO 8601 time diff encoding" olarak temsil etmeye de izin verir, [daha fazla bilgi için dokümanlara bakın](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers). + * Pydantic, bunu ayrıca bir "ISO 8601 time diff encoding" olarak temsil etmeye de izin verir, [daha fazla bilgi için dokümanlara bakın](https://pydantic.dev/docs/validation/latest/concepts/serialization/#custom-serializers). * `frozenset`: * request'lerde ve response'larda, `set` ile aynı şekilde ele alınır: * request'lerde bir list okunur, tekrarlar kaldırılır ve `set`'e dönüştürülür. @@ -49,11 +49,11 @@ Kullanabileceğiniz ek veri tiplerinden bazıları şunlardır: * `Decimal`: * Standart Python `Decimal`. * request'lerde ve response'larda `float` ile aynı şekilde işlenir. -* Geçerli tüm Pydantic veri tiplerini burada görebilirsiniz: [Pydantic veri tipleri](https://docs.pydantic.dev/latest/usage/types/types/). +* Geçerli tüm Pydantic veri tiplerini burada görebilirsiniz: [Pydantic veri tipleri](https://pydantic.dev/docs/validation/latest/concepts/types/). ## Örnek { #example } -Yukarıdaki tiplerden bazılarını kullanan parametrelere sahip bir örnek *path operation*: +Yukarıdaki tiplerden bazılarını kullanan parametrelere sahip bir örnek *path operation*. {* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[1,3,12:16] *} diff --git a/docs/tr/docs/tutorial/extra-models.md b/docs/tr/docs/tutorial/extra-models.md index 9a499b3..9cc065e 100644 --- a/docs/tr/docs/tutorial/extra-models.md +++ b/docs/tr/docs/tutorial/extra-models.md @@ -167,7 +167,7 @@ Bunu yapmak için standart Python type hint'i olan [`typing.Union`](https://docs /// note | Not -Bir [`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions) tanımlarken en spesifik type'ı önce, daha az spesifik olanı sonra ekleyin. Aşağıdaki örnekte daha spesifik olan `PlaneItem`, `Union[PlaneItem, CarItem]` içinde `CarItem`'dan önce gelir. +Bir [`Union`](https://pydantic.dev/docs/validation/latest/concepts/unions/) tanımlarken en spesifik type'ı önce, daha az spesifik olanı sonra ekleyin. Aşağıdaki örnekte daha spesifik olan `PlaneItem`, `Union[PlaneItem, CarItem]` içinde `CarItem`'dan önce gelir. /// @@ -209,4 +209,4 @@ Bu durumda `dict` kullanabilirsiniz: Her duruma göre birden fazla Pydantic modeli kullanın ve gerekirse özgürce inheritance uygulayın. -Bir entity'nin farklı "state"lere sahip olması gerekiyorsa, o entity için tek bir veri modeli kullanmak zorunda değilsiniz. Örneğin `password` içeren, `password_hash` içeren ve `password` içermeyen state'lere sahip kullanıcı "entity"si gibi. +Bir entity'nin farklı "state"lere sahip olması gerekiyorsa, o entity için tek bir veri modeli kullanmak zorunda değilsiniz. **user** "entity"si buna örnektir; `password`, `password_hash` içeren veya password içermeyen state'lere sahip olabilir. diff --git a/docs/tr/docs/tutorial/first-steps.md b/docs/tr/docs/tutorial/first-steps.md index 5147f25..04487a9 100644 --- a/docs/tr/docs/tutorial/first-steps.md +++ b/docs/tr/docs/tutorial/first-steps.md @@ -7,12 +7,18 @@ En sade FastAPI dosyası şu şekilde görünür: Yukarıdakini `main.py` adlı bir dosyaya kopyalayın. +/// tip | İpucu + +FastAPI'nin [VS Code için resmi bir eklentisi](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (ve Cursor için) vardır; path operation explorer, path operation search, testlerde CodeLens navigasyonu (testlerden tanıma atlama), FastAPI Cloud deployment ve log'lar dahil olmak üzere birçok özelliği doğrudan editörünüzden sağlar. + +/// + Canlı sunucuyu çalıştırın:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -79,7 +85,7 @@ Otomatik etkileşimli API dokümantasyonunu ([Swagger UI](https://github.com/swa Ve şimdi [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) adresine gidin. -Alternatif otomatik dokümantasyonu ([ReDoc](https://github.com/Rebilly/ReDoc) tarafından sağlanan) göreceksiniz: +Alternatif otomatik dokümantasyonu ([ReDoc](https://github.com/Redocly/redoc) tarafından sağlanan) göreceksiniz: ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -186,16 +192,16 @@ from backend.main import app Dosya path'ini `fastapi dev` komutuna da verebilirsiniz; hangi FastAPI app objesini kullanacağını tahmin eder: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` Veya `fastapi dev` komutuna `--entrypoint` seçeneğini de geçebilirsiniz: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` -Ancak `fastapi` komutunu her çağırdığınızda doğru path'i veya entrypoint'i geçmeyi hatırlamanız gerekir. +Ancak `fastapi` komutunu her çağırdığınızda doğru path'i/entrypoint'i geçmeyi hatırlamanız gerekir. Ayrıca, [VS Code Eklentisi](../editor-support.md) veya [FastAPI Cloud](https://fastapicloud.com) gibi başka araçlar da onu bulamayabilir; bu yüzden `pyproject.toml` içindeki `entrypoint`'i kullanmanız önerilir. @@ -206,7 +212,7 @@ Ayrıca, [VS Code Eklentisi](../editor-support.md) veya [FastAPI Cloud](https://
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -233,7 +239,7 @@ Bu kadar! Artık uygulamanıza o URL üzerinden erişebilirsiniz. ✨ `FastAPI`, doğrudan `Starlette`'ten miras alan bir class'tır. -[Starlette](https://www.starlette.dev/)'in tüm işlevselliğini `FastAPI` ile de kullanabilirsiniz. +[Starlette](https://starlette.dev/)'in tüm işlevselliğini `FastAPI` ile de kullanabilirsiniz. /// diff --git a/docs/tr/docs/tutorial/frontend.md b/docs/tr/docs/tutorial/frontend.md index a9797dc..97efd35 100644 --- a/docs/tr/docs/tutorial/frontend.md +++ b/docs/tr/docs/tutorial/frontend.md @@ -52,7 +52,7 @@ Bunun için `fallback="index.html"` kullanın: {* ../../docs_src/frontend/tutorial002_py310.py hl[5] *} -**FastAPI** bu fallback'i yalnızca tarayıcı gezinmesi gibi görünen `GET` ve `HEAD` request'leri için kullanır. JavaScript, CSS ve görseller gibi eksik dosyalar yine `404` döndürür. +**FastAPI** bu fallback'i yalnızca, tarayıcı gezinme request'lerinin normalde yaptığı gibi `Accept: text/html` veya `Accept: application/xhtml+xml` ile HTML'i açıkça kabul eden `GET` ve `HEAD` request'leri için kullanır. JavaScript, CSS ve görseller gibi eksik dosyalar yine `404` döndürür. `POST` veya `PUT` gibi diğer metotlarla, yalnızca frontend fallback'i ile eşleşen path'lere yapılan request'ler de `404` döndürür. Normal **FastAPI** *path operation*'ları frontend route'larından yine daha yüksek önceliğe sahiptir. @@ -106,9 +106,13 @@ Bundan sonra bulunamayan frontend path'leri normal `404` döndürür. ## Dizini Kontrol Etme { #check-directory } -Varsayılan olarak `app.frontend()`, uygulama oluşturulduğunda dizinin var olduğunu kontrol eder. +Varsayılan olarak `app.frontend()`, `check_dir="auto"` kullanır. -Bu, yapılandırma hatalarını erken yakalamaya yardımcı olur. Örneğin frontend build çıktısı dizini yoksa, **FastAPI** başlangıçta hata verir. +`FASTAPI_ENV` ortam değişkeni `development` olarak ayarlandığında, frontend build çıktısı dizini eksikse **FastAPI** yalnızca bir uyarı gösterir. [`fastapi dev` komutu](https://github.com/fastapi/fastapi-cli#fastapi-dev), bu ortam değişkeni zaten ayarlı değilse sizin için ayarlar. Bu, development sırasında frontend'i build etmeden veya başlatmadan önce backend'i başlatmanıza olanak tanır. + +Diğer tüm ortamlarda, app oluşturulduğunda **FastAPI** bir hata verir. Bu, frontend dosyaları olmadan bir app deploy etmeden önce yapılandırma hatalarını erken yakalamaya yardımcı olur. + +App oluşturulduğunda dizini her zaman kontrol etmek için `check_dir=True` de ayarlayabilirsiniz. Frontend dosyalarınız daha sonra oluşturuluyorsa, örneğin app nesnesi oluşturulduktan sonra ayrı bir build adımıyla, `check_dir=False` ayarlayın: @@ -132,6 +136,8 @@ Frontend response'ları normal **FastAPI** uygulaması içinde çalışır, bu y Uygulamadan, bir `APIRouter`'dan ve `include_router()`'dan gelen dependencies de frontend response'larına uygulanır. Bu, bir frontend'i cookie authentication veya benzeri bir yöntemle korumak için kullanışlı olabilir. +Dependencies, normal *path operation*'larda olduğu gibi response header'larını değiştirebilir ve background task'lar ekleyebilir. + ## Yalnızca Statik Build Çıktısı { #static-build-output-only } `app.frontend()`, frontend build'iniz tarafından önceden oluşturulmuş dosyaları sunar. diff --git a/docs/tr/docs/tutorial/handling-errors.md b/docs/tr/docs/tutorial/handling-errors.md index 0339bde..c8a398c 100644 --- a/docs/tr/docs/tutorial/handling-errors.md +++ b/docs/tr/docs/tutorial/handling-errors.md @@ -81,7 +81,7 @@ Ama ileri seviye bir senaryo için ihtiyaç duyarsanız, özel header’lar ekle ## Özel Exception Handler’ları Kurmak { #install-custom-exception-handlers } -[Starlette’in aynı exception yardımcı araçlarıyla](https://www.starlette.dev/exceptions/) özel exception handler’lar ekleyebilirsiniz. +[Starlette’in aynı exception yardımcı araçlarıyla](https://starlette.dev/exceptions/) özel exception handler’lar ekleyebilirsiniz. Diyelim ki sizin (ya da kullandığınız bir kütüphanenin) `raise` edebileceği `UnicornException` adında özel bir exception’ınız var. diff --git a/docs/tr/docs/tutorial/index.md b/docs/tr/docs/tutorial/index.md index e30f3bf..8e9a7b2 100644 --- a/docs/tr/docs/tutorial/index.md +++ b/docs/tr/docs/tutorial/index.md @@ -10,12 +10,12 @@ Ayrıca, ileride tekrar dönüp tam olarak ihtiyaç duyduğunuz şeyi görebilec Tüm code block'lar kopyalanıp doğrudan kullanılabilir (zaten test edilmiş Python dosyalarıdır). -Örneklerden herhangi birini çalıştırmak için, kodu `main.py` adlı bir dosyaya kopyalayın ve `fastapi dev`'i başlatın: +Örneklerden herhangi birini çalıştırmak için, kodu `main.py` adlı bir dosyaya kopyalayın ve `uv run` ile `fastapi dev`'i başlatın:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -60,35 +60,75 @@ Editörünüzde kullanmak FastAPI'nin avantajlarını gerçekten gösterir: ne k ## FastAPI'yi Kurun { #install-fastapi } -İlk adım FastAPI'yi kurmaktır. +İlk adım projenizi hazırlamak ve FastAPI'yi eklemektir. -Bir [sanal ortam](../virtual-environments.md) oluşturduğunuzdan emin olun, etkinleştirin ve ardından **FastAPI'yi kurun**: +[`uv`](https://docs.astral.sh/uv/getting-started/installation/)'yi kurun, ardından bir proje oluşturup FastAPI'yi ekleyin:
```console -$ pip install "fastapi[standard]" +$ uv init awesome-project --bare +$ cd awesome-project +$ uv add "fastapi[standard]" ---> 100% ```
+`uv add`, projenin sanal ortamını `.venv` içinde oluşturur, FastAPI'yi `pyproject.toml` dosyasına ekler ve aynı paket sürümlerinin daha sonra kurulabilmesi için `uv.lock` oluşturur. + +/// details | Bu komutlar ne yapar + +* `uv init`: yeni bir Python projesi oluşturur. +* `awesome-project`: projeyi bu adla yeni bir dizinde oluşturur. +* `--bare`: örnek bir `main.py`, `README.md` veya başka dosyalar oluşturmadan yalnızca en minimal `pyproject.toml` dosyasını oluşturur. Bu eğitimin sonraki adımlarında uygulama dosyalarını kendiniz oluşturacaksınız. + +Ardından `cd awesome-project`, FastAPI eklenmeden önce yeni proje dizinine girer. + +`uv`, sisteminizde zaten kurulu olan uyumlu bir Python sürümünü kullanır veya gerekirse bir tane indirir. + +`uv add` çalıştırdığınızda, FastAPI'nin ve FastAPI'nin bağlı olduğu tüm paketlerin uyumlu sürümlerini seçer. Kesin sürümleri `uv.lock` içine kaydeder; bu da aynı paket sürümlerini daha sonra başka bir bilgisayarda veya uygulamayı deploy ederken kurmayı mümkün kılar. + +Bu dosyayı oluşturmak veya güncellemek, proje bağımlılıklarını [**lock'lamak**](https://docs.astral.sh/uv/concepts/projects/sync/) olarak adlandırılır. `uv`, bir paket eklediğinizde bunu otomatik olarak yapar. + +/// + +/// details | FastAPI kurulum seçenekleri + +`uv add "fastapi[standard]"` ile kurduğunuzda, bazı varsayılan opsiyonel standart bağımlılıklarla birlikte gelir. Bunlara `fastapi-cloud-cli` da dahildir; bu sayede [FastAPI Cloud](https://fastapicloud.com)'a deploy edebilirsiniz. + +Bu opsiyonel bağımlılıkları istemiyorsanız bunun yerine `uv add fastapi` kurabilirsiniz. + +Standart bağımlılıkları kurmak istiyor ama `fastapi-cloud-cli` olmasın diyorsanız, `uv add "fastapi[standard-no-fastapi-cloud-cli]"` ile kurabilirsiniz. + +/// + +/// details | Bunun yerine `pip` kullanmak + +Bir sanal ortamı ve paketleri manuel yönetmeyi tercih ediyorsanız, bir sanal ortam oluşturup etkinleştirin ve ardından FastAPI'yi `pip install "fastapi[standard]"` ile kurun. + +Ayrıntılı adımlar için [Sanal Ortamlar rehberini](https://tiangolo.com/guides/virtual-environments/) okuyun. + +/// + +## AI Agent Skill'leri { #ai-agent-skills } + +FastAPI, AI kodlama agent'ları için resmi bir skill içerir. Paketle birlikte gelir; bu nedenle yönergeleri projenizde kurulu FastAPI sürümüyle uyumlu kalır ve FastAPI'yi güncellediğinizde güncellenir. + +Projenize FastAPI'yi kurduktan sonra, skill'i Library Skills ile kurabilirsiniz: + +```bash +uvx library-skills +``` + /// note | Not -`pip install "fastapi[standard]"` ile kurduğunuzda, bazı varsayılan opsiyonel standart bağımlılıklarla birlikte gelir. Bunlara `fastapi-cloud-cli` da dahildir; bu sayede [FastAPI Cloud](https://fastapicloud.com)'a deploy edebilirsiniz. - -Bu opsiyonel bağımlılıkları istemiyorsanız bunun yerine `pip install fastapi` kurabilirsiniz. - -Standart bağımlılıkları kurmak istiyor ama `fastapi-cloud-cli` olmasın diyorsanız, `pip install "fastapi[standard-no-fastapi-cloud-cli]"` ile kurabilirsiniz. +`uvx`, `uv tool run` için bir alias'tır. Library Skills projenizde kurulu paketleri tararken, Library Skills'i geçici ve izole bir ortamda çalıştırır. /// -/// tip | İpucu - -FastAPI'nin [VS Code için resmi bir eklentisi](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (ve Cursor) vardır; path operation gezgini, path operation araması, testlerde CodeLens ile gezinme (testlerden tanıma atlama) ve FastAPI Cloud deploy ve logları gibi pek çok özelliği doğrudan editörünüzden sunar. - -/// +Skill; Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Pi, OpenCode ve diğer çoğu kodlama agent'ı ile uyumludur. Claude Code için, skill'in nereye kurulacağı sorulduğunda `.claude/skills` seçeneğini seçin. ## İleri Düzey Kullanıcı Rehberi { #advanced-user-guide } diff --git a/docs/tr/docs/tutorial/middleware.md b/docs/tr/docs/tutorial/middleware.md index 3404835..9e7fdec 100644 --- a/docs/tr/docs/tutorial/middleware.md +++ b/docs/tr/docs/tutorial/middleware.md @@ -37,7 +37,7 @@ Middleware fonksiyonu şunları alır: Özel (proprietary) header'lar [`X-` prefix'i kullanılarak](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) eklenebilir, bunu aklınızda tutun. -Ancak tarayıcıdaki bir client'ın görebilmesini istediğiniz özel header'larınız varsa, bunları CORS konfigürasyonlarınıza ([CORS (Cross-Origin Resource Sharing)](cors.md)) eklemeniz gerekir. Bunun için, [Starlette'ın CORS dokümanlarında](https://www.starlette.dev/middleware/#corsmiddleware) belgelenen `expose_headers` parametresini kullanın. +Ancak tarayıcıdaki bir client'ın görebilmesini istediğiniz özel header'larınız varsa, bunları CORS konfigürasyonlarınıza ([CORS (Cross-Origin Resource Sharing)](cors.md)) eklemeniz gerekir. Bunun için, [Starlette'ın CORS dokümanlarında](https://starlette.dev/middleware/#corsmiddleware) belgelenen `expose_headers` parametresini kullanın. /// diff --git a/docs/tr/docs/tutorial/path-params.md b/docs/tr/docs/tutorial/path-params.md index d1a9b6f..e3c39fb 100644 --- a/docs/tr/docs/tutorial/path-params.md +++ b/docs/tr/docs/tutorial/path-params.md @@ -1,4 +1,4 @@ -# Yol Parametreleri { #path-parameters } +# Path Parametreleri { #path-parameters } Python string biçimlemede kullanılan sözdizimiyle path "parametreleri"ni veya "değişkenleri"ni tanımlayabilirsiniz: @@ -12,7 +12,7 @@ Yani, bu örneği çalıştırıp [http://127.0.0.1:8000/items/foo](http://127.0 {"item_id":"foo"} ``` -## Tip İçeren Yol Parametreleri { #path-parameters-with-types } +## Tip İçeren Path Parametreleri { #path-parameters-with-types } Standart Python tip belirteçlerini kullanarak path parametresinin tipini fonksiyonun içinde tanımlayabilirsiniz: @@ -92,7 +92,7 @@ Dikkat edin: path parametresi integer olarak tanımlanmıştır. ## Standartlara Dayalı Avantajlar, Alternatif Dokümantasyon { #standards-based-benefits-alternative-documentation } -Üretilen şema [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md) standardından geldiği için birçok uyumlu araç vardır. +Üretilen şema [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) standardından geldiği için birçok uyumlu araç vardır. Bu nedenle **FastAPI**'ın kendisi, [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) adresinden erişebileceğiniz alternatif bir API dokümantasyonu (ReDoc kullanarak) sağlar: @@ -102,7 +102,7 @@ Aynı şekilde, birçok uyumlu araç vardır. Birçok dil için kod üretme ara ## Pydantic { #pydantic } -Tüm veri doğrulamaları, arka planda [Pydantic](https://docs.pydantic.dev/) tarafından gerçekleştirilir; böylece onun tüm avantajlarından faydalanırsınız. Ve emin ellerde olduğunuzu bilirsiniz. +Tüm veri doğrulamaları, arka planda [Pydantic](https://pydantic.dev/docs/) tarafından gerçekleştirilir; böylece onun tüm avantajlarından faydalanırsınız. Ve emin ellerde olduğunuzu bilirsiniz. Aynı tip tanımlarını `str`, `float`, `bool` ve daha birçok karmaşık veri tipiyle kullanabilirsiniz. diff --git a/docs/tr/docs/tutorial/query-params-str-validations.md b/docs/tr/docs/tutorial/query-params-str-validations.md index 831cfcb..86c102e 100644 --- a/docs/tr/docs/tutorial/query-params-str-validations.md +++ b/docs/tr/docs/tutorial/query-params-str-validations.md @@ -371,11 +371,11 @@ Yukarıdaki parametrelerle yapılamayan bazı **özel doğrulama** ihtiyaçları Bu durumlarda, normal doğrulamadan sonra (ör. değerin `str` olduğunun doğrulanmasından sonra) uygulanacak bir **custom validator function** kullanabilirsiniz. -Bunu, `Annotated` içinde [Pydantic’in `AfterValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator)’ını kullanarak yapabilirsiniz. +Bunu, `Annotated` içinde [Pydantic’in `AfterValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-after-validator)’ını kullanarak yapabilirsiniz. /// tip | İpucu -Pydantic’te [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator) ve başka validator’lar da vardır. 🤓 +Pydantic’te [`BeforeValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-before-validator) ve başka validator’lar da vardır. 🤓 /// @@ -403,7 +403,7 @@ Bu custom validator’lar, request’te sağlanan **yalnızca** **aynı veri** i --- -Ama bu örnek kodun detaylarını merak ediyorsanız, birkaç ek bilgi: +Ama bu özel kod örneğini merak ediyorsanız ve hâlâ eğleniyorsanız, işte birkaç ek detay. #### `value.startswith()` ile String { #string-with-value-startswith } diff --git a/docs/tr/docs/tutorial/request-files.md b/docs/tr/docs/tutorial/request-files.md index ab54cfd..844453c 100644 --- a/docs/tr/docs/tutorial/request-files.md +++ b/docs/tr/docs/tutorial/request-files.md @@ -6,10 +6,10 @@ Upload edilen dosyaları alabilmek için önce [`python-multipart`](https://github.com/Kludex/python-multipart) yükleyin. -Bir [Sanal ortam](../virtual-environments.md) oluşturduğunuzdan, aktive ettiğinizden ve ardından paketi yüklediğinizden emin olun. Örneğin: +Projenize ekleyin: ```console -$ pip install python-multipart +$ uv add python-multipart ``` Bunun nedeni, upload edilen dosyaların "form data" olarak gönderilmesidir. diff --git a/docs/tr/docs/tutorial/request-form-models.md b/docs/tr/docs/tutorial/request-form-models.md index 6f5532b..28afab7 100644 --- a/docs/tr/docs/tutorial/request-form-models.md +++ b/docs/tr/docs/tutorial/request-form-models.md @@ -6,10 +6,10 @@ FastAPI'de **form field**'larını tanımlamak için **Pydantic model**'lerini k Form'ları kullanmak için önce [`python-multipart`](https://github.com/Kludex/python-multipart)'ı yükleyin. -Bir [Sanal ortam](../virtual-environments.md) oluşturduğunuzdan, onu etkinleştirdiğinizden ve ardından paketi kurduğunuzdan emin olun. Örneğin: +Projenize ekleyin: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/tr/docs/tutorial/request-forms-and-files.md b/docs/tr/docs/tutorial/request-forms-and-files.md index fc50491..c47dddd 100644 --- a/docs/tr/docs/tutorial/request-forms-and-files.md +++ b/docs/tr/docs/tutorial/request-forms-and-files.md @@ -6,10 +6,10 @@ Yüklenen dosyaları ve/veya form verisini almak için önce [`python-multipart`](https://github.com/Kludex/python-multipart) paketini kurun. -Bir [sanal ortam](../virtual-environments.md) oluşturduğunuzdan, onu aktive ettiğinizden ve ardından paketi kurduğunuzdan emin olun, örneğin: +Projenize ekleyin: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/tr/docs/tutorial/request-forms.md b/docs/tr/docs/tutorial/request-forms.md index 57f10fb..836b17e 100644 --- a/docs/tr/docs/tutorial/request-forms.md +++ b/docs/tr/docs/tutorial/request-forms.md @@ -1,16 +1,15 @@ # Form Verisi { #form-data } - -JSON yerine form alanlarını almanız gerektiğinde `Form` kullanabilirsiniz. +When you need to receive form fields instead of JSON, you can use `Form`. /// note | Not Formları kullanmak için önce [`python-multipart`](https://github.com/Kludex/python-multipart) paketini kurun. -Bir [virtual environment](../virtual-environments.md) oluşturduğunuzdan, onu etkinleştirdiğinizden emin olun ve ardından örneğin şöyle kurun: +Projenize ekleyin: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/tr/docs/tutorial/response-model.md b/docs/tr/docs/tutorial/response-model.md index 063ec90..6766315 100644 --- a/docs/tr/docs/tutorial/response-model.md +++ b/docs/tr/docs/tutorial/response-model.md @@ -76,16 +76,16 @@ Burada `UserIn` adında bir model declare ediyoruz; bu model plaintext bir passw `EmailStr` kullanmak için önce [`email-validator`](https://github.com/JoshData/python-email-validator) paketini kurun. -Bir [virtual environment](../virtual-environments.md) oluşturduğunuzdan, onu aktive ettiğinizden emin olun ve ardından örneğin şöyle kurun: +Projenize ekleyin: ```console -$ pip install email-validator +$ uv add email-validator ``` veya şöyle: ```console -$ pip install "pydantic[email]" +$ uv add "pydantic[email]" ``` /// @@ -98,9 +98,9 @@ Artık bir browser password ile user oluşturduğunda, API response içinde ayn Bu örnekte sorun olmayabilir; çünkü password’ü gönderen kullanıcı zaten aynı kişi. -Namun aynı modeli başka bir *path operation* için kullanırsak, kullanıcının password’lerini her client’a gönderiyor olabiliriz. +Ama aynı modeli başka bir *path operation* için kullanırsak, kullanıcının password’lerini her client’a gönderiyor olabiliriz. -/// danger +/// danger | Tehlike Tüm riskleri bildiğinizden ve ne yaptığınızdan emin olmadığınız sürece, bir kullanıcının plain password’ünü asla saklamayın ve bu şekilde response içinde göndermeyin. @@ -258,7 +258,7 @@ Ayrıca şunları da kullanabilirsiniz: * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -Bunlar, `exclude_defaults` ve `exclude_none` için [Pydantic dokümanlarında](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict) anlatıldığı gibidir. +Bunlar, `exclude_defaults` ve `exclude_none` için [Pydantic dokümanlarında](https://pydantic.dev/docs/validation/latest/concepts/serialization/#excluding-and-including-fields-based-on-their-value) anlatıldığı gibidir. /// diff --git a/docs/tr/docs/tutorial/schema-extra-example.md b/docs/tr/docs/tutorial/schema-extra-example.md index 03f9eac..9fb3023 100644 --- a/docs/tr/docs/tutorial/schema-extra-example.md +++ b/docs/tr/docs/tutorial/schema-extra-example.md @@ -12,7 +12,7 @@ Oluşturulan JSON Schema’ya eklenecek şekilde bir Pydantic model için `examp Bu ek bilgi, o modelin çıktı **JSON Schema**’sına olduğu gibi eklenir ve API dokümanlarında kullanılır. -[Pydantic dokümanları: Configuration](https://docs.pydantic.dev/latest/api/config/) bölümünde anlatıldığı gibi, bir `dict` alan `model_config` niteliğini kullanabilirsiniz. +[Pydantic dokümanları: Configuration](https://pydantic.dev/docs/validation/latest/api/pydantic/config/) bölümünde anlatıldığı gibi, bir `dict` alan `model_config` niteliğini kullanabilirsiniz. Üretilen JSON Schema’da görünmesini istediğiniz (ör. `examples` dahil) her türlü ek veriyi içeren bir `dict` ile `"json_schema_extra"` ayarlayabilirsiniz. diff --git a/docs/tr/docs/tutorial/security/first-steps.md b/docs/tr/docs/tutorial/security/first-steps.md index 0d19aa0..f781a79 100644 --- a/docs/tr/docs/tutorial/security/first-steps.md +++ b/docs/tr/docs/tutorial/security/first-steps.md @@ -26,14 +26,14 @@ Güvenliği yönetmek için **FastAPI**’nin sunduğu araçları kullanalım. /// note | Not -[`python-multipart`](https://github.com/Kludex/python-multipart) paketi, `pip install "fastapi[standard]"` komutunu çalıştırdığınızda **FastAPI** ile birlikte otomatik olarak kurulur. +[`python-multipart`](https://github.com/Kludex/python-multipart) paketi, `uv add "fastapi[standard]"` komutunu çalıştırdığınızda **FastAPI** ile birlikte otomatik olarak kurulur. -Ancak `pip install fastapi` komutunu kullanırsanız, `python-multipart` paketi varsayılan olarak dahil edilmez. +Ancak `uv add fastapi` komutunu kullanırsanız, `python-multipart` paketi varsayılan olarak dahil edilmez. -Elle kurmak için bir [Sanal ortam](../../virtual-environments.md) oluşturduğunuzdan, onu aktive ettiğinizden emin olun ve ardından şununla kurun: +Elle kurmak için projenize şununla ekleyin: ```console -$ pip install python-multipart +$ uv add python-multipart ``` Bunun nedeni, **OAuth2**’nin `username` ve `password` göndermek için "form data" kullanmasıdır. @@ -45,7 +45,7 @@ Bunun nedeni, **OAuth2**’nin `username` ve `password` göndermek için "form d
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/tr/docs/tutorial/security/oauth2-jwt.md b/docs/tr/docs/tutorial/security/oauth2-jwt.md index df893ec..68355b9 100644 --- a/docs/tr/docs/tutorial/security/oauth2-jwt.md +++ b/docs/tr/docs/tutorial/security/oauth2-jwt.md @@ -30,12 +30,12 @@ JWT token'larıyla oynayıp nasıl çalıştıklarını görmek isterseniz [http Python'da JWT token'larını üretmek ve doğrulamak için `PyJWT` kurmamız gerekiyor. -Bir [sanal ortam](../../virtual-environments.md) oluşturduğunuzdan emin olun, aktif edin ve ardından `pyjwt` kurun: +Projenize `pyjwt` ekleyin:
```console -$ pip install pyjwt +$ uv add pyjwt ---> 100% ``` @@ -72,12 +72,12 @@ Birçok güvenli hashing algoritmasını ve bunlarla çalışmak için yardımc Önerilen algoritma "Argon2"dir. -Bir [sanal ortam](../../virtual-environments.md) oluşturduğunuzdan emin olun, aktif edin ve sonra Argon2 ile birlikte pwdlib'i kurun: +Projenize Argon2 ile birlikte `pwdlib` ekleyin:
```console -$ pip install "pwdlib[argon2]" +$ uv add "pwdlib[argon2]" ---> 100% ``` diff --git a/docs/tr/docs/tutorial/sql-databases.md b/docs/tr/docs/tutorial/sql-databases.md index 1145c20..9bdf203 100644 --- a/docs/tr/docs/tutorial/sql-databases.md +++ b/docs/tr/docs/tutorial/sql-databases.md @@ -34,12 +34,12 @@ Bu çok basit ve kısa bir eğitimdir. Veritabanları genelinde, SQL hakkında v ## `SQLModel` Kurulumu { #install-sqlmodel } -Önce [virtual environment](../virtual-environments.md) oluşturduğunuzdan emin olun, aktive edin ve ardından `sqlmodel`’i yükleyin: +Projenize `sqlmodel` ekleyin:
```console -$ pip install sqlmodel +$ uv add sqlmodel ---> 100% ``` @@ -152,7 +152,7 @@ Uygulamayı çalıştırabilirsiniz:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -337,7 +337,7 @@ Uygulamayı tekrar çalıştırabilirsiniz:
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/tr/docs/tutorial/static-files.md b/docs/tr/docs/tutorial/static-files.md index b271139..da7d338 100644 --- a/docs/tr/docs/tutorial/static-files.md +++ b/docs/tr/docs/tutorial/static-files.md @@ -45,4 +45,4 @@ Bu parametrelerin hepsi "`static`" ile aynı olmak zorunda değildir; kendi uygu ## Daha Fazla Bilgi { #more-info } -Daha fazla detay ve seçenek için [Starlette'in Statik Dosyalar hakkındaki dokümanlarını](https://www.starlette.dev/staticfiles/) inceleyin. +Daha fazla detay ve seçenek için [Starlette'in Statik Dosyalar hakkındaki dokümanlarını](https://starlette.dev/staticfiles/) inceleyin. diff --git a/docs/tr/docs/tutorial/testing.md b/docs/tr/docs/tutorial/testing.md index df5248f..95d1ede 100644 --- a/docs/tr/docs/tutorial/testing.md +++ b/docs/tr/docs/tutorial/testing.md @@ -1,10 +1,10 @@ # Test Etme { #testing } -[Starlette](https://www.starlette.dev/testclient/) sayesinde **FastAPI** uygulamalarını test etmek kolay ve keyiflidir. +[Starlette](https://starlette.dev/testclient/) sayesinde **FastAPI** uygulamalarını test etmek kolay ve keyiflidir. Temelde [HTTPX](https://www.python-httpx.org) üzerine kuruludur; HTTPX de Requests’i temel alarak tasarlandığı için oldukça tanıdık ve sezgiseldir. -Bununla birlikte **FastAPI** ile [pytest](https://docs.pytest.org/)'i doğrudan kullanabilirsiniz. +Bu sayede **FastAPI** ile [pytest](https://docs.pytest.org/)'i doğrudan kullanabilirsiniz. ## `TestClient` Kullanımı { #using-testclient } @@ -12,10 +12,10 @@ Bununla birlikte **FastAPI** ile [pytest](https://docs.pytest.org/)'i doğrudan `TestClient` kullanmak için önce [`httpx`](https://www.python-httpx.org)'i kurun. -Bir [Sanal Ortam](../virtual-environments.md) oluşturduğunuzdan, onu aktifleştirdiğinizden ve sonra kurulumu yaptığınızdan emin olun; örneğin: +Projenize ekleyin: ```console -$ pip install httpx +$ uv add httpx ``` /// @@ -156,12 +156,12 @@ Testinizde bir Pydantic model'iniz varsa ve test sırasında verisini uygulamaya Bundan sonra yapmanız gereken tek şey `pytest`'i kurmaktır. -Bir [Sanal Ortam](../virtual-environments.md) oluşturduğunuzdan, onu aktifleştirdiğinizden ve sonra kurulumu yaptığınızdan emin olun; örneğin: +Projenize ekleyin:
```console -$ pip install pytest +$ uv add pytest ---> 100% ``` @@ -175,7 +175,7 @@ Testleri şu şekilde çalıştırın:
```console -$ pytest +$ uv run pytest ================ test session starts ================ platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1 diff --git a/docs/tr/docs/virtual-environments.md b/docs/tr/docs/virtual-environments.md index 60494ac..5793140 100644 --- a/docs/tr/docs/virtual-environments.md +++ b/docs/tr/docs/virtual-environments.md @@ -1,864 +1,35 @@ -# Virtual Environments { #virtual-environments } +# Virtual Environment'ler { #virtual-environments } -Python projeleriyle çalışırken, her proje için kurduğunuz package'leri birbirinden izole etmek adına büyük ihtimalle bir **virtual environment** (veya benzer bir mekanizma) kullanmalısınız. +Python projeleriyle çalışırken, her proje için kurulan package'leri izole etmek adına bir **virtual environment** kullanmalısınız. -/// note | Not - -Virtual environment'leri, nasıl oluşturulduklarını ve nasıl kullanıldıklarını zaten biliyorsanız bu bölümü atlamak isteyebilirsiniz. 🤓 - -/// - -/// tip | İpucu - -**Virtual environment**, **environment variable** ile aynı şey değildir. - -**Environment variable**, sistemde bulunan ve programların kullanabildiği bir değişkendir. - -**Virtual environment** ise içinde bazı dosyalar bulunan bir klasördür. - -/// - -/// note | Not - -Bu sayfada **virtual environment**'leri nasıl kullanacağınızı ve nasıl çalıştıklarını öğreneceksiniz. - -Eğer Python'ı kurmak dahil her şeyi sizin yerinize yöneten bir **tool** kullanmaya hazırsanız, [uv](https://github.com/astral-sh/uv)'yi deneyin. - -/// +FastAPI projeleri için projeyi, bağımlılıklarını ve virtual environment'ini yönetmek üzere [uv](https://docs.astral.sh/uv/) kullanmanızı öneririm. ## Proje Oluşturun { #create-a-project } -Önce projeniz için bir klasör oluşturun. - -Ben genelde home/user klasörümün içinde `code` adlı bir klasör oluştururum. - -Sonra bunun içinde her proje için ayrı bir klasör oluştururum. +`uv`'yi [resmi kurulum rehberini](https://docs.astral.sh/uv/getting-started/installation/) kullanarak kurun ve ardından bir proje oluşturun:
```console -// Gelelim home dizinine -$ cd -// Tüm kod projeleriniz için bir klasör oluşturun -$ mkdir code -// Bu code klasörüne girin -$ cd code -// Bu proje için bir klasör oluşturun -$ mkdir awesome-project -// Proje klasörüne girin +$ uv init awesome-project --bare $ cd awesome-project +$ uv add "fastapi[standard]" ```
-## Virtual Environment Oluşturun { #create-a-virtual-environment } +`uv`, proje için virtual environment'i otomatik olarak oluşturur. Kendiniz oluşturmanız veya aktive etmeniz gerekmez. -Bir Python projesi üzerinde **ilk kez** çalışmaya başladığınızda, virtual environment'i **projenizin içinde** oluşturun. - -/// tip | İpucu - -Bunu her çalıştığınızda değil, **proje başına sadece bir kez** yapmanız yeterlidir. - -/// - -//// tab | `venv` - -Bir virtual environment oluşturmak için, Python ile birlikte gelen `venv` modülünü kullanabilirsiniz. +Komutları projenin environment'i içinde `uv run` ile çalıştırın, örneğin:
```console -$ python -m venv .venv +$ uv run fastapi dev ```
-/// details | Bu komut ne anlama geliyor +## Daha Fazla Bilgi Edinin { #learn-more } -* `python`: `python` adlı programı kullan -* `-m`: bir modülü script gibi çalıştır; bir sonraki kısımda hangi modül olduğunu söyleyeceğiz -* `venv`: normalde Python ile birlikte kurulu gelen `venv` modülünü kullan -* `.venv`: virtual environment'i yeni `.venv` klasörünün içine oluştur - -/// - -//// - -//// tab | `uv` - -Eğer [`uv`](https://github.com/astral-sh/uv) kuruluysa, onunla da virtual environment oluşturabilirsiniz. - -
- -```console -$ uv venv -``` - -
- -/// tip | İpucu - -Varsayılan olarak `uv`, `.venv` adlı bir klasörde virtual environment oluşturur. - -Ancak ek bir argümanla klasör adını vererek bunu özelleştirebilirsiniz. - -/// - -//// - -Bu komut `.venv` adlı bir klasörün içinde yeni bir virtual environment oluşturur. - -/// details | `.venv` veya başka bir ad - -Virtual environment'i başka bir klasörde de oluşturabilirsiniz; ancak buna `.venv` demek yaygın bir konvansiyondur. - -/// - -## Virtual Environment'i Aktif Edin { #activate-the-virtual-environment } - -Oluşturduğunuz virtual environment'i aktif edin; böylece çalıştırdığınız her Python komutu veya kurduğunuz her package onu kullanır. - -/// tip | İpucu - -Projede çalışmak için **yeni bir terminal oturumu** başlattığınız **her seferinde** bunu yapın. - -/// - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Ya da Windows'ta Bash kullanıyorsanız (örn. [Git Bash](https://gitforwindows.org/)): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -/// tip | İpucu - -Bu environment'e **yeni bir package** kurduğunuz her seferinde environment'i yeniden **aktif edin**. - -Böylece, o package'in kurduğu bir **terminal (CLI) programı** kullanıyorsanız, global olarak kurulu (ve muhtemelen ihtiyacınız olandan farklı bir versiyona sahip) başka bir program yerine, virtual environment'inizdeki programı kullanmış olursunuz. - -/// - -## Virtual Environment'in Aktif Olduğunu Kontrol Edin { #check-the-virtual-environment-is-active } - -Virtual environment'in aktif olduğunu (bir önceki komutun çalıştığını) kontrol edin. - -/// tip | İpucu - -Bu **opsiyoneldir**; ancak her şeyin beklendiği gibi çalıştığını ve hedeflediğiniz virtual environment'i kullandığınızı **kontrol etmek** için iyi bir yöntemdir. - -/// - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -Eğer `python` binary'sini projenizin içinde (bu örnekte `awesome-project`) `.venv/bin/python` yolunda gösteriyorsa, tamamdır. 🎉 - -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -Eğer `python` binary'sini projenizin içinde (bu örnekte `awesome-project`) `.venv\Scripts\python` yolunda gösteriyorsa, tamamdır. 🎉 - -//// - -## `pip`'i Yükseltin { #upgrade-pip } - -/// tip | İpucu - -[`uv`](https://github.com/astral-sh/uv) kullanıyorsanız, `pip` yerine onunla kurulum yaparsınız; dolayısıyla `pip`'i yükseltmeniz gerekmez. 😎 - -/// - -Package'leri kurmak için `pip` kullanıyorsanız (Python ile varsayılan olarak gelir), en güncel sürüme **yükseltmeniz** gerekir. - -Bir package kurarken görülen birçok garip hata, önce `pip`'i yükseltince çözülür. - -/// tip | İpucu - -Bunu genelde virtual environment'i oluşturduktan hemen sonra **bir kez** yaparsınız. - -/// - -Virtual environment'in aktif olduğundan emin olun (yukarıdaki komutla) ve sonra şunu çalıştırın: - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip | İpucu - -Bazen pip'i yükseltmeye çalışırken **`No module named pip`** hatası alabilirsiniz. - -Böyle olursa, aşağıdaki komutla pip'i kurup yükseltin: - -
- -```console -$ python -m ensurepip --upgrade - ----> 100% -``` - -
- -Bu komut pip kurulu değilse kurar ve ayrıca kurulu pip sürümünün `ensurepip` içinde bulunan sürüm kadar güncel olmasını garanti eder. - -/// - -## `.gitignore` Ekleyin { #add-gitignore } - -**Git** kullanıyorsanız (kullanmalısınız), `.venv` içindeki her şeyi Git'ten hariç tutmak için bir `.gitignore` dosyası ekleyin. - -/// tip | İpucu - -Virtual environment'i [`uv`](https://github.com/astral-sh/uv) ile oluşturduysanız, bunu zaten sizin için yaptı; bu adımı atlayabilirsiniz. 😎 - -/// - -/// tip | İpucu - -Bunu virtual environment'i oluşturduktan hemen sonra **bir kez** yapın. - -/// - -
- -```console -$ echo "*" > .venv/.gitignore -``` - -
- -/// details | Bu komut ne anlama geliyor - -* `echo "*"`: terminale `*` metnini "yazar" (sonraki kısım bunu biraz değiştiriyor) -* `>`: `>` işaretinin solundaki komutun terminale yazdıracağı çıktı, ekrana basılmak yerine sağ taraftaki dosyaya yazılsın -* `.gitignore`: metnin yazılacağı dosyanın adı - -Git'te `*` "her şey" demektir. Yani `.venv` klasörü içindeki her şeyi ignore eder. - -Bu komut, içeriği şu olan bir `.gitignore` dosyası oluşturur: - -```gitignore -* -``` - -/// - -## Package'leri Kurun { #install-packages } - -Environment'i aktif ettikten sonra, içine package kurabilirsiniz. - -/// tip | İpucu - -Projede ihtiyaç duyduğunuz package'leri ilk kez kurarken veya yükseltirken bunu **bir kez** yapın. - -Bir sürümü yükseltmeniz veya yeni bir package eklemeniz gerekirse **tekrar** yaparsınız. - -/// - -### Package'leri Doğrudan Kurun { #install-packages-directly } - -Acele ediyorsanız ve projenizin package gereksinimlerini bir dosyada belirtmek istemiyorsanız, doğrudan kurabilirsiniz. - -/// tip | İpucu - -Programınızın ihtiyaç duyduğu package'leri ve versiyonlarını bir dosyada tutmak (ör. `requirements.txt` veya `pyproject.toml`) (çok) iyi bir fikirdir. - -/// - -//// tab | `pip` - -
- -```console -$ pip install "fastapi[standard]" - ----> 100% -``` - -
- -//// - -//// tab | `uv` - -Eğer [`uv`](https://github.com/astral-sh/uv) varsa: - -
- -```console -$ uv pip install "fastapi[standard]" ----> 100% -``` - -
- -//// - -### `requirements.txt`'ten Kurun { #install-from-requirements-txt } - -Bir `requirements.txt` dosyanız varsa, içindeki package'leri kurmak için artık onu kullanabilirsiniz. - -//// tab | `pip` - -
- -```console -$ pip install -r requirements.txt ----> 100% -``` - -
- -//// - -//// tab | `uv` - -Eğer [`uv`](https://github.com/astral-sh/uv) varsa: - -
- -```console -$ uv pip install -r requirements.txt ----> 100% -``` - -
- -//// - -/// details | `requirements.txt` - -Bazı package'ler içeren bir `requirements.txt` şöyle görünebilir: - -```requirements.txt -fastapi[standard]==0.113.0 -pydantic==2.8.0 -``` - -/// - -## Programınızı Çalıştırın { #run-your-program } - -Virtual environment'i aktif ettikten sonra programınızı çalıştırabilirsiniz; program, virtual environment'in içindeki Python'ı ve oraya kurduğunuz package'leri kullanır. - -
- -```console -$ python main.py - -Hello World -``` - -
- -## Editörünüzü Yapılandırın { #configure-your-editor } - -Muhtemelen bir editör kullanırsınız; otomatik tamamlamayı ve satır içi hataları alabilmek için, editörünüzü oluşturduğunuz aynı virtual environment'i kullanacak şekilde yapılandırdığınızdan emin olun (muhtemelen otomatik algılar). - -Örneğin: - -* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) -* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) - -/// tip | İpucu - -Bunu genelde yalnızca **bir kez**, virtual environment'i oluşturduğunuzda yapmanız gerekir. - -/// - -## Virtual Environment'i Devre Dışı Bırakın { #deactivate-the-virtual-environment } - -Projeniz üzerinde işiniz bittiğinde virtual environment'i **deactivate** edebilirsiniz. - -
- -```console -$ deactivate -``` - -
- -Böylece `python` çalıştırdığınızda, o virtual environment içinden (ve oraya kurulu package'lerle) çalıştırmaya çalışmaz. - -## Çalışmaya Hazırsınız { #ready-to-work } - -Artık projeniz üzerinde çalışmaya başlayabilirsiniz. - - - -/// tip | İpucu - -Yukarıdaki her şeyin aslında ne olduğunu anlamak ister misiniz? - -Okumaya devam edin. 👇🤓 - -/// - -## Neden Virtual Environment { #why-virtual-environments } - -FastAPI ile çalışmak için [Python](https://www.python.org/) kurmanız gerekir. - -Sonrasında FastAPI'yi ve kullanmak istediğiniz diğer tüm **package**'leri **kurmanız** gerekir. - -Package kurmak için genelde Python ile gelen `pip` komutunu (veya benzeri alternatifleri) kullanırsınız. - -Ancak `pip`'i doğrudan kullanırsanız, package'ler **global Python environment**'ınıza (Python'ın global kurulumuna) yüklenir. - -### Problem { #the-problem } - -Peki package'leri global Python environment'a kurmanın sorunu ne? - -Bir noktada, muhtemelen **farklı package**'lere bağımlı birçok farklı program yazacaksınız. Ayrıca üzerinde çalıştığınız bazı projeler, aynı package'in **farklı versiyonlarına** ihtiyaç duyacak. 😱 - -Örneğin `philosophers-stone` adında bir proje oluşturduğunuzu düşünün; bu program, `harry` adlı başka bir package'e **`1` versiyonu ile** bağlı. Yani `harry`'yi kurmanız gerekir. - -```mermaid -flowchart LR - stone(philosophers-stone) -->|requires| harry-1[harry v1] -``` - -Sonra daha ileri bir zamanda `prisoner-of-azkaban` adlı başka bir proje oluşturuyorsunuz; bu proje de `harry`'ye bağlı, fakat bu proje **`harry` versiyon `3`** istiyor. - -```mermaid -flowchart LR - azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3] -``` - -Şimdi sorun şu: package'leri local bir **virtual environment** yerine global (global environment) olarak kurarsanız, `harry`'nin hangi versiyonunu kuracağınıza karar vermek zorunda kalırsınız. - -`philosophers-stone`'u çalıştırmak istiyorsanız önce `harry` versiyon `1`'i kurmanız gerekir; örneğin: - -
- -```console -$ pip install "harry==1" -``` - -
- -Sonuç olarak global Python environment'ınızda `harry` versiyon `1` kurulu olur. - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -->|requires| harry-1 - end -``` - -Fakat `prisoner-of-azkaban`'ı çalıştırmak istiyorsanız, `harry` versiyon `1`'i kaldırıp `harry` versiyon `3`'ü kurmanız gerekir (ya da sadece `3`'ü kurmak, otomatik olarak `1`'i kaldırabilir). - -
- -```console -$ pip install "harry==3" -``` - -
- -Sonuç olarak global Python environment'ınızda `harry` versiyon `3` kurulu olur. - -Ve `philosophers-stone`'u tekrar çalıştırmaya kalkarsanız, `harry` versiyon `1`'e ihtiyaç duyduğu için **çalışmama** ihtimali vardır. - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - style harry-1 fill:#ccc,stroke-dasharray: 5 5 - harry-3[harry v3] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -.-x|⛔️| harry-1 - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --> |requires| harry-3 - end -``` - -/// tip | İpucu - -Python package'lerinde **yeni versiyonlarda** **breaking change**'lerden kaçınmak oldukça yaygındır; ancak yine de daha güvenlisi, yeni versiyonları bilinçli şekilde kurmak ve mümkünse test'leri çalıştırıp her şeyin doğru çalıştığını doğrulamaktır. - -/// - -Şimdi bunu, **projelerinizin bağımlı olduğu** daha **birçok** başka **package** ile birlikte düşünün. Yönetmesi epey zorlaşır. Sonunda bazı projeleri package'lerin **uyumsuz versiyonlarıyla** çalıştırıp, bir şeylerin neden çalışmadığını anlamamak gibi durumlara düşebilirsiniz. - -Ayrıca işletim sisteminize (örn. Linux, Windows, macOS) bağlı olarak Python zaten kurulu gelmiş olabilir. Bu durumda, sisteminizin **ihtiyaç duyduğu** bazı package'ler belirli versiyonlarla önceden kurulu olabilir. Global Python environment'a package kurarsanız, işletim sistemiyle gelen bazı programları **bozma** ihtimaliniz olabilir. - -## Package'ler Nereye Kuruluyor { #where-are-packages-installed } - -Python'ı kurduğunuzda, bilgisayarınızda bazı dosyalar içeren klasörler oluşturulur. - -Bu klasörlerin bir kısmı, kurduğunuz tüm package'leri barındırmaktan sorumludur. - -Şunu çalıştırdığınızda: - -
- -```console -// Bunu şimdi çalıştırmayın, bu sadece bir örnek 🤓 -$ pip install "fastapi[standard]" ----> 100% -``` - -
- -Bu, FastAPI kodunu içeren sıkıştırılmış bir dosyayı genellikle [PyPI](https://pypi.org/project/fastapi/)'dan indirir. - -Ayrıca FastAPI'nin bağımlı olduğu diğer package'ler için de dosyaları **indirir**. - -Sonra tüm bu dosyaları **açar (extract)** ve bilgisayarınızdaki bir klasöre koyar. - -Varsayılan olarak bu indirilip çıkarılan dosyaları, Python kurulumunuzla birlikte gelen klasöre yerleştirir; yani **global environment**'a. - -## Virtual Environment Nedir { #what-are-virtual-environments } - -Global environment'da tüm package'leri bir arada tutmanın sorunlarına çözüm, çalıştığınız her proje için ayrı bir **virtual environment** kullanmaktır. - -Virtual environment, global olana çok benzeyen bir **klasördür**; bir projenin ihtiyaç duyduğu package'leri buraya kurarsınız. - -Böylece her projenin kendi virtual environment'i (`.venv` klasörü) ve kendi package'leri olur. - -```mermaid -flowchart TB - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) --->|requires| harry-1 - subgraph venv1[.venv] - harry-1[harry v1] - end - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --->|requires| harry-3 - subgraph venv2[.venv] - harry-3[harry v3] - end - end - stone-project ~~~ azkaban-project -``` - -## Virtual Environment'i Aktif Etmek Ne Demek { #what-does-activating-a-virtual-environment-mean } - -Bir virtual environment'i örneğin şununla aktif ettiğinizde: - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Ya da Windows'ta Bash kullanıyorsanız (örn. [Git Bash](https://gitforwindows.org/)): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -Bu komut, sonraki komutlarda kullanılabilecek bazı [environment variable](environment-variables.md)'ları oluşturur veya değiştirir. - -Bunlardan biri `PATH` değişkenidir. - -/// tip | İpucu - -`PATH` environment variable hakkında daha fazla bilgiyi [Environment Variables](environment-variables.md#path-environment-variable) bölümünde bulabilirsiniz. - -/// - -Bir virtual environment'i aktive etmek, onun `.venv/bin` (Linux ve macOS'ta) veya `.venv\Scripts` (Windows'ta) yolunu `PATH` environment variable'ına ekler. - -Diyelim ki environment'i aktive etmeden önce `PATH` değişkeni şöyleydi: - -//// tab | Linux, macOS - -```plaintext -/usr/bin:/bin:/usr/sbin:/sbin -``` - -Bu, sistemin programları şu klasörlerde arayacağı anlamına gelir: - -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Windows\System32 -``` - -Bu, sistemin programları şurada arayacağı anlamına gelir: - -* `C:\Windows\System32` - -//// - -Virtual environment'i aktive ettikten sonra `PATH` değişkeni şuna benzer hale gelir: - -//// tab | Linux, macOS - -```plaintext -/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -Bu, sistemin artık programları önce şurada aramaya başlayacağı anlamına gelir: - -```plaintext -/home/user/code/awesome-project/.venv/bin -``` - -diğer klasörlere bakmadan önce. - -Dolayısıyla terminale `python` yazdığınızda, sistem Python programını şurada bulur: - -```plaintext -/home/user/code/awesome-project/.venv/bin/python -``` - -ve onu kullanır. - -//// - -//// tab | Windows - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32 -``` - -Bu, sistemin artık programları önce şurada aramaya başlayacağı anlamına gelir: - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts -``` - -diğer klasörlere bakmadan önce. - -Dolayısıyla terminale `python` yazdığınızda, sistem Python programını şurada bulur: - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -ve onu kullanır. - -//// - -Önemli bir detay: virtual environment yolu `PATH` değişkeninin **en başına** eklenir. Sistem, mevcut başka herhangi bir Python'ı bulmadan **önce** bunu bulur. Böylece `python` çalıştırdığınızda, başka bir `python` (örneğin global environment'tan gelen `python`) yerine **virtual environment'taki** Python kullanılır. - -Virtual environment'i aktive etmek birkaç şeyi daha değiştirir; ancak yaptığı en önemli işlerden biri budur. - -## Virtual Environment'i Kontrol Etmek { #checking-a-virtual-environment } - -Bir virtual environment'in aktif olup olmadığını örneğin şununla kontrol ettiğinizde: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -//// - -Bu, kullanılacak `python` programının **virtual environment'in içindeki** Python olduğu anlamına gelir. - -Linux ve macOS'ta `which`, Windows PowerShell'de ise `Get-Command` kullanırsınız. - -Bu komutun çalışma mantığı şudur: `PATH` environment variable içindeki **her yolu sırayla** dolaşır, `python` adlı programı arar. Bulduğunda, size o programın **dosya yolunu** gösterir. - -En önemli kısım şu: `python` dediğinizde çalışacak olan "`python`" tam olarak budur. - -Yani doğru virtual environment'da olup olmadığınızı doğrulayabilirsiniz. - -/// tip | İpucu - -Bir virtual environment'i aktive etmek kolaydır; sonra o Python ile kalıp **başka bir projeye geçmek** de kolaydır. - -Bu durumda ikinci proje, başka bir projenin virtual environment'ından gelen **yanlış Python**'ı kullandığınız için **çalışmayabilir**. - -Hangi `python`'ın kullanıldığını kontrol edebilmek bu yüzden faydalıdır. 🤓 - -/// - -## Neden Virtual Environment'i Deactivate Edelim { #why-deactivate-a-virtual-environment } - -Örneğin `philosophers-stone` projesi üzerinde çalışıyor olabilirsiniz; **o virtual environment'i aktive eder**, package kurar ve o environment ile çalışırsınız. - -Sonra **başka bir proje** olan `prisoner-of-azkaban` üzerinde çalışmak istersiniz. - -O projeye gidersiniz: - -
- -```console -$ cd ~/code/prisoner-of-azkaban -``` - -
- -Eğer `philosophers-stone` için olan virtual environment'i deactivate etmezseniz, terminalde `python` çalıştırdığınızda `philosophers-stone`'dan gelen Python'ı kullanmaya çalışır. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -$ python main.py - -// sirius import edilirken hata, kurulu değil 😱 -Traceback (most recent call last): - File "main.py", line 1, in - import sirius -``` - -
- -Ama virtual environment'i deactivate edip `prisoner-of-azkaban` için yeni olanı aktive ederseniz, `python` çalıştırdığınızda `prisoner-of-azkaban` içindeki virtual environment'dan gelen Python kullanılır. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -// Deactivate etmek için eski klasörde olmanız gerekmez; nerede olursanız olun, hatta diğer projeye geçtikten sonra bile yapabilirsiniz 😎 -$ deactivate - -// prisoner-of-azkaban/.venv içindeki virtual environment'i aktive edin 🚀 -$ source .venv/bin/activate - -// Artık python çalıştırdığınızda, bu virtual environment'e kurulu olan sirius package'ini bulacak ✨ -$ python main.py - -I solemnly swear 🐺 -``` - -
- -## Alternatifler { #alternatives } - -Bu, başlamanız için basit bir rehber ve alttaki mekanizmaların nasıl çalıştığını öğretmeyi amaçlıyor. - -Virtual environment'leri, package bağımlılıklarını (requirements) ve projeleri yönetmek için birçok **alternatif** vardır. - -Hazır olduğunuzda ve package bağımlılıkları, virtual environment'ler vb. dahil **tüm projeyi yönetmek** için bir tool kullanmak istediğinizde, [uv](https://github.com/astral-sh/uv)'yi denemenizi öneririm. - -`uv` birçok şey yapabilir, örneğin: - -* Sizin için **Python kurabilir**, farklı sürümler dahil -* Projelerinizin **virtual environment**'ini yönetebilir -* **Package** kurabilir -* Projeniz için package **bağımlılıklarını ve versiyonlarını** yönetebilir -* Bağımlılıkları dahil, kurulacak package ve versiyonların **tam (exact)** bir setini garanti edebilir; böylece geliştirirken bilgisayarınızda çalıştırdığınız projeyi production'da da birebir aynı şekilde çalıştırabileceğinizden emin olursunuz; buna **locking** denir -* Ve daha birçok şey - -## Sonuç { #conclusion } - -Buradaki her şeyi okuduysanız ve anladıysanız, artık birçok geliştiriciden **çok daha fazla** virtual environment bilgisine sahipsiniz. 🤓 - -Bu detayları bilmek, ileride karmaşık görünen bir sorunu debug ederken büyük olasılıkla işinize yarayacak; çünkü **altta nasıl çalıştığını** biliyor olacaksınız. 😎 +Virtual environment'lerin altta nasıl çalıştığını, activation'ı ve alternatif `python -m venv` ile `pip` workflow'unu öğrenmek için [Virtual Environments rehberini](https://tiangolo.com/guides/virtual-environments/) okuyun. diff --git a/docs/uk/docs/advanced/additional-responses.md b/docs/uk/docs/advanced/additional-responses.md index 3b30645..d17af5c 100644 --- a/docs/uk/docs/advanced/additional-responses.md +++ b/docs/uk/docs/advanced/additional-responses.md @@ -16,7 +16,7 @@ ## Додаткова відповідь з `model` { #additional-response-with-model } -Ви можете передати вашим декораторам операцій шляху параметр `responses`. +Ви можете передати вашим *декораторам операцій шляху* параметр `responses`. Він приймає `dict`: ключі - це коди статусу для кожної відповіді (наприклад, `200`), а значення - інші `dict` з інформацією для кожної з них. @@ -49,7 +49,7 @@ /// -Згенеровані відповіді в OpenAPI для цієї операції шляху будуть такими: +Згенеровані відповіді в OpenAPI для цієї *операції шляху* будуть такими: ```JSON hl_lines="3-12" { @@ -173,7 +173,7 @@ Можна використати цей самий параметр `responses`, щоб додати різні типи медіа для тієї ж основної відповіді. -Наприклад, можна додати додатковий тип медіа `image/png`, оголосивши, що ваша операція шляху може повертати JSON-об'єкт (з типом медіа `application/json`) або PNG-зображення: +Наприклад, можна додати додатковий тип медіа `image/png`, оголосивши, що ваша *операція шляху* може повертати JSON-об'єкт (з типом медіа `application/json`) або PNG-зображення: {* ../../docs_src/additional_responses/tutorial002_py310.py hl[17:22,26] *} @@ -211,7 +211,7 @@ ## Комбінуйте попередньо визначені та власні відповіді { #combine-predefined-responses-and-custom-ones } -Можливо, ви захочете мати кілька попередньо визначених відповідей, що застосовуються до багатьох операцій шляху, але поєднувати їх із власними відповідями, потрібними для кожної операції шляху. +Можливо, ви захочете мати кілька попередньо визначених відповідей, що застосовуються до багатьох *операцій шляху*, але поєднувати їх із власними відповідями, потрібними для кожної *операції шляху*. Для таких випадків можна скористатися прийомом Python «розпакування» `dict` за допомогою `**dict_to_unpack`: @@ -233,7 +233,7 @@ new_dict = {**old_dict, "new key": "new value"} } ``` -Цей прийом можна використати, щоб перевикористовувати деякі попередньо визначені відповіді у ваших операціях шляху та поєднувати їх із додатковими власними. +Цей прийом можна використати, щоб перевикористовувати деякі попередньо визначені відповіді у ваших *операціях шляху* та поєднувати їх із додатковими власними. Наприклад: @@ -243,5 +243,5 @@ new_dict = {**old_dict, "new key": "new value"} Щоб побачити, що саме можна включати у відповіді, ознайомтеся з цими розділами специфікації OpenAPI: -- [Об'єкт відповідей OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object), він включає `Response Object`. -- [Об'єкт відповіді OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object), ви можете включити будь-що з цього безпосередньо в кожну відповідь у параметрі `responses`. Зокрема `description`, `headers`, `content` (усередині нього ви оголошуєте різні типи медіа та Схеми JSON) і `links`. +- [Об'єкт відповідей OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object), він включає `Response Object`. +- [Об'єкт відповіді OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object), ви можете включити будь-що з цього безпосередньо в кожну відповідь у параметрі `responses`. Зокрема `description`, `headers`, `content` (усередині нього ви оголошуєте різні типи медіа та Схеми JSON) і `links`. diff --git a/docs/uk/docs/advanced/async-tests.md b/docs/uk/docs/advanced/async-tests.md index 9f19bed..3cdcba7 100644 --- a/docs/uk/docs/advanced/async-tests.md +++ b/docs/uk/docs/advanced/async-tests.md @@ -45,7 +45,7 @@
```console -$ pytest +$ uv run pytest ---> 100% ``` diff --git a/docs/uk/docs/advanced/behind-a-proxy.md b/docs/uk/docs/advanced/behind-a-proxy.md index 55fc248..67b382a 100644 --- a/docs/uk/docs/advanced/behind-a-proxy.md +++ b/docs/uk/docs/advanced/behind-a-proxy.md @@ -33,7 +33,7 @@
```console -$ fastapi run --forwarded-allow-ips="*" +$ uv run fastapi run --forwarded-allow-ips="*" INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -91,9 +91,9 @@ sequenceDiagram Ці заголовки зберігають інформацію про оригінальний запит, яка інакше була б втрачена: -- X-Forwarded-For: оригінальна IP-адреса клієнта -- X-Forwarded-Proto: оригінальний протокол (`https`) -- X-Forwarded-Host: оригінальний хост (`mysuperapp.com`) +* **X-Forwarded-For**: оригінальна IP-адреса клієнта +* **X-Forwarded-Proto**: оригінальний протокол (`https`) +* **X-Forwarded-Host**: оригінальний хост (`mysuperapp.com`) Коли **FastAPI CLI** налаштовано з `--forwarded-allow-ips`, він довіряє цим заголовкам і використовує їх, наприклад, для побудови коректних URL-адрес у перенаправленнях. @@ -170,7 +170,7 @@ IP `0.0.0.0` зазвичай означає, що програма слухає
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -200,7 +200,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -253,7 +253,7 @@ Uvicorn очікуватиме, що представник буде зверт Ви можете легко провести експеримент локально з вилученим префіксом шляху, використовуючи [Traefik](https://docs.traefik.io/). -[Завантажте Traefik](https://github.com/containous/traefik/releases), це один бінарний файл, ви можете розпакувати архів і запустити його безпосередньо з термінала. +[Завантажте Traefik](https://github.com/traefik/traefik/releases), це один бінарний файл, ви можете розпакувати архів і запустити його безпосередньо з термінала. Потім створіть файл `traefik.toml` з таким вмістом: @@ -321,7 +321,7 @@ INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/uk/docs/advanced/dataclasses.md b/docs/uk/docs/advanced/dataclasses.md index f019183..d488450 100644 --- a/docs/uk/docs/advanced/dataclasses.md +++ b/docs/uk/docs/advanced/dataclasses.md @@ -1,13 +1,12 @@ # Використання dataclasses { #using-dataclasses } - FastAPI побудовано поверх **Pydantic**, і я показував вам, як використовувати моделі Pydantic для оголошення запитів і відповідей. Але FastAPI також підтримує використання [`dataclasses`](https://docs.python.org/3/library/dataclasses.html) таким самим чином: {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -Це підтримується завдяки **Pydantic**, адже він має [внутрішню підтримку `dataclasses`](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel). +Це підтримується завдяки **Pydantic**, адже він має [внутрішню підтримку `dataclasses`](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/#usage-of-stdlib-dataclasses-with-basemodel). Тож навіть із наведеним вище кодом, який явно не використовує Pydantic, FastAPI використовує Pydantic, щоб перетворити стандартні dataclasses у власний варіант dataclasses Pydantic. @@ -89,7 +88,7 @@ Dataclass буде автоматично перетворено на dataclass Можна поєднувати `dataclasses` з іншими моделями Pydantic, наслідувати їх, включати у власні моделі тощо. -Щоб дізнатися більше, перегляньте [документацію Pydantic про dataclasses](https://docs.pydantic.dev/latest/concepts/dataclasses/). +Щоб дізнатися більше, перегляньте [документацію Pydantic про dataclasses](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/). ## Версія { #version } diff --git a/docs/uk/docs/advanced/events.md b/docs/uk/docs/advanced/events.md index bc6e784..124a455 100644 --- a/docs/uk/docs/advanced/events.md +++ b/docs/uk/docs/advanced/events.md @@ -154,7 +154,7 @@ async with lifespan(app): /// note | Примітка -Ви можете прочитати більше про обробники `lifespan` Starlette у [документації Starlette про Lifespan](https://www.starlette.dev/lifespan/). +Ви можете прочитати більше про обробники `lifespan` Starlette у [документації Starlette про Lifespan](https://starlette.dev/lifespan/). Зокрема, як працювати зі станом тривалості життя, який можна використовувати в інших ділянках вашого коду. diff --git a/docs/uk/docs/advanced/generate-clients.md b/docs/uk/docs/advanced/generate-clients.md index 0fad82d..9919d99 100644 --- a/docs/uk/docs/advanced/generate-clients.md +++ b/docs/uk/docs/advanced/generate-clients.md @@ -12,7 +12,7 @@ Для **клієнтів TypeScript** [Hey API](https://heyapi.dev/) - спеціалізоване рішення, що надає оптимізований досвід для екосистеми TypeScript. -Більше генераторів SDK ви можете знайти на [OpenAPI.Tools](https://openapi.tools/#sdk). +Більше генераторів SDK ви можете знайти на [OpenAPI.Tools](https://openapi.tools/categories/sdk-generators). /// tip | Порада diff --git a/docs/uk/docs/advanced/middleware.md b/docs/uk/docs/advanced/middleware.md index d24bc4a..6d7a5e1 100644 --- a/docs/uk/docs/advanced/middleware.md +++ b/docs/uk/docs/advanced/middleware.md @@ -1,20 +1,20 @@ # Просунуте проміжне програмне забезпечення { #advanced-middleware } -У головному навчальному посібнику ви читали, як додати [Користувацьке проміжне ПЗ](../tutorial/middleware.md) до вашого застосунку. +У головному навчальному посібнику ви читали, як додати [Користувацьке проміжне програмне забезпечення](../tutorial/middleware.md) до вашого застосунку. Також ви читали, як обробляти [CORS за допомогою `CORSMiddleware`](../tutorial/cors.md). -У цьому розділі розглянемо, як використовувати інше проміжне ПЗ. +У цьому розділі розглянемо, як використовувати інше проміжне програмне забезпечення. -## Додавання middleware ASGI { #adding-asgi-middlewares } +## Додавання проміжного програмного забезпечення ASGI { #adding-asgi-middlewares } -Оскільки **FastAPI** базується на Starlette і реалізує специфікацію ASGI, ви можете використовувати будь-яке проміжне ПЗ ASGI. +Оскільки **FastAPI** базується на Starlette і реалізує специфікацію ASGI, ви можете використовувати будь-яке проміжне програмне забезпечення ASGI. -Middleware не обов'язково має бути створене саме для FastAPI або Starlette, головне - щоб воно відповідало специфікації ASGI. +Проміжне програмне забезпечення не обов'язково має бути створене саме для FastAPI або Starlette, головне - щоб воно відповідало специфікації ASGI. -Загалом, middleware ASGI — це класи, які очікують отримати застосунок ASGI як перший аргумент. +Загалом, компоненти проміжного програмного забезпечення ASGI - це класи, які очікують отримати застосунок ASGI як перший аргумент. -Тож у документації до сторонніх middleware ASGI вам, імовірно, порадять зробити приблизно так: +Тож у документації до сторонніх компонентів проміжного програмного забезпечення ASGI вам, імовірно, порадять зробити приблизно так: ```Python from unicorn import UnicornMiddleware @@ -24,7 +24,7 @@ app = SomeASGIApp() new_app = UnicornMiddleware(app, some_config="rainbow") ``` -Але FastAPI (точніше Starlette) надає простіший спосіб, який гарантує, що внутрішнє middleware обробляє помилки сервера, а користувацькі обробники винятків працюють коректно. +Але FastAPI (точніше Starlette) надає простіший спосіб, який гарантує, що внутрішнє проміжне програмне забезпечення обробляє помилки сервера, а користувацькі обробники винятків працюють коректно. Для цього використовуйте `app.add_middleware()` (як у прикладі для CORS). @@ -37,17 +37,17 @@ app = FastAPI() app.add_middleware(UnicornMiddleware, some_config="rainbow") ``` -`app.add_middleware()` приймає клас middleware як перший аргумент і будь-які додаткові аргументи, що будуть передані цьому middleware. +`app.add_middleware()` приймає клас проміжного програмного забезпечення як перший аргумент і будь-які додаткові аргументи, що будуть передані цьому проміжному програмному забезпеченню. -## Вбудоване middleware { #integrated-middlewares } +## Вбудоване проміжне програмне забезпечення { #integrated-middlewares } -**FastAPI** містить кілька middleware для поширених випадків використання, далі розглянемо, як їх використовувати. +**FastAPI** містить кілька компонентів проміжного програмного забезпечення для поширених випадків використання, далі розглянемо, як їх використовувати. /// note | Технічні деталі У наступних прикладах ви також можете використовувати `from starlette.middleware.something import SomethingMiddleware`. -**FastAPI** надає кілька middleware у `fastapi.middleware` виключно для зручності розробника. Але більшість доступних middleware походять безпосередньо зі Starlette. +**FastAPI** надає кілька компонентів проміжного програмного забезпечення у `fastapi.middleware` виключно для зручності розробника. Але більшість доступних компонентів проміжного програмного забезпечення походять безпосередньо зі Starlette. /// @@ -61,14 +61,14 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") ## `TrustedHostMiddleware` { #trustedhostmiddleware } -Примушує, щоб усі вхідні запити мали коректно встановлений заголовок `Host`, щоб захиститися від атак HTTP Host Header. +Примушує, щоб усі вхідні запити мали коректно встановлений заголовок `Host`, щоб захиститися від атак через заголовок HTTP Host. {* ../../docs_src/advanced_middleware/tutorial002_py310.py hl[2,6:8] *} Підтримуються такі аргументи: -- `allowed_hosts` - Список доменних імен, які слід дозволити як імена хостів. Підтримуються домени з «дикою картою», такі як `*.example.com`, для зіставлення піддоменів. Щоб дозволити будь-яке ім'я хоста, або використовуйте `allowed_hosts=["*"]`, або не додавайте це middleware. -- `www_redirect` - Якщо встановлено True, запити до не-www версій дозволених хостів буде перенаправлено до їхніх www-варіантів. Типово `True`. +* `allowed_hosts` - Список доменних імен, які слід дозволити як імена хостів. Підтримуються домени з «дикою картою», такі як `*.example.com`, для зіставлення піддоменів. Щоб дозволити будь-яке ім'я хоста, або використовуйте `allowed_hosts=["*"]`, або не додавайте це проміжне програмне забезпечення. +* `www_redirect` - Якщо встановлено True, запити до не-www версій дозволених хостів буде перенаправлено до їхніх www-варіантів. Типово `True`. Якщо вхідний запит не проходить перевірку, буде надіслано відповідь `400`. @@ -76,22 +76,22 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") Обробляє відповіді GZip для будь-якого запиту, що містить `"gzip"` у заголовку `Accept-Encoding`. -Middleware обробляє як стандартні, так і потокові відповіді. +Проміжне програмне забезпечення обробляє як стандартні, так і потокові відповіді. {* ../../docs_src/advanced_middleware/tutorial003_py310.py hl[2,6] *} Підтримуються такі аргументи: -- `minimum_size` - Не GZip-увати відповіді, менші за цей мінімальний розмір у байтах. Типово `500`. -- `compresslevel` - Використовується під час стиснення GZip. Це ціле число в діапазоні від 1 до 9. Типово `9`. Менше значення дає швидше стиснення, але більший розмір файлів; більше значення дає повільніше стиснення, але менший розмір файлів. +* `minimum_size` - Не GZip-увати відповіді, менші за цей мінімальний розмір у байтах. Типово `500`. +* `compresslevel` - Використовується під час стиснення GZip. Це ціле число в діапазоні від 1 до 9. Типово `9`. Менше значення дає швидше стиснення, але більший розмір файлів; більше значення дає повільніше стиснення, але менший розмір файлів. -## Інше middleware { #other-middlewares } +## Інше проміжне програмне забезпечення { #other-middlewares } -Є багато іншого проміжного ПЗ ASGI. +Є багато іншого проміжного програмного забезпечення ASGI. Наприклад: -- [`ProxyHeadersMiddleware` з Uvicorn](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) -- [MessagePack](https://github.com/florimondmanca/msgpack-asgi) +* [`ProxyHeadersMiddleware` від Uvicorn](https://github.com/Kludex/uvicorn/blob/main/uvicorn/middleware/proxy_headers.py) +* [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -Щоб переглянути інші доступні middleware, ознайомтеся з [документацією Starlette щодо middleware](https://www.starlette.dev/middleware/) та [списком ASGI Awesome](https://github.com/florimondmanca/awesome-asgi). +Щоб переглянути інше доступне проміжне програмне забезпечення, ознайомтеся з [документацією Starlette щодо проміжного програмного забезпечення](https://starlette.dev/middleware/) та [списком ASGI Awesome](https://github.com/florimondmanca/awesome-asgi). diff --git a/docs/uk/docs/advanced/openapi-callbacks.md b/docs/uk/docs/advanced/openapi-callbacks.md index ab0eb15..9d733c0 100644 --- a/docs/uk/docs/advanced/openapi-callbacks.md +++ b/docs/uk/docs/advanced/openapi-callbacks.md @@ -18,10 +18,10 @@ Потім ваш API буде (уявімо): -- Надсилати рахунок деякому клієнту зовнішнього розробника. -- Отримувати оплату. -- Надсилати сповіщення назад користувачу API (зовнішньому розробнику). - - Це буде зроблено шляхом надсилання POST-запиту (з *вашого API*) до деякого *зовнішнього API*, наданого тим зовнішнім розробником (це і є «зворотний виклик»). +* Надсилати рахунок деякому клієнту зовнішнього розробника. +* Отримувати оплату. +* Надсилати сповіщення назад користувачу API (зовнішньому розробнику). + * Це буде зроблено шляхом надсилання POST-запиту (з *вашого API*) до деякого *зовнішнього API*, наданого тим зовнішнім розробником (це і є «зворотний виклик»). ## Звичайний застосунок **FastAPI** { #the-normal-fastapi-app } @@ -35,7 +35,7 @@ /// tip | Порада -Параметр запиту `callback_url` використовує тип Pydantic [Url](https://docs.pydantic.dev/latest/api/networks/). +Параметр запиту `callback_url` використовує тип Pydantic [Url](https://pydantic.dev/docs/validation/latest/api/pydantic/networks/). /// @@ -98,19 +98,19 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) Вона має виглядати як звичайна *операція шляху* FastAPI: -- Ймовірно має містити оголошення тіла, яке вона приймає, наприклад `body: InvoiceEvent`. -- І також може містити оголошення відповіді, яку вона повертає, наприклад `response_model=InvoiceEventReceived`. +* Ймовірно має містити оголошення тіла, яке вона приймає, наприклад `body: InvoiceEvent`. +* І також може містити оголошення відповіді, яку вона повертає, наприклад `response_model=InvoiceEventReceived`. {* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[14:16,19:20,26:30] *} Є 2 основні відмінності від звичайної *операції шляху*: -- Їй не потрібен реальний код, адже ваш застосунок ніколи не викликатиме цей код. Вона використовується лише для документування *зовнішнього API*. Тому функція може просто містити `pass`. -- *Шлях* може містити [вираз OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) (див. нижче), де можна використовувати змінні з параметрами та частини оригінального запиту, надісланого до *вашого API*. +* Їй не потрібен реальний код, адже ваш застосунок ніколи не викликатиме цей код. Вона використовується лише для документування *зовнішнього API*. Тому функція може просто містити `pass`. +* *Шлях* може містити [вираз OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression) (див. нижче), де можна використовувати змінні з параметрами та частини оригінального запиту, надісланого до *вашого API*. ### Вираз шляху зворотного виклику { #the-callback-path-expression } -*Шлях* зворотного виклику може містити [вираз OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression), який включає частини оригінального запиту, надісланого до *вашого API*. +*Шлях* зворотного виклику може містити [вираз OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression), який включає частини оригінального запиту, надісланого до *вашого API*. У цьому випадку це `str`: diff --git a/docs/uk/docs/advanced/response-cookies.md b/docs/uk/docs/advanced/response-cookies.md index 2e062ad..434eac7 100644 --- a/docs/uk/docs/advanced/response-cookies.md +++ b/docs/uk/docs/advanced/response-cookies.md @@ -48,4 +48,4 @@ /// -Щоб побачити всі доступні параметри та опції, перегляньте [документацію в Starlette](https://www.starlette.dev/responses/#set-cookie). +Щоб побачити всі доступні параметри та опції, перегляньте [документацію в Starlette](https://starlette.dev/responses/#set-cookie). diff --git a/docs/uk/docs/advanced/response-headers.md b/docs/uk/docs/advanced/response-headers.md index 67f1f0c..05519e6 100644 --- a/docs/uk/docs/advanced/response-headers.md +++ b/docs/uk/docs/advanced/response-headers.md @@ -2,7 +2,7 @@ ## Використовуйте параметр `Response` { #use-a-response-parameter } -Ви можете оголосити параметр типу `Response` у вашій функції операції шляху (так само, як і для кукі). +Ви можете оголосити параметр типу `Response` у вашій *функції операції шляху* (так само, як і для кукі). Потім ви можете встановлювати заголовки в цьому *тимчасовому* обʼєкті відповіді. @@ -38,4 +38,4 @@ Майте на увазі, що власні пропрієтарні заголовки можна додавати [за допомогою префікса `X-`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). -Але якщо у вас є власні заголовки, які клієнт у браузері має бачити, вам потрібно додати їх у вашу конфігурацію CORS (докладніше в [CORS (спільне використання ресурсів між різними джерелами)](../tutorial/cors.md)), використовуючи параметр `expose_headers`, задокументований у [документації Starlette щодо CORS](https://www.starlette.dev/middleware/#corsmiddleware). +Але якщо у вас є власні заголовки, які клієнт у браузері має бачити, вам потрібно додати їх у вашу конфігурацію CORS (докладніше в [CORS (спільне використання ресурсів між різними джерелами)](../tutorial/cors.md)), використовуючи параметр `expose_headers`, задокументований у [документації Starlette щодо CORS](https://starlette.dev/middleware/#corsmiddleware). diff --git a/docs/uk/docs/advanced/settings.md b/docs/uk/docs/advanced/settings.md index 867eb23..71d8ed7 100644 --- a/docs/uk/docs/advanced/settings.md +++ b/docs/uk/docs/advanced/settings.md @@ -6,41 +6,45 @@ З цієї причини поширено надавати їх у змінних оточення, які зчитуються застосунком. +**Змінна оточення** (також відома як **env var**) - це значення, яке існує поза кодом Python, в операційній системі, і може бути прочитане вашим застосунком та іншими програмами. + +Ви можете створити змінну оточення для команди під час її запуску. Нижче ви побачите команди для конкретних платформ. + /// tip | Порада -Щоб зрозуміти змінні оточення, ви можете прочитати [Змінні оточення](../environment-variables.md). +Прочитайте [посібник зі змінних оточення](https://tiangolo.com/guides/environment-variables/) для докладного пояснення того, як працюють змінні оточення. /// ## Типи та перевірка { #types-and-validation } -Ці змінні оточення можуть містити лише текстові строки, оскільки вони зовнішні до Python і мають бути сумісні з іншими програмами та рештою системи (і навіть з різними операційними системами, як-от Linux, Windows, macOS). +Ці змінні оточення можуть містити лише текстові строки, оскільки вони зовнішні до Python і мають бути сумісні з іншими програмами та рештою системи (і навіть з різними операційними системами, як-от Linux, Windows і macOS). Це означає, що будь-яке значення, прочитане в Python зі змінної оточення, буде `str`, і будь-яке перетворення в інший тип або будь-яка перевірка мають виконуватися в коді. ## Pydantic `Settings` { #pydantic-settings } -На щастя, Pydantic надає чудовий інструмент для обробки цих налаштувань із змінних оточення - [Pydantic: Settings management](https://docs.pydantic.dev/latest/concepts/pydantic_settings/). +На щастя, Pydantic надає чудовий інструмент для обробки цих налаштувань із змінних оточення - [Pydantic: Settings management](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/). ### Встановіть `pydantic-settings` { #install-pydantic-settings } -Спершу переконайтеся, що ви створили [віртуальне оточення](../virtual-environments.md), активували його, а потім встановили пакет `pydantic-settings`: +Додайте пакет `pydantic-settings` до вашого проєкту:
```console -$ pip install pydantic-settings +$ uv add pydantic-settings ---> 100% ```
-Він також входить у склад, якщо ви встановлюєте додаткові можливості «all» за допомогою: +Він також входить у склад, якщо ви встановлюєте додаткові можливості `all` за допомогою:
```console -$ pip install "fastapi[all]" +$ uv add "fastapi[all]" ---> 100% ``` @@ -76,19 +80,39 @@ $ pip install "fastapi[all]" Далі ви б запустили сервер, передаючи конфігурації як змінні оточення, наприклад, ви можете встановити `ADMIN_EMAIL` і `APP_NAME` так: +//// tab | Linux, macOS, Windows Bash +
```console -$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py +$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uv run fastapi run main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
+//// + +//// tab | Windows PowerShell + +
+ +```console +$ $Env:ADMIN_EMAIL = "deadpool@example.com" +$ $Env:APP_NAME = "ChimichangApp" +$ uv run fastapi run main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +//// + /// tip | Порада -Щоб встановити кілька змінних оточення для однієї команди, просто розділіть їх пробілами і розмістіть усі перед командою. +У Bash, щоб встановити кілька змінних оточення для однієї команди, розділіть їх пробілом і розмістіть усі перед командою. /// @@ -172,11 +196,11 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p /// -Pydantic має підтримку читання з таких типів файлів за допомогою зовнішньої бібліотеки. Ви можете дізнатися більше тут: [Pydantic Settings: Dotenv (.env) support](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support). +Pydantic має підтримку читання з таких типів файлів за допомогою зовнішньої бібліотеки. Ви можете дізнатися більше тут: [Pydantic Settings: Dotenv (.env) support](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#dotenv-env-support). /// tip | Порада -Щоб це працювало, потрібно виконати `pip install python-dotenv`. +Щоб це працювало, додайте `python-dotenv` до вашого проєкту за допомогою `uv add python-dotenv`. /// @@ -197,7 +221,7 @@ APP_NAME="ChimichangApp" /// tip | Порада -Атрибут `model_config` використовується лише для конфігурації Pydantic. Докладніше: [Pydantic: Concepts: Configuration](https://docs.pydantic.dev/latest/concepts/config/). +Атрибут `model_config` використовується лише для конфігурації Pydantic. Докладніше: [Pydantic: Concepts: Configuration](https://pydantic.dev/docs/validation/latest/concepts/config/). /// diff --git a/docs/uk/docs/advanced/sub-applications.md b/docs/uk/docs/advanced/sub-applications.md index bc10582..b522724 100644 --- a/docs/uk/docs/advanced/sub-applications.md +++ b/docs/uk/docs/advanced/sub-applications.md @@ -35,7 +35,7 @@
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/uk/docs/advanced/templates.md b/docs/uk/docs/advanced/templates.md index 3d9f96e..b054f27 100644 --- a/docs/uk/docs/advanced/templates.md +++ b/docs/uk/docs/advanced/templates.md @@ -8,12 +8,12 @@ ## Встановіть залежності { #install-dependencies } -Переконайтеся, що ви створили [віртуальне оточення](../virtual-environments.md), активували його та встановили `jinja2`: +Додайте `jinja2` до вашого проєкту:
```console -$ pip install jinja2 +$ uv add jinja2 ---> 100% ``` @@ -22,10 +22,10 @@ $ pip install jinja2 ## Використання `Jinja2Templates` { #using-jinja2templates } -- Імпортуйте `Jinja2Templates`. -- Створіть об'єкт `templates`, який ви зможете перевикористовувати. -- Оголосіть параметр `Request` в *операції шляху*, яка повертатиме шаблон. -- Використайте створені `templates`, щоб зрендерити та повернути `TemplateResponse`; передайте назву шаблону, об'єкт `request` і словник «контекст» з парами ключ-значення, які будуть використані всередині шаблону Jinja2. +* Імпортуйте `Jinja2Templates`. +* Створіть об'єкт `templates`, який ви зможете перевикористовувати. +* Оголосіть параметр `Request` в *операції шляху*, яка повертатиме шаблон. +* Використайте створені `templates`, щоб зрендерити та повернути `TemplateResponse`; передайте назву шаблону, об'єкт `request` і словник «контекст» з парами ключ-значення, які будуть використані всередині шаблону Jinja2. {* ../../docs_src/templates/tutorial001_py310.py hl[4,11,15:18] *} @@ -123,4 +123,4 @@ Item ID: 42 ## Детальніше { #more-details } -Докладніше, зокрема як тестувати шаблони, дивіться [документацію Starlette щодо шаблонів](https://www.starlette.dev/templates/). +Докладніше, зокрема як тестувати шаблони, дивіться [документацію Starlette щодо шаблонів](https://starlette.dev/templates/). diff --git a/docs/uk/docs/advanced/testing-events.md b/docs/uk/docs/advanced/testing-events.md index 040b4f7..1749a00 100644 --- a/docs/uk/docs/advanced/testing-events.md +++ b/docs/uk/docs/advanced/testing-events.md @@ -4,7 +4,8 @@ {* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *} -Ви можете прочитати більше у [«Запуск тривалості життя у тестах на офіційному сайті документації Starlette.»](https://www.starlette.dev/lifespan/#running-lifespan-in-tests) + +Ви можете прочитати більше деталей про [«Запуск тривалості життя у тестах на офіційному сайті документації Starlette.»](https://starlette.dev/lifespan/#running-lifespan-in-tests) Для застарілих подій `startup` і `shutdown` ви можете використовувати `TestClient` так: diff --git a/docs/uk/docs/advanced/testing-websockets.md b/docs/uk/docs/advanced/testing-websockets.md index 717bffa..68ac290 100644 --- a/docs/uk/docs/advanced/testing-websockets.md +++ b/docs/uk/docs/advanced/testing-websockets.md @@ -8,6 +8,6 @@ /// note | Примітка -Докладніше дивіться документацію Starlette щодо [тестування WebSocket](https://www.starlette.dev/testclient/#testing-websocket-sessions). +Докладніше дивіться документацію Starlette щодо [тестування WebSocket](https://starlette.dev/testclient/#testing-websocket-sessions). /// diff --git a/docs/uk/docs/advanced/using-request-directly.md b/docs/uk/docs/advanced/using-request-directly.md index 330a0b7..1070443 100644 --- a/docs/uk/docs/advanced/using-request-directly.md +++ b/docs/uk/docs/advanced/using-request-directly.md @@ -14,7 +14,7 @@ ## Деталі про об'єкт `Request` { #details-about-the-request-object } -Оскільки під капотом **FastAPI** - це **Starlette** з шаром інструментів зверху, ви можете за потреби використовувати об'єкт [`Request`](https://www.starlette.dev/requests/) Starlette безпосередньо. +Оскільки під капотом **FastAPI** - це **Starlette** з шаром інструментів зверху, ви можете за потреби використовувати об'єкт [`Request`](https://starlette.dev/requests/) Starlette безпосередньо. Це також означає, що якщо ви отримуєте дані безпосередньо з об'єкта `Request` (наприклад, читаєте тіло), FastAPI не буде їх перевіряти, перетворювати або документувати (через OpenAPI для автоматичного інтерфейсу користувача API). @@ -24,13 +24,13 @@ ## Використовуйте об'єкт `Request` безпосередньо { #use-the-request-object-directly } -Припустімо, ви хочете отримати IP-адресу/хост клієнта всередині вашої функції операції шляху. +Припустімо, ви хочете отримати IP-адресу/хост клієнта всередині вашої *функції операції шляху*. Для цього потрібно звернутися до запиту безпосередньо. {* ../../docs_src/using_request_directly/tutorial001_py310.py hl[1,7:8] *} -Якщо вказати у функції операції шляху параметр типу `Request`, **FastAPI** передасть у нього об'єкт `Request`. +Якщо вказати у *функції операції шляху* параметр типу `Request`, **FastAPI** передасть у нього об'єкт `Request`. /// tip | Порада @@ -44,7 +44,7 @@ ## Документація `Request` { #request-documentation } -Докладніше про [об'єкт [`Request`] на офіційному сайті документації Starlette](https://www.starlette.dev/requests/). +Докладніше про [об'єкт [`Request`] на офіційному сайті документації Starlette](https://starlette.dev/requests/). /// note | Технічні деталі diff --git a/docs/uk/docs/advanced/websockets.md b/docs/uk/docs/advanced/websockets.md index 1d96933..249321d 100644 --- a/docs/uk/docs/advanced/websockets.md +++ b/docs/uk/docs/advanced/websockets.md @@ -4,12 +4,12 @@ ## Встановіть `websockets` { #install-websockets } -Переконайтеся, що ви створили [віртуальне оточення](../virtual-environments.md), активували його та встановили `websockets` (бібліотеку Python, що полегшує використання протоколу «WebSocket»): +Додайте `websockets` (бібліотеку Python, що полегшує використання протоколу «WebSocket») до вашого проєкту:
```console -$ pip install websockets +$ uv add websockets ---> 100% ``` @@ -69,7 +69,7 @@ $ pip install websockets
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -111,7 +111,7 @@ $ fastapi dev {* ../../docs_src/websockets_/tutorial002_an_py310.py hl[68:69,82] *} -/// note +/// note | Примітка Оскільки це WebSocket, не має сенсу піднімати `HTTPException`, натомість ми піднімаємо `WebSocketException`. @@ -126,7 +126,7 @@ $ fastapi dev
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -140,7 +140,7 @@ $ fastapi dev * «Item ID», який використовується у шляху. * «Token», який використовується як параметр запиту. -/// tip +/// tip | Порада Зверніть увагу, що параметр запиту `token` буде оброблено залежністю. @@ -168,7 +168,7 @@ $ fastapi dev Client #1596980209979 left the chat ``` -/// tip +/// tip | Порада Застосунок вище - це мінімальний і простий приклад, що демонструє, як обробляти та розсилати повідомлення кільком з'єднанням WebSocket. @@ -182,5 +182,5 @@ Client #1596980209979 left the chat Щоб дізнатися більше про можливості, перегляньте документацію Starlette: -* [Клас `WebSocket`](https://www.starlette.dev/websockets/). -* [Обробка WebSocket на основі класів](https://www.starlette.dev/endpoints/#websocketendpoint). +* [Клас `WebSocket`](https://starlette.dev/websockets/). +* [Обробка WebSocket на основі класів](https://starlette.dev/endpoints/#websocketendpoint). diff --git a/docs/uk/docs/advanced/wsgi.md b/docs/uk/docs/advanced/wsgi.md index aa4dcb6..df2c2bc 100644 --- a/docs/uk/docs/advanced/wsgi.md +++ b/docs/uk/docs/advanced/wsgi.md @@ -9,7 +9,7 @@ /// note | Примітка -Для цього потрібно встановити `a2wsgi`, наприклад за допомогою `pip install a2wsgi`. +Для цього потрібно додати `a2wsgi` до вашого проєкту, наприклад за допомогою `uv add a2wsgi`. /// diff --git a/docs/uk/docs/alternatives.md b/docs/uk/docs/alternatives.md index f903f3f..4fc62b5 100644 --- a/docs/uk/docs/alternatives.md +++ b/docs/uk/docs/alternatives.md @@ -20,7 +20,7 @@ Він відносно тісно пов’язаний з реляційними базами даних (наприклад, MySQL або PostgreSQL), тому мати базу даних NoSQL (наприклад, Couchbase, MongoDB, Cassandra тощо) як основний механізм зберігання не дуже просто. -Він був створений для створення HTML у серверній частині, а не для створення API, які використовуються сучасним інтерфейсом (як-от React, Vue.js і Angular) або іншими системами (як-от IoT пристрої), які спілкуються з ним. +Він був створений для створення HTML у серверній частині, а не для створення API, які використовються сучасним інтерфейсом (як-от React, Vue.js і Angular) або іншими системами (як-от IoT пристрої), які спілкуються з ним. ### [Django REST Framework](https://www.django-rest-framework.org/) { #django-rest-framework } @@ -125,7 +125,7 @@ def read_url(): Інтегрувати інструменти інтерфейсу на основі стандартів: * [Swagger UI](https://github.com/swagger-api/swagger-ui) -* [ReDoc](https://github.com/Rebilly/ReDoc) +* [ReDoc](https://github.com/Redocly/redoc) Ці два було обрано через те, що вони досить популярні та стабільні, але, виконавши швидкий пошук, ви можете знайти десятки додаткових альтернативних інтерфейсів для OpenAPI (які можна використовувати з **FastAPI**). @@ -237,7 +237,7 @@ Flask-apispec був створений тими ж розробниками Mar /// -### [NestJS](https://nestjs.com/) (та [Angular](https://angular.io/)) { #nestjs-and-angular } +### [NestJS](https://nestjs.com/) (та [Angular](https://angular.dev/)) { #nestjs-and-angular } Це навіть не Python, NestJS - це фреймворк NodeJS JavaScript (TypeScript), натхненний Angular. @@ -337,7 +337,7 @@ Hug був одним із перших фреймворків, який реа /// note | Примітка -Hug створив Тімоті Крослі, той самий творець [`isort`](https://github.com/timothycrosley/isort), чудовий інструмент для автоматичного сортування імпорту у файлах Python. +Hug створив Тімоті Крослі, той самий творець [`isort`](https://github.com/PyCQA/isort), чудовий інструмент для автоматичного сортування імпорту у файлах Python. /// @@ -363,7 +363,7 @@ Hug надихнув **FastAPI** оголосити параметр `response` Він мав найкращі показники продуктивності на той час (перевершив лише Starlette). -Спочатку він не мав автоматичного веб-інтерфейсу документації API, але я знав, що можу додати до нього інтерфейс користувача Swagger. +Спочатку він не мав автоматичного веб-інтерфейсу документації API, але я знав, що можу додати до нього Swagger UI. Він мав систему введення залежностей. Він вимагав попередньої реєстрації компонентів, як і інші інструменти, розглянуті вище. Але все одно це була чудова функція. @@ -401,7 +401,7 @@ APIStar створив Том Крісті. Той самий хлопець, я ## Використовується **FastAPI** { #used-by-fastapi } -### [Pydantic](https://docs.pydantic.dev/) { #pydantic } +### [Pydantic](https://pydantic.dev/docs/) { #pydantic } Pydantic - це бібліотека для визначення перевірки даних, серіалізації та документації (за допомогою Схеми JSON) на основі підказок типу Python. @@ -417,7 +417,7 @@ Pydantic - це бібліотека для визначення перевір /// -### [Starlette](https://www.starlette.dev/) { #starlette } +### [Starlette](https://starlette.dev/) { #starlette } Starlette - це легкий фреймворк/набір інструментів ASGI, який ідеально підходить для створення високопродуктивних asyncio сервісів. @@ -462,7 +462,7 @@ ASGI - це новий «стандарт», який розробляється /// -### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn } +### [Uvicorn](https://uvicorn.dev) { #uvicorn } Uvicorn - це блискавичний сервер ASGI, побудований на uvloop і httptools. diff --git a/docs/uk/docs/deployment/docker.md b/docs/uk/docs/deployment/docker.md index 83799a0..5890de7 100644 --- a/docs/uk/docs/deployment/docker.md +++ b/docs/uk/docs/deployment/docker.md @@ -105,36 +105,32 @@ Docker був одним з основних інструментів для с ### Вимоги до пакетів { #package-requirements } -Зазвичай ви маєте **вимоги до пакетів** для вашого застосунку в окремому файлі. +Коли ви керуєте своїм проєктом за допомогою `uv`, його прямі залежності оголошуються в `pyproject.toml`, а точні розв’язані версії зберігаються в `uv.lock`. -Це залежить переважно від інструменту, який ви використовуєте для **встановлення** цих вимог. - -Найпоширеніший спосіб - мати файл `requirements.txt` з назвами пакетів і їхніми версіями, по одному на рядок. - -Звісно, ви застосуєте ті самі ідеї з [Про версії FastAPI](versions.md), щоб задати діапазони версій. - -Наприклад, ваш `requirements.txt` може виглядати так: - -``` -fastapi[standard]>=0.113.0,<0.114.0 -pydantic>=2.7.0,<3.0.0 -``` - -І зазвичай ви встановлюватимете ці залежності пакетів через `pip`, наприклад: +Ви можете додати пакети, потрібні вашому застосунку, за допомогою:
```console -$ pip install -r requirements.txt +$ uv add "fastapi[standard]" pydantic ---> 100% -Successfully installed fastapi pydantic ```
/// note | Примітка -Існують інші формати та інструменти для визначення і встановлення залежностей пакетів. +`Dockerfile` нижче використовує `pip` всередині контейнера. Ви можете експортувати зафіксовані залежності з вашого проєкту uv у формат `requirements.txt`, якого він очікує: + +
+ +```console +$ uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt +``` + +
+ +Згенерований `requirements.txt` - це експорт для збірки контейнера. Продовжуйте керувати залежностями за допомогою `uv add` і генеруйте його повторно, коли `uv.lock` змінюється. /// @@ -372,7 +368,7 @@ $ docker run -d --name mycontainer -p 80:80 myimage Також ви можете перейти на [http://192.168.99.100/redoc](http://192.168.99.100/redoc) або [http://127.0.0.1/redoc](http://127.0.0.1/redoc) (або еквівалент, використовуючи ваш Docker-хост). -Ви побачите альтернативну автоматичну документацію (надається [ReDoc](https://github.com/Rebilly/ReDoc)): +Ви побачите альтернативну автоматичну документацію (надається [ReDoc](https://github.com/Redocly/redoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) diff --git a/docs/uk/docs/deployment/fastapicloud.md b/docs/uk/docs/deployment/fastapicloud.md index cc59caa..b5c0c17 100644 --- a/docs/uk/docs/deployment/fastapicloud.md +++ b/docs/uk/docs/deployment/fastapicloud.md @@ -5,7 +5,7 @@
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -30,11 +30,11 @@ CLI автоматично визначить ваш застосунок FastAP Він також подбає про більшість речей, які вам потрібні під час розгортання застосунку, як-от: -- HTTPS -- реплікація з автомасштабуванням на основі запитів -- тощо +* HTTPS +* Реплікація, з автомасштабуванням на основі запитів +* тощо -FastAPI Cloud - основний спонсор і джерело фінансування для відкритих проєктів *«FastAPI та друзі»*. ✨ +FastAPI Cloud - основний спонсор і джерело фінансування для проєктів з відкритим кодом *FastAPI та друзі*. ✨ ## Розгортання в інших хмарних провайдерів { #deploy-to-other-cloud-providers } @@ -44,4 +44,4 @@ FastAPI є відкритим кодом і базується на станда ## Розгортання на вашому сервері { #deploy-your-own-server } -Пізніше в цьому розділі **Розгортання** я також навчу вас усім деталям, щоб ви розуміли, що відбувається, що потрібно зробити і як розгортати застосунки FastAPI самостійно, зокрема на власних серверах. 🤓 +Пізніше в цьому посібнику з **Розгортання** я також навчу вас усім деталям, щоб ви розуміли, що відбувається, що потрібно зробити і як розгортати застосунки FastAPI самостійно, зокрема на власних серверах. 🤓 diff --git a/docs/uk/docs/deployment/manually.md b/docs/uk/docs/deployment/manually.md index 6692efd..de80f06 100644 --- a/docs/uk/docs/deployment/manually.md +++ b/docs/uk/docs/deployment/manually.md @@ -52,7 +52,7 @@ FastAPI використовує стандарт для побудови Python Є кілька альтернатив, зокрема: -* [Uvicorn](https://www.uvicorn.dev/): високопродуктивний ASGI-сервер. +* [Uvicorn](https://uvicorn.dev): високопродуктивний ASGI-сервер. * [Hypercorn](https://hypercorn.readthedocs.io/): ASGI-сервер, сумісний з HTTP/2 і Trio, серед інших можливостей. * [Daphne](https://github.com/django/daphne): ASGI-сервер, створений для Django Channels. * [Granian](https://github.com/emmett-framework/granian): Rust HTTP-сервер для Python-застосунків. @@ -73,14 +73,14 @@ FastAPI використовує стандарт для побудови Python Але ви також можете встановити ASGI-сервер вручну. -Переконайтеся, що ви створили [віртуальне оточення](../virtual-environments.md), активували його, після чого можете встановити серверну програму. +Додайте серверний застосунок до вашого проєкту. Наприклад, щоб установити Uvicorn:
```console -$ pip install "uvicorn[standard]" +$ uv add "uvicorn[standard]" ---> 100% ``` @@ -95,7 +95,7 @@ $ pip install "uvicorn[standard]" Зокрема `uvloop` - високопродуктивну заміну «без змін у коді» для `asyncio`, що суттєво підвищує рівночасність і продуктивність. -Якщо ви встановлюєте FastAPI через `pip install "fastapi[standard]"`, ви вже отримаєте і `uvicorn[standard]`. +Коли ви додаєте FastAPI за допомогою чогось на кшталт `uv add "fastapi[standard]"`, ви також уже отримуєте `uvicorn[standard]`. /// @@ -106,7 +106,7 @@ $ pip install "uvicorn[standard]"
```console -$ uvicorn main:app --host 0.0.0.0 --port 80 +$ uv run uvicorn main:app --host 0.0.0.0 --port 80 INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) ``` diff --git a/docs/uk/docs/deployment/server-workers.md b/docs/uk/docs/deployment/server-workers.md index 3bbf445..80da906 100644 --- a/docs/uk/docs/deployment/server-workers.md +++ b/docs/uk/docs/deployment/server-workers.md @@ -1,27 +1,27 @@ -# Працівники сервера - Uvicorn з працівниками { #server-workers-uvicorn-with-workers } +# Серверні працівники - Uvicorn із працівниками { #server-workers-uvicorn-with-workers } Повернімося до попередніх концепцій розгортання: -- Безпека - HTTPS -- Запуск під час старту -- Перезапуски -- **Реплікація (кількість процесів, що виконуються)** -- Пам'ять -- Попередні кроки перед запуском +* Безпека - HTTPS +* Запуск під час старту +* Перезапуски +* **Реплікація (кількість процесів, що виконуються)** +* Пам'ять +* Попередні кроки перед запуском -До цього моменту, проходячи всі навчальні посібники в документації, ви, ймовірно, запускали серверну програму, наприклад, використовуючи команду `fastapi`, яка запускає Uvicorn у вигляді одного процесу. +До цього моменту, проходячи всі навчальні посібники в документації, ви, ймовірно, запускали **серверну програму**, наприклад, використовуючи команду `fastapi`, яка запускає Uvicorn у вигляді **одного процесу**. -Під час розгортання застосунків ви, найімовірніше, захочете мати реплікацію процесів, щоб використовувати кілька ядер і обробляти більше запитів. +Під час розгортання застосунків ви, найімовірніше, захочете мати **реплікацію процесів**, щоб використовувати **кілька ядер** і обробляти більше запитів. Як ви бачили в попередньому розділі про [Концепції розгортання](concepts.md), існує кілька стратегій, які можна використовувати. -Тут я покажу, як використовувати Uvicorn із процесами-працівниками за допомогою команди `fastapi` або безпосередньо команди `uvicorn`. +Тут я покажу, як використовувати **Uvicorn** із **процесами-працівниками** за допомогою команди `fastapi` або безпосередньо команди `uvicorn`. /// note | Примітка Якщо ви використовуєте контейнери, наприклад з Docker або Kubernetes, я розповім про це більше в наступному розділі: [FastAPI у контейнерах - Docker](docker.md). -Зокрема, під час запуску в Kubernetes вам, найімовірніше, не варто використовувати працівників, натомість запускати один процес Uvicorn на контейнер. Але про це я розповім пізніше в тому розділі. +Зокрема, під час запуску в **Kubernetes** вам, найімовірніше, **не** варто використовувати працівників, натомість запускати **один процес Uvicorn на контейнер**, але про це я розповім пізніше в тому розділі. /// @@ -86,7 +86,7 @@ $ fastapi run --workers 4 ```console -$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 +$ uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit) INFO: Started parent process [27365] INFO: Started server process [27368] @@ -107,33 +107,33 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 //// -Єдина нова опція тут — `--workers`, яка вказує Uvicorn запустити 4 процеси-працівники. +Єдина нова опція тут - `--workers`, яка вказує Uvicorn запустити 4 процеси-працівники. -Також ви можете побачити, що виводиться PID кожного процесу: `27365` для батьківського процесу (це менеджер процесів) і по одному для кожного процесу-працівника: `27368`, `27369`, `27370` і `27367`. +Також ви можете побачити, що виводиться **PID** кожного процесу: `27365` для батьківського процесу (це **менеджер процесів**) і по одному для кожного процесу-працівника: `27368`, `27369`, `27370` і `27367`. ## Концепції розгортання { #deployment-concepts } -Тут ви побачили, як використовувати кілька працівників, щоб паралелізувати виконання застосунку, використати кілька ядер процесора та обслуговувати більше запитів. +Тут ви побачили, як використовувати кілька **працівників**, щоб **паралелізувати** виконання застосунку, використати **кілька ядер** процесора та обслуговувати **більше запитів**. -Із наведеного вище списку концепцій розгортання, використання працівників головним чином допоможе з частиною про реплікацію і трохи з перезапусками, але про інше все ще треба подбати: +Із наведеного вище списку концепцій розгортання, використання працівників головним чином допоможе з частиною про **реплікацію** і трохи з **перезапусками**, але про інше все ще треба подбати: -- **Безпека - HTTPS** -- **Запуск під час старту** -- ***Перезапуски*** -- Реплікація (кількість процесів, що виконуються) -- **Пам'ять** -- **Попередні кроки перед запуском** +* **Безпека - HTTPS** +* **Запуск під час старту** +* ***Перезапуски*** +* Реплікація (кількість процесів, що виконуються) +* **Пам'ять** +* **Попередні кроки перед запуском** ## Контейнери і Docker { #containers-and-docker } -У наступному розділі про [FastAPI у контейнерах - Docker](docker.md) я поясню кілька стратегій, які ви можете використати для інших концепцій розгортання. +У наступному розділі про [FastAPI у контейнерах - Docker](docker.md) я поясню кілька стратегій, які ви можете використати для інших **концепцій розгортання**. -Я покажу, як побудувати власний образ з нуля для запуску одного процесу Uvicorn. Це простий процес і, ймовірно, саме те, що потрібно при використанні розподіленої системи керування контейнерами, такої як Kubernetes. +Я покажу, як **побудувати власний образ з нуля** для запуску одного процесу Uvicorn. Це простий процес і, ймовірно, саме те, що потрібно при використанні розподіленої системи керування контейнерами, такої як **Kubernetes**. ## Підсумок { #recap } -Ви можете використовувати кілька процесів-працівників за допомогою параметра CLI `--workers` у командах `fastapi` або `uvicorn`, щоб скористатися перевагами багатоядерних процесорів і запускати кілька процесів паралельно. +Ви можете використовувати кілька процесів-працівників за допомогою параметра CLI `--workers` у командах `fastapi` або `uvicorn`, щоб скористатися перевагами **багатоядерних процесорів** і запускати **кілька процесів паралельно**. -Ви можете застосувати ці інструменти та ідеї, якщо налаштовуєте власну систему розгортання і самостійно дбаєте про інші концепції розгортання. +Ви можете застосувати ці інструменти та ідеї, якщо налаштовуєте **власну систему розгортання** і самостійно дбаєте про інші концепції розгортання. -Перегляньте наступний розділ, щоб дізнатися про FastAPI з контейнерами (наприклад Docker і Kubernetes). Ви побачите, що ці інструменти також мають прості способи вирішити інші концепції розгортання. ✨ +Перегляньте наступний розділ, щоб дізнатися про **FastAPI** з контейнерами (наприклад Docker і Kubernetes). Ви побачите, що ці інструменти також мають прості способи вирішити інші **концепції розгортання**. ✨ diff --git a/docs/uk/docs/environment-variables.md b/docs/uk/docs/environment-variables.md index 95c142c..9838392 100644 --- a/docs/uk/docs/environment-variables.md +++ b/docs/uk/docs/environment-variables.md @@ -1,298 +1,11 @@ # Змінні оточення { #environment-variables } -/// tip | Порада +**Змінна оточення** (також відома як **env var**) - це значення, що існує поза вашим кодом Python, в операційній системі, і може бути прочитане вашим застосунком та іншими програмами. -Якщо ви вже знаєте, що таке «змінні оточення» і як їх використовувати, можете пропустити цей розділ. +Застосунки FastAPI часто використовують змінні оточення для конфігурації, наприклад URL бази даних, облікових даних email і секретних ключів. -/// +Ви дізнаєтеся, як використовувати їх для конфігурації застосунку, у розділі [Налаштування та змінні оточення](advanced/settings.md). -Змінна оточення (також відома як «**env var**») - це змінна, що існує **поза** кодом Python, в **операційній системі**, і може бути прочитана вашим кодом Python (а також іншими програмами). +## Дізнайтеся більше { #learn-more } -Змінні оточення корисні для роботи з **налаштуваннями** застосунку, як частина **встановлення** Python тощо. - -## Створення і використання змінних оточення { #create-and-use-env-vars } - -Ви можете **створювати** і використовувати змінні оточення в **оболонці (терміналі)** без участі Python: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// Ви можете створити змінну оточення MY_NAME командою -$ export MY_NAME="Wade Wilson" - -// Потім можна використати її з іншими програмами, наприклад -$ echo "Hello $MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// Створіть змінну оточення MY_NAME -$ $Env:MY_NAME = "Wade Wilson" - -// Використайте її з іншими програмами, наприклад -$ echo "Hello $Env:MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -## Читання змінних оточення в Python { #read-env-vars-in-python } - -Ви також можете створити змінні оточення **поза** Python, у терміналі (або будь-яким іншим способом), а потім **зчитати їх у Python**. - -Наприклад, у вас може бути файл `main.py` з: - -```Python hl_lines="3" -import os - -name = os.getenv("MY_NAME", "World") -print(f"Hello {name} from Python") -``` - -/// tip | Порада - -Другий аргумент до [`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) - це значення за замовчуванням, яке буде повернено. - -Якщо його не вказано, за замовчуванням це `None`. Тут ми надаємо `"World"` як значення за замовчуванням. - -/// - -Потім ви можете запустити цю програму Python: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// Тут ми ще не встановлюємо змінну оточення -$ python main.py - -// Оскільки ми не встановили змінну оточення, отримуємо значення за замовчуванням - -Hello World from Python - -// Але якщо спочатку створимо змінну оточення -$ export MY_NAME="Wade Wilson" - -// А потім знову викличемо програму -$ python main.py - -// Тепер вона може прочитати змінну оточення - -Hello Wade Wilson from Python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// Тут ми ще не встановлюємо змінну оточення -$ python main.py - -// Оскільки ми не встановили змінну оточення, отримуємо значення за замовчуванням - -Hello World from Python - -// Але якщо спочатку створимо змінну оточення -$ $Env:MY_NAME = "Wade Wilson" - -// А потім знову викличемо програму -$ python main.py - -// Тепер вона може прочитати змінну оточення - -Hello Wade Wilson from Python -``` - -
- -//// - -Оскільки змінні оточення можна встановлювати поза кодом, але читати в коді, і їх не потрібно зберігати (фіксувати у `git`) разом з іншими файлами, їх часто використовують для конфігурацій або **налаштувань**. - -Ви також можете створити змінну оточення лише для **конкретного запуску програми**, вона буде доступна тільки цій програмі і лише на час її виконання. - -Щоб зробити це, створіть її безпосередньо перед командою запуску програми, в тому самому рядку: - -
- -```console -// Створіть змінну оточення MY_NAME безпосередньо в цьому виклику програми -$ MY_NAME="Wade Wilson" python main.py - -// Тепер вона може прочитати змінну оточення - -Hello Wade Wilson from Python - -// Після цього змінна оточення більше не існує -$ python main.py - -Hello World from Python -``` - -
- -/// tip | Порада - -Ви можете прочитати більше у [The Twelve-Factor App: Config](https://12factor.net/config). - -/// - -## Типи і перевірка { #types-and-validation } - -Ці змінні оточення можуть містити лише **текстові строки**, оскільки вони зовнішні щодо Python і мають бути сумісними з іншими програмами та рештою системи (і навіть з різними операційними системами, як-от Linux, Windows, macOS). - -Це означає, що **будь-яке значення**, прочитане в Python зі змінної оточення, **буде `str`**, а будь-яке перетворення до іншого типу або будь-яка перевірка має виконуватися в коді. - -Ви дізнаєтеся більше про використання змінних оточення для роботи з **налаштуваннями застосунку** в розділі [Просунутий посібник користувача - Налаштування і змінні оточення](./advanced/settings.md). - -## Змінна оточення `PATH` { #path-environment-variable } - -Є **спеціальна** змінна оточення **`PATH`**, яку використовують операційні системи (Linux, macOS, Windows) для пошуку програм для запуску. - -Значення змінної `PATH` - це довга строка, що складається з каталогів, розділених двокрапкою `:` у Linux і macOS та крапкою з комою `;` у Windows. - -Наприклад, змінна оточення `PATH` може виглядати так: - -//// tab | Linux, macOS - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -Це означає, що система має шукати програми в каталогах: - -* `/usr/local/bin` -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32 -``` - -Це означає, що система має шукати програми в каталогах: - -* `C:\Program Files\Python312\Scripts` -* `C:\Program Files\Python312` -* `C:\Windows\System32` - -//// - -Коли ви вводите **команду** в терміналі, операційна система **шукає** програму в **кожному з тих каталогів**, перелічених у змінній оточення `PATH`. - -Наприклад, коли ви вводите `python` у терміналі, операційна система шукає програму з назвою `python` у **першому каталозі** цього списку. - -Якщо знайде, вона **використає її**. Інакше продовжить пошук в **інших каталогах**. - -### Встановлення Python і оновлення `PATH` { #installing-python-and-updating-the-path } - -Під час встановлення Python вас можуть запитати, чи хочете ви оновити змінну оточення `PATH`. - -//// tab | Linux, macOS - -Припустімо, ви встановлюєте Python і він опиняється в каталозі `/opt/custompython/bin`. - -Якщо ви погодитеся оновити змінну оточення `PATH`, інсталятор додасть `/opt/custompython/bin` до змінної `PATH`. - -Це може виглядати так: - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin -``` - -Тепер, коли ви введете `python` у терміналі, система знайде програму Python у `/opt/custompython/bin` (останній каталог) і використає саме її. - -//// - -//// tab | Windows - -Припустімо, ви встановлюєте Python і він опиняється в каталозі `C:\opt\custompython\bin`. - -Якщо ви погодитеся оновити змінну оточення `PATH`, інсталятор додасть `C:\opt\custompython\bin` до змінної `PATH`. - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin -``` - -Тепер, коли ви введете `python` у терміналі, система знайде програму Python у `C:\opt\custompython\bin` (останній каталог) і використає саме її. - -//// - -Отже, якщо ви введете: - -
- -```console -$ python -``` - -
- -//// tab | Linux, macOS - -Система **знайде** програму `python` у `/opt/custompython/bin` і запустить її. - -Це приблизно еквівалентно введенню: - -
- -```console -$ /opt/custompython/bin/python -``` - -
- -//// - -//// tab | Windows - -Система **знайде** програму `python` у `C:\opt\custompython\bin\python` і запустить її. - -Це приблизно еквівалентно введенню: - -
- -```console -$ C:\opt\custompython\bin\python -``` - -
- -//// - -Ця інформація стане у пригоді під час вивчення [Віртуальних середовищ](virtual-environments.md). - -## Висновок { #conclusion } - -Тепер ви маєте базове розуміння того, що таке **змінні оточення** і як їх використовувати в Python. - -Також можна прочитати більше у [Вікіпедії про змінну оточення](https://en.wikipedia.org/wiki/Environment_variable). - -У багатьох випадках не одразу очевидно, як змінні оточення будуть корисними та застосовними. Але вони постійно з’являються в різних сценаріях під час розробки, тож варто про них знати. - -Наприклад, вам знадобиться ця інформація в наступному розділі про [Віртуальні середовища](virtual-environments.md). +Прочитайте [посібник зі змінних оточення](https://tiangolo.com/guides/environment-variables/) для детального, кросплатформного пояснення, зокрема як створювати й читати змінні оточення та як працює змінна оточення `PATH`. diff --git a/docs/uk/docs/fastapi-cli.md b/docs/uk/docs/fastapi-cli.md index 3ec7751..ca8c06c 100644 --- a/docs/uk/docs/fastapi-cli.md +++ b/docs/uk/docs/fastapi-cli.md @@ -2,7 +2,7 @@ **FastAPI CLI** — це програма командного рядка, яку ви можете використовувати, щоб обслуговувати ваш застосунок FastAPI, керувати вашим проєктом FastAPI тощо. -Коли ви встановлюєте FastAPI (наприклад, за допомогою `pip install "fastapi[standard]"`), він постачається з програмою командного рядка, яку можна запускати в терміналі. +Коли ви додаєте FastAPI до вашого проєкту (наприклад, за допомогою `uv add "fastapi[standard]"`), він постачається з програмою командного рядка, яку можна запускати в терміналі. Щоб запустити ваш застосунок FastAPI для розробки, ви можете використати команду `fastapi dev`: @@ -52,7 +52,7 @@ $ fastapi dev /// -Внутрішньо **FastAPI CLI** використовує [Uvicorn](https://www.uvicorn.dev), високопродуктивний, готовий до продакшну ASGI сервер. 😎 +Внутрішньо **FastAPI CLI** використовує [Uvicorn](https://uvicorn.dev), високопродуктивний, готовий до продакшну ASGI сервер. 😎 CLI `fastapi` спробує автоматично визначити застосунок FastAPI для запуску, припускаючи, що це об'єкт з назвою `app` у файлі `main.py` (або кілька інших варіантів). @@ -100,13 +100,13 @@ from backend.main import app Ви також можете передати шлях до файлу команді `fastapi dev`, і вона здогадається, який об'єкт застосунку FastAPI використовувати: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` Або ви також можете передати опцію `--entrypoint` команді `fastapi dev`: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` Але вам доведеться щоразу пам'ятати, щоб передавати правильний шлях\entrypoint під час виклику команди `fastapi`. @@ -119,9 +119,13 @@ $ fastapi dev --entrypoint main:app За замовчуванням **auto-reload** увімкнено, і сервер автоматично перезавантажується, коли ви вносите зміни у ваш код. Це ресурсоємно та може бути менш стабільним, ніж коли його вимкнено. Вам слід використовувати це лише для розробки. Також він слухає IP-адресу `127.0.0.1`, яка є IP-адресою для того, щоб ваша машина могла взаємодіяти лише сама з собою (`localhost`). +Перед імпортом вашого застосунку `fastapi dev` встановлює змінну оточення `FASTAPI_ENV` у значення `development`. Якщо `FASTAPI_ENV` уже встановлено, його наявне значення зберігається. Це дозволяє коду запуску застосунку обирати зручну для розробки поведінку, водночас даючи вам змогу вказати оточення, специфічне для застосунку, наприклад `staging`. + +Умовними значеннями `FASTAPI_ENV` є `development` і `production`. Наразі `fastapi run` залишає `FASTAPI_ENV` без змін, тому встановіть його явно, якщо вашому застосунку потрібно визначати продакшн-режим. + ## `fastapi run` { #fastapi-run } -Виконання `fastapi run` за замовчуванням запускає FastAPI у продакшн-режимі. +Виконання `fastapi run` запускає FastAPI у продакшн-режимі. За замовчуванням **auto-reload** вимкнено. Також він слухає IP-адресу `0.0.0.0`, що означає всі доступні IP-адреси, таким чином він буде публічно доступним для будь-кого, хто може взаємодіяти з машиною. Зазвичай саме так ви запускатимете його в продакшн, наприклад у контейнері. diff --git a/docs/uk/docs/features.md b/docs/uk/docs/features.md index 3f8b004..2078ac8 100644 --- a/docs/uk/docs/features.md +++ b/docs/uk/docs/features.md @@ -19,7 +19,7 @@ ![взаємодія Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* Альтернативна документація API за допомогою [**ReDoc**](https://github.com/Rebilly/ReDoc). +* Альтернативна документація API за допомогою [**ReDoc**](https://github.com/Redocly/redoc). ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) @@ -159,7 +159,7 @@ FastAPI містить надзвичайно просту у використа ## Можливості Starlette { #starlette-features } -**FastAPI** повністю сумісний із (та побудований на основі) [**Starlette**](https://www.starlette.dev/). Тому будь-який додатковий код Starlette, який ви маєте, також працюватиме. +**FastAPI** повністю сумісний із (та побудований на основі) [**Starlette**](https://starlette.dev/). Тому будь-який додатковий код Starlette, який ви маєте, також працюватиме. `FastAPI` фактично є підкласом `Starlette`. Тому, якщо ви вже знайомі зі Starlette або використовуєте його, більшість функціональності працюватиме так само. @@ -177,7 +177,7 @@ FastAPI містить надзвичайно просту у використа ## Можливості Pydantic { #pydantic-features } -**FastAPI** повністю сумісний із (та побудований на основі) [**Pydantic**](https://docs.pydantic.dev/). Тому будь-який додатковий код Pydantic, який ви маєте, також працюватиме. +**FastAPI** повністю сумісний із (та побудований на основі) [**Pydantic**](https://pydantic.dev/docs/). Тому будь-який додатковий код Pydantic, який ви маєте, також працюватиме. Включно із зовнішніми бібліотеками, які також базуються на Pydantic, як-от ORM-и, ODM-и для баз даних. diff --git a/docs/uk/docs/help-fastapi.md b/docs/uk/docs/help-fastapi.md index fe1b35c..b5a326c 100644 --- a/docs/uk/docs/help-fastapi.md +++ b/docs/uk/docs/help-fastapi.md @@ -45,20 +45,6 @@ * [@tiangolo.com у **Bluesky**](https://bsky.app/profile/tiangolo.com) * [@tiangolo у **LinkedIn**](https://www.linkedin.com/in/tiangolo/). -## Допомагайте іншим з питаннями на GitHub { #help-others-with-questions-in-github } - -Ви можете спробувати допомагати іншим з їхніми питаннями у [GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered). - -У багатьох випадках ви вже можете знати відповідь на ці питання. 🤓 - -Якщо ви багато допомагаєте людям із їхніми питаннями, ви станете офіційним [Експертом FastAPI](fastapi-people.md#fastapi-experts). 🎉 - -Пам'ятайте, найважливіше: намагайтеся бути добрими. 🤗 - -### Як допомагати { #how-to-help } - -Дотримуйтесь [посібника, як допомагати](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github) тут. - ## Ставте питання { #ask-questions } Ви можете [створити нове питання](https://github.com/fastapi/fastapi/discussions/new?category=questions) у репозиторії GitHub, наприклад, щоб: @@ -68,7 +54,7 @@ ## Долучайтеся до чату { #join-the-chat } -Долучайтеся до 👥 [серверу чату Discord](https://discord.gg/VQjSZaeJmf) 👥 і спілкуйтеся з іншими в спільноті FastAPI. +Долучайтеся до 👥 [серверу чату Discord](https://discord.com/invite/VQjSZaeJmf) 👥 і спілкуйтеся з іншими в спільноті FastAPI. /// tip | Порада @@ -85,3 +71,9 @@ У GitHub шаблон підкаже вам, як написати правильне питання, щоб ви легше отримали хорошу відповідь, або навіть розв'язали проблему самостійно ще до запиту. Розмови в чатах також не так просто шукати, як у GitHub, вони губляться. + +## Спробуйте FastAPI Cloud { #try-fastapi-cloud } + +Основне фінансування FastAPI та друзів надходить від [**FastAPI Cloud**](https://fastapicloud.com), платформи для розгортання застосунків FastAPI простим і швидким способом, однією командою, `fastapi deploy`. + +FastAPI Cloud створено тією ж командою, що стоїть за FastAPI. Ви можете спробувати його та розглянути для своїх проєктів. diff --git a/docs/uk/docs/history-design-future.md b/docs/uk/docs/history-design-future.md index 6218859..f387fbb 100644 --- a/docs/uk/docs/history-design-future.md +++ b/docs/uk/docs/history-design-future.md @@ -44,7 +44,7 @@ Я протестував кілька ідей у найпопулярніших Python-редакторах: PyCharm, VS Code, редакторах на основі Jedi. -За даними [Python Developer Survey](https://www.jetbrains.com/research/python-developers-survey-2018/#development-tools), це охоплює близько 80% користувачів. +За даними останнього [Python Developer Survey](https://www.jetbrains.com/research/python-developers-survey-2018/#development-tools), це охоплює близько 80% користувачів. Це означає, що **FastAPI** спеціально тестувався з редакторами, якими користуються 80% розробників Python. І оскільки більшість інших редакторів працюють подібно, усі ці переваги мають працювати практично у всіх редакторах. @@ -54,11 +54,11 @@ ## Вимоги { #requirements } -Після перевірки кількох альтернатив я вирішив використовувати [**Pydantic**](https://docs.pydantic.dev/) через його переваги. +Після перевірки кількох альтернатив я вирішив використовувати [**Pydantic**](https://pydantic.dev/docs/) через його переваги. Потім я зробив внески до нього, щоб зробити його повністю сумісним із Схемою JSON, додати підтримку різних способів оголошення обмежень і поліпшити підтримку редакторів (перевірки типів, автодоповнення) на основі тестів у кількох редакторах. -Під час розробки я також зробив внески до [**Starlette**](https://www.starlette.dev/), іншої ключової залежності. +Під час розробки я також зробив внески до [**Starlette**](https://starlette.dev/), іншої ключової залежності. ## Розробка { #development } diff --git a/docs/uk/docs/how-to/custom-request-and-route.md b/docs/uk/docs/how-to/custom-request-and-route.md index f45fc1e..a0500cb 100644 --- a/docs/uk/docs/how-to/custom-request-and-route.md +++ b/docs/uk/docs/how-to/custom-request-and-route.md @@ -66,7 +66,7 @@ І саме ці дві сутності - `scope` та `receive` - потрібні для створення нового екземпляра `Request`. -Щоб дізнатися більше про `Request`, перегляньте [документацію Starlette про запити](https://www.starlette.dev/requests/). +Щоб дізнатися більше про `Request`, перегляньте [документацію Starlette про запити](https://starlette.dev/requests/). /// diff --git a/docs/uk/docs/how-to/extending-openapi.md b/docs/uk/docs/how-to/extending-openapi.md index 4267d37..cc75984 100644 --- a/docs/uk/docs/how-to/extending-openapi.md +++ b/docs/uk/docs/how-to/extending-openapi.md @@ -45,7 +45,7 @@ Використовуючи наведене вище, ви можете скористатися тією ж утилітарною функцією для генерації схеми OpenAPI і переписати потрібні частини. -Наприклад, додаймо [розширення OpenAPI ReDoc для додавання власного логотипа](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo). +Наприклад, додаймо [розширення OpenAPI ReDoc для додавання власного логотипа](https://github.com/Redocly/redoc/blob/main/docs/redoc-vendor-extensions.md#x-logo). ### Звичайний **FastAPI** { #normal-fastapi } diff --git a/docs/uk/docs/how-to/graphql.md b/docs/uk/docs/how-to/graphql.md index 91fa361..140ba9c 100644 --- a/docs/uk/docs/how-to/graphql.md +++ b/docs/uk/docs/how-to/graphql.md @@ -21,7 +21,7 @@ * [Strawberry](https://strawberry.rocks/) 🍓 * З [документацією для FastAPI](https://strawberry.rocks/docs/integrations/fastapi) * [Ariadne](https://ariadnegraphql.org/) - * З [документацією для FastAPI](https://ariadnegraphql.org/docs/fastapi-integration) + * З [документацією для FastAPI](https://ariadnegraphql.org/server/Integrations/fastapi-integration) * [Tartiflette](https://tartiflette.io/) * З [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) для інтеграції з ASGI * [Graphene](https://graphene-python.org/) diff --git a/docs/uk/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/uk/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index 7f71df2..aa337c9 100644 --- a/docs/uk/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/uk/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -24,7 +24,7 @@ FastAPI 0.128.0 також припинив підтримку `pydantic.v1`, т ## Офіційний посібник { #official-guide } -У Pydantic є офіційний [Посібник з міграції](https://docs.pydantic.dev/latest/migration/) з v1 на v2. +У Pydantic є офіційний [Посібник з міграції](https://pydantic.dev/docs/validation/latest/get-started/migration/) з v1 на v2. Там описано, що змінилося, як перевірки тепер стали коректнішими та суворішими, можливі застереження тощо. diff --git a/docs/uk/docs/index.md b/docs/uk/docs/index.md index fe7d111..069a341 100644 --- a/docs/uk/docs/index.md +++ b/docs/uk/docs/index.md @@ -45,7 +45,7 @@ FastAPI - це сучасний, швидкий (високопродуктив * **Швидкий**: дуже висока продуктивність, на рівні з **NodeJS** та **Go** (завдяки Starlette та Pydantic). [Один із найшвидших Python-фреймворків](#performance). * **Швидке написання коду**: пришвидшує розробку функціоналу приблизно на 200%–300%. * * **Менше помилок**: зменшує приблизно на 40% кількість помилок, спричинених людиною (розробником). * -* **Інтуїтивний**: чудова підтримка редакторами коду. Автодоповнення всюди. Менше часу на налагодження. +* **Інтуїтивний**: чудова підтримка редакторами коду. Автодоповнення всюди. Менше часу на налагодження. * **Простий**: спроєктований так, щоб бути простим у використанні та вивченні. Менше часу на читання документації. * **Короткий**: мінімізує дублювання коду. Кілька можливостей з кожного оголошення параметра. Менше помилок. * **Надійний**: ви отримуєте код, готовий до продакшну. З автоматичною інтерактивною документацією. @@ -110,7 +110,7 @@ FastAPI - це сучасний, швидкий (високопродуктив
-## Конференція FastAPI { #fastapi-conf } - -[**FastAPI Conf '26**](https://fastapiconf.com) відбудеться **28 жовтня 2026 року** в **Амстердамі, Нідерланди**. Усе про FastAPI з першоджерела. 🎤 - -FastAPI Conf '26 - October 28, 2026 - Amsterdam, NL - ## Міні-документальний фільм про FastAPI { #fastapi-mini-documentary } Наприкінці 2025 року вийшов [міні-документальний фільм про FastAPI](https://www.youtube.com/watch?v=mpR8ngthqiE), ви можете переглянути його онлайн: @@ -175,17 +169,17 @@ FastAPI - це сучасний, швидкий (високопродуктив FastAPI стоїть на плечах гігантів: -* [Starlette](https://www.starlette.dev/) для вебчастини. -* [Pydantic](https://docs.pydantic.dev/) для частини даних. +* [Starlette](https://starlette.dev/) для вебчастини. +* [Pydantic](https://pydantic.dev/docs/) для частини даних. ## Встановлення { #installation } -Створіть і активуйте [віртуальне середовище](https://fastapi.tiangolo.com/uk/virtual-environments/), а потім встановіть FastAPI: +Спочатку [встановіть `uv`](https://docs.astral.sh/uv/getting-started/installation/), а потім додайте FastAPI до вашого проєкту:
```console -$ pip install "fastapi[standard]" +$ uv add "fastapi[standard]" ---> 100% ``` @@ -194,6 +188,8 @@ $ pip install "fastapi[standard]" **Примітка**: переконайтеся, що ви взяли `"fastapi[standard]"` у лапки, щоб це працювало в усіх терміналах. +Якщо ви віддаєте перевагу `pip`, встановіть `fastapi[standard]` у віртуальному середовищі. Дивіться [посібник зі встановлення](tutorial/#install-fastapi) для альтернативних кроків. + ## Приклад { #example } ### Створіть { #create-it } @@ -250,7 +246,7 @@ async def read_item(item_id: int, q: str | None = None):
```console -$ fastapi dev +$ uv run fastapi dev ╭────────── FastAPI CLI - Development mode ───────────╮ │ │ @@ -277,7 +273,7 @@ INFO: Application startup complete.
Про команду fastapi dev... -Команда `fastapi dev` автоматично читає ваш файл `main.py`, знаходить у ньому застосунок **FastAPI** і запускає сервер за допомогою [Uvicorn](https://www.uvicorn.dev). +Команда `fastapi dev` автоматично читає ваш файл `main.py`, знаходить у ньому застосунок **FastAPI** і запускає сервер за допомогою [Uvicorn](https://uvicorn.dev). За замовчуванням `fastapi dev` запускається з авто-перезавантаженням для локальної розробки. @@ -314,7 +310,7 @@ INFO: Application startup complete. А тепер перейдіть на [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc). -Ви побачите альтернативну автоматичну документацію (надану [ReDoc](https://github.com/Rebilly/ReDoc)): +Ви побачите альтернативну автоматичну документацію (надану [ReDoc](https://github.com/Redocly/redoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -479,7 +475,7 @@ item: Item * Оголошення **параметрів** з інших різних місць, як-от: **заголовки**, **кукі**, **поля форми** та **файли**. * Як встановлювати **обмеження валідації** як `maximum_length` або `regex`. -* Дуже потужну і просту у використанні систему **Впровадження залежностей**. +* Дуже потужну і просту у використанні систему **Впровадження залежностей**. * Безпеку та автентифікацію, включно з підтримкою **OAuth2** з **токенами JWT** та **базовою автентифікацією HTTP**. * Досконаліші (але однаково прості) техніки для оголошення **глибоко вкладених моделей JSON** (завдяки Pydantic). * Інтеграцію **GraphQL** з [Strawberry](https://strawberry.rocks) та іншими бібліотеками. @@ -497,7 +493,7 @@ item: Item
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -540,7 +536,7 @@ FastAPI залежить від Pydantic і Starlette. ### Залежності `standard` { #standard-dependencies } -Коли ви встановлюєте FastAPI за допомогою `pip install "fastapi[standard]"`, ви отримуєте групу необовʼязкових залежностей `standard`: +Коли ви встановлюєте FastAPI за допомогою `uv add "fastapi[standard]"`, ви отримуєте групу необовʼязкових залежностей `standard`: Використовується Pydantic: @@ -554,17 +550,17 @@ FastAPI залежить від Pydantic і Starlette. Використовується FastAPI: -* [`uvicorn`](https://www.uvicorn.dev) - для сервера, який завантажує та обслуговує ваш застосунок. Це включає `uvicorn[standard]`, до якого входять деякі залежності (наприклад, `uvloop`), потрібні для високопродуктивної роботи сервера. +* [`uvicorn`](https://uvicorn.dev) - для сервера, який завантажує та обслуговує ваш застосунок. Це включає `uvicorn[standard]`, до якого входять деякі залежності (наприклад, `uvloop`), потрібні для високопродуктивної роботи сервера. * `fastapi-cli[standard]` - щоб надати команду `fastapi`. * Це включає `fastapi-cloud-cli`, який дозволяє розгортати ваш застосунок FastAPI у [FastAPI Cloud](https://fastapicloud.com). ### Без залежностей `standard` { #without-standard-dependencies } -Якщо ви не хочете включати необовʼязкові залежності `standard`, ви можете встановити через `pip install fastapi` замість `pip install "fastapi[standard]"`. +Якщо ви не хочете включати необовʼязкові залежності `standard`, ви можете встановити через `uv add fastapi` замість `uv add "fastapi[standard]"`. ### Без `fastapi-cloud-cli` { #without-fastapi-cloud-cli } -Якщо ви хочете встановити FastAPI зі стандартними залежностями, але без `fastapi-cloud-cli`, ви можете встановити через `pip install "fastapi[standard-no-fastapi-cloud-cli]"`. +Якщо ви хочете встановити FastAPI зі стандартними залежностями, але без `fastapi-cloud-cli`, ви можете встановити через `uv add "fastapi[standard-no-fastapi-cloud-cli]"`. ### Додаткові необовʼязкові залежності { #additional-optional-dependencies } @@ -572,13 +568,13 @@ FastAPI залежить від Pydantic і Starlette. Додаткові необовʼязкові залежності Pydantic: -* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - для керування налаштуваннями. -* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - для додаткових типів, що можуть бути використані з Pydantic. +* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) - для керування налаштуваннями. +* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) - для додаткових типів, що можуть бути використані з Pydantic. Додаткові необовʼязкові залежності FastAPI: * [`orjson`](https://github.com/ijl/orjson) - потрібно, якщо ви хочете використовувати `ORJSONResponse`. -* [`ujson`](https://github.com/esnme/ultrajson) - потрібно, якщо ви хочете використовувати `UJSONResponse`. +* [`ujson`](https://github.com/ultrajson/ultrajson) - потрібно, якщо ви хочете використовувати `UJSONResponse`. ## Ліцензія { #license } diff --git a/docs/uk/docs/project-generation.md b/docs/uk/docs/project-generation.md index e4e8256..da43ede 100644 --- a/docs/uk/docs/project-generation.md +++ b/docs/uk/docs/project-generation.md @@ -1,17 +1,16 @@ # Шаблон Full Stack FastAPI { #full-stack-fastapi-template } - Шаблони, хоча зазвичай постачаються з певним налаштуванням, спроєктовані бути гнучкими та налаштовуваними. Це дає змогу змінювати їх і адаптувати до вимог вашого проєкту, що робить їх чудовою відправною точкою. 🏁 Ви можете використати цей шаблон для старту, адже в ньому вже виконано значну частину початкового налаштування, безпеки, роботи з базою даних і деяких кінцевих точок API. -Репозиторій GitHub: [Шаблон Full Stack FastAPI](https://github.com/tiangolo/full-stack-fastapi-template) +Репозиторій GitHub: [Шаблон Full Stack FastAPI](https://github.com/fastapi/full-stack-fastapi-template) ## Шаблон Full Stack FastAPI - стек технологій і можливості { #full-stack-fastapi-template-technology-stack-and-features } - ⚡ [**FastAPI**](https://fastapi.tiangolo.com/uk) для бекенд API на Python. - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) для взаємодії з SQL-базою даних у Python (ORM). - - 🔍 [Pydantic](https://docs.pydantic.dev), який використовується FastAPI, для перевірки даних і керування налаштуваннями. + - 🔍 [Pydantic](https://pydantic.dev/docs/), який використовується FastAPI, для перевірки даних і керування налаштуваннями. - 💾 [PostgreSQL](https://www.postgresql.org) як SQL-база даних. - 🚀 [React](https://react.dev) для фронтенду. - 💃 Використання TypeScript, хуків, Vite та інших частин сучасного фронтенд-стеку. diff --git a/docs/uk/docs/python-types.md b/docs/uk/docs/python-types.md index 06cc67f..e22d585 100644 --- a/docs/uk/docs/python-types.md +++ b/docs/uk/docs/python-types.md @@ -269,7 +269,7 @@ def some_function(data: Any): ## Моделі Pydantic { #pydantic-models } -[Pydantic](https://docs.pydantic.dev/) — це бібліотека Python для валідації даних. +[Pydantic](https://pydantic.dev/docs/) - це бібліотека Python для валідації даних. Ви оголошуєте «форму» даних як класи з атрибутами. @@ -285,7 +285,7 @@ def some_function(data: Any): /// note | Примітка -Щоб дізнатись більше про [Pydantic, перегляньте його документацію](https://docs.pydantic.dev/). +Щоб дізнатись більше про [Pydantic, перегляньте його документацію](https://pydantic.dev/docs/). /// diff --git a/docs/uk/docs/tutorial/background-tasks.md b/docs/uk/docs/tutorial/background-tasks.md index 2894bd2..10b9531 100644 --- a/docs/uk/docs/tutorial/background-tasks.md +++ b/docs/uk/docs/tutorial/background-tasks.md @@ -25,7 +25,7 @@ Це звичайна функція, яка може отримувати параметри. -Вона може бути асинхронною `async def` або звичайною `def` функцією – **FastAPI** обробить її правильно. +Вона може бути асинхронною `async def` або звичайною `def` функцією - **FastAPI** обробить її правильно. У нашому випадку функція записує у файл (імітуючи надсилання email). @@ -51,8 +51,10 @@ **FastAPI** знає, як діяти в кожному випадку і як повторно використовувати один і той самий об'єкт, щоб усі фонові задачі були об’єднані та виконувалися у фоновому режимі після завершення основного запиту: + {* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *} + У цьому прикладі повідомлення будуть записані у файл `log.txt` після того, як відповідь буде надіслана. Якщо у запиті був переданий параметр запиту, він буде записаний у лог у фоновій задачі. @@ -61,7 +63,7 @@ ## Технічні деталі { #technical-details } -Клас `BackgroundTasks` походить безпосередньо з [`starlette.background`](https://www.starlette.dev/background/). +Клас `BackgroundTasks` походить безпосередньо з [`starlette.background`](https://starlette.dev/background/). Він імпортується/включається безпосередньо у FastAPI, щоб ви могли імпортувати його з `fastapi` і випадково не імпортували альтернативний `BackgroundTask` (без `s` в кінці) з `starlette.background`. @@ -69,13 +71,13 @@ Також можна використовувати `BackgroundTask` окремо в FastAPI, але для цього вам доведеться створити об'єкт у коді та повернути Starlette `Response`, включаючи його. -Детальніше можна почитати в [офіційній документації Starlette про Background Tasks](https://www.starlette.dev/background/). +Детальніше можна почитати в [офіційній документації Starlette про Background Tasks](https://starlette.dev/background/). ## Застереження { #caveat } Якщо вам потрібно виконувати складні фонові обчислення, і при цьому нема потреби запускати їх у тому ж процесі (наприклад, не потрібно спільного доступу до пам’яті чи змінних), можливо, варто скористатися більш потужними інструментами, такими як [Celery](https://docs.celeryq.dev). -Такі інструменти зазвичай потребують складнішої конфігурації та менеджера черги повідомлень/завдань, наприклад, RabbitMQ або Redis. Однак вони дозволяють виконувати фонові задачі в кількох процесах і особливо — на кількох серверах. +Такі інструменти зазвичай потребують складнішої конфігурації та менеджера черги повідомлень/завдань, наприклад, RabbitMQ або Redis. Однак вони дозволяють виконувати фонові задачі в кількох процесах і особливо - на кількох серверах. Якщо ж вам потрібно отримати доступ до змінних і об’єктів із тієї ж **FastAPI**-програми або виконувати невеликі фонові завдання (наприклад, надсилати email-сповіщення), достатньо просто використовувати `BackgroundTasks`. diff --git a/docs/uk/docs/tutorial/bigger-applications.md b/docs/uk/docs/tutorial/bigger-applications.md index 85a6c66..51785bf 100644 --- a/docs/uk/docs/tutorial/bigger-applications.md +++ b/docs/uk/docs/tutorial/bigger-applications.md @@ -487,7 +487,7 @@ from app.main import app Ви також могли б передати шлях команді, наприклад: ```console -$ fastapi dev app/main.py +$ uv run fastapi dev app/main.py ``` Але тоді вам доведеться щоразу пам'ятати, щоб передавати правильний шлях, коли ви викликаєте команду `fastapi`. @@ -503,7 +503,7 @@ $ fastapi dev app/main.py
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/uk/docs/tutorial/body-nested-models.md b/docs/uk/docs/tutorial/body-nested-models.md index c1daaf6..2c5c166 100644 --- a/docs/uk/docs/tutorial/body-nested-models.md +++ b/docs/uk/docs/tutorial/body-nested-models.md @@ -96,7 +96,7 @@ my_list: list[str] Окрім звичайних одиничних типів, таких як `str`, `int`, `float`, та ін. ви можете використовувати складніші одиничні типи, які наслідують `str`. -Щоб побачити всі доступні варіанти, ознайомтеся з [Оглядом типів у Pydantic](https://docs.pydantic.dev/latest/concepts/types/). Деякі приклади будуть у наступному розділі. +Щоб побачити всі доступні варіанти, ознайомтеся з [Оглядом типів у Pydantic](https://pydantic.dev/docs/validation/latest/concepts/types/). Деякі приклади будуть у наступному розділі. Наприклад, оскільки в моделі `Image` є поле `url`, ми можемо оголосити його як екземпляр `HttpUrl` від Pydantic замість `str`: diff --git a/docs/uk/docs/tutorial/body.md b/docs/uk/docs/tutorial/body.md index 64d9af9..bcf6d65 100644 --- a/docs/uk/docs/tutorial/body.md +++ b/docs/uk/docs/tutorial/body.md @@ -6,7 +6,7 @@ Ваш API майже завжди має надсилати тіло **відповіді**. Але клієнтам не обов’язково потрібно постійно надсилати тіла **запитів** - інколи вони лише запитують шлях, можливо з деякими параметрами запиту, але не надсилають тіло. -Щоб оголосити тіло **запиту**, ви використовуєте [Pydantic](https://docs.pydantic.dev/) моделі з усією їх потужністю та перевагами. +Щоб оголосити тіло **запиту**, ви використовуєте [Pydantic](https://pydantic.dev/docs/) моделі з усією їх потужністю та перевагами. /// note | Примітка diff --git a/docs/uk/docs/tutorial/debugging.md b/docs/uk/docs/tutorial/debugging.md index 4d99569..176ad2d 100644 --- a/docs/uk/docs/tutorial/debugging.md +++ b/docs/uk/docs/tutorial/debugging.md @@ -16,7 +16,7 @@
```console -$ python myapp.py +$ uv run python myapp.py ```
@@ -36,7 +36,7 @@ from myapp import app
```console -$ python myapp.py +$ uv run python myapp.py ```
diff --git a/docs/uk/docs/tutorial/extra-data-types.md b/docs/uk/docs/tutorial/extra-data-types.md index 15e6b64..2477149 100644 --- a/docs/uk/docs/tutorial/extra-data-types.md +++ b/docs/uk/docs/tutorial/extra-data-types.md @@ -36,7 +36,7 @@ * `datetime.timedelta`: * Пайтонівський `datetime.timedelta`. * У запитах та відповідях буде представлений як `float` загальної кількості секунд. - * Pydantic також дозволяє представляти це як «ISO 8601 time diff encoding», [дивіться документацію для отримання додаткової інформації](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers). + * Pydantic також дозволяє представляти це як «ISO 8601 time diff encoding», [дивіться документацію для отримання додаткової інформації](https://pydantic.dev/docs/validation/latest/concepts/serialization/#custom-serializers). * `frozenset`: * У запитах і відповідях це буде оброблено так само, як і `set`: * У запитах список буде зчитано, дублікати буде видалено, і його буде перетворено на `set`. @@ -49,7 +49,7 @@ * `Decimal`: * Стандартний Пайтонівський `Decimal`. * У запитах і відповідях це буде оброблено так само, як і `float`. -* Ви можете перевірити всі дійсні типи даних Pydantic тут: [типи даних Pydantic](https://docs.pydantic.dev/latest/usage/types/types/). +* Ви можете перевірити всі дійсні типи даних Pydantic тут: [типи даних Pydantic](https://pydantic.dev/docs/validation/latest/concepts/types/). ## Приклад { #example } diff --git a/docs/uk/docs/tutorial/extra-models.md b/docs/uk/docs/tutorial/extra-models.md index 564f9fc..dfeca76 100644 --- a/docs/uk/docs/tutorial/extra-models.md +++ b/docs/uk/docs/tutorial/extra-models.md @@ -166,7 +166,7 @@ UserInDB( /// note | Примітка -Під час визначення [`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions) спочатку вказуйте найконкретніший тип, а потім менш конкретний. У прикладі нижче більш конкретний `PlaneItem` стоїть перед `CarItem` у `Union[PlaneItem, CarItem]`. +Під час визначення [`Union`](https://pydantic.dev/docs/validation/latest/concepts/unions/) спочатку вказуйте найконкретніший тип, а потім менш конкретний. У прикладі нижче більш конкретний `PlaneItem` стоїть перед `CarItem` у `Union[PlaneItem, CarItem]`. /// diff --git a/docs/uk/docs/tutorial/first-steps.md b/docs/uk/docs/tutorial/first-steps.md index 0469e6c..77b3fd9 100644 --- a/docs/uk/docs/tutorial/first-steps.md +++ b/docs/uk/docs/tutorial/first-steps.md @@ -6,12 +6,18 @@ Скопіюйте це до файлу `main.py`. +/// tip | Порада + +FastAPI має [офіційне розширення для VS Code](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (і Cursor), яке надає багато функцій, включно з оглядачем операцій шляху, пошуком операцій шляху, навігацією CodeLens у тестах (перехід до визначення з тестів), а також розгортанням і логами FastAPI Cloud - усе з вашого редактора. + +/// + Запустіть live-сервер:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -78,7 +84,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) А тепер перейдіть сюди [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc). -Ви побачите альтернативну автоматичну документацію (надається [ReDoc](https://github.com/Rebilly/ReDoc)): +Ви побачите альтернативну автоматичну документацію (надається [ReDoc](https://github.com/Redocly/redoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -185,13 +191,13 @@ from backend.main import app Ви також можете передати шлях до файлу в команду `fastapi dev`, і вона вгадає обʼєкт FastAPI app, який слід використовувати: ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` Або ви також можете передати параметр `--entrypoint` команді `fastapi dev`: ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` Але вам доведеться щоразу памʼятати передавати правильний шлях\entrypoint під час виклику команди `fastapi`. @@ -205,7 +211,7 @@ $ fastapi dev --entrypoint main:app
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -232,7 +238,7 @@ CLI автоматично визначить ваш застосунок FastAP `FastAPI` - це клас, який успадковується безпосередньо від `Starlette`. -Ви також можете використовувати всю функціональність [Starlette](https://www.starlette.dev/) у `FastAPI`. +Ви також можете використовувати всю функціональність [Starlette](https://starlette.dev/) у `FastAPI`. /// diff --git a/docs/uk/docs/tutorial/frontend.md b/docs/uk/docs/tutorial/frontend.md index 3670376..b63dc93 100644 --- a/docs/uk/docs/tutorial/frontend.md +++ b/docs/uk/docs/tutorial/frontend.md @@ -52,9 +52,9 @@ npm run build {* ../../docs_src/frontend/tutorial002_py310.py hl[5] *} -**FastAPI** використовує цей fallback лише для запитів `GET` і `HEAD`, які виглядають як навігація браузера. Відсутні файли, як-от JavaScript, CSS і зображення, все ще повертають `404`. +**FastAPI** використовує цей fallback лише для запитів `GET` і `HEAD`, які явно приймають HTML з `Accept: text/html` або `Accept: application/xhtml+xml`, як зазвичай роблять запити навігації браузера. Відсутні файли, як-от JavaScript, CSS і зображення, все ще повертають `404`. -Запити з іншими методами, як-от `POST` або `PUT`, до шляхів, що збігаються лише з frontend fallback, також повертають `404`. Звичайні *операції шляху* **FastAPI** все ще мають вищий пріоритет, ніж фронтенд-маршрути. +Запити з іншими методами, як-от `POST` або `PUT`, до шляхів, що збігаються лише з frontend fallback, також повертають `404`. Звичайні **FastAPI** *операції шляху* все ще мають вищий пріоритет, ніж фронтенд-маршрути. /// tip | Порада @@ -106,9 +106,13 @@ npm run build ## Перевірка директорії { #check-directory } -За замовчуванням `app.frontend()` перевіряє, що директорія існує, коли застосунок створюється. +За замовчуванням `app.frontend()` використовує `check_dir="auto"`. -Це допомагає виявити помилки конфігурації завчасно. Наприклад, якщо директорія вихідних файлів збірки фронтенду відсутня, **FastAPI** викличе помилку під час запуску. +Коли змінна оточення `FASTAPI_ENV` має значення `development`, **FastAPI** лише показує попередження, якщо директорія вихідних файлів збірки фронтенду відсутня. Команда [`fastapi dev`](https://github.com/fastapi/fastapi-cli#fastapi-dev) встановлює цю змінну оточення для вас, якщо її ще не встановлено. Це дає змогу запустити бекенд перед збіркою або запуском фронтенду під час розробки. + +У будь-якому іншому оточенні **FastAPI** викликає помилку, коли застосунок створюється. Це допомагає виявити помилки конфігурації завчасно перед розгортанням застосунку без його фронтенд-файлів. + +Ви також можете встановити `check_dir=True`, щоб завжди перевіряти директорію під час створення застосунку. Якщо ваші фронтенд-файли створюються пізніше, наприклад окремим кроком збірки після створення об'єкта застосунку, встановіть `check_dir=False`: @@ -132,6 +136,8 @@ npm run build Залежності із застосунку, з `APIRouter` і з `include_router()` також застосовуються до фронтенд-відповідей. Це може бути корисно для захисту фронтенду за допомогою автентифікації на основі кукі або подібного. +Залежності також можуть змінювати заголовки відповіді та додавати фонові завдання, як і зі звичайними *операціями шляху*. + ## Лише статичний результат збірки { #static-build-output-only } `app.frontend()` обслуговує файли, вже згенеровані вашою фронтенд-збіркою. diff --git a/docs/uk/docs/tutorial/handling-errors.md b/docs/uk/docs/tutorial/handling-errors.md index 381e65c..ba80705 100644 --- a/docs/uk/docs/tutorial/handling-errors.md +++ b/docs/uk/docs/tutorial/handling-errors.md @@ -81,7 +81,7 @@ ## Встановлення власних обробників виключень { #install-custom-exception-handlers } -Ви можете додати власні обробники виключень за допомогою [тих самих утиліт для виключень зі Starlette](https://www.starlette.dev/exceptions/). +Ви можете додати власні обробники виключень за допомогою [тих самих утиліт для виключень зі Starlette](https://starlette.dev/exceptions/). Припустімо, у вас є власне виключення `UnicornException`, яке ви (або бібліотека, яку ви використовуєте) можете `raise`. diff --git a/docs/uk/docs/tutorial/index.md b/docs/uk/docs/tutorial/index.md index f896562..22b05aa 100644 --- a/docs/uk/docs/tutorial/index.md +++ b/docs/uk/docs/tutorial/index.md @@ -10,12 +10,12 @@ Усі блоки коду можна скопіювати та використовувати безпосередньо (це фактично перевірені файли Python). -Щоб запустити будь-який із прикладів, скопіюйте код у файл `main.py`, і запустіть `fastapi dev`: +Щоб запустити будь-який із прикладів, скопіюйте код у файл `main.py` і запустіть `fastapi dev` за допомогою `uv run`:
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -60,35 +60,75 @@ $ fastapi dev ## Встановлення FastAPI { #install-fastapi } -Першим кроком є встановлення FastAPI. +Першим кроком є налаштування вашого проєкту та додавання FastAPI. -Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md), активували його, а потім **встановіть FastAPI**: +Встановіть [`uv`](https://docs.astral.sh/uv/getting-started/installation/), потім створіть проєкт і додайте FastAPI:
```console -$ pip install "fastapi[standard]" +$ uv init awesome-project --bare +$ cd awesome-project +$ uv add "fastapi[standard]" ---> 100% ```
+`uv add` створює віртуальне середовище проєкту в `.venv`, додає FastAPI до `pyproject.toml` і створює `uv.lock`, щоб ті самі версії пакетів можна було встановити пізніше. + +/// details | Що роблять ці команди + +* `uv init`: створює новий Python-проєкт. +* `awesome-project`: створює проєкт у новому каталозі з цією назвою. +* `--bare`: створює лише мінімальний файл `pyproject.toml`, без генерування прикладу `main.py`, `README.md` або інших файлів. Ви створите файли застосунку самостійно в наступних кроках цього навчального посібника. + +Потім `cd awesome-project` входить до нового каталогу проєкту перед додаванням FastAPI. + +`uv` використовуватиме сумісну версію Python, уже встановлену у вашій системі, або завантажить її за потреби. + +Коли ви запускаєте `uv add`, він вибирає сумісні версії FastAPI та всіх пакетів, від яких залежить FastAPI. Він записує точні версії в `uv.lock`, що дає змогу встановити ті самі версії пакетів пізніше на іншому комп'ютері або під час розгортання застосунку. + +Створення або оновлення цього файлу називається [**закріпленням** залежностей проєкту](https://docs.astral.sh/uv/concepts/projects/sync/). `uv` робить це автоматично, коли ви додаєте пакет. + +/// + +/// details | Варіанти встановлення FastAPI + +Коли ви встановлюєте через `uv add "fastapi[standard]"`, він постачається з деякими типовими необов'язковими стандартними залежностями, включно з `fastapi-cloud-cli`, який дозволяє розгортати в [FastAPI Cloud](https://fastapicloud.com). + +Якщо ви не хочете мати ці необов'язкові залежності, натомість можете встановити `uv add fastapi`. + +Якщо ви хочете встановити стандартні залежності, але без `fastapi-cloud-cli`, ви можете встановити через `uv add "fastapi[standard-no-fastapi-cloud-cli]"`. + +/// + +/// details | Натомість використання `pip` + +Якщо ви віддаєте перевагу керуванню віртуальним середовищем і пакетами вручну, створіть і активуйте віртуальне середовище, а потім встановіть FastAPI за допомогою `pip install "fastapi[standard]"`. + +Прочитайте [посібник з віртуальних середовищ](https://tiangolo.com/guides/virtual-environments/) для детальних кроків. + +/// + +## Навички AI-агента { #ai-agent-skills } + +FastAPI включає офіційну навичку для AI-агентів для кодування. Вона постачається з пакетом, тому її настанови залишаються узгодженими з версією FastAPI, встановленою у вашому проєкті, і оновлюються, коли ви оновлюєте FastAPI. + +Після встановлення FastAPI у вашому проєкті ви можете встановити навичку за допомогою Library Skills: + +```bash +uvx library-skills +``` + /// note | Примітка -Коли ви встановлюєте через `pip install "fastapi[standard]"`, він постачається з деякими типовими необов’язковими стандартними залежностями, включно з `fastapi-cloud-cli`, який дозволяє розгортати в [FastAPI Cloud](https://fastapicloud.com). - -Якщо ви не хочете мати ці необов’язкові залежності, натомість можете встановити `pip install fastapi`. - -Якщо ви хочете встановити стандартні залежності, але без `fastapi-cloud-cli`, ви можете встановити через `pip install "fastapi[standard-no-fastapi-cloud-cli]"`. +`uvx` - це псевдонім для `uv tool run`. Він запускає Library Skills у тимчасовому ізольованому середовищі, поки Library Skills сканує пакети, встановлені у вашому проєкті. /// -/// tip | Порада - -FastAPI має [офіційне розширення для VS Code](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (та Cursor), яке надає багато можливостей, включно з переглядачем операцій шляху, пошуком операцій шляху, навігацією CodeLens у тестах (перехід до визначення з тестів), а також розгортанням і журналами FastAPI Cloud - усе безпосередньо з вашого редактора. - -/// +Навичка сумісна з Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Pi, OpenCode і більшістю інших агентів для кодування. Для Claude Code виберіть `.claude/skills`, коли вас запитають, куди встановити навичку. ## Просунутий посібник користувача { #advanced-user-guide } diff --git a/docs/uk/docs/tutorial/middleware.md b/docs/uk/docs/tutorial/middleware.md index a31357b..f4972e6 100644 --- a/docs/uk/docs/tutorial/middleware.md +++ b/docs/uk/docs/tutorial/middleware.md @@ -33,11 +33,11 @@ {* ../../docs_src/middleware/tutorial001_py310.py hl[8:9,11,14] *} -/// tip +/// tip | Порада Пам’ятайте, що власні пропрієтарні заголовки можна додавати [використовуючи префікс `X-`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). -Але якщо у вас є власні заголовки, які ви хочете, щоб клієнт у браузері міг побачити, потрібно додати їх до ваших конфігурацій CORS ([CORS (Спільне використання ресурсів між джерелами)](cors.md)) за допомогою параметра `expose_headers`, описаного в [документації Starlette по CORS](https://www.starlette.dev/middleware/#corsmiddleware). +Але якщо у вас є власні заголовки, які ви хочете, щоб клієнт у браузері міг побачити, потрібно додати їх до ваших конфігурацій CORS ([CORS (Спільне використання ресурсів між джерелами)](cors.md)) за допомогою параметра `expose_headers`, описаного в [документації Starlette по CORS](https://starlette.dev/middleware/#corsmiddleware). /// @@ -59,7 +59,7 @@ {* ../../docs_src/middleware/tutorial001_py310.py hl[10,12:13] *} -/// tip +/// tip | Порада Тут ми використовуємо [`time.perf_counter()`](https://docs.python.org/3/library/time.html#time.perf_counter) замість `time.time()` оскільки він може бути більш точним для таких випадків. 🤓 diff --git a/docs/uk/docs/tutorial/path-params.md b/docs/uk/docs/tutorial/path-params.md index 12fdeca..13f4dff 100644 --- a/docs/uk/docs/tutorial/path-params.md +++ b/docs/uk/docs/tutorial/path-params.md @@ -1,6 +1,6 @@ # Параметри шляху { #path-parameters } -Ви можете оголосити «параметри» або «змінні» шляху, використовуючи той самий синтаксис, що й у форматованих рядках Python: +Ви можете оголосити «параметри» або «змінні» шляху, використовуючи той самий синтаксис, що й у форматованих строках Python: {* ../../docs_src/path_params/tutorial001_py310.py hl[6:7] *} @@ -36,9 +36,9 @@ /// tip | Порада -Зверніть увагу, що значення, яке отримала (і повернула) ваша функція, — це `3`, як Python `int`, а не рядок `"3"`. +Зверніть увагу, що значення, яке отримала (і повернула) ваша функція, - це `3`, як Python `int`, а не строка `"3"`. -Отже, з таким оголошенням типу **FastAPI** надає вам автоматичний запит «парсинг». +Отже, з таким оголошенням типу **FastAPI** надає вам автоматичний «парсинг» запиту. /// @@ -92,7 +92,7 @@ ## Переваги стандартів, альтернативна документація { #standards-based-benefits-alternative-documentation } -І оскільки згенерована схема відповідає стандарту [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md), існує багато сумісних інструментів. +І оскільки згенерована схема відповідає стандарту [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md), існує багато сумісних інструментів. Через це **FastAPI** також надає альтернативну API-документацію (використовуючи ReDoc), до якої ви можете отримати доступ за посиланням [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc): @@ -102,17 +102,17 @@ ## Pydantic { #pydantic } -Уся валідація даних виконується за лаштунками за допомогою [Pydantic](https://docs.pydantic.dev/), тож ви отримуєте всі переваги від його використання. І ви знаєте, що ви в надійних руках. +Уся валідація даних виконується за лаштунками за допомогою [Pydantic](https://pydantic.dev/docs/), тож ви отримуєте всі переваги від його використання. І ви знаєте, що ви в надійних руках. Ви можете використовувати ті самі оголошення типів з `str`, `float`, `bool` та багатьма іншими складними типами даних. -Декілька з них розглядаються в наступних розділах посібника. +Декілька з них розглядаються в наступних розділах навчального посібника. ## Порядок має значення { #order-matters } Під час створення *операцій шляху* можуть виникати ситуації, коли у вас є фіксований шлях. -Наприклад, `/users/me` — припустімо, це для отримання даних про поточного користувача. +Наприклад, `/users/me` - припустімо, це для отримання даних про поточного користувача. І тоді у вас також може бути шлях `/users/{user_id}` для отримання даних про конкретного користувача за його ID. @@ -144,13 +144,13 @@ /// tip | Порада -Якщо вам цікаво, «AlexNet», «ResNet» та «LeNet» — це просто назви моделей машинного навчання моделі. +Якщо вам цікаво, «AlexNet», «ResNet» та «LeNet» - це просто назви моделей машинного навчання моделі. /// ### Оголосіть *параметр шляху* { #declare-a-path-parameter } -Потім створіть *параметр шляху* з анотацією типу, використовуючи створений вами клас enum (`ModelName`): +Потім створіть *параметр шляху* з анотацією типу, використовуючи створений вами клас переліку (`ModelName`): {* ../../docs_src/path_params/tutorial005_py310.py hl[16] *} @@ -160,17 +160,17 @@ -### Робота з Python *переліченнями* { #working-with-python-enumerations } +### Робота з Python *переліками* { #working-with-python-enumerations } -Значення *параметра шляху* буде *елементом перелічування*. +Значення *параметра шляху* буде *елементом переліку*. -#### Порівняйте *елементи перелічування* { #compare-enumeration-members } +#### Порівняйте *елементи переліку* { #compare-enumeration-members } -Ви можете порівнювати його з *елементом перелічування* у створеному вами enum `ModelName`: +Ви можете порівнювати його з *елементом переліку* у створеному вами переліку `ModelName`: {* ../../docs_src/path_params/tutorial005_py310.py hl[17] *} -#### Отримайте *значення перелічування* { #get-the-enumeration-value } +#### Отримайте *значення переліку* { #get-the-enumeration-value } Ви можете отримати фактичне значення (у цьому випадку це `str`), використовуючи `model_name.value`, або загалом `your_enum_member.value`: @@ -182,11 +182,11 @@ /// -#### Поверніть *елементи перелічування* { #return-enumeration-members } +#### Поверніть *елементи переліку* { #return-enumeration-members } -Ви можете повертати *елементи enum* з вашої *операції шляху*, навіть вкладені у JSON-тіло (наприклад, `dict`). +Ви можете повертати *елементи переліку* з вашої *операції шляху*, навіть вкладені у JSON-тіло (наприклад, `dict`). -Вони будуть перетворені на відповідні значення (у цьому випадку рядки) перед поверненням клієнту: +Вони будуть перетворені на відповідні значення (у цьому випадку строки) перед поверненням клієнту: {* ../../docs_src/path_params/tutorial005_py310.py hl[18,21,23] *} @@ -223,7 +223,7 @@ OpenAPI не підтримує спосіб оголошення *параме /files/{file_path:path} ``` -У цьому випадку ім’я параметра — `file_path`, а остання частина `:path` вказує, що параметр має відповідати будь-якому *шляху*. +У цьому випадку ім’я параметра - `file_path`, а остання частина `:path` вказує, що параметр має відповідати будь-якому *шляху*. Отже, ви можете використати його так: @@ -242,7 +242,7 @@ OpenAPI не підтримує спосіб оголошення *параме З **FastAPI**, використовуючи короткі, інтуїтивно зрозумілі та стандартні оголошення типів Python, ви отримуєте: * Підтримку редактора: перевірка помилок, автодоповнення тощо. -* Перетворення даних «парсинг» +* Перетворення даних «парсинг» * Валідацію даних * Анотацію API та автоматичну документацію diff --git a/docs/uk/docs/tutorial/query-params-str-validations.md b/docs/uk/docs/tutorial/query-params-str-validations.md index 610e83f..d745bfb 100644 --- a/docs/uk/docs/tutorial/query-params-str-validations.md +++ b/docs/uk/docs/tutorial/query-params-str-validations.md @@ -80,7 +80,7 @@ q: Annotated[str | None] = None Тепер FastAPI: * **Перевірить** дані, щоб переконатися, що їхня максимальна довжина - 50 символів -* Покажe **чітку помилку** клієнту, якщо дані недійсні +* Покаже **чітку помилку** клієнту, якщо дані недійсні * **Задокументує** параметр в *операції шляху* схеми OpenAPI (що відобразиться в **автоматичному інтерфейсі документації**) ## Альтернативний (застарілий) метод: `Query` як значення за замовчуванням { #alternative-old-query-as-the-default-value } @@ -370,11 +370,11 @@ http://127.0.0.1:8000/items/?item-query=foobaritems У таких випадках ви можете використати **кастомну функцію-валідатор**, яка буде застосована після звичайної валідації (наприклад, після перевірки, що значення є типом `str`). -Це можна досягти за допомогою [Pydantic's `AfterValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator) всередині `Annotated`. +Це можна досягти за допомогою [`AfterValidator` від Pydantic](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-after-validator) всередині `Annotated`. /// tip | Порада -Pydantic також має [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator) та інші. 🤓 +Pydantic також має [`BeforeValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-before-validator) та інші. 🤓 /// diff --git a/docs/uk/docs/tutorial/request-files.md b/docs/uk/docs/tutorial/request-files.md index 0785dd2..2b4c4ea 100644 --- a/docs/uk/docs/tutorial/request-files.md +++ b/docs/uk/docs/tutorial/request-files.md @@ -6,10 +6,10 @@ Щоб отримувати завантажені файли, спочатку встановіть [`python-multipart`](https://github.com/Kludex/python-multipart). -Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md), активували його, а потім встановили його, наприклад: +Додайте його до вашого проєкту: ```console -$ pip install python-multipart +$ uv add python-multipart ``` Це необхідно, оскільки завантажені файли передаються як «дані форми». diff --git a/docs/uk/docs/tutorial/request-form-models.md b/docs/uk/docs/tutorial/request-form-models.md index c61eeea..818959c 100644 --- a/docs/uk/docs/tutorial/request-form-models.md +++ b/docs/uk/docs/tutorial/request-form-models.md @@ -6,10 +6,10 @@ Щоб використовувати форми, спочатку встановіть [`python-multipart`](https://github.com/Kludex/python-multipart). -Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md), активували його, а потім встановили його, наприклад: +Додайте його до вашого проєкту: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/uk/docs/tutorial/request-forms-and-files.md b/docs/uk/docs/tutorial/request-forms-and-files.md index 74de801..8410e38 100644 --- a/docs/uk/docs/tutorial/request-forms-and-files.md +++ b/docs/uk/docs/tutorial/request-forms-and-files.md @@ -6,10 +6,10 @@ Щоб отримувати завантажені файли та/або дані форми, спочатку встановіть [`python-multipart`](https://github.com/Kludex/python-multipart). -Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md), активували його, а потім встановили бібліотеку, наприклад: +Додайте його до вашого проєкту: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// @@ -30,7 +30,7 @@ $ pip install python-multipart /// warning | Попередження -Ви можете оголосити кілька параметрів `File` і `Form` в операції *шляху*, але не можете одночасно оголошувати `Body`-поля, які очікуєте отримати у форматі JSON, оскільки запит матиме тіло, закодоване за допомогою `multipart/form-data`, а не `application/json`. +Ви можете оголосити кілька параметрів `File` і `Form` в *операції шляху*, але не можете одночасно оголошувати `Body`-поля, які очікуєте отримати у форматі JSON, оскільки запит матиме тіло, закодоване за допомогою `multipart/form-data`, а не `application/json`. Це не обмеження **FastAPI**, а частина протоколу HTTP. diff --git a/docs/uk/docs/tutorial/request-forms.md b/docs/uk/docs/tutorial/request-forms.md index 3113779..16b60ea 100644 --- a/docs/uk/docs/tutorial/request-forms.md +++ b/docs/uk/docs/tutorial/request-forms.md @@ -6,10 +6,10 @@ Щоб використовувати форми, спочатку встановіть [`python-multipart`](https://github.com/Kludex/python-multipart). -Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md), активували його, і потім встановили бібліотеку, наприклад: +Додайте його до вашого проєкту: ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/uk/docs/tutorial/response-model.md b/docs/uk/docs/tutorial/response-model.md index a5c2972..3795864 100644 --- a/docs/uk/docs/tutorial/response-model.md +++ b/docs/uk/docs/tutorial/response-model.md @@ -1,4 +1,4 @@ -# Модель відповіді — Тип, що повертається { #response-model-return-type } +# Модель відповіді - Тип, що повертається { #response-model-return-type } Ви можете оголосити тип, який використовуватиметься у відповіді, анотувавши **тип повернення** *функції операції шляху*. @@ -10,7 +10,7 @@ FastAPI використовуватиме цей тип повернення, * **Перевірити правильність** повернених даних. * Якщо дані не валідні (наприклад, відсутнє поле), це означає, що *ваш* код застосунку зламаний, не повертає те, що повинен, і буде повернуто помилку сервера замість некоректних даних. Так ви та ваші клієнти можете бути впевнені, що отримаєте дані й очікувану структуру даних. -* Додати **JSON Schema** для відповіді в OpenAPI *операції шляху*. +* Додати **Схему JSON** для відповіді в OpenAPI *операції шляху*. * Це буде використано в **автоматичній документації**. * Це також буде використано інструментами, які автоматично генерують клієнтський код. * **Серіалізувати** повернені дані в JSON за допомогою Pydantic, який написаний мовою **Rust**, тому це буде **набагато швидше**. @@ -76,16 +76,16 @@ FastAPI використовуватиме цей `response_model` для вик Щоб використовувати `EmailStr`, спочатку встановіть [`email-validator`](https://github.com/JoshData/python-email-validator). -Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md), активували його, а потім встановили пакет, наприклад: +Додайте його до вашого проєкту: ```console -$ pip install email-validator +$ uv add email-validator ``` -або так: +або за допомогою: ```console -$ pip install "pydantic[email]" +$ uv add "pydantic[email]" ``` /// @@ -144,7 +144,7 @@ $ pip install "pydantic[email]" {* ../../docs_src/response_model/tutorial003_01_py310.py hl[7:10,13:14,18] *} -Завдяки цьому ми отримуємо підтримку інструментів — від редакторів і mypy, адже цей код коректний з точки зору типів, — але ми також отримуємо фільтрацію даних від FastAPI. +Завдяки цьому ми отримуємо підтримку інструментів - від редакторів і mypy, адже цей код коректний з точки зору типів, але ми також отримуємо фільтрацію даних від FastAPI. Як це працює? Давайте розберемося. 🤓 @@ -168,7 +168,7 @@ FastAPI виконує кілька внутрішніх операцій з Pyd ## Подивитися в документації { #see-it-in-the-docs } -Коли ви дивитеся автоматичну документацію, ви можете перевірити, що вхідна модель і вихідна модель матимуть власну JSON Schema: +Коли ви дивитеся автоматичну документацію, ви можете перевірити, що вхідна модель і вихідна модель матимуть власну Схему JSON: @@ -182,11 +182,11 @@ FastAPI виконує кілька внутрішніх операцій з Pyd ### Повернути Response напряму { #return-a-response-directly } -Найпоширенішим випадком буде [повернення Response напряму, як пояснюється пізніше у просунутому посібнику користувача](../advanced/response-directly.md). +Найпоширенішим випадком буде [повернення Response напряму, як пояснюється пізніше у просунутій документації](../advanced/response-directly.md). {* ../../docs_src/response_model/tutorial003_02_py310.py hl[8,10:11] *} -Цей простий випадок автоматично обробляється FastAPI, тому що анотація типу повернення — це клас (або підклас) `Response`. +Цей простий випадок автоматично обробляється FastAPI, тому що анотація типу повернення - це клас (або підклас) `Response`. І інструменти також будуть задоволені, бо і `RedirectResponse`, і `JSONResponse` є підкласами `Response`, отже анотація типу коректна. @@ -202,7 +202,7 @@ FastAPI виконує кілька внутрішніх операцій з Pyd Але коли ви повертаєте якийсь інший довільний об’єкт, що не є валідним типом Pydantic (наприклад, об’єкт бази даних), і анотуєте його так у функції, FastAPI спробує створити модель відповіді Pydantic на основі цієї анотації типу і це завершиться помилкою. -Те саме станеться, якщо у вас буде об'єднання між різними типами, де один або більше не є валідними типами Pydantic, наприклад, це завершиться помилкою 💥: +Те саме станеться, якщо у вас буде об’єднання між різними типами, де один або більше не є валідними типами Pydantic, наприклад, це завершиться помилкою 💥: {* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *} @@ -258,7 +258,7 @@ FastAPI виконує кілька внутрішніх операцій з Pyd * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -як описано в [документації Pydantic](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict) для `exclude_defaults` та `exclude_none`. +як описано в [документації Pydantic](https://pydantic.dev/docs/validation/latest/concepts/serialization/#excluding-and-including-fields-based-on-their-value) для `exclude_defaults` та `exclude_none`. /// @@ -315,7 +315,7 @@ FastAPI достатньо розумний (насправді, Pydantic дос Але все ж рекомендується використовувати описані вище підходи, застосовуючи кілька класів, замість цих параметрів. -Це тому, що JSON Schema, який генерується в OpenAPI вашого застосунку (і в документації), все одно буде відповідати повній моделі, навіть якщо ви використовуєте `response_model_include` або `response_model_exclude`, щоб пропустити деякі атрибути. +Це тому, що Схема JSON, яка генерується в OpenAPI вашого застосунку (і в документації), все одно буде відповідати повній моделі, навіть якщо ви використовуєте `response_model_include` або `response_model_exclude`, щоб пропустити деякі атрибути. Це також стосується `response_model_by_alias`, який працює подібним чином. diff --git a/docs/uk/docs/tutorial/schema-extra-example.md b/docs/uk/docs/tutorial/schema-extra-example.md index 734a06d..1f642fe 100644 --- a/docs/uk/docs/tutorial/schema-extra-example.md +++ b/docs/uk/docs/tutorial/schema-extra-example.md @@ -12,7 +12,7 @@ Ця додаткова інформація буде додана як є до **Схеми JSON** для цієї моделі, і вона буде використана в документації до API. -Ви можете використати атрибут `model_config`, який приймає `dict`, як описано в [документації Pydantic: Configuration](https://docs.pydantic.dev/latest/api/config/). +Ви можете використати атрибут `model_config`, який приймає `dict`, як описано в [документації Pydantic: Configuration](https://pydantic.dev/docs/validation/latest/api/pydantic/config/). Ви можете встановити `"json_schema_extra"` як `dict`, що містить будь-які додаткові дані, які ви хочете відобразити у згенерованій Схемі JSON, включаючи `examples`. diff --git a/docs/uk/docs/tutorial/security/first-steps.md b/docs/uk/docs/tutorial/security/first-steps.md index 7feee1c..c747459 100644 --- a/docs/uk/docs/tutorial/security/first-steps.md +++ b/docs/uk/docs/tutorial/security/first-steps.md @@ -26,14 +26,14 @@ /// note | Примітка -Пакет [`python-multipart`](https://github.com/Kludex/python-multipart) автоматично встановлюється з **FastAPI**, коли ви виконуєте команду `pip install "fastapi[standard]"`. +Пакет [`python-multipart`](https://github.com/Kludex/python-multipart) автоматично встановлюється з **FastAPI**, коли ви виконуєте команду `uv add "fastapi[standard]"`. -Однак, якщо ви використовуєте команду `pip install fastapi`, пакет `python-multipart` за замовчуванням не включено. +Однак, якщо ви використовуєте команду `uv add fastapi`, пакет `python-multipart` за замовчуванням не включено. -Щоб встановити його вручну, переконайтеся, що ви створили [віртуальне оточення](../../virtual-environments.md), активували його, а потім встановили: +Щоб встановити його вручну, додайте його до вашого проєкту за допомогою: ```console -$ pip install python-multipart +$ uv add python-multipart ``` Це тому, що **OAuth2** використовує «form data» для надсилання `username` та `password`. @@ -45,7 +45,7 @@ $ pip install python-multipart
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/uk/docs/tutorial/security/oauth2-jwt.md b/docs/uk/docs/tutorial/security/oauth2-jwt.md index 1fb53ff..481bf14 100644 --- a/docs/uk/docs/tutorial/security/oauth2-jwt.md +++ b/docs/uk/docs/tutorial/security/oauth2-jwt.md @@ -30,12 +30,12 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4 Нам потрібно встановити `PyJWT`, щоб створювати та перевіряти токени JWT у Python. -Переконайтеся, що ви створили [віртуальне оточення](../../virtual-environments.md), активували його і тоді встановіть `pyjwt`: +Додайте `pyjwt` до вашого проєкту:
```console -$ pip install pyjwt +$ uv add pyjwt ---> 100% ``` @@ -72,12 +72,12 @@ pwdlib - це чудовий пакет Python для роботи з хешам Рекомендований алгоритм - «Argon2». -Переконайтеся, що ви створили [віртуальне оточення](../../virtual-environments.md), активували його і тоді встановіть pwdlib з Argon2: +Додайте `pwdlib` з Argon2 до вашого проєкту:
```console -$ pip install "pwdlib[argon2]" +$ uv add "pwdlib[argon2]" ---> 100% ``` diff --git a/docs/uk/docs/tutorial/sql-databases.md b/docs/uk/docs/tutorial/sql-databases.md index ff29405..16763ea 100644 --- a/docs/uk/docs/tutorial/sql-databases.md +++ b/docs/uk/docs/tutorial/sql-databases.md @@ -34,12 +34,12 @@ ## Встановіть `SQLModel` { #install-sqlmodel } -Спочатку переконайтеся, що ви створили [віртуальне оточення](../virtual-environments.md), активували його та встановили `sqlmodel`: +Додайте `sqlmodel` до вашого проєкту:
```console -$ pip install sqlmodel +$ uv add sqlmodel ---> 100% ``` @@ -49,7 +49,7 @@ $ pip install sqlmodel Спершу створимо найпростішу версію застосунку з однією моделлю **SQLModel**. -Потім нижче покращимо безпеку і гнучкість за допомогою кількох моделей. 🤓 +Потім нижче покращимо безпеку і гнучкість за допомогою **кількох моделей**. 🤓 ### Створіть моделі { #create-models } @@ -152,7 +152,7 @@ SQLModel матиме утиліти міграцій-обгортки над Al
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -337,14 +337,14 @@ $ fastapi dev
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
-Якщо ви перейдете до UI `/docs`, побачите, що він оновився і більше не очікуватиме отримати `id` від клієнта під час створення героя тощо. +Якщо ви перейдете до UI API `/docs`, побачите, що він оновився і більше не очікуватиме отримати `id` від клієнта під час створення героя тощо.
diff --git a/docs/uk/docs/tutorial/static-files.md b/docs/uk/docs/tutorial/static-files.md index 26c3c59..2d12000 100644 --- a/docs/uk/docs/tutorial/static-files.md +++ b/docs/uk/docs/tutorial/static-files.md @@ -4,7 +4,7 @@ /// tip | Порада -Якщо вам потрібно розмістити фронтенд, натомість використовуйте `app.frontend()`, прочитайте про це у [Frontend](frontend.md). +Якщо вам потрібно розмістити фронтенд, натомість використовуйте `app.frontend()`, прочитайте про це у [Фронтенді](frontend.md). `app.frontend()` використовує `StaticFiles` всередині, з кількома додатковими перевагами для фронтендів, як-от обробка клієнтської маршрутизації. @@ -45,4 +45,4 @@ ## Додаткова інформація { #more-info } -Для отримання додаткової інформації та параметрів перевірте [документацію Starlette про Static Files](https://www.starlette.dev/staticfiles/). +Для отримання додаткової інформації та параметрів перевірте [документацію Starlette про Static Files](https://starlette.dev/staticfiles/). diff --git a/docs/uk/docs/tutorial/testing.md b/docs/uk/docs/tutorial/testing.md index 393855a..2398039 100644 --- a/docs/uk/docs/tutorial/testing.md +++ b/docs/uk/docs/tutorial/testing.md @@ -1,6 +1,6 @@ # Тестування { #testing } -Завдяки [Starlette](https://www.starlette.dev/testclient/), тестувати застосунки **FastAPI** просто й приємно. +Завдяки [Starlette](https://starlette.dev/testclient/), тестувати застосунки **FastAPI** просто й приємно. Воно базується на [HTTPX](https://www.python-httpx.org), який, своєю чергою, спроєктований на основі Requests, тож він дуже знайомий та інтуїтивно зрозумілий. @@ -12,10 +12,10 @@ Щоб використовувати `TestClient`, спочатку встановіть [`httpx`](https://www.python-httpx.org). -Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md), активували його, а потім встановили `httpx`, наприклад: +Додайте його до вашого проєкту: ```console -$ pip install httpx +$ uv add httpx ``` /// @@ -130,7 +130,7 @@ $ pip install httpx {* ../../docs_src/app_testing/app_b_an_py310/test_main.py *} -Коли вам потрібно, щоб клієнт передав інформацію в запиті, але ви не знаєте, як це зробити, ви можете пошукати (Google), як це зробити в `httpx`, або навіть як це зробити з `requests`, оскільки дизайн HTTPX базується на дизайні Requests. +Коли вам потрібно, щоб клієнт передав інформацію в запиті, але ви не знаєте, як це зробити, ви можете пошукати (Google), як це зробити в `httpx`, або навіть як це зробити з `requests`, оскільки дизайн HTTPX базується на дизайі Requests. Далі ви просто повторюєте ці ж дії у ваших тестах. @@ -156,12 +156,12 @@ $ pip install httpx Після цього вам потрібно встановити `pytest`. -Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md), активували його і встановили необхідні пакети, наприклад: +Додайте його до вашого проєкту:
```console -$ pip install pytest +$ uv add pytest ---> 100% ``` @@ -175,7 +175,7 @@ $ pip install pytest
```console -$ pytest +$ uv run pytest ================ test session starts ================ platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1 diff --git a/docs/uk/docs/virtual-environments.md b/docs/uk/docs/virtual-environments.md index 57f3e90..d568c64 100644 --- a/docs/uk/docs/virtual-environments.md +++ b/docs/uk/docs/virtual-environments.md @@ -1,864 +1,35 @@ # Віртуальні середовища { #virtual-environments } -Коли ви працюєте над проєктами Python, вам, імовірно, слід використовувати **віртуальне середовище** (або схожий механізм), щоб ізолювати пакети, які ви встановлюєте для кожного проєкту. +Коли ви працюєте над проєктами Python, вам слід використовувати **віртуальне середовище**, щоб ізолювати пакети, встановлені для кожного проєкту. -/// note | Примітка - -Якщо ви вже знаєте про віртуальні середовища, як їх створювати та використовувати, можете пропустити цей розділ. 🤓 - -/// - -/// tip | Порада - -**Віртуальне середовище** відрізняється від **змінної оточення**. - -**Змінна оточення** - це змінна в системі, яку можуть використовувати програми. - -**Віртуальне середовище** - це каталог із файлами в ньому. - -/// - -/// note | Примітка - -На цій сторінці ви дізнаєтеся, як використовувати **віртуальні середовища** і як вони працюють. - -Якщо ви готові прийняти **інструмент, що керує всім** за вас (включно з установленням Python), спробуйте [uv](https://github.com/astral-sh/uv). - -/// +Для проєктів FastAPI я рекомендую використовувати [uv](https://docs.astral.sh/uv/) для керування проєктом, його залежностями та віртуальним середовищем. ## Створіть проєкт { #create-a-project } -Спочатку створіть каталог для вашого проєкту. - -Зазвичай я створюю каталог з назвою `code` у моєму домашньому каталозі користувача. - -І всередині нього я створюю окремий каталог на кожен проєкт. +Встановіть `uv` за допомогою [офіційного посібника зі встановлення](https://docs.astral.sh/uv/getting-started/installation/), а потім створіть проєкт:
```console -// Перейдіть до домашнього каталогу -$ cd -// Створіть каталог для всіх ваших проєктів з кодом -$ mkdir code -// Перейдіть у цей каталог code -$ cd code -// Створіть каталог для цього проєкту -$ mkdir awesome-project -// Перейдіть до каталогу цього проєкту +$ uv init awesome-project --bare $ cd awesome-project +$ uv add "fastapi[standard]" ```
-## Створіть віртуальне середовище { #create-a-virtual-environment } +`uv` автоматично створює віртуальне середовище для проєкту. Вам не потрібно створювати або активувати його самостійно. -Коли ви починаєте працювати над проєктом Python **уперше**, створіть віртуальне середовище **у вашому проєкті**. - -/// tip | Порада - -Це потрібно робити лише **один раз на проєкт**, не щоразу, коли ви працюєте. - -/// - -//// tab | `venv` - -Щоб створити віртуальне середовище, ви можете використати модуль `venv`, який постачається разом із Python. +Виконуйте команди в середовищі проєкту за допомогою `uv run`, наприклад:
```console -$ python -m venv .venv +$ uv run fastapi dev ```
-/// details | Що означає ця команда +## Дізнайтеся більше { #learn-more } -* `python`: використати програму з назвою `python` -* `-m`: викликати модуль як скрипт, далі ми вкажемо, який модуль -* `venv`: використати модуль з назвою `venv`, який зазвичай уже встановлено з Python -* `.venv`: створити віртуальне середовище в новому каталозі `.venv` - -/// - -//// - -//// tab | `uv` - -Якщо у вас встановлено [`uv`](https://github.com/astral-sh/uv), ви можете використати його для створення віртуального середовища. - -
- -```console -$ uv venv -``` - -
- -/// tip | Порада - -Типово `uv` створить віртуальне середовище в каталозі з назвою `.venv`. - -Але ви можете налаштувати це, передавши додатковий аргумент з назвою каталогу. - -/// - -//// - -Ця команда створює нове віртуальне середовище в каталозі з назвою `.venv`. - -/// details | `.venv` або інша назва - -Ви можете створити віртуальне середовище в іншому каталозі, але існує усталена домовленість називати його `.venv`. - -/// - -## Активуйте віртуальне середовище { #activate-the-virtual-environment } - -Активуйте нове віртуальне середовище, щоб будь-яка команда Python, яку ви запускаєте, або пакет, який ви встановлюєте, використовували його. - -/// tip | Порада - -Робіть це **щоразу**, коли ви починаєте **нову сесію термінала** для роботи над проєктом. - -/// - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Або якщо ви використовуєте Bash для Windows (напр., [Git Bash](https://gitforwindows.org/)): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -/// tip | Порада - -Кожного разу, коли ви встановлюєте **новий пакет** у це середовище, **активуйте** середовище знову. - -Це гарантує, що якщо ви використовуєте **програму термінала (CLI)**, встановлену цим пакетом, ви використовуєте саме ту з вашого віртуального середовища, а не будь-яку іншу, яка може бути встановлена глобально, імовірно з іншою версією, ніж вам потрібно. - -/// - -## Перевірте активність віртуального середовища { #check-the-virtual-environment-is-active } - -Перевірте, що віртуальне середовище активне (попередня команда спрацювала). - -/// tip | Порада - -Це **необов'язково**, але це гарний спосіб **перевірити**, що все працює як очікується і ви використовуєте саме те віртуальне середовище, яке планували. - -/// - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -Якщо показано бінарний файл `python` за шляхом `.venv/bin/python` усередині вашого проєкту (у цьому випадку `awesome-project`), тоді все спрацювало. 🎉 - -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -Якщо показано бінарний файл `python` за шляхом `.venv\Scripts\python` усередині вашого проєкту (у цьому випадку `awesome-project`), тоді все спрацювало. 🎉 - -//// - -## Оновіть `pip` { #upgrade-pip } - -/// tip | Порада - -Якщо ви використовуєте [`uv`](https://github.com/astral-sh/uv), ви використовуватимете його для встановлення замість `pip`, тож вам не потрібно оновлювати `pip`. 😎 - -/// - -Якщо ви використовуєте `pip` для встановлення пакетів (він іде за замовчуванням із Python), вам слід **оновити** його до найновішої версії. - -Багато дивних помилок під час встановлення пакета вирішуються тим, що спочатку оновлюють `pip`. - -/// tip | Порада - -Зазвичай це роблять **один раз**, відразу після створення віртуального середовища. - -/// - -Переконайтеся, що віртуальне середовище активне (командою вище), а потім виконайте: - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip | Порада - -Іноді ви можете отримати помилку **`No module named pip`** при спробі оновити pip. - -Якщо це сталося, встановіть і оновіть pip за допомогою команди нижче: - -
- -```console -$ python -m ensurepip --upgrade - ----> 100% -``` - -
- -Ця команда встановить pip, якщо він ще не встановлений, і також гарантує, що встановлена версія pip принаймні така ж нова, як доступна в `ensurepip`. - -/// - -## Додайте `.gitignore` { #add-gitignore } - -Якщо ви використовуєте **Git** (варто це робити), додайте файл `.gitignore`, щоб виключити з Git усе у вашому `.venv`. - -/// tip | Порада - -Якщо ви використали [`uv`](https://github.com/astral-sh/uv) для створення віртуального середовища, він уже зробив це за вас, можете пропустити цей крок. 😎 - -/// - -/// tip | Порада - -Зробіть це **один раз**, відразу після створення віртуального середовища. - -/// - -
- -```console -$ echo "*" > .venv/.gitignore -``` - -
- -/// details | Що означає ця команда - -* `echo "*"`: «виведе» текст `*` у термінал (наступна частина трохи це змінює) -* `>`: усе, що команда ліворуч від `>` «виводить» у термінал, не слід друкувати, натомість записати у файл, вказаний праворуч від `>` -* `.gitignore`: назва файлу, куди слід записати текст - -А `*` для Git означає «все». Тож він ігноруватиме все в каталозі `.venv`. - -Ця команда створить файл `.gitignore` із вмістом: - -```gitignore -* -``` - -/// - -## Встановіть пакети { #install-packages } - -Після активації середовища ви можете встановлювати в нього пакети. - -/// tip | Порада - -Робіть це **один раз** під час встановлення або оновлення пакетів, потрібних вашому проєкту. - -Якщо вам потрібно оновити версію або додати новий пакет, ви **зробите це знову**. - -/// - -### Встановіть пакети безпосередньо { #install-packages-directly } - -Якщо ви поспішаєте та не хочете використовувати файл для оголошення вимог вашого проєкту до пакетів, ви можете встановити їх безпосередньо. - -/// tip | Порада - -Дуже добра ідея - записати пакети та версії, потрібні вашій програмі, у файл (наприклад, `requirements.txt` або `pyproject.toml`). - -/// - -//// tab | `pip` - -
- -```console -$ pip install "fastapi[standard]" - ----> 100% -``` - -
- -//// - -//// tab | `uv` - -Якщо у вас є [`uv`](https://github.com/astral-sh/uv): - -
- -```console -$ uv pip install "fastapi[standard]" ----> 100% -``` - -
- -//// - -### Встановіть з `requirements.txt` { #install-from-requirements-txt } - -Якщо у вас є `requirements.txt`, ви можете використати його для встановлення перелічених там пакетів. - -//// tab | `pip` - -
- -```console -$ pip install -r requirements.txt ----> 100% -``` - -
- -//// - -//// tab | `uv` - -Якщо у вас є [`uv`](https://github.com/astral-sh/uv): - -
- -```console -$ uv pip install -r requirements.txt ----> 100% -``` - -
- -//// - -/// details | `requirements.txt` - -`requirements.txt` із деякими пакетами може виглядати так: - -```requirements.txt -fastapi[standard]==0.113.0 -pydantic==2.8.0 -``` - -/// - -## Запустіть вашу програму { #run-your-program } - -Після активації віртуального середовища ви можете запустити вашу програму, і вона використовуватиме Python із вашого віртуального середовища з пакетами, які ви там встановили. - -
- -```console -$ python main.py - -Hello World -``` - -
- -## Налаштуйте ваш редактор { #configure-your-editor } - -Ймовірно, ви використовуєте редактор коду, переконайтеся, що ви налаштували його на використання того самого віртуального середовища, яке ви створили (швидше за все, він визначить його автоматично), щоб отримувати автодоповнення та підсвічування помилок. - -Наприклад: - -* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) -* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) - -/// tip | Порада - -Зазвичай це потрібно робити лише **один раз**, коли ви створюєте віртуальне середовище. - -/// - -## Деактивуйте віртуальне середовище { #deactivate-the-virtual-environment } - -Коли ви завершили роботу над проєктом, ви можете **деактивувати** віртуальне середовище. - -
- -```console -$ deactivate -``` - -
- -Таким чином, коли ви запустите `python`, він не намагатиметься запускатися з того віртуального середовища з установленими там пакетами. - -## Готові до роботи { #ready-to-work } - -Тепер ви готові почати працювати над вашим проєктом. - - - -/// tip | Порада - -Хочете зрозуміти, що це все було вище? - -Продовжуйте читати. 👇🤓 - -/// - -## Навіщо віртуальні середовища { #why-virtual-environments } - -Щоб працювати з FastAPI, вам потрібно встановити [Python](https://www.python.org/). - -Після цього вам потрібно буде **встановити** FastAPI та інші **пакети**, які ви хочете використовувати. - -Для встановлення пакетів зазвичай використовують команду `pip`, що постачається з Python (або схожі альтернативи). - -Однак, якщо ви просто користуватиметеся `pip` напряму, пакети встановлюватимуться у ваше **глобальне середовище Python** (глобальну інсталяцію Python). - -### Проблема { #the-problem } - -То в чому ж проблема встановлення пакетів у глобальне середовище Python? - -З часом ви, вірогідно, писатимете багато різних програм, які залежать від **різних пакетів**. І деякі з цих ваших проєктів залежатимуть від **різних версій** одного й того ж пакета. 😱 - -Наприклад, ви можете створити проєкт із назвою `philosophers-stone`, ця програма залежить від іншого пакета з назвою **`harry`, використовуючи версію `1`**. Тож вам потрібно встановити `harry`. - -```mermaid -flowchart LR - stone(philosophers-stone) -->|requires| harry-1[harry v1] -``` - -Потім, трохи згодом, ви створюєте інший проєкт із назвою `prisoner-of-azkaban`, і цей проєкт також залежить від `harry`, але йому потрібна **версія `harry` `3`**. - -```mermaid -flowchart LR - azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3] -``` - -Але тепер проблема в тому, що якщо ви встановлюєте пакети глобально (у глобальне середовище), а не у локальне **віртуальне середовище**, вам доведеться вибирати, яку версію `harry` встановити. - -Якщо ви хочете запустити `philosophers-stone`, вам спочатку потрібно встановити `harry` версії `1`, наприклад, так: - -
- -```console -$ pip install "harry==1" -``` - -
- -У підсумку у вас буде встановлено `harry` версії `1` у глобальному середовищі Python. - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -->|requires| harry-1 - end -``` - -Але якщо ви захочете запустити `prisoner-of-azkaban`, вам доведеться видалити `harry` версії `1` і встановити `harry` версії `3` (або просто встановлення версії `3` автоматично видалить версію `1`). - -
- -```console -$ pip install "harry==3" -``` - -
- -У підсумку у вас буде встановлено `harry` версії `3` у глобальному середовищі Python. - -А якщо ви знову спробуєте запустити `philosophers-stone`, є шанс, що він **не працюватиме**, тому що йому потрібен `harry` версії `1`. - -```mermaid -flowchart LR - subgraph global[global env] - harry-1[harry v1] - style harry-1 fill:#ccc,stroke-dasharray: 5 5 - harry-3[harry v3] - end - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) -.-x|⛔️| harry-1 - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --> |requires| harry-3 - end -``` - -/// tip | Порада - -У пакетах Python дуже поширена практика намагатися якнайкраще **уникати несумісних змін** у **нових версіях**, але краще підстрахуватися та встановлювати новіші версії свідомо і тоді, коли ви можете запустити тести, щоб перевірити, що все працює коректно. - -/// - -Тепер уявіть те саме з **багатьма** іншими **пакетами**, від яких залежать усі ваші **проєкти**. Це дуже складно керувати. І ви, імовірно, запускатимете деякі проєкти з деякими **несумісними версіями** пакетів і не розумітимете, чому щось не працює. - -Також, залежно від вашої операційної системи (напр., Linux, Windows, macOS), у ній може бути вже встановлений Python. І в такому разі, імовірно, уже будуть попередньо встановлені деякі пакети з певними версіями, **потрібними вашій системі**. Якщо ви встановлюєте пакети в глобальне середовище Python, ви можете **зламати** деякі програми, що постачаються з вашою операційною системою. - -## Де встановлюються пакети { #where-are-packages-installed } - -Коли ви встановлюєте Python, він створює на вашому комп'ютері кілька каталогів із деякими файлами. - -Деякі з цих каталогів відповідають за зберігання всіх пакетів, які ви встановлюєте. - -Коли ви запускаєте: - -
- -```console -// Не запускайте це зараз, це лише приклад 🤓 -$ pip install "fastapi[standard]" ----> 100% -``` - -
- -Це завантажить стиснений файл з кодом FastAPI, зазвичай із [PyPI](https://pypi.org/project/fastapi/). - -Також будуть **завантажені** файли для інших пакетів, від яких залежить FastAPI. - -Потім усе це буде **розпаковано** та покладено в каталог на вашому комп'ютері. - -Типово ці завантажені та розпаковані файли будуть покладені в каталог, що постачається з вашою інсталяцією Python, це **глобальне середовище**. - -## Що таке віртуальні середовища { #what-are-virtual-environments } - -Рішенням проблеми з наявністю всіх пакетів у глобальному середовищі є використання **віртуального середовища для кожного проєкту**, над яким ви працюєте. - -Віртуальне середовище - це **каталог**, дуже схожий на глобальний, у якому ви можете встановлювати пакети для конкретного проєкту. - -Таким чином кожен проєкт матиме власне віртуальне середовище (каталог `.venv`) із власними пакетами. - -```mermaid -flowchart TB - subgraph stone-project[philosophers-stone project] - stone(philosophers-stone) --->|requires| harry-1 - subgraph venv1[.venv] - harry-1[harry v1] - end - end - subgraph azkaban-project[prisoner-of-azkaban project] - azkaban(prisoner-of-azkaban) --->|requires| harry-3 - subgraph venv2[.venv] - harry-3[harry v3] - end - end - stone-project ~~~ azkaban-project -``` - -## Що означає активація віртуального середовища { #what-does-activating-a-virtual-environment-mean } - -Коли ви активуєте віртуальне середовище, наприклад так: - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Або якщо ви використовуєте Bash для Windows (напр., [Git Bash](https://gitforwindows.org/)): - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -Ця команда створить або змінить деякі [змінні оточення](environment-variables.md), які будуть доступні для наступних команд. - -Однією з цих змінних є змінна `PATH`. - -/// tip | Порада - -Ви можете дізнатися більше про змінну оточення `PATH` у розділі [Змінні оточення](environment-variables.md#path-environment-variable). - -/// - -Активація віртуального середовища додає його шлях `.venv/bin` (на Linux і macOS) або `.venv\Scripts` (на Windows) до змінної оточення `PATH`. - -Скажімо, до активації середовища змінна `PATH` виглядала так: - -//// tab | Linux, macOS - -```plaintext -/usr/bin:/bin:/usr/sbin:/sbin -``` - -Це означає, що система шукатиме програми в: - -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Windows\System32 -``` - -Це означає, що система шукатиме програми в: - -* `C:\Windows\System32` - -//// - -Після активації віртуального середовища змінна `PATH` виглядатиме приблизно так: - -//// tab | Linux, macOS - -```plaintext -/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -Це означає, що система тепер спочатку шукатиме програми в: - -```plaintext -/home/user/code/awesome-project/.venv/bin -``` - -перед тим, як шукати в інших каталогах. - -Тож коли ви введете `python` у терміналі, система знайде програму Python у - -```plaintext -/home/user/code/awesome-project/.venv/bin/python -``` - -і використає саме її. - -//// - -//// tab | Windows - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32 -``` - -Це означає, що система тепер спочатку шукатиме програми в: - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts -``` - -перед тим, як шукати в інших каталогах. - -Тож коли ви введете `python` у терміналі, система знайде програму Python у - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -і використає саме її. - -//// - -Важлива деталь: шлях до віртуального середовища буде додано на **початок** змінної `PATH`. Система знайде його **раніше** за будь-який інший доступний Python. Таким чином, коли ви запускаєте `python`, використовується саме Python **із віртуального середовища**, а не будь-який інший `python` (наприклад, з глобального середовища). - -Активація віртуального середовища також змінює ще кілька речей, але це одна з найважливіших. - -## Перевірка віртуального середовища { #checking-a-virtual-environment } - -Коли ви перевіряєте, чи активне віртуальне середовище, наприклад так: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -//// - -Це означає, що програма `python`, яка буде використана, знаходиться **у віртуальному середовищі**. - -На Linux і macOS використовують `which`, а в Windows PowerShell - `Get-Command`. - -Принцип роботи цієї команди в тому, що вона перевіряє змінну оточення `PATH`, проходячи по **кожному шляху по порядку**, шукаючи програму з назвою `python`. Щойно вона її знайде, вона **покаже вам шлях** до цієї програми. - -Найважливіше, що коли ви викликаєте `python`, це рівно той «`python`», який буде виконаний. - -Отже, ви можете підтвердити, чи перебуваєте в правильному віртуальному середовищі. - -/// tip | Порада - -Легко активувати одне віртуальне середовище, отримати один Python, а потім **перейти до іншого проєкту**. - -І другий проєкт **не працюватиме**, бо ви використовуєте **некоректний Python** з віртуального середовища іншого проєкту. - -Корисно вміти перевіряти, який саме `python` використовується. 🤓 - -/// - -## Навіщо деактивувати віртуальне середовище { #why-deactivate-a-virtual-environment } - -Наприклад, ви працюєте над проєктом `philosophers-stone`, **активували його віртуальне середовище**, встановили пакети та працюєте з цим середовищем. - -А потім ви хочете працювати над **іншим проєктом** `prisoner-of-azkaban`. - -Ви переходите до цього проєкту: - -
- -```console -$ cd ~/code/prisoner-of-azkaban -``` - -
- -Якщо ви не деактивуєте віртуальне середовище для `philosophers-stone`, коли ви запустите `python` у терміналі, він спробує використовувати Python із `philosophers-stone`. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -$ python main.py - -// Помилка імпорту sirius, його не встановлено 😱 -Traceback (most recent call last): - File "main.py", line 1, in - import sirius -``` - -
- -Але якщо ви деактивуєте віртуальне середовище і активуєте нове для `prisoner-of-azkaban`, тоді при запуску `python` він використовуватиме Python із віртуального середовища в `prisoner-of-azkaban`. - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -// Вам не потрібно бути в старому каталозі, щоб деактивувати, це можна зробити будь-де, навіть після переходу до іншого проєкту 😎 -$ deactivate - -// Активуйте віртуальне середовище в prisoner-of-azkaban/.venv 🚀 -$ source .venv/bin/activate - -// Тепер, коли ви запускаєте python, він знайде пакет sirius, встановлений у цьому віртуальному середовищі ✨ -$ python main.py - -I solemnly swear 🐺 -``` - -
- -## Альтернативи { #alternatives } - -Це простий посібник, щоб ви швидко стартували та зрозуміли, як усе працює **«під капотом»**. - -Існує багато **альтернатив** керування віртуальними середовищами, залежностями пакетів (вимогами), проєктами. - -Коли будете готові й захочете використовувати інструмент для **керування всім проєктом**, залежностями пакетів, віртуальними середовищами тощо, я раджу спробувати [uv](https://github.com/astral-sh/uv). - -`uv` уміє багато чого, зокрема: - -* **Встановлювати Python** для вас, включно з різними версіями -* Керувати **віртуальним середовищем** ваших проєктів -* Встановлювати **пакети** -* Керувати **залежностями і версіями** пакетів у вашому проєкті -* Гарантувати, що у вас є **точний** набір пакетів і версій для встановлення, включно з їхніми залежностями, щоб ви були певні, що зможете запустити ваш проєкт у продакшені точно так само, як і на вашому комп'ютері під час розробки - це називається **блокуванням** -* І багато іншого - -## Висновок { #conclusion } - -Якщо ви все це прочитали й зрозуміли, тепер **ви знаєте значно більше** про віртуальні середовища, ніж багато розробників. 🤓 - -Знання цих деталей, найімовірніше, стане в пригоді в майбутньому, коли ви налагоджуватимете щось, що виглядає складним, але ви знатимете, **як усе працює «під капотом»**. 😎 +Прочитайте [посібник з віртуальних середовищ](https://tiangolo.com/guides/virtual-environments/), щоб дізнатися, як віртуальні середовища працюють під капотом, включно з активацією та альтернативним робочим процесом із `python -m venv` і `pip`. diff --git a/docs/zh-hant/docs/advanced/additional-responses.md b/docs/zh-hant/docs/advanced/additional-responses.md index 552ce2e..9bcfd70 100644 --- a/docs/zh-hant/docs/advanced/additional-responses.md +++ b/docs/zh-hant/docs/advanced/additional-responses.md @@ -243,5 +243,5 @@ new_dict = {**old_dict, "new key": "new value"} 若要查看回應中究竟可以包含哪些內容，你可以參考 OpenAPI 規範中的這些章節： -* [OpenAPI Responses 物件](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object)，其中包含 `Response Object`。 -* [OpenAPI Response 物件](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object)，你可以把這裡的任何內容直接放到 `responses` 參數內各個回應中。包含 `description`、`headers`、`content`（在其中宣告不同的媒體型別與 JSON Schemas）、以及 `links`。 +* [OpenAPI Responses 物件](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object)，其中包含 `Response Object`。 +* [OpenAPI Response 物件](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object)，你可以把這裡的任何內容直接放到 `responses` 參數內各個回應中。包含 `description`、`headers`、`content`（在其中宣告不同的媒體型別與 JSON Schemas）、以及 `links`。 diff --git a/docs/zh-hant/docs/advanced/async-tests.md b/docs/zh-hant/docs/advanced/async-tests.md index 639c42b..6ea583f 100644 --- a/docs/zh-hant/docs/advanced/async-tests.md +++ b/docs/zh-hant/docs/advanced/async-tests.md @@ -1,6 +1,6 @@ # 非同步測試 { #async-tests } -你已經看過如何使用提供的 `TestClient` 來測試你的 FastAPI 應用。到目前為止，你只看到如何撰寫同步測試，沒有使用 `async` 函式。 +你已經看過如何使用提供的 `TestClient` 來測試你的 **FastAPI** 應用。到目前為止，你只看到如何撰寫同步測試，沒有使用 `async` 函式。 在測試中能使用非同步函式會很有用，例如當你以非同步方式查詢資料庫時。想像你想測試發送請求到 FastAPI 應用，然後在使用非同步資料庫函式庫時，驗證後端是否成功把正確資料寫入資料庫。 @@ -12,7 +12,7 @@ ## HTTPX { #httpx } -即使你的 FastAPI 應用使用一般的 `def` 函式而非 `async def`，它在底層仍然是個 `async` 應用。 +即使你的 **FastAPI** 應用使用一般的 `def` 函式而非 `async def`，它在底層仍然是個 `async` 應用。 `TestClient` 在內部做了一些魔法，讓我們能在一般的 `def` 測試函式中，使用標準 pytest 來呼叫非同步的 FastAPI 應用。但當我們在非同步函式中使用它時，這個魔法就不再奏效了。也就是說，當以非同步方式執行測試時，就不能在測試函式內使用 `TestClient`。 @@ -40,12 +40,12 @@ ## 執行 { #run-it } -如常執行測試： +你可以像往常一樣透過以下方式執行測試：
```console -$ pytest +$ uv run pytest ---> 100% ``` @@ -74,7 +74,7 @@ $ pytest response = client.get('/') ``` -也就是先前用 `TestClient` 發送請求時所用的寫法。 +...也就是我們先前用 `TestClient` 發送請求時所用的寫法。 /// tip @@ -90,7 +90,7 @@ response = client.get('/') ## 其他非同步函式呼叫 { #other-asynchronous-function-calls } -由於測試函式現在是非同步的，你也可以在測試中呼叫（並 `await`）其他 `async` 函式，和在程式碼其他地方一樣。 +由於測試函式現在是非同步的，除了在測試中向你的 FastAPI 應用發送請求之外，你也可以呼叫（並 `await`）其他 `async` 函式，就像在程式碼其他地方呼叫它們一樣。 /// tip diff --git a/docs/zh-hant/docs/advanced/behind-a-proxy.md b/docs/zh-hant/docs/advanced/behind-a-proxy.md index a7f4b83..feb3bab 100644 --- a/docs/zh-hant/docs/advanced/behind-a-proxy.md +++ b/docs/zh-hant/docs/advanced/behind-a-proxy.md @@ -33,7 +33,7 @@
```console -$ fastapi run --forwarded-allow-ips="*" +$ uv run fastapi run --forwarded-allow-ips="*" INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -170,7 +170,7 @@ IP `0.0.0.0` 通常用來表示程式在該機器／伺服器上的所有可用
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -200,7 +200,7 @@ ASGI 規格針對這種用例定義了 `root_path`。
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -253,7 +253,7 @@ Uvicorn 會預期代理以 `http://127.0.0.1:8000/app` 來存取 Uvicorn，而 你可以很容易地用 [Traefik](https://docs.traefik.io/) 在本機跑一個「移除路徑前綴」的測試。 -[下載 Traefik](https://github.com/containous/traefik/releases)，它是一個單一的執行檔，你可以解壓縮後直接在終端機執行。 +[下載 Traefik](https://github.com/traefik/traefik/releases)，它是一個單一的執行檔，你可以解壓縮後直接在終端機執行。 然後建立一個 `traefik.toml` 檔案，內容如下： @@ -321,7 +321,7 @@ INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/zh-hant/docs/advanced/dataclasses.md b/docs/zh-hant/docs/advanced/dataclasses.md index 64ba7dd..4866046 100644 --- a/docs/zh-hant/docs/advanced/dataclasses.md +++ b/docs/zh-hant/docs/advanced/dataclasses.md @@ -6,15 +6,15 @@ FastAPI 建立在 **Pydantic** 之上，我之前示範過如何使用 Pydantic {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -這之所以可行，要感謝 **Pydantic**，因為它 [內建支援 `dataclasses`](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel)。 +這之所以可行，要感謝 **Pydantic**，因為它 [內建支援 `dataclasses`](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/#usage-of-stdlib-dataclasses-with-basemodel)。 所以，即使上面的程式碼沒有明確使用 Pydantic，FastAPI 仍會使用 Pydantic 將那些標準的 dataclass 轉換為 Pydantic 版本的 dataclass。 而且當然一樣支援： -- 資料驗證 -- 資料序列化 -- 資料文件化等 +* 資料驗證 +* 資料序列化 +* 資料文件化等 它的運作方式與 Pydantic 模型相同；實際上，底層就是透過 Pydantic 達成的。 @@ -51,26 +51,34 @@ FastAPI 建立在 **Pydantic** 之上，我之前示範過如何使用 Pydantic {* ../../docs_src/dataclasses_/tutorial003_py310.py hl[1,4,7:10,13:16,22:24,27] *} 1. 我們仍然從標準的 `dataclasses` 匯入 `field`。 + 2. `pydantic.dataclasses` 是 `dataclasses` 的可直接替換版本。 + 3. `Author` dataclass 內含一個 `Item` dataclass 的清單。 + 4. `Author` dataclass 被用作 `response_model` 參數。 + 5. 你可以將其他標準型別註記與 dataclass 一起用作請求本文。 - 在此例中，它是 `Item` dataclass 的清單。 + 在此例中，它是 `Item` dataclass 的清單。 + 6. 這裡我們回傳一個字典，其中的 `items` 是一個 dataclass 清單。 - FastAPI 仍能將資料序列化為 JSON。 + FastAPI 仍能將資料序列化為 JSON。 + 7. 這裡 `response_model` 使用的是「`Author` dataclass 的清單」這種型別註記。 - 同樣地，你可以把 `dataclasses` 與標準型別註記組合使用。 + 同樣地，你可以把 `dataclasses` 與標準型別註記組合使用。 + 8. 注意這個*路徑操作函式*使用的是一般的 `def` 而非 `async def`。 - 一如往常，在 FastAPI 中你可以視需要混用 `def` 與 `async def`。 + 一如往常，在 FastAPI 中你可以視需要混用 `def` 與 `async def`。 + + 如果需要複習何時用哪個，請參考文件中關於 [`async` 與 `await`](../async.md#in-a-hurry) 的章節 _「趕時間？」_。 - 如果需要複習何時用哪個，請參考文件中關於 [`async` 與 `await`](../async.md#in-a-hurry) 的章節 _「趕時間？」_。 9. 這個*路徑操作函式*回傳的不是 dataclass（雖然也可以），而是一個包含內部資料的字典清單。 - FastAPI 會使用 `response_model` 參數（其中包含 dataclass）來轉換回應。 + FastAPI 會使用 `response_model` 參數（其中包含 dataclass）來轉換回應。 你可以把 `dataclasses` 與其他型別註記以多種方式組合，形成複雜的資料結構。 @@ -80,7 +88,7 @@ FastAPI 建立在 **Pydantic** 之上，我之前示範過如何使用 Pydantic 你也可以將 `dataclasses` 與其他 Pydantic 模型結合、從它們繼承、把它們包含進你的自訂模型等。 -想了解更多，請參考 [Pydantic 關於 dataclasses 的文件](https://docs.pydantic.dev/latest/concepts/dataclasses/)。 +想了解更多，請參考 [Pydantic 關於 dataclasses 的文件](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/)。 ## 版本 { #version } diff --git a/docs/zh-hant/docs/advanced/events.md b/docs/zh-hant/docs/advanced/events.md index e132d9f..c6dda91 100644 --- a/docs/zh-hant/docs/advanced/events.md +++ b/docs/zh-hant/docs/advanced/events.md @@ -155,7 +155,7 @@ async with lifespan(app): /// note -你可以在 [Starlette 的 Lifespan 文件](https://www.starlette.dev/lifespan/) 讀到更多關於 Starlette `lifespan` 處理器的資訊。 +你可以在 [Starlette 的 Lifespan 文件](https://starlette.dev/lifespan/) 讀到更多關於 Starlette `lifespan` 處理器的資訊。 也包含如何處理可在程式其他區域使用的 lifespan 狀態。 diff --git a/docs/zh-hant/docs/advanced/generate-clients.md b/docs/zh-hant/docs/advanced/generate-clients.md index cc7a686..4c2846b 100644 --- a/docs/zh-hant/docs/advanced/generate-clients.md +++ b/docs/zh-hant/docs/advanced/generate-clients.md @@ -12,7 +12,7 @@ 針對 **TypeScript 用戶端**，[Hey API](https://heyapi.dev/) 是專門打造的解決方案，為 TypeScript 生態系提供最佳化的體驗。 -你可以在 [OpenAPI.Tools](https://openapi.tools/#sdk) 找到更多 SDK 產生器。 +你可以在 [OpenAPI.Tools](https://openapi.tools/categories/sdk-generators) 找到更多 SDK 產生器。 /// tip @@ -179,9 +179,9 @@ npx @hey-api/openapi-ts -i ./openapi.json -o src/client 使用自動產生的用戶端時，你會得到以下項目的**自動完成**： -* 方法 -* Body 中的請求有效載荷、查詢參數等 -* 回應的有效載荷 +* 方法。 +* Body 中的請求有效載荷、查詢參數等。 +* 回應的有效載荷。 你也會對所有內容獲得**行內錯誤**提示。 diff --git a/docs/zh-hant/docs/advanced/middleware.md b/docs/zh-hant/docs/advanced/middleware.md index d8a5339..a11d4eb 100644 --- a/docs/zh-hant/docs/advanced/middleware.md +++ b/docs/zh-hant/docs/advanced/middleware.md @@ -91,7 +91,7 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") 例如： -- [Uvicorn 的 `ProxyHeadersMiddleware`](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) +- [Uvicorn 的 `ProxyHeadersMiddleware`](https://github.com/Kludex/uvicorn/blob/main/uvicorn/middleware/proxy_headers.py) - [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -想瞭解更多可用的中介軟體，請參考 [Starlette 的中介軟體文件](https://www.starlette.dev/middleware/) 與 [ASGI 精選清單](https://github.com/florimondmanca/awesome-asgi)。 +想瞭解更多可用的中介軟體，請參考 [Starlette 的中介軟體文件](https://starlette.dev/middleware/) 與 [ASGI 精選清單](https://github.com/florimondmanca/awesome-asgi)。 diff --git a/docs/zh-hant/docs/advanced/openapi-callbacks.md b/docs/zh-hant/docs/advanced/openapi-callbacks.md index 6ab869a..a1ea394 100644 --- a/docs/zh-hant/docs/advanced/openapi-callbacks.md +++ b/docs/zh-hant/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ /// tip -`callback_url` 查詢參數使用的是 Pydantic 的 [Url](https://docs.pydantic.dev/latest/api/networks/) 型別。 +`callback_url` 查詢參數使用的是 Pydantic 的 [Url](https://pydantic.dev/docs/validation/latest/api/pydantic/networks/) 型別。 /// @@ -106,11 +106,11 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) 和一般「路徑操作」相比有兩個主要差異： * 不需要任何實際程式碼，因為你的應用永遠不會呼叫這段程式。它只用來文件化「外部 API」。因此函式可以只有 `pass`。 -* 「路徑」可以包含一個 [OpenAPI 3 表達式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)（見下文），可使用參數與原始送到「你的 API」的請求中的部分欄位。 +* 「路徑」可以包含一個 [OpenAPI 3 表達式](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression)（見下文），可使用參數與原始送到「你的 API」的請求中的部分欄位。 ### 回呼路徑表達式 { #the-callback-path-expression } -回呼的「路徑」可以包含一個 [OpenAPI 3 表達式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)，能引用原本送到「你的 API」的請求中的部分內容。 +回呼的「路徑」可以包含一個 [OpenAPI 3 表達式](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression)，能引用原本送到「你的 API」的請求中的部分內容。 在這個例子中，它是一個 `str`： diff --git a/docs/zh-hant/docs/advanced/response-cookies.md b/docs/zh-hant/docs/advanced/response-cookies.md index b275523..ef471aa 100644 --- a/docs/zh-hant/docs/advanced/response-cookies.md +++ b/docs/zh-hant/docs/advanced/response-cookies.md @@ -48,4 +48,4 @@ /// -想查看所有可用的參數與選項，請參閱 [Starlette 文件](https://www.starlette.dev/responses/#set-cookie)。 +想查看所有可用的參數與選項，請參閱 [Starlette 文件](https://starlette.dev/responses/#set-cookie)。 diff --git a/docs/zh-hant/docs/advanced/response-headers.md b/docs/zh-hant/docs/advanced/response-headers.md index 002fb0e..9612e6b 100644 --- a/docs/zh-hant/docs/advanced/response-headers.md +++ b/docs/zh-hant/docs/advanced/response-headers.md @@ -38,4 +38,4 @@ 請記住，專有的自訂標頭可以[使用 `X-` 前綴](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)來新增。 -但如果你有自訂標頭並希望瀏覽器端的客戶端能看見它們，你需要把這些標頭加入到 CORS 設定中（詳見 [CORS（跨來源資源共用）](../tutorial/cors.md)），使用在[Starlette 的 CORS 文件](https://www.starlette.dev/middleware/#corsmiddleware)中記載的 `expose_headers` 參數。 +但如果你有自訂標頭並希望瀏覽器端的客戶端能看見它們，你需要把這些標頭加入到 CORS 設定中（詳見 [CORS（跨來源資源共用）](../tutorial/cors.md)），使用在[Starlette 的 CORS 文件](https://starlette.dev/middleware/#corsmiddleware)中記載的 `expose_headers` 參數。 diff --git a/docs/zh-hant/docs/advanced/settings.md b/docs/zh-hant/docs/advanced/settings.md index 4ec1ea6..912f42f 100644 --- a/docs/zh-hant/docs/advanced/settings.md +++ b/docs/zh-hant/docs/advanced/settings.md @@ -6,9 +6,13 @@ 因此，通常會透過環境變數提供這些設定，讓應用程式去讀取。 +**環境變數**（也稱為 **env var**）是存在於 Python 程式碼之外、作業系統中的值，並可由你的應用程式與其他程式讀取。 + +你可以在執行指令時為該指令建立環境變數。你會在下方看到各平台專用的指令。 + /// tip -若想了解環境變數，你可以閱讀[環境變數](../environment-variables.md)。 +請閱讀[環境變數指南](https://tiangolo.com/guides/environment-variables/)以詳細了解環境變數的運作方式。 /// @@ -20,27 +24,27 @@ ## Pydantic `Settings` { #pydantic-settings } -幸好，Pydantic 提供了很好的工具，可用來處理由環境變數而來的設定：[Pydantic：設定管理](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)。 +幸好，Pydantic 提供了很好的工具，可用來處理由環境變數而來的設定：[Pydantic：設定管理](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/)。 ### 安裝 `pydantic-settings` { #install-pydantic-settings } -首先，請先建立你的[虛擬環境](../virtual-environments.md)，啟用它，然後安裝 `pydantic-settings` 套件： +將 `pydantic-settings` 套件加入你的專案：
```console -$ pip install pydantic-settings +$ uv add pydantic-settings ---> 100% ```
-當你用 `all` extras 安裝時，它也會一併包含在內： +當你用以下方式安裝 `all` extras 時，它也會一併包含在內：
```console -$ pip install "fastapi[all]" +$ uv add "fastapi[all]" ---> 100% ``` @@ -74,21 +78,41 @@ $ pip install "fastapi[all]" ### 執行伺服器 { #run-the-server } -接下來，你可以在啟動伺服器時，將設定以環境變數傳入。舉例來說，你可以設定 `ADMIN_EMAIL` 與 `APP_NAME`： +接下來，你可以在啟動伺服器時，將設定以環境變數傳入。例如，你可以用以下方式設定 `ADMIN_EMAIL` 與 `APP_NAME`： + +//// tab | Linux, macOS, Windows Bash
```console -$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py +$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uv run fastapi run main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
+//// + +//// tab | Windows PowerShell + +
+ +```console +$ $Env:ADMIN_EMAIL = "deadpool@example.com" +$ $Env:APP_NAME = "ChimichangApp" +$ uv run fastapi run main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +//// + /// tip -要為單一指令設定多個環境變數，只要用空白分隔它們，並全部放在指令前面即可。 +在 Bash 中，要為單一指令設定多個環境變數，只要用空白分隔它們，並全部放在指令前面即可。 /// @@ -172,11 +196,11 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p /// -Pydantic 透過外部函式庫支援讀取這類型的檔案。你可以閱讀更多：[Pydantic Settings：Dotenv (.env) 支援](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support)。 +Pydantic 透過外部函式庫支援讀取這類型的檔案。你可以閱讀更多：[Pydantic Settings：Dotenv (.env) 支援](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#dotenv-env-support)。 /// tip -要讓這個功能運作，你需要 `pip install python-dotenv`。 +要讓這個功能運作，請用 `uv add python-dotenv` 將 `python-dotenv` 加入你的專案。 /// @@ -197,7 +221,7 @@ APP_NAME="ChimichangApp" /// tip -`model_config` 屬性僅用於 Pydantic 的設定。你可以閱讀更多：[Pydantic：概念：設定](https://docs.pydantic.dev/latest/concepts/config/)。 +`model_config` 屬性僅用於 Pydantic 的設定。你可以閱讀更多：[Pydantic：概念：設定](https://pydantic.dev/docs/validation/latest/concepts/config/)。 /// diff --git a/docs/zh-hant/docs/advanced/sub-applications.md b/docs/zh-hant/docs/advanced/sub-applications.md index 7199e6d..1afef7d 100644 --- a/docs/zh-hant/docs/advanced/sub-applications.md +++ b/docs/zh-hant/docs/advanced/sub-applications.md @@ -35,7 +35,7 @@
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/zh-hant/docs/advanced/templates.md b/docs/zh-hant/docs/advanced/templates.md index 6e622d5..2f200ed 100644 --- a/docs/zh-hant/docs/advanced/templates.md +++ b/docs/zh-hant/docs/advanced/templates.md @@ -8,12 +8,12 @@ ## 安裝相依套件 { #install-dependencies } -請先建立一個[虛擬環境](../virtual-environments.md)、啟用它，然後安裝 `jinja2`： +將 `jinja2` 加入你的專案：
```console -$ pip install jinja2 +$ uv add jinja2 ---> 100% ``` @@ -22,10 +22,10 @@ $ pip install jinja2 ## 使用 `Jinja2Templates` { #using-jinja2templates } -- 匯入 `Jinja2Templates`。 -- 建立一個可重複使用的 `templates` 物件。 -- 在會回傳模板的「*路徑操作（path operation）*」中宣告一個 `Request` 參數。 -- 使用你建立的 `templates` 來渲染並回傳 `TemplateResponse`，傳入模板名稱、`request` 物件，以及在 Jinja2 模板中使用的「context」鍵值對字典。 +* 匯入 `Jinja2Templates`。 +* 建立一個可重複使用的 `templates` 物件。 +* 在會回傳模板的「*路徑操作（path operation）*」中宣告一個 `Request` 參數。 +* 使用你建立的 `templates` 來渲染並回傳 `TemplateResponse`，傳入模板名稱、`request` 物件，以及在 Jinja2 模板中使用的「context」鍵值對字典。 {* ../../docs_src/templates/tutorial001_py310.py hl[4,11,15:18] *} @@ -123,4 +123,4 @@ Item ID: 42 ## 更多細節 { #more-details } -想了解更多細節（包含如何測試模板），請參考 [Starlette 的模板說明文件](https://www.starlette.dev/templates/)。 +想了解更多細節（包含如何測試模板），請參考 [Starlette 的模板說明文件](https://starlette.dev/templates/)。 diff --git a/docs/zh-hant/docs/advanced/testing-events.md b/docs/zh-hant/docs/advanced/testing-events.md index db67897..f880885 100644 --- a/docs/zh-hant/docs/advanced/testing-events.md +++ b/docs/zh-hant/docs/advanced/testing-events.md @@ -1,11 +1,12 @@ # 測試事件：lifespan 與 startup - shutdown { #testing-events-lifespan-and-startup-shutdown } -當你需要在測試中執行 lifespan（生命週期）時，你可以使用 TestClient 並搭配 with 陳述式： +當你需要在測試中執行 `lifespan` 時，你可以使用 `TestClient` 並搭配 `with` 陳述式： {* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *} -你可以閱讀更多細節：[在測試中執行 lifespan](https://www.starlette.dev/lifespan/#running-lifespan-in-tests)（Starlette 官方文件）。 -對於已棄用的 `startup` 和 `shutdown` 事件，你可以這樣使用 TestClient： +你可以閱讀更多關於[「在官方 Starlette 文件網站中在測試中執行 lifespan。」](https://starlette.dev/lifespan/#running-lifespan-in-tests)的細節 + +對於已棄用的 `startup` 和 `shutdown` 事件，你可以這樣使用 `TestClient`： {* ../../docs_src/app_testing/tutorial003_py310.py hl[9:12,20:24] *} diff --git a/docs/zh-hant/docs/advanced/testing-websockets.md b/docs/zh-hant/docs/advanced/testing-websockets.md index caedc11..6053717 100644 --- a/docs/zh-hant/docs/advanced/testing-websockets.md +++ b/docs/zh-hant/docs/advanced/testing-websockets.md @@ -8,6 +8,6 @@ /// note | 注意 -想了解更多，請參考 Starlette 的[測試 WebSocket](https://www.starlette.dev/testclient/#testing-websocket-sessions)文件。 +想了解更多，請參考 Starlette 的[測試 WebSocket](https://starlette.dev/testclient/#testing-websocket-sessions)文件。 /// diff --git a/docs/zh-hant/docs/advanced/using-request-directly.md b/docs/zh-hant/docs/advanced/using-request-directly.md index 2c35598..dd6544a 100644 --- a/docs/zh-hant/docs/advanced/using-request-directly.md +++ b/docs/zh-hant/docs/advanced/using-request-directly.md @@ -4,18 +4,18 @@ 例如從以下來源取得資料： -- 路徑中的參數。 -- 標頭。 -- Cookies。 -- 等等。 +* 路徑中的參數。 +* 標頭。 +* Cookies。 +* 等等。 -這麼做時，FastAPI 會自動驗證並轉換這些資料，還會為你的 API 產生文件。 +這麼做時，**FastAPI** 會自動驗證並轉換這些資料，還會為你的 API 產生文件。 但有些情況你可能需要直接存取 `Request` 物件。 ## 關於 `Request` 物件的細節 { #details-about-the-request-object } -由於 FastAPI 底層其實是 Starlette，再加上一層工具，因此在需要時你可以直接使用 Starlette 的 [`Request`](https://www.starlette.dev/requests/) 物件。 +由於 **FastAPI** 底層其實是 **Starlette**，再加上一層工具，因此在需要時你可以直接使用 Starlette 的 [`Request`](https://starlette.dev/requests/) 物件。 同時也代表，如果你直接從 `Request` 物件取得資料（例如讀取 body），FastAPI 不會替它做驗證、轉換或文件化（透過 OpenAPI 為自動化的 API 介面產生文件）。 @@ -25,13 +25,13 @@ ## 直接使用 `Request` 物件 { #use-the-request-object-directly } -假設你想在你的 路徑操作函式（path operation function） 中取得用戶端的 IP 位址／主機。 +假設你想在你的 *路徑操作函式* 中取得用戶端的 IP 位址／主機。 為此，你需要直接存取請求。 {* ../../docs_src/using_request_directly/tutorial001_py310.py hl[1,7:8] *} -只要在 路徑操作函式 中宣告一個型別為 `Request` 的參數，FastAPI 就會將當前的 `Request` 傳入該參數。 +只要在 *路徑操作函式* 中宣告一個型別為 `Request` 的參數，**FastAPI** 就會將當前的 `Request` 傳入該參數。 /// tip @@ -45,12 +45,12 @@ ## `Request` 文件 { #request-documentation } -你可以在 [Starlette 官方文件站點中的 `Request` 物件](https://www.starlette.dev/requests/) 了解更多細節。 +你可以在 [Starlette 官方文件站點中的 `Request` 物件](https://starlette.dev/requests/) 了解更多細節。 /// note | 技術細節 你也可以使用 `from starlette.requests import Request`。 -FastAPI 之所以直接提供它，是為了讓開發者更方便；但它本身是來自 Starlette。 +**FastAPI** 之所以直接提供它，是為了讓開發者更方便；但它本身是來自 Starlette。 /// diff --git a/docs/zh-hant/docs/advanced/websockets.md b/docs/zh-hant/docs/advanced/websockets.md index 29a9549..73294df 100644 --- a/docs/zh-hant/docs/advanced/websockets.md +++ b/docs/zh-hant/docs/advanced/websockets.md @@ -4,12 +4,12 @@ ## 安裝 `websockets` { #install-websockets } -請先建立[虛擬環境](../virtual-environments.md)、啟用它，然後安裝 `websockets`（一個讓你更容易使用「WebSocket」通訊協定的 Python 套件）： +將 `websockets`（一個讓你更容易使用「WebSocket」通訊協定的 Python 套件）加入你的專案：
```console -$ pip install websockets +$ uv add websockets ---> 100% ``` @@ -64,12 +64,12 @@ $ pip install websockets ## 試試看 { #try-it } -如果你的檔案名為 `main.py`，用以下指令執行應用： +將你的程式碼放在 `main.py` 檔案中，然後執行你的應用：
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -126,7 +126,7 @@ $ fastapi dev
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -182,5 +182,5 @@ Client #1596980209979 left the chat 想了解更多選項，請參考 Starlette 的文件： -* [`WebSocket` 類別](https://www.starlette.dev/websockets/)。 -* [以類別為基礎的 WebSocket 處理](https://www.starlette.dev/endpoints/#websocketendpoint)。 +* [`WebSocket` 類別](https://starlette.dev/websockets/)。 +* [以類別為基礎的 WebSocket 處理](https://starlette.dev/endpoints/#websocketendpoint)。 diff --git a/docs/zh-hant/docs/advanced/wsgi.md b/docs/zh-hant/docs/advanced/wsgi.md index 161496a..aac3359 100644 --- a/docs/zh-hant/docs/advanced/wsgi.md +++ b/docs/zh-hant/docs/advanced/wsgi.md @@ -9,7 +9,7 @@ /// note -這需要先安裝 `a2wsgi`，例如使用 `pip install a2wsgi`。 +這需要將 `a2wsgi` 加入你的專案，例如使用 `uv add a2wsgi`。 /// diff --git a/docs/zh-hant/docs/alternatives.md b/docs/zh-hant/docs/alternatives.md index d957389..166f3f6 100644 --- a/docs/zh-hant/docs/alternatives.md +++ b/docs/zh-hant/docs/alternatives.md @@ -24,7 +24,7 @@ ### [Django REST Framework](https://www.django-rest-framework.org/) { #django-rest-framework } -Django REST framework 的目標是成為一套在 Django 之上構建 Web API 的彈性工具組，以強化其 API 能力。 +Django REST Framework 被創建為一套在 Django 之上構建 Web API 的彈性工具組，以強化其 API 能力。 它被 Mozilla、Red Hat、Eventbrite 等眾多公司使用。 @@ -125,7 +125,7 @@ def read_url(): 並整合基於標準的使用者介面工具： * [Swagger UI](https://github.com/swagger-api/swagger-ui) -* [ReDoc](https://github.com/Rebilly/ReDoc) +* [ReDoc](https://github.com/Redocly/redoc) 選擇這兩個是因為它們相當受歡迎且穩定，但稍加搜尋，你會發現有數十種 OpenAPI 的替代使用者介面（都能與 **FastAPI** 一起使用）。 @@ -237,7 +237,7 @@ Flask-apispec 由與 Marshmallow 相同的開發者創建。 /// -### [NestJS](https://nestjs.com/)（與 [Angular](https://angular.io/)） { #nestjs-and-angular } +### [NestJS](https://nestjs.com/)（與 [Angular](https://angular.dev/)） { #nestjs-and-angular } 這甚至不是 Python。NestJS 是受 Angular 啟發的 JavaScript（TypeScript）NodeJS 框架。 @@ -337,7 +337,7 @@ Hug 是最早使用 Python 型別提示來宣告 API 參數型別的框架之一 /// note -Hug 由 Timothy Crosley 創建，他同時也是 [`isort`](https://github.com/timothycrosley/isort) 的作者，一個自動排序 Python 匯入的好工具。 +Hug 由 Timothy Crosley 創建，他同時也是 [`isort`](https://github.com/PyCQA/isort) 的作者，一個能自動排序 Python 檔案中 import 的好工具。 /// @@ -401,7 +401,7 @@ APIStar 由 Tom Christie 創建。他也創建了： ## **FastAPI** 所採用的工具 { #used-by-fastapi } -### [Pydantic](https://docs.pydantic.dev/) { #pydantic } +### [Pydantic](https://pydantic.dev/docs/) { #pydantic } Pydantic 是基於 Python 型別提示，定義資料驗證、序列化與文件（使用 JSON Schema）的函式庫。 @@ -417,7 +417,7 @@ Pydantic 是基於 Python 型別提示，定義資料驗證、序列化與文件 /// -### [Starlette](https://www.starlette.dev/) { #starlette } +### [Starlette](https://starlette.dev/) { #starlette } Starlette 是一個輕量的 ASGI 框架／工具集，非常適合用來建構高效能的 asyncio 服務。 @@ -462,7 +462,7 @@ ASGI 是由 Django 核心團隊成員正在開發的新「標準」。它尚未 /// -### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn } +### [Uvicorn](https://uvicorn.dev) { #uvicorn } Uvicorn 是基於 uvloop 與 httptools 的極速 ASGI 伺服器。 diff --git a/docs/zh-hant/docs/deployment/docker.md b/docs/zh-hant/docs/deployment/docker.md index b10299d..7b058be 100644 --- a/docs/zh-hant/docs/deployment/docker.md +++ b/docs/zh-hant/docs/deployment/docker.md @@ -105,40 +105,36 @@ Docker 是用來建立與管理容器映像與容器的主要工具之一。 ### 套件需求 { #package-requirements } -你的應用通常會把「套件需求」放在某個檔案中。 +當你使用 `uv` 管理專案時，它的直接相依會宣告在 `pyproject.toml` 中，而精確解析出的版本會儲存在 `uv.lock`。 -這主要取決於你用什麼工具來安裝那些需求。 - -最常見的方式是準備一個 `requirements.txt` 檔案，逐行列出套件名稱與版本。 - -當然，你會用與在 [關於 FastAPI 版本](versions.md) 中讀到的相同概念，來設定版本範圍。 - -例如，你的 `requirements.txt` 可能像這樣： - -``` -fastapi[standard]>=0.113.0,<0.114.0 -pydantic>=2.7.0,<3.0.0 -``` - -接著你通常會用 `pip` 來安裝這些套件相依，例如： +你可以用以下指令加入你的應用需要的套件：
```console -$ pip install -r requirements.txt +$ uv add "fastapi[standard]" pydantic ---> 100% -Successfully installed fastapi pydantic ```
/// note | 注意 -還有其他格式與工具可以用來定義與安裝套件相依。 +下面的 Dockerfile 會在容器內使用 `pip`。你可以從你的 uv 專案匯出鎖定的相依，轉成它預期的 `requirements.txt` 格式： + +
+ +```console +$ uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt +``` + +
+ +產生的 `requirements.txt` 是用於容器建置的匯出檔。請繼續使用 `uv add` 管理相依，並在 `uv.lock` 變更時重新產生它。 /// -### 建立 FastAPI 程式碼 { #create-the-fastapi-code } +### 建立 **FastAPI** 程式碼 { #create-the-fastapi-code } * 建立一個 `app` 目錄並進入。 * 建立一個空的 `__init__.py` 檔案。 @@ -372,7 +368,7 @@ $ docker run -d --name mycontainer -p 80:80 myimage 你也可以前往 [http://192.168.99.100/redoc](http://192.168.99.100/redoc) 或 [http://127.0.0.1/redoc](http://127.0.0.1/redoc)（或等效的、使用你的 Docker 主機）。 -你會看到另一種自動產生的文件（由 [ReDoc](https://github.com/Rebilly/ReDoc) 提供）： +你會看到另一種自動產生的文件（由 [ReDoc](https://github.com/Redocly/redoc) 提供）： ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) diff --git a/docs/zh-hant/docs/deployment/fastapicloud.md b/docs/zh-hant/docs/deployment/fastapicloud.md index 0d5c5e7..ecd3309 100644 --- a/docs/zh-hant/docs/deployment/fastapicloud.md +++ b/docs/zh-hant/docs/deployment/fastapicloud.md @@ -5,7 +5,7 @@
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -24,9 +24,9 @@ CLI 會自動偵測你的 FastAPI 應用並將其部署到雲端。若你尚未 **[FastAPI Cloud](https://fastapicloud.com)** 由 **FastAPI** 的作者與團隊打造。 -它以最少的心力，精簡化建立、部署與存取 API 的流程。 +它以最少的心力，精簡化**建立**、**部署**與**存取** API 的流程。 -它把使用 FastAPI 開發應用的優異開發體驗，延伸到將它們部署到雲端。🎉 +它把使用 FastAPI 開發應用的優異**開發體驗**，延伸到將它們**部署**到雲端。🎉 它也會為你處理部署應用時多數需要面對的事項，例如： diff --git a/docs/zh-hant/docs/deployment/manually.md b/docs/zh-hant/docs/deployment/manually.md index 590d0b0..5cf240f 100644 --- a/docs/zh-hant/docs/deployment/manually.md +++ b/docs/zh-hant/docs/deployment/manually.md @@ -52,7 +52,7 @@ FastAPI 採用建立 Python 網頁框架與伺服器的標準 ```console -$ pip install "uvicorn[standard]" +$ uv add "uvicorn[standard]" ---> 100% ``` @@ -95,7 +95,7 @@ $ pip install "uvicorn[standard]" 其中包含 `uvloop`，它是 `asyncio` 的高效能替代實作，可大幅提升並行效能。 -當你用 `pip install "fastapi[standard]"` 安裝 FastAPI 時，也會一併取得 `uvicorn[standard]`。 +當你用像 `uv add "fastapi[standard]"` 這樣加入 FastAPI 時，也會一併取得 `uvicorn[standard]`。 /// @@ -106,7 +106,7 @@ $ pip install "uvicorn[standard]"
```console -$ uvicorn main:app --host 0.0.0.0 --port 80 +$ uv run uvicorn main:app --host 0.0.0.0 --port 80 INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) ``` diff --git a/docs/zh-hant/docs/deployment/server-workers.md b/docs/zh-hant/docs/deployment/server-workers.md index 82ffa0f..070f75a 100644 --- a/docs/zh-hant/docs/deployment/server-workers.md +++ b/docs/zh-hant/docs/deployment/server-workers.md @@ -9,19 +9,19 @@ * 記憶體 * 啟動前的前置作業 -到目前為止，依照文件中的教學，你大多是透過 `fastapi` 指令啟動一個執行 Uvicorn 的伺服器程式，且只跑單一處理序。 +到目前為止，依照文件中的教學，你大多是透過 `fastapi` 指令啟動一個執行 Uvicorn 的**伺服器程式**，且只跑**單一處理序**。 -在部署應用時，你通常會希望有一些處理序的複製來善用多核心，並能處理更多請求。 +在部署應用時，你通常會希望有一些**處理序的複製**來善用**多核心**，並能處理更多請求。 如同前一章關於 [部署概念](concepts.md) 所示，你可以採用多種策略。 -這裡會示範如何使用 `fastapi` 指令或直接使用 `uvicorn` 指令，搭配 Uvicorn 的工作處理序（worker processes）。 +這裡會示範如何使用 `fastapi` 指令或直接使用 `uvicorn` 指令，搭配 **Uvicorn** 的**工作處理序**（worker processes）。 /// note 如果你使用容器（例如 Docker 或 Kubernetes），我會在下一章說明更多：[容器中的 FastAPI - Docker](docker.md)。 -特別是，在 **Kubernetes** 上執行時，你多半會選擇不要使用 workers，而是每個容器只跑一個 **Uvicorn 單一處理序**。我會在該章節中進一步說明。 +特別是，在 **Kubernetes** 上執行時，你多半會**不要**使用 workers，而是每個容器只跑一個 **Uvicorn 單一處理序**。我會在該章節中進一步說明。 /// @@ -86,7 +86,7 @@ $ fastapi run --workers 4 ```console -$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 +$ uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit) INFO: Started parent process [27365] INFO: Started server process [27368] @@ -109,7 +109,7 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 這裡唯一新增的選項是 `--workers`，告訴 Uvicorn 要啟動 4 個工作處理序。 -你也會看到它顯示每個處理序的 **PID**，`27365` 是父處理序（這是**處理序管理器**），另外每個工作處理序各有一個：`27368`、`27369`、`27370`、`27367`。 +你也會看到它顯示每個處理序的 **PID**，`27365` 是父處理序（這是**處理序管理器**），另外每個工作處理序各有一個：`27368`、`27369`、`27370` 和 `27367`。 ## 部署概念 { #deployment-concepts } diff --git a/docs/zh-hant/docs/environment-variables.md b/docs/zh-hant/docs/environment-variables.md index 71248ac..91d7a7f 100644 --- a/docs/zh-hant/docs/environment-variables.md +++ b/docs/zh-hant/docs/environment-variables.md @@ -1,299 +1,11 @@ # 環境變數 { #environment-variables } +**環境變數**（也稱為 **env var**）是存在於 Python 程式碼之外、作業系統中的值，可以被你的應用程式和其他程式讀取。 -/// tip +FastAPI 應用程式通常使用環境變數進行設定，例如資料庫 URL、電子郵件憑證和秘密金鑰。 -如果你已經知道什麼是「環境變數」並且知道如何使用它們，你可以放心跳過這一部分。 +你將在[設定與環境變數](advanced/settings.md)中學習如何將它們用於應用程式設定。 -/// +## 了解更多 { #learn-more } -環境變數（也稱為「**env var**」）是一個獨立於 Python 程式碼**之外**的變數，它存在於**作業系統**中，可以被你的 Python 程式碼（或其他程式）讀取。 - -環境變數對於處理應用程式**設定**（作為 Python **安裝**的一部分等方面）非常有用。 - -## 建立和使用環境變數 { #create-and-use-env-vars } - -你在 **shell（終端機）**中就可以**建立**和使用環境變數，並不需要用到 Python： - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// 你可以使用以下指令建立一個名為 MY_NAME 的環境變數 -$ export MY_NAME="Wade Wilson" - -// 然後，你可以在其他程式中使用它，例如 -$ echo "Hello $MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// 建立一個名為 MY_NAME 的環境變數 -$ $Env:MY_NAME = "Wade Wilson" - -// 在其他程式中使用它，例如 -$ echo "Hello $Env:MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -## 在 Python 中讀取環境變數 { #read-env-vars-in-python } - -你也可以在 Python **之外**的終端機中建立環境變數（或使用其他方法），然後在 Python 中**讀取**它們。 - -例如，你可以建立一個名為 `main.py` 的檔案，其中包含以下內容： - -```Python hl_lines="3" -import os - -name = os.getenv("MY_NAME", "World") -print(f"Hello {name} from Python") -``` - -/// tip - -第二個參數是 [`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) 的預設回傳值。 - -如果沒有提供，預設值為 `None`，這裡我們提供 `"World"` 作為預設值。 - -/// - -然後你可以呼叫這個 Python 程式： - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// 這裡我們還沒有設定環境變數 -$ python main.py - -// 因為我們沒有設定環境變數，所以我們得到的是預設值 - -Hello World from Python - -// 但是如果我們事先建立過一個環境變數 -$ export MY_NAME="Wade Wilson" - -// 然後再次呼叫程式 -$ python main.py - -// 現在就可以讀取到環境變數了 - -Hello Wade Wilson from Python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// 這裡我們還沒有設定環境變數 -$ python main.py - -// 因為我們沒有設定環境變數，所以我們得到的是預設值 - -Hello World from Python - -// 但是如果我們事先建立過一個環境變數 -$ $Env:MY_NAME = "Wade Wilson" - -// 然後再次呼叫程式 -$ python main.py - -// 現在就可以讀取到環境變數了 - -Hello Wade Wilson from Python -``` - -
- -//// - -由於環境變數可以在程式碼之外設定，但可以被程式碼讀取，並且不必與其他檔案一起儲存（提交到 `git`），因此通常用於配置或**設定**。 - -你還可以為**特定的程式呼叫**建立特定的環境變數，該環境變數僅對該程式可用，且僅在其執行期間有效。 - -要實現這一點，只需在同一行內（程式本身之前）建立它： - -
- -```console -// 在這個程式呼叫的同一行中建立一個名為 MY_NAME 的環境變數 -$ MY_NAME="Wade Wilson" python main.py - -// 現在就可以讀取到環境變數了 - -Hello Wade Wilson from Python - -// 在此之後這個環境變數將不再存在 -$ python main.py - -Hello World from Python -``` - -
- -/// tip - -你可以在 [The Twelve-Factor App: 配置](https://12factor.net/config) 中了解更多資訊。 - -/// - -## 型別和驗證 { #types-and-validation } - -這些環境變數只能處理**文字字串**，因為它們是位於 Python 範疇之外的，必須與其他程式和作業系統的其餘部分相容（甚至與不同的作業系統相容，如 Linux、Windows、macOS）。 - -這意味著從環境變數中讀取的**任何值**在 Python 中都將是一個 `str`，任何型別轉換或驗證都必須在程式碼中完成。 - -你將在[進階使用者指南 - 設定和環境變數](./advanced/settings.md)中了解更多關於使用環境變數處理**應用程式設定**的資訊。 - -## `PATH` 環境變數 { #path-environment-variable } - -有一個**特殊的**環境變數稱為 **`PATH`**，作業系統（Linux、macOS、Windows）用它來查找要執行的程式。 - -`PATH` 變數的值是一個長字串，由 Linux 和 macOS 上的冒號 `:` 分隔的目錄組成，而在 Windows 上則是由分號 `;` 分隔的。 - -例如，`PATH` 環境變數可能如下所示： - -//// tab | Linux, macOS - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -這意味著系統應該在以下目錄中查找程式： - -- `/usr/local/bin` -- `/usr/bin` -- `/bin` -- `/usr/sbin` -- `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32 -``` - -這意味著系統應該在以下目錄中查找程式： - -- `C:\Program Files\Python312\Scripts` -- `C:\Program Files\Python312` -- `C:\Windows\System32` - -//// - -當你在終端機中輸入一個**指令**時，作業系統會在 `PATH` 環境變數中列出的**每個目錄**中**查找**程式。 - -例如，當你在終端機中輸入 `python` 時，作業系統會在該列表中的**第一個目錄**中查找名為 `python` 的程式。 - -如果找到了，那麼作業系統將**使用它**；否則，作業系統會繼續在**其他目錄**中查找。 - -### 安裝 Python 並更新 `PATH` { #installing-python-and-updating-the-path } - -安裝 Python 時，可能會詢問你是否要更新 `PATH` 環境變數。 - -//// tab | Linux, macOS - -假設你安裝了 Python，並將其安裝在目錄 `/opt/custompython/bin` 中。 - -如果你選擇更新 `PATH` 環境變數，那麼安裝程式會將 `/opt/custompython/bin` 加入到 `PATH` 環境變數中。 - -它看起來大致會是這樣： - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin -``` - -如此一來，當你在終端機輸入 `python` 時，系統會在 `/opt/custompython/bin` 中找到 Python 程式（最後一個目錄）並使用它。 - -//// - -//// tab | Windows - -假設你安裝了 Python，並將其安裝在目錄 `C:\opt\custompython\bin` 中。 - -如果你選擇更新 `PATH` 環境變數，那麼安裝程式會將 `C:\opt\custompython\bin` 加入到 `PATH` 環境變數中。 - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin -``` - -如此一來，當你在終端機輸入 `python` 時，系統會在 `C:\opt\custompython\bin` 中找到 Python 程式（最後一個目錄）並使用它。 - -//// - -因此，如果你輸入： - -
- -```console -$ python -``` - -
- -//// tab | Linux, macOS - -系統會在 `/opt/custompython/bin` 中**找到** `python` 程式並執行它。 - -這大致等同於輸入以下指令： - -
- -```console -$ /opt/custompython/bin/python -``` - -
- -//// - -//// tab | Windows - -系統會在 `C:\opt\custompython\bin\python` 中**找到** `python` 程式並執行它。 - -這大致等同於輸入以下指令： - -
- -```console -$ C:\opt\custompython\bin\python -``` - -
- -//// - -當學習[虛擬環境](virtual-environments.md)時，這些資訊將會很有用。 - -## 結論 { #conclusion } - -透過這個教學，你應該對**環境變數**是什麼以及如何在 Python 中使用它們有了基本的了解。 - -你也可以在 [環境變數的維基百科條目](https://en.wikipedia.org/wiki/Environment_variable) 中閱讀更多。 - -在許多情況下，環境變數的用途和適用性可能不會立刻顯現。但是在開發過程中，它們會在許多不同的場景中出現，因此瞭解它們是非常必要的。 - -例如，你在接下來的[虛擬環境](virtual-environments.md)章節中將需要這些資訊。 +閱讀[環境變數指南](https://tiangolo.com/guides/environment-variables/)以取得詳細的跨平台說明，包括如何建立和讀取環境變數，以及 `PATH` 環境變數的運作方式。 diff --git a/docs/zh-hant/docs/fastapi-cli.md b/docs/zh-hant/docs/fastapi-cli.md index 55220af..e92998b 100644 --- a/docs/zh-hant/docs/fastapi-cli.md +++ b/docs/zh-hant/docs/fastapi-cli.md @@ -2,7 +2,7 @@ **FastAPI CLI** 是一個命令列程式，你可以用它來啟動你的 FastAPI 應用程式、管理你的 FastAPI 專案，等等。 -當你安裝 FastAPI（例如使用 `pip install "fastapi[standard]"`）時，會附帶一個可以在終端機執行的命令列程式。 +當你將 FastAPI 加入專案（例如使用 `uv add "fastapi[standard]"`）時，會附帶一個可以在終端機執行的命令列程式。 要在開發時運行你的 FastAPI 應用程式，你可以使用 `fastapi dev` 指令： @@ -52,7 +52,7 @@ $ fastapi dev /// -在內部，**FastAPI CLI** 使用 [Uvicorn](https://www.uvicorn.dev)，這是一個高效能、適用於生產環境的 ASGI 伺服器。😎 +在內部，**FastAPI CLI** 使用 [Uvicorn](https://uvicorn.dev)，這是一個高效能、適用於生產環境的 ASGI 伺服器。😎 `fastapi` CLI 會嘗試自動偵測要執行的 FastAPI 應用程式，預設假設它是檔案 `main.py` 中名為 `app` 的物件（或其他幾種變體）。 @@ -100,13 +100,13 @@ from backend.main import app 你也可以把檔案路徑傳給 `fastapi dev` 指令，它會推測要使用的 FastAPI app 物件： ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` 或者，你也可以把 `--entrypoint` 選項傳給 `fastapi dev` 指令： ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` 但這樣每次呼叫 `fastapi` 指令時都得記得傳入正確的路徑或 entrypoint。 @@ -119,6 +119,10 @@ $ fastapi dev --entrypoint main:app 預設情況下，**auto-reload** 功能是啟用的，當你對程式碼進行修改時，伺服器會自動重新載入。這會消耗較多資源，並且可能比禁用時更不穩定。因此，你應該只在開發環境中使用此功能。它也會在 IP 位址 `127.0.0.1` 上監聽，這是用於你的機器與自身通訊的 IP 位址（`localhost`）。 +在匯入你的 app 之前，`fastapi dev` 會將 `FASTAPI_ENV` 環境變數設為 `development`。如果 `FASTAPI_ENV` 已經設定，則會保留其既有值。這讓 app 啟動程式碼可以選擇適合開發的行為，同時允許你提供 app 專用的環境，例如 `staging`。 + +慣例的 `FASTAPI_ENV` 值是 `development` 和 `production`。`fastapi run` 目前會讓 `FASTAPI_ENV` 保持不變，因此如果你的 app 需要偵測生產模式，請明確設定它。 + ## `fastapi run` { #fastapi-run } 執行 `fastapi run` 會以生產模式啟動 FastAPI。 diff --git a/docs/zh-hant/docs/features.md b/docs/zh-hant/docs/features.md index 193e4a1..aa2b684 100644 --- a/docs/zh-hant/docs/features.md +++ b/docs/zh-hant/docs/features.md @@ -19,7 +19,7 @@ ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* 使用 [**ReDoc**](https://github.com/Rebilly/ReDoc) 的替代 API 文件。 +* 使用 [**ReDoc**](https://github.com/Redocly/redoc) 的替代 API 文件。 ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) @@ -159,7 +159,7 @@ FastAPI 有一個使用簡單，但是非常強大的 ORMs 和 ODMs。 diff --git a/docs/zh-hant/docs/help-fastapi.md b/docs/zh-hant/docs/help-fastapi.md index 4a4a4fd..f4cc8ae 100644 --- a/docs/zh-hant/docs/help-fastapi.md +++ b/docs/zh-hant/docs/help-fastapi.md @@ -46,20 +46,6 @@ * [**Bluesky** 上的 @tiangolo.com](https://bsky.app/profile/tiangolo.com) * [**LinkedIn** 上的 @tiangolo](https://www.linkedin.com/in/tiangolo/)。 -## 在 GitHub 幫助他人解答問題 { #help-others-with-questions-in-github } - -你可以嘗試在 [GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered) 幫助他人回答問題。 - -很多時候你可能已經知道這些問題的答案。🤓 - -如果你經常幫大家解決問題，你會成為官方的 [FastAPI 專家](fastapi-people.md#fastapi-experts)。🎉 - -請記得，最重要的是：盡量友善。🤗 - -### 如何協助 { #how-to-help } - -請依照這裡的[協助指南](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github)。 - ## 提問 { #ask-questions } 你可以在 GitHub 儲存庫[建立一個新的問題（Question）](https://github.com/fastapi/fastapi/discussions/new?category=questions)，例如用來： @@ -69,7 +55,7 @@ ## 加入聊天室 { #join-the-chat } -加入 👥 [Discord 聊天伺服器](https://discord.gg/VQjSZaeJmf) 👥，與 FastAPI 社群的其他人一起交流。 +加入 👥 [Discord 聊天伺服器](https://discord.com/invite/VQjSZaeJmf) 👥，與 FastAPI 社群的其他人一起交流。 /// tip @@ -86,3 +72,9 @@ 在 GitHub 上，模板會引導你寫出合適的提問，讓你更容易得到好的解答，甚至在提問前就自己解決問題。 聊天系統中的對話也不像 GitHub 那樣容易被搜尋，常常會淹沒在對話中。 + +## 試用 FastAPI Cloud { #try-fastapi-cloud } + +FastAPI 與夥伴的主要資金來自 [**FastAPI Cloud**](https://fastapicloud.com)，這是一個能以簡單快速的方式部署 FastAPI 應用程式的平台，只需一個指令 `fastapi deploy`。 + +FastAPI Cloud 由 FastAPI 背後的同一個團隊打造。你可以試用它，並考慮在你的專案中使用。 diff --git a/docs/zh-hant/docs/history-design-future.md b/docs/zh-hant/docs/history-design-future.md index f3c7333..8911b80 100644 --- a/docs/zh-hant/docs/history-design-future.md +++ b/docs/zh-hant/docs/history-design-future.md @@ -54,11 +54,11 @@ ## 需求 { #requirements } -在測試多種替代方案後，我決定採用 [**Pydantic**](https://docs.pydantic.dev/)，因為它的優勢。 +在測試多種替代方案後，我決定採用 [**Pydantic**](https://pydantic.dev/docs/)，因為它的優勢。 隨後我也對它做出貢獻，使其完全符合 JSON Schema、支援以不同方式定義約束，並依據在多款編輯器中的測試結果改進編輯器支援（型別檢查、自動補全）。 -在開發過程中，我也對 [**Starlette**](https://www.starlette.dev/)（另一個關鍵依賴）做出貢獻。 +在開發過程中，我也對 [**Starlette**](https://starlette.dev/)（另一個關鍵依賴）做出貢獻。 ## 開發 { #development } diff --git a/docs/zh-hant/docs/how-to/custom-request-and-route.md b/docs/zh-hant/docs/how-to/custom-request-and-route.md index afd097f..e118ed0 100644 --- a/docs/zh-hant/docs/how-to/custom-request-and-route.md +++ b/docs/zh-hant/docs/how-to/custom-request-and-route.md @@ -66,7 +66,7 @@ 而 `scope` 與 `receive` 這兩者，就是建立一個新的 `Request` 實例所需的資料。 -想了解更多 `Request`，請參考 [Starlette 的 Request 文件](https://www.starlette.dev/requests/)。 +想了解更多 `Request`，請參考 [Starlette 的 Request 文件](https://starlette.dev/requests/)。 /// diff --git a/docs/zh-hant/docs/how-to/extending-openapi.md b/docs/zh-hant/docs/how-to/extending-openapi.md index 0a6ba5a..0b68c54 100644 --- a/docs/zh-hant/docs/how-to/extending-openapi.md +++ b/docs/zh-hant/docs/how-to/extending-openapi.md @@ -45,7 +45,7 @@ 基於上述資訊，你可以用相同的工具函式來產生 OpenAPI 結構，並覆寫你需要客製的部分。 -例如，我們要加入 [ReDoc 的 OpenAPI 擴充，插入自訂 logo](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo)。 +例如，我們要加入 [ReDoc 的 OpenAPI 擴充，插入自訂 logo](https://github.com/Redocly/redoc/blob/main/docs/redoc-vendor-extensions.md#x-logo)。 ### 一般的 **FastAPI** { #normal-fastapi } diff --git a/docs/zh-hant/docs/how-to/graphql.md b/docs/zh-hant/docs/how-to/graphql.md index fce5f41..b2ad596 100644 --- a/docs/zh-hant/docs/how-to/graphql.md +++ b/docs/zh-hant/docs/how-to/graphql.md @@ -21,7 +21,7 @@ * [Strawberry](https://strawberry.rocks/) 🍓 * 提供 [FastAPI 文件](https://strawberry.rocks/docs/integrations/fastapi) * [Ariadne](https://ariadnegraphql.org/) - * 提供 [FastAPI 文件](https://ariadnegraphql.org/docs/fastapi-integration) + * 提供 [FastAPI 文件](https://ariadnegraphql.org/server/Integrations/fastapi-integration) * [Tartiflette](https://tartiflette.io/) * 使用 [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) 提供 ASGI 整合 * [Graphene](https://graphene-python.org/) diff --git a/docs/zh-hant/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/zh-hant/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index 77a5825..6941ddb 100644 --- a/docs/zh-hant/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/zh-hant/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -24,7 +24,7 @@ Pydantic 團隊自 **Python 3.14** 起，已停止在最新的 Python 版本中 ## 官方指南 { #official-guide } -Pydantic 提供從 v1 遷移到 v2 的官方[遷移指南](https://docs.pydantic.dev/latest/migration/)。 +Pydantic 提供從 v1 遷移到 v2 的官方[遷移指南](https://pydantic.dev/docs/validation/latest/get-started/migration/)。 其中包含變更內容、驗證如何更正確且更嚴格、可能的注意事項等。 diff --git a/docs/zh-hant/docs/index.md b/docs/zh-hant/docs/index.md index 743357b..27f506b 100644 --- a/docs/zh-hant/docs/index.md +++ b/docs/zh-hant/docs/index.md @@ -110,7 +110,7 @@ FastAPI 是一個現代、快速（高效能）的 Web 框架，用於以 Python
-## FastAPI 大會 { #fastapi-conf } - -[**FastAPI Conf '26**](https://fastapiconf.com) 將於 **2026 年 10 月 28 日** 在 **荷蘭阿姆斯特丹** 舉行。全部關於 FastAPI，來自第一手來源。🎤 - -FastAPI Conf '26 - October 28, 2026 - Amsterdam, NL - ## FastAPI 迷你紀錄片 { #fastapi-mini-documentary } 在 2025 年底發布了一支 [FastAPI 迷你紀錄片](https://www.youtube.com/watch?v=mpR8ngthqiE)，你可以在線上觀看： @@ -175,17 +169,17 @@ FastAPI 是一個現代、快速（高效能）的 Web 框架，用於以 Python FastAPI 是站在以下巨人的肩膀上： -* [Starlette](https://www.starlette.dev/) 負責 Web 部分。 -* [Pydantic](https://docs.pydantic.dev/) 負責資料部分。 +* [Starlette](https://starlette.dev/) 負責 Web 部分。 +* [Pydantic](https://pydantic.dev/docs/) 負責資料部分。 ## 安裝 { #installation } -建立並啟用一個[虛擬環境](https://fastapi.tiangolo.com/zh-hant/virtual-environments/)，然後安裝 FastAPI： +首先，[安裝 `uv`](https://docs.astral.sh/uv/getting-started/installation/)，然後將 FastAPI 加入你的專案：
```console -$ pip install "fastapi[standard]" +$ uv add "fastapi[standard]" ---> 100% ``` @@ -194,6 +188,8 @@ $ pip install "fastapi[standard]" **注意**：請務必將 `"fastapi[standard]"` 用引號包起來，以確保在所有終端機中都能正常運作。 +如果你偏好使用 `pip`，請在虛擬環境中安裝 `fastapi[standard]`。請參閱[安裝指南](tutorial/#install-fastapi)了解替代步驟。 + ## 範例 { #example } ### 建立 { #create-it } @@ -250,7 +246,7 @@ async def read_item(item_id: int, q: str | None = None):
```console -$ fastapi dev +$ uv run fastapi dev ╭────────── FastAPI CLI - Development mode ───────────╮ │ │ @@ -277,7 +273,7 @@ INFO: Application startup complete.
關於指令 fastapi dev... -指令 `fastapi dev` 會自動讀取你的 `main.py`，偵測其中的 **FastAPI** 應用，並使用 [Uvicorn](https://www.uvicorn.dev) 啟動伺服器。 +指令 `fastapi dev` 會自動讀取你的 `main.py`，偵測其中的 **FastAPI** 應用，並使用 [Uvicorn](https://uvicorn.dev) 啟動伺服器。 預設情況下，`fastapi dev` 會在本機開發時啟用自動重新載入。 @@ -314,7 +310,7 @@ INFO: Application startup complete. 現在前往 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)。 -你會看到另一種自動文件（由 [ReDoc](https://github.com/Rebilly/ReDoc) 提供）： +你會看到另一種自動文件（由 [ReDoc](https://github.com/Redocly/redoc) 提供）： ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -400,7 +396,7 @@ item_id: int item: Item ``` -…透過一次宣告，你將獲得： +...透過一次宣告，你將獲得： * 編輯器支援，包括： * 自動補全。 @@ -457,19 +453,19 @@ item: Item return {"item_name": item.name, "item_id": item_id} ``` -…從： +...從： ```Python ... "item_name": item.name ... ``` -…改為： +...改為： ```Python ... "item_price": item.price ... ``` -…然後看看你的編輯器如何自動補全屬性並知道它們的型別： +...然後看看你的編輯器如何自動補全屬性並知道它們的型別： ![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) @@ -497,7 +493,7 @@ item: Item
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -540,7 +536,7 @@ FastAPI 依賴 Pydantic 與 Starlette。 ### `standard` 依賴套件 { #standard-dependencies } -當你以 `pip install "fastapi[standard]"` 安裝 FastAPI 時，會包含 `standard` 這組可選依賴套件： +當你以 `uv add "fastapi[standard]"` 安裝 FastAPI 時，會包含 `standard` 這組可選依賴套件： Pydantic 會使用： @@ -554,17 +550,17 @@ Starlette 會使用： FastAPI 會使用： -* [`uvicorn`](https://www.uvicorn.dev) - 用於載入並服務你的應用的伺服器。這包含 `uvicorn[standard]`，其中含有一些高效能服務所需的依賴（例如 `uvloop`）。 +* [`uvicorn`](https://uvicorn.dev) - 用於載入並服務你的應用的伺服器。這包含 `uvicorn[standard]`，其中含有一些高效能服務所需的依賴（例如 `uvloop`）。 * `fastapi-cli[standard]` - 提供 `fastapi` 指令。 * 其中包含 `fastapi-cloud-cli`，可讓你將 FastAPI 應用部署到 [FastAPI Cloud](https://fastapicloud.com)。 ### 不含 `standard` 依賴套件 { #without-standard-dependencies } -如果你不想包含 `standard` 可選依賴，可以改用 `pip install fastapi`（而不是 `pip install "fastapi[standard]"`）。 +如果你不想包含 `standard` 可選依賴，可以改用 `uv add fastapi`（而不是 `uv add "fastapi[standard]"`）。 ### 不含 `fastapi-cloud-cli` { #without-fastapi-cloud-cli } -如果你想安裝帶有 standard 依賴、但不包含 `fastapi-cloud-cli`，可以使用 `pip install "fastapi[standard-no-fastapi-cloud-cli]"`。 +如果你想安裝帶有 standard 依賴、但不包含 `fastapi-cloud-cli`，可以使用 `uv add "fastapi[standard-no-fastapi-cloud-cli]"`。 ### 額外可選依賴套件 { #additional-optional-dependencies } @@ -572,13 +568,13 @@ FastAPI 會使用： Pydantic 的額外可選依賴： -* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - 設定管理。 -* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - 與 Pydantic 一起使用的額外型別。 +* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) - 設定管理。 +* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) - 與 Pydantic 一起使用的額外型別。 FastAPI 的額外可選依賴： * [`orjson`](https://github.com/ijl/orjson) - 若要使用 `ORJSONResponse` 必須安裝。 -* [`ujson`](https://github.com/esnme/ultrajson) - 若要使用 `UJSONResponse` 必須安裝。 +* [`ujson`](https://github.com/ultrajson/ultrajson) - 若要使用 `UJSONResponse` 必須安裝。 ## 授權 { #license } diff --git a/docs/zh-hant/docs/project-generation.md b/docs/zh-hant/docs/project-generation.md index 862417a..e6743c5 100644 --- a/docs/zh-hant/docs/project-generation.md +++ b/docs/zh-hant/docs/project-generation.md @@ -5,13 +5,13 @@ 你可以使用此範本快速起步，裡面已替你完成大量初始設定、安全性、資料庫，以及部分 API 端點。 -GitHub 儲存庫：[全端 FastAPI 範本](https://github.com/tiangolo/full-stack-fastapi-template) +GitHub 儲存庫：[全端 FastAPI 範本](https://github.com/fastapi/full-stack-fastapi-template) ## 全端 FastAPI 範本 - 技術堆疊與功能 { #full-stack-fastapi-template-technology-stack-and-features } - ⚡ [**FastAPI**](https://fastapi.tiangolo.com/zh-hant) 作為 Python 後端 API。 - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) 作為 Python 與 SQL 資料庫互動（ORM）。 - - 🔍 [Pydantic](https://docs.pydantic.dev)（由 FastAPI 使用）用於資料驗證與設定管理。 + - 🔍 [Pydantic](https://pydantic.dev/docs/)（由 FastAPI 使用）用於資料驗證與設定管理。 - 💾 [PostgreSQL](https://www.postgresql.org) 作為 SQL 資料庫。 - 🚀 [React](https://react.dev) 作為前端。 - 💃 使用 TypeScript、hooks、Vite，以及現代前端技術堆疊的其他組件。 diff --git a/docs/zh-hant/docs/python-types.md b/docs/zh-hant/docs/python-types.md index 2959217..8ecc12d 100644 --- a/docs/zh-hant/docs/python-types.md +++ b/docs/zh-hant/docs/python-types.md @@ -269,7 +269,7 @@ def some_function(data: Any): ## Pydantic 模型 { #pydantic-models } -[Pydantic](https://docs.pydantic.dev/) 是一個用來做資料驗證的 Python 程式庫。 +[Pydantic](https://pydantic.dev/docs/) 是一個用來做資料驗證的 Python 程式庫。 你以帶有屬性的類別來宣告資料的「形狀」。 @@ -285,7 +285,7 @@ def some_function(data: Any): /// note | 注意 -想了解更多 [Pydantic，請查看它的文件](https://docs.pydantic.dev/)。 +想了解更多 [Pydantic，請查看它的文件](https://pydantic.dev/docs/)。 /// diff --git a/docs/zh-hant/docs/tutorial/background-tasks.md b/docs/zh-hant/docs/tutorial/background-tasks.md index 216ec88..49cfdde 100644 --- a/docs/zh-hant/docs/tutorial/background-tasks.md +++ b/docs/zh-hant/docs/tutorial/background-tasks.md @@ -1,6 +1,6 @@ # 背景任務 { #background-tasks } -你可以定義背景任務，讓它們在傳回回應之後執行。 +你可以定義背景任務，讓它們在傳回回應*之後*執行。 這對於那些需要在請求之後發生、但用戶端其實不必在收到回應前等它完成的操作很有用。 @@ -13,11 +13,11 @@ ## 使用 `BackgroundTasks` { #using-backgroundtasks } -首先，匯入 `BackgroundTasks`，並在你的路徑操作函式中定義一個型別為 `BackgroundTasks` 的參數： +首先，匯入 `BackgroundTasks`，並在你的*路徑操作函式*中定義一個型別宣告為 `BackgroundTasks` 的參數： {* ../../docs_src/background_tasks/tutorial001_py310.py hl[1,13] *} -**FastAPI** 會為你建立 `BackgroundTasks` 物件，並以該參數傳入。 +**FastAPI** 會為你建立 `BackgroundTasks` 型別的物件，並以該參數傳入。 ## 建立任務函式 { #create-a-task-function } @@ -35,7 +35,7 @@ ## 新增背景任務 { #add-the-background-task } -在路徑操作函式內，使用 `.add_task()` 將任務函式加入背景任務物件： +在你的*路徑操作函式*內，使用 `.add_task()` 將任務函式傳給*背景任務*物件： {* ../../docs_src/background_tasks/tutorial001_py310.py hl[14] *} @@ -47,29 +47,31 @@ ## 相依性注入 { #dependency-injection } -在相依性注入系統中也可使用 `BackgroundTasks`。你可以在多個層級宣告 `BackgroundTasks` 型別的參數：路徑操作函式、相依項（dependable）、次級相依項等。 +在相依性注入系統中也可使用 `BackgroundTasks`。你可以在多個層級宣告 `BackgroundTasks` 型別的參數：*路徑操作函式*、相依項（dependable）、次級相依項等。 **FastAPI** 會在各種情況下正確處理並重用同一個物件，將所有背景任務合併，並在之後於背景執行： + {* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *} -在此範例中，訊息會在回應送出之後寫入 `log.txt` 檔案。 + +在此範例中，訊息會在回應送出*之後*寫入 `log.txt` 檔案。 如果請求中有查詢參數，會以背景任務寫入日誌。 -接著，在路徑操作函式中建立的另一個背景任務會使用 `email` 路徑參數寫入訊息。 +接著，在*路徑操作函式*中建立的另一個背景任務會使用 `email` 路徑參數寫入訊息。 ## 技術細節 { #technical-details } -類別 `BackgroundTasks` 直接來自 [`starlette.background`](https://www.starlette.dev/background/)。 +類別 `BackgroundTasks` 直接來自 [`starlette.background`](https://starlette.dev/background/)。 -它被直接匯入/包含到 FastAPI 中，因此你可以從 `fastapi` 匯入它，並避免不小心從 `starlette.background` 匯入另一個同名的 `BackgroundTask`（結尾沒有 s）。 +它被直接匯入/包含到 FastAPI 中，因此你可以從 `fastapi` 匯入它，並避免不小心從 `starlette.background` 匯入替代的 `BackgroundTask`（結尾沒有 `s`）。 -只使用 `BackgroundTasks`（而非 `BackgroundTask`）時，你就能把它當作路徑操作函式的參數，並讓 **FastAPI** 幫你處理其餘部分，就像直接使用 `Request` 物件一樣。 +只使用 `BackgroundTasks`（而非 `BackgroundTask`）時，你就能把它當作*路徑操作函式*的參數，並讓 **FastAPI** 幫你處理其餘部分，就像直接使用 `Request` 物件一樣。 在 FastAPI 中仍可單獨使用 `BackgroundTask`，但你需要在程式碼中自行建立該物件，並回傳包含它的 Starlette `Response`。 -更多細節請參閱 [Starlette 官方的 Background Tasks 文件](https://www.starlette.dev/background/)。 +更多細節請參閱 [Starlette 官方的 Background Tasks 文件](https://starlette.dev/background/)。 ## 注意事項 { #caveat } @@ -81,4 +83,4 @@ ## 重點回顧 { #recap } -在路徑操作函式與相依項中匯入並使用 `BackgroundTasks` 參數，以新增背景任務。 +在*路徑操作函式*與相依項中匯入並使用 `BackgroundTasks` 參數，以新增背景任務。 diff --git a/docs/zh-hant/docs/tutorial/bigger-applications.md b/docs/zh-hant/docs/tutorial/bigger-applications.md index 624b2c2..20441af 100644 --- a/docs/zh-hant/docs/tutorial/bigger-applications.md +++ b/docs/zh-hant/docs/tutorial/bigger-applications.md @@ -487,7 +487,7 @@ from app.main import app 你也可以把路徑直接傳給指令，例如： ```console -$ fastapi dev app/main.py +$ uv run fastapi dev app/main.py ``` 但你每次呼叫 `fastapi` 指令時都得記得傳入正確的路徑。 @@ -503,7 +503,7 @@ $ fastapi dev app/main.py
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/zh-hant/docs/tutorial/body-nested-models.md b/docs/zh-hant/docs/tutorial/body-nested-models.md index 4e2e642..02c13e0 100644 --- a/docs/zh-hant/docs/tutorial/body-nested-models.md +++ b/docs/zh-hant/docs/tutorial/body-nested-models.md @@ -96,7 +96,7 @@ my_list: list[str] 除了 `str`、`int`、`float` 等一般的單一型別外，你也可以使用繼承自 `str` 的更複雜單一型別。 -若要查看所有可用選項，請參閱 [Pydantic 的型別總覽](https://docs.pydantic.dev/latest/concepts/types/)。你會在下一章看到一些範例。 +若要查看所有可用選項，請參閱 [Pydantic 的型別總覽](https://pydantic.dev/docs/validation/latest/concepts/types/)。你會在下一章看到一些範例。 例如，在 `Image` 模型中有一個 `url` 欄位，我們可以將其宣告為 Pydantic 的 `HttpUrl`，而不是 `str`： diff --git a/docs/zh-hant/docs/tutorial/body.md b/docs/zh-hant/docs/tutorial/body.md index f1ba8e9..0dc4df2 100644 --- a/docs/zh-hant/docs/tutorial/body.md +++ b/docs/zh-hant/docs/tutorial/body.md @@ -6,7 +6,7 @@ 你的 API 幾乎總是需要傳回**回應**本文。但用戶端不一定每次都要送出**請求本文**，有時只會請求某個路徑，可能帶一些查詢參數，但不會傳送本文。 -要宣告**請求**本文，你會使用 [Pydantic](https://docs.pydantic.dev/) 模型，享受其完整的功能與優點。 +要宣告**請求**本文，你會使用 [Pydantic](https://pydantic.dev/docs/) 模型，享受其完整的功能與優點。 /// note diff --git a/docs/zh-hant/docs/tutorial/debugging.md b/docs/zh-hant/docs/tutorial/debugging.md index a3254e3..c15df56 100644 --- a/docs/zh-hant/docs/tutorial/debugging.md +++ b/docs/zh-hant/docs/tutorial/debugging.md @@ -16,7 +16,7 @@
```console -$ python myapp.py +$ uv run python myapp.py ```
@@ -36,7 +36,7 @@ from myapp import app
```console -$ python myapp.py +$ uv run python myapp.py ```
diff --git a/docs/zh-hant/docs/tutorial/extra-data-types.md b/docs/zh-hant/docs/tutorial/extra-data-types.md index 23c7532..b04d986 100644 --- a/docs/zh-hant/docs/tutorial/extra-data-types.md +++ b/docs/zh-hant/docs/tutorial/extra-data-types.md @@ -37,7 +37,7 @@ * `datetime.timedelta`： * Python 的 `datetime.timedelta`。 * 在請求與回應中會以總秒數的 `float` 表示。 - * Pydantic 也允許用「ISO 8601 time diff encoding」來表示，[詳情見文件](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers)。 + * Pydantic 也允許用「ISO 8601 time diff encoding」來表示，[詳情見文件](https://pydantic.dev/docs/validation/latest/concepts/serialization/#custom-serializers)。 * `frozenset`： * 在請求與回應中與 `set` 相同處理： * 在請求中，會讀取一個 list，去除重複並轉為 `set`。 @@ -50,7 +50,7 @@ * `Decimal`： * 標準的 Python `Decimal`。 * 在請求與回應中，與 `float` 的處理方式相同。 -* 你可以在此查閱所有可用的 Pydantic 資料型別：[Pydantic 資料型別](https://docs.pydantic.dev/latest/usage/types/types/)。 +* 你可以在此查閱所有可用的 Pydantic 資料型別：[Pydantic 資料型別](https://pydantic.dev/docs/validation/latest/concepts/types/)。 ## 範例 { #example } diff --git a/docs/zh-hant/docs/tutorial/extra-models.md b/docs/zh-hant/docs/tutorial/extra-models.md index 162325e..0a2b90f 100644 --- a/docs/zh-hant/docs/tutorial/extra-models.md +++ b/docs/zh-hant/docs/tutorial/extra-models.md @@ -166,7 +166,7 @@ UserInDB( /// note -在定義 [`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions) 時，請先放置「更具體」的型別，再放「較不具體」的型別。以下範例中，較具體的 `PlaneItem` 置於 `CarItem` 之前：`Union[PlaneItem, CarItem]`。 +在定義 [`Union`](https://pydantic.dev/docs/validation/latest/concepts/unions/) 時，請先放置「更具體」的型別，再放「較不具體」的型別。以下範例中，較具體的 `PlaneItem` 置於 `CarItem` 之前：`Union[PlaneItem, CarItem]`。 /// diff --git a/docs/zh-hant/docs/tutorial/first-steps.md b/docs/zh-hant/docs/tutorial/first-steps.md index bc023cc..726e181 100644 --- a/docs/zh-hant/docs/tutorial/first-steps.md +++ b/docs/zh-hant/docs/tutorial/first-steps.md @@ -6,12 +6,18 @@ 將其複製到一個名為 `main.py` 的文件中。 +/// tip + +FastAPI 有一個[官方 VS Code 擴充套件](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode)（也支援 Cursor），提供許多功能，包括路徑操作瀏覽器、路徑操作搜尋、測試中的 CodeLens 導航（從測試跳到定義），以及 FastAPI Cloud 部署與日誌，全部都能從你的編輯器中使用。 + +/// + 執行即時重新載入伺服器（live server）：
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -78,7 +84,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) 現在，前往 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)。 -你將看到另一種自動文件（由 [ReDoc](https://github.com/Rebilly/ReDoc) 提供）： +你將看到另一種自動文件（由 [ReDoc](https://github.com/Redocly/redoc) 提供）： ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -185,13 +191,13 @@ from backend.main import app 你也可以把檔案路徑傳給 `fastapi dev` 指令，它會自動猜測要使用的 FastAPI app 物件： ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` 或者，你也可以把 `--entrypoint` 選項傳給 `fastapi dev` 指令： ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` 但這樣每次執行 `fastapi` 指令時都要記得傳入正確的路徑\entrypoint。 @@ -205,7 +211,7 @@ $ fastapi dev --entrypoint main:app
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -232,7 +238,7 @@ CLI 會自動偵測你的 FastAPI 應用並將它部署到雲端。若你尚未 `FastAPI` 是一個直接繼承自 `Starlette` 的類別。 -你同樣可以透過 `FastAPI` 來使用 [Starlette](https://www.starlette.dev/) 所有的功能。 +你同樣可以透過 `FastAPI` 來使用 [Starlette](https://starlette.dev/) 所有的功能。 /// diff --git a/docs/zh-hant/docs/tutorial/frontend.md b/docs/zh-hant/docs/tutorial/frontend.md index fbfd8b3..cc7709d 100644 --- a/docs/zh-hant/docs/tutorial/frontend.md +++ b/docs/zh-hant/docs/tutorial/frontend.md @@ -52,7 +52,7 @@ npm run build {* ../../docs_src/frontend/tutorial002_py310.py hl[5] *} -**FastAPI** 只會對看起來像瀏覽器導覽的 `GET` 和 `HEAD` 請求使用這個 fallback。遺失的檔案，例如 JavaScript、CSS 和圖片，仍會回傳 `404`。 +**FastAPI** 只會對明確使用 `Accept: text/html` 或 `Accept: application/xhtml+xml` 接受 HTML 的 `GET` 和 `HEAD` 請求使用這個 fallback，就像瀏覽器導覽請求通常會做的那樣。遺失的檔案，例如 JavaScript、CSS 和圖片，仍會回傳 `404`。 對於只符合前端 fallback 的路徑，使用其他方法的請求，例如 `POST` 或 `PUT`，也會回傳 `404`。一般的 **FastAPI** *路徑操作*仍然比前端路由有更高優先順序。 @@ -106,9 +106,13 @@ npm run build ## 檢查目錄 { #check-directory } -預設情況下，`app.frontend()` 會在建立應用程式時檢查目錄是否存在。 +預設情況下，`app.frontend()` 會使用 `check_dir="auto"`。 -這有助於及早發現設定錯誤。例如，如果缺少前端建置輸出目錄，**FastAPI** 會在啟動時引發錯誤。 +當 `FASTAPI_ENV` 環境變數設定為 `development` 時，如果前端建置輸出目錄遺失，**FastAPI** 只會顯示警告。如果尚未設定此環境變數，[`fastapi dev` 指令](https://github.com/fastapi/fastapi-cli#fastapi-dev)會為你設定。這讓你可以在開發期間，在建置或啟動前端之前先啟動後端。 + +在任何其他環境中，**FastAPI** 會在建立應用程式時引發錯誤。這有助於在部署沒有前端檔案的應用程式之前，及早發現設定錯誤。 + +你也可以設定 `check_dir=True`，以便在建立應用程式時一律檢查目錄。 如果你的前端檔案稍後才會建立，例如在建立 app 物件之後由另一個建置步驟產生，請設定 `check_dir=False`： @@ -132,6 +136,8 @@ npm run build 來自 app、`APIRouter` 和 `include_router()` 的 dependencies 也會套用到前端回應。這對使用 cookie authentication 或類似方式保護前端很有用。 +Dependencies 也可以像一般*路徑操作*一樣修改回應 headers 並加入 background tasks。 + ## 僅限靜態建置輸出 { #static-build-output-only } `app.frontend()` 會提供你的前端建置已經產生的檔案。 diff --git a/docs/zh-hant/docs/tutorial/handling-errors.md b/docs/zh-hant/docs/tutorial/handling-errors.md index dc6d7a7..b20151e 100644 --- a/docs/zh-hant/docs/tutorial/handling-errors.md +++ b/docs/zh-hant/docs/tutorial/handling-errors.md @@ -81,7 +81,7 @@ ## 安裝自訂例外處理器 { #install-custom-exception-handlers } -你可以使用 [Starlette 的相同例外工具](https://www.starlette.dev/exceptions/) 來加入自訂例外處理器。 +你可以使用 [Starlette 的相同例外工具](https://starlette.dev/exceptions/) 來加入自訂例外處理器。 假設你有一個自訂例外 `UnicornException`，你（或你使用的函式庫）可能會 `raise` 它。 diff --git a/docs/zh-hant/docs/tutorial/index.md b/docs/zh-hant/docs/tutorial/index.md index e20c9ca..5612ded 100644 --- a/docs/zh-hant/docs/tutorial/index.md +++ b/docs/zh-hant/docs/tutorial/index.md @@ -10,12 +10,12 @@ 所有程式碼區塊都可以直接複製和使用（它們實際上是經過測試的 Python 檔案）。 -要運行任何範例，請將程式碼複製到 `main.py` 檔案，並使用以下命令啟動 `fastapi dev`： +要運行任何範例，請將程式碼複製到 `main.py` 檔案，並使用 `uv run` 啟動 `fastapi dev`：
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -60,36 +60,76 @@ $ fastapi dev ## 安裝 FastAPI { #install-fastapi } -第一步是安裝 FastAPI。 +第一步是設定你的專案並加入 FastAPI。 -確保你建立一個[虛擬環境](../virtual-environments.md)，啟用它，然後**安裝 FastAPI**： +安裝 [`uv`](https://docs.astral.sh/uv/getting-started/installation/)，然後建立專案並加入 FastAPI：
```console -$ pip install "fastapi[standard]" +$ uv init awesome-project --bare +$ cd awesome-project +$ uv add "fastapi[standard]" ---> 100% ```
-/// note | 注意 +`uv add` 會在 `.venv` 中建立專案的虛擬環境，將 FastAPI 加入 `pyproject.toml`，並建立 `uv.lock`，讓之後可以安裝相同的套件版本。 -當你使用 `pip install "fastapi[standard]"` 安裝時，會包含一些預設的可選標準依賴項，其中包括 `fastapi-cloud-cli`，它可以讓你部署到 [FastAPI Cloud](https://fastapicloud.com)。 +/// details | 這些指令的作用 -如果你不想包含那些可選的依賴項，你可以改為安裝 `pip install fastapi`。 +* `uv init`：建立新的 Python 專案。 +* `awesome-project`：在具有此名稱的新目錄中建立專案。 +* `--bare`：只建立最小的 `pyproject.toml` 檔案，不產生範例 `main.py`、`README.md` 或其他檔案。你將在本教學的後續步驟中自行建立應用程式檔案。 -如果你想安裝標準依賴項，但不包含 `fastapi-cloud-cli`，可以使用 `pip install "fastapi[standard-no-fastapi-cloud-cli]"` 安裝。 +接著 `cd awesome-project` 會在加入 FastAPI 前進入新的專案目錄。 + +`uv` 會使用你系統上已安裝的相容 Python 版本，或在需要時下載一個。 + +當你運行 `uv add` 時，它會選擇 FastAPI 與 FastAPI 依賴的所有套件的相容版本。它會將確切版本記錄在 `uv.lock` 中，讓之後在另一台電腦或部署應用程式時，可以安裝相同的套件版本。 + +建立或更新這個檔案稱為[**鎖定**專案依賴項](https://docs.astral.sh/uv/concepts/projects/sync/)。`uv` 會在你加入套件時自動完成。 /// -/// tip +/// details | FastAPI 安裝選項 -FastAPI 提供了 [VS Code 官方擴充功能](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode)（以及 Cursor），包含許多功能，例如路徑操作探索器、路徑操作搜尋、測試中的 CodeLens 導航（從測試跳到定義）、以及 FastAPI Cloud 的部署與日誌，全部可直接在你的編輯器中完成。 +當你使用 `uv add "fastapi[standard]"` 安裝時，會包含一些預設的可選標準依賴項，其中包括 `fastapi-cloud-cli`，它可以讓你部署到 [FastAPI Cloud](https://fastapicloud.com)。 + +如果你不想包含那些可選的依賴項，你可以改為安裝 `uv add fastapi`。 + +如果你想安裝標準依賴項，但不包含 `fastapi-cloud-cli`，可以使用 `uv add "fastapi[standard-no-fastapi-cloud-cli]"` 安裝。 /// +/// details | 改用 `pip` + +如果你偏好手動管理虛擬環境與套件，請建立並啟用虛擬環境，然後使用 `pip install "fastapi[standard]"` 安裝 FastAPI。 + +請閱讀[虛擬環境指南](https://tiangolo.com/guides/virtual-environments/)以取得詳細步驟。 + +/// + +## AI Agent 技能 { #ai-agent-skills } + +FastAPI 包含給 AI coding agent 使用的官方技能。它隨套件一起提供，因此其指引會與你專案中安裝的 FastAPI 版本保持一致，並在你更新 FastAPI 時一起更新。 + +在你的專案中安裝 FastAPI 後，你可以使用 Library Skills 安裝這個技能： + +```bash +uvx library-skills +``` + +/// note + +`uvx` 是 `uv tool run` 的別名。它會在暫時且隔離的環境中運行 Library Skills，同時 Library Skills 會掃描你專案中已安裝的套件。 + +/// + +這個技能相容於 Codex、Claude Code、Cursor、GitHub Copilot、Gemini CLI、Pi、OpenCode，以及大多數其他 coding agent。若使用 Claude Code，當系統詢問要將技能安裝到哪裡時，請選擇 `.claude/skills`。 + ## 進階使用者指南 { #advanced-user-guide } 還有一個**進階使用者指南**你可以在讀完這個**教學 - 使用者指南**後再閱讀。 diff --git a/docs/zh-hant/docs/tutorial/middleware.md b/docs/zh-hant/docs/tutorial/middleware.md index 42a922d..fcf9a36 100644 --- a/docs/zh-hant/docs/tutorial/middleware.md +++ b/docs/zh-hant/docs/tutorial/middleware.md @@ -37,7 +37,7 @@ 請記得，自訂的非標準標頭可以[使用 `X-` 前綴](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)。 -但如果你有自訂標頭並希望瀏覽器端的用戶端能看到它們，你需要在 CORS 設定（[CORS（跨來源資源共用）](cors.md)）中使用 [Starlette 的 CORS 文件](https://www.starlette.dev/middleware/#corsmiddleware)所記載的參數 `expose_headers` 將它們加入。 +但如果你有自訂標頭並希望瀏覽器端的用戶端能看到它們，你需要在 CORS 設定（[CORS（跨來源資源共用）](cors.md)）中使用 [Starlette 的 CORS 文件](https://starlette.dev/middleware/#corsmiddleware)所記載的參數 `expose_headers` 將它們加入。 /// diff --git a/docs/zh-hant/docs/tutorial/path-params.md b/docs/zh-hant/docs/tutorial/path-params.md index 4e8d3dd..98525fe 100644 --- a/docs/zh-hant/docs/tutorial/path-params.md +++ b/docs/zh-hant/docs/tutorial/path-params.md @@ -92,7 +92,7 @@ ## 基於標準的優勢與替代文件 { #standards-based-benefits-alternative-documentation } -而且因為產生的 schema 來自 [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md) 標準，有很多相容的工具可用。 +而且因為產生的 schema 來自 [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) 標準，有很多相容的工具可用。 因此，**FastAPI** 本身也提供另一種 API 文件（使用 ReDoc），你可以在 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) 存取： @@ -102,7 +102,7 @@ ## Pydantic { #pydantic } -所有資料驗證都由 [Pydantic](https://docs.pydantic.dev/) 在底層處理，因此你能直接受惠。而且你可以放心使用。 +所有資料驗證都由 [Pydantic](https://pydantic.dev/docs/) 在底層處理，因此你能直接受惠。而且你可以放心使用。 你可以用相同的型別宣告搭配 `str`、`float`、`bool` 與許多更複雜的資料型別。 @@ -248,4 +248,4 @@ OpenAPI 並不支援直接宣告一個「路徑參數」內再包含一個「路 而且你只要宣告一次就好。 -這大概是 **FastAPI** 相較於其他框架最明顯的優勢之一（除了原始效能之外）。 +這大概是 **FastAPI** 相較於其他框架最明顯的優勢（除了原始效能之外）。 diff --git a/docs/zh-hant/docs/tutorial/query-params-str-validations.md b/docs/zh-hant/docs/tutorial/query-params-str-validations.md index 9969070..61e6ca1 100644 --- a/docs/zh-hant/docs/tutorial/query-params-str-validations.md +++ b/docs/zh-hant/docs/tutorial/query-params-str-validations.md @@ -370,11 +370,11 @@ http://127.0.0.1:8000/items/?item-query=foobaritems 這種情況下，你可以使用**自訂驗證函式**，它會在一般驗證之後套用（例如先確認值是 `str` 之後）。 -你可以在 `Annotated` 中使用 [Pydantic 的 `AfterValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator) 來達成。 +你可以在 `Annotated` 中使用 [Pydantic 的 `AfterValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-after-validator) 來達成。 /// tip | 提示 -Pydantic 也有 [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator) 等等。🤓 +Pydantic 也有 [`BeforeValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-before-validator) 等等。🤓 /// diff --git a/docs/zh-hant/docs/tutorial/request-files.md b/docs/zh-hant/docs/tutorial/request-files.md index 979a579..7d6bded 100644 --- a/docs/zh-hant/docs/tutorial/request-files.md +++ b/docs/zh-hant/docs/tutorial/request-files.md @@ -7,10 +7,10 @@ 若要接收上傳的檔案，請先安裝 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -請先建立並啟用一個[虛擬環境](../virtual-environments.md)，然後安裝，例如： +將它加入你的專案： ```console -$ pip install python-multipart +$ uv add python-multipart ``` 因為上傳的檔案是以「表單資料」送出的。 diff --git a/docs/zh-hant/docs/tutorial/request-form-models.md b/docs/zh-hant/docs/tutorial/request-form-models.md index 9bafb0e..681a0e0 100644 --- a/docs/zh-hant/docs/tutorial/request-form-models.md +++ b/docs/zh-hant/docs/tutorial/request-form-models.md @@ -6,10 +6,10 @@ 要使用表單，首先安裝 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -請先建立[虛擬環境](../virtual-environments.md)、啟用後再安裝，例如： +將它加入你的專案： ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// @@ -26,7 +26,7 @@ $ pip install python-multipart {* ../../docs_src/request_form_models/tutorial001_an_py310.py hl[9:11,15] *} -**FastAPI** 會從請求中的 **表單資料** 擷取 **各欄位** 的資料，並將這些資料組成你定義的 Pydantic 模型實例。 +**FastAPI** 會從請求中的 **表單資料** **擷取** **每個欄位** 的資料，並給你所定義的 Pydantic 模型。 ## 檢視文件 { #check-the-docs } @@ -38,7 +38,7 @@ $ pip install python-multipart ## 禁止額外的表單欄位 { #forbid-extra-form-fields } -在某些特殊情況（可能不常見）下，你可能希望僅允許 Pydantic 模型中宣告的表單欄位，並禁止任何額外欄位。 +在某些特殊情況（可能不常見）下，你可能希望將 **表單欄位** **限制** 為只有 Pydantic 模型中宣告的欄位。並**禁止**任何**額外**欄位。 /// note | 注意 @@ -50,7 +50,7 @@ $ pip install python-multipart {* ../../docs_src/request_form_models/tutorial002_an_py310.py hl[12] *} -如果用戶端嘗試傳送額外資料，將會收到錯誤回應。 +如果用戶端嘗試傳送額外資料，將會收到**錯誤**回應。 例如，用戶端若送出以下表單欄位： diff --git a/docs/zh-hant/docs/tutorial/request-forms-and-files.md b/docs/zh-hant/docs/tutorial/request-forms-and-files.md index 2db9e28..91ea5cd 100644 --- a/docs/zh-hant/docs/tutorial/request-forms-and-files.md +++ b/docs/zh-hant/docs/tutorial/request-forms-and-files.md @@ -6,10 +6,10 @@ 要接收上傳的檔案與/或表單資料，請先安裝 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -請先建立並啟用一個 [虛擬環境](../virtual-environments.md)，然後再安裝，例如： +將它加入你的專案： ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/zh-hant/docs/tutorial/request-forms.md b/docs/zh-hant/docs/tutorial/request-forms.md index 5907791..d116d4a 100644 --- a/docs/zh-hant/docs/tutorial/request-forms.md +++ b/docs/zh-hant/docs/tutorial/request-forms.md @@ -7,10 +7,10 @@ 要使用表單，請先安裝 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -請先建立並啟用一個[虛擬環境](../virtual-environments.md)，然後再安裝，例如： +將它加入你的專案： ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/zh-hant/docs/tutorial/response-model.md b/docs/zh-hant/docs/tutorial/response-model.md index be27694..1a20dab 100644 --- a/docs/zh-hant/docs/tutorial/response-model.md +++ b/docs/zh-hant/docs/tutorial/response-model.md @@ -76,16 +76,16 @@ FastAPI 會使用這個 `response_model` 來做所有的資料文件、驗證等 要使用 `EmailStr`，請先安裝 [`email-validator`](https://github.com/JoshData/python-email-validator)。 -請先建立一個[虛擬環境](../virtual-environments.md)、啟用它，然後安裝，例如： +將它加入你的專案： ```console -$ pip install email-validator +$ uv add email-validator ``` -或： +或使用： ```console -$ pip install "pydantic[email]" +$ uv add "pydantic[email]" ``` /// @@ -258,7 +258,7 @@ FastAPI 在內部會搭配 Pydantic 做一些事情，來確保不會把類別 * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -如 [Pydantic 文件](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict)中對 `exclude_defaults` 與 `exclude_none` 的說明。 +如 [Pydantic 文件](https://pydantic.dev/docs/validation/latest/concepts/serialization/#excluding-and-including-fields-based-on-their-value)中對 `exclude_defaults` 與 `exclude_none` 的說明。 /// diff --git a/docs/zh-hant/docs/tutorial/schema-extra-example.md b/docs/zh-hant/docs/tutorial/schema-extra-example.md index 8cca500..d2f196c 100644 --- a/docs/zh-hant/docs/tutorial/schema-extra-example.md +++ b/docs/zh-hant/docs/tutorial/schema-extra-example.md @@ -12,7 +12,7 @@ 這些額外資訊會原封不動加入該模型輸出的 **JSON Schema**，並且會用在 API 文件裡。 -你可以使用屬性 `model_config`（接收一個 `dict`），詳見 [Pydantic 文件：Configuration](https://docs.pydantic.dev/latest/api/config/)。 +你可以使用屬性 `model_config`（接收一個 `dict`），詳見 [Pydantic 文件：Configuration](https://pydantic.dev/docs/validation/latest/api/pydantic/config/)。 你可以將 `"json_schema_extra"` 設為一個 `dict`，其中包含你想在產生的 JSON Schema 中出現的任何額外資料，包括 `examples`。 @@ -197,6 +197,6 @@ JSON Schema 中新的 `examples` 欄位「就是一個 `list`」的範例集合 ### 總結 { #summary } -我以前常說我不太喜歡歷史……結果現在在這裡講「科技史」。😅 +我以前常說我不太喜歡歷史...結果現在在這裡講「科技史」。😅 簡而言之，**升級到 FastAPI 0.99.0 或以上**，事情會更**簡單、一致又直覺**，而且你不需要了解這些歷史細節。😎 diff --git a/docs/zh-hant/docs/tutorial/security/first-steps.md b/docs/zh-hant/docs/tutorial/security/first-steps.md index 7640a45..dbf1542 100644 --- a/docs/zh-hant/docs/tutorial/security/first-steps.md +++ b/docs/zh-hant/docs/tutorial/security/first-steps.md @@ -26,14 +26,14 @@ /// note -當你使用 `pip install "fastapi[standard]"` 指令安裝時，[`python-multipart`](https://github.com/Kludex/python-multipart) 套件會隨 **FastAPI** 自動安裝。 +當你執行 `uv add "fastapi[standard]"` 指令時，[`python-multipart`](https://github.com/Kludex/python-multipart) 套件會隨 **FastAPI** 自動安裝。 -不過若只執行 `pip install fastapi`，預設不會包含 `python-multipart`。 +不過若你使用 `uv add fastapi` 指令，預設不會包含 `python-multipart` 套件。 -若要手動安裝，請先建立並啟用一個[虛擬環境](../../virtual-environments.md)，接著執行： +若要手動安裝，請將它加入你的專案： ```console -$ pip install python-multipart +$ uv add python-multipart ``` 因為 **OAuth2** 會以「form data」傳送 `username` 與 `password`。 @@ -45,7 +45,7 @@ $ pip install python-multipart
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -72,7 +72,7 @@ $ fastapi dev -/// note | 注意 +/// note 不管你在表單輸入什麼，現在都還不會成功；等等我們會把它完成。 @@ -98,19 +98,19 @@ OAuth2 的設計讓後端或 API 可以獨立於執行使用者驗證的伺服 簡化來看流程如下： -- 使用者在前端輸入 `username` 與 `password`，按下 `Enter`。 -- 前端（在使用者的瀏覽器中執行）把 `username` 與 `password` 傳到我們 API 的特定 URL（在程式中宣告為 `tokenUrl="token"`）。 -- API 檢查 `username` 與 `password`，並回應一個「token（權杖）」（我們還沒實作這部分）。 - - 「token（權杖）」就是一段字串，之後可用來識別並驗證此使用者。 - - 通常 token 會設定一段時間後失效。 - - 因此使用者之後需要重新登入。 - - 若 token 被竊取，風險也較低；它不像永遠有效的萬用鑰匙（多數情況下）。 -- 前端會暫存這個 token。 -- 使用者在前端點擊，前往前端網頁應用程式的另一個區段。 -- 前端需要再向 API 取得資料。 - - 但該端點需要驗證。 - - 因此為了向 API 驗證，請求會帶上一個 `Authorization` 標頭，值為 `Bearer ` 加上 token。 - - 例如 token 是 `foobar`，則 `Authorization` 標頭內容為：`Bearer foobar`。 +* 使用者在前端輸入 `username` 與 `password`，按下 `Enter`。 +* 前端（在使用者的瀏覽器中執行）把 `username` 與 `password` 傳到我們 API 的特定 URL（在程式中宣告為 `tokenUrl="token"`）。 +* API 檢查 `username` 與 `password`，並回應一個「token（權杖）」（我們還沒實作這部分）。 + * 「token（權杖）」就是一段字串，之後可用來識別並驗證此使用者。 + * 通常 token 會設定一段時間後失效。 + * 因此使用者之後需要重新登入。 + * 若 token 被竊取，風險也較低；它不像永遠有效的萬用鑰匙（多數情況下）。 +* 前端會暫存這個 token。 +* 使用者在前端點擊，前往前端網頁應用程式的另一個區段。 +* 前端需要再向 API 取得資料。 + * 但該端點需要驗證。 + * 因此為了向 API 驗證，請求會帶上一個 `Authorization` 標頭，值為 `Bearer ` 加上 token。 + * 例如 token 是 `foobar`，則 `Authorization` 標頭內容為：`Bearer foobar`。 ## **FastAPI** 的 `OAuth2PasswordBearer` { #fastapis-oauth2passwordbearer } diff --git a/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md b/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md index dc75092..499a3b2 100644 --- a/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md +++ b/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md @@ -30,12 +30,12 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4 我們需要安裝 `PyJWT` 才能在 Python 中產生與驗證 JWT 權杖。 -請先建立並啟用一個[虛擬環境](../../virtual-environments.md)，然後安裝 `pyjwt`： +將 `pyjwt` 加入你的專案：
```console -$ pip install pyjwt +$ uv add pyjwt ---> 100% ``` @@ -72,12 +72,12 @@ pwdlib 是一個很棒的 Python 套件，用來處理密碼雜湊。 建議使用的演算法是「Argon2」。 -請先建立並啟用一個[虛擬環境](../../virtual-environments.md)，然後以 Argon2 支援安裝 pwdlib： +將帶有 Argon2 的 `pwdlib` 加入你的專案：
```console -$ pip install "pwdlib[argon2]" +$ uv add "pwdlib[argon2]" ---> 100% ``` diff --git a/docs/zh-hant/docs/tutorial/sql-databases.md b/docs/zh-hant/docs/tutorial/sql-databases.md index 3a0e43d..aa1e450 100644 --- a/docs/zh-hant/docs/tutorial/sql-databases.md +++ b/docs/zh-hant/docs/tutorial/sql-databases.md @@ -34,12 +34,12 @@ ## 安裝 `SQLModel` { #install-sqlmodel } -首先，請先建立你的[虛擬環境](../virtual-environments.md)、啟用它，然後安裝 `sqlmodel`： +將 `sqlmodel` 加入你的專案：
```console -$ pip install sqlmodel +$ uv add sqlmodel ---> 100% ``` @@ -152,7 +152,7 @@ SQLModel 之後會提供包裝 Alembic 的遷移工具，但目前你可以直
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -337,7 +337,7 @@ $ fastapi dev
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/zh-hant/docs/tutorial/static-files.md b/docs/zh-hant/docs/tutorial/static-files.md index 0d6369e..fba526b 100644 --- a/docs/zh-hant/docs/tutorial/static-files.md +++ b/docs/zh-hant/docs/tutorial/static-files.md @@ -12,8 +12,8 @@ ## 使用 `StaticFiles` { #use-staticfiles } -- 匯入 `StaticFiles`。 -- 在特定路徑上「掛載」一個 `StaticFiles()` 實例。 +* 匯入 `StaticFiles`。 +* 在特定路徑上「掛載」一個 `StaticFiles()` 實例。 {* ../../docs_src/static_files/tutorial001_py310.py hl[2,6] *} @@ -45,4 +45,4 @@ ## 更多資訊 { #more-info } -如需更多細節與選項，請參考 [Starlette 關於靜態檔案的文件](https://www.starlette.dev/staticfiles/)。 +如需更多細節與選項，請參考 [Starlette 關於靜態檔案的文件](https://starlette.dev/staticfiles/)。 diff --git a/docs/zh-hant/docs/tutorial/testing.md b/docs/zh-hant/docs/tutorial/testing.md index 09f6c0e..fbc5b10 100644 --- a/docs/zh-hant/docs/tutorial/testing.md +++ b/docs/zh-hant/docs/tutorial/testing.md @@ -1,6 +1,6 @@ # 測試 { #testing } -多虧了 [Starlette](https://www.starlette.dev/testclient/)，測試 **FastAPI** 應用既簡單又好用。 +多虧了 [Starlette](https://starlette.dev/testclient/)，測試 **FastAPI** 應用既簡單又好用。 它是基於 [HTTPX](https://www.python-httpx.org) 打造，而 HTTPX 的設計又參考了 Requests，所以用起來非常熟悉、直覺。 @@ -12,10 +12,10 @@ 要使用 `TestClient`，請先安裝 [`httpx`](https://www.python-httpx.org)。 -請先建立並啟用一個[虛擬環境](../virtual-environments.md)，然後安裝，例如： +把它加入你的專案： ```console -$ pip install httpx +$ uv add httpx ``` /// @@ -156,12 +156,12 @@ $ pip install httpx 接下來，你只需要安裝 `pytest`。 -請先建立並啟用一個[虛擬環境](../virtual-environments.md)，然後安裝，例如： +把它加入你的專案：
```console -$ pip install pytest +$ uv add pytest ---> 100% ``` @@ -175,7 +175,7 @@ $ pip install pytest
```console -$ pytest +$ uv run pytest ================ test session starts ================ platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1 diff --git a/docs/zh-hant/docs/virtual-environments.md b/docs/zh-hant/docs/virtual-environments.md index 5503634..a9c306e 100644 --- a/docs/zh-hant/docs/virtual-environments.md +++ b/docs/zh-hant/docs/virtual-environments.md @@ -1,864 +1,35 @@ # 虛擬環境 { #virtual-environments } -當你在 Python 專案中工作時，你可能會需要使用一個**虛擬環境**（或類似的機制）來隔離你為每個專案安裝的套件。 +當你在 Python 專案中工作時，你應該使用**虛擬環境**來隔離每個專案安裝的套件。 -/// note - -如果你已經了解虛擬環境，知道如何建立和使用它們，你可以考慮跳過這一部分。🤓 - -/// - -/// tip - -**虛擬環境**和**環境變數**是不同的。 - -**環境變數**是系統中的一個變數，可以被程式使用。 - -**虛擬環境**是一個包含一些檔案的目錄。 - -/// - -/// note - -這個頁面將教你如何使用**虛擬環境**以及了解它們的工作原理。 - -如果你計畫使用一個**可以為你管理一切的工具**（包括安裝 Python），試試 [uv](https://github.com/astral-sh/uv)。 - -/// +對於 FastAPI 專案，我建議使用 [uv](https://docs.astral.sh/uv/) 來管理專案、其依賴項和虛擬環境。 ## 建立一個專案 { #create-a-project } -首先，為你的專案建立一個目錄。 - -我通常會在我的主目錄下建立一個名為 `code` 的目錄。 - -在這個目錄下，我再為每個專案建立一個目錄。 +使用[官方安裝指南](https://docs.astral.sh/uv/getting-started/installation/)安裝 `uv`，然後建立一個專案：
```console -// 進入主目錄 -$ cd -// 建立一個用於存放所有程式碼專案的目錄 -$ mkdir code -// 進入 code 目錄 -$ cd code -// 建立一個用於存放這個專案的目錄 -$ mkdir awesome-project -// 進入這個專案的目錄 +$ uv init awesome-project --bare $ cd awesome-project +$ uv add "fastapi[standard]" ```
-## 建立一個虛擬環境 { #create-a-virtual-environment } +`uv` 會自動為專案建立虛擬環境。你不需要自己建立或啟動虛擬環境。 -在開始一個 Python 專案的**第一時間**，**在你的專案內部**建立一個虛擬環境。 - -/// tip - -你只需要**在每個專案中操作一次**，而不是每次工作時都操作。 - -/// - -//// tab | `venv` - -你可以使用 Python 自帶的 `venv` 模組來建立一個虛擬環境。 +使用 `uv run` 在專案環境中執行指令，例如：
```console -$ python -m venv .venv +$ uv run fastapi dev ```
-/// details | 上述指令的含義 +## 了解更多 { #learn-more } -* `python`: 使用名為 `python` 的程式 -* `-m`: 以腳本的方式呼叫一個模組，我們將告訴它接下來使用哪個模組 -* `venv`: 使用名為 `venv` 的模組，這個模組通常隨 Python 一起安裝 -* `.venv`: 在新目錄 `.venv` 中建立虛擬環境 - -/// - -//// - -//// tab | `uv` - -如果你安裝了 [`uv`](https://github.com/astral-sh/uv)，你也可以使用它來建立一個虛擬環境。 - -
- -```console -$ uv venv -``` - -
- -/// tip - -預設情況下，`uv` 會在一個名為 `.venv` 的目錄中建立一個虛擬環境。 - -但你可以透過傳遞一個額外的引數來自訂它，指定目錄的名稱。 - -/// - -//// - -這個指令會在一個名為 `.venv` 的目錄中建立一個新的虛擬環境。 - -/// details | `.venv`，或是其他名稱 - -你可以在不同的目錄下建立虛擬環境，但通常我們會把它命名為 `.venv`。 - -/// - -## 啟動虛擬環境 { #activate-the-virtual-environment } - -啟動新的虛擬環境來確保你運行的任何 Python 指令或安裝的套件都能使用到它。 - -/// tip - -**每次**開始一個**新的終端會話**來在這個專案工作時，你都需要執行這個操作。 - -/// - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -或者，如果你在 Windows 上使用 Bash（例如 [Git Bash](https://gitforwindows.org/)）： - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -/// tip - -每次你在這個環境中安裝一個**新的套件**時，都需要**再次啟用**這個環境。 - -這麼做確保了當你使用一個由這個套件安裝的**終端（CLI）程式**時，你使用的是你的虛擬環境中的程式，而不是全域安裝、可能版本不同的程式。 - -/// - -## 檢查虛擬環境是否啟動 { #check-the-virtual-environment-is-active } - -檢查虛擬環境是否啟動（前面的指令是否生效）。 - -/// tip - -這是**非必需的**，但這是一個很好的方法，可以**檢查**一切是否按預期工作，以及你是否使用了你打算使用的虛擬環境。 - -/// - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -如果它顯示了在你專案（在這個例子中是 `awesome-project`）的 `.venv/bin/python` 中的 `python` 二進位檔案，那麼它就生效了。🎉 - -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -如果它顯示了在你專案（在這個例子中是 `awesome-project`）的 `.venv\Scripts\python` 中的 `python` 二進位檔案，那麼它就生效了。🎉 - -//// - -## 升級 `pip` { #upgrade-pip } - -/// tip - -如果你使用 [`uv`](https://github.com/astral-sh/uv) 來安裝內容，而不是 `pip`，那麼你就不需要升級 `pip`。😎 - -/// - -如果你使用 `pip` 來安裝套件（它是 Python 的預設元件），你應該將它**升級**到最新版本。 - -在安裝套件時出現的許多奇怪的錯誤都可以透過先升級 `pip` 來解決。 - -/// tip - -通常你只需要在建立虛擬環境後**執行一次**這個操作。 - -/// - -確保虛擬環境是啟動的（使用上面的指令），然後運行： - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip - -有時你在嘗試升級 pip 時，可能會遇到 **`No module named pip`** 的錯誤。 - -如果發生這種情況，請用下面的指令安裝並升級 pip： - -
- -```console -$ python -m ensurepip --upgrade - ----> 100% -``` - -
- -此指令會在未安裝 pip 時為你安裝它，並確保安裝的 pip 版本至少與 `ensurepip` 所提供的版本一樣新。 - -/// - -## 加入 `.gitignore` { #add-gitignore } - -如果你使用 **Git**（這是你應該使用的），加入一個 `.gitignore` 檔案來排除你的 `.venv` 中的所有內容。 - -/// tip - -如果你使用 [`uv`](https://github.com/astral-sh/uv) 來建立虛擬環境，它會自動為你完成這個操作，你可以跳過這一步。😎 - -/// - -/// tip - -通常你只需要在建立虛擬環境後**執行一次**這個操作。 - -/// - -
- -```console -$ echo "*" > .venv/.gitignore -``` - -
- -/// details | 上述指令的含義 - -- `echo "*"`: 將在終端中「顯示」文本 `*`（接下來的部分會對這個操作進行一些修改） -- `>`: 使左邊的指令顯示到終端的任何內容實際上都不會被顯示，而是會被寫入到右邊的檔案中 -- `.gitignore`: 被寫入文本的檔案的名稱 - -而 `*` 對於 Git 來說意味著「所有內容」。所以，它會忽略 `.venv` 目錄中的所有內容。 - -該指令會建立一個名為 `.gitignore` 的檔案，內容如下： - -```gitignore -* -``` - -/// - -## 安裝套件 { #install-packages } - -在啟用虛擬環境後，你可以在其中安裝套件。 - -/// tip - -當你需要安裝或升級套件時，執行本操作**一次**； - -如果你需要再升級版本或新增套件，你可以**再次執行此操作**。 - -/// - -### 直接安裝套件 { #install-packages-directly } - -如果你急於安裝，不想使用檔案來聲明專案的套件依賴，你可以直接安裝它們。 - -/// tip - -將程式所需的套件及其版本放在檔案中（例如 `requirements.txt` 或 `pyproject.toml`）是個好（而且非常好）的主意。 - -/// - -//// tab | `pip` - -
- -```console -$ pip install "fastapi[standard]" - ----> 100% -``` - -
- -//// - -//// tab | `uv` - -如果你有 [`uv`](https://github.com/astral-sh/uv): - -
- -```console -$ uv pip install "fastapi[standard]" ----> 100% -``` - -
- -//// - -### 從 `requirements.txt` 安裝 { #install-from-requirements-txt } - -如果你有一個 `requirements.txt` 檔案，你可以使用它來安裝其中的套件。 - -//// tab | `pip` - -
- -```console -$ pip install -r requirements.txt ----> 100% -``` - -
- -//// - -//// tab | `uv` - -如果你有 [`uv`](https://github.com/astral-sh/uv): - -
- -```console -$ uv pip install -r requirements.txt ----> 100% -``` - -
- -//// - -/// details | `requirements.txt` - -一個包含一些套件的 `requirements.txt` 檔案看起來應該是這樣的： - -```requirements.txt -fastapi[standard]==0.113.0 -pydantic==2.8.0 -``` - -/// - -## 執行程式 { #run-your-program } - -在啟用虛擬環境後，你可以執行你的程式，它將使用虛擬環境中的 Python 和你在其中安裝的套件。 - -
- -```console -$ python main.py - -Hello World -``` - -
- -## 設定編輯器 { #configure-your-editor } - -你可能會用到編輯器，請確保設定它使用你建立的相同虛擬環境（它可能會自動偵測到），以便你可以獲得自動完成和內嵌錯誤提示。 - -例如： - -* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) -* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) - -/// tip - -通常你只需要在建立虛擬環境時執行此操作**一次**。 - -/// - -## 退出虛擬環境 { #deactivate-the-virtual-environment } - -當你完成工作後，你可以**退出**虛擬環境。 - -
- -```console -$ deactivate -``` - -
- -這樣，當你執行 `python` 時它不會嘗試從已安裝套件的虛擬環境中執行。 - -## 開始工作 { #ready-to-work } - -現在你已經準備好開始你的工作了。 - - - -/// tip - -你想要理解上面的所有內容嗎？ - -繼續閱讀。👇🤓 - -/// - -## 為什麼要使用虛擬環境 { #why-virtual-environments } - -你需要安裝 [Python](https://www.python.org/) 才能使用 FastAPI。 - -接下來，你需要**安裝** FastAPI 以及你想使用的其他**套件**。 - -要安裝套件，你通常會使用隨 Python 一起提供的 `pip` 指令（或類似的替代工具）。 - -然而，如果你直接使用 `pip`，套件將會安裝在你的**全域 Python 環境**中（即 Python 的全域安裝）。 - -### 存在的問題 { #the-problem } - -那麼，在全域 Python 環境中安裝套件有什麼問題呢？ - -有時候，你可能會開發許多不同的程式，而這些程式各自依賴於**不同的套件**；有些專案甚至需要依賴於**相同套件的不同版本**。😱 - -例如，你可能會建立一個名為 `philosophers-stone` 的專案，這個程式依賴於另一個名為 **`harry` 的套件，並使用版本 `1`**。因此，你需要安裝 `harry`。 - -```mermaid -flowchart LR - stone(philosophers-stone) -->|需要| harry-1[harry v1] -``` - -然而，在此之後，你又建立了另一個名為 `prisoner-of-azkaban` 的專案，而這個專案也依賴於 `harry`，但需要的是 **`harry` 版本 `3`**。 - -```mermaid -flowchart LR - azkaban(prisoner-of-azkaban) --> |需要| harry-3[harry v3] -``` - -現在的問題是，如果你在全域環境中安裝套件而不是在本地**虛擬環境**中，你將面臨選擇安裝哪個版本的 `harry` 的困境。 - -如果你想運行 `philosophers-stone`，你需要先安裝 `harry` 版本 `1`，例如： - -
- -```console -$ pip install "harry==1" -``` - -
- -然後你會在全域 Python 環境中安裝 `harry` 版本 `1`。 - -```mermaid -flowchart LR - subgraph global[全域環境] - harry-1[harry v1] - end - subgraph stone-project[專案 philosophers-stone] - stone(philosophers-stone) -->|需要| harry-1 - end -``` - -但如果你想運行 `prisoner-of-azkaban`，你需要解除安裝 `harry` 版本 `1` 並安裝 `harry` 版本 `3`（或者只要你安裝版本 `3`，版本 `1` 就會自動移除）。 - -
- -```console -$ pip install "harry==3" -``` - -
- -於是，你在全域 Python 環境中安裝了 `harry` 版本 `3`。 - -如果你再次嘗試運行 `philosophers-stone`，很可能會**無法正常運作**，因為它需要的是 `harry` 版本 `1`。 - -```mermaid -flowchart LR - subgraph global[全域環境] - harry-1[harry v1] - style harry-1 fill:#ccc,stroke-dasharray: 5 5 - harry-3[harry v3] - end - subgraph stone-project[專案 philosophers-stone] - stone(philosophers-stone) -.-x|⛔️| harry-1 - end - subgraph azkaban-project[專案 prisoner-of-azkaban] - azkaban(prisoner-of-azkaban) --> |需要| harry-3 - end -``` - -/// tip - -Python 套件在推出**新版本**時通常會儘量**避免破壞性更改**，但最好還是要謹慎，在安裝新版本前進行測試，以確保一切能正常運行。 - -/// - -現在，想像一下如果有**許多**其他**套件**，它們都是你的**專案所依賴的**。這樣是非常難以管理的。你可能會發現有些專案使用了一些**不相容的套件版本**，而無法得知為什麼某些程式無法正常運作。 - -此外，取決於你的作業系統（例如 Linux、Windows、macOS），它可能已經預先安裝了 Python。在這種情況下，它可能已經有一些系統所需的套件和特定版本。如果你在全域 Python 環境中安裝套件，可能會**破壞**某些隨作業系統一起安裝的程式。 - -## 套件安裝在哪裡 { #where-are-packages-installed } - -當你安裝 Python 時，它會在你的電腦中建立一些目錄並放置一些檔案。 - -其中一些目錄專門用來存放你所安裝的所有套件。 - -當你運行： - -
- -```console -// 先別去運行這個指令，這只是個示例 🤓 -$ pip install "fastapi[standard]" ----> 100% -``` - -
- -這會從 [PyPI](https://pypi.org/project/fastapi/) 下載一個壓縮檔案，其中包含 FastAPI 的程式碼。 - -它還會**下載** FastAPI 所依賴的其他套件的檔案。 - -接著，它會**解壓**所有這些檔案，並將它們放在你的電腦中的某個目錄中。 - -預設情況下，這些下載和解壓的檔案會放置於隨 Python 安裝的目錄中，即**全域環境**。 - -## 什麼是虛擬環境 { #what-are-virtual-environments } - -解決套件都安裝在全域環境中的問題方法是為你所做的每個專案使用一個**虛擬環境**。 - -虛擬環境是一個**目錄**，與全域環境非常相似，你可以在其中針對某個專案安裝套件。 - -這樣，每個專案都會有自己的虛擬環境（`.venv` 目錄），其中包含自己的套件。 - -```mermaid -flowchart TB - subgraph stone-project[專案 philosophers-stone] - stone(philosophers-stone) --->|需要| harry-1 - subgraph venv1[.venv] - harry-1[harry v1] - end - end - subgraph azkaban-project[專案 prisoner-of-azkaban] - azkaban(prisoner-of-azkaban) --->|需要| harry-3 - subgraph venv2[.venv] - harry-3[harry v3] - end - end - stone-project ~~~ azkaban-project -``` - -## 啟用虛擬環境意味著什麼 { #what-does-activating-a-virtual-environment-mean } - -當你啟用了虛擬環境，例如： - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -或者如果你在 Windows 上使用 Bash（例如 [Git Bash](https://gitforwindows.org/)）： - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -這個命令會建立或修改一些[環境變數](environment-variables.md)，這些環境變數將在接下來的指令中可用。 - -其中之一是 `PATH` 變數。 - -/// tip - -你可以在 [環境變數](environment-variables.md#path-environment-variable) 部分了解更多關於 `PATH` 環境變數的內容。 - -/// - -啟用虛擬環境會將其路徑 `.venv/bin`（在 Linux 和 macOS 上）或 `.venv\Scripts`（在 Windows 上）加入到 `PATH` 環境變數中。 - -假設在啟用環境之前，`PATH` 變數看起來像這樣： - -//// tab | Linux, macOS - -```plaintext -/usr/bin:/bin:/usr/sbin:/sbin -``` - -這意味著系統會在以下目錄中查找程式： - -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Windows\System32 -``` - -這意味著系統會在以下目錄中查找程式： - -* `C:\Windows\System32` - -//// - -啟用虛擬環境後，`PATH` 變數會變成這樣： - -//// tab | Linux, macOS - -```plaintext -/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -這意味著系統現在會首先在以下目錄中查找程式： - -```plaintext -/home/user/code/awesome-project/.venv/bin -``` - -然後再在其他目錄中查找。 - -因此，當你在終端機中輸入 `python` 時，系統會在以下目錄中找到 Python 程式： - -```plaintext -/home/user/code/awesome-project/.venv/bin/python -``` - -並使用這個。 - -//// - -//// tab | Windows - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32 -``` - -這意味著系統現在會首先在以下目錄中查找程式： - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts -``` - -然後再在其他目錄中查找。 - -因此，當你在終端機中輸入 `python` 時，系統會在以下目錄中找到 Python 程式： - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -並使用這個。 - -//// - -一個重要的細節是，虛擬環境路徑會被放在 `PATH` 變數的**開頭**。系統會在找到任何其他可用的 Python **之前**找到它。這樣，當你運行 `python` 時，它會使用**虛擬環境中的** Python，而不是任何其他 `python`（例如，全域環境中的 `python`）。 - -啟用虛擬環境還會改變其他一些內容，但這是它所做的最重要的事情之一。 - -## 檢查虛擬環境 { #checking-a-virtual-environment } - -當你檢查虛擬環境是否啟動時，例如： - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -//// - -這表示將使用的 `python` 程式是**在虛擬環境中**的那一個。 - -在 Linux 和 macOS 中使用 `which`，在 Windows PowerShell 中使用 `Get-Command`。 - -這個指令的運作方式是，它會在 `PATH` 環境變數中搜尋，依序**逐個路徑**查找名為 `python` 的程式。一旦找到，它會**顯示該程式的路徑**。 - -最重要的是，當你呼叫 `python` 時，將執行的就是這個確切的 "`python`"。 - -因此，你可以確認是否在正確的虛擬環境中。 - -/// tip - -啟動一個虛擬環境，取得一個 Python，然後**切換到另一個專案**是件很容易的事； - -但如果第二個專案**無法正常運作**，那可能是因為你使用了來自其他專案的虛擬環境的、**不正確的 Python**。 - -因此，檢查正在使用的 `python` 是非常實用的。🤓 - -/// - -## 為什麼要停用虛擬環境 { #why-deactivate-a-virtual-environment } - -例如，你可能正在一個專案 `philosophers-stone` 上工作，**啟動了該虛擬環境**，安裝了套件並使用了該環境， - -然後你想要在**另一個專案** `prisoner-of-azkaban` 上工作， - -你進入那個專案： - -
- -```console -$ cd ~/code/prisoner-of-azkaban -``` - -
- -如果你不去停用 `philosophers-stone` 的虛擬環境，當你在終端中執行 `python` 時，它會嘗試使用 `philosophers-stone` 中的 Python。 - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -$ python main.py - -// 匯入 sirius 錯誤，未安裝 😱 -Traceback (most recent call last): - File "main.py", line 1, in - import sirius -``` - -
- -但如果你停用虛擬環境並啟用 `prisoner-of-azkaban` 的新虛擬環境，那麼當你執行 `python` 時，它會使用 `prisoner-of-azkaban` 中虛擬環境的 Python。 - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -// 你不需要在舊目錄中操作停用，你可以在任何地方操作停用，甚至在切換到另一個專案之後 😎 -$ deactivate - -// 啟用 prisoner-of-azkaban/.venv 中的虛擬環境 🚀 -$ source .venv/bin/activate - -// 現在當你執行 python 時，它會在這個虛擬環境中找到已安裝的 sirius 套件 ✨ -$ python main.py - -I solemnly swear 🐺 -``` - -
- -## 替代方案 { #alternatives } - -這是一個簡單的指南，幫助你入門並教會你如何理解一切**底層**的原理。 - -有許多**替代方案**來管理虛擬環境、套件依賴（requirements）、專案。 - -當你準備好並想要使用一個工具來**管理整個專案**、套件依賴、虛擬環境等，建議你嘗試 [uv](https://github.com/astral-sh/uv)。 - -`uv` 可以執行許多操作，它可以： - -* 為你**安裝 Python**，包括不同的版本 -* 為你的專案管理**虛擬環境** -* 安裝**套件** -* 為你的專案管理套件的**依賴和版本** -* 確保你有一個**精確**的套件和版本集合來安裝，包括它們的依賴項，這樣你可以確保專案在生產環境中運行的狀態與開發時在你的電腦上運行的狀態完全相同，這被稱為**鎖定** -* 還有很多其他功能 - -## 結論 { #conclusion } - -如果你讀過並理解了所有這些，現在**你對虛擬環境的了解已超過許多開發者**。🤓 - -未來當你為看起來複雜的問題除錯時，了解這些細節很可能會有所幫助，你會知道**它是如何在底層運作的**。😎 +閱讀[虛擬環境指南](https://tiangolo.com/guides/virtual-environments/)來了解虛擬環境在底層如何運作，包括啟動，以及替代的 `python -m venv` 和 `pip` 工作流程。 diff --git a/docs/zh/docs/advanced/additional-responses.md b/docs/zh/docs/advanced/additional-responses.md index 842d49b..b94715c 100644 --- a/docs/zh/docs/advanced/additional-responses.md +++ b/docs/zh/docs/advanced/additional-responses.md @@ -243,5 +243,5 @@ new_dict = {**old_dict, "new key": "new value"} 要查看响应中究竟可以包含什么，你可以查看 OpenAPI 规范中的以下部分： -* [OpenAPI Responses 对象](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object)，它包含 `Response Object`。 -* [OpenAPI Response 对象](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object)，你可以把这里的任何内容直接包含到 `responses` 参数中的每个响应里。包括 `description`、`headers`、`content`（在这里声明不同的媒体类型和 JSON Schemas），以及 `links`。 +* [OpenAPI Responses 对象](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object)，它包含 `Response Object`。 +* [OpenAPI Response 对象](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object)，你可以把这里的任何内容直接包含到 `responses` 参数中的每个响应里。包括 `description`、`headers`、`content`（在这里声明不同的媒体类型和 JSON Schemas），以及 `links`。 diff --git a/docs/zh/docs/advanced/async-tests.md b/docs/zh/docs/advanced/async-tests.md index 2030bb1..5ba7c61 100644 --- a/docs/zh/docs/advanced/async-tests.md +++ b/docs/zh/docs/advanced/async-tests.md @@ -45,7 +45,7 @@
```console -$ pytest +$ uv run pytest ---> 100% ``` diff --git a/docs/zh/docs/advanced/behind-a-proxy.md b/docs/zh/docs/advanced/behind-a-proxy.md index b3c91eb..bd99497 100644 --- a/docs/zh/docs/advanced/behind-a-proxy.md +++ b/docs/zh/docs/advanced/behind-a-proxy.md @@ -33,7 +33,7 @@
```console -$ fastapi run --forwarded-allow-ips="*" +$ uv run fastapi run --forwarded-allow-ips="*" INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -91,9 +91,9 @@ sequenceDiagram 这些请求头保留了原始请求中否则会丢失的信息： -- X-Forwarded-For：原始客户端的 IP 地址 -- X-Forwarded-Proto：原始协议（`https`） -- X-Forwarded-Host：原始主机（`mysuperapp.com`） +* **X-Forwarded-For**：原始客户端的 IP 地址 +* **X-Forwarded-Proto**：原始协议（`https`） +* **X-Forwarded-Host**：原始主机（`mysuperapp.com`） 当 **FastAPI CLI** 配置了 `--forwarded-allow-ips` 后，它会信任并使用这些请求头，例如用于在重定向中生成正确的 URL。 @@ -149,14 +149,14 @@ IP `0.0.0.0` 通常表示程序监听该机器/服务器上的所有可用 IP。 ```JSON hl_lines="4-8" { "openapi": "3.1.0", - // More stuff here + // 这里还有更多内容 "servers": [ { "url": "/api/v1" } ], "paths": { - // More stuff here + // 这里还有更多内容 } } ``` @@ -170,7 +170,7 @@ IP `0.0.0.0` 通常表示程序监听该机器/服务器上的所有可用 IP。
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -200,7 +200,7 @@ ASGI 规范为这种用例定义了 `root_path`。
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -253,7 +253,7 @@ Uvicorn 会期望代理以 `http://127.0.0.1:8000/app` 访问 Uvicorn，而在 你可以很容易地使用 [Traefik](https://docs.traefik.io/) 在本地运行一个移除路径前缀的实验。 -[下载 Traefik](https://github.com/containous/traefik/releases)，它是一个单独的二进制文件，你可以解压压缩包并直接在终端中运行。 +[下载 Traefik](https://github.com/traefik/traefik/releases)，它是一个单独的二进制文件，你可以解压压缩包并直接在终端中运行。 然后创建一个 `traefik.toml` 文件，内容如下： @@ -321,7 +321,7 @@ INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -407,7 +407,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 ```JSON hl_lines="5-7" { "openapi": "3.1.0", - // More stuff here + // 这里还有更多内容 "servers": [ { "url": "/api/v1" @@ -422,7 +422,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 } ], "paths": { - // More stuff here + // 这里还有更多内容 } } ``` diff --git a/docs/zh/docs/advanced/dataclasses.md b/docs/zh/docs/advanced/dataclasses.md index df94a7d..bc21dae 100644 --- a/docs/zh/docs/advanced/dataclasses.md +++ b/docs/zh/docs/advanced/dataclasses.md @@ -7,7 +7,7 @@ FastAPI 基于 **Pydantic** 构建，我已经向你展示过如何使用 Pydant {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -这仍然得益于 **Pydantic**，因为它对 [`dataclasses` 的内置支持](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel)。 +这仍然得益于 **Pydantic**，因为它对 [`dataclasses` 的内置支持](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/#usage-of-stdlib-dataclasses-with-basemodel)。 因此，即便上面的代码没有显式使用 Pydantic，FastAPI 也会使用 Pydantic 将那些标准数据类转换为 Pydantic 风格的 dataclasses。 @@ -81,7 +81,7 @@ FastAPI 基于 **Pydantic** 构建，我已经向你展示过如何使用 Pydant 你还可以把 `dataclasses` 与其它 Pydantic 模型组合、从它们继承、把它们包含到你自己的模型中等。 -想了解更多，请查看 [Pydantic 关于 dataclasses 的文档](https://docs.pydantic.dev/latest/concepts/dataclasses/)。 +想了解更多，请查看 [Pydantic 关于 dataclasses 的文档](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/)。 ## 版本 { #version } diff --git a/docs/zh/docs/advanced/events.md b/docs/zh/docs/advanced/events.md index 49d497d..0c44983 100644 --- a/docs/zh/docs/advanced/events.md +++ b/docs/zh/docs/advanced/events.md @@ -155,7 +155,7 @@ async with lifespan(app): /// note | 注意 -你可以在 [Starlette 的 Lifespan 文档](https://www.starlette.dev/lifespan/) 中阅读更多关于 `lifespan` 处理器的内容。 +你可以在 [Starlette 的 Lifespan 文档](https://starlette.dev/lifespan/) 中阅读更多关于 `lifespan` 处理器的内容。 包括如何处理生命周期状态，以便在代码的其他部分使用。 diff --git a/docs/zh/docs/advanced/generate-clients.md b/docs/zh/docs/advanced/generate-clients.md index dd15f0e..34ee35f 100644 --- a/docs/zh/docs/advanced/generate-clients.md +++ b/docs/zh/docs/advanced/generate-clients.md @@ -12,7 +12,7 @@ 对于 **TypeScript 客户端**，[Hey API](https://heyapi.dev/) 是为 TypeScript 生态打造的专用方案，提供优化的使用体验。 -你还可以在 [OpenAPI.Tools](https://openapi.tools/#sdk) 上发现更多 SDK 生成器。 +你还可以在 [OpenAPI.Tools](https://openapi.tools/categories/sdk-generators) 上发现更多 SDK 生成器。 /// tip | 提示 diff --git a/docs/zh/docs/advanced/middleware.md b/docs/zh/docs/advanced/middleware.md index 4077ec0..3632f00 100644 --- a/docs/zh/docs/advanced/middleware.md +++ b/docs/zh/docs/advanced/middleware.md @@ -87,11 +87,11 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") ## 其它中间件 { #other-middlewares } -除了上述中间件外，FastAPI 还支持其它 ASGI 中间件。 +还有许多其它 ASGI 中间件。 例如： -* [Uvicorn 的 `ProxyHeadersMiddleware`](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) +* [Uvicorn 的 `ProxyHeadersMiddleware`](https://github.com/Kludex/uvicorn/blob/main/uvicorn/middleware/proxy_headers.py) * [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -其它可用中间件详见 [Starlette 官档 - 中间件](https://www.starlette.dev/middleware/) 及 [ASGI Awesome 列表](https://github.com/florimondmanca/awesome-asgi)。 +其它可用中间件详见 [Starlette 的中间件文档](https://starlette.dev/middleware/) 及 [ASGI Awesome 列表](https://github.com/florimondmanca/awesome-asgi)。 diff --git a/docs/zh/docs/advanced/openapi-callbacks.md b/docs/zh/docs/advanced/openapi-callbacks.md index 3ca99b9..01cdc20 100644 --- a/docs/zh/docs/advanced/openapi-callbacks.md +++ b/docs/zh/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ /// tip | 提示 -`callback_url` 查询参数使用 Pydantic 的 [Url](https://docs.pydantic.dev/latest/api/networks/) 类型。 +`callback_url` 查询参数使用 Pydantic 的 [Url](https://pydantic.dev/docs/validation/latest/api/pydantic/networks/) 类型。 /// @@ -106,11 +106,11 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) 它与普通*路径操作*有 2 个主要区别： * 它不需要任何实际代码，因为你的应用永远不会调用这段代码。它只用于记录*外部 API*。因此，函数可以只有 `pass`。 -* *路径*可以包含 [OpenAPI 3 表达式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)（见下文），其中可以使用带参数的变量，以及发送到*你的 API*的原始请求的部分内容。 +* *路径*可以包含 [OpenAPI 3 表达式](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression)（见下文），其中可以使用带参数的变量，以及发送到*你的 API*的原始请求的部分内容。 ### 回调路径表达式 { #the-callback-path-expression } -回调*路径*可以有一个 [OpenAPI 3 表达式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)，其中可以包含发送到*你的 API*的原始请求的部分内容。 +回调*路径*可以有一个 [OpenAPI 3 表达式](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression)，其中可以包含发送到*你的 API*的原始请求的部分内容。 在这个例子中，它是这个 `str`： diff --git a/docs/zh/docs/advanced/response-cookies.md b/docs/zh/docs/advanced/response-cookies.md index 9a41b95..88bcf0a 100644 --- a/docs/zh/docs/advanced/response-cookies.md +++ b/docs/zh/docs/advanced/response-cookies.md @@ -48,4 +48,4 @@ /// -要查看所有可用参数和选项，请查看 [Starlette 文档](https://www.starlette.dev/responses/#set-cookie)。 +要查看所有可用参数和选项，请查看 [Starlette 文档](https://starlette.dev/responses/#set-cookie)。 diff --git a/docs/zh/docs/advanced/response-headers.md b/docs/zh/docs/advanced/response-headers.md index 8935705..e39d66b 100644 --- a/docs/zh/docs/advanced/response-headers.md +++ b/docs/zh/docs/advanced/response-headers.md @@ -1,6 +1,5 @@ # 响应头 { #response-headers } - ## 使用 `Response` 参数 { #use-a-response-parameter } 你可以在你的*路径操作函数*中声明一个 `Response` 类型的参数（就像你可以为 cookies 做的那样）。 @@ -39,4 +38,4 @@ 请注意，可以通过[使用 `X-` 前缀](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)添加自定义专有头部。 -但是，如果你有自定义头部，并希望浏览器中的客户端能够看到它们，你需要将它们添加到你的 CORS 配置中（在 [CORS（跨源资源共享）](../tutorial/cors.md) 中阅读更多），使用在 [Starlette 的 CORS 文档](https://www.starlette.dev/middleware/#corsmiddleware)中记录的 `expose_headers` 参数。 +但是，如果你有自定义头部，并希望浏览器中的客户端能够看到它们，你需要将它们添加到你的 CORS 配置中（在 [CORS（跨源资源共享）](../tutorial/cors.md) 中阅读更多），使用在 [Starlette 的 CORS 文档](https://starlette.dev/middleware/#corsmiddleware)中记录的 `expose_headers` 参数。 diff --git a/docs/zh/docs/advanced/settings.md b/docs/zh/docs/advanced/settings.md index 2159ccb..f2d2f62 100644 --- a/docs/zh/docs/advanced/settings.md +++ b/docs/zh/docs/advanced/settings.md @@ -6,9 +6,13 @@ 因此，通常会将它们提供为由应用程序读取的环境变量。 +**环境变量**（也称为 **env var**）是存在于 Python 代码之外、操作系统中的值，可以由你的应用和其他程序读取。 + +你可以在运行命令时为该命令创建环境变量。你将在下面看到特定于平台的命令。 + /// tip | 提示 -要理解环境变量，你可以阅读[环境变量](../environment-variables.md)。 +阅读[环境变量指南](https://tiangolo.com/guides/environment-variables/)以详细了解环境变量的工作方式。 /// @@ -20,16 +24,16 @@ ## Pydantic 的 `Settings` { #pydantic-settings } -幸运的是，Pydantic 提供了一个很好的工具来处理来自环境变量的这些设置：[Pydantic：Settings 管理](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)。 +幸运的是，Pydantic 提供了一个很好的工具来处理来自环境变量的这些设置：[Pydantic：Settings 管理](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/)。 ### 安装 `pydantic-settings` { #install-pydantic-settings } -首先，确保你创建并激活了[虚拟环境](../virtual-environments.md)，然后安装 `pydantic-settings` 包： +将 `pydantic-settings` 包添加到你的项目：
```console -$ pip install pydantic-settings +$ uv add pydantic-settings ---> 100% ``` @@ -40,7 +44,7 @@ $ pip install pydantic-settings
```console -$ pip install "fastapi[all]" +$ uv add "fastapi[all]" ---> 100% ``` @@ -76,19 +80,39 @@ $ pip install "fastapi[all]" 接下来，运行服务器，并把配置作为环境变量传入，例如你可以设置 `ADMIN_EMAIL` 和 `APP_NAME`： +//// tab | Linux, macOS, Windows Bash +
```console -$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py +$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uv run fastapi run main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
+//// + +//// tab | Windows PowerShell + +
+ +```console +$ $Env:ADMIN_EMAIL = "deadpool@example.com" +$ $Env:APP_NAME = "ChimichangApp" +$ uv run fastapi run main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +//// + /// tip | 提示 -要为单个命令设置多个环境变量，只需用空格分隔它们，并把它们都放在命令前面。 +在 Bash 中，要为单个命令设置多个环境变量，只需用空格分隔它们，并把它们都放在命令前面。 /// @@ -172,11 +196,11 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p /// -Pydantic 支持使用一个外部库来从这类文件中读取。你可以在 [Pydantic Settings：Dotenv（.env）支持](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support) 中阅读更多信息。 +Pydantic 支持使用一个外部库来从这类文件中读取。你可以在 [Pydantic Settings：Dotenv（.env）支持](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#dotenv-env-support) 中阅读更多信息。 /// tip | 提示 -要使其工作，你需要执行 `pip install python-dotenv`。 +要使其工作，请使用 `uv add python-dotenv` 将 `python-dotenv` 添加到你的项目。 /// @@ -197,7 +221,7 @@ APP_NAME="ChimichangApp" /// tip | 提示 -`model_config` 属性仅用于 Pydantic 配置。你可以在 [Pydantic：概念：配置](https://docs.pydantic.dev/latest/concepts/config/) 中阅读更多信息。 +`model_config` 属性仅用于 Pydantic 配置。你可以在 [Pydantic：概念：配置](https://pydantic.dev/docs/validation/latest/concepts/config/) 中阅读更多信息。 /// diff --git a/docs/zh/docs/advanced/sub-applications.md b/docs/zh/docs/advanced/sub-applications.md index b023040..51e8f87 100644 --- a/docs/zh/docs/advanced/sub-applications.md +++ b/docs/zh/docs/advanced/sub-applications.md @@ -1,6 +1,6 @@ # 子应用 - 挂载 { #sub-applications-mounts } -如果需要两个独立的 FastAPI 应用，拥有各自独立的 OpenAPI 与文档，则需设置一个主应用，并**挂载**一个（或多个）子应用。 +如果需要两个独立的 FastAPI 应用，拥有各自独立的 OpenAPI 与文档 UI，则需设置一个主应用，并**挂载**一个（或多个）子应用。 ## 挂载 **FastAPI** 应用 { #mounting-a-fastapi-application } @@ -35,7 +35,7 @@
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/zh/docs/advanced/templates.md b/docs/zh/docs/advanced/templates.md index 952f438..8535c24 100644 --- a/docs/zh/docs/advanced/templates.md +++ b/docs/zh/docs/advanced/templates.md @@ -1,19 +1,19 @@ # 模板 { #templates } -**FastAPI** 支持多种模板引擎。 +你可以在 **FastAPI** 中使用任何你想用的模板引擎。 -Flask 等工具使用的 Jinja2 是最用的模板引擎。 +常见选择是 Jinja2，它也是 Flask 和其他工具使用的模板引擎。 -在 Starlette 的支持下，**FastAPI** 应用可以直接使用工具轻易地配置 Jinja2。 +有一些工具可以轻松配置它，你可以直接在 **FastAPI** 应用中使用（由 Starlette 提供）。 ## 安装依赖项 { #install-dependencies } -确保你创建一个[虚拟环境](../virtual-environments.md)，激活它，并安装 `jinja2`： +将 `jinja2` 添加到你的项目中：
```console -$ pip install jinja2 +$ uv add jinja2 ---> 100% ``` @@ -22,37 +22,38 @@ $ pip install jinja2 ## 使用 `Jinja2Templates` { #using-jinja2templates } -* 导入 `Jinja2Templates` -* 创建可复用的 `templates` 对象 -* 在返回模板的*路径操作*中声明 `Request` 参数 -* 使用 `templates` 渲染并返回 `TemplateResponse`，传递模板的名称、request 对象以及一个包含多个键值对（用于 Jinja2 模板）的 "context" 字典。 +* 导入 `Jinja2Templates`。 +* 创建可复用的 `templates` 对象。 +* 在返回模板的*路径操作*中声明 `Request` 参数。 +* 使用你创建的 `templates` 渲染并返回 `TemplateResponse`，传递模板的名称、请求对象以及一个包含多个键值对（用于 Jinja2 模板）的 "context" 字典。 {* ../../docs_src/templates/tutorial001_py310.py hl[4,11,15:18] *} /// note | 注意 在 FastAPI 0.108.0，Starlette 0.29.0 之前，`name` 是第一个参数。 -并且，在此之前，`request` 对象是作为 context 的一部分以键值对的形式传递的。 + +并且，在此之前的旧版本中，`request` 对象是作为 Jinja2 的 context 中的键值对的一部分传递的。 /// /// tip | 提示 -通过声明 `response_class=HTMLResponse`，API 文档就能识别响应的对象是 HTML。 +通过声明 `response_class=HTMLResponse`，文档 UI 就能知道响应会是 HTML。 /// /// note | 技术细节 -您还可以使用 `from starlette.templating import Jinja2Templates`。 +你还可以使用 `from starlette.templating import Jinja2Templates`。 -**FastAPI** 的 `fastapi.templating` 只是为开发者提供的快捷方式。实际上，绝大多数可用响应都直接继承自 Starlette。`Request` 与 `StaticFiles` 也一样。 +**FastAPI** 将同一个 `starlette.templating` 作为 `fastapi.templating` 提供，只是为了方便开发者使用。但绝大多数可用响应都直接来自 Starlette。`Request` 和 `StaticFiles` 也一样。 /// ## 编写模板 { #writing-templates } -编写模板 `templates/item.html`，代码如下： +然后你可以在 `templates/item.html` 编写一个模板，例如： ```jinja hl_lines="7" {!../../docs_src/templates/templates/item.html!} @@ -60,7 +61,7 @@ $ pip install jinja2 ### 模板上下文值 { #template-context-values } -在包含如下语句的html中: +在包含如下语句的 HTML 中： {% raw %} @@ -70,13 +71,13 @@ Item ID: {{ id }} {% endraw %} -...这将显示你从 "context" 字典传递的 `id`: +...它会显示你传入的 "context" `dict` 中取得的 `id`： ```Python {"id": id} ``` -例如。当 ID 为 `42` 时, 会渲染成: +例如，当 ID 为 `42` 时，会渲染成： ```html Item ID: 42 @@ -84,9 +85,9 @@ Item ID: 42 ### 模板 `url_for` 参数 { #template-url-for-arguments } -你还可以在模板内使用 `url_for()`，其参数与*路径操作函数*的参数相同。 +你还可以在模板内使用 `url_for()`，其参数与*路径操作函数*使用的参数相同。 -所以，该部分: +所以，该部分： {% raw %} @@ -96,9 +97,9 @@ Item ID: 42 {% endraw %} -...将生成一个与处理*路径操作函数* `read_item(id=id)`的 URL 相同的链接 +...将生成一个链接，指向由*路径操作函数* `read_item(id=id)` 处理的同一个 URL。 -例如。当 ID 为 `42` 时, 会渲染成: +例如，当 ID 为 `42` 时，会渲染成： ```html @@ -106,20 +107,20 @@ Item ID: 42 ## 模板与静态文件 { #templates-and-static-files } -你还可以在模板内部将 `url_for()` 用于静态文件，例如你挂载的 `name="static"` 的 `StaticFiles`。 +你还可以在模板内部使用 `url_for()`，例如将它与你挂载的 `name="static"` 的 `StaticFiles` 一起使用。 ```jinja hl_lines="4" {!../../docs_src/templates/templates/item.html!} ``` -本例中，它将链接到 `static/styles.css` 中的 CSS 文件： +在这个示例中，它会通过以下内容链接到 `static/styles.css` 中的 CSS 文件： ```CSS hl_lines="4" {!../../docs_src/templates/static/styles.css!} ``` -因为使用了 `StaticFiles`，**FastAPI** 应用会自动提供位于 URL `/static/styles.css` 的 CSS 文件。 +而且因为你使用了 `StaticFiles`，该 CSS 文件会由你的 **FastAPI** 应用在 URL `/static/styles.css` 自动提供。 ## 更多说明 { #more-details } -包括如何测试模板在内的更多详情，请查看 [Starlette 的模板文档](https://www.starlette.dev/templates/)。 +包括如何测试模板在内的更多详情，请查看 [Starlette 的模板文档](https://starlette.dev/templates/)。 diff --git a/docs/zh/docs/advanced/testing-events.md b/docs/zh/docs/advanced/testing-events.md index 90cbbda..3135115 100644 --- a/docs/zh/docs/advanced/testing-events.md +++ b/docs/zh/docs/advanced/testing-events.md @@ -4,7 +4,8 @@ {* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *} -你可以在[官方 Starlette 文档站点的“在测试中运行 lifespan”](https://www.starlette.dev/lifespan/#running-lifespan-in-tests)阅读更多细节。 + +你可以阅读更多关于[“官方 Starlette 文档站点中的在测试中运行 lifespan。”](https://starlette.dev/lifespan/#running-lifespan-in-tests)的细节。 对于已弃用的 `startup` 和 `shutdown` 事件，可以按如下方式使用 `TestClient`： diff --git a/docs/zh/docs/advanced/testing-websockets.md b/docs/zh/docs/advanced/testing-websockets.md index 6d2e4b0..15302ef 100644 --- a/docs/zh/docs/advanced/testing-websockets.md +++ b/docs/zh/docs/advanced/testing-websockets.md @@ -8,6 +8,6 @@ /// note | 注意 -更多细节请查看 Starlette 的文档：[测试 WebSockets](https://www.starlette.dev/testclient/#testing-websocket-sessions)。 +更多细节请查看 Starlette 的文档：[测试 WebSockets](https://starlette.dev/testclient/#testing-websocket-sessions)。 /// diff --git a/docs/zh/docs/advanced/using-request-directly.md b/docs/zh/docs/advanced/using-request-directly.md index 519443d..fc9b9c8 100644 --- a/docs/zh/docs/advanced/using-request-directly.md +++ b/docs/zh/docs/advanced/using-request-directly.md @@ -15,7 +15,7 @@ ## `Request` 对象的细节 { #details-about-the-request-object } -实际上，**FastAPI** 的底层是 **Starlette**，**FastAPI** 只不过是在 **Starlette** 顶层提供了一些工具，所以能直接使用 Starlette 的 [`Request`](https://www.starlette.dev/requests/) 对象。 +实际上，**FastAPI** 的底层是 **Starlette**，**FastAPI** 只不过是在 **Starlette** 顶层提供了一些工具，所以能直接使用 Starlette 的 [`Request`](https://starlette.dev/requests/) 对象。 但直接从 `Request` 对象提取数据时（例如，读取请求体），这些数据不会被 **FastAPI** 验证、转换或文档化（使用 OpenAPI，为自动的 API 用户界面）。 @@ -25,7 +25,7 @@ ## 直接使用 `Request` 对象 { #use-the-request-object-directly } -假设要在*路径操作函数*中获取客户端 IP 地址和主机。 +假设要在*路径操作函数*中获取客户端 IP 地址/主机。 此时，需要直接访问请求。 @@ -39,17 +39,17 @@ 因此，能够提取、验证路径参数、并转换为指定类型，还可以用 OpenAPI 注释。 -同样，您也可以正常声明其它参数，而且还可以提取 `Request`。 +同样，你也可以正常声明其它参数，而且还可以提取 `Request`。 /// ## `Request` 文档 { #request-documentation } -你可以在[Starlette 官方文档站点的 `Request` 对象](https://www.starlette.dev/requests/)中阅读更多细节。 +你可以在[Starlette 官方文档站点的 `Request` 对象](https://starlette.dev/requests/)中阅读更多细节。 /// note | 技术细节 -您也可以使用 `from starlette.requests import Request`。 +你也可以使用 `from starlette.requests import Request`。 **FastAPI** 直接提供它只是为了方便开发者，但它直接来自 Starlette。 diff --git a/docs/zh/docs/advanced/websockets.md b/docs/zh/docs/advanced/websockets.md index 7950f90..0b8498f 100644 --- a/docs/zh/docs/advanced/websockets.md +++ b/docs/zh/docs/advanced/websockets.md @@ -4,12 +4,12 @@ ## 安装 `websockets` { #install-websockets } -请确保您创建一个[虚拟环境](../virtual-environments.md)、激活它，并安装 `websockets`（一个让使用“WebSocket”协议更容易的 Python 库）： +将 `websockets`（一个让使用“WebSocket”协议更容易的 Python 库）添加到你的项目中：
```console -$ pip install websockets +$ uv add websockets ---> 100% ``` @@ -64,12 +64,12 @@ $ pip install websockets ## 尝试一下 { #try-it } -将代码放在 `main.py`，然后运行你的应用程序： +将代码放在文件 `main.py` 中，然后运行你的应用程序：
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -126,7 +126,7 @@ $ fastapi dev
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -182,5 +182,5 @@ Client #1596980209979 left the chat 要了解更多选项，请查看 Starlette 的文档： -* [`WebSocket` 类](https://www.starlette.dev/websockets/)。 -* [基于类的 WebSocket 处理](https://www.starlette.dev/endpoints/#websocketendpoint)。 +* [`WebSocket` 类](https://starlette.dev/websockets/)。 +* [基于类的 WebSocket 处理](https://starlette.dev/endpoints/#websocketendpoint)。 diff --git a/docs/zh/docs/advanced/wsgi.md b/docs/zh/docs/advanced/wsgi.md index eb83a09..5d675f5 100644 --- a/docs/zh/docs/advanced/wsgi.md +++ b/docs/zh/docs/advanced/wsgi.md @@ -9,7 +9,7 @@ /// note | 注意 -需要安装 `a2wsgi`，例如使用 `pip install a2wsgi`。 +这需要将 `a2wsgi` 添加到你的项目中，例如使用 `uv add a2wsgi`。 /// diff --git a/docs/zh/docs/alternatives.md b/docs/zh/docs/alternatives.md index 20de25c..aa117b0 100644 --- a/docs/zh/docs/alternatives.md +++ b/docs/zh/docs/alternatives.md @@ -24,7 +24,7 @@ ### [Django REST Framework](https://www.django-rest-framework.org/) { #django-rest-framework } -Django REST framework 作为一个灵活工具箱而创建，用于在底层使用 Django 构建 Web API，从而增强其 API 能力。 +Django REST Framework 作为一个灵活工具箱而创建，用于在底层使用 Django 构建 Web API，从而增强其 API 能力。 它被包括 Mozilla、Red Hat、Eventbrite 在内的许多公司使用。 @@ -125,7 +125,7 @@ def read_url(): 并集成基于标准的用户界面工具： * [Swagger UI](https://github.com/swagger-api/swagger-ui) -* [ReDoc](https://github.com/Rebilly/ReDoc) +* [ReDoc](https://github.com/Redocly/redoc) 选择这两者是因为它们相当流行且稳定；但稍作搜索，你就能找到数十种 OpenAPI 的替代用户界面（都可以与 **FastAPI** 搭配使用）。 @@ -237,7 +237,7 @@ Flask-apispec 由与 Marshmallow 相同的开发者创建。 /// -### [NestJS](https://nestjs.com/)（以及 [Angular](https://angular.io/)） { #nestjs-and-angular } +### [NestJS](https://nestjs.com/)（以及 [Angular](https://angular.dev/)） { #nestjs-and-angular } 这甚至不是 Python。NestJS 是一个 JavaScript（TypeScript）的 NodeJS 框架，受 Angular 启发。 @@ -335,7 +335,7 @@ Hug 是最早使用 Python 类型提示来声明 API 参数类型的框架之一 /// note | 注意 -Hug 由 Timothy Crosley 创建，他也是 [`isort`](https://github.com/timothycrosley/isort) 的作者，这是一个能自动排序 Python 文件中导入的优秀工具。 +Hug 由 Timothy Crosley 创建，他也是 [`isort`](https://github.com/PyCQA/isort) 的作者，这是一个能自动排序 Python 文件中导入的优秀工具。 /// @@ -399,7 +399,7 @@ APIStar 由 Tom Christie 创建。他还创建了： ## **FastAPI** 所使用的组件 { #used-by-fastapi } -### [Pydantic](https://docs.pydantic.dev/) { #pydantic } +### [Pydantic](https://pydantic.dev/docs/) { #pydantic } Pydantic 是一个基于 Python 类型提示来定义数据校验、序列化与文档（使用 JSON Schema）的库。 @@ -415,7 +415,7 @@ Pydantic 是一个基于 Python 类型提示来定义数据校验、序列化与 /// -### [Starlette](https://www.starlette.dev/) { #starlette } +### [Starlette](https://starlette.dev/) { #starlette } Starlette 是一个轻量级的 ASGI 框架/工具集，非常适合构建高性能的 asyncio 服务。 @@ -460,7 +460,7 @@ ASGI 是由 Django 核心团队成员推动的新“标准”。它尚不是正 /// -### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn } +### [Uvicorn](https://uvicorn.dev) { #uvicorn } Uvicorn 是一个基于 uvloop 与 httptools 构建的极速 ASGI 服务器。 diff --git a/docs/zh/docs/deployment/docker.md b/docs/zh/docs/deployment/docker.md index 5e3919b..1702af0 100644 --- a/docs/zh/docs/deployment/docker.md +++ b/docs/zh/docs/deployment/docker.md @@ -106,36 +106,32 @@ Docker 一直是创建和管理**容器镜像**与**容器**的主要工具之 ### 包依赖 { #package-requirements } -通常你会把应用的**包依赖**放在某个文件里。 +当你使用 `uv` 管理项目时，它的直接依赖会声明在 `pyproject.toml` 中，而精确解析出的版本会存储在 `uv.lock` 中。 -这主要取决于你用来**安装**这些依赖的工具。 - -最常见的方式是使用 `requirements.txt` 文件，每行一个包名及其版本范围。 - -当然，你也可以参考你在[关于 FastAPI 版本](versions.md)中读到的思路来设置版本范围。 - -例如，你的 `requirements.txt` 可能是： - -``` -fastapi[standard]>=0.113.0,<0.114.0 -pydantic>=2.7.0,<3.0.0 -``` - -通常你会用 `pip` 安装这些依赖，例如： +你可以用以下命令添加应用所需的包：
```console -$ pip install -r requirements.txt +$ uv add "fastapi[standard]" pydantic ---> 100% -Successfully installed fastapi pydantic ```
/// note | 注意 -还有其他格式和工具可以定义并安装包依赖。 +下面的 Dockerfile 在容器内使用 `pip`。你可以将 uv 项目中锁定的依赖导出为它所期望的 `requirements.txt` 格式： + +
+ +```console +$ uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt +``` + +
+ +生成的 `requirements.txt` 是用于容器构建的导出文件。继续使用 `uv add` 管理依赖，并在 `uv.lock` 变化时重新生成它。 /// @@ -373,7 +369,7 @@ $ docker run -d --name mycontainer -p 80:80 myimage 你还可以访问 [http://192.168.99.100/redoc](http://192.168.99.100/redoc) 或 [http://127.0.0.1/redoc](http://127.0.0.1/redoc)（或其他等价地址，取决于你的 Docker 主机）。 -你将看到备选的自动文档（由 [ReDoc](https://github.com/Rebilly/ReDoc) 提供）： +你将看到备选的自动文档（由 [ReDoc](https://github.com/Redocly/redoc) 提供）： ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) diff --git a/docs/zh/docs/deployment/fastapicloud.md b/docs/zh/docs/deployment/fastapicloud.md index 9140e30..b075f06 100644 --- a/docs/zh/docs/deployment/fastapicloud.md +++ b/docs/zh/docs/deployment/fastapicloud.md @@ -5,7 +5,7 @@
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... diff --git a/docs/zh/docs/deployment/manually.md b/docs/zh/docs/deployment/manually.md index ee468f4..301809f 100644 --- a/docs/zh/docs/deployment/manually.md +++ b/docs/zh/docs/deployment/manually.md @@ -52,7 +52,7 @@ FastAPI 使用了一种用于构建 Python Web 框架和服务器的标准，称 除此之外，还有其他一些可选的 ASGI 服务器，例如： -* [Uvicorn](https://www.uvicorn.dev/): 高性能 ASGI 服务器。 +* [Uvicorn](https://uvicorn.dev): 高性能 ASGI 服务器。 * [Hypercorn](https://hypercorn.readthedocs.io/): 与 HTTP/2 和 Trio 等兼容的 ASGI 服务器。 * [Daphne](https://github.com/django/daphne): 为 Django Channels 构建的 ASGI 服务器。 * [Granian](https://github.com/emmett-framework/granian): 基于 Rust 的 HTTP 服务器，专为 Python 应用设计。 @@ -73,14 +73,14 @@ FastAPI 使用了一种用于构建 Python Web 框架和服务器的标准，称 不过，你也可以手动安装 ASGI 服务器。 -请确保你创建并激活一个[虚拟环境](../virtual-environments.md)，然后再安装服务器应用程序。 +将服务器应用程序添加到你的项目中。 -例如，要安装 Uvicorn，可以运行以下命令： +例如，要安装 Uvicorn：
```console -$ pip install "uvicorn[standard]" +$ uv add "uvicorn[standard]" ---> 100% ``` @@ -91,11 +91,11 @@ $ pip install "uvicorn[standard]" /// tip | 提示 -通过添加 `standard` 选项，Uvicorn 将安装并使用一些推荐的额外依赖项。 +通过添加 `standard`，Uvicorn 将安装并使用一些推荐的额外依赖项。 其中包括 `uvloop`，这是 `asyncio` 的高性能替代方案，能够显著提升并发性能。 -当你使用 `pip install "fastapi[standard]"` 安装 FastAPI 时，实际上也会安装 `uvicorn[standard]`。 +当你使用类似 `uv add "fastapi[standard]"` 的命令添加 FastAPI 时，也已经会同时得到 `uvicorn[standard]`。 /// @@ -106,7 +106,7 @@ $ pip install "uvicorn[standard]"
```console -$ uvicorn main:app --host 0.0.0.0 --port 80 +$ uv run uvicorn main:app --host 0.0.0.0 --port 80 INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) ``` diff --git a/docs/zh/docs/deployment/server-workers.md b/docs/zh/docs/deployment/server-workers.md index e20d9ef..452f2e2 100644 --- a/docs/zh/docs/deployment/server-workers.md +++ b/docs/zh/docs/deployment/server-workers.md @@ -86,7 +86,7 @@ $ fastapi run --workers 4 ```console -$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 +$ uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit) INFO: Started parent process [27365] INFO: Started server process [27368] diff --git a/docs/zh/docs/environment-variables.md b/docs/zh/docs/environment-variables.md index be6869e..5ec4937 100644 --- a/docs/zh/docs/environment-variables.md +++ b/docs/zh/docs/environment-variables.md @@ -1,299 +1,11 @@ # 环境变量 { #environment-variables } +**环境变量**（也称为 **env var**）是一个独立于 Python 代码之外、存在于操作系统中的值，可以被你的应用程序和其他程序读取。 -/// tip | 提示 +FastAPI 应用程序通常使用环境变量进行配置，例如数据库 URL、电子邮件凭据和密钥。 -如果你已经知道什么是“环境变量”并且知道如何使用它们，你可以放心跳过这一部分。 +你将在[设置和环境变量](advanced/settings.md)中了解如何将它们用于应用程序配置。 -/// +## 了解更多 { #learn-more } -环境变量（也称为“**env var**”）是一个独立于 Python 代码**之外**的变量，它存在于**操作系统**中，可以被你的 Python 代码（或其他程序）读取。 - -环境变量对于处理应用程序**设置**、作为 Python **安装**的一部分等方面非常有用。 - -## 创建和使用环境变量 { #create-and-use-env-vars } - -你在 **shell（终端）**中就可以**创建**和使用环境变量，并不需要用到 Python： - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// 你可以使用以下命令创建一个名为 MY_NAME 的环境变量 -$ export MY_NAME="Wade Wilson" - -// 然后，你可以在其他程序中使用它，例如 -$ echo "Hello $MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// 创建一个名为 MY_NAME 的环境变量 -$ $Env:MY_NAME = "Wade Wilson" - -// 在其他程序中使用它，例如 -$ echo "Hello $Env:MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -## 在 Python 中读取环境变量 { #read-env-vars-in-python } - -你也可以在 Python **之外**的终端中创建环境变量（或使用任何其他方法），然后在 Python 中**读取**它们。 - -例如，你可以创建一个名为 `main.py` 的文件，其中包含以下内容： - -```Python hl_lines="3" -import os - -name = os.getenv("MY_NAME", "World") -print(f"Hello {name} from Python") -``` - -/// tip | 提示 - -第二个参数是 [`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) 的默认返回值。 - -如果没有提供，默认值为 `None`，这里我们提供 `"World"` 作为默认值。 - -/// - -然后你可以调用这个 Python 程序： - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// 这里我们还没有设置环境变量 -$ python main.py - -// 因为我们没有设置环境变量，所以我们得到的是默认值 - -Hello World from Python - -// 但是如果我们事先创建过一个环境变量 -$ export MY_NAME="Wade Wilson" - -// 然后再次调用程序 -$ python main.py - -// 现在就可以读取到环境变量了 - -Hello Wade Wilson from Python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// 这里我们还没有设置环境变量 -$ python main.py - -// 因为我们没有设置环境变量，所以我们得到的是默认值 - -Hello World from Python - -// 但是如果我们事先创建过一个环境变量 -$ $Env:MY_NAME = "Wade Wilson" - -// 然后再次调用程序 -$ python main.py - -// 现在就可以读取到环境变量了 - -Hello Wade Wilson from Python -``` - -
- -//// - -由于环境变量可以在代码之外设置、但可以被代码读取，并且不必与其他文件一起存储（提交到 `git`），因此通常用于配置或**设置**。 - -你还可以为**特定的程序调用**创建特定的环境变量，该环境变量仅对该程序可用，且仅在其运行期间有效。 - -要实现这一点，只需在同一行内、程序本身之前创建它： - -
- -```console -// 在这个程序调用的同一行中创建一个名为 MY_NAME 的环境变量 -$ MY_NAME="Wade Wilson" python main.py - -// 现在就可以读取到环境变量了 - -Hello Wade Wilson from Python - -// 在此之后这个环境变量将不会依然存在 -$ python main.py - -Hello World from Python -``` - -
- -/// tip | 提示 - -你可以在 [The Twelve-Factor App: 配置](https://12factor.net/config) 中了解更多信息。 - -/// - -## 类型和验证 { #types-and-validation } - -这些环境变量只能处理**文本字符串**，因为它们是处于 Python 范畴之外的，必须与其他程序和操作系统的其余部分兼容（甚至与不同的操作系统兼容，如 Linux、Windows、macOS）。 - -这意味着从环境变量中读取的**任何值**在 Python 中都将是一个 `str`，任何类型转换或验证都必须在代码中完成。 - -你将在[高级用户指南 - 设置和环境变量](./advanced/settings.md)中了解更多关于使用环境变量处理**应用程序设置**的信息。 - -## `PATH` 环境变量 { #path-environment-variable } - -有一个**特殊的**环境变量称为 **`PATH`**，操作系统（Linux、macOS、Windows）用它来查找要运行的程序。 - -`PATH` 变量的值是一个长字符串，由 Linux 和 macOS 上的冒号 `:` 分隔的目录组成，而在 Windows 上则是由分号 `;` 分隔的。 - -例如，`PATH` 环境变量可能如下所示： - -//// tab | Linux, macOS - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -这意味着系统应该在以下目录中查找程序： - -- `/usr/local/bin` -- `/usr/bin` -- `/bin` -- `/usr/sbin` -- `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32 -``` - -这意味着系统应该在以下目录中查找程序： - -- `C:\Program Files\Python312\Scripts` -- `C:\Program Files\Python312` -- `C:\Windows\System32` - -//// - -当你在终端中输入一个**命令**时，操作系统会在 `PATH` 环境变量中列出的**每个目录**中**查找**程序。 - -例如，当你在终端中输入 `python` 时，操作系统会在该列表中的**第一个目录**中查找名为 `python` 的程序。 - -如果找到了，那么操作系统将**使用它**；否则，操作系统会继续在**其他目录**中查找。 - -### 安装 Python 和更新 `PATH` { #installing-python-and-updating-the-path } - -安装 Python 时，可能会询问你是否要更新 `PATH` 环境变量。 - -//// tab | Linux, macOS - -假设你安装 Python 并最终将其安装在了目录 `/opt/custompython/bin` 中。 - -如果你同意更新 `PATH` 环境变量，那么安装程序将会将 `/opt/custompython/bin` 添加到 `PATH` 环境变量中。 - -它看起来大概会像这样： - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin -``` - -如此一来，当你在终端中输入 `python` 时，系统会在 `/opt/custompython/bin` 中找到 Python 程序（最后一个目录）并使用它。 - -//// - -//// tab | Windows - -假设你安装 Python 并最终将其安装在了目录 `C:\opt\custompython\bin` 中。 - -如果你同意更新 `PATH` 环境变量，那么安装程序将会将 `C:\opt\custompython\bin` 添加到 `PATH` 环境变量中。 - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin -``` - -如此一来，当你在终端中输入 `python` 时，系统会在 `C:\opt\custompython\bin` 中找到 Python 程序（最后一个目录）并使用它。 - -//// - -因此，如果你输入： - -
- -```console -$ python -``` - -
- -//// tab | Linux, macOS - -系统会在 `/opt/custompython/bin` 中**找到** `python` 程序并运行它。 - -这和输入以下命令大致等价： - -
- -```console -$ /opt/custompython/bin/python -``` - -
- -//// - -//// tab | Windows - -系统会在 `C:\opt\custompython\bin\python` 中**找到** `python` 程序并运行它。 - -这和输入以下命令大致等价： - -
- -```console -$ C:\opt\custompython\bin\python -``` - -
- -//// - -当学习[虚拟环境](virtual-environments.md)时，这些信息将会很有用。 - -## 结论 { #conclusion } - -通过这个教程，你应该对**环境变量**是什么以及如何在 Python 中使用它们有了基本的了解。 - -你也可以在[环境变量 - 维基百科](https://en.wikipedia.org/wiki/Environment_variable)中了解更多关于它们的信息。 - -在许多情况下，环境变量的用途和适用性并不是很明显。但是在开发过程中，它们会在许多不同的场景中出现，因此了解它们是很有必要的。 - -例如，你将在下一节关于[虚拟环境](virtual-environments.md)中需要这些信息。 +阅读[环境变量指南](https://tiangolo.com/guides/environment-variables/)，了解详细的跨平台说明，包括如何创建和读取环境变量，以及 `PATH` 环境变量的工作方式。 diff --git a/docs/zh/docs/fastapi-cli.md b/docs/zh/docs/fastapi-cli.md index ff05e1b..77aac00 100644 --- a/docs/zh/docs/fastapi-cli.md +++ b/docs/zh/docs/fastapi-cli.md @@ -2,7 +2,7 @@ **FastAPI CLI** 是一个命令行程序，你可以用它来部署和运行你的 FastAPI 应用、管理 FastAPI 项目，等等。 -当你安装 FastAPI（例如使用 `pip install "fastapi[standard]"`）时，会附带一个可以在终端中运行的命令行程序。 +当你将 FastAPI 添加到你的项目中（例如使用 `uv add "fastapi[standard]"`）时，会附带一个可以在终端中运行的命令行程序。 要在开发环境中运行你的 FastAPI 应用，可以使用 `fastapi dev` 命令： @@ -52,7 +52,7 @@ $ fastapi dev /// -在内部，**FastAPI CLI** 使用 [Uvicorn](https://www.uvicorn.dev)，这是一个高性能、适用于生产环境的 ASGI 服务器。😎 +在内部，**FastAPI CLI** 使用 [Uvicorn](https://uvicorn.dev)，这是一个高性能、适用于生产环境的 ASGI 服务器。😎 `fastapi` CLI 会尝试自动检测要运行的 FastAPI 应用，默认假设它是文件 `main.py` 中名为 `app` 的对象（或少数其他变体）。 @@ -100,28 +100,32 @@ from backend.main import app 你也可以把文件路径传给 `fastapi dev` 命令，它会猜测要使用的 FastAPI 应用对象： ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` 或者，你也可以给 `fastapi dev` 命令传入 `--entrypoint` 选项： ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` -但每次运行 `fastapi` 命令都需要记得传入正确的路径或 entrypoint。 +但每次运行 `fastapi` 命令都需要记得传入正确的路径\entrypoint。 另外，其他工具可能找不到它，例如 [VS Code 扩展](editor-support.md) 或 [FastAPI Cloud](https://fastapicloud.com)，因此推荐在 `pyproject.toml` 中使用 `entrypoint`。 ## `fastapi dev` { #fastapi-dev } -当你运行 `fastapi dev` 时，它将以开发模式运行。 +运行 `fastapi dev` 会启动开发模式。 默认情况下，它会启用**自动重载**，因此当你更改代码时，它会自动重新加载服务器。该功能是资源密集型的，且相较不启用时更不稳定，因此你应该仅在开发环境下使用它。它还会监听 IP 地址 `127.0.0.1`，这是你的机器仅与自身通信的 IP（`localhost`）。 +在导入你的应用之前，`fastapi dev` 会将 `FASTAPI_ENV` 环境变量设置为 `development`。如果 `FASTAPI_ENV` 已经设置，则会保留其现有值。这让应用启动代码可以选择适合开发的行为，同时允许你提供应用特定的环境，例如 `staging`。 + +约定的 `FASTAPI_ENV` 值是 `development` 和 `production`。`fastapi run` 目前会保持 `FASTAPI_ENV` 不变，因此如果你的应用需要检测生产模式，请显式设置它。 + ## `fastapi run` { #fastapi-run } -当你运行 `fastapi run` 时，它默认以生产环境模式运行。 +执行 `fastapi run` 会以生产模式启动 FastAPI。 默认情况下，**自动重载是禁用的**。它将监听 IP 地址 `0.0.0.0`，即所有可用的 IP 地址，这样任何能够与该机器通信的人都可以公开访问它。这通常是你在生产环境中运行它的方式，例如在容器中运行。 diff --git a/docs/zh/docs/features.md b/docs/zh/docs/features.md index 1405bee..878be5d 100644 --- a/docs/zh/docs/features.md +++ b/docs/zh/docs/features.md @@ -19,7 +19,7 @@ ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* 另外的 API 文档：[**ReDoc**](https://github.com/Rebilly/ReDoc)。 +* 另外的 API 文档：[**ReDoc**](https://github.com/Redocly/redoc)。 ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) @@ -160,7 +160,7 @@ FastAPI 有一个使用非常简单，但是非常强大的ORMs、ODMs。 diff --git a/docs/zh/docs/help-fastapi.md b/docs/zh/docs/help-fastapi.md index 1692d07..fecfb1b 100644 --- a/docs/zh/docs/help-fastapi.md +++ b/docs/zh/docs/help-fastapi.md @@ -45,20 +45,6 @@ * [@tiangolo.com 在 **Bluesky** 上](https://bsky.app/profile/tiangolo.com) * [@tiangolo 在 **LinkedIn** 上](https://www.linkedin.com/in/tiangolo/)。 -## 在 GitHub 上帮别人解答问题 { #help-others-with-questions-in-github } - -你可以尝试在 [GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered) 中帮助他人解答问题。 - -很多情况下，你也许已经知道这些问题的答案了。🤓 - -如果你帮助了很多人解答问题，你会成为官方的 [FastAPI 专家](fastapi-people.md#fastapi-experts)。🎉 - -只要记住，最重要的是：尽量友善。🤗 - -### 如何提供帮助 { #how-to-help } - -请参照这里的[帮助指南](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github)。 - ## 提问 { #ask-questions } 你可以在 GitHub 资源库中[创建一个新问题（Question）](https://github.com/fastapi/fastapi/discussions/new?category=questions)，例如： @@ -68,7 +54,7 @@ ## 加入聊天 { #join-the-chat } -加入 👥 [Discord 聊天服务器](https://discord.gg/VQjSZaeJmf) 👥，和 FastAPI 社区的小伙伴们一起交流。 +加入 👥 [Discord 聊天服务器](https://discord.com/invite/VQjSZaeJmf) 👥，和 FastAPI 社区的小伙伴们一起交流。 /// tip | 提示 @@ -85,3 +71,9 @@ 在 GitHub 中，模板会引导你写出恰当的问题，从而更容易获得好的回答，甚至在提问之前就能自己解决。 聊天系统中的对话也不像 GitHub 那样容易搜索，它们会淹没消失。 + +## 试用 FastAPI Cloud { #try-fastapi-cloud } + +FastAPI 及其小伙伴的主要资金来源是 [**FastAPI Cloud**](https://fastapicloud.com)，这是一个用简单快速的方式部署 FastAPI 应用的平台，只需一个命令：`fastapi deploy`。 + +FastAPI Cloud 由 FastAPI 背后的同一团队构建。你可以试用它，并考虑在你的项目中使用。 diff --git a/docs/zh/docs/history-design-future.md b/docs/zh/docs/history-design-future.md index 429eb8d..3f400be 100644 --- a/docs/zh/docs/history-design-future.md +++ b/docs/zh/docs/history-design-future.md @@ -17,6 +17,7 @@ 正如[备选方案](alternatives.md)一章所述：
+ 没有大家之前所做的工作，**FastAPI** 就不会存在。 以前创建的这些工具为它的出现提供了灵感。 @@ -24,6 +25,7 @@ 在那几年中，我一直回避创建新的框架。首先，我尝试使用各种框架、插件、工具解决 **FastAPI** 现在的功能。 但到了一定程度之后，我别无选择，只能从之前的工具中汲取最优思路，并以尽量好的方式把这些思路整合在一起，使用之前甚至是不支持的语言特性（Python 3.6+ 的类型提示），从而创建一个能满足我所有需求的框架。 +
## 调研 { #investigation } @@ -52,11 +54,11 @@ ## 需求项 { #requirements } -经过测试多种备选方案，我最终决定使用 [**Pydantic**](https://docs.pydantic.dev/)，并充分利用它的优势。 +经过测试多种备选方案，我最终决定使用 [**Pydantic**](https://pydantic.dev/docs/)，并充分利用它的优势。 我甚至为它做了不少贡献，让它完美兼容了 JSON Schema，支持多种方式定义约束声明，并基于多个编辑器，改进了它对编辑器支持（类型检查、自动补全）。 -在开发期间，我还为 [**Starlette**](https://www.starlette.dev/) 做了不少贡献，这是另一个关键需求项。 +在开发期间，我还为 [**Starlette**](https://starlette.dev/) 做了不少贡献，这是另一个关键需求项。 ## 开发 { #development } diff --git a/docs/zh/docs/how-to/custom-request-and-route.md b/docs/zh/docs/how-to/custom-request-and-route.md index 4065818..a88813c 100644 --- a/docs/zh/docs/how-to/custom-request-and-route.md +++ b/docs/zh/docs/how-to/custom-request-and-route.md @@ -66,7 +66,7 @@ 创建一个新的 `Request` 实例需要这两样：`scope` 和 `receive`。 -想了解更多关于 `Request` 的信息，请查看 [Starlette 的 Request 文档](https://www.starlette.dev/requests/)。 +想了解更多关于 `Request` 的信息，请查看 [Starlette 的 Request 文档](https://starlette.dev/requests/)。 /// diff --git a/docs/zh/docs/how-to/extending-openapi.md b/docs/zh/docs/how-to/extending-openapi.md index 9b8d1c0..09bc9b1 100644 --- a/docs/zh/docs/how-to/extending-openapi.md +++ b/docs/zh/docs/how-to/extending-openapi.md @@ -45,7 +45,7 @@ 基于以上信息，你可以用同一个工具函数生成 OpenAPI 架构，并按需覆盖其中的各个部分。 -例如，让我们添加 [ReDoc 的 OpenAPI 扩展以包含自定义 Logo](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo)。 +例如，让我们添加 [ReDoc 的 OpenAPI 扩展以包含自定义 Logo](https://github.com/Redocly/redoc/blob/main/docs/redoc-vendor-extensions.md#x-logo)。 ### 常规 **FastAPI** { #normal-fastapi } diff --git a/docs/zh/docs/how-to/graphql.md b/docs/zh/docs/how-to/graphql.md index 31d15d3..a8f7c9b 100644 --- a/docs/zh/docs/how-to/graphql.md +++ b/docs/zh/docs/how-to/graphql.md @@ -21,7 +21,7 @@ * [Strawberry](https://strawberry.rocks/) 🍓 * 提供 [面向 FastAPI 的文档](https://strawberry.rocks/docs/integrations/fastapi) * [Ariadne](https://ariadnegraphql.org/) - * 提供 [面向 FastAPI 的文档](https://ariadnegraphql.org/docs/fastapi-integration) + * 提供 [面向 FastAPI 的文档](https://ariadnegraphql.org/server/Integrations/fastapi-integration) * [Tartiflette](https://tartiflette.io/) * 提供用于 ASGI 集成的 [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) * [Graphene](https://graphene-python.org/) diff --git a/docs/zh/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/zh/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index ecfdd02..de38913 100644 --- a/docs/zh/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/zh/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -24,7 +24,7 @@ FastAPI 0.128.0 也移除了对 `pydantic.v1` 的支持，因此最新版本的 ## 官方指南 { #official-guide } -Pydantic 有一份从 v1 迁移到 v2 的官方[迁移指南](https://docs.pydantic.dev/latest/migration/)。 +Pydantic 有一份从 v1 迁移到 v2 的官方[迁移指南](https://pydantic.dev/docs/validation/latest/get-started/migration/)。 其中包含变更内容、校验如何更准确更严格、可能的注意事项等。 @@ -80,7 +80,7 @@ Pydantic v2 以子模块 `pydantic.v1` 的形式包含了 Pydantic v1 的全部 ### 同一应用中同时使用 Pydantic v1 与 v2 { #pydantic-v1-and-v2-on-the-same-app } -Pydantic 不支持在一个 Pydantic v2 模型的字段中定义 Pydantic v1 模型，反之亦然。 +Pydantic **不支持**在一个 Pydantic v2 模型的字段中定义 Pydantic v1 模型，反之亦然。 ```mermaid graph TB @@ -120,7 +120,7 @@ graph TB style V2Field fill:#f9fff3 ``` -在某些情况下，甚至可以在 FastAPI 应用的同一个路径操作中同时使用 Pydantic v1 和 v2 模型： +在某些情况下，甚至可以在 FastAPI 应用的同一个 **路径操作** 中同时使用 Pydantic v1 和 v2 模型： {* ../../docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py hl[2:3,6,12,21:22] *} diff --git a/docs/zh/docs/index.md b/docs/zh/docs/index.md index 6b75291..74ca286 100644 --- a/docs/zh/docs/index.md +++ b/docs/zh/docs/index.md @@ -110,7 +110,7 @@ FastAPI 是一个用于构建 API 的现代、快速（高性能）的 Web 框
-## FastAPI 大会 { #fastapi-conf } - -[**FastAPI Conf '26**](https://fastapiconf.com) 将于 **2026 年 10 月 28 日** 在 **荷兰阿姆斯特丹** 举行。来自源头的 FastAPI 干货。🎤 - -FastAPI Conf '26 - 2026 年 10 月 28 日 - 荷兰阿姆斯特丹 - ## FastAPI 迷你纪录片 { #fastapi-mini-documentary } 在 2025 年末发布了一部 [FastAPI 迷你纪录片](https://www.youtube.com/watch?v=mpR8ngthqiE)，你可以在线观看： @@ -175,17 +169,17 @@ FastAPI 是一个用于构建 API 的现代、快速（高性能）的 Web 框 FastAPI 站在巨人的肩膀之上： -* [Starlette](https://www.starlette.dev/) 负责 Web 部分。 -* [Pydantic](https://docs.pydantic.dev/) 负责数据部分。 +* [Starlette](https://starlette.dev/) 负责 Web 部分。 +* [Pydantic](https://pydantic.dev/docs/) 负责数据部分。 ## 安装 { #installation } -创建并激活一个 [虚拟环境](https://fastapi.tiangolo.com/zh/virtual-environments/)，然后安装 FastAPI： +首先，[安装 `uv`](https://docs.astral.sh/uv/getting-started/installation/)，然后将 FastAPI 添加到你的项目中：
```console -$ pip install "fastapi[standard]" +$ uv add "fastapi[standard]" ---> 100% ``` @@ -194,6 +188,8 @@ $ pip install "fastapi[standard]" **注意**: 请确保把 `"fastapi[standard]"` 用引号包起来，以保证在所有终端中都能正常工作。 +如果你更喜欢使用 `pip`，请在虚拟环境中安装 `fastapi[standard]`。请参阅[安装指南](tutorial/#install-fastapi)了解替代步骤。 + ## 示例 { #example } ### 创建 { #create-it } @@ -250,7 +246,7 @@ async def read_item(item_id: int, q: str | None = None):
```console -$ fastapi dev +$ uv run fastapi dev ╭────────── FastAPI CLI - Development mode ───────────╮ │ │ @@ -277,7 +273,7 @@ INFO: Application startup complete.
关于命令 fastapi dev... -`fastapi dev` 命令会读取你的 `main.py` 文件，检测其中的 **FastAPI** 应用，并使用 [Uvicorn](https://www.uvicorn.dev) 启动服务器。 +`fastapi dev` 命令会自动读取你的 `main.py` 文件，检测其中的 **FastAPI** 应用，并使用 [Uvicorn](https://uvicorn.dev) 启动服务器。 默认情况下，`fastapi dev` 会在本地开发时启用自动重载。 @@ -314,7 +310,7 @@ INFO: Application startup complete. 然后访问 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)。 -你会看到另一个自动生成的文档（由 [ReDoc](https://github.com/Rebilly/ReDoc) 提供）： +你会看到另一个自动生成的文档（由 [ReDoc](https://github.com/Redocly/redoc) 提供）： ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -497,7 +493,7 @@ item: Item
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -520,7 +516,7 @@ CLI 会自动检测你的 FastAPI 应用并将其部署到云端。如果你尚 它把用 FastAPI 构建应用时的**开发者体验**带到了部署到云上的过程。🎉 -FastAPI Cloud 是「FastAPI and friends」开源项目的主要赞助方和资金提供者。✨ +FastAPI Cloud 是 *FastAPI and friends* 开源项目的主要赞助方和资金提供者。✨ #### 部署到其他云厂商 { #deploy-to-other-cloud-providers } @@ -540,7 +536,7 @@ FastAPI 依赖 Pydantic 和 Starlette。 ### `standard` 依赖 { #standard-dependencies } -当你通过 `pip install "fastapi[standard]"` 安装 FastAPI 时，会包含 `standard` 组的一些可选依赖： +当你通过 `uv add "fastapi[standard]"` 安装 FastAPI 时，会包含 `standard` 组的一些可选依赖： Pydantic 使用： @@ -554,17 +550,17 @@ Starlette 使用： FastAPI 使用： -* [`uvicorn`](https://www.uvicorn.dev) - 加载并提供你的应用的服务器。包含 `uvicorn[standard]`，其中包含高性能服务所需的一些依赖（例如 `uvloop`）。 +* [`uvicorn`](https://uvicorn.dev) - 加载并提供你的应用的服务器。包含 `uvicorn[standard]`，其中包含高性能服务所需的一些依赖（例如 `uvloop`）。 * `fastapi-cli[standard]` - 提供 `fastapi` 命令。 * 其中包含 `fastapi-cloud-cli`，它允许你将 FastAPI 应用部署到 [FastAPI Cloud](https://fastapicloud.com)。 ### 不包含 `standard` 依赖 { #without-standard-dependencies } -如果你不想包含这些 `standard` 可选依赖，可以使用 `pip install fastapi`，而不是 `pip install "fastapi[standard]"`。 +如果你不想包含这些 `standard` 可选依赖，可以使用 `uv add fastapi`，而不是 `uv add "fastapi[standard]"`。 ### 不包含 `fastapi-cloud-cli` { #without-fastapi-cloud-cli } -如果你想安装带有 standard 依赖但不包含 `fastapi-cloud-cli` 的 FastAPI，可以使用 `pip install "fastapi[standard-no-fastapi-cloud-cli]"`。 +如果你想安装带有 standard 依赖但不包含 `fastapi-cloud-cli` 的 FastAPI，可以使用 `uv add "fastapi[standard-no-fastapi-cloud-cli]"`。 ### 其他可选依赖 { #additional-optional-dependencies } @@ -572,13 +568,13 @@ FastAPI 使用： 额外的 Pydantic 可选依赖： -* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - 用于配置管理。 -* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - 用于在 Pydantic 中使用的额外类型。 +* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) - 用于配置管理。 +* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) - 用于在 Pydantic 中使用的额外类型。 额外的 FastAPI 可选依赖： * [`orjson`](https://github.com/ijl/orjson) - 使用 `ORJSONResponse` 时需要。 -* [`ujson`](https://github.com/esnme/ultrajson) - 使用 `UJSONResponse` 时需要。 +* [`ujson`](https://github.com/ultrajson/ultrajson) - 使用 `UJSONResponse` 时需要。 ## 许可协议 { #license } diff --git a/docs/zh/docs/project-generation.md b/docs/zh/docs/project-generation.md index 371eb73..bbe335a 100644 --- a/docs/zh/docs/project-generation.md +++ b/docs/zh/docs/project-generation.md @@ -5,13 +5,13 @@ 你可以使用此模板开始，它已经为你完成了大量的初始设置、安全性、数据库以及一些 API 端点。 -GitHub 仓库：[Full Stack FastAPI Template](https://github.com/tiangolo/full-stack-fastapi-template) +GitHub 仓库：[Full Stack FastAPI Template](https://github.com/fastapi/full-stack-fastapi-template) ## FastAPI全栈模板 - 技术栈和特性 { #full-stack-fastapi-template-technology-stack-and-features } - ⚡ [**FastAPI**](https://fastapi.tiangolo.com/zh) 用于 Python 后端 API。 - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) 用于 Python 与 SQL 数据库的交互（ORM）。 - - 🔍 [Pydantic](https://docs.pydantic.dev)，FastAPI 使用，用于数据验证与配置管理。 + - 🔍 [Pydantic](https://pydantic.dev/docs/)，FastAPI 使用，用于数据验证与配置管理。 - 💾 [PostgreSQL](https://www.postgresql.org) 作为 SQL 数据库。 - 🚀 [React](https://react.dev) 用于前端。 - 💃 使用 TypeScript、hooks、Vite 以及现代前端技术栈的其他部分。 diff --git a/docs/zh/docs/python-types.md b/docs/zh/docs/python-types.md index 4d2c274..b0609e5 100644 --- a/docs/zh/docs/python-types.md +++ b/docs/zh/docs/python-types.md @@ -269,7 +269,7 @@ def some_function(data: Any): ## Pydantic 模型 { #pydantic-models } -[Pydantic](https://docs.pydantic.dev/) 是一个用于执行数据校验的 Python 库。 +[Pydantic](https://pydantic.dev/docs/) 是一个用于执行数据校验的 Python 库。 你将数据的“结构”声明为带有属性的类。 @@ -285,7 +285,7 @@ def some_function(data: Any): /// note | 注意 -要了解更多关于 [Pydantic 的信息，请查看其文档](https://docs.pydantic.dev/)。 +要了解更多关于 [Pydantic 的信息，请查看其文档](https://pydantic.dev/docs/)。 /// diff --git a/docs/zh/docs/tutorial/background-tasks.md b/docs/zh/docs/tutorial/background-tasks.md index 975bb26..511f27c 100644 --- a/docs/zh/docs/tutorial/background-tasks.md +++ b/docs/zh/docs/tutorial/background-tasks.md @@ -7,9 +7,9 @@ 包括这些例子： * 执行操作后发送的电子邮件通知： - * 由于连接到电子邮件服务器并发送电子邮件往往很“慢”（几秒钟），您可以立即返回响应并在后台发送电子邮件通知。 + * 由于连接到电子邮件服务器并发送电子邮件往往很“慢”（几秒钟），你可以立即返回响应并在后台发送电子邮件通知。 * 处理数据： - * 例如，假设您收到的文件必须经过一个缓慢的过程，您可以返回一个"Accepted"(HTTP 202)响应并在后台处理它。 + * 例如，假设你收到的文件必须经过一个缓慢的过程，你可以返回一个"Accepted"(HTTP 202)响应并在后台处理它。 ## 使用 `BackgroundTasks` { #using-backgroundtasks } @@ -61,23 +61,23 @@ ## 技术细节 { #technical-details } -`BackgroundTasks` 类直接来自 [`starlette.background`](https://www.starlette.dev/background/)。 +`BackgroundTasks` 类直接来自 [`starlette.background`](https://starlette.dev/background/)。 它被直接导入/包含到FastAPI以便你可以从 `fastapi` 导入，并避免意外从 `starlette.background` 导入备用的 `BackgroundTask` (后面没有 `s`)。 -通过仅使用 `BackgroundTasks` (而不是 `BackgroundTask`)，使得能将它作为 *路径操作函数* 的参数 ，并让**FastAPI**为您处理其余部分, 就像直接使用 `Request` 对象。 +通过仅使用 `BackgroundTasks` (而不是 `BackgroundTask`)，使得能将它作为 *路径操作函数* 的参数 ，并让**FastAPI**为你处理其余部分, 就像直接使用 `Request` 对象。 -在FastAPI中仍然可以单独使用 `BackgroundTask`，但您必须在代码中创建对象，并返回包含它的Starlette `Response`。 +在FastAPI中仍然可以单独使用 `BackgroundTask`，但你必须在代码中创建对象，并返回包含它的Starlette `Response`。 -更多细节查看 [Starlette 后台任务的官方文档](https://www.starlette.dev/background/)。 +更多细节查看 [Starlette 后台任务的官方文档](https://starlette.dev/background/)。 ## 告诫 { #caveat } -如果您需要执行繁重的后台计算，并且不一定需要由同一进程运行（例如，您不需要共享内存、变量等），那么使用其他更大的工具（如 [Celery](https://docs.celeryq.dev)）可能更好。 +如果你需要执行繁重的后台计算，并且不一定需要由同一进程运行（例如，你不需要共享内存、变量等），那么使用其他更大的工具（如 [Celery](https://docs.celeryq.dev)）可能更好。 -它们往往需要更复杂的配置，即消息/作业队列管理器，如RabbitMQ或Redis，但它们允许您在多个进程中运行后台任务，甚至是在多个服务器中。 +它们往往需要更复杂的配置，即消息/作业队列管理器，如RabbitMQ或Redis，但它们允许你在多个进程中运行后台任务，甚至是在多个服务器中。 -但是，如果您需要从同一个**FastAPI**应用程序访问变量和对象，或者您需要执行小型后台任务（如发送电子邮件通知），您只需使用 `BackgroundTasks` 即可。 +但是，如果你需要从同一个**FastAPI**应用程序访问变量和对象，或者你需要执行小型后台任务（如发送电子邮件通知），你只需使用 `BackgroundTasks` 即可。 ## 回顾 { #recap } diff --git a/docs/zh/docs/tutorial/bigger-applications.md b/docs/zh/docs/tutorial/bigger-applications.md index 9bb4bea..fb21396 100644 --- a/docs/zh/docs/tutorial/bigger-applications.md +++ b/docs/zh/docs/tutorial/bigger-applications.md @@ -487,7 +487,7 @@ from app.main import app 你也可以把路径传给命令，比如： ```console -$ fastapi dev app/main.py +$ uv run fastapi dev app/main.py ``` 但是每次调用 `fastapi` 命令时，你都需要记得传入正确的路径。 @@ -503,7 +503,7 @@ $ fastapi dev app/main.py
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/zh/docs/tutorial/body-nested-models.md b/docs/zh/docs/tutorial/body-nested-models.md index ce10b74..98a3439 100644 --- a/docs/zh/docs/tutorial/body-nested-models.md +++ b/docs/zh/docs/tutorial/body-nested-models.md @@ -95,7 +95,7 @@ Pydantic 模型的每个属性都具有类型。 除了普通的单一值类型（如 `str`、`int`、`float` 等）外，你还可以使用从 `str` 继承的更复杂的单一值类型。 -要了解所有的可用选项，请查看 [Pydantic 的类型概览](https://docs.pydantic.dev/latest/concepts/types/)。你将在下一章节中看到一些示例。 +要了解所有的可用选项，请查看 [Pydantic 的类型概览](https://pydantic.dev/docs/validation/latest/concepts/types/)。你将在下一章节中看到一些示例。 例如，在 `Image` 模型中我们有一个 `url` 字段，我们可以把它声明为 Pydantic 的 `HttpUrl`，而不是 `str`： diff --git a/docs/zh/docs/tutorial/body.md b/docs/zh/docs/tutorial/body.md index b32a5ac..2f546ce 100644 --- a/docs/zh/docs/tutorial/body.md +++ b/docs/zh/docs/tutorial/body.md @@ -6,7 +6,7 @@ 你的 API 几乎总是需要发送**响应体**。但客户端不一定总是要发送**请求体**，有时它们只请求某个路径，可能带一些查询参数，但不会发送请求体。 -使用 [Pydantic](https://docs.pydantic.dev/) 模型来声明**请求体**，能充分利用它的功能和优点。 +使用 [Pydantic](https://pydantic.dev/docs/) 模型来声明**请求体**，能充分利用它的功能和优点。 /// note | 注意 diff --git a/docs/zh/docs/tutorial/debugging.md b/docs/zh/docs/tutorial/debugging.md index 0b1ada2..8a6df4c 100644 --- a/docs/zh/docs/tutorial/debugging.md +++ b/docs/zh/docs/tutorial/debugging.md @@ -15,7 +15,7 @@
```console -$ python myapp.py +$ uv run python myapp.py ```
@@ -35,7 +35,7 @@ from myapp import app
```console -$ python myapp.py +$ uv run python myapp.py ```
diff --git a/docs/zh/docs/tutorial/extra-data-types.md b/docs/zh/docs/tutorial/extra-data-types.md index 4415582..26d5e8c 100644 --- a/docs/zh/docs/tutorial/extra-data-types.md +++ b/docs/zh/docs/tutorial/extra-data-types.md @@ -36,7 +36,7 @@ * `datetime.timedelta`: * 一个 Python `datetime.timedelta`. * 在请求和响应中将表示为 `float` 代表总秒数。 - * Pydantic 也允许将其表示为 "ISO 8601 时间差异编码", [查看文档了解更多信息](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers)。 + * Pydantic 也允许将其表示为 "ISO 8601 时间差异编码", [查看文档了解更多信息](https://pydantic.dev/docs/validation/latest/concepts/serialization/#custom-serializers)。 * `frozenset`: * 在请求和响应中，作为 `set` 对待： * 在请求中，列表将被读取，消除重复，并将其转换为一个 `set`。 @@ -49,7 +49,7 @@ * `Decimal`: * 标准的 Python `Decimal`。 * 在请求和响应中被当做 `float` 一样处理。 -* 你可以在这里检查所有有效的 Pydantic 数据类型: [Pydantic data types](https://docs.pydantic.dev/latest/usage/types/types/)。 +* 你可以在这里检查所有有效的 Pydantic 数据类型: [Pydantic 数据类型](https://pydantic.dev/docs/validation/latest/concepts/types/)。 ## 例子 { #example } diff --git a/docs/zh/docs/tutorial/extra-models.md b/docs/zh/docs/tutorial/extra-models.md index 60f66c5..5672ccb 100644 --- a/docs/zh/docs/tutorial/extra-models.md +++ b/docs/zh/docs/tutorial/extra-models.md @@ -167,7 +167,7 @@ UserInDB( /// note | 注意 -定义 [`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions) 类型时，要把更具体的类型写在前面，然后是不太具体的类型。下例中，更具体的 `PlaneItem` 位于 `Union[PlaneItem, CarItem]` 中的 `CarItem` 之前。 +定义 [`Union`](https://pydantic.dev/docs/validation/latest/concepts/unions/) 类型时，要把更具体的类型写在前面，然后是不太具体的类型。下例中，更具体的 `PlaneItem` 位于 `Union[PlaneItem, CarItem]` 中的 `CarItem` 之前。 /// @@ -209,4 +209,4 @@ some_variable: PlaneItem | CarItem 针对不同场景，可以随意使用不同的 Pydantic 模型并通过继承复用。 -当一个实体需要具备不同的“状态”时，无需只为该实体定义一个数据模型。例如，用户“实体”就可能有包含 `password`、包含 `password_hash` 以及不含密码等多种状态。 +当一个实体需要具备不同的“状态”时，无需只为该实体定义一个数据模型。例如，**用户**“实体”就可能有包含 `password`、包含 `password_hash` 以及不含密码等多种状态。 diff --git a/docs/zh/docs/tutorial/first-steps.md b/docs/zh/docs/tutorial/first-steps.md index cadcac3..5099946 100644 --- a/docs/zh/docs/tutorial/first-steps.md +++ b/docs/zh/docs/tutorial/first-steps.md @@ -7,12 +7,18 @@ 将其复制到 `main.py` 文件中。 +/// tip | 提示 + +FastAPI 有一个[官方 VS Code 扩展](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode)（以及 Cursor），它提供了很多功能，包括路径操作浏览器、路径操作搜索、测试中的 CodeLens 导航（从测试跳转到定义），以及 FastAPI Cloud 部署和日志，全部都可以在你的编辑器中完成。 + +/// + 运行实时服务器：
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -79,7 +85,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) 前往 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)。 -你将会看到可选的自动生成文档 （由 [ReDoc](https://github.com/Rebilly/ReDoc) 提供）： +你将会看到可选的自动生成文档 （由 [ReDoc](https://github.com/Redocly/redoc) 提供）： ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -186,16 +192,16 @@ from backend.main import app 你也可以把文件路径传给 `fastapi dev` 命令，它会尝试推断要使用的 FastAPI 应用对象： ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` 或者，你也可以给 `fastapi dev` 命令传入 `--entrypoint` 选项： ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` -但这样每次调用 `fastapi` 命令时都需要记得传入正确的路径/entrypoint。 +但这样每次调用 `fastapi` 命令时都需要记得传入正确的路径\entrypoint。 另外，其他工具可能无法找到它，例如 [VS Code 扩展](../editor-support.md) 或 [FastAPI Cloud](https://fastapicloud.com)，因此推荐在 `pyproject.toml` 中使用 `entrypoint`。 @@ -206,7 +212,7 @@ $ fastapi dev --entrypoint main:app
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -233,7 +239,7 @@ CLI 会自动检测你的 FastAPI 应用并将其部署到云端。如果你尚 `FastAPI` 是直接从 `Starlette` 继承的类。 -你可以通过 `FastAPI` 使用所有的 [Starlette](https://www.starlette.dev/) 的功能。 +你也可以通过 `FastAPI` 使用所有的 [Starlette](https://starlette.dev/) 的功能。 /// diff --git a/docs/zh/docs/tutorial/frontend.md b/docs/zh/docs/tutorial/frontend.md index 3216907..2e01cc2 100644 --- a/docs/zh/docs/tutorial/frontend.md +++ b/docs/zh/docs/tutorial/frontend.md @@ -52,7 +52,7 @@ npm run build {* ../../docs_src/frontend/tutorial002_py310.py hl[5] *} -**FastAPI** 只会对看起来像浏览器导航的 `GET` 和 `HEAD` 请求使用此 fallback。缺失的 JavaScript、CSS 和图片等文件仍会返回 `404`。 +**FastAPI** 只会对明确使用 `Accept: text/html` 或 `Accept: application/xhtml+xml` 接受 HTML 的 `GET` 和 `HEAD` 请求使用此 fallback，就像浏览器导航请求通常会做的那样。缺失的 JavaScript、CSS 和图片等文件仍会返回 `404`。 对于其他方法的请求，例如 `POST` 或 `PUT`，如果路径只匹配前端 fallback，也会返回 `404`。常规 **FastAPI** *路径操作*仍然比前端路由具有更高优先级。 @@ -106,9 +106,13 @@ npm run build ## 检查目录 { #check-directory } -默认情况下，`app.frontend()` 会在应用创建时检查目录是否存在。 +默认情况下，`app.frontend()` 使用 `check_dir="auto"`。 -这有助于尽早发现配置错误。例如，如果前端构建输出目录缺失，**FastAPI** 会在启动时抛出错误。 +当 `FASTAPI_ENV` 环境变量设置为 `development` 时，如果前端构建输出目录缺失，**FastAPI** 只会显示警告。如果尚未设置，[`fastapi dev` 命令](https://github.com/fastapi/fastapi-cli#fastapi-dev)会为你设置这个环境变量。这样你就可以在开发期间，在构建或启动前端之前先启动后端。 + +在其他任何环境中，**FastAPI** 会在创建应用时抛出错误。这有助于在部署缺少前端文件的应用之前，尽早发现配置错误。 + +你也可以设置 `check_dir=True`，以便始终在创建应用时检查目录。 如果你的前端文件会稍后创建，例如在应用对象创建之后由单独的构建步骤创建，请设置 `check_dir=False`： @@ -132,6 +136,8 @@ npm run build 来自 app、`APIRouter` 和 `include_router()` 的依赖项也会应用于前端响应。这可用于通过 cookie 身份验证或类似方式保护前端。 +依赖项也可以像普通*路径操作*一样修改响应标头并添加后台任务。 + ## 仅限静态构建输出 { #static-build-output-only } `app.frontend()` 提供的是你的前端构建已经生成的文件。 diff --git a/docs/zh/docs/tutorial/handling-errors.md b/docs/zh/docs/tutorial/handling-errors.md index b77ca7a..4f8eb0d 100644 --- a/docs/zh/docs/tutorial/handling-errors.md +++ b/docs/zh/docs/tutorial/handling-errors.md @@ -81,7 +81,7 @@ ## 安装自定义异常处理器 { #install-custom-exception-handlers } -可以使用[与 Starlette 相同的异常处理工具](https://www.starlette.dev/exceptions/)添加自定义异常处理器。 +可以使用[与 Starlette 相同的异常处理工具](https://starlette.dev/exceptions/)添加自定义异常处理器。 假设有一个自定义异常 `UnicornException`（你自己或你使用的库可能会 `raise` 它）。 diff --git a/docs/zh/docs/tutorial/index.md b/docs/zh/docs/tutorial/index.md index fde264d..cbdbc6e 100644 --- a/docs/zh/docs/tutorial/index.md +++ b/docs/zh/docs/tutorial/index.md @@ -10,12 +10,12 @@ 所有代码片段都可以复制后直接使用（它们实际上是经过测试的 Python 文件）。 -要运行任何示例，请将代码复制到 `main.py` 文件中，然后启动 `fastapi dev`： +要运行任何示例，请将代码复制到 `main.py` 文件中，然后使用 `uv run` 启动 `fastapi dev`：
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -60,35 +60,75 @@ $ fastapi dev ## 安装 FastAPI { #install-fastapi } -第一个步骤是安装 FastAPI。 +第一步是设置你的项目并添加 FastAPI。 -请确保你创建并激活一个[虚拟环境](../virtual-environments.md)，然后**安装 FastAPI**： +安装 [`uv`](https://docs.astral.sh/uv/getting-started/installation/)，然后创建一个项目并添加 FastAPI：
```console -$ pip install "fastapi[standard]" +$ uv init awesome-project --bare +$ cd awesome-project +$ uv add "fastapi[standard]" ---> 100% ```
+`uv add` 会在 `.venv` 中创建项目的虚拟环境，将 FastAPI 添加到 `pyproject.toml`，并创建 `uv.lock`，以便稍后可以安装相同的包版本。 + +/// details | 这些命令的作用 + +* `uv init`：创建一个新的 Python 项目。 +* `awesome-project`：在一个使用此名称的新目录中创建项目。 +* `--bare`：只创建最小的 `pyproject.toml` 文件，不生成示例 `main.py`、`README.md` 或其他文件。你将在本教程的后续步骤中自己创建应用程序文件。 + +然后，`cd awesome-project` 会在添加 FastAPI 之前进入新的项目目录。 + +`uv` 会使用系统中已安装的兼容 Python 版本，或者在需要时下载一个。 + +当你运行 `uv add` 时，它会选择 FastAPI 以及 FastAPI 依赖的所有包的兼容版本。它会把确切版本记录到 `uv.lock` 中，从而可以稍后在另一台计算机上或部署应用程序时安装相同的包版本。 + +创建或更新此文件称为[**锁定**项目依赖项](https://docs.astral.sh/uv/concepts/projects/sync/)。当你添加包时，`uv` 会自动执行此操作。 + +/// + +/// details | FastAPI 安装选项 + +当你使用 `uv add "fastapi[standard]"` 安装时，它会附带一些默认的可选标准依赖项，其中包括 `fastapi-cloud-cli`，它可以让你部署到 [FastAPI Cloud](https://fastapicloud.com)。 + +如果你不想安装这些可选依赖，可以选择安装 `uv add fastapi`。 + +如果你想安装标准依赖但不包含 `fastapi-cloud-cli`，可以使用 `uv add "fastapi[standard-no-fastapi-cloud-cli]"` 安装。 + +/// + +/// details | 改用 `pip` + +如果你更喜欢手动管理虚拟环境和包，请创建并激活一个虚拟环境，然后使用 `pip install "fastapi[standard]"` 安装 FastAPI。 + +阅读[虚拟环境指南](https://tiangolo.com/guides/virtual-environments/)了解详细步骤。 + +/// + +## AI Agent 技能 { #ai-agent-skills } + +FastAPI 为 AI coding agent 提供了一个官方 skill。它随包一起提供，因此它的指导会与你项目中安装的 FastAPI 版本保持一致，并在你更新 FastAPI 时随之更新。 + +在你的项目中安装 FastAPI 后，你可以使用 Library Skills 安装该 skill： + +```bash +uvx library-skills +``` + /// note | 注意 -当你使用 `pip install "fastapi[standard]"` 安装时，它会附带一些默认的可选标准依赖项，其中包括 `fastapi-cloud-cli`，它可以让你部署到 [FastAPI Cloud](https://fastapicloud.com)。 - -如果你不想安装这些可选依赖，可以选择安装 `pip install fastapi`。 - -如果你想安装标准依赖但不包含 `fastapi-cloud-cli`，可以使用 `pip install "fastapi[standard-no-fastapi-cloud-cli]"` 安装。 +`uvx` 是 `uv tool run` 的别名。它会在一个临时、隔离的环境中运行 Library Skills，同时 Library Skills 会扫描你项目中安装的包。 /// -/// tip | 提示 - -FastAPI 提供了一个[VS Code 官方扩展](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode)（也支持 Cursor），包含众多功能，例如路径操作浏览器、路径操作搜索、测试中的 CodeLens 导航（从测试跳转到定义），以及从编辑器内进行 FastAPI Cloud 部署和查看日志。 - -/// +该 skill 与 Codex、Claude Code、Cursor、GitHub Copilot、Gemini CLI、Pi、OpenCode 以及大多数其他 coding agent 兼容。对于 Claude Code，当被询问要将该 skill 安装到哪里时，选择 `.claude/skills`。 ## 进阶用户指南 { #advanced-user-guide } diff --git a/docs/zh/docs/tutorial/middleware.md b/docs/zh/docs/tutorial/middleware.md index e758613..ca1431b 100644 --- a/docs/zh/docs/tutorial/middleware.md +++ b/docs/zh/docs/tutorial/middleware.md @@ -33,11 +33,11 @@ {* ../../docs_src/middleware/tutorial001_py310.py hl[8:9,11,14] *} -/// tip +/// tip | 提示 请记住可以[使用 `X-` 前缀](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)添加专有自定义请求头。 -但是如果你有希望让浏览器中的客户端可见的自定义请求头，你需要把它们加到你的 CORS 配置（[CORS（跨域资源共享）](cors.md)）的 `expose_headers` 参数中，参见 [Starlette 的 CORS 文档](https://www.starlette.dev/middleware/#corsmiddleware)。 +但是如果你有希望让浏览器中的客户端可见的自定义请求头，你需要把它们加到你的 CORS 配置（[CORS（跨域资源共享）](cors.md)）的 `expose_headers` 参数中，参见 [Starlette 的 CORS 文档](https://starlette.dev/middleware/#corsmiddleware)。 /// @@ -59,7 +59,7 @@ {* ../../docs_src/middleware/tutorial001_py310.py hl[10,12:13] *} -/// tip +/// tip | 提示 这里我们使用 [`time.perf_counter()`](https://docs.python.org/3/library/time.html#time.perf_counter) 而不是 `time.time()`，因为在这类场景中它可能更精确。🤓 @@ -82,9 +82,9 @@ app.add_middleware(MiddlewareB) 这会产生如下执行顺序： -* 请求：MiddlewareB → MiddlewareA → 路由 +* **请求**：MiddlewareB → MiddlewareA → 路由 -* 响应：路由 → MiddlewareA → MiddlewareB +* **响应**：路由 → MiddlewareA → MiddlewareB 这种栈式行为确保中间件按可预测且可控的顺序执行。 diff --git a/docs/zh/docs/tutorial/path-params.md b/docs/zh/docs/tutorial/path-params.md index 0db7185..adf1a74 100644 --- a/docs/zh/docs/tutorial/path-params.md +++ b/docs/zh/docs/tutorial/path-params.md @@ -38,7 +38,7 @@ 注意，函数接收并返回的值是 `3`（ `int`），不是 `"3"`（`str`）。 -**FastAPI** 通过类型声明自动进行请求的解析。 +**FastAPI** 通过类型声明自动进行请求的“解析”。 /// @@ -92,7 +92,7 @@ ## 基于标准的好处，备选文档 { #standards-based-benefits-alternative-documentation } -**FastAPI** 使用 [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md) 生成概图，所以能兼容很多工具。 +**FastAPI** 使用 [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) 生成概图，所以能兼容很多工具。 因此，**FastAPI** 还内置了 ReDoc 生成的备选 API 文档，可在此查看 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)： @@ -102,7 +102,7 @@ ## Pydantic { #pydantic } -所有数据校验都由 [Pydantic](https://docs.pydantic.dev/) 在幕后完成，因此你能从中获得所有好处。而且你可以放心。 +所有数据校验都由 [Pydantic](https://pydantic.dev/docs/) 在幕后完成，因此你能从中获得所有好处。而且你可以放心。 同样，`str`、`float`、`bool` 以及很多复合数据类型都可以使用类型声明。 @@ -130,7 +130,7 @@ ## 预设值 { #predefined-values } -路径操作使用 Python 的 `Enum` 类型接收预设的路径参数。 +如果你的*路径操作*接收一个*路径参数*，但你希望可能有效的*路径参数*值是预设的，可以使用标准 Python `Enum`。 ### 创建 `Enum` 类 { #create-an-enum-class } @@ -144,33 +144,33 @@ /// tip | 提示 -**AlexNet**、**ResNet**、**LeNet** 是机器学习模型的名字。 +如果你好奇，"AlexNet"、"ResNet" 和 "LeNet" 只是机器学习模型的名字。 /// -### 声明路径参数 { #declare-a-path-parameter } +### 声明*路径参数* { #declare-a-path-parameter } -使用 Enum 类（`ModelName`）创建使用类型注解的路径参数： +使用你创建的枚举类（`ModelName`）创建带有类型注解的*路径参数*： {* ../../docs_src/path_params/tutorial005_py310.py hl[16] *} ### 查看文档 { #check-the-docs } -API 文档会显示预定义路径参数的可用值： +由于*路径参数*的可用值是预定义的，交互式文档可以很好地显示它们： -### 使用 Python 枚举 { #working-with-python-enumerations } +### 使用 Python *枚举* { #working-with-python-enumerations } -路径参数的值是一个枚举成员。 +*路径参数*的值是一个*枚举成员*。 -#### 比较枚举成员 { #compare-enumeration-members } +#### 比较*枚举成员* { #compare-enumeration-members } -可以将其与枚举类 `ModelName` 中的枚举成员进行比较： +可以将其与你创建的枚举 `ModelName` 中的*枚举成员*进行比较： {* ../../docs_src/path_params/tutorial005_py310.py hl[17] *} -#### 获取枚举值 { #get-the-enumeration-value } +#### 获取*枚举值* { #get-the-enumeration-value } 使用 `model_name.value` 或通用的 `your_enum_member.value` 获取实际的值（本例中为 `str`）： @@ -182,11 +182,11 @@ API 文档会显示预定义路径参数的可用值： /// -#### 返回枚举成员 { #return-enumeration-members } +#### 返回*枚举成员* { #return-enumeration-members } -即使嵌套在 JSON 请求体里（例如，`dict`），也可以从路径操作返回枚举成员。 +即使嵌套在 JSON 请求体里（例如，`dict`），也可以从你的*路径操作*返回*枚举成员*。 -返回给客户端之前，会把枚举成员转换为对应的值（本例中为字符串）： +返回给客户端之前，会把它们转换为对应的值（本例中为字符串）： {* ../../docs_src/path_params/tutorial005_py310.py hl[18,21,23] *} @@ -201,29 +201,29 @@ API 文档会显示预定义路径参数的可用值： ## 包含路径的路径参数 { #path-parameters-containing-paths } -假设路径操作的路径为 `/files/{file_path}`。 +假设你有一个路径为 `/files/{file_path}` 的*路径操作*。 -但需要 `file_path` 中也包含路径，比如，`home/johndoe/myfile.txt`。 +但需要 `file_path` 本身也包含*路径*，比如，`home/johndoe/myfile.txt`。 -此时，该文件的 URL 是这样的：`/files/home/johndoe/myfile.txt`。 +因此，该文件的 URL 可能是这样的：`/files/home/johndoe/myfile.txt`。 ### OpenAPI 支持 { #openapi-support } -OpenAPI 不支持声明包含路径的路径参数，因为这会导致测试和定义更加困难。 +OpenAPI 不支持声明内部包含*路径*的*路径参数*，因为这会导致测试和定义更加困难。 -不过，仍可使用 Starlette 内置工具在 **FastAPI** 中实现这一功能。 +不过，仍可使用 Starlette 内部工具之一在 **FastAPI** 中实现这一功能。 -而且不影响文档正常运行，但是不会添加该参数包含路径的说明。 +而且不影响文档正常运行，但是不会添加该参数应包含路径的说明。 ### 路径转换器 { #path-convertor } -直接使用 Starlette 的选项声明包含路径的路径参数： +直接使用 Starlette 的选项，就可以用如下 URL 声明包含*路径*的*路径参数*： ``` /files/{file_path:path} ``` -本例中，参数名为 `file_path`，结尾部分的 `:path` 说明该参数应匹配路径。 +本例中，参数名为 `file_path`，结尾部分的 `:path` 说明该参数应匹配任意*路径*。 用法如下： @@ -241,10 +241,10 @@ OpenAPI 不支持声明包含路径的路径参数，因为这会导致测试和 通过简短、直观的 Python 标准类型声明，**FastAPI** 可以获得： -- 编辑器支持：错误检查，代码自动补全等 -- 数据 "解析" -- 数据校验 -- API 注解和自动文档 +* 编辑器支持：错误检查，代码自动补全等 +* 数据 "解析" +* 数据校验 +* API 注解和自动文档 只需要声明一次即可。 diff --git a/docs/zh/docs/tutorial/query-params-str-validations.md b/docs/zh/docs/tutorial/query-params-str-validations.md index 0164c27..88d4306 100644 --- a/docs/zh/docs/tutorial/query-params-str-validations.md +++ b/docs/zh/docs/tutorial/query-params-str-validations.md @@ -370,11 +370,11 @@ http://127.0.0.1:8000/items/?item-query=foobaritems 在这些情况下，你可以使用**自定义校验函数**，该函数会在正常校验之后应用（例如，在先校验值是 `str` 之后）。 -你可以在 `Annotated` 中使用 [Pydantic 的 `AfterValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator) 来实现。 +你可以在 `Annotated` 中使用 [Pydantic 的 `AfterValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-after-validator) 来实现。 /// tip | 提示 -Pydantic 还有 [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator) 等。🤓 +Pydantic 还有 [`BeforeValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-before-validator) 等。🤓 /// diff --git a/docs/zh/docs/tutorial/request-files.md b/docs/zh/docs/tutorial/request-files.md index 38c089f..8e98b54 100644 --- a/docs/zh/docs/tutorial/request-files.md +++ b/docs/zh/docs/tutorial/request-files.md @@ -6,10 +6,10 @@ 要接收上传的文件，请先安装 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -请确保你创建一个[虚拟环境](../virtual-environments.md)、激活它，然后安装，例如： +将它添加到你的项目中： ```console -$ pip install python-multipart +$ uv add python-multipart ``` 这是因为上传文件是以「表单数据」发送的。 @@ -151,7 +151,7 @@ HTML 表单（`
`）向服务器发送数据的方式通常会对数 它们会被关联到同一个通过「表单数据」发送的「表单字段」。 -要实现这一点，声明一个由 `bytes` 或 `UploadFile` 组成的列表（`List`）： +要实现这一点，声明一个由 `bytes` 或 `UploadFile` 组成的列表： {* ../../docs_src/request_files/tutorial002_an_py310.py hl[10,15] *} diff --git a/docs/zh/docs/tutorial/request-form-models.md b/docs/zh/docs/tutorial/request-form-models.md index bbe805e..9b3de06 100644 --- a/docs/zh/docs/tutorial/request-form-models.md +++ b/docs/zh/docs/tutorial/request-form-models.md @@ -6,10 +6,10 @@ 要使用表单，首先安装 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -确保你创建一个[虚拟环境](../virtual-environments.md)，激活它，然后再安装，例如： +将它添加到你的项目： ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/zh/docs/tutorial/request-forms-and-files.md b/docs/zh/docs/tutorial/request-forms-and-files.md index d972391..b0e0052 100644 --- a/docs/zh/docs/tutorial/request-forms-and-files.md +++ b/docs/zh/docs/tutorial/request-forms-and-files.md @@ -6,10 +6,10 @@ FastAPI 支持同时使用 `File` 和 `Form` 定义文件和表单字段。 接收上传的文件和/或表单数据，首先安装 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -请先创建并激活一个[虚拟环境](../virtual-environments.md)，然后再安装，例如： +将它添加到你的项目中： ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/zh/docs/tutorial/request-forms.md b/docs/zh/docs/tutorial/request-forms.md index 0e7f19c..6da128a 100644 --- a/docs/zh/docs/tutorial/request-forms.md +++ b/docs/zh/docs/tutorial/request-forms.md @@ -6,10 +6,10 @@ 要使用表单，首先安装 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -请先创建并激活一个[虚拟环境](../virtual-environments.md)，然后再进行安装，例如： +将其添加到你的项目中： ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/zh/docs/tutorial/response-model.md b/docs/zh/docs/tutorial/response-model.md index 5d8d0c1..5cdfee2 100644 --- a/docs/zh/docs/tutorial/response-model.md +++ b/docs/zh/docs/tutorial/response-model.md @@ -76,16 +76,16 @@ FastAPI 会使用这个 `response_model` 来完成数据文档、校验等，并 要使用 `EmailStr`，首先安装 [`email-validator`](https://github.com/JoshData/python-email-validator)。 -请先创建并激活一个[虚拟环境](../virtual-environments.md)，然后安装，例如： +将它添加到你的项目中： ```console -$ pip install email-validator +$ uv add email-validator ``` -或者： +或者使用： ```console -$ pip install "pydantic[email]" +$ uv add "pydantic[email]" ``` /// @@ -258,7 +258,7 @@ FastAPI 在内部配合 Pydantic 做了多项处理，确保不会把类继承 * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -详见 [Pydantic 文档](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict)中对 `exclude_defaults` 和 `exclude_none` 的说明。 +详见 [Pydantic 文档](https://pydantic.dev/docs/validation/latest/concepts/serialization/#excluding-and-including-fields-based-on-their-value)中对 `exclude_defaults` 和 `exclude_none` 的说明。 /// diff --git a/docs/zh/docs/tutorial/schema-extra-example.md b/docs/zh/docs/tutorial/schema-extra-example.md index b18e696..a2ffcc8 100644 --- a/docs/zh/docs/tutorial/schema-extra-example.md +++ b/docs/zh/docs/tutorial/schema-extra-example.md @@ -12,7 +12,7 @@ 这些额外信息会原样添加到该模型输出的 **JSON Schema** 中，并会在 API 文档中使用。 -你可以使用属性 `model_config`，它接收一个 `dict`，详见 [Pydantic 文档：配置](https://docs.pydantic.dev/latest/api/config/)。 +你可以使用属性 `model_config`，它接收一个 `dict`，详见 [Pydantic 文档：配置](https://pydantic.dev/docs/validation/latest/api/pydantic/config/)。 你可以设置 `"json_schema_extra"`，其值为一个 `dict`，包含你希望出现在生成 JSON Schema 中的任意附加数据，包括 `examples`。 diff --git a/docs/zh/docs/tutorial/security/first-steps.md b/docs/zh/docs/tutorial/security/first-steps.md index ca3ef83..5274582 100644 --- a/docs/zh/docs/tutorial/security/first-steps.md +++ b/docs/zh/docs/tutorial/security/first-steps.md @@ -1,6 +1,5 @@ # 安全 - 第一步 { #security-first-steps } - 假设你的**后端** API 位于某个域名下。 而**前端**在另一个域名，或同一域名的不同路径（或在移动应用中）。 @@ -27,14 +26,14 @@ /// note | 注意 -当你使用命令 `pip install "fastapi[standard]"` 安装 **FastAPI** 时，[`python-multipart`](https://github.com/Kludex/python-multipart) 包会自动安装。 +当你运行 `uv add "fastapi[standard]"` 命令时，[`python-multipart`](https://github.com/Kludex/python-multipart) 包会随 **FastAPI** 自动安装。 -但是，如果你使用 `pip install fastapi`，默认不会包含 `python-multipart` 包。 +但是，如果你使用 `uv add fastapi` 命令，默认不会包含 `python-multipart` 包。 -如需手动安装，请先创建[虚拟环境](../../virtual-environments.md)、激活它，然后执行： +如需手动安装，请把它添加到你的项目中： ```console -$ pip install python-multipart +$ uv add python-multipart ``` 这是因为 **OAuth2** 使用“表单数据”来发送 `username` 和 `password`。 @@ -46,7 +45,7 @@ $ pip install python-multipart
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -145,7 +144,7 @@ OAuth2 的设计目标是让后端或 API 与负责用户认证的服务器解 /// -这个参数不会创建该端点/*路径操作*，而是声明客户端应使用 `/token` 这个 URL 来获取令牌。这些信息会用于 OpenAPI，进而用于交互式 API 文档系统。 +这个参数不会创建该端点 / *路径操作*，而是声明客户端应使用 `/token` 这个 URL 来获取令牌。这些信息会用于 OpenAPI，进而用于交互式 API 文档系统。 我们很快也会创建对应的实际路径操作。 diff --git a/docs/zh/docs/tutorial/security/oauth2-jwt.md b/docs/zh/docs/tutorial/security/oauth2-jwt.md index 418b3b9..ae26082 100644 --- a/docs/zh/docs/tutorial/security/oauth2-jwt.md +++ b/docs/zh/docs/tutorial/security/oauth2-jwt.md @@ -30,12 +30,12 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4 我们需要安装 `PyJWT`，以便在 Python 中生成和校验 JWT 令牌。 -请确保创建并激活一个[虚拟环境](../../virtual-environments.md)，然后安装 `pyjwt`： +将 `pyjwt` 添加到你的项目：
```console -$ pip install pyjwt +$ uv add pyjwt ---> 100% ``` @@ -72,12 +72,12 @@ pwdlib 是一个用于处理密码哈希的优秀 Python 包。 推荐的算法是 “Argon2”。 -请确保创建并激活一个[虚拟环境](../../virtual-environments.md)，然后安装带 Argon2 的 pwdlib： +将带 Argon2 的 `pwdlib` 添加到你的项目：
```console -$ pip install "pwdlib[argon2]" +$ uv add "pwdlib[argon2]" ---> 100% ``` diff --git a/docs/zh/docs/tutorial/sql-databases.md b/docs/zh/docs/tutorial/sql-databases.md index 1d6a3cd..01a787f 100644 --- a/docs/zh/docs/tutorial/sql-databases.md +++ b/docs/zh/docs/tutorial/sql-databases.md @@ -34,12 +34,12 @@ ## 安装 `SQLModel` { #install-sqlmodel } -首先，确保你创建并激活了[虚拟环境](../virtual-environments.md)，然后安装 `sqlmodel`： +将 `sqlmodel` 添加到你的项目中：
```console -$ pip install sqlmodel +$ uv add sqlmodel ---> 100% ``` @@ -152,7 +152,7 @@ SQLModel 将会拥有封装 Alembic 的迁移工具，但目前你可以直接
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -337,7 +337,7 @@ $ fastapi dev
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/zh/docs/tutorial/static-files.md b/docs/zh/docs/tutorial/static-files.md index b700f46..82c0803 100644 --- a/docs/zh/docs/tutorial/static-files.md +++ b/docs/zh/docs/tutorial/static-files.md @@ -45,4 +45,4 @@ ## 更多信息 { #more-info } -更多细节和选项请查阅 [Starlette 的静态文件文档](https://www.starlette.dev/staticfiles/)。 +更多细节和选项请查阅 [Starlette 的静态文件文档](https://starlette.dev/staticfiles/)。 diff --git a/docs/zh/docs/tutorial/testing.md b/docs/zh/docs/tutorial/testing.md index 79e5044..c878d0f 100644 --- a/docs/zh/docs/tutorial/testing.md +++ b/docs/zh/docs/tutorial/testing.md @@ -1,6 +1,6 @@ # 测试 { #testing } -感谢 [Starlette](https://www.starlette.dev/testclient/)，测试**FastAPI** 应用轻松又愉快。 +感谢 [Starlette](https://starlette.dev/testclient/)，测试**FastAPI** 应用轻松又愉快。 它基于 [HTTPX](https://www.python-httpx.org)，而HTTPX又是基于Requests设计的，所以很相似且易懂。 @@ -12,10 +12,10 @@ 要使用 `TestClient`，先要安装 [`httpx`](https://www.python-httpx.org)。 -确保你创建并激活一个[虚拟环境](../virtual-environments.md)，然后再安装，例如： +将它添加到你的项目中： ```console -$ pip install httpx +$ uv add httpx ``` /// @@ -156,12 +156,12 @@ $ pip install httpx 之后，你只需要安装 `pytest`。 -确保你创建并激活一个[虚拟环境](../virtual-environments.md)，然后再安装，例如： +将它添加到你的项目中：
```console -$ pip install pytest +$ uv add pytest ---> 100% ``` @@ -175,7 +175,7 @@ $ pip install pytest
```console -$ pytest +$ uv run pytest ================ test session starts ================ platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1 diff --git a/docs/zh/docs/virtual-environments.md b/docs/zh/docs/virtual-environments.md index a31240d..a81efc6 100644 --- a/docs/zh/docs/virtual-environments.md +++ b/docs/zh/docs/virtual-environments.md @@ -1,864 +1,35 @@ # 虚拟环境 { #virtual-environments } -当你在 Python 工程中工作时，你可能会有必要用到一个**虚拟环境**（或类似的机制）来隔离你为每个工程安装的包。 +当你在 Python 工程中工作时，你应该使用**虚拟环境**来隔离为每个工程安装的包。 -/// note | 注意 +对于 FastAPI 工程，我推荐使用 [uv](https://docs.astral.sh/uv/) 来管理工程、依赖项和虚拟环境。 -如果你已经了解虚拟环境，知道如何创建和使用它们，你可以考虑跳过这一部分。🤓 +## 创建工程 { #create-a-project } -/// - -/// tip | 提示 - -**虚拟环境**和**环境变量**是不同的。 - -**环境变量**是系统中的一个变量，可以被程序使用。 - -**虚拟环境**是一个包含一些文件的目录。 - -/// - -/// note | 注意 - -这个页面将教你如何使用**虚拟环境**以及了解它们的工作原理。 - -如果你计划使用一个**可以为你管理一切的工具**（包括安装 Python），试试 [uv](https://github.com/astral-sh/uv)。 - -/// - -## 创建一个工程 { #create-a-project } - -首先，为你的工程创建一个目录。 - -我通常会在我的主目录下创建一个名为 `code` 的目录。 - -在这个目录下，我再为每个工程创建一个目录。 +使用[官方安装指南](https://docs.astral.sh/uv/getting-started/installation/)安装 `uv`，然后创建一个工程：
```console -// 进入主目录 -$ cd -// 创建一个用于存放所有代码工程的目录 -$ mkdir code -// 进入 code 目录 -$ cd code -// 创建一个用于存放这个工程的目录 -$ mkdir awesome-project -// 进入这个工程的目录 +$ uv init awesome-project --bare $ cd awesome-project +$ uv add "fastapi[standard]" ```
-## 创建一个虚拟环境 { #create-a-virtual-environment } +`uv` 会自动为工程创建虚拟环境。你不需要自己创建或激活虚拟环境。 -在开始一个 Python 工程的**第一时间**，**在你的工程内部**创建一个虚拟环境。 - -/// tip | 提示 - -你只需要 **在每个工程中操作一次**，而不是每次工作时都操作。 - -/// - -//// tab | `venv` - -你可以使用 Python 自带的 `venv` 模块来创建一个虚拟环境。 +使用 `uv run` 在工程环境中运行命令，例如：
```console -$ python -m venv .venv +$ uv run fastapi dev ```
-/// details | 上述命令的含义 +## 了解更多 { #learn-more } -* `python`: 使用名为 `python` 的程序 -* `-m`: 以脚本的方式调用一个模块，我们将告诉它接下来使用哪个模块 -* `venv`: 使用名为 `venv` 的模块，这个模块通常随 Python 一起安装 -* `.venv`: 在新目录 `.venv` 中创建虚拟环境 - -/// - -//// - -//// tab | `uv` - -如果你安装了 [`uv`](https://github.com/astral-sh/uv)，你也可以使用它来创建一个虚拟环境。 - -
- -```console -$ uv venv -``` - -
- -/// tip | 提示 - -默认情况下，`uv` 会在一个名为 `.venv` 的目录中创建一个虚拟环境。 - -但你可以通过传递一个额外的参数来自定义它，指定目录的名称。 - -/// - -//// - -这个命令会在一个名为 `.venv` 的目录中创建一个新的虚拟环境。 - -/// details | `.venv`，或是其他名称 - -你可以在不同的目录下创建虚拟环境，但通常我们会把它命名为 `.venv`。 - -/// - -## 激活虚拟环境 { #activate-the-virtual-environment } - -激活新的虚拟环境来确保你运行的任何 Python 命令或安装的包都能使用到它。 - -/// tip | 提示 - -**每次**开始一个 **新的终端会话** 来工作在这个工程时，你都需要执行这个操作。 - -/// - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -或者，如果你在 Windows 上使用 Bash（例如 [Git Bash](https://gitforwindows.org/)）： - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -/// tip | 提示 - -每次你在这个环境中安装一个 **新的包** 时，都需要 **重新激活** 这个环境。 - -这么做确保了当你使用一个由这个包安装的 **终端（CLI）程序** 时，你使用的是你的虚拟环境中的程序，而不是全局安装、可能版本不同的程序。 - -/// - -## 检查虚拟环境是否激活 { #check-the-virtual-environment-is-active } - -检查虚拟环境是否激活 (前面的命令是否生效)。 - -/// tip | 提示 - -这是 **可选的**，但这是一个很好的方法，可以 **检查** 一切是否按预期工作，以及你是否使用了你打算使用的虚拟环境。 - -/// - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -如果它显示了在你工程 (在这个例子中是 `awesome-project`) 的 `.venv/bin/python` 中的 `python` 二进制文件，那么它就生效了。🎉 - -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -如果它显示了在你工程 (在这个例子中是 `awesome-project`) 的 `.venv\Scripts\python` 中的 `python` 二进制文件，那么它就生效了。🎉 - -//// - -## 升级 `pip` { #upgrade-pip } - -/// tip | 提示 - -如果你使用 [`uv`](https://github.com/astral-sh/uv) 来安装内容，而不是 `pip`，那么你就不需要升级 `pip`。😎 - -/// - -如果你使用 `pip` 来安装包（它是 Python 的默认组件），你应该将它 **升级** 到最新版本。 - -在安装包时出现的许多奇怪的错误都可以通过先升级 `pip` 来解决。 - -/// tip | 提示 - -通常你只需要在创建虚拟环境后 **执行一次** 这个操作。 - -/// - -确保虚拟环境是激活的 (使用上面的命令)，然后运行： - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip | 提示 - -有时在尝试升级 pip 时，你可能会遇到 **`No module named pip`** 错误。 - -如果发生这种情况，使用下面的命令来安装并升级 pip： - -
- -```console -$ python -m ensurepip --upgrade - ----> 100% -``` - -
- -该命令会在尚未安装 pip 时进行安装，并确保安装的 pip 版本不早于 `ensurepip` 提供的版本。 - -/// - -## 添加 `.gitignore` { #add-gitignore } - -如果你使用 **Git** (这是你应该使用的)，添加一个 `.gitignore` 文件来排除你的 `.venv` 中的所有内容。 - -/// tip | 提示 - -如果你使用 [`uv`](https://github.com/astral-sh/uv) 来创建虚拟环境，它会自动为你完成这个操作，你可以跳过这一步。😎 - -/// - -/// tip | 提示 - -通常你只需要在创建虚拟环境后 **执行一次** 这个操作。 - -/// - -
- -```console -$ echo "*" > .venv/.gitignore -``` - -
- -/// details | 上述命令的含义 - -* `echo "*"`: 将在终端中 "打印" 文本 `*`（接下来的部分会对这个操作进行一些修改） -* `>`: 使左边的命令打印到终端的任何内容实际上都不会被打印，而是会被写入到右边的文件中 -* `.gitignore`: 被写入文本的文件的名称 - -而 `*` 对于 Git 来说意味着 "所有内容"。所以，它会忽略 `.venv` 目录中的所有内容。 - -该命令会创建一个名为 `.gitignore` 的文件，内容如下： - -```gitignore -* -``` - -/// - -## 安装软件包 { #install-packages } - -在激活虚拟环境后，你可以在其中安装软件包。 - -/// tip | 提示 - -当你需要安装或升级软件包时，执行本操作**一次**； - -如果你需要再升级版本或添加新软件包，你可以**再次执行此操作**。 - -/// - -### 直接安装包 { #install-packages-directly } - -如果你急于安装，不想使用文件来声明工程的软件包依赖，你可以直接安装它们。 - -/// tip | 提示 - -将程序所需的软件包及其版本放在文件中（例如 `requirements.txt` 或 `pyproject.toml`）是个好（并且非常好）的主意。 - -/// - -//// tab | `pip` - -
- -```console -$ pip install "fastapi[standard]" - ----> 100% -``` - -
- -//// - -//// tab | `uv` - -如果你有 [`uv`](https://github.com/astral-sh/uv): - -
- -```console -$ uv pip install "fastapi[standard]" ----> 100% -``` - -
- -//// - -### 从 `requirements.txt` 安装 { #install-from-requirements-txt } - -如果你有一个 `requirements.txt` 文件，你可以使用它来安装其中的软件包。 - -//// tab | `pip` - -
- -```console -$ pip install -r requirements.txt ----> 100% -``` - -
- -//// - -//// tab | `uv` - -如果你有 [`uv`](https://github.com/astral-sh/uv): - -
- -```console -$ uv pip install -r requirements.txt ----> 100% -``` - -
- -//// - -/// details | 关于 `requirements.txt` - -一个包含一些软件包的 `requirements.txt` 文件看起来应该是这样的： - -```requirements.txt -fastapi[standard]==0.113.0 -pydantic==2.8.0 -``` - -/// - -## 运行程序 { #run-your-program } - -在你激活虚拟环境后，你可以运行你的程序，它将使用虚拟环境中的 Python 和你在其中安装的软件包。 - -
- -```console -$ python main.py - -Hello World -``` - -
- -## 配置编辑器 { #configure-your-editor } - -你可能会用到编辑器，请确保配置它使用与你创建的相同的虚拟环境（它可能会自动检测到），以便你可以获得自动补全和内联错误提示。 - -例如： - -* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) -* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) - -/// tip | 提示 - -通常你只需要在创建虚拟环境时执行此操作**一次**。 - -/// - -## 退出虚拟环境 { #deactivate-the-virtual-environment } - -当你完成工作后，你可以**退出**虚拟环境。 - -
- -```console -$ deactivate -``` - -
- -这样，当你运行 `python` 时，它不会尝试从那个虚拟环境及其已安装的软件包中运行。 - -## 开始工作 { #ready-to-work } - -现在你已经准备好开始你的工作了。 - - - -/// tip | 提示 - -你想要理解上面的所有内容吗？ - -继续阅读。👇🤓 - -/// - -## 为什么要使用虚拟环境 { #why-virtual-environments } - -你需要安装 [Python](https://www.python.org/) 才能使用 FastAPI。 - -之后，你需要**安装** FastAPI 和你想要使用的任何其他**软件包**。 - -要安装软件包，你通常会使用随 Python 一起提供的 `pip` 命令（或类似的替代方案）。 - -然而，如果你直接使用 `pip`，软件包将被安装在你的**全局 Python 环境**中（即 Python 的全局安装）。 - -### 存在的问题 { #the-problem } - -那么，在全局 Python 环境中安装软件包有什么问题呢？ - -有些时候，你可能会编写许多不同的程序，这些程序依赖于**不同的软件包**；你所做的一些工程也会依赖于**同一软件包的不同版本**。😱 - -例如，你可能会创建一个名为 `philosophers-stone` 的工程，这个程序依赖于另一个名为 **`harry` 的软件包，使用版本 `1`**。因此，你需要安装 `harry`。 - -```mermaid -flowchart LR - stone(philosophers-stone) -->|需要| harry-1[harry v1] -``` - -然而在此之后，你又创建了另一个名为 `prisoner-of-azkaban` 的工程，这个工程也依赖于 `harry`，但是这个工程需要 **`harry` 版本 `3`**。 - -```mermaid -flowchart LR - azkaban(prisoner-of-azkaban) --> |需要| harry-3[harry v3] -``` - -那么现在的问题是，如果你将软件包安装在全局环境中而不是在本地**虚拟环境**中，你将不得不面临选择安装哪个版本的 `harry` 的问题。 - -如果你想运行 `philosophers-stone`，你需要首先安装 `harry` 版本 `1`，例如： - -
- -```console -$ pip install "harry==1" -``` - -
- -然后你将在全局 Python 环境中安装 `harry` 版本 `1`。 - -```mermaid -flowchart LR - subgraph global[全局环境] - harry-1[harry v1] - end - subgraph stone-project[工程 philosophers-stone] - stone(philosophers-stone) -->|需要| harry-1 - end -``` - -但是如果你想运行 `prisoner-of-azkaban`，你需要卸载 `harry` 版本 `1` 并安装 `harry` 版本 `3`（或者说，只要你安装版本 `3` ，版本 `1` 就会自动卸载）。 - -
- -```console -$ pip install "harry==3" -``` - -
- -于是，你在你的全局 Python 环境中安装了 `harry` 版本 `3`。 - -如果你再次尝试运行 `philosophers-stone`，有可能它**无法正常工作**，因为它需要 `harry` 版本 `1`。 - -```mermaid -flowchart LR - subgraph global[全局环境] - harry-1[harry v1] - style harry-1 fill:#ccc,stroke-dasharray: 5 5 - harry-3[harry v3] - end - subgraph stone-project[工程 philosophers-stone] - stone(philosophers-stone) -.-x|⛔️| harry-1 - end - subgraph azkaban-project[工程 prisoner-of-azkaban] - azkaban(prisoner-of-azkaban) --> |需要| harry-3 - end -``` - -/// tip | 提示 - -Python 包在推出**新版本**时通常会尽量**避免破坏性更改**，但最好还是要小心，要想清楚再安装新版本，而且在运行测试以确保一切能正常工作时再安装。 - -/// - -现在，想象一下，如果有**许多**其他**软件包**，它们都是你的**工程所依赖的**。这是非常难以管理的。你可能会发现，有些工程使用了一些**不兼容的软件包版本**，而不知道为什么某些东西无法正常工作。 - -此外，取决于你的操作系统（例如 Linux、Windows、macOS），它可能已经预先安装了 Python。在这种情况下，它可能已经预先安装了一些软件包，这些软件包的特定版本是**系统所需的**。如果你在全局 Python 环境中安装软件包，你可能会**破坏**一些随操作系统一起安装的程序。 - -## 软件包安装在哪里 { #where-are-packages-installed } - -当你安装 Python 时，它会在你的计算机上创建一些目录，并在这些目录中放一些文件。 - -其中一些目录负责存放你安装的所有软件包。 - -当你运行： - -
- -```console -// 先别去运行这个命令，这只是一个示例 🤓 -$ pip install "fastapi[standard]" ----> 100% -``` - -
- -这将会从 [PyPI](https://pypi.org/project/fastapi/) 下载一个压缩文件，其中包含 FastAPI 代码。 - -它还会**下载** FastAPI 依赖的其他软件包的文件。 - -然后它会**解压**所有这些文件，并将它们放在你的计算机上的一个目录中。 - -默认情况下，它会将下载并解压的这些文件放在随 Python 安装的目录中，这就是**全局环境**。 - -## 什么是虚拟环境 { #what-are-virtual-environments } - -解决软件包都安装在全局环境中的问题的方法是为你所做的每个工程使用一个**虚拟环境**。 - -虚拟环境是一个**目录**，与全局环境非常相似，你可以在其中专为某个工程安装软件包。 - -这样，每个工程都会有自己的虚拟环境（`.venv` 目录），其中包含自己的软件包。 - -```mermaid -flowchart TB - subgraph stone-project[工程 philosophers-stone] - stone(philosophers-stone) --->|需要| harry-1 - subgraph venv1[.venv] - harry-1[harry v1] - end - end - subgraph azkaban-project[工程 prisoner-of-azkaban] - azkaban(prisoner-of-azkaban) --->|需要| harry-3 - subgraph venv2[.venv] - harry-3[harry v3] - end - end - stone-project ~~~ azkaban-project -``` - -## 激活虚拟环境意味着什么 { #what-does-activating-a-virtual-environment-mean } - -当你激活了一个虚拟环境，例如： - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -或者如果你在 Windows 上使用 Bash（例如 [Git Bash](https://gitforwindows.org/)）： - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -这个命令会创建或修改一些[环境变量](environment-variables.md)，这些环境变量将在接下来的命令中可用。 - -其中之一是 `PATH` 变量。 - -/// tip | 提示 - -你可以在 [环境变量](environment-variables.md#path-environment-variable) 部分了解更多关于 `PATH` 环境变量的内容。 - -/// - -激活虚拟环境会将其路径 `.venv/bin`（在 Linux 和 macOS 上）或 `.venv\Scripts`（在 Windows 上）添加到 `PATH` 环境变量中。 - -假设在激活环境之前，`PATH` 变量看起来像这样： - -//// tab | Linux, macOS - -```plaintext -/usr/bin:/bin:/usr/sbin:/sbin -``` - -这意味着系统会在以下目录中查找程序： - -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Windows\System32 -``` - -这意味着系统会在以下目录中查找程序： - -* `C:\Windows\System32` - -//// - -激活虚拟环境后，`PATH` 变量会变成这样： - -//// tab | Linux, macOS - -```plaintext -/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -这意味着系统现在会首先在以下目录中查找程序： - -```plaintext -/home/user/code/awesome-project/.venv/bin -``` - -然后再在其他目录中查找。 - -因此，当你在终端中输入 `python` 时，系统会在以下目录中找到 Python 程序： - -```plaintext -/home/user/code/awesome-project/.venv/bin/python -``` - -并使用这个。 - -//// - -//// tab | Windows - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32 -``` - -这意味着系统现在会首先在以下目录中查找程序： - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts -``` - -然后再在其他目录中查找。 - -因此，当你在终端中输入 `python` 时，系统会在以下目录中找到 Python 程序： - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -并使用这个。 - -//// - -一个重要的细节是，虚拟环境路径会被放在 `PATH` 变量的**开头**。系统会在找到任何其他可用的 Python **之前**找到它。这样，当你运行 `python` 时，它会使用**虚拟环境中**的 Python，而不是任何其他 `python`（例如，全局环境中的 `python`）。 - -激活虚拟环境还会改变其他一些东西，但这是它所做的最重要的事情之一。 - -## 检查虚拟环境 { #checking-a-virtual-environment } - -当你检查虚拟环境是否激活时，例如： - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -//// - -这意味着将使用的 `python` 程序是**在虚拟环境中**的那个。 - -在 Linux 和 macOS 中使用 `which`，在 Windows PowerShell 中使用 `Get-Command`。 - -这个命令的工作方式是，它会在 `PATH` 环境变量中查找，按顺序**逐个路径**查找名为 `python` 的程序。一旦找到，它会**显示该程序的路径**。 - -最重要的部分是，当你调用 `python` 时，将执行的就是这个确切的 "`python`"。 - -因此，你可以确认你是否在正确的虚拟环境中。 - -/// tip | 提示 - -激活一个虚拟环境，获取一个 Python，然后**转到另一个工程**是一件很容易的事情； - -但如果第二个工程**无法工作**，那是因为你使用了来自另一个工程的虚拟环境的、**不正确的 Python**。 - -因此，会检查正在使用的 `python` 是很有用的。🤓 - -/// - -## 为什么要停用虚拟环境 { #why-deactivate-a-virtual-environment } - -例如，你可能正在一个工程 `philosophers-stone` 上工作，**激活了该虚拟环境**，安装了包并使用了该环境， - -然后你想要在**另一个工程** `prisoner-of-azkaban` 上工作， - -你进入那个工程： - -
- -```console -$ cd ~/code/prisoner-of-azkaban -``` - -
- -如果你不去停用 `philosophers-stone` 的虚拟环境，当你在终端中运行 `python` 时，它会尝试使用 `philosophers-stone` 中的 Python。 - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -$ python main.py - -// 导入 sirius 报错，它没有安装 😱 -Traceback (most recent call last): - File "main.py", line 1, in - import sirius -``` - -
- -但是如果你停用虚拟环境并激活 `prisoner-of-azkaban` 的新虚拟环境，那么当你运行 `python` 时，它会使用 `prisoner-of-azkaban` 中的虚拟环境中的 Python。 - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -// 你不需要在旧目录中操作停用，你可以在任何地方操作停用，甚至在转到另一个工程之后 😎 -$ deactivate - -// 激活 prisoner-of-azkaban/.venv 中的虚拟环境 🚀 -$ source .venv/bin/activate - -// 现在当你运行 python 时，它会在这个虚拟环境中找到安装的 sirius 包 ✨ -$ python main.py - -I solemnly swear 🐺 -``` - -
- -## 替代方案 { #alternatives } - -这是一个简单的指南，可以帮助你入门并教会你如何理解一切**底层**的东西。 - -有许多**替代方案**来管理虚拟环境、包依赖（requirements）、工程。 - -一旦你准备好并想要使用一个工具来**管理整个工程**、包依赖、虚拟环境等，建议你尝试 [uv](https://github.com/astral-sh/uv)。 - -`uv` 可以做很多事情，它可以： - -* 为你**安装 Python**，包括不同的版本 -* 为你的工程管理**虚拟环境** -* 安装**软件包** -* 为你的工程管理软件包的**依赖和版本** -* 确保你有一个**确切**的软件包和版本集合来安装，包括它们的依赖项，这样你就可以确保在生产中运行你的工程与在开发时在你的计算机上运行的工程完全相同，这被称为**锁定** -* 还有很多其他功能 - -## 结论 { #conclusion } - -如果你读过并理解了所有这些，现在**你对虚拟环境的了解比很多开发者都要多**。🤓 - -在未来当你调试看起来复杂的东西时，了解这些细节很可能会有用，你会知道**它是如何在底层工作的**。😎 +阅读[虚拟环境指南](https://tiangolo.com/guides/virtual-environments/)以了解虚拟环境在底层是如何工作的，包括激活以及替代的 `python -m venv` 和 `pip` 工作流。