diff --git a/.github/workflows/latest-changes.yml b/.github/workflows/latest-changes.yml index 16da3bc63..b8b5c42ee 100644 --- a/.github/workflows/latest-changes.yml +++ b/.github/workflows/latest-changes.yml @@ -34,7 +34,7 @@ jobs: if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug_enabled == 'true' }} with: limit-access-to-actor: true - - uses: tiangolo/latest-changes@0.3.1 + - uses: tiangolo/latest-changes@0.3.2 with: token: ${{ secrets.GITHUB_TOKEN }} latest_changes_file: docs/en/docs/release-notes.md diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index d90e7281e..3869328a7 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -14,7 +14,7 @@ repos: - id: end-of-file-fixer - id: trailing-whitespace - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.7.2 + rev: v0.7.3 hooks: - id: ruff args: diff --git a/docs/de/docs/advanced/additional-responses.md b/docs/de/docs/advanced/additional-responses.md index a87c56491..bf38d9795 100644 --- a/docs/de/docs/advanced/additional-responses.md +++ b/docs/de/docs/advanced/additional-responses.md @@ -1,6 +1,6 @@ # Zusätzliche Responses in OpenAPI -/// warning | "Achtung" +/// warning | Achtung Dies ist ein eher fortgeschrittenes Thema. @@ -26,11 +26,9 @@ Jedes dieser Response-`dict`s kann einen Schlüssel `model` haben, welcher ein P Um beispielsweise eine weitere Response mit dem Statuscode `404` und einem Pydantic-Modell `Message` zu deklarieren, können Sie schreiben: -```Python hl_lines="18 22" -{!../../docs_src/additional_responses/tutorial001.py!} -``` +{* ../../docs_src/additional_responses/tutorial001.py hl[18,22] *} -/// note | "Hinweis" +/// note | Hinweis Beachten Sie, dass Sie die `JSONResponse` direkt zurückgeben müssen. @@ -177,11 +175,9 @@ Sie können denselben `responses`-Parameter verwenden, um verschiedene Medientyp Sie können beispielsweise einen zusätzlichen Medientyp `image/png` hinzufügen und damit deklarieren, dass Ihre *Pfadoperation* ein JSON-Objekt (mit dem Medientyp `application/json`) oder ein PNG-Bild zurückgeben kann: -```Python hl_lines="19-24 28" -{!../../docs_src/additional_responses/tutorial002.py!} -``` +{* ../../docs_src/additional_responses/tutorial002.py hl[19:24,28] *} -/// note | "Hinweis" +/// note | Hinweis Beachten Sie, dass Sie das Bild direkt mit einer `FileResponse` zurückgeben müssen. @@ -207,9 +203,7 @@ Sie können beispielsweise eine Response mit dem Statuscode `404` deklarieren, d Und eine Response mit dem Statuscode `200`, die Ihr `response_model` verwendet, aber ein benutzerdefiniertes Beispiel (`example`) enthält: -```Python hl_lines="20-31" -{!../../docs_src/additional_responses/tutorial003.py!} -``` +{* ../../docs_src/additional_responses/tutorial003.py hl[20:31] *} Es wird alles kombiniert und in Ihre OpenAPI eingebunden und in der API-Dokumentation angezeigt: @@ -243,9 +237,7 @@ Mit dieser Technik können Sie einige vordefinierte Responses in Ihren *Pfadoper Zum Beispiel: -```Python hl_lines="13-17 26" -{!../../docs_src/additional_responses/tutorial004.py!} -``` +{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *} ## Weitere Informationen zu OpenAPI-Responses diff --git a/docs/de/docs/advanced/additional-status-codes.md b/docs/de/docs/advanced/additional-status-codes.md index fc8d09e4c..50702e7e6 100644 --- a/docs/de/docs/advanced/additional-status-codes.md +++ b/docs/de/docs/advanced/additional-status-codes.md @@ -40,7 +40,7 @@ Um dies zu erreichen, importieren Sie `JSONResponse`, und geben Sie Ihren Inhalt //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -54,7 +54,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -66,7 +66,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// -/// warning | "Achtung" +/// warning | Achtung Wenn Sie eine `Response` direkt zurückgeben, wie im obigen Beispiel, wird sie direkt zurückgegeben. @@ -76,7 +76,7 @@ Stellen Sie sicher, dass sie die gewünschten Daten enthält und dass die Werte /// -/// note | "Technische Details" +/// note | Technische Details Sie können auch `from starlette.responses import JSONResponse` verwenden. diff --git a/docs/de/docs/advanced/advanced-dependencies.md b/docs/de/docs/advanced/advanced-dependencies.md index 54351714e..80cbf1fd3 100644 --- a/docs/de/docs/advanced/advanced-dependencies.md +++ b/docs/de/docs/advanced/advanced-dependencies.md @@ -36,7 +36,7 @@ Dazu deklarieren wir eine Methode `__call__`: //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -72,7 +72,7 @@ Und jetzt können wir `__init__` verwenden, um die Parameter der Instanz zu dekl //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -108,7 +108,7 @@ Wir könnten eine Instanz dieser Klasse erstellen mit: //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -152,7 +152,7 @@ checker(q="somequery") //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -164,7 +164,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// -/// tip | "Tipp" +/// tip | Tipp Das alles mag gekünstelt wirken. Und es ist möglicherweise noch nicht ganz klar, welchen Nutzen das hat. diff --git a/docs/de/docs/advanced/async-tests.md b/docs/de/docs/advanced/async-tests.md index 6c1981e25..c118e588f 100644 --- a/docs/de/docs/advanced/async-tests.md +++ b/docs/de/docs/advanced/async-tests.md @@ -62,7 +62,7 @@ Der Marker `@pytest.mark.anyio` teilt pytest mit, dass diese Testfunktion asynch {* ../../docs_src/async_tests/test_main.py hl[7] *} -/// tip | "Tipp" +/// tip | Tipp Beachten Sie, dass die Testfunktion jetzt `async def` ist und nicht nur `def` wie zuvor, wenn Sie den `TestClient` verwenden. @@ -80,13 +80,13 @@ response = client.get('/') ... welches wir verwendet haben, um unsere Requests mit dem `TestClient` zu machen. -/// tip | "Tipp" +/// tip | Tipp Beachten Sie, dass wir async/await mit dem neuen `AsyncClient` verwenden – der Request ist asynchron. /// -/// warning | "Achtung" +/// warning | Achtung Falls Ihre Anwendung auf Lifespan-Events angewiesen ist, der `AsyncClient` löst diese Events nicht aus. Um sicherzustellen, dass sie ausgelöst werden, verwenden Sie `LifespanManager` von florimondmanca/asgi-lifespan. @@ -96,7 +96,7 @@ Falls Ihre Anwendung auf Lifespan-Events angewiesen ist, der `AsyncClient` löst Da die Testfunktion jetzt asynchron ist, können Sie in Ihren Tests neben dem Senden von Requests an Ihre FastAPI-Anwendung jetzt auch andere `async`hrone Funktionen aufrufen (und `await`en), genau so, wie Sie diese an anderer Stelle in Ihrem Code aufrufen würden. -/// tip | "Tipp" +/// tip | Tipp Wenn Sie einen `RuntimeError: Task attached to a different loop` erhalten, wenn Sie asynchrone Funktionsaufrufe in Ihre Tests integrieren (z. B. bei Verwendung von MongoDBs MotorClient), dann denken Sie daran, Objekte zu instanziieren, die einen Event Loop nur innerhalb asynchroner Funktionen benötigen, z. B. einen `@app.on_event("startup")`-Callback. diff --git a/docs/de/docs/advanced/behind-a-proxy.md b/docs/de/docs/advanced/behind-a-proxy.md index 74b25308a..9da18a626 100644 --- a/docs/de/docs/advanced/behind-a-proxy.md +++ b/docs/de/docs/advanced/behind-a-proxy.md @@ -43,7 +43,7 @@ browser --> proxy proxy --> server ``` -/// tip | "Tipp" +/// tip | Tipp Die IP `0.0.0.0` wird üblicherweise verwendet, um anzudeuten, dass das Programm alle auf diesem Computer/Server verfügbaren IPs abhört. @@ -84,7 +84,7 @@ $ uvicorn main:app --root-path /api/v1 Falls Sie Hypercorn verwenden, das hat auch die Option `--root-path`. -/// note | "Technische Details" +/// note | Technische Details Die ASGI-Spezifikation definiert einen `root_path` für diesen Anwendungsfall. @@ -178,7 +178,7 @@ Dann erstellen Sie eine Datei `traefik.toml` mit: Dadurch wird Traefik angewiesen, Port 9999 abzuhören und eine andere Datei `routes.toml` zu verwenden. -/// tip | "Tipp" +/// tip | Tipp Wir verwenden Port 9999 anstelle des Standard-HTTP-Ports 80, damit Sie ihn nicht mit Administratorrechten (`sudo`) ausführen müssen. @@ -248,7 +248,7 @@ Wenn Sie nun zur URL mit dem Port für Uvicorn gehen: -/// tip | "Tipp" +/// tip | Tipp Die Dokumentationsoberfläche interagiert mit dem von Ihnen ausgewählten Server. diff --git a/docs/de/docs/advanced/custom-response.md b/docs/de/docs/advanced/custom-response.md index 357d2c562..7738bfca4 100644 --- a/docs/de/docs/advanced/custom-response.md +++ b/docs/de/docs/advanced/custom-response.md @@ -12,7 +12,7 @@ Der Inhalt, den Sie von Ihrer *Pfadoperation-Funktion* zurückgeben, wird in die Und wenn diese `Response` einen JSON-Medientyp (`application/json`) hat, wie es bei `JSONResponse` und `UJSONResponse` der Fall ist, werden die von Ihnen zurückgegebenen Daten automatisch mit jedem Pydantic `response_model` konvertiert (und gefiltert), das Sie im *Pfadoperation-Dekorator* deklariert haben. -/// note | "Hinweis" +/// note | Hinweis Wenn Sie eine Response-Klasse ohne Medientyp verwenden, erwartet FastAPI, dass Ihre Response keinen Inhalt hat, und dokumentiert daher das Format der Response nicht in deren generierter OpenAPI-Dokumentation. @@ -44,7 +44,7 @@ Und er wird als solcher in OpenAPI dokumentiert. /// -/// tip | "Tipp" +/// tip | Tipp Die `ORJSONResponse` ist derzeit nur in FastAPI verfügbar, nicht in Starlette. @@ -81,7 +81,7 @@ Das gleiche Beispiel von oben, das eine `HTMLResponse` zurückgibt, könnte so a {!../../docs_src/custom_response/tutorial003.py!} ``` -/// warning | "Achtung" +/// warning | Achtung Eine `Response`, die direkt von Ihrer *Pfadoperation-Funktion* zurückgegeben wird, wird in OpenAPI nicht dokumentiert (zum Beispiel wird der `Content-Type` nicht dokumentiert) und ist in der automatischen interaktiven Dokumentation nicht sichtbar. @@ -121,7 +121,7 @@ Hier sind einige der verfügbaren Responses. Bedenken Sie, dass Sie `Response` verwenden können, um alles andere zurückzugeben, oder sogar eine benutzerdefinierte Unterklasse zu erstellen. -/// note | "Technische Details" +/// note | Technische Details Sie können auch `from starlette.responses import HTMLResponse` verwenden. @@ -174,7 +174,7 @@ Eine schnelle alternative JSON-Response mit `ujson`. -/// warning | "Achtung" +/// warning | Achtung `ujson` ist bei der Behandlung einiger Sonderfälle weniger sorgfältig als Pythons eingebaute Implementierung. @@ -184,7 +184,7 @@ Eine alternative JSON-Response mit `dataclasses`: -```Python hl_lines="1 7-12 19-20" -{!../../docs_src/dataclasses/tutorial001.py!} -``` +{* ../../docs_src/dataclasses/tutorial001.py hl[1,7:12,19:20] *} Das ist dank **Pydantic** ebenfalls möglich, da es `dataclasses` intern unterstützt. @@ -34,9 +32,7 @@ Wenn Sie jedoch eine Menge Datenklassen herumliegen haben, ist dies ein guter Tr Sie können `dataclasses` auch im Parameter `response_model` verwenden: -```Python hl_lines="1 7-13 19" -{!../../docs_src/dataclasses/tutorial002.py!} -``` +{* ../../docs_src/dataclasses/tutorial002.py hl[1,7:13,19] *} Die Datenklasse wird automatisch in eine Pydantic-Datenklasse konvertiert. @@ -52,9 +48,7 @@ In einigen Fällen müssen Sie möglicherweise immer noch Pydantics Version von In diesem Fall können Sie einfach die Standard-`dataclasses` durch `pydantic.dataclasses` ersetzen, was einen direkten Ersatz darstellt: -```{ .python .annotate hl_lines="1 5 8-11 14-17 23-25 28" } -{!../../docs_src/dataclasses/tutorial003.py!} -``` +{* ../../docs_src/dataclasses/tutorial003.py hl[1,5,8:11,14:17,23:25,28] *} 1. Wir importieren `field` weiterhin von Standard-`dataclasses`. diff --git a/docs/de/docs/advanced/events.md b/docs/de/docs/advanced/events.md index b0c4d3922..cae53091c 100644 --- a/docs/de/docs/advanced/events.md +++ b/docs/de/docs/advanced/events.md @@ -38,7 +38,7 @@ Hier simulieren wir das langsame *Hochfahren*, das Laden des Modells, indem wir Und dann, direkt nach dem `yield`, entladen wir das Modell. Dieser Code wird unmittelbar vor dem *Herunterfahren* ausgeführt, **nachdem** die Anwendung **die Bearbeitung von Requests abgeschlossen hat**. Dadurch könnten beispielsweise Ressourcen wie Arbeitsspeicher oder eine GPU freigegeben werden. -/// tip | "Tipp" +/// tip | Tipp Das *Herunterfahren* würde erfolgen, wenn Sie die Anwendung **stoppen**. @@ -94,7 +94,7 @@ Der Parameter `lifespan` der `FastAPI`-App benötigt einen **asynchronen Kontext ## Alternative Events (deprecated) -/// warning | "Achtung" +/// warning | Achtung Der empfohlene Weg, das *Hochfahren* und *Herunterfahren* zu handhaben, ist die Verwendung des `lifespan`-Parameters der `FastAPI`-App, wie oben beschrieben. Wenn Sie einen `lifespan`-Parameter übergeben, werden die `startup`- und `shutdown`-Eventhandler nicht mehr aufgerufen. Es ist entweder alles `lifespan` oder alles Events, nicht beides. @@ -138,7 +138,7 @@ In der Funktion `open()` bedeutet `mode="a"` „append“ („anhängen“), sod /// -/// tip | "Tipp" +/// tip | Tipp Beachten Sie, dass wir in diesem Fall eine Standard-Python-Funktion `open()` verwenden, die mit einer Datei interagiert. diff --git a/docs/de/docs/advanced/generate-clients.md b/docs/de/docs/advanced/generate-clients.md index 80c44b3f9..8f71e5419 100644 --- a/docs/de/docs/advanced/generate-clients.md +++ b/docs/de/docs/advanced/generate-clients.md @@ -127,7 +127,7 @@ Sie erhalten außerdem automatische Vervollständigung für die zu sendende Payl -/// tip | "Tipp" +/// tip | Tipp Beachten Sie die automatische Vervollständigung für `name` und `price`, welche in der FastAPI-Anwendung im `Item`-Modell definiert wurden. diff --git a/docs/de/docs/advanced/index.md b/docs/de/docs/advanced/index.md index 953ad317d..d93cd5fe8 100644 --- a/docs/de/docs/advanced/index.md +++ b/docs/de/docs/advanced/index.md @@ -6,7 +6,7 @@ Das Haupt-[Tutorial – Benutzerhandbuch](../tutorial/index.md){.internal-link t In den nächsten Abschnitten sehen Sie weitere Optionen, Konfigurationen und zusätzliche Funktionen. -/// tip | "Tipp" +/// tip | Tipp Die nächsten Abschnitte sind **nicht unbedingt „fortgeschritten“**. diff --git a/docs/de/docs/advanced/middleware.md b/docs/de/docs/advanced/middleware.md index b4001efda..d2130c9b7 100644 --- a/docs/de/docs/advanced/middleware.md +++ b/docs/de/docs/advanced/middleware.md @@ -43,7 +43,7 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") **FastAPI** enthält mehrere Middlewares für gängige Anwendungsfälle. Wir werden als Nächstes sehen, wie man sie verwendet. -/// note | "Technische Details" +/// note | Technische Details Für die nächsten Beispiele könnten Sie auch `from starlette.middleware.something import SomethingMiddleware` verwenden. diff --git a/docs/de/docs/advanced/openapi-callbacks.md b/docs/de/docs/advanced/openapi-callbacks.md index f407d5450..4ee2874a3 100644 --- a/docs/de/docs/advanced/openapi-callbacks.md +++ b/docs/de/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ Dieser Teil ist ziemlich normal, der größte Teil des Codes ist Ihnen wahrschei {!../../docs_src/openapi_callbacks/tutorial001.py!} ``` -/// tip | "Tipp" +/// tip | Tipp Der Query-Parameter `callback_url` verwendet einen Pydantic-Url-Typ. @@ -64,7 +64,7 @@ Diese Dokumentation wird in der Swagger-Oberfläche unter `/docs` in Ihrer API a In diesem Beispiel wird nicht der Callback selbst implementiert (das könnte nur eine Codezeile sein), sondern nur der Dokumentationsteil. -/// tip | "Tipp" +/// tip | Tipp Der eigentliche Callback ist nur ein HTTP-Request. @@ -80,7 +80,7 @@ Sie wissen jedoch bereits, wie Sie mit **FastAPI** ganz einfach eine automatisch Daher werden wir dasselbe Wissen nutzen, um zu dokumentieren, wie die *externe API* aussehen sollte ... indem wir die *Pfadoperation(en)* erstellen, welche die externe API implementieren soll (die, welche Ihre API aufruft). -/// tip | "Tipp" +/// tip | Tipp Wenn Sie den Code zum Dokumentieren eines Callbacks schreiben, kann es hilfreich sein, sich vorzustellen, dass Sie dieser *externe Entwickler* sind. Und dass Sie derzeit die *externe API* implementieren, nicht *Ihre API*. @@ -163,7 +163,7 @@ und sie würde eine Response von dieser *externen API* mit einem JSON-Body wie d } ``` -/// tip | "Tipp" +/// tip | Tipp Beachten Sie, dass die verwendete Callback-URL die URL enthält, die als Query-Parameter in `callback_url` (`https://www.external.org/events`) empfangen wurde, und auch die Rechnungs-`id` aus dem JSON-Body (`2expen51ve`). @@ -179,7 +179,7 @@ Verwenden Sie nun den Parameter `callbacks` im *Pfadoperation-Dekorator Ihrer AP {!../../docs_src/openapi_callbacks/tutorial001.py!} ``` -/// tip | "Tipp" +/// tip | Tipp Beachten Sie, dass Sie nicht den Router selbst (`invoices_callback_router`) an `callback=` übergeben, sondern das Attribut `.routes`, wie in `invoices_callback_router.routes`. diff --git a/docs/de/docs/advanced/path-operation-advanced-configuration.md b/docs/de/docs/advanced/path-operation-advanced-configuration.md index 2d8b88be5..53d395724 100644 --- a/docs/de/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/de/docs/advanced/path-operation-advanced-configuration.md @@ -2,7 +2,7 @@ ## OpenAPI operationId -/// warning | "Achtung" +/// warning | Achtung Wenn Sie kein „Experte“ für OpenAPI sind, brauchen Sie dies wahrscheinlich nicht. @@ -26,13 +26,13 @@ Sie sollten dies tun, nachdem Sie alle Ihre *Pfadoperationen* hinzugefügt haben {!../../docs_src/path_operation_advanced_configuration/tutorial002.py!} ``` -/// tip | "Tipp" +/// tip | Tipp Wenn Sie `app.openapi()` manuell aufrufen, sollten Sie vorher die `operationId`s aktualisiert haben. /// -/// warning | "Achtung" +/// warning | Achtung Wenn Sie dies tun, müssen Sie sicherstellen, dass jede Ihrer *Pfadoperation-Funktionen* einen eindeutigen Namen hat. @@ -74,7 +74,7 @@ Es gibt hier in der Dokumentation ein ganzes Kapitel darüber, Sie können es un Wenn Sie in Ihrer Anwendung eine *Pfadoperation* deklarieren, generiert **FastAPI** automatisch die relevanten Metadaten dieser *Pfadoperation*, die in das OpenAPI-Schema aufgenommen werden sollen. -/// note | "Technische Details" +/// note | Technische Details In der OpenAPI-Spezifikation wird das Operationsobjekt genannt. @@ -86,7 +86,7 @@ Es enthält `tags`, `parameters`, `requestBody`, `responses`, usw. Dieses *Pfadoperation*-spezifische OpenAPI-Schema wird normalerweise automatisch von **FastAPI** generiert, Sie können es aber auch erweitern. -/// tip | "Tipp" +/// tip | Tipp Dies ist ein Low-Level Erweiterungspunkt. @@ -215,7 +215,7 @@ In Pydantic Version 1 war die Methode zum Parsen und Validieren eines Objekts `I /// -/// tip | "Tipp" +/// tip | Tipp Hier verwenden wir dasselbe Pydantic-Modell wieder. diff --git a/docs/de/docs/advanced/response-cookies.md b/docs/de/docs/advanced/response-cookies.md index ba100870d..6f9d66e07 100644 --- a/docs/de/docs/advanced/response-cookies.md +++ b/docs/de/docs/advanced/response-cookies.md @@ -30,7 +30,7 @@ Setzen Sie dann Cookies darin und geben Sie sie dann zurück: {!../../docs_src/response_cookies/tutorial001.py!} ``` -/// tip | "Tipp" +/// tip | Tipp Beachten Sie, dass, wenn Sie eine Response direkt zurückgeben, anstatt den `Response`-Parameter zu verwenden, FastAPI diese direkt zurückgibt. @@ -42,7 +42,7 @@ Und auch, dass Sie keine Daten senden, die durch ein `response_model` hätten ge ### Mehr Informationen -/// note | "Technische Details" +/// note | Technische Details Sie können auch `from starlette.responses import Response` oder `from starlette.responses import JSONResponse` verwenden. diff --git a/docs/de/docs/advanced/response-directly.md b/docs/de/docs/advanced/response-directly.md index 70c045f57..fab2e3965 100644 --- a/docs/de/docs/advanced/response-directly.md +++ b/docs/de/docs/advanced/response-directly.md @@ -14,7 +14,7 @@ Das kann beispielsweise nützlich sein, um benutzerdefinierte Header oder Cookie Tatsächlich können Sie jede `Response` oder jede Unterklasse davon zurückgeben. -/// tip | "Tipp" +/// tip | Tipp `JSONResponse` selbst ist eine Unterklasse von `Response`. @@ -38,7 +38,7 @@ In diesen Fällen können Sie den `jsonable_encoder` verwenden, um Ihre Daten zu {!../../docs_src/response_directly/tutorial001.py!} ``` -/// note | "Technische Details" +/// note | Technische Details Sie können auch `from starlette.responses import JSONResponse` verwenden. diff --git a/docs/de/docs/advanced/response-headers.md b/docs/de/docs/advanced/response-headers.md index 31c2c9c98..ca1a28fa4 100644 --- a/docs/de/docs/advanced/response-headers.md +++ b/docs/de/docs/advanced/response-headers.md @@ -28,7 +28,7 @@ Erstellen Sie eine Response wie in [Eine Response direkt zurückgeben](response- {!../../docs_src/response_headers/tutorial001.py!} ``` -/// note | "Technische Details" +/// note | Technische Details Sie können auch `from starlette.responses import Response` oder `from starlette.responses import JSONResponse` verwenden. diff --git a/docs/de/docs/advanced/security/index.md b/docs/de/docs/advanced/security/index.md index 380e48bbf..25eeb25b5 100644 --- a/docs/de/docs/advanced/security/index.md +++ b/docs/de/docs/advanced/security/index.md @@ -4,7 +4,7 @@ Neben den in [Tutorial – Benutzerhandbuch: Sicherheit](../../tutorial/security/index.md){.internal-link target=_blank} behandelten Funktionen gibt es noch einige zusätzliche Funktionen zur Handhabung der Sicherheit. -/// tip | "Tipp" +/// tip | Tipp Die nächsten Abschnitte sind **nicht unbedingt „fortgeschritten“**. diff --git a/docs/de/docs/advanced/security/oauth2-scopes.md b/docs/de/docs/advanced/security/oauth2-scopes.md index c0af2560a..85175a895 100644 --- a/docs/de/docs/advanced/security/oauth2-scopes.md +++ b/docs/de/docs/advanced/security/oauth2-scopes.md @@ -10,7 +10,7 @@ Jedes Mal, wenn Sie sich mit Facebook, Google, GitHub, Microsoft oder Twitter an In diesem Abschnitt erfahren Sie, wie Sie Authentifizierung und Autorisierung mit demselben OAuth2, mit Scopes in Ihrer **FastAPI**-Anwendung verwalten. -/// warning | "Achtung" +/// warning | Achtung Dies ist ein mehr oder weniger fortgeschrittener Abschnitt. Wenn Sie gerade erst anfangen, können Sie ihn überspringen. @@ -88,7 +88,7 @@ Sehen wir uns zunächst kurz die Teile an, die sich gegenüber den Beispielen im //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -102,7 +102,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.9+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -116,7 +116,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -162,7 +162,7 @@ Der `scopes`-Parameter erhält ein `dict` mit jedem Scope als Schlüssel und des //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -176,7 +176,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.9+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -190,7 +190,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -218,7 +218,7 @@ Wir verwenden immer noch dasselbe `OAuth2PasswordRequestForm`. Es enthält eine Und wir geben die Scopes als Teil des JWT-Tokens zurück. -/// danger | "Gefahr" +/// danger | Gefahr Der Einfachheit halber fügen wir hier die empfangenen Scopes direkt zum Token hinzu. @@ -252,7 +252,7 @@ Aus Sicherheitsgründen sollten Sie jedoch sicherstellen, dass Sie in Ihrer Anwe //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -266,7 +266,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.9+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -280,7 +280,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -308,7 +308,7 @@ Und die Abhängigkeitsfunktion `get_current_active_user` kann auch Unterabhängi In diesem Fall erfordert sie den Scope `me` (sie könnte mehr als einen Scope erfordern). -/// note | "Hinweis" +/// note | Hinweis Sie müssen nicht unbedingt an verschiedenen Stellen verschiedene Scopes hinzufügen. @@ -342,7 +342,7 @@ Wir tun dies hier, um zu demonstrieren, wie **FastAPI** auf verschiedenen Ebenen //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -356,7 +356,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.9+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -370,7 +370,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -382,7 +382,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// -/// info | "Technische Details" +/// info | Technische Details `Security` ist tatsächlich eine Unterklasse von `Depends` und hat nur noch einen zusätzlichen Parameter, den wir später kennenlernen werden. @@ -432,7 +432,7 @@ Diese `SecurityScopes`-Klasse ähnelt `Request` (`Request` wurde verwendet, um d //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -446,7 +446,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.9+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -460,7 +460,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -510,7 +510,7 @@ In diese Exception fügen wir (falls vorhanden) die erforderlichen Scopes als du //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -524,7 +524,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.9+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -538,7 +538,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -590,7 +590,7 @@ Wir verifizieren auch, dass wir einen Benutzer mit diesem Benutzernamen haben, u //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -604,7 +604,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.9+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -618,7 +618,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -662,7 +662,7 @@ Hierzu verwenden wir `security_scopes.scopes`, das eine `list`e mit allen diesen //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -676,7 +676,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.9+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -690,7 +690,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -727,7 +727,7 @@ So sieht die Hierarchie der Abhängigkeiten und Scopes aus: * `security_scopes.scopes` enthält `["me"]` für die *Pfadoperation* `read_users_me`, da das in der Abhängigkeit `get_current_active_user` deklariert ist. * `security_scopes.scopes` wird `[]` (nichts) für die *Pfadoperation* `read_system_status` enthalten, da diese keine `Security` mit `scopes` deklariert hat, und deren Abhängigkeit `get_current_user` ebenfalls keinerlei `scopes` deklariert. -/// tip | "Tipp" +/// tip | Tipp Das Wichtige und „Magische“ hier ist, dass `get_current_user` für jede *Pfadoperation* eine andere Liste von `scopes` hat, die überprüft werden. @@ -771,7 +771,7 @@ Am häufigsten ist der „Implicit“-Flow. Am sichersten ist der „Code“-Flow, die Implementierung ist jedoch komplexer, da mehr Schritte erforderlich sind. Da er komplexer ist, schlagen viele Anbieter letztendlich den „Implicit“-Flow vor. -/// note | "Hinweis" +/// note | Hinweis Es ist üblich, dass jeder Authentifizierungsanbieter seine Flows anders benennt, um sie zu einem Teil seiner Marke zu machen. diff --git a/docs/de/docs/advanced/settings.md b/docs/de/docs/advanced/settings.md index 8b9ba2f48..c90f74844 100644 --- a/docs/de/docs/advanced/settings.md +++ b/docs/de/docs/advanced/settings.md @@ -8,7 +8,7 @@ Aus diesem Grund werden diese üblicherweise in Umgebungsvariablen bereitgestell ## Umgebungsvariablen -/// tip | "Tipp" +/// tip | Tipp Wenn Sie bereits wissen, was „Umgebungsvariablen“ sind und wie man sie verwendet, können Sie gerne mit dem nächsten Abschnitt weiter unten fortfahren. @@ -67,7 +67,7 @@ name = os.getenv("MY_NAME", "World") print(f"Hello {name} from Python") ``` -/// tip | "Tipp" +/// tip | Tipp Das zweite Argument für `os.getenv()` ist der zurückzugebende Defaultwert. @@ -124,7 +124,7 @@ Hello World from Python -/// tip | "Tipp" +/// tip | Tipp Weitere Informationen dazu finden Sie unter The Twelve-Factor App: Config. @@ -200,7 +200,7 @@ In Pydantic v1 würden Sie `BaseSettings` direkt von `pydantic` statt von `pydan //// -/// tip | "Tipp" +/// tip | Tipp Für ein schnelles Copy-and-paste verwenden Sie nicht dieses Beispiel, sondern das letzte unten. @@ -232,7 +232,7 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uvicorn main:app -/// tip | "Tipp" +/// 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. @@ -260,7 +260,7 @@ Und dann verwenden Sie diese in einer Datei `main.py`: {!../../docs_src/settings/app01/main.py!} ``` -/// tip | "Tipp" +/// tip | Tipp Sie benötigen außerdem eine Datei `__init__.py`, wie in [Größere Anwendungen – mehrere Dateien](../tutorial/bigger-applications.md){.internal-link target=_blank} gesehen. @@ -304,7 +304,7 @@ Jetzt erstellen wir eine Abhängigkeit, die ein neues `config.Settings()` zurüc //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -316,7 +316,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// -/// tip | "Tipp" +/// tip | Tipp Wir werden das `@lru_cache` in Kürze besprechen. @@ -344,7 +344,7 @@ Und dann können wir das von der *Pfadoperation-Funktion* als Abhängigkeit einf //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -374,7 +374,7 @@ Wenn Sie viele Einstellungen haben, die sich möglicherweise oft ändern, vielle Diese Praxis ist so weit verbreitet, dass sie einen Namen hat. Diese Umgebungsvariablen werden üblicherweise in einer Datei `.env` abgelegt und die Datei wird „dotenv“ genannt. -/// tip | "Tipp" +/// tip | Tipp Eine Datei, die mit einem Punkt (`.`) beginnt, ist eine versteckte Datei in Unix-ähnlichen Systemen wie Linux und macOS. @@ -384,7 +384,7 @@ 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) support. -/// tip | "Tipp" +/// tip | Tipp Damit das funktioniert, müssen Sie `pip install python-dotenv` ausführen. @@ -409,7 +409,7 @@ Und dann aktualisieren Sie Ihre `config.py` mit: {!> ../../docs_src/settings/app03_an/config.py!} ``` -/// tip | "Tipp" +/// tip | Tipp Das Attribut `model_config` wird nur für die Pydantic-Konfiguration verwendet. Weitere Informationen finden Sie unter Pydantic: Configuration. @@ -423,7 +423,7 @@ Das Attribut `model_config` wird nur für die Pydantic-Konfiguration verwendet. {!> ../../docs_src/settings/app03_an/config_pv1.py!} ``` -/// tip | "Tipp" +/// tip | Tipp Die Klasse `Config` wird nur für die Pydantic-Konfiguration verwendet. Weitere Informationen finden Sie unter Pydantic Model Config. @@ -480,7 +480,7 @@ Da wir jedoch den `@lru_cache`-Dekorator oben verwenden, wird das `Settings`-Obj //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. diff --git a/docs/de/docs/advanced/templates.md b/docs/de/docs/advanced/templates.md index 6cb3fcf6c..658a2592e 100644 --- a/docs/de/docs/advanced/templates.md +++ b/docs/de/docs/advanced/templates.md @@ -31,7 +31,7 @@ $ pip install jinja2 {!../../docs_src/templates/tutorial001.py!} ``` -/// note | "Hinweis" +/// note | Hinweis Vor FastAPI 0.108.0 und Starlette 0.29.0 war `name` der erste Parameter. @@ -39,13 +39,13 @@ Außerdem wurde in früheren Versionen das `request`-Objekt als Teil der Schlüs /// -/// tip | "Tipp" +/// tip | Tipp Durch die Deklaration von `response_class=HTMLResponse` kann die Dokumentationsoberfläche erkennen, dass die Response HTML sein wird. /// -/// note | "Technische Details" +/// note | Technische Details Sie können auch `from starlette.templating import Jinja2Templates` verwenden. diff --git a/docs/de/docs/advanced/testing-dependencies.md b/docs/de/docs/advanced/testing-dependencies.md index c565b30f2..3b4604da3 100644 --- a/docs/de/docs/advanced/testing-dependencies.md +++ b/docs/de/docs/advanced/testing-dependencies.md @@ -54,7 +54,7 @@ Und dann ruft **FastAPI** diese Überschreibung anstelle der ursprünglichen Abh //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -68,7 +68,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -80,7 +80,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// -/// tip | "Tipp" +/// tip | Tipp Sie können eine Überschreibung für eine Abhängigkeit festlegen, die an einer beliebigen Stelle in Ihrer **FastAPI**-Anwendung verwendet wird. @@ -96,7 +96,7 @@ Anschließend können Sie Ihre Überschreibungen zurücksetzen (entfernen), inde app.dependency_overrides = {} ``` -/// tip | "Tipp" +/// tip | Tipp Wenn Sie eine Abhängigkeit nur während einiger Tests überschreiben möchten, können Sie die Überschreibung zu Beginn des Tests (innerhalb der Testfunktion) festlegen und am Ende (am Ende der Testfunktion) zurücksetzen. diff --git a/docs/de/docs/advanced/testing-websockets.md b/docs/de/docs/advanced/testing-websockets.md index 7ae7d92d6..5122e1f33 100644 --- a/docs/de/docs/advanced/testing-websockets.md +++ b/docs/de/docs/advanced/testing-websockets.md @@ -8,7 +8,7 @@ Dazu verwenden Sie den `TestClient` in einer `with`-Anweisung, eine Verbindung z {!../../docs_src/app_testing/tutorial002.py!} ``` -/// note | "Hinweis" +/// note | Hinweis Weitere Informationen finden Sie in der Starlette-Dokumentation zum Testen von WebSockets. diff --git a/docs/de/docs/advanced/using-request-directly.md b/docs/de/docs/advanced/using-request-directly.md index 6a0b96680..1c2a6f852 100644 --- a/docs/de/docs/advanced/using-request-directly.md +++ b/docs/de/docs/advanced/using-request-directly.md @@ -35,7 +35,7 @@ Dazu müssen Sie direkt auf den Request zugreifen. Durch die Deklaration eines *Pfadoperation-Funktionsparameters*, dessen Typ der `Request` ist, weiß **FastAPI**, dass es den `Request` diesem Parameter übergeben soll. -/// tip | "Tipp" +/// tip | Tipp Beachten Sie, dass wir in diesem Fall einen Pfad-Parameter zusätzlich zum Request-Parameter deklarieren. @@ -49,7 +49,7 @@ Auf die gleiche Weise können Sie wie gewohnt jeden anderen Parameter deklariere Weitere Details zum `Request`-Objekt finden Sie in der offiziellen Starlette-Dokumentation. -/// note | "Technische Details" +/// note | Technische Details Sie können auch `from starlette.requests import Request` verwenden. diff --git a/docs/de/docs/advanced/websockets.md b/docs/de/docs/advanced/websockets.md index cf13fa23c..5bc5f6902 100644 --- a/docs/de/docs/advanced/websockets.md +++ b/docs/de/docs/advanced/websockets.md @@ -50,7 +50,7 @@ Erstellen Sie in Ihrer **FastAPI**-Anwendung einen `websocket`: {!../../docs_src/websockets/tutorial001.py!} ``` -/// note | "Technische Details" +/// note | Technische Details Sie können auch `from starlette.websockets import WebSocket` verwenden. @@ -141,7 +141,7 @@ Diese funktionieren auf die gleiche Weise wie für andere FastAPI-Endpunkte/*Pfa //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -155,7 +155,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -196,7 +196,7 @@ Dort können Sie einstellen: * Die „Item ID“, die im Pfad verwendet wird. * Das „Token“, das als Query-Parameter verwendet wird. -/// tip | "Tipp" +/// tip | Tipp Beachten Sie, dass der Query-„Token“ von einer Abhängigkeit verarbeitet wird. @@ -238,7 +238,7 @@ Das wird die Ausnahme `WebSocketDisconnect` auslösen und alle anderen Clients e Client #1596980209979 left the chat ``` -/// tip | "Tipp" +/// tip | Tipp Die obige Anwendung ist ein minimales und einfaches Beispiel, das zeigt, wie Nachrichten verarbeitet und an mehrere WebSocket-Verbindungen gesendet werden. diff --git a/docs/de/docs/alternatives.md b/docs/de/docs/alternatives.md index 49e1cc6f0..611315501 100644 --- a/docs/de/docs/alternatives.md +++ b/docs/de/docs/alternatives.md @@ -30,13 +30,13 @@ Es wird von vielen Unternehmen verwendet, darunter Mozilla, Red Hat und Eventbri Es war eines der ersten Beispiele für **automatische API-Dokumentation**, und dies war insbesondere eine der ersten Ideen, welche „die Suche nach“ **FastAPI** inspirierten. -/// note | "Hinweis" +/// note | Hinweis Das Django REST Framework wurde von Tom Christie erstellt. Derselbe Schöpfer von Starlette und Uvicorn, auf denen **FastAPI** basiert. /// -/// check | "Inspirierte **FastAPI**" +/// check | Inspirierte **FastAPI** Eine automatische API-Dokumentationsoberfläche zu haben. @@ -56,7 +56,7 @@ Diese Entkopplung der Teile und die Tatsache, dass es sich um ein „Mikroframew Angesichts der Einfachheit von Flask schien es eine gute Ergänzung zum Erstellen von APIs zu sein. Als Nächstes musste ein „Django REST Framework“ für Flask gefunden werden. -/// check | "Inspirierte **FastAPI**" +/// check | Inspirierte **FastAPI** Ein Mikroframework zu sein. Es einfach zu machen, die benötigten Tools und Teile zu kombinieren. @@ -98,7 +98,7 @@ def read_url(): Sehen Sie sich die Ähnlichkeiten in `requests.get(...)` und `@app.get(...)` an. -/// check | "Inspirierte **FastAPI**" +/// check | Inspirierte **FastAPI** * Über eine einfache und intuitive API zu verfügen. * HTTP-Methodennamen (Operationen) direkt, auf einfache und intuitive Weise zu verwenden. @@ -118,7 +118,7 @@ Irgendwann wurde Swagger an die Linux Foundation übergeben und in OpenAPI umben Aus diesem Grund spricht man bei Version 2.0 häufig von „Swagger“ und ab Version 3 von „OpenAPI“. -/// check | "Inspirierte **FastAPI**" +/// check | Inspirierte **FastAPI** Einen offenen Standard für API-Spezifikationen zu übernehmen und zu verwenden, anstelle eines benutzerdefinierten Schemas. @@ -147,7 +147,7 @@ Für diese Funktionen wurde Marshmallow entwickelt. Es ist eine großartige Bibl Aber sie wurde erstellt, bevor Typhinweise in Python existierten. Um also ein Schema zu definieren, müssen Sie bestimmte Werkzeuge und Klassen verwenden, die von Marshmallow bereitgestellt werden. -/// check | "Inspirierte **FastAPI**" +/// check | Inspirierte **FastAPI** Code zu verwenden, um „Schemas“ zu definieren, welche Datentypen und Validierung automatisch bereitstellen. @@ -169,7 +169,7 @@ Webargs wurde von denselben Marshmallow-Entwicklern erstellt. /// -/// check | "Inspirierte **FastAPI**" +/// check | Inspirierte **FastAPI** Eingehende Requestdaten automatisch zu validieren. @@ -199,7 +199,7 @@ APISpec wurde von denselben Marshmallow-Entwicklern erstellt. /// -/// check | "Inspirierte **FastAPI**" +/// check | Inspirierte **FastAPI** Den offenen Standard für APIs, OpenAPI, zu unterstützen. @@ -231,7 +231,7 @@ Flask-apispec wurde von denselben Marshmallow-Entwicklern erstellt. /// -/// check | "Inspirierte **FastAPI**" +/// check | Inspirierte **FastAPI** Das OpenAPI-Schema automatisch zu generieren, aus demselben Code, welcher die Serialisierung und Validierung definiert. @@ -251,7 +251,7 @@ Da TypeScript-Daten jedoch nach der Kompilierung nach JavaScript nicht erhalten Es kann nicht sehr gut mit verschachtelten Modellen umgehen. Wenn es sich beim JSON-Body in der Anfrage also um ein JSON-Objekt mit inneren Feldern handelt, die wiederum verschachtelte JSON-Objekte sind, kann er nicht richtig dokumentiert und validiert werden. -/// check | "Inspirierte **FastAPI**" +/// check | Inspirierte **FastAPI** Python-Typen zu verwenden, um eine hervorragende Editorunterstützung zu erhalten. @@ -263,7 +263,7 @@ Python-Typen zu verwenden, um eine hervorragende Editorunterstützung zu erhalte Es war eines der ersten extrem schnellen Python-Frameworks, welches auf `asyncio` basierte. Es wurde so gestaltet, dass es Flask sehr ähnlich ist. -/// note | "Technische Details" +/// note | Technische Details Es verwendete `uvloop` anstelle der standardmäßigen Python-`asyncio`-Schleife. Das hat es so schnell gemacht. @@ -271,7 +271,7 @@ Hat eindeutig Uvicorn und Starlette inspiriert, welche derzeit in offenen Benchm /// -/// check | "Inspirierte **FastAPI**" +/// check | Inspirierte **FastAPI** Einen Weg zu finden, eine hervorragende Performanz zu haben. @@ -287,7 +287,7 @@ Es ist so konzipiert, dass es über Funktionen verfügt, welche zwei Parameter e Daher müssen Datenvalidierung, Serialisierung und Dokumentation im Code und nicht automatisch erfolgen. Oder sie müssen als Framework oberhalb von Falcon implementiert werden, so wie Hug. Dieselbe Unterscheidung findet auch in anderen Frameworks statt, die vom Design von Falcon inspiriert sind und ein Requestobjekt und ein Responseobjekt als Parameter haben. -/// check | "Inspirierte **FastAPI**" +/// check | Inspirierte **FastAPI** Wege zu finden, eine großartige Performanz zu erzielen. @@ -313,7 +313,7 @@ Das Dependency Injection System erfordert eine Vorab-Registrierung der Abhängig Routen werden an einer einzigen Stelle deklariert, indem Funktionen verwendet werden, die an anderen Stellen deklariert wurden (anstatt Dekoratoren zu verwenden, welche direkt über der Funktion platziert werden können, welche den Endpunkt verarbeitet). Dies ähnelt eher der Vorgehensweise von Django als der Vorgehensweise von Flask (und Starlette). Es trennt im Code Dinge, die relativ eng miteinander gekoppelt sind. -/// check | "Inspirierte **FastAPI**" +/// check | Inspirierte **FastAPI** Zusätzliche Validierungen für Datentypen zu definieren, mithilfe des „Default“-Werts von Modellattributen. Dies verbessert die Editorunterstützung und war zuvor in Pydantic nicht verfügbar. @@ -341,7 +341,7 @@ Hug wurde von Timothy Crosley erstellt, dem gleichen Schöpfer von fastapi Repository bereits geklont haben und tief in den Code eintauchen möchten, hier einen Leitfaden zum Einrichten Ihrer Umgebung. - -### Virtuelle Umgebung mit `venv` - -Sie können mit dem Python-Modul `venv` in einem Verzeichnis eine isolierte virtuelle lokale Umgebung erstellen. Machen wir das im geklonten Repository (da wo sich die `requirements.txt` befindet): - -
- -```console -$ python -m venv env -``` - -
- -Das erstellt ein Verzeichnis `./env/` mit den Python-Binärdateien und Sie können dann Packages in dieser lokalen Umgebung installieren. - -### Umgebung aktivieren - -Aktivieren Sie die neue Umgebung mit: - -//// tab | Linux, macOS - -
- -```console -$ source ./env/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .\env\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Oder, wenn Sie Bash für Windows verwenden (z. B. Git Bash): - -
- -```console -$ source ./env/Scripts/activate -``` - -
- -//// - -Um zu überprüfen, ob es funktioniert hat, geben Sie ein: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which pip - -some/directory/fastapi/env/bin/pip -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command pip - -some/directory/fastapi/env/bin/pip -``` - -
- -//// - -Wenn die `pip` Binärdatei unter `env/bin/pip` angezeigt wird, hat es funktioniert. 🎉 - -Stellen Sie sicher, dass Sie über die neueste Version von pip in Ihrer lokalen Umgebung verfügen, um Fehler bei den nächsten Schritten zu vermeiden: - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip | "Tipp" - -Aktivieren Sie jedes Mal, wenn Sie ein neues Package mit `pip` in dieser Umgebung installieren, die Umgebung erneut. - -Dadurch wird sichergestellt, dass Sie, wenn Sie ein von diesem Package installiertes Terminalprogramm verwenden, das Programm aus Ihrer lokalen Umgebung verwenden und kein anderes, das global installiert sein könnte. - -/// - -### Benötigtes mit pip installieren - -Nachdem Sie die Umgebung wie oben beschrieben aktiviert haben: - -
- -```console -$ pip install -r requirements.txt - ----> 100% -``` - -
- -Das installiert alle Abhängigkeiten und Ihr lokales FastAPI in Ihrer lokalen Umgebung. - -#### Das lokale FastAPI verwenden - -Wenn Sie eine Python-Datei erstellen, die FastAPI importiert und verwendet, und diese mit dem Python aus Ihrer lokalen Umgebung ausführen, wird Ihr geklonter lokaler FastAPI-Quellcode verwendet. - -Und wenn Sie diesen lokalen FastAPI-Quellcode aktualisieren und dann die Python-Datei erneut ausführen, wird die neue Version von FastAPI verwendet, die Sie gerade bearbeitet haben. - -Auf diese Weise müssen Sie Ihre lokale Version nicht „installieren“, um jede Änderung testen zu können. - -/// note | "Technische Details" - -Das geschieht nur, wenn Sie die Installation mit der enthaltenen `requirements.txt` durchführen, anstatt `pip install fastapi` direkt auszuführen. - -Das liegt daran, dass in der Datei `requirements.txt` die lokale Version von FastAPI mit der Option `-e` für die Installation im „editierbaren“ Modus markiert ist. - -/// - -### Den Code formatieren - -Es gibt ein Skript, das, wenn Sie es ausführen, Ihren gesamten Code formatiert und bereinigt: - -
- -```console -$ bash scripts/format.sh -``` - -
- -Es sortiert auch alle Ihre Importe automatisch. - -Damit es sie richtig sortiert, muss FastAPI lokal in Ihrer Umgebung installiert sein, mit dem Befehl vom obigen Abschnitt, welcher `-e` verwendet. - -## Dokumentation - -Stellen Sie zunächst sicher, dass Sie Ihre Umgebung wie oben beschrieben einrichten, was alles Benötigte installiert. - -### Dokumentation live - -Während der lokalen Entwicklung gibt es ein Skript, das die Site erstellt, auf Änderungen prüft und direkt neu lädt (Live Reload): - -
- -```console -$ python ./scripts/docs.py live - -[INFO] Serving on http://127.0.0.1:8008 -[INFO] Start watching changes -[INFO] Start detecting changes -``` - -
- -Das stellt die Dokumentation unter `http://127.0.0.1:8008` bereit. - -Auf diese Weise können Sie die Dokumentation/Quelldateien bearbeiten und die Änderungen live sehen. - -/// tip | "Tipp" - -Alternativ können Sie die Schritte des Skripts auch manuell ausführen. - -Gehen Sie in das Verzeichnis für die entsprechende Sprache. Das für die englischsprachige Hauptdokumentation befindet sich unter `docs/en/`: - -```console -$ cd docs/en/ -``` - -Führen Sie dann `mkdocs` in diesem Verzeichnis aus: - -```console -$ mkdocs serve --dev-addr 8008 -``` - -/// - -#### Typer-CLI (optional) - -Die Anleitung hier zeigt Ihnen, wie Sie das Skript unter `./scripts/docs.py` direkt mit dem `python` Programm verwenden. - -Sie können aber auch Typer CLI verwenden und erhalten dann Autovervollständigung für Kommandos in Ihrem Terminal, nach dem Sie dessen Vervollständigung installiert haben. - -Wenn Sie Typer CLI installieren, können Sie die Vervollständigung installieren mit: - -
- -```console -$ typer --install-completion - -zsh completion installed in /home/user/.bashrc. -Completion will take effect once you restart the terminal. -``` - -
- -### Dokumentationsstruktur - -Die Dokumentation verwendet MkDocs. - -Und es gibt zusätzliche Tools/Skripte für Übersetzungen, in `./scripts/docs.py`. - -/// tip | "Tipp" - -Sie müssen sich den Code in `./scripts/docs.py` nicht anschauen, verwenden Sie ihn einfach in der Kommandozeile. - -/// - -Die gesamte Dokumentation befindet sich im Markdown-Format im Verzeichnis `./docs/en/`. - -Viele der Tutorials enthalten Codeblöcke. - -In den meisten Fällen handelt es sich bei diesen Codeblöcken um vollständige Anwendungen, die unverändert ausgeführt werden können. - -Tatsächlich sind diese Codeblöcke nicht Teil des Markdowns, sondern Python-Dateien im Verzeichnis `./docs_src/`. - -Und diese Python-Dateien werden beim Generieren der Site in die Dokumentation eingefügt. - -### Dokumentation für Tests - -Tatsächlich arbeiten die meisten Tests mit den Beispielquelldateien in der Dokumentation. - -Dadurch wird sichergestellt, dass: - -* Die Dokumentation aktuell ist. -* Die Dokumentationsbeispiele ohne Änderung ausgeführt werden können. -* Die meisten Funktionalitäten durch die Dokumentation abgedeckt werden, sichergestellt durch die Testabdeckung. - -#### Gleichzeitig Apps und Dokumentation - -Wenn Sie die Beispiele ausführen, mit z. B.: - -
- -```console -$ uvicorn tutorial001:app --reload - -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -``` - -
- -wird das, da Uvicorn standardmäßig den Port `8000` verwendet, mit der Dokumentation auf dem Port `8008` nicht in Konflikt geraten. - -### Übersetzungen - -Hilfe bei Übersetzungen wird SEHR geschätzt! Und es kann nicht getan werden, ohne die Hilfe der Gemeinschaft. 🌎 🚀 - -Hier sind die Schritte, die Ihnen bei Übersetzungen helfen. - -#### Tipps und Richtlinien - -* Schauen Sie nach aktuellen Pull Requests für Ihre Sprache. Sie können die Pull Requests nach dem Label für Ihre Sprache filtern. Für Spanisch lautet das Label beispielsweise `lang-es`. - -* Sehen Sie diese Pull Requests durch (Review), schlagen Sie Änderungen vor, oder segnen Sie sie ab (Approval). Bei den Sprachen, die ich nicht spreche, warte ich, bis mehrere andere die Übersetzung durchgesehen haben, bevor ich den Pull Request merge. - -/// tip | "Tipp" - -Sie können Kommentare mit Änderungsvorschlägen zu vorhandenen Pull Requests hinzufügen. - -Schauen Sie sich die Dokumentation an, wie man ein Review zu einem Pull Request hinzufügt, welches den PR absegnet oder Änderungen vorschlägt. - -/// - -* Überprüfen Sie, ob es eine GitHub-Diskussion gibt, die Übersetzungen für Ihre Sprache koordiniert. Sie können sie abonnieren, und wenn ein neuer Pull Request zum Review vorliegt, wird der Diskussion automatisch ein Kommentar hinzugefügt. - -* Wenn Sie Seiten übersetzen, fügen Sie einen einzelnen Pull Request pro übersetzter Seite hinzu. Dadurch wird es für andere viel einfacher, ihn zu durchzusehen. - -* Um den Zwei-Buchstaben-Code für die Sprache zu finden, die Sie übersetzen möchten, schauen Sie sich die Tabelle List of ISO 639-1 codes an. - -#### Vorhandene Sprache - -Angenommen, Sie möchten eine Seite für eine Sprache übersetzen, die bereits Übersetzungen für einige Seiten hat, beispielsweise für Spanisch. - -Im Spanischen lautet der Zwei-Buchstaben-Code `es`. Das Verzeichnis für spanische Übersetzungen befindet sich also unter `docs/es/`. - -/// tip | "Tipp" - -Die Haupt („offizielle“) Sprache ist Englisch und befindet sich unter `docs/en/`. - -/// - -Führen Sie nun den Live-Server für die Dokumentation auf Spanisch aus: - -
- -```console -// Verwenden Sie das Kommando „live“ und fügen Sie den Sprach-Code als Argument hinten an -$ python ./scripts/docs.py live es - -[INFO] Serving on http://127.0.0.1:8008 -[INFO] Start watching changes -[INFO] Start detecting changes -``` - -
- -/// tip | "Tipp" - -Alternativ können Sie die Schritte des Skripts auch manuell ausführen. - -Gehen Sie in das Sprachverzeichnis, für die spanischen Übersetzungen ist das `docs/es/`: - -```console -$ cd docs/es/ -``` - -Dann führen Sie in dem Verzeichnis `mkdocs` aus: - -```console -$ mkdocs serve --dev-addr 8008 -``` - -/// - -Jetzt können Sie auf http://127.0.0.1:8008 gehen und Ihre Änderungen live sehen. - -Sie werden sehen, dass jede Sprache alle Seiten hat. Einige Seiten sind jedoch nicht übersetzt und haben oben eine Info-Box, dass die Übersetzung noch fehlt. - -Nehmen wir nun an, Sie möchten eine Übersetzung für den Abschnitt [Features](features.md){.internal-link target=_blank} hinzufügen. - -* Kopieren Sie die Datei: - -``` -docs/en/docs/features.md -``` - -* Fügen Sie sie an genau derselben Stelle ein, jedoch für die Sprache, die Sie übersetzen möchten, z. B.: - -``` -docs/es/docs/features.md -``` - -/// tip | "Tipp" - -Beachten Sie, dass die einzige Änderung in Pfad und Dateiname der Sprachcode ist, von `en` zu `es`. - -/// - -Wenn Sie in Ihrem Browser nachsehen, werden Sie feststellen, dass die Dokumentation jetzt Ihren neuen Abschnitt anzeigt (die Info-Box oben ist verschwunden). 🎉 - -Jetzt können Sie alles übersetzen und beim Speichern sehen, wie es aussieht. - -#### Neue Sprache - -Nehmen wir an, Sie möchten Übersetzungen für eine Sprache hinzufügen, die noch nicht übersetzt ist, nicht einmal einige Seiten. - -Angenommen, Sie möchten Übersetzungen für Kreolisch hinzufügen, diese sind jedoch noch nicht in den Dokumenten enthalten. - -Wenn Sie den Link von oben überprüfen, lautet der Sprachcode für Kreolisch `ht`. - -Der nächste Schritt besteht darin, das Skript auszuführen, um ein neues Übersetzungsverzeichnis zu erstellen: - -
- -```console -// Verwenden Sie das Kommando new-lang und fügen Sie den Sprach-Code als Argument hinten an -$ python ./scripts/docs.py new-lang ht - -Successfully initialized: docs/ht -``` - -
- -Jetzt können Sie in Ihrem Code-Editor das neu erstellte Verzeichnis `docs/ht/` sehen. - -Obiges Kommando hat eine Datei `docs/ht/mkdocs.yml` mit einer Minimal-Konfiguration erstellt, die alles von der `en`-Version erbt: - -```yaml -INHERIT: ../en/mkdocs.yml -``` - -/// tip | "Tipp" - -Sie können diese Datei mit diesem Inhalt auch einfach manuell erstellen. - -/// - -Das Kommando hat auch eine Dummy-Datei `docs/ht/index.md` für die Hauptseite erstellt. Sie können mit der Übersetzung dieser Datei beginnen. - -Sie können nun mit den obigen Instruktionen für eine „vorhandene Sprache“ fortfahren. - -Fügen Sie dem ersten Pull Request beide Dateien `docs/ht/mkdocs.yml` und `docs/ht/index.md` bei. 🎉 - -#### Vorschau des Ergebnisses - -Wie bereits oben erwähnt, können Sie `./scripts/docs.py` mit dem Befehl `live` verwenden, um eine Vorschau der Ergebnisse anzuzeigen (oder `mkdocs serve`). - -Sobald Sie fertig sind, können Sie auch alles so testen, wie es online aussehen würde, einschließlich aller anderen Sprachen. - -Bauen Sie dazu zunächst die gesamte Dokumentation: - -
- -```console -// Verwenden Sie das Kommando „build-all“, das wird ein wenig dauern -$ python ./scripts/docs.py build-all - -Building docs for: en -Building docs for: es -Successfully built docs for: es -``` - -
- -Dadurch werden alle diese unabhängigen MkDocs-Sites für jede Sprache erstellt, kombiniert und das endgültige Resultat unter `./site/` gespeichert. - -Dieses können Sie dann mit dem Befehl `serve` bereitstellen: - -
- -```console -// Verwenden Sie das Kommando „serve“ nachdem Sie „build-all“ ausgeführt haben. -$ python ./scripts/docs.py serve - -Warning: this is a very simple server. For development, use mkdocs serve instead. -This is here only to preview a site with translations already built. -Make sure you run the build-all command first. -Serving at: http://127.0.0.1:8008 -``` - -
- -#### Übersetzungsspezifische Tipps und Richtlinien - -* Übersetzen Sie nur die Markdown-Dokumente (`.md`). Übersetzen Sie nicht die Codebeispiele unter `./docs_src`. - -* In Codeblöcken innerhalb des Markdown-Dokuments, übersetzen Sie Kommentare (`# ein Kommentar`), aber lassen Sie den Rest unverändert. - -* Ändern Sie nichts, was in "``" (Inline-Code) eingeschlossen ist. - -* In Zeilen, die mit `===` oder `!!!` beginnen, übersetzen Sie nur den ` "... Text ..."`-Teil. Lassen Sie den Rest unverändert. - -* Sie können Info-Boxen wie `!!! warning` mit beispielsweise `!!! warning "Achtung"` übersetzen. Aber ändern Sie nicht das Wort direkt nach dem `!!!`, es bestimmt die Farbe der Info-Box. - -* Ändern Sie nicht die Pfade in Links zu Bildern, Codedateien, Markdown Dokumenten. - -* Wenn ein Markdown-Dokument übersetzt ist, ändern sich allerdings unter Umständen die `#hash-teile` in Links zu dessen Überschriften. Aktualisieren Sie diese Links, wenn möglich. - * Suchen Sie im übersetzten Dokument nach solchen Links mit dem Regex `#[^# ]`. - * Suchen Sie in allen bereits in ihre Sprache übersetzen Dokumenten nach `ihr-ubersetztes-dokument.md`. VS Code hat beispielsweise eine Option „Bearbeiten“ -> „In Dateien suchen“. - * Übersetzen Sie bei der Übersetzung eines Dokuments nicht „im Voraus“ `#hash-teile`, die zu Überschriften in noch nicht übersetzten Dokumenten verlinken. - -## Tests - -Es gibt ein Skript, das Sie lokal ausführen können, um den gesamten Code zu testen und Code Coverage Reporte in HTML zu generieren: - -
- -```console -$ bash scripts/test-cov-html.sh -``` - -
- -Dieses Kommando generiert ein Verzeichnis `./htmlcov/`. Wenn Sie die Datei `./htmlcov/index.html` in Ihrem Browser öffnen, können Sie interaktiv die Codebereiche erkunden, die von den Tests abgedeckt werden, und feststellen, ob Bereiche fehlen. diff --git a/docs/de/docs/deployment/concepts.md b/docs/de/docs/deployment/concepts.md index 3c1c0cfce..97ad854e2 100644 --- a/docs/de/docs/deployment/concepts.md +++ b/docs/de/docs/deployment/concepts.md @@ -151,7 +151,7 @@ Und dennoch möchten Sie wahrscheinlich nicht, dass die Anwendung tot bleibt, we Aber in den Fällen mit wirklich schwerwiegenden Fehlern, die den laufenden **Prozess** zum Absturz bringen, benötigen Sie eine externe Komponente, die den Prozess **neu startet**, zumindest ein paar Mal ... -/// tip | "Tipp" +/// tip | Tipp ... Obwohl es wahrscheinlich keinen Sinn macht, sie immer wieder neu zu starten, wenn die gesamte Anwendung einfach **sofort abstürzt**. Aber in diesen Fällen werden Sie es wahrscheinlich während der Entwicklung oder zumindest direkt nach dem Deployment bemerken. @@ -241,7 +241,7 @@ Hier sind einige mögliche Kombinationen und Strategien: * **Cloud-Dienste**, welche das für Sie erledigen * Der Cloud-Dienst wird wahrscheinlich **die Replikation für Sie übernehmen**. Er würde Sie möglicherweise **einen auszuführenden Prozess** oder ein **zu verwendendes Container-Image** definieren lassen, in jedem Fall wäre es höchstwahrscheinlich **ein einzelner Uvicorn-Prozess**, und der Cloud-Dienst wäre auch verantwortlich für die Replikation. -/// tip | "Tipp" +/// tip | Tipp Machen Sie sich keine Sorgen, wenn einige dieser Punkte zu **Containern**, Docker oder Kubernetes noch nicht viel Sinn ergeben. @@ -263,7 +263,7 @@ Und Sie müssen sicherstellen, dass es sich um einen einzelnen Prozess handelt, Natürlich gibt es Fälle, in denen es kein Problem darstellt, die Vorab-Schritte mehrmals auszuführen. In diesem Fall ist die Handhabung viel einfacher. -/// tip | "Tipp" +/// tip | Tipp Bedenken Sie außerdem, dass Sie, abhängig von Ihrer Einrichtung, in manchen Fällen **gar keine Vorab-Schritte** benötigen, bevor Sie die Anwendung starten. @@ -281,7 +281,7 @@ Hier sind einige mögliche Ideen: * Ein Bash-Skript, das die Vorab-Schritte ausführt und dann Ihre Anwendung startet * Sie benötigen immer noch eine Möglichkeit, *dieses* Bash-Skript zu starten/neu zu starten, Fehler zu erkennen, usw. -/// tip | "Tipp" +/// tip | Tipp Konkretere Beispiele hierfür mit Containern gebe ich Ihnen in einem späteren Kapitel: [FastAPI in Containern – Docker](docker.md){.internal-link target=_blank}. diff --git a/docs/de/docs/deployment/docker.md b/docs/de/docs/deployment/docker.md index c11dc4127..a2734e068 100644 --- a/docs/de/docs/deployment/docker.md +++ b/docs/de/docs/deployment/docker.md @@ -4,7 +4,7 @@ Beim Deployment von FastAPI-Anwendungen besteht ein gängiger Ansatz darin, ein Die Verwendung von Linux-Containern bietet mehrere Vorteile, darunter **Sicherheit**, **Replizierbarkeit**, **Einfachheit** und andere. -/// tip | "Tipp" +/// tip | Tipp Sie haben es eilig und kennen sich bereits aus? Springen Sie zum [`Dockerfile` unten 👇](#ein-docker-image-fur-fastapi-erstellen). @@ -231,7 +231,7 @@ CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] Da das Programm unter `/code` gestartet wird und sich darin das Verzeichnis `./app` mit Ihrem Code befindet, kann **Uvicorn** `app` sehen und aus `app.main` **importieren**. -/// tip | "Tipp" +/// tip | Tipp Lernen Sie, was jede Zeile bewirkt, indem Sie auf die Zahlenblasen im Code klicken. 👆 @@ -305,7 +305,7 @@ $ docker build -t myimage . -/// tip | "Tipp" +/// tip | Tipp Beachten Sie das `.` am Ende, es entspricht `./` und teilt Docker mit, welches Verzeichnis zum Erstellen des Containerimages verwendet werden soll. @@ -409,7 +409,7 @@ Wenn wir uns nur auf das **Containerimage** für eine FastAPI-Anwendung (und sp Es könnte sich um einen anderen Container handeln, zum Beispiel mit Traefik, welcher **HTTPS** und **automatischen** Erwerb von **Zertifikaten** handhabt. -/// tip | "Tipp" +/// tip | Tipp Traefik verfügt über Integrationen mit Docker, Kubernetes und anderen, sodass Sie damit ganz einfach HTTPS für Ihre Container einrichten und konfigurieren können. @@ -441,7 +441,7 @@ Bei der Verwendung von Containern ist normalerweise eine Komponente vorhanden, * Da diese Komponente die **Last** an Requests aufnehmen und diese (hoffentlich) **ausgewogen** auf die Worker verteilen würde, wird sie üblicherweise auch **Load Balancer** – Lastverteiler – genannt. -/// tip | "Tipp" +/// tip | Tipp Die gleiche **TLS-Terminierungsproxy**-Komponente, die für HTTPS verwendet wird, wäre wahrscheinlich auch ein **Load Balancer**. @@ -544,7 +544,7 @@ Dieses Image wäre vor allem in den oben beschriebenen Situationen nützlich: [C * tiangolo/uvicorn-gunicorn-fastapi. -/// warning | "Achtung" +/// warning | Achtung Es besteht eine hohe Wahrscheinlichkeit, dass Sie dieses oder ein ähnliches Basisimage **nicht** benötigen und es besser wäre, wenn Sie das Image von Grund auf neu erstellen würden, wie [oben beschrieben in: Ein Docker-Image für FastAPI erstellen](#ein-docker-image-fur-fastapi-erstellen). @@ -556,7 +556,7 @@ Es verfügt über **vernünftige Standardeinstellungen**, aber Sie können trotz Es unterstützt auch die Ausführung von **Vorab-Schritten vor dem Start** mit einem Skript. -/// tip | "Tipp" +/// tip | Tipp Um alle Konfigurationen und Optionen anzuzeigen, gehen Sie zur Docker-Image-Seite: tiangolo/uvicorn-gunicorn-fastapi. @@ -687,7 +687,7 @@ CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] 11. Führe den Befehl `uvicorn` aus und weise ihn an, das aus `app.main` importierte `app`-Objekt zu verwenden. -/// tip | "Tipp" +/// tip | Tipp Klicken Sie auf die Zahlenblasen, um zu sehen, was jede Zeile bewirkt. diff --git a/docs/de/docs/deployment/https.md b/docs/de/docs/deployment/https.md index b1f0aca77..630582995 100644 --- a/docs/de/docs/deployment/https.md +++ b/docs/de/docs/deployment/https.md @@ -4,7 +4,7 @@ Es ist leicht anzunehmen, dass HTTPS etwas ist, was einfach nur „aktiviert“ Aber es ist viel komplexer als das. -/// tip | "Tipp" +/// tip | Tipp Wenn Sie es eilig haben oder es Ihnen egal ist, fahren Sie mit den nächsten Abschnitten fort, um Schritt-für-Schritt-Anleitungen für die Einrichtung der verschiedenen Technologien zu erhalten. @@ -71,7 +71,7 @@ In dem oder den DNS-Server(n) würden Sie einen Eintrag (einen „`A record`“) Sie würden dies wahrscheinlich nur einmal tun, beim ersten Mal, wenn Sie alles einrichten. -/// tip | "Tipp" +/// tip | Tipp Dieser Domainnamen-Aspekt liegt weit vor HTTPS, aber da alles von der Domain und der IP-Adresse abhängt, lohnt es sich, das hier zu erwähnen. @@ -121,7 +121,7 @@ Danach verfügen der Client und der Server über eine **verschlüsselte TCP-Verb Und genau das ist **HTTPS**, es ist einfach **HTTP** innerhalb einer **sicheren TLS-Verbindung**, statt einer puren (unverschlüsselten) TCP-Verbindung. -/// tip | "Tipp" +/// tip | Tipp Beachten Sie, dass die Verschlüsselung der Kommunikation auf der **TCP-Ebene** und nicht auf der HTTP-Ebene erfolgt. diff --git a/docs/de/docs/deployment/manually.md b/docs/de/docs/deployment/manually.md index 2b4ed3fad..fdb33f7fe 100644 --- a/docs/de/docs/deployment/manually.md +++ b/docs/de/docs/deployment/manually.md @@ -36,7 +36,7 @@ $ pip install "uvicorn[standard]" -/// tip | "Tipp" +/// tip | Tipp Durch das Hinzufügen von `standard` installiert und verwendet Uvicorn einige empfohlene zusätzliche Abhängigkeiten. @@ -96,7 +96,7 @@ Running on 0.0.0.0:8080 over http (CTRL + C to quit) //// -/// warning | "Achtung" +/// warning | Achtung Denken Sie daran, die Option `--reload` zu entfernen, wenn Sie diese verwendet haben. diff --git a/docs/de/docs/deployment/versions.md b/docs/de/docs/deployment/versions.md index 2d10ac4b6..5b8c69754 100644 --- a/docs/de/docs/deployment/versions.md +++ b/docs/de/docs/deployment/versions.md @@ -42,7 +42,7 @@ Gemäß den Konventionen zur semantischen Versionierung könnte jede Version unt FastAPI folgt auch der Konvention, dass jede „PATCH“-Versionsänderung für Bugfixes und abwärtskompatible Änderungen gedacht ist. -/// tip | "Tipp" +/// tip | Tipp Der „PATCH“ ist die letzte Zahl, zum Beispiel ist in `0.2.3` die PATCH-Version `3`. @@ -56,7 +56,7 @@ fastapi>=0.45.0,<0.46.0 Nicht abwärtskompatible Änderungen und neue Funktionen werden in „MINOR“-Versionen hinzugefügt. -/// tip | "Tipp" +/// tip | Tipp „MINOR“ ist die Zahl in der Mitte, zum Beispiel ist in `0.2.3` die MINOR-Version `2`. diff --git a/docs/de/docs/help-fastapi.md b/docs/de/docs/help-fastapi.md index 2c84a5e5b..0b9c52316 100644 --- a/docs/de/docs/help-fastapi.md +++ b/docs/de/docs/help-fastapi.md @@ -228,7 +228,7 @@ Wenn Sie mir dabei helfen können, **helfen Sie mir, FastAPI am Laufen zu erhalt Treten Sie dem 👥 Discord-Chatserver 👥 bei und treffen Sie sich mit anderen Mitgliedern der FastAPI-Community. -/// tip | "Tipp" +/// tip | Tipp Wenn Sie Fragen haben, stellen Sie sie bei GitHub Diskussionen, es besteht eine viel bessere Chance, dass Sie hier Hilfe von den [FastAPI-Experten](fastapi-people.md#experten){.internal-link target=_blank} erhalten. diff --git a/docs/de/docs/how-to/configure-swagger-ui.md b/docs/de/docs/how-to/configure-swagger-ui.md index 31b9cd290..1ee72d205 100644 --- a/docs/de/docs/how-to/configure-swagger-ui.md +++ b/docs/de/docs/how-to/configure-swagger-ui.md @@ -18,9 +18,7 @@ Ohne Änderung der Einstellungen ist die Syntaxhervorhebung standardmäßig akti Sie können sie jedoch deaktivieren, indem Sie `syntaxHighlight` auf `False` setzen: -```Python hl_lines="3" -{!../../docs_src/configure_swagger_ui/tutorial001.py!} -``` +{* ../../docs_src/configure_swagger_ui/tutorial001.py hl[3] *} ... und dann zeigt die Swagger-Oberfläche die Syntaxhervorhebung nicht mehr an: @@ -30,9 +28,7 @@ Sie können sie jedoch deaktivieren, indem Sie `syntaxHighlight` auf `False` set Auf die gleiche Weise könnten Sie das Theme der Syntaxhervorhebung mit dem Schlüssel `syntaxHighlight.theme` festlegen (beachten Sie, dass er einen Punkt in der Mitte hat): -```Python hl_lines="3" -{!../../docs_src/configure_swagger_ui/tutorial002.py!} -``` +{* ../../docs_src/configure_swagger_ui/tutorial002.py hl[3] *} Obige Konfiguration würde das Theme für die Farbe der Syntaxhervorhebung ändern: @@ -44,17 +40,13 @@ FastAPI enthält einige Defaultkonfigurationsparameter, die für die meisten Anw Es umfasst die folgenden Defaultkonfigurationen: -```Python -{!../../fastapi/openapi/docs.py[ln:7-23]!} -``` +{* ../../fastapi/openapi/docs.py ln[7:23] *} Sie können jede davon überschreiben, indem Sie im Argument `swagger_ui_parameters` einen anderen Wert festlegen. Um beispielsweise `deepLinking` zu deaktivieren, könnten Sie folgende Einstellungen an `swagger_ui_parameters` übergeben: -```Python hl_lines="3" -{!../../docs_src/configure_swagger_ui/tutorial003.py!} -``` +{* ../../docs_src/configure_swagger_ui/tutorial003.py hl[3] *} ## Andere Parameter der Swagger-Oberfläche diff --git a/docs/de/docs/how-to/custom-docs-ui-assets.md b/docs/de/docs/how-to/custom-docs-ui-assets.md index e5fd20a10..a292be69b 100644 --- a/docs/de/docs/how-to/custom-docs-ui-assets.md +++ b/docs/de/docs/how-to/custom-docs-ui-assets.md @@ -40,7 +40,7 @@ Und genau so für ReDoc ... {!../../docs_src/custom_docs_ui/tutorial001.py!} ``` -/// tip | "Tipp" +/// tip | Tipp Die *Pfadoperation* für `swagger_ui_redirect` ist ein Hilfsmittel bei der Verwendung von OAuth2. @@ -180,7 +180,7 @@ Und genau so für ReDoc ... {!../../docs_src/custom_docs_ui/tutorial002.py!} ``` -/// tip | "Tipp" +/// tip | Tipp Die *Pfadoperation* für `swagger_ui_redirect` ist ein Hilfsmittel bei der Verwendung von OAuth2. 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 f81fa1da3..ef71d96dc 100644 --- a/docs/de/docs/how-to/custom-request-and-route.md +++ b/docs/de/docs/how-to/custom-request-and-route.md @@ -6,7 +6,7 @@ Das kann insbesondere eine gute Alternative zur Logik in einer Middleware sein. Wenn Sie beispielsweise den Requestbody lesen oder manipulieren möchten, bevor er von Ihrer Anwendung verarbeitet wird. -/// danger | "Gefahr" +/// danger | Gefahr Dies ist eine „fortgeschrittene“ Funktion. @@ -30,7 +30,7 @@ Und eine `APIRoute`-Unterklasse zur Verwendung dieser benutzerdefinierten Reques ### Eine benutzerdefinierte `GzipRequest`-Klasse erstellen -/// tip | "Tipp" +/// tip | Tipp Dies ist nur ein einfaches Beispiel, um zu demonstrieren, wie es funktioniert. Wenn Sie Gzip-Unterstützung benötigen, können Sie die bereitgestellte [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank} verwenden. @@ -60,7 +60,7 @@ Hier verwenden wir sie, um aus dem ursprünglichen Request einen `GzipRequest` z {!../../docs_src/custom_request_and_route/tutorial001.py!} ``` -/// note | "Technische Details" +/// note | Technische Details Ein `Request` hat ein `request.scope`-Attribut, welches einfach ein Python-`dict` ist, welches die mit dem Request verbundenen Metadaten enthält. @@ -84,7 +84,7 @@ Aufgrund unserer Änderungen in `GzipRequest.body` wird der Requestbody jedoch b ## Zugriff auf den Requestbody in einem Exceptionhandler -/// tip | "Tipp" +/// tip | Tipp Um dasselbe Problem zu lösen, ist es wahrscheinlich viel einfacher, den `body` in einem benutzerdefinierten Handler für `RequestValidationError` zu verwenden ([Fehlerbehandlung](../tutorial/handling-errors.md#den-requestvalidationerror-body-verwenden){.internal-link target=_blank}). diff --git a/docs/de/docs/how-to/graphql.md b/docs/de/docs/how-to/graphql.md index cde56ffde..4366ea52d 100644 --- a/docs/de/docs/how-to/graphql.md +++ b/docs/de/docs/how-to/graphql.md @@ -4,7 +4,7 @@ Da **FastAPI** auf dem **ASGI**-Standard basiert, ist es sehr einfach, jede **Gr Sie können normale FastAPI-*Pfadoperationen* mit GraphQL in derselben Anwendung kombinieren. -/// tip | "Tipp" +/// tip | Tipp **GraphQL** löst einige sehr spezifische Anwendungsfälle. @@ -49,7 +49,7 @@ Frühere Versionen von Starlette enthielten eine `GraphQLApp`-Klasse zur Integra Das wurde von Starlette deprecated, aber wenn Sie Code haben, der das verwendet, können Sie einfach zu starlette-graphene3 **migrieren**, welches denselben Anwendungsfall abdeckt und über eine **fast identische Schnittstelle** verfügt. -/// tip | "Tipp" +/// tip | Tipp Wenn Sie GraphQL benötigen, würde ich Ihnen trotzdem empfehlen, sich Strawberry anzuschauen, da es auf Typannotationen basiert, statt auf benutzerdefinierten Klassen und Typen. diff --git a/docs/de/docs/how-to/index.md b/docs/de/docs/how-to/index.md index 75779a01c..84a178fc8 100644 --- a/docs/de/docs/how-to/index.md +++ b/docs/de/docs/how-to/index.md @@ -6,7 +6,7 @@ Die meisten dieser Ideen sind mehr oder weniger **unabhängig**, und in den meis Wenn etwas für Ihr Projekt interessant und nützlich erscheint, lesen Sie es, andernfalls überspringen Sie es einfach. -/// tip | "Tipp" +/// tip | Tipp Wenn Sie strukturiert **FastAPI lernen** möchten (empfohlen), lesen Sie stattdessen Kapitel für Kapitel das [Tutorial – Benutzerhandbuch](../tutorial/index.md){.internal-link target=_blank}. diff --git a/docs/de/docs/python-types.md b/docs/de/docs/python-types.md index a43bf5ffe..81d43bc5b 100644 --- a/docs/de/docs/python-types.md +++ b/docs/de/docs/python-types.md @@ -12,7 +12,7 @@ Dies ist lediglich eine **schnelle Anleitung / Auffrischung** über Pythons Typh Aber selbst wenn Sie **FastAPI** nie verwenden, wird es für Sie nützlich sein, ein wenig darüber zu lernen. -/// note | "Hinweis" +/// note | Hinweis Wenn Sie ein Python-Experte sind und bereits alles über Typhinweise wissen, überspringen Sie dieses Kapitel und fahren Sie mit dem nächsten fort. @@ -22,9 +22,7 @@ Wenn Sie ein Python-Experte sind und bereits alles über Typhinweise wissen, üb Fangen wir mit einem einfachen Beispiel an: -```Python -{!../../docs_src/python_types/tutorial001.py!} -``` +{* ../../docs_src/python_types/tutorial001.py *} Dieses Programm gibt aus: @@ -38,9 +36,7 @@ Die Funktion macht Folgendes: * Schreibt den ersten Buchstaben eines jeden Wortes groß, mithilfe von `title()`. * Verkettet sie mit einem Leerzeichen in der Mitte. -```Python hl_lines="2" -{!../../docs_src/python_types/tutorial001.py!} -``` +{* ../../docs_src/python_types/tutorial001.py hl[2] *} ### Bearbeiten Sie es @@ -82,9 +78,7 @@ Das war's. Das sind die „Typhinweise“: -```Python hl_lines="1" -{!../../docs_src/python_types/tutorial002.py!} -``` +{* ../../docs_src/python_types/tutorial002.py hl[1] *} Das ist nicht das gleiche wie das Deklarieren von Defaultwerten, wie es hier der Fall ist: @@ -112,9 +106,7 @@ Hier können Sie durch die Optionen blättern, bis Sie diejenige finden, bei der Sehen Sie sich diese Funktion an, sie hat bereits Typhinweise: -```Python hl_lines="1" -{!../../docs_src/python_types/tutorial003.py!} -``` +{* ../../docs_src/python_types/tutorial003.py hl[1] *} Da der Editor die Typen der Variablen kennt, erhalten Sie nicht nur Code-Vervollständigung, sondern auch eine Fehlerprüfung: @@ -122,9 +114,7 @@ Da der Editor die Typen der Variablen kennt, erhalten Sie nicht nur Code-Vervoll Jetzt, da Sie wissen, dass Sie das reparieren müssen, konvertieren Sie `age` mittels `str(age)` in einen String: -```Python hl_lines="2" -{!../../docs_src/python_types/tutorial004.py!} -``` +{* ../../docs_src/python_types/tutorial004.py hl[2] *} ## Deklarieren von Typen @@ -143,9 +133,7 @@ Zum Beispiel diese: * `bool` * `bytes` -```Python hl_lines="1" -{!../../docs_src/python_types/tutorial005.py!} -``` +{* ../../docs_src/python_types/tutorial005.py hl[1] *} ### Generische Typen mit Typ-Parametern @@ -207,7 +195,7 @@ Da die Liste ein Typ ist, welcher innere Typen enthält, werden diese von eckige //// -/// tip | "Tipp" +/// tip | Tipp Die inneren Typen in den eckigen Klammern werden als „Typ-Parameter“ bezeichnet. @@ -217,7 +205,7 @@ In diesem Fall ist `str` der Typ-Parameter, der an `List` übergeben wird (oder Das bedeutet: Die Variable `items` ist eine Liste – `list` – und jedes der Elemente in dieser Liste ist ein String – `str`. -/// tip | "Tipp" +/// tip | Tipp Wenn Sie Python 3.9 oder höher verwenden, müssen Sie `List` nicht von `typing` importieren, Sie können stattdessen den regulären `list`-Typ verwenden. @@ -320,9 +308,7 @@ Sie können deklarieren, dass ein Wert ein `str`, aber vielleicht auch `None` se In Python 3.6 und darüber (inklusive Python 3.10) können Sie das deklarieren, indem Sie `Optional` vom `typing` Modul importieren und verwenden. -```Python hl_lines="1 4" -{!../../docs_src/python_types/tutorial009.py!} -``` +{* ../../docs_src/python_types/tutorial009.py hl[1,4] *} Wenn Sie `Optional[str]` anstelle von nur `str` verwenden, wird Ihr Editor Ihnen dabei helfen, Fehler zu erkennen, bei denen Sie annehmen könnten, dass ein Wert immer eine String (`str`) ist, obwohl er auch `None` sein könnte. @@ -369,9 +355,7 @@ Es geht nur um Wörter und Namen. Aber diese Worte können beeinflussen, wie Sie Nehmen wir zum Beispiel diese Funktion: -```Python hl_lines="1 4" -{!../../docs_src/python_types/tutorial009c.py!} -``` +{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *} Der Parameter `name` ist definiert als `Optional[str]`, aber er ist **nicht optional**, Sie können die Funktion nicht ohne diesen Parameter aufrufen: @@ -387,9 +371,7 @@ say_hi(name=None) # Das funktioniert, None is gültig 🎉 Die gute Nachricht ist, dass Sie sich darüber keine Sorgen mehr machen müssen, wenn Sie Python 3.10 verwenden, da Sie einfach `|` verwenden können, um Vereinigungen von Typen zu definieren: -```Python hl_lines="1 4" -{!../../docs_src/python_types/tutorial009c_py310.py!} -``` +{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *} Und dann müssen Sie sich nicht mehr um Namen wie `Optional` und `Union` kümmern. 😎 @@ -451,15 +433,11 @@ Sie können auch eine Klasse als Typ einer Variablen deklarieren. Nehmen wir an, Sie haben eine Klasse `Person`, mit einem Namen: -```Python hl_lines="1-3" -{!../../docs_src/python_types/tutorial010.py!} -``` +{* ../../docs_src/python_types/tutorial010.py hl[1:3] *} Dann können Sie eine Variable vom Typ `Person` deklarieren: -```Python hl_lines="6" -{!../../docs_src/python_types/tutorial010.py!} -``` +{* ../../docs_src/python_types/tutorial010.py hl[6] *} Und wiederum bekommen Sie die volle Editor-Unterstützung: @@ -517,7 +495,7 @@ Um mehr über Required fields mehr erfahren. @@ -559,7 +537,7 @@ Im Moment müssen Sie nur wissen, dass `Annotated` existiert, und dass es Standa Später werden Sie sehen, wie **mächtig** es sein kann. -/// tip | "Tipp" +/// tip | Tipp Der Umstand, dass es **Standard-Python** ist, bedeutet, dass Sie immer noch die **bestmögliche Entwickler-Erfahrung** in ihrem Editor haben, sowie mit den Tools, die Sie nutzen, um ihren Code zu analysieren, zu refaktorisieren, usw. ✨ diff --git a/docs/de/docs/tutorial/background-tasks.md b/docs/de/docs/tutorial/background-tasks.md index cd857f5e7..fc699daf4 100644 --- a/docs/de/docs/tutorial/background-tasks.md +++ b/docs/de/docs/tutorial/background-tasks.md @@ -83,7 +83,7 @@ Die Verwendung von `BackgroundTasks` funktioniert auch mit dem ../../docs_src/body_multiple_params/tutorial001_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="18-20" -{!> ../../docs_src/body_multiple_params/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="19-21" -{!> ../../docs_src/body_multiple_params/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.10+ nicht annotiert - -/// tip | "Tipp" - -Bevorzugen Sie die `Annotated`-Version, falls möglich. - -/// - -```Python hl_lines="17-19" -{!> ../../docs_src/body_multiple_params/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.8+ nicht annotiert - -/// tip | "Tipp" - -Bevorzugen Sie die `Annotated`-Version, falls möglich. - -/// - -```Python hl_lines="19-21" -{!> ../../docs_src/body_multiple_params/tutorial001.py!} -``` - -//// - -/// note | "Hinweis" +/// note | Hinweis Beachten Sie, dass in diesem Fall das `item`, welches vom Body genommen wird, optional ist. Da es `None` als Defaultwert hat. @@ -81,21 +31,7 @@ Im vorherigen Beispiel erwartete die *Pfadoperation* einen JSON-Body mit den Att Aber Sie können auch mehrere Body-Parameter deklarieren, z. B. `item` und `user`: -//// tab | Python 3.10+ - -```Python hl_lines="20" -{!> ../../docs_src/body_multiple_params/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="22" -{!> ../../docs_src/body_multiple_params/tutorial002.py!} -``` - -//// +{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *} In diesem Fall wird **FastAPI** bemerken, dass es mehr als einen Body-Parameter in der Funktion gibt (zwei Parameter, die Pydantic-Modelle sind). @@ -116,7 +52,7 @@ Es wird deshalb die Parameternamen als Schlüssel (Feldnamen) im Body verwenden, } ``` -/// note | "Hinweis" +/// note | Hinweis Beachten Sie, dass, obwohl `item` wie zuvor deklariert wurde, es nun unter einem Schlüssel `item` im Body erwartet wird. @@ -136,57 +72,7 @@ Wenn Sie diesen Parameter einfach so hinzufügen, wird **FastAPI** annehmen, das Aber Sie können **FastAPI** instruieren, ihn als weiteren Body-Schlüssel zu erkennen, indem Sie `Body` verwenden: -//// tab | Python 3.10+ - -```Python hl_lines="23" -{!> ../../docs_src/body_multiple_params/tutorial003_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="23" -{!> ../../docs_src/body_multiple_params/tutorial003_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="24" -{!> ../../docs_src/body_multiple_params/tutorial003_an.py!} -``` - -//// - -//// tab | Python 3.10+ nicht annotiert - -/// tip | "Tipp" - -Bevorzugen Sie die `Annotated`-Version, falls möglich. - -/// - -```Python hl_lines="20" -{!> ../../docs_src/body_multiple_params/tutorial003_py310.py!} -``` - -//// - -//// tab | Python 3.8+ nicht annotiert - -/// tip | "Tipp" - -Bevorzugen Sie die `Annotated`-Version, falls möglich. - -/// - -```Python hl_lines="22" -{!> ../../docs_src/body_multiple_params/tutorial003.py!} -``` - -//// +{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *} In diesem Fall erwartet **FastAPI** einen Body wie: @@ -226,57 +112,7 @@ q: str | None = None Zum Beispiel: -//// tab | Python 3.10+ - -```Python hl_lines="27" -{!> ../../docs_src/body_multiple_params/tutorial004_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="27" -{!> ../../docs_src/body_multiple_params/tutorial004_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="28" -{!> ../../docs_src/body_multiple_params/tutorial004_an.py!} -``` - -//// - -//// tab | Python 3.10+ nicht annotiert - -/// tip | "Tipp" - -Bevorzugen Sie die `Annotated`-Version, falls möglich. - -/// - -```Python hl_lines="25" -{!> ../../docs_src/body_multiple_params/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.8+ nicht annotiert - -/// tip | "Tipp" - -Bevorzugen Sie die `Annotated`-Version, falls möglich. - -/// - -```Python hl_lines="27" -{!> ../../docs_src/body_multiple_params/tutorial004.py!} -``` - -//// +{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[27] *} /// info @@ -298,57 +134,7 @@ item: Item = Body(embed=True) so wie in: -//// tab | Python 3.10+ - -```Python hl_lines="17" -{!> ../../docs_src/body_multiple_params/tutorial005_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="17" -{!> ../../docs_src/body_multiple_params/tutorial005_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="18" -{!> ../../docs_src/body_multiple_params/tutorial005_an.py!} -``` - -//// - -//// tab | Python 3.10+ nicht annotiert - -/// tip | "Tipp" - -Bevorzugen Sie die `Annotated`-Version, falls möglich. - -/// - -```Python hl_lines="15" -{!> ../../docs_src/body_multiple_params/tutorial005_py310.py!} -``` - -//// - -//// tab | Python 3.8+ nicht annotiert - -/// tip | "Tipp" - -Bevorzugen Sie die `Annotated`-Version, falls möglich. - -/// - -```Python hl_lines="17" -{!> ../../docs_src/body_multiple_params/tutorial005.py!} -``` - -//// +{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *} In diesem Fall erwartet **FastAPI** einen Body wie: diff --git a/docs/de/docs/tutorial/body-nested-models.md b/docs/de/docs/tutorial/body-nested-models.md index 13153aa68..478064a8b 100644 --- a/docs/de/docs/tutorial/body-nested-models.md +++ b/docs/de/docs/tutorial/body-nested-models.md @@ -420,7 +420,7 @@ Im folgenden Beispiel akzeptieren Sie irgendein `dict`, solange es `int`-Schlüs //// -/// tip | "Tipp" +/// tip | Tipp Bedenken Sie, dass JSON nur `str` als Schlüssel unterstützt. diff --git a/docs/de/docs/tutorial/body-updates.md b/docs/de/docs/tutorial/body-updates.md index ed5c1890f..01a534a23 100644 --- a/docs/de/docs/tutorial/body-updates.md +++ b/docs/de/docs/tutorial/body-updates.md @@ -54,7 +54,7 @@ Sie können auch die -/// tip | "Tipp" +/// tip | Tipp Wenn Sie PyCharm als Ihren Editor verwenden, probieren Sie das Pydantic PyCharm Plugin aus. @@ -233,7 +233,7 @@ Die Funktionsparameter werden wie folgt erkannt: * Wenn der Parameter ein **einfacher Typ** ist (wie `int`, `float`, `str`, `bool`, usw.), wird er als **Query**-Parameter interpretiert. * Wenn der Parameter vom Typ eines **Pydantic-Modells** ist, wird er als Request**body** interpretiert. -/// note | "Hinweis" +/// note | Hinweis FastAPI weiß, dass der Wert von `q` nicht erforderlich ist, wegen des definierten Defaultwertes `= None` diff --git a/docs/de/docs/tutorial/cookie-params.md b/docs/de/docs/tutorial/cookie-params.md index 4714a59ae..ecb14ad03 100644 --- a/docs/de/docs/tutorial/cookie-params.md +++ b/docs/de/docs/tutorial/cookie-params.md @@ -32,7 +32,7 @@ Importieren Sie zuerst `Cookie`: //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -46,7 +46,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -90,7 +90,7 @@ Der erste Wert ist der Typ. Sie können `Cookie` die gehabten Extra Validierungs //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -104,7 +104,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -116,7 +116,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// -/// note | "Technische Details" +/// note | Technische Details `Cookie` ist eine Schwesterklasse von `Path` und `Query`. Sie erbt von derselben gemeinsamen `Param`-Elternklasse. diff --git a/docs/de/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/de/docs/tutorial/dependencies/classes-as-dependencies.md index a660ab337..a3e3d2c60 100644 --- a/docs/de/docs/tutorial/dependencies/classes-as-dependencies.md +++ b/docs/de/docs/tutorial/dependencies/classes-as-dependencies.md @@ -32,7 +32,7 @@ Im vorherigen Beispiel haben wir ein `dict` von unserer Abhängigkeit („Depend //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -46,7 +46,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -145,7 +145,7 @@ Dann können wir das „Dependable“ `common_parameters` der Abhängigkeit von //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -159,7 +159,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -199,7 +199,7 @@ Achten Sie auf die Methode `__init__`, die zum Erstellen der Instanz der Klasse //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -213,7 +213,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -253,7 +253,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -267,7 +267,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -319,7 +319,7 @@ Jetzt können Sie Ihre Abhängigkeit mithilfe dieser Klasse deklarieren. //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -333,7 +333,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -361,7 +361,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -397,7 +397,7 @@ commons: Annotated[CommonQueryParams, ... //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -423,7 +423,7 @@ commons: Annotated[Any, Depends(CommonQueryParams)] //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -463,7 +463,7 @@ commons = Depends(CommonQueryParams) //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -477,7 +477,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -507,7 +507,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -535,7 +535,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -559,7 +559,7 @@ commons: Annotated[CommonQueryParams, Depends()] //// tab | Python 3.8 nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -601,7 +601,7 @@ Dasselbe Beispiel würde dann so aussehen: //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -615,7 +615,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -629,7 +629,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. ... und **FastAPI** wird wissen, was zu tun ist. -/// tip | "Tipp" +/// tip | Tipp Wenn Sie das eher verwirrt, als Ihnen zu helfen, ignorieren Sie es, Sie *brauchen* es nicht. diff --git a/docs/de/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/de/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md index 3bb261e44..6aa5ef199 100644 --- a/docs/de/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md +++ b/docs/de/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md @@ -32,7 +32,7 @@ Es sollte eine `list`e von `Depends()` sein: //// tab | Python 3.8 nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -46,7 +46,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. Diese Abhängigkeiten werden auf die gleiche Weise wie normale Abhängigkeiten ausgeführt/aufgelöst. Aber ihr Wert (falls sie einen zurückgeben) wird nicht an Ihre *Pfadoperation-Funktion* übergeben. -/// tip | "Tipp" +/// tip | Tipp Einige Editoren prüfen, ob Funktionsparameter nicht verwendet werden, und zeigen das als Fehler an. @@ -90,7 +90,7 @@ Sie können Anforderungen für einen Request (wie Header) oder andere Unterabhä //// tab | Python 3.8 nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -124,7 +124,7 @@ Die Abhängigkeiten können Exceptions `raise`n, genau wie normale Abhängigkeit //// tab | Python 3.8 nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -160,7 +160,7 @@ Sie können also eine normale Abhängigkeit (die einen Wert zurückgibt), die Si //// tab | Python 3.8 nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. diff --git a/docs/de/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/de/docs/tutorial/dependencies/dependencies-with-yield.md index 48b057e28..ce6bbad69 100644 --- a/docs/de/docs/tutorial/dependencies/dependencies-with-yield.md +++ b/docs/de/docs/tutorial/dependencies/dependencies-with-yield.md @@ -4,13 +4,13 @@ FastAPI unterstützt Abhängigkeiten, die nach Abschluss einige Kontextmanager. @@ -163,7 +163,7 @@ Sie haben gesehen, dass Ihre Abhängigkeiten `yield` verwenden können und `try` Auf die gleiche Weise könnten Sie im Exit-Code nach dem `yield` eine `HTTPException` oder ähnliches auslösen. -/// tip | "Tipp" +/// tip | Tipp Dies ist eine etwas fortgeschrittene Technik, die Sie in den meisten Fällen nicht wirklich benötigen, da Sie Exceptions (einschließlich `HTTPException`) innerhalb des restlichen Anwendungscodes auslösen können, beispielsweise in der *Pfadoperation-Funktion*. @@ -189,7 +189,7 @@ Aber es ist für Sie da, wenn Sie es brauchen. 🤓 //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -250,7 +250,7 @@ Nachdem eine dieser Responses gesendet wurde, kann keine weitere Response gesend /// -/// tip | "Tipp" +/// tip | Tipp Obiges Diagramm verwendet `HTTPException`, aber Sie können auch jede andere Exception auslösen, die Sie in einer Abhängigkeit mit `yield` abfangen, oder mit einem [benutzerdefinierten Exceptionhandler](../handling-errors.md#benutzerdefinierte-exceptionhandler-definieren){.internal-link target=_blank} erstellt haben. @@ -260,7 +260,7 @@ Wenn Sie eine Exception auslösen, wird diese mit yield an die Abhängigkeiten ## Abhängigkeiten mit `yield`, `HTTPException` und Hintergrundtasks -/// warning | "Achtung" +/// warning | Achtung Sie benötigen diese technischen Details höchstwahrscheinlich nicht, Sie können diesen Abschnitt überspringen und weiter unten fortfahren. @@ -274,7 +274,7 @@ Dies wurde hauptsächlich so konzipiert, damit die gleichen Objekte, die durch A Da dies jedoch bedeuten würde, darauf zu warten, dass die Response durch das Netzwerk reist, während eine Ressource unnötigerweise in einer Abhängigkeit mit yield gehalten wird (z. B. eine Datenbankverbindung), wurde dies in FastAPI 0.106.0 geändert. -/// tip | "Tipp" +/// tip | Tipp Darüber hinaus handelt es sich bei einem Hintergrundtask normalerweise um einen unabhängigen Satz von Logik, der separat behandelt werden sollte, mit eigenen Ressourcen (z. B. einer eigenen Datenbankverbindung). @@ -308,7 +308,7 @@ Wenn Sie eine Abhängigkeit mit `yield` erstellen, erstellt **FastAPI** dafür i ### Kontextmanager in Abhängigkeiten mit `yield` verwenden -/// warning | "Achtung" +/// warning | Achtung Dies ist mehr oder weniger eine „fortgeschrittene“ Idee. @@ -324,7 +324,7 @@ Sie können solche auch innerhalb von **FastAPI**-Abhängigkeiten mit `yield` ve {!../../docs_src/dependencies/tutorial010.py!} ``` -/// tip | "Tipp" +/// tip | Tipp Andere Möglichkeiten, einen Kontextmanager zu erstellen, sind: diff --git a/docs/de/docs/tutorial/dependencies/global-dependencies.md b/docs/de/docs/tutorial/dependencies/global-dependencies.md index 6b9e9e395..4df9f64e9 100644 --- a/docs/de/docs/tutorial/dependencies/global-dependencies.md +++ b/docs/de/docs/tutorial/dependencies/global-dependencies.md @@ -24,7 +24,7 @@ In diesem Fall werden sie auf alle *Pfadoperationen* in der Anwendung angewendet //// tab | Python 3.8 nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. diff --git a/docs/de/docs/tutorial/dependencies/index.md b/docs/de/docs/tutorial/dependencies/index.md index 494708d19..2a4a5177a 100644 --- a/docs/de/docs/tutorial/dependencies/index.md +++ b/docs/de/docs/tutorial/dependencies/index.md @@ -56,7 +56,7 @@ Es handelt sich einfach um eine Funktion, die die gleichen Parameter entgegennim //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -70,7 +70,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -138,7 +138,7 @@ Bitte [aktualisieren Sie FastAPI](../../deployment/versions.md#upgrade-der-fasta //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -152,7 +152,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -194,7 +194,7 @@ So wie auch `Body`, `Query`, usw., verwenden Sie `Depends` mit den Parametern Ih //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -208,7 +208,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -230,7 +230,7 @@ Sie **rufen diese nicht direkt auf** (fügen Sie am Ende keine Klammern hinzu), Und diese Funktion akzeptiert Parameter auf die gleiche Weise wie *Pfadoperation-Funktionen*. -/// tip | "Tipp" +/// tip | Tipp Im nächsten Kapitel erfahren Sie, welche anderen „Dinge“, außer Funktionen, Sie als Abhängigkeiten verwenden können. @@ -299,7 +299,7 @@ Da wir jedoch `Annotated` verwenden, können wir diesen `Annotated`-Wert in eine //// -/// tip | "Tipp" +/// tip | Tipp Das ist schlicht Standard-Python, es wird als „Typalias“ bezeichnet und ist eigentlich nicht **FastAPI**-spezifisch. @@ -321,7 +321,7 @@ Und Sie können Abhängigkeiten mit `async def` innerhalb normaler `def`-*Pfadop Es spielt keine Rolle. **FastAPI** weiß, was zu tun ist. -/// note | "Hinweis" +/// note | Hinweis Wenn Ihnen das nichts sagt, lesen Sie den [Async: *„In Eile?“*](../../async.md#in-eile){.internal-link target=_blank}-Abschnitt über `async` und `await` in der Dokumentation. diff --git a/docs/de/docs/tutorial/dependencies/sub-dependencies.md b/docs/de/docs/tutorial/dependencies/sub-dependencies.md index a20aed63b..6da7c64de 100644 --- a/docs/de/docs/tutorial/dependencies/sub-dependencies.md +++ b/docs/de/docs/tutorial/dependencies/sub-dependencies.md @@ -36,7 +36,7 @@ Sie könnten eine erste Abhängigkeit („Dependable“) wie folgt erstellen: //// tab | Python 3.10 nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -50,7 +50,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8 nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -96,7 +96,7 @@ Dann können Sie eine weitere Abhängigkeitsfunktion (ein „Dependable“) erst //// tab | Python 3.10 nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -110,7 +110,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8 nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -159,7 +159,7 @@ Diese Abhängigkeit verwenden wir nun wie folgt: //// tab | Python 3.10 nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -173,7 +173,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8 nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -223,7 +223,7 @@ async def needy_dependency(fresh_value: Annotated[str, Depends(get_value, use_ca //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -244,7 +244,7 @@ Einfach Funktionen, die genauso aussehen wie *Pfadoperation-Funktionen*. Dennoch ist es sehr mächtig und ermöglicht Ihnen die Deklaration beliebig tief verschachtelter Abhängigkeits-„Graphen“ (Bäume). -/// tip | "Tipp" +/// tip | Tipp All dies scheint angesichts dieser einfachen Beispiele möglicherweise nicht so nützlich zu sein. diff --git a/docs/de/docs/tutorial/encoder.md b/docs/de/docs/tutorial/encoder.md index 0ab72b8dd..428eee287 100644 --- a/docs/de/docs/tutorial/encoder.md +++ b/docs/de/docs/tutorial/encoder.md @@ -42,7 +42,7 @@ Das Resultat dieses Aufrufs ist etwas, das mit Pythons Standard-gehashtes Passwort haben. -/// danger | "Gefahr" +/// danger | Gefahr Speichern Sie niemals das Klartext-Passwort eines Benutzers. Speichern Sie immer den „sicheren Hash“, den Sie verifizieren können. @@ -154,7 +154,7 @@ UserInDB( ) ``` -/// warning | "Achtung" +/// warning | Achtung Die Hilfsfunktionen `fake_password_hasher` und `fake_save_user` demonstrieren nur den möglichen Fluss der Daten und bieten natürlich keine echte Sicherheit. @@ -200,7 +200,7 @@ Das wird in OpenAPI mit `anyOf` angezeigt. Um das zu tun, verwenden Sie Pythons Standard-Typhinweis `typing.Union`: -/// note | "Hinweis" +/// note | Hinweis Listen Sie, wenn Sie eine `Union` definieren, denjenigen Typ zuerst, der am spezifischsten ist, gefolgt von den weniger spezifischen Typen. Im Beispiel oben, in `Union[PlaneItem, CarItem]` also den spezifischeren `PlaneItem` vor dem weniger spezifischen `CarItem`. diff --git a/docs/de/docs/tutorial/first-steps.md b/docs/de/docs/tutorial/first-steps.md index fe3886b70..debefb156 100644 --- a/docs/de/docs/tutorial/first-steps.md +++ b/docs/de/docs/tutorial/first-steps.md @@ -24,7 +24,7 @@ $ uvicorn main:app --reload -/// note | "Hinweis" +/// note | Hinweis Der Befehl `uvicorn main:app` bezieht sich auf: @@ -139,7 +139,7 @@ Ebenfalls können Sie es verwenden, um automatisch Code für Clients zu generier `FastAPI` ist eine Python-Klasse, die die gesamte Funktionalität für Ihre API bereitstellt. -/// note | "Technische Details" +/// note | Technische Details `FastAPI` ist eine Klasse, die direkt von `Starlette` erbt. @@ -259,7 +259,7 @@ Das `@app.get("/")` sagt **FastAPI**, dass die Funktion direkt darunter für die * den Pfad `/` * unter der Verwendung der get-Operation gehen -/// info | "`@decorator` Information" +/// info | `@decorator` Information Diese `@something`-Syntax wird in Python „Dekorator“ genannt. @@ -286,7 +286,7 @@ Oder die exotischeren: * `@app.patch()` * `@app.trace()` -/// tip | "Tipp" +/// tip | Tipp Es steht Ihnen frei, jede Operation (HTTP-Methode) so zu verwenden, wie Sie es möchten. @@ -324,7 +324,7 @@ Sie könnten sie auch als normale Funktion anstelle von `async def` definieren: {!../../docs_src/first_steps/tutorial003.py!} ``` -/// note | "Hinweis" +/// note | Hinweis Wenn Sie den Unterschied nicht kennen, lesen Sie [Async: *„In Eile?“*](../async.md#in-eile){.internal-link target=_blank}. diff --git a/docs/de/docs/tutorial/handling-errors.md b/docs/de/docs/tutorial/handling-errors.md index 70dc0c523..85de76ef1 100644 --- a/docs/de/docs/tutorial/handling-errors.md +++ b/docs/de/docs/tutorial/handling-errors.md @@ -63,7 +63,7 @@ Aber wenn der Client `http://example.com/items/bar` anfragt (ein nicht-existiere } ``` -/// tip | "Tipp" +/// tip | Tipp Wenn Sie eine `HTTPException` auslösen, können Sie dem Parameter `detail` jeden Wert übergeben, der nach JSON konvertiert werden kann, nicht nur `str`. @@ -109,7 +109,7 @@ Sie erhalten also einen sauberen Error mit einem Statuscode `418` und dem JSON-I {"message": "Oops! yolo did something. There goes a rainbow..."} ``` -/// note | "Technische Details" +/// note | Technische Details Sie können auch `from starlette.requests import Request` und `from starlette.responses import JSONResponse` verwenden. @@ -166,7 +166,7 @@ path -> item_id #### `RequestValidationError` vs. `ValidationError` -/// warning | "Achtung" +/// warning | Achtung Das folgende sind technische Details, die Sie überspringen können, wenn sie für Sie nicht wichtig sind. @@ -192,7 +192,7 @@ Zum Beispiel könnten Sie eine Klartext-Response statt JSON für diese Fehler zu {!../../docs_src/handling_errors/tutorial004.py!} ``` -/// note | "Technische Details" +/// note | Technische Details Sie können auch `from starlette.responses import PlainTextResponse` verwenden. diff --git a/docs/de/docs/tutorial/header-params.md b/docs/de/docs/tutorial/header-params.md index c4901c2ee..40a773f50 100644 --- a/docs/de/docs/tutorial/header-params.md +++ b/docs/de/docs/tutorial/header-params.md @@ -32,7 +32,7 @@ Importieren Sie zuerst `Header`: //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -46,7 +46,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -90,7 +90,7 @@ Der erste Wert ist der Typ. Sie können `Header` die gehabten Extra Validierungs //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -104,7 +104,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -116,7 +116,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// -/// note | "Technische Details" +/// note | Technische Details `Header` ist eine Schwesterklasse von `Path`, `Query` und `Cookie`. Sie erbt von derselben gemeinsamen `Param`-Elternklasse. @@ -172,7 +172,7 @@ Wenn Sie aus irgendeinem Grund das automatische Konvertieren von Unterstrichen z //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -186,7 +186,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -198,7 +198,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// -/// warning | "Achtung" +/// warning | Achtung Bevor Sie `convert_underscores` auf `False` setzen, bedenken Sie, dass manche HTTP-Proxys und Server die Verwendung von Headern mit Unterstrichen nicht erlauben. @@ -240,7 +240,7 @@ Um zum Beispiel einen Header `X-Token` zu deklarieren, der mehrmals vorkommen ka //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -254,7 +254,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.9+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -268,7 +268,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. diff --git a/docs/de/docs/tutorial/index.md b/docs/de/docs/tutorial/index.md index c15d0b0bd..3cbfe37f4 100644 --- a/docs/de/docs/tutorial/index.md +++ b/docs/de/docs/tutorial/index.md @@ -52,7 +52,7 @@ $ pip install "fastapi[all]" ... das beinhaltet auch `uvicorn`, welchen Sie als Server verwenden können, der ihren Code ausführt. -/// note | "Hinweis" +/// note | Hinweis Sie können die einzelnen Teile auch separat installieren. diff --git a/docs/de/docs/tutorial/metadata.md b/docs/de/docs/tutorial/metadata.md index 98724e1e8..5a0b723c5 100644 --- a/docs/de/docs/tutorial/metadata.md +++ b/docs/de/docs/tutorial/metadata.md @@ -22,7 +22,7 @@ Sie können diese wie folgt setzen: {!../../docs_src/metadata/tutorial001.py!} ``` -/// tip | "Tipp" +/// tip | Tipp Sie können Markdown in das Feld `description` schreiben und es wird in der Ausgabe gerendert. @@ -68,7 +68,7 @@ Erstellen Sie Metadaten für Ihre Tags und übergeben Sie sie an den Parameter ` Beachten Sie, dass Sie Markdown in den Beschreibungen verwenden können. Beispielsweise wird „login“ in Fettschrift (**login**) und „fancy“ in Kursivschrift (_fancy_) angezeigt. -/// tip | "Tipp" +/// tip | Tipp Sie müssen nicht für alle von Ihnen verwendeten Tags Metadaten hinzufügen. diff --git a/docs/de/docs/tutorial/middleware.md b/docs/de/docs/tutorial/middleware.md index 410dc0247..d3699be1b 100644 --- a/docs/de/docs/tutorial/middleware.md +++ b/docs/de/docs/tutorial/middleware.md @@ -11,7 +11,7 @@ Eine „Middleware“ ist eine Funktion, die mit jedem **Request** arbeitet, bev * Sie kann etwas mit dieser **Response** tun oder beliebigen Code ausführen. * Dann gibt sie die **Response** zurück. -/// note | "Technische Details" +/// note | Technische Details Wenn Sie Abhängigkeiten mit `yield` haben, wird der Exit-Code *nach* der Middleware ausgeführt. @@ -31,11 +31,9 @@ Die Middleware-Funktion erhält: * 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. -```Python hl_lines="8-9 11 14" -{!../../docs_src/middleware/tutorial001.py!} -``` +{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *} -/// tip | "Tipp" +/// tip | Tipp Beachten Sie, dass benutzerdefinierte proprietäre Header hinzugefügt werden können. Verwenden Sie dafür das Präfix 'X-'. @@ -43,7 +41,7 @@ Wenn Sie jedoch benutzerdefinierte Header haben, die ein Client in einem Browser /// -/// note | "Technische Details" +/// note | Technische Details Sie könnten auch `from starlette.requests import Request` verwenden. @@ -59,9 +57,7 @@ Und auch nachdem die `response` generiert wurde, bevor sie zurückgegeben wird. Sie könnten beispielsweise einen benutzerdefinierten Header `X-Process-Time` hinzufügen, der die Zeit in Sekunden enthält, die benötigt wurde, um den Request zu verarbeiten und eine Response zu generieren: -```Python hl_lines="10 12-13" -{!../../docs_src/middleware/tutorial001.py!} -``` +{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *} ## Andere Middlewares diff --git a/docs/de/docs/tutorial/path-operation-configuration.md b/docs/de/docs/tutorial/path-operation-configuration.md index 411916e9c..55d0f2a91 100644 --- a/docs/de/docs/tutorial/path-operation-configuration.md +++ b/docs/de/docs/tutorial/path-operation-configuration.md @@ -2,7 +2,7 @@ Es gibt mehrere Konfigurations-Parameter, die Sie Ihrem *Pfadoperation-Dekorator* übergeben können. -/// warning | "Achtung" +/// warning | Achtung Beachten Sie, dass diese Parameter direkt dem *Pfadoperation-Dekorator* übergeben werden, nicht der *Pfadoperation-Funktion*. @@ -42,7 +42,7 @@ Aber falls Sie sich nicht mehr erinnern, wofür jede Nummer steht, können Sie d Dieser Statuscode wird in der Response verwendet und zum OpenAPI-Schema hinzugefügt. -/// note | "Technische Details" +/// note | Technische Details Sie können auch `from starlette import status` verwenden. diff --git a/docs/de/docs/tutorial/path-params-numeric-validations.md b/docs/de/docs/tutorial/path-params-numeric-validations.md index fc2d5dff1..b74fc8a04 100644 --- a/docs/de/docs/tutorial/path-params-numeric-validations.md +++ b/docs/de/docs/tutorial/path-params-numeric-validations.md @@ -32,7 +32,7 @@ Importieren Sie zuerst `Path` von `fastapi`, und importieren Sie `Annotated`. //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -46,7 +46,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -100,7 +100,7 @@ Um zum Beispiel einen `title`-Metadaten-Wert für den Pfad-Parameter `item_id` z //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -114,7 +114,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -126,7 +126,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// -/// note | "Hinweis" +/// note | Hinweis Ein Pfad-Parameter ist immer erforderlich, weil er Teil des Pfads sein muss. @@ -138,7 +138,7 @@ Doch selbst wenn Sie ihn mit `None` deklarieren, oder einen Defaultwert setzen, ## Sortieren Sie die Parameter, wie Sie möchten -/// tip | "Tipp" +/// tip | Tipp Wenn Sie `Annotated` verwenden, ist das folgende nicht so wichtig / nicht notwendig. @@ -160,7 +160,7 @@ Sie können Ihre Funktion also so deklarieren: //// tab | Python 3.8 nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -192,7 +192,7 @@ Aber bedenken Sie, dass Sie dieses Problem nicht haben, wenn Sie `Annotated` ver ## Sortieren Sie die Parameter wie Sie möchten: Tricks -/// tip | "Tipp" +/// tip | Tipp Wenn Sie `Annotated` verwenden, ist das folgende nicht so wichtig / nicht notwendig. @@ -260,7 +260,7 @@ Hier, mit `ge=1`, wird festgelegt, dass `item_id` eine Ganzzahl benötigt, die g //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -297,7 +297,7 @@ Das Gleiche trifft zu auf: //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -337,7 +337,7 @@ Das gleiche gilt für ltModellen für maschinelles Lernen. @@ -199,7 +199,7 @@ Den tatsächlichen Wert (in diesem Fall ein `str`) erhalten Sie via `model_name. {!../../docs_src/path_params/tutorial005.py!} ``` -/// tip | "Tipp" +/// tip | Tipp Sie können den Wert `"lenet"` außerdem mittels `ModelName.lenet.value` abrufen. @@ -256,7 +256,7 @@ Sie verwenden das also wie folgt: {!../../docs_src/path_params/tutorial004.py!} ``` -/// tip | "Tipp" +/// tip | Tipp Der Parameter könnte einen führenden Schrägstrich (`/`) haben, wie etwa in `/home/johndoe/myfile.txt`. diff --git a/docs/de/docs/tutorial/query-params-str-validations.md b/docs/de/docs/tutorial/query-params-str-validations.md index a9f1e0f39..d71a23dc2 100644 --- a/docs/de/docs/tutorial/query-params-str-validations.md +++ b/docs/de/docs/tutorial/query-params-str-validations.md @@ -22,7 +22,7 @@ Nehmen wir als Beispiel die folgende Anwendung: Der Query-Parameter `q` hat den Typ `Union[str, None]` (oder `str | None` in Python 3.10), was bedeutet, er ist entweder ein `str` oder `None`. Der Defaultwert ist `None`, also weiß FastAPI, der Parameter ist nicht erforderlich. -/// note | "Hinweis" +/// note | Hinweis FastAPI weiß nur dank des definierten Defaultwertes `=None`, dass der Wert von `q` nicht erforderlich ist @@ -153,7 +153,7 @@ FastAPI wird nun: Frühere Versionen von FastAPI (vor 0.95.0) benötigten `Query` als Defaultwert des Parameters, statt es innerhalb von `Annotated` unterzubringen. Die Chance ist groß, dass Sie Quellcode sehen, der das immer noch so macht, darum erkläre ich es Ihnen. -/// tip | "Tipp" +/// tip | Tipp Verwenden Sie für neuen Code, und wann immer möglich, `Annotated`, wie oben erklärt. Es gibt mehrere Vorteile (unten erläutert) und keine Nachteile. 🍰 @@ -301,7 +301,7 @@ Sie können auch einen Parameter `min_length` hinzufügen: //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -315,7 +315,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -357,7 +357,7 @@ Sie können einen ../../docs_src/query_params_str_validations/tutorial006.py!} ``` -/// tip | "Tipp" +/// tip | Tipp Beachten Sie, dass, obwohl in diesem Fall `Query()` der Funktionsparameter-Defaultwert ist, wir nicht `default=None` zu `Query()` hinzufügen. @@ -545,7 +545,7 @@ Es gibt eine Alternative, die explizit deklariert, dass ein Wert erforderlich is //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -599,7 +599,7 @@ Um das zu machen, deklarieren Sie, dass `None` ein gültiger Typ ist, aber verwe //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -613,7 +613,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -625,13 +625,13 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// -/// tip | "Tipp" +/// tip | Tipp Pydantic, welches die gesamte Datenvalidierung und Serialisierung in FastAPI antreibt, hat ein spezielles Verhalten, wenn Sie `Optional` oder `Union[Something, None]` ohne Defaultwert verwenden, Sie können mehr darüber in der Pydantic-Dokumentation unter Required fields erfahren. /// -/// tip | "Tipp" +/// tip | Tipp Denken Sie daran, dass Sie in den meisten Fällen, wenn etwas erforderlich ist, einfach den Defaultwert weglassen können. Sie müssen also normalerweise `...` nicht verwenden. @@ -669,7 +669,7 @@ Um zum Beispiel einen Query-Parameter `q` zu deklarieren, der mehrere Male in de //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -683,7 +683,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.9+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -697,7 +697,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -728,7 +728,7 @@ Die Response für diese URL wäre also: } ``` -/// tip | "Tipp" +/// tip | Tipp Um einen Query-Parameter vom Typ `list` zu deklarieren, wie im Beispiel oben, müssen Sie explizit `Query` verwenden, sonst würde der Parameter als Requestbody interpretiert werden. @@ -760,7 +760,7 @@ Und Sie können auch eine Default-`list`e von Werten definieren, wenn keine übe //// tab | Python 3.9+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -774,7 +774,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -825,7 +825,7 @@ Sie können auch `list` direkt verwenden, anstelle von `List[str]` (oder `list[s //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -837,7 +837,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// -/// note | "Hinweis" +/// note | Hinweis Beachten Sie, dass FastAPI in diesem Fall den Inhalt der Liste nicht überprüft. @@ -851,7 +851,7 @@ Sie können mehr Informationen zum Parameter hinzufügen. Diese Informationen werden zur generierten OpenAPI hinzugefügt, und von den Dokumentations-Oberflächen und von externen Tools verwendet. -/// note | "Hinweis" +/// note | Hinweis Beachten Sie, dass verschiedene Tools OpenAPI möglicherweise unterschiedlich gut unterstützen. @@ -887,7 +887,7 @@ Sie können einen Titel hinzufügen – `title`: //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -901,7 +901,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -941,7 +941,7 @@ Und eine Beschreibung – `description`: //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -955,7 +955,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -1011,7 +1011,7 @@ Dann können Sie einen `alias` deklarieren, und dieser Alias wird verwendet, um //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -1025,7 +1025,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -1071,7 +1071,7 @@ In diesem Fall fügen Sie den Parameter `deprecated=True` zu `Query` hinzu. //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -1085,7 +1085,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -1131,7 +1131,7 @@ Um einen Query-Parameter vom generierten OpenAPI-Schema auszuschließen (und dah //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -1145,7 +1145,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. diff --git a/docs/de/docs/tutorial/query-params.md b/docs/de/docs/tutorial/query-params.md index bb1dbdf9c..e67fef79d 100644 --- a/docs/de/docs/tutorial/query-params.md +++ b/docs/de/docs/tutorial/query-params.md @@ -241,7 +241,7 @@ In diesem Fall gibt es drei Query-Parameter: * `skip`, ein `int` mit einem Defaultwert `0`. * `limit`, ein optionales `int`. -/// tip | "Tipp" +/// tip | Tipp Sie können auch `Enum`s verwenden, auf die gleiche Weise wie mit [Pfad-Parametern](path-params.md#vordefinierte-parameterwerte){.internal-link target=_blank}. diff --git a/docs/de/docs/tutorial/request-files.md b/docs/de/docs/tutorial/request-files.md index c0d0ef3f2..cbfb4271f 100644 --- a/docs/de/docs/tutorial/request-files.md +++ b/docs/de/docs/tutorial/request-files.md @@ -34,7 +34,7 @@ Importieren Sie `File` und `UploadFile` von `fastapi`: //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -68,7 +68,7 @@ Erstellen Sie Datei-Parameter, so wie Sie es auch mit `Body` und `Form` machen w //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -88,7 +88,7 @@ Aber erinnern Sie sich, dass, wenn Sie `Query`, `Path`, `File` und andere von ` /// -/// tip | "Tipp" +/// tip | Tipp Um Dateibodys zu deklarieren, müssen Sie `File` verwenden, da diese Parameter sonst als Query-Parameter oder Body(-JSON)-Parameter interpretiert werden würden. @@ -124,7 +124,7 @@ Definieren Sie einen Datei-Parameter mit dem Typ `UploadFile`: //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -177,13 +177,13 @@ Wenn Sie sich innerhalb einer normalen `def`-*Pfadoperation-Funktion* befinden, contents = myfile.file.read() ``` -/// note | "Technische Details zu `async`" +/// note | Technische Details zu `async` Wenn Sie die `async`-Methoden verwenden, führt **FastAPI** die Datei-Methoden in einem Threadpool aus und erwartet sie. /// -/// note | "Technische Details zu Starlette" +/// note | Technische Details zu Starlette **FastAPI**s `UploadFile` erbt direkt von **Starlette**s `UploadFile`, fügt aber ein paar notwendige Teile hinzu, um es kompatibel mit **Pydantic** und anderen Teilen von FastAPI zu machen. @@ -195,7 +195,7 @@ HTML-Formulare (`
`) senden die Daten in einer „speziellen“ Kodi **FastAPI** stellt sicher, dass diese Daten korrekt ausgelesen werden, statt JSON zu erwarten. -/// note | "Technische Details" +/// note | Technische Details Daten aus Formularen werden, wenn es keine Dateien sind, normalerweise mit dem „media type“ `application/x-www-form-urlencoded` kodiert. @@ -205,7 +205,7 @@ Wenn Sie mehr über Formularfelder und ihre Kodierungen lesen möchten, besuchen /// -/// warning | "Achtung" +/// warning | Achtung Sie können mehrere `File`- und `Form`-Parameter in einer *Pfadoperation* deklarieren, aber Sie können nicht gleichzeitig auch `Body`-Felder deklarieren, welche Sie als JSON erwarten, da der Request den Body mittels `multipart/form-data` statt `application/json` kodiert. @@ -243,7 +243,7 @@ Sie können eine Datei optional machen, indem Sie Standard-Typannotationen verwe //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -257,7 +257,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -291,7 +291,7 @@ Sie können auch `File()` zusammen mit `UploadFile` verwenden, um zum Beispiel z //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -329,7 +329,7 @@ Um das zu machen, deklarieren Sie eine Liste von `bytes` oder `UploadFile`s: //// tab | Python 3.9+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -343,7 +343,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -357,7 +357,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. Sie erhalten, wie deklariert, eine `list`e von `bytes` oder `UploadFile`s. -/// note | "Technische Details" +/// note | Technische Details Sie können auch `from starlette.responses import HTMLResponse` verwenden. @@ -387,7 +387,7 @@ Und so wie zuvor können Sie `File()` verwenden, um zusätzliche Parameter zu se //// tab | Python 3.9+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -401,7 +401,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. diff --git a/docs/de/docs/tutorial/request-forms-and-files.md b/docs/de/docs/tutorial/request-forms-and-files.md index 2b89edbb4..bdd1e0fac 100644 --- a/docs/de/docs/tutorial/request-forms-and-files.md +++ b/docs/de/docs/tutorial/request-forms-and-files.md @@ -30,7 +30,7 @@ Z. B. `pip install python-multipart`. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -64,7 +64,7 @@ Erstellen Sie Datei- und Formularparameter, so wie Sie es auch mit `Body` und `Q //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -80,7 +80,7 @@ Die Datei- und Formularfelder werden als Formulardaten hochgeladen, und Sie erha Und Sie können einige der Dateien als `bytes` und einige als `UploadFile` deklarieren. -/// warning | "Achtung" +/// warning | Achtung Sie können mehrere `File`- und `Form`-Parameter in einer *Pfadoperation* deklarieren, aber Sie können nicht gleichzeitig auch `Body`-Felder deklarieren, welche Sie als JSON erwarten, da der Request den Body mittels `multipart/form-data` statt `application/json` kodiert. diff --git a/docs/de/docs/tutorial/request-forms.md b/docs/de/docs/tutorial/request-forms.md index 0784aa8c0..2b6aeb41c 100644 --- a/docs/de/docs/tutorial/request-forms.md +++ b/docs/de/docs/tutorial/request-forms.md @@ -32,7 +32,7 @@ Importieren Sie `Form` von `fastapi`: //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -66,7 +66,7 @@ Erstellen Sie Formular-Parameter, so wie Sie es auch mit `Body` und `Query` mach //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -90,7 +90,7 @@ Mit `Form` haben Sie die gleichen Konfigurationsmöglichkeiten wie mit `Body` (u /// -/// tip | "Tipp" +/// tip | Tipp Um Formularbodys zu deklarieren, verwenden Sie explizit `Form`, da diese Parameter sonst als Query-Parameter oder Body(-JSON)-Parameter interpretiert werden würden. @@ -102,7 +102,7 @@ HTML-Formulare (`
`) senden die Daten in einer „speziellen“ Kodi **FastAPI** stellt sicher, dass diese Daten korrekt ausgelesen werden, statt JSON zu erwarten. -/// note | "Technische Details" +/// note | Technische Details Daten aus Formularen werden normalerweise mit dem „media type“ `application/x-www-form-urlencoded` kodiert. @@ -112,7 +112,7 @@ Wenn Sie mehr über Formularfelder und ihre Kodierungen lesen möchten, besuchen /// -/// warning | "Achtung" +/// warning | Achtung Sie können mehrere `Form`-Parameter in einer *Pfadoperation* deklarieren, aber Sie können nicht gleichzeitig auch `Body`-Felder deklarieren, welche Sie als JSON erwarten, da der Request den Body mittels `application/x-www-form-urlencoded` statt `application/json` kodiert. diff --git a/docs/de/docs/tutorial/response-model.md b/docs/de/docs/tutorial/response-model.md index 31ad73c77..aa27e0726 100644 --- a/docs/de/docs/tutorial/response-model.md +++ b/docs/de/docs/tutorial/response-model.md @@ -83,7 +83,7 @@ Sie können `response_model` in jeder möglichen *Pfadoperation* verwenden: //// -/// note | "Hinweis" +/// 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. @@ -93,7 +93,7 @@ Beachten Sie, dass `response_model` ein Parameter der „Dekorator“-Methode is 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" +/// tip | Tipp Wenn Sie in Ihrem Editor strikte Typchecks haben, mypy, usw., können Sie den Funktions-Rückgabetyp als `Any` deklarieren. @@ -162,7 +162,7 @@ Hier ist das möglicherweise kein Problem, da es derselbe Benutzer ist, der das Aber wenn wir dasselbe Modell für eine andere *Pfadoperation* verwenden, könnten wir das Passwort dieses Benutzers zu jedem Client schicken. -/// danger | "Gefahr" +/// 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. @@ -503,7 +503,7 @@ dann ist FastAPI klug genug (tatsächlich ist Pydantic klug genug) zu erkennen, Diese Felder werden also in der JSON-Response enthalten sein. -/// tip | "Tipp" +/// tip | Tipp Beachten Sie, dass Defaultwerte alles Mögliche sein können, nicht nur `None`. @@ -519,7 +519,7 @@ Diese nehmen ein `set` von `str`s entgegen, welches Namen von Attributen sind, d Das kann als schnelle Abkürzung verwendet werden, wenn Sie nur ein Pydantic-Modell haben und ein paar Daten von der Ausgabe ausschließen wollen. -/// tip | "Tipp" +/// tip | Tipp Es wird dennoch empfohlen, dass Sie die Ideen von oben verwenden, also mehrere Klassen statt dieser Parameter. @@ -545,7 +545,7 @@ Das trifft auch auf `response_model_by_alias` zu, welches ähnlich funktioniert. //// -/// tip | "Tipp" +/// tip | Tipp Die Syntax `{"name", "description"}` erzeugt ein `set` mit diesen zwei Werten. diff --git a/docs/de/docs/tutorial/response-status-code.md b/docs/de/docs/tutorial/response-status-code.md index 5f017355b..a1b388a0a 100644 --- a/docs/de/docs/tutorial/response-status-code.md +++ b/docs/de/docs/tutorial/response-status-code.md @@ -10,7 +10,7 @@ So wie ein Responsemodell, können Sie auch einen HTTP-Statuscode für die Respo {* ../../docs_src/response_status_code/tutorial001.py hl[6] *} -/// note | "Hinweis" +/// note | Hinweis Beachten Sie, dass `status_code` ein Parameter der „Dekorator“-Methode ist (`get`, `post`, usw.). Nicht der *Pfadoperation-Funktion*, so wie die anderen Parameter und der Body. @@ -31,7 +31,7 @@ Das wird: -/// note | "Hinweis" +/// note | Hinweis Einige Responsecodes (siehe nächster Abschnitt) kennzeichnen, dass die Response keinen Body hat. @@ -41,7 +41,7 @@ FastAPI versteht das und wird in der OpenAPI-Dokumentation anzeigen, dass es kei ## Über HTTP-Statuscodes -/// note | "Hinweis" +/// note | Hinweis Wenn Sie bereits wissen, was HTTP-Statuscodes sind, überspringen Sie dieses Kapitel und fahren Sie mit dem nächsten fort. @@ -64,7 +64,7 @@ Kurz: * Für allgemeine Fehler beim Client können Sie einfach `400` verwenden. * `500` und darüber stehen für Server-Fehler. Diese verwenden Sie fast nie direkt. Wenn etwas an irgendeiner Stelle in Ihrem Anwendungscode oder im Server schiefläuft, wird automatisch einer dieser Fehler-Statuscodes zurückgegeben. -/// tip | "Tipp" +/// tip | Tipp Um mehr über Statuscodes zu lernen, und welcher wofür verwendet wird, lesen Sie die MDN Dokumentation über HTTP-Statuscodes. @@ -88,7 +88,7 @@ Diese sind nur eine Annehmlichkeit und enthalten dieselbe Nummer, aber auf diese -/// note | "Technische Details" +/// note | Technische Details Sie können auch `from starlette import status` verwenden. diff --git a/docs/de/docs/tutorial/schema-extra-example.md b/docs/de/docs/tutorial/schema-extra-example.md index 0da1a4ea4..f065ad4ca 100644 --- a/docs/de/docs/tutorial/schema-extra-example.md +++ b/docs/de/docs/tutorial/schema-extra-example.md @@ -8,35 +8,15 @@ Hier sind mehrere Möglichkeiten, das zu tun. Sie können `examples` („Beispiele“) für ein Pydantic-Modell deklarieren, welche dem generierten JSON-Schema hinzugefügt werden. -//// tab | Python 3.10+ Pydantic v2 +//// tab | Pydantic v2 -```Python hl_lines="13-24" -{!> ../../docs_src/schema_extra_example/tutorial001_py310.py!} -``` +{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *} //// -//// tab | Python 3.10+ Pydantic v1 +//// tab | Pydantic v1 -```Python hl_lines="13-23" -{!> ../../docs_src/schema_extra_example/tutorial001_py310_pv1.py!} -``` - -//// - -//// tab | Python 3.8+ Pydantic v2 - -```Python hl_lines="15-26" -{!> ../../docs_src/schema_extra_example/tutorial001.py!} -``` - -//// - -//// tab | Python 3.8+ Pydantic v1 - -```Python hl_lines="15-25" -{!> ../../docs_src/schema_extra_example/tutorial001_pv1.py!} -``` +{* ../../docs_src/schema_extra_example/tutorial001_pv1_py310.py hl[13:23] *} //// @@ -58,7 +38,7 @@ Sie können `schema_extra` setzen, mit einem `dict`, das alle zusätzlichen Date //// -/// tip | "Tipp" +/// tip | Tipp Mit derselben Technik können Sie das JSON-Schema erweitern und Ihre eigenen benutzerdefinierten Zusatzinformationen hinzufügen. @@ -80,21 +60,7 @@ Mehr erfahren Sie am Ende dieser Seite. Wenn Sie `Field()` mit Pydantic-Modellen verwenden, können Sie ebenfalls zusätzliche `examples` deklarieren: -//// tab | Python 3.10+ - -```Python hl_lines="2 8-11" -{!> ../../docs_src/schema_extra_example/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="4 10-13" -{!> ../../docs_src/schema_extra_example/tutorial002.py!} -``` - -//// +{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *} ## `examples` im JSON-Schema – OpenAPI @@ -114,57 +80,7 @@ können Sie auch eine Gruppe von `examples` mit zusätzlichen Informationen dekl Hier übergeben wir `examples`, welches ein einzelnes Beispiel für die in `Body()` erwarteten Daten enthält: -//// tab | Python 3.10+ - -```Python hl_lines="22-29" -{!> ../../docs_src/schema_extra_example/tutorial003_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="22-29" -{!> ../../docs_src/schema_extra_example/tutorial003_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="23-30" -{!> ../../docs_src/schema_extra_example/tutorial003_an.py!} -``` - -//// - -//// tab | Python 3.10+ nicht annotiert - -/// tip | "Tipp" - -Bevorzugen Sie die `Annotated`-Version, falls möglich. - -/// - -```Python hl_lines="18-25" -{!> ../../docs_src/schema_extra_example/tutorial003_py310.py!} -``` - -//// - -//// tab | Python 3.8+ nicht annotiert - -/// tip | "Tipp" - -Bevorzugen Sie die `Annotated`-Version, falls möglich. - -/// - -```Python hl_lines="20-27" -{!> ../../docs_src/schema_extra_example/tutorial003.py!} -``` - -//// +{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *} ### Beispiel in der Dokumentations-Benutzeroberfläche @@ -176,57 +92,7 @@ Mit jeder der oben genannten Methoden würde es in `/docs` so aussehen: Sie können natürlich auch mehrere `examples` übergeben: -//// tab | Python 3.10+ - -```Python hl_lines="23-38" -{!> ../../docs_src/schema_extra_example/tutorial004_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="23-38" -{!> ../../docs_src/schema_extra_example/tutorial004_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="24-39" -{!> ../../docs_src/schema_extra_example/tutorial004_an.py!} -``` - -//// - -//// tab | Python 3.10+ nicht annotiert - -/// tip | "Tipp" - -Bevorzugen Sie die `Annotated`-Version, falls möglich. - -/// - -```Python hl_lines="19-34" -{!> ../../docs_src/schema_extra_example/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.8+ nicht annotiert - -/// tip | "Tipp" - -Bevorzugen Sie die `Annotated`-Version, falls möglich. - -/// - -```Python hl_lines="21-36" -{!> ../../docs_src/schema_extra_example/tutorial004.py!} -``` - -//// +{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *} Wenn Sie das tun, werden die Beispiele Teil des internen **JSON-Schemas** für diese Body-Daten. @@ -267,57 +133,7 @@ Jedes spezifische Beispiel-`dict` in den `examples` kann Folgendes enthalten: Sie können es so verwenden: -//// tab | Python 3.10+ - -```Python hl_lines="23-49" -{!> ../../docs_src/schema_extra_example/tutorial005_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="23-49" -{!> ../../docs_src/schema_extra_example/tutorial005_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="24-50" -{!> ../../docs_src/schema_extra_example/tutorial005_an.py!} -``` - -//// - -//// tab | Python 3.10+ nicht annotiert - -/// tip | "Tipp" - -Bevorzugen Sie die `Annotated`-Version, falls möglich. - -/// - -```Python hl_lines="19-45" -{!> ../../docs_src/schema_extra_example/tutorial005_py310.py!} -``` - -//// - -//// tab | Python 3.8+ nicht annotiert - -/// tip | "Tipp" - -Bevorzugen Sie die `Annotated`-Version, falls möglich. - -/// - -```Python hl_lines="21-47" -{!> ../../docs_src/schema_extra_example/tutorial005.py!} -``` - -//// +{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *} ### OpenAPI-Beispiele in der Dokumentations-Benutzeroberfläche @@ -327,7 +143,7 @@ Wenn `openapi_examples` zu `Body()` hinzugefügt wird, würde `/docs` so aussehe ## Technische Details -/// tip | "Tipp" +/// tip | Tipp Wenn Sie bereits **FastAPI** Version **0.99.0 oder höher** verwenden, können Sie diese Details wahrscheinlich **überspringen**. @@ -337,7 +153,7 @@ Sie können dies als eine kurze **Geschichtsstunde** zu OpenAPI und JSON Schema /// -/// warning | "Achtung" +/// warning | Achtung Dies sind sehr technische Details zu den Standards **JSON Schema** und **OpenAPI**. diff --git a/docs/de/docs/tutorial/security/first-steps.md b/docs/de/docs/tutorial/security/first-steps.md index c552a681b..935b8ecca 100644 --- a/docs/de/docs/tutorial/security/first-steps.md +++ b/docs/de/docs/tutorial/security/first-steps.md @@ -38,7 +38,7 @@ Kopieren Sie das Beispiel in eine Datei `main.py`: //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -82,7 +82,7 @@ Sie werden etwa Folgendes sehen: -/// check | "Authorize-Button!" +/// check | Authorize-Button! Sie haben bereits einen glänzenden, neuen „Authorize“-Button. @@ -94,7 +94,7 @@ Und wenn Sie darauf klicken, erhalten Sie ein kleines Anmeldeformular zur Eingab -/// note | "Hinweis" +/// note | Hinweis Es spielt keine Rolle, was Sie in das Formular eingeben, es wird noch nicht funktionieren. Wir kommen dahin. @@ -172,7 +172,7 @@ Wenn wir eine Instanz der Klasse `OAuth2PasswordBearer` erstellen, übergeben wi //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -184,7 +184,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// -/// tip | "Tipp" +/// tip | Tipp Hier bezieht sich `tokenUrl="token"` auf eine relative URL `token`, die wir noch nicht erstellt haben. Da es sich um eine relative URL handelt, entspricht sie `./token`. @@ -238,7 +238,7 @@ Jetzt können Sie dieses `oauth2_scheme` als Abhängigkeit `Depends` übergeben. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -254,7 +254,7 @@ Diese Abhängigkeit stellt einen `str` bereit, der dem Parameter `token` der *Pf **FastAPI** weiß, dass es diese Abhängigkeit verwenden kann, um ein „Sicherheitsschema“ im OpenAPI-Schema (und der automatischen API-Dokumentation) zu definieren. -/// info | "Technische Details" +/// info | Technische Details **FastAPI** weiß, dass es die Klasse `OAuth2PasswordBearer` (deklariert in einer Abhängigkeit) verwenden kann, um das Sicherheitsschema in OpenAPI zu definieren, da es von `fastapi.security.oauth2.OAuth2` erbt, das wiederum von `fastapi.security.base.SecurityBase` erbt. diff --git a/docs/de/docs/tutorial/security/get-current-user.md b/docs/de/docs/tutorial/security/get-current-user.md index a9478a36e..5f28f231f 100644 --- a/docs/de/docs/tutorial/security/get-current-user.md +++ b/docs/de/docs/tutorial/security/get-current-user.md @@ -20,7 +20,7 @@ Im vorherigen Kapitel hat das Sicherheitssystem (das auf dem Dependency Injectio //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -68,7 +68,7 @@ So wie wir Pydantic zum Deklarieren von Bodys verwenden, können wir es auch üb //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -82,7 +82,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -130,7 +130,7 @@ So wie wir es zuvor in der *Pfadoperation* direkt gemacht haben, erhält unsere //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -144,7 +144,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -186,7 +186,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -200,7 +200,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -242,7 +242,7 @@ Und jetzt können wir wiederum `Depends` mit unserem `get_current_user` in der * //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -256,7 +256,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -272,7 +272,7 @@ Beachten Sie, dass wir als Typ von `current_user` das Pydantic-Modell `User` dek Das wird uns innerhalb der Funktion bei Codevervollständigung und Typprüfungen helfen. -/// tip | "Tipp" +/// tip | Tipp Sie erinnern sich vielleicht, dass Requestbodys ebenfalls mit Pydantic-Modellen deklariert werden. @@ -346,7 +346,7 @@ Und alle diese Tausenden von *Pfadoperationen* können nur drei Zeilen lang sein //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -360,7 +360,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. diff --git a/docs/de/docs/tutorial/security/index.md b/docs/de/docs/tutorial/security/index.md index ad0927361..b01243901 100644 --- a/docs/de/docs/tutorial/security/index.md +++ b/docs/de/docs/tutorial/security/index.md @@ -32,7 +32,7 @@ Heutzutage ist es nicht sehr populär und wird kaum verwendet. OAuth2 spezifiziert nicht, wie die Kommunikation verschlüsselt werden soll, sondern erwartet, dass Ihre Anwendung mit HTTPS bereitgestellt wird. -/// tip | "Tipp" +/// tip | Tipp Im Abschnitt über **Deployment** erfahren Sie, wie Sie HTTPS mithilfe von Traefik und Let's Encrypt kostenlos einrichten. @@ -89,7 +89,7 @@ OpenAPI definiert die folgenden Sicherheitsschemas: * Diese automatische Erkennung ist es, die in der OpenID Connect Spezifikation definiert ist. -/// tip | "Tipp" +/// tip | Tipp Auch die Integration anderer Authentifizierungs-/Autorisierungsanbieter wie Google, Facebook, Twitter, GitHub, usw. ist möglich und relativ einfach. diff --git a/docs/de/docs/tutorial/security/oauth2-jwt.md b/docs/de/docs/tutorial/security/oauth2-jwt.md index 79e817840..25c1e1c97 100644 --- a/docs/de/docs/tutorial/security/oauth2-jwt.md +++ b/docs/de/docs/tutorial/security/oauth2-jwt.md @@ -44,7 +44,7 @@ $ pip install "python-jose[cryptography]" Hier verwenden wir das empfohlene: pyca/cryptography. -/// tip | "Tipp" +/// tip | Tipp Dieses Tutorial verwendete zuvor PyJWT. @@ -86,7 +86,7 @@ $ pip install "passlib[bcrypt]" -/// tip | "Tipp" +/// tip | Tipp Mit `passlib` können Sie sogar konfigurieren, Passwörter zu lesen, die von **Django**, einem **Flask**-Sicherheit-Plugin, oder vielen anderen erstellt wurden. @@ -102,7 +102,7 @@ Importieren Sie die benötigten Tools aus `passlib`. Erstellen Sie einen PassLib-„Kontext“. Der wird für das Hashen und Verifizieren von Passwörtern verwendet. -/// tip | "Tipp" +/// tip | Tipp Der PassLib-Kontext kann auch andere Hashing-Algorithmen verwenden, einschließlich deprecateter Alter, um etwa nur eine Verifizierung usw. zu ermöglichen. @@ -144,7 +144,7 @@ Und noch eine, um einen Benutzer zu authentifizieren und zurückzugeben. //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -158,7 +158,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -170,7 +170,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// -/// note | "Hinweis" +/// note | Hinweis Wenn Sie sich die neue (gefakte) Datenbank `fake_users_db` anschauen, sehen Sie, wie das gehashte Passwort jetzt aussieht: `"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`. @@ -230,7 +230,7 @@ Erstellen Sie eine Hilfsfunktion, um einen neuen Zugriffstoken zu generieren. //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -244,7 +244,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -290,7 +290,7 @@ Wenn der Token ungültig ist, geben Sie sofort einen HTTP-Fehler zurück. //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -304,7 +304,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -348,7 +348,7 @@ Erstellen Sie einen echten JWT-Zugriffstoken und geben Sie ihn zurück. //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -362,7 +362,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -436,7 +436,7 @@ Wenn Sie die Developer Tools öffnen, können Sie sehen, dass die gesendeten Dat -/// note | "Hinweis" +/// note | Hinweis Beachten Sie den Header `Authorization` mit einem Wert, der mit `Bearer` beginnt. diff --git a/docs/de/docs/tutorial/security/simple-oauth2.md b/docs/de/docs/tutorial/security/simple-oauth2.md index 4c20fae55..2fa1385b0 100644 --- a/docs/de/docs/tutorial/security/simple-oauth2.md +++ b/docs/de/docs/tutorial/security/simple-oauth2.md @@ -78,7 +78,7 @@ Importieren Sie zunächst `OAuth2PasswordRequestForm` und verwenden Sie es als A //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -92,7 +92,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -111,7 +111,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. * Einem optionalen `scope`-Feld als langem String, bestehend aus durch Leerzeichen getrennten Strings. * Einem optionalen `grant_type` („Art der Anmeldung“). -/// tip | "Tipp" +/// tip | Tipp Die OAuth2-Spezifikation *erfordert* tatsächlich ein Feld `grant_type` mit dem festen Wert `password`, aber `OAuth2PasswordRequestForm` erzwingt dies nicht. @@ -136,7 +136,7 @@ Da es sich jedoch um einen häufigen Anwendungsfall handelt, wird er zur Vereinf ### Die Formulardaten verwenden -/// tip | "Tipp" +/// tip | Tipp Die Instanz der Klassenabhängigkeit `OAuth2PasswordRequestForm` verfügt, statt eines Attributs `scope` mit dem durch Leerzeichen getrennten langen String, über das Attribut `scopes` mit einer tatsächlichen Liste von Strings, einem für jeden gesendeten Scope. @@ -176,7 +176,7 @@ Für den Fehler verwenden wir die Exception `HTTPException`: //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -190,7 +190,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -252,7 +252,7 @@ Der Dieb kann also nicht versuchen, die gleichen Passwörter in einem anderen Sy //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -266,7 +266,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -310,7 +310,7 @@ Und es sollte einen `access_token` haben, mit einem String, der unseren Zugriffs In diesem einfachen Beispiel gehen wir einfach völlig unsicher vor und geben denselben `username` wie der Token zurück. -/// tip | "Tipp" +/// tip | Tipp Im nächsten Kapitel sehen Sie eine wirklich sichere Implementierung mit Passwort-Hashing und JWT-Tokens. @@ -344,7 +344,7 @@ Aber konzentrieren wir uns zunächst auf die spezifischen Details, die wir benö //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -358,7 +358,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -370,7 +370,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// -/// tip | "Tipp" +/// tip | Tipp Gemäß der Spezifikation sollten Sie ein JSON mit einem `access_token` und einem `token_type` zurückgeben, genau wie in diesem Beispiel. @@ -420,7 +420,7 @@ In unserem Endpunkt erhalten wir also nur dann einen Benutzer, wenn der Benutzer //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -434,7 +434,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. diff --git a/docs/de/docs/tutorial/static-files.md b/docs/de/docs/tutorial/static-files.md index 4afd251aa..aa44e3f4e 100644 --- a/docs/de/docs/tutorial/static-files.md +++ b/docs/de/docs/tutorial/static-files.md @@ -11,7 +11,7 @@ Mit `StaticFiles` können Sie statische Dateien aus einem Verzeichnis automatisc {!../../docs_src/static_files/tutorial001.py!} ``` -/// note | "Technische Details" +/// note | Technische Details Sie könnten auch `from starlette.staticfiles import StaticFiles` verwenden. diff --git a/docs/de/docs/tutorial/testing.md b/docs/de/docs/tutorial/testing.md index bda6d7d60..53459342b 100644 --- a/docs/de/docs/tutorial/testing.md +++ b/docs/de/docs/tutorial/testing.md @@ -30,7 +30,7 @@ Schreiben Sie einfache `assert`-Anweisungen mit den Standard-Python-Ausdrücken, {!../../docs_src/app_testing/tutorial001.py!} ``` -/// tip | "Tipp" +/// tip | Tipp Beachten Sie, dass die Testfunktionen normal `def` und nicht `async def` sind. @@ -40,7 +40,7 @@ Dadurch können Sie `pytest` ohne Komplikationen direkt nutzen. /// -/// note | "Technische Details" +/// note | Technische Details Sie könnten auch `from starlette.testclient import TestClient` verwenden. @@ -48,7 +48,7 @@ Sie könnten auch `from starlette.testclient import TestClient` verwenden. /// -/// tip | "Tipp" +/// tip | Tipp Wenn Sie in Ihren Tests neben dem Senden von Anfragen 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){.internal-link target=_blank} im Handbuch für fortgeschrittene Benutzer. @@ -148,7 +148,7 @@ Beide *Pfadoperationen* erfordern einen `X-Token`-Header. //// tab | Python 3.10+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. @@ -162,7 +162,7 @@ Bevorzugen Sie die `Annotated`-Version, falls möglich. //// tab | Python 3.8+ nicht annotiert -/// tip | "Tipp" +/// tip | Tipp Bevorzugen Sie die `Annotated`-Version, falls möglich. diff --git a/docs/em/docs/advanced/additional-status-codes.md b/docs/em/docs/advanced/additional-status-codes.md index 7a50e1bca..5eb2ec90e 100644 --- a/docs/em/docs/advanced/additional-status-codes.md +++ b/docs/em/docs/advanced/additional-status-codes.md @@ -28,7 +28,7 @@ /// -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette.responses import JSONResponse`. diff --git a/docs/em/docs/advanced/behind-a-proxy.md b/docs/em/docs/advanced/behind-a-proxy.md index e66ddccf7..36aa2e6b3 100644 --- a/docs/em/docs/advanced/behind-a-proxy.md +++ b/docs/em/docs/advanced/behind-a-proxy.md @@ -80,7 +80,7 @@ $ uvicorn main:app --root-path /api/v1 🚥 👆 ⚙️ Hypercorn, ⚫️ ✔️ 🎛 `--root-path`. -/// note | "📡 ℹ" +/// note | 📡 ℹ 🔫 🔧 🔬 `root_path` 👉 ⚙️ 💼. diff --git a/docs/em/docs/advanced/custom-response.md b/docs/em/docs/advanced/custom-response.md index 7147a4536..301f99957 100644 --- a/docs/em/docs/advanced/custom-response.md +++ b/docs/em/docs/advanced/custom-response.md @@ -121,7 +121,7 @@ ✔️ 🤯 👈 👆 💪 ⚙️ `Response` 📨 🕳 🙆, ⚖️ ✍ 🛃 🎧-🎓. -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette.responses import HTMLResponse`. diff --git a/docs/em/docs/advanced/middleware.md b/docs/em/docs/advanced/middleware.md index 23d2918d7..914ce4a30 100644 --- a/docs/em/docs/advanced/middleware.md +++ b/docs/em/docs/advanced/middleware.md @@ -43,7 +43,7 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") **FastAPI** 🔌 📚 🛠️ ⚠ ⚙️ 💼, 👥 🔜 👀 ⏭ ❔ ⚙️ 👫. -/// note | "📡 ℹ" +/// note | 📡 ℹ ⏭ 🖼, 👆 💪 ⚙️ `from starlette.middleware.something import SomethingMiddleware`. diff --git a/docs/em/docs/advanced/path-operation-advanced-configuration.md b/docs/em/docs/advanced/path-operation-advanced-configuration.md index 805bfdf30..47e89a90f 100644 --- a/docs/em/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/em/docs/advanced/path-operation-advanced-configuration.md @@ -74,7 +74,7 @@ 🕐❔ 👆 📣 *➡ 🛠️* 👆 🈸, **FastAPI** 🔁 🏗 🔗 🗃 🔃 👈 *➡ 🛠️* 🔌 🗄 🔗. -/// note | "📡 ℹ" +/// note | 📡 ℹ 🗄 🔧 ⚫️ 🤙 🛠️ 🎚. diff --git a/docs/em/docs/advanced/response-cookies.md b/docs/em/docs/advanced/response-cookies.md index 6b9e9a4d9..0fe47baec 100644 --- a/docs/em/docs/advanced/response-cookies.md +++ b/docs/em/docs/advanced/response-cookies.md @@ -42,7 +42,7 @@ ### 🌅 ℹ -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette.responses import Response` ⚖️ `from starlette.responses import JSONResponse`. diff --git a/docs/em/docs/advanced/response-directly.md b/docs/em/docs/advanced/response-directly.md index dcffc56c6..335c381c7 100644 --- a/docs/em/docs/advanced/response-directly.md +++ b/docs/em/docs/advanced/response-directly.md @@ -38,7 +38,7 @@ {!../../docs_src/response_directly/tutorial001.py!} ``` -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette.responses import JSONResponse`. diff --git a/docs/em/docs/advanced/response-headers.md b/docs/em/docs/advanced/response-headers.md index cbbbae237..d577347fe 100644 --- a/docs/em/docs/advanced/response-headers.md +++ b/docs/em/docs/advanced/response-headers.md @@ -28,7 +28,7 @@ {!../../docs_src/response_headers/tutorial001.py!} ``` -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette.responses import Response` ⚖️ `from starlette.responses import JSONResponse`. diff --git a/docs/em/docs/advanced/security/oauth2-scopes.md b/docs/em/docs/advanced/security/oauth2-scopes.md index 661be034e..f4d1a3b82 100644 --- a/docs/em/docs/advanced/security/oauth2-scopes.md +++ b/docs/em/docs/advanced/security/oauth2-scopes.md @@ -134,7 +134,7 @@ Oauth2️⃣ 👫 🎻. {!../../docs_src/security/tutorial005.py!} ``` -/// info | "📡 ℹ" +/// info | 📡 ℹ `Security` 🤙 🏿 `Depends`, & ⚫️ ✔️ 1️⃣ ➕ 🔢 👈 👥 🔜 👀 ⏪. diff --git a/docs/em/docs/advanced/templates.md b/docs/em/docs/advanced/templates.md index 66c7484a6..53428151d 100644 --- a/docs/em/docs/advanced/templates.md +++ b/docs/em/docs/advanced/templates.md @@ -43,7 +43,7 @@ $ pip install jinja2 /// -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette.templating import Jinja2Templates`. diff --git a/docs/em/docs/advanced/using-request-directly.md b/docs/em/docs/advanced/using-request-directly.md index ae212364f..3eb0067ad 100644 --- a/docs/em/docs/advanced/using-request-directly.md +++ b/docs/em/docs/advanced/using-request-directly.md @@ -49,7 +49,7 @@ 👆 💪 ✍ 🌅 ℹ 🔃 `Request` 🎚 🛂 💃 🧾 🕸. -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette.requests import Request`. diff --git a/docs/em/docs/advanced/websockets.md b/docs/em/docs/advanced/websockets.md index 7957eba1f..4b260e20a 100644 --- a/docs/em/docs/advanced/websockets.md +++ b/docs/em/docs/advanced/websockets.md @@ -50,7 +50,7 @@ $ pip install websockets {!../../docs_src/websockets/tutorial001.py!} ``` -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette.websockets import WebSocket`. diff --git a/docs/em/docs/alternatives.md b/docs/em/docs/alternatives.md index 5309de51f..59b587285 100644 --- a/docs/em/docs/alternatives.md +++ b/docs/em/docs/alternatives.md @@ -36,7 +36,7 @@ /// -/// check | "😮 **FastAPI** " +/// check | 😮 **FastAPI** ✔️ 🏧 🛠️ 🧾 🕸 👩‍💻 🔢. @@ -56,7 +56,7 @@ 👐 🦁 🏺, ⚫️ 😑 💖 👍 🏏 🏗 🔗. ⏭ 👜 🔎 "✳ 🎂 🛠️" 🏺. -/// check | "😮 **FastAPI** " +/// check | 😮 **FastAPI** ◾-🛠️. ⚒ ⚫️ ⏩ 🌀 & 🏏 🧰 & 🍕 💪. @@ -98,7 +98,7 @@ def read_url(): 👀 🔀 `requests.get(...)` & `@app.get(...)`. -/// check | "😮 **FastAPI** " +/// check | 😮 **FastAPI** * ✔️ 🙅 & 🏋️ 🛠️. * ⚙️ 🇺🇸🔍 👩‍🔬 📛 (🛠️) 🔗, 🎯 & 🏋️ 🌌. @@ -118,7 +118,7 @@ def read_url(): 👈 ⚫️❔ 🕐❔ 💬 🔃 ⏬ 2️⃣.0️⃣ ⚫️ ⚠ 💬 "🦁", & ⏬ 3️⃣ ➕ "🗄". -/// check | "😮 **FastAPI** " +/// check | 😮 **FastAPI** 🛠️ & ⚙️ 📂 🐩 🛠️ 🔧, ↩️ 🛃 🔗. @@ -147,7 +147,7 @@ def read_url(): ✋️ ⚫️ ✍ ⏭ 📤 🔀 🐍 🆎 🔑. , 🔬 🔠 🔗 👆 💪 ⚙️ 🎯 🇨🇻 & 🎓 🚚 🍭. -/// check | "😮 **FastAPI** " +/// check | 😮 **FastAPI** ⚙️ 📟 🔬 "🔗" 👈 🚚 💽 🆎 & 🔬, 🔁. @@ -169,7 +169,7 @@ Webarg ✍ 🎏 🍭 👩‍💻. /// -/// check | "😮 **FastAPI** " +/// check | 😮 **FastAPI** ✔️ 🏧 🔬 📨 📨 💽. @@ -199,7 +199,7 @@ APISpec ✍ 🎏 🍭 👩‍💻. /// -/// check | "😮 **FastAPI** " +/// check | 😮 **FastAPI** 🐕‍🦺 📂 🐩 🛠️, 🗄. @@ -231,7 +231,7 @@ APISpec ✍ 🎏 🍭 👩‍💻. /// -/// check | "😮 **FastAPI** " +/// check | 😮 **FastAPI** 🏗 🗄 🔗 🔁, ⚪️➡️ 🎏 📟 👈 🔬 🛠️ & 🔬. @@ -251,7 +251,7 @@ APISpec ✍ 🎏 🍭 👩‍💻. ⚫️ 💪 🚫 🍵 🔁 🏷 📶 👍. , 🚥 🎻 💪 📨 🎻 🎚 👈 ✔️ 🔘 🏑 👈 🔄 🐦 🎻 🎚, ⚫️ 🚫🔜 ☑ 📄 & ✔. -/// check | "😮 **FastAPI** " +/// check | 😮 **FastAPI** ⚙️ 🐍 🆎 ✔️ 👑 👨‍🎨 🐕‍🦺. @@ -263,7 +263,7 @@ APISpec ✍ 🎏 🍭 👩‍💻. ⚫️ 🕐 🥇 📶 ⏩ 🐍 🛠️ ⚓️ 🔛 `asyncio`. ⚫️ ⚒ 📶 🎏 🏺. -/// note | "📡 ℹ" +/// note | 📡 ℹ ⚫️ ⚙️ `uvloop` ↩️ 🔢 🐍 `asyncio` ➰. 👈 ⚫️❔ ⚒ ⚫️ ⏩. @@ -271,7 +271,7 @@ APISpec ✍ 🎏 🍭 👩‍💻. /// -/// check | "😮 **FastAPI** " +/// check | 😮 **FastAPI** 🔎 🌌 ✔️ 😜 🎭. @@ -287,7 +287,7 @@ APISpec ✍ 🎏 🍭 👩‍💻. , 💽 🔬, 🛠️, & 🧾, ✔️ ⌛ 📟, 🚫 🔁. ⚖️ 👫 ✔️ 🛠️ 🛠️ 🔛 🔝 🦅, 💖 🤗. 👉 🎏 🔺 🔨 🎏 🛠️ 👈 😮 🦅 🔧, ✔️ 1️⃣ 📨 🎚 & 1️⃣ 📨 🎚 🔢. -/// check | "😮 **FastAPI** " +/// check | 😮 **FastAPI** 🔎 🌌 🤚 👑 🎭. @@ -313,7 +313,7 @@ APISpec ✍ 🎏 🍭 👩‍💻. 🛣 📣 👁 🥉, ⚙️ 🔢 📣 🎏 🥉 (↩️ ⚙️ 👨‍🎨 👈 💪 🥉 ▶️️ 🔛 🔝 🔢 👈 🍵 🔗). 👉 🔐 ❔ ✳ 🔨 ⚫️ 🌘 ❔ 🏺 (& 💃) 🔨 ⚫️. ⚫️ 🎏 📟 👜 👈 📶 😆 🔗. -/// check | "😮 **FastAPI** " +/// check | 😮 **FastAPI** 🔬 ➕ 🔬 💽 🆎 ⚙️ "🔢" 💲 🏷 🔢. 👉 📉 👨‍🎨 🐕‍🦺, & ⚫️ 🚫 💪 Pydantic ⏭. @@ -341,7 +341,7 @@ APISpec ✍ 🎏 🍭 👩‍💻. /// -/// check | "💭 😮 **FastAPI**" +/// check | 💭 😮 **FastAPI** 🤗 😮 🍕 APIStar, & 1️⃣ 🧰 👤 🔎 🏆 👍, 🌟 APIStar. @@ -385,7 +385,7 @@ APIStar ✍ ✡ 🇺🇸🏛. 🎏 👨 👈 ✍: /// -/// check | "😮 **FastAPI** " +/// check | 😮 **FastAPI** 🔀. @@ -409,7 +409,7 @@ Pydantic 🗃 🔬 💽 🔬, 🛠️ & 🧾 (⚙️ 🎻 🔗) ⚓️ 🔛 ⚫️ ⭐ 🍭. 👐 ⚫️ ⏩ 🌘 🍭 📇. & ⚫️ ⚓️ 🔛 🎏 🐍 🆎 🔑, 👨‍🎨 🐕‍🦺 👑. -/// check | "**FastAPI** ⚙️ ⚫️" +/// check | **FastAPI** ⚙️ ⚫️ 🍵 🌐 💽 🔬, 💽 🛠️ & 🏧 🏷 🧾 (⚓️ 🔛 🎻 🔗). @@ -444,7 +444,7 @@ Pydantic 🗃 🔬 💽 🔬, 🛠️ & 🧾 (⚙️ 🎻 🔗) ⚓️ 🔛 👈 1️⃣ 👑 👜 👈 **FastAPI** 🚮 🔛 🔝, 🌐 ⚓️ 🔛 🐍 🆎 🔑 (⚙️ Pydantic). 👈, ➕ 🔗 💉 ⚙️, 💂‍♂ 🚙, 🗄 🔗 ⚡, ♒️. -/// note | "📡 ℹ" +/// note | 📡 ℹ 🔫 🆕 "🐩" ➖ 🛠️ ✳ 🐚 🏉 👨‍🎓. ⚫️ 🚫 "🐍 🐩" (🇩🇬), 👐 👫 🛠️ 🔨 👈. @@ -452,7 +452,7 @@ Pydantic 🗃 🔬 💽 🔬, 🛠️ & 🧾 (⚙️ 🎻 🔗) ⚓️ 🔛 /// -/// check | "**FastAPI** ⚙️ ⚫️" +/// check | **FastAPI** ⚙️ ⚫️ 🍵 🌐 🐚 🕸 🍕. ❎ ⚒ 🔛 🔝. @@ -470,7 +470,7 @@ Uvicorn 🌩-⏩ 🔫 💽, 🏗 🔛 uvloop & httptool. ⚫️ 👍 💽 💃 & **FastAPI**. -/// check | "**FastAPI** 👍 ⚫️" +/// check | **FastAPI** 👍 ⚫️ 👑 🕸 💽 🏃 **FastAPI** 🈸. diff --git a/docs/em/docs/contributing.md b/docs/em/docs/contributing.md deleted file mode 100644 index 3ac1afda4..000000000 --- a/docs/em/docs/contributing.md +++ /dev/null @@ -1,493 +0,0 @@ -# 🛠️ - 📉 - -🥇, 👆 💪 💚 👀 🔰 🌌 [ℹ FastAPI & 🤚 ℹ](help-fastapi.md){.internal-link target=_blank}. - -## 🛠️ - -🚥 👆 ⏪ 🖖 🗃 & 👆 💭 👈 👆 💪 ⏬ 🤿 📟, 📥 📄 ⚒ 🆙 👆 🌐. - -### 🕹 🌐 ⏮️ `venv` - -👆 💪 ✍ 🕹 🌐 📁 ⚙️ 🐍 `venv` 🕹: - -
- -```console -$ python -m venv env -``` - -
- -👈 🔜 ✍ 📁 `./env/` ⏮️ 🐍 💱 & ⤴️ 👆 🔜 💪 ❎ 📦 👈 ❎ 🌐. - -### 🔓 🌐 - -🔓 🆕 🌐 ⏮️: - -//// tab | 💾, 🇸🇻 - -
- -```console -$ source ./env/bin/activate -``` - -
- -//// - -//// tab | 🚪 📋 - -
- -```console -$ .\env\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | 🚪 🎉 - -⚖️ 🚥 👆 ⚙️ 🎉 🖥 (✅ 🐛 🎉): - -
- -```console -$ source ./env/Scripts/activate -``` - -
- -//// - -✅ ⚫️ 👷, ⚙️: - -//// tab | 💾, 🇸🇻, 🚪 🎉 - -
- -```console -$ which pip - -some/directory/fastapi/env/bin/pip -``` - -
- -//// - -//// tab | 🚪 📋 - -
- -```console -$ Get-Command pip - -some/directory/fastapi/env/bin/pip -``` - -
- -//// - -🚥 ⚫️ 🎦 `pip` 💱 `env/bin/pip` ⤴️ ⚫️ 👷. 👶 - -⚒ 💭 👆 ✔️ 📰 🐖 ⏬ 🔛 👆 🕹 🌐 ❎ ❌ 🔛 ⏭ 📶: - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip - -🔠 🕰 👆 ❎ 🆕 📦 ⏮️ `pip` 🔽 👈 🌐, 🔓 🌐 🔄. - -👉 ⚒ 💭 👈 🚥 👆 ⚙️ 📶 📋 ❎ 👈 📦, 👆 ⚙️ 1️⃣ ⚪️➡️ 👆 🇧🇿 🌐 & 🚫 🙆 🎏 👈 💪 ❎ 🌐. - -/// - -### 🐖 - -⏮️ 🔓 🌐 🔬 🔛: - -
- -```console -$ pip install -r requirements.txt - ----> 100% -``` - -
- -⚫️ 🔜 ❎ 🌐 🔗 & 👆 🇧🇿 FastAPI 👆 🇧🇿 🌐. - -#### ⚙️ 👆 🇧🇿 FastAPI - -🚥 👆 ✍ 🐍 📁 👈 🗄 & ⚙️ FastAPI, & 🏃 ⚫️ ⏮️ 🐍 ⚪️➡️ 👆 🇧🇿 🌐, ⚫️ 🔜 ⚙️ 👆 🇧🇿 FastAPI ℹ 📟. - -& 🚥 👆 ℹ 👈 🇧🇿 FastAPI ℹ 📟, ⚫️ ❎ ⏮️ `-e`, 🕐❔ 👆 🏃 👈 🐍 📁 🔄, ⚫️ 🔜 ⚙️ 🍋 ⏬ FastAPI 👆 ✍. - -👈 🌌, 👆 🚫 ✔️ "❎" 👆 🇧🇿 ⏬ 💪 💯 🔠 🔀. - -### 📁 - -📤 ✍ 👈 👆 💪 🏃 👈 🔜 📁 & 🧹 🌐 👆 📟: - -
- -```console -$ bash scripts/format.sh -``` - -
- -⚫️ 🔜 🚘-😇 🌐 👆 🗄. - -⚫️ 😇 👫 ☑, 👆 💪 ✔️ FastAPI ❎ 🌐 👆 🌐, ⏮️ 📋 📄 🔛 ⚙️ `-e`. - -## 🩺 - -🥇, ⚒ 💭 👆 ⚒ 🆙 👆 🌐 🔬 🔛, 👈 🔜 ❎ 🌐 📄. - -🧾 ⚙️ ⬜. - -& 📤 ➕ 🧰/✍ 🥉 🍵 ✍ `./scripts/docs.py`. - -/// tip - -👆 🚫 💪 👀 📟 `./scripts/docs.py`, 👆 ⚙️ ⚫️ 📋 ⏸. - -/// - -🌐 🧾 ✍ 📁 📁 `./docs/en/`. - -📚 🔰 ✔️ 🍫 📟. - -🌅 💼, 👫 🍫 📟 ☑ 🏁 🈸 👈 💪 🏃. - -👐, 👈 🍫 📟 🚫 ✍ 🔘 ✍, 👫 🐍 📁 `./docs_src/` 📁. - -& 👈 🐍 📁 🔌/💉 🧾 🕐❔ 🏭 🕸. - -### 🩺 💯 - -🏆 💯 🤙 🏃 🛡 🖼 ℹ 📁 🧾. - -👉 ℹ ⚒ 💭 👈: - -* 🧾 🆙 📅. -* 🧾 🖼 💪 🏃. -* 🌅 ⚒ 📔 🧾, 🚚 💯 💰. - -⏮️ 🇧🇿 🛠️, 📤 ✍ 👈 🏗 🕸 & ✅ 🙆 🔀, 🖖-🔫: - -
- -```console -$ python ./scripts/docs.py live - -[INFO] Serving on http://127.0.0.1:8008 -[INFO] Start watching changes -[INFO] Start detecting changes -``` - -
- -⚫️ 🔜 🍦 🧾 🔛 `http://127.0.0.1:8008`. - -👈 🌌, 👆 💪 ✍ 🧾/ℹ 📁 & 👀 🔀 🖖. - -#### 🏎 ✳ (📦) - -👩‍🌾 📥 🎦 👆 ❔ ⚙️ ✍ `./scripts/docs.py` ⏮️ `python` 📋 🔗. - -✋️ 👆 💪 ⚙️ 🏎 ✳, & 👆 🔜 🤚 ✍ 👆 📶 📋 ⏮️ ❎ 🛠️. - -🚥 👆 ❎ 🏎 ✳, 👆 💪 ❎ 🛠️ ⏮️: - -
- -```console -$ typer --install-completion - -zsh completion installed in /home/user/.bashrc. -Completion will take effect once you restart the terminal. -``` - -
- -### 📱 & 🩺 🎏 🕰 - -🚥 👆 🏃 🖼 ⏮️, ✅: - -
- -```console -$ uvicorn tutorial001:app --reload - -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -``` - -
- -Uvicorn 🔢 🔜 ⚙️ ⛴ `8000`, 🧾 🔛 ⛴ `8008` 🏆 🚫 ⚔. - -### ✍ - -ℹ ⏮️ ✍ 📶 🌅 👍 ❗ & ⚫️ 💪 🚫 🔨 🍵 ℹ ⚪️➡️ 👪. 👶 👶 - -📥 📶 ℹ ⏮️ ✍. - -#### 💁‍♂ & 📄 - -* ✅ ⏳ ♻ 🚲 📨 👆 🇪🇸 & 🚮 📄 ✔ 🔀 ⚖️ ✔ 👫. - -/// tip - -👆 💪 🚮 🏤 ⏮️ 🔀 🔑 ♻ 🚲 📨. - -✅ 🩺 🔃 ❎ 🚲 📨 📄 ✔ ⚫️ ⚖️ 📨 🔀. - -/// - -* ✅ ❔ 👀 🚥 📤 1️⃣ 🛠️ ✍ 👆 🇪🇸. - -* 🚮 👁 🚲 📨 📍 📃 💬. 👈 🔜 ⚒ ⚫️ 🌅 ⏩ 🎏 📄 ⚫️. - -🇪🇸 👤 🚫 💬, 👤 🔜 ⌛ 📚 🎏 📄 ✍ ⏭ 🔗. - -* 👆 💪 ✅ 🚥 📤 ✍ 👆 🇪🇸 & 🚮 📄 👫, 👈 🔜 ℹ 👤 💭 👈 ✍ ☑ & 👤 💪 🔗 ⚫️. - -* ⚙️ 🎏 🐍 🖼 & 🕴 💬 ✍ 🩺. 👆 🚫 ✔️ 🔀 🕳 👉 👷. - -* ⚙️ 🎏 🖼, 📁 📛, & 🔗. 👆 🚫 ✔️ 🔀 🕳 ⚫️ 👷. - -* ✅ 2️⃣-🔤 📟 🇪🇸 👆 💚 💬 👆 💪 ⚙️ 🏓 📇 💾 6️⃣3️⃣9️⃣-1️⃣ 📟. - -#### ♻ 🇪🇸 - -➡️ 💬 👆 💚 💬 📃 🇪🇸 👈 ⏪ ✔️ ✍ 📃, 💖 🇪🇸. - -💼 🇪🇸, 2️⃣-🔤 📟 `es`. , 📁 🇪🇸 ✍ 🔎 `docs/es/`. - -/// tip - -👑 ("🛂") 🇪🇸 🇪🇸, 🔎 `docs/en/`. - -/// - -🔜 🏃 🖖 💽 🩺 🇪🇸: - -
- -```console -// Use the command "live" and pass the language code as a CLI argument -$ python ./scripts/docs.py live es - -[INFO] Serving on http://127.0.0.1:8008 -[INFO] Start watching changes -[INFO] Start detecting changes -``` - -
- -🔜 👆 💪 🚶 http://127.0.0.1:8008 & 👀 👆 🔀 🖖. - -🚥 👆 👀 FastAPI 🩺 🕸, 👆 🔜 👀 👈 🔠 🇪🇸 ✔️ 🌐 📃. ✋️ 📃 🚫 💬 & ✔️ 📨 🔃 ❌ ✍. - -✋️ 🕐❔ 👆 🏃 ⚫️ 🌐 💖 👉, 👆 🔜 🕴 👀 📃 👈 ⏪ 💬. - -🔜 ➡️ 💬 👈 👆 💚 🚮 ✍ 📄 [⚒](features.md){.internal-link target=_blank}. - -* 📁 📁: - -``` -docs/en/docs/features.md -``` - -* 📋 ⚫️ ⚫️❔ 🎏 🗺 ✋️ 🇪🇸 👆 💚 💬, ✅: - -``` -docs/es/docs/features.md -``` - -/// tip - -👀 👈 🕴 🔀 ➡ & 📁 📛 🇪🇸 📟, ⚪️➡️ `en` `es`. - -/// - -* 🔜 📂 ⬜ 📁 📁 🇪🇸: - -``` -docs/en/mkdocs.yml -``` - -* 🔎 🥉 🌐❔ 👈 `docs/features.md` 🔎 📁 📁. 👱 💖: - -```YAML hl_lines="8" -site_name: FastAPI -# More stuff -nav: -- FastAPI: index.md -- Languages: - - en: / - - es: /es/ -- features.md -``` - -* 📂 ⬜ 📁 📁 🇪🇸 👆 ✍, ✅: - -``` -docs/es/mkdocs.yml -``` - -* 🚮 ⚫️ 📤 ☑ 🎏 🗺 ⚫️ 🇪🇸, ✅: - -```YAML hl_lines="8" -site_name: FastAPI -# More stuff -nav: -- FastAPI: index.md -- Languages: - - en: / - - es: /es/ -- features.md -``` - -⚒ 💭 👈 🚥 📤 🎏 ⛔, 🆕 ⛔ ⏮️ 👆 ✍ ⚫️❔ 🎏 ✔ 🇪🇸 ⏬. - -🚥 👆 🚶 👆 🖥 👆 🔜 👀 👈 🔜 🩺 🎦 👆 🆕 📄. 👶 - -🔜 👆 💪 💬 ⚫️ 🌐 & 👀 ❔ ⚫️ 👀 👆 🖊 📁. - -#### 🆕 🇪🇸 - -➡️ 💬 👈 👆 💚 🚮 ✍ 🇪🇸 👈 🚫 💬, 🚫 📃. - -➡️ 💬 👆 💚 🚮 ✍ 🇭🇹, & ⚫️ 🚫 📤 🩺. - -✅ 🔗 ⚪️➡️ 🔛, 📟 "🇭🇹" `ht`. - -⏭ 🔁 🏃 ✍ 🏗 🆕 ✍ 📁: - -
- -```console -// Use the command new-lang, pass the language code as a CLI argument -$ python ./scripts/docs.py new-lang ht - -Successfully initialized: docs/ht -Updating ht -Updating en -``` - -
- -🔜 👆 💪 ✅ 👆 📟 👨‍🎨 ⏳ ✍ 📁 `docs/ht/`. - -/// tip - -✍ 🥇 🚲 📨 ⏮️ 👉, ⚒ 🆙 📳 🆕 🇪🇸, ⏭ ❎ ✍. - -👈 🌌 🎏 💪 ℹ ⏮️ 🎏 📃 ⏪ 👆 👷 🔛 🥇 🕐. 👶 - -/// - -▶️ ✍ 👑 📃, `docs/ht/index.md`. - -⤴️ 👆 💪 😣 ⏮️ ⏮️ 👩‍🌾, "♻ 🇪🇸". - -##### 🆕 🇪🇸 🚫 🐕‍🦺 - -🚥 🕐❔ 🏃‍♂ 🖖 💽 ✍ 👆 🤚 ❌ 🔃 🇪🇸 🚫 ➖ 🐕‍🦺, 🕳 💖: - -``` - raise TemplateNotFound(template) -jinja2.exceptions.TemplateNotFound: partials/language/xx.html -``` - -👈 ⛓ 👈 🎢 🚫 🐕‍🦺 👈 🇪🇸 (👉 💼, ⏮️ ❌ 2️⃣-🔤 📟 `xx`). - -✋️ 🚫 😟, 👆 💪 ⚒ 🎢 🇪🇸 🇪🇸 & ⤴️ 💬 🎚 🩺. - -🚥 👆 💪 👈, ✍ `mkdocs.yml` 👆 🆕 🇪🇸, ⚫️ 🔜 ✔️ 🕳 💖: - -```YAML hl_lines="5" -site_name: FastAPI -# More stuff -theme: - # More stuff - language: xx -``` - -🔀 👈 🇪🇸 ⚪️➡️ `xx` (⚪️➡️ 👆 🇪🇸 📟) `en`. - -⤴️ 👆 💪 ▶️ 🖖 💽 🔄. - -#### 🎮 🏁 - -🕐❔ 👆 ⚙️ ✍ `./scripts/docs.py` ⏮️ `live` 📋 ⚫️ 🕴 🎦 📁 & ✍ 💪 ⏮️ 🇪🇸. - -✋️ 🕐 👆 🔨, 👆 💪 💯 ⚫️ 🌐 ⚫️ 🔜 👀 💳. - -👈, 🥇 🏗 🌐 🩺: - -
- -```console -// Use the command "build-all", this will take a bit -$ python ./scripts/docs.py build-all - -Updating es -Updating en -Building docs for: en -Building docs for: es -Successfully built docs for: es -Copying en index.md to README.md -``` - -
- -👈 🏗 🌐 🩺 `./docs_build/` 🔠 🇪🇸. 👉 🔌 ❎ 🙆 📁 ⏮️ ❌ ✍, ⏮️ 🗒 💬 👈 "👉 📁 🚫 ✔️ ✍". ✋️ 👆 🚫 ✔️ 🕳 ⏮️ 👈 📁. - -⤴️ ⚫️ 🏗 🌐 👈 🔬 ⬜ 🕸 🔠 🇪🇸, 🌀 👫, & 🏗 🏁 🔢 `./site/`. - -⤴️ 👆 💪 🍦 👈 ⏮️ 📋 `serve`: - -
- -```console -// Use the command "serve" after running "build-all" -$ python ./scripts/docs.py serve - -Warning: this is a very simple server. For development, use mkdocs serve instead. -This is here only to preview a site with translations already built. -Make sure you run the build-all command first. -Serving at: http://127.0.0.1:8008 -``` - -
- -## 💯 - -📤 ✍ 👈 👆 💪 🏃 🌐 💯 🌐 📟 & 🏗 💰 📄 🕸: - -
- -```console -$ bash scripts/test-cov-html.sh -``` - -
- -👉 📋 🏗 📁 `./htmlcov/`, 🚥 👆 📂 📁 `./htmlcov/index.html` 👆 🖥, 👆 💪 🔬 🖥 🇹🇼 📟 👈 📔 💯, & 👀 🚥 📤 🙆 🇹🇼 ❌. diff --git a/docs/em/docs/how-to/custom-request-and-route.md b/docs/em/docs/how-to/custom-request-and-route.md index 0425e6267..cd8811d4e 100644 --- a/docs/em/docs/how-to/custom-request-and-route.md +++ b/docs/em/docs/how-to/custom-request-and-route.md @@ -60,7 +60,7 @@ {!../../docs_src/custom_request_and_route/tutorial001.py!} ``` -/// note | "📡 ℹ" +/// note | 📡 ℹ `Request` ✔️ `request.scope` 🔢, 👈 🐍 `dict` ⚗ 🗃 🔗 📨. diff --git a/docs/em/docs/tutorial/background-tasks.md b/docs/em/docs/tutorial/background-tasks.md index 0f4585ebe..6b14c6135 100644 --- a/docs/em/docs/tutorial/background-tasks.md +++ b/docs/em/docs/tutorial/background-tasks.md @@ -97,8 +97,6 @@ 👫 😑 🚚 🌖 🏗 📳, 📧/👨‍🏭 📤 👨‍💼, 💖 ✳ ⚖️ ✳, ✋️ 👫 ✔ 👆 🏃 🖥 📋 💗 🛠️, & ✴️, 💗 💽. -👀 🖼, ✅ [🏗 🚂](../project-generation.md){.internal-link target=_blank}, 👫 🌐 🔌 🥒 ⏪ 📶. - ✋️ 🚥 👆 💪 🔐 🔢 & 🎚 ⚪️➡️ 🎏 **FastAPI** 📱, ⚖️ 👆 💪 🎭 🤪 🖥 📋 (💖 📨 📧 📨), 👆 💪 🎯 ⚙️ `BackgroundTasks`. ## 🌃 diff --git a/docs/em/docs/tutorial/bigger-applications.md b/docs/em/docs/tutorial/bigger-applications.md index 074ab302c..68f506f27 100644 --- a/docs/em/docs/tutorial/bigger-applications.md +++ b/docs/em/docs/tutorial/bigger-applications.md @@ -414,7 +414,7 @@ from .routers.users import router ⚫️ 🔜 🔌 🌐 🛣 ⚪️➡️ 👈 📻 🍕 ⚫️. -/// note | "📡 ℹ" +/// note | 📡 ℹ ⚫️ 🔜 🤙 🔘 ✍ *➡ 🛠️* 🔠 *➡ 🛠️* 👈 📣 `APIRouter`. @@ -477,7 +477,7 @@ from .routers.users import router & ⚫️ 🔜 👷 ☑, 👯‍♂️ ⏮️ 🌐 🎏 *➡ 🛠️* 🚮 ⏮️ `app.include_router()`. -/// info | "📶 📡 ℹ" +/// info | 📶 📡 ℹ **🗒**: 👉 📶 📡 ℹ 👈 👆 🎲 💪 **🚶**. diff --git a/docs/em/docs/tutorial/body-fields.md b/docs/em/docs/tutorial/body-fields.md index eb3093de2..be39b4a9a 100644 --- a/docs/em/docs/tutorial/body-fields.md +++ b/docs/em/docs/tutorial/body-fields.md @@ -50,7 +50,7 @@ `Field` 👷 🎏 🌌 `Query`, `Path` & `Body`, ⚫️ ✔️ 🌐 🎏 🔢, ♒️. -/// note | "📡 ℹ" +/// note | 📡 ℹ 🤙, `Query`, `Path` & 🎏 👆 🔜 👀 ⏭ ✍ 🎚 🏿 ⚠ `Param` 🎓, ❔ ⚫️ 🏿 Pydantic `FieldInfo` 🎓. diff --git a/docs/em/docs/tutorial/body-updates.md b/docs/em/docs/tutorial/body-updates.md index 4a4b3b6b8..7e2fbfaf7 100644 --- a/docs/em/docs/tutorial/body-updates.md +++ b/docs/em/docs/tutorial/body-updates.md @@ -6,29 +6,7 @@ 👆 💪 ⚙️ `jsonable_encoder` 🗜 🔢 💽 📊 👈 💪 🏪 🎻 (✅ ⏮️ ☁ 💽). 🖼, 🏭 `datetime` `str`. -//// tab | 🐍 3️⃣.6️⃣ & 🔛 - -```Python hl_lines="30-35" -{!> ../../docs_src/body_updates/tutorial001.py!} -``` - -//// - -//// tab | 🐍 3️⃣.9️⃣ & 🔛 - -```Python hl_lines="30-35" -{!> ../../docs_src/body_updates/tutorial001_py39.py!} -``` - -//// - -//// tab | 🐍 3️⃣.1️⃣0️⃣ & 🔛 - -```Python hl_lines="28-33" -{!> ../../docs_src/body_updates/tutorial001_py310.py!} -``` - -//// +{* ../../docs_src/body_updates/tutorial001.py hl[30:35] *} `PUT` ⚙️ 📨 💽 👈 🔜 ❎ ♻ 💽. @@ -76,29 +54,7 @@ ⤴️ 👆 💪 ⚙️ 👉 🏗 `dict` ⏮️ 🕴 💽 👈 ⚒ (📨 📨), 🚫 🔢 💲: -//// tab | 🐍 3️⃣.6️⃣ & 🔛 - -```Python hl_lines="34" -{!> ../../docs_src/body_updates/tutorial002.py!} -``` - -//// - -//// tab | 🐍 3️⃣.9️⃣ & 🔛 - -```Python hl_lines="34" -{!> ../../docs_src/body_updates/tutorial002_py39.py!} -``` - -//// - -//// tab | 🐍 3️⃣.1️⃣0️⃣ & 🔛 - -```Python hl_lines="32" -{!> ../../docs_src/body_updates/tutorial002_py310.py!} -``` - -//// +{* ../../docs_src/body_updates/tutorial002.py hl[34] *} ### ⚙️ Pydantic `update` 🔢 @@ -106,29 +62,7 @@ 💖 `stored_item_model.copy(update=update_data)`: -//// tab | 🐍 3️⃣.6️⃣ & 🔛 - -```Python hl_lines="35" -{!> ../../docs_src/body_updates/tutorial002.py!} -``` - -//// - -//// tab | 🐍 3️⃣.9️⃣ & 🔛 - -```Python hl_lines="35" -{!> ../../docs_src/body_updates/tutorial002_py39.py!} -``` - -//// - -//// tab | 🐍 3️⃣.1️⃣0️⃣ & 🔛 - -```Python hl_lines="33" -{!> ../../docs_src/body_updates/tutorial002_py310.py!} -``` - -//// +{* ../../docs_src/body_updates/tutorial002.py hl[35] *} ### 🍕 ℹ 🌃 @@ -145,29 +79,7 @@ * 🖊 💽 👆 💽. * 📨 ℹ 🏷. -//// tab | 🐍 3️⃣.6️⃣ & 🔛 - -```Python hl_lines="30-37" -{!> ../../docs_src/body_updates/tutorial002.py!} -``` - -//// - -//// tab | 🐍 3️⃣.9️⃣ & 🔛 - -```Python hl_lines="30-37" -{!> ../../docs_src/body_updates/tutorial002_py39.py!} -``` - -//// - -//// tab | 🐍 3️⃣.1️⃣0️⃣ & 🔛 - -```Python hl_lines="28-35" -{!> ../../docs_src/body_updates/tutorial002_py310.py!} -``` - -//// +{* ../../docs_src/body_updates/tutorial002.py hl[30:37] *} /// tip diff --git a/docs/em/docs/tutorial/cookie-params.md b/docs/em/docs/tutorial/cookie-params.md index f4956e76f..5126eab0a 100644 --- a/docs/em/docs/tutorial/cookie-params.md +++ b/docs/em/docs/tutorial/cookie-params.md @@ -44,7 +44,7 @@ //// -/// note | "📡 ℹ" +/// note | 📡 ℹ `Cookie` "👭" 🎓 `Path` & `Query`. ⚫️ 😖 ⚪️➡️ 🎏 ⚠ `Param` 🎓. diff --git a/docs/em/docs/tutorial/cors.md b/docs/em/docs/tutorial/cors.md index 5829319cb..801d66fdd 100644 --- a/docs/em/docs/tutorial/cors.md +++ b/docs/em/docs/tutorial/cors.md @@ -78,7 +78,7 @@ 🌖 ℹ 🔃 ⚜, ✅ 🦎 ⚜ 🧾. -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette.middleware.cors import CORSMiddleware`. diff --git a/docs/em/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/em/docs/tutorial/dependencies/dependencies-with-yield.md index e0d6dba24..2896be39d 100644 --- a/docs/em/docs/tutorial/dependencies/dependencies-with-yield.md +++ b/docs/em/docs/tutorial/dependencies/dependencies-with-yield.md @@ -10,7 +10,7 @@ FastAPI 🐕‍🦺 🔗 👈 🔑 👨‍💼. diff --git a/docs/em/docs/tutorial/first-steps.md b/docs/em/docs/tutorial/first-steps.md index d8cc05c40..d6762422e 100644 --- a/docs/em/docs/tutorial/first-steps.md +++ b/docs/em/docs/tutorial/first-steps.md @@ -139,7 +139,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) `FastAPI` 🐍 🎓 👈 🚚 🌐 🛠️ 👆 🛠️. -/// note | "📡 ℹ" +/// note | 📡 ℹ `FastAPI` 🎓 👈 😖 🔗 ⚪️➡️ `Starlette`. @@ -259,7 +259,7 @@ https://example.com/items/foo * ➡ `/` * ⚙️ get 🛠️ -/// info | "`@decorator` ℹ" +/// info | `@decorator` ℹ 👈 `@something` ❕ 🐍 🤙 "👨‍🎨". diff --git a/docs/em/docs/tutorial/handling-errors.md b/docs/em/docs/tutorial/handling-errors.md index 7f6a704eb..e0edae51a 100644 --- a/docs/em/docs/tutorial/handling-errors.md +++ b/docs/em/docs/tutorial/handling-errors.md @@ -109,7 +109,7 @@ {"message": "Oops! yolo did something. There goes a rainbow..."} ``` -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette.requests import Request` & `from starlette.responses import JSONResponse`. @@ -192,7 +192,7 @@ path -> item_id {!../../docs_src/handling_errors/tutorial004.py!} ``` -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette.responses import PlainTextResponse`. diff --git a/docs/em/docs/tutorial/header-params.md b/docs/em/docs/tutorial/header-params.md index 34abd3a4c..d9eafe77e 100644 --- a/docs/em/docs/tutorial/header-params.md +++ b/docs/em/docs/tutorial/header-params.md @@ -44,7 +44,7 @@ //// -/// note | "📡 ℹ" +/// note | 📡 ℹ `Header` "👭" 🎓 `Path`, `Query` & `Cookie`. ⚫️ 😖 ⚪️➡️ 🎏 ⚠ `Param` 🎓. diff --git a/docs/em/docs/tutorial/middleware.md b/docs/em/docs/tutorial/middleware.md index cd0777ebb..a794ab019 100644 --- a/docs/em/docs/tutorial/middleware.md +++ b/docs/em/docs/tutorial/middleware.md @@ -11,7 +11,7 @@ * ⚫️ 💪 🕳 👈 **📨** ⚖️ 🏃 🙆 💪 📟. * ⤴️ ⚫️ 📨 **📨**. -/// note | "📡 ℹ" +/// note | 📡 ℹ 🚥 👆 ✔️ 🔗 ⏮️ `yield`, 🚪 📟 🔜 🏃 *⏮️* 🛠️. @@ -43,7 +43,7 @@ /// -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette.requests import Request`. diff --git a/docs/em/docs/tutorial/path-operation-configuration.md b/docs/em/docs/tutorial/path-operation-configuration.md index 9529928fb..deb71c807 100644 --- a/docs/em/docs/tutorial/path-operation-configuration.md +++ b/docs/em/docs/tutorial/path-operation-configuration.md @@ -42,7 +42,7 @@ 👈 👔 📟 🔜 ⚙️ 📨 & 🔜 🚮 🗄 🔗. -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette import status`. diff --git a/docs/em/docs/tutorial/path-params-numeric-validations.md b/docs/em/docs/tutorial/path-params-numeric-validations.md index c25f0323e..74dbb55f7 100644 --- a/docs/em/docs/tutorial/path-params-numeric-validations.md +++ b/docs/em/docs/tutorial/path-params-numeric-validations.md @@ -140,7 +140,7 @@ /// -/// note | "📡 ℹ" +/// note | 📡 ℹ 🕐❔ 👆 🗄 `Query`, `Path` & 🎏 ⚪️➡️ `fastapi`, 👫 🤙 🔢. diff --git a/docs/em/docs/tutorial/request-files.md b/docs/em/docs/tutorial/request-files.md index 102690f4b..9dcad81b4 100644 --- a/docs/em/docs/tutorial/request-files.md +++ b/docs/em/docs/tutorial/request-files.md @@ -99,13 +99,13 @@ contents = await myfile.read() contents = myfile.file.read() ``` -/// note | "`async` 📡 ℹ" +/// note | `async` 📡 ℹ 🕐❔ 👆 ⚙️ `async` 👩‍🔬, **FastAPI** 🏃 📁 👩‍🔬 🧵 & ⌛ 👫. /// -/// note | "💃 📡 ℹ" +/// note | 💃 📡 ℹ **FastAPI**'Ⓜ `UploadFile` 😖 🔗 ⚪️➡️ **💃**'Ⓜ `UploadFile`, ✋️ 🚮 💪 🍕 ⚒ ⚫️ 🔗 ⏮️ **Pydantic** & 🎏 🍕 FastAPI. @@ -117,7 +117,7 @@ contents = myfile.file.read() **FastAPI** 🔜 ⚒ 💭 ✍ 👈 📊 ⚪️➡️ ▶️️ 🥉 ↩️ 🎻. -/// note | "📡 ℹ" +/// note | 📡 ℹ 📊 ⚪️➡️ 📨 🛎 🗜 ⚙️ "📻 🆎" `application/x-www-form-urlencoded` 🕐❔ ⚫️ 🚫 🔌 📁. @@ -189,7 +189,7 @@ contents = myfile.file.read() 👆 🔜 📨, 📣, `list` `bytes` ⚖️ `UploadFile`Ⓜ. -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette.responses import HTMLResponse`. diff --git a/docs/em/docs/tutorial/request-forms.md b/docs/em/docs/tutorial/request-forms.md index cbe4e2862..d364d2c92 100644 --- a/docs/em/docs/tutorial/request-forms.md +++ b/docs/em/docs/tutorial/request-forms.md @@ -50,7 +50,7 @@ **FastAPI** 🔜 ⚒ 💭 ✍ 👈 📊 ⚪️➡️ ▶️️ 🥉 ↩️ 🎻. -/// note | "📡 ℹ" +/// note | 📡 ℹ 📊 ⚪️➡️ 📨 🛎 🗜 ⚙️ "📻 🆎" `application/x-www-form-urlencoded`. diff --git a/docs/em/docs/tutorial/response-status-code.md b/docs/em/docs/tutorial/response-status-code.md index cefff708f..478060326 100644 --- a/docs/em/docs/tutorial/response-status-code.md +++ b/docs/em/docs/tutorial/response-status-code.md @@ -94,7 +94,7 @@ FastAPI 💭 👉, & 🔜 🏭 🗄 🩺 👈 🇵🇸 📤 🙅‍♂ 📨 -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette import status`. diff --git a/docs/em/docs/tutorial/security/first-steps.md b/docs/em/docs/tutorial/security/first-steps.md index 6245f52ab..21c48757f 100644 --- a/docs/em/docs/tutorial/security/first-steps.md +++ b/docs/em/docs/tutorial/security/first-steps.md @@ -56,7 +56,7 @@ $ uvicorn main:app --reload -/// check | "✔ 🔼 ❗" +/// check | ✔ 🔼 ❗ 👆 ⏪ ✔️ ✨ 🆕 "✔" 🔼. @@ -176,7 +176,7 @@ oauth2_scheme(some, parameters) **FastAPI** 🔜 💭 👈 ⚫️ 💪 ⚙️ 👉 🔗 🔬 "💂‍♂ ⚖" 🗄 🔗 (& 🏧 🛠️ 🩺). -/// info | "📡 ℹ" +/// info | 📡 ℹ **FastAPI** 🔜 💭 👈 ⚫️ 💪 ⚙️ 🎓 `OAuth2PasswordBearer` (📣 🔗) 🔬 💂‍♂ ⚖ 🗄 ↩️ ⚫️ 😖 ⚪️➡️ `fastapi.security.oauth2.OAuth2`, ❔ 🔄 😖 ⚪️➡️ `fastapi.security.base.SecurityBase`. diff --git a/docs/em/docs/tutorial/sql-databases.md b/docs/em/docs/tutorial/sql-databases.md index c59d8c131..49162dd62 100644 --- a/docs/em/docs/tutorial/sql-databases.md +++ b/docs/em/docs/tutorial/sql-databases.md @@ -159,7 +159,7 @@ connect_args={"check_same_thread": False} ...💪 🕴 `SQLite`. ⚫️ 🚫 💪 🎏 💽. -/// info | "📡 ℹ" +/// info | 📡 ℹ 🔢 🗄 🔜 🕴 ✔ 1️⃣ 🧵 🔗 ⏮️ ⚫️, 🤔 👈 🔠 🧵 🔜 🍵 🔬 📨. @@ -622,7 +622,7 @@ current_user.items //// -/// info | "📡 ℹ" +/// info | 📡 ℹ 🔢 `db` 🤙 🆎 `SessionLocal`, ✋️ 👉 🎓 (✍ ⏮️ `sessionmaker()`) "🗳" 🇸🇲 `Session`,, 👨‍🎨 🚫 🤙 💭 ⚫️❔ 👩‍🔬 🚚. @@ -705,7 +705,7 @@ def read_user(user_id: int, db: Session = Depends(get_db)): /// -/// note | "📶 📡 ℹ" +/// note | 📶 📡 ℹ 🚥 👆 😟 & ✔️ ⏬ 📡 💡, 👆 💪 ✅ 📶 📡 ℹ ❔ 👉 `async def` 🆚 `def` 🍵 [🔁](../async.md#i_2){.internal-link target=_blank} 🩺. diff --git a/docs/em/docs/tutorial/static-files.md b/docs/em/docs/tutorial/static-files.md index 0627031b3..c9bb9ff6a 100644 --- a/docs/em/docs/tutorial/static-files.md +++ b/docs/em/docs/tutorial/static-files.md @@ -11,7 +11,7 @@ {!../../docs_src/static_files/tutorial001.py!} ``` -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette.staticfiles import StaticFiles`. diff --git a/docs/em/docs/tutorial/testing.md b/docs/em/docs/tutorial/testing.md index 5f3d5e736..27cf9f16e 100644 --- a/docs/em/docs/tutorial/testing.md +++ b/docs/em/docs/tutorial/testing.md @@ -40,7 +40,7 @@ /// -/// note | "📡 ℹ" +/// note | 📡 ℹ 👆 💪 ⚙️ `from starlette.testclient import TestClient`. diff --git a/docs/en/docs/advanced/additional-status-codes.md b/docs/en/docs/advanced/additional-status-codes.md index e39249467..077a00488 100644 --- a/docs/en/docs/advanced/additional-status-codes.md +++ b/docs/en/docs/advanced/additional-status-codes.md @@ -26,7 +26,7 @@ Make sure it has the data you want it to have, and that the values are valid JSO /// -/// note | "Technical Details" +/// note | Technical Details You could also use `from starlette.responses import JSONResponse`. diff --git a/docs/en/docs/advanced/behind-a-proxy.md b/docs/en/docs/advanced/behind-a-proxy.md index 87a62e88b..1f0d0fd9f 100644 --- a/docs/en/docs/advanced/behind-a-proxy.md +++ b/docs/en/docs/advanced/behind-a-proxy.md @@ -82,7 +82,7 @@ $ fastapi run main.py --root-path /api/v1 If you use Hypercorn, it also has the option `--root-path`. -/// note | "Technical Details" +/// note | Technical Details The ASGI specification defines a `root_path` for this use case. diff --git a/docs/en/docs/advanced/custom-response.md b/docs/en/docs/advanced/custom-response.md index 1d6dc3f6d..8268dd81a 100644 --- a/docs/en/docs/advanced/custom-response.md +++ b/docs/en/docs/advanced/custom-response.md @@ -30,9 +30,7 @@ This is because by default, FastAPI will inspect every item inside and make sure But if you are certain that the content that you are returning is **serializable with JSON**, you can pass it directly to the response class and avoid the extra overhead that FastAPI would have by passing your return content through the `jsonable_encoder` before passing it to the response class. -```Python hl_lines="2 7" -{!../../docs_src/custom_response/tutorial001b.py!} -``` +{* ../../docs_src/custom_response/tutorial001b.py hl[2,7] *} /// info @@ -57,9 +55,7 @@ To return a response with HTML directly from **FastAPI**, use `HTMLResponse`. * Import `HTMLResponse`. * Pass `HTMLResponse` as the parameter `response_class` of your *path operation decorator*. -```Python hl_lines="2 7" -{!../../docs_src/custom_response/tutorial002.py!} -``` +{* ../../docs_src/custom_response/tutorial002.py hl[2,7] *} /// info @@ -77,9 +73,7 @@ As seen in [Return a Response directly](response-directly.md){.internal-link tar The same example from above, returning an `HTMLResponse`, could look like: -```Python hl_lines="2 7 19" -{!../../docs_src/custom_response/tutorial003.py!} -``` +{* ../../docs_src/custom_response/tutorial003.py hl[2,7,19] *} /// warning @@ -103,9 +97,7 @@ The `response_class` will then be used only to document the OpenAPI *path operat For example, it could be something like: -```Python hl_lines="7 21 23" -{!../../docs_src/custom_response/tutorial004.py!} -``` +{* ../../docs_src/custom_response/tutorial004.py hl[7,21,23] *} In this example, the function `generate_html_response()` already generates and returns a `Response` instead of returning the HTML in a `str`. @@ -121,7 +113,7 @@ Here are some of the available responses. Keep in mind that you can use `Response` to return anything else, or even create a custom sub-class. -/// note | "Technical Details" +/// note | Technical Details You could also use `from starlette.responses import HTMLResponse`. @@ -144,9 +136,7 @@ It accepts the following parameters: FastAPI (actually Starlette) will automatically include a Content-Length header. It will also include a Content-Type header, based on the `media_type` and appending a charset for text types. -```Python hl_lines="1 18" -{!../../docs_src/response_directly/tutorial002.py!} -``` +{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *} ### `HTMLResponse` @@ -156,9 +146,7 @@ Takes some text or bytes and returns an HTML response, as you read above. Takes some text or bytes and returns a plain text response. -```Python hl_lines="2 7 9" -{!../../docs_src/custom_response/tutorial005.py!} -``` +{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *} ### `JSONResponse` @@ -192,9 +180,7 @@ This requires installing `ujson` for example with `pip install ujson`. /// -```Python hl_lines="2 7" -{!../../docs_src/custom_response/tutorial001.py!} -``` +{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *} /// tip @@ -208,18 +194,14 @@ Returns an HTTP redirect. Uses a 307 status code (Temporary Redirect) by default You can return a `RedirectResponse` directly: -```Python hl_lines="2 9" -{!../../docs_src/custom_response/tutorial006.py!} -``` +{* ../../docs_src/custom_response/tutorial006.py hl[2,9] *} --- Or you can use it in the `response_class` parameter: -```Python hl_lines="2 7 9" -{!../../docs_src/custom_response/tutorial006b.py!} -``` +{* ../../docs_src/custom_response/tutorial006b.py hl[2,7,9] *} If you do that, then you can return the URL directly from your *path operation* function. @@ -229,17 +211,13 @@ In this case, the `status_code` used will be the default one for the `RedirectRe You can also use the `status_code` parameter combined with the `response_class` parameter: -```Python hl_lines="2 7 9" -{!../../docs_src/custom_response/tutorial006c.py!} -``` +{* ../../docs_src/custom_response/tutorial006c.py hl[2,7,9] *} ### `StreamingResponse` Takes an async generator or a normal generator/iterator and streams the response body. -```Python hl_lines="2 14" -{!../../docs_src/custom_response/tutorial007.py!} -``` +{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *} #### Using `StreamingResponse` with file-like objects @@ -249,9 +227,7 @@ That way, you don't have to read it all first in memory, and you can pass that g This includes many libraries to interact with cloud storage, video processing, and others. -```{ .python .annotate hl_lines="2 10-12 14" } -{!../../docs_src/custom_response/tutorial008.py!} -``` +{* ../../docs_src/custom_response/tutorial008.py hl[2,10:12,14] *} 1. This is the generator function. It's a "generator function" because it contains `yield` statements inside. 2. By using a `with` block, we make sure that the file-like object is closed after the generator function is done. So, after it finishes sending the response. @@ -280,15 +256,11 @@ Takes a different set of arguments to instantiate than the other response types: File responses will include appropriate `Content-Length`, `Last-Modified` and `ETag` headers. -```Python hl_lines="2 10" -{!../../docs_src/custom_response/tutorial009.py!} -``` +{* ../../docs_src/custom_response/tutorial009.py hl[2,10] *} You can also use the `response_class` parameter: -```Python hl_lines="2 8 10" -{!../../docs_src/custom_response/tutorial009b.py!} -``` +{* ../../docs_src/custom_response/tutorial009b.py hl[2,8,10] *} In this case, you can return the file path directly from your *path operation* function. @@ -302,9 +274,7 @@ Let's say you want it to return indented and formatted JSON, so you want to use You could create a `CustomORJSONResponse`. The main thing you have to do is create a `Response.render(content)` method that returns the content as `bytes`: -```Python hl_lines="9-14 17" -{!../../docs_src/custom_response/tutorial009c.py!} -``` +{* ../../docs_src/custom_response/tutorial009c.py hl[9:14,17] *} Now instead of returning: @@ -330,9 +300,7 @@ The parameter that defines this is `default_response_class`. In the example below, **FastAPI** will use `ORJSONResponse` by default, in all *path operations*, instead of `JSONResponse`. -```Python hl_lines="2 4" -{!../../docs_src/custom_response/tutorial010.py!} -``` +{* ../../docs_src/custom_response/tutorial010.py hl[2,4] *} /// tip diff --git a/docs/en/docs/advanced/generate-clients.md b/docs/en/docs/advanced/generate-clients.md index 7872103c3..fe4194ac7 100644 --- a/docs/en/docs/advanced/generate-clients.md +++ b/docs/en/docs/advanced/generate-clients.md @@ -32,21 +32,7 @@ There are also several other companies offering similar services that you can se Let's start with a simple FastAPI application: -//// tab | Python 3.9+ - -```Python hl_lines="7-9 12-13 16-17 21" -{!> ../../docs_src/generate_clients/tutorial001_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9-11 14-15 18 19 23" -{!> ../../docs_src/generate_clients/tutorial001.py!} -``` - -//// +{* ../../docs_src/generate_clients/tutorial001_py39.py hl[7:9,12:13,16:17,21] *} Notice that the *path operations* define the models they use for request payload and response payload, using the models `Item` and `ResponseMessage`. @@ -151,21 +137,7 @@ In many cases your FastAPI app will be bigger, and you will probably use tags to For example, you could have a section for **items** and another section for **users**, and they could be separated by tags: -//// tab | Python 3.9+ - -```Python hl_lines="21 26 34" -{!> ../../docs_src/generate_clients/tutorial002_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="23 28 36" -{!> ../../docs_src/generate_clients/tutorial002.py!} -``` - -//// +{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *} ### Generate a TypeScript Client with Tags @@ -212,21 +184,7 @@ For example, here it is using the first tag (you will probably have only one tag You can then pass that custom function to **FastAPI** as the `generate_unique_id_function` parameter: -//// tab | Python 3.9+ - -```Python hl_lines="6-7 10" -{!> ../../docs_src/generate_clients/tutorial003_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="8-9 12" -{!> ../../docs_src/generate_clients/tutorial003.py!} -``` - -//// +{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *} ### Generate a TypeScript Client with Custom Operation IDs diff --git a/docs/en/docs/advanced/middleware.md b/docs/en/docs/advanced/middleware.md index 3faf3fbf9..1d40b1c8f 100644 --- a/docs/en/docs/advanced/middleware.md +++ b/docs/en/docs/advanced/middleware.md @@ -43,7 +43,7 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") **FastAPI** includes several middlewares for common use cases, we'll see next how to use them. -/// note | "Technical Details" +/// note | Technical Details For the next examples, you could also use `from starlette.middleware.something import SomethingMiddleware`. diff --git a/docs/en/docs/advanced/openapi-callbacks.md b/docs/en/docs/advanced/openapi-callbacks.md index 82069a950..ca9065a89 100644 --- a/docs/en/docs/advanced/openapi-callbacks.md +++ b/docs/en/docs/advanced/openapi-callbacks.md @@ -31,9 +31,7 @@ It will have a *path operation* that will receive an `Invoice` body, and a query This part is pretty normal, most of the code is probably already familiar to you: -```Python hl_lines="9-13 36-53" -{!../../docs_src/openapi_callbacks/tutorial001.py!} -``` +{* ../../docs_src/openapi_callbacks/tutorial001.py hl[9:13,36:53] *} /// tip @@ -92,9 +90,7 @@ Temporarily adopting this point of view (of the *external developer*) can help y First create a new `APIRouter` that will contain one or more callbacks. -```Python hl_lines="3 25" -{!../../docs_src/openapi_callbacks/tutorial001.py!} -``` +{* ../../docs_src/openapi_callbacks/tutorial001.py hl[3,25] *} ### Create the callback *path operation* @@ -105,9 +101,7 @@ It should look just like a normal FastAPI *path operation*: * It should probably have a declaration of the body it should receive, e.g. `body: InvoiceEvent`. * And it could also have a declaration of the response it should return, e.g. `response_model=InvoiceEventReceived`. -```Python hl_lines="16-18 21-22 28-32" -{!../../docs_src/openapi_callbacks/tutorial001.py!} -``` +{* ../../docs_src/openapi_callbacks/tutorial001.py hl[16:18,21:22,28:32] *} There are 2 main differences from a normal *path operation*: @@ -175,9 +169,7 @@ At this point you have the *callback path operation(s)* needed (the one(s) that Now use the parameter `callbacks` in *your API's path operation decorator* to pass the attribute `.routes` (that's actually just a `list` of routes/*path operations*) from that callback router: -```Python hl_lines="35" -{!../../docs_src/openapi_callbacks/tutorial001.py!} -``` +{* ../../docs_src/openapi_callbacks/tutorial001.py hl[35] *} /// tip diff --git a/docs/en/docs/advanced/path-operation-advanced-configuration.md b/docs/en/docs/advanced/path-operation-advanced-configuration.md index a61e3f19b..c4814ebd2 100644 --- a/docs/en/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/en/docs/advanced/path-operation-advanced-configuration.md @@ -12,9 +12,7 @@ You can set the OpenAPI `operationId` to be used in your *path operation* with t You would have to make sure that it is unique for each operation. -```Python hl_lines="6" -{!../../docs_src/path_operation_advanced_configuration/tutorial001.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *} ### Using the *path operation function* name as the operationId @@ -22,9 +20,7 @@ If you want to use your APIs' function names as `operationId`s, you can iterate You should do it after adding all your *path operations*. -```Python hl_lines="2 12-21 24" -{!../../docs_src/path_operation_advanced_configuration/tutorial002.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2, 12:21, 24] *} /// tip @@ -44,9 +40,7 @@ Even if they are in different modules (Python files). To exclude a *path operation* from the generated OpenAPI schema (and thus, from the automatic documentation systems), use the parameter `include_in_schema` and set it to `False`: -```Python hl_lines="6" -{!../../docs_src/path_operation_advanced_configuration/tutorial003.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *} ## Advanced description from docstring @@ -56,9 +50,7 @@ Adding an `\f` (an escaped "form feed" character) causes **FastAPI** to truncate It won't show up in the documentation, but other tools (such as Sphinx) will be able to use the rest. -```Python hl_lines="19-29" -{!../../docs_src/path_operation_advanced_configuration/tutorial004.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *} ## Additional Responses @@ -74,7 +66,7 @@ There's a whole chapter here in the documentation about it, you can read it at [ When you declare a *path operation* in your application, **FastAPI** automatically generates the relevant metadata about that *path operation* to be included in the OpenAPI schema. -/// note | "Technical details" +/// note | Technical details In the OpenAPI specification it is called the Operation Object. @@ -100,9 +92,7 @@ You can extend the OpenAPI schema for a *path operation* using the parameter `op This `openapi_extra` can be helpful, for example, to declare [OpenAPI Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions): -```Python hl_lines="6" -{!../../docs_src/path_operation_advanced_configuration/tutorial005.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial005.py hl[6] *} If you open the automatic API docs, your extension will show up at the bottom of the specific *path operation*. @@ -149,9 +139,7 @@ For example, you could decide to read and validate the request with your own cod You could do that with `openapi_extra`: -```Python hl_lines="19-36 39-40" -{!../../docs_src/path_operation_advanced_configuration/tutorial006.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial006.py hl[19:36, 39:40] *} In this example, we didn't declare any Pydantic model. In fact, the request body is not even parsed as JSON, it is read directly as `bytes`, and the function `magic_data_reader()` would be in charge of parsing it in some way. @@ -167,17 +155,13 @@ For example, in this application we don't use FastAPI's integrated functionality //// tab | Pydantic v2 -```Python hl_lines="17-22 24" -{!> ../../docs_src/path_operation_advanced_configuration/tutorial007.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[17:22, 24] *} //// //// tab | Pydantic v1 -```Python hl_lines="17-22 24" -{!> ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py hl[17:22, 24] *} //// @@ -195,17 +179,13 @@ And then in our code, we parse that YAML content directly, and then we are again //// tab | Pydantic v2 -```Python hl_lines="26-33" -{!> ../../docs_src/path_operation_advanced_configuration/tutorial007.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[26:33] *} //// //// tab | Pydantic v1 -```Python hl_lines="26-33" -{!> ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py hl[26:33] *} //// diff --git a/docs/en/docs/advanced/response-change-status-code.md b/docs/en/docs/advanced/response-change-status-code.md index fc041f7de..6d3f9f3e8 100644 --- a/docs/en/docs/advanced/response-change-status-code.md +++ b/docs/en/docs/advanced/response-change-status-code.md @@ -20,9 +20,7 @@ You can declare a parameter of type `Response` in your *path operation function* And then you can set the `status_code` in that *temporal* response object. -```Python hl_lines="1 9 12" -{!../../docs_src/response_change_status_code/tutorial001.py!} -``` +{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *} And then you can return any object you need, as you normally would (a `dict`, a database model, etc). diff --git a/docs/en/docs/advanced/response-cookies.md b/docs/en/docs/advanced/response-cookies.md index 4467779ba..f6d17f35d 100644 --- a/docs/en/docs/advanced/response-cookies.md +++ b/docs/en/docs/advanced/response-cookies.md @@ -6,9 +6,7 @@ You can declare a parameter of type `Response` in your *path operation function* And then you can set cookies in that *temporal* response object. -```Python hl_lines="1 8-9" -{!../../docs_src/response_cookies/tutorial002.py!} -``` +{* ../../docs_src/response_cookies/tutorial002.py hl[1, 8:9] *} And then you can return any object you need, as you normally would (a `dict`, a database model, etc). @@ -26,9 +24,7 @@ To do that, you can create a response as described in [Return a Response Directl Then set Cookies in it, and then return it: -```Python hl_lines="10-12" -{!../../docs_src/response_cookies/tutorial001.py!} -``` +{* ../../docs_src/response_cookies/tutorial001.py hl[10:12] *} /// tip @@ -42,7 +38,7 @@ And also that you are not sending any data that should have been filtered by a ` ### More info -/// note | "Technical Details" +/// note | Technical Details You could also use `from starlette.responses import Response` or `from starlette.responses import JSONResponse`. diff --git a/docs/en/docs/advanced/response-directly.md b/docs/en/docs/advanced/response-directly.md index 8246b9674..691b1e7cd 100644 --- a/docs/en/docs/advanced/response-directly.md +++ b/docs/en/docs/advanced/response-directly.md @@ -34,11 +34,9 @@ For example, you cannot put a Pydantic model in a `JSONResponse` without first c For those cases, you can use the `jsonable_encoder` to convert your data before passing it to a response: -```Python hl_lines="6-7 21-22" -{!../../docs_src/response_directly/tutorial001.py!} -``` +{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *} -/// note | "Technical Details" +/// note | Technical Details You could also use `from starlette.responses import JSONResponse`. @@ -56,9 +54,7 @@ Let's say that you want to return an ../../docs_src/dependency_testing/tutorial001_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="28-29 32" -{!> ../../docs_src/dependency_testing/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="29-30 33" -{!> ../../docs_src/dependency_testing/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="24-25 28" -{!> ../../docs_src/dependency_testing/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="28-29 32" -{!> ../../docs_src/dependency_testing/tutorial001.py!} -``` - -//// +{* ../../docs_src/dependency_testing/tutorial001_an_py310.py hl[26:27,30] *} /// tip diff --git a/docs/en/docs/advanced/testing-websockets.md b/docs/en/docs/advanced/testing-websockets.md index ab08c90fe..60dfdc343 100644 --- a/docs/en/docs/advanced/testing-websockets.md +++ b/docs/en/docs/advanced/testing-websockets.md @@ -4,9 +4,7 @@ You can use the same `TestClient` to test WebSockets. For this, you use the `TestClient` in a `with` statement, connecting to the WebSocket: -```Python hl_lines="27-31" -{!../../docs_src/app_testing/tutorial002.py!} -``` +{* ../../docs_src/app_testing/tutorial002.py hl[27:31] *} /// note diff --git a/docs/en/docs/advanced/using-request-directly.md b/docs/en/docs/advanced/using-request-directly.md index 917d77a95..2f88c8f20 100644 --- a/docs/en/docs/advanced/using-request-directly.md +++ b/docs/en/docs/advanced/using-request-directly.md @@ -29,9 +29,7 @@ Let's imagine you want to get the client's IP address/host inside of your *path For that you need to access the request directly. -```Python hl_lines="1 7-8" -{!../../docs_src/using_request_directly/tutorial001.py!} -``` +{* ../../docs_src/using_request_directly/tutorial001.py hl[1,7:8] *} By declaring a *path operation function* parameter with the type being the `Request` **FastAPI** will know to pass the `Request` in that parameter. @@ -49,7 +47,7 @@ The same way, you can declare any other parameter as normally, and additionally, You can read more details about the `Request` object in the official Starlette documentation site. -/// note | "Technical Details" +/// note | Technical Details You could also use `from starlette.requests import Request`. diff --git a/docs/en/docs/advanced/websockets.md b/docs/en/docs/advanced/websockets.md index 8947f32e7..ee8e901df 100644 --- a/docs/en/docs/advanced/websockets.md +++ b/docs/en/docs/advanced/websockets.md @@ -38,19 +38,15 @@ In production you would have one of the options above. But it's the simplest way to focus on the server-side of WebSockets and have a working example: -```Python hl_lines="2 6-38 41-43" -{!../../docs_src/websockets/tutorial001.py!} -``` +{* ../../docs_src/websockets/tutorial001.py hl[2,6:38,41:43] *} ## Create a `websocket` In your **FastAPI** application, create a `websocket`: -```Python hl_lines="1 46-47" -{!../../docs_src/websockets/tutorial001.py!} -``` +{* ../../docs_src/websockets/tutorial001.py hl[1,46:47] *} -/// note | "Technical Details" +/// note | Technical Details You could also use `from starlette.websockets import WebSocket`. @@ -62,9 +58,7 @@ You could also use `from starlette.websockets import WebSocket`. In your WebSocket route you can `await` for messages and send messages. -```Python hl_lines="48-52" -{!../../docs_src/websockets/tutorial001.py!} -``` +{* ../../docs_src/websockets/tutorial001.py hl[48:52] *} You can receive and send binary, text, and JSON data. @@ -115,57 +109,7 @@ In WebSocket endpoints you can import from `fastapi` and use: They work the same way as for other FastAPI endpoints/*path operations*: -//// tab | Python 3.10+ - -```Python hl_lines="68-69 82" -{!> ../../docs_src/websockets/tutorial002_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="68-69 82" -{!> ../../docs_src/websockets/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="69-70 83" -{!> ../../docs_src/websockets/tutorial002_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="66-67 79" -{!> ../../docs_src/websockets/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="68-69 81" -{!> ../../docs_src/websockets/tutorial002.py!} -``` - -//// +{* ../../docs_src/websockets/tutorial002_an_py310.py hl[68:69,82] *} /// info @@ -210,21 +154,7 @@ With that you can connect the WebSocket and then send and receive messages: When a WebSocket connection is closed, the `await websocket.receive_text()` will raise a `WebSocketDisconnect` exception, which you can then catch and handle like in this example. -//// tab | Python 3.9+ - -```Python hl_lines="79-81" -{!> ../../docs_src/websockets/tutorial003_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="81-83" -{!> ../../docs_src/websockets/tutorial003.py!} -``` - -//// +{* ../../docs_src/websockets/tutorial003_py39.py hl[79:81] *} To try it out: diff --git a/docs/en/docs/advanced/wsgi.md b/docs/en/docs/advanced/wsgi.md index 3974d491c..296eb1364 100644 --- a/docs/en/docs/advanced/wsgi.md +++ b/docs/en/docs/advanced/wsgi.md @@ -12,9 +12,7 @@ Then wrap the WSGI (e.g. Flask) app with the middleware. And then mount that under a path. -```Python hl_lines="2-3 23" -{!../../docs_src/wsgi/tutorial001.py!} -``` +{* ../../docs_src/wsgi/tutorial001.py hl[2:3,3] *} ## Check it diff --git a/docs/en/docs/alternatives.md b/docs/en/docs/alternatives.md index f596232d3..326f0dbe1 100644 --- a/docs/en/docs/alternatives.md +++ b/docs/en/docs/alternatives.md @@ -36,7 +36,7 @@ Django REST Framework was created by Tom Christie. The same creator of Starlette /// -/// check | "Inspired **FastAPI** to" +/// check | Inspired **FastAPI** to Have an automatic API documentation web user interface. @@ -56,7 +56,7 @@ This decoupling of parts, and being a "microframework" that could be extended to Given the simplicity of Flask, it seemed like a good match for building APIs. The next thing to find was a "Django REST Framework" for Flask. -/// check | "Inspired **FastAPI** to" +/// check | Inspired **FastAPI** to Be a micro-framework. Making it easy to mix and match the tools and parts needed. @@ -98,7 +98,7 @@ def read_url(): See the similarities in `requests.get(...)` and `@app.get(...)`. -/// check | "Inspired **FastAPI** to" +/// check | Inspired **FastAPI** to * Have a simple and intuitive API. * Use HTTP method names (operations) directly, in a straightforward and intuitive way. @@ -118,7 +118,7 @@ At some point, Swagger was given to the Linux Foundation, to be renamed OpenAPI. That's why when talking about version 2.0 it's common to say "Swagger", and for version 3+ "OpenAPI". -/// check | "Inspired **FastAPI** to" +/// check | Inspired **FastAPI** to Adopt and use an open standard for API specifications, instead of a custom schema. @@ -147,7 +147,7 @@ These features are what Marshmallow was built to provide. It is a great library, But it was created before there existed Python type hints. So, to define every schema you need to use specific utils and classes provided by Marshmallow. -/// check | "Inspired **FastAPI** to" +/// check | Inspired **FastAPI** to Use code to define "schemas" that provide data types and validation, automatically. @@ -169,7 +169,7 @@ Webargs was created by the same Marshmallow developers. /// -/// check | "Inspired **FastAPI** to" +/// check | Inspired **FastAPI** to Have automatic validation of incoming request data. @@ -199,7 +199,7 @@ APISpec was created by the same Marshmallow developers. /// -/// check | "Inspired **FastAPI** to" +/// check | Inspired **FastAPI** to Support the open standard for APIs, OpenAPI. @@ -231,7 +231,7 @@ Flask-apispec was created by the same Marshmallow developers. /// -/// check | "Inspired **FastAPI** to" +/// check | Inspired **FastAPI** to Generate the OpenAPI schema automatically, from the same code that defines serialization and validation. @@ -251,7 +251,7 @@ But as TypeScript data is not preserved after compilation to JavaScript, it cann It can't handle nested models very well. So, if the JSON body in the request is a JSON object that has inner fields that in turn are nested JSON objects, it cannot be properly documented and validated. -/// check | "Inspired **FastAPI** to" +/// check | Inspired **FastAPI** to Use Python types to have great editor support. @@ -263,7 +263,7 @@ Have a powerful dependency injection system. Find a way to minimize code repetit It was one of the first extremely fast Python frameworks based on `asyncio`. It was made to be very similar to Flask. -/// note | "Technical Details" +/// note | Technical Details It used `uvloop` instead of the default Python `asyncio` loop. That's what made it so fast. @@ -271,7 +271,7 @@ It clearly inspired Uvicorn and Starlette, that are currently faster than Sanic /// -/// check | "Inspired **FastAPI** to" +/// check | Inspired **FastAPI** to Find a way to have a crazy performance. @@ -287,7 +287,7 @@ It is designed to have functions that receive two parameters, one "request" and So, data validation, serialization, and documentation, have to be done in code, not automatically. Or they have to be implemented as a framework on top of Falcon, like Hug. This same distinction happens in other frameworks that are inspired by Falcon's design, of having one request object and one response object as parameters. -/// check | "Inspired **FastAPI** to" +/// check | Inspired **FastAPI** to Find ways to get great performance. @@ -313,7 +313,7 @@ The dependency injection system requires pre-registration of the dependencies an Routes are declared in a single place, using functions declared in other places (instead of using decorators that can be placed right on top of the function that handles the endpoint). This is closer to how Django does it than to how Flask (and Starlette) does it. It separates in the code things that are relatively tightly coupled. -/// check | "Inspired **FastAPI** to" +/// check | Inspired **FastAPI** to Define extra validations for data types using the "default" value of model attributes. This improves editor support, and it was not available in Pydantic before. @@ -341,7 +341,7 @@ Hug was created by Timothy Crosley, the same creator of ../../docs_src/body_multiple_params/tutorial001_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="18-20" -{!> ../../docs_src/body_multiple_params/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="19-21" -{!> ../../docs_src/body_multiple_params/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="17-19" -{!> ../../docs_src/body_multiple_params/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="19-21" -{!> ../../docs_src/body_multiple_params/tutorial001.py!} -``` - -//// +## Multiple body parameters /// note @@ -81,21 +33,8 @@ In the previous example, the *path operations* would expect a JSON body with the But you can also declare multiple body parameters, e.g. `item` and `user`: -//// tab | Python 3.10+ +{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *} -```Python hl_lines="20" -{!> ../../docs_src/body_multiple_params/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="22" -{!> ../../docs_src/body_multiple_params/tutorial002.py!} -``` - -//// In this case, **FastAPI** will notice that there is more than one body parameter in the function (there are two parameters that are Pydantic models). @@ -136,57 +75,8 @@ If you declare it as is, because it is a singular value, **FastAPI** will assume But you can instruct **FastAPI** to treat it as another body key using `Body`: -//// tab | Python 3.10+ +{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *} -```Python hl_lines="23" -{!> ../../docs_src/body_multiple_params/tutorial003_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="23" -{!> ../../docs_src/body_multiple_params/tutorial003_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="24" -{!> ../../docs_src/body_multiple_params/tutorial003_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="20" -{!> ../../docs_src/body_multiple_params/tutorial003_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="22" -{!> ../../docs_src/body_multiple_params/tutorial003.py!} -``` - -//// In this case, **FastAPI** will expect a body like: @@ -226,57 +116,8 @@ q: str | None = None For example: -//// tab | Python 3.10+ +{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *} -```Python hl_lines="28" -{!> ../../docs_src/body_multiple_params/tutorial004_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="28" -{!> ../../docs_src/body_multiple_params/tutorial004_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="29" -{!> ../../docs_src/body_multiple_params/tutorial004_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="26" -{!> ../../docs_src/body_multiple_params/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="28" -{!> ../../docs_src/body_multiple_params/tutorial004.py!} -``` - -//// /// info @@ -298,57 +139,8 @@ item: Item = Body(embed=True) as in: -//// tab | Python 3.10+ +{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *} -```Python hl_lines="17" -{!> ../../docs_src/body_multiple_params/tutorial005_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="17" -{!> ../../docs_src/body_multiple_params/tutorial005_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="18" -{!> ../../docs_src/body_multiple_params/tutorial005_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="15" -{!> ../../docs_src/body_multiple_params/tutorial005_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="17" -{!> ../../docs_src/body_multiple_params/tutorial005.py!} -``` - -//// In this case **FastAPI** will expect a body like: diff --git a/docs/en/docs/tutorial/body-nested-models.md b/docs/en/docs/tutorial/body-nested-models.md index 38f3eb136..b473062de 100644 --- a/docs/en/docs/tutorial/body-nested-models.md +++ b/docs/en/docs/tutorial/body-nested-models.md @@ -6,21 +6,7 @@ With **FastAPI**, you can define, validate, document, and use arbitrarily deeply You can define an attribute to be a subtype. For example, a Python `list`: -//// tab | Python 3.10+ - -```Python hl_lines="12" -{!> ../../docs_src/body_nested_models/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="14" -{!> ../../docs_src/body_nested_models/tutorial001.py!} -``` - -//// +{* ../../docs_src/body_nested_models/tutorial001_py310.py hl[12] *} This will make `tags` be a list, although it doesn't declare the type of the elements of the list. @@ -34,9 +20,7 @@ In Python 3.9 and above you can use the standard `list` to declare these type an But in Python versions before 3.9 (3.6 and above), you first need to import `List` from standard Python's `typing` module: -```Python hl_lines="1" -{!> ../../docs_src/body_nested_models/tutorial002.py!} -``` +{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *} ### Declare a `list` with a type parameter @@ -65,29 +49,7 @@ Use that same standard syntax for model attributes with internal types. So, in our example, we can make `tags` be specifically a "list of strings": -//// tab | Python 3.10+ - -```Python hl_lines="12" -{!> ../../docs_src/body_nested_models/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="14" -{!> ../../docs_src/body_nested_models/tutorial002_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="14" -{!> ../../docs_src/body_nested_models/tutorial002.py!} -``` - -//// +{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *} ## Set types @@ -97,29 +59,7 @@ And Python has a special data type for sets of unique items, the `set`. Then we can declare `tags` as a set of strings: -//// tab | Python 3.10+ - -```Python hl_lines="12" -{!> ../../docs_src/body_nested_models/tutorial003_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="14" -{!> ../../docs_src/body_nested_models/tutorial003_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="1 14" -{!> ../../docs_src/body_nested_models/tutorial003.py!} -``` - -//// +{* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *} With this, even if you receive a request with duplicate data, it will be converted to a set of unique items. @@ -141,57 +81,13 @@ All that, arbitrarily nested. For example, we can define an `Image` model: -//// tab | Python 3.10+ - -```Python hl_lines="7-9" -{!> ../../docs_src/body_nested_models/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="9-11" -{!> ../../docs_src/body_nested_models/tutorial004_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9-11" -{!> ../../docs_src/body_nested_models/tutorial004.py!} -``` - -//// +{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *} ### Use the submodel as a type And then we can use it as the type of an attribute: -//// tab | Python 3.10+ - -```Python hl_lines="18" -{!> ../../docs_src/body_nested_models/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="20" -{!> ../../docs_src/body_nested_models/tutorial004_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="20" -{!> ../../docs_src/body_nested_models/tutorial004.py!} -``` - -//// +{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[18] *} This would mean that **FastAPI** would expect a body similar to: @@ -224,29 +120,7 @@ To see all the options you have, checkout ../../docs_src/body_nested_models/tutorial005_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="4 10" -{!> ../../docs_src/body_nested_models/tutorial005_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="4 10" -{!> ../../docs_src/body_nested_models/tutorial005.py!} -``` - -//// +{* ../../docs_src/body_nested_models/tutorial005_py310.py hl[2,8] *} The string will be checked to be a valid URL, and documented in JSON Schema / OpenAPI as such. @@ -254,29 +128,7 @@ The string will be checked to be a valid URL, and documented in JSON Schema / Op You can also use Pydantic models as subtypes of `list`, `set`, etc.: -//// tab | Python 3.10+ - -```Python hl_lines="18" -{!> ../../docs_src/body_nested_models/tutorial006_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="20" -{!> ../../docs_src/body_nested_models/tutorial006_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="20" -{!> ../../docs_src/body_nested_models/tutorial006.py!} -``` - -//// +{* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *} This will expect (convert, validate, document, etc.) a JSON body like: @@ -314,29 +166,7 @@ Notice how the `images` key now has a list of image objects. You can define arbitrarily deeply nested models: -//// tab | Python 3.10+ - -```Python hl_lines="7 12 18 21 25" -{!> ../../docs_src/body_nested_models/tutorial007_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="9 14 20 23 27" -{!> ../../docs_src/body_nested_models/tutorial007_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9 14 20 23 27" -{!> ../../docs_src/body_nested_models/tutorial007.py!} -``` - -//// +{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *} /// info @@ -360,21 +190,7 @@ images: list[Image] as in: -//// tab | Python 3.9+ - -```Python hl_lines="13" -{!> ../../docs_src/body_nested_models/tutorial008_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="15" -{!> ../../docs_src/body_nested_models/tutorial008.py!} -``` - -//// +{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *} ## Editor support everywhere @@ -404,21 +220,7 @@ That's what we are going to see here. In this case, you would accept any `dict` as long as it has `int` keys with `float` values: -//// tab | Python 3.9+ - -```Python hl_lines="7" -{!> ../../docs_src/body_nested_models/tutorial009_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9" -{!> ../../docs_src/body_nested_models/tutorial009.py!} -``` - -//// +{* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *} /// tip diff --git a/docs/en/docs/tutorial/body-updates.md b/docs/en/docs/tutorial/body-updates.md index 3ac2e3914..df5b960db 100644 --- a/docs/en/docs/tutorial/body-updates.md +++ b/docs/en/docs/tutorial/body-updates.md @@ -6,29 +6,7 @@ To update an item you can use the ../../docs_src/body_updates/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="30-35" -{!> ../../docs_src/body_updates/tutorial001_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="30-35" -{!> ../../docs_src/body_updates/tutorial001.py!} -``` - -//// +{* ../../docs_src/body_updates/tutorial001_py310.py hl[28:33] *} `PUT` is used to receive data that should replace the existing data. @@ -84,29 +62,7 @@ That would generate a `dict` with only the data that was set when creating the ` Then you can use this to generate a `dict` with only the data that was set (sent in the request), omitting default values: -//// tab | Python 3.10+ - -```Python hl_lines="32" -{!> ../../docs_src/body_updates/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="34" -{!> ../../docs_src/body_updates/tutorial002_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="34" -{!> ../../docs_src/body_updates/tutorial002.py!} -``` - -//// +{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *} ### Using Pydantic's `update` parameter @@ -122,29 +78,7 @@ The examples here use `.copy()` for compatibility with Pydantic v1, but you shou Like `stored_item_model.model_copy(update=update_data)`: -//// tab | Python 3.10+ - -```Python hl_lines="33" -{!> ../../docs_src/body_updates/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="35" -{!> ../../docs_src/body_updates/tutorial002_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="35" -{!> ../../docs_src/body_updates/tutorial002.py!} -``` - -//// +{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *} ### Partial updates recap @@ -161,29 +95,7 @@ In summary, to apply partial updates you would: * Save the data to your DB. * Return the updated model. -//// tab | Python 3.10+ - -```Python hl_lines="28-35" -{!> ../../docs_src/body_updates/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="30-37" -{!> ../../docs_src/body_updates/tutorial002_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="30-37" -{!> ../../docs_src/body_updates/tutorial002.py!} -``` - -//// +{* ../../docs_src/body_updates/tutorial002_py310.py hl[28:35] *} /// tip diff --git a/docs/en/docs/tutorial/body.md b/docs/en/docs/tutorial/body.md index 9c97f64cb..aba5593a5 100644 --- a/docs/en/docs/tutorial/body.md +++ b/docs/en/docs/tutorial/body.md @@ -126,7 +126,7 @@ It improves editor support for Pydantic models, with: Inside of the function, you can access all the attributes of the model object directly: -{!> ../../docs_src/body/tutorial002_py310.py!} +{* ../../docs_src/body/tutorial002_py310.py *} ## Request body + path parameters diff --git a/docs/en/docs/tutorial/cookie-param-models.md b/docs/en/docs/tutorial/cookie-param-models.md index 62cafbb23..55a812852 100644 --- a/docs/en/docs/tutorial/cookie-param-models.md +++ b/docs/en/docs/tutorial/cookie-param-models.md @@ -20,57 +20,7 @@ This same technique applies to `Query`, `Cookie`, and `Header`. 😎 Declare the **cookie** parameters that you need in a **Pydantic model**, and then declare the parameter as `Cookie`: -//// tab | Python 3.10+ - -```Python hl_lines="9-12 16" -{!> ../../docs_src/cookie_param_models/tutorial001_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="9-12 16" -{!> ../../docs_src/cookie_param_models/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="10-13 17" -{!> ../../docs_src/cookie_param_models/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="7-10 14" -{!> ../../docs_src/cookie_param_models/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="9-12 16" -{!> ../../docs_src/cookie_param_models/tutorial001.py!} -``` - -//// +{* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *} **FastAPI** will **extract** the data for **each field** from the **cookies** received in the request and give you the Pydantic model you defined. @@ -100,35 +50,7 @@ Your API now has the power to control its own ../../docs_src/cookie_param_models/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="11" -{!> ../../docs_src/cookie_param_models/tutorial002_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="10" -{!> ../../docs_src/cookie_param_models/tutorial002.py!} -``` - -//// +{* ../../docs_src/cookie_param_models/tutorial002_an_py39.py hl[10] *} If a client tries to send some **extra cookies**, they will receive an **error** response. diff --git a/docs/en/docs/tutorial/cookie-params.md b/docs/en/docs/tutorial/cookie-params.md index 8804f854f..5341406d5 100644 --- a/docs/en/docs/tutorial/cookie-params.md +++ b/docs/en/docs/tutorial/cookie-params.md @@ -6,57 +6,7 @@ You can define Cookie parameters the same way you define `Query` and `Path` para First import `Cookie`: -//// tab | Python 3.10+ - -```Python hl_lines="3" -{!> ../../docs_src/cookie_params/tutorial001_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="3" -{!> ../../docs_src/cookie_params/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="3" -{!> ../../docs_src/cookie_params/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="1" -{!> ../../docs_src/cookie_params/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="3" -{!> ../../docs_src/cookie_params/tutorial001.py!} -``` - -//// +{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[3] *} ## Declare `Cookie` parameters @@ -64,59 +14,9 @@ Then declare the cookie parameters using the same structure as with `Path` and ` You can define the default value as well as all the extra validation or annotation parameters: -//// tab | Python 3.10+ +{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[9] *} -```Python hl_lines="9" -{!> ../../docs_src/cookie_params/tutorial001_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="9" -{!> ../../docs_src/cookie_params/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="10" -{!> ../../docs_src/cookie_params/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="7" -{!> ../../docs_src/cookie_params/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="9" -{!> ../../docs_src/cookie_params/tutorial001.py!} -``` - -//// - -/// note | "Technical Details" +/// note | Technical Details `Cookie` is a "sister" class of `Path` and `Query`. It also inherits from the same common `Param` class. diff --git a/docs/en/docs/tutorial/cors.md b/docs/en/docs/tutorial/cors.md index 8dfc9bad9..cf31cfcf5 100644 --- a/docs/en/docs/tutorial/cors.md +++ b/docs/en/docs/tutorial/cors.md @@ -46,9 +46,8 @@ You can also specify whether your backend allows: * Specific HTTP methods (`POST`, `PUT`) or all of them with the wildcard `"*"`. * Specific HTTP headers or all of them with the wildcard `"*"`. -```Python hl_lines="2 6-11 13-19" -{!../../docs_src/cors/tutorial001.py!} -``` +{* ../../docs_src/cors/tutorial001.py hl[2,6:11,13:19] *} + The default parameters used by the `CORSMiddleware` implementation are restrictive by default, so you'll need to explicitly enable particular origins, methods, or headers, in order for browsers to be permitted to use them in a Cross-Domain context. @@ -78,7 +77,7 @@ Any request with an `Origin` header. In this case the middleware will pass the r For more info about CORS, check the Mozilla CORS documentation. -/// note | "Technical Details" +/// note | Technical Details You could also use `from starlette.middleware.cors import CORSMiddleware`. diff --git a/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md index defd61a0d..9c7bb1fd3 100644 --- a/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md +++ b/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md @@ -6,57 +6,7 @@ Before diving deeper into the **Dependency Injection** system, let's upgrade the In the previous example, we were returning a `dict` from our dependency ("dependable"): -//// tab | Python 3.10+ - -```Python hl_lines="9" -{!> ../../docs_src/dependencies/tutorial001_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="11" -{!> ../../docs_src/dependencies/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="12" -{!> ../../docs_src/dependencies/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="7" -{!> ../../docs_src/dependencies/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="11" -{!> ../../docs_src/dependencies/tutorial001.py!} -``` - -//// +{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[9] *} But then we get a `dict` in the parameter `commons` of the *path operation function*. @@ -119,165 +69,15 @@ That also applies to callables with no parameters at all. The same as it would b Then, we can change the dependency "dependable" `common_parameters` from above to the class `CommonQueryParams`: -//// tab | Python 3.10+ - -```Python hl_lines="11-15" -{!> ../../docs_src/dependencies/tutorial002_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="11-15" -{!> ../../docs_src/dependencies/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="12-16" -{!> ../../docs_src/dependencies/tutorial002_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="9-13" -{!> ../../docs_src/dependencies/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="11-15" -{!> ../../docs_src/dependencies/tutorial002.py!} -``` - -//// +{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[11:15] *} Pay attention to the `__init__` method used to create the instance of the class: -//// tab | Python 3.10+ - -```Python hl_lines="12" -{!> ../../docs_src/dependencies/tutorial002_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="12" -{!> ../../docs_src/dependencies/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="13" -{!> ../../docs_src/dependencies/tutorial002_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="10" -{!> ../../docs_src/dependencies/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="12" -{!> ../../docs_src/dependencies/tutorial002.py!} -``` - -//// +{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[12] *} ...it has the same parameters as our previous `common_parameters`: -//// tab | Python 3.10+ - -```Python hl_lines="8" -{!> ../../docs_src/dependencies/tutorial001_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="9" -{!> ../../docs_src/dependencies/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="10" -{!> ../../docs_src/dependencies/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="6" -{!> ../../docs_src/dependencies/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="9" -{!> ../../docs_src/dependencies/tutorial001.py!} -``` - -//// +{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[8] *} Those parameters are what **FastAPI** will use to "solve" the dependency. @@ -293,57 +93,7 @@ In both cases the data will be converted, validated, documented on the OpenAPI s Now you can declare your dependency using this class. -//// tab | Python 3.10+ - -```Python hl_lines="19" -{!> ../../docs_src/dependencies/tutorial002_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="19" -{!> ../../docs_src/dependencies/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="20" -{!> ../../docs_src/dependencies/tutorial002_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="17" -{!> ../../docs_src/dependencies/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="19" -{!> ../../docs_src/dependencies/tutorial002.py!} -``` - -//// +{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[19] *} **FastAPI** calls the `CommonQueryParams` class. This creates an "instance" of that class and the instance will be passed as the parameter `commons` to your function. @@ -437,57 +187,7 @@ commons = Depends(CommonQueryParams) ...as in: -//// tab | Python 3.10+ - -```Python hl_lines="19" -{!> ../../docs_src/dependencies/tutorial003_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="19" -{!> ../../docs_src/dependencies/tutorial003_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="20" -{!> ../../docs_src/dependencies/tutorial003_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="17" -{!> ../../docs_src/dependencies/tutorial003_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="19" -{!> ../../docs_src/dependencies/tutorial003.py!} -``` - -//// +{* ../../docs_src/dependencies/tutorial003_an_py310.py hl[19] *} But declaring the type is encouraged as that way your editor will know what will be passed as the parameter `commons`, and then it can help you with code completion, type checks, etc: @@ -575,57 +275,7 @@ You declare the dependency as the type of the parameter, and you use `Depends()` The same example would then look like: -//// tab | Python 3.10+ - -```Python hl_lines="19" -{!> ../../docs_src/dependencies/tutorial004_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="19" -{!> ../../docs_src/dependencies/tutorial004_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="20" -{!> ../../docs_src/dependencies/tutorial004_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="17" -{!> ../../docs_src/dependencies/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="19" -{!> ../../docs_src/dependencies/tutorial004.py!} -``` - -//// +{* ../../docs_src/dependencies/tutorial004_an_py310.py hl[19] *} ...and **FastAPI** will know what to do. diff --git a/docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md index e89d520be..88ad99403 100644 --- a/docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md +++ b/docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md @@ -14,35 +14,7 @@ The *path operation decorator* receives an optional argument `dependencies`. It should be a `list` of `Depends()`: -//// tab | Python 3.9+ - -```Python hl_lines="19" -{!> ../../docs_src/dependencies/tutorial006_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="18" -{!> ../../docs_src/dependencies/tutorial006_an.py!} -``` - -//// - -//// tab | Python 3.8 non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="17" -{!> ../../docs_src/dependencies/tutorial006.py!} -``` - -//// +{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[19] *} These dependencies will be executed/solved the same way as normal dependencies. But their value (if they return any) won't be passed to your *path operation function*. @@ -72,69 +44,13 @@ You can use the same dependency *functions* you use normally. They can declare request requirements (like headers) or other sub-dependencies: -//// tab | Python 3.9+ - -```Python hl_lines="8 13" -{!> ../../docs_src/dependencies/tutorial006_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="7 12" -{!> ../../docs_src/dependencies/tutorial006_an.py!} -``` - -//// - -//// tab | Python 3.8 non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="6 11" -{!> ../../docs_src/dependencies/tutorial006.py!} -``` - -//// +{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[8,13] *} ### Raise exceptions These dependencies can `raise` exceptions, the same as normal dependencies: -//// tab | Python 3.9+ - -```Python hl_lines="10 15" -{!> ../../docs_src/dependencies/tutorial006_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9 14" -{!> ../../docs_src/dependencies/tutorial006_an.py!} -``` - -//// - -//// tab | Python 3.8 non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="8 13" -{!> ../../docs_src/dependencies/tutorial006.py!} -``` - -//// +{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[10,15] *} ### Return values @@ -142,35 +58,7 @@ And they can return values or not, the values won't be used. So, you can reuse a normal dependency (that returns a value) you already use somewhere else, and even though the value won't be used, the dependency will be executed: -//// tab | Python 3.9+ - -```Python hl_lines="11 16" -{!> ../../docs_src/dependencies/tutorial006_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="10 15" -{!> ../../docs_src/dependencies/tutorial006_an.py!} -``` - -//// - -//// tab | Python 3.8 non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="9 14" -{!> ../../docs_src/dependencies/tutorial006.py!} -``` - -//// +{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[11,16] *} ## Dependencies for a group of *path operations* diff --git a/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md index 97da668aa..70b5945a4 100644 --- a/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md +++ b/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md @@ -10,7 +10,7 @@ Make sure to use `yield` one single time per dependency. /// -/// note | "Technical Details" +/// note | Technical Details Any function that is valid to use with: @@ -39,7 +39,7 @@ The yielded value is what is injected into *path operations* and other dependenc {!../../docs_src/dependencies/tutorial007.py!} ``` -The code following the `yield` statement is executed after the response has been delivered: +The code following the `yield` statement is executed after creating the response but before sending it: ```Python hl_lines="5-6" {!../../docs_src/dependencies/tutorial007.py!} @@ -149,7 +149,7 @@ You can have any combinations of dependencies that you want. **FastAPI** will make sure everything is run in the correct order. -/// note | "Technical Details" +/// note | Technical Details This works thanks to Python's Context Managers. diff --git a/docs/en/docs/tutorial/dependencies/global-dependencies.md b/docs/en/docs/tutorial/dependencies/global-dependencies.md index 21a8cb6be..e4696ee14 100644 --- a/docs/en/docs/tutorial/dependencies/global-dependencies.md +++ b/docs/en/docs/tutorial/dependencies/global-dependencies.md @@ -6,35 +6,8 @@ Similar to the way you can [add `dependencies` to the *path operation decorators In that case, they will be applied to all the *path operations* in the application: -//// tab | Python 3.9+ +{* ../../docs_src/dependencies/tutorial012_an_py39.py hl[16] *} -```Python hl_lines="16" -{!> ../../docs_src/dependencies/tutorial012_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="16" -{!> ../../docs_src/dependencies/tutorial012_an.py!} -``` - -//// - -//// tab | Python 3.8 non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="15" -{!> ../../docs_src/dependencies/tutorial012.py!} -``` - -//// And all the ideas in the section about [adding `dependencies` to the *path operation decorators*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} still apply, but in this case, to all of the *path operations* in the app. diff --git a/docs/en/docs/tutorial/dependencies/sub-dependencies.md b/docs/en/docs/tutorial/dependencies/sub-dependencies.md index 2b098d159..1f8ba420a 100644 --- a/docs/en/docs/tutorial/dependencies/sub-dependencies.md +++ b/docs/en/docs/tutorial/dependencies/sub-dependencies.md @@ -10,57 +10,7 @@ They can be as **deep** as you need them to be. You could create a first dependency ("dependable") like: -//// tab | Python 3.10+ - -```Python hl_lines="8-9" -{!> ../../docs_src/dependencies/tutorial005_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="8-9" -{!> ../../docs_src/dependencies/tutorial005_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9-10" -{!> ../../docs_src/dependencies/tutorial005_an.py!} -``` - -//// - -//// tab | Python 3.10 non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="6-7" -{!> ../../docs_src/dependencies/tutorial005_py310.py!} -``` - -//// - -//// tab | Python 3.8 non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="8-9" -{!> ../../docs_src/dependencies/tutorial005.py!} -``` - -//// +{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[8:9] *} It declares an optional query parameter `q` as a `str`, and then it just returns it. @@ -70,57 +20,7 @@ This is quite simple (not very useful), but will help us focus on how the sub-de Then you can create another dependency function (a "dependable") that at the same time declares a dependency of its own (so it is a "dependant" too): -//// tab | Python 3.10+ - -```Python hl_lines="13" -{!> ../../docs_src/dependencies/tutorial005_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="13" -{!> ../../docs_src/dependencies/tutorial005_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="14" -{!> ../../docs_src/dependencies/tutorial005_an.py!} -``` - -//// - -//// tab | Python 3.10 non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="11" -{!> ../../docs_src/dependencies/tutorial005_py310.py!} -``` - -//// - -//// tab | Python 3.8 non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="13" -{!> ../../docs_src/dependencies/tutorial005.py!} -``` - -//// +{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[13] *} Let's focus on the parameters declared: @@ -133,57 +33,7 @@ Let's focus on the parameters declared: Then we can use the dependency with: -//// tab | Python 3.10+ - -```Python hl_lines="23" -{!> ../../docs_src/dependencies/tutorial005_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="23" -{!> ../../docs_src/dependencies/tutorial005_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="24" -{!> ../../docs_src/dependencies/tutorial005_an.py!} -``` - -//// - -//// tab | Python 3.10 non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="19" -{!> ../../docs_src/dependencies/tutorial005_py310.py!} -``` - -//// - -//// tab | Python 3.8 non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="22" -{!> ../../docs_src/dependencies/tutorial005.py!} -``` - -//// +{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[23] *} /// info diff --git a/docs/en/docs/tutorial/extra-models.md b/docs/en/docs/tutorial/extra-models.md index 4e6f69f31..5fac3f69e 100644 --- a/docs/en/docs/tutorial/extra-models.md +++ b/docs/en/docs/tutorial/extra-models.md @@ -20,21 +20,8 @@ If you don't know, you will learn what a "password hash" is in the [security cha Here's a general idea of how the models could look like with their password fields and the places where they are used: -//// tab | Python 3.10+ +{* ../../docs_src/extra_models/tutorial001_py310.py hl[7,9,14,20,22,27:28,31:33,38:39] *} -```Python hl_lines="7 9 14 20 22 27-28 31-33 38-39" -{!> ../../docs_src/extra_models/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9 11 16 22 24 29-30 33-35 40-41" -{!> ../../docs_src/extra_models/tutorial001.py!} -``` - -//// /// info @@ -176,21 +163,7 @@ All the data conversion, validation, documentation, etc. will still work as norm That way, we can declare just the differences between the models (with plaintext `password`, with `hashed_password` and without password): -//// tab | Python 3.10+ - -```Python hl_lines="7 13-14 17-18 21-22" -{!> ../../docs_src/extra_models/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9 15-16 19-20 23-24" -{!> ../../docs_src/extra_models/tutorial002.py!} -``` - -//// +{* ../../docs_src/extra_models/tutorial002_py310.py hl[7,13:14,17:18,21:22] *} ## `Union` or `anyOf` @@ -206,21 +179,8 @@ When defining a ../../docs_src/extra_models/tutorial003_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="1 14-15 18-20 33" -{!> ../../docs_src/extra_models/tutorial003.py!} -``` - -//// ### `Union` in Python 3.10 @@ -242,21 +202,8 @@ The same way, you can declare responses of lists of objects. For that, use the standard Python `typing.List` (or just `list` in Python 3.9 and above): -//// tab | Python 3.9+ +{* ../../docs_src/extra_models/tutorial004_py39.py hl[18] *} -```Python hl_lines="18" -{!> ../../docs_src/extra_models/tutorial004_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="1 20" -{!> ../../docs_src/extra_models/tutorial004.py!} -``` - -//// ## Response with arbitrary `dict` @@ -266,21 +213,8 @@ This is useful if you don't know the valid field/attribute names (that would be In this case, you can use `typing.Dict` (or just `dict` in Python 3.9 and above): -//// tab | Python 3.9+ +{* ../../docs_src/extra_models/tutorial005_py39.py hl[6] *} -```Python hl_lines="6" -{!> ../../docs_src/extra_models/tutorial005_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="1 8" -{!> ../../docs_src/extra_models/tutorial005.py!} -``` - -//// ## Recap diff --git a/docs/en/docs/tutorial/first-steps.md b/docs/en/docs/tutorial/first-steps.md index 1c20b945a..783295933 100644 --- a/docs/en/docs/tutorial/first-steps.md +++ b/docs/en/docs/tutorial/first-steps.md @@ -159,7 +159,7 @@ You could also use it to generate code automatically, for clients that communica `FastAPI` is a Python class that provides all the functionality for your API. -/// note | "Technical Details" +/// note | Technical Details `FastAPI` is a class that inherits directly from `Starlette`. @@ -245,7 +245,7 @@ The `@app.get("/")` tells **FastAPI** that the function right below is in charge * the path `/` * using a get operation -/// info | "`@decorator` Info" +/// info | `@decorator` Info That `@something` syntax in Python is called a "decorator". diff --git a/docs/en/docs/tutorial/handling-errors.md b/docs/en/docs/tutorial/handling-errors.md index 38c15761b..537cb3e72 100644 --- a/docs/en/docs/tutorial/handling-errors.md +++ b/docs/en/docs/tutorial/handling-errors.md @@ -109,7 +109,7 @@ So, you will receive a clean error, with an HTTP status code of `418` and a JSON {"message": "Oops! yolo did something. There goes a rainbow..."} ``` -/// note | "Technical Details" +/// note | Technical Details You could also use `from starlette.requests import Request` and `from starlette.responses import JSONResponse`. @@ -192,7 +192,7 @@ For example, you could want to return a plain text response instead of JSON for {!../../docs_src/handling_errors/tutorial004.py!} ``` -/// note | "Technical Details" +/// note | Technical Details You could also use `from starlette.responses import PlainTextResponse`. diff --git a/docs/en/docs/tutorial/header-param-models.md b/docs/en/docs/tutorial/header-param-models.md index 78517e498..73950a668 100644 --- a/docs/en/docs/tutorial/header-param-models.md +++ b/docs/en/docs/tutorial/header-param-models.md @@ -14,71 +14,7 @@ This is supported since FastAPI version `0.115.0`. 🤓 Declare the **header parameters** that you need in a **Pydantic model**, and then declare the parameter as `Header`: -//// tab | Python 3.10+ - -```Python hl_lines="9-14 18" -{!> ../../docs_src/header_param_models/tutorial001_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="9-14 18" -{!> ../../docs_src/header_param_models/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="10-15 19" -{!> ../../docs_src/header_param_models/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="7-12 16" -{!> ../../docs_src/header_param_models/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.9+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="9-14 18" -{!> ../../docs_src/header_param_models/tutorial001_py39.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="7-12 16" -{!> ../../docs_src/header_param_models/tutorial001_py310.py!} -``` - -//// +{* ../../docs_src/header_param_models/tutorial001_an_py310.py hl[9:14,18] *} **FastAPI** will **extract** the data for **each field** from the **headers** in the request and give you the Pydantic model you defined. @@ -96,71 +32,7 @@ In some special use cases (probably not very common), you might want to **restri You can use Pydantic's model configuration to `forbid` any `extra` fields: -//// tab | Python 3.10+ - -```Python hl_lines="10" -{!> ../../docs_src/header_param_models/tutorial002_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="10" -{!> ../../docs_src/header_param_models/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="11" -{!> ../../docs_src/header_param_models/tutorial002_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="8" -{!> ../../docs_src/header_param_models/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.9+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="10" -{!> ../../docs_src/header_param_models/tutorial002_py39.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="10" -{!> ../../docs_src/header_param_models/tutorial002.py!} -``` - -//// +{* ../../docs_src/header_param_models/tutorial002_an_py310.py hl[10] *} If a client tries to send some **extra headers**, they will receive an **error** response. diff --git a/docs/en/docs/tutorial/header-params.md b/docs/en/docs/tutorial/header-params.md index 293de897f..49ad7aa25 100644 --- a/docs/en/docs/tutorial/header-params.md +++ b/docs/en/docs/tutorial/header-params.md @@ -6,57 +6,7 @@ You can define Header parameters the same way you define `Query`, `Path` and `Co First import `Header`: -//// tab | Python 3.10+ - -```Python hl_lines="3" -{!> ../../docs_src/header_params/tutorial001_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="3" -{!> ../../docs_src/header_params/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="3" -{!> ../../docs_src/header_params/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="1" -{!> ../../docs_src/header_params/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="3" -{!> ../../docs_src/header_params/tutorial001.py!} -``` - -//// +{* ../../docs_src/header_params/tutorial001_an_py310.py hl[3] *} ## Declare `Header` parameters @@ -64,59 +14,9 @@ Then declare the header parameters using the same structure as with `Path`, `Que You can define the default value as well as all the extra validation or annotation parameters: -//// tab | Python 3.10+ +{* ../../docs_src/header_params/tutorial001_an_py310.py hl[9] *} -```Python hl_lines="9" -{!> ../../docs_src/header_params/tutorial001_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="9" -{!> ../../docs_src/header_params/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="10" -{!> ../../docs_src/header_params/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="7" -{!> ../../docs_src/header_params/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="9" -{!> ../../docs_src/header_params/tutorial001.py!} -``` - -//// - -/// note | "Technical Details" +/// note | Technical Details `Header` is a "sister" class of `Path`, `Query` and `Cookie`. It also inherits from the same common `Param` class. @@ -146,57 +46,7 @@ So, you can use `user_agent` as you normally would in Python code, instead of ne If for some reason you need to disable automatic conversion of underscores to hyphens, set the parameter `convert_underscores` of `Header` to `False`: -//// tab | Python 3.10+ - -```Python hl_lines="10" -{!> ../../docs_src/header_params/tutorial002_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="11" -{!> ../../docs_src/header_params/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="12" -{!> ../../docs_src/header_params/tutorial002_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="8" -{!> ../../docs_src/header_params/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="10" -{!> ../../docs_src/header_params/tutorial002.py!} -``` - -//// +{* ../../docs_src/header_params/tutorial002_an_py310.py hl[10] *} /// warning @@ -214,71 +64,7 @@ You will receive all the values from the duplicate header as a Python `list`. For example, to declare a header of `X-Token` that can appear more than once, you can write: -//// tab | Python 3.10+ - -```Python hl_lines="9" -{!> ../../docs_src/header_params/tutorial003_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="9" -{!> ../../docs_src/header_params/tutorial003_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="10" -{!> ../../docs_src/header_params/tutorial003_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="7" -{!> ../../docs_src/header_params/tutorial003_py310.py!} -``` - -//// - -//// tab | Python 3.9+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="9" -{!> ../../docs_src/header_params/tutorial003_py39.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="9" -{!> ../../docs_src/header_params/tutorial003.py!} -``` - -//// +{* ../../docs_src/header_params/tutorial003_an_py310.py hl[9] *} If you communicate with that *path operation* sending two HTTP headers like: diff --git a/docs/en/docs/tutorial/metadata.md b/docs/en/docs/tutorial/metadata.md index 715bb999a..6bd48caaf 100644 --- a/docs/en/docs/tutorial/metadata.md +++ b/docs/en/docs/tutorial/metadata.md @@ -18,9 +18,7 @@ You can set the following fields that are used in the OpenAPI specification and You can set them as follows: -```Python hl_lines="3-16 19-32" -{!../../docs_src/metadata/tutorial001.py!} -``` +{* ../../docs_src/metadata/tutorial001.py hl[3:16, 19:32] *} /// tip @@ -38,9 +36,7 @@ Since OpenAPI 3.1.0 and FastAPI 0.99.0, you can also set the `license_info` with For example: -```Python hl_lines="31" -{!../../docs_src/metadata/tutorial001_1.py!} -``` +{* ../../docs_src/metadata/tutorial001_1.py hl[31] *} ## Metadata for tags @@ -62,9 +58,7 @@ Let's try that in an example with tags for `users` and `items`. Create metadata for your tags and pass it to the `openapi_tags` parameter: -```Python hl_lines="3-16 18" -{!../../docs_src/metadata/tutorial004.py!} -``` +{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *} Notice that you can use Markdown inside of the descriptions, for example "login" will be shown in bold (**login**) and "fancy" will be shown in italics (_fancy_). @@ -78,9 +72,7 @@ You don't have to add metadata for all the tags that you use. Use the `tags` parameter with your *path operations* (and `APIRouter`s) to assign them to different tags: -```Python hl_lines="21 26" -{!../../docs_src/metadata/tutorial004.py!} -``` +{* ../../docs_src/metadata/tutorial004.py hl[21,26] *} /// info @@ -108,9 +100,7 @@ But you can configure it with the parameter `openapi_url`. For example, to set it to be served at `/api/v1/openapi.json`: -```Python hl_lines="3" -{!../../docs_src/metadata/tutorial002.py!} -``` +{* ../../docs_src/metadata/tutorial002.py hl[3] *} If you want to disable the OpenAPI schema completely you can set `openapi_url=None`, that will also disable the documentation user interfaces that use it. @@ -127,6 +117,4 @@ You can configure the two documentation user interfaces included: For example, to set Swagger UI to be served at `/documentation` and disable ReDoc: -```Python hl_lines="3" -{!../../docs_src/metadata/tutorial003.py!} -``` +{* ../../docs_src/metadata/tutorial003.py hl[3] *} diff --git a/docs/en/docs/tutorial/middleware.md b/docs/en/docs/tutorial/middleware.md index 7c4954c7b..53c47a085 100644 --- a/docs/en/docs/tutorial/middleware.md +++ b/docs/en/docs/tutorial/middleware.md @@ -11,7 +11,7 @@ A "middleware" is a function that works with every **request** before it is proc * It can do something to that **response** or run any needed code. * Then it returns the **response**. -/// note | "Technical Details" +/// note | Technical Details If you have dependencies with `yield`, the exit code will run *after* the middleware. @@ -31,9 +31,7 @@ The middleware function receives: * Then it returns the `response` generated by the corresponding *path operation*. * You can then further modify the `response` before returning it. -```Python hl_lines="8-9 11 14" -{!../../docs_src/middleware/tutorial001.py!} -``` +{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *} /// tip @@ -43,7 +41,7 @@ But if you have custom headers that you want a client in a browser to be able to /// -/// note | "Technical Details" +/// note | Technical Details You could also use `from starlette.requests import Request`. @@ -59,9 +57,7 @@ And also after the `response` is generated, before returning it. For example, you could add a custom header `X-Process-Time` containing the time in seconds that it took to process the request and generate a response: -```Python hl_lines="10 12-13" -{!../../docs_src/middleware/tutorial001.py!} -``` +{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *} /// tip diff --git a/docs/en/docs/tutorial/path-operation-configuration.md b/docs/en/docs/tutorial/path-operation-configuration.md index 4ca6ebf13..f2b5fd795 100644 --- a/docs/en/docs/tutorial/path-operation-configuration.md +++ b/docs/en/docs/tutorial/path-operation-configuration.md @@ -16,33 +16,11 @@ You can pass directly the `int` code, like `404`. But if you don't remember what each number code is for, you can use the shortcut constants in `status`: -//// tab | Python 3.10+ - -```Python hl_lines="1 15" -{!> ../../docs_src/path_operation_configuration/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="3 17" -{!> ../../docs_src/path_operation_configuration/tutorial001_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="3 17" -{!> ../../docs_src/path_operation_configuration/tutorial001.py!} -``` - -//// +{* ../../docs_src/path_operation_configuration/tutorial001_py310.py hl[1,15] *} That status code will be used in the response and will be added to the OpenAPI schema. -/// note | "Technical Details" +/// note | Technical Details You could also use `from starlette import status`. @@ -54,29 +32,7 @@ You could also use `from starlette import status`. You can add tags to your *path operation*, pass the parameter `tags` with a `list` of `str` (commonly just one `str`): -//// tab | Python 3.10+ - -```Python hl_lines="15 20 25" -{!> ../../docs_src/path_operation_configuration/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="17 22 27" -{!> ../../docs_src/path_operation_configuration/tutorial002_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="17 22 27" -{!> ../../docs_src/path_operation_configuration/tutorial002.py!} -``` - -//// +{* ../../docs_src/path_operation_configuration/tutorial002_py310.py hl[15,20,25] *} They will be added to the OpenAPI schema and used by the automatic documentation interfaces: @@ -90,37 +46,13 @@ In these cases, it could make sense to store the tags in an `Enum`. **FastAPI** supports that the same way as with plain strings: -```Python hl_lines="1 8-10 13 18" -{!../../docs_src/path_operation_configuration/tutorial002b.py!} -``` +{* ../../docs_src/path_operation_configuration/tutorial002b.py hl[1,8:10,13,18] *} ## Summary and description You can add a `summary` and `description`: -//// tab | Python 3.10+ - -```Python hl_lines="18-19" -{!> ../../docs_src/path_operation_configuration/tutorial003_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="20-21" -{!> ../../docs_src/path_operation_configuration/tutorial003_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="20-21" -{!> ../../docs_src/path_operation_configuration/tutorial003.py!} -``` - -//// +{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[18:19] *} ## Description from docstring @@ -128,29 +60,7 @@ As descriptions tend to be long and cover multiple lines, you can declare the *p You can write Markdown in the docstring, it will be interpreted and displayed correctly (taking into account docstring indentation). -//// tab | Python 3.10+ - -```Python hl_lines="17-25" -{!> ../../docs_src/path_operation_configuration/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="19-27" -{!> ../../docs_src/path_operation_configuration/tutorial004_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="19-27" -{!> ../../docs_src/path_operation_configuration/tutorial004.py!} -``` - -//// +{* ../../docs_src/path_operation_configuration/tutorial004_py310.py hl[17:25] *} It will be used in the interactive docs: @@ -160,29 +70,7 @@ It will be used in the interactive docs: You can specify the response description with the parameter `response_description`: -//// tab | Python 3.10+ - -```Python hl_lines="19" -{!> ../../docs_src/path_operation_configuration/tutorial005_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="21" -{!> ../../docs_src/path_operation_configuration/tutorial005_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="21" -{!> ../../docs_src/path_operation_configuration/tutorial005.py!} -``` - -//// +{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[19] *} /// info @@ -204,9 +92,7 @@ So, if you don't provide one, **FastAPI** will automatically generate one of "Su If you need to mark a *path operation* as deprecated, but without removing it, pass the parameter `deprecated`: -```Python hl_lines="16" -{!../../docs_src/path_operation_configuration/tutorial006.py!} -``` +{* ../../docs_src/path_operation_configuration/tutorial006.py hl[16] *} It will be clearly marked as deprecated in the interactive docs: diff --git a/docs/en/docs/tutorial/path-params-numeric-validations.md b/docs/en/docs/tutorial/path-params-numeric-validations.md index 9ddf49ea9..9440bcc03 100644 --- a/docs/en/docs/tutorial/path-params-numeric-validations.md +++ b/docs/en/docs/tutorial/path-params-numeric-validations.md @@ -6,57 +6,7 @@ In the same way that you can declare more validations and metadata for query par First, import `Path` from `fastapi`, and import `Annotated`: -//// tab | Python 3.10+ - -```Python hl_lines="1 3" -{!> ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="1 3" -{!> ../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="3-4" -{!> ../../docs_src/path_params_numeric_validations/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="1" -{!> ../../docs_src/path_params_numeric_validations/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="3" -{!> ../../docs_src/path_params_numeric_validations/tutorial001.py!} -``` - -//// +{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *} /// info @@ -74,57 +24,7 @@ You can declare all the same parameters as for `Query`. For example, to declare a `title` metadata value for the path parameter `item_id` you can type: -//// tab | Python 3.10+ - -```Python hl_lines="10" -{!> ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="10" -{!> ../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="11" -{!> ../../docs_src/path_params_numeric_validations/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="8" -{!> ../../docs_src/path_params_numeric_validations/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="10" -{!> ../../docs_src/path_params_numeric_validations/tutorial001.py!} -``` - -//// +{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *} /// note @@ -162,29 +62,13 @@ Prefer to use the `Annotated` version if possible. /// -```Python hl_lines="7" -{!> ../../docs_src/path_params_numeric_validations/tutorial002.py!} -``` +{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *} //// But keep in mind that if you use `Annotated`, you won't have this problem, it won't matter as you're not using the function parameter default values for `Query()` or `Path()`. -//// tab | Python 3.9+ - -```Python hl_lines="10" -{!> ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9" -{!> ../../docs_src/path_params_numeric_validations/tutorial002_an.py!} -``` - -//// +{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py *} ## Order the parameters as you need, tricks @@ -209,29 +93,13 @@ Pass `*`, as the first parameter of the function. Python won't do anything with that `*`, but it will know that all the following parameters should be called as keyword arguments (key-value pairs), also known as kwargs. Even if they don't have a default value. -```Python hl_lines="7" -{!../../docs_src/path_params_numeric_validations/tutorial003.py!} -``` +{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *} ### Better with `Annotated` Keep in mind that if you use `Annotated`, as you are not using function parameter default values, you won't have this problem, and you probably won't need to use `*`. -//// tab | Python 3.9+ - -```Python hl_lines="10" -{!> ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9" -{!> ../../docs_src/path_params_numeric_validations/tutorial003_an.py!} -``` - -//// +{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *} ## Number validations: greater than or equal @@ -239,35 +107,7 @@ With `Query` and `Path` (and others you'll see later) you can declare number con Here, with `ge=1`, `item_id` will need to be an integer number "`g`reater than or `e`qual" to `1`. -//// tab | Python 3.9+ - -```Python hl_lines="10" -{!> ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9" -{!> ../../docs_src/path_params_numeric_validations/tutorial004_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="8" -{!> ../../docs_src/path_params_numeric_validations/tutorial004.py!} -``` - -//// +{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *} ## Number validations: greater than and less than or equal @@ -276,35 +116,7 @@ The same applies for: * `gt`: `g`reater `t`han * `le`: `l`ess than or `e`qual -//// tab | Python 3.9+ - -```Python hl_lines="10" -{!> ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9" -{!> ../../docs_src/path_params_numeric_validations/tutorial005_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="9" -{!> ../../docs_src/path_params_numeric_validations/tutorial005.py!} -``` - -//// +{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *} ## Number validations: floats, greater than and less than @@ -316,35 +128,7 @@ So, `0.5` would be a valid value. But `0.0` or `0` would not. And the same for lt. -//// tab | Python 3.9+ - -```Python hl_lines="13" -{!> ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="12" -{!> ../../docs_src/path_params_numeric_validations/tutorial006_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="11" -{!> ../../docs_src/path_params_numeric_validations/tutorial006.py!} -``` - -//// +{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *} ## Recap @@ -365,7 +149,7 @@ All of them share the same parameters for additional validation and metadata you /// -/// note | "Technical Details" +/// note | Technical Details When you import `Query`, `Path` and others from `fastapi`, they are actually functions. diff --git a/docs/en/docs/tutorial/path-params.md b/docs/en/docs/tutorial/path-params.md index fd9e74585..7e83d3ae5 100644 --- a/docs/en/docs/tutorial/path-params.md +++ b/docs/en/docs/tutorial/path-params.md @@ -2,9 +2,7 @@ You can declare path "parameters" or "variables" with the same syntax used by Python format strings: -```Python hl_lines="6-7" -{!../../docs_src/path_params/tutorial001.py!} -``` +{* ../../docs_src/path_params/tutorial001.py hl[6:7] *} The value of the path parameter `item_id` will be passed to your function as the argument `item_id`. @@ -18,9 +16,7 @@ So, if you run this example and go to ../../docs_src/query_param_models/tutorial001_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="8-12 16" -{!> ../../docs_src/query_param_models/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="10-14 18" -{!> ../../docs_src/query_param_models/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="9-13 17" -{!> ../../docs_src/query_param_models/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.9+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="8-12 16" -{!> ../../docs_src/query_param_models/tutorial001_py39.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="9-13 17" -{!> ../../docs_src/query_param_models/tutorial001_py310.py!} -``` - -//// +{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *} **FastAPI** will **extract** the data for **each field** from the **query parameters** in the request and give you the Pydantic model you defined. @@ -96,71 +32,7 @@ In some special use cases (probably not very common), you might want to **restri You can use Pydantic's model configuration to `forbid` any `extra` fields: -//// tab | Python 3.10+ - -```Python hl_lines="10" -{!> ../../docs_src/query_param_models/tutorial002_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="9" -{!> ../../docs_src/query_param_models/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="11" -{!> ../../docs_src/query_param_models/tutorial002_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="10" -{!> ../../docs_src/query_param_models/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.9+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="9" -{!> ../../docs_src/query_param_models/tutorial002_py39.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="11" -{!> ../../docs_src/query_param_models/tutorial002.py!} -``` - -//// +{* ../../docs_src/query_param_models/tutorial002_an_py310.py hl[10] *} If a client tries to send some **extra** data in the **query parameters**, they will receive an **error** response. diff --git a/docs/en/docs/tutorial/request-files.md b/docs/en/docs/tutorial/request-files.md index f3f1eb103..0d57f3566 100644 --- a/docs/en/docs/tutorial/request-files.md +++ b/docs/en/docs/tutorial/request-files.md @@ -20,69 +20,13 @@ This is because uploaded files are sent as "form data". Import `File` and `UploadFile` from `fastapi`: -//// tab | Python 3.9+ - -```Python hl_lines="3" -{!> ../../docs_src/request_files/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="1" -{!> ../../docs_src/request_files/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="1" -{!> ../../docs_src/request_files/tutorial001.py!} -``` - -//// +{* ../../docs_src/request_files/tutorial001_an_py39.py hl[3] *} ## Define `File` Parameters Create file parameters the same way you would for `Body` or `Form`: -//// tab | Python 3.9+ - -```Python hl_lines="9" -{!> ../../docs_src/request_files/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="8" -{!> ../../docs_src/request_files/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="7" -{!> ../../docs_src/request_files/tutorial001.py!} -``` - -//// +{* ../../docs_src/request_files/tutorial001_an_py39.py hl[9] *} /// info @@ -110,35 +54,7 @@ But there are several cases in which you might benefit from using `UploadFile`. Define a file parameter with a type of `UploadFile`: -//// tab | Python 3.9+ - -```Python hl_lines="14" -{!> ../../docs_src/request_files/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="13" -{!> ../../docs_src/request_files/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="12" -{!> ../../docs_src/request_files/tutorial001.py!} -``` - -//// +{* ../../docs_src/request_files/tutorial001_an_py39.py hl[14] *} Using `UploadFile` has several advantages over `bytes`: @@ -181,13 +97,13 @@ If you are inside of a normal `def` *path operation function*, you can access th contents = myfile.file.read() ``` -/// note | "`async` Technical Details" +/// note | `async` Technical Details When you use the `async` methods, **FastAPI** runs the file methods in a threadpool and awaits for them. /// -/// note | "Starlette Technical Details" +/// note | Starlette Technical Details **FastAPI**'s `UploadFile` inherits directly from **Starlette**'s `UploadFile`, but adds some necessary parts to make it compatible with **Pydantic** and the other parts of FastAPI. @@ -199,7 +115,7 @@ The way HTML forms (`
`) sends the data to the server normally uses **FastAPI** will make sure to read that data from the right place instead of JSON. -/// note | "Technical Details" +/// note | Technical Details Data from forms is normally encoded using the "media type" `application/x-www-form-urlencoded` when it doesn't include files. @@ -221,91 +137,13 @@ This is not a limitation of **FastAPI**, it's part of the HTTP protocol. You can make a file optional by using standard type annotations and setting a default value of `None`: -//// tab | Python 3.10+ - -```Python hl_lines="9 17" -{!> ../../docs_src/request_files/tutorial001_02_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="9 17" -{!> ../../docs_src/request_files/tutorial001_02_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="10 18" -{!> ../../docs_src/request_files/tutorial001_02_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="7 15" -{!> ../../docs_src/request_files/tutorial001_02_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="9 17" -{!> ../../docs_src/request_files/tutorial001_02.py!} -``` - -//// +{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *} ## `UploadFile` with Additional Metadata You can also use `File()` with `UploadFile`, for example, to set additional metadata: -//// tab | Python 3.9+ - -```Python hl_lines="9 15" -{!> ../../docs_src/request_files/tutorial001_03_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="8 14" -{!> ../../docs_src/request_files/tutorial001_03_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="7 13" -{!> ../../docs_src/request_files/tutorial001_03.py!} -``` - -//// +{* ../../docs_src/request_files/tutorial001_03_an_py39.py hl[9,15] *} ## Multiple File Uploads @@ -315,53 +153,11 @@ They would be associated to the same "form field" sent using "form data". To use that, declare a list of `bytes` or `UploadFile`: -//// tab | Python 3.9+ - -```Python hl_lines="10 15" -{!> ../../docs_src/request_files/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="11 16" -{!> ../../docs_src/request_files/tutorial002_an.py!} -``` - -//// - -//// tab | Python 3.9+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="8 13" -{!> ../../docs_src/request_files/tutorial002_py39.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="10 15" -{!> ../../docs_src/request_files/tutorial002.py!} -``` - -//// +{* ../../docs_src/request_files/tutorial002_an_py39.py hl[10,15] *} You will receive, as declared, a `list` of `bytes` or `UploadFile`s. -/// note | "Technical Details" +/// note | Technical Details You could also use `from starlette.responses import HTMLResponse`. @@ -373,49 +169,7 @@ You could also use `from starlette.responses import HTMLResponse`. And the same way as before, you can use `File()` to set additional parameters, even for `UploadFile`: -//// tab | Python 3.9+ - -```Python hl_lines="11 18-20" -{!> ../../docs_src/request_files/tutorial003_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="12 19-21" -{!> ../../docs_src/request_files/tutorial003_an.py!} -``` - -//// - -//// tab | Python 3.9+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="9 16" -{!> ../../docs_src/request_files/tutorial003_py39.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="11 18" -{!> ../../docs_src/request_files/tutorial003.py!} -``` - -//// +{* ../../docs_src/request_files/tutorial003_an_py39.py hl[11,18:20] *} ## Recap diff --git a/docs/en/docs/tutorial/request-form-models.md b/docs/en/docs/tutorial/request-form-models.md index f1142877a..79046a3f6 100644 --- a/docs/en/docs/tutorial/request-form-models.md +++ b/docs/en/docs/tutorial/request-form-models.md @@ -24,35 +24,7 @@ This is supported since FastAPI version `0.113.0`. 🤓 You just need to declare a **Pydantic model** with the fields you want to receive as **form fields**, and then declare the parameter as `Form`: -//// tab | Python 3.9+ - -```Python hl_lines="9-11 15" -{!> ../../docs_src/request_form_models/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="8-10 14" -{!> ../../docs_src/request_form_models/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="7-9 13" -{!> ../../docs_src/request_form_models/tutorial001.py!} -``` - -//// +{* ../../docs_src/request_form_models/tutorial001_an_py39.py hl[9:11,15] *} **FastAPI** will **extract** the data for **each field** from the **form data** in the request and give you the Pydantic model you defined. @@ -76,35 +48,7 @@ This is supported since FastAPI version `0.114.0`. 🤓 You can use Pydantic's model configuration to `forbid` any `extra` fields: -//// tab | Python 3.9+ - -```Python hl_lines="12" -{!> ../../docs_src/request_form_models/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="11" -{!> ../../docs_src/request_form_models/tutorial002_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="10" -{!> ../../docs_src/request_form_models/tutorial002.py!} -``` - -//// +{* ../../docs_src/request_form_models/tutorial002_an_py39.py hl[12] *} If a client tries to send some extra data, they will receive an **error** response. diff --git a/docs/en/docs/tutorial/request-forms.md b/docs/en/docs/tutorial/request-forms.md index 2ccc6886e..3c6a0ddaa 100644 --- a/docs/en/docs/tutorial/request-forms.md +++ b/docs/en/docs/tutorial/request-forms.md @@ -18,69 +18,13 @@ $ pip install python-multipart Import `Form` from `fastapi`: -//// tab | Python 3.9+ - -```Python hl_lines="3" -{!> ../../docs_src/request_forms/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="1" -{!> ../../docs_src/request_forms/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="1" -{!> ../../docs_src/request_forms/tutorial001.py!} -``` - -//// +{* ../../docs_src/request_forms/tutorial001_an_py39.py hl[3] *} ## Define `Form` parameters Create form parameters the same way you would for `Body` or `Query`: -//// tab | Python 3.9+ - -```Python hl_lines="9" -{!> ../../docs_src/request_forms/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="8" -{!> ../../docs_src/request_forms/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="7" -{!> ../../docs_src/request_forms/tutorial001.py!} -``` - -//// +{* ../../docs_src/request_forms/tutorial001_an_py39.py hl[9] *} For example, in one of the ways the OAuth2 specification can be used (called "password flow") it is required to send a `username` and `password` as form fields. @@ -106,7 +50,7 @@ The way HTML forms (`
`) sends the data to the server normally uses **FastAPI** will make sure to read that data from the right place instead of JSON. -/// note | "Technical Details" +/// note | Technical Details Data from forms is normally encoded using the "media type" `application/x-www-form-urlencoded`. diff --git a/docs/en/docs/tutorial/response-model.md b/docs/en/docs/tutorial/response-model.md index 36ccfc4ce..e7837086f 100644 --- a/docs/en/docs/tutorial/response-model.md +++ b/docs/en/docs/tutorial/response-model.md @@ -4,29 +4,7 @@ You can declare the type used for the response by annotating the *path operation You can use **type annotations** the same way you would for input data in function **parameters**, you can use Pydantic models, lists, dictionaries, scalar values like integers, booleans, etc. -//// tab | Python 3.10+ - -```Python hl_lines="16 21" -{!> ../../docs_src/response_model/tutorial001_01_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="18 23" -{!> ../../docs_src/response_model/tutorial001_01_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="18 23" -{!> ../../docs_src/response_model/tutorial001_01.py!} -``` - -//// +{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *} FastAPI will use this return type to: @@ -59,29 +37,7 @@ You can use the `response_model` parameter in any of the *path operations*: * `@app.delete()` * etc. -//// tab | Python 3.10+ - -```Python hl_lines="17 22 24-27" -{!> ../../docs_src/response_model/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="17 22 24-27" -{!> ../../docs_src/response_model/tutorial001_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="17 22 24-27" -{!> ../../docs_src/response_model/tutorial001.py!} -``` - -//// +{* ../../docs_src/response_model/tutorial001_py310.py hl[17,22,24:27] *} /// note @@ -113,21 +69,7 @@ You can also use `response_model=None` to disable creating a response model for Here we are declaring a `UserIn` model, it will contain a plaintext password: -//// tab | Python 3.10+ - -```Python hl_lines="7 9" -{!> ../../docs_src/response_model/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9 11" -{!> ../../docs_src/response_model/tutorial002.py!} -``` - -//// +{* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *} /// info @@ -149,21 +91,7 @@ $ pip install "pydantic[email]" And we are using this model to declare our input and the same model to declare our output: -//// tab | Python 3.10+ - -```Python hl_lines="16" -{!> ../../docs_src/response_model/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="18" -{!> ../../docs_src/response_model/tutorial002.py!} -``` - -//// +{* ../../docs_src/response_model/tutorial002_py310.py hl[16] *} Now, whenever a browser is creating a user with a password, the API will return the same password in the response. @@ -181,57 +109,15 @@ Never store the plain password of a user or send it in a response like this, unl We can instead create an input model with the plaintext password and an output model without it: -//// tab | Python 3.10+ - -```Python hl_lines="9 11 16" -{!> ../../docs_src/response_model/tutorial003_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9 11 16" -{!> ../../docs_src/response_model/tutorial003.py!} -``` - -//// +{* ../../docs_src/response_model/tutorial003_py310.py hl[9,11,16] *} Here, even though our *path operation function* is returning the same input user that contains the password: -//// tab | Python 3.10+ - -```Python hl_lines="24" -{!> ../../docs_src/response_model/tutorial003_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="24" -{!> ../../docs_src/response_model/tutorial003.py!} -``` - -//// +{* ../../docs_src/response_model/tutorial003_py310.py hl[24] *} ...we declared the `response_model` to be our model `UserOut`, that doesn't include the password: -//// tab | Python 3.10+ - -```Python hl_lines="22" -{!> ../../docs_src/response_model/tutorial003_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="22" -{!> ../../docs_src/response_model/tutorial003.py!} -``` - -//// +{* ../../docs_src/response_model/tutorial003_py310.py hl[22] *} So, **FastAPI** will take care of filtering out all the data that is not declared in the output model (using Pydantic). @@ -255,21 +141,7 @@ But in most of the cases where we need to do something like this, we want the mo And in those cases, we can use classes and inheritance to take advantage of function **type annotations** to get better support in the editor and tools, and still get the FastAPI **data filtering**. -//// tab | Python 3.10+ - -```Python hl_lines="7-10 13-14 18" -{!> ../../docs_src/response_model/tutorial003_01_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9-13 15-16 20" -{!> ../../docs_src/response_model/tutorial003_01.py!} -``` - -//// +{* ../../docs_src/response_model/tutorial003_01_py310.py hl[7:10,13:14,18] *} With this, we get tooling support, from editors and mypy as this code is correct in terms of types, but we also get the data filtering from FastAPI. @@ -311,9 +183,7 @@ There might be cases where you return something that is not a valid Pydantic fie The most common case would be [returning a Response directly as explained later in the advanced docs](../advanced/response-directly.md){.internal-link target=_blank}. -```Python hl_lines="8 10-11" -{!> ../../docs_src/response_model/tutorial003_02.py!} -``` +{* ../../docs_src/response_model/tutorial003_02.py hl[8,10:11] *} This simple case is handled automatically by FastAPI because the return type annotation is the class (or a subclass of) `Response`. @@ -323,9 +193,7 @@ And tools will also be happy because both `RedirectResponse` and `JSONResponse` You can also use a subclass of `Response` in the type annotation: -```Python hl_lines="8-9" -{!> ../../docs_src/response_model/tutorial003_03.py!} -``` +{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *} This will also work because `RedirectResponse` is a subclass of `Response`, and FastAPI will automatically handle this simple case. @@ -335,21 +203,7 @@ But when you return some other arbitrary object that is not a valid Pydantic typ The same would happen if you had something like a union between different types where one or more of them are not valid Pydantic types, for example this would fail 💥: -//// tab | Python 3.10+ - -```Python hl_lines="8" -{!> ../../docs_src/response_model/tutorial003_04_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="10" -{!> ../../docs_src/response_model/tutorial003_04.py!} -``` - -//// +{* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *} ...this fails because the type annotation is not a Pydantic type and is not just a single `Response` class or subclass, it's a union (any of the two) between a `Response` and a `dict`. @@ -361,21 +215,7 @@ But you might want to still keep the return type annotation in the function to g In this case, you can disable the response model generation by setting `response_model=None`: -//// tab | Python 3.10+ - -```Python hl_lines="7" -{!> ../../docs_src/response_model/tutorial003_05_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="9" -{!> ../../docs_src/response_model/tutorial003_05.py!} -``` - -//// +{* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *} This will make FastAPI skip the response model generation and that way you can have any return type annotations you need without it affecting your FastAPI application. 🤓 @@ -383,29 +223,7 @@ This will make FastAPI skip the response model generation and that way you can h Your response model could have default values, like: -//// tab | Python 3.10+ - -```Python hl_lines="9 11-12" -{!> ../../docs_src/response_model/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="11 13-14" -{!> ../../docs_src/response_model/tutorial004_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="11 13-14" -{!> ../../docs_src/response_model/tutorial004.py!} -``` - -//// +{* ../../docs_src/response_model/tutorial004_py310.py hl[9,11:12] *} * `description: Union[str, None] = None` (or `str | None = None` in Python 3.10) has a default of `None`. * `tax: float = 10.5` has a default of `10.5`. @@ -419,29 +237,7 @@ For example, if you have models with many optional attributes in a NoSQL databas You can set the *path operation decorator* parameter `response_model_exclude_unset=True`: -//// tab | Python 3.10+ - -```Python hl_lines="22" -{!> ../../docs_src/response_model/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="24" -{!> ../../docs_src/response_model/tutorial004_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="24" -{!> ../../docs_src/response_model/tutorial004.py!} -``` - -//// +{* ../../docs_src/response_model/tutorial004_py310.py hl[22] *} and those default values won't be included in the response, only the values actually set. @@ -538,21 +334,7 @@ This also applies to `response_model_by_alias` that works similarly. /// -//// tab | Python 3.10+ - -```Python hl_lines="29 35" -{!> ../../docs_src/response_model/tutorial005_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="31 37" -{!> ../../docs_src/response_model/tutorial005.py!} -``` - -//// +{* ../../docs_src/response_model/tutorial005_py310.py hl[29,35] *} /// tip @@ -566,21 +348,7 @@ It is equivalent to `set(["name", "description"])`. If you forget to use a `set` and use a `list` or `tuple` instead, FastAPI will still convert it to a `set` and it will work correctly: -//// tab | Python 3.10+ - -```Python hl_lines="29 35" -{!> ../../docs_src/response_model/tutorial006_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="31 37" -{!> ../../docs_src/response_model/tutorial006.py!} -``` - -//// +{* ../../docs_src/response_model/tutorial006_py310.py hl[29,35] *} ## Recap diff --git a/docs/en/docs/tutorial/response-status-code.md b/docs/en/docs/tutorial/response-status-code.md index a32faa40b..711042a46 100644 --- a/docs/en/docs/tutorial/response-status-code.md +++ b/docs/en/docs/tutorial/response-status-code.md @@ -88,7 +88,7 @@ They are just a convenience, they hold the same number, but that way you can use -/// note | "Technical Details" +/// note | Technical Details You could also use `from starlette import status`. diff --git a/docs/en/docs/tutorial/schema-extra-example.md b/docs/en/docs/tutorial/schema-extra-example.md index 5896b54d9..32a1f5ca2 100644 --- a/docs/en/docs/tutorial/schema-extra-example.md +++ b/docs/en/docs/tutorial/schema-extra-example.md @@ -8,35 +8,15 @@ Here are several ways to do it. You can declare `examples` for a Pydantic model that will be added to the generated JSON Schema. -//// tab | Python 3.10+ Pydantic v2 +//// tab | Pydantic v2 -```Python hl_lines="13-24" -{!> ../../docs_src/schema_extra_example/tutorial001_py310.py!} -``` +{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *} //// -//// tab | Python 3.10+ Pydantic v1 +//// tab | Pydantic v1 -```Python hl_lines="13-23" -{!> ../../docs_src/schema_extra_example/tutorial001_py310_pv1.py!} -``` - -//// - -//// tab | Python 3.8+ Pydantic v2 - -```Python hl_lines="15-26" -{!> ../../docs_src/schema_extra_example/tutorial001.py!} -``` - -//// - -//// tab | Python 3.8+ Pydantic v1 - -```Python hl_lines="15-25" -{!> ../../docs_src/schema_extra_example/tutorial001_pv1.py!} -``` +{* ../../docs_src/schema_extra_example/tutorial001_pv1_py310.py hl[13:23] *} //// @@ -80,21 +60,7 @@ You can read more at the end of this page. When using `Field()` with Pydantic models, you can also declare additional `examples`: -//// tab | Python 3.10+ - -```Python hl_lines="2 8-11" -{!> ../../docs_src/schema_extra_example/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="4 10-13" -{!> ../../docs_src/schema_extra_example/tutorial002.py!} -``` - -//// +{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *} ## `examples` in JSON Schema - OpenAPI @@ -114,57 +80,7 @@ you can also declare a group of `examples` with additional information that will Here we pass `examples` containing one example of the data expected in `Body()`: -//// tab | Python 3.10+ - -```Python hl_lines="22-29" -{!> ../../docs_src/schema_extra_example/tutorial003_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="22-29" -{!> ../../docs_src/schema_extra_example/tutorial003_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="23-30" -{!> ../../docs_src/schema_extra_example/tutorial003_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="18-25" -{!> ../../docs_src/schema_extra_example/tutorial003_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="20-27" -{!> ../../docs_src/schema_extra_example/tutorial003.py!} -``` - -//// +{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *} ### Example in the docs UI @@ -176,57 +92,7 @@ With any of the methods above it would look like this in the `/docs`: You can of course also pass multiple `examples`: -//// tab | Python 3.10+ - -```Python hl_lines="23-38" -{!> ../../docs_src/schema_extra_example/tutorial004_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="23-38" -{!> ../../docs_src/schema_extra_example/tutorial004_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="24-39" -{!> ../../docs_src/schema_extra_example/tutorial004_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="19-34" -{!> ../../docs_src/schema_extra_example/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="21-36" -{!> ../../docs_src/schema_extra_example/tutorial004.py!} -``` - -//// +{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *} When you do this, the examples will be part of the internal **JSON Schema** for that body data. @@ -267,57 +133,7 @@ Each specific example `dict` in the `examples` can contain: You can use it like this: -//// tab | Python 3.10+ - -```Python hl_lines="23-49" -{!> ../../docs_src/schema_extra_example/tutorial005_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="23-49" -{!> ../../docs_src/schema_extra_example/tutorial005_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="24-50" -{!> ../../docs_src/schema_extra_example/tutorial005_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="19-45" -{!> ../../docs_src/schema_extra_example/tutorial005_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="21-47" -{!> ../../docs_src/schema_extra_example/tutorial005.py!} -``` - -//// +{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *} ### OpenAPI Examples in the Docs UI diff --git a/docs/en/docs/tutorial/security/first-steps.md b/docs/en/docs/tutorial/security/first-steps.md index ead2aa799..8f6578e12 100644 --- a/docs/en/docs/tutorial/security/first-steps.md +++ b/docs/en/docs/tutorial/security/first-steps.md @@ -20,35 +20,7 @@ Let's first just use the code and see how it works, and then we'll come back to Copy the example in a file `main.py`: -//// tab | Python 3.9+ - -```Python -{!> ../../docs_src/security/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python -{!> ../../docs_src/security/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python -{!> ../../docs_src/security/tutorial001.py!} -``` - -//// +{* ../../docs_src/security/tutorial001_an_py39.py *} ## Run it @@ -88,7 +60,7 @@ You will see something like this: -/// check | "Authorize button!" +/// check | Authorize button! You already have a shiny new "Authorize" button. @@ -160,35 +132,7 @@ In that case, **FastAPI** also provides you with the tools to build it. When we create an instance of the `OAuth2PasswordBearer` class we pass in the `tokenUrl` parameter. This parameter contains the URL that the client (the frontend running in the user's browser) will use to send the `username` and `password` in order to get a token. -//// tab | Python 3.9+ - -```Python hl_lines="8" -{!> ../../docs_src/security/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="7" -{!> ../../docs_src/security/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="6" -{!> ../../docs_src/security/tutorial001.py!} -``` - -//// +{* ../../docs_src/security/tutorial001_an_py39.py hl[8] *} /// tip @@ -226,41 +170,13 @@ So, it can be used with `Depends`. Now you can pass that `oauth2_scheme` in a dependency with `Depends`. -//// tab | Python 3.9+ - -```Python hl_lines="12" -{!> ../../docs_src/security/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="11" -{!> ../../docs_src/security/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="10" -{!> ../../docs_src/security/tutorial001.py!} -``` - -//// +{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *} This dependency will provide a `str` that is assigned to the parameter `token` of the *path operation function*. **FastAPI** will know that it can use this dependency to define a "security scheme" in the OpenAPI schema (and the automatic API docs). -/// info | "Technical Details" +/// info | Technical Details **FastAPI** will know that it can use the class `OAuth2PasswordBearer` (declared in a dependency) to define the security scheme in OpenAPI because it inherits from `fastapi.security.oauth2.OAuth2`, which in turn inherits from `fastapi.security.base.SecurityBase`. diff --git a/docs/en/docs/tutorial/security/get-current-user.md b/docs/en/docs/tutorial/security/get-current-user.md index 069806621..5de3a8e7d 100644 --- a/docs/en/docs/tutorial/security/get-current-user.md +++ b/docs/en/docs/tutorial/security/get-current-user.md @@ -2,35 +2,7 @@ In the previous chapter the security system (which is based on the dependency injection system) was giving the *path operation function* a `token` as a `str`: -//// tab | Python 3.9+ - -```Python hl_lines="12" -{!> ../../docs_src/security/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="11" -{!> ../../docs_src/security/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="10" -{!> ../../docs_src/security/tutorial001.py!} -``` - -//// +{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *} But that is still not that useful. @@ -42,57 +14,7 @@ First, let's create a Pydantic user model. The same way we use Pydantic to declare bodies, we can use it anywhere else: -//// tab | Python 3.10+ - -```Python hl_lines="5 12-16" -{!> ../../docs_src/security/tutorial002_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="5 12-16" -{!> ../../docs_src/security/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="5 13-17" -{!> ../../docs_src/security/tutorial002_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="3 10-14" -{!> ../../docs_src/security/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="5 12-16" -{!> ../../docs_src/security/tutorial002.py!} -``` - -//// +{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:6] *} ## Create a `get_current_user` dependency @@ -104,169 +26,19 @@ Remember that dependencies can have sub-dependencies? The same as we were doing before in the *path operation* directly, our new dependency `get_current_user` will receive a `token` as a `str` from the sub-dependency `oauth2_scheme`: -//// tab | Python 3.10+ - -```Python hl_lines="25" -{!> ../../docs_src/security/tutorial002_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="25" -{!> ../../docs_src/security/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="26" -{!> ../../docs_src/security/tutorial002_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="23" -{!> ../../docs_src/security/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="25" -{!> ../../docs_src/security/tutorial002.py!} -``` - -//// +{* ../../docs_src/security/tutorial002_an_py310.py hl[25] *} ## Get the user `get_current_user` will use a (fake) utility function we created, that takes a token as a `str` and returns our Pydantic `User` model: -//// tab | Python 3.10+ - -```Python hl_lines="19-22 26-27" -{!> ../../docs_src/security/tutorial002_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="19-22 26-27" -{!> ../../docs_src/security/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="20-23 27-28" -{!> ../../docs_src/security/tutorial002_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="17-20 24-25" -{!> ../../docs_src/security/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="19-22 26-27" -{!> ../../docs_src/security/tutorial002.py!} -``` - -//// +{* ../../docs_src/security/tutorial002_an_py310.py hl[19:22,26:27] *} ## Inject the current user So now we can use the same `Depends` with our `get_current_user` in the *path operation*: -//// tab | Python 3.10+ - -```Python hl_lines="31" -{!> ../../docs_src/security/tutorial002_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="31" -{!> ../../docs_src/security/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="32" -{!> ../../docs_src/security/tutorial002_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="29" -{!> ../../docs_src/security/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="31" -{!> ../../docs_src/security/tutorial002.py!} -``` - -//// +{* ../../docs_src/security/tutorial002_an_py310.py hl[31] *} Notice that we declare the type of `current_user` as the Pydantic model `User`. @@ -320,57 +92,7 @@ And all of them (or any portion of them that you want) can take advantage of re- And all these thousands of *path operations* can be as small as 3 lines: -//// tab | Python 3.10+ - -```Python hl_lines="30-32" -{!> ../../docs_src/security/tutorial002_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="30-32" -{!> ../../docs_src/security/tutorial002_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="31-33" -{!> ../../docs_src/security/tutorial002_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="28-30" -{!> ../../docs_src/security/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="30-32" -{!> ../../docs_src/security/tutorial002.py!} -``` - -//// +{* ../../docs_src/security/tutorial002_an_py310.py hl[30:32] *} ## Recap diff --git a/docs/en/docs/tutorial/security/oauth2-jwt.md b/docs/en/docs/tutorial/security/oauth2-jwt.md index 6ae1507dc..8644db45c 100644 --- a/docs/en/docs/tutorial/security/oauth2-jwt.md +++ b/docs/en/docs/tutorial/security/oauth2-jwt.md @@ -116,57 +116,7 @@ And another utility to verify if a received password matches the hash stored. And another one to authenticate and return a user. -//// tab | Python 3.10+ - -```Python hl_lines="8 49 56-57 60-61 70-76" -{!> ../../docs_src/security/tutorial004_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="8 49 56-57 60-61 70-76" -{!> ../../docs_src/security/tutorial004_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="8 50 57-58 61-62 71-77" -{!> ../../docs_src/security/tutorial004_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="7 48 55-56 59-60 69-75" -{!> ../../docs_src/security/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="8 49 56-57 60-61 70-76" -{!> ../../docs_src/security/tutorial004.py!} -``` - -//// +{* ../../docs_src/security/tutorial004_an_py310.py hl[8,49,56:57,60:61,70:76] *} /// note @@ -202,57 +152,7 @@ Define a Pydantic Model that will be used in the token endpoint for the response Create a utility function to generate a new access token. -//// tab | Python 3.10+ - -```Python hl_lines="4 7 13-15 29-31 79-87" -{!> ../../docs_src/security/tutorial004_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="4 7 13-15 29-31 79-87" -{!> ../../docs_src/security/tutorial004_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="4 7 14-16 30-32 80-88" -{!> ../../docs_src/security/tutorial004_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="3 6 12-14 28-30 78-86" -{!> ../../docs_src/security/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="4 7 13-15 29-31 79-87" -{!> ../../docs_src/security/tutorial004.py!} -``` - -//// +{* ../../docs_src/security/tutorial004_an_py310.py hl[4,7,13:15,29:31,79:87] *} ## Update the dependencies @@ -262,57 +162,7 @@ Decode the received token, verify it, and return the current user. If the token is invalid, return an HTTP error right away. -//// tab | Python 3.10+ - -```Python hl_lines="90-107" -{!> ../../docs_src/security/tutorial004_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="90-107" -{!> ../../docs_src/security/tutorial004_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="91-108" -{!> ../../docs_src/security/tutorial004_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="89-106" -{!> ../../docs_src/security/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="90-107" -{!> ../../docs_src/security/tutorial004.py!} -``` - -//// +{* ../../docs_src/security/tutorial004_an_py310.py hl[90:107] *} ## Update the `/token` *path operation* @@ -320,57 +170,7 @@ Create a `timedelta` with the expiration time of the token. Create a real JWT access token and return it. -//// tab | Python 3.10+ - -```Python hl_lines="118-133" -{!> ../../docs_src/security/tutorial004_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="118-133" -{!> ../../docs_src/security/tutorial004_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="119-134" -{!> ../../docs_src/security/tutorial004_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="115-130" -{!> ../../docs_src/security/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Prefer to use the `Annotated` version if possible. - -/// - -```Python hl_lines="116-131" -{!> ../../docs_src/security/tutorial004.py!} -``` - -//// +{* ../../docs_src/security/tutorial004_an_py310.py hl[118:133] *} ### Technical details about the JWT "subject" `sub` diff --git a/docs/en/docs/tutorial/static-files.md b/docs/en/docs/tutorial/static-files.md index 46affd4f2..1d277a51c 100644 --- a/docs/en/docs/tutorial/static-files.md +++ b/docs/en/docs/tutorial/static-files.md @@ -9,7 +9,7 @@ You can serve static files automatically from a directory using `StaticFiles`. {* ../../docs_src/static_files/tutorial001.py hl[2,6] *} -/// note | "Technical Details" +/// note | Technical Details You could also use `from starlette.staticfiles import StaticFiles`. diff --git a/docs/en/docs/tutorial/testing.md b/docs/en/docs/tutorial/testing.md index 7f609a595..a204f596f 100644 --- a/docs/en/docs/tutorial/testing.md +++ b/docs/en/docs/tutorial/testing.md @@ -44,7 +44,7 @@ This allows you to use `pytest` directly without complications. /// -/// note | "Technical Details" +/// note | Technical Details You could also use `from starlette.testclient import TestClient`. diff --git a/docs/es/docs/advanced/path-operation-advanced-configuration.md b/docs/es/docs/advanced/path-operation-advanced-configuration.md index f6813f0ff..12399d581 100644 --- a/docs/es/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/es/docs/advanced/path-operation-advanced-configuration.md @@ -2,7 +2,7 @@ ## OpenAPI operationId -/// warning | "Advertencia" +/// warning | Advertencia Si no eres una persona "experta" en OpenAPI, probablemente no necesitas leer esto. diff --git a/docs/es/docs/tutorial/cookie-params.md b/docs/es/docs/tutorial/cookie-params.md index db3fc092e..9a3b1a00b 100644 --- a/docs/es/docs/tutorial/cookie-params.md +++ b/docs/es/docs/tutorial/cookie-params.md @@ -16,7 +16,7 @@ El primer valor es el valor por defecto, puedes pasar todos los parámetros adic {* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[9]*} -/// note | "Detalles Técnicos" +/// note | Detalles Técnicos `Cookie` es una clase "hermana" de `Path` y `Query`. También hereda de la misma clase común `Param`. diff --git a/docs/es/docs/tutorial/index.md b/docs/es/docs/tutorial/index.md index 46c57c4c3..fa13450f0 100644 --- a/docs/es/docs/tutorial/index.md +++ b/docs/es/docs/tutorial/index.md @@ -50,7 +50,7 @@ $ pip install "fastapi[all]" ...eso también incluye `uvicorn` que puedes usar como el servidor que ejecuta tu código. -/// note | "Nota" +/// note | Nota También puedes instalarlo parte por parte. diff --git a/docs/fa/docs/tutorial/middleware.md b/docs/fa/docs/tutorial/middleware.md index ca631d507..a3ab483fb 100644 --- a/docs/fa/docs/tutorial/middleware.md +++ b/docs/fa/docs/tutorial/middleware.md @@ -11,7 +11,7 @@ * می تواند کاری با **پاسخ** انجام دهید یا هر کد مورد نیازتان را اجرا کند. * سپس **پاسخ** را برمی گرداند. -/// توجه | "جزئیات فنی" +/// توجه | جزئیات فنی در صورت وجود وابستگی هایی با `yield`، کد خروجی **پس از** اجرای میان‌‌افزار اجرا خواهد شد. @@ -40,7 +40,7 @@ /// -/// توجه | "جزئیات فنی" +/// توجه | جزئیات فنی شما همچنین می‌توانید از `from starlette.requests import Request` استفاده کنید. diff --git a/docs/fr/docs/advanced/additional-responses.md b/docs/fr/docs/advanced/additional-responses.md index 52a0a0792..38527aad3 100644 --- a/docs/fr/docs/advanced/additional-responses.md +++ b/docs/fr/docs/advanced/additional-responses.md @@ -1,6 +1,6 @@ # Réponses supplémentaires dans OpenAPI -/// warning | "Attention" +/// warning | Attention Ceci concerne un sujet plutôt avancé. @@ -26,11 +26,9 @@ Chacun de ces `dict` de réponse peut avoir une clé `model`, contenant un modè Par exemple, pour déclarer une autre réponse avec un code HTTP `404` et un modèle Pydantic `Message`, vous pouvez écrire : -```Python hl_lines="18 22" -{!../../docs_src/additional_responses/tutorial001.py!} -``` +{* ../../docs_src/additional_responses/tutorial001.py hl[18,22] *} -/// note | "Remarque" +/// note | Remarque Gardez à l'esprit que vous devez renvoyer directement `JSONResponse`. @@ -177,11 +175,9 @@ Vous pouvez utiliser ce même paramètre `responses` pour ajouter différents ty Par exemple, vous pouvez ajouter un type de média supplémentaire `image/png`, en déclarant que votre *opération de chemin* peut renvoyer un objet JSON (avec le type de média `application/json`) ou une image PNG : -```Python hl_lines="19-24 28" -{!../../docs_src/additional_responses/tutorial002.py!} -``` +{* ../../docs_src/additional_responses/tutorial002.py hl[19:24,28] *} -/// note | "Remarque" +/// note | Remarque Notez que vous devez retourner l'image en utilisant directement un `FileResponse`. @@ -207,9 +203,7 @@ Par exemple, vous pouvez déclarer une réponse avec un code HTTP `404` qui util Et une réponse avec un code HTTP `200` qui utilise votre `response_model`, mais inclut un `example` personnalisé : -```Python hl_lines="20-31" -{!../../docs_src/additional_responses/tutorial003.py!} -``` +{* ../../docs_src/additional_responses/tutorial003.py hl[20:31] *} Tout sera combiné et inclus dans votre OpenAPI, et affiché dans la documentation de l'API : @@ -243,9 +237,7 @@ Vous pouvez utiliser cette technique pour réutiliser certaines réponses préd Par exemple: -```Python hl_lines="13-17 26" -{!../../docs_src/additional_responses/tutorial004.py!} -``` +{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *} ## Plus d'informations sur les réponses OpenAPI diff --git a/docs/fr/docs/advanced/additional-status-codes.md b/docs/fr/docs/advanced/additional-status-codes.md index 06a8043ea..c406ae8cb 100644 --- a/docs/fr/docs/advanced/additional-status-codes.md +++ b/docs/fr/docs/advanced/additional-status-codes.md @@ -18,7 +18,7 @@ Pour y parvenir, importez `JSONResponse` et renvoyez-y directement votre contenu {!../../docs_src/additional_status_codes/tutorial001.py!} ``` -/// warning | "Attention" +/// warning | Attention Lorsque vous renvoyez une `Response` directement, comme dans l'exemple ci-dessus, elle sera renvoyée directement. @@ -28,7 +28,7 @@ Assurez-vous qu'il contient les données souhaitées et que les valeurs soient d /// -/// note | "Détails techniques" +/// note | Détails techniques Vous pouvez également utiliser `from starlette.responses import JSONResponse`. diff --git a/docs/fr/docs/advanced/index.md b/docs/fr/docs/advanced/index.md index 198fa8c30..d9d8ad8e6 100644 --- a/docs/fr/docs/advanced/index.md +++ b/docs/fr/docs/advanced/index.md @@ -6,7 +6,7 @@ Le [Tutoriel - Guide de l'utilisateur](../tutorial/index.md){.internal-link targ Dans les sections suivantes, vous verrez des options, configurations et fonctionnalités supplémentaires. -/// note | "Remarque" +/// note | Remarque Les sections de ce chapitre ne sont **pas nécessairement "avancées"**. diff --git a/docs/fr/docs/advanced/path-operation-advanced-configuration.md b/docs/fr/docs/advanced/path-operation-advanced-configuration.md index 94b20b0f3..7daf0fc65 100644 --- a/docs/fr/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/fr/docs/advanced/path-operation-advanced-configuration.md @@ -2,7 +2,7 @@ ## ID d'opération OpenAPI -/// warning | "Attention" +/// warning | Attention Si vous n'êtes pas un "expert" en OpenAPI, vous n'en avez probablement pas besoin. @@ -12,9 +12,7 @@ Dans OpenAPI, les chemins sont des ressources, tels que /users/ ou /items/, expo Vous devez vous assurer qu'il est unique pour chaque opération. -```Python hl_lines="6" -{!../../docs_src/path_operation_advanced_configuration/tutorial001.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *} ### Utilisation du nom *path operation function* comme operationId @@ -22,17 +20,15 @@ Si vous souhaitez utiliser les noms de fonction de vos API comme `operationId`, Vous devriez le faire après avoir ajouté toutes vos *paramètres de chemin*. -```Python hl_lines="2 12-21 24" -{!../../docs_src/path_operation_advanced_configuration/tutorial002.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2,12:21,24] *} -/// tip | "Astuce" +/// tip | Astuce Si vous appelez manuellement `app.openapi()`, vous devez mettre à jour les `operationId` avant. /// -/// warning | "Attention" +/// warning | Attention Pour faire cela, vous devez vous assurer que chacun de vos *chemin* ait un nom unique. @@ -44,9 +40,7 @@ Même s'ils se trouvent dans des modules différents (fichiers Python). Pour exclure un *chemin* du schéma OpenAPI généré (et donc des systèmes de documentation automatiques), utilisez le paramètre `include_in_schema` et assignez-lui la valeur `False` : -```Python hl_lines="6" -{!../../docs_src/path_operation_advanced_configuration/tutorial003.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *} ## Description avancée de docstring @@ -56,9 +50,7 @@ L'ajout d'un `\f` (un caractère d'échappement "form feed") va permettre à **F Il n'apparaîtra pas dans la documentation, mais d'autres outils (tel que Sphinx) pourront utiliser le reste. -```Python hl_lines="19-29" -{!../../docs_src/path_operation_advanced_configuration/tutorial004.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *} ## Réponses supplémentaires @@ -74,7 +66,7 @@ Il y a un chapitre entier ici dans la documentation à ce sujet, vous pouvez le Lorsque vous déclarez un *chemin* dans votre application, **FastAPI** génère automatiquement les métadonnées concernant ce *chemin* à inclure dans le schéma OpenAPI. -/// note | "Détails techniques" +/// note | Détails techniques La spécification OpenAPI appelle ces métadonnées des Objets d'opération. @@ -86,7 +78,7 @@ Il inclut les `tags`, `parameters`, `requestBody`, `responses`, etc. Ce schéma OpenAPI spécifique aux *operations* est normalement généré automatiquement par **FastAPI**, mais vous pouvez également l'étendre. -/// tip | "Astuce" +/// tip | Astuce Si vous avez seulement besoin de déclarer des réponses supplémentaires, un moyen plus pratique de le faire est d'utiliser les [réponses supplémentaires dans OpenAPI](additional-responses.md){.internal-link target=_blank}. @@ -98,9 +90,7 @@ Vous pouvez étendre le schéma OpenAPI pour une *opération de chemin* en utili Cet `openapi_extra` peut être utile, par exemple, pour déclarer [OpenAPI Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions) : -```Python hl_lines="6" -{!../../docs_src/path_operation_advanced_configuration/tutorial005.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial005.py hl[6] *} Si vous ouvrez la documentation automatique de l'API, votre extension apparaîtra au bas du *chemin* spécifique. @@ -147,9 +137,7 @@ Par exemple, vous pouvez décider de lire et de valider la requête avec votre p Vous pouvez le faire avec `openapi_extra` : -```Python hl_lines="20-37 39-40" -{!../../docs_src/path_operation_advanced_configuration/tutorial006.py !} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial006.py hl[20:37,39:40] *} Dans cet exemple, nous n'avons déclaré aucun modèle Pydantic. En fait, le corps de la requête n'est même pas parsé en tant que JSON, il est lu directement en tant que `bytes`, et la fonction `magic_data_reader()` serait chargé de l'analyser d'une manière ou d'une autre. @@ -163,9 +151,7 @@ Et vous pouvez le faire même si le type de données dans la requête n'est pas Dans cet exemple, nous n'utilisons pas les fonctionnalités de FastAPI pour extraire le schéma JSON des modèles Pydantic ni la validation automatique pour JSON. En fait, nous déclarons le type de contenu de la requête en tant que YAML, et non JSON : -```Python hl_lines="17-22 24" -{!../../docs_src/path_operation_advanced_configuration/tutorial007.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[17:22,24] *} Néanmoins, bien que nous n'utilisions pas la fonctionnalité par défaut, nous utilisons toujours un modèle Pydantic pour générer manuellement le schéma JSON pour les données que nous souhaitons recevoir en YAML. @@ -173,11 +159,9 @@ Ensuite, nous utilisons directement la requête et extrayons son contenu en tant Et nous analysons directement ce contenu YAML, puis nous utilisons à nouveau le même modèle Pydantic pour valider le contenu YAML : -```Python hl_lines="26-33" -{!../../docs_src/path_operation_advanced_configuration/tutorial007.py!} -``` +{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[26:33] *} -/// tip | "Astuce" +/// tip | Astuce Ici, nous réutilisons le même modèle Pydantic. diff --git a/docs/fr/docs/advanced/response-directly.md b/docs/fr/docs/advanced/response-directly.md index 80876bc18..4ff883c77 100644 --- a/docs/fr/docs/advanced/response-directly.md +++ b/docs/fr/docs/advanced/response-directly.md @@ -14,7 +14,7 @@ Cela peut être utile, par exemple, pour retourner des en-têtes personnalisés En fait, vous pouvez retourner n'importe quelle `Response` ou n'importe quelle sous-classe de celle-ci. -/// note | "Remarque" +/// note | Remarque `JSONResponse` est elle-même une sous-classe de `Response`. @@ -34,11 +34,9 @@ Par exemple, vous ne pouvez pas mettre un modèle Pydantic dans une `JSONRespons Pour ces cas, vous pouvez spécifier un appel à `jsonable_encoder` pour convertir vos données avant de les passer à une réponse : -```Python hl_lines="6-7 21-22" -{!../../docs_src/response_directly/tutorial001.py!} -``` +{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *} -/// note | "Détails techniques" +/// note | Détails techniques Vous pouvez aussi utiliser `from starlette.responses import JSONResponse`. @@ -56,9 +54,7 @@ Disons que vous voulez retourner une réponse schéma, vous devez utiliser des utilitaires et des classes spécifiques fournies par Marshmallow. -/// check | "A inspiré **FastAPI** à" +/// check | A inspiré **FastAPI** à Utilisez du code pour définir des "schémas" qui fournissent automatiquement les types de données et la validation. @@ -189,7 +189,7 @@ Webargs a été créé par les développeurs de Marshmallow. /// -/// check | "A inspiré **FastAPI** à" +/// check | A inspiré **FastAPI** à Disposer d'une validation automatique des données des requêtes entrantes. @@ -219,7 +219,7 @@ APISpec a été créé par les développeurs de Marshmallow. /// -/// check | "A inspiré **FastAPI** à" +/// check | A inspiré **FastAPI** à Supporter la norme ouverte pour les API, OpenAPI. @@ -252,7 +252,7 @@ Flask-apispec a été créé par les développeurs de Marshmallow. /// -/// check | "A inspiré **FastAPI** à" +/// check | A inspiré **FastAPI** à Générer le schéma OpenAPI automatiquement, à partir du même code qui définit la sérialisation et la validation. @@ -273,7 +273,7 @@ Mais comme les données TypeScript ne sont pas préservées après la compilatio Il ne peut pas très bien gérer les modèles imbriqués. Ainsi, si le corps JSON de la requête est un objet JSON comportant des champs internes qui sont à leur tour des objets JSON imbriqués, il ne peut pas être correctement documenté et validé. -/// check | "A inspiré **FastAPI** à" +/// check | A inspiré **FastAPI** à Utiliser les types Python pour bénéficier d'un excellent support de l'éditeur. @@ -285,7 +285,7 @@ Disposer d'un puissant système d'injection de dépendances. Trouver un moyen de C'était l'un des premiers frameworks Python extrêmement rapides basés sur `asyncio`. Il a été conçu pour être très similaire à Flask. -/// note | "Détails techniques" +/// note | Détails techniques Il utilisait `uvloop` au lieu du système par défaut de Python `asyncio`. C'est ce qui l'a rendu si rapide. @@ -293,7 +293,7 @@ Il a clairement inspiré Uvicorn et Starlette, qui sont actuellement plus rapide /// -/// check | "A inspiré **FastAPI** à" +/// check | A inspiré **FastAPI** à Trouvez un moyen d'avoir une performance folle. @@ -313,7 +313,7 @@ pas possible de déclarer des paramètres de requête et des corps avec des indi Ainsi, la validation, la sérialisation et la documentation des données doivent être effectuées dans le code, et non pas automatiquement. Ou bien elles doivent être implémentées comme un framework au-dessus de Falcon, comme Hug. Cette même distinction se retrouve dans d'autres frameworks qui s'inspirent de la conception de Falcon, qui consiste à avoir un objet de requête et un objet de réponse comme paramètres. -/// check | "A inspiré **FastAPI** à" +/// check | A inspiré **FastAPI** à Trouver des moyens d'obtenir de bonnes performances. @@ -343,7 +343,7 @@ d'utiliser des décorateurs qui peuvent être placés juste au-dessus de la fonc méthode est plus proche de celle de Django que de celle de Flask (et Starlette). Il sépare dans le code des choses qui sont relativement fortement couplées. -/// check | "A inspiré **FastAPI** à" +/// check | A inspiré **FastAPI** à Définir des validations supplémentaires pour les types de données utilisant la valeur "par défaut" des attributs du modèle. Ceci améliore le support de l'éditeur, et n'était pas disponible dans Pydantic auparavant. @@ -372,7 +372,7 @@ Hug a été créé par Timothy Crosley, le créateur de - -```console -$ python -m venv env -``` - - - -Cela va créer un répertoire `./env/` avec les binaires Python et vous pourrez alors installer des paquets pour cet environnement isolé. - -### Activer l'environnement - -Activez le nouvel environnement avec : - -//// tab | Linux, macOS - -
- -```console -$ source ./env/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .\env\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Ou si vous utilisez Bash pour Windows (par exemple Git Bash): - -
- -```console -$ source ./env/Scripts/activate -``` - -
- -//// - -Pour vérifier que cela a fonctionné, utilisez : - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which pip - -some/directory/fastapi/env/bin/pip -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command pip - -some/directory/fastapi/env/bin/pip -``` - -
- -//// - -Si celui-ci montre le binaire `pip` à `env/bin/pip`, alors ça a fonctionné. 🎉 - - - -/// tip - -Chaque fois que vous installez un nouveau paquet avec `pip` sous cet environnement, activez à nouveau l'environnement. - -Cela permet de s'assurer que si vous utilisez un programme terminal installé par ce paquet (comme `flit`), vous utilisez celui de votre environnement local et pas un autre qui pourrait être installé globalement. - -/// - -### Flit - -**FastAPI** utilise Flit pour build, packager et publier le projet. - -Après avoir activé l'environnement comme décrit ci-dessus, installez `flit` : - -
- -```console -$ pip install flit - ----> 100% -``` - -
- -Réactivez maintenant l'environnement pour vous assurer que vous utilisez le "flit" que vous venez d'installer (et non un environnement global). - -Et maintenant, utilisez `flit` pour installer les dépendances de développement : - -//// tab | Linux, macOS - -
- -```console -$ flit install --deps develop --symlink - ----> 100% -``` - -
- -//// - -//// tab | Windows - -Si vous êtes sous Windows, utilisez `--pth-file` au lieu de `--symlink` : - -
- -```console -$ flit install --deps develop --pth-file - ----> 100% -``` - -
- -//// - -Il installera toutes les dépendances et votre FastAPI local dans votre environnement local. - -#### Utiliser votre FastAPI local - -Si vous créez un fichier Python qui importe et utilise FastAPI, et que vous l'exécutez avec le Python de votre environnement local, il utilisera votre code source FastAPI local. - -Et si vous mettez à jour le code source local de FastAPI, tel qu'il est installé avec `--symlink` (ou `--pth-file` sous Windows), lorsque vous exécutez à nouveau ce fichier Python, il utilisera la nouvelle version de FastAPI que vous venez d'éditer. - -De cette façon, vous n'avez pas à "installer" votre version locale pour pouvoir tester chaque changement. - -### Formatage - -Il existe un script que vous pouvez exécuter qui formatera et nettoiera tout votre code : - -
- -```console -$ bash scripts/format.sh -``` - -
- -Il effectuera également un tri automatique de touts vos imports. - -Pour qu'il puisse les trier correctement, vous devez avoir FastAPI installé localement dans votre environnement, avec la commande dans la section ci-dessus en utilisant `--symlink` (ou `--pth-file` sous Windows). - -### Formatage des imports - -Il existe un autre script qui permet de formater touts les imports et de s'assurer que vous n'avez pas d'imports inutilisés : - -
- -```console -$ bash scripts/format-imports.sh -``` - -
- -Comme il exécute une commande après l'autre et modifie et inverse de nombreux fichiers, il prend un peu plus de temps à s'exécuter, il pourrait donc être plus facile d'utiliser fréquemment `scripts/format.sh` et `scripts/format-imports.sh` seulement avant de commit. - -## Documentation - -Tout d'abord, assurez-vous que vous configurez votre environnement comme décrit ci-dessus, qui installera toutes les exigences. - -La documentation utilise MkDocs. - -Et il y a des outils/scripts supplémentaires en place pour gérer les traductions dans `./scripts/docs.py`. - -/// tip - -Vous n'avez pas besoin de voir le code dans `./scripts/docs.py`, vous l'utilisez simplement dans la ligne de commande. - -/// - -Toute la documentation est au format Markdown dans le répertoire `./docs/fr/`. - -De nombreux tutoriels comportent des blocs de code. - -Dans la plupart des cas, ces blocs de code sont de véritables applications complètes qui peuvent être exécutées telles quelles. - -En fait, ces blocs de code ne sont pas écrits à l'intérieur du Markdown, ce sont des fichiers Python dans le répertoire `./docs_src/`. - -Et ces fichiers Python sont inclus/injectés dans la documentation lors de la génération du site. - -### Documentation pour les tests - -La plupart des tests sont en fait effectués par rapport aux exemples de fichiers sources dans la documentation. - -Cela permet de s'assurer que : - -* La documentation est à jour. -* Les exemples de documentation peuvent être exécutés tels quels. -* La plupart des fonctionnalités sont couvertes par la documentation, assurées par la couverture des tests. - -Au cours du développement local, un script build le site et vérifie les changements éventuels, puis il est rechargé en direct : - -
- -```console -$ python ./scripts/docs.py live - -[INFO] Serving on http://127.0.0.1:8008 -[INFO] Start watching changes -[INFO] Start detecting changes -``` - -
- -Il servira la documentation sur `http://127.0.0.1:8008`. - -De cette façon, vous pouvez modifier la documentation/les fichiers sources et voir les changements en direct. - -#### Typer CLI (facultatif) - -Les instructions ici vous montrent comment utiliser le script à `./scripts/docs.py` avec le programme `python` directement. - -Mais vous pouvez également utiliser Typer CLI, et vous obtiendrez l'auto-complétion dans votre terminal pour les commandes après l'achèvement de l'installation. - -Si vous installez Typer CLI, vous pouvez installer la complétion avec : - -
- -```console -$ typer --install-completion - -zsh completion installed in /home/user/.bashrc. -Completion will take effect once you restart the terminal. -``` - -
- -### Apps et documentation en même temps - -Si vous exécutez les exemples avec, par exemple : - -
- -```console -$ uvicorn tutorial001:app --reload - -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -``` - -
- -Comme Uvicorn utilisera par défaut le port `8000`, la documentation sur le port `8008` n'entrera pas en conflit. - -### Traductions - -L'aide aux traductions est TRÈS appréciée ! Et cela ne peut se faire sans l'aide de la communauté. 🌎 🚀 - -Voici les étapes à suivre pour aider à la traduction. - -#### Conseils et lignes directrices - -* Vérifiez les pull requests existantes pour votre langue et ajouter des reviews demandant des changements ou les approuvant. - -/// tip - -Vous pouvez ajouter des commentaires avec des suggestions de changement aux pull requests existantes. - -Consultez les documents concernant l'ajout d'un review de pull request pour l'approuver ou demander des modifications. - -/// - -* Vérifiez dans issues pour voir s'il y a une personne qui coordonne les traductions pour votre langue. - -* Ajoutez une seule pull request par page traduite. Il sera ainsi beaucoup plus facile pour les autres de l'examiner. - -Pour les langues que je ne parle pas, je vais attendre plusieurs autres reviews de la traduction avant de merge. - -* Vous pouvez également vérifier s'il existe des traductions pour votre langue et y ajouter une review, ce qui m'aidera à savoir si la traduction est correcte et je pourrai la fusionner. - -* Utilisez les mêmes exemples en Python et ne traduisez que le texte des documents. Vous n'avez pas besoin de changer quoi que ce soit pour que cela fonctionne. - -* Utilisez les mêmes images, noms de fichiers et liens. Vous n'avez pas besoin de changer quoi que ce soit pour que cela fonctionne. - -* Pour vérifier le code à 2 lettres de la langue que vous souhaitez traduire, vous pouvez utiliser le tableau Liste des codes ISO 639-1. - -#### Langue existante - -Disons que vous voulez traduire une page pour une langue qui a déjà des traductions pour certaines pages, comme l'espagnol. - -Dans le cas de l'espagnol, le code à deux lettres est `es`. Ainsi, le répertoire des traductions espagnoles se trouve à l'adresse `docs/es/`. - -/// tip - -La langue principale ("officielle") est l'anglais, qui se trouve à l'adresse "docs/en/". - -/// - -Maintenant, lancez le serveur en live pour les documents en espagnol : - -
- -```console -// Use the command "live" and pass the language code as a CLI argument -$ python ./scripts/docs.py live es - -[INFO] Serving on http://127.0.0.1:8008 -[INFO] Start watching changes -[INFO] Start detecting changes -``` - -
- -Vous pouvez maintenant aller sur http://127.0.0.1:8008 et voir vos changements en direct. - -Si vous regardez le site web FastAPI docs, vous verrez que chaque langue a toutes les pages. Mais certaines pages ne sont pas traduites et sont accompagnées d'une notification concernant la traduction manquante. - -Mais si vous le gérez localement de cette manière, vous ne verrez que les pages déjà traduites. - -Disons maintenant que vous voulez ajouter une traduction pour la section [Features](features.md){.internal-link target=_blank}. - -* Copiez le fichier à : - -``` -docs/en/docs/features.md -``` - -* Collez-le exactement au même endroit mais pour la langue que vous voulez traduire, par exemple : - -``` -docs/es/docs/features.md -``` - -/// tip - -Notez que le seul changement dans le chemin et le nom du fichier est le code de langue, qui passe de `en` à `es`. - -/// - -* Ouvrez maintenant le fichier de configuration de MkDocs pour l'anglais à - -``` -docs/en/docs/mkdocs.yml -``` - -* Trouvez l'endroit où cette `docs/features.md` se trouve dans le fichier de configuration. Quelque part comme : - -```YAML hl_lines="8" -site_name: FastAPI -# More stuff -nav: -- FastAPI: index.md -- Languages: - - en: / - - es: /es/ -- features.md -``` - -* Ouvrez le fichier de configuration MkDocs pour la langue que vous éditez, par exemple : - -``` -docs/es/docs/mkdocs.yml -``` - -* Ajoutez-le à l'endroit exact où il se trouvait pour l'anglais, par exemple : - -```YAML hl_lines="8" -site_name: FastAPI -# More stuff -nav: -- FastAPI: index.md -- Languages: - - en: / - - es: /es/ -- features.md -``` - -Assurez-vous que s'il y a d'autres entrées, la nouvelle entrée avec votre traduction est exactement dans le même ordre que dans la version anglaise. - -Si vous allez sur votre navigateur, vous verrez que maintenant les documents montrent votre nouvelle section. 🎉 - -Vous pouvez maintenant tout traduire et voir à quoi cela ressemble au fur et à mesure que vous enregistrez le fichier. - -#### Nouvelle langue - -Disons que vous voulez ajouter des traductions pour une langue qui n'est pas encore traduite, pas même quelques pages. - -Disons que vous voulez ajouter des traductions pour le Créole, et que ce n'est pas encore dans les documents. - -En vérifiant le lien ci-dessus, le code pour "Créole" est `ht`. - -L'étape suivante consiste à exécuter le script pour générer un nouveau répertoire de traduction : - -
- -```console -// Use the command new-lang, pass the language code as a CLI argument -$ python ./scripts/docs.py new-lang ht - -Successfully initialized: docs/ht -Updating ht -Updating en -``` - -
- -Vous pouvez maintenant vérifier dans votre éditeur de code le répertoire nouvellement créé `docs/ht/`. - -/// tip - -Créez une première demande d'extraction à l'aide de cette fonction, afin de configurer la nouvelle langue avant d'ajouter des traductions. - -Ainsi, d'autres personnes peuvent vous aider à rédiger d'autres pages pendant que vous travaillez sur la première. 🚀 - -/// - -Commencez par traduire la page principale, `docs/ht/index.md`. - -Vous pouvez ensuite continuer avec les instructions précédentes, pour une "langue existante". - -##### Nouvelle langue non prise en charge - -Si, lors de l'exécution du script du serveur en direct, vous obtenez une erreur indiquant que la langue n'est pas prise en charge, quelque chose comme : - -``` - raise TemplateNotFound(template) -jinja2.exceptions.TemplateNotFound: partials/language/xx.html -``` - -Cela signifie que le thème ne supporte pas cette langue (dans ce cas, avec un faux code de 2 lettres de `xx`). - -Mais ne vous inquiétez pas, vous pouvez définir la langue du thème en anglais et ensuite traduire le contenu des documents. - -Si vous avez besoin de faire cela, modifiez le fichier `mkdocs.yml` pour votre nouvelle langue, il aura quelque chose comme : - -```YAML hl_lines="5" -site_name: FastAPI -# More stuff -theme: - # More stuff - language: xx -``` - -Changez cette langue de `xx` (de votre code de langue) à `fr`. - -Vous pouvez ensuite relancer le serveur live. - -#### Prévisualisez le résultat - -Lorsque vous utilisez le script à `./scripts/docs.py` avec la commande `live`, il n'affiche que les fichiers et les traductions disponibles pour la langue courante. - -Mais une fois que vous avez terminé, vous pouvez tester le tout comme il le ferait en ligne. - -Pour ce faire, il faut d'abord construire tous les documents : - -
- -```console -// Use the command "build-all", this will take a bit -$ python ./scripts/docs.py build-all - -Updating es -Updating en -Building docs for: en -Building docs for: es -Successfully built docs for: es -Copying en index.md to README.md -``` - -
- -Cela génère tous les documents à `./docs_build/` pour chaque langue. Cela inclut l'ajout de tout fichier dont la traduction est manquante, avec une note disant que "ce fichier n'a pas encore de traduction". Mais vous n'avez rien à faire avec ce répertoire. - -Ensuite, il construit tous ces sites MkDocs indépendants pour chaque langue, les combine, et génère le résultat final à `./site/`. - -Ensuite, vous pouvez servir cela avec le commandement `serve`: - -
- -```console -// Use the command "serve" after running "build-all" -$ python ./scripts/docs.py serve - -Warning: this is a very simple server. For development, use mkdocs serve instead. -This is here only to preview a site with translations already built. -Make sure you run the build-all command first. -Serving at: http://127.0.0.1:8008 -``` - -
- -## Tests - -Il existe un script que vous pouvez exécuter localement pour tester tout le code et générer des rapports de couverture en HTML : - -
- -```console -$ bash scripts/test-cov-html.sh -``` - -
- -Cette commande génère un répertoire `./htmlcov/`, si vous ouvrez le fichier `./htmlcov/index.html` dans votre navigateur, vous pouvez explorer interactivement les régions de code qui sont couvertes par les tests, et remarquer s'il y a une région manquante. diff --git a/docs/fr/docs/deployment/docker.md b/docs/fr/docs/deployment/docker.md index 0f3b64700..05b597a2d 100644 --- a/docs/fr/docs/deployment/docker.md +++ b/docs/fr/docs/deployment/docker.md @@ -17,7 +17,7 @@ Cette image est dotée d'un mécanisme d'"auto-tuning", de sorte qu'il vous suff Mais vous pouvez toujours changer et mettre à jour toutes les configurations avec des variables d'environnement ou des fichiers de configuration. -/// tip | "Astuce" +/// tip | Astuce Pour voir toutes les configurations et options, rendez-vous sur la page de l'image Docker : tiangolo/uvicorn-gunicorn-fastapi. diff --git a/docs/fr/docs/deployment/manually.md b/docs/fr/docs/deployment/manually.md index 6a737fdef..7c29242a9 100644 --- a/docs/fr/docs/deployment/manually.md +++ b/docs/fr/docs/deployment/manually.md @@ -39,7 +39,7 @@ $ pip install "uvicorn[standard]" -/// tip | "Astuce" +/// tip | Astuce En ajoutant `standard`, Uvicorn va installer et utiliser quelques dépendances supplémentaires recommandées. diff --git a/docs/fr/docs/deployment/versions.md b/docs/fr/docs/deployment/versions.md index 8ea79a172..9d84274e2 100644 --- a/docs/fr/docs/deployment/versions.md +++ b/docs/fr/docs/deployment/versions.md @@ -48,7 +48,7 @@ des changements non rétrocompatibles. FastAPI suit également la convention que tout changement de version "PATCH" est pour des corrections de bogues et des changements rétrocompatibles. -/// tip | "Astuce" +/// tip | Astuce Le "PATCH" est le dernier chiffre, par exemple, dans `0.2.3`, la version PATCH est `3`. @@ -62,7 +62,7 @@ fastapi>=0.45.0,<0.46.0 Les changements non rétrocompatibles et les nouvelles fonctionnalités sont ajoutés dans les versions "MINOR". -/// tip | "Astuce" +/// tip | Astuce Le "MINOR" est le numéro au milieu, par exemple, dans `0.2.3`, la version MINOR est `2`. diff --git a/docs/fr/docs/python-types.md b/docs/fr/docs/python-types.md index 8a0f1f3f4..99ca90827 100644 --- a/docs/fr/docs/python-types.md +++ b/docs/fr/docs/python-types.md @@ -161,7 +161,7 @@ Les listes étant un type contenant des types internes, mettez ces derniers entr {*../../docs_src/python_types/tutorial006.py hl[4] *} -/// tip | "Astuce" +/// tip | Astuce Ces types internes entre crochets sont appelés des "paramètres de type". diff --git a/docs/fr/docs/tutorial/background-tasks.md b/docs/fr/docs/tutorial/background-tasks.md index e14d5a8e8..2065ca58e 100644 --- a/docs/fr/docs/tutorial/background-tasks.md +++ b/docs/fr/docs/tutorial/background-tasks.md @@ -77,8 +77,6 @@ Si vous avez besoin de réaliser des traitements lourds en tâche d'arrière-pla 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 potentiellement, sur plusieurs serveurs. -Pour voir un exemple, allez voir les [Générateurs de projets](../project-generation.md){.internal-link target=_blank}, ils incluent tous Celery déjà configuré. - 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é diff --git a/docs/fr/docs/tutorial/body-multiple-params.md b/docs/fr/docs/tutorial/body-multiple-params.md index dafd869e3..0541acc74 100644 --- a/docs/fr/docs/tutorial/body-multiple-params.md +++ b/docs/fr/docs/tutorial/body-multiple-params.md @@ -8,57 +8,7 @@ Tout d'abord, sachez que vous pouvez mélanger les déclarations des paramètres Vous pouvez également déclarer des paramètres body comme étant optionnels, en leur assignant une valeur par défaut à `None` : -//// tab | Python 3.10+ - -```Python hl_lines="18-20" -{!> ../../docs_src/body_multiple_params/tutorial001_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="18-20" -{!> ../../docs_src/body_multiple_params/tutorial001_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="19-21" -{!> ../../docs_src/body_multiple_params/tutorial001_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Préférez utiliser la version `Annotated` si possible. - -/// - -```Python hl_lines="17-19" -{!> ../../docs_src/body_multiple_params/tutorial001_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Préférez utiliser la version `Annotated` si possible. - -/// - -```Python hl_lines="19-21" -{!> ../../docs_src/body_multiple_params/tutorial001.py!} -``` - -//// +{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *} /// note @@ -81,21 +31,7 @@ Dans l'exemple précédent, les opérations de routage attendaient un body JSON Mais vous pouvez également déclarer plusieurs paramètres provenant de body, par exemple `item` et `user` simultanément : -//// tab | Python 3.10+ - -```Python hl_lines="20" -{!> ../../docs_src/body_multiple_params/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="22" -{!> ../../docs_src/body_multiple_params/tutorial002.py!} -``` - -//// +{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *} Dans ce cas, **FastAPI** détectera qu'il y a plus d'un paramètre dans le body (chacun correspondant à un modèle Pydantic). @@ -135,57 +71,8 @@ Par exemple, en étendant le modèle précédent, vous pouvez vouloir ajouter un Si vous le déclarez tel quel, comme c'est une valeur [scalaire](https://docs.github.com/fr/graphql/reference/scalars), **FastAPI** supposera qu'il s'agit d'un paramètre de requête (`Query`). Mais vous pouvez indiquer à **FastAPI** de la traiter comme une variable de body en utilisant `Body` : -//// tab | Python 3.10+ -```Python hl_lines="23" -{!> ../../docs_src/body_multiple_params/tutorial003_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="23" -{!> ../../docs_src/body_multiple_params/tutorial003_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="24" -{!> ../../docs_src/body_multiple_params/tutorial003_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Préférez utiliser la version `Annotated` si possible. - -/// - -```Python hl_lines="20" -{!> ../../docs_src/body_multiple_params/tutorial003_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Préférez utiliser la version `Annotated` si possible. - -/// - -```Python hl_lines="22" -{!> ../../docs_src/body_multiple_params/tutorial003.py!} -``` - -//// +{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *} Dans ce cas, **FastAPI** s'attendra à un body semblable à : @@ -225,57 +112,7 @@ q: str | None = None Par exemple : -//// tab | Python 3.10+ - -```Python hl_lines="27" -{!> ../../docs_src/body_multiple_params/tutorial004_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="27" -{!> ../../docs_src/body_multiple_params/tutorial004_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="28" -{!> ../../docs_src/body_multiple_params/tutorial004_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Préférez utiliser la version `Annotated` si possible. - -/// - -```Python hl_lines="25" -{!> ../../docs_src/body_multiple_params/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Préférez utiliser la version `Annotated` si possible. - -/// - -```Python hl_lines="27" -{!> ../../docs_src/body_multiple_params/tutorial004.py!} -``` - -//// +{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[27] *} /// info @@ -297,57 +134,7 @@ item: Item = Body(embed=True) Voici un exemple complet : -//// tab | Python 3.10+ - -```Python hl_lines="17" -{!> ../../docs_src/body_multiple_params/tutorial005_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="17" -{!> ../../docs_src/body_multiple_params/tutorial005_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="18" -{!> ../../docs_src/body_multiple_params/tutorial005_an.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated - -/// tip - -Préférez utiliser la version `Annotated` si possible. - -/// - -```Python hl_lines="15" -{!> ../../docs_src/body_multiple_params/tutorial005_py310.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated - -/// tip - -Préférez utiliser la version `Annotated` si possible. - -/// - -```Python hl_lines="17" -{!> ../../docs_src/body_multiple_params/tutorial005.py!} -``` - -//// +{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *} Dans ce cas **FastAPI** attendra un body semblable à : diff --git a/docs/fr/docs/tutorial/body.md b/docs/fr/docs/tutorial/body.md index c4d493a45..760b6d80a 100644 --- a/docs/fr/docs/tutorial/body.md +++ b/docs/fr/docs/tutorial/body.md @@ -107,7 +107,7 @@ Mais vous auriez le même support de l'éditeur avec -/// tip | "Astuce" +/// tip | Astuce Si vous utilisez PyCharm comme éditeur, vous pouvez utiliser le Plugin Pydantic PyCharm Plugin. diff --git a/docs/fr/docs/tutorial/first-steps.md b/docs/fr/docs/tutorial/first-steps.md index e9511b029..758145362 100644 --- a/docs/fr/docs/tutorial/first-steps.md +++ b/docs/fr/docs/tutorial/first-steps.md @@ -2,9 +2,7 @@ Le fichier **FastAPI** le plus simple possible pourrait ressembler à cela : -```Python -{!../../docs_src/first_steps/tutorial001.py!} -``` +{* ../../docs_src/first_steps/tutorial001.py *} Copiez ce code dans un fichier nommé `main.py`. @@ -134,13 +132,11 @@ Vous pourriez aussi l'utiliser pour générer du code automatiquement, pour les ### Étape 1 : import `FastAPI` -```Python hl_lines="1" -{!../../docs_src/first_steps/tutorial001.py!} -``` +{* ../../docs_src/first_steps/tutorial001.py hl[1] *} `FastAPI` est une classe Python qui fournit toutes les fonctionnalités nécessaires au lancement de votre API. -/// note | "Détails techniques" +/// note | Détails techniques `FastAPI` est une classe héritant directement de `Starlette`. @@ -150,9 +146,7 @@ Vous pouvez donc aussi utiliser toutes les fonctionnalités de opération get -/// info | "`@décorateur` Info" +/// info | `@décorateur` Info Cette syntaxe `@something` en Python est appelée un "décorateur". @@ -286,7 +276,7 @@ Tout comme celles les plus exotiques : * `@app.patch()` * `@app.trace()` -/// tip | "Astuce" +/// tip | Astuce Vous êtes libres d'utiliser chaque opération (méthode HTTP) comme vous le désirez. @@ -306,9 +296,7 @@ Voici notre "**fonction de chemin**" (ou fonction d'opération de chemin) : * **opération** : `get`. * **fonction** : la fonction sous le "décorateur" (sous `@app.get("/")`). -```Python hl_lines="7" -{!../../docs_src/first_steps/tutorial001.py!} -``` +{* ../../docs_src/first_steps/tutorial001.py hl[7] *} C'est une fonction Python. @@ -320,9 +308,7 @@ Ici, c'est une fonction asynchrone (définie avec `async def`). Vous pourriez aussi la définir comme une fonction classique plutôt qu'avec `async def` : -```Python hl_lines="7" -{!../../docs_src/first_steps/tutorial003.py!} -``` +{* ../../docs_src/first_steps/tutorial003.py hl[7] *} /// note @@ -332,9 +318,7 @@ Si vous ne connaissez pas la différence, allez voir la section [Concurrence : * ### Étape 5 : retourner le contenu -```Python hl_lines="8" -{!../../docs_src/first_steps/tutorial001.py!} -``` +{* ../../docs_src/first_steps/tutorial001.py hl[8] *} Vous pouvez retourner un dictionnaire (`dict`), une liste (`list`), des valeurs seules comme des chaines de caractères (`str`) et des entiers (`int`), etc. diff --git a/docs/fr/docs/tutorial/path-params-numeric-validations.md b/docs/fr/docs/tutorial/path-params-numeric-validations.md index b3635fb86..3f3280e64 100644 --- a/docs/fr/docs/tutorial/path-params-numeric-validations.md +++ b/docs/fr/docs/tutorial/path-params-numeric-validations.md @@ -148,7 +148,7 @@ Tous partagent les mêmes paramètres pour des validations supplémentaires et d /// -/// note | "Détails techniques" +/// note | Détails techniques Lorsque vous importez `Query`, `Path` et d'autres de `fastapi`, ce sont en fait des fonctions. diff --git a/docs/fr/docs/tutorial/path-params.md b/docs/fr/docs/tutorial/path-params.md index 34012c278..71c96b18e 100644 --- a/docs/fr/docs/tutorial/path-params.md +++ b/docs/fr/docs/tutorial/path-params.md @@ -4,9 +4,7 @@ Vous pouvez déclarer des "paramètres" ou "variables" de chemin avec la même s formatage de chaîne Python : -```Python hl_lines="6-7" -{!../../docs_src/path_params/tutorial001.py!} -``` +{* ../../docs_src/path_params/tutorial001.py hl[6:7] *} La valeur du paramètre `item_id` sera transmise à la fonction dans l'argument `item_id`. @@ -22,13 +20,11 @@ vous verrez comme réponse : Vous pouvez déclarer le type d'un paramètre de chemin dans la fonction, en utilisant les annotations de type Python : -```Python hl_lines="7" -{!../../docs_src/path_params/tutorial002.py!} -``` +{* ../../docs_src/path_params/tutorial002.py hl[7] *} Ici, `item_id` est déclaré comme `int`. -/// check | "vérifier" +/// check | vérifier Ceci vous permettra d'obtenir des fonctionnalités de l'éditeur dans votre fonction, telles que des vérifications d'erreur, de l'auto-complétion, etc. @@ -43,7 +39,7 @@ Si vous exécutez cet exemple et allez sur http://127.0.0.1:8000/items/4.2. -/// check | "vérifier" +/// check | vérifier Donc, avec ces mêmes déclarations de type Python, **FastAPI** vous fournit de la validation de données. @@ -131,9 +127,7 @@ Et vous avez un second chemin : `/users/{user_id}` pour récupérer de la donné Les *fonctions de chemin* étant évaluées dans l'ordre, il faut s'assurer que la fonction correspondant à `/users/me` est déclarée avant celle de `/users/{user_id}` : -```Python hl_lines="6 11" -{!../../docs_src/path_params/tutorial003.py!} -``` +{* ../../docs_src/path_params/tutorial003.py hl[6,11] *} Sinon, le chemin `/users/{user_id}` correspondrait aussi à `/users/me`, la fonction "croyant" qu'elle a reçu un paramètre `user_id` avec pour valeur `"me"`. @@ -149,9 +143,7 @@ En héritant de `str` la documentation sera capable de savoir que les valeurs do Créez ensuite des attributs de classe avec des valeurs fixes, qui seront les valeurs autorisées pour cette énumération. -```Python hl_lines="1 6-9" -{!../../docs_src/path_params/tutorial005.py!} -``` +{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *} /// info @@ -159,7 +151,7 @@ Créez ensuite des attributs de classe avec des valeurs fixes, qui seront les va /// -/// tip | "Astuce" +/// tip | Astuce Pour ceux qui se demandent, "AlexNet", "ResNet", et "LeNet" sont juste des noms de modèles de Machine Learning. @@ -169,9 +161,7 @@ Pour ceux qui se demandent, "AlexNet", "ResNet", et "LeNet" sont juste des noms Créez ensuite un *paramètre de chemin* avec une annotation de type désignant l'énumération créée précédemment (`ModelName`) : -```Python hl_lines="16" -{!../../docs_src/path_params/tutorial005.py!} -``` +{* ../../docs_src/path_params/tutorial005.py hl[16] *} ### Documentation @@ -187,19 +177,15 @@ La valeur du *paramètre de chemin* sera un des "membres" de l'énumération. Vous pouvez comparer ce paramètre avec les membres de votre énumération `ModelName` : -```Python hl_lines="17" -{!../../docs_src/path_params/tutorial005.py!} -``` +{* ../../docs_src/path_params/tutorial005.py hl[17] *} #### Récupérer la *valeur de l'énumération* Vous pouvez obtenir la valeur réel d'un membre (une chaîne de caractères ici), avec `model_name.value`, ou en général, `votre_membre_d'enum.value` : -```Python hl_lines="20" -{!../../docs_src/path_params/tutorial005.py!} -``` +{* ../../docs_src/path_params/tutorial005.py hl[20] *} -/// tip | "Astuce" +/// tip | Astuce Vous pouvez aussi accéder la valeur `"lenet"` avec `ModelName.lenet.value`. @@ -211,9 +197,7 @@ Vous pouvez retourner des *membres d'énumération* dans vos *fonctions de chemi Ils seront convertis vers leurs valeurs correspondantes (chaînes de caractères ici) avant d'être transmis au client : -```Python hl_lines="18 21 23" -{!../../docs_src/path_params/tutorial005.py!} -``` +{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *} Le client recevra une réponse JSON comme celle-ci : @@ -252,11 +236,9 @@ Dans ce cas, le nom du paramètre est `file_path`, et la dernière partie, `:pat Vous pouvez donc l'utilisez comme tel : -```Python hl_lines="6" -{!../../docs_src/path_params/tutorial004.py!} -``` +{* ../../docs_src/path_params/tutorial004.py hl[6] *} -/// tip | "Astuce" +/// tip | Astuce Vous pourriez avoir besoin que le paramètre contienne `/home/johndoe/myfile.txt`, avec un slash au début (`/`). diff --git a/docs/fr/docs/tutorial/query-params-str-validations.md b/docs/fr/docs/tutorial/query-params-str-validations.md index a3cf76302..c54c0c717 100644 --- a/docs/fr/docs/tutorial/query-params-str-validations.md +++ b/docs/fr/docs/tutorial/query-params-str-validations.md @@ -106,7 +106,7 @@ Disons que vous déclarez le paramètre `q` comme ayant une longueur minimale de {* ../../docs_src/query_params_str_validations/tutorial005.py hl[7] *} -/// note | "Rappel" +/// note | Rappel Avoir une valeur par défaut rend le paramètre optionnel. @@ -171,7 +171,7 @@ Donc la réponse de cette URL serait : } ``` -/// tip | "Astuce" +/// tip | Astuce Pour déclarer un paramètre de requête de type `list`, comme dans l'exemple ci-dessus, il faut explicitement utiliser `Query`, sinon cela sera interprété comme faisant partie du corps de la requête. diff --git a/docs/fr/docs/tutorial/query-params.md b/docs/fr/docs/tutorial/query-params.md index 798f84fa3..b87c26c78 100644 --- a/docs/fr/docs/tutorial/query-params.md +++ b/docs/fr/docs/tutorial/query-params.md @@ -65,7 +65,7 @@ De la même façon, vous pouvez définir des paramètres de requête comme optio Ici, le paramètre `q` sera optionnel, et aura `None` comme valeur par défaut. -/// check | "Remarque" +/// check | Remarque On peut voir que **FastAPI** est capable de détecter que le paramètre de chemin `item_id` est un paramètre de chemin et que `q` n'en est pas un, c'est donc un paramètre de requête. @@ -187,7 +187,7 @@ Ici, on a donc 3 paramètres de requête : * `skip`, un `int` avec comme valeur par défaut `0`. * `limit`, un `int` optionnel. -/// tip | "Astuce" +/// tip | Astuce Vous pouvez utiliser les `Enum`s de la même façon qu'avec les [Paramètres de chemin](path-params.md#valeurs-predefinies){.internal-link target=_blank}. diff --git a/docs/id/docs/tutorial/index.md b/docs/id/docs/tutorial/index.md index f0dee3d73..c01ec9a89 100644 --- a/docs/id/docs/tutorial/index.md +++ b/docs/id/docs/tutorial/index.md @@ -52,7 +52,7 @@ $ pip install "fastapi[all]" ...yang juga termasuk `uvicorn`, yang dapat kamu gunakan sebagai server yang menjalankan kodemu. -/// note | "Catatan" +/// note | Catatan Kamu juga dapat meng-installnya bagian demi bagian. diff --git a/docs/ja/docs/advanced/additional-status-codes.md b/docs/ja/docs/advanced/additional-status-codes.md index 904d539e7..fb3164328 100644 --- a/docs/ja/docs/advanced/additional-status-codes.md +++ b/docs/ja/docs/advanced/additional-status-codes.md @@ -18,7 +18,7 @@ {!../../docs_src/additional_status_codes/tutorial001.py!} ``` -/// warning | "注意" +/// warning | 注意 上記の例のように `Response` を明示的に返す場合、それは直接返されます。 @@ -28,7 +28,7 @@ /// -/// note | "技術詳細" +/// note | 技術詳細 `from starlette.responses import JSONResponse` を利用することもできます。 diff --git a/docs/ja/docs/advanced/custom-response.md b/docs/ja/docs/advanced/custom-response.md index 88269700e..15edc11ad 100644 --- a/docs/ja/docs/advanced/custom-response.md +++ b/docs/ja/docs/advanced/custom-response.md @@ -12,7 +12,7 @@ そしてもし、`Response` が、`JSONResponse` や `UJSONResponse` の場合のようにJSONメディアタイプ (`application/json`) ならば、データは *path operationデコレータ* に宣言したPydantic `response_model` により自動的に変換 (もしくはフィルタ) されます。 -/// note | "備考" +/// note | 備考 メディアタイプを指定せずにレスポンスクラスを利用すると、FastAPIは何もコンテンツがないことを期待します。そのため、生成されるOpenAPIドキュメントにレスポンスフォーマットが記載されません。 @@ -28,7 +28,7 @@ {!../../docs_src/custom_response/tutorial001b.py!} ``` -/// info | "情報" +/// info | 情報 パラメータ `response_class` は、レスポンスの「メディアタイプ」を定義するために利用することもできます。 @@ -38,7 +38,7 @@ /// -/// tip | "豆知識" +/// tip | 豆知識 `ORJSONResponse` は、現在はFastAPIのみで利用可能で、Starletteでは利用できません。 @@ -55,7 +55,7 @@ {!../../docs_src/custom_response/tutorial002.py!} ``` -/// info | "情報" +/// info | 情報 パラメータ `response_class` は、レスポンスの「メディアタイプ」を定義するために利用されます。 @@ -75,13 +75,13 @@ {!../../docs_src/custom_response/tutorial003.py!} ``` -/// warning | "注意" +/// warning | 注意 *path operation関数* から直接返される `Response` は、OpenAPIにドキュメントされず (例えば、 `Content-Type` がドキュメントされない) 、自動的な対話的ドキュメントからも閲覧できません。 /// -/// info | "情報" +/// info | 情報 もちろん、実際の `Content-Type` ヘッダーやステータスコードなどは、返された `Response` オブジェクトに由来しています。 @@ -115,7 +115,7 @@ `Response` を使って他の何かを返せますし、カスタムのサブクラスも作れることを覚えておいてください。 -/// note | "技術詳細" +/// note | 技術詳細 `from starlette.responses import HTMLResponse` も利用できます。 @@ -168,7 +168,7 @@ FastAPI (実際にはStarlette) は自動的にContent-Lengthヘッダーを含 `ujson`を使った、代替のJSONレスポンスです。 -/// warning | "注意" +/// warning | 注意 `ujson` は、いくつかのエッジケースの取り扱いについて、Pythonにビルトインされた実装よりも作りこまれていません。 @@ -178,7 +178,7 @@ FastAPI (実際にはStarlette) は自動的にContent-Lengthヘッダーを含 {!../../docs_src/custom_response/tutorial001.py!} ``` -/// tip | "豆知識" +/// tip | 豆知識 `ORJSONResponse` のほうが高速な代替かもしれません。 @@ -210,7 +210,7 @@ HTTPリダイレクトを返します。デフォルトでは307ステータス {!../../docs_src/custom_response/tutorial008.py!} ``` -/// tip | "豆知識" +/// tip | 豆知識 ここでは `async` や `await` をサポートしていない標準の `open()` を使っているので、通常の `def` でpath operationを宣言していることに注意してください。 @@ -245,7 +245,7 @@ HTTPリダイレクトを返します。デフォルトでは307ステータス {!../../docs_src/custom_response/tutorial010.py!} ``` -/// tip | "豆知識" +/// tip | 豆知識 前に見たように、 *path operation* の中で `response_class` をオーバーライドできます。 diff --git a/docs/ja/docs/advanced/index.md b/docs/ja/docs/advanced/index.md index da3c2a2bf..22eaf6eb8 100644 --- a/docs/ja/docs/advanced/index.md +++ b/docs/ja/docs/advanced/index.md @@ -6,7 +6,7 @@ 以降のセクションでは、チュートリアルでは説明しきれなかったオプションや設定、および機能について説明します。 -/// tip | "豆知識" +/// tip | 豆知識 以降のセクションは、 **必ずしも"応用編"ではありません**。 diff --git a/docs/ja/docs/advanced/path-operation-advanced-configuration.md b/docs/ja/docs/advanced/path-operation-advanced-configuration.md index 2dab4aec1..99428bcbe 100644 --- a/docs/ja/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/ja/docs/advanced/path-operation-advanced-configuration.md @@ -2,7 +2,7 @@ ## OpenAPI operationId -/// warning | "注意" +/// warning | 注意 あなたがOpenAPIの「エキスパート」でなければ、これは必要ないかもしれません。 @@ -26,13 +26,13 @@ APIの関数名を `operationId` として利用したい場合、すべてのAP {!../../docs_src/path_operation_advanced_configuration/tutorial002.py!} ``` -/// tip | "豆知識" +/// tip | 豆知識 `app.openapi()` を手動でコールする場合、その前に`operationId`を更新する必要があります。 /// -/// warning | "注意" +/// warning | 注意 この方法をとる場合、各 *path operation関数* が一意な名前である必要があります。 diff --git a/docs/ja/docs/advanced/response-directly.md b/docs/ja/docs/advanced/response-directly.md index 167d15589..dc66e238c 100644 --- a/docs/ja/docs/advanced/response-directly.md +++ b/docs/ja/docs/advanced/response-directly.md @@ -14,7 +14,7 @@ 実際は、`Response` やそのサブクラスを返すことができます。 -/// tip | "豆知識" +/// tip | 豆知識 `JSONResponse` それ自体は、 `Response` のサブクラスです。 @@ -38,7 +38,7 @@ {!../../docs_src/response_directly/tutorial001.py!} ``` -/// note | "技術詳細" +/// note | 技術詳細 また、`from starlette.responses import JSONResponse` も利用できます。 diff --git a/docs/ja/docs/advanced/websockets.md b/docs/ja/docs/advanced/websockets.md index f7bcb6af3..365ceca9d 100644 --- a/docs/ja/docs/advanced/websockets.md +++ b/docs/ja/docs/advanced/websockets.md @@ -50,7 +50,7 @@ $ pip install websockets {!../../docs_src/websockets/tutorial001.py!} ``` -/// note | "技術詳細" +/// note | 技術詳細 `from starlette.websockets import WebSocket` を使用しても構いません. @@ -119,7 +119,7 @@ WebSocketエンドポイントでは、`fastapi` から以下をインポート {!../../docs_src/websockets/tutorial002.py!} ``` -/// info | "情報" +/// info | 情報 WebSocket で `HTTPException` を発生させることはあまり意味がありません。したがって、WebSocketの接続を直接閉じる方がよいでしょう。 @@ -150,7 +150,7 @@ $ uvicorn main:app --reload * パスで使用される「Item ID」 * クエリパラメータとして使用される「Token」 -/// tip | "豆知識" +/// tip | 豆知識 クエリ `token` は依存パッケージによって処理されることに注意してください。 @@ -180,7 +180,7 @@ WebSocket接続が閉じられると、 `await websocket.receive_text()` は例 Client #1596980209979 left the chat ``` -/// tip | "豆知識" +/// tip | 豆知識 上記のアプリは、複数の WebSocket 接続に対してメッセージを処理し、ブロードキャストする方法を示すための最小限のシンプルな例です。 diff --git a/docs/ja/docs/alternatives.md b/docs/ja/docs/alternatives.md index 343ae4ed8..8129a7002 100644 --- a/docs/ja/docs/alternatives.md +++ b/docs/ja/docs/alternatives.md @@ -30,13 +30,13 @@ Mozilla、Red Hat、Eventbrite など多くの企業で利用されています これは**自動的なAPIドキュメント生成**の最初の例であり、これは**FastAPI**に向けた「調査」を触発した最初のアイデアの一つでした。 -/// note | "備考" +/// note | 備考 Django REST Framework は Tom Christie によって作成されました。StarletteとUvicornの生みの親であり、**FastAPI**のベースとなっています。 /// -/// check | "**FastAPI**へ与えたインスピレーション" +/// check | **FastAPI**へ与えたインスピレーション 自動でAPIドキュメントを生成するWebユーザーインターフェースを持っている点。 @@ -56,7 +56,7 @@ Flask は「マイクロフレームワーク」であり、データベース Flaskのシンプルさを考えると、APIを構築するのに適しているように思えました。次に見つけるべきは、Flask 用の「Django REST Framework」でした。 -/// check | "**FastAPI**へ与えたインスピレーション" +/// check | **FastAPI**へ与えたインスピレーション マイクロフレームワークであること。ツールやパーツを目的に合うように簡単に組み合わせられる点。 @@ -98,7 +98,7 @@ def read_url(): `requests.get(...)` と`@app.get(...)` には類似点が見受けられます。 -/// check | "**FastAPI**へ与えたインスピレーション" +/// check | **FastAPI**へ与えたインスピレーション * シンプルで直感的なAPIを持っている点。 * HTTPメソッド名を直接利用し、単純で直感的である。 @@ -118,7 +118,7 @@ def read_url(): そのため、バージョン2.0では「Swagger」、バージョン3以上では「OpenAPI」と表記するのが一般的です。 -/// check | "**FastAPI**へ与えたインスピレーション" +/// check | **FastAPI**へ与えたインスピレーション 独自のスキーマの代わりに、API仕様のオープンな標準を採用しました。 @@ -147,7 +147,7 @@ APIが必要とするもう一つの大きな機能はデータのバリデー しかし、それはPythonの型ヒントが存在する前に作られたものです。そのため、すべてのスキーマを定義するためには、Marshmallowが提供する特定のユーティリティやクラスを使用する必要があります。 -/// check | "**FastAPI**へ与えたインスピレーション" +/// check | **FastAPI**へ与えたインスピレーション コードで「スキーマ」を定義し、データの型やバリデーションを自動で提供する点。 @@ -163,13 +163,13 @@ WebargsはFlaskをはじめとするいくつかのフレームワークの上 素晴らしいツールで、私も**FastAPI**を持つ前はよく使っていました。 -/// info | "情報" +/// info | 情報 Webargsは、Marshmallowと同じ開発者により作られました。 /// -/// check | "**FastAPI**へ与えたインスピレーション" +/// check | **FastAPI**へ与えたインスピレーション 受信したデータに対する自動的なバリデーションを持っている点。 @@ -193,13 +193,13 @@ Flask, Starlette, Responderなどにおいてはそのように動作します エディタでは、この問題を解決することはできません。また、パラメータやMarshmallowスキーマを変更したときに、YAMLのdocstringを変更するのを忘れてしまうと、生成されたスキーマが古くなってしまいます。 -/// info | "情報" +/// info | 情報 APISpecは、Marshmallowと同じ開発者により作成されました。 /// -/// check | "**FastAPI**へ与えたインスピレーション" +/// check | **FastAPI**へ与えたインスピレーション OpenAPIという、APIについてのオープンな標準をサポートしている点。 @@ -225,13 +225,13 @@ Flask、Flask-apispec、Marshmallow、Webargsの組み合わせは、**FastAPI** そして、これらのフルスタックジェネレーターは、[**FastAPI** Project Generators](project-generation.md){.internal-link target=_blank}の元となっていました。 -/// info | "情報" +/// info | 情報 Flask-apispecはMarshmallowと同じ開発者により作成されました。 /// -/// check | "**FastAPI**へ与えたインスピレーション" +/// check | **FastAPI**へ与えたインスピレーション シリアライゼーションとバリデーションを定義したコードから、OpenAPIスキーマを自動的に生成する点。 @@ -251,7 +251,7 @@ Angular 2にインスピレーションを受けた、統合された依存性 入れ子になったモデルをうまく扱えません。そのため、リクエストのJSONボディが内部フィールドを持つJSONオブジェクトで、それが順番にネストされたJSONオブジェクトになっている場合、適切にドキュメント化やバリデーションをすることができません。 -/// check | "**FastAPI**へ与えたインスピレーション" +/// check | **FastAPI**へ与えたインスピレーション 素晴らしいエディターの補助を得るために、Pythonの型ヒントを利用している点。 @@ -263,7 +263,7 @@ Angular 2にインスピレーションを受けた、統合された依存性 `asyncio`に基づいた、Pythonのフレームワークの中でも非常に高速なものの一つです。Flaskと非常に似た作りになっています。 -/// note | "技術詳細" +/// note | 技術詳細 Pythonの`asyncio`ループの代わりに、`uvloop`が利用されています。それにより、非常に高速です。 @@ -271,7 +271,7 @@ Pythonの`asyncio`ループの代わりに、`uvloop`が利用されています /// -/// check | "**FastAPI**へ与えたインスピレーション" +/// check | **FastAPI**へ与えたインスピレーション 物凄い性能を出す方法を見つけた点。 @@ -289,7 +289,7 @@ Pythonのウェブフレームワーク標準規格 (WSGI) を使用していま そのため、データのバリデーション、シリアライゼーション、ドキュメント化は、自動的にできずコードの中で行わなければなりません。あるいは、HugのようにFalconの上にフレームワークとして実装されなければなりません。このような分断は、パラメータとして1つのリクエストオブジェクトと1つのレスポンスオブジェクトを持つというFalconのデザインにインスピレーションを受けた他のフレームワークでも起こります。 -/// check | "**FastAPI**へ与えたインスピレーション" +/// check | **FastAPI**へ与えたインスピレーション 素晴らしい性能を得るための方法を見つけた点。 @@ -315,7 +315,7 @@ Pydanticのようなデータのバリデーション、シリアライゼーシ ルーティングは一つの場所で宣言され、他の場所で宣言された関数を使用します (エンドポイントを扱う関数のすぐ上に配置できるデコレータを使用するのではなく) 。これはFlask (やStarlette) よりも、Djangoに近いです。これは、比較的緊密に結合されているものをコードの中で分離しています。 -/// check | "**FastAPI**へ与えたインスピレーション" +/// check | **FastAPI**へ与えたインスピレーション モデルの属性の「デフォルト」値を使用したデータ型の追加バリデーションを定義します。これはエディタの補助を改善するもので、以前はPydanticでは利用できませんでした。 @@ -337,13 +337,13 @@ OpenAPIやJSON Schemaのような標準に基づいたものではありませ 以前のPythonの同期型Webフレームワーク標準 (WSGI) をベースにしているため、Websocketなどは扱えませんが、それでも高性能です。 -/// info | "情報" +/// info | 情報 HugはTimothy Crosleyにより作成されました。彼は`isort`など、Pythonのファイル内のインポートの並び替えを自動的におこうなう素晴らしいツールの開発者です。 /// -/// check | "**FastAPI**へ与えたインスピレーション" +/// check | **FastAPI**へ与えたインスピレーション HugはAPIStarに部分的なインスピレーションを与えており、私が発見した中ではAPIStarと同様に最も期待の持てるツールの一つでした。 @@ -377,7 +377,7 @@ Hugは、**FastAPI**がヘッダーやクッキーを設定するために関数 今ではAPIStarはOpenAPI仕様を検証するためのツールセットであり、ウェブフレームワークではありません。 -/// info | "情報" +/// info | 情報 APIStarはTom Christieにより開発されました。以下の開発者でもあります: @@ -387,7 +387,7 @@ APIStarはTom Christieにより開発されました。以下の開発者でも /// -/// check | "**FastAPI**へ与えたインスピレーション" +/// check | **FastAPI**へ与えたインスピレーション 存在そのもの。 @@ -411,7 +411,7 @@ Pydanticは、Pythonの型ヒントを元にデータのバリデーション、 Marshmallowに匹敵しますが、ベンチマークではMarshmallowよりも高速です。また、Pythonの型ヒントを元にしているので、エディタの補助が素晴らしいです。 -/// check | "**FastAPI**での使用用途" +/// check | **FastAPI**での使用用途 データのバリデーション、データのシリアライゼーション、自動的なモデルの (JSON Schemaに基づいた) ドキュメント化の全てを扱えます。 @@ -447,7 +447,7 @@ Starletteは基本的なWebマイクロフレームワークの機能をすべ これは **FastAPI** が追加する主な機能の一つで、すべての機能は Pythonの型ヒントに基づいています (Pydanticを使用しています) 。これに加えて、依存性注入の仕組み、セキュリティユーティリティ、OpenAPIスキーマ生成などがあります。 -/// note | "技術詳細" +/// note | 技術詳細 ASGIはDjangoのコアチームメンバーにより開発された新しい「標準」です。まだ「Pythonの標準 (PEP) 」ではありませんが、現在そうなるように進めています。 @@ -455,7 +455,7 @@ ASGIはDjangoのコアチームメンバーにより開発された新しい「 /// -/// check | "**FastAPI**での使用用途" +/// check | **FastAPI**での使用用途 webに関するコアな部分を全て扱います。その上に機能を追加します。 @@ -473,7 +473,7 @@ Uvicornは非常に高速なASGIサーバーで、uvloopとhttptoolsにより構 Starletteや**FastAPI**のサーバーとして推奨されています。 -/// check | "**FastAPI**が推奨する理由" +/// check | **FastAPI**が推奨する理由 **FastAPI**アプリケーションを実行するメインのウェブサーバーである点。 diff --git a/docs/ja/docs/async.md b/docs/ja/docs/async.md index ce9dac56f..d1da1f82d 100644 --- a/docs/ja/docs/async.md +++ b/docs/ja/docs/async.md @@ -21,7 +21,7 @@ async def read_results(): return results ``` -/// note | "備考" +/// note | 備考 `async def` を使用して作成された関数の内部でしか `await` は使用できません。 @@ -358,7 +358,7 @@ async def read_burgers(): ## 非常に発展的な技術的詳細 -/// warning | "注意" +/// warning | 注意 恐らくスキップしても良いでしょう。 diff --git a/docs/ja/docs/contributing.md b/docs/ja/docs/contributing.md deleted file mode 100644 index 86926b213..000000000 --- a/docs/ja/docs/contributing.md +++ /dev/null @@ -1,498 +0,0 @@ -# 開発 - 貢献 - -まず、[FastAPIを応援 - ヘルプの入手](help-fastapi.md){.internal-link target=_blank}の基本的な方法を見て、ヘルプを得た方がいいかもしれません。 - -## 開発 - -すでにリポジトリをクローンし、コードを詳しく調べる必要があるとわかっている場合に、環境構築のためのガイドラインをいくつか紹介します。 - -### `venv`を使用した仮想環境 - -Pythonの`venv`モジュールを使用して、ディレクトリに仮想環境を作成します: - -
- -```console -$ python -m venv env -``` - -
- -これにより、Pythonバイナリを含む`./env/`ディレクトリが作成され、その隔離された環境にパッケージのインストールが可能になります。 - -### 仮想環境の有効化 - -新しい環境を有効化するには: - -//// tab | Linux, macOS - -
- -```console -$ source ./env/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .\env\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -もしwindows用のBash (例えば、Git Bash)を使っているなら: - -
- -```console -$ source ./env/Scripts/activate -``` - -
- -//// - -動作の確認には、下記を実行します: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which pip - -some/directory/fastapi/env/bin/pip -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command pip - -some/directory/fastapi/env/bin/pip -``` - -
- -//// - -`env/bin/pip`に`pip`バイナリが表示される場合は、正常に機能しています。🎉 - - -/// tip | "豆知識" - -この環境で`pip`を使って新しいパッケージをインストールするたびに、仮想環境を再度有効化します。 - -これにより、そのパッケージによってインストールされたターミナルのプログラム を使用する場合、ローカル環境のものを使用し、グローバルにインストールされたものは使用されなくなります。 - -/// - -### pip - -上記のように環境を有効化した後: - -
- -```console -$ pip install -r requirements.txt - ----> 100% -``` - -
- -これで、すべての依存関係とFastAPIを、ローカル環境にインストールします。 - -#### ローカル環境でFastAPIを使う - -FastAPIをインポートして使用するPythonファイルを作成し、ローカル環境で実行すると、ローカルのFastAPIソースコードが使用されます。 - -そして、`-e` でインストールされているローカルのFastAPIソースコードを更新した場合、そのPythonファイルを再度実行すると、更新したばかりの新しいバージョンのFastAPIが使用されます。 - -これにより、ローカルバージョンを「インストール」しなくても、すべての変更をテストできます。 - -### コードの整形 - -すべてのコードを整形してクリーンにするスクリプトがあります: - -
- -```console -$ bash scripts/format.sh -``` - -
- -また、すべてのインポートを自動でソートします。 - -正しく並べ替えるには、上記セクションのコマンドで `-e` を使い、FastAPIをローカル環境にインストールしている必要があります。 - -### インポートの整形 - -他にも、すべてのインポートを整形し、未使用のインポートがないことを確認するスクリプトがあります: - -
- -```console -$ bash scripts/format-imports.sh -``` - -
- -多くのファイルを編集したり、リバートした後、これらのコマンドを実行すると、少し時間がかかります。なので`scripts/format.sh`を頻繁に使用し、`scripts/format-imports.sh`をコミット前に実行する方が楽でしょう。 - -## ドキュメント - -まず、上記のように環境をセットアップしてください。すべての必要なパッケージがインストールされます。 - -ドキュメントは、MkDocsを使っています。 - -そして、翻訳を処理するためのツール/スクリプトが、`./scripts/docs.py`に用意されています。 - -/// tip | "豆知識" - -`./scripts/docs.py`のコードを見る必要はなく、コマンドラインからただ使うだけです。 - -/// - -すべてのドキュメントが、Markdown形式で`./docs/en/`ディレクトリにあります。 - -多くのチュートリアルには、コードブロックがあります。 - -ほとんどの場合、これらのコードブロックは、実際にそのまま実行できる完全なアプリケーションです。 - -実際、これらのコードブロックはMarkdown内には記述されておらず、`./docs_src/`ディレクトリのPythonファイルです。 - -そして、これらのPythonファイルは、サイトの生成時にドキュメントに含まれるか/挿入されます。 - -### ドキュメントのテスト - -ほとんどのテストは、実際にドキュメント内のサンプルソースファイルに対して実行されます。 - -これにより、次のことが確認できます: - -* ドキュメントが最新であること。 -* ドキュメントの例が、そのまま実行できること。 -* ほとんどの機能がドキュメントでカバーされており、テスト範囲で保証されていること。 - -ローカル開発中に、サイトを構築して変更がないかチェックするスクリプトがあり、ライブリロードされます: - -
- -```console -$ python ./scripts/docs.py live - -[INFO] Serving on http://127.0.0.1:8008 -[INFO] Start watching changes -[INFO] Start detecting changes -``` - -
- -ドキュメントは、`http://127.0.0.1:8008`で提供します。 - -そうすることで、ドキュメント/ソースファイルを編集し、変更をライブで見ることができます。 - -#### Typer CLI (任意) - -ここでは、`./scripts/docs.py`のスクリプトを`python`プログラムで直接使う方法を説明します。 - -ですがTyper CLIを使用して、インストール完了後にターミナルでの自動補完もできます。 - -Typer CLIをインストールする場合、次のコマンドで補完をインストールできます: - -
- -```console -$ typer --install-completion - -zsh completion installed in /home/user/.bashrc. -Completion will take effect once you restart the terminal. -``` - -
- -### アプリとドキュメントを同時に - -以下の様にサンプルを実行すると: - -
- -```console -$ uvicorn tutorial001:app --reload - -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -``` - -
- -Uvicornはデフォルトでポート`8000`を使用するため、ポート`8008`のドキュメントは衝突しません。 - -### 翻訳 - -翻訳のヘルプをとても歓迎しています！これはコミュニティの助けなしでは成し遂げられません。 🌎🚀 - -翻訳を支援するための手順は次のとおりです。 - -#### 豆知識とガイドライン - -* あなたの言語の今あるプルリクエストを確認し、変更や承認をするレビューを追加します。 - -/// tip | "豆知識" - -すでにあるプルリクエストに修正提案つきのコメントを追加できます。 - -修正提案の承認のためにプルリクエストのレビューの追加のドキュメントを確認してください。 - -/// - -* issuesをチェックして、あなたの言語に対応する翻訳があるかどうかを確認してください。 - -* 翻訳したページごとに1つのプルリクエストを追加します。これにより、他のユーザーがレビューしやすくなります。 - -私が話さない言語については、他の何人かが翻訳をレビューするのを待って、マージします。 - -* 自分の言語の翻訳があるかどうか確認し、レビューを追加できます。これにより、翻訳が正しく、マージできることがわかります。 - -* 同じPythonの例を使用し、ドキュメント内のテキストのみを翻訳してください。何も変更する必要はありません。 - -* 同じ画像、ファイル名、リンクを使用します。何も変更する必要はありません。 - -* 翻訳する言語の2文字のコードを確認するには、表 ISO 639-1コードのリストが使用できます。 - -#### すでにある言語 - -スペイン語の様に、既に一部のページが翻訳されている言語の翻訳を追加したいとしましょう。 - -スペイン語の場合、2文字のコードは`es`です。したがって、スペイン語のディレクトリは`docs/es/`です。 - -/// tip | "豆知識" - -メイン (「公式」) 言語は英語で、`docs/en/`にあります。 - -/// - -次に、ドキュメントのライブサーバーをスペイン語で実行します: - -
- -```console -// コマンド"live"を使用し、言語コードをCLIに引数で渡します。 -$ python ./scripts/docs.py live es - -[INFO] Serving on http://127.0.0.1:8008 -[INFO] Start watching changes -[INFO] Start detecting changes -``` - -
- -これでhttp://127.0.0.1:8008 を開いて、変更を確認できます。 - -FastAPI docs Webサイトを見ると、すべての言語にすべてのページがあります。しかし、一部のページは翻訳されておらず、翻訳の欠落ページについて通知があります。 - -しかし、このようにローカルで実行すると、翻訳済みのページのみが表示されます。 - -ここで、セクション[Features](features.md){.internal-link target=_blank}の翻訳を追加するとします。 - -* 下記のファイルをコピーします: - -``` -docs/en/docs/features.md -``` - -* 翻訳したい言語のまったく同じところに貼り付けます。例えば: - -``` -docs/es/docs/features.md -``` - -/// tip | "豆知識" - -パスとファイル名の変更は、`en`から`es`への言語コードだけであることに注意してください。 - -/// - -* ここで、英語のMkDocs構成ファイルを開きます: - -``` -docs/en/docs/mkdocs.yml -``` - -* 設定ファイルの中で、`docs/features.md`が記述されている箇所を見つけます: - -```YAML hl_lines="8" -site_name: FastAPI -# More stuff -nav: -- FastAPI: index.md -- Languages: - - en: / - - es: /es/ -- features.md -``` - -* 編集している言語のMkDocs構成ファイルを開きます。例えば: - -``` -docs/es/docs/mkdocs.yml -``` - -* 英語とまったく同じ場所に追加します。例えば: - -```YAML hl_lines="8" -site_name: FastAPI -# More stuff -nav: -- FastAPI: index.md -- Languages: - - en: / - - es: /es/ -- features.md -``` - -他のエントリがある場合は、翻訳を含む新しいエントリが英語版とまったく同じ順序になっていることを確認してください。 - -ブラウザにアクセスすれば、ドキュメントに新しいセクションが表示されています。 🎉 - -これですべて翻訳して、ファイルを保存した状態を確認できます。 - -#### 新しい言語 - -まだ翻訳されていない言語の翻訳を追加したいとしましょう。 - -クレオール語の翻訳を追加したいのですが、それはまだドキュメントにありません。 - -上記のリンクを確認すると、「クレオール語」のコードは`ht`です。 - -次のステップは、スクリプトを実行して新しい翻訳ディレクトリを生成することです: - -
- -```console -// コマンド「new-lang」を使用して、言語コードをCLIに引数で渡します -$ python ./scripts/docs.py new-lang ht - -Successfully initialized: docs/ht -Updating ht -Updating en -``` - -
- -これで、新しく作成された`docs/ht/`ディレクトリをコードエディターから確認できます。 - -/// tip | "豆知識" - -翻訳を追加する前に、これだけで最初のプルリクエストを作成し、新しい言語の設定をセットアップします。 - -そうすることで、最初のページで作業している間、誰かの他のページの作業を助けることができます。 🚀 - -/// - -まず、メインページの`docs/ht/index.md`を翻訳します。 - -その後、「既存の言語」で、さきほどの手順を続行してください。 - -##### まだサポートされていない新しい言語 - -ライブサーバースクリプトを実行するときに、サポートされていない言語に関するエラーが発生した場合は、次のように表示されます: - -``` - raise TemplateNotFound(template) -jinja2.exceptions.TemplateNotFound: partials/language/xx.html -``` - -これは、テーマがその言語をサポートしていないことを意味します (この場合は、`xx`の2文字の偽のコード) 。 - -ただし、心配しないでください。テーマ言語を英語に設定して、ドキュメントの内容を翻訳できます。 - -その必要がある場合は、新しい言語の`mkdocs.yml`を次のように編集してください: - -```YAML hl_lines="5" -site_name: FastAPI -# More stuff -theme: - # More stuff - language: xx -``` - -その言語を`xx` (あなたの言語コード) から`en`に変更します。 - -その後、ライブサーバーを再起動します。 - -#### 結果のプレビュー - -`./scripts/docs.py`のスクリプトを`live`コマンドで使用すると、現在の言語で利用可能なファイルと翻訳のみが表示されます。 - -しかし一度実行したら、オンラインで表示されるのと同じように、すべてをテストできます。 - -このために、まずすべてのドキュメントをビルドします: - -
- -```console -// 「build-all」コマンドは少し時間がかかります。 -$ python ./scripts/docs.py build-all - -Updating es -Updating en -Building docs for: en -Building docs for: es -Successfully built docs for: es -Copying en index.md to README.md -``` - -
- -これで、言語ごとにすべてのドキュメントが`./docs_build/`に作成されます。 - -これには、翻訳が欠落しているファイルを追加することと、「このファイルにはまだ翻訳がない」というメモが含まれます。ただし、そのディレクトリで何もする必要はありません。 - -次に、言語ごとにこれらすべての個別のMkDocsサイトを構築し、それらを組み合わせて、`./site/`に最終結果を出力します。 - -これは、コマンド`serve`で提供できます: - -
- -```console -// 「build-all」コマンドの実行の後に、「serve」コマンドを使います -$ python ./scripts/docs.py serve - -Warning: this is a very simple server. For development, use mkdocs serve instead. -This is here only to preview a site with translations already built. -Make sure you run the build-all command first. -Serving at: http://127.0.0.1:8008 -``` - -
- -## テスト - -すべてのコードをテストし、HTMLでカバレッジレポートを生成するためにローカルで実行できるスクリプトがあります: - -
- -```console -$ bash scripts/test-cov-html.sh -``` - -
- -このコマンドは`./htmlcov/`ディレクトリを生成します。ブラウザでファイル`./htmlcov/index.html`を開くと、テストでカバーされているコードの領域をインタラクティブに探索できます。それによりテストが不足しているかどうか気付くことができます。 diff --git a/docs/ja/docs/deployment/manually.md b/docs/ja/docs/deployment/manually.md index c17e63728..4ea6bd8ff 100644 --- a/docs/ja/docs/deployment/manually.md +++ b/docs/ja/docs/deployment/manually.md @@ -20,7 +20,7 @@ $ pip install "uvicorn[standard]" //// -/// tip | "豆知識" +/// tip | 豆知識 `standard` を加えることで、Uvicornがインストールされ、いくつかの推奨される依存関係を利用するようになります。 diff --git a/docs/ja/docs/deployment/versions.md b/docs/ja/docs/deployment/versions.md index 941ddb71b..7575fc4f7 100644 --- a/docs/ja/docs/deployment/versions.md +++ b/docs/ja/docs/deployment/versions.md @@ -42,7 +42,7 @@ PoetryやPipenvなど、他のインストール管理ツールを使用して FastAPIでは「パッチ」バージョンはバグ修正と非破壊的な変更に留めるという規約に従っています。 -/// tip | "豆知識" +/// tip | 豆知識 「パッチ」は最後の数字を指します。例えば、`0.2.3` ではパッチバージョンは `3` です。 @@ -56,7 +56,7 @@ fastapi>=0.45.0,<0.46.0 破壊的な変更と新機能実装は「マイナー」バージョンで加えられます。 -/// tip | "豆知識" +/// tip | 豆知識 「マイナー」は真ん中の数字です。例えば、`0.2.3` ではマイナーバージョンは `2` です。 diff --git a/docs/ja/docs/features.md b/docs/ja/docs/features.md index 73c0192c7..4024590cf 100644 --- a/docs/ja/docs/features.md +++ b/docs/ja/docs/features.md @@ -62,7 +62,7 @@ second_user_data = { my_second_user: User = User(**second_user_data) ``` -/// info | "情報" +/// info | 情報 `**second_user_data` は以下を意味します： diff --git a/docs/ja/docs/python-types.md b/docs/ja/docs/python-types.md index 7af6ce0c0..77ddf4654 100644 --- a/docs/ja/docs/python-types.md +++ b/docs/ja/docs/python-types.md @@ -12,7 +12,7 @@ しかしたとえまったく **FastAPI** を使用しない場合でも、それらについて少し学ぶことで利点を得ることができるでしょう。 -/// note | "備考" +/// note | 備考 もしあなたがPythonの専門家で、すでに型ヒントについてすべて知っているのであれば、次の章まで読み飛ばしてください。 @@ -175,7 +175,7 @@ John Doe {!../../docs_src/python_types/tutorial006.py!} ``` -/// tip | "豆知識" +/// tip | 豆知識 角括弧内の内部の型は「型パラメータ」と呼ばれています。 @@ -288,7 +288,7 @@ Pydanticの公式ドキュメントから引用: {!../../docs_src/python_types/tutorial011.py!} ``` -/// info | "情報" +/// info | 情報 Pydanticについてより学びたい方はドキュメントを参照してください. @@ -320,7 +320,7 @@ Pydanticについてより学びたい方は`mypy`のチートシートを参照してください diff --git a/docs/ja/docs/tutorial/background-tasks.md b/docs/ja/docs/tutorial/background-tasks.md index 6f9340817..8a4bc161c 100644 --- a/docs/ja/docs/tutorial/background-tasks.md +++ b/docs/ja/docs/tutorial/background-tasks.md @@ -85,8 +85,6 @@ これらは、より複雑な構成、RabbitMQ や Redis などのメッセージ/ジョブキューマネージャーを必要とする傾向がありますが、複数のプロセス、特に複数のサーバーでバックグラウンドタスクを実行できます。 -例を確認するには、[Project Generators](../project-generation.md){.internal-link target=_blank} を参照してください。これらにはすべて、Celery が構築済みです。 - ただし、同じ **FastAPI** アプリから変数とオブジェクトにアクセスする必要がある場合、または小さなバックグラウンドタスク (電子メール通知の送信など) を実行する必要がある場合は、単に `BackgroundTasks` を使用できます。 ## まとめ diff --git a/docs/ja/docs/tutorial/body-fields.md b/docs/ja/docs/tutorial/body-fields.md index 1d386040a..5b3b3622b 100644 --- a/docs/ja/docs/tutorial/body-fields.md +++ b/docs/ja/docs/tutorial/body-fields.md @@ -10,7 +10,7 @@ {!../../docs_src/body_fields/tutorial001.py!} ``` -/// warning | "注意" +/// warning | 注意 `Field`は他の全てのもの（`Query`、`Path`、`Body`など）とは違い、`fastapi`からではなく、`pydantic`から直接インポートされていることに注意してください。 @@ -26,7 +26,7 @@ `Field`は`Query`や`Path`、`Body`と同じように動作し、全く同様のパラメータなどを持ちます。 -/// note | "技術詳細" +/// note | 技術詳細 実際には次に見る`Query`や`Path`などは、共通の`Param`クラスのサブクラスのオブジェクトを作成しますが、それ自体はPydanticの`FieldInfo`クラスのサブクラスです。 @@ -38,7 +38,7 @@ /// -/// tip | "豆知識" +/// tip | 豆知識 型、デフォルト値、`Field`を持つ各モデルの属性が、`Path`や`Query`、`Body`の代わりに`Field`を持つ、*path operation 関数の*パラメータと同じ構造になっていることに注目してください。 diff --git a/docs/ja/docs/tutorial/body-multiple-params.md b/docs/ja/docs/tutorial/body-multiple-params.md index 647143ee5..982c23565 100644 --- a/docs/ja/docs/tutorial/body-multiple-params.md +++ b/docs/ja/docs/tutorial/body-multiple-params.md @@ -12,7 +12,7 @@ {!../../docs_src/body_multiple_params/tutorial001.py!} ``` -/// note | "備考" +/// note | 備考 この場合、ボディから取得する`item`はオプションであることに注意してください。デフォルト値は`None`です。 @@ -56,7 +56,7 @@ } ``` -/// note | "備考" +/// note | 備考 以前と同じように`item`が宣言されていたにもかかわらず、`item`はキー`item`を持つボディの内部にあることが期待されていることに注意してください。 @@ -118,7 +118,7 @@ q: str = None {!../../docs_src/body_multiple_params/tutorial004.py!} ``` -/// info | "情報" +/// info | 情報 `Body`もまた、後述する `Query` や `Path` などと同様に、すべての検証パラメータとメタデータパラメータを持っています。 diff --git a/docs/ja/docs/tutorial/body-nested-models.md b/docs/ja/docs/tutorial/body-nested-models.md index 8703a40e7..dc2d5e81a 100644 --- a/docs/ja/docs/tutorial/body-nested-models.md +++ b/docs/ja/docs/tutorial/body-nested-models.md @@ -162,7 +162,7 @@ Pydanticモデルを`list`や`set`などのサブタイプとして使用する } ``` -/// info | "情報" +/// info | 情報 `images`キーが画像オブジェクトのリストを持つようになったことに注目してください。 @@ -176,7 +176,7 @@ Pydanticモデルを`list`や`set`などのサブタイプとして使用する {!../../docs_src/body_nested_models/tutorial007.py!} ``` -/// info | "情報" +/// info | 情報 `Offer`は`Item`のリストであり、オプションの`Image`のリストを持っていることに注目してください。 @@ -228,7 +228,7 @@ Pydanticモデルではなく、`dict`を直接使用している場合はこの {!../../docs_src/body_nested_models/tutorial009.py!} ``` -/// tip | "豆知識" +/// tip | 豆知識 JSONはキーとして`str`しかサポートしていないことに注意してください。 diff --git a/docs/ja/docs/tutorial/body-updates.md b/docs/ja/docs/tutorial/body-updates.md index fde9f4f5e..fcaeb0d16 100644 --- a/docs/ja/docs/tutorial/body-updates.md +++ b/docs/ja/docs/tutorial/body-updates.md @@ -34,7 +34,7 @@ つまり、更新したいデータだけを送信して、残りはそのままにしておくことができます。 -/// note | "備考" +/// note | 備考 `PATCH`は`PUT`よりもあまり使われておらず、知られていません。 @@ -89,7 +89,7 @@ {!../../docs_src/body_updates/tutorial002.py!} ``` -/// tip | "豆知識" +/// tip | 豆知識 実際には、HTTPの`PUT`操作でも同じテクニックを使用することができます。 @@ -97,7 +97,7 @@ /// -/// note | "備考" +/// note | 備考 入力モデルがまだ検証されていることに注目してください。 diff --git a/docs/ja/docs/tutorial/body.md b/docs/ja/docs/tutorial/body.md index 888d4388a..277ee79c8 100644 --- a/docs/ja/docs/tutorial/body.md +++ b/docs/ja/docs/tutorial/body.md @@ -8,7 +8,7 @@ APIはほとんどの場合 **レスポンス** ボディを送らなければ **リクエスト** ボディを宣言するために Pydantic モデルを使用します。そして、その全てのパワーとメリットを利用します。 -/// info | "情報" +/// info | 情報 データを送るには、`POST` (もっともよく使われる)、`PUT`、`DELETE` または `PATCH` を使うべきです。 @@ -113,7 +113,7 @@ GET リクエストでボディを送信することは、仕様では未定義 -/// tip | "豆知識" +/// tip | 豆知識 PyCharmエディタを使用している場合は、Pydantic PyCharm Pluginが使用可能です。 @@ -161,7 +161,7 @@ GET リクエストでボディを送信することは、仕様では未定義 * パラメータが**単数型** (`int`、`float`、`str`、`bool` など)の場合は**クエリ**パラメータとして解釈されます。 * パラメータが **Pydantic モデル**型で宣言された場合、リクエスト**ボディ**として解釈されます。 -/// note | "備考" +/// note | 備考 FastAPIは、`= None`があるおかげで、`q`がオプショナルだとわかります。 diff --git a/docs/ja/docs/tutorial/cookie-params.md b/docs/ja/docs/tutorial/cookie-params.md index 1f45db17c..7f029b483 100644 --- a/docs/ja/docs/tutorial/cookie-params.md +++ b/docs/ja/docs/tutorial/cookie-params.md @@ -20,7 +20,7 @@ {!../../docs_src/cookie_params/tutorial001.py!} ``` -/// note | "技術詳細" +/// note | 技術詳細 `Cookie`は`Path`と`Query`の「姉妹」クラスです。また、同じ共通の`Param`クラスを継承しています。 @@ -28,7 +28,7 @@ /// -/// info | "情報" +/// info | 情報 クッキーを宣言するには、`Cookie`を使う必要があります。なぜなら、そうしないとパラメータがクエリのパラメータとして解釈されてしまうからです。 diff --git a/docs/ja/docs/tutorial/cors.md b/docs/ja/docs/tutorial/cors.md index 9530c51bf..9834a460b 100644 --- a/docs/ja/docs/tutorial/cors.md +++ b/docs/ja/docs/tutorial/cors.md @@ -78,7 +78,7 @@ CORSについてより詳しい情報は、Mozilla CORS documentation を参照して下さい。 -/// note | "技術詳細" +/// note | 技術詳細 `from starlette.middleware.cors import CORSMiddleware` も使用できます。 diff --git a/docs/ja/docs/tutorial/debugging.md b/docs/ja/docs/tutorial/debugging.md index be0ff81d4..7413332a8 100644 --- a/docs/ja/docs/tutorial/debugging.md +++ b/docs/ja/docs/tutorial/debugging.md @@ -74,7 +74,7 @@ from myapp import app は実行されません。 -/// info | "情報" +/// info | 情報 より詳しい情報は、公式Pythonドキュメントを参照してください。 diff --git a/docs/ja/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/ja/docs/tutorial/dependencies/classes-as-dependencies.md index fb23a7b2b..55885a61f 100644 --- a/docs/ja/docs/tutorial/dependencies/classes-as-dependencies.md +++ b/docs/ja/docs/tutorial/dependencies/classes-as-dependencies.md @@ -185,7 +185,7 @@ commons: CommonQueryParams = Depends() ...そして **FastAPI** は何をすべきか知っています。 -/// tip | "豆知識" +/// tip | 豆知識 役に立つというよりも、混乱するようであれば無視してください。それをする*必要*はありません。 diff --git a/docs/ja/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/ja/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md index 59f21c3df..3b78f4e0b 100644 --- a/docs/ja/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md +++ b/docs/ja/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md @@ -20,7 +20,7 @@ これらの依存関係は、通常の依存関係と同様に実行・解決されます。しかし、それらの値（何かを返す場合）は*path operation関数*には渡されません。 -/// tip | "豆知識" +/// tip | 豆知識 エディタによっては、未使用の関数パラメータをチェックしてエラーとして表示するものもあります。 diff --git a/docs/ja/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/ja/docs/tutorial/dependencies/dependencies-with-yield.md index 7ef1caf0d..bd4e689bf 100644 --- a/docs/ja/docs/tutorial/dependencies/dependencies-with-yield.md +++ b/docs/ja/docs/tutorial/dependencies/dependencies-with-yield.md @@ -4,13 +4,13 @@ FastAPIは、いくつかのしてカスタムの独自ヘッダーを追加できます。 @@ -43,7 +43,7 @@ /// -/// note | "技術詳細" +/// note | 技術詳細 `from starlette.requests import Request` を使用することもできます。 diff --git a/docs/ja/docs/tutorial/path-operation-configuration.md b/docs/ja/docs/tutorial/path-operation-configuration.md index 7eceb377d..36223d35d 100644 --- a/docs/ja/docs/tutorial/path-operation-configuration.md +++ b/docs/ja/docs/tutorial/path-operation-configuration.md @@ -2,7 +2,7 @@ *path operationデコレータ*を設定するためのパラメータがいくつかあります。 -/// warning | "注意" +/// warning | 注意 これらのパラメータは*path operation関数*ではなく、*path operationデコレータ*に直接渡されることに注意してください。 @@ -22,7 +22,7 @@ そのステータスコードはレスポンスで使用され、OpenAPIスキーマに追加されます。 -/// note | "技術詳細" +/// note | 技術詳細 また、`from starlette import status`を使用することもできます。 @@ -72,13 +72,13 @@ docstringにhttp://127.0.0.1:8000/items/4.2 で見られるように、intのかわりに `float` が与えられた場合にも同様なエラーが表示されます。 -/// check | "確認" +/// check | 確認 したがって、Pythonの型宣言を使用することで、**FastAPI**はデータのバリデーションを行います。 @@ -85,7 +85,7 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー -/// check | "確認" +/// check | 確認 繰り返しになりますが、Python型宣言を使用するだけで、**FastAPI**は対話的なAPIドキュメントを自動的に生成します（Swagger UIを統合）。 @@ -143,13 +143,13 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー {!../../docs_src/path_params/tutorial005.py!} ``` -/// info | "情報" +/// info | 情報 Enumerations (もしくは、enums)はPython 3.4以降で利用できます。 /// -/// tip | "豆知識" +/// tip | 豆知識 "AlexNet"、"ResNet"そして"LeNet"は機械学習モデルの名前です。 @@ -189,7 +189,7 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー {!../../docs_src/path_params/tutorial005.py!} ``` -/// tip | "豆知識" +/// tip | 豆知識 `ModelName.lenet.value` でも `"lenet"` 値にアクセスできます。 @@ -246,7 +246,7 @@ Starletteのオプションを直接使用することで、以下のURLの様 {!../../docs_src/path_params/tutorial004.py!} ``` -/// tip | "豆知識" +/// tip | 豆知識 最初のスラッシュ (`/`)が付いている `/home/johndoe/myfile.txt` をパラメータが含んでいる必要があります。 diff --git a/docs/ja/docs/tutorial/query-params-str-validations.md b/docs/ja/docs/tutorial/query-params-str-validations.md index 9e54a6f55..6450c91c4 100644 --- a/docs/ja/docs/tutorial/query-params-str-validations.md +++ b/docs/ja/docs/tutorial/query-params-str-validations.md @@ -10,7 +10,7 @@ クエリパラメータ `q` は `Optional[str]` 型で、`None` を許容する `str` 型を意味しており、デフォルトは `None` です。そのため、FastAPIはそれが必須ではないと理解します。 -/// note | "備考" +/// note | 備考 FastAPIは、 `q` はデフォルト値が `=None` であるため、必須ではないと理解します。 @@ -54,7 +54,7 @@ q: Optional[str] = None しかし、これはクエリパラメータとして明示的に宣言しています。 -/// info | "情報" +/// info | 情報 FastAPIは以下の部分を気にすることを覚えておいてください: @@ -118,7 +118,7 @@ q: Union[str, None] = Query(default=None, max_length=50) {!../../docs_src/query_params_str_validations/tutorial005.py!} ``` -/// note | "備考" +/// note | 備考 デフォルト値を指定すると、パラメータは任意になります。 @@ -150,7 +150,7 @@ q: Union[str, None] = Query(default=None, min_length=3) {!../../docs_src/query_params_str_validations/tutorial006.py!} ``` -/// info | "情報" +/// info | 情報 これまで`...`を見たことがない方へ: これは特殊な単一値です。Pythonの一部であり、"Ellipsis"と呼ばれています。 @@ -187,7 +187,7 @@ http://localhost:8000/items/?q=foo&q=bar } ``` -/// tip | "豆知識" +/// tip | 豆知識 上述の例のように、`list`型のクエリパラメータを宣言するには明示的に`Query`を使用する必要があります。そうしない場合、リクエストボディと解釈されます。 @@ -230,7 +230,7 @@ http://localhost:8000/items/ {!../../docs_src/query_params_str_validations/tutorial013.py!} ``` -/// note | "備考" +/// note | 備考 この場合、FastAPIはリストの内容をチェックしないことを覚えておいてください。 @@ -244,7 +244,7 @@ http://localhost:8000/items/ その情報は、生成されたOpenAPIに含まれ、ドキュメントのユーザーインターフェースや外部のツールで使用されます。 -/// note | "備考" +/// note | 備考 ツールによってOpenAPIのサポートのレベルが異なる可能性があることを覚えておいてください。 diff --git a/docs/ja/docs/tutorial/query-params.md b/docs/ja/docs/tutorial/query-params.md index 6d41d3742..71f78eca5 100644 --- a/docs/ja/docs/tutorial/query-params.md +++ b/docs/ja/docs/tutorial/query-params.md @@ -69,7 +69,7 @@ http://127.0.0.1:8000/items/?skip=20 この場合、関数パラメータ `q` はオプショナルとなり、デフォルトでは `None` になります。 -/// check | "確認" +/// check | 確認 パスパラメータ `item_id` はパスパラメータであり、`q` はそれとは違ってクエリパラメータであると判別できるほど**FastAPI** が賢いということにも注意してください。 @@ -191,7 +191,7 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy * `skip`、デフォルト値を `0` とする `int` 。 * `limit`、オプショナルな `int` 。 -/// tip | "豆知識" +/// tip | 豆知識 [パスパラメータ](path-params.md#_8){.internal-link target=_blank}と同様に `Enum` を使用できます。 diff --git a/docs/ja/docs/tutorial/request-forms-and-files.md b/docs/ja/docs/tutorial/request-forms-and-files.md index e03b9166d..1e4237b20 100644 --- a/docs/ja/docs/tutorial/request-forms-and-files.md +++ b/docs/ja/docs/tutorial/request-forms-and-files.md @@ -2,7 +2,7 @@ `File`と`Form`を同時に使うことでファイルとフォームフィールドを定義することができます。 -/// info | "情報" +/// info | 情報 アップロードされたファイルやフォームデータを受信するには、まず`python-multipart`をインストールします。 @@ -28,7 +28,7 @@ また、いくつかのファイルを`bytes`として、いくつかのファイルを`UploadFile`として宣言することができます。 -/// warning | "注意" +/// warning | 注意 *path operation*で複数の`File`と`Form`パラメータを宣言することができますが、JSONとして受け取ることを期待している`Body`フィールドを宣言することはできません。なぜなら、リクエストのボディは`application/json`の代わりに`multipart/form-data`を使ってエンコードされているからです。 diff --git a/docs/ja/docs/tutorial/request-forms.md b/docs/ja/docs/tutorial/request-forms.md index eb453c04a..f130c067f 100644 --- a/docs/ja/docs/tutorial/request-forms.md +++ b/docs/ja/docs/tutorial/request-forms.md @@ -2,7 +2,7 @@ JSONの代わりにフィールドを受け取る場合は、`Form`を使用します。 -/// info | "情報" +/// info | 情報 フォームを使うためには、まず`python-multipart`をインストールします。 @@ -32,13 +32,13 @@ JSONの代わりにフィールドを受け取る場合は、`Form`を使用し `Form`では`Body`（および`Query`や`Path`、`Cookie`）と同じメタデータとバリデーションを宣言することができます。 -/// info | "情報" +/// info | 情報 `Form`は`Body`を直接継承するクラスです。 /// -/// tip | "豆知識" +/// tip | 豆知識 フォームのボディを宣言するには、明示的に`Form`を使用する必要があります。なぜなら、これを使わないと、パラメータはクエリパラメータやボディ（JSON）パラメータとして解釈されるからです。 @@ -50,7 +50,7 @@ HTMLフォーム（`
`）がサーバにデータを送信する方 **FastAPI** は、JSONの代わりにそのデータを適切な場所から読み込むようにします。 -/// note | "技術詳細" +/// note | 技術詳細 フォームからのデータは通常、`application/x-www-form-urlencoded`の「media type」を使用してエンコードされます。 @@ -60,7 +60,7 @@ HTMLフォーム（`
`）がサーバにデータを送信する方 /// -/// warning | "注意" +/// warning | 注意 *path operation*で複数の`Form`パラメータを宣言することができますが、JSONとして受け取ることを期待している`Body`フィールドを宣言することはできません。なぜなら、リクエストは`application/json`の代わりに`application/x-www-form-urlencoded`を使ってボディをエンコードするからです。 diff --git a/docs/ja/docs/tutorial/response-model.md b/docs/ja/docs/tutorial/response-model.md index 973f893de..97821f125 100644 --- a/docs/ja/docs/tutorial/response-model.md +++ b/docs/ja/docs/tutorial/response-model.md @@ -12,7 +12,7 @@ {!../../docs_src/response_model/tutorial001.py!} ``` -/// note | "備考" +/// note | 備考 `response_model`は「デコレータ」メソッド（`get`、`post`など）のパラメータであることに注意してください。すべてのパラメータやボディのように、*path operation関数* のパラメータではありません。 @@ -31,7 +31,7 @@ FastAPIは`response_model`を使って以下のことをします: * 出力データをモデルのデータに限定します。これがどのように重要なのか以下で見ていきましょう。 -/// note | "技術詳細" +/// note | 技術詳細 レスポンスモデルは、関数の戻り値のアノテーションではなく、このパラメータで宣言されています。なぜなら、パス関数は実際にはそのレスポンスモデルを返すのではなく、`dict`やデータベースオブジェクト、あるいは他のモデルを返し、`response_model`を使用してフィールドの制限やシリアライズを行うからです。 @@ -57,7 +57,7 @@ FastAPIは`response_model`を使って以下のことをします: しかし、同じモデルを別の*path operation*に使用すると、すべてのクライアントにユーザーのパスワードを送信してしまうことになります。 -/// danger | "危険" +/// danger | 危険 ユーザーの平文のパスワードを保存したり、レスポンスで送信したりすることは絶対にしないでください。 @@ -130,13 +130,13 @@ FastAPIは`response_model`を使って以下のことをします: } ``` -/// info | "情報" +/// info | 情報 FastAPIはこれをするために、Pydanticモデルの`.dict()`をその`exclude_unset`パラメータで使用しています。 /// -/// info | "情報" +/// info | 情報 以下も使用することができます: @@ -180,7 +180,7 @@ FastAPIは十分に賢いので（実際には、Pydanticが十分に賢い）`d そのため、それらはJSONレスポンスに含まれることになります。 -/// tip | "豆知識" +/// tip | 豆知識 デフォルト値は`None`だけでなく、なんでも良いことに注意してください。 例えば、リスト（`[]`）や`10.5`の`float`などです。 @@ -195,7 +195,7 @@ FastAPIは十分に賢いので（実際には、Pydanticが十分に賢い）`d これは、Pydanticモデルが１つしかなく、出力からいくつかのデータを削除したい場合のクイックショートカットとして使用することができます。 -/// tip | "豆知識" +/// tip | 豆知識 それでも、これらのパラメータではなく、複数のクラスを使用して、上記のようなアイデアを使うことをおすすめします。 @@ -209,7 +209,7 @@ FastAPIは十分に賢いので（実際には、Pydanticが十分に賢い）`d {!../../docs_src/response_model/tutorial005.py!} ``` -/// tip | "豆知識" +/// tip | 豆知識 `{"name", "description"}`の構文はこれら２つの値をもつ`set`を作成します。 diff --git a/docs/ja/docs/tutorial/response-status-code.md b/docs/ja/docs/tutorial/response-status-code.md index 90b290887..56bcdaf6c 100644 --- a/docs/ja/docs/tutorial/response-status-code.md +++ b/docs/ja/docs/tutorial/response-status-code.md @@ -12,7 +12,7 @@ {!../../docs_src/response_status_code/tutorial001.py!} ``` -/// note | "備考" +/// note | 備考 `status_code`は「デコレータ」メソッド（`get`、`post`など）のパラメータであることに注意してください。すべてのパラメータやボディのように、*path operation関数*のものではありません。 @@ -20,7 +20,7 @@ `status_code`パラメータはHTTPステータスコードを含む数値を受け取ります。 -/// info | "情報" +/// info | 情報 `status_code`は代わりに、Pythonの`http.HTTPStatus`のように、`IntEnum`を受け取ることもできます。 @@ -33,7 +33,7 @@ -/// note | "備考" +/// note | 備考 いくつかのレスポンスコード（次のセクションを参照）は、レスポンスにボディがないことを示しています。 @@ -43,7 +43,7 @@ FastAPIはこれを知っていて、レスポンスボディがないというO ## HTTPステータスコードについて -/// note | "備考" +/// note | 備考 すでにHTTPステータスコードが何であるかを知っている場合は、次のセクションにスキップしてください。 @@ -66,7 +66,7 @@ HTTPでは、レスポンスの一部として３桁の数字のステータス * クライアントからの一般的なエラーについては、`400`を使用することができます。 * `500`以上はサーバーエラーのためのものです。これらを直接使うことはほとんどありません。アプリケーションコードやサーバーのどこかで何か問題が発生した場合、これらのステータスコードのいずれかが自動的に返されます。 -/// tip | "豆知識" +/// tip | 豆知識 それぞれのステータスコードとどのコードが何のためのコードなのかについて詳細はMDN HTTP レスポンスステータスコードについてのドキュメントを参照してください。 @@ -94,7 +94,7 @@ HTTPでは、レスポンスの一部として３桁の数字のステータス -/// note | "技術詳細" +/// note | 技術詳細 また、`from starlette import status`を使うこともできます。 diff --git a/docs/ja/docs/tutorial/schema-extra-example.md b/docs/ja/docs/tutorial/schema-extra-example.md index baf1bbedd..44dfad737 100644 --- a/docs/ja/docs/tutorial/schema-extra-example.md +++ b/docs/ja/docs/tutorial/schema-extra-example.md @@ -24,7 +24,7 @@ JSON Schemaの追加情報を宣言する方法はいくつかあります。 {!../../docs_src/schema_extra_example/tutorial002.py!} ``` -/// warning | "注意" +/// warning | 注意 これらの追加引数が渡されても、文書化のためのバリデーションは追加されず、注釈だけが追加されることを覚えておいてください。 diff --git a/docs/ja/docs/tutorial/security/first-steps.md b/docs/ja/docs/tutorial/security/first-steps.md index 51f7bf829..6ace1b542 100644 --- a/docs/ja/docs/tutorial/security/first-steps.md +++ b/docs/ja/docs/tutorial/security/first-steps.md @@ -26,7 +26,7 @@ ## 実行 -/// info | "情報" +/// info | 情報 まず`python-multipart`をインストールします。 @@ -56,7 +56,7 @@ $ uvicorn main:app --reload -/// check | "Authorizeボタン!" +/// check | Authorizeボタン! すでにピカピカの新しい「Authorize」ボタンがあります。 @@ -68,7 +68,7 @@ $ uvicorn main:app --reload -/// note | "備考" +/// note | 備考 フォームに何を入力しても、まだうまくいきません。ですが、これから動くようになります。 @@ -114,7 +114,7 @@ OAuth2は、バックエンドやAPIがユーザーを認証するサーバー この例では、**Bearer**トークンを使用して**OAuth2**を**パスワード**フローで使用します。これには`OAuth2PasswordBearer`クラスを使用します。 -/// info | "情報" +/// info | 情報 「bearer」トークンが、唯一の選択肢ではありません。 @@ -132,7 +132,7 @@ OAuth2は、バックエンドやAPIがユーザーを認証するサーバー {!../../docs_src/security/tutorial001.py!} ``` -/// tip | "豆知識" +/// tip | 豆知識 ここで、`tokenUrl="token"`は、まだ作成していない相対URL`token`を指します。相対URLなので、`./token`と同じです。 @@ -146,7 +146,7 @@ OAuth2は、バックエンドやAPIがユーザーを認証するサーバー 実際のpath operationもすぐに作ります。 -/// info | "情報" +/// info | 情報 非常に厳格な「Pythonista」であれば、パラメーター名のスタイルが`token_url`ではなく`tokenUrl`であることを気に入らないかもしれません。 @@ -176,7 +176,7 @@ oauth2_scheme(some, parameters) **FastAPI**は、この依存関係を使用してOpenAPIスキーマ (および自動APIドキュメント) で「セキュリティスキーム」を定義できることを知っています。 -/// info | "技術詳細" +/// info | 技術詳細 **FastAPI**は、`OAuth2PasswordBearer` クラス (依存関係で宣言されている) を使用してOpenAPIのセキュリティスキームを定義できることを知っています。これは`fastapi.security.oauth2.OAuth2`、`fastapi.security.base.SecurityBase`を継承しているからです。 diff --git a/docs/ja/docs/tutorial/security/get-current-user.md b/docs/ja/docs/tutorial/security/get-current-user.md index 0edbd983f..898bbd797 100644 --- a/docs/ja/docs/tutorial/security/get-current-user.md +++ b/docs/ja/docs/tutorial/security/get-current-user.md @@ -54,7 +54,7 @@ Pydanticモデルの `User` として、 `current_user` の型を宣言するこ その関数の中ですべての入力補完や型チェックを行う際に役に立ちます。 -/// tip | "豆知識" +/// tip | 豆知識 リクエストボディはPydanticモデルでも宣言できることを覚えているかもしれません。 @@ -62,7 +62,7 @@ Pydanticモデルの `User` として、 `current_user` の型を宣言するこ /// -/// check | "確認" +/// check | 確認 依存関係システムがこのように設計されているおかげで、 `User` モデルを返却する別の依存関係（別の"dependables"）を持つことができます。 diff --git a/docs/ja/docs/tutorial/security/index.md b/docs/ja/docs/tutorial/security/index.md index c68e7e7f2..37b8bb958 100644 --- a/docs/ja/docs/tutorial/security/index.md +++ b/docs/ja/docs/tutorial/security/index.md @@ -32,7 +32,7 @@ OAuth 1というものもありましたが、これはOAuth2とは全く異な OAuth2は、通信を暗号化する方法を指定せず、アプリケーションがHTTPSで提供されることを想定しています。 -/// tip | "豆知識" +/// tip | 豆知識 **デプロイ**のセクションでは、TraefikとLet's Encryptを使用して、無料でHTTPSを設定する方法が紹介されています。 @@ -89,7 +89,7 @@ OpenAPIでは、以下のセキュリティスキームを定義しています: * この自動検出メカニズムは、OpenID Connectの仕様で定義されているものです。 -/// tip | "豆知識" +/// tip | 豆知識 Google、Facebook、Twitter、GitHubなど、他の認証/認可プロバイダを統合することも可能で、比較的簡単です。 diff --git a/docs/ja/docs/tutorial/security/oauth2-jwt.md b/docs/ja/docs/tutorial/security/oauth2-jwt.md index b2f511610..825a1b2b3 100644 --- a/docs/ja/docs/tutorial/security/oauth2-jwt.md +++ b/docs/ja/docs/tutorial/security/oauth2-jwt.md @@ -44,7 +44,7 @@ $ pip install python-jose[cryptography] ここでは、推奨されているものを使用します：pyca/cryptography。 -/// tip | "豆知識" +/// tip | 豆知識 このチュートリアルでは以前、PyJWTを使用していました。 @@ -86,7 +86,7 @@ $ pip install passlib[bcrypt] -/// tip | "豆知識" +/// tip | 豆知識 `passlib`を使用すると、**Django**や**Flask**のセキュリティプラグインなどで作成されたパスワードを読み取れるように設定できます。 @@ -102,7 +102,7 @@ $ pip install passlib[bcrypt] PassLib の「context」を作成します。これは、パスワードのハッシュ化と検証に使用されるものです。 -/// tip | "豆知識" +/// tip | 豆知識 PassLibのcontextには、検証だけが許された非推奨の古いハッシュアルゴリズムを含む、様々なハッシュアルゴリズムを使用した検証機能もあります。 @@ -122,7 +122,7 @@ PassLibのcontextには、検証だけが許された非推奨の古いハッシ {!../../docs_src/security/tutorial004.py!} ``` -/// note | "備考" +/// note | 備考 新しい（偽の）データベース`fake_users_db`を確認すると、ハッシュ化されたパスワードが次のようになっていることがわかります：`"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"` @@ -219,7 +219,7 @@ IDの衝突を回避するために、ユーザーのJWTトークンを作成す Username: `johndoe` Password: `secret` -/// check | "確認" +/// check | 確認 コードのどこにも平文のパスワード"`secret`"はなく、ハッシュ化されたものしかないことを確認してください。 @@ -244,7 +244,7 @@ Password: `secret` -/// note | "備考" +/// note | 備考 ヘッダーの`Authorization`には、`Bearer`で始まる値があります。 diff --git a/docs/ja/docs/tutorial/static-files.md b/docs/ja/docs/tutorial/static-files.md index e6002a1fb..37ea22dd7 100644 --- a/docs/ja/docs/tutorial/static-files.md +++ b/docs/ja/docs/tutorial/static-files.md @@ -11,7 +11,7 @@ {!../../docs_src/static_files/tutorial001.py!} ``` -/// note | "技術詳細" +/// note | 技術詳細 `from starlette.staticfiles import StaticFiles` も使用できます。 diff --git a/docs/ja/docs/tutorial/testing.md b/docs/ja/docs/tutorial/testing.md index 6c5e712e8..b7e80cb8d 100644 --- a/docs/ja/docs/tutorial/testing.md +++ b/docs/ja/docs/tutorial/testing.md @@ -22,7 +22,7 @@ {!../../docs_src/app_testing/tutorial001.py!} ``` -/// tip | "豆知識" +/// tip | 豆知識 テスト関数は `async def` ではなく、通常の `def` であることに注意してください。 @@ -32,7 +32,7 @@ /// -/// note | "技術詳細" +/// note | 技術詳細 `from starlette.testclient import TestClient` も使用できます。 @@ -40,7 +40,7 @@ /// -/// tip | "豆知識" +/// tip | 豆知識 FastAPIアプリケーションへのリクエストの送信とは別に、テストで `async` 関数 (非同期データベース関数など) を呼び出したい場合は、高度なチュートリアルの[Async Tests](../advanced/async-tests.md){.internal-link target=_blank} を参照してください。 @@ -121,7 +121,7 @@ FastAPIアプリケーションへのリクエストの送信とは別に、テ (`httpx` または `TestClient` を使用して) バックエンドにデータを渡す方法の詳細は、HTTPXのドキュメントを確認してください。 -/// info | "情報" +/// info | 情報 `TestClient` は、Pydanticモデルではなく、JSONに変換できるデータを受け取ることに注意してください。 diff --git a/docs/ko/docs/advanced/events.md b/docs/ko/docs/advanced/events.md index 94867c198..273c9a479 100644 --- a/docs/ko/docs/advanced/events.md +++ b/docs/ko/docs/advanced/events.md @@ -4,7 +4,7 @@ 이 함수들은 `async def` 또는 평범하게 `def`으로 선언할 수 있습니다. -/// warning | "경고" +/// warning | 경고 이벤트 핸들러는 주 응용 프로그램에서만 작동합니다. [하위 응용 프로그램 - 마운트](./sub-applications.md){.internal-link target=_blank}에서는 작동하지 않습니다. @@ -34,13 +34,13 @@ 이 예제에서 `shutdown` 이벤트 핸들러 함수는 `"Application shutdown"`이라는 텍스트가 적힌 `log.txt` 파일을 추가할 것입니다. -/// info | "정보" +/// info | 정보 `open()` 함수에서 `mode="a"`는 "추가"를 의미합니다. 따라서 이미 존재하는 파일의 내용을 덮어쓰지 않고 새로운 줄을 추가합니다. /// -/// tip | "팁" +/// tip | 팁 이 예제에서는 파일과 상호작용 하기 위해 파이썬 표준 함수인 `open()`을 사용하고 있습니다. @@ -50,7 +50,7 @@ /// -/// info | "정보" +/// info | 정보 이벤트 핸들러에 관한 내용은 Starlette 이벤트 문서에서 추가로 확인할 수 있습니다. diff --git a/docs/ko/docs/advanced/index.md b/docs/ko/docs/advanced/index.md index cb628fa10..31704727c 100644 --- a/docs/ko/docs/advanced/index.md +++ b/docs/ko/docs/advanced/index.md @@ -6,7 +6,7 @@ 이어지는 장에서는 여러분이 다른 옵션, 구성 및 추가 기능을 보실 수 있습니다. -/// tip | "팁" +/// tip | 팁 다음 장들이 **반드시 "심화"**인 것은 아닙니다. diff --git a/docs/ko/docs/advanced/response-cookies.md b/docs/ko/docs/advanced/response-cookies.md index 3f87b320a..f762e94b5 100644 --- a/docs/ko/docs/advanced/response-cookies.md +++ b/docs/ko/docs/advanced/response-cookies.md @@ -40,7 +40,7 @@ ### 추가 정보 -/// note | "기술적 세부사항" +/// note | 기술적 세부사항 `from starlette.responses import Response` 또는 `from starlette.responses import JSONResponse`를 사용할 수도 있습니다. diff --git a/docs/ko/docs/advanced/response-directly.md b/docs/ko/docs/advanced/response-directly.md index 20389ff2a..aedebff9d 100644 --- a/docs/ko/docs/advanced/response-directly.md +++ b/docs/ko/docs/advanced/response-directly.md @@ -38,7 +38,7 @@ Pydantic 모델로 데이터 변환을 수행하지 않으며, 내용을 다른 {!../../docs_src/response_directly/tutorial001.py!} ``` -/// note | "기술적 세부 사항" +/// note | 기술적 세부 사항 `from starlette.responses import JSONResponse`를 사용할 수도 있습니다. diff --git a/docs/ko/docs/advanced/response-headers.md b/docs/ko/docs/advanced/response-headers.md new file mode 100644 index 000000000..974a06969 --- /dev/null +++ b/docs/ko/docs/advanced/response-headers.md @@ -0,0 +1,45 @@ +# 응답 헤더 + +## `Response` 매개변수 사용하기 + +여러분은 *경로 작동 함수*에서 `Response` 타입의 매개변수를 선언할 수 있습니다 (쿠키와 같이 사용할 수 있습니다). + +그런 다음, 여러분은 해당 *임시* 응답 객체에서 헤더를 설정할 수 있습니다. + +```Python hl_lines="1 7-8" +{!../../docs_src/response_headers/tutorial002.py!} +``` + +그 후, 일반적으로 사용하듯이 필요한 객체(`dict`, 데이터베이스 모델 등)를 반환할 수 있습니다. + +`response_model`을 선언한 경우, 반환한 객체를 필터링하고 변환하는 데 여전히 사용됩니다. + +**FastAPI**는 해당 *임시* 응답에서 헤더(쿠키와 상태 코드도 포함)를 추출하여, 여러분이 반환한 값을 포함하는 최종 응답에 `response_model`로 필터링된 값을 넣습니다. + +또한, 종속성에서 `Response` 매개변수를 선언하고 그 안에서 헤더(및 쿠키)를 설정할 수 있습니다. + +## `Response` 직접 반환하기 + +`Response`를 직접 반환할 때에도 헤더를 추가할 수 있습니다. + +[응답을 직접 반환하기](response-directly.md){.internal-link target=_blank}에서 설명한 대로 응답을 생성하고, 헤더를 추가 매개변수로 전달하세요. + +```Python hl_lines="10-12" +{!../../docs_src/response_headers/tutorial001.py!} +``` + +/// note | 기술적 세부사항 + +`from starlette.responses import Response`나 `from starlette.responses import JSONResponse`를 사용할 수도 있습니다. + +**FastAPI**는 `starlette.responses`를 `fastapi.responses`로 개발자의 편의를 위해 직접 제공하지만, 대부분의 응답은 Starlette에서 직접 제공됩니다. + +그리고 `Response`는 헤더와 쿠키를 설정하는 데 자주 사용될 수 있으므로, **FastAPI**는 `fastapi.Response`로도 이를 제공합니다. + +/// + +## 커스텀 헤더 + +‘X-’ 접두어를 사용하여 커스텀 사설 헤더를 추가할 수 있습니다. + +하지만, 여러분이 브라우저에서 클라이언트가 볼 수 있기를 원하는 커스텀 헤더가 있는 경우, CORS 설정에 이를 추가해야 합니다([CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank}에서 자세히 알아보세요). `expose_headers` 매개변수를 사용하여 Starlette의 CORS 설명서에 문서화된 대로 설정할 수 있습니다. diff --git a/docs/ko/docs/advanced/testing-websockets.md b/docs/ko/docs/advanced/testing-websockets.md new file mode 100644 index 000000000..f1580c3c3 --- /dev/null +++ b/docs/ko/docs/advanced/testing-websockets.md @@ -0,0 +1,15 @@ +# WebSocket 테스트하기 + +`TestClient`를 사용하여 WebSocket을 테스트할 수 있습니다. + +이를 위해 `with` 문에서 `TestClient`를 사용하여 WebSocket에 연결합니다: + +```Python hl_lines="27-31" +{!../../docs_src/app_testing/tutorial002.py!} +``` + +/// note | 참고 + +자세한 내용은 Starlette의 WebSocket 테스트에 관한 설명서를 참고하시길 바랍니다. + +/// diff --git a/docs/ko/docs/async.md b/docs/ko/docs/async.md index dfc2caa78..fa0d20488 100644 --- a/docs/ko/docs/async.md +++ b/docs/ko/docs/async.md @@ -21,7 +21,7 @@ async def read_results(): return results ``` -/// note | "참고" +/// note | 참고 `async def`로 생성된 함수 내부에서만 `await`를 사용할 수 있습니다. @@ -369,7 +369,7 @@ FastAPI를 사용하지 않더라도, 높은 호환성 및 -/// info | "정보" +/// info | 정보 패키지 종속성을 정의하고 설치하기 위한 방법과 도구는 다양합니다. @@ -231,7 +231,7 @@ CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] 프로그램이 `/code`에서 시작하고 그 속에 `./app` 디렉터리가 여러분의 코드와 함께 들어있기 때문에, **Uvicorn**은 이를 보고 `app`을 `app.main`으로부터 **불러 올** 것입니다. -/// tip | "팁" +/// tip | 팁 각 코드 라인을 코드의 숫자 버블을 클릭하여 리뷰할 수 있습니다. 👆 @@ -305,7 +305,7 @@ $ docker build -t myimage . -/// tip | "팁" +/// tip | 팁 맨 끝에 있는 `.` 에 주목합시다. 이는 `./`와 동등하며, 도커에게 컨테이너 이미지를 빌드하기 위한 디렉터리를 알려줍니다. @@ -409,7 +409,7 @@ CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"] **HTTPS**와 **인증서**의 **자동** 취득을 다루는 것은 다른 컨테이너가 될 수 있는데, 예를 들어 Traefik을 사용하는 것입니다. -/// tip | "팁" +/// tip | 팁 Traefik은 도커, 쿠버네티스, 그리고 다른 도구와 통합되어 있어 여러분의 컨테이너를 포함하는 HTTPS를 셋업하고 설정하는 것이 매우 쉽습니다. @@ -441,7 +441,7 @@ Traefik은 도커, 쿠버네티스, 그리고 다른 도구와 통합되어 있 이 요소가 요청들의 **로드**를 읽어들이고 각 워커에게 (바라건대) **균형적으로** 분배한다면, 이 요소는 일반적으로 **로드 밸런서**라고 불립니다. -/// tip | "팁" +/// tip | 팁 HTTPS를 위해 사용된 **TLS 종료 프록시** 요소 또한 **로드 밸런서**가 될 수 있습니다. @@ -524,7 +524,7 @@ HTTPS를 위해 사용된 **TLS 종료 프록시** 요소 또한 **로드 밸런 만약 여러분이 **여러개의 컨테이너**를 가지고 있다면, 아마도 각각의 컨테이너는 **하나의 프로세스**를 가지고 있을 것입니다(예를 들어, **쿠버네티스** 클러스터에서). 그러면 여러분은 복제된 워커 컨테이너를 실행하기 **이전에**, 하나의 컨테이너에 있는 **이전의 단계들을** 수행하는 단일 프로세스를 가지는 **별도의 컨테이너들**을 가지고 싶을 것입니다. -/// info | "정보" +/// info | 정보 만약 여러분이 쿠버네티스를 사용하고 있다면, 아마도 이는 Init Container일 것입니다. @@ -544,7 +544,7 @@ HTTPS를 위해 사용된 **TLS 종료 프록시** 요소 또한 **로드 밸런 * tiangolo/uvicorn-gunicorn-fastapi. -/// warning | "경고" +/// warning | 경고 여러분이 이 베이스 이미지 또는 다른 유사한 이미지를 필요로 하지 **않을** 높은 가능성이 있으며, [위에서 설명된 것처럼: FastAPI를 위한 도커 이미지 빌드하기](#build-a-docker-image-for-fastapi) 처음부터 이미지를 빌드하는 것이 더 나을 수 있습니다. @@ -556,7 +556,7 @@ HTTPS를 위해 사용된 **TLS 종료 프록시** 요소 또한 **로드 밸런 또한 스크립트를 통해 **시작하기 전 사전 단계**를 실행하는 것을 지원합니다. -/// tip | "팁" +/// tip | 팁 모든 설정과 옵션을 보려면, 도커 이미지 페이지로 이동합니다: tiangolo/uvicorn-gunicorn-fastapi. @@ -687,7 +687,7 @@ CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] 11. `uvicorn` 커맨드를 실행하여, `app.main`에서 불러온 `app` 객체를 사용하도록 합니다. -/// tip | "팁" +/// tip | 팁 버블 숫자를 클릭해 각 줄이 하는 일을 알아볼 수 있습니다. diff --git a/docs/ko/docs/deployment/server-workers.md b/docs/ko/docs/deployment/server-workers.md index 39976faf5..b40b25cd8 100644 --- a/docs/ko/docs/deployment/server-workers.md +++ b/docs/ko/docs/deployment/server-workers.md @@ -17,7 +17,7 @@ 지금부터 **구니콘**을 **유비콘 워커 프로세스**와 함께 사용하는 방법을 알려드리겠습니다. -/// info | "정보" +/// info | 정보 만약 도커와 쿠버네티스 같은 컨테이너를 사용하고 있다면 다음 챕터 [FastAPI와 컨테이너 - 도커](docker.md){.internal-link target=_blank}에서 더 많은 정보를 얻을 수 있습니다. diff --git a/docs/ko/docs/deployment/versions.md b/docs/ko/docs/deployment/versions.md index f3b3c2d7b..559a892ab 100644 --- a/docs/ko/docs/deployment/versions.md +++ b/docs/ko/docs/deployment/versions.md @@ -43,7 +43,7 @@ fastapi>=0.45.0,<0.46.0 FastAPI는 오류를 수정하고, 일반적인 변경사항을 위해 "패치"버전의 관습을 따릅니다. -/// tip | "팁" +/// tip | 팁 여기서 말하는 "패치"란 버전의 마지막 숫자로, 예를 들어 `0.2.3` 버전에서 "패치"는 `3`을 의미합니다. @@ -57,7 +57,7 @@ fastapi>=0.45.0,<0.46.0 수정된 사항과 새로운 요소들이 "마이너" 버전에 추가되었습니다. -/// tip | "팁" +/// tip | 팁 "마이너"란 버전 넘버의 가운데 숫자로, 예를 들어서 `0.2.3`의 "마이너" 버전은 `2`입니다. diff --git a/docs/ko/docs/environment-variables.md b/docs/ko/docs/environment-variables.md index 09c2fd6d3..1e6af3ceb 100644 --- a/docs/ko/docs/environment-variables.md +++ b/docs/ko/docs/environment-variables.md @@ -1,6 +1,6 @@ # 환경 변수 -/// tip | "팁" +/// tip | 팁 만약 "환경 변수"가 무엇이고, 어떻게 사용하는지 알고 계시다면, 이 챕터를 스킵하셔도 좋습니다. @@ -63,7 +63,7 @@ name = os.getenv("MY_NAME", "World") print(f"Hello {name} from Python") ``` -/// tip | "팁" +/// tip | 팁 `os.getenv()` 의 두 번째 인자는 반환할 기본값입니다. @@ -151,7 +151,7 @@ Hello World from Python -/// tip | "팁" +/// tip | 팁 The Twelve-Factor App: Config 에서 좀 더 자세히 알아볼 수 있습니다. diff --git a/docs/ko/docs/features.md b/docs/ko/docs/features.md index b6f6f7af2..5e880c298 100644 --- a/docs/ko/docs/features.md +++ b/docs/ko/docs/features.md @@ -63,7 +63,7 @@ second_user_data = { my_second_user: User = User(**second_user_data) ``` -/// info | "정보" +/// info | 정보 `**second_user_data`가 뜻하는 것: diff --git a/docs/ko/docs/python-types.md b/docs/ko/docs/python-types.md index 6d7346189..7cc98ba76 100644 --- a/docs/ko/docs/python-types.md +++ b/docs/ko/docs/python-types.md @@ -12,7 +12,7 @@ 비록 **FastAPI**를 쓰지 않는다고 하더라도, 조금이라도 알아두면 도움이 될 것입니다. -/// note | "참고" +/// note | 참고 파이썬에 능숙하셔서 타입 힌트에 대해 모두 아신다면, 다음 챕터로 건너뛰세요. @@ -175,7 +175,7 @@ John Doe {!../../docs_src/python_types/tutorial006.py!} ``` -/// tip | "팁" +/// tip | 팁 대괄호 안의 내부 타입은 "타입 매개변수(type paramters)"라고 합니다. @@ -287,7 +287,7 @@ Pydantic 공식 문서 예시: {!../../docs_src/python_types/tutorial011.py!} ``` -/// info | "정보" +/// info | 정보 Pydantic<에 대해 더 배우고 싶다면 공식 문서를 참고하세요. @@ -319,7 +319,7 @@ Pydantic<에 대해 더 배우고 싶다면 `mypy`에서 제공하는 "cheat sheet"이 좋은 자료가 될 겁니다. diff --git a/docs/ko/docs/tutorial/background-tasks.md b/docs/ko/docs/tutorial/background-tasks.md index 376c52524..27f265608 100644 --- a/docs/ko/docs/tutorial/background-tasks.md +++ b/docs/ko/docs/tutorial/background-tasks.md @@ -97,8 +97,6 @@ FastAPI에서 `BackgroundTask`를 단독으로 사용하는 것은 여전히 가 RabbitMQ 또는 Redis와 같은 메시지/작업 큐 시스템 보다 복잡한 구성이 필요한 경향이 있지만, 여러 작업 프로세스를 특히 여러 서버의 백그라운드에서 실행할 수 있습니다. -예제를 보시려면 [프로젝트 생성기](../project-generation.md){.internal-link target=\_blank} 를 참고하세요. 해당 예제에는 이미 구성된 `Celery`가 포함되어 있습니다. - 그러나 동일한 FastAPI 앱에서 변수 및 개체에 접근해야햐는 작은 백그라운드 수행이 필요한 경우 (예 : 알림 이메일 보내기) 간단하게 `BackgroundTasks`를 사용해보세요. ## 요약 diff --git a/docs/ko/docs/tutorial/body-fields.md b/docs/ko/docs/tutorial/body-fields.md index a13159c27..f6532f369 100644 --- a/docs/ko/docs/tutorial/body-fields.md +++ b/docs/ko/docs/tutorial/body-fields.md @@ -32,7 +32,7 @@ //// tab | Python 3.10+ Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -46,7 +46,7 @@ //// tab | Python 3.8+ Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -58,7 +58,7 @@ //// -/// warning | "경고" +/// warning | 경고 `Field`는 다른 것들처럼 (`Query`, `Path`, `Body` 등) `fastapi`에서가 아닌 `pydantic`에서 바로 임포트 되는 점에 주의하세요. @@ -94,7 +94,7 @@ //// tab | Python 3.10+ Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -108,7 +108,7 @@ //// tab | Python 3.8+ Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -122,7 +122,7 @@ `Field`는 `Query`, `Path`와 `Body`와 같은 방식으로 동작하며, 모두 같은 매개변수들 등을 가집니다. -/// note | "기술적 세부사항" +/// note | 기술적 세부사항 실제로 `Query`, `Path`등, 여러분이 앞으로 볼 다른 것들은 공통 클래스인 `Param` 클래스의 서브클래스 객체를 만드는데, 그 자체로 Pydantic의 `FieldInfo` 클래스의 서브클래스입니다. @@ -134,7 +134,7 @@ /// -/// tip | "팁" +/// tip | 팁 주목할 점은 타입, 기본 값 및 `Field`로 이루어진 각 모델 어트리뷰트가 `Path`, `Query`와 `Body`대신 `Field`를 사용하는 *경로 작동 함수*의 매개변수와 같은 구조를 가진다는 점 입니다. @@ -146,7 +146,7 @@ 여러분이 예제를 선언할 때 나중에 이 공식 문서에서 별도 정보를 추가하는 방법을 배울 것입니다. -/// warning | "경고" +/// warning | 경고 별도 키가 전달된 `Field` 또한 여러분의 어플리케이션의 OpenAPI 스키마에 나타날 것입니다. 이런 키가 OpenAPI 명세서, [the OpenAPI validator](https://validator.swagger.io/)같은 몇몇 OpenAPI 도구들에 포함되지 못할 수 있으며, 여러분이 생성한 스키마와 호환되지 않을 수 있습니다. diff --git a/docs/ko/docs/tutorial/body-multiple-params.md b/docs/ko/docs/tutorial/body-multiple-params.md index 0a0f34585..569ff016e 100644 --- a/docs/ko/docs/tutorial/body-multiple-params.md +++ b/docs/ko/docs/tutorial/body-multiple-params.md @@ -14,7 +14,7 @@ {!../../docs_src/body_multiple_params/tutorial001.py!} ``` -/// note | "참고" +/// note | 참고 이 경우에는 본문으로 부터 가져온 ` item`은 기본값이 `None`이기 때문에, 선택사항이라는 점을 유의해야 합니다. @@ -58,7 +58,7 @@ } ``` -/// note | "참고" +/// note | 참고 이전과 같이 `item`이 선언 되었더라도, 본문 내의 `item` 키가 있을 것이라고 예측합니다. @@ -120,7 +120,7 @@ FastAPI는 요청을 자동으로 변환해, 매개변수의 `item`과 `user`를 q: Optional[str] = None ``` -/// info | "정보" +/// info | 정보 `Body` 또한 `Query`, `Path` 그리고 이후에 볼 다른 것들처럼 동일한 추가 검증과 메타데이터 매개변수를 갖고 있습니다. diff --git a/docs/ko/docs/tutorial/body-nested-models.md b/docs/ko/docs/tutorial/body-nested-models.md index 12fb4e0cc..e9b1d2e18 100644 --- a/docs/ko/docs/tutorial/body-nested-models.md +++ b/docs/ko/docs/tutorial/body-nested-models.md @@ -161,7 +161,7 @@ Pydantic 모델의 각 어트리뷰트는 타입을 갖습니다. } ``` -/// info | "정보" +/// info | 정보 `images` 키가 어떻게 이미지 객체 리스트를 갖는지 주목하세요. @@ -175,7 +175,7 @@ Pydantic 모델의 각 어트리뷰트는 타입을 갖습니다. {!../../docs_src/body_nested_models/tutorial007.py!} ``` -/// info | "정보" +/// info | 정보 `Offer`가 선택사항 `Image` 리스트를 차례로 갖는 `Item` 리스트를 어떻게 가지고 있는지 주목하세요 @@ -227,7 +227,7 @@ Pydantic 모델 대신에 `dict`를 직접 사용하여 작업할 경우, 이러 {!../../docs_src/body_nested_models/tutorial009.py!} ``` -/// tip | "팁" +/// tip | 팁 JSON은 오직 `str`형 키만 지원한다는 것을 염두에 두세요. diff --git a/docs/ko/docs/tutorial/body.md b/docs/ko/docs/tutorial/body.md index 8df8d556e..9e614ef1c 100644 --- a/docs/ko/docs/tutorial/body.md +++ b/docs/ko/docs/tutorial/body.md @@ -8,7 +8,7 @@ **요청** 본문을 선언하기 위해서 모든 강력함과 이점을 갖춘 Pydantic 모델을 사용합니다. -/// info | "정보" +/// info | 정보 데이터를 보내기 위해, (좀 더 보편적인) `POST`, `PUT`, `DELETE` 혹은 `PATCH` 중에 하나를 사용하는 것이 좋습니다. @@ -149,7 +149,7 @@ -/// tip | "팁" +/// tip | 팁 만약 PyCharm를 편집기로 사용한다면, Pydantic PyCharm Plugin을 사용할 수 있습니다. @@ -233,7 +233,7 @@ * 만약 매개변수가 (`int`, `float`, `str`, `bool` 등과 같은) **유일한 타입**으로 되어있으면, **쿼리** 매개변수로 해석될 것입니다. * 만약 매개변수가 **Pydantic 모델** 타입으로 선언되어 있으면, 요청 **본문**으로 해석될 것입니다. -/// note | "참고" +/// note | 참고 FastAPI는 `q`의 값이 필요없음을 알게 될 것입니다. 기본 값이 `= None`이기 때문입니다. diff --git a/docs/ko/docs/tutorial/cookie-params.md b/docs/ko/docs/tutorial/cookie-params.md index 1e21e069d..427539210 100644 --- a/docs/ko/docs/tutorial/cookie-params.md +++ b/docs/ko/docs/tutorial/cookie-params.md @@ -32,7 +32,7 @@ //// tab | Python 3.10+ Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -46,7 +46,7 @@ //// tab | Python 3.8+ Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -90,7 +90,7 @@ //// tab | Python 3.10+ Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -104,7 +104,7 @@ //// tab | Python 3.8+ Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -116,7 +116,7 @@ //// -/// note | "기술 세부사항" +/// note | 기술 세부사항 `Cookie`는 `Path` 및 `Query`의 "자매"클래스입니다. 이 역시 동일한 공통 `Param` 클래스를 상속합니다. @@ -124,7 +124,7 @@ /// -/// info | "정보" +/// info | 정보 쿠키를 선언하기 위해서는 `Cookie`를 사용해야 합니다. 그렇지 않으면 해당 매개변수를 쿼리 매개변수로 해석하기 때문입니다. diff --git a/docs/ko/docs/tutorial/cors.md b/docs/ko/docs/tutorial/cors.md index 65357ae3f..0222e6258 100644 --- a/docs/ko/docs/tutorial/cors.md +++ b/docs/ko/docs/tutorial/cors.md @@ -78,7 +78,7 @@ CORS에 대한 더 많은 정보를 알고싶다면, Mozilla CORS 문서를 참고하기 바랍니다. -/// note | "기술적 세부 사항" +/// note | 기술적 세부 사항 `from starlette.middleware.cors import CORSMiddleware` 역시 사용할 수 있습니다. diff --git a/docs/ko/docs/tutorial/debugging.md b/docs/ko/docs/tutorial/debugging.md index 27e8f9abf..fcb68b565 100644 --- a/docs/ko/docs/tutorial/debugging.md +++ b/docs/ko/docs/tutorial/debugging.md @@ -74,7 +74,7 @@ from myapp import app 은 실행되지 않습니다. -/// info | "정보" +/// info | 정보 자세한 내용은 공식 Python 문서를 확인하세요 diff --git a/docs/ko/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/ko/docs/tutorial/dependencies/classes-as-dependencies.md index 7430efbb4..41e48aefc 100644 --- a/docs/ko/docs/tutorial/dependencies/classes-as-dependencies.md +++ b/docs/ko/docs/tutorial/dependencies/classes-as-dependencies.md @@ -266,7 +266,7 @@ commons: CommonQueryParams = Depends() ...이렇게 코드를 단축하여도 **FastAPI**는 무엇을 해야하는지 알고 있습니다. -/// tip | "팁" +/// tip | 팁 만약 이것이 도움이 되기보다 더 헷갈리게 만든다면, 잊어버리십시오. 이것이 반드시 필요한 것은 아닙니다. diff --git a/docs/ko/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/ko/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md index e71ba8546..fab636b7f 100644 --- a/docs/ko/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md +++ b/docs/ko/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md @@ -32,7 +32,7 @@ //// tab | Python 3.8 Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -46,7 +46,7 @@ 이러한 의존성들은 기존 의존성들과 같은 방식으로 실행/해결됩니다. 그러나 값은 (무엇이든 반환한다면) *경로 작동 함수*에 제공되지 않습니다. -/// tip | "팁" +/// tip | 팁 일부 편집기에서는 사용되지 않는 함수 매개변수를 검사하고 오류로 표시합니다. @@ -56,7 +56,7 @@ /// -/// info | "정보" +/// info | 정보 이 예시에서 `X-Key`와 `X-Token`이라는 커스텀 헤더를 만들어 사용했습니다. @@ -90,7 +90,7 @@ //// tab | Python 3.8 Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -124,7 +124,7 @@ //// tab | Python 3.8 Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -160,7 +160,7 @@ //// tab | Python 3.8 Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. diff --git a/docs/ko/docs/tutorial/dependencies/global-dependencies.md b/docs/ko/docs/tutorial/dependencies/global-dependencies.md index dd6586c3e..0ad8b55fd 100644 --- a/docs/ko/docs/tutorial/dependencies/global-dependencies.md +++ b/docs/ko/docs/tutorial/dependencies/global-dependencies.md @@ -24,7 +24,7 @@ //// tab | Python 3.8 Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. diff --git a/docs/ko/docs/tutorial/dependencies/index.md b/docs/ko/docs/tutorial/dependencies/index.md index f7b2f1788..1aba6e787 100644 --- a/docs/ko/docs/tutorial/dependencies/index.md +++ b/docs/ko/docs/tutorial/dependencies/index.md @@ -57,7 +57,7 @@ //// tab | Python 3.10+ Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -71,7 +71,7 @@ //// tab | Python 3.8+ Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -101,7 +101,7 @@ 그 후 위의 값을 포함한 `dict` 자료형으로 반환할 뿐입니다. -/// info | "정보" +/// info | 정보 FastAPI는 0.95.0 버전부터 `Annotated`에 대한 지원을 (그리고 이를 사용하기 권장합니다) 추가했습니다. @@ -139,7 +139,7 @@ FastAPI는 0.95.0 버전부터 `Annotated`에 대한 지원을 (그리고 이를 //// tab | Python 3.10+ Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -153,7 +153,7 @@ FastAPI는 0.95.0 버전부터 `Annotated`에 대한 지원을 (그리고 이를 //// tab | Python 3.8+ Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -195,7 +195,7 @@ FastAPI는 0.95.0 버전부터 `Annotated`에 대한 지원을 (그리고 이를 //// tab | Python 3.10+ Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -209,7 +209,7 @@ FastAPI는 0.95.0 버전부터 `Annotated`에 대한 지원을 (그리고 이를 //// tab | Python 3.8+ Annotated가 없는 경우 -/// tip | "팁" +/// tip | 팁 가능하다면 `Annotated`가 달린 버전을 권장합니다. @@ -231,7 +231,7 @@ FastAPI는 0.95.0 버전부터 `Annotated`에 대한 지원을 (그리고 이를 그리고 그 함수는 *경로 작동 함수*가 작동하는 것과 같은 방식으로 매개변수를 받습니다. -/// tip | "팁" +/// tip | 팁 여러분은 다음 장에서 함수를 제외하고서, "다른 것들"이 어떻게 의존성으로 사용되는지 알게 될 것입니다. @@ -256,7 +256,7 @@ common_parameters --> read_users 이렇게 하면 공용 코드를 한번만 적어도 되며, **FastAPI**는 *경로 작동*을 위해 이에 대한 호출을 처리합니다. -/// check | "확인" +/// check | 확인 특별한 클래스를 만들지 않아도 되며, 이러한 것 혹은 비슷한 종류를 **FastAPI**에 "등록"하기 위해 어떤 곳에 넘겨주지 않아도 됩니다. @@ -300,7 +300,7 @@ commons: Annotated[dict, Depends(common_parameters)] //// -/// tip | "팁" +/// tip | 팁 이는 그저 표준 파이썬이고 "type alias"라고 부르며 사실 **FastAPI**에 국한되는 것은 아닙니다. @@ -322,7 +322,7 @@ commons: Annotated[dict, Depends(common_parameters)] 아무 문제 없습니다. **FastAPI**는 무엇을 할지 알고 있습니다. -/// note | "참고" +/// note | 참고 잘 모르시겠다면, [Async: *"In a hurry?"*](../../async.md){.internal-link target=_blank} 문서에서 `async`와 `await`에 대해 확인할 수 있습니다. diff --git a/docs/ko/docs/tutorial/encoder.md b/docs/ko/docs/tutorial/encoder.md index 732566d6d..52277f258 100644 --- a/docs/ko/docs/tutorial/encoder.md +++ b/docs/ko/docs/tutorial/encoder.md @@ -30,7 +30,7 @@ Pydantic 모델과 같은 객체를 받고 JSON 호환 가능한 버전으로 길이가 긴 문자열 형태의 JSON 형식(문자열)의 데이터가 들어있는 상황에서는 `str`로 반환하지 않습니다. JSON과 모두 호환되는 값과 하위 값이 있는 Python 표준 데이터 구조 (예: `dict`)를 반환합니다. -/// note | "참고" +/// note | 참고 실제로 `jsonable_encoder`는 **FastAPI** 에서 내부적으로 데이터를 변환하는 데 사용하지만, 다른 많은 곳에서도 이는 유용합니다. diff --git a/docs/ko/docs/tutorial/first-steps.md b/docs/ko/docs/tutorial/first-steps.md index c2c48fb3e..4a689b74a 100644 --- a/docs/ko/docs/tutorial/first-steps.md +++ b/docs/ko/docs/tutorial/first-steps.md @@ -24,7 +24,7 @@ $ uvicorn main:app --reload -/// note | "참고" +/// note | 참고 `uvicorn main:app` 명령은 다음을 의미합니다: @@ -139,7 +139,7 @@ API와 통신하는 클라이언트(프론트엔드, 모바일, IoT 애플리케 `FastAPI`는 당신의 API를 위한 모든 기능을 제공하는 파이썬 클래스입니다. -/// note | "기술 세부사항" +/// note | 기술 세부사항 `FastAPI`는 `Starlette`를 직접 상속하는 클래스입니다. @@ -205,7 +205,7 @@ https://example.com/items/foo /items/foo ``` -/// info | "정보" +/// info | 정보 "경로"는 일반적으로 "엔드포인트" 또는 "라우트"라고도 불립니다. @@ -259,7 +259,7 @@ API를 설계할 때 일반적으로 특정 행동을 수행하기 위해 특정 * 경로 `/` * get 작동 사용 -/// info | "`@decorator` 정보" +/// info | `@decorator` 정보 이 `@something` 문법은 파이썬에서 "데코레이터"라 부릅니다. @@ -286,7 +286,7 @@ API를 설계할 때 일반적으로 특정 행동을 수행하기 위해 특정 * `@app.patch()` * `@app.trace()` -/// tip | "팁" +/// tip | 팁 각 작동(HTTP 메소드)을 원하는 대로 사용해도 됩니다. @@ -324,7 +324,7 @@ URL "`/`"에 대한 `GET` 작동을 사용하는 요청을 받을 때마다 **Fa {!../../docs_src/first_steps/tutorial003.py!} ``` -/// note | "참고" +/// note | 참고 차이점을 모르겠다면 [Async: *"바쁘신 경우"*](../async.md#_1){.internal-link target=_blank}을 확인하세요. diff --git a/docs/ko/docs/tutorial/header-params.md b/docs/ko/docs/tutorial/header-params.md index 26e198869..972f52a33 100644 --- a/docs/ko/docs/tutorial/header-params.md +++ b/docs/ko/docs/tutorial/header-params.md @@ -20,7 +20,7 @@ {!../../docs_src/header_params/tutorial001.py!} ``` -/// note | "기술 세부사항" +/// note | 기술 세부사항 `Header`는 `Path`, `Query` 및 `Cookie`의 "자매"클래스입니다. 이 역시 동일한 공통 `Param` 클래스를 상속합니다. @@ -28,7 +28,7 @@ /// -/// info | "정보" +/// info | 정보 헤더를 선언하기 위해서 `Header`를 사용해야 합니다. 그렇지 않으면 해당 매개변수를 쿼리 매개변수로 해석하기 때문입니다. @@ -54,7 +54,7 @@ {!../../docs_src/header_params/tutorial002.py!} ``` -/// warning | "경고" +/// warning | 경고 `convert_underscore`를 `False`로 설정하기 전에, 어떤 HTTP 프록시들과 서버들은 언더스코어가 포함된 헤더 사용을 허락하지 않는다는 것을 명심하십시오. diff --git a/docs/ko/docs/tutorial/index.md b/docs/ko/docs/tutorial/index.md index a148bc76e..9f5328992 100644 --- a/docs/ko/docs/tutorial/index.md +++ b/docs/ko/docs/tutorial/index.md @@ -53,7 +53,7 @@ $ pip install "fastapi[all]" ...이는 코드를 실행하는 서버로 사용할 수 있는 `uvicorn` 또한 포함하고 있습니다. -/// note | "참고" +/// note | 참고 부분적으로 설치할 수도 있습니다. diff --git a/docs/ko/docs/tutorial/middleware.md b/docs/ko/docs/tutorial/middleware.md index f36f11a27..0547066f1 100644 --- a/docs/ko/docs/tutorial/middleware.md +++ b/docs/ko/docs/tutorial/middleware.md @@ -11,7 +11,7 @@ * **응답** 또는 다른 필요한 코드를 실행시키는 동작을 할 수 있습니다. * **응답**를 반환합니다. -/// note | "기술 세부사항" +/// note | 기술 세부사항 만약 `yield`를 사용한 의존성을 가지고 있다면, 미들웨어가 실행되고 난 후에 exit이 실행됩니다. @@ -35,7 +35,7 @@ {!../../docs_src/middleware/tutorial001.py!} ``` -/// tip | "팁" +/// tip | 팁 사용자 정의 헤더는 'X-' 접두사를 사용하여 추가할 수 있습니다. @@ -43,7 +43,7 @@ /// -/// note | "기술적 세부사항" +/// note | 기술적 세부사항 `from starlette.requests import request`를 사용할 수도 있습니다. diff --git a/docs/ko/docs/tutorial/path-operation-configuration.md b/docs/ko/docs/tutorial/path-operation-configuration.md index 6ebe613a8..75a9c71ce 100644 --- a/docs/ko/docs/tutorial/path-operation-configuration.md +++ b/docs/ko/docs/tutorial/path-operation-configuration.md @@ -2,7 +2,7 @@ *경로 작동 데코레이터*를 설정하기 위해서 전달할수 있는 몇 가지 매개변수가 있습니다. -/// warning | "경고" +/// warning | 경고 아래 매개변수들은 *경로 작동 함수*가 아닌 *경로 작동 데코레이터*에 직접 전달된다는 사실을 기억하십시오. @@ -22,7 +22,7 @@ 각 상태 코드들은 응답에 사용되며, OpenAPI 스키마에 추가됩니다. -/// note | "기술적 세부사항" +/// note | 기술적 세부사항 다음과 같이 임포트하셔도 좋습니다. `from starlette import status`. @@ -72,13 +72,13 @@ {!../../docs_src/path_operation_configuration/tutorial005.py!} ``` -/// info | "정보" +/// info | 정보 `response_description`은 구체적으로 응답을 지칭하며, `description`은 일반적인 *경로 작동*을 지칭합니다. /// -/// check | "확인" +/// check | 확인 OpenAPI는 각 *경로 작동*이 응답에 관한 설명을 요구할 것을 명시합니다. diff --git a/docs/ko/docs/tutorial/path-params-numeric-validations.md b/docs/ko/docs/tutorial/path-params-numeric-validations.md index caab2d453..736f2dc1d 100644 --- a/docs/ko/docs/tutorial/path-params-numeric-validations.md +++ b/docs/ko/docs/tutorial/path-params-numeric-validations.md @@ -20,7 +20,7 @@ {!../../docs_src/path_params_numeric_validations/tutorial001.py!} ``` -/// note | "참고" +/// note | 참고 경로 매개변수는 경로의 일부여야 하므로 언제나 필수적입니다. @@ -108,7 +108,7 @@ * `lt`: 작거나(`l`ess `t`han) * `le`: 작거나 같은(`l`ess than or `e`qual) -/// info | "정보" +/// info | 정보 `Query`, `Path`, 그리고 나중에게 보게될 것들은 (여러분이 사용할 필요가 없는) 공통 `Param` 클래스의 서브 클래스입니다. @@ -116,7 +116,7 @@ /// -/// note | "기술 세부사항" +/// note | 기술 세부사항 `fastapi`에서 `Query`, `Path` 등을 임포트 할 때, 이것들은 실제로 함수입니다. diff --git a/docs/ko/docs/tutorial/path-params.md b/docs/ko/docs/tutorial/path-params.md index 09a27a7b3..21808e2ca 100644 --- a/docs/ko/docs/tutorial/path-params.md +++ b/docs/ko/docs/tutorial/path-params.md @@ -24,7 +24,7 @@ 위의 예시에서, `item_id`는 `int`로 선언되었습니다. -/// check | "확인" +/// check | 확인 이 기능은 함수 내에서 오류 검사, 자동완성 등의 편집기 기능을 활용할 수 있게 해줍니다. @@ -38,7 +38,7 @@ {"item_id":3} ``` -/// check | "확인" +/// check | 확인 함수가 받은(반환도 하는) 값은 문자열 `"3"`이 아니라 파이썬 `int` 형인 `3`입니다. @@ -69,7 +69,7 @@ `int`가 아닌 `float`을 전달하는 경우에도 동일한 오류가 나타납니다: http://127.0.0.1:8000/items/4.2 -/// check | "확인" +/// check | 확인 즉, 파이썬 타입 선언을 하면 **FastAPI**는 데이터 검증을 합니다. @@ -85,7 +85,7 @@ -/// check | "확인" +/// check | 확인 그저 파이썬 타입 선언을 하기만 하면 **FastAPI**는 자동 대화형 API 문서(Swagger UI)를 제공합니다. @@ -143,13 +143,13 @@ {!../../docs_src/path_params/tutorial005.py!} ``` -/// info | "정보" +/// info | 정보 열거형(또는 enums)은 파이썬 버전 3.4 이후로 사용 가능합니다. /// -/// tip | "팁" +/// tip | 팁 혹시 궁금하다면, "AlexNet", "ResNet", 그리고 "LeNet"은 그저 기계 학습 모델들의 이름입니다. @@ -189,7 +189,7 @@ {!../../docs_src/path_params/tutorial005.py!} ``` -/// tip | "팁" +/// tip | 팁 `ModelName.lenet.value`로도 값 `"lenet"`에 접근할 수 있습니다. @@ -246,7 +246,7 @@ Starlette의 옵션을 직접 이용하여 다음과 같은 URL을 사용함으 {!../../docs_src/path_params/tutorial004.py!} ``` -/// tip | "팁" +/// tip | 팁 매개변수가 가져야 하는 값이 `/home/johndoe/myfile.txt`와 같이 슬래시로 시작(`/`)해야 할 수 있습니다. diff --git a/docs/ko/docs/tutorial/query-params-str-validations.md b/docs/ko/docs/tutorial/query-params-str-validations.md index e44f6dd16..71f884e83 100644 --- a/docs/ko/docs/tutorial/query-params-str-validations.md +++ b/docs/ko/docs/tutorial/query-params-str-validations.md @@ -10,7 +10,7 @@ 쿼리 매개변수 `q`는 `Optional[str]` 자료형입니다. 즉, `str` 자료형이지만 `None` 역시 될 수 있음을 뜻하고, 실제로 기본값은 `None`이기 때문에 FastAPI는 이 매개변수가 필수가 아니라는 것을 압니다. -/// note | "참고" +/// note | 참고 FastAPI는 `q`의 기본값이 `= None`이기 때문에 필수가 아님을 압니다. @@ -54,7 +54,7 @@ q: Optional[str] = None 하지만 명시적으로 쿼리 매개변수를 선언합니다. -/// info | "정보" +/// info | 정보 FastAPI는 다음 부분에 관심이 있습니다: @@ -118,7 +118,7 @@ q: str = Query(None, max_length=50) {!../../docs_src/query_params_str_validations/tutorial005.py!} ``` -/// note | "참고" +/// note | 참고 기본값을 갖는 것만으로 매개변수는 선택적이 됩니다. @@ -150,7 +150,7 @@ q: Optional[str] = Query(None, min_length=3) {!../../docs_src/query_params_str_validations/tutorial006.py!} ``` -/// info | "정보" +/// info | 정보 이전에 `...`를 본적이 없다면: 특별한 단일값으로, 파이썬의 일부이며 "Ellipsis"라 부릅니다. @@ -187,7 +187,7 @@ http://localhost:8000/items/?q=foo&q=bar } ``` -/// tip | "팁" +/// tip | 팁 위의 예와 같이 `list` 자료형으로 쿼리 매개변수를 선언하려면 `Query`를 명시적으로 사용해야 합니다. 그렇지 않으면 요청 본문으로 해석됩니다. @@ -230,7 +230,7 @@ http://localhost:8000/items/ {!../../docs_src/query_params_str_validations/tutorial013.py!} ``` -/// note | "참고" +/// note | 참고 이 경우 FastAPI는 리스트의 내용을 검사하지 않음을 명심하기 바랍니다. @@ -244,7 +244,7 @@ http://localhost:8000/items/ 해당 정보는 생성된 OpenAPI에 포함되고 문서 사용자 인터페이스 및 외부 도구에서 사용됩니다. -/// note | "참고" +/// note | 참고 도구에 따라 OpenAPI 지원 수준이 다를 수 있음을 명심하기 바랍니다. diff --git a/docs/ko/docs/tutorial/query-params.md b/docs/ko/docs/tutorial/query-params.md index b2a946c09..7fa3e8c53 100644 --- a/docs/ko/docs/tutorial/query-params.md +++ b/docs/ko/docs/tutorial/query-params.md @@ -69,13 +69,13 @@ http://127.0.0.1:8000/items/?skip=20 이 경우 함수 매개변수 `q`는 선택적이며 기본값으로 `None` 값이 됩니다. -/// check | "확인" +/// check | 확인 **FastAPI**는 `item_id`가 경로 매개변수이고 `q`는 경로 매개변수가 아닌 쿼리 매개변수라는 것을 알 정도로 충분히 똑똑합니다. /// -/// note | "참고" +/// note | 참고 FastAPI는 `q`가 `= None`이므로 선택적이라는 것을 인지합니다. @@ -200,7 +200,7 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy * `skip`, 기본값이 `0`인 `int`. * `limit`, 선택적인 `int`. -/// tip | "팁" +/// tip | 팁 [경로 매개변수](path-params.md#_8){.internal-link target=_blank}와 마찬가지로 `Enum`을 사용할 수 있습니다. diff --git a/docs/ko/docs/tutorial/request-files.md b/docs/ko/docs/tutorial/request-files.md index 40579dd51..ca0f43978 100644 --- a/docs/ko/docs/tutorial/request-files.md +++ b/docs/ko/docs/tutorial/request-files.md @@ -2,7 +2,7 @@ `File`을 사용하여 클라이언트가 업로드할 파일들을 정의할 수 있습니다. -/// info | "정보" +/// info | 정보 업로드된 파일을 전달받기 위해 먼저 `python-multipart`를 설치해야합니다. @@ -28,7 +28,7 @@ {!../../docs_src/request_files/tutorial001.py!} ``` -/// info | "정보" +/// info | 정보 `File` 은 `Form` 으로부터 직접 상속된 클래스입니다. @@ -36,7 +36,7 @@ /// -/// tip | "팁" +/// tip | 팁 File의 본문을 선언할 때, 매개변수가 쿼리 매개변수 또는 본문(JSON) 매개변수로 해석되는 것을 방지하기 위해 `File` 을 사용해야합니다. @@ -104,7 +104,7 @@ contents = myfile.file.read() /// -/// note | "Starlette 기술적 세부사항" +/// note | Starlette 기술적 세부사항 **FastAPI**의 `UploadFile` 은 **Starlette**의 `UploadFile` 을 직접적으로 상속받지만, **Pydantic** 및 FastAPI의 다른 부분들과의 호환성을 위해 필요한 부분들이 추가되었습니다. @@ -116,7 +116,7 @@ HTML의 폼들(`
`)이 서버에 데이터를 전송하는 방식은 **FastAPI**는 JSON 대신 올바른 위치에서 데이터를 읽을 수 있도록 합니다. -/// note | "기술적 세부사항" +/// note | 기술적 세부사항 폼의 데이터는 파일이 포함되지 않은 경우 일반적으로 "미디어 유형" `application/x-www-form-urlencoded` 을 사용해 인코딩 됩니다. @@ -126,7 +126,7 @@ HTML의 폼들(`
`)이 서버에 데이터를 전송하는 방식은 /// -/// warning | "경고" +/// warning | 경고 다수의 `File` 과 `Form` 매개변수를 한 *경로 작동*에 선언하는 것이 가능하지만, 요청의 본문이 `application/json` 가 아닌 `multipart/form-data` 로 인코딩 되기 때문에 JSON으로 받아야하는 `Body` 필드를 함께 선언할 수는 없습니다. @@ -148,7 +148,7 @@ HTML의 폼들(`
`)이 서버에 데이터를 전송하는 방식은 선언한대로, `bytes` 의 `list` 또는 `UploadFile` 들을 전송받을 것입니다. -/// note | "참고" +/// note | 참고 2019년 4월 14일부터 Swagger UI가 하나의 폼 필드로 다수의 파일을 업로드하는 것을 지원하지 않습니다. 더 많은 정보를 원하면, #4276과 #3641을 참고하세요. @@ -158,7 +158,7 @@ HTML의 폼들(`
`)이 서버에 데이터를 전송하는 방식은 /// -/// note | "기술적 세부사항" +/// note | 기술적 세부사항 `from starlette.responses import HTMLResponse` 역시 사용할 수 있습니다. diff --git a/docs/ko/docs/tutorial/request-forms-and-files.md b/docs/ko/docs/tutorial/request-forms-and-files.md index 24501fe34..75bca9f15 100644 --- a/docs/ko/docs/tutorial/request-forms-and-files.md +++ b/docs/ko/docs/tutorial/request-forms-and-files.md @@ -2,7 +2,7 @@ `File` 과 `Form` 을 사용하여 파일과 폼을 함께 정의할 수 있습니다. -/// info | "정보" +/// info | 정보 파일과 폼 데이터를 함께, 또는 각각 업로드하기 위해 먼저 `python-multipart`를 설치해야합니다. @@ -28,7 +28,7 @@ 어떤 파일들은 `bytes`로, 또 어떤 파일들은 `UploadFile`로 선언할 수 있습니다. -/// warning | "경고" +/// warning | 경고 다수의 `File`과 `Form` 매개변수를 한 *경로 작동*에 선언하는 것이 가능하지만, 요청의 본문이 `application/json`가 아닌 `multipart/form-data`로 인코딩 되기 때문에 JSON으로 받아야하는 `Body` 필드를 함께 선언할 수는 없습니다. diff --git a/docs/ko/docs/tutorial/response-model.md b/docs/ko/docs/tutorial/response-model.md index 74034e34d..6ba9654d6 100644 --- a/docs/ko/docs/tutorial/response-model.md +++ b/docs/ko/docs/tutorial/response-model.md @@ -12,7 +12,7 @@ {!../../docs_src/response_model/tutorial001.py!} ``` -/// note | "참고" +/// note | 참고 `response_model`은 "데코레이터" 메소드(`get`, `post`, 등)의 매개변수입니다. 모든 매개변수들과 본문(body)처럼 *경로 작동 함수*가 아닙니다. @@ -31,7 +31,7 @@ FastAPI는 이 `response_model`를 사용하여: * 해당 모델의 출력 데이터 제한. 이것이 얼마나 중요한지 아래에서 볼 것입니다. -/// note | "기술 세부사항" +/// note | 기술 세부사항 응답 모델은 함수의 타입 어노테이션 대신 이 매개변수로 선언하는데, 경로 함수가 실제 응답 모델을 반환하지 않고 `dict`, 데이터베이스 객체나 기타 다른 모델을 `response_model`을 사용하여 필드 제한과 직렬화를 수행하고 반환할 수 있기 때문입니다 @@ -57,7 +57,7 @@ FastAPI는 이 `response_model`를 사용하여: 그러나 동일한 모델을 다른 *경로 작동*에서 사용할 경우, 모든 클라이언트에게 사용자의 비밀번호를 발신할 수 있습니다. -/// danger | "위험" +/// danger | 위험 절대로 사용자의 평문 비밀번호를 저장하거나 응답으로 발신하지 마십시오. @@ -130,13 +130,13 @@ FastAPI는 이 `response_model`를 사용하여: } ``` -/// info | "정보" +/// info | 정보 FastAPI는 이를 위해 Pydantic 모델의 `.dict()`의 `exclude_unset` 매개변수를 사용합니다. /// -/// info | "정보" +/// info | 정보 아래 또한 사용할 수 있습니다: @@ -181,7 +181,7 @@ ID가 `baz`인 항목(items)처럼 기본값과 동일한 값을 갖는다면: 따라서 JSON 스키마에 포함됩니다. -/// tip | "팁" +/// tip | 팁 `None` 뿐만 아니라 다른 어떤 것도 기본값이 될 수 있습니다. @@ -197,7 +197,7 @@ ID가 `baz`인 항목(items)처럼 기본값과 동일한 값을 갖는다면: Pydantic 모델이 하나만 있고 출력에서 ​​일부 데이터를 제거하려는 경우 빠른 지름길로 사용할 수 있습니다. -/// tip | "팁" +/// tip | 팁 하지만 이러한 매개변수 대신 여러 클래스를 사용하여 위 아이디어를 사용하는 것을 추천합니다. @@ -211,7 +211,7 @@ Pydantic 모델이 하나만 있고 출력에서 ​​일부 데이터를 제 {!../../docs_src/response_model/tutorial005.py!} ``` -/// tip | "팁" +/// tip | 팁 문법 `{"name", "description"}`은 두 값을 갖는 `set`을 만듭니다. diff --git a/docs/ko/docs/tutorial/response-status-code.md b/docs/ko/docs/tutorial/response-status-code.md index 57eef6ba1..8e3a16645 100644 --- a/docs/ko/docs/tutorial/response-status-code.md +++ b/docs/ko/docs/tutorial/response-status-code.md @@ -12,7 +12,7 @@ {!../../docs_src/response_status_code/tutorial001.py!} ``` -/// note | "참고" +/// note | 참고 `status_code` 는 "데코레이터" 메소드(`get`, `post` 등)의 매개변수입니다. 모든 매개변수들과 본문처럼 *경로 작동 함수*가 아닙니다. @@ -20,7 +20,7 @@ `status_code` 매개변수는 HTTP 상태 코드를 숫자로 입력받습니다. -/// info | "정보" +/// info | 정보 `status_code` 는 파이썬의 `http.HTTPStatus` 와 같은 `IntEnum` 을 입력받을 수도 있습니다. @@ -33,7 +33,7 @@ -/// note | "참고" +/// note | 참고 어떤 응답 코드들은 해당 응답에 본문이 없다는 것을 의미하기도 합니다 (다음 항목 참고). @@ -43,7 +43,7 @@ ## HTTP 상태 코드에 대하여 -/// note | "참고" +/// note | 참고 만약 HTTP 상태 코드에 대하여 이미 알고있다면, 다음 항목으로 넘어가십시오. @@ -66,7 +66,7 @@ HTTP는 세자리의 숫자 상태 코드를 응답의 일부로 전송합니다 * 일반적인 클라이언트 오류의 경우 `400` 을 사용할 수 있습니다. * `5xx` 상태 코드는 서버 오류에 사용됩니다. 이것들을 직접 사용할 일은 거의 없습니다. 응용 프로그램 코드나 서버의 일부에서 문제가 발생하면 자동으로 이들 상태 코드 중 하나를 반환합니다. -/// tip | "팁" +/// tip | 팁 각각의 상태 코드와 이들이 의미하는 내용에 대해 더 알고싶다면 MDN HTTP 상태 코드에 관한 문서 를 확인하십시오. @@ -94,7 +94,7 @@ HTTP는 세자리의 숫자 상태 코드를 응답의 일부로 전송합니다 -/// note | "기술적 세부사항" +/// note | 기술적 세부사항 `from starlette import status` 역시 사용할 수 있습니다. diff --git a/docs/ko/docs/tutorial/schema-extra-example.md b/docs/ko/docs/tutorial/schema-extra-example.md index 71052b334..77e94db72 100644 --- a/docs/ko/docs/tutorial/schema-extra-example.md +++ b/docs/ko/docs/tutorial/schema-extra-example.md @@ -8,35 +8,15 @@ 생성된 JSON 스키마에 추가될 Pydantic 모델을 위한 `examples`을 선언할 수 있습니다. -//// tab | Python 3.10+ Pydantic v2 +//// tab | Pydantic v2 -```Python hl_lines="13-24" -{!> ../../docs_src/schema_extra_example/tutorial001_py310.py!} -``` +{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *} //// -//// tab | Python 3.10+ Pydantic v1 +//// tab | Pydantic v1 -```Python hl_lines="13-23" -{!> ../../docs_src/schema_extra_example/tutorial001_py310_pv1.py!} -``` - -//// - -//// tab | Python 3.8+ Pydantic v2 - -```Python hl_lines="15-26" -{!> ../../docs_src/schema_extra_example/tutorial001.py!} -``` - -//// - -//// tab | Python 3.8+ Pydantic v1 - -```Python hl_lines="15-25" -{!> ../../docs_src/schema_extra_example/tutorial001_pv1.py!} -``` +{* ../../docs_src/schema_extra_example/tutorial001_pv1_py310.py hl[13:23] *} //// @@ -58,7 +38,7 @@ Pydantic v1에서 ../../docs_src/schema_extra_example/tutorial002_py310.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="4 10-13" -{!> ../../docs_src/schema_extra_example/tutorial002.py!} -``` - -//// +{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *} ## JSON Schema에서의 `examples` - OpenAPI @@ -114,57 +80,7 @@ Pydantic 모델과 같이 `Field()`를 사용할 때 추가적인 `examples`를 여기, `Body()`에 예상되는 예제 데이터 하나를 포함한 `examples`를 넘겼습니다: -//// tab | Python 3.10+ - -```Python hl_lines="22-29" -{!> ../../docs_src/schema_extra_example/tutorial003_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="22-29" -{!> ../../docs_src/schema_extra_example/tutorial003_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="23-30" -{!> ../../docs_src/schema_extra_example/tutorial003_an.py!} -``` - -//// - -//// tab | Python 3.10+ Annotated가 없는 경우 - -/// tip | "팁" - -가능하다면 `Annotated`가 달린 버전을 권장합니다. - -/// - -```Python hl_lines="18-25" -{!> ../../docs_src/schema_extra_example/tutorial003_py310.py!} -``` - -//// - -//// tab | Python 3.8+ Annotated가 없는 경우 - -/// tip | "팁" - -가능하다면 `Annotated`가 달린 버전을 권장합니다. - -/// - -```Python hl_lines="20-27" -{!> ../../docs_src/schema_extra_example/tutorial003.py!} -``` - -//// +{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *} ### 문서 UI 예시 @@ -176,57 +92,7 @@ Pydantic 모델과 같이 `Field()`를 사용할 때 추가적인 `examples`를 물론 여러 `examples`를 넘길 수 있습니다: -//// tab | Python 3.10+ - -```Python hl_lines="23-38" -{!> ../../docs_src/schema_extra_example/tutorial004_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="23-38" -{!> ../../docs_src/schema_extra_example/tutorial004_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="24-39" -{!> ../../docs_src/schema_extra_example/tutorial004_an.py!} -``` - -//// - -//// tab | Python 3.10+ Annotated가 없는 경우 - -/// tip | "팁" - -가능하다면 `Annotated`가 달린 버전을 권장합니다. - -/// - -```Python hl_lines="19-34" -{!> ../../docs_src/schema_extra_example/tutorial004_py310.py!} -``` - -//// - -//// tab | Python 3.8+ Annotated가 없는 경우 - -/// tip | "팁" - -가능하다면 `Annotated`가 달린 버전을 권장합니다. - -/// - -```Python hl_lines="21-36" -{!> ../../docs_src/schema_extra_example/tutorial004.py!} -``` - -//// +{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *} 이와 같이 하면 이 예제는 그 본문 데이터를 위한 내부 **JSON 스키마**의 일부가 될 것입니다. @@ -267,57 +133,7 @@ Pydantic 모델과 같이 `Field()`를 사용할 때 추가적인 `examples`를 이를 다음과 같이 사용할 수 있습니다: -//// tab | Python 3.10+ - -```Python hl_lines="23-49" -{!> ../../docs_src/schema_extra_example/tutorial005_an_py310.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python hl_lines="23-49" -{!> ../../docs_src/schema_extra_example/tutorial005_an_py39.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python hl_lines="24-50" -{!> ../../docs_src/schema_extra_example/tutorial005_an.py!} -``` - -//// - -//// tab | Python 3.10+ Annotated가 없는 경우 - -/// tip | "팁" - -가능하다면 `Annotated`가 달린 버전을 권장합니다. - -/// - -```Python hl_lines="19-45" -{!> ../../docs_src/schema_extra_example/tutorial005_py310.py!} -``` - -//// - -//// tab | Python 3.8+ Annotated가 없는 경우 - -/// tip | "팁" - -가능하다면 `Annotated`가 달린 버전을 권장합니다. - -/// - -```Python hl_lines="21-47" -{!> ../../docs_src/schema_extra_example/tutorial005.py!} -``` - -//// +{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *} ### 문서 UI에서의 OpenAPI 예시 @@ -327,7 +143,7 @@ Pydantic 모델과 같이 `Field()`를 사용할 때 추가적인 `examples`를 ## 기술적 세부 사항 -/// tip | "팁" +/// tip | 팁 이미 **FastAPI**의 **0.99.0 혹은 그 이상** 버전을 사용하고 있다면, 이 세부 사항을 **스킵**해도 상관 없을 것입니다. @@ -337,7 +153,7 @@ Pydantic 모델과 같이 `Field()`를 사용할 때 추가적인 `examples`를 /// -/// warning | "경고" +/// warning | 경고 표준 **JSON 스키마**와 **OpenAPI**에 대한 아주 기술적인 세부사항입니다. @@ -361,7 +177,7 @@ OpenAPI는 또한 `example`과 `examples` 필드를 명세서의 다른 부분 * `File()` * `Form()` -/// info | "정보" +/// info | 정보 이 예전 OpenAPI-특화 `examples` 매개변수는 이제 FastAPI `0.103.0`부터 `openapi_examples`입니다. @@ -377,7 +193,7 @@ OpenAPI는 또한 `example`과 `examples` 필드를 명세서의 다른 부분 JSON 스키마의 새로운 `examples` 필드는 예제 속 **단순한 `list`**이며, (위에서 상술한 것처럼) OpenAPI의 다른 곳에 존재하는 dict으로 된 추가적인 메타데이터가 아닙니다. -/// info | "정보" +/// info | 정보 더 쉽고 새로운 JSON 스키마와의 통합과 함께 OpenAPI 3.1.0가 배포되었지만, 잠시동안 자동 문서 생성을 제공하는 도구인 Swagger UI는 OpenAPI 3.1.0을 지원하지 않았습니다 (5.0.0 버전부터 지원합니다 🎉). diff --git a/docs/ko/docs/tutorial/security/get-current-user.md b/docs/ko/docs/tutorial/security/get-current-user.md index 56f5792a7..cf550735a 100644 --- a/docs/ko/docs/tutorial/security/get-current-user.md +++ b/docs/ko/docs/tutorial/security/get-current-user.md @@ -102,7 +102,7 @@ Pydantic 모델인 `User`로 `current_user`의 타입을 선언하는 것을 알 이것은 모든 완료 및 타입 검사를 통해 함수 내부에서 우리를 도울 것입니다. -/// tip | "팁" +/// tip | 팁 요청 본문도 Pydantic 모델로 선언된다는 것을 기억할 것입니다. @@ -110,7 +110,7 @@ Pydantic 모델인 `User`로 `current_user`의 타입을 선언하는 것을 알 /// -/// check | "확인" +/// check | 확인 이 의존성 시스템이 설계된 방식은 모두 `User` 모델을 반환하는 다양한 의존성(다른 "의존적인")을 가질 수 있도록 합니다. diff --git a/docs/ko/docs/tutorial/static-files.md b/docs/ko/docs/tutorial/static-files.md index 90a60d193..af785f206 100644 --- a/docs/ko/docs/tutorial/static-files.md +++ b/docs/ko/docs/tutorial/static-files.md @@ -11,7 +11,7 @@ {!../../docs_src/static_files/tutorial001.py!} ``` -/// note | "기술적 세부사항" +/// note | 기술적 세부사항 `from starlette.staticfiles import StaticFiles` 를 사용할 수도 있습니다. diff --git a/docs/pl/docs/help-fastapi.md b/docs/pl/docs/help-fastapi.md index 4daad5e90..3ea328dc2 100644 --- a/docs/pl/docs/help-fastapi.md +++ b/docs/pl/docs/help-fastapi.md @@ -229,7 +229,7 @@ Jeśli możesz mi w tym pomóc, **pomożesz mi utrzymać FastAPI** i zapewnisz Dołącz do 👥 serwera czatu na Discordzie 👥 i spędzaj czas z innymi w społeczności FastAPI. -/// tip | "Wskazówka" +/// tip | Wskazówka Jeśli masz pytania, zadaj je w Dyskusjach na GitHubie, jest dużo większa szansa, że otrzymasz pomoc od [Ekspertów FastAPI](fastapi-people.md#fastapi-experts){.internal-link target=_blank}. diff --git a/docs/pl/docs/tutorial/first-steps.md b/docs/pl/docs/tutorial/first-steps.md index 9466ca84d..8fa4c75ad 100644 --- a/docs/pl/docs/tutorial/first-steps.md +++ b/docs/pl/docs/tutorial/first-steps.md @@ -135,7 +135,7 @@ Możesz go również użyć do automatycznego generowania kodu dla klientów, kt `FastAPI` jest klasą, która zapewnia wszystkie funkcjonalności Twojego API. -/// note | "Szczegóły techniczne" +/// note | Szczegóły techniczne `FastAPI` jest klasą, która dziedziczy bezpośrednio z `Starlette`. @@ -249,7 +249,7 @@ Będziemy je również nazywali "**operacjami**". * ścieżki `/` * używając operacji get -/// info | "`@decorator` Info" +/// info | `@decorator` Info Składnia `@something` jest w Pythonie nazywana "dekoratorem". diff --git a/docs/pt/docs/advanced/additional-responses.md b/docs/pt/docs/advanced/additional-responses.md index 46cf1efc3..58e75ad93 100644 --- a/docs/pt/docs/advanced/additional-responses.md +++ b/docs/pt/docs/advanced/additional-responses.md @@ -1,6 +1,6 @@ # Retornos Adicionais no OpenAPI -/// warning | "Aviso" +/// warning | Aviso Este é um tema bem avançado. @@ -30,13 +30,13 @@ Por exemplo, para declarar um outro retorno com o status code `404` e um modelo {!../../docs_src/additional_responses/tutorial001.py!} ``` -/// note | "Nota" +/// note | Nota Lembre-se que você deve retornar o `JSONResponse` diretamente. /// -/// info | "Informação" +/// info | Informação A chave `model` não é parte do OpenAPI. @@ -181,13 +181,13 @@ Por exemplo, você pode adicionar um media type adicional de `image/png`, declar {!../../docs_src/additional_responses/tutorial002.py!} ``` -/// note | "Nota" +/// note | Nota Note que você deve retornar a imagem utilizando um `FileResponse` diretamente. /// -/// info | "Informação" +/// info | Informação 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`). diff --git a/docs/pt/docs/advanced/additional-status-codes.md b/docs/pt/docs/advanced/additional-status-codes.md index 02bb4c015..5fe970d2a 100644 --- a/docs/pt/docs/advanced/additional-status-codes.md +++ b/docs/pt/docs/advanced/additional-status-codes.md @@ -40,7 +40,7 @@ Para conseguir isso, importe `JSONResponse` e retorne o seu conteúdo diretament //// tab | Python 3.10+ non-Annotated -/// tip | "Dica" +/// tip | Dica Faça uso da versão `Annotated` quando possível. @@ -54,7 +54,7 @@ Faça uso da versão `Annotated` quando possível. //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Faça uso da versão `Annotated` quando possível. @@ -66,7 +66,7 @@ Faça uso da versão `Annotated` quando possível. //// -/// warning | "Aviso" +/// warning | Aviso Quando você retorna um `Response` diretamente, como no exemplo acima, ele será retornado diretamente. @@ -76,7 +76,7 @@ Garanta que ele tenha toda informação que você deseja, e que os valores sejam /// -/// note | "Detalhes técnicos" +/// note | Detalhes técnicos Você também pode utilizar `from starlette.responses import JSONResponse`. diff --git a/docs/pt/docs/advanced/advanced-dependencies.md b/docs/pt/docs/advanced/advanced-dependencies.md index a656390a4..52fe121f9 100644 --- a/docs/pt/docs/advanced/advanced-dependencies.md +++ b/docs/pt/docs/advanced/advanced-dependencies.md @@ -36,7 +36,7 @@ Para fazer isso, nós declaramos o método `__call__`: //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Prefira utilizar a versão `Annotated` se possível. @@ -72,7 +72,7 @@ E agora, nós podemos utilizar o `__init__` para declarar os parâmetros da inst //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Prefira utilizar a versão `Annotated` se possível. @@ -108,7 +108,7 @@ Nós poderíamos criar uma instância desta classe com: //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Prefira utilizar a versão `Annotated` se possível. @@ -152,7 +152,7 @@ checker(q="somequery") //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Prefira utilizar a versão `Annotated` se possível. @@ -164,7 +164,7 @@ Prefira utilizar a versão `Annotated` se possível. //// -/// tip | "Dica" +/// tip | Dica Tudo isso parece não ser natural. E pode não estar muito claro ou aparentar ser útil ainda. diff --git a/docs/pt/docs/advanced/async-tests.md b/docs/pt/docs/advanced/async-tests.md index c81d6124b..8fae97298 100644 --- a/docs/pt/docs/advanced/async-tests.md +++ b/docs/pt/docs/advanced/async-tests.md @@ -64,7 +64,7 @@ O marcador `@pytest.mark.anyio` informa ao pytest que esta função de teste dev {!../../docs_src/async_tests/test_main.py!} ``` -/// tip | "Dica" +/// tip | Dica Note que a função de teste é `async def` agora, no lugar de apenas `def` como quando estávamos utilizando o `TestClient` anteriormente. @@ -84,13 +84,13 @@ response = client.get('/') ...que nós utilizamos para fazer as nossas requisições utilizando o `TestClient`. -/// tip | "Dica" +/// tip | Dica Note que nós estamos utilizando async/await com o novo `AsyncClient` - a requisição é assíncrona. /// -/// warning | "Aviso" +/// warning | Aviso Se a sua aplicação depende dos eventos de vida útil (*lifespan*), o `AsyncClient` não acionará estes eventos. Para garantir que eles são acionados, utilize o `LifespanManager` do florimondmanca/asgi-lifespan. @@ -100,7 +100,7 @@ Se a sua aplicação depende dos eventos de vida útil (*lifespan*), o `AsyncCli Como a função de teste agora é assíncrona, você pode chamar (e `esperar`) outras funções `async` além de enviar requisições para a sua aplicação FastAPI em seus testes, exatamente como você as chamaria em qualquer outro lugar do seu código. -/// tip | "Dica" +/// 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) 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")`. diff --git a/docs/pt/docs/advanced/behind-a-proxy.md b/docs/pt/docs/advanced/behind-a-proxy.md index 12fd83f3d..6837c9542 100644 --- a/docs/pt/docs/advanced/behind-a-proxy.md +++ b/docs/pt/docs/advanced/behind-a-proxy.md @@ -41,7 +41,7 @@ browser --> proxy proxy --> server ``` -/// tip | "Dica" +/// tip | Dica O IP `0.0.0.0` é comumente usado para significar que o programa escuta em todos os IPs disponíveis naquela máquina/servidor. @@ -82,7 +82,7 @@ $ fastapi run main.py --root-path /api/v1 Se você usar Hypercorn, ele também tem a opção `--root-path`. -/// note | "Detalhes Técnicos" +/// note | Detalhes Técnicos A especificação ASGI define um `root_path` para esse caso de uso. @@ -172,7 +172,7 @@ Então, crie um arquivo `traefik.toml` com: Isso diz ao Traefik para escutar na porta 9999 e usar outro arquivo `routes.toml`. -/// tip | "Dica" +/// tip | Dica Estamos usando a porta 9999 em vez da porta padrão HTTP 80 para que você não precise executá-lo com privilégios de administrador (`sudo`). @@ -242,7 +242,7 @@ Agora, se você for ao URL com a porta para o Uvicorn: -/// tip | "Dica" +/// tip | Dica A interface de documentação interagirá com o servidor que você selecionar. diff --git a/docs/pt/docs/advanced/events.md b/docs/pt/docs/advanced/events.md index 02f5b6d2b..783dbfc83 100644 --- a/docs/pt/docs/advanced/events.md +++ b/docs/pt/docs/advanced/events.md @@ -39,7 +39,7 @@ Aqui nós estamos simulando a *inicialização* custosa do carregamento do model E então, logo após o `yield`, descarregaremos o modelo. Esse código será executado **após** a aplicação **terminar de lidar com as requisições**, pouco antes do *encerramento*. Isso poderia, por exemplo, liberar recursos como memória ou GPU. -/// tip | "Dica" +/// tip | Dica O `shutdown` aconteceria quando você estivesse **encerrando** a aplicação. @@ -95,7 +95,7 @@ O parâmetro `lifespan` da aplicação `FastAPI` usa um **Gerenciador de Context ## Eventos alternativos (deprecados) -/// warning | "Aviso" +/// warning | Aviso A maneira recomendada para lidar com a *inicialização* e o *encerramento* é usando o parâmetro `lifespan` da aplicação `FastAPI` como descrito acima. @@ -133,13 +133,13 @@ Para adicionar uma função que deve ser executada quando a aplicação estiver Aqui, a função de manipulação de evento `shutdown` irá escrever uma linha de texto `"Application shutdown"` no arquivo `log.txt`. -/// info | "Informação" +/// info | Informação Na função `open()`, o `mode="a"` significa "acrescentar", então, a linha irá ser adicionada depois de qualquer coisa que esteja naquele arquivo, sem sobrescrever o conteúdo anterior. /// -/// tip | "Dica" +/// tip | Dica Perceba que nesse caso nós estamos usando a função padrão do Python `open()` que interage com um arquivo. @@ -165,7 +165,7 @@ Só um detalhe técnico para nerds curiosos. 🤓 Por baixo, na especificação técnica ASGI, essa é a parte do Protocolo Lifespan, e define eventos chamados `startup` e `shutdown`. -/// info | "Informação" +/// info | Informação Você pode ler mais sobre o manipulador `lifespan` do Starlette na Documentação do Lifespan Starlette. diff --git a/docs/pt/docs/advanced/index.md b/docs/pt/docs/advanced/index.md index 2569fc914..22ba2bf4a 100644 --- a/docs/pt/docs/advanced/index.md +++ b/docs/pt/docs/advanced/index.md @@ -6,7 +6,7 @@ O [Tutorial - Guia de Usuário](../tutorial/index.md){.internal-link target=_bla Na próxima seção você verá outras opções, configurações, e recursos adicionais. -/// tip | "Dica" +/// tip | Dica As próximas seções **não são necessáriamente "avançadas"** diff --git a/docs/pt/docs/advanced/openapi-webhooks.md b/docs/pt/docs/advanced/openapi-webhooks.md index 5a0226c74..344fe6371 100644 --- a/docs/pt/docs/advanced/openapi-webhooks.md +++ b/docs/pt/docs/advanced/openapi-webhooks.md @@ -22,7 +22,7 @@ Com o **FastAPI**, utilizando o OpenAPI, você pode definir os nomes destes webh Isto pode facilitar bastante para os seus usuários **implementarem as APIs deles** para receber as requisições dos seus **webhooks**, eles podem inclusive ser capazes de gerar parte do código da API deles. -/// info | "Informação" +/// info | Informação Webhooks estão disponíveis a partir do OpenAPI 3.1.0, e possui suporte do FastAPI a partir da versão `0.99.0`. @@ -38,7 +38,7 @@ Quando você cria uma aplicação com o **FastAPI**, existe um atributo chamado Os webhooks que você define aparecerão no esquema do **OpenAPI** e na **página de documentação** gerada automaticamente. -/// info | "Informação" +/// info | Informação O objeto `app.webhooks` é na verdade apenas um `APIRouter`, o mesmo tipo que você utilizaria ao estruturar a sua aplicação com diversos arquivos. diff --git a/docs/pt/docs/advanced/response-cookies.md b/docs/pt/docs/advanced/response-cookies.md index d0821b5b2..cd8f39db3 100644 --- a/docs/pt/docs/advanced/response-cookies.md +++ b/docs/pt/docs/advanced/response-cookies.md @@ -42,7 +42,7 @@ E também que você não esteja enviando nenhum dado que deveria ter sido filtra ### Mais informações -/// note | "Detalhes Técnicos" +/// note | Detalhes Técnicos Você também poderia usar `from starlette.responses import Response` ou `from starlette.responses import JSONResponse`. diff --git a/docs/pt/docs/advanced/response-headers.md b/docs/pt/docs/advanced/response-headers.md index d1958e46b..98a7e0b6d 100644 --- a/docs/pt/docs/advanced/response-headers.md +++ b/docs/pt/docs/advanced/response-headers.md @@ -28,7 +28,7 @@ Crie uma resposta conforme descrito em [Retornar uma resposta diretamente](respo {!../../docs_src/response_headers/tutorial001.py!} ``` -/// note | "Detalhes técnicos" +/// note | Detalhes técnicos Você também pode usar `from starlette.responses import Response` ou `from starlette.responses import JSONResponse`. diff --git a/docs/pt/docs/advanced/security/http-basic-auth.md b/docs/pt/docs/advanced/security/http-basic-auth.md index 26983a103..28c718f64 100644 --- a/docs/pt/docs/advanced/security/http-basic-auth.md +++ b/docs/pt/docs/advanced/security/http-basic-auth.md @@ -38,7 +38,7 @@ Então, quando você digitar o usuário e senha, o navegador os envia automatica //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Prefira utilizar a versão `Annotated` se possível. @@ -86,7 +86,7 @@ Então nós podemos utilizar o `secrets.compare_digest()` para garantir que o `c //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Prefira utilizar a versão `Annotated` se possível. @@ -179,7 +179,7 @@ Após detectar que as credenciais estão incorretas, retorne um `HTTPException` //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Prefira utilizar a versão `Annotated` se possível. diff --git a/docs/pt/docs/advanced/security/index.md b/docs/pt/docs/advanced/security/index.md index ae63f1c96..6c7becb67 100644 --- a/docs/pt/docs/advanced/security/index.md +++ b/docs/pt/docs/advanced/security/index.md @@ -4,7 +4,7 @@ Existem algumas funcionalidades adicionais para lidar com segurança além das cobertas em [Tutorial - Guia de Usuário: Segurança](../../tutorial/security/index.md){.internal-link target=_blank}. -/// tip | "Dica" +/// tip | Dica As próximas seções **não são necessariamente "avançadas"**. diff --git a/docs/pt/docs/advanced/security/oauth2-scopes.md b/docs/pt/docs/advanced/security/oauth2-scopes.md index fa4594c89..49fb75944 100644 --- a/docs/pt/docs/advanced/security/oauth2-scopes.md +++ b/docs/pt/docs/advanced/security/oauth2-scopes.md @@ -10,7 +10,7 @@ Toda vez que você "se autentica com" Facebook, Google, GitHub, Microsoft, Twitt Nesta seção, você verá como gerenciar a autenticação e autorização com os mesmos escopos do OAuth2 em sua aplicação **FastAPI**. -/// warning | "Aviso" +/// warning | Aviso Isso é uma seção mais ou menos avançada. Se você está apenas começando, você pode pular. @@ -308,7 +308,7 @@ E a função de dependência `get_current_active_user` também pode declarar sub Neste caso, ele requer o escopo `me` (poderia requerer mais de um escopo). -/// note | "Nota" +/// note | Nota Você não necessariamente precisa adicionar diferentes escopos em diferentes lugares. @@ -771,7 +771,7 @@ O mais comum é o fluxo implícito. O mais seguro é o fluxo de código, mas ele é mais complexo para implementar, pois ele necessita mais passos. Como ele é mais complexo, muitos provedores terminam sugerindo o fluxo implícito. -/// note | "Nota" +/// note | Nota É comum que cada provedor de autenticação nomeie os seus fluxos de forma diferente, para torná-lo parte de sua marca. diff --git a/docs/pt/docs/advanced/templates.md b/docs/pt/docs/advanced/templates.md index 88a5b940e..2314fed91 100644 --- a/docs/pt/docs/advanced/templates.md +++ b/docs/pt/docs/advanced/templates.md @@ -37,13 +37,13 @@ Além disso, em versões anteriores, o objeto `request` era passado como parte d /// -/// tip | "Dica" +/// tip | Dica Ao declarar `response_class=HTMLResponse`, a documentação entenderá que a resposta será HTML. /// -/// note | "Detalhes Técnicos" +/// note | Detalhes Técnicos Você também poderia usar `from starlette.templating import Jinja2Templates`. diff --git a/docs/pt/docs/advanced/testing-dependencies.md b/docs/pt/docs/advanced/testing-dependencies.md index f978350a5..94594e7e9 100644 --- a/docs/pt/docs/advanced/testing-dependencies.md +++ b/docs/pt/docs/advanced/testing-dependencies.md @@ -54,7 +54,7 @@ E então o **FastAPI** chamará a sobreposição no lugar da dependência origin //// tab | Python 3.10+ non-Annotated -/// tip | "Dica" +/// tip | Dica Prefira utilizar a versão `Annotated` se possível. @@ -68,7 +68,7 @@ Prefira utilizar a versão `Annotated` se possível. //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Prefira utilizar a versão `Annotated` se possível. @@ -80,7 +80,7 @@ Prefira utilizar a versão `Annotated` se possível. //// -/// tip | "Dica" +/// tip | Dica Você pode definir uma sobreposição de dependência para uma dependência que é utilizada em qualquer lugar da sua aplicação **FastAPI**. @@ -96,7 +96,7 @@ E então você pode redefinir as suas sobreposições (removê-las) definindo o app.dependency_overrides = {} ``` -/// tip | "Dica" +/// tip | Dica Se você quer sobrepor uma dependência apenas para alguns testes, você pode definir a sobreposição no início do testes (dentro da função de teste) e reiniciá-la ao final (no final da função de teste). diff --git a/docs/pt/docs/advanced/testing-websockets.md b/docs/pt/docs/advanced/testing-websockets.md index daa610df6..99e1a6db4 100644 --- a/docs/pt/docs/advanced/testing-websockets.md +++ b/docs/pt/docs/advanced/testing-websockets.md @@ -8,7 +8,7 @@ Para isso, você utiliza o `TestClient` dentro de uma instrução `with`, conect {!../../docs_src/app_testing/tutorial002.py!} ``` -/// note | "Nota" +/// note | Nota Para mais detalhes, confira a documentação do Starlette para testar WebSockets. diff --git a/docs/pt/docs/advanced/using-request-directly.md b/docs/pt/docs/advanced/using-request-directly.md index c2114c214..df7e01833 100644 --- a/docs/pt/docs/advanced/using-request-directly.md +++ b/docs/pt/docs/advanced/using-request-directly.md @@ -35,7 +35,7 @@ Para isso você precisa acessar a requisição diretamente. Ao declarar o parâmetro com o tipo sendo um `Request` em sua *função de operação de rota*, o **FastAPI** saberá como passar o `Request` neste parâmetro. -/// tip | "Dica" +/// tip | Dica Note que neste caso, nós estamos declarando o parâmetro da rota ao lado do parâmetro da requisição. @@ -49,7 +49,7 @@ Do mesmo jeito, você pode declarar qualquer outro parâmetro normalmente, e al Você pode ler mais sobre os detalhes do objeto `Request` no site da documentação oficial do Starlette.. -/// note | "Detalhes Técnicos" +/// note | Detalhes Técnicos Você também pode utilizar `from starlette.requests import Request`. diff --git a/docs/pt/docs/advanced/wsgi.md b/docs/pt/docs/advanced/wsgi.md index e6d08c8db..a36261e5e 100644 --- a/docs/pt/docs/advanced/wsgi.md +++ b/docs/pt/docs/advanced/wsgi.md @@ -12,9 +12,7 @@ Em seguinda, encapsular a aplicação WSGI (e.g. Flask) com o middleware. E então **"montar"** em um caminho de rota. -```Python hl_lines="2-3 23" -{!../../docs_src/wsgi/tutorial001.py!} -``` +{* ../../docs_src/wsgi/tutorial001.py hl[2:3,23] *} ## Conferindo diff --git a/docs/pt/docs/alternatives.md b/docs/pt/docs/alternatives.md index 2a2632bbc..29c9693bb 100644 --- a/docs/pt/docs/alternatives.md +++ b/docs/pt/docs/alternatives.md @@ -30,13 +30,13 @@ Ele é utilizado por muitas companhias incluindo Mozilla, Red Hat e Eventbrite. Ele foi um dos primeiros exemplos de **documentação automática de API**, e essa foi especificamente uma das primeiras idéias que inspirou "a busca por" **FastAPI**. -/// note | "Nota" +/// note | Nota Django REST Framework foi criado por Tom Christie. O mesmo criador de Starlette e Uvicorn, nos quais **FastAPI** é baseado. /// -/// check | "**FastAPI** inspirado para" +/// check | **FastAPI** inspirado para Ter uma documentação automática da API em interface web. @@ -56,7 +56,7 @@ Esse desacoplamento de partes, e sendo um "microframework" que pode ser extendid Dada a simplicidade do Flask, parecia uma ótima opção para construção de APIs. A próxima coisa a procurar era um "Django REST Framework" para Flask. -/// check | "**FastAPI** inspirado para" +/// check | **FastAPI** inspirado para Ser um microframework. Fazer ele fácil para misturar e combinar com ferramentas e partes necessárias. @@ -98,7 +98,7 @@ def read_url(): Veja as similaridades em `requests.get(...)` e `@app.get(...)`. -/// check | "**FastAPI** inspirado para" +/// check | **FastAPI** inspirado para * Ter uma API simples e intuitiva. * Utilizar nomes de métodos HTTP (operações) diretamente, de um jeito direto e intuitivo. @@ -118,7 +118,7 @@ Em algum ponto, Swagger foi dado para a Fundação Linux, e foi renomeado OpenAP Isso acontece porquê quando alguém fala sobre a versão 2.0 é comum dizer "Swagger", e para a versão 3+, "OpenAPI". -/// check | "**FastAPI** inspirado para" +/// check | **FastAPI** inspirado para Adotar e usar um padrão aberto para especificações API, ao invés de algum esquema customizado. @@ -147,7 +147,7 @@ Esses recursos são o que Marshmallow foi construído para fornecer. Ele é uma Mas ele foi criado antes da existência do _type hints_ do Python. Então, para definir todo o _schema_ você precisa utilizar específicas ferramentas e classes fornecidas pelo Marshmallow. -/// check | "**FastAPI** inspirado para" +/// check | **FastAPI** inspirado para Usar código para definir "schemas" que forneçam, automaticamente, tipos de dados e validação. @@ -169,7 +169,7 @@ Webargs foi criado pelos mesmos desenvolvedores do Marshmallow. /// -/// check | "**FastAPI** inspirado para" +/// check | **FastAPI** inspirado para Ter validação automática de dados vindos de requisições. @@ -199,7 +199,7 @@ APISpec foi criado pelos mesmos desenvolvedores do Marshmallow. /// -/// check | "**FastAPI** inspirado para" +/// check | **FastAPI** inspirado para Dar suporte a padrões abertos para APIs, OpenAPI. @@ -231,7 +231,7 @@ Flask-apispec foi criado pelos mesmos desenvolvedores do Marshmallow. /// -/// check | "**FastAPI** inspirado para" +/// check | **FastAPI** inspirado para Gerar _schema_ OpenAPI automaticamente, a partir do mesmo código que define serialização e validação. @@ -251,7 +251,7 @@ Mas como os dados TypeScript não são preservados após a compilação para o J Ele também não controla modelos aninhados muito bem. Então, se o corpo JSON na requisição for um objeto JSON que contém campos internos que contém objetos JSON aninhados, ele não consegue ser validado e documentado apropriadamente. -/// check | "**FastAPI** inspirado para" +/// check | **FastAPI** inspirado para Usar tipos Python para ter um ótimo suporte do editor. @@ -263,7 +263,7 @@ Ter um sistema de injeção de dependência poderoso. Achar um jeito de minimiza Ele foi um dos primeiros frameworks Python extremamente rápido baseado em `asyncio`. Ele foi feito para ser muito similar ao Flask. -/// note | "Detalhes técnicos" +/// note | Detalhes técnicos Ele utiliza `uvloop` ao invés do '_loop_' `asyncio` padrão do Python. É isso que deixa ele tão rápido. @@ -271,7 +271,7 @@ Ele claramente inspirou Uvicorn e Starlette, que são atualmente mais rápidos q /// -/// check | "**FastAPI** inspirado para" +/// check | **FastAPI** inspirado para Achar um jeito de ter uma performance insana. @@ -289,7 +289,7 @@ Ele é projetado para ter funções que recebem dois parâmetros, uma "requisiç Então, validação de dados, serialização e documentação tem que ser feitos no código, não automaticamente. Ou eles terão que ser implementados como um framework acima do Falcon, como o Hug. Essa mesma distinção acontece em outros frameworks que são inspirados pelo design do Falcon, tendo um objeto de requisição e um objeto de resposta como parâmetros. -/// check | "**FastAPI** inspirado para" +/// check | **FastAPI** inspirado para Achar jeitos de conseguir melhor performance. @@ -315,7 +315,7 @@ O sistema de injeção de dependência exige pré-registro das dependências e a Rotas são declaradas em um único lugar, usando funções declaradas em outros lugares (ao invés de usar decoradores que possam ser colocados diretamente acima da função que controla o _endpoint_). Isso é mais perto de como o Django faz isso do que como Flask (e Starlette) faz. Ele separa no código coisas que são relativamente amarradas. -/// check | "**FastAPI** inspirado para" +/// check | **FastAPI** inspirado para Definir validações extras para tipos de dados usando valores "padrão" de atributos dos modelos. Isso melhora o suporte do editor, e não estava disponível no Pydantic antes. @@ -343,7 +343,7 @@ Hug foi criado por Timothy Crosley, o mesmo criador do - -```console -$ python -m venv env -``` - - - -Isso criará o diretório `./env/` com os binários Python e então você será capaz de instalar pacotes nesse ambiente isolado. - -### Ativar o ambiente - -Ative o novo ambiente com: - -//// tab | Linux, macOS - -
- -```console -$ source ./env/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .\env\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Ou se você usa Bash para Windows (por exemplo Git Bash): - -
- -```console -$ source ./env/Scripts/activate -``` - -
- -//// - -Para verificar se funcionou, use: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which pip - -some/directory/fastapi/env/bin/pip -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command pip - -some/directory/fastapi/env/bin/pip -``` - -
- -//// - -Se ele exibir o binário `pip` em `env/bin/pip` então funcionou. 🎉 - - - -/// tip - -Toda vez que você instalar um novo pacote com `pip` nesse ambiente, ative o ambiente novamente. - -Isso garante que se você usar um programa instalado por aquele pacote, você utilizará aquele de seu ambiente local e não outro que possa estar instalado globalmente. - -/// - -### pip - -Após ativar o ambiente como descrito acima: - -
- -```console -$ pip install -r requirements.txt - ----> 100% -``` - -
- -Isso irá instalar todas as dependências e seu FastAPI local em seu ambiente local. - -#### Usando seu FastAPI local - -Se você cria um arquivo Python que importa e usa FastAPI, e roda com Python de seu ambiente local, ele irá utilizar o código fonte de seu FastAPI local. - -E se você atualizar o código fonte do FastAPI local, como ele é instalado com `-e`, quando você rodar aquele arquivo Python novamente, ele irá utilizar a nova versão do FastAPI que você acabou de editar. - -Desse modo, você não tem que "instalar" sua versão local para ser capaz de testar cada mudança. - -### Formato - -Tem um arquivo que você pode rodar que irá formatar e limpar todo o seu código: - -
- -```console -$ bash scripts/format.sh -``` - -
- -Ele irá organizar também todos os seus imports. - -Para que ele organize os imports corretamente, você precisa ter o FastAPI instalado localmente em seu ambiente, com o comando na seção acima usando `-e`. - -### Formato dos imports - -Tem outro _script_ que formata todos os imports e garante que você não tenha imports não utilizados: - -
- -```console -$ bash scripts/format-imports.sh -``` - -
- -Como ele roda um comando após o outro, modificando e revertendo muitos arquivos, ele demora um pouco para concluir, então pode ser um pouco mais fácil utilizar `scripts/format.sh` frequentemente e `scripts/format-imports.sh` somente após "commitar uma branch". - -## Documentação - -Primeiro, tenha certeza de configurar seu ambiente como descrito acima, isso irá instalar todas as requisições. - -A documentação usa MkDocs. - -E existem ferramentas/_scripts_ extras para controlar as traduções em `./scripts/docs.py`. - -/// tip - -Você não precisa ver o código em `./scripts/docs.py`, você apenas o utiliza na linha de comando. - -/// - -Toda a documentação está no formato Markdown no diretório `./docs/pt/`. - -Muitos dos tutoriais tem blocos de código. - -Na maioria dos casos, esse blocos de código são aplicações completas que podem ser rodadas do jeito que estão apresentados. - -De fato, esses blocos de código não estão escritos dentro do Markdown, eles são arquivos Python dentro do diretório `./docs_src/`. - -E esses arquivos Python são incluídos/injetados na documentação quando se gera o site. - -### Testes para Documentação - -A maioria dos testes na verdade rodam encima dos arquivos fonte na documentação. - -Isso ajuda a garantir: - -* Que a documentação esteja atualizada. -* Que os exemplos da documentação possam ser rodadas do jeito que estão apresentadas. -* A maior parte dos recursos é coberta pela documentação, garantida por cobertura de testes. - -Durante o desenvolvimento local, existe um _script_ que constrói o site e procura por quaisquer mudanças, carregando na hora: - -
- -```console -$ python ./scripts/docs.py live - -[INFO] Serving on http://127.0.0.1:8008 -[INFO] Start watching changes -[INFO] Start detecting changes -``` - -
- -Isso irá servir a documentação em `http://127.0.0.1:8008`. - -Desse jeito, você poderá editar a documentação/arquivos fonte e ver as mudanças na hora. - -#### Typer CLI (opcional) - -As instruções aqui mostram como utilizar _scripts_ em `./scripts/docs.py` com o programa `python` diretamente. - -Mas você pode usar também Typer CLI, e você terá auto-completação para comandos no seu terminal após instalar o _completion_. - -Se você instalou Typer CLI, você pode instalar _completion_ com: - -
- -```console -$ typer --install-completion - -zsh completion installed in /home/user/.bashrc. -Completion will take effect once you restart the terminal. -``` - -
- -### Aplicações e documentação ao mesmo tempo - -Se você rodar os exemplos com, por exemplo: - -
- -```console -$ uvicorn tutorial001:app --reload - -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -``` - -
- -como Uvicorn utiliza por padrão a porta `8000`, a documentação na porta `8008` não dará conflito. - -### Traduções - -Ajuda com traduções É MUITO apreciada! E essa tarefa não pode ser concluída sem a ajuda da comunidade. 🌎 🚀 - -Aqui estão os passos para ajudar com as traduções. - -#### Dicas e orientações - -* Verifique sempre os _pull requests_ existentes para a sua linguagem e faça revisões das alterações e aprove elas. - -/// tip - -Você pode adicionar comentários com sugestões de alterações para _pull requests_ existentes. - -Verifique as documentações sobre adicionar revisão ao _pull request_ para aprovação ou solicitação de alterações. - -/// - -* Verifique em _issues_ para ver se existe alguém coordenando traduções para a sua linguagem. - -* Adicione um único _pull request_ por página traduzida. Isso tornará muito mais fácil a revisão para as outras pessoas. - -Para as linguagens que eu não falo, vou esperar por várias pessoas revisarem a tradução antes de _mergear_. - -* Você pode verificar também se há traduções para sua linguagem e adicionar revisão para elas, isso irá me ajudar a saber que a tradução está correta e eu possa _mergear_. - -* Utilize os mesmos exemplos Python e somente traduza o texto na documentação. Você não tem que alterar nada no código para que funcione. - -* Utilize as mesmas imagens, nomes de arquivo e links. Você não tem que alterar nada disso para que funcione. - -* Para verificar o código de duas letras para a linguagem que você quer traduzir, você pode usar a Lista de códigos ISO 639-1. - -#### Linguagem existente - -Vamos dizer que você queira traduzir uma página para uma linguagem que já tenha traduções para algumas páginas, como o Espanhol. - -No caso do Espanhol, o código de duas letras é `es`. Então, o diretório para traduções em Espanhol está localizada em `docs/es/`. - -/// tip - -A principal ("oficial") linguagem é o Inglês, localizado em `docs/en/`. - -/// - -Agora rode o _servidor ao vivo_ para as documentações em Espanhol: - -
- -```console -// Use o comando "live" e passe o código da linguagem como um argumento de linha de comando -$ python ./scripts/docs.py live es - -[INFO] Serving on http://127.0.0.1:8008 -[INFO] Start watching changes -[INFO] Start detecting changes -``` - -
- -Agora você pode ir em http://127.0.0.1:8008 e ver suas mudanças ao vivo. - -Se você procurar no site da documentação do FastAPI, você verá que toda linguagem tem todas as páginas. Mas algumas páginas não estão traduzidas e tem notificação sobre a falta da tradução. - -Mas quando você rodar localmente como descrito acima, você somente verá as páginas que já estão traduzidas. - -Agora vamos dizer que você queira adicionar uma tradução para a seção [Recursos](features.md){.internal-link target=_blank}. - -* Copie o arquivo em: - -``` -docs/en/docs/features.md -``` - -* Cole ele exatamente no mesmo local mas para a linguagem que você quer traduzir, por exemplo: - -``` -docs/es/docs/features.md -``` - -/// tip - -Observe que a única mudança na rota é o código da linguagem, de `en` para `es`. - -/// - -* Agora abra o arquivo de configuração MkDocs para Inglês em: - -``` -docs/en/docs/mkdocs.yml -``` - -* Procure o lugar onde `docs/features.md` está localizado no arquivo de configuração. Algum lugar como: - -```YAML hl_lines="8" -site_name: FastAPI -# Mais coisas -nav: -- FastAPI: index.md -- Languages: - - en: / - - es: /es/ -- features.md -``` - -* Abra o arquivo de configuração MkDocs para a linguagem que você está editando, por exemplo: - -``` -docs/es/docs/mkdocs.yml -``` - -* Adicione no mesmo local que está no arquivo em Inglês, por exemplo: - -```YAML hl_lines="8" -site_name: FastAPI -# Mais coisas -nav: -- FastAPI: index.md -- Languages: - - en: / - - es: /es/ -- features.md -``` - -Tenha certeza que se existem outras entradas, a nova entrada com sua tradução esteja exatamente na mesma ordem como na versão em Inglês. - -Se você for no seu navegador verá que agora a documentação mostra sua nova seção. 🎉 - -Agora você poderá traduzir tudo e ver como está toda vez que salva o arquivo. - -#### Nova linguagem - -Vamos dizer que você queira adicionar traduções para uma linguagem que ainda não foi traduzida, nem sequer uma página. - -Vamos dizer que você queira adicionar tradução para Haitiano, e ainda não tenha na documentação. - -Verificando o link acima, o código para "Haitiano" é `ht`. - -O próximo passo é rodar o _script_ para gerar um novo diretório de tradução: - -
- -```console -// Use o comando new-lang, passe o código da linguagem como um argumento de linha de comando -$ python ./scripts/docs.py new-lang ht - -Successfully initialized: docs/ht -Updating ht -Updating en -``` - -
- -Agora você pode verificar em seu editor de código o mais novo diretório criado `docs/ht/`. - -/// tip - -Crie um primeiro _pull request_ com apenas isso, para iniciar a configuração da nova linguagem, antes de adicionar traduções. - -Desse modo outros poderão ajudar com outras páginas enquanto você trabalha na primeira. 🚀 - -/// - -Inicie traduzindo a página principal, `docs/ht/index.md`. - -Então você pode continuar com as instruções anteriores, para uma "Linguagem Existente". - -##### Nova linguagem não suportada - -Se quando rodar o _script_ do _servidor ao vivo_ você pega um erro sobre linguagem não suportada, alguma coisa como: - -``` - raise TemplateNotFound(template) -jinja2.exceptions.TemplateNotFound: partials/language/xx.html -``` - -Isso significa que o tema não suporta essa linguagem (nesse caso, com um código falso de duas letras `xx`). - -Mas não se preocupe, você pode configurar o tema de linguagem para Inglês e então traduzir o conteúdo da documentação. - -Se você precisar fazer isso, edite o `mkdocs.yml` para sua nova linguagem, teremos algo como: - -```YAML hl_lines="5" -site_name: FastAPI -# Mais coisas -theme: - # Mais coisas - language: xx -``` - -Altere essa linguagem de `xx` (do seu código de linguagem) para `en`. - -Então você poderá iniciar novamente o _servidor ao vivo_. - -#### Pré-visualize o resultado - -Quando você usa o _script_ em `./scripts/docs.py` com o comando `live` ele somente exibe os arquivos e traduções disponíveis para a linguagem atual. - -Mas uma vez que você tenha concluído, você poderá testar tudo como se parecesse _online_. - -Para fazer isso, primeiro construa toda a documentação: - -
- -```console -// Use o comando "build-all", isso leverá um tempinho -$ python ./scripts/docs.py build-all - -Updating es -Updating en -Building docs for: en -Building docs for: es -Successfully built docs for: es -Copying en index.md to README.md -``` - -
- -Isso gera toda a documentação em `./docs_build/` para cada linguagem. Isso inclui a adição de quaisquer arquivos com tradução faltando, com uma nota dizendo que "esse arquivo ainda não tem tradução". Mas você não tem que fazer nada com esse diretório. - -Então ele constrói todos aqueles _sites_ independentes MkDocs para cada linguagem, combina eles, e gera a saída final em `./site/`. - -Então você poderá "servir" eles com o comando `serve`: - -
- -```console -// Use o comando "serve" após rodar "build-all" -$ python ./scripts/docs.py serve - -Warning: this is a very simple server. For development, use mkdocs serve instead. -This is here only to preview a site with translations already built. -Make sure you run the build-all command first. -Serving at: http://127.0.0.1:8008 -``` - -
- -## Testes - -Tem um _script_ que você pode rodar localmente para testar todo o código e gerar relatórios de cobertura em HTML: - -
- -```console -$ bash scripts/test-cov-html.sh -``` - -
- -Esse comando gera um diretório `./htmlcov/`, se você abrir o arquivo `./htmlcov/index.html` no seu navegador, poderá explorar interativamente as regiões de código que estão cobertas pelos testes, e observar se existe alguma região faltando. - -### Testes no seu editor - -Se você quer usar os testes integrados em seu editor adicione `./docs_src` na sua variável `PYTHONPATH`. - -Por exemplo, no VS Code você pode criar um arquivo `.env` com: - -```env -PYTHONPATH=./docs_src -``` diff --git a/docs/pt/docs/deployment/concepts.md b/docs/pt/docs/deployment/concepts.md index 20513c366..8cf70d0b4 100644 --- a/docs/pt/docs/deployment/concepts.md +++ b/docs/pt/docs/deployment/concepts.md @@ -151,7 +151,7 @@ E ainda assim, você provavelmente não gostaria que o aplicativo permanecesse i Mas nos casos com erros realmente graves que travam o **processo** em execução, você vai querer um componente externo que seja responsável por **reiniciar** o processo, pelo menos algumas vezes... -/// tip | "Dica" +/// tip | Dica ...Embora se o aplicativo inteiro estiver **travando imediatamente**, provavelmente não faça sentido reiniciá-lo para sempre. Mas nesses casos, você provavelmente notará isso durante o desenvolvimento, ou pelo menos logo após a implantação. @@ -239,7 +239,7 @@ Aqui estão algumas combinações e estratégias possíveis: * **Serviços de nuvem** que cuidam disso para você * O serviço de nuvem provavelmente **cuidará da replicação para você**. Ele possivelmente deixaria você definir **um processo para executar**, ou uma **imagem de contêiner** para usar, em qualquer caso, provavelmente seria **um único processo Uvicorn**, e o serviço de nuvem seria responsável por replicá-lo. -/// tip | "Dica" +/// tip | Dica Não se preocupe se alguns desses itens sobre **contêineres**, Docker ou Kubernetes ainda não fizerem muito sentido. @@ -261,7 +261,7 @@ E você terá que se certificar de que é um único processo executando essas et Claro, há alguns casos em que não há problema em executar as etapas anteriores várias vezes; nesse caso, é muito mais fácil de lidar. -/// tip | "Dica" +/// tip | Dica Além disso, tenha em mente que, dependendo da sua configuração, em alguns casos você **pode nem precisar de nenhuma etapa anterior** antes de iniciar sua aplicação. @@ -279,7 +279,7 @@ Aqui estão algumas ideias possíveis: * Um script bash que roda os passos anteriores e então inicia seu aplicativo * Você ainda precisaria de uma maneira de iniciar/reiniciar *aquele* script bash, detectar erros, etc. -/// tip | "Dica" +/// tip | Dica Darei exemplos mais concretos de como fazer isso com contêineres em um capítulo futuro: [FastAPI em contêineres - Docker](docker.md){.internal-link target=_blank}. diff --git a/docs/pt/docs/deployment/docker.md b/docs/pt/docs/deployment/docker.md index df93bac2c..cf18bb153 100644 --- a/docs/pt/docs/deployment/docker.md +++ b/docs/pt/docs/deployment/docker.md @@ -4,7 +4,7 @@ Ao fazer o deploy de aplicações FastAPI uma abordagem comum é construir uma * Usando contêineres Linux você tem diversas vantagens incluindo **segurança**, **replicabilidade**, **simplicidade**, entre outras. -/// tip | "Dica" +/// tip | Dica Está com pressa e já sabe dessas coisas? Pode ir direto para [`Dockerfile` abaixo 👇](#construindo-uma-imagem-docker-para-fastapi). diff --git a/docs/pt/docs/deployment/https.md b/docs/pt/docs/deployment/https.md index 6ccc875fd..9a13977ec 100644 --- a/docs/pt/docs/deployment/https.md +++ b/docs/pt/docs/deployment/https.md @@ -4,7 +4,7 @@ Mas é bem mais complexo do que isso. -/// tip | "Dica" +/// tip | Dica Se você está com pressa ou não se importa, continue com as seções seguintes para instruções passo a passo para configurar tudo com diferentes técnicas. diff --git a/docs/pt/docs/deployment/manually.md b/docs/pt/docs/deployment/manually.md index 9eff3daaa..237f4f8b9 100644 --- a/docs/pt/docs/deployment/manually.md +++ b/docs/pt/docs/deployment/manually.md @@ -102,7 +102,7 @@ $ pip install "uvicorn[standard]" Um processo semelhante se aplicaria a qualquer outro programa de servidor ASGI. -/// tip | "Dica" +/// tip | Dica Adicionando o `standard`, o Uvicorn instalará e usará algumas dependências extras recomendadas. @@ -126,7 +126,7 @@ $ uvicorn main:app --host 0.0.0.0 --port 80 -/// note | "Nota" +/// note | Nota O comando `uvicorn main:app` refere-se a: @@ -143,7 +143,7 @@ from main import app Cada programa de servidor ASGI alternativo teria um comando semelhante, você pode ler mais na documentação respectiva. -/// warning | "Aviso" +/// warning | Aviso Uvicorn e outros servidores suportam a opção `--reload` que é útil durante o desenvolvimento. diff --git a/docs/pt/docs/deployment/server-workers.md b/docs/pt/docs/deployment/server-workers.md index 0d6cd5b39..63eda56b4 100644 --- a/docs/pt/docs/deployment/server-workers.md +++ b/docs/pt/docs/deployment/server-workers.md @@ -17,7 +17,7 @@ Como você viu no capítulo anterior sobre [Conceitos de implantação](concepts Aqui mostrarei como usar o **Uvicorn** com **processos de trabalho** usando o comando `fastapi` ou o comando `uvicorn` diretamente. -/// info | "Informação" +/// info | Informação 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){.internal-link target=_blank}. diff --git a/docs/pt/docs/deployment/versions.md b/docs/pt/docs/deployment/versions.md index 79243a014..323ddbd45 100644 --- a/docs/pt/docs/deployment/versions.md +++ b/docs/pt/docs/deployment/versions.md @@ -42,7 +42,7 @@ Seguindo as convenções de controle de versão semântica, qualquer versão aba FastAPI também segue a convenção de que qualquer alteração de versão "PATCH" é para correção de bugs e alterações não significativas. -/// tip | "Dica" +/// tip | Dica O "PATCH" é o último número, por exemplo, em `0.2.3`, a versão PATCH é `3`. @@ -56,7 +56,7 @@ fastapi>=0.45.0,<0.46.0 Mudanças significativas e novos recursos são adicionados em versões "MINOR". -/// tip | "Dica" +/// tip | Dica O "MINOR" é o número que está no meio, por exemplo, em `0.2.3`, a versão MINOR é `2`. diff --git a/docs/pt/docs/environment-variables.md b/docs/pt/docs/environment-variables.md index 360d1c496..432f78af0 100644 --- a/docs/pt/docs/environment-variables.md +++ b/docs/pt/docs/environment-variables.md @@ -1,6 +1,6 @@ # Variáveis de Ambiente -/// tip | "Dica" +/// tip | Dica Se você já sabe o que são "variáveis de ambiente" e como usá-las, pode pular esta seção. @@ -63,7 +63,7 @@ name = os.getenv("MY_NAME", "World") print(f"Hello {name} from Python") ``` -/// tip | "Dica" +/// tip | Dica O segundo argumento para `os.getenv()` é o valor padrão a ser retornado. @@ -151,7 +151,7 @@ Hello World from Python -/// tip | "Dica" +/// tip | Dica Você pode ler mais sobre isso em The Twelve-Factor App: Config. diff --git a/docs/pt/docs/help-fastapi.md b/docs/pt/docs/help-fastapi.md index 61eeac0dc..3d6e1f9d2 100644 --- a/docs/pt/docs/help-fastapi.md +++ b/docs/pt/docs/help-fastapi.md @@ -109,7 +109,7 @@ Assim podendo tentar ajudar a resolver essas questões. Entre no 👥 server de conversa do Discord 👥 e conheça novas pessoas da comunidade do FastAPI. -/// tip | "Dica" +/// tip | Dica Para perguntas, pergunte nas questões do GitHub, lá tem um chance maior de você ser ajudado sobre o FastAPI [FastAPI Experts](fastapi-people.md#especialistas){.internal-link target=_blank}. diff --git a/docs/pt/docs/how-to/graphql.md b/docs/pt/docs/how-to/graphql.md index 2cfd790c5..250135e23 100644 --- a/docs/pt/docs/how-to/graphql.md +++ b/docs/pt/docs/how-to/graphql.md @@ -4,7 +4,7 @@ Como o **FastAPI** é baseado no padrão **ASGI**, é muito fácil integrar qual Você pode combinar *operações de rota* normais do FastAPI com GraphQL na mesma aplicação. -/// tip | "Dica" +/// tip | Dica **GraphQL** resolve alguns casos de uso muito específicos. @@ -49,7 +49,7 @@ Versões anteriores do Starlette incluiam uma classe `GraphQLApp` para integrar Ela foi descontinuada do Starlette, mas se você tem código que a utilizava, você pode facilmente **migrar** para starlette-graphene3, que cobre o mesmo caso de uso e tem uma **interface quase idêntica**. -/// tip | "Dica" +/// tip | Dica Se você precisa de GraphQL, eu ainda recomendaria que você desse uma olhada no Strawberry, pois ele é baseado em type annotations em vez de classes e tipos personalizados. diff --git a/docs/pt/docs/python-types.md b/docs/pt/docs/python-types.md index a0938259f..90a361f40 100644 --- a/docs/pt/docs/python-types.md +++ b/docs/pt/docs/python-types.md @@ -22,9 +22,7 @@ Se você é um especialista em Python e já sabe tudo sobre type hints, pule par Vamos começar com um exemplo simples: -```Python -{!../../docs_src/python_types/tutorial001.py!} -``` +{* ../../docs_src/python_types/tutorial001.py *} A chamada deste programa gera: @@ -38,9 +36,7 @@ A função faz o seguinte: * Converte a primeira letra de cada uma em maiúsculas com `title()`. * Concatena com um espaço no meio. -```Python hl_lines="2" -{!../../docs_src/python_types/tutorial001.py!} -``` +{* ../../docs_src/python_types/tutorial001.py hl[2] *} ### Edite-o @@ -82,9 +78,7 @@ para: Esses são os "type hints": -```Python hl_lines="1" -{!../../docs_src/python_types/tutorial002.py!} -``` +{* ../../docs_src/python_types/tutorial002.py hl[1] *} Isso não é o mesmo que declarar valores padrão como seria com: @@ -112,9 +106,7 @@ Com isso, você pode rolar, vendo as opções, até encontrar o que "soa familia Verifique esta função, ela já possui type hints: -```Python hl_lines="1" -{!../../docs_src/python_types/tutorial003.py!} -``` +{* ../../docs_src/python_types/tutorial003.py hl[1] *} Como o editor conhece os tipos de variáveis, você não obtém apenas o preenchimento automático, mas também as verificações de erro: @@ -122,9 +114,7 @@ Como o editor conhece os tipos de variáveis, você não obtém apenas o preench Agora você sabe que precisa corrigí-lo, converta `age` em uma string com `str(age)`: -```Python hl_lines="2" -{!../../docs_src/python_types/tutorial004.py!} -``` +{* ../../docs_src/python_types/tutorial004.py hl[2] *} ## Declarando Tipos @@ -143,9 +133,7 @@ Você pode usar, por exemplo: * `bool` * `bytes` -```Python hl_lines="1" -{!../../docs_src/python_types/tutorial005.py!} -``` +{* ../../docs_src/python_types/tutorial005.py hl[1] *} ### Tipos genéricos com parâmetros de tipo @@ -321,7 +309,7 @@ Você pode declarar que um valor pode ter um tipo, como `str`, mas que ele tamb No Python 3.6 e superior (incluindo o Python 3.10) você pode declará-lo importando e utilizando `Optional` do módulo `typing`. -```Python hl_lines="1 4" +```Python hl_lines="1 4" {!../../docs_src/python_types/tutorial009.py!} ``` @@ -370,9 +358,7 @@ Isso é apenas sobre palavras e nomes. Mas estas palavras podem afetar como os s Por exemplo, vamos pegar esta função: -```Python hl_lines="1 4" -{!../../docs_src/python_types/tutorial009c.py!} -``` +{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *} O paâmetro `name` é definido como `Optional[str]`, mas ele **não é opcional**, você não pode chamar a função sem o parâmetro: @@ -388,9 +374,7 @@ say_hi(name=None) # This works, None is valid 🎉 A boa notícia é, quando você estiver no Python 3.10 você não precisará se preocupar mais com isso, pois você poderá simplesmente utilizar o `|` para definir uniões de tipos: -```Python hl_lines="1 4" -{!../../docs_src/python_types/tutorial009c_py310.py!} -``` +{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *} E então você não precisará mais se preocupar com nomes como `Optional` e `Union`. 😎 @@ -452,15 +436,11 @@ Você também pode declarar uma classe como o tipo de uma variável. Digamos que você tenha uma classe `Person`, com um nome: -```Python hl_lines="1-3" -{!../../docs_src/python_types/tutorial010.py!} -``` +{* ../../docs_src/python_types/tutorial010.py hl[1:3] *} Então você pode declarar que uma variável é do tipo `Person`: -```Python hl_lines="6" -{!../../docs_src/python_types/tutorial010.py!} -``` +{* ../../docs_src/python_types/tutorial010.py hl[6] *} E então, novamente, você recebe todo o suporte do editor: diff --git a/docs/pt/docs/tutorial/background-tasks.md b/docs/pt/docs/tutorial/background-tasks.md index 2b5f82464..0f3796371 100644 --- a/docs/pt/docs/tutorial/background-tasks.md +++ b/docs/pt/docs/tutorial/background-tasks.md @@ -15,9 +15,7 @@ Isso inclui, por exemplo: Primeiro, importe `BackgroundTasks` e defina um parâmetro em sua _função de operação de caminho_ com uma declaração de tipo de `BackgroundTasks`: -```Python hl_lines="1 13" -{!../../docs_src/background_tasks/tutorial001.py!} -``` +{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *} O **FastAPI** criará o objeto do tipo `BackgroundTasks` para você e o passará como esse parâmetro. @@ -33,17 +31,13 @@ Nesse caso, a função de tarefa gravará em um arquivo (simulando o envio de um E como a operação de gravação não usa `async` e `await`, definimos a função com `def` normal: -```Python hl_lines="6-9" -{!../../docs_src/background_tasks/tutorial001.py!} -``` +{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *} ## Adicionar a tarefa em segundo plano Dentro de sua _função de operação de caminho_, passe sua função de tarefa para o objeto _tarefas em segundo plano_ com o método `.add_task()`: -```Python hl_lines="14" -{!../../docs_src/background_tasks/tutorial001.py!} -``` +{* ../../docs_src/background_tasks/tutorial001.py hl[14] *} `.add_task()` recebe como argumentos: @@ -57,9 +51,7 @@ Usar `BackgroundTasks` também funciona com o sistema de injeção de dependênc O **FastAPI** sabe o que fazer em cada caso e como reutilizar o mesmo objeto, de forma que todas as tarefas em segundo plano sejam mescladas e executadas em segundo plano posteriormente: -```Python hl_lines="13 15 22 25" -{!../../docs_src/background_tasks/tutorial002.py!} -``` +{* ../../docs_src/background_tasks/tutorial002.py hl[13,15,22,25] *} Neste exemplo, as mensagens serão gravadas no arquivo `log.txt` _após_ o envio da resposta. @@ -85,8 +77,6 @@ Se você precisa realizar cálculos pesados ​​em segundo plano e não necess Eles tendem a exigir configurações mais complexas, um gerenciador de fila de mensagens/tarefas, como RabbitMQ ou Redis, mas permitem que você execute tarefas em segundo plano em vários processos e, especialmente, em vários servidores. -Para ver um exemplo, verifique os [Geradores de projeto](../project-generation.md){.internal-link target=\_blank}, todos incluem celery já configurado. - Mas se você precisa acessar variáveis ​​e objetos do mesmo aplicativo **FastAPI**, ou precisa realizar pequenas tarefas em segundo plano (como enviar uma notificação por e-mail), você pode simplesmente usar `BackgroundTasks`. ## Recapitulando diff --git a/docs/pt/docs/tutorial/bigger-applications.md b/docs/pt/docs/tutorial/bigger-applications.md index fcc30961f..a094005fd 100644 --- a/docs/pt/docs/tutorial/bigger-applications.md +++ b/docs/pt/docs/tutorial/bigger-applications.md @@ -4,7 +4,7 @@ Se você está construindo uma aplicação ou uma API web, é raro que você pos **FastAPI** oferece uma ferramenta conveniente para estruturar sua aplicação, mantendo toda a flexibilidade. -/// info | "Informação" +/// info | Informação Se você vem do Flask, isso seria o equivalente aos Blueprints do Flask. @@ -29,7 +29,7 @@ Digamos que você tenha uma estrutura de arquivos como esta: │   └── admin.py ``` -/// tip | "Dica" +/// tip | Dica Existem vários arquivos `__init__.py` presentes em cada diretório ou subdiretório. @@ -105,7 +105,7 @@ Todas as mesmas opções são suportadas. Todos os mesmos `parameters`, `responses`, `dependencies`, `tags`, etc. -/// tip | "Dica" +/// tip | Dica Neste exemplo, a variável é chamada de `router`, mas você pode nomeá-la como quiser. @@ -139,7 +139,7 @@ Agora usaremos uma dependência simples para ler um cabeçalho `X-Token` persona //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Prefira usar a versão `Annotated` se possível. @@ -151,7 +151,7 @@ Prefira usar a versão `Annotated` se possível. //// -/// tip | "Dica" +/// tip | Dica Estamos usando um cabeçalho inventado para simplificar este exemplo. @@ -201,7 +201,7 @@ Também podemos adicionar uma lista de `tags` e `responses` extras que serão ap E podemos adicionar uma lista de `dependencies` que serão adicionadas a todas as *operações de rota* no roteador e serão executadas/resolvidas para cada solicitação feita a elas. -/// tip | "Dica" +/// tip | Dica Observe que, assim como [dependências em *decoradores de operação de rota*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, nenhum valor será passado para sua *função de operação de rota*. @@ -222,7 +222,7 @@ O resultado final é que os caminhos dos itens agora são: * As dependências do roteador são executadas primeiro, depois as [`dependencies` no decorador](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank} 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){.internal-link target=_blank}. -/// tip | "Dica" +/// tip | Dica Ter `dependências` no `APIRouter` pode ser usado, por exemplo, para exigir autenticação para um grupo inteiro de *operações de rota*. Mesmo que as dependências não sejam adicionadas individualmente a cada uma delas. @@ -248,7 +248,7 @@ Então usamos uma importação relativa com `..` para as dependências: #### Como funcionam as importações relativas -/// tip | "Dica" +/// tip | Dica Se você sabe perfeitamente como funcionam as importações, continue para a próxima seção abaixo. @@ -319,7 +319,7 @@ Mas ainda podemos adicionar _mais_ `tags` que serão aplicadas a uma *operação {!../../docs_src/bigger_applications/app/routers/items.py!} ``` -/// tip | "Dica" +/// tip | Dica Esta última operação de caminho terá a combinação de tags: `["items", "custom"]`. @@ -381,7 +381,7 @@ Também poderíamos importá-los como: from app.routers import items, users ``` -/// info | "Informação" +/// info | Informação A primeira versão é uma "importação relativa": @@ -428,7 +428,7 @@ Agora, vamos incluir os `roteadores` dos submódulos `usuários` e `itens`: {!../../docs_src/bigger_applications/app/main.py!} ``` -/// info | "Informação" +/// info | Informação `users.router` contém o `APIRouter` dentro do arquivo `app/routers/users.py`. @@ -440,7 +440,7 @@ Com `app.include_router()` podemos adicionar cada `APIRouter` ao aplicativo prin Ele incluirá todas as rotas daquele roteador como parte dele. -/// note | "Detalhe Técnico" +/// note | Detalhe Técnico Na verdade, ele criará internamente uma *operação de rota* para cada *operação de rota* que foi declarada no `APIRouter`. @@ -503,7 +503,7 @@ Aqui fazemos isso... só para mostrar que podemos 🤷: e funcionará corretamente, junto com todas as outras *operações de rota* adicionadas com `app.include_router()`. -/// info | "Detalhes Técnicos" +/// info | Detalhes Técnicos **Observação**: este é um detalhe muito técnico que você provavelmente pode **simplesmente pular**. diff --git a/docs/pt/docs/tutorial/body-fields.md b/docs/pt/docs/tutorial/body-fields.md index ab9377fdb..ac0b85ab5 100644 --- a/docs/pt/docs/tutorial/body-fields.md +++ b/docs/pt/docs/tutorial/body-fields.md @@ -10,7 +10,7 @@ Primeiro, você tem que importá-lo: {!../../docs_src/body_fields/tutorial001.py!} ``` -/// warning | "Aviso" +/// warning | Aviso Note que `Field` é importado diretamente do `pydantic`, não do `fastapi` como todo o resto (`Query`, `Path`, `Body`, etc). @@ -26,7 +26,7 @@ Você pode então utilizar `Field` com atributos do modelo: `Field` funciona da mesma forma que `Query`, `Path` e `Body`, ele possui todos os mesmos parâmetros, etc. -/// note | "Detalhes técnicos" +/// note | Detalhes técnicos Na realidade, `Query`, `Path` e outros que você verá em seguida, criam objetos de subclasses de uma classe `Param` comum, que é ela mesma uma subclasse da classe `FieldInfo` do Pydantic. @@ -38,7 +38,7 @@ Lembre-se que quando você importa `Query`, `Path`, e outros de `fastapi`, esse /// -/// tip | "Dica" +/// tip | Dica Note como cada atributo do modelo com um tipo, valor padrão e `Field` possuem a mesma estrutura que parâmetros de *funções de operações de rota*, com `Field` ao invés de `Path`, `Query` e `Body`. diff --git a/docs/pt/docs/tutorial/body-multiple-params.md b/docs/pt/docs/tutorial/body-multiple-params.md index 400813a7b..ad4931b11 100644 --- a/docs/pt/docs/tutorial/body-multiple-params.md +++ b/docs/pt/docs/tutorial/body-multiple-params.md @@ -24,7 +24,7 @@ E você também pode declarar parâmetros de corpo como opcionais, definindo o v //// -/// note | "Nota" +/// note | Nota Repare que, neste caso, o `item` que seria capturado a partir do corpo é opcional. Visto que ele possui `None` como valor padrão. @@ -80,7 +80,7 @@ Então, ele usará o nome dos parâmetros como chaves (nome dos campos) no corpo } ``` -/// note | "Nota" +/// note | Nota Repare que mesmo que o `item` esteja declarado da mesma maneira que antes, agora é esperado que ele esteja dentro do corpo com uma chave `item`. @@ -170,7 +170,7 @@ Por exemplo: //// -/// info | "Informação" +/// info | Informação `Body` também possui todas as validações adicionais e metadados de parâmetros como em `Query`,`Path` e outras que você verá depois. diff --git a/docs/pt/docs/tutorial/body-nested-models.md b/docs/pt/docs/tutorial/body-nested-models.md index 3aa79d563..bbe72a744 100644 --- a/docs/pt/docs/tutorial/body-nested-models.md +++ b/docs/pt/docs/tutorial/body-nested-models.md @@ -165,7 +165,7 @@ Isso vai esperar(converter, validar, documentar, etc) um corpo JSON tal qual: } ``` -/// info | "informação" +/// info | informação Note como o campo `images` agora tem uma lista de objetos de image. @@ -179,7 +179,7 @@ Você pode definir modelos profundamente aninhados de forma arbitrária: {!../../docs_src/body_nested_models/tutorial007.py!} ``` -/// info | "informação" +/// info | informação Note como `Offer` tem uma lista de `Item`s, que por sua vez possui opcionalmente uma lista `Image`s @@ -232,7 +232,7 @@ Neste caso, você aceitaria qualquer `dict`, desde que tenha chaves` int` com va {!../../docs_src/body_nested_models/tutorial009.py!} ``` -/// tip | "Dica" +/// tip | Dica Leve em condideração que o JSON só suporta `str` como chaves. diff --git a/docs/pt/docs/tutorial/body.md b/docs/pt/docs/tutorial/body.md index 429e4fd5a..f3a1fda75 100644 --- a/docs/pt/docs/tutorial/body.md +++ b/docs/pt/docs/tutorial/body.md @@ -8,7 +8,7 @@ Sua API quase sempre irá enviar um corpo na **resposta**. Mas os clientes não Para declarar um corpo da **requisição**, você utiliza os modelos do Pydantic com todos os seus poderes e benefícios. -/// info | "Informação" +/// info | Informação Para enviar dados, você deve usar utilizar um dos métodos: `POST` (Mais comum), `PUT`, `DELETE` ou `PATCH`. @@ -113,7 +113,7 @@ Mas você terá o mesmo suporte do editor no -/// tip | "Dica" +/// tip | Dica Se você utiliza o PyCharm como editor, você pode utilizar o Plugin do Pydantic para o PyCharm . @@ -161,7 +161,7 @@ Os parâmetros da função serão reconhecidos conforme abaixo: * Se o parâmetro é de um **tipo único** (como `int`, `float`, `str`, `bool`, etc) será interpretado como um parâmetro de **consulta**. * Se o parâmetro é declarado como um **modelo Pydantic**, será interpretado como o **corpo** da requisição. -/// note | "Observação" +/// note | Observação O FastAPI saberá que o valor de `q` não é obrigatório por causa do valor padrão `= None`. diff --git a/docs/pt/docs/tutorial/cors.md b/docs/pt/docs/tutorial/cors.md index 16c4e9bf5..326101bd2 100644 --- a/docs/pt/docs/tutorial/cors.md +++ b/docs/pt/docs/tutorial/cors.md @@ -78,7 +78,7 @@ Qualquer solicitação com um cabeçalho `Origin`. Neste caso, o middleware pass Para mais informações CORS, acesse Mozilla CORS documentation. -/// note | "Detalhes técnicos" +/// note | Detalhes técnicos Você também pode usar `from starlette.middleware.cors import CORSMiddleware`. diff --git a/docs/pt/docs/tutorial/debugging.md b/docs/pt/docs/tutorial/debugging.md index 6bac7eb85..fca162988 100644 --- a/docs/pt/docs/tutorial/debugging.md +++ b/docs/pt/docs/tutorial/debugging.md @@ -74,7 +74,7 @@ Então, a linha: não será executada. -/// info | "Informação" +/// info | Informação Para mais informações, consulte a documentação oficial do Python. diff --git a/docs/pt/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/pt/docs/tutorial/dependencies/classes-as-dependencies.md index 179bfefb5..fcf71d08c 100644 --- a/docs/pt/docs/tutorial/dependencies/classes-as-dependencies.md +++ b/docs/pt/docs/tutorial/dependencies/classes-as-dependencies.md @@ -32,7 +32,7 @@ No exemplo anterior, nós retornávamos um `dict` da nossa dependência ("injet //// tab | Python 3.10+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -46,7 +46,7 @@ Utilize a versão com `Annotated` se possível. //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -145,7 +145,7 @@ Então, podemos mudar o "injetável" na dependência `common_parameters` acima p //// tab | Python 3.10+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -159,7 +159,7 @@ Utilize a versão com `Annotated` se possível. //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -199,7 +199,7 @@ Observe o método `__init__` usado para criar uma instância da classe: //// tab | Python 3.10+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -213,7 +213,7 @@ Utilize a versão com `Annotated` se possível. //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -253,7 +253,7 @@ Utilize a versão com `Annotated` se possível. //// tab | Python 3.10+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -267,7 +267,7 @@ Utilize a versão com `Annotated` se possível. //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -319,7 +319,7 @@ Agora você pode declarar sua dependência utilizando essa classe. //// tab | Python 3.10+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -333,7 +333,7 @@ Utilize a versão com `Annotated` se possível. //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -361,7 +361,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -397,7 +397,7 @@ commons: Annotated[CommonQueryParams, ... //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -423,7 +423,7 @@ commons: Annotated[Any, Depends(CommonQueryParams)] //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -463,7 +463,7 @@ commons = Depends(CommonQueryParams) //// tab | Python 3.10+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -477,7 +477,7 @@ Utilize a versão com `Annotated` se possível. //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -507,7 +507,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -535,7 +535,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -559,7 +559,7 @@ commons: Annotated[CommonQueryParams, Depends()] //// tab | Python 3.8 non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -601,7 +601,7 @@ O mesmo exemplo ficaria então dessa forma: //// tab | Python 3.10+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -615,7 +615,7 @@ Utilize a versão com `Annotated` se possível. //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível. @@ -629,7 +629,7 @@ Utilize a versão com `Annotated` se possível. ...e o **FastAPI** saberá o que fazer. -/// tip | "Dica" +/// tip | Dica Se isso parece mais confuso do que útil, não utilize, você não *precisa* disso. diff --git a/docs/pt/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/pt/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md index 7d7086945..89c34855e 100644 --- a/docs/pt/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md +++ b/docs/pt/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md @@ -32,7 +32,7 @@ Ele deve ser uma lista de `Depends()`: //// tab | Python 3.8 non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível @@ -46,7 +46,7 @@ Utilize a versão com `Annotated` se possível Essas dependências serão executadas/resolvidas da mesma forma que dependências comuns. Mas o valor delas (se existir algum) não será passado para a sua *função de operação de rota*. -/// tip | "Dica" +/// tip | Dica Alguns editores de texto checam parâmetros de funções não utilizados, e os mostram como erros. @@ -56,7 +56,7 @@ Isso também pode ser útil para evitar confundir novos desenvolvedores que ao v /// -/// info | "Informação" +/// info | Informação Neste exemplo utilizamos cabeçalhos personalizados inventados `X-Keys` e `X-Token`. @@ -90,7 +90,7 @@ Dependências podem declarar requisitos de requisições (como cabeçalhos) ou o //// tab | Python 3.8 non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível @@ -124,7 +124,7 @@ Essas dependências podem levantar exceções, da mesma forma que dependências //// tab | Python 3.8 non-Annotated -/// tip | "Dica" +/// tip | Dica Utilize a versão com `Annotated` se possível @@ -160,7 +160,7 @@ Então, você pode reutilizar uma dependência comum (que retorna um valor) que //// tab | Python 3.8 non-Annotated -/// tip | "Dica" +/// tip | Dica diff --git a/docs/pt/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/pt/docs/tutorial/dependencies/dependencies-with-yield.md index d90bebe39..90c1e02e0 100644 --- a/docs/pt/docs/tutorial/dependencies/dependencies-with-yield.md +++ b/docs/pt/docs/tutorial/dependencies/dependencies-with-yield.md @@ -4,13 +4,13 @@ O FastAPI possui suporte para dependências que realizam . @@ -43,7 +43,7 @@ Mas se você tiver cabeçalhos personalizados desejando que um cliente em um nav /// -/// note | "Detalhes técnicos" +/// note | Detalhes técnicos Você também pode usar `from starlette.requests import Request`. diff --git a/docs/pt/docs/tutorial/path-operation-configuration.md b/docs/pt/docs/tutorial/path-operation-configuration.md index 48753d725..5f3cc82fb 100644 --- a/docs/pt/docs/tutorial/path-operation-configuration.md +++ b/docs/pt/docs/tutorial/path-operation-configuration.md @@ -2,7 +2,7 @@ Existem vários parâmetros que você pode passar para o seu *decorador de operação de rota* para configurá-lo. -/// warning | "Aviso" +/// warning | Aviso Observe que esses parâmetros são passados diretamente para o *decorador de operação de rota*, não para a sua *função de operação de rota*. @@ -42,7 +42,7 @@ Mas se você não se lembrar o que cada código numérico significa, pode usar a Esse código de status será usado na resposta e será adicionado ao esquema OpenAPI. -/// note | "Detalhes Técnicos" +/// note | Detalhes Técnicos Você também poderia usar `from starlette import status`. @@ -185,7 +185,7 @@ Você pode especificar a descrição da resposta com o parâmetro `response_desc //// -/// info | "Informação" +/// info | Informação Note que `response_description` se refere especificamente à resposta, a `description` se refere à *operação de rota* em geral. diff --git a/docs/pt/docs/tutorial/path-params-numeric-validations.md b/docs/pt/docs/tutorial/path-params-numeric-validations.md index 28c55482f..3361f86c5 100644 --- a/docs/pt/docs/tutorial/path-params-numeric-validations.md +++ b/docs/pt/docs/tutorial/path-params-numeric-validations.md @@ -44,7 +44,7 @@ Por exemplo para declarar um valor de metadado `title` para o parâmetro de rota //// -/// note | "Nota" +/// note | Nota Um parâmetro de rota é sempre obrigatório, como se fizesse parte da rota. @@ -132,7 +132,7 @@ E você também pode declarar validações numéricas: * `lt`: menor que (`l`ess `t`han) * `le`: menor que ou igual (`l`ess than or `e`qual) -/// info | "Informação" +/// info | Informação `Query`, `Path` e outras classes que você verá a frente são subclasses de uma classe comum `Param`. @@ -140,7 +140,7 @@ Todas elas compartilham os mesmos parâmetros para validação adicional e metad /// -/// note | "Detalhes Técnicos" +/// note | Detalhes Técnicos Quando você importa `Query`, `Path` e outras de `fastapi`, elas são na verdade funções. diff --git a/docs/pt/docs/tutorial/path-params.md b/docs/pt/docs/tutorial/path-params.md index a68354a1b..64f8a0253 100644 --- a/docs/pt/docs/tutorial/path-params.md +++ b/docs/pt/docs/tutorial/path-params.md @@ -24,7 +24,7 @@ Você pode declarar o tipo de um parâmetro na função usando as anotações pa Nesse caso, `item_id` está sendo declarado como um `int`. -/// check | "Verifique" +/// check | Verifique @@ -40,7 +40,7 @@ Se você rodar esse exemplo e abrir o seu navegador em http://127.0.0.1:8000/items/4.2 -/// check | "Verifique" +/// check | Verifique @@ -91,7 +91,7 @@ Quando você abrir o seu navegador em -/// check | "Verifique" +/// check | Verifique @@ -151,13 +151,13 @@ Assim, crie atributos de classe com valores fixos, que serão os valores válido {!../../docs_src/path_params/tutorial005.py!} ``` -/// info | "informação" +/// info | informação Enumerations (ou enums) estão disponíveis no Python desde a versão 3.4. /// -/// tip | "Dica" +/// tip | Dica @@ -199,7 +199,7 @@ Você pode ter o valor exato de enumerate (um `str` nesse caso) usando `model_na {!../../docs_src/path_params/tutorial005.py!} ``` -/// tip | "Dica" +/// tip | Dica @@ -258,7 +258,7 @@ Então, você poderia usar ele com: {!../../docs_src/path_params/tutorial004.py!} ``` -/// tip | "Dica" +/// tip | Dica diff --git a/docs/pt/docs/tutorial/query-params-str-validations.md b/docs/pt/docs/tutorial/query-params-str-validations.md index e6dcf748e..2fa0eeba0 100644 --- a/docs/pt/docs/tutorial/query-params-str-validations.md +++ b/docs/pt/docs/tutorial/query-params-str-validations.md @@ -10,7 +10,7 @@ Vamos utilizar essa aplicação como exemplo: O parâmetro de consulta `q` é do tipo `Union[str, None]`, o que significa que é do tipo `str` mas que também pode ser `None`, e de fato, o valor padrão é `None`, então o FastAPI saberá que não é obrigatório. -/// note | "Observação" +/// note | Observação O FastAPI saberá que o valor de `q` não é obrigatório por causa do valor padrão `= None`. @@ -54,7 +54,7 @@ q: Union[str, None] = None Mas o declara explicitamente como um parâmetro de consulta. -/// info | "Informação" +/// info | Informação Tenha em mente que o FastAPI se preocupa com a parte: @@ -118,7 +118,7 @@ Vamos dizer que você queira que o parâmetro de consulta `q` tenha um `min_leng {!../../docs_src/query_params_str_validations/tutorial005.py!} ``` -/// note | "Observação" +/// note | Observação O parâmetro torna-se opcional quando possui um valor padrão. @@ -150,7 +150,7 @@ Então, quando você precisa declarar um parâmetro obrigatório utilizando o `Q {!../../docs_src/query_params_str_validations/tutorial006.py!} ``` -/// info | "Informação" +/// info | Informação Se você nunca viu os `...` antes: é um valor único especial, faz parte do Python e é chamado "Ellipsis". @@ -187,7 +187,7 @@ Assim, a resposta para essa URL seria: } ``` -/// tip | "Dica" +/// tip | Dica Para declarar um parâmetro de consulta com o tipo `list`, como no exemplo acima, você precisa usar explicitamente o `Query`, caso contrário será interpretado como um corpo da requisição. @@ -230,7 +230,7 @@ Você também pode utilizar o tipo `list` diretamente em vez de `List[str]`: {!../../docs_src/query_params_str_validations/tutorial013.py!} ``` -/// note | "Observação" +/// note | Observação Tenha em mente que neste caso, o FastAPI não irá validar os conteúdos da lista. @@ -244,7 +244,7 @@ Você pode adicionar mais informações sobre o parâmetro. Essa informações serão inclusas no esquema do OpenAPI e utilizado pela documentação interativa e ferramentas externas. -/// note | "Observação" +/// note | Observação Tenha em mente que cada ferramenta oferece diferentes níveis de suporte ao OpenAPI. diff --git a/docs/pt/docs/tutorial/query-params.md b/docs/pt/docs/tutorial/query-params.md index 6e6699cd5..89b951de6 100644 --- a/docs/pt/docs/tutorial/query-params.md +++ b/docs/pt/docs/tutorial/query-params.md @@ -81,7 +81,7 @@ Da mesma forma, você pode declarar parâmetros de consulta opcionais, definindo Nesse caso, o parâmetro da função `q` será opcional, e `None` será o padrão. -/// check | "Verificar" +/// check | Verificar Você também pode notar que o **FastAPI** é esperto o suficiente para perceber que o parâmetro da rota `item_id` é um parâmetro da rota, e `q` não é, portanto, `q` é o parâmetro de consulta. @@ -239,7 +239,7 @@ Nesse caso, existem 3 parâmetros de consulta: * `skip`, um `int` com o valor padrão `0`. * `limit`, um `int` opcional. -/// tip | "Dica" +/// tip | Dica Você também poderia usar `Enum` da mesma forma que com [Path Parameters](path-params.md#valores-predefinidos){.internal-link target=_blank}. diff --git a/docs/pt/docs/tutorial/request-files.md b/docs/pt/docs/tutorial/request-files.md index d230f1feb..c22c1c513 100644 --- a/docs/pt/docs/tutorial/request-files.md +++ b/docs/pt/docs/tutorial/request-files.md @@ -103,7 +103,7 @@ Quando você usa os métodos `async`, o **FastAPI** executa os métodos de arqui /// -/// note | "Detalhes Técnicos do Starlette" +/// note | Detalhes Técnicos do Starlette O `UploadFile` do ***FastAPI** herda diretamente do `UploadFile` do **Starlette** , mas adiciona algumas partes necessárias para torná-lo compatível com o **Pydantic** e as outras partes do FastAPI. @@ -115,7 +115,7 @@ O jeito que os formulários HTML (`
`) enviam os dados para o servid **FastAPI** se certificará de ler esses dados do lugar certo, ao invés de JSON. -/// note | "Detalhes Técnicos" +/// note | Detalhes Técnicos Dados de formulários normalmente são codificados usando o "media type" (tipo de mídia) `application/x-www-form-urlencoded` quando não incluem arquivos. @@ -157,7 +157,7 @@ Para usar isso, declare uma lista de `bytes` ou `UploadFile`: Você receberá, tal como declarado, uma `list` de `bytes` ou `UploadFile`. -/// note | "Detalhes Técnicos" +/// note | Detalhes Técnicos Você pode também pode usar `from starlette.responses import HTMLResponse`. diff --git a/docs/pt/docs/tutorial/request-form-models.md b/docs/pt/docs/tutorial/request-form-models.md index 837e24c34..7128a0ae2 100644 --- a/docs/pt/docs/tutorial/request-form-models.md +++ b/docs/pt/docs/tutorial/request-form-models.md @@ -2,7 +2,7 @@ Você pode utilizar **Modelos Pydantic** para declarar **campos de formulários** no FastAPI. -/// info | "Informação" +/// info | Informação Para utilizar formulários, instale primeiramente o `python-multipart`. @@ -14,7 +14,7 @@ $ pip install python-multipart /// -/// note | "Nota" +/// note | Nota Isto é suportado desde a versão `0.113.0` do FastAPI. 🤓 @@ -42,7 +42,7 @@ Você precisa apenas declarar um **modelo Pydantic** com os campos que deseja re //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Prefira utilizar a versão `Annotated` se possível. @@ -68,7 +68,7 @@ Você pode verificar na UI de documentação em `/docs`: Em alguns casos de uso especiais (provavelmente não muito comum), você pode desejar **restringir** os campos do formulário para aceitar apenas os declarados no modelo Pydantic. E **proibir** qualquer campo **extra**. -/// note | "Nota" +/// note | Nota Isso é suportado deste a versão `0.114.0` do FastAPI. 🤓 diff --git a/docs/pt/docs/tutorial/request-forms-and-files.md b/docs/pt/docs/tutorial/request-forms-and-files.md index 29488b4f2..77c099eb3 100644 --- a/docs/pt/docs/tutorial/request-forms-and-files.md +++ b/docs/pt/docs/tutorial/request-forms-and-files.md @@ -2,7 +2,7 @@ Você pode definir arquivos e campos de formulário ao mesmo tempo usando `File` e `Form`. -/// info | "Informação" +/// info | Informação Para receber arquivos carregados e/ou dados de formulário, primeiro instale `python-multipart`. @@ -28,7 +28,7 @@ Os arquivos e campos de formulário serão carregados como dados de formulário E você pode declarar alguns dos arquivos como `bytes` e alguns como `UploadFile`. -/// warning | "Aviso" +/// warning | Aviso Você pode declarar vários parâmetros `File` e `Form` em uma *operação de caminho*, mas não é possível declarar campos `Body` para receber como JSON, pois a requisição terá o corpo codificado usando `multipart/form-data` ao invés de `application/json`. diff --git a/docs/pt/docs/tutorial/request-forms.md b/docs/pt/docs/tutorial/request-forms.md index 1e2faf269..367fca072 100644 --- a/docs/pt/docs/tutorial/request-forms.md +++ b/docs/pt/docs/tutorial/request-forms.md @@ -2,7 +2,7 @@ Quando você precisar receber campos de formulário ao invés de JSON, você pode usar `Form`. -/// info | "Informação" +/// info | Informação Para usar formulários, primeiro instale `python-multipart`. @@ -32,13 +32,13 @@ A spec exige que os campos sejam exatamente Com `Form` você pode declarar os mesmos metadados e validação que com `Body` (e `Query`, `Path`, `Cookie`). -/// info | "Informação" +/// info | Informação `Form` é uma classe que herda diretamente de `Body`. /// -/// tip | "Dica" +/// tip | Dica Para declarar corpos de formulário, você precisa usar `Form` explicitamente, porque sem ele os parâmetros seriam interpretados como parâmetros de consulta ou parâmetros de corpo (JSON). @@ -50,7 +50,7 @@ A forma como os formulários HTML (`
`) enviam os dados para o servi O **FastAPI** fará a leitura desses dados no lugar certo em vez de JSON. -/// note | "Detalhes técnicos" +/// note | Detalhes técnicos Os dados dos formulários são normalmente codificados usando o "tipo de mídia" `application/x-www-form-urlencoded`. @@ -60,7 +60,7 @@ Se você quiser ler mais sobre essas codificações e campos de formulário, vá /// -/// warning | "Aviso" +/// warning | Aviso Você pode declarar vários parâmetros `Form` em uma *operação de caminho*, mas não pode declarar campos `Body` que espera receber como JSON, pois a solicitação terá o corpo codificado usando `application/x-www- form-urlencoded` em vez de `application/json`. diff --git a/docs/pt/docs/tutorial/response-status-code.md b/docs/pt/docs/tutorial/response-status-code.md index bc4a2cd34..2c8924925 100644 --- a/docs/pt/docs/tutorial/response-status-code.md +++ b/docs/pt/docs/tutorial/response-status-code.md @@ -12,7 +12,7 @@ Da mesma forma que você pode especificar um modelo de resposta, você também p {!../../docs_src/response_status_code/tutorial001.py!} ``` -/// note | "Nota" +/// note | Nota Observe que `status_code` é um parâmetro do método "decorador" (get, post, etc). Não da sua função de *operação de caminho*, como todos os parâmetros e corpo. @@ -20,7 +20,7 @@ Observe que `status_code` é um parâmetro do método "decorador" (get, post, et O parâmetro `status_code` recebe um número com o código de status HTTP. -/// info | "Informação" +/// info | Informação `status_code` também pode receber um `IntEnum`, como o do Python `http.HTTPStatus`. @@ -33,7 +33,7 @@ Dessa forma: -/// note | "Nota" +/// note | Nota Alguns códigos de resposta (consulte a próxima seção) indicam que a resposta não possui um corpo. @@ -43,7 +43,7 @@ O FastAPI sabe disso e produzirá documentos OpenAPI informando que não há cor ## Sobre os códigos de status HTTP -/// note | "Nota" +/// note | Nota Se você já sabe o que são códigos de status HTTP, pule para a próxima seção. @@ -67,7 +67,7 @@ Resumidamente: * Para erros genéricos do cliente, você pode usar apenas `400`. * `500` e acima são para erros do servidor. Você quase nunca os usa diretamente. Quando algo der errado em alguma parte do código do seu aplicativo ou servidor, ele retornará automaticamente um desses códigos de status. -/// tip | "Dica" +/// tip | Dica Para saber mais sobre cada código de status e qual código serve para quê, verifique o MDN documentação sobre códigos de status HTTP. @@ -95,7 +95,7 @@ Eles são apenas uma conveniência, eles possuem o mesmo número, mas dessa form -/// note | "Detalhes técnicos" +/// note | Detalhes técnicos Você também pode usar `from starlette import status`. diff --git a/docs/pt/docs/tutorial/schema-extra-example.md b/docs/pt/docs/tutorial/schema-extra-example.md index 2d78e4ef1..dd95d4c7d 100644 --- a/docs/pt/docs/tutorial/schema-extra-example.md +++ b/docs/pt/docs/tutorial/schema-extra-example.md @@ -14,7 +14,7 @@ Você pode declarar um `example` para um modelo Pydantic usando `Config` e `sche Essas informações extras serão adicionadas como se encontram no **JSON Schema** de resposta desse modelo e serão usadas na documentação da API. -/// tip | "Dica" +/// tip | Dica Você pode usar a mesma técnica para estender o JSON Schema e adicionar suas próprias informações extras de forma personalizada. @@ -32,7 +32,7 @@ Você pode usar isso para adicionar um `example` para cada campo: {!../../docs_src/schema_extra_example/tutorial002.py!} ``` -/// warning | "Atenção" +/// warning | Atenção Lembre-se de que esses argumentos extras passados ​​não adicionarão nenhuma validação, apenas informações extras, para fins de documentação. @@ -91,7 +91,7 @@ Com `examples` adicionado a `Body()`, os `/docs` vão ficar assim: ## Detalhes técnicos -/// warning | "Atenção" +/// warning | Atenção Esses são detalhes muito técnicos sobre os padrões **JSON Schema** e **OpenAPI**. diff --git a/docs/pt/docs/tutorial/security/first-steps.md b/docs/pt/docs/tutorial/security/first-steps.md index 9fb94fe67..02871c90a 100644 --- a/docs/pt/docs/tutorial/security/first-steps.md +++ b/docs/pt/docs/tutorial/security/first-steps.md @@ -25,7 +25,7 @@ Copie o exemplo em um arquivo `main.py`: ## Execute-o -/// info | "informação" +/// info | informação @@ -57,7 +57,7 @@ Você verá algo deste tipo: -/// check | "Botão de Autorizar!" +/// check | Botão de Autorizar! @@ -71,7 +71,7 @@ E se você clicar, você terá um pequeno formulário de autorização para digi -/// note | "Nota" +/// note | Nota @@ -119,7 +119,7 @@ Então, vamos rever de um ponto de vista simplificado: Neste exemplo, nós vamos usar o **OAuth2** com o fluxo de **Senha**, usando um token **Bearer**. Fazemos isso usando a classe `OAuth2PasswordBearer`. -/// info | "informação" +/// info | informação @@ -139,7 +139,7 @@ Quando nós criamos uma instância da classe `OAuth2PasswordBearer`, nós passam {!../../docs_src/security/tutorial001.py!} ``` -/// tip | "Dica" +/// tip | Dica @@ -155,7 +155,7 @@ Esse parâmetro não cria um endpoint / *path operation*, mas declara que a URL Em breve também criaremos o atual path operation. -/// info | "informação" +/// info | informação @@ -187,7 +187,7 @@ Esse dependência vai fornecer uma `str` que é atribuído ao parâmetro `token A **FastAPI** saberá que pode usar essa dependência para definir um "esquema de segurança" no esquema da OpenAPI (e na documentação da API automática). -/// info | "Detalhes técnicos" +/// info | Detalhes técnicos diff --git a/docs/pt/docs/tutorial/security/index.md b/docs/pt/docs/tutorial/security/index.md index 2f23aa47e..b4440ec04 100644 --- a/docs/pt/docs/tutorial/security/index.md +++ b/docs/pt/docs/tutorial/security/index.md @@ -32,7 +32,7 @@ Não é muito popular ou usado nos dias atuais. OAuth2 não especifica como criptografar a comunicação, ele espera que você tenha sua aplicação em um servidor HTTPS. -/// tip | "Dica" +/// tip | Dica Na seção sobre **deployment** você irá ver como configurar HTTPS de modo gratuito, usando Traefik e Let’s Encrypt. @@ -89,7 +89,7 @@ OpenAPI define os seguintes esquemas de segurança: * Essa descoberta automática é o que é definido na especificação OpenID Connect. -/// tip | "Dica" +/// tip | Dica Integração com outros provedores de autenticação/autorização como Google, Facebook, Twitter, GitHub, etc. é bem possível e relativamente fácil. diff --git a/docs/pt/docs/tutorial/static-files.md b/docs/pt/docs/tutorial/static-files.md index 901fca1d2..aba4b8221 100644 --- a/docs/pt/docs/tutorial/static-files.md +++ b/docs/pt/docs/tutorial/static-files.md @@ -11,7 +11,7 @@ Você pode servir arquivos estáticos automaticamente de um diretório usando `S {!../../docs_src/static_files/tutorial001.py!} ``` -/// note | "Detalhes técnicos" +/// note | Detalhes técnicos Você também pode usar `from starlette.staticfiles import StaticFiles`. diff --git a/docs/pt/docs/tutorial/testing.md b/docs/pt/docs/tutorial/testing.md index 4e28a43c0..4f8eaa299 100644 --- a/docs/pt/docs/tutorial/testing.md +++ b/docs/pt/docs/tutorial/testing.md @@ -8,7 +8,7 @@ Com ele, você pode usar o `httpx`. @@ -34,7 +34,7 @@ Escreva instruções `assert` simples com as expressões Python padrão que voc {!../../docs_src/app_testing/tutorial001.py!} ``` -/// tip | "Dica" +/// tip | Dica Observe que as funções de teste são `def` normais, não `async def`. @@ -44,7 +44,7 @@ Isso permite que você use `pytest` diretamente sem complicações. /// -/// note | "Detalhes técnicos" +/// note | Detalhes técnicos Você também pode usar `from starlette.testclient import TestClient`. @@ -52,7 +52,7 @@ Você também pode usar `from starlette.testclient import TestClient`. /// -/// tip | "Dica" +/// tip | Dica Se você quiser chamar funções `async` em seus testes além de enviar solicitações ao seu aplicativo FastAPI (por exemplo, funções de banco de dados assíncronas), dê uma olhada em [Testes assíncronos](../advanced/async-tests.md){.internal-link target=_blank} no tutorial avançado. @@ -152,7 +152,7 @@ Ambas as *operações de rotas* requerem um cabeçalho `X-Token`. //// tab | Python 3.10+ non-Annotated -/// tip | "Dica" +/// tip | Dica Prefira usar a versão `Annotated` se possível. @@ -166,7 +166,7 @@ Prefira usar a versão `Annotated` se possível. //// tab | Python 3.8+ non-Annotated -/// tip | "Dica" +/// tip | Dica Prefira usar a versão `Annotated` se possível. @@ -200,7 +200,7 @@ Por exemplo: Para mais informações sobre como passar dados para o backend (usando `httpx` ou `TestClient`), consulte a documentação do HTTPX. -/// info | "Informação" +/// info | Informação Observe que o `TestClient` recebe dados que podem ser convertidos para JSON, não para modelos Pydantic. diff --git a/docs/pt/docs/virtual-environments.md b/docs/pt/docs/virtual-environments.md index 863c8d65e..5fc1a8866 100644 --- a/docs/pt/docs/virtual-environments.md +++ b/docs/pt/docs/virtual-environments.md @@ -2,13 +2,13 @@ Ao trabalhar em projetos Python, você provavelmente deve usar um **ambiente virtual** (ou um mecanismo similar) para isolar os pacotes que você instala para cada projeto. -/// info | "Informação" +/// info | Informação Se você já sabe sobre ambientes virtuais, como criá-los e usá-los, talvez seja melhor pular esta seção. 🤓 /// -/// tip | "Dica" +/// tip | Dica Um **ambiente virtual** é diferente de uma **variável de ambiente**. @@ -18,7 +18,7 @@ Um **ambiente virtual** é um diretório com alguns arquivos. /// -/// info | "Informação" +/// info | Informação Esta página lhe ensinará como usar **ambientes virtuais** e como eles funcionam. @@ -55,7 +55,7 @@ $ cd awesome-project Ao começar a trabalhar em um projeto Python **pela primeira vez**, crie um ambiente virtual **dentro do seu projeto**. -/// tip | "Dica" +/// tip | Dica Você só precisa fazer isso **uma vez por projeto**, não toda vez que trabalhar. @@ -96,7 +96,7 @@ $ uv venv -/// tip | "Dica" +/// tip | Dica Por padrão, `uv` criará um ambiente virtual em um diretório chamado `.venv`. @@ -118,7 +118,7 @@ Você pode criar o ambiente virtual em um diretório diferente, mas há uma conv Ative o novo ambiente virtual para que qualquer comando Python que você executar ou pacote que você instalar o utilize. -/// tip | "Dica" +/// tip | Dica Faça isso **toda vez** que iniciar uma **nova sessão de terminal** para trabalhar no projeto. @@ -162,7 +162,7 @@ $ source .venv/Scripts/activate //// -/// tip | "Dica" +/// tip | Dica Toda vez que você instalar um **novo pacote** naquele ambiente, **ative** o ambiente novamente. @@ -174,7 +174,7 @@ Isso garante que, se você usar um **programa de terminal (`uv`, você o usará para instalar coisas em vez do `pip`, então não precisará atualizar o `pip`. 😎 @@ -224,7 +224,7 @@ Se você estiver usando `pip` para instalar pacotes (ele vem por padrão com o P Muitos erros exóticos durante a instalação de um pacote são resolvidos apenas atualizando o `pip` primeiro. -/// tip | "Dica" +/// tip | Dica Normalmente, você faria isso **uma vez**, logo após criar o ambiente virtual. @@ -246,13 +246,13 @@ $ python -m pip install --upgrade pip Se você estiver usando **Git** (você deveria), adicione um arquivo `.gitignore` para excluir tudo em seu `.venv` do Git. -/// tip | "Dica" +/// tip | Dica Se você usou `uv` para criar o ambiente virtual, ele já fez isso para você, você pode pular esta etapa. 😎 /// -/// tip | "Dica" +/// tip | Dica Faça isso **uma vez**, logo após criar o ambiente virtual. @@ -286,7 +286,7 @@ Esse comando criará um arquivo `.gitignore` com o conteúdo: Após ativar o ambiente, você pode instalar pacotes nele. -/// tip | "Dica" +/// tip | Dica Faça isso **uma vez** ao instalar ou atualizar os pacotes que seu projeto precisa. @@ -298,7 +298,7 @@ Se precisar atualizar uma versão ou adicionar um novo pacote, você **fará iss 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" +/// 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`). @@ -399,7 +399,7 @@ Por exemplo: * VS Code * PyCharm -/// tip | "Dica" +/// tip | Dica Normalmente, você só precisa fazer isso **uma vez**, ao criar o ambiente virtual. @@ -425,7 +425,7 @@ Agora você está pronto para começar a trabalhar no seu projeto. -/// tip | "Dica" +/// tip | Dica Você quer entender o que é tudo isso acima? @@ -516,7 +516,7 @@ flowchart LR end ``` -/// tip | "Dica" +/// 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. @@ -623,7 +623,7 @@ Esse comando criará ou modificará algumas [variáveis ​​de ambiente](envir Uma dessas variáveis ​​é a variável `PATH`. -/// tip | "Dica" +/// 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){.internal-link target=_blank}. @@ -756,7 +756,7 @@ A parte mais importante é que quando você chama ``python`, esse é exatamente Assim, você pode confirmar se está no ambiente virtual correto. -/// tip | "Dica" +/// tip | Dica É fácil ativar um ambiente virtual, obter um Python e então **ir para outro projeto**. diff --git a/docs/ru/docs/alternatives.md b/docs/ru/docs/alternatives.md index f83024ad9..3c5147e79 100644 --- a/docs/ru/docs/alternatives.md +++ b/docs/ru/docs/alternatives.md @@ -33,14 +33,14 @@ DRF использовался многими компаниями, включа Это был один из первых примеров **автоматического документирования API** и это была одна из первых идей, вдохновивших на создание **FastAPI**. -/// note | "Заметка" +/// note | Заметка Django REST Framework был создан Tom Christie. Он же создал Starlette и Uvicorn, на которых основан **FastAPI**. /// -/// check | "Идея для **FastAPI**" +/// check | Идея для **FastAPI** Должно быть автоматическое создание документации API с пользовательским веб-интерфейсом. @@ -62,7 +62,7 @@ Flask часто используется и для приложений, кот Простота Flask, показалась мне подходящей для создания API. Но ещё нужно было найти "Django REST Framework" для Flask. -/// check | "Идеи для **FastAPI**" +/// check | Идеи для **FastAPI** Это будет микрофреймворк. К нему легко будет добавить необходимые инструменты и части. @@ -108,7 +108,7 @@ def read_url(): Глядите, как похоже `requests.get(...)` и `@app.get(...)`. -/// check | "Идеи для **FastAPI**" +/// check | Идеи для **FastAPI** * Должен быть простой и понятный API. * Нужно использовать названия HTTP-методов (операций) для упрощения понимания происходящего. @@ -129,7 +129,7 @@ def read_url(): Вот почему, когда говорят о версии 2.0, обычно говорят "Swagger", а для версии 3+ "OpenAPI". -/// check | "Идеи для **FastAPI**" +/// check | Идеи для **FastAPI** Использовать открытые стандарты для спецификаций API вместо самодельных схем. @@ -165,7 +165,7 @@ def read_url(): Итак, чтобы определить каждую схему, Вам нужно использовать определенные утилиты и классы, предоставляемые Marshmallow. -/// check | "Идея для **FastAPI**" +/// check | Идея для **FastAPI** Использовать код программы для автоматического создания "схем", определяющих типы данных и их проверку. @@ -181,13 +181,13 @@ Webargs - это инструмент, который был создан для Это превосходный инструмент и я тоже часто пользовался им до **FastAPI**. -/// info | "Информация" +/// info | Информация Webargs бы создан разработчиками Marshmallow. /// -/// check | "Идея для **FastAPI**" +/// check | Идея для **FastAPI** Должна быть автоматическая проверка входных данных. @@ -212,13 +212,13 @@ Marshmallow и Webargs осуществляют проверку, анализ Редактор кода не особо может помочь в такой парадигме. А изменив какие-то параметры или схемы для Marshmallow можно забыть отредактировать докстринг с YAML и сгенерированная схема становится недействительной. -/// info | "Информация" +/// info | Информация APISpec тоже был создан авторами Marshmallow. /// -/// check | "Идея для **FastAPI**" +/// check | Идея для **FastAPI** Необходима поддержка открытого стандарта для API - OpenAPI. @@ -246,13 +246,13 @@ APISpec тоже был создан авторами Marshmallow. Эти генераторы проектов также стали основой для [Генераторов проектов с **FastAPI**](project-generation.md){.internal-link target=_blank}. -/// info | "Информация" +/// info | Информация Как ни странно, но Flask-apispec тоже создан авторами Marshmallow. /// -/// check | "Идея для **FastAPI**" +/// check | Идея для **FastAPI** Схема OpenAPI должна создаваться автоматически и использовать тот же код, который осуществляет сериализацию и проверку данных. @@ -276,7 +276,7 @@ APISpec тоже был создан авторами Marshmallow. Кроме того, он не очень хорошо справляется с вложенными моделями. Если в запросе имеется объект JSON, внутренние поля которого, в свою очередь, являются вложенными объектами JSON, это не может быть должным образом задокументировано и проверено. -/// check | "Идеи для **FastAPI** " +/// check | Идеи для **FastAPI** Нужно использовать подсказки типов, чтоб воспользоваться поддержкой редактора кода. @@ -289,7 +289,7 @@ APISpec тоже был создан авторами Marshmallow. Sanic был одним из первых чрезвычайно быстрых Python-фреймворков основанных на `asyncio`. Он был сделан очень похожим на Flask. -/// note | "Технические детали" +/// note | Технические детали В нём использован `uvloop` вместо стандартного цикла событий `asyncio`, что и сделало его таким быстрым. @@ -297,7 +297,7 @@ Sanic был одним из первых чрезвычайно быстрых /// -/// check | "Идеи для **FastAPI**" +/// check | Идеи для **FastAPI** Должна быть сумасшедшая производительность. @@ -318,7 +318,7 @@ Falcon - ещё один высокопроизводительный Python-ф Либо эти функции должны быть встроены во фреймворк, сконструированный поверх Falcon, как в Hug. Такая же особенность присутствует и в других фреймворках, вдохновлённых идеей Falcon, использовать только один объект запроса и один объект ответа. -/// check | "Идея для **FastAPI**" +/// check | Идея для **FastAPI** Найдите способы добиться отличной производительности. @@ -348,7 +348,7 @@ Molten мне попался на начальной стадии написан Это больше похоже на Django, чем на Flask и Starlette. Он разделяет в коде вещи, которые довольно тесно связаны. -/// check | "Идея для **FastAPI**" +/// check | Идея для **FastAPI** Определить дополнительные проверки типов данных, используя значения атрибутов модели "по умолчанию". Это улучшает помощь редактора и раньше это не было доступно в Pydantic. @@ -374,13 +374,13 @@ Hug был одним из первых фреймворков, реализов Поскольку он основан на WSGI, старом стандарте для синхронных веб-фреймворков, он не может работать с веб-сокетами и другими модными штуками, но всё равно обладает высокой производительностью. -/// info | "Информация" +/// info | Информация Hug создан Timothy Crosley, автором `isort`, отличного инструмента для автоматической сортировки импортов в Python-файлах. /// -/// check | "Идеи для **FastAPI**" +/// check | Идеи для **FastAPI** Hug повлиял на создание некоторых частей APIStar и был одним из инструментов, которые я счел наиболее многообещающими, наряду с APIStar. @@ -418,7 +418,7 @@ Hug вдохновил **FastAPI** объявить параметр `ответ Ныне APIStar - это набор инструментов для проверки спецификаций OpenAPI. -/// info | "Информация" +/// info | Информация APIStar был создан Tom Christie. Тот самый парень, который создал: @@ -428,7 +428,7 @@ APIStar был создан Tom Christie. Тот самый парень, кот /// -/// check | "Идеи для **FastAPI**" +/// check | Идеи для **FastAPI** Воплощение. @@ -452,7 +452,7 @@ Pydantic - это библиотека для валидации данных, Его можно сравнить с Marshmallow, хотя в бенчмарках Pydantic быстрее, чем Marshmallow. И он основан на тех же подсказках типов, которые отлично поддерживаются редакторами кода. -/// check | "**FastAPI** использует Pydantic" +/// check | **FastAPI** использует Pydantic Для проверки данных, сериализации данных и автоматической документации моделей (на основе JSON Schema). @@ -488,7 +488,7 @@ Starlette обеспечивает весь функционал микрофр **FastAPI** добавляет эти функции используя подсказки типов Python и Pydantic. Ещё **FastAPI** добавляет систему внедрения зависимостей, утилиты безопасности, генерацию схемы OpenAPI и т.д. -/// note | "Технические детали" +/// note | Технические детали ASGI - это новый "стандарт" разработанный участниками команды Django. Он пока что не является "стандартом в Python" (то есть принятым PEP), но процесс принятия запущен. @@ -498,7 +498,7 @@ ASGI - это новый "стандарт" разработанный учас /// -/// check | "**FastAPI** использует Starlette" +/// check | **FastAPI** использует Starlette В качестве ядра веб-сервиса для обработки запросов, добавив некоторые функции сверху. @@ -518,7 +518,7 @@ Uvicorn является сервером, а не фреймворком. Он рекомендуется в качестве сервера для Starlette и **FastAPI**. -/// check | "**FastAPI** рекомендует его" +/// check | **FastAPI** рекомендует его Как основной сервер для запуска приложения **FastAPI**. diff --git a/docs/ru/docs/contributing.md b/docs/ru/docs/contributing.md deleted file mode 100644 index c4370f9bb..000000000 --- a/docs/ru/docs/contributing.md +++ /dev/null @@ -1,496 +0,0 @@ -# Участие в разработке фреймворка - -Возможно, для начала Вам стоит ознакомиться с основными способами [помочь FastAPI или получить помощь](help-fastapi.md){.internal-link target=_blank}. - -## Разработка - -Если Вы уже склонировали репозиторий и знаете, что Вам нужно более глубокое погружение в код фреймворка, то здесь представлены некоторые инструкции по настройке виртуального окружения. - -### Виртуальное окружение с помощью `venv` - -Находясь в нужной директории, Вы можете создать виртуальное окружение при помощи Python модуля `venv`. - -
- -```console -$ python -m venv env -``` - -
- -Эта команда создаст директорию `./env/` с бинарными (двоичными) файлами Python, а затем Вы сможете скачивать и устанавливать необходимые библиотеки в изолированное виртуальное окружение. - -### Активация виртуального окружения - -Активируйте виртуально окружение командой: - -//// tab | Linux, macOS - -
- -```console -$ source ./env/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .\env\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Если Вы пользуетесь Bash для Windows (например: Git Bash): - -
- -```console -$ source ./env/Scripts/activate -``` - -
- -//// - -Проверьте, что всё сработало: - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which pip - -some/directory/fastapi/env/bin/pip -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command pip - -some/directory/fastapi/env/bin/pip -``` - -
- -//// - -Если в терминале появится ответ, что бинарник `pip` расположен по пути `.../env/bin/pip`, значит всё в порядке. 🎉 - -Во избежание ошибок в дальнейших шагах, удостоверьтесь, что в Вашем виртуальном окружении установлена последняя версия `pip`: - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip | "Подсказка" - -Каждый раз, перед установкой новой библиотеки в виртуальное окружение при помощи `pip`, не забудьте активировать это виртуальное окружение. - -Это гарантирует, что если Вы используете библиотеку, установленную этим пакетом, то Вы используете библиотеку из Вашего локального окружения, а не любую другую, которая может быть установлена глобально. - -/// - -### pip - -После активации виртуального окружения, как было указано ранее, введите следующую команду: - -
- -```console -$ pip install -r requirements.txt - ----> 100% -``` - -
- -Это установит все необходимые зависимости в локальное окружение для Вашего локального FastAPI. - -#### Использование локального FastAPI - -Если Вы создаёте Python файл, который импортирует и использует FastAPI,а затем запускаете его интерпретатором Python из Вашего локального окружения, то он будет использовать код из локального FastAPI. - -И, так как при вводе вышеупомянутой команды был указан флаг `-e`, если Вы измените код локального FastAPI, то при следующем запуске этого файла, он будет использовать свежую версию локального FastAPI, который Вы только что изменили. - -Таким образом, Вам не нужно "переустанавливать" Вашу локальную версию, чтобы протестировать каждое изменение. - -### Форматировние - -Скачанный репозиторий содержит скрипт, который может отформатировать и подчистить Ваш код: - -
- -```console -$ bash scripts/format.sh -``` - -
- -Заодно он упорядочит Ваши импорты. - -Чтобы он сортировал их правильно, необходимо, чтобы FastAPI был установлен локально в Вашей среде, с помощью команды из раздела выше, использующей флаг `-e`. - -## Документация - -Прежде всего, убедитесь, что Вы настроили своё окружение, как описано выше, для установки всех зависимостей. - -Документация использует MkDocs. - -Также существуют дополнительные инструменты/скрипты для работы с переводами в `./scripts/docs.py`. - -/// tip | "Подсказка" - -Нет необходимости заглядывать в `./scripts/docs.py`, просто используйте это в командной строке. - -/// - -Вся документация имеет формат Markdown и расположена в директории `./docs/en/`. - -Многие руководства содержат блоки кода. - -В большинстве случаев эти блоки кода представляют собой вполне законченные приложения, которые можно запускать как есть. - -На самом деле, эти блоки кода не написаны внутри Markdown, это Python файлы в директории `./docs_src/`. - -И эти Python файлы включаются/вводятся в документацию при создании сайта. - -### Тестирование документации - - -Фактически, большинство тестов запускаются с примерами исходных файлов в документации. - -Это помогает убедиться, что: - -* Документация находится в актуальном состоянии. -* Примеры из документации могут быть запущены как есть. -* Большинство функций описаны в документации и покрыты тестами. - -Существует скрипт, который во время локальной разработки создаёт сайт и проверяет наличие любых изменений, перезагружая его в реальном времени: - -
- -```console -$ python ./scripts/docs.py live - -[INFO] Serving on http://127.0.0.1:8008 -[INFO] Start watching changes -[INFO] Start detecting changes -``` - -
- -Он запустит сайт документации по адресу: `http://127.0.0.1:8008`. - - -Таким образом, Вы сможете редактировать файлы с документацией или кодом и наблюдать изменения вживую. - -#### Typer CLI (опционально) - - -Приведенная ранее инструкция показала Вам, как запускать скрипт `./scripts/docs.py` непосредственно через интерпретатор `python` . - -Но также можно использовать Typer CLI, что позволит Вам воспользоваться автозаполнением команд в Вашем терминале. - -Если Вы установили Typer CLI, то для включения функции автозаполнения, введите эту команду: - -
- -```console -$ typer --install-completion - -zsh completion installed in /home/user/.bashrc. -Completion will take effect once you restart the terminal. -``` - -
- -### Приложения и документация одновременно - -Если Вы запускаете приложение, например так: - -
- -```console -$ uvicorn tutorial001:app --reload - -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -``` - -
- -По умолчанию Uvicorn будет использовать порт `8000` и не будет конфликтовать с сайтом документации, использующим порт `8008`. - -### Переводы на другие языки - -Помощь с переводами ценится КРАЙНЕ ВЫСОКО! И переводы не могут быть сделаны без помощи сообщества. 🌎 🚀 - -Ниже приведены шаги, как помочь с переводами. - -#### Подсказки и инструкции - -* Проверьте существующие пул-реквесты для Вашего языка. Добавьте отзывы с просьбой внести изменения, если они необходимы, или одобрите их. - -/// tip | "Подсказка" - -Вы можете добавлять комментарии с предложениями по изменению в существующие пул-реквесты. - -Ознакомьтесь с документацией о добавлении отзыва к пул-реквесту, чтобы утвердить его или запросить изменения. - -/// - -* Проверьте проблемы и вопросы, чтобы узнать, есть ли кто-то, координирующий переводы для Вашего языка. - -* Добавляйте один пул-реквест для каждой отдельной переведённой страницы. Это значительно облегчит другим его просмотр. - -Для языков, которые я не знаю, прежде чем добавить перевод в основную ветку, я подожду пока несколько других участников сообщества проверят его. - -* Вы также можете проверить, есть ли переводы для Вашего языка и добавить к ним отзыв, который поможет мне убедиться в правильности перевода. Тогда я смогу объединить его с основной веткой. - -* Используйте те же самые примеры кода Python. Переводите только текст документации. Вам не нужно ничего менять, чтобы эти примеры работали. - -* Используйте те же самые изображения, имена файлов и ссылки. Вы не должны менять ничего для сохранения работоспособности. - -* Чтобы узнать 2-буквенный код языка, на который Вы хотите сделать перевод, Вы можете воспользоваться таблицей Список кодов языков ISO 639-1. - -#### Существующий язык - -Допустим, Вы хотите перевести страницу на язык, на котором уже есть какие-то переводы, например, на испанский. - -Кодом испанского языка является `es`. А значит директория для переводов на испанский язык: `docs/es/`. - -/// tip | "Подсказка" - -Главный ("официальный") язык - английский, директория для него `docs/en/`. - -/// - -Вы можете запустить сервер документации на испанском: - -
- -```console -// Используйте команду "live" и передайте код языка в качестве аргумента командной строки -$ python ./scripts/docs.py live es - -[INFO] Serving on http://127.0.0.1:8008 -[INFO] Start watching changes -[INFO] Start detecting changes -``` - -
- -Теперь Вы можете перейти по адресу: http://127.0.0.1:8008 и наблюдать вносимые Вами изменения вживую. - - -Если Вы посмотрите на сайт документации FastAPI, то увидите, что все страницы есть на каждом языке. Но некоторые страницы не переведены и имеют уведомление об отсутствующем переводе. - -Но когда Вы запускаете сайт локально, Вы видите только те страницы, которые уже переведены. - - -Предположим, что Вы хотите добавить перевод страницы [Основные свойства](features.md){.internal-link target=_blank}. - -* Скопируйте файл: - -``` -docs/en/docs/features.md -``` - -* Вставьте его точно в то же место, но в директорию языка, на который Вы хотите сделать перевод, например: - -``` -docs/es/docs/features.md -``` - -/// tip | "Подсказка" - -Заметьте, что в пути файла мы изменили только код языка с `en` на `es`. - -/// - -* Теперь откройте файл конфигурации MkDocs для английского языка, расположенный тут: - -``` -docs/en/mkdocs.yml -``` - -* Найдите в файле конфигурации место, где расположена строка `docs/features.md`. Похожее на это: - -```YAML hl_lines="8" -site_name: FastAPI -# More stuff -nav: -- FastAPI: index.md -- Languages: - - en: / - - es: /es/ -- features.md -``` - -* Откройте файл конфигурации MkDocs для языка, на который Вы переводите, например: - -``` -docs/es/mkdocs.yml -``` - -* Добавьте строку `docs/features.md` точно в то же место, как и в случае для английского, как-то так: - -```YAML hl_lines="8" -site_name: FastAPI -# More stuff -nav: -- FastAPI: index.md -- Languages: - - en: / - - es: /es/ -- features.md -``` - -Убедитесь, что при наличии других записей, новая запись с Вашим переводом находится точно в том же порядке, что и в английской версии. - -Если Вы зайдёте в свой браузер, то увидите, что в документации стал отображаться Ваш новый раздел.🎉 - -Теперь Вы можете переводить эту страницу и смотреть, как она выглядит при сохранении файла. - -#### Новый язык - -Допустим, Вы хотите добавить перевод для языка, на который пока что не переведена ни одна страница. - -Скажем, Вы решили сделать перевод для креольского языка, но его еще нет в документации. - -Перейдите в таблицу кодов языков по ссылке указанной выше, где найдёте, что кодом креольского языка является `ht`. - -Затем запустите скрипт, генерирующий директорию для переводов на новые языки: - -
- -```console -// Используйте команду new-lang и передайте код языка в качестве аргумента командной строки -$ python ./scripts/docs.py new-lang ht - -Successfully initialized: docs/ht -Updating ht -Updating en -``` - -
- -После чего Вы можете проверить в своем редакторе кода, что появился новый каталог `docs/ht/`. - -/// tip | "Подсказка" - -Создайте первый пул-реквест, который будет содержать только пустую директорию для нового языка, прежде чем добавлять переводы. - -Таким образом, другие участники могут переводить другие страницы, пока Вы работаете над одной. 🚀 - -/// - -Начните перевод с главной страницы `docs/ht/index.md`. - -В дальнейшем можно действовать, как указано в предыдущих инструкциях для "существующего языка". - -##### Новый язык не поддерживается - -Если при запуске скрипта `./scripts/docs.py live` Вы получаете сообщение об ошибке, что язык не поддерживается, что-то вроде: - -``` - raise TemplateNotFound(template) -jinja2.exceptions.TemplateNotFound: partials/language/xx.html -``` - -Сие означает, что тема не поддерживает этот язык (в данном случае с поддельным 2-буквенным кодом `xx`). - -Но не стоит переживать. Вы можете установить языком темы английский, а затем перевести текст документации. - -Если возникла такая необходимость, отредактируйте `mkdocs.yml` для Вашего нового языка. Это будет выглядеть как-то так: - -```YAML hl_lines="5" -site_name: FastAPI -# More stuff -theme: - # More stuff - language: xx -``` - -Измените `xx` (код Вашего языка) на `en` и перезапустите сервер. - -#### Предпросмотр результата - -Когда Вы запускаете скрипт `./scripts/docs.py` с командой `live`, то будут показаны файлы и переводы для указанного языка. - -Но когда Вы закончите, то можете посмотреть, как это будет выглядеть по-настоящему. - -Для этого сначала создайте всю документацию: - -
- -```console -// Используйте команду "build-all", это займёт немного времени -$ python ./scripts/docs.py build-all - -Updating es -Updating en -Building docs for: en -Building docs for: es -Successfully built docs for: es -Copying en index.md to README.md -``` - -
- -Скрипт сгенерирует `./docs_build/` для каждого языка. Он добавит все файлы с отсутствующими переводами с пометкой о том, что "у этого файла еще нет перевода". Но Вам не нужно ничего делать с этим каталогом. - -Затем он создаст независимые сайты MkDocs для каждого языка, объединит их и сгенерирует конечный результат на `./site/`. - -После чего Вы сможете запустить сервер со всеми языками командой `serve`: - -
- -```console -// Используйте команду "serve" после того, как отработает команда "build-all" -$ python ./scripts/docs.py serve - -Warning: this is a very simple server. For development, use mkdocs serve instead. -This is here only to preview a site with translations already built. -Make sure you run the build-all command first. -Serving at: http://127.0.0.1:8008 -``` - -
- -## Тесты - -Также в репозитории есть скрипт, который Вы можете запустить локально, чтобы протестировать весь код и сгенерировать отчеты о покрытии тестами в HTML: - -
- -```console -$ bash scripts/test-cov-html.sh -``` - -
- -Эта команда создаст директорию `./htmlcov/`, в которой будет файл `./htmlcov/index.html`. Открыв его в Вашем браузере, Вы можете в интерактивном режиме изучить, все ли части кода охвачены тестами. diff --git a/docs/ru/docs/deployment/concepts.md b/docs/ru/docs/deployment/concepts.md index c41025790..7cdc29526 100644 --- a/docs/ru/docs/deployment/concepts.md +++ b/docs/ru/docs/deployment/concepts.md @@ -151,7 +151,7 @@ Для случаев, когда ошибки приводят к сбою в запущенном **процессе**, Вам понадобится добавить компонент, который **перезапустит** процесс хотя бы пару раз... -/// tip | "Заметка" +/// tip | Заметка ... Если приложение падает сразу же после запуска, вероятно бесполезно его бесконечно перезапускать. Но полагаю, вы заметите такое поведение во время разработки или, по крайней мере, сразу после развёртывания. @@ -241,7 +241,7 @@ * **Облачные сервисы**, которые позаботятся обо всём за Вас * Возможно, что облачный сервис умеет **управлять запуском дополнительных экземпляров приложения**. Вероятно, он потребует, чтоб вы указали - какой **процесс** или **образ** следует клонировать. Скорее всего, вы укажете **один процесс Uvicorn** и облачный сервис будет запускать его копии при необходимости. -/// tip | "Заметка" +/// tip | Заметка Если вы не знаете, что такое **контейнеры**, Docker или Kubernetes, не переживайте. @@ -263,7 +263,7 @@ Безусловно, возможны случаи, когда нет проблем при выполнении предварительной подготовки параллельно или несколько раз. Тогда Вам повезло, работать с ними намного проще. -/// tip | "Заметка" +/// tip | Заметка Имейте в виду, что в некоторых случаях запуск вашего приложения **может не требовать каких-либо предварительных шагов вовсе**. @@ -281,7 +281,7 @@ * Bash-скрипт, выполняющий предварительные шаги, а затем запускающий приложение. * При этом Вам всё ещё нужно найти способ - как запускать/перезапускать *такой* bash-скрипт, обнаруживать ошибки и т.п. -/// tip | "Заметка" +/// tip | Заметка Я приведу Вам больше конкретных примеров работы с контейнерами в главе: [FastAPI внутри контейнеров - Docker](docker.md){.internal-link target=_blank}. diff --git a/docs/ru/docs/deployment/docker.md b/docs/ru/docs/deployment/docker.md index 9eef5c4d2..31da01b78 100644 --- a/docs/ru/docs/deployment/docker.md +++ b/docs/ru/docs/deployment/docker.md @@ -4,7 +4,7 @@ Использование контейнеров на основе Linux имеет ряд преимуществ, включая **безопасность**, **воспроизводимость**, **простоту** и прочие. -/// tip | "Подсказка" +/// tip | Подсказка Торопитесь или уже знакомы с этой технологией? Перепрыгните на раздел [Создать Docker-образ для FastAPI 👇](#docker-fastapi) @@ -135,7 +135,7 @@ Successfully installed fastapi pydantic uvicorn -/// info | "Информация" +/// info | Информация Существуют и другие инструменты управления зависимостями. @@ -231,7 +231,7 @@ CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] Так как команда выполняется внутри директории `/code`, в которую мы поместили папку `./app` с приложением, то **Uvicorn** сможет найти и **импортировать** объект `app` из файла `app.main`. -/// tip | "Подсказка" +/// tip | Подсказка Если ткнёте на кружок с плюсом, то увидите пояснения. 👆 @@ -306,7 +306,7 @@ $ docker build -t myimage . -/// tip | "Подсказка" +/// tip | Подсказка Обратите внимание, что в конце написана точка - `.`, это то же самое что и `./`, тем самым мы указываем Docker директорию, из которой нужно выполнять сборку образа контейнера. @@ -410,7 +410,7 @@ CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"] Это может быть другой контейнер, в котором есть, например, Traefik, работающий с **HTTPS** и **самостоятельно** обновляющий **сертификаты**. -/// tip | "Подсказка" +/// tip | Подсказка Traefik совместим с Docker, Kubernetes и им подобными инструментами. Он очень прост в установке и настройке использования HTTPS для Ваших контейнеров. @@ -442,7 +442,7 @@ Traefik совместим с Docker, Kubernetes и им подобными ин Поскольку этот компонент **принимает запросы** и равномерно **распределяет** их между компонентами, его также называют **балансировщиком нагрузки**. -/// tip | "Подсказка" +/// tip | Подсказка **Прокси-сервер завершения работы TLS** одновременно может быть **балансировщиком нагрузки**. @@ -525,7 +525,7 @@ Traefik совместим с Docker, Kubernetes и им подобными ин Когда вы запускаете **множество контейнеров**, в каждом из которых работает **только один процесс** (например, в кластере **Kubernetes**), может возникнуть необходимость иметь **отдельный контейнер**, который осуществит **предварительные шаги перед запуском** остальных контейнеров (например, применяет миграции к базе данных). -/// info | "Информация" +/// info | Информация При использовании Kubernetes, это может быть Инициализирующий контейнер. @@ -545,7 +545,7 @@ Traefik совместим с Docker, Kubernetes и им подобными ин * tiangolo/uvicorn-gunicorn-fastapi. -/// warning | "Предупреждение" +/// warning | Предупреждение Скорее всего у вас **нет необходимости** в использовании этого образа или подобного ему и лучше создать свой образ с нуля как описано тут: [Создать Docker-образ для FastAPI](#docker-fastapi). @@ -557,7 +557,7 @@ Traefik совместим с Docker, Kubernetes и им подобными ин Он также поддерживает прохождение **Подготовительных шагов при запуске контейнеров** при помощи скрипта. -/// tip | "Подсказка" +/// tip | Подсказка Для просмотра всех возможных настроек перейдите на страницу этого Docker-образа: tiangolo/uvicorn-gunicorn-fastapi. @@ -689,7 +689,7 @@ CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] 11. Запустите `uvicorn`, указав ему использовать объект `app`, расположенный в `app.main`. -/// tip | "Подсказка" +/// tip | Подсказка Если ткнёте на кружок с плюсом, то увидите объяснения, что происходит в этой строке. diff --git a/docs/ru/docs/deployment/https.md b/docs/ru/docs/deployment/https.md index 3d487c465..85c4cce60 100644 --- a/docs/ru/docs/deployment/https.md +++ b/docs/ru/docs/deployment/https.md @@ -4,7 +4,7 @@ Но всё несколько сложнее. -/// tip | "Заметка" +/// tip | Заметка Если вы торопитесь или вам не интересно, можете перейти на следующую страницу этого пошагового руководства по размещению приложений на серверах с использованием различных технологий. @@ -78,7 +78,7 @@ Обычно эту запись достаточно указать один раз, при первоначальной настройке всего сервера. -/// tip | "Заметка" +/// tip | Заметка Уровни протоколов, работающих с именами доменов, намного ниже HTTPS, но об этом следует упомянуть здесь, так как всё зависит от доменов и IP-адресов. @@ -128,7 +128,7 @@ DNS-сервера присылают браузеру определённый Таким образом, **HTTPS** это тот же **HTTP**, но внутри **безопасного TLS-соединения** вместо чистого (незашифрованного) TCP-соединения. -/// tip | "Заметка" +/// tip | Заметка Обратите внимание, что шифрование происходит на **уровне TCP**, а не на более высоком уровне HTTP. diff --git a/docs/ru/docs/deployment/manually.md b/docs/ru/docs/deployment/manually.md index 78363cef8..9b1d32be8 100644 --- a/docs/ru/docs/deployment/manually.md +++ b/docs/ru/docs/deployment/manually.md @@ -39,7 +39,7 @@ $ pip install "uvicorn[standard]" -/// tip | "Подсказка" +/// tip | Подсказка С опцией `standard`, Uvicorn будет устанавливаться и использоваться с некоторыми дополнительными рекомендованными зависимостями. @@ -99,7 +99,7 @@ Running on 0.0.0.0:8080 over http (CTRL + C to quit) //// -/// warning | "Предупреждение" +/// warning | Предупреждение Не забудьте удалить опцию `--reload`, если ранее пользовались ею. diff --git a/docs/ru/docs/deployment/versions.md b/docs/ru/docs/deployment/versions.md index 17b6446d9..e8db30ce8 100644 --- a/docs/ru/docs/deployment/versions.md +++ b/docs/ru/docs/deployment/versions.md @@ -42,7 +42,7 @@ fastapi>=0.45.0,<0.46.0 FastAPI следует соглашению в том, что любые изменения "ПАТЧ"-версии предназначены для исправления багов и внесения обратно совместимых изменений. -/// tip | "Подсказка" +/// tip | Подсказка "ПАТЧ" - это последнее число. Например, в `0.2.3`, ПАТЧ-версия - это `3`. @@ -56,7 +56,7 @@ fastapi>=0.45.0,<0.46.0 Обратно несовместимые изменения и новые функции добавляются в "МИНОРНЫЕ" версии. -/// tip | "Подсказка" +/// tip | Подсказка "МИНОРНАЯ" версия - это число в середине. Например, в `0.2.3` МИНОРНАЯ версия - это `2`. diff --git a/docs/ru/docs/features.md b/docs/ru/docs/features.md index 31f245e7a..77d6b936a 100644 --- a/docs/ru/docs/features.md +++ b/docs/ru/docs/features.md @@ -66,7 +66,7 @@ second_user_data = { my_second_user: User = User(**second_user_data) ``` -/// info | "Информация" +/// info | Информация `**second_user_data` означает: diff --git a/docs/ru/docs/help-fastapi.md b/docs/ru/docs/help-fastapi.md index fa8200817..474b3d689 100644 --- a/docs/ru/docs/help-fastapi.md +++ b/docs/ru/docs/help-fastapi.md @@ -162,7 +162,7 @@ * Затем, используя **комментарий**, сообщите, что Вы сделали проверку, тогда я буду знать, что Вы действительно проверили код. -/// info | "Информация" +/// info | Информация К сожалению, я не могу так просто доверять пул-реквестам, у которых уже есть несколько одобрений. @@ -221,7 +221,7 @@ Подключайтесь к 👥 чату в Discord 👥 и общайтесь с другими участниками сообщества FastAPI. -/// tip | "Подсказка" +/// tip | Подсказка Вопросы по проблемам с фреймворком лучше задавать в GitHub issues, так больше шансов, что Вы получите помощь от [Экспертов FastAPI](fastapi-people.md#_3){.internal-link target=_blank}. diff --git a/docs/ru/docs/tutorial/background-tasks.md b/docs/ru/docs/tutorial/background-tasks.md index 0f6ce0eb3..a4f98f643 100644 --- a/docs/ru/docs/tutorial/background-tasks.md +++ b/docs/ru/docs/tutorial/background-tasks.md @@ -97,8 +97,6 @@ Их тяжелее настраивать, также им нужен брокер сообщений наподобие RabbitMQ или Redis, но зато они позволяют вам запускать фоновые задачи в нескольких процессах и даже на нескольких серверах. -Для примера, посмотрите [Project Generators](../project-generation.md){.internal-link target=_blank}, там есть проект с уже настроенным Celery. - Но если вам нужен доступ к общим переменным и объектам вашего **FastAPI** приложения или вам нужно выполнять простые фоновые задачи (наподобие отправки письма из примера) вы можете просто использовать `BackgroundTasks`. ## Резюме diff --git a/docs/ru/docs/tutorial/body-fields.md b/docs/ru/docs/tutorial/body-fields.md index f3b2c6113..0c4cbb09c 100644 --- a/docs/ru/docs/tutorial/body-fields.md +++ b/docs/ru/docs/tutorial/body-fields.md @@ -22,7 +22,7 @@ //// -/// warning | "Внимание" +/// warning | Внимание Обратите внимание, что функция `Field` импортируется непосредственно из `pydantic`, а не из `fastapi`, как все остальные функции (`Query`, `Path`, `Body` и т.д.). @@ -50,7 +50,7 @@ Функция `Field` работает так же, как `Query`, `Path` и `Body`, у неё такие же параметры и т.д. -/// note | "Технические детали" +/// note | Технические детали На самом деле, `Query`, `Path` и другие функции, которые вы увидите в дальнейшем, создают объекты подклассов общего класса `Param`, который сам по себе является подклассом `FieldInfo` из Pydantic. @@ -62,7 +62,7 @@ /// -/// tip | "Подсказка" +/// tip | Подсказка Обратите внимание, что каждый атрибут модели с типом, значением по умолчанию и `Field` имеет ту же структуру, что и параметр *функции обработки пути* с `Field` вместо `Path`, `Query` и `Body`. @@ -75,7 +75,7 @@ Вы узнаете больше о добавлении дополнительной информации позже в документации, когда будете изучать, как задавать примеры принимаемых данных. -/// warning | "Внимание" +/// warning | Внимание Дополнительные ключи, переданные в функцию `Field`, также будут присутствовать в сгенерированной OpenAPI схеме вашего приложения. Поскольку эти ключи не являются обязательной частью спецификации OpenAPI, некоторые инструменты OpenAPI, например, [валидатор OpenAPI](https://validator.swagger.io/), могут не работать с вашей сгенерированной схемой. diff --git a/docs/ru/docs/tutorial/body-multiple-params.md b/docs/ru/docs/tutorial/body-multiple-params.md index 53965f0ec..594e1dbca 100644 --- a/docs/ru/docs/tutorial/body-multiple-params.md +++ b/docs/ru/docs/tutorial/body-multiple-params.md @@ -34,7 +34,7 @@ //// tab | Python 3.10+ non-Annotated -/// tip | "Заметка" +/// tip | Заметка Рекомендуется использовать `Annotated` версию, если это возможно. @@ -48,7 +48,7 @@ //// tab | Python 3.8+ non-Annotated -/// tip | "Заметка" +/// tip | Заметка Рекомендуется использовать версию с `Annotated`, если это возможно. @@ -60,7 +60,7 @@ //// -/// note | "Заметка" +/// note | Заметка Заметьте, что в данном случае параметр `item`, который будет взят из тела запроса, необязателен. Так как было установлено значение `None` по умолчанию. @@ -116,7 +116,7 @@ } ``` -/// note | "Внимание" +/// note | Внимание Обратите внимание, что хотя параметр `item` был объявлен таким же способом, как и раньше, теперь предпологается, что он находится внутри тела с ключом `item`. @@ -162,7 +162,7 @@ //// tab | Python 3.10+ non-Annotated -/// tip | "Заметка" +/// tip | Заметка Рекомендуется использовать `Annotated` версию, если это возможно. @@ -176,7 +176,7 @@ //// tab | Python 3.8+ non-Annotated -/// tip | "Заметка" +/// tip | Заметка Рекомендуется использовать `Annotated` версию, если это возможно. @@ -252,7 +252,7 @@ q: str | None = None //// tab | Python 3.10+ non-Annotated -/// tip | "Заметка" +/// tip | Заметка Рекомендуется использовать `Annotated` версию, если это возможно. @@ -266,7 +266,7 @@ q: str | None = None //// tab | Python 3.8+ non-Annotated -/// tip | "Заметка" +/// tip | Заметка Рекомендуется использовать `Annotated` версию, если это возможно. @@ -278,7 +278,7 @@ q: str | None = None //// -/// info | "Информация" +/// info | Информация `Body` также имеет все те же дополнительные параметры валидации и метаданных, как у `Query`,`Path` и других, которые вы увидите позже. @@ -324,7 +324,7 @@ item: Item = Body(embed=True) //// tab | Python 3.10+ non-Annotated -/// tip | "Заметка" +/// tip | Заметка Рекомендуется использовать `Annotated` версию, если это возможно. @@ -338,7 +338,7 @@ item: Item = Body(embed=True) //// tab | Python 3.8+ non-Annotated -/// tip | "Заметка" +/// tip | Заметка Рекомендуется использовать `Annotated` версию, если это возможно. diff --git a/docs/ru/docs/tutorial/body-nested-models.md b/docs/ru/docs/tutorial/body-nested-models.md index 780946725..9abd4f432 100644 --- a/docs/ru/docs/tutorial/body-nested-models.md +++ b/docs/ru/docs/tutorial/body-nested-models.md @@ -304,7 +304,7 @@ my_list: List[str] } ``` -/// info | "Информация" +/// info | Информация Заметьте, что теперь у ключа `images` есть список объектов изображений. @@ -338,7 +338,7 @@ my_list: List[str] //// -/// info | "Информация" +/// info | Информация Заметьте, что у объекта `Offer` есть список объектов `Item`, которые, в свою очередь, могут содержать необязательный список объектов `Image` @@ -420,7 +420,7 @@ images: list[Image] //// -/// tip | "Совет" +/// tip | Совет Имейте в виду, что JSON поддерживает только ключи типа `str`. diff --git a/docs/ru/docs/tutorial/body-updates.md b/docs/ru/docs/tutorial/body-updates.md index 3ecfe52f4..c80952f70 100644 --- a/docs/ru/docs/tutorial/body-updates.md +++ b/docs/ru/docs/tutorial/body-updates.md @@ -54,7 +54,7 @@ Это означает, что можно передавать только те данные, которые необходимо обновить, оставляя остальные нетронутыми. -/// note | "Технические детали" +/// note | Технические детали `PATCH` менее распространен и известен, чем `PUT`. @@ -167,7 +167,7 @@ //// -/// tip | "Подсказка" +/// tip | Подсказка Эту же технику можно использовать и для операции HTTP `PUT`. @@ -175,7 +175,7 @@ /// -/// note | "Технические детали" +/// note | Технические детали Обратите внимание, что входная модель по-прежнему валидируется. diff --git a/docs/ru/docs/tutorial/body.md b/docs/ru/docs/tutorial/body.md index 91b169d07..62927f0d1 100644 --- a/docs/ru/docs/tutorial/body.md +++ b/docs/ru/docs/tutorial/body.md @@ -8,7 +8,7 @@ Чтобы объявить тело **запроса**, необходимо использовать модели Pydantic, со всей их мощью и преимуществами. -/// info | "Информация" +/// info | Информация Чтобы отправить данные, необходимо использовать один из методов: `POST` (обычно), `PUT`, `DELETE` или `PATCH`. @@ -113,7 +113,7 @@ -/// tip | "Подсказка" +/// tip | Подсказка Если вы используете PyCharm в качестве редактора, то вам стоит попробовать плагин Pydantic PyCharm Plugin. @@ -161,7 +161,7 @@ * Если аннотация типа параметра содержит **примитивный тип** (`int`, `float`, `str`, `bool` и т.п.), он будет интерпретирован как параметр **запроса**. * Если аннотация типа параметра представляет собой **модель Pydantic**, он будет интерпретирован как параметр **тела запроса**. -/// note | "Заметка" +/// note | Заметка FastAPI понимает, что значение параметра `q` не является обязательным, потому что имеет значение по умолчанию `= None`. diff --git a/docs/ru/docs/tutorial/cookie-params.md b/docs/ru/docs/tutorial/cookie-params.md index 2a73a5918..88533f7f8 100644 --- a/docs/ru/docs/tutorial/cookie-params.md +++ b/docs/ru/docs/tutorial/cookie-params.md @@ -44,7 +44,7 @@ //// -/// note | "Технические детали" +/// note | Технические детали `Cookie` - это класс, родственный `Path` и `Query`. Он также наследуется от общего класса `Param`. @@ -52,7 +52,7 @@ /// -/// info | "Дополнительная информация" +/// info | Дополнительная информация Для объявления cookies, вам нужно использовать `Cookie`, иначе параметры будут интерпретированы как параметры запроса. diff --git a/docs/ru/docs/tutorial/cors.md b/docs/ru/docs/tutorial/cors.md index 8d415a2c1..622cd5a98 100644 --- a/docs/ru/docs/tutorial/cors.md +++ b/docs/ru/docs/tutorial/cors.md @@ -78,7 +78,7 @@ Для получения более подробной информации о CORS, обратитесь к Документации CORS от Mozilla. -/// note | "Технические детали" +/// note | Технические детали Вы также можете использовать `from starlette.middleware.cors import CORSMiddleware`. diff --git a/docs/ru/docs/tutorial/debugging.md b/docs/ru/docs/tutorial/debugging.md index 606a32bfc..0feeaa20c 100644 --- a/docs/ru/docs/tutorial/debugging.md +++ b/docs/ru/docs/tutorial/debugging.md @@ -74,7 +74,7 @@ from myapp import app не будет выполнена. -/// info | "Информация" +/// info | Информация Для получения дополнительной информации, ознакомьтесь с официальной документацией Python. diff --git a/docs/ru/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/ru/docs/tutorial/dependencies/classes-as-dependencies.md index 161101bb3..486ff9ea9 100644 --- a/docs/ru/docs/tutorial/dependencies/classes-as-dependencies.md +++ b/docs/ru/docs/tutorial/dependencies/classes-as-dependencies.md @@ -32,7 +32,7 @@ //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -46,7 +46,7 @@ //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -143,7 +143,7 @@ fluffy = Cat(name="Mr Fluffy") //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -157,7 +157,7 @@ fluffy = Cat(name="Mr Fluffy") //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -197,7 +197,7 @@ fluffy = Cat(name="Mr Fluffy") //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -211,7 +211,7 @@ fluffy = Cat(name="Mr Fluffy") //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -251,7 +251,7 @@ fluffy = Cat(name="Mr Fluffy") //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -265,7 +265,7 @@ fluffy = Cat(name="Mr Fluffy") //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -317,7 +317,7 @@ fluffy = Cat(name="Mr Fluffy") //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -331,7 +331,7 @@ fluffy = Cat(name="Mr Fluffy") //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -351,7 +351,7 @@ fluffy = Cat(name="Mr Fluffy") //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -395,7 +395,7 @@ commons: Annotated[CommonQueryParams, ... //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -421,7 +421,7 @@ commons: Annotated[Any, Depends(CommonQueryParams)] //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -461,7 +461,7 @@ commons = Depends(CommonQueryParams) //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -475,7 +475,7 @@ commons = Depends(CommonQueryParams) //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -497,7 +497,7 @@ commons = Depends(CommonQueryParams) //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -532,7 +532,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -556,7 +556,7 @@ commons: Annotated[CommonQueryParams, Depends()] //// tab | Python 3.6 без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -598,7 +598,7 @@ commons: CommonQueryParams = Depends() //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -612,7 +612,7 @@ commons: CommonQueryParams = Depends() //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -626,7 +626,7 @@ commons: CommonQueryParams = Depends() ...и **FastAPI** будет знать, что делать. -/// tip | "Подсказка" +/// tip | Подсказка Если это покажется вам более запутанным, чем полезным, не обращайте внимания, это вам не *нужно*. diff --git a/docs/ru/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/ru/docs/tutorial/dependencies/dependencies-with-yield.md index 99a86e999..83f8ec0d2 100644 --- a/docs/ru/docs/tutorial/dependencies/dependencies-with-yield.md +++ b/docs/ru/docs/tutorial/dependencies/dependencies-with-yield.md @@ -4,13 +4,13 @@ FastAPI поддерживает зависимости, которые выпо Для этого используйте `yield` вместо `return`, а дополнительный код напишите после него. -/// tip | "Подсказка" +/// tip | Подсказка Обязательно используйте `yield` один-единственный раз. /// -/// note | "Технические детали" +/// note | Технические детали Любая функция, с которой может работать: @@ -45,7 +45,7 @@ FastAPI поддерживает зависимости, которые выпо {!../../docs_src/dependencies/tutorial007.py!} ``` -/// tip | "Подсказка" +/// tip | Подсказка Можно использовать как `async` так и обычные функции. @@ -93,7 +93,7 @@ FastAPI поддерживает зависимости, которые выпо //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -129,7 +129,7 @@ FastAPI поддерживает зависимости, которые выпо //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -149,7 +149,7 @@ FastAPI поддерживает зависимости, которые выпо **FastAPI** проследит за тем, чтобы все выполнялось в правильном порядке. -/// note | "Технические детали" +/// note | Технические детали Это работает благодаря Контекстным менеджерам в Python. @@ -177,7 +177,7 @@ FastAPI поддерживает зависимости, которые выпо Если у вас есть пользовательские исключения, которые вы хотите обрабатывать *до* возврата ответа и, возможно, модифицировать ответ, даже вызывая `HTTPException`, создайте [Cобственный обработчик исключений](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}. -/// tip | "Подсказка" +/// tip | Подсказка Вы все еще можете вызывать исключения, включая `HTTPException`, *до* `yield`. Но не после. @@ -225,7 +225,7 @@ participant tasks as Background tasks end ``` -/// info | "Дополнительная информация" +/// info | Дополнительная информация Клиенту будет отправлен только **один ответ**. Это может быть один из ответов об ошибке или это будет ответ от *операции пути*. @@ -233,7 +233,7 @@ participant tasks as Background tasks /// -/// tip | "Подсказка" +/// tip | Подсказка На этой диаграмме показано "HttpException", но вы также можете вызвать любое другое исключение, для которого вы создаете [Пользовательский обработчик исключений](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}. @@ -243,7 +243,7 @@ participant tasks as Background tasks ## Зависимости с `yield`, `HTTPException` и фоновыми задачами -/// warning | "Внимание" +/// warning | Внимание Скорее всего, вам не нужны эти технические подробности, вы можете пропустить этот раздел и продолжить ниже. @@ -257,7 +257,7 @@ participant tasks as Background tasks Тем не менее, поскольку это означало бы ожидание ответа в сети, а также ненужное удержание ресурса в зависимости от доходности (например, соединение с базой данных), это было изменено в FastAPI 0.106.0. -/// tip | "Подсказка" +/// tip | Подсказка Кроме того, фоновая задача обычно представляет собой независимый набор логики, который должен обрабатываться отдельно, со своими собственными ресурсами (например, собственным подключением к базе данных). Таким образом, вы, вероятно, получите более чистый код. @@ -290,7 +290,7 @@ with open("./somefile.txt") as f: ### Использование менеджеров контекста в зависимостях с помощью `yield` -/// warning | "Внимание" +/// warning | Внимание Это более или менее "продвинутая" идея. @@ -307,7 +307,7 @@ with open("./somefile.txt") as f: {!../../docs_src/dependencies/tutorial010.py!} ``` -/// tip | "Подсказка" +/// tip | Подсказка Другой способ создания контекстного менеджера - с помощью: diff --git a/docs/ru/docs/tutorial/dependencies/global-dependencies.md b/docs/ru/docs/tutorial/dependencies/global-dependencies.md index 7dbd50ae1..a4dfeb8ac 100644 --- a/docs/ru/docs/tutorial/dependencies/global-dependencies.md +++ b/docs/ru/docs/tutorial/dependencies/global-dependencies.md @@ -24,7 +24,7 @@ //// tab | Python 3.8 non-Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать 'Annotated' версию, если это возможно. diff --git a/docs/ru/docs/tutorial/dependencies/index.md b/docs/ru/docs/tutorial/dependencies/index.md index fcd9f46dc..b6cf7c780 100644 --- a/docs/ru/docs/tutorial/dependencies/index.md +++ b/docs/ru/docs/tutorial/dependencies/index.md @@ -55,7 +55,7 @@ //// tab | Python 3.10+ non-Annotated -/// tip | "Подсказка" +/// tip | Подсказка Настоятельно рекомендуем использовать `Annotated` версию насколько это возможно. @@ -69,7 +69,7 @@ //// tab | Python 3.8+ non-Annotated -/// tip | "Подсказка" +/// tip | Подсказка Настоятельно рекомендуем использовать `Annotated` версию насколько это возможно. @@ -99,7 +99,7 @@ И в конце она возвращает `dict`, содержащий эти значения. -/// info | "Информация" +/// info | Информация **FastAPI** добавил поддержку для `Annotated` (и начал её рекомендовать) в версии 0.95.0. @@ -137,7 +137,7 @@ //// tab | Python 3.10+ non-Annotated -/// tip | "Подсказка" +/// tip | Подсказка Настоятельно рекомендуем использовать `Annotated` версию насколько это возможно. @@ -151,7 +151,7 @@ //// tab | Python 3.8+ non-Annotated -/// tip | "Подсказка" +/// tip | Подсказка Настоятельно рекомендуем использовать `Annotated` версию насколько это возможно. @@ -193,7 +193,7 @@ //// tab | Python 3.10+ non-Annotated -/// tip | "Подсказка" +/// tip | Подсказка Настоятельно рекомендуем использовать `Annotated` версию насколько это возможно. @@ -207,7 +207,7 @@ //// tab | Python 3.8+ non-Annotated -/// tip | "Подсказка" +/// tip | Подсказка Настоятельно рекомендуем использовать `Annotated` версию насколько это возможно. @@ -225,7 +225,7 @@ И потом функция берёт параметры так же, как *функция обработки пути*. -/// tip | "Подсказка" +/// tip | Подсказка В следующей главе вы увидите, какие другие вещи, помимо функций, можно использовать в качестве зависимостей. @@ -250,7 +250,7 @@ common_parameters --> read_users Таким образом, вы пишете общий код один раз, и **FastAPI** позаботится о его вызове для ваших *операций с путями*. -/// check | "Проверка" +/// check | Проверка Обратите внимание, что вы не создаёте специальный класс и не передаёте его куда-то в **FastAPI** для регистрации, или что-то в этом роде. @@ -294,7 +294,7 @@ commons: Annotated[dict, Depends(common_parameters)] //// -/// tip | "Подсказка" +/// tip | Подсказка Это стандартный синтаксис python и называется "type alias", это не особенность **FastAPI**. @@ -316,7 +316,7 @@ commons: Annotated[dict, Depends(common_parameters)] Это всё не важно. **FastAPI** знает, что нужно сделать. 😎 -/// note | "Информация" +/// note | Информация Если вам эта тема не знакома, прочтите [Async: *"In a hurry?"*](../../async.md){.internal-link target=_blank} раздел о `async` и `await` в документации. diff --git a/docs/ru/docs/tutorial/dependencies/sub-dependencies.md b/docs/ru/docs/tutorial/dependencies/sub-dependencies.md index ae0fd0824..0e8cb20e7 100644 --- a/docs/ru/docs/tutorial/dependencies/sub-dependencies.md +++ b/docs/ru/docs/tutorial/dependencies/sub-dependencies.md @@ -36,7 +36,7 @@ //// tab | Python 3.10 без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -50,7 +50,7 @@ //// tab | Python 3.6 без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -96,7 +96,7 @@ //// tab | Python 3.10 без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -110,7 +110,7 @@ //// tab | Python 3.6 без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -159,7 +159,7 @@ //// tab | Python 3.10 без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -173,7 +173,7 @@ //// tab | Python 3.6 без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -185,7 +185,7 @@ //// -/// info | "Дополнительная информация" +/// info | Дополнительная информация Обратите внимание, что мы объявляем только одну зависимость в *функции операции пути* - `query_or_cookie_extractor`. @@ -223,7 +223,7 @@ async def needy_dependency(fresh_value: Annotated[str, Depends(get_value, use_ca //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -244,7 +244,7 @@ async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False Но, тем не менее, эта система очень мощная и позволяет вам объявлять вложенные графы (деревья) зависимостей сколь угодно глубоко. -/// tip | "Подсказка" +/// tip | Подсказка Все это может показаться не столь полезным на этих простых примерах. diff --git a/docs/ru/docs/tutorial/encoder.md b/docs/ru/docs/tutorial/encoder.md index c9900cb2c..523644ac8 100644 --- a/docs/ru/docs/tutorial/encoder.md +++ b/docs/ru/docs/tutorial/encoder.md @@ -42,7 +42,7 @@ Функция не возвращает большой `str`, содержащий данные в формате JSON (в виде строки). Она возвращает стандартную структуру данных Python (например, `dict`) со значениями и подзначениями, которые совместимы с JSON. -/// note | "Технические детали" +/// note | Технические детали `jsonable_encoder` фактически используется **FastAPI** внутри системы для преобразования данных. Однако он полезен и во многих других сценариях. diff --git a/docs/ru/docs/tutorial/extra-models.md b/docs/ru/docs/tutorial/extra-models.md index e7ff3f40f..241f70779 100644 --- a/docs/ru/docs/tutorial/extra-models.md +++ b/docs/ru/docs/tutorial/extra-models.md @@ -8,7 +8,7 @@ * **Модель для вывода** не должна содержать пароль. * **Модель для базы данных**, возможно, должна содержать хэшированный пароль. -/// danger | "Внимание" +/// danger | Внимание Никогда не храните пароли пользователей в чистом виде. Всегда храните "безопасный хэш", который вы затем сможете проверить. @@ -146,7 +146,7 @@ UserInDB( ) ``` -/// warning | "Предупреждение" +/// warning | Предупреждение Цель использованных в примере вспомогательных функций - не более чем демонстрация возможных операций с данными, но, конечно, они не обеспечивают настоящую безопасность. @@ -192,7 +192,7 @@ UserInDB( Для этого используйте стандартные аннотации типов в Python `typing.Union`: -/// note | "Примечание" +/// note | Примечание При объявлении `Union`, сначала указывайте наиболее детальные типы, затем менее детальные. В примере ниже более детальный `PlaneItem` стоит перед `CarItem` в `Union[PlaneItem, CarItem]`. diff --git a/docs/ru/docs/tutorial/first-steps.md b/docs/ru/docs/tutorial/first-steps.md index b1de217cd..309f26c4f 100644 --- a/docs/ru/docs/tutorial/first-steps.md +++ b/docs/ru/docs/tutorial/first-steps.md @@ -24,7 +24,7 @@ $ uvicorn main:app --reload -/// note | "Технические детали" +/// note | Технические детали Команда `uvicorn main:app` обращается к: @@ -139,7 +139,7 @@ OpenAPI описывает схему API. Эта схема содержит о `FastAPI` это класс в Python, который предоставляет всю функциональность для API. -/// note | "Технические детали" +/// note | Технические детали `FastAPI` это класс, который наследуется непосредственно от `Starlette`. @@ -205,7 +205,7 @@ https://example.com/items/foo /items/foo ``` -/// info | "Дополнительная иформация" +/// info | Дополнительная иформация Термин "path" также часто называется "endpoint" или "route". @@ -259,7 +259,7 @@ https://example.com/items/foo * путь `/` * использующих get операцию -/// info | "`@decorator` Дополнительная информация" +/// info | `@decorator` Дополнительная информация Синтаксис `@something` в Python называется "декоратор". @@ -286,7 +286,7 @@ https://example.com/items/foo * `@app.patch()` * `@app.trace()` -/// tip | "Подсказка" +/// tip | Подсказка Вы можете использовать каждую операцию (HTTP-метод) по своему усмотрению. @@ -324,7 +324,7 @@ https://example.com/items/foo {!../../docs_src/first_steps/tutorial003.py!} ``` -/// note | "Технические детали" +/// note | Технические детали Если не знаете в чём разница, посмотрите [Конкурентность: *"Нет времени?"*](../async.md#_1){.internal-link target=_blank}. diff --git a/docs/ru/docs/tutorial/handling-errors.md b/docs/ru/docs/tutorial/handling-errors.md index e7bfb85aa..a06644376 100644 --- a/docs/ru/docs/tutorial/handling-errors.md +++ b/docs/ru/docs/tutorial/handling-errors.md @@ -63,7 +63,7 @@ } ``` -/// tip | "Подсказка" +/// tip | Подсказка При вызове `HTTPException` в качестве параметра `detail` можно передавать любое значение, которое может быть преобразовано в JSON, а не только `str`. @@ -109,7 +109,7 @@ {"message": "Oops! yolo did something. There goes a rainbow..."} ``` -/// note | "Технические детали" +/// note | Технические детали Также можно использовать `from starlette.requests import Request` и `from starlette.responses import JSONResponse`. @@ -166,7 +166,7 @@ path -> item_id #### `RequestValidationError` или `ValidationError` -/// warning | "Внимание" +/// warning | Внимание Это технические детали, которые можно пропустить, если они не важны для вас сейчас. @@ -192,7 +192,7 @@ path -> item_id {!../../docs_src/handling_errors/tutorial004.py!} ``` -/// note | "Технические детали" +/// note | Технические детали Можно также использовать `from starlette.responses import PlainTextResponse`. diff --git a/docs/ru/docs/tutorial/header-params.md b/docs/ru/docs/tutorial/header-params.md index 18e1e60d0..904709b04 100644 --- a/docs/ru/docs/tutorial/header-params.md +++ b/docs/ru/docs/tutorial/header-params.md @@ -32,7 +32,7 @@ //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -46,7 +46,7 @@ //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -90,7 +90,7 @@ //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -104,7 +104,7 @@ //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -116,7 +116,7 @@ //// -/// note | "Технические детали" +/// note | Технические детали `Header` - это "родственный" класс `Path`, `Query` и `Cookie`. Он также наследуется от того же общего класса `Param`. @@ -124,7 +124,7 @@ /// -/// info | "Дополнительная информация" +/// info | Дополнительная информация Чтобы объявить заголовки, важно использовать `Header`, иначе параметры интерпретируются как query-параметры. @@ -172,7 +172,7 @@ //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -186,7 +186,7 @@ //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -198,7 +198,7 @@ //// -/// warning | "Внимание" +/// warning | Внимание Прежде чем установить для `convert_underscores` значение `False`, имейте в виду, что некоторые HTTP-прокси и серверы запрещают использование заголовков с подчеркиванием. @@ -240,7 +240,7 @@ //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -254,7 +254,7 @@ //// tab | Python 3.9+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -268,7 +268,7 @@ //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. diff --git a/docs/ru/docs/tutorial/index.md b/docs/ru/docs/tutorial/index.md index 4cf45c0ed..ddca2fbb1 100644 --- a/docs/ru/docs/tutorial/index.md +++ b/docs/ru/docs/tutorial/index.md @@ -52,7 +52,7 @@ $ pip install "fastapi[all]" ...это также включает `uvicorn`, который вы можете использовать в качестве сервера, который запускает ваш код. -/// note | "Технические детали" +/// note | Технические детали Вы также можете установить его по частям. diff --git a/docs/ru/docs/tutorial/metadata.md b/docs/ru/docs/tutorial/metadata.md index 246458f42..ae739a043 100644 --- a/docs/ru/docs/tutorial/metadata.md +++ b/docs/ru/docs/tutorial/metadata.md @@ -21,7 +21,7 @@ {!../../docs_src/metadata/tutorial001.py!} ``` -/// tip | "Подсказка" +/// tip | Подсказка Вы можете использовать Markdown в поле `description`, и оно будет отображено в выводе. @@ -57,7 +57,7 @@ Помните, что вы можете использовать Markdown внутри описания, к примеру "login" будет отображен жирным шрифтом (**login**) и "fancy" будет отображаться курсивом (_fancy_). -/// tip | "Подсказка" +/// tip | Подсказка Вам необязательно добавлять метаданные для всех используемых тегов @@ -70,7 +70,7 @@ {!../../docs_src/metadata/tutorial004.py!} ``` -/// info | "Дополнительная информация" +/// info | Дополнительная информация Узнайте больше о тегах в [Конфигурации операции пути](path-operation-configuration.md#_3){.internal-link target=_blank}. diff --git a/docs/ru/docs/tutorial/path-operation-configuration.md b/docs/ru/docs/tutorial/path-operation-configuration.md index 5f3855af2..ac12b7084 100644 --- a/docs/ru/docs/tutorial/path-operation-configuration.md +++ b/docs/ru/docs/tutorial/path-operation-configuration.md @@ -2,7 +2,7 @@ Существует несколько параметров, которые вы можете передать вашему *декоратору операций пути* для его настройки. -/// warning | "Внимание" +/// warning | Внимание Помните, что эти параметры передаются непосредственно *декоратору операций пути*, а не вашей *функции-обработчику операций пути*. @@ -42,7 +42,7 @@ Этот код состояния будет использован в ответе и будет добавлен в схему OpenAPI. -/// note | "Технические детали" +/// note | Технические детали Вы также можете использовать `from starlette import status`. @@ -184,13 +184,13 @@ //// -/// info | "Дополнительная информация" +/// info | Дополнительная информация Помните, что `response_description` относится конкретно к ответу, а `description` относится к *операции пути* в целом. /// -/// check | "Технические детали" +/// check | Технические детали OpenAPI указывает, что каждой *операции пути* необходимо описание ответа. diff --git a/docs/ru/docs/tutorial/path-params-numeric-validations.md b/docs/ru/docs/tutorial/path-params-numeric-validations.md index bf42ec725..ed19576a2 100644 --- a/docs/ru/docs/tutorial/path-params-numeric-validations.md +++ b/docs/ru/docs/tutorial/path-params-numeric-validations.md @@ -32,7 +32,7 @@ //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -46,7 +46,7 @@ //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -58,7 +58,7 @@ //// -/// info | "Информация" +/// info | Информация Поддержка `Annotated` была добавлена в FastAPI начиная с версии 0.95.0 (и с этой версии рекомендуется использовать этот подход). @@ -100,7 +100,7 @@ //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -114,7 +114,7 @@ //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -126,7 +126,7 @@ //// -/// note | "Примечание" +/// note | Примечание Path-параметр всегда является обязательным, поскольку он составляет часть пути. @@ -138,7 +138,7 @@ Path-параметр всегда является обязательным, п ## Задайте нужный вам порядок параметров -/// tip | "Подсказка" +/// tip | Подсказка Это не имеет большого значения, если вы используете `Annotated`. @@ -160,7 +160,7 @@ Path-параметр всегда является обязательным, п //// tab | Python 3.8 без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -192,7 +192,7 @@ Path-параметр всегда является обязательным, п ## Задайте нужный вам порядок параметров, полезные приёмы -/// tip | "Подсказка" +/// tip | Подсказка Это не имеет большого значения, если вы используете `Annotated`. @@ -261,7 +261,7 @@ Python не будет ничего делать с `*`, но он будет з //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -298,7 +298,7 @@ Python не будет ничего делать с `*`, но он будет з //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -338,7 +338,7 @@ Python не будет ничего делать с `*`, но он будет з //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -361,7 +361,7 @@ Python не будет ничего делать с `*`, но он будет з * `lt`: меньше (`l`ess `t`han) * `le`: меньше или равно (`l`ess than or `e`qual) -/// info | "Информация" +/// info | Информация `Query`, `Path` и другие классы, которые мы разберём позже, являются наследниками общего класса `Param`. @@ -369,7 +369,7 @@ Python не будет ничего делать с `*`, но он будет з /// -/// note | "Технические детали" +/// note | Технические детали `Query`, `Path` и другие "классы", которые вы импортируете из `fastapi`, на самом деле являются функциями, которые при вызове возвращают экземпляры одноимённых классов. diff --git a/docs/ru/docs/tutorial/path-params.md b/docs/ru/docs/tutorial/path-params.md index d1d76cf7b..ba23ba5ea 100644 --- a/docs/ru/docs/tutorial/path-params.md +++ b/docs/ru/docs/tutorial/path-params.md @@ -24,7 +24,7 @@ Здесь, `item_id` объявлен типом `int`. -/// check | "Заметка" +/// check | Заметка Это обеспечит поддержку редактора внутри функции (проверка ошибок, автодополнение и т.п.). @@ -38,7 +38,7 @@ {"item_id":3} ``` -/// check | "Заметка" +/// check | Заметка Обратите внимание на значение `3`, которое получила (и вернула) функция. Это целочисленный Python `int`, а не строка `"3"`. @@ -69,7 +69,7 @@ Та же ошибка возникнет, если вместо `int` передать `float` , например: http://127.0.0.1:8000/items/4.2 -/// check | "Заметка" +/// check | Заметка **FastAPI** обеспечивает проверку типов, используя всё те же определения типов. @@ -85,7 +85,7 @@ -/// check | "Заметка" +/// check | Заметка Ещё раз, просто используя определения типов, **FastAPI** обеспечивает автоматическую интерактивную документацию (с интеграцией Swagger UI). @@ -152,13 +152,13 @@ {!../../docs_src/path_params/tutorial005.py!} ``` -/// info | "Дополнительная информация" +/// info | Дополнительная информация Перечисления (enum) доступны в Python начиная с версии 3.4. /// -/// tip | "Подсказка" +/// tip | Подсказка Если интересно, то "AlexNet", "ResNet" и "LeNet" - это названия моделей машинного обучения. @@ -198,7 +198,7 @@ {!../../docs_src/path_params/tutorial005.py!} ``` -/// tip | "Подсказка" +/// tip | Подсказка Значение `"lenet"` также можно получить с помощью `ModelName.lenet.value`. @@ -254,7 +254,7 @@ OpenAPI не поддерживает способов объявления *п {!../../docs_src/path_params/tutorial004.py!} ``` -/// tip | "Подсказка" +/// tip | Подсказка Возможно, вам понадобится, чтобы параметр содержал `/home/johndoe/myfile.txt` с ведущим слэшем (`/`). diff --git a/docs/ru/docs/tutorial/query-params-str-validations.md b/docs/ru/docs/tutorial/query-params-str-validations.md index 0054af6ed..f76570ce8 100644 --- a/docs/ru/docs/tutorial/query-params-str-validations.md +++ b/docs/ru/docs/tutorial/query-params-str-validations.md @@ -22,7 +22,7 @@ Query-параметр `q` имеет тип `Union[str, None]` (или `str | None` в Python 3.10). Это означает, что входной параметр будет типа `str`, но может быть и `None`. Ещё параметр имеет значение по умолчанию `None`, из-за чего FastAPI определит параметр как необязательный. -/// note | "Технические детали" +/// note | Технические детали FastAPI определит параметр `q` как необязательный, потому что его значение по умолчанию `= None`. @@ -143,7 +143,7 @@ q: Annotated[Union[str, None]] = None В предыдущих версиях FastAPI (ниже 0.95.0) необходимо было использовать `Query` как значение по умолчанию для query-параметра. Так было вместо размещения его в `Annotated`, так что велика вероятность, что вам встретится такой код. Сейчас объясню. -/// tip | "Подсказка" +/// tip | Подсказка При написании нового кода и везде где это возможно, используйте `Annotated`, как было описано ранее. У этого способа есть несколько преимуществ (о них дальше) и никаких недостатков. 🍰 @@ -195,7 +195,7 @@ q: str | None = None Но он явно объявляет его как query-параметр. -/// info | "Дополнительная информация" +/// info | Дополнительная информация Запомните, важной частью объявления параметра как необязательного является: @@ -291,7 +291,7 @@ q: str = Query(default="rick") //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -305,7 +305,7 @@ q: str = Query(default="rick") //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -347,7 +347,7 @@ q: str = Query(default="rick") //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -361,7 +361,7 @@ q: str = Query(default="rick") //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -407,7 +407,7 @@ q: str = Query(default="rick") //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -419,7 +419,7 @@ q: str = Query(default="rick") //// -/// note | "Технические детали" +/// note | Технические детали Наличие значения по умолчанию делает параметр необязательным. @@ -477,7 +477,7 @@ q: Union[str, None] = Query(default=None, min_length=3) //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -487,7 +487,7 @@ q: Union[str, None] = Query(default=None, min_length=3) {!> ../../docs_src/query_params_str_validations/tutorial006.py!} ``` -/// tip | "Подсказка" +/// tip | Подсказка Обратите внимание, что даже когда `Query()` используется как значение по умолчанию для параметра функции, мы не передаём `default=None` в `Query()`. @@ -519,7 +519,7 @@ q: Union[str, None] = Query(default=None, min_length=3) //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -531,7 +531,7 @@ q: Union[str, None] = Query(default=None, min_length=3) //// -/// info | "Дополнительная информация" +/// info | Дополнительная информация Если вы ранее не сталкивались с `...`: это специальное значение, часть языка Python и называется "Ellipsis". @@ -573,7 +573,7 @@ q: Union[str, None] = Query(default=None, min_length=3) //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -587,7 +587,7 @@ q: Union[str, None] = Query(default=None, min_length=3) //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -599,7 +599,7 @@ q: Union[str, None] = Query(default=None, min_length=3) //// -/// tip | "Подсказка" +/// tip | Подсказка Pydantic, мощь которого используется в FastAPI для валидации и сериализации, имеет специальное поведение для `Optional` или `Union[Something, None]` без значения по умолчанию. Вы можете узнать об этом больше в документации Pydantic, раздел Обязательные Опциональные поля. @@ -627,7 +627,7 @@ Pydantic, мощь которого используется в FastAPI для //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -639,7 +639,7 @@ Pydantic, мощь которого используется в FastAPI для //// -/// tip | "Подсказка" +/// tip | Подсказка Запомните, когда вам необходимо объявить query-параметр обязательным, вы можете просто не указывать параметр `default`. Таким образом, вам редко придётся использовать `...` или `Required`. @@ -677,7 +677,7 @@ Pydantic, мощь которого используется в FastAPI для //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -691,7 +691,7 @@ Pydantic, мощь которого используется в FastAPI для //// tab | Python 3.9+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -705,7 +705,7 @@ Pydantic, мощь которого используется в FastAPI для //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -736,7 +736,7 @@ http://localhost:8000/items/?q=foo&q=bar } ``` -/// tip | "Подсказка" +/// tip | Подсказка Чтобы объявить query-параметр типом `list`, как в примере выше, вам нужно явно использовать `Query`, иначе он будет интерпретирован как тело запроса. @@ -768,7 +768,7 @@ http://localhost:8000/items/?q=foo&q=bar //// tab | Python 3.9+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -782,7 +782,7 @@ http://localhost:8000/items/?q=foo&q=bar //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -833,7 +833,7 @@ http://localhost:8000/items/ //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -845,7 +845,7 @@ http://localhost:8000/items/ //// -/// note | "Технические детали" +/// note | Технические детали Запомните, что в таком случае, FastAPI не будет проверять содержимое списка. @@ -859,7 +859,7 @@ http://localhost:8000/items/ Указанная информация будет включена в генерируемую OpenAPI документацию и использована в пользовательском интерфейсе и внешних инструментах. -/// note | "Технические детали" +/// note | Технические детали Имейте в виду, что разные инструменты могут иметь разные уровни поддержки OpenAPI. @@ -895,7 +895,7 @@ http://localhost:8000/items/ //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -909,7 +909,7 @@ http://localhost:8000/items/ //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -949,7 +949,7 @@ http://localhost:8000/items/ //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -963,7 +963,7 @@ http://localhost:8000/items/ //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -1019,7 +1019,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -1033,7 +1033,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -1079,7 +1079,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -1093,7 +1093,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -1139,7 +1139,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. @@ -1153,7 +1153,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать версию с `Annotated` если возможно. diff --git a/docs/ru/docs/tutorial/query-params.md b/docs/ru/docs/tutorial/query-params.md index edf06746b..2c697224c 100644 --- a/docs/ru/docs/tutorial/query-params.md +++ b/docs/ru/docs/tutorial/query-params.md @@ -81,7 +81,7 @@ http://127.0.0.1:8000/items/?skip=20 В этом случае, параметр `q` будет не обязательным и будет иметь значение `None` по умолчанию. -/// check | "Важно" +/// check | Важно Также обратите внимание, что **FastAPI** достаточно умён чтобы заметить, что параметр `item_id` является path-параметром, а `q` нет, поэтому, это параметр запроса. @@ -240,7 +240,7 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy * `skip`, типа `int` и со значением по умолчанию `0`. * `limit`, необязательный `int`. -/// tip | "Подсказка" +/// tip | Подсказка Вы можете использовать класс `Enum` также, как ранее применяли его с [Path-параметрами](path-params.md#_7){.internal-link target=_blank}. diff --git a/docs/ru/docs/tutorial/request-files.md b/docs/ru/docs/tutorial/request-files.md index 34b9c94fa..836d6efed 100644 --- a/docs/ru/docs/tutorial/request-files.md +++ b/docs/ru/docs/tutorial/request-files.md @@ -2,7 +2,7 @@ Используя класс `File`, мы можем позволить клиентам загружать файлы. -/// info | "Дополнительная информация" +/// info | Дополнительная информация Чтобы получать загруженные файлы, сначала установите `python-multipart`. @@ -34,7 +34,7 @@ //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -68,7 +68,7 @@ //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -80,7 +80,7 @@ //// -/// info | "Дополнительная информация" +/// info | Дополнительная информация `File` - это класс, который наследуется непосредственно от `Form`. @@ -88,7 +88,7 @@ /// -/// tip | "Подсказка" +/// tip | Подсказка Для объявления тела файла необходимо использовать `File`, поскольку в противном случае параметры будут интерпретироваться как параметры запроса или параметры тела (JSON). @@ -124,7 +124,7 @@ //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -177,13 +177,13 @@ contents = await myfile.read() contents = myfile.file.read() ``` -/// note | "Технические детали `async`" +/// note | Технические детали `async` При использовании методов `async` **FastAPI** запускает файловые методы в пуле потоков и ожидает их. /// -/// note | "Технические детали Starlette" +/// note | Технические детали Starlette **FastAPI** наследует `UploadFile` непосредственно из **Starlette**, но добавляет некоторые детали для совместимости с **Pydantic** и другими частями FastAPI. @@ -195,7 +195,7 @@ contents = myfile.file.read() **FastAPI** позаботится о том, чтобы считать эти данные из нужного места, а не из JSON. -/// note | "Технические детали" +/// note | Технические детали Данные из форм обычно кодируются с использованием "media type" `application/x-www-form-urlencoded` когда он не включает файлы. @@ -205,7 +205,7 @@ contents = myfile.file.read() /// -/// warning | "Внимание" +/// warning | Внимание В операции *функции операции пути* можно объявить несколько параметров `File` и `Form`, но нельзя также объявлять поля `Body`, которые предполагается получить в виде JSON, поскольку тело запроса будет закодировано с помощью `multipart/form-data`, а не `application/json`. @@ -243,7 +243,7 @@ contents = myfile.file.read() //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -257,7 +257,7 @@ contents = myfile.file.read() //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -291,7 +291,7 @@ contents = myfile.file.read() //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -329,7 +329,7 @@ contents = myfile.file.read() //// tab | Python 3.9+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -343,7 +343,7 @@ contents = myfile.file.read() //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -357,7 +357,7 @@ contents = myfile.file.read() Вы получите, как и было объявлено, список `list` из `bytes` или `UploadFile`. -/// note | "Technical Details" +/// note | Technical Details Можно также использовать `from starlette.responses import HTMLResponse`. @@ -387,7 +387,7 @@ contents = myfile.file.read() //// tab | Python 3.9+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -401,7 +401,7 @@ contents = myfile.file.read() //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. diff --git a/docs/ru/docs/tutorial/request-forms-and-files.md b/docs/ru/docs/tutorial/request-forms-and-files.md index 9b449bcd9..fd98ec953 100644 --- a/docs/ru/docs/tutorial/request-forms-and-files.md +++ b/docs/ru/docs/tutorial/request-forms-and-files.md @@ -2,7 +2,7 @@ Вы можете определять файлы и поля формы одновременно, используя `File` и `Form`. -/// info | "Дополнительная информация" +/// info | Дополнительная информация Чтобы получать загруженные файлы и/или данные форм, сначала установите `python-multipart`. @@ -30,7 +30,7 @@ //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -64,7 +64,7 @@ //// tab | Python 3.6+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -80,7 +80,7 @@ Вы можете объявить некоторые файлы как `bytes`, а некоторые - как `UploadFile`. -/// warning | "Внимание" +/// warning | Внимание Вы можете объявить несколько параметров `File` и `Form` в операции *path*, но вы не можете также объявить поля `Body`, которые вы ожидаете получить в виде JSON, так как запрос будет иметь тело, закодированное с помощью `multipart/form-data` вместо `application/json`. diff --git a/docs/ru/docs/tutorial/request-forms.md b/docs/ru/docs/tutorial/request-forms.md index 93b44437b..cd17613de 100644 --- a/docs/ru/docs/tutorial/request-forms.md +++ b/docs/ru/docs/tutorial/request-forms.md @@ -2,7 +2,7 @@ Когда вам нужно получить поля формы вместо JSON, вы можете использовать `Form`. -/// info | "Дополнительная информация" +/// info | Дополнительная информация Чтобы использовать формы, сначала установите `python-multipart`. @@ -32,7 +32,7 @@ //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать 'Annotated' версию, если это возможно. @@ -66,7 +66,7 @@ //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Рекомендуется использовать 'Annotated' версию, если это возможно. @@ -84,13 +84,13 @@ Вы можете настроить `Form` точно так же, как настраиваете и `Body` ( `Query`, `Path`, `Cookie`), включая валидации, примеры, псевдонимы (например, `user-name` вместо `username`) и т.д. -/// info | "Дополнительная информация" +/// info | Дополнительная информация `Form` - это класс, который наследуется непосредственно от `Body`. /// -/// tip | "Подсказка" +/// tip | Подсказка Вам необходимо явно указывать параметр `Form` при объявлении каждого поля, иначе поля будут интерпретироваться как параметры запроса или параметры тела (JSON). @@ -102,7 +102,7 @@ **FastAPI** гарантирует правильное чтение этих данных из соответствующего места, а не из JSON. -/// note | "Технические детали" +/// note | Технические детали Данные из форм обычно кодируются с использованием "типа медиа" `application/x-www-form-urlencoded`. @@ -112,7 +112,7 @@ /// -/// warning | "Предупреждение" +/// warning | Предупреждение Вы можете объявлять несколько параметров `Form` в *операции пути*, но вы не можете одновременно с этим объявлять поля `Body`, которые вы ожидаете получить в виде JSON, так как запрос будет иметь тело, закодированное с использованием `application/x-www-form-urlencoded`, а не `application/json`. diff --git a/docs/ru/docs/tutorial/response-model.md b/docs/ru/docs/tutorial/response-model.md index 363e64676..c55be38ef 100644 --- a/docs/ru/docs/tutorial/response-model.md +++ b/docs/ru/docs/tutorial/response-model.md @@ -83,7 +83,7 @@ FastAPI будет использовать этот возвращаемый т //// -/// note | "Технические детали" +/// note | Технические детали Помните, что параметр `response_model` является параметром именно декоратора http-методов (`get`, `post`, и т.п.). Не следует его указывать для *функций операций пути*, как вы бы поступили с другими параметрами или с телом запроса. @@ -93,7 +93,7 @@ FastAPI будет использовать этот возвращаемый т FastAPI будет использовать значение `response_model` для того, чтобы автоматически генерировать документацию, производить валидацию и т.п. А также для **конвертации и фильтрации выходных данных** в объявленный тип. -/// tip | "Подсказка" +/// tip | Подсказка Если вы используете анализаторы типов со строгой проверкой (например, mypy), можно указать `Any` в качестве типа возвращаемого значения функции. @@ -129,7 +129,7 @@ FastAPI будет использовать значение `response_model` д //// -/// info | "Информация" +/// info | Информация Чтобы использовать `EmailStr`, прежде необходимо установить `email-validator`. Используйте `pip install email-validator` @@ -161,7 +161,7 @@ FastAPI будет использовать значение `response_model` д Но что если мы захотим использовать эту модель для какой-либо другой *операции пути*? Мы можем, сами того не желая, отправить пароль любому другому пользователю. -/// danger | "Осторожно" +/// danger | Осторожно Никогда не храните пароли пользователей в открытом виде, а также никогда не возвращайте их в ответе, как в примере выше. В противном случае - убедитесь, что вы хорошо продумали и учли все возможные риски такого подхода и вам известно, что вы делаете. @@ -444,13 +444,13 @@ FastAPI совместно с Pydantic выполнит некоторую ма } ``` -/// info | "Информация" +/// info | Информация "Под капотом" FastAPI использует метод `.dict()` у объектов моделей Pydantic с параметром `exclude_unset`, чтобы достичь такого эффекта. /// -/// info | "Информация" +/// info | Информация Вы также можете использовать: @@ -494,7 +494,7 @@ FastAPI достаточно умен (на самом деле, это засл И поэтому, они также будут включены в JSON ответа. -/// tip | "Подсказка" +/// tip | Подсказка Значением по умолчанию может быть что угодно, не только `None`. @@ -510,7 +510,7 @@ FastAPI достаточно умен (на самом деле, это засл Это можно использовать как быстрый способ исключить данные из ответа, не создавая отдельную модель Pydantic. -/// tip | "Подсказка" +/// tip | Подсказка Но по-прежнему рекомендуется следовать изложенным выше советам и использовать несколько моделей вместо данных параметров. @@ -536,7 +536,7 @@ FastAPI достаточно умен (на самом деле, это засл //// -/// tip | "Подсказка" +/// tip | Подсказка При помощи кода `{"name","description"}` создается объект множества (`set`) с двумя строковыми значениями. diff --git a/docs/ru/docs/tutorial/response-status-code.md b/docs/ru/docs/tutorial/response-status-code.md index 48808bea7..f08b15379 100644 --- a/docs/ru/docs/tutorial/response-status-code.md +++ b/docs/ru/docs/tutorial/response-status-code.md @@ -12,7 +12,7 @@ {!../../docs_src/response_status_code/tutorial001.py!} ``` -/// note | "Примечание" +/// note | Примечание Обратите внимание, что `status_code` является атрибутом метода-декоратора (`get`, `post` и т.д.), а не *функции-обработчика пути* в отличие от всех остальных параметров и тела запроса. @@ -20,7 +20,7 @@ Параметр `status_code` принимает число, обозначающее HTTP код статуса ответа. -/// info | "Информация" +/// info | Информация В качестве значения параметра `status_code` также может использоваться `IntEnum`, например, из библиотеки `http.HTTPStatus` в Python. @@ -33,7 +33,7 @@ -/// note | "Примечание" +/// note | Примечание Некоторые коды статуса ответа (см. следующий раздел) указывают на то, что ответ не имеет тела. @@ -43,7 +43,7 @@ FastAPI знает об этом и создаст документацию Open ## Об HTTP кодах статуса ответа -/// note | "Примечание" +/// note | Примечание Если вы уже знаете, что представляют собой HTTP коды статуса ответа, можете перейти к следующему разделу. @@ -66,7 +66,7 @@ FastAPI знает об этом и создаст документацию Open * Для общих ошибок со стороны клиента можно просто использовать код `400`. * `5XX` – статус-коды, сообщающие о серверной ошибке. Они почти никогда не используются разработчиками напрямую. Когда что-то идет не так в какой-то части кода вашего приложения или на сервере, он автоматически вернёт один из 5XX кодов. -/// tip | "Подсказка" +/// tip | Подсказка Чтобы узнать больше о HTTP кодах статуса и о том, для чего каждый из них предназначен, ознакомьтесь с документацией MDN об HTTP кодах статуса ответа. @@ -94,7 +94,7 @@ FastAPI знает об этом и создаст документацию Open -/// note | "Технические детали" +/// note | Технические детали Вы также можете использовать `from starlette import status` вместо `from fastapi import status`. diff --git a/docs/ru/docs/tutorial/security/first-steps.md b/docs/ru/docs/tutorial/security/first-steps.md index c98ce2c60..484dfceff 100644 --- a/docs/ru/docs/tutorial/security/first-steps.md +++ b/docs/ru/docs/tutorial/security/first-steps.md @@ -38,7 +38,7 @@ //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -52,7 +52,7 @@ ## Запуск -/// info | "Дополнительная информация" +/// info | Дополнительная информация Вначале, установите библиотеку `python-multipart`. @@ -82,7 +82,7 @@ $ uvicorn main:app --reload -/// check | "Кнопка авторизации!" +/// check | Кнопка авторизации! У вас уже появилась новая кнопка "Authorize". @@ -94,7 +94,7 @@ $ uvicorn main:app --reload -/// note | "Технические детали" +/// note | Технические детали Неважно, что вы введете в форму, она пока не будет работать. Но мы к этому еще придем. @@ -140,7 +140,7 @@ OAuth2 был разработан для того, чтобы бэкэнд ил В данном примере мы будем использовать **OAuth2**, с аутентификацией по паролю, используя токен **Bearer**. Для этого мы используем класс `OAuth2PasswordBearer`. -/// info | "Дополнительная информация" +/// info | Дополнительная информация Токен "bearer" - не единственный вариант, но для нашего случая он является наилучшим. @@ -170,7 +170,7 @@ OAuth2 был разработан для того, чтобы бэкэнд ил //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -182,7 +182,7 @@ OAuth2 был разработан для того, чтобы бэкэнд ил //// -/// tip | "Подсказка" +/// tip | Подсказка Здесь `tokenUrl="token"` ссылается на относительный URL `token`, который мы еще не создали. Поскольку это относительный URL, он эквивалентен `./token`. @@ -196,7 +196,7 @@ OAuth2 был разработан для того, чтобы бэкэнд ил Вскоре мы создадим и саму операцию пути. -/// info | "Дополнительная информация" +/// info | Дополнительная информация Если вы очень строгий "питонист", то вам может не понравиться стиль названия параметра `tokenUrl` вместо `token_url`. @@ -236,7 +236,7 @@ oauth2_scheme(some, parameters) //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка Предпочтительнее использовать версию с аннотацией, если это возможно. @@ -252,7 +252,7 @@ oauth2_scheme(some, parameters) **FastAPI** будет знать, что он может использовать эту зависимость для определения "схемы безопасности" в схеме OpenAPI (и автоматической документации по API). -/// info | "Технические детали" +/// info | Технические детали **FastAPI** будет знать, что он может использовать класс `OAuth2PasswordBearer` (объявленный в зависимости) для определения схемы безопасности в OpenAPI, поскольку он наследуется от `fastapi.security.oauth2.OAuth2`, который, в свою очередь, наследуется от `fastapi.security.base.SecurityBase`. diff --git a/docs/ru/docs/tutorial/security/index.md b/docs/ru/docs/tutorial/security/index.md index bd512fde3..e4969c4cf 100644 --- a/docs/ru/docs/tutorial/security/index.md +++ b/docs/ru/docs/tutorial/security/index.md @@ -32,7 +32,7 @@ OAuth2 включает в себя способы аутентификации OAuth2 не указывает, как шифровать сообщение, он ожидает, что ваше приложение будет обслуживаться по протоколу HTTPS. -/// tip | "Подсказка" +/// tip | Подсказка В разделе **Развертывание** вы увидите [как настроить протокол HTTPS бесплатно, используя Traefik и Let's Encrypt.](https://fastapi.tiangolo.com/ru/deployment/https/) @@ -89,7 +89,7 @@ OpenAPI может использовать следующие схемы авт * Это автоматическое обнаружение определено в спецификации OpenID Connect. -/// tip | "Подсказка" +/// tip | Подсказка Интеграция сторонних сервисов для аутентификации/авторизации таких как Google, Facebook, Twitter, GitHub и т.д. осуществляется достаточно легко. diff --git a/docs/ru/docs/tutorial/static-files.md b/docs/ru/docs/tutorial/static-files.md index 4734554f3..0287fb017 100644 --- a/docs/ru/docs/tutorial/static-files.md +++ b/docs/ru/docs/tutorial/static-files.md @@ -11,7 +11,7 @@ {!../../docs_src/static_files/tutorial001.py!} ``` -/// note | "Технические детали" +/// note | Технические детали Вы также можете использовать `from starlette.staticfiles import StaticFiles`. diff --git a/docs/ru/docs/tutorial/testing.md b/docs/ru/docs/tutorial/testing.md index ae045bbbe..0485ef801 100644 --- a/docs/ru/docs/tutorial/testing.md +++ b/docs/ru/docs/tutorial/testing.md @@ -8,7 +8,7 @@ ## Использование класса `TestClient` -/// info | "Информация" +/// info | Информация Для использования класса `TestClient` необходимо установить библиотеку `httpx`. @@ -30,7 +30,7 @@ {!../../docs_src/app_testing/tutorial001.py!} ``` -/// tip | "Подсказка" +/// tip | Подсказка Обратите внимание, что тестирующая функция является обычной `def`, а не асинхронной `async def`. @@ -40,7 +40,7 @@ /// -/// note | "Технические детали" +/// note | Технические детали Также можно написать `from starlette.testclient import TestClient`. @@ -48,7 +48,7 @@ /// -/// tip | "Подсказка" +/// tip | Подсказка Если для тестирования Вам, помимо запросов к приложению FastAPI, необходимо вызывать асинхронные функции (например, для подключения к базе данных с помощью асинхронного драйвера), то ознакомьтесь со страницей [Асинхронное тестирование](../advanced/async-tests.md){.internal-link target=_blank} в расширенном руководстве. @@ -148,7 +148,7 @@ //// tab | Python 3.10+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка По возможности используйте версию с `Annotated`. @@ -162,7 +162,7 @@ //// tab | Python 3.8+ без Annotated -/// tip | "Подсказка" +/// tip | Подсказка По возможности используйте версию с `Annotated`. @@ -196,7 +196,7 @@ Для получения дополнительной информации о передаче данных на бэкенд с помощью `httpx` или `TestClient` ознакомьтесь с документацией HTTPX. -/// info | "Информация" +/// info | Информация Обратите внимание, что `TestClient` принимает данные, которые можно конвертировать в JSON, но не модели Pydantic. diff --git a/docs/tr/docs/advanced/index.md b/docs/tr/docs/advanced/index.md index 6c057162e..836e63c8a 100644 --- a/docs/tr/docs/advanced/index.md +++ b/docs/tr/docs/advanced/index.md @@ -6,7 +6,7 @@ İlerleyen bölümlerde diğer seçenekler, konfigürasyonlar ve ek özellikleri göreceğiz. -/// tip | "İpucu" +/// tip | İpucu Sonraki bölümler **mutlaka "gelişmiş" olmak zorunda değildir**. diff --git a/docs/tr/docs/advanced/security/index.md b/docs/tr/docs/advanced/security/index.md index 227674bd4..709f74c72 100644 --- a/docs/tr/docs/advanced/security/index.md +++ b/docs/tr/docs/advanced/security/index.md @@ -4,7 +4,7 @@ [Tutorial - User Guide: Security](../../tutorial/security/index.md){.internal-link target=_blank} sayfasında ele alınanların dışında güvenlikle ilgili bazı ek özellikler vardır. -/// tip | "İpucu" +/// tip | İpucu Sonraki bölümler **mutlaka "gelişmiş" olmak zorunda değildir**. diff --git a/docs/tr/docs/advanced/testing-websockets.md b/docs/tr/docs/advanced/testing-websockets.md index aa8a040d0..12b6ab60f 100644 --- a/docs/tr/docs/advanced/testing-websockets.md +++ b/docs/tr/docs/advanced/testing-websockets.md @@ -8,7 +8,7 @@ Bu işlem için, `TestClient`'ı bir `with` ifadesinde kullanarak WebSocket'e ba {!../../docs_src/app_testing/tutorial002.py!} ``` -/// note | "Not" +/// note | Not Daha fazla detay için Starlette'in Websockets'i Test Etmek dokümantasyonunu inceleyin. diff --git a/docs/tr/docs/alternatives.md b/docs/tr/docs/alternatives.md index 286b7897a..c98b966b5 100644 --- a/docs/tr/docs/alternatives.md +++ b/docs/tr/docs/alternatives.md @@ -30,13 +30,13 @@ Django REST framework'ü, Django'nun API kabiliyetlerini arttırmak için arka p **Otomatik API dökümantasyonu**nun ilk örneklerinden biri olduğu için, **FastAPI** arayışına ilham veren ilk fikirlerden biri oldu. -/// note | "Not" +/// note | Not Django REST Framework'ü, aynı zamanda **FastAPI**'ın dayandığı Starlette ve Uvicorn'un da yaratıcısı olan Tom Christie tarafından geliştirildi. /// -/// check | "**FastAPI**'a nasıl ilham verdi?" +/// check | **FastAPI**'a nasıl ilham verdi? Kullanıcılar için otomatik API dökümantasyonu sunan bir web arayüzüne sahip olmalı. @@ -56,7 +56,7 @@ Uygulama parçalarının böyle ayrılıyor oluşu ve istenilen özelliklerle ge Flask'ın basitliği göz önünde bulundurulduğu zaman, API geliştirmek için iyi bir seçim gibi görünüyordu. Sıradaki şey ise Flask için bir "Django REST Framework"! -/// check | "**FastAPI**'a nasıl ilham verdi?" +/// check | **FastAPI**'a nasıl ilham verdi? Gereken araçları ve parçaları birleştirip eşleştirmeyi kolaylaştıracak bir mikro framework olmalı. @@ -98,7 +98,7 @@ def read_url(): `requests.get(...)` ile `@app.get(...)` arasındaki benzerliklere bakın. -/// check | "**FastAPI**'a nasıl ilham verdi?" +/// check | **FastAPI**'a nasıl ilham verdi? * Basit ve sezgisel bir API'ya sahip olmalı. * HTTP metot isimlerini (işlemlerini) anlaşılır olacak bir şekilde, direkt kullanmalı. @@ -118,7 +118,7 @@ Swagger bir noktada Linux Foundation'a verildi ve adı OpenAPI olarak değiştir İşte bu yüzden versiyon 2.0 hakkında konuşurken "Swagger", versiyon 3 ve üzeri için ise "OpenAPI" adını kullanmak daha yaygın. -/// check | "**FastAPI**'a nasıl ilham verdi?" +/// check | **FastAPI**'a nasıl ilham verdi? API spesifikasyonları için özel bir şema yerine bir açık standart benimseyip kullanmalı. @@ -147,7 +147,7 @@ Marshmallow bu özellikleri sağlamak için geliştirilmişti. Benim de geçmiş Ama... Python'un tip belirteçleri gelmeden önce oluşturulmuştu. Yani her şemayı tanımlamak için Marshmallow'un sunduğu spesifik araçları ve sınıfları kullanmanız gerekiyordu. -/// check | "**FastAPI**'a nasıl ilham verdi?" +/// check | **FastAPI**'a nasıl ilham verdi? Kod kullanarak otomatik olarak veri tipini ve veri doğrulamayı belirten "şemalar" tanımlamalı. @@ -163,13 +163,13 @@ Veri doğrulama için arka planda Marshmallow kullanıyor, hatta aynı geliştir Webargs da harika bir araç ve onu da geçmişte henüz **FastAPI** yokken çok kullandım. -/// info | "Bilgi" +/// info | Bilgi Webargs aynı Marshmallow geliştirileri tarafından oluşturuldu. /// -/// check | "**FastAPI**'a nasıl ilham verdi?" +/// check | **FastAPI**'a nasıl ilham verdi? Gelen istek verisi için otomatik veri doğrulamaya sahip olmalı. @@ -191,13 +191,13 @@ Fakat sonrasında yine mikro sözdizimi problemiyle karşılaşıyoruz. Python m Editör bu konuda pek yardımcı olamaz. Üstelik eğer parametreleri ya da Marshmallow şemalarını değiştirip YAML kodunu güncellemeyi unutursak artık döküman geçerliliğini yitiriyor. -/// info | "Bilgi" +/// info | Bilgi APISpec de aynı Marshmallow geliştiricileri tarafından oluşturuldu. /// -/// check | "**FastAPI**'a nasıl ilham verdi?" +/// check | **FastAPI**'a nasıl ilham verdi? API'lar için açık standart desteği olmalı (OpenAPI gibi). @@ -223,13 +223,13 @@ Bunu kullanmak, bir kaç `uvloop` kullanıldı. Hızının asıl kaynağı buydu. @@ -269,7 +269,7 @@ Uvicorn ve Starlette'e ilham kaynağı olduğu oldukça açık, şu anda ikisi d /// -/// check | "**FastAPI**'a nasıl ilham oldu?" +/// check | **FastAPI**'a nasıl ilham oldu? Uçuk performans sağlayacak bir yol bulmalı. @@ -285,7 +285,7 @@ Falcon ise bir diğer yüksek performanslı Python framework'ü. Minimal olacak Yani veri doğrulama, veri dönüştürme ve dökümantasyonun hepsi kodda yer almalı, otomatik halledemiyoruz. Ya da Falcon üzerine bir framework olarak uygulanmaları gerekiyor, aynı Hug'da olduğu gibi. Bu ayrım Falcon'un tasarımından esinlenen, istek ve cevap objelerini parametre olarak işleyen diğer kütüphanelerde de yer alıyor. -/// check | "**FastAPI**'a nasıl ilham oldu?" +/// check | **FastAPI**'a nasıl ilham oldu? Harika bir performans'a sahip olmanın yollarını bulmalı. @@ -311,7 +311,7 @@ Biraz daha detaylı ayarlamalara gerek duyuyor. Ayrıca Yol'lar fonksiyonun üstünde endpoint'i işleyen dekoratörler yerine farklı yerlerde tanımlanan fonksiyonlarla belirlenir. Bu Flask (ve Starlette) yerine daha çok Django'nun yaklaşımına daha yakın bir metot. Bu, kodda nispeten birbiriyle sıkı ilişkili olan şeyleri ayırmaya sebep oluyor. -/// check | "**FastAPI**'a nasıl ilham oldu?" +/// check | **FastAPI**'a nasıl ilham oldu? Model özelliklerinin "standart" değerlerini kullanarak veri tipleri için ekstra veri doğrulama koşulları tanımlamalı. Bu editör desteğini geliştiriyor ve daha önceden Pydantic'te yoktu. @@ -333,13 +333,13 @@ Ayrıca ilginç ve çok rastlanmayan bir özelliği vardı: aynı framework'ü k Senkron çalışan Python web framework'lerinin standardına (WSGI) dayandığından dolayı Websocket'leri ve diğer şeyleri işleyemiyor, ancak yine de yüksek performansa sahip. -/// info | "Bilgi" +/// info | Bilgi Hug, Python dosyalarında bulunan dahil etme satırlarını otomatik olarak sıralayan harika bir araç olan `isort`'un geliştiricisi Timothy Crosley tarafından geliştirildi. /// -/// check | "**FastAPI**'a nasıl ilham oldu?" +/// check | **FastAPI**'a nasıl ilham oldu? Hug, APIStar'ın çeşitli kısımlarında esin kaynağı oldu ve APIStar'la birlikte en umut verici bulduğum araçlardan biriydi. @@ -373,7 +373,7 @@ Geliştiricinin Starlette'e odaklanması gerekince proje de artık bir API web f Artık APIStar, OpenAPI özelliklerini doğrulamak için bir dizi araç sunan bir proje haline geldi. -/// info | "Bilgi" +/// info | Bilgi APIStar, aşağıdaki projeleri de üreten Tom Christie tarafından geliştirildi: @@ -383,7 +383,7 @@ APIStar, aşağıdaki projeleri de üreten Tom Christie tarafından geliştirild /// -/// check | "**FastAPI**'a nasıl ilham oldu?" +/// check | **FastAPI**'a nasıl ilham oldu? Var oldu. @@ -407,7 +407,7 @@ Tip belirteçleri kullanıyor olması onu aşırı sezgisel yapıyor. Marshmallow ile karşılaştırılabilir. Ancak karşılaştırmalarda Marshmallowdan daha hızlı görünüyor. Aynı Python tip belirteçlerine dayanıyor ve editör desteği de harika. -/// check | "**FastAPI** nerede kullanıyor?" +/// check | **FastAPI** nerede kullanıyor? Bütün veri doğrulama, veri dönüştürme ve JSON Şemasına bağlı otomatik model dökümantasyonunu halletmek için! @@ -442,7 +442,7 @@ Ancak otomatik veri doğrulama, veri dönüştürme ve dökümantasyon sağlamyo Bu, **FastAPI**'ın onun üzerine tamamen Python tip belirteçlerine bağlı olarak eklediği (Pydantic ile) ana şeylerden biri. **FastAPI** bunun yanında artı olarak bağımlılık enjeksiyonu sistemi, güvenlik araçları, OpenAPI şema üretimi ve benzeri özellikler de ekliyor. -/// note | "Teknik Detaylar" +/// note | Teknik Detaylar ASGI, Django'nun ana ekibi tarafından geliştirilen yeni bir "standart". Bir "Python standardı" (PEP) olma sürecinde fakat henüz bir standart değil. @@ -450,7 +450,7 @@ Bununla birlikte, halihazırda birçok araç tarafından bir "standart" olarak k /// -/// check | "**FastAPI** nerede kullanıyor?" +/// check | **FastAPI** nerede kullanıyor? Tüm temel web kısımlarında üzerine özellikler eklenerek kullanılmakta. @@ -468,7 +468,7 @@ Bir web framework'ünden ziyade bir sunucudur, yani yollara bağlı yönlendirme Starlette ve **FastAPI** için tavsiye edilen sunucu Uvicorndur. -/// check | "**FastAPI** neden tavsiye ediyor?" +/// check | **FastAPI** neden tavsiye ediyor? **FastAPI** uygulamalarını çalıştırmak için ana web sunucusu Uvicorn! diff --git a/docs/tr/docs/async.md b/docs/tr/docs/async.md index 0d463a2f0..558a79cb7 100644 --- a/docs/tr/docs/async.md +++ b/docs/tr/docs/async.md @@ -21,7 +21,7 @@ async def read_results(): return results ``` -/// note | "Not" +/// note | Not Sadece `async def` ile tanımlanan fonksiyonlar içinde `await` kullanabilirsiniz. diff --git a/docs/tr/docs/how-to/index.md b/docs/tr/docs/how-to/index.md index 798adca61..26dd9026c 100644 --- a/docs/tr/docs/how-to/index.md +++ b/docs/tr/docs/how-to/index.md @@ -6,7 +6,7 @@ Bu fikirlerin büyük bir kısmı aşağı yukarı **bağımsız** olacaktır, Projeniz için ilginç ve yararlı görünen bir şey varsa devam edin ve inceleyin, aksi halde bunları atlayabilirsiniz. -/// tip | "İpucu" +/// tip | İpucu **FastAPI**'ı düzgün (ve önerilen) şekilde öğrenmek istiyorsanız [Öğretici - Kullanıcı Rehberi](../tutorial/index.md){.internal-link target=_blank}'ni bölüm bölüm okuyun. diff --git a/docs/tr/docs/python-types.md b/docs/tr/docs/python-types.md index 9584a5732..308dfa6fb 100644 --- a/docs/tr/docs/python-types.md +++ b/docs/tr/docs/python-types.md @@ -12,7 +12,7 @@ Bu pythonda tip belirteçleri için **hızlı bir başlangıç / bilgi tazeleme **FastAPI** kullanmayacak olsanız bile tür belirteçleri hakkında bilgi edinmenizde fayda var. -/// note | "Not" +/// note | Not Python uzmanıysanız ve tip belirteçleri ilgili her şeyi zaten biliyorsanız, sonraki bölüme geçin. @@ -175,7 +175,7 @@ Liste, bazı dahili tipleri içeren bir tür olduğundan, bunları köşeli para {!../../docs_src/python_types/tutorial006.py!} ``` -/// tip | "Ipucu" +/// tip | Ipucu Köşeli parantez içindeki bu dahili tiplere "tip parametreleri" denir. diff --git a/docs/tr/docs/tutorial/cookie-params.md b/docs/tr/docs/tutorial/cookie-params.md index 895cf9b03..56bcc0c86 100644 --- a/docs/tr/docs/tutorial/cookie-params.md +++ b/docs/tr/docs/tutorial/cookie-params.md @@ -32,7 +32,7 @@ //// tab | Python 3.10+ non-Annotated -/// tip | "İpucu" +/// tip | İpucu Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın. @@ -46,7 +46,7 @@ Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın. //// tab | Python 3.8+ non-Annotated -/// tip | "İpucu" +/// tip | İpucu Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın. @@ -90,7 +90,7 @@ Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın. //// tab | Python 3.10+ non-Annotated -/// tip | "İpucu" +/// tip | İpucu Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın. @@ -104,7 +104,7 @@ Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın. //// tab | Python 3.8+ non-Annotated -/// tip | "İpucu" +/// tip | İpucu Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın. @@ -116,7 +116,7 @@ Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın. //// -/// note | "Teknik Detaylar" +/// note | Teknik Detaylar `Cookie` sınıfı `Path` ve `Query` sınıflarının kardeşidir. Diğerleri gibi `Param` sınıfını miras alan bir sınıftır. @@ -124,7 +124,7 @@ Ancak `fastapi`'dan projenize dahil ettiğiniz `Query`, `Path`, `Cookie` ve diğ /// -/// info | "Bilgi" +/// info | Bilgi Çerez tanımlamak için `Cookie` sınıfını kullanmanız gerekmektedir, aksi taktirde parametreler sorgu parametreleri olarak yorumlanır. diff --git a/docs/tr/docs/tutorial/first-steps.md b/docs/tr/docs/tutorial/first-steps.md index 335fcaece..da9057204 100644 --- a/docs/tr/docs/tutorial/first-steps.md +++ b/docs/tr/docs/tutorial/first-steps.md @@ -24,7 +24,7 @@ $ uvicorn main:app --reload -/// note | "Not" +/// note | Not `uvicorn main:app` komutunu şu şekilde açıklayabiliriz: @@ -139,7 +139,7 @@ Ayrıca, API'ınızla iletişim kuracak önyüz, mobil veya IoT uygulamaları gi `FastAPI`, API'niz için tüm işlevselliği sağlayan bir Python sınıfıdır. -/// note | "Teknik Detaylar" +/// note | Teknik Detaylar `FastAPI` doğrudan `Starlette`'i miras alan bir sınıftır. @@ -205,7 +205,7 @@ https://example.com/items/foo /items/foo ``` -/// info | "Bilgi" +/// info | Bilgi "Yol" genellikle "endpoint" veya "route" olarak adlandırılır. @@ -259,7 +259,7 @@ Biz de onları "**operasyonlar**" olarak adlandıracağız. * get operasyonu ile * `/` yoluna gelen istekler -/// info | "`@decorator` Bilgisi" +/// info | `@decorator` Bilgisi Python'da `@something` sözdizimi "dekoratör" olarak adlandırılır. @@ -286,7 +286,7 @@ Daha az kullanılanları da kullanabilirsiniz: * `@app.patch()` * `@app.trace()` -/// tip | "İpucu" +/// tip | İpucu Her işlemi (HTTP metod) istediğiniz gibi kullanmakta özgürsünüz. @@ -324,7 +324,7 @@ Bu fonksiyonu `async def` yerine normal bir fonksiyon olarak da tanımlayabilirs {!../../docs_src/first_steps/tutorial003.py!} ``` -/// note | "Not" +/// note | Not Eğer farkı bilmiyorsanız, [Async: *"Aceleniz mi var?"*](../async.md#in-a-hurry){.internal-link target=_blank} sayfasını kontrol edebilirsiniz. diff --git a/docs/tr/docs/tutorial/path-params.md b/docs/tr/docs/tutorial/path-params.md index 9017d99ab..c883c2f9f 100644 --- a/docs/tr/docs/tutorial/path-params.md +++ b/docs/tr/docs/tutorial/path-params.md @@ -24,7 +24,7 @@ Standart Python tip belirteçlerini kullanarak yol parametresinin tipini fonksiy Bu durumda, `item_id` bir `int` olarak tanımlanacaktır. -/// check | "Ek bilgi" +/// check | Ek bilgi Bu sayede, fonksiyon içerisinde hata denetimi, kod tamamlama gibi konularda editör desteğine kavuşacaksınız. @@ -38,7 +38,7 @@ Eğer bu örneği çalıştırıp tarayıcınızda http://127.0.0.1:8000/items/4.2 sayfasında olduğu gibi `int` yerine `float` bir değer verseydik de ortaya çıkardı. -/// check | "Ek bilgi" +/// check | Ek bilgi Böylece, aynı Python tip tanımlaması ile birlikte, **FastAPI** veri doğrulama özelliği sağlar. @@ -87,7 +87,7 @@ Ayrıca, tarayıcınızı -/// check | "Ek bilgi" +/// check | Ek bilgi Üstelik, sadece aynı Python tip tanımlaması ile, **FastAPI** size otomatik ve interaktif (Swagger UI ile entegre) bir dokümantasyon sağlar. @@ -153,13 +153,13 @@ Sonrasında, sınıf içerisinde, mevcut ve geçerli değerler olacak olan sabit {!../../docs_src/path_params/tutorial005.py!} ``` -/// info | "Bilgi" +/// info | Bilgi 3.4 sürümünden beri enumerationlar (ya da enumlar) Python'da mevcuttur. /// -/// tip | "İpucu" +/// tip | İpucu Merak ediyorsanız söyleyeyim, "AlexNet", "ResNet" ve "LeNet" isimleri Makine Öğrenmesi modellerini temsil eder. @@ -199,7 +199,7 @@ Parametreyi, yarattığınız enum olan `ModelName` içerisindeki *enumeration {!../../docs_src/path_params/tutorial005.py!} ``` -/// tip | "İpucu" +/// tip | İpucu `"lenet"` değerine `ModelName.lenet.value` tanımı ile de ulaşabilirsiniz. @@ -256,7 +256,7 @@ Böylece şunun gibi bir kullanım yapabilirsiniz: {!../../docs_src/path_params/tutorial004.py!} ``` -/// tip | "İpucu" +/// tip | İpucu Parametrenin başında `/home/johndoe/myfile.txt` yolunda olduğu gibi (`/`) işareti ile birlikte kullanmanız gerektiği durumlar olabilir. diff --git a/docs/tr/docs/tutorial/query-params.md b/docs/tr/docs/tutorial/query-params.md index 886f5783f..b31d13be4 100644 --- a/docs/tr/docs/tutorial/query-params.md +++ b/docs/tr/docs/tutorial/query-params.md @@ -81,7 +81,7 @@ Aynı şekilde, varsayılan değerlerini `None` olarak atayarak isteğe bağlı Bu durumda, `q` fonksiyon parametresi isteğe bağlı olacak ve varsayılan değer olarak `None` alacaktır. -/// check | "Ek bilgi" +/// check | Ek bilgi Ayrıca, dikkatinizi çekerim ki; **FastAPI**, `item_id` parametresinin bir yol parametresi olduğunu ve `q` parametresinin yol değil bir sorgu parametresi olduğunu fark edecek kadar beceriklidir. @@ -242,7 +242,7 @@ Bu durumda, 3 tane sorgu parametresi var olacaktır: * `skip`, varsayılan değeri `0` olan bir `int`. * `limit`, isteğe bağlı bir `int`. -/// tip | "İpucu" +/// tip | İpucu Ayrıca, [Yol Parametrelerinde](path-params.md#on-tanml-degerler){.internal-link target=_blank} de kullanıldığı şekilde `Enum` sınıfından faydalanabilirsiniz. diff --git a/docs/tr/docs/tutorial/request-forms.md b/docs/tr/docs/tutorial/request-forms.md index 19b6150ff..4ed8ac021 100644 --- a/docs/tr/docs/tutorial/request-forms.md +++ b/docs/tr/docs/tutorial/request-forms.md @@ -2,7 +2,7 @@ İstek gövdesinde JSON verisi yerine form alanlarını karşılamanız gerketiğinde `Form` sınıfını kullanabilirsiniz. -/// info | "Bilgi" +/// info | Bilgi Formları kullanmak için öncelikle `python-multipart` paketini indirmeniz gerekmektedir. @@ -84,13 +84,13 @@ Bu spesifikasyon form alanlar `Form` sınıfıyla tanımlama yaparken `Body`, `Query`, `Path` ve `Cookie` sınıflarında kullandığınız aynı validasyon, örnekler, isimlendirme (örneğin `username` yerine `user-name` kullanımı) ve daha fazla konfigurasyonu kullanabilirsiniz. -/// info | "Bilgi" +/// info | Bilgi `Form` doğrudan `Body` sınıfını miras alan bir sınıftır. /// -/// tip | "İpucu" +/// tip | İpucu Form gövdelerini tanımlamak için `Form` sınıfını kullanmanız gerekir; çünkü bu olmadan parametreler sorgu parametreleri veya gövde (JSON) parametreleri olarak yorumlanır. @@ -102,7 +102,7 @@ HTML formlarının (`
`) verileri sunucuya gönderirken JSON'dan far **FastAPI** bu verilerin JSON yerine doğru şekilde okunmasını sağlayacaktır. -/// note | "Teknik Detaylar" +/// note | Teknik Detaylar Form verileri normalde `application/x-www-form-urlencoded` medya tipiyle kodlanır. @@ -112,7 +112,7 @@ Form kodlama türleri ve form alanları hakkında daha fazla bilgi edinmek istiy /// -/// warning | "Uyarı" +/// warning | Uyarı *Yol operasyonları* içerisinde birden fazla `Form` parametresi tanımlayabilirsiniz ancak bunlarla birlikte JSON verisi kabul eden `Body` alanları tanımlayamazsınız çünkü bu durumda istek gövdesi `application/json` yerine `application/x-www-form-urlencoded` ile kodlanmış olur. diff --git a/docs/tr/docs/tutorial/static-files.md b/docs/tr/docs/tutorial/static-files.md index 8bff59744..da8bed86a 100644 --- a/docs/tr/docs/tutorial/static-files.md +++ b/docs/tr/docs/tutorial/static-files.md @@ -11,7 +11,7 @@ {!../../docs_src/static_files/tutorial001.py!} ``` -/// note | "Teknik Detaylar" +/// note | Teknik Detaylar Projenize dahil etmek için `from starlette.staticfiles import StaticFiles` kullanabilirsiniz. diff --git a/docs/uk/docs/alternatives.md b/docs/uk/docs/alternatives.md index 6821ffe70..1acbe237a 100644 --- a/docs/uk/docs/alternatives.md +++ b/docs/uk/docs/alternatives.md @@ -30,13 +30,13 @@ Це був один із перших прикладів **автоматичної документації API**, і саме це була одна з перших ідей, яка надихнула на «пошук» **FastAPI**. -/// note | "Примітка" +/// note | Примітка Django REST Framework створив Том Крісті. Той самий творець Starlette і Uvicorn, на яких базується **FastAPI**. /// -/// check | "Надихнуло **FastAPI** на" +/// check | Надихнуло **FastAPI** на Мати автоматичний веб-інтерфейс документації API. @@ -56,7 +56,7 @@ Flask — це «мікрофреймворк», він не включає ін Враховуючи простоту Flask, він здавався хорошим підходом для створення API. Наступним, що знайшов, був «Django REST Framework» для Flask. -/// check | "Надихнуло **FastAPI** на" +/// check | Надихнуло **FastAPI** на Бути мікрофреймоворком. Зробити легким комбінування та поєднання необхідних інструментів та частин. @@ -98,7 +98,7 @@ def read_url(): Зверніть увагу на схожість у `requests.get(...)` і `@app.get(...)`. -/// check | "Надихнуло **FastAPI** на" +/// check | Надихнуло **FastAPI** на * Майте простий та інтуїтивно зрозумілий API. * Використовуйте імена (операції) методів HTTP безпосередньо, простим та інтуїтивно зрозумілим способом. @@ -118,7 +118,7 @@ def read_url(): Тому, коли говорять про версію 2.0, прийнято говорити «Swagger», а про версію 3+ «OpenAPI». -/// check | "Надихнуло **FastAPI** на" +/// check | Надихнуло **FastAPI** на Прийняти і використовувати відкритий стандарт для специфікацій API замість спеціальної схеми. @@ -147,7 +147,7 @@ Marshmallow створено для забезпечення цих функці Але він був створений до того, як існували підказки типу Python. Отже, щоб визначити кожну схему, вам потрібно використовувати спеціальні утиліти та класи, надані Marshmallow. -/// check | "Надихнуло **FastAPI** на" +/// check | Надихнуло **FastAPI** на Використовувати код для автоматичного визначення "схем", які надають типи даних і перевірку. @@ -163,13 +163,13 @@ Webargs — це інструмент, створений, щоб забезпе Це чудовий інструмент, і я також часто використовував його, перш ніж створити **FastAPI**. -/// info | "Інформація" +/// info | Інформація Webargs був створений тими ж розробниками Marshmallow. /// -/// check | "Надихнуло **FastAPI** на" +/// check | Надихнуло **FastAPI** на Мати автоматичну перевірку даних вхідного запиту. @@ -193,13 +193,13 @@ Marshmallow і Webargs забезпечують перевірку, аналіз Редактор тут нічим не може допомогти. І якщо ми змінимо параметри чи схеми Marshmallow і забудемо також змінити цю строку документа YAML, згенерована схема буде застарілою. -/// info | "Інформація" +/// info | Інформація APISpec був створений тими ж розробниками Marshmallow. /// -/// check | "Надихнуло **FastAPI** на" +/// check | Надихнуло **FastAPI** на Підтримувати відкритий стандарт API, OpenAPI. @@ -225,13 +225,13 @@ APISpec був створений тими ж розробниками Marshmall І ці самі генератори повного стеку були основою [**FastAPI** генераторів проектів](project-generation.md){.internal-link target=_blank}. -/// info | "Інформація" +/// info | Інформація Flask-apispec був створений тими ж розробниками Marshmallow. /// -/// check | "Надихнуло **FastAPI** на" +/// check | Надихнуло **FastAPI** на Створення схеми OpenAPI автоматично з того самого коду, який визначає серіалізацію та перевірку. @@ -251,7 +251,7 @@ Flask-apispec був створений тими ж розробниками Mar Він не дуже добре обробляє вкладені моделі. Отже, якщо тіло JSON у запиті є об’єктом JSON із внутрішніми полями, які, у свою чергу, є вкладеними об’єктами JSON, його неможливо належним чином задокументувати та перевірити. -/// check | "Надихнуло **FastAPI** на" +/// check | Надихнуло **FastAPI** на Використовувати типи Python, щоб мати чудову підтримку редактора. @@ -263,7 +263,7 @@ Flask-apispec був створений тими ж розробниками Mar Це був один із перших надзвичайно швидких фреймворків Python на основі `asyncio`. Він був дуже схожий на Flask. -/// note | "Технічні деталі" +/// note | Технічні деталі Він використовував `uvloop` замість стандартного циклу Python `asyncio`. Ось що зробило його таким швидким. @@ -271,7 +271,7 @@ Flask-apispec був створений тими ж розробниками Mar /// -/// check | "Надихнуло **FastAPI** на" +/// check | Надихнуло **FastAPI** на Знайти спосіб отримати божевільну продуктивність. @@ -287,7 +287,7 @@ Falcon — ще один високопродуктивний фреймворк Таким чином, перевірка даних, серіалізація та документація повинні виконуватися в коді, а не автоматично. Або вони повинні бути реалізовані як фреймворк поверх Falcon, як Hug. Така сама відмінність спостерігається в інших фреймворках, натхненних дизайном Falcon, що мають один об’єкт запиту та один об’єкт відповіді як параметри. -/// check | "Надихнуло **FastAPI** на" +/// check | Надихнуло **FastAPI** на Знайти способи отримати чудову продуктивність. @@ -313,7 +313,7 @@ Falcon — ще один високопродуктивний фреймворк Маршрути оголошуються в одному місці з використанням функцій, оголошених в інших місцях (замість використання декораторів, які можна розмістити безпосередньо поверх функції, яка обробляє кінцеву точку). Це ближче до того, як це робить Django, ніж до Flask (і Starlette). Він розділяє в коді речі, які відносно тісно пов’язані. -/// check | "Надихнуло **FastAPI** на" +/// check | Надихнуло **FastAPI** на Визначити додаткові перевірки для типів даних, використовуючи значення "за замовчуванням" атрибутів моделі. Це покращує підтримку редактора, а раніше вона була недоступна в Pydantic. @@ -335,13 +335,13 @@ Hug був одним із перших фреймворків, який реа Оскільки він заснований на попередньому стандарті для синхронних веб-фреймворків Python (WSGI), він не може працювати з Websockets та іншими речами, хоча він також має високу продуктивність. -/// info | "Інформація" +/// info | Інформація Hug створив Тімоті Крослі, той самий творець `isort`, чудовий інструмент для автоматичного сортування імпорту у файлах Python. /// -/// check | "Надихнуло **FastAPI** на" +/// check | Надихнуло **FastAPI** на Hug надихнув частину APIStar і був одним із найбільш перспективних інструментів, поряд із APIStar. @@ -375,7 +375,7 @@ Hug надихнув частину APIStar і був одним із найбі Тепер APIStar — це набір інструментів для перевірки специфікацій OpenAPI, а не веб-фреймворк. -/// info | "Інформація" +/// info | Інформація APIStar створив Том Крісті. Той самий хлопець, який створив: @@ -385,7 +385,7 @@ APIStar створив Том Крісті. Той самий хлопець, я /// -/// check | "Надихнуло **FastAPI** на" +/// check | Надихнуло **FastAPI** на Існувати. @@ -407,7 +407,7 @@ Pydantic — це бібліотека для визначення переві Його можна порівняти з Marshmallow. Хоча він швидший за Marshmallow у тестах. Оскільки він базується на тих самих підказках типу Python, підтримка редактора чудова. -/// check | "**FastAPI** використовує його для" +/// check | **FastAPI** використовує його для Виконання перевірки всіх даних, серіалізації даних і автоматичної документацію моделі (на основі схеми JSON). @@ -442,7 +442,7 @@ Starlette надає всі основні функції веб-мікрофр Це одна з головних речей, які **FastAPI** додає зверху, все на основі підказок типу Python (з використанням Pydantic). Це, а також система впровадження залежностей, утиліти безпеки, створення схеми OpenAPI тощо. -/// note | "Технічні деталі" +/// note | Технічні деталі ASGI — це новий «стандарт», який розробляється членами основної команди Django. Це ще не «стандарт Python» (PEP), хоча вони в процесі цього. @@ -450,7 +450,7 @@ ASGI — це новий «стандарт», який розробляєтьс /// -/// check | "**FastAPI** використовує його для" +/// check | **FastAPI** використовує його для Керування всіма основними веб-частинами. Додавання функцій зверху. @@ -468,7 +468,7 @@ Uvicorn — це блискавичний сервер ASGI, побудован Це рекомендований сервер для Starlette і **FastAPI**. -/// check | "**FastAPI** рекомендує це як" +/// check | **FastAPI** рекомендує це як Основний веб-сервер для запуску програм **FastAPI**. diff --git a/docs/uk/docs/tutorial/body-fields.md b/docs/uk/docs/tutorial/body-fields.md index b1f645932..c286744a8 100644 --- a/docs/uk/docs/tutorial/body-fields.md +++ b/docs/uk/docs/tutorial/body-fields.md @@ -122,7 +122,7 @@ `Field` працює так само, як `Query`, `Path` і `Body`, у нього такі самі параметри тощо. -/// note | "Технічні деталі" +/// note | Технічні деталі Насправді, `Query`, `Path` та інші, що ви побачите далі, створюють об'єкти підкласів загального класу `Param`, котрий сам є підкласом класу `FieldInfo` з Pydantic. diff --git a/docs/uk/docs/tutorial/cookie-params.md b/docs/uk/docs/tutorial/cookie-params.md index 40ca4f6e6..229f81b63 100644 --- a/docs/uk/docs/tutorial/cookie-params.md +++ b/docs/uk/docs/tutorial/cookie-params.md @@ -116,7 +116,7 @@ //// -/// note | "Технічні Деталі" +/// note | Технічні Деталі `Cookie` це "сестра" класів `Path` і `Query`. Вони наслідуються від одного батьківського класу `Param`. Але пам'ятайте, що коли ви імпортуєте `Query`, `Path`, `Cookie` та інше з `fastapi`, це фактично функції, що повертають спеціальні класи. diff --git a/docs/uk/docs/tutorial/encoder.md b/docs/uk/docs/tutorial/encoder.md index 39dca9be8..77b0baf4d 100644 --- a/docs/uk/docs/tutorial/encoder.md +++ b/docs/uk/docs/tutorial/encoder.md @@ -42,7 +42,7 @@ Вона не повертає велику строку `str`, яка містить дані у форматі JSON (як строка). Вона повертає стандартну структуру даних Python (наприклад `dict`) із значеннями та підзначеннями, які є сумісними з JSON. -/// note | "Примітка" +/// note | Примітка `jsonable_encoder` фактично використовується **FastAPI** внутрішньо для перетворення даних. Проте вона корисна в багатьох інших сценаріях. diff --git a/docs/uk/docs/tutorial/first-steps.md b/docs/uk/docs/tutorial/first-steps.md index 6f79c0d1d..63fec207d 100644 --- a/docs/uk/docs/tutorial/first-steps.md +++ b/docs/uk/docs/tutorial/first-steps.md @@ -163,7 +163,7 @@ OpenAPI описує схему для вашого API. І ця схема вк `FastAPI` це клас у Python, який надає всю функціональність для API. -/// note | "Технічні деталі" +/// note | Технічні деталі `FastAPI` це клас, який успадковується безпосередньо від `Starlette`. @@ -198,7 +198,7 @@ https://example.com/items/foo /items/foo ``` -/// info | "Додаткова інформація" +/// info | Додаткова інформація "Шлях" (path) також зазвичай називають "ендпоінтом" (endpoint) або "маршрутом" (route). @@ -250,7 +250,7 @@ https://example.com/items/foo * шлях `/` * використовуючи get операцію -/// info | "`@decorator` Додаткова інформація" +/// info | `@decorator` Додаткова інформація Синтаксис `@something` у Python називається "декоратором". @@ -277,7 +277,7 @@ https://example.com/items/foo * `@app.patch()` * `@app.trace()` -/// tip | "Порада" +/// tip | Порада Ви можете використовувати кожну операцію (HTTP-метод) на свій розсуд. @@ -315,7 +315,7 @@ FastAPI викликатиме її щоразу, коли отримає зап {!../../docs_src/first_steps/tutorial003.py!} ``` -/// note | "Примітка" +/// note | Примітка Якщо не знаєте в чому різниця, подивіться [Конкурентність: *"Поспішаєш?"*](../async.md#in-a-hurry){.internal-link target=_blank}. diff --git a/docs/vi/docs/tutorial/first-steps.md b/docs/vi/docs/tutorial/first-steps.md index d80d78506..901c8fd59 100644 --- a/docs/vi/docs/tutorial/first-steps.md +++ b/docs/vi/docs/tutorial/first-steps.md @@ -2,9 +2,7 @@ Tệp tin FastAPI đơn giản nhất có thể trông như này: -```Python -{!../../docs_src/first_steps/tutorial001.py!} -``` +{* ../../docs_src/first_steps/tutorial001.py *} Sao chép sang một tệp tin `main.py`. @@ -133,13 +131,11 @@ Bạn cũng có thể sử dụng nó để sinh code tự động, với các c ### Bước 1: import `FastAPI` -```Python hl_lines="1" -{!../../docs_src/first_steps/tutorial001.py!} -``` +{* ../../docs_src/first_steps/tutorial001.py hl[1] *} `FastAPI` là một Python class cung cấp tất cả chức năng cho API của bạn. -/// note | "Chi tiết kĩ thuật" +/// note | Chi tiết kĩ thuật `FastAPI` là một class kế thừa trực tiếp `Starlette`. @@ -149,9 +145,7 @@ Bạn cũng có thể sử dụng tất cả + +```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 中讀取環境變數 + +你也可以在 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()` 的預設回傳值。 + +如果沒有提供，預設值為 `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: 配置中了解更多資訊。 + +/// + +## 型別和驗證 + +這些環境變數只能處理**文字字串**，因為它們是位於 Python 範疇之外的，必須與其他程式和作業系統的其餘部分相容（甚至與不同的作業系統相容，如 Linux、Windows、macOS）。 + +這意味著從環境變數中讀取的**任何值**在 Python 中都將是一個 `str`，任何型別轉換或驗證都必須在程式碼中完成。 + +你將在[進階使用者指南 - 設定和環境變數](./advanced/settings.md)中了解更多關於使用環境變數處理**應用程式設定**的資訊。 + +## `PATH` 環境變數 + +有一個**特殊的**環境變數稱為 **`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` + +安裝 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` 環境變數（在 Python 安裝程式中，這個選項是名為 `Add Python x.xx to 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)時，這些資訊將會很有用。 + +## 結論 + +透過這個教學，你應該對**環境變數**是什麼以及如何在 Python 中使用它們有了基本的了解。 + +你也可以在環境變數 - 維基百科 (Wikipedia for Environment Variable) 中了解更多關於它們的資訊。 + +在許多情況下，環境變數的用途和適用性可能不會立刻顯現。但是在開發過程中，它們會在許多不同的場景中出現，因此瞭解它們是非常必要的。 + +例如，你在接下來的[虛擬環境](virtual-environments.md)章節中將需要這些資訊。 diff --git a/docs/zh/docs/advanced/additional-responses.md b/docs/zh/docs/advanced/additional-responses.md index f051b12a4..362ef9460 100644 --- a/docs/zh/docs/advanced/additional-responses.md +++ b/docs/zh/docs/advanced/additional-responses.md @@ -16,9 +16,7 @@ **FastAPI**将采用该模型，生成其`JSON Schema`并将其包含在`OpenAPI`中的正确位置。 例如，要声明另一个具有状态码 `404` 和`Pydantic`模型 `Message` 的响应，可以写： -```Python hl_lines="18 22" -{!../../docs_src/additional_responses/tutorial001.py!} -``` +{* ../../docs_src/additional_responses/tutorial001.py hl[18,22] *} /// note @@ -163,9 +161,7 @@ 例如，您可以添加一个额外的媒体类型` image/png` ，声明您的路径操作可以返回JSON对象（媒体类型 `application/json` ）或PNG图像： -```Python hl_lines="19-24 28" -{!../../docs_src/additional_responses/tutorial002.py!} -``` +{* ../../docs_src/additional_responses/tutorial002.py hl[19:24,28] *} /// note @@ -191,9 +187,7 @@ 以及一个状态码为 `200` 的响应，它使用您的 `response_model` ，但包含自定义的 `example` ： -```Python hl_lines="20-31" -{!../../docs_src/additional_responses/tutorial003.py!} -``` +{* ../../docs_src/additional_responses/tutorial003.py hl[20:31] *} 所有这些都将被合并并包含在您的OpenAPI中，并在API文档中显示： @@ -219,9 +213,7 @@ new_dict = {**old_dict, "new key": "new value"} ``` 您可以使用该技术在路径操作中重用一些预定义的响应，并将它们与其他自定义响应相结合。 **例如：** -```Python hl_lines="13-17 26" -{!../../docs_src/additional_responses/tutorial004.py!} -``` +{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *} ## 有关OpenAPI响应的更多信息 要了解您可以在响应中包含哪些内容，您可以查看OpenAPI规范中的以下部分： diff --git a/docs/zh/docs/advanced/additional-status-codes.md b/docs/zh/docs/advanced/additional-status-codes.md index f79b853ef..b8f9b0837 100644 --- a/docs/zh/docs/advanced/additional-status-codes.md +++ b/docs/zh/docs/advanced/additional-status-codes.md @@ -18,7 +18,7 @@ {!../../docs_src/additional_status_codes/tutorial001.py!} ``` -/// warning | "警告" +/// warning | 警告 当你直接返回一个像上面例子中的 `Response` 对象时，它会直接返回。 @@ -28,7 +28,7 @@ FastAPI 不会用模型等对该响应进行序列化。 /// -/// note | "技术细节" +/// note | 技术细节 你也可以使用 `from starlette.responses import JSONResponse`。　 diff --git a/docs/zh/docs/advanced/advanced-dependencies.md b/docs/zh/docs/advanced/advanced-dependencies.md index f3fe1e395..bd37ecebb 100644 --- a/docs/zh/docs/advanced/advanced-dependencies.md +++ b/docs/zh/docs/advanced/advanced-dependencies.md @@ -60,7 +60,7 @@ checker(q="somequery") {!../../docs_src/dependencies/tutorial011.py!} ``` -/// tip | "提示" +/// tip | 提示 本章示例有些刻意，也看不出有什么用处。 diff --git a/docs/zh/docs/advanced/behind-a-proxy.md b/docs/zh/docs/advanced/behind-a-proxy.md index 8c4b6bb04..5ed6baa82 100644 --- a/docs/zh/docs/advanced/behind-a-proxy.md +++ b/docs/zh/docs/advanced/behind-a-proxy.md @@ -37,7 +37,7 @@ browser --> proxy proxy --> server ``` -/// tip | "提示" +/// tip | 提示 IP `0.0.0.0` 常用于指程序监听本机或服务器上的所有有效 IP。 @@ -78,7 +78,7 @@ $ uvicorn main:app --root-path /api/v1 Hypercorn 也支持 `--root-path `选项。 -/// note | "技术细节" +/// note | 技术细节 ASGI 规范定义的 `root_path` 就是为了这种用例。 @@ -172,7 +172,7 @@ Uvicorn 预期代理在 `http://127.0.0.1:8000/app` 访问 Uvicorn，而在顶 这个文件把 Traefik 监听端口设置为 `9999`，并设置要使用另一个文件 `routes.toml`。 -/// tip | "提示" +/// tip | 提示 使用端口 9999 代替标准的 HTTP 端口 80，这样就不必使用管理员权限运行（`sudo`）。 @@ -242,7 +242,7 @@ $ uvicorn main:app --root-path /api/v1 } ``` -/// tip | "提示" +/// tip | 提示 注意，就算访问 `http://127.0.0.1:8000/app`，也显示从选项 `--root-path` 中提取的 `/api/v1`，这是 `root_path` 的值。 @@ -289,7 +289,7 @@ $ uvicorn main:app --root-path /api/v1 ## 附加的服务器 -/// warning | "警告" +/// warning | 警告 此用例较难，可以跳过。 @@ -332,7 +332,7 @@ $ uvicorn main:app --root-path /api/v1 } ``` -/// tip | "提示" +/// tip | 提示 注意，自动生成服务器时，`url` 的值 `/api/v1` 提取自 `roog_path`。 @@ -342,7 +342,7 @@ $ uvicorn main:app --root-path /api/v1 -/// tip | "提示" +/// tip | 提示 API 文档与所选的服务器进行交互。 diff --git a/docs/zh/docs/advanced/custom-response.md b/docs/zh/docs/advanced/custom-response.md index 27c026904..85ca1d06d 100644 --- a/docs/zh/docs/advanced/custom-response.md +++ b/docs/zh/docs/advanced/custom-response.md @@ -12,7 +12,7 @@ 并且如果该 `Response` 有一个 JSON 媒体类型（`application/json`），比如使用 `JSONResponse` 或者 `UJSONResponse` 的时候，返回的数据将使用你在路径操作装饰器中声明的任何 Pydantic 的 `response_model` 自动转换（和过滤）。 -/// note | "说明" +/// note | 说明 如果你使用不带有任何媒体类型的响应类，FastAPI 认为你的响应没有任何内容，所以不会在生成的OpenAPI文档中记录响应格式。 @@ -28,7 +28,7 @@ {!../../docs_src/custom_response/tutorial001b.py!} ``` -/// info | "提示" +/// info | 提示 参数 `response_class` 也会用来定义响应的「媒体类型」。 @@ -38,7 +38,7 @@ /// -/// tip | "小贴士" +/// tip | 小贴士 `ORJSONResponse` 目前只在 FastAPI 中可用，而在 Starlette 中不可用。 @@ -55,7 +55,7 @@ {!../../docs_src/custom_response/tutorial002.py!} ``` -/// info | "提示" +/// info | 提示 参数 `response_class` 也会用来定义响应的「媒体类型」。 @@ -75,13 +75,13 @@ {!../../docs_src/custom_response/tutorial003.py!} ``` -/// warning | "警告" +/// warning | 警告 *路径操作函数* 直接返回的 `Response` 不会被 OpenAPI 的文档记录（比如，`Content-Type` 不会被文档记录），并且在自动化交互文档中也是不可见的。 /// -/// info | "提示" +/// info | 提示 当然，实际的 `Content-Type` 头，状态码等等，将来自于你返回的 `Response` 对象。 @@ -115,7 +115,7 @@ 要记得你可以使用 `Response` 来返回任何其他东西，甚至创建一个自定义的子类。 -/// note | "技术细节" +/// note | 技术细节 你也可以使用 `from starlette.responses import HTMLResponse`。 @@ -170,7 +170,7 @@ FastAPI（实际上是 Starlette）将自动包含 Content-Length 的头。它 `UJSONResponse` 是一个使用 `ujson` 的可选 JSON 响应。 -/// warning | "警告" +/// warning | 警告 在处理某些边缘情况时，`ujson` 不如 Python 的内置实现那么谨慎。 @@ -180,7 +180,7 @@ FastAPI（实际上是 Starlette）将自动包含 Content-Length 的头。它 {!../../docs_src/custom_response/tutorial001.py!} ``` -/// tip | "小贴士" +/// tip | 小贴士 `ORJSONResponse` 可能是一个更快的选择。 @@ -212,7 +212,7 @@ FastAPI（实际上是 Starlette）将自动包含 Content-Length 的头。它 {!../../docs_src/custom_response/tutorial008.py!} ``` -/// tip | "小贴士" +/// tip | 小贴士 注意在这里，因为我们使用的是不支持 `async` 和 `await` 的标准 `open()`，我们使用普通的 `def` 声明了路径操作。 diff --git a/docs/zh/docs/advanced/dataclasses.md b/docs/zh/docs/advanced/dataclasses.md index f33c05ff4..7d977a0c7 100644 --- a/docs/zh/docs/advanced/dataclasses.md +++ b/docs/zh/docs/advanced/dataclasses.md @@ -20,7 +20,7 @@ FastAPI 基于 **Pydantic** 构建，前文已经介绍过如何使用 Pydantic 数据类的和运作方式与 Pydantic 模型相同。实际上，它的底层使用的也是 Pydantic。 -/// info | "说明" +/// info | 说明 注意，数据类不支持 Pydantic 模型的所有功能。 diff --git a/docs/zh/docs/advanced/events.md b/docs/zh/docs/advanced/events.md index e5b44f321..a34c03f3f 100644 --- a/docs/zh/docs/advanced/events.md +++ b/docs/zh/docs/advanced/events.md @@ -4,7 +4,7 @@ 事件函数既可以声明为异步函数（`async def`），也可以声明为普通函数（`def`）。 -/// warning | "警告" +/// warning | 警告 **FastAPI** 只执行主应用中的事件处理器，不执行[子应用 - 挂载](sub-applications.md){.internal-link target=_blank}中的事件处理器。 @@ -34,13 +34,13 @@ 此处，`shutdown` 事件处理器函数在 `log.txt` 中写入一行文本 `Application shutdown`。 -/// info | "说明" +/// info | 说明 `open()` 函数中，`mode="a"` 指的是**追加**。因此这行文本会添加在文件已有内容之后，不会覆盖之前的内容。 /// -/// tip | "提示" +/// tip | 提示 注意，本例使用 Python `open()` 标准函数与文件交互。 @@ -52,7 +52,7 @@ /// -/// info | "说明" +/// info | 说明 有关事件处理器的详情，请参阅 Starlette 官档 - 事件。 diff --git a/docs/zh/docs/advanced/middleware.md b/docs/zh/docs/advanced/middleware.md index 525dc89ac..78a7d559c 100644 --- a/docs/zh/docs/advanced/middleware.md +++ b/docs/zh/docs/advanced/middleware.md @@ -43,7 +43,7 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") **FastAPI** 为常见用例提供了一些中间件，下面介绍怎么使用这些中间件。 -/// note | "技术细节" +/// note | 技术细节 以下几个示例中也可以使用 `from starlette.middleware.something import SomethingMiddleware`。 diff --git a/docs/zh/docs/advanced/openapi-callbacks.md b/docs/zh/docs/advanced/openapi-callbacks.md index dc1c2539b..601cbdb5d 100644 --- a/docs/zh/docs/advanced/openapi-callbacks.md +++ b/docs/zh/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ API 的用户 （外部开发者）要在您的 API 内使用 POST 请求创建 {!../../docs_src/openapi_callbacks/tutorial001.py!} ``` -/// tip | "提示" +/// tip | 提示 `callback_url` 查询参数使用 Pydantic 的 URL 类型。 @@ -64,7 +64,7 @@ requests.post(callback_url, json={"description": "Invoice paid", "paid": True}) 本例没有实现回调本身（只是一行代码），只有文档部分。 -/// tip | "提示" +/// tip | 提示 实际的回调只是 HTTP 请求。 @@ -80,7 +80,7 @@ requests.post(callback_url, json={"description": "Invoice paid", "paid": True}) 我们要使用与存档*外部 API* 相同的知识……通过创建外部 API 要实现的*路径操作*（您的 API 要调用的）。 -/// tip | "提示" +/// tip | 提示 编写存档回调的代码时，假设您是*外部开发者*可能会用的上。并且您当前正在实现的是*外部 API*，不是*您自己的 API*。 @@ -163,7 +163,7 @@ JSON 请求体包含如下内容： } ``` -/// tip | "提示" +/// tip | 提示 注意，回调 URL包含 `callback_url` （`https://www.external.org/events`）中的查询参数，还有 JSON 请求体内部的发票 ID（`2expen51ve`）。 @@ -179,7 +179,7 @@ JSON 请求体包含如下内容： {!../../docs_src/openapi_callbacks/tutorial001.py!} ``` -/// tip | "提示" +/// tip | 提示 注意，不能把路由本身（`invoices_callback_router`）传递给 `callback=`，要传递 `invoices_callback_router.routes` 中的 `.routes` 属性。 diff --git a/docs/zh/docs/advanced/response-cookies.md b/docs/zh/docs/advanced/response-cookies.md index 5772664b0..2d56c6e9b 100644 --- a/docs/zh/docs/advanced/response-cookies.md +++ b/docs/zh/docs/advanced/response-cookies.md @@ -40,7 +40,7 @@ ### 更多信息 -/// note | "技术细节" +/// note | 技术细节 你也可以使用`from starlette.responses import Response` 或者 `from starlette.responses import JSONResponse`。 diff --git a/docs/zh/docs/advanced/response-directly.md b/docs/zh/docs/advanced/response-directly.md index 9d191c622..934f60ef6 100644 --- a/docs/zh/docs/advanced/response-directly.md +++ b/docs/zh/docs/advanced/response-directly.md @@ -14,7 +14,7 @@ 事实上，你可以返回任意 `Response` 或者任意 `Response` 的子类。 -/// tip | "小贴士" +/// tip | 小贴士 `JSONResponse` 本身是一个 `Response` 的子类。 @@ -39,7 +39,7 @@ {!../../docs_src/response_directly/tutorial001.py!} ``` -/// note | "技术细节" +/// note | 技术细节 你也可以使用 `from starlette.responses import JSONResponse`。 diff --git a/docs/zh/docs/advanced/response-headers.md b/docs/zh/docs/advanced/response-headers.md index d593fdccc..e7861ad0c 100644 --- a/docs/zh/docs/advanced/response-headers.md +++ b/docs/zh/docs/advanced/response-headers.md @@ -25,7 +25,7 @@ ``` -/// note | "技术细节" +/// note | 技术细节 你也可以使用`from starlette.responses import Response`或`from starlette.responses import JSONResponse`。 diff --git a/docs/zh/docs/advanced/security/index.md b/docs/zh/docs/advanced/security/index.md index 836086ae2..267e7ced7 100644 --- a/docs/zh/docs/advanced/security/index.md +++ b/docs/zh/docs/advanced/security/index.md @@ -4,7 +4,7 @@ 除 [教程 - 用户指南: 安全性](../../tutorial/security/index.md){.internal-link target=_blank} 中涵盖的功能之外，还有一些额外的功能来处理安全性. -/// tip | "小贴士" +/// tip | 小贴士 接下来的章节 **并不一定是 "高级的"**. diff --git a/docs/zh/docs/advanced/security/oauth2-scopes.md b/docs/zh/docs/advanced/security/oauth2-scopes.md index d6354230e..b26522113 100644 --- a/docs/zh/docs/advanced/security/oauth2-scopes.md +++ b/docs/zh/docs/advanced/security/oauth2-scopes.md @@ -10,7 +10,7 @@ OAuth2 也是脸书、谷歌、GitHub、微软、推特等第三方身份验证 本章介绍如何在 **FastAPI** 应用中使用 OAuth2 作用域管理验证与授权。 -/// warning | "警告" +/// warning | 警告 本章内容较难，刚接触 FastAPI 的新手可以跳过。 @@ -46,7 +46,7 @@ OpenAPI 中（例如 API 文档）可以定义**安全方案**。 * 脸书和 Instagram 使用 `instagram_basic` * 谷歌使用 `https://www.googleapis.com/auth/drive` -/// info | "说明" +/// info | 说明 OAuth2 中，**作用域**只是声明特定权限的字符串。 @@ -94,7 +94,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 这样，返回的 JWT 令牌中就包含了作用域。 -/// danger | "危险" +/// danger | 危险 为了简明起见，本例把接收的作用域直接添加到了令牌里。 @@ -122,7 +122,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 本例要求使用作用域 `me`（还可以使用更多作用域）。 -/// note | "笔记" +/// note | 笔记 不必在不同位置添加不同的作用域。 @@ -134,7 +134,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 {!../../docs_src/security/tutorial005.py!} ``` -/// info | "技术细节" +/// info | 技术细节 `Security` 实际上是 `Depends` 的子类，而且只比 `Depends` 多一个参数。 @@ -231,7 +231,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 * `security_scopes.scopes` 包含*路径操作* `read_users_me` 的 `["me"]`，因为它在依赖项里被声明 * `security_scopes.scopes` 包含用于*路径操作* `read_system_status` 的 `[]`（空列表），并且它的依赖项 `get_current_user` 也没有声明任何 `scope` -/// tip | "提示" +/// tip | 提示 此处重要且**神奇**的事情是，`get_current_user` 检查每个*路径操作*时可以使用不同的 `scopes` 列表。 @@ -275,7 +275,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 最安全的是代码流，但实现起来更复杂，而且需要更多步骤。因为它更复杂，很多第三方身份验证应用最终建议使用隐式流。 -/// note | "笔记" +/// note | 笔记 每个身份验证应用都会采用不同方式会命名流，以便融合入自己的品牌。 diff --git a/docs/zh/docs/advanced/templates.md b/docs/zh/docs/advanced/templates.md index 1159302a9..7692aa47b 100644 --- a/docs/zh/docs/advanced/templates.md +++ b/docs/zh/docs/advanced/templates.md @@ -31,20 +31,20 @@ $ pip install jinja2 {!../../docs_src/templates/tutorial001.py!} ``` -/// note | "笔记" +/// note | 笔记 在FastAPI 0.108.0，Starlette 0.29.0之前，`name`是第一个参数。 并且，在此之前，`request`对象是作为context的一部分以键值对的形式传递的。 /// -/// tip | "提示" +/// tip | 提示 通过声明 `response_class=HTMLResponse`，API 文档就能识别响应的对象是 HTML。 /// -/// note | "技术细节" +/// note | 技术细节 您还可以使用 `from starlette.templating import Jinja2Templates`。 diff --git a/docs/zh/docs/advanced/testing-dependencies.md b/docs/zh/docs/advanced/testing-dependencies.md index c3d912e2f..b4b5b32df 100644 --- a/docs/zh/docs/advanced/testing-dependencies.md +++ b/docs/zh/docs/advanced/testing-dependencies.md @@ -32,7 +32,7 @@ {!../../docs_src/dependency_testing/tutorial001.py!} ``` -/// tip | "提示" +/// tip | 提示 **FastAPI** 应用中的任何位置都可以实现覆盖依赖项。 @@ -48,7 +48,7 @@ FastAPI 可以覆盖这些位置的依赖项。 app.dependency_overrides = {} ``` -/// tip | "提示" +/// tip | 提示 如果只在某些测试时覆盖依赖项，您可以在测试开始时（在测试函数内）设置覆盖依赖项，并在结束时（在测试函数结尾）重置覆盖依赖项。 diff --git a/docs/zh/docs/advanced/testing-websockets.md b/docs/zh/docs/advanced/testing-websockets.md index a69053f24..b30939b97 100644 --- a/docs/zh/docs/advanced/testing-websockets.md +++ b/docs/zh/docs/advanced/testing-websockets.md @@ -8,7 +8,7 @@ {!../../docs_src/app_testing/tutorial002.py!} ``` -/// note | "笔记" +/// note | 笔记 更多细节详见 Starlette 官档 - 测试 WebSockets。 diff --git a/docs/zh/docs/advanced/using-request-directly.md b/docs/zh/docs/advanced/using-request-directly.md index 992458217..f01644de6 100644 --- a/docs/zh/docs/advanced/using-request-directly.md +++ b/docs/zh/docs/advanced/using-request-directly.md @@ -35,7 +35,7 @@ 把*路径操作函数*的参数类型声明为 `Request`，**FastAPI** 就能把 `Request` 传递到参数里。 -/// tip | "提示" +/// tip | 提示 注意，本例除了声明请求参数之外，还声明了路径参数。 @@ -49,7 +49,7 @@ 更多细节详见 Starlette 官档 - `Request` 对象。 -/// note | "技术细节" +/// note | 技术细节 您也可以使用 `from starlette.requests import Request`。 diff --git a/docs/zh/docs/advanced/websockets.md b/docs/zh/docs/advanced/websockets.md index 15ae84c58..dcd4cd5a9 100644 --- a/docs/zh/docs/advanced/websockets.md +++ b/docs/zh/docs/advanced/websockets.md @@ -46,7 +46,7 @@ $ pip install websockets {!../../docs_src/websockets/tutorial001.py!} ``` -/// note | "技术细节" +/// note | 技术细节 您也可以使用 `from starlette.websockets import WebSocket`。 diff --git a/docs/zh/docs/contributing.md b/docs/zh/docs/contributing.md deleted file mode 100644 index 85b341a8d..000000000 --- a/docs/zh/docs/contributing.md +++ /dev/null @@ -1,472 +0,0 @@ -# 开发 - 贡献 - -首先，你可能想了解 [帮助 FastAPI 及获取帮助](help-fastapi.md){.internal-link target=_blank}的基本方式。 - -## 开发 - -如果你已经克隆了源码仓库，并且需要深入研究代码，下面是设置开发环境的指南。 - -### 通过 `venv` 管理虚拟环境 - -你可以使用 Python 的 `venv` 模块在一个目录中创建虚拟环境： - -
- -```console -$ python -m venv env -``` - -
- -这将使用 Python 程序创建一个 `./env/` 目录，然后你将能够为这个隔离的环境安装软件包。 - -### 激活虚拟环境 - -使用以下方法激活新环境： - -//// tab | Linux, macOS - -
- -```console -$ source ./env/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .\env\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -Or if you use Bash for Windows (e.g. Git Bash): - -
- -```console -$ source ./env/Scripts/activate -``` - -
- -//// - -要检查操作是否成功，运行： - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which pip - -some/directory/fastapi/env/bin/pip -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command pip - -some/directory/fastapi/env/bin/pip -``` - -
- -//// - -如果显示 `pip` 程序文件位于 `env/bin/pip` 则说明激活成功。 🎉 - -确保虚拟环境中的 pip 版本是最新的，以避免后续步骤出现错误： - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip - -每一次你在该环境下使用 `pip` 安装了新软件包时，请再次激活该环境。 - -这样可以确保你在使用由该软件包安装的终端程序时使用的是当前虚拟环境中的程序，而不是其他的可能是全局安装的程序。 - -/// - -### pip - -如上所述激活环境后： - -
- -```console -$ pip install -r requirements.txt - ----> 100% -``` - -
- -这将在虚拟环境中安装所有依赖和本地版本的 FastAPI。 - -#### 使用本地 FastAPI - -如果你创建一个导入并使用 FastAPI 的 Python 文件，然后使用虚拟环境中的 Python 运行它，它将使用你本地的 FastAPI 源码。 - -并且如果你更改该本地 FastAPI 的源码，由于它是通过 `-e` 安装的，当你再次运行那个 Python 文件，它将使用你刚刚编辑过的最新版本的 FastAPI。 - -这样，你不必再去重新"安装"你的本地版本即可测试所有更改。 - -/// note | "技术细节" - -仅当你使用此项目中的 `requirements.txt` 安装而不是直接使用 `pip install fastapi` 安装时，才会发生这种情况。 - -这是因为在 `requirements.txt` 中，本地的 FastAPI 是使用“可编辑” （`-e`）选项安装的 - -/// - -### 格式化 - -你可以运行下面的脚本来格式化和清理所有代码： - -
- -```console -$ bash scripts/format.sh -``` - -
- -它还会自动对所有导入代码进行排序整理。 - -为了使整理正确进行，你需要在当前环境中安装本地的 FastAPI，即在运行上述段落中的命令时添加 `-e`。 - -## 文档 - -首先，请确保按上述步骤设置好环境，这将安装所有需要的依赖。 - -### 实时文档 - -在本地开发时，可以使用该脚本构建站点并检查所做的任何更改，并实时重载： - -
- -```console -$ python ./scripts/docs.py live - -[INFO] Serving on http://127.0.0.1:8008 -[INFO] Start watching changes -[INFO] Start detecting changes -``` - -
- -文档服务将运行在 `http://127.0.0.1:8008`。 - -这样，你可以编辑文档 / 源文件并实时查看更改。 - -/// tip - -或者你也可以手动执行和该脚本一样的操作 - -进入语言目录，如果是英文文档，目录则是 `docs/en/`: - -```console -$ cd docs/en/ -``` - -在该目录执行 `mkdocs` 命令 - -```console -$ mkdocs serve --dev-addr 8008 -``` - -/// - -#### Typer CLI （可选） - -本指引向你展示了如何直接用 `python` 运行 `./scripts/docs.py` 中的脚本。 - -但你也可以使用 Typer CLI，而且在安装了补全功能后，你将可以在终端中对命令进行自动补全。 - -如果你已经安装 Typer CLI ，则可以使用以下命令安装自动补全功能： - -
- -```console -$ typer --install-completion - -zsh completion installed in /home/user/.bashrc. -Completion will take effect once you restart the terminal. -``` - -
- -### 文档架构 - -文档使用 MkDocs 生成。 - -在 `./scripts/docs.py` 中还有额外工具 / 脚本来处理翻译。 - -/// tip - -你不需要去了解 `./scripts/docs.py` 中的代码，只需在命令行中使用它即可。 - -/// - -所有文档均在 `./docs/en/` 目录中以 Markdown 文件格式保存。 - -许多的教程中都有一些代码块，大多数情况下，这些代码是可以直接运行的，因为这些代码不是写在 Markdown 文件里的，而是写在 `./docs_src/` 目录中的 Python 文件里。 - -在生成站点的时候，这些 Python 文件会被打包进文档中。 - -### 测试文档 - -大多数的测试实际上都是针对文档中的示例源文件运行的。 - -这有助于确保： - -* 文档始终是最新的。 -* 文档示例可以直接运行。 -* 绝大多数特性既在文档中得以阐述，又通过测试覆盖进行保障。 - - -### 应用和文档同时运行 - -如果你使用以下方式运行示例程序： - -
- -```console -$ uvicorn tutorial001:app --reload - -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -``` - -
- -由于 Uvicorn 默认使用 `8000` 端口 ，因此运行在 `8008` 端口上的文档不会与之冲突。 - -### 翻译 - -**非常感谢**你能够参与文档的翻译！这项工作需要社区的帮助才能完成。 🌎 🚀 - -以下是参与帮助翻译的步骤。 - -#### 建议和指南 - -* 在当前 已有的 pull requests 中查找你使用的语言，添加要求修改或同意合并的评审意见。 - -/// tip - -你可以为已有的 pull requests 添加包含修改建议的评论。 - -详情可查看关于 添加 pull request 评审意见 以同意合并或要求修改的文档。 - -/// - -* 检查在 GitHub Discussion 是否有关于你所用语言的协作翻译。 如果有，你可以订阅它，当有一条新的 PR 请求需要评审时，系统会自动将其添加到讨论中，你也会收到对应的推送。 - -* 每翻译一个页面新增一个 pull request。这将使其他人更容易对其进行评审。 - -对于我（译注：作者使用西班牙语和英语）不懂的语言，我将在等待其他人评审翻译之后将其合并。 - -* 你还可以查看是否有你所用语言的翻译，并对其进行评审，这将帮助我了解翻译是否正确以及能否将其合并。 - * 可以在 GitHub Discussions 中查看。 - * 也可以在现有 PR 中通过你使用的语言标签来筛选对应的 PR，举个例子，对于西班牙语，标签是 `lang-es`。 - -* 请使用相同的 Python 示例，且只需翻译文档中的文本，不用修改其它东西。 - -* 请使用相同的图片、文件名以及链接地址，不用修改其它东西。 - -* 你可以从 ISO 639-1 代码列表 表中查找你想要翻译语言的两位字母代码。 - -#### 已有的语言 - -假设你想将某个页面翻译成已经翻译了一些页面的语言，例如西班牙语。 - -对于西班牙语来说，它的两位字母代码是 `es`。所以西班牙语翻译的目录位于 `docs/es/`。 - -/// tip - -默认语言是英语，位于 `docs/en/`目录。 - -/// - -现在为西班牙语文档运行实时服务器： - -
- -```console -// Use the command "live" and pass the language code as a CLI argument -$ python ./scripts/docs.py live es - -[INFO] Serving on http://127.0.0.1:8008 -[INFO] Start watching changes -[INFO] Start detecting changes -``` - -
- -/// tip - -或者你也可以手动执行和该脚本一样的操作 - -进入语言目录，对于西班牙语的翻译，目录是 `docs/es/`: - -```console -$ cd docs/es/ -``` - -在该目录执行 `mkdocs` 命令 - -```console -$ mkdocs serve --dev-addr 8008 -``` - -/// - -现在你可以访问 http://127.0.0.1:8008 实时查看你所做的更改。 - -如果你查看 FastAPI 的线上文档网站，会看到每种语言都有所有的文档页面，但是某些页面并未被翻译并且会有一处关于缺少翻译的提示。（但是当你像上面这样在本地运行文档时，你只会看到已经翻译的页面。） - -现在假设你要为 [Features](features.md){.internal-link target=_blank} 章节添加翻译。 - -* 复制下面的文件： - -``` -docs/en/docs/features.md -``` - -* 粘贴到你想要翻译语言目录的相同位置，比如： - -``` -docs/es/docs/features.md -``` - -/// tip - -注意路径和文件名的唯一变化是语言代码，从 `en` 更改为 `es`。 - -/// - -回到浏览器你就可以看到刚刚更新的章节了。🎉 - -现在，你可以翻译这些内容并在保存文件后进行预览。 - -#### 新语言 - -假设你想要为尚未有任何页面被翻译的语言添加翻译。 - -假设你想要添加克里奥尔语翻译，而且文档中还没有该语言的翻译。 - -点击上面提到的“ISO 639-1 代码列表”链接，可以查到“克里奥尔语”的代码为 `ht`。 - -下一步是运行脚本以生成新的翻译目录： - -
- -```console -// Use the command new-lang, pass the language code as a CLI argument -$ python ./scripts/docs.py new-lang ht - -Successfully initialized: docs/ht -``` - -
- -现在，你可以在编辑器中查看新创建的目录 `docs/ht/`。 - -这条命令会生成一个从 `en` 版本继承了所有属性的配置文件 `docs/ht/mkdocs.yml`: - -```yaml -INHERIT: ../en/mkdocs.yml -``` - -/// tip - -你也可以自己手动创建包含这些内容的文件。 - -/// - -这条命令还会生成一个文档主页 `docs/ht/index.md`，你可以从这个文件开始翻译。 - -然后，你可以根据上面的"已有语言"的指引继续进行翻译。 - -翻译完成后，你就可以用 `docs/ht/mkdocs.yml` 和 `docs/ht/index.md` 发起 PR 了。🎉 - -#### 预览结果 - -你可以执行 `./scripts/docs.py live` 命令来预览结果（或者 `mkdocs serve`）。 - -但是当你完成翻译后，你可以像在线上展示一样测试所有内容，包括所有其他语言。 - -为此，首先构建所有文档： - -
- -```console -// Use the command "build-all", this will take a bit -$ python ./scripts/docs.py build-all - -Building docs for: en -Building docs for: es -Successfully built docs for: es -``` - -
- -这样会对每一种语言构建一个独立的文档站点，并最终把这些站点全部打包输出到 `./site/` 目录。 - - - -然后你可以使用命令 `serve` 来运行生成的站点： - -
- -```console -// Use the command "serve" after running "build-all" -$ python ./scripts/docs.py serve - -Warning: this is a very simple server. For development, use mkdocs serve instead. -This is here only to preview a site with translations already built. -Make sure you run the build-all command first. -Serving at: http://127.0.0.1:8008 -``` - -
- -## 测试 - -你可以在本地运行下面的脚本来测试所有代码并生成 HTML 格式的覆盖率报告： - -
- -```console -$ bash scripts/test-cov-html.sh -``` - -
- -该命令生成了一个 `./htmlcov/` 目录，如果你在浏览器中打开 `./htmlcov/index.html` 文件，你可以交互式地浏览被测试所覆盖的代码区块，并注意是否缺少了任何区块。 diff --git a/docs/zh/docs/environment-variables.md b/docs/zh/docs/environment-variables.md new file mode 100644 index 000000000..812278051 --- /dev/null +++ b/docs/zh/docs/environment-variables.md @@ -0,0 +1,298 @@ +# 环境变量 + +/// tip + +如果你已经知道什么是“环境变量”并且知道如何使用它们，你可以放心跳过这一部分。 + +/// + +环境变量（也称为“**env var**”）是一个独立于 Python 代码**之外**的变量，它存在于**操作系统**中，可以被你的 Python 代码（或其他程序）读取。 + +环境变量对于处理应用程序**设置**、作为 Python **安装**的一部分等方面非常有用。 + +## 创建和使用环境变量 + +你在 **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 中读取环境变量 + +你也可以在 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()` 的默认返回值。 + +如果没有提供，默认值为 `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: 配置中了解更多信息。 + +/// + +## 类型和验证 + +这些环境变量只能处理**文本字符串**，因为它们是处于 Python 范畴之外的，必须与其他程序和操作系统的其余部分兼容（甚至与不同的操作系统兼容，如 Linux、Windows、macOS）。 + +这意味着从环境变量中读取的**任何值**在 Python 中都将是一个 `str`，任何类型转换或验证都必须在代码中完成。 + +你将在[高级用户指南 - 设置和环境变量](./advanced/settings.md)中了解更多关于使用环境变量处理**应用程序设置**的信息。 + +## `PATH` 环境变量 + +有一个**特殊的**环境变量称为 **`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` + +安装 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` 环境变量 (在 Python 安装程序中，这个操作是名为 `Add Python x.xx to 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)时，这些信息将会很有用。 + +## 结论 + +通过这个教程，你应该对**环境变量**是什么以及如何在 Python 中使用它们有了基本的了解。 + +你也可以在环境变量 - 维基百科 (Wikipedia for Environment Variable) 中了解更多关于它们的信息。 + +在许多情况下，环境变量的用途和适用性并不是很明显。但是在开发过程中，它们会在许多不同的场景中出现，因此了解它们是很有必要的。 + +例如，你将在下一节关于[虚拟环境](virtual-environments.md)中需要这些信息。 diff --git a/docs/zh/docs/fastapi-cli.md b/docs/zh/docs/fastapi-cli.md index 00235bd02..f532c7fb7 100644 --- a/docs/zh/docs/fastapi-cli.md +++ b/docs/zh/docs/fastapi-cli.md @@ -80,7 +80,7 @@ FastAPI CLI 接收你的 Python 程序路径，自动检测包含 FastAPI 的变 在大多数情况下，你会（且应该）有一个“终止代理”在上层为你处理 HTTPS，这取决于你如何部署应用程序，你的服务提供商可能会为你处理此事，或者你可能需要自己设置。 -/// tip | "提示" +/// tip | 提示 你可以在 [deployment documentation](deployment/index.md){.internal-link target=_blank} 获得更多信息。 diff --git a/docs/zh/docs/help-fastapi.md b/docs/zh/docs/help-fastapi.md index fc47ed89d..09f37a44b 100644 --- a/docs/zh/docs/help-fastapi.md +++ b/docs/zh/docs/help-fastapi.md @@ -108,7 +108,7 @@ 快加入 👥 Discord 聊天服务器 👥 和 FastAPI 社区里的小伙伴一起哈皮吧。 -/// tip | "提示" +/// tip | 提示 如有问题，请在 GitHub Issues 里提问，在这里更容易得到 [FastAPI 专家](fastapi-people.md#_3){.internal-link target=_blank}的帮助。 diff --git a/docs/zh/docs/tutorial/background-tasks.md b/docs/zh/docs/tutorial/background-tasks.md index fc9312bc5..40e61add7 100644 --- a/docs/zh/docs/tutorial/background-tasks.md +++ b/docs/zh/docs/tutorial/background-tasks.md @@ -15,9 +15,7 @@ 首先导入 `BackgroundTasks` 并在 *路径操作函数* 中使用类型声明 `BackgroundTasks` 定义一个参数： -```Python hl_lines="1 13" -{!../../docs_src/background_tasks/tutorial001.py!} -``` +{* ../../docs_src/background_tasks/tutorial001.py hl[1, 13] *} **FastAPI** 会创建一个 `BackgroundTasks` 类型的对象并作为该参数传入。 @@ -33,17 +31,13 @@ 由于写操作不使用 `async` 和 `await`，我们用普通的 `def` 定义函数： -```Python hl_lines="6-9" -{!../../docs_src/background_tasks/tutorial001.py!} -``` +{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *} ## 添加后台任务 在你的 *路径操作函数* 里，用 `.add_task()` 方法将任务函数传到 *后台任务* 对象中： -```Python hl_lines="14" -{!../../docs_src/background_tasks/tutorial001.py!} -``` +{* ../../docs_src/background_tasks/tutorial001.py hl[14] *} `.add_task()` 接收以下参数： @@ -59,25 +53,19 @@ //// tab | Python 3.10+ -```Python hl_lines="13 15 22 25" -{!> ../../docs_src/background_tasks/tutorial002_an_py310.py!} -``` +{* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13, 15, 22, 25] *} //// //// tab | Python 3.9+ -```Python hl_lines="13 15 22 25" -{!> ../../docs_src/background_tasks/tutorial002_an_py39.py!} -``` +{* ../../docs_src/background_tasks/tutorial002_an_py39.py hl[13, 15, 22, 25] *} //// //// tab | Python 3.8+ -```Python hl_lines="14 16 23 26" -{!> ../../docs_src/background_tasks/tutorial002_an.py!} -``` +{* ../../docs_src/background_tasks/tutorial002_an.py hl[14, 16, 23, 26] *} //// @@ -89,9 +77,7 @@ /// -```Python hl_lines="11 13 20 23" -{!> ../../docs_src/background_tasks/tutorial002_py310.py!} -``` +{* ../../docs_src/background_tasks/tutorial002_py310.py hl[11, 13, 20, 23] *} //// @@ -103,9 +89,7 @@ /// -```Python hl_lines="13 15 22 25" -{!> ../../docs_src/background_tasks/tutorial002.py!} -``` +{* ../../docs_src/background_tasks/tutorial002.py hl[13, 15, 22, 25] *} //// @@ -133,8 +117,6 @@ 它们往往需要更复杂的配置，即消息/作业队列管理器，如RabbitMQ或Redis，但它们允许您在多个进程中运行后台任务，甚至是在多个服务器中。 -要查看示例，查阅 [Project Generators](../project-generation.md){.internal-link target=_blank}，它们都包括已经配置的Celery。 - 但是，如果您需要从同一个**FastAPI**应用程序访问变量和对象，或者您需要执行小型后台任务（如发送电子邮件通知），您只需使用 `BackgroundTasks` 即可。 ## 回顾 diff --git a/docs/zh/docs/tutorial/bigger-applications.md b/docs/zh/docs/tutorial/bigger-applications.md index 64afd99af..318e10fd7 100644 --- a/docs/zh/docs/tutorial/bigger-applications.md +++ b/docs/zh/docs/tutorial/bigger-applications.md @@ -414,7 +414,7 @@ from .routers.users import router 它将包含来自该路由器的所有路由作为其一部分。 -/// note | "技术细节" +/// note | 技术细节 实际上，它将在内部为声明在 `APIRouter` 中的每个*路径操作*创建一个*路径操作*。 @@ -477,7 +477,7 @@ from .routers.users import router 它将与通过 `app.include_router()` 添加的所有其他*路径操作*一起正常运行。 -/// info | "特别的技术细节" +/// info | 特别的技术细节 **注意**：这是一个非常技术性的细节，你也许可以**直接跳过**。 diff --git a/docs/zh/docs/tutorial/body-fields.md b/docs/zh/docs/tutorial/body-fields.md index ac59d7e6a..9aeb481ef 100644 --- a/docs/zh/docs/tutorial/body-fields.md +++ b/docs/zh/docs/tutorial/body-fields.md @@ -58,7 +58,7 @@ //// -/// warning | "警告" +/// warning | 警告 注意，与从 `fastapi` 导入 `Query`，`Path`、`Body` 不同，要直接从 `pydantic` 导入 `Field` 。 @@ -122,7 +122,7 @@ Prefer to use the `Annotated` version if possible. `Field` 的工作方式和 `Query`、`Path`、`Body` 相同，参数也相同。 -/// note | "技术细节" +/// note | 技术细节 实际上，`Query`、`Path` 都是 `Params` 的子类，而 `Params` 类又是 Pydantic 中 `FieldInfo` 的子类。 @@ -134,7 +134,7 @@ Pydantic 的 `Field` 返回也是 `FieldInfo` 的类实例。 /// -/// tip | "提示" +/// tip | 提示 注意，模型属性的类型、默认值及 `Field` 的代码结构与*路径操作函数*的参数相同，只不过是用 `Field` 替换了`Path`、`Query`、`Body`。 diff --git a/docs/zh/docs/tutorial/body-updates.md b/docs/zh/docs/tutorial/body-updates.md index 5e9008d6a..9372e1dfd 100644 --- a/docs/zh/docs/tutorial/body-updates.md +++ b/docs/zh/docs/tutorial/body-updates.md @@ -34,7 +34,7 @@ 即，只发送要更新的数据，其余数据保持不变。 -/// note | "笔记" +/// note | 笔记 `PATCH` 没有 `PUT` 知名，也怎么不常用。 @@ -89,14 +89,14 @@ {!../../docs_src/body_updates/tutorial002.py!} ``` -/// tip | "提示" +/// tip | 提示 实际上，HTTP `PUT` 也可以完成相同的操作。 但本节以 `PATCH` 为例的原因是，该操作就是为了这种用例创建的。 /// -/// note | "笔记" +/// note | 笔记 注意，输入模型仍需验证。 diff --git a/docs/zh/docs/tutorial/body.md b/docs/zh/docs/tutorial/body.md index 67a7f28e0..bf3117beb 100644 --- a/docs/zh/docs/tutorial/body.md +++ b/docs/zh/docs/tutorial/body.md @@ -8,7 +8,7 @@ API 基本上肯定要发送**响应体**，但是客户端不一定发送**请 使用 Pydantic 模型声明**请求体**，能充分利用它的功能和优点。 -/// info | "说明" +/// info | 说明 发送数据使用 `POST`（最常用）、`PUT`、`DELETE`、`PATCH` 等操作。 @@ -149,7 +149,7 @@ Pydantic 模型的 JSON 概图是 OpenAPI 生成的概图部件，可在 API 文 -/// tip | "提示" +/// tip | 提示 使用 PyCharm 编辑器时，推荐安装 Pydantic PyCharm 插件。 @@ -233,7 +233,7 @@ Pydantic 模型的 JSON 概图是 OpenAPI 生成的概图部件，可在 API 文 - 类型是（`int`、`float`、`str`、`bool` 等）**单类型**的参数，是**查询**参数 - 类型是 **Pydantic 模型**的参数，是**请求体** -/// note | "笔记" +/// note | 笔记 因为默认值是 `None`， FastAPI 会把 `q` 当作可选参数。 diff --git a/docs/zh/docs/tutorial/cookie-params.md b/docs/zh/docs/tutorial/cookie-params.md index b01c28238..762dca766 100644 --- a/docs/zh/docs/tutorial/cookie-params.md +++ b/docs/zh/docs/tutorial/cookie-params.md @@ -117,7 +117,7 @@ //// -/// note | "技术细节" +/// note | 技术细节 `Cookie` 、`Path` 、`Query` 是**兄弟类**，都继承自共用的 `Param` 类。 @@ -125,7 +125,7 @@ /// -/// info | "说明" +/// info | 说明 必须使用 `Cookie` 声明 cookie 参数，否则该参数会被解释为查询参数。 diff --git a/docs/zh/docs/tutorial/cors.md b/docs/zh/docs/tutorial/cors.md index 1166d5c97..84c435c97 100644 --- a/docs/zh/docs/tutorial/cors.md +++ b/docs/zh/docs/tutorial/cors.md @@ -78,7 +78,7 @@ 更多关于 CORS 的信息，请查看 Mozilla CORS 文档。 -/// note | "技术细节" +/// note | 技术细节 你也可以使用 `from starlette.middleware.cors import CORSMiddleware`。 diff --git a/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md index c7cfe0531..c202c977b 100644 --- a/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md +++ b/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md @@ -20,7 +20,7 @@ 路径操作装饰器依赖项（以下简称为**“路径装饰器依赖项”**）的执行或解析方式和普通依赖项一样，但就算这些依赖项会返回值，它们的值也不会传递给*路径操作函数*。 -/// tip | "提示" +/// tip | 提示 有些编辑器会检查代码中没使用过的函数参数，并显示错误提示。 @@ -30,7 +30,7 @@ /// -/// info | "说明" +/// info | 说明 本例中，使用的是自定义响应头 `X-Key` 和 `X-Token`。 diff --git a/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md index a30313719..792b6784d 100644 --- a/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md +++ b/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md @@ -10,7 +10,7 @@ FastAPI支持在完成后执行一些上下文管理器完成的。 diff --git a/docs/zh/docs/tutorial/dependencies/index.md b/docs/zh/docs/tutorial/dependencies/index.md index b039e1654..e0d2c5f70 100644 --- a/docs/zh/docs/tutorial/dependencies/index.md +++ b/docs/zh/docs/tutorial/dependencies/index.md @@ -75,7 +75,7 @@ FastAPI 提供了简单易用，但功能强大的** read_users 这样，只编写一次代码，**FastAPI** 就可以为多个*路径操作*共享这段代码 。 -/// check | "检查" +/// check | 检查 注意，无需创建专门的类，并将之传递给 **FastAPI** 以进行「注册」或执行类似的操作。 @@ -118,7 +118,7 @@ common_parameters --> read_users 上述这些操作都是可行的，**FastAPI** 知道该怎么处理。 -/// note | "笔记" +/// note | 笔记 如里不了解异步，请参阅[异步：*“着急了？”*](../../async.md){.internal-link target=_blank} 一章中 `async` 和 `await` 的内容。 diff --git a/docs/zh/docs/tutorial/dependencies/sub-dependencies.md b/docs/zh/docs/tutorial/dependencies/sub-dependencies.md index dd4c60857..e0b75aa0c 100644 --- a/docs/zh/docs/tutorial/dependencies/sub-dependencies.md +++ b/docs/zh/docs/tutorial/dependencies/sub-dependencies.md @@ -41,7 +41,7 @@ FastAPI 支持创建含**子依赖项**的依赖项。 {!../../docs_src/dependencies/tutorial005.py!} ``` -/// info | "信息" +/// info | 信息 注意，这里在*路径操作函数*中只声明了一个依赖项，即 `query_or_cookie_extractor` 。 @@ -81,7 +81,7 @@ async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False 但它依然非常强大，能够声明任意嵌套深度的「图」或树状的依赖结构。 -/// tip | "提示" +/// tip | 提示 这些简单的例子现在看上去虽然没有什么实用价值， diff --git a/docs/zh/docs/tutorial/extra-models.md b/docs/zh/docs/tutorial/extra-models.md index 6649b06c7..982cf15fb 100644 --- a/docs/zh/docs/tutorial/extra-models.md +++ b/docs/zh/docs/tutorial/extra-models.md @@ -8,7 +8,7 @@ * **输出模型**不应含密码 * **数据库模型**需要加密的密码 -/// danger | "危险" +/// danger | 危险 千万不要存储用户的明文密码。始终存储可以进行验证的**安全哈希值**。 @@ -146,7 +146,7 @@ UserInDB( ) ``` -/// warning | "警告" +/// warning | 警告 辅助的附加函数只是为了演示可能的数据流，但它们显然不能提供任何真正的安全机制。 @@ -194,7 +194,7 @@ FastAPI 可以做得更好。 为此，请使用 Python 标准类型提示 `typing.Union`： -/// note | "笔记" +/// note | 笔记 定义 `Union` 类型时，要把详细的类型写在前面，然后是不太详细的类型。下例中，更详细的 `PlaneItem` 位于 `Union[PlaneItem，CarItem]` 中的 `CarItem` 之前。 diff --git a/docs/zh/docs/tutorial/first-steps.md b/docs/zh/docs/tutorial/first-steps.md index b9bbca193..2f573501c 100644 --- a/docs/zh/docs/tutorial/first-steps.md +++ b/docs/zh/docs/tutorial/first-steps.md @@ -140,7 +140,7 @@ OpenAPI 为你的 API 定义 API 模式。该模式中包含了你的 API 发送 `FastAPI` 是一个为你的 API 提供了所有功能的 Python 类。 -/// note | "技术细节" +/// note | 技术细节 `FastAPI` 是直接从 `Starlette` 继承的类。 @@ -260,7 +260,7 @@ https://example.com/items/foo * 请求路径为 `/` * 使用 get 操作 -/// info | "`@decorator` Info" +/// info | `@decorator` Info `@something` 语法在 Python 中被称为「装饰器」。 diff --git a/docs/zh/docs/tutorial/handling-errors.md b/docs/zh/docs/tutorial/handling-errors.md index 0820c363c..799e81eb2 100644 --- a/docs/zh/docs/tutorial/handling-errors.md +++ b/docs/zh/docs/tutorial/handling-errors.md @@ -67,7 +67,7 @@ ``` -/// tip | "提示" +/// tip | 提示 触发 `HTTPException` 时，可以用参数 `detail` 传递任何能转换为 JSON 的值，不仅限于 `str`。 @@ -116,7 +116,7 @@ ``` -/// note | "技术细节" +/// note | 技术细节 `from starlette.requests import Request` 和 `from starlette.responses import JSONResponse` 也可以用于导入 `Request` 和 `JSONResponse`。 @@ -176,7 +176,7 @@ path -> item_id ### `RequestValidationError` vs `ValidationError` -/// warning | "警告" +/// warning | 警告 如果您觉得现在还用不到以下技术细节，可以先跳过下面的内容。 @@ -203,7 +203,7 @@ path -> item_id ``` -/// note | "技术细节" +/// note | 技术细节 还可以使用 `from starlette.responses import PlainTextResponse`。 diff --git a/docs/zh/docs/tutorial/header-params.md b/docs/zh/docs/tutorial/header-params.md index 4de8bf4df..c45a6b095 100644 --- a/docs/zh/docs/tutorial/header-params.md +++ b/docs/zh/docs/tutorial/header-params.md @@ -116,7 +116,7 @@ //// -/// note | "技术细节" +/// note | 技术细节 `Header` 是 `Path`、`Query`、`Cookie` 的**兄弟类**，都继承自共用的 `Param` 类。 @@ -124,7 +124,7 @@ /// -/// info | "说明" +/// info | 说明 必须使用 `Header` 声明 header 参数，否则该参数会被解释为查询参数。 @@ -198,7 +198,7 @@ //// -/// warning | "警告" +/// warning | 警告 注意，使用 `convert_underscores = False` 要慎重，有些 HTTP 代理和服务器不支持使用带有下划线的请求头。 diff --git a/docs/zh/docs/tutorial/metadata.md b/docs/zh/docs/tutorial/metadata.md index 7252db9f6..2398f3e01 100644 --- a/docs/zh/docs/tutorial/metadata.md +++ b/docs/zh/docs/tutorial/metadata.md @@ -46,7 +46,7 @@ 注意你可以在描述内使用 Markdown，例如「login」会显示为粗体（**login**）以及「fancy」会显示为斜体（_fancy_）。 -/// tip | "提示" +/// tip | 提示 不必为你使用的所有标签都添加元数据。 @@ -60,7 +60,7 @@ {!../../docs_src/metadata/tutorial004.py!} ``` -/// info | "信息" +/// info | 信息 阅读更多关于标签的信息[路径操作配置](path-operation-configuration.md#tags){.internal-link target=_blank}。 diff --git a/docs/zh/docs/tutorial/middleware.md b/docs/zh/docs/tutorial/middleware.md index fb2874ba3..8076f8d52 100644 --- a/docs/zh/docs/tutorial/middleware.md +++ b/docs/zh/docs/tutorial/middleware.md @@ -11,7 +11,7 @@ * 它可以对该**响应**做些什么或者执行任何需要的代码. * 然后它返回这个 **响应**. -/// note | "技术细节" +/// note | 技术细节 如果你使用了 `yield` 关键字依赖, 依赖中的退出代码将在执行中间件*后*执行. @@ -43,7 +43,7 @@ /// -/// note | "技术细节" +/// note | 技术细节 你也可以使用 `from starlette.requests import Request`. diff --git a/docs/zh/docs/tutorial/path-operation-configuration.md b/docs/zh/docs/tutorial/path-operation-configuration.md index 12e1f24ba..add370d1c 100644 --- a/docs/zh/docs/tutorial/path-operation-configuration.md +++ b/docs/zh/docs/tutorial/path-operation-configuration.md @@ -2,7 +2,7 @@ *路径操作装饰器*支持多种配置参数。 -/// warning | "警告" +/// warning | 警告 注意：以下参数应直接传递给**路径操作装饰器**，不能传递给*路径操作函数*。 @@ -22,7 +22,7 @@ 状态码在响应中使用，并会被添加到 OpenAPI 概图。 -/// note | "技术细节" +/// note | 技术细节 也可以使用 `from starlette import status` 导入状态码。 @@ -72,13 +72,13 @@ OpenAPI 概图会自动添加标签，供 API 文档接口使用： {!../../docs_src/path_operation_configuration/tutorial005.py!} ``` -/// info | "说明" +/// info | 说明 注意，`response_description` 只用于描述响应，`description` 一般则用于描述*路径操作*。 /// -/// check | "检查" +/// check | 检查 OpenAPI 规定每个*路径操作*都要有响应描述。 diff --git a/docs/zh/docs/tutorial/path-params-numeric-validations.md b/docs/zh/docs/tutorial/path-params-numeric-validations.md index 29197ac53..3a1ebdbca 100644 --- a/docs/zh/docs/tutorial/path-params-numeric-validations.md +++ b/docs/zh/docs/tutorial/path-params-numeric-validations.md @@ -222,7 +222,7 @@ Python 不会对该 `*` 做任何事情，但是它将知道之后的所有参 /// -/// note | "技术细节" +/// note | 技术细节 当你从 `fastapi` 导入 `Query`、`Path` 和其他同类对象时，它们实际上是函数。 diff --git a/docs/zh/docs/tutorial/path-params.md b/docs/zh/docs/tutorial/path-params.md index a29ee0e2b..0666783e2 100644 --- a/docs/zh/docs/tutorial/path-params.md +++ b/docs/zh/docs/tutorial/path-params.md @@ -24,7 +24,7 @@ FastAPI 支持使用 Python 字符串格式化语法声明**路径参数**（** 本例把 `item_id` 的类型声明为 `int`。 -/// check | "检查" +/// check | 检查 类型声明将为函数提供错误检查、代码补全等编辑器支持。 @@ -38,7 +38,7 @@ FastAPI 支持使用 Python 字符串格式化语法声明**路径参数**（** {"item_id":3} ``` -/// check | "检查" +/// check | 检查 注意，函数接收并返回的值是 `3`（ `int`），不是 `"3"`（`str`）。 @@ -69,7 +69,7 @@ FastAPI 支持使用 Python 字符串格式化语法声明**路径参数**（** 值的类型不是 `int ` 而是浮点数（`float`）时也会显示同样的错误，比如： http://127.0.0.1:8000/items/4.2。 -/// check | "检查" +/// check | 检查 **FastAPI** 使用 Python 类型声明实现了数据校验。 @@ -85,7 +85,7 @@ FastAPI 支持使用 Python 字符串格式化语法声明**路径参数**（** -/// check | "检查" +/// check | 检查 还是使用 Python 类型声明，**FastAPI** 提供了（集成 Swagger UI 的）API 文档。 @@ -143,13 +143,13 @@ FastAPI 充分地利用了 枚举（即 enums）。 /// -/// tip | "提示" +/// tip | 提示 **AlexNet**、**ResNet**、**LeNet** 是机器学习模型。 @@ -189,7 +189,7 @@ Python 3.4 及之后版本支持`python-multipart`。 @@ -28,7 +28,7 @@ FastAPI 支持同时使用 `File` 和 `Form` 定义文件和表单字段。 声明文件可以使用 `bytes` 或 `UploadFile` 。 -/// warning | "警告" +/// warning | 警告 可在一个*路径操作*中声明多个 `File` 与 `Form` 参数，但不能同时声明要接收 JSON 的 `Body` 字段。因为此时请求体的编码为 `multipart/form-data`，不是 `application/json`。 diff --git a/docs/zh/docs/tutorial/request-forms.md b/docs/zh/docs/tutorial/request-forms.md index 94c8839b3..5938bb83d 100644 --- a/docs/zh/docs/tutorial/request-forms.md +++ b/docs/zh/docs/tutorial/request-forms.md @@ -2,7 +2,7 @@ 接收的不是 JSON，而是表单字段时，要使用 `Form`。 -/// info | "说明" +/// info | 说明 要使用表单，需预先安装 `python-multipart`。 @@ -32,13 +32,13 @@ 使用 `Form` 可以声明与 `Body` （及 `Query`、`Path`、`Cookie`）相同的元数据和验证。 -/// info | "说明" +/// info | 说明 `Form` 是直接继承自 `Body` 的类。 /// -/// tip | "提示" +/// tip | 提示 声明表单体要显式使用 `Form` ，否则，FastAPI 会把该参数当作查询参数或请求体（JSON）参数。 @@ -50,7 +50,7 @@ **FastAPI** 要确保从正确的位置读取数据，而不是读取 JSON。 -/// note | "技术细节" +/// note | 技术细节 表单数据的「媒体类型」编码一般为 `application/x-www-form-urlencoded`。 @@ -60,7 +60,7 @@ /// -/// warning | "警告" +/// warning | 警告 可在一个*路径操作*中声明多个 `Form` 参数，但不能同时声明要接收 JSON 的 `Body` 字段。因为此时请求体的编码是 `application/x-www-form-urlencoded`，不是 `application/json`。 diff --git a/docs/zh/docs/tutorial/response-model.md b/docs/zh/docs/tutorial/response-model.md index 40fb40720..fd0facca8 100644 --- a/docs/zh/docs/tutorial/response-model.md +++ b/docs/zh/docs/tutorial/response-model.md @@ -51,7 +51,7 @@ FastAPI 将使用此 `response_model` 来： * 会将输出数据限制在该模型定义内。下面我们会看到这一点有多重要。 -/// note | "技术细节" +/// note | 技术细节 响应模型在参数中被声明，而不是作为函数返回类型的注解，这是因为路径函数可能不会真正返回该响应模型，而是返回一个 `dict`、数据库对象或其他模型，然后再使用 `response_model` 来执行字段约束和序列化。 diff --git a/docs/zh/docs/tutorial/response-status-code.md b/docs/zh/docs/tutorial/response-status-code.md index 55bf502ae..1e5e7964f 100644 --- a/docs/zh/docs/tutorial/response-status-code.md +++ b/docs/zh/docs/tutorial/response-status-code.md @@ -12,7 +12,7 @@ {!../../docs_src/response_status_code/tutorial001.py!} ``` -/// note | "笔记" +/// note | 笔记 注意，`status_code` 是（`get`、`post` 等）**装饰器**方法中的参数。与之前的参数和请求体不同，不是*路径操作函数*的参数。 @@ -20,7 +20,7 @@ `status_code` 参数接收表示 HTTP 状态码的数字。 -/// info | "说明" +/// info | 说明 `status_code` 还能接收 `IntEnum` 类型，比如 Python 的 `http.HTTPStatus`。 @@ -33,7 +33,7 @@ -/// note | "笔记" +/// note | 笔记 某些响应状态码表示响应没有响应体（参阅下一章）。 @@ -43,7 +43,7 @@ FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。 ## 关于 HTTP 状态码 -/// note | "笔记" +/// note | 笔记 如果已经了解 HTTP 状态码，请跳到下一章。 @@ -66,7 +66,7 @@ FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。 * 对于来自客户端的一般错误，可以只使用 `400` * `500` 及以上的状态码用于表示服务器端错误。几乎永远不会直接使用这些状态码。应用代码或服务器出现问题时，会自动返回这些状态代码 -/// tip | "提示" +/// tip | 提示 状态码及适用场景的详情，请参阅 MDN 的 HTTP 状态码文档。 @@ -94,7 +94,7 @@ FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。 -/// note | "技术细节" +/// note | 技术细节 也可以使用 `from starlette import status`。 diff --git a/docs/zh/docs/tutorial/security/first-steps.md b/docs/zh/docs/tutorial/security/first-steps.md index 8294b6444..561721f6e 100644 --- a/docs/zh/docs/tutorial/security/first-steps.md +++ b/docs/zh/docs/tutorial/security/first-steps.md @@ -52,7 +52,7 @@ ## 运行 -/// info | "说明" +/// info | 说明 先安装 `python-multipart`。 @@ -82,7 +82,7 @@ $ uvicorn main:app --reload -/// check | "Authorize 按钮！" +/// check | Authorize 按钮！ 页面右上角出现了一个「**Authorize**」按钮。 @@ -94,7 +94,7 @@ $ uvicorn main:app --reload -/// note | "笔记" +/// note | 笔记 目前，在表单中输入内容不会有任何反应，后文会介绍相关内容。 @@ -140,7 +140,7 @@ OAuth2 的设计目标是为了让后端或 API 独立于服务器验证用户 本例使用 **OAuth2** 的 **Password** 流以及 **Bearer** 令牌（`Token`）。为此要使用 `OAuth2PasswordBearer` 类。 -/// info | "说明" +/// info | 说明 `Bearer` 令牌不是唯一的选择。 @@ -158,7 +158,7 @@ OAuth2 的设计目标是为了让后端或 API 独立于服务器验证用户 {!../../docs_src/security/tutorial001.py!} ``` -/// tip | "提示" +/// tip | 提示 在此，`tokenUrl="token"` 指向的是暂未创建的相对 URL `token`。这个相对 URL 相当于 `./token`。 @@ -172,7 +172,7 @@ OAuth2 的设计目标是为了让后端或 API 独立于服务器验证用户 接下来，学习如何创建实际的路径操作。 -/// info | "说明" +/// info | 说明 严苛的 **Pythonista** 可能不喜欢用 `tokenUrl` 这种命名风格代替 `token_url`。 @@ -202,7 +202,7 @@ oauth2_scheme(some, parameters) **FastAPI** 使用依赖项在 OpenAPI 概图（及 API 文档）中定义**安全方案**。 -/// info | "技术细节" +/// info | 技术细节 **FastAPI** 使用（在依赖项中声明的）类 `OAuth2PasswordBearer` 在 OpenAPI 中定义安全方案，这是因为它继承自 `fastapi.security.oauth2.OAuth2`，而该类又是继承自`fastapi.security.base.SecurityBase`。 diff --git a/docs/zh/docs/tutorial/security/get-current-user.md b/docs/zh/docs/tutorial/security/get-current-user.md index 97461817a..e0f763b30 100644 --- a/docs/zh/docs/tutorial/security/get-current-user.md +++ b/docs/zh/docs/tutorial/security/get-current-user.md @@ -55,7 +55,7 @@ 这有助于在函数内部使用代码补全和类型检查。 -/// tip | "提示" +/// tip | 提示 还记得请求体也是使用 Pydantic 模型声明的吧。 @@ -63,7 +63,7 @@ /// -/// check | "检查" +/// check | 检查 依赖系统的这种设计方式可以支持不同的依赖项返回同一个 `User` 模型。 diff --git a/docs/zh/docs/tutorial/security/oauth2-jwt.md b/docs/zh/docs/tutorial/security/oauth2-jwt.md index 8e497b844..4bb6e6318 100644 --- a/docs/zh/docs/tutorial/security/oauth2-jwt.md +++ b/docs/zh/docs/tutorial/security/oauth2-jwt.md @@ -40,7 +40,7 @@ $ pip install pyjwt -/// info | "说明" +/// info | 说明 如果您打算使用类似 RSA 或 ECDSA 的数字签名算法，您应该安装加密库依赖项 `pyjwt[crypto]`。 @@ -82,7 +82,7 @@ $ pip install passlib[bcrypt] -/// tip | "提示" +/// tip | 提示 `passlib` 甚至可以读取 Django、Flask 的安全插件等工具创建的密码。 @@ -98,7 +98,7 @@ $ pip install passlib[bcrypt] 创建用于密码哈希和身份校验的 PassLib **上下文**。 -/// tip | "提示" +/// tip | 提示 PassLib 上下文还支持使用不同哈希算法的功能，包括只能校验的已弃用旧算法等。 @@ -166,7 +166,7 @@ Prefer to use the `Annotated` version if possible. //// -/// note | "笔记" +/// note | 笔记 查看新的（伪）数据库 `fake_users_db`，就能看到哈希后的密码：`"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`。 @@ -358,7 +358,7 @@ JWT 规范还包括 `sub` 键，值是令牌的主题。 用户名: `johndoe` 密码: `secret` -/// check | "检查" +/// check | 检查 注意，代码中没有明文密码**`secret`**，只保存了它的哈希值。 @@ -383,7 +383,7 @@ JWT 规范还包括 `sub` 键，值是令牌的主题。 -/// note | "笔记" +/// note | 笔记 注意，请求中 `Authorization` 响应头的值以 `Bearer` 开头。 diff --git a/docs/zh/docs/tutorial/security/simple-oauth2.md b/docs/zh/docs/tutorial/security/simple-oauth2.md index 1f031a6b2..8ce9263db 100644 --- a/docs/zh/docs/tutorial/security/simple-oauth2.md +++ b/docs/zh/docs/tutorial/security/simple-oauth2.md @@ -32,7 +32,7 @@ OAuth2 还支持客户端发送**`scope`**表单字段。 * 脸书和 Instagram 使用 `instagram_basic` * 谷歌使用 `https://www.googleapis.com/auth/drive` -/// info | "说明" +/// info | 说明 OAuth2 中，**作用域**只是声明指定权限的字符串。 @@ -63,7 +63,7 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。 * 可选的 `scope` 字段，由多个空格分隔的字符串组成的长字符串 * 可选的 `grant_type` -/// tip | "提示" +/// tip | 提示 实际上，OAuth2 规范*要求* `grant_type` 字段使用固定值 `password`，但 `OAuth2PasswordRequestForm` 没有作强制约束。 @@ -74,7 +74,7 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。 * 可选的 `client_id`（本例未使用） * 可选的 `client_secret`（本例未使用） -/// info | "说明" +/// info | 说明 `OAuth2PasswordRequestForm` 与 `OAuth2PasswordBearer` 一样，都不是 FastAPI 的特殊类。 @@ -88,7 +88,7 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。 ### 使用表单数据 -/// tip | "提示" +/// tip | 提示 `OAuth2PasswordRequestForm` 类依赖项的实例没有以空格分隔的长字符串属性 `scope`，但它支持 `scopes` 属性，由已发送的 scope 字符串列表组成。 @@ -150,7 +150,7 @@ UserInDB( ) ``` -/// info | "说明" +/// info | 说明 `user_dict` 的说明，详见[**更多模型**一章](../extra-models.md#user_indict){.internal-link target=_blank}。 @@ -166,7 +166,7 @@ UserInDB( 本例只是简单的演示，返回的 Token 就是 `username`，但这种方式极不安全。 -/// tip | "提示" +/// tip | 提示 下一章介绍使用哈希密码和 JWT Token 的真正安全机制。 @@ -178,7 +178,7 @@ UserInDB( {!../../docs_src/security/tutorial003.py!} ``` -/// tip | "提示" +/// tip | 提示 按规范的要求，应像本示例一样，返回带有 `access_token` 和 `token_type` 的 JSON 对象。 @@ -206,7 +206,7 @@ UserInDB( {!../../docs_src/security/tutorial003.py!} ``` -/// info | "说明" +/// info | 说明 此处返回值为 `Bearer` 的响应头 `WWW-Authenticate` 也是规范的一部分。 diff --git a/docs/zh/docs/tutorial/sql-databases.md b/docs/zh/docs/tutorial/sql-databases.md index 379c44143..06b373e6d 100644 --- a/docs/zh/docs/tutorial/sql-databases.md +++ b/docs/zh/docs/tutorial/sql-databases.md @@ -167,7 +167,7 @@ connect_args={"check_same_thread": False} ...仅用于`SQLite`，在其他数据库不需要它。 -/// info | "技术细节" +/// info | 技术细节 默认情况下，SQLite 只允许一个线程与其通信，假设有多个线程的话，也只将处理一个独立的请求。 @@ -630,7 +630,7 @@ SQLAlchemy 模型`User`包含一个`hashed_password`，它应该是一个包含 //// -/// info | "技术细节" +/// info | 技术细节 参数`db`实际上是 type `SessionLocal`，但是这个类（用 创建`sessionmaker()`）是 SQLAlchemy 的“代理” `Session`，所以，编辑器并不真正知道提供了哪些方法。 @@ -713,7 +713,7 @@ def read_user(user_id: int, db: Session = Depends(get_db)): /// -/// note | "Very Technical Details" +/// note | Very Technical Details 如果您很好奇并且拥有深厚的技术知识，您可以在[Async](https://fastapi.tiangolo.com/zh/async/#very-technical-details)文档中查看有关如何处理 `async def`于`def`差别的技术细节。 diff --git a/docs/zh/docs/tutorial/static-files.md b/docs/zh/docs/tutorial/static-files.md index 37e90ad43..7580f731b 100644 --- a/docs/zh/docs/tutorial/static-files.md +++ b/docs/zh/docs/tutorial/static-files.md @@ -11,7 +11,7 @@ {!../../docs_src/static_files/tutorial001.py!} ``` -/// note | "技术细节" +/// note | 技术细节 你也可以用 `from starlette.staticfiles import StaticFiles`。 diff --git a/docs/zh/docs/tutorial/testing.md b/docs/zh/docs/tutorial/testing.md index 173e6f8a6..bb3ef8a6a 100644 --- a/docs/zh/docs/tutorial/testing.md +++ b/docs/zh/docs/tutorial/testing.md @@ -8,7 +8,7 @@ ## 使用 `TestClient` -/// info | "信息" +/// info | 信息 要使用 `TestClient`，先要安装 `httpx`. @@ -30,7 +30,7 @@ {!../../docs_src/app_testing/tutorial001.py!} ``` -/// tip | "提示" +/// tip | 提示 注意测试函数是普通的 `def`，不是 `async def`。 @@ -40,7 +40,7 @@ /// -/// note | "技术细节" +/// note | 技术细节 你也可以用 `from starlette.testclient import TestClient`。 @@ -48,7 +48,7 @@ /// -/// tip | "提示" +/// tip | 提示 除了发送请求之外，如果你还想测试时在FastAPI应用中调用 `async` 函数（例如异步数据库函数）， 可以在高级教程中看下 [Async Tests](../advanced/async-tests.md){.internal-link target=_blank} 。 @@ -148,7 +148,7 @@ //// tab | Python 3.10+ non-Annotated -/// tip | "提示" +/// tip | 提示 Prefer to use the `Annotated` version if possible. @@ -162,7 +162,7 @@ Prefer to use the `Annotated` version if possible. //// tab | Python 3.8+ non-Annotated -/// tip | "提示" +/// tip | 提示 Prefer to use the `Annotated` version if possible. @@ -196,7 +196,7 @@ Prefer to use the `Annotated` version if possible. 关于如何传数据给后端的更多信息 (使用`httpx` 或 `TestClient`)，请查阅 HTTPX 文档. -/// info | "信息" +/// info | 信息 注意 `TestClient` 接收可以被转化为JSON的数据，而不是Pydantic模型。 diff --git a/docs/zh/docs/virtual-environments.md b/docs/zh/docs/virtual-environments.md new file mode 100644 index 000000000..9b3c0340a --- /dev/null +++ b/docs/zh/docs/virtual-environments.md @@ -0,0 +1,844 @@ +# 虚拟环境 + +当你在 Python 工程中工作时，你可能会有必要用到一个**虚拟环境**（或类似的机制）来隔离你为每个工程安装的包。 + +/// info + +如果你已经了解虚拟环境，知道如何创建和使用它们，你可以考虑跳过这一部分。🤓 + +/// + +/// tip + +**虚拟环境**和**环境变量**是不同的。 + +**环境变量**是系统中的一个变量，可以被程序使用。 + +**虚拟环境**是一个包含一些文件的目录。 + +/// + +/// info + +这个页面将教你如何使用**虚拟环境**以及了解它们的工作原理。 + +如果你计划使用一个**可以为你管理一切的工具**（包括安装 Python），试试 uv。 + +/// + +## 创建一个工程 + +首先，为你的工程创建一个目录。 + +我 (指原作者 —— 译者注) 通常会在我的主目录下创建一个名为 `code` 的目录。 + +在这个目录下，我再为每个工程创建一个目录。 + +
+ +```console +// 进入主目录 +$ cd +// 创建一个用于存放所有代码工程的目录 +$ mkdir code +// 进入 code 目录 +$ cd code +// 创建一个用于存放这个工程的目录 +$ mkdir awesome-project +// 进入这个工程的目录 +$ cd awesome-project +``` + +
+ +## 创建一个虚拟环境 + +在开始一个 Python 工程的**第一时间**，**在你的工程内部**创建一个虚拟环境。 + +/// tip + +你只需要 **在每个工程中操作一次**，而不是每次工作时都操作。 + +/// + +//// tab | `venv` + +你可以使用 Python 自带的 `venv` 模块来创建一个虚拟环境。 + +
+ +```console +$ python -m venv .venv +``` + +
+ +/// details | 上述命令的含义 + +* `python`: 使用名为 `python` 的程序 +* `-m`: 以脚本的方式调用一个模块，我们将告诉它接下来使用哪个模块 +* `venv`: 使用名为 `venv` 的模块，这个模块通常随 Python 一起安装 +* `.venv`: 在新目录 `.venv` 中创建虚拟环境 + +/// + +//// + +//// tab | `uv` + +如果你安装了 `uv`，你也可以使用它来创建一个虚拟环境。 + +
+ +```console +$ uv venv +``` + +
+ +/// tip + +默认情况下，`uv` 会在一个名为 `.venv` 的目录中创建一个虚拟环境。 + +但你可以通过传递一个额外的参数来自定义它，指定目录的名称。 + +/// + +//// + +这个命令会在一个名为 `.venv` 的目录中创建一个新的虚拟环境。 + +/// details | `.venv`，或是其他名称 + +你可以在不同的目录下创建虚拟环境，但通常我们会把它命名为 `.venv`。 + +/// + +## 激活虚拟环境 + +激活新的虚拟环境来确保你运行的任何 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）： + +
+ +```console +$ source .venv/Scripts/activate +``` + +
+ +//// + +/// tip + +每次你在这个环境中安装一个 **新的包** 时，都需要 **重新激活** 这个环境。 + +这么做确保了当你使用一个由这个包安装的 **终端（CLI）程序** 时，你使用的是你的虚拟环境中的程序，而不是全局安装、可能版本不同的程序。 + +/// + +## 检查虚拟环境是否激活 + +检查虚拟环境是否激活 (前面的命令是否生效)。 + +/// 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` + +/// tip + +如果你使用 `uv` 来安装内容，而不是 `pip`，那么你就不需要升级 `pip`。😎 + +/// + +如果你使用 `pip` 来安装包（它是 Python 的默认组件），你应该将它 **升级** 到最新版本。 + +在安装包时出现的许多奇怪的错误都可以通过先升级 `pip` 来解决。 + +/// tip + +通常你只需要在创建虚拟环境后 **执行一次** 这个操作。 + +/// + +确保虚拟环境是激活的 (使用上面的命令)，然后运行： + +
+ +```console +$ python -m pip install --upgrade pip + +---> 100% +``` + +
+ +## 添加 `.gitignore` + +如果你使用 **Git** (这是你应该使用的)，添加一个 `.gitignore` 文件来排除你的 `.venv` 中的所有内容。 + +/// tip + +如果你使用 `uv` 来创建虚拟环境，它会自动为你完成这个操作，你可以跳过这一步。😎 + +/// + +/// tip + +通常你只需要在创建虚拟环境后 **执行一次** 这个操作。 + +/// + +
+ +```console +$ echo "*" > .venv/.gitignore +``` + +
+ +/// details | 上述命令的含义 + +* `echo "*"`: 将在终端中 "打印" 文本 `*`（接下来的部分会对这个操作进行一些修改） +* `>`: 使左边的命令打印到终端的任何内容实际上都不会被打印，而是会被写入到右边的文件中 +* `.gitignore`: 被写入文本的文件的名称 + +而 `*` 对于 Git 来说意味着 "所有内容"。所以，它会忽略 `.venv` 目录中的所有内容。 + +该命令会创建一个名为 `.gitignore` 的文件，内容如下： + +```gitignore +* +``` + +/// + +## 安装软件包 + +在激活虚拟环境后，你可以在其中安装软件包。 + +/// tip + +当你需要安装或升级软件包时，执行本操作**一次**； + +如果你需要再升级版本或添加新软件包，你可以**再次执行此操作**。 + +/// + +### 直接安装包 + +如果你急于安装，不想使用文件来声明工程的软件包依赖，您可以直接安装它们。 + +/// tip + +将程序所需的软件包及其版本放在文件中（例如 `requirements.txt` 或 `pyproject.toml`）是个好（并且非常好）的主意。 + +/// + +//// tab | `pip` + +
+ +```console +$ pip install "fastapi[standard]" + +---> 100% +``` + +
+ +//// + +//// tab | `uv` + +如果你有 `uv`: + +
+ +```console +$ uv pip install "fastapi[standard]" +---> 100% +``` + +
+ +//// + +### 从 `requirements.txt` 安装 + +如果你有一个 `requirements.txt` 文件，你可以使用它来安装其中的软件包。 + +//// tab | `pip` + +
+ +```console +$ pip install -r requirements.txt +---> 100% +``` + +
+ +//// + +//// tab | `uv` + +如果你有 `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 +``` + +/// + +## 运行程序 + +在你激活虚拟环境后，你可以运行你的程序，它将使用虚拟环境中的 Python 和你在其中安装的软件包。 + +
+ +```console +$ python main.py + +Hello World +``` + +
+ +## 配置编辑器 + +你可能会用到编辑器（即 IDE —— 译者注），请确保配置它使用与你创建的相同的虚拟环境（它可能会自动检测到），以便你可以获得自动补全和内联错误提示。 + +例如： + +* VS Code +* PyCharm + +/// tip + +通常你只需要在创建虚拟环境时执行此操作**一次**。 + +/// + +## 退出虚拟环境 + +当你完成工作后，你可以**退出**虚拟环境。 + +
+ +```console +$ deactivate +``` + +
+ +这样，当你运行 `python` 时，它不会尝试从安装了软件包的虚拟环境中运行。（即，它将不再会尝试从虚拟环境中运行，也不会使用其中安装的软件包。—— 译者注） + +## 开始工作 + +现在你已经准备好开始你的工作了。 + + + +/// tip + +你想要理解上面的所有内容吗？ + +继续阅读。👇🤓 + +/// + +## 为什么要使用虚拟环境 + +你需要安装 Python 才能使用 FastAPI。 + +之后，你需要**安装** FastAPI 和你想要使用的任何其他**软件包**。 + +要安装软件包，你通常会使用随 Python 一起提供的 `pip` 命令（或类似的替代方案）。 + +然而，如果你直接使用 `pip`，软件包将被安装在你的**全局 Python 环境**中（即 Python 的全局安装）。 + +### 存在的问题 + +那么，在全局 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 环境中安装软件包，你可能会**破坏**一些随操作系统一起安装的程序。 + +## 软件包安装在哪里 + +当你安装 Python 时，它会在你的计算机上创建一些目录，并在这些目录中放一些文件。 + +其中一些目录负责存放你安装的所有软件包。 + +当你运行： + +
+ +```console +// 先别去运行这个命令，这只是一个示例 🤓 +$ pip install "fastapi[standard]" +---> 100% +``` + +
+ +这将会从 PyPI 下载一个压缩文件，其中包含 FastAPI 代码。 + +它还会**下载** FastAPI 依赖的其他软件包的文件。 + +然后它会**解压**所有这些文件，并将它们放在你的计算机上的一个目录中。 + +默认情况下，它会将下载并解压的这些文件放在随 Python 安装的目录中，这就是**全局环境**。 + +## 什么是虚拟环境 + +解决软件包都安装在全局环境中的问题的方法是为你所做的每个工程使用一个**虚拟环境**。 + +虚拟环境是一个**目录**，与全局环境非常相似，你可以在其中专为某个工程安装软件包。 + +这样，每个工程都会有自己的虚拟环境（`.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 +``` + +## 激活虚拟环境意味着什么 + +当你激活了一个虚拟环境，例如： + +//// tab | Linux, macOS + +
+ +```console +$ source .venv/bin/activate +``` + +
+ +//// + +//// tab | Windows PowerShell + +
+ +```console +$ .venv\Scripts\Activate.ps1 +``` + +
+ +//// + +//// tab | Windows Bash + +或者如果你在 Windows 上使用 Bash（例如 Git Bash）： + +
+ +```console +$ source .venv/Scripts/activate +``` + +
+ +//// + +这个命令会创建或修改一些[环境变量](environment-variables.md){.internal-link target=_blank}，这些环境变量将在接下来的命令中可用。 + +其中之一是 `PATH` 变量。 + +/// tip + +你可以在 [环境变量](environment-variables.md#path-environment-variable){.internal-link target=_blank} 部分了解更多关于 `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`）。 + +激活虚拟环境还会改变其他一些东西，但这是它所做的最重要的事情之一。 + +## 检查虚拟环境 + +当你检查虚拟环境是否激活时，例如： + +//// 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` 是很有用的。🤓 + +/// + +## 为什么要停用虚拟环境 + +例如，你可能正在一个工程 `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-askaban` 的新虚拟环境，那么当你运行 `python` 时，它会使用 `prisoner-of-askaban` 中的虚拟环境中的 Python。 + +
+ +```console +$ cd ~/code/prisoner-of-azkaban + +// 你不需要在旧目录中操作停用，你可以在任何地方操作停用，甚至在转到另一个工程之后 😎 +$ deactivate + +// 激活 prisoner-of-azkaban/.venv 中的虚拟环境 🚀 +$ source .venv/bin/activate + +// 现在当你运行 python 时，它会在这个虚拟环境中找到安装的 sirius 包 ✨ +$ python main.py + +I solemnly swear 🐺 +``` + +
+ +## 替代方案 + +这是一个简单的指南，可以帮助你入门并教会你如何理解一切**底层**的东西。 + +有许多**替代方案**来管理虚拟环境、包依赖（requirements）、工程。 + +一旦你准备好并想要使用一个工具来**管理整个工程**、包依赖、虚拟环境等，建议你尝试 uv。 + +`uv` 可以做很多事情，它可以： + +* 为你**安装 Python**，包括不同的版本 +* 为你的工程管理**虚拟环境** +* 安装**软件包** +* 为你的工程管理软件包的**依赖和版本** +* 确保你有一个**确切**的软件包和版本集合来安装，包括它们的依赖项，这样你就可以确保在生产中运行你的工程与在开发时在你的计算机上运行的工程完全相同，这被称为**锁定** +* 还有很多其他功能 + +## 结论 + +如果你读过并理解了所有这些，现在**你对虚拟环境的了解比很多开发者都要多**。🤓 + +在未来当你调试看起来复杂的东西时，了解这些细节很可能会有用，你会知道**它是如何在底层工作的**。😎 diff --git a/docs_src/schema_extra_example/tutorial001_py310_pv1.py b/docs_src/schema_extra_example/tutorial001_pv1_py310.py similarity index 100% rename from docs_src/schema_extra_example/tutorial001_py310_pv1.py rename to docs_src/schema_extra_example/tutorial001_pv1_py310.py diff --git a/fastapi/__init__.py b/fastapi/__init__.py index 51e3ca510..12faea987 100644 --- a/fastapi/__init__.py +++ b/fastapi/__init__.py @@ -1,6 +1,6 @@ """FastAPI framework, high performance, easy to learn, fast to code, ready for production""" -__version__ = "0.115.4" +__version__ = "0.115.5" from starlette import status as status diff --git a/fastapi/_compat.py b/fastapi/_compat.py index 56c5d744e..2b4d3e725 100644 --- a/fastapi/_compat.py +++ b/fastapi/_compat.py @@ -27,7 +27,8 @@ from typing_extensions import Annotated, Literal, get_args, get_origin # Reassign variable to make it reexported for mypy PYDANTIC_VERSION = P_VERSION -PYDANTIC_V2 = PYDANTIC_VERSION.startswith("2.") +PYDANTIC_VERSION_MINOR_TUPLE = tuple(int(x) for x in PYDANTIC_VERSION.split(".")[:2]) +PYDANTIC_V2 = PYDANTIC_VERSION_MINOR_TUPLE[0] == 2 sequence_annotation_to_type = { diff --git a/fastapi/params.py b/fastapi/params.py index 90ca7cb01..8f5601dd3 100644 --- a/fastapi/params.py +++ b/fastapi/params.py @@ -6,7 +6,11 @@ from fastapi.openapi.models import Example from pydantic.fields import FieldInfo from typing_extensions import Annotated, deprecated -from ._compat import PYDANTIC_V2, PYDANTIC_VERSION, Undefined +from ._compat import ( + PYDANTIC_V2, + PYDANTIC_VERSION_MINOR_TUPLE, + Undefined, +) _Unset: Any = Undefined @@ -105,7 +109,7 @@ class Param(FieldInfo): stacklevel=4, ) current_json_schema_extra = json_schema_extra or extra - if PYDANTIC_VERSION < "2.7.0": + if PYDANTIC_VERSION_MINOR_TUPLE < (2, 7): self.deprecated = deprecated else: kwargs["deprecated"] = deprecated @@ -561,7 +565,7 @@ class Body(FieldInfo): stacklevel=4, ) current_json_schema_extra = json_schema_extra or extra - if PYDANTIC_VERSION < "2.7.0": + if PYDANTIC_VERSION_MINOR_TUPLE < (2, 7): self.deprecated = deprecated else: kwargs["deprecated"] = deprecated diff --git a/scripts/deploy_docs_status.py b/scripts/deploy_docs_status.py index 19dffbcb9..c652cdb6e 100644 --- a/scripts/deploy_docs_status.py +++ b/scripts/deploy_docs_status.py @@ -2,7 +2,7 @@ import logging import re from github import Github -from pydantic import SecretStr +from pydantic import BaseModel, SecretStr from pydantic_settings import BaseSettings @@ -15,7 +15,13 @@ class Settings(BaseSettings): is_done: bool = False -def main(): +class LinkData(BaseModel): + previous_link: str + preview_link: str + en_link: str | None = None + + +def main() -> None: logging.basicConfig(level=logging.INFO) settings = Settings() @@ -60,7 +66,7 @@ def main(): docs_files = [f for f in files if f.filename.startswith("docs/")] deploy_url = settings.deploy_url.rstrip("/") - lang_links: dict[str, list[str]] = {} + lang_links: dict[str, list[LinkData]] = {} for f in docs_files: match = re.match(r"docs/([^/]+)/docs/(.*)", f.filename) if not match: @@ -71,15 +77,22 @@ def main(): path = path.replace("index.md", "") else: path = path.replace(".md", "/") + en_path = path if lang == "en": - link = f"{deploy_url}/{path}" + use_path = en_path else: - link = f"{deploy_url}/{lang}/{path}" + use_path = f"{lang}/{path}" + link = LinkData( + previous_link=f"https://fastapi.tiangolo.com/{use_path}", + preview_link=f"{deploy_url}/{use_path}", + ) + if lang != "en": + link.en_link = f"https://fastapi.tiangolo.com/{en_path}" lang_links.setdefault(lang, []).append(link) - links: list[str] = [] + links: list[LinkData] = [] en_links = lang_links.get("en", []) - en_links.sort() + en_links.sort(key=lambda x: x.preview_link) links.extend(en_links) langs = list(lang_links.keys()) @@ -88,14 +101,19 @@ def main(): if lang == "en": continue current_lang_links = lang_links[lang] - current_lang_links.sort() + current_lang_links.sort(key=lambda x: x.preview_link) links.extend(current_lang_links) message = f"📝 Docs preview for commit {settings.commit_sha} at: {deploy_url}" if links: message += "\n\n### Modified Pages\n\n" - message += "\n".join([f"* {link}" for link in links]) + for link in links: + message += f"* {link.preview_link}" + message += f" - ([before]({link.previous_link}))" + if link.en_link: + message += f" - ([English]({link.en_link}))" + message += "\n" print(message) use_pr.as_issue().create_comment(message) diff --git a/scripts/docs.py b/scripts/docs.py index f26f96d85..8462e2bc1 100644 --- a/scripts/docs.py +++ b/scripts/docs.py @@ -35,6 +35,7 @@ non_translated_sections = [ "newsletter.md", "management-tasks.md", "management.md", + "contributing.md", ] docs_path = Path("docs") diff --git a/tests/test_tutorial/test_schema_extra_example/test_tutorial001_py310_pv1.py b/tests/test_tutorial/test_schema_extra_example/test_tutorial001_pv1_py310.py similarity index 98% rename from tests/test_tutorial/test_schema_extra_example/test_tutorial001_py310_pv1.py rename to tests/test_tutorial/test_schema_extra_example/test_tutorial001_pv1_py310.py index e036d6b68..b2a4d15b1 100644 --- a/tests/test_tutorial/test_schema_extra_example/test_tutorial001_py310_pv1.py +++ b/tests/test_tutorial/test_schema_extra_example/test_tutorial001_pv1_py310.py @@ -6,7 +6,7 @@ from ...utils import needs_py310, needs_pydanticv1 @pytest.fixture(name="client") def get_client(): - from docs_src.schema_extra_example.tutorial001_py310_pv1 import app + from docs_src.schema_extra_example.tutorial001_pv1_py310 import app client = TestClient(app) return client