From 1054fbd2563c91ac7798ae25c486c426df9d7909 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Sun, 11 Jan 2026 10:18:38 -0800 Subject: [PATCH 001/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20docs=20for=20co?= =?UTF-8?q?ntributing=20with=20translations=20(#14701)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/contributing.md | 235 +++-------------------------------- scripts/docs.py | 11 +- 2 files changed, 17 insertions(+), 229 deletions(-) diff --git a/docs/en/docs/contributing.md b/docs/en/docs/contributing.md index 18b7f60f72..be4706f742 100644 --- a/docs/en/docs/contributing.md +++ b/docs/en/docs/contributing.md @@ -177,252 +177,45 @@ as Uvicorn by default will use the port `8000`, the documentation on port `8008` ### Translations -/// warning | Attention - -**Update on Translations** - -We're updating the way we handle documentation translations. - -Until now, we invited community members to translate pages via pull requests, which were then reviewed by at least two native speakers. While this has helped bring FastAPI to many more users, we’ve also run into several challenges - some languages have only a few translated pages, others are outdated and hard to maintain over time. -To improve this, we’re working on automation tools 🀖 to manage translations more efficiently. Once ready, documentation will be machine-translated and still reviewed by at least two native speakers ✅ before publishing. This will allow us to keep translations up-to-date while reducing the review burden on maintainers. - -What’s changing now: - -* 🚫 We’re no longer accepting new community-submitted translation PRs. - -* ⏳ Existing open PRs will be reviewed and can still be merged if completed within the next 3 weeks (since July 11 2025). - -* 🌐 In the future, we will only support languages where at least three active native speakers are available to review and maintain translations. - -This transition will help us keep translations more consistent and timely while better supporting our contributors 🙌. Thank you to everyone who has contributed so far — your help has been invaluable! 💖 - -/// - - Help with translations is VERY MUCH appreciated! And it can't be done without the help from the community. 🌎 🚀 Here are the steps to help with translations. -#### Tips and guidelines +#### Review Translation PRs + +Translation pull requests are made by LLMs guided with prompts designed by the FastAPI team together with the community of native speakers for each supported language. + +These translations are normally still reviewed by native speakers, and here's where you can help! * Check the currently existing pull requests for your language. You can filter the pull requests by the ones with the label for your language. For example, for Spanish, the label is `lang-es`. -* Review those pull requests, requesting changes or approving them. For the languages I don't speak, I'll wait for several others to review the translation before merging. +* When reviewing a pull request, it's better not to suggest changes in the same pull request, because it is LLM generated, and it won't be possible to make sure that small individual changes are replicated in other similar sections, or that they are preserved when translating the same content again. + +* Instead of adding suggestions to the translation PR, make the suggestions to the LLM prompt file for that language, in a new PR. For example, for Spanish, the LLM prompt file is at: `docs/es/llm-prompt.md`. /// tip -You can add comments with change suggestions to existing pull requests. - Check the docs about adding a pull request review to approve it or request changes. /// +#### Subscribe to Notifications for Your Language + * Check if there's a GitHub Discussion to coordinate translations for your language. You can subscribe to it, and when there's a new pull request to review, an automatic comment will be added to the discussion. -* If you translate pages, add a single pull request per page translated. That will make it much easier for others to review it. - * To check the 2-letter code for the language you want to translate, you can use the table List of ISO 639-1 codes. -#### Existing language - -Let's say you want to translate a page for a language that already has translations for some pages, like Spanish. - -In the case of Spanish, the 2-letter code is `es`. So, the directory for Spanish translations is located at `docs/es/`. - -/// tip - -The main ("official") language is English, located at `docs/en/`. - -/// - -Now run the live server for the docs in Spanish: - -
- -```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 - -Alternatively, you can perform the same steps that scripts does manually. - -Go into the language directory, for the Spanish translations it's at `docs/es/`: - -```console -$ cd docs/es/ -``` - -Then run `mkdocs` in that directory: - -```console -$ mkdocs serve --dev-addr 127.0.0.1:8008 -``` - -/// - -Now you can go to http://127.0.0.1:8008 and see your changes live. - -You will see that every language has all the pages. But some pages are not translated and have an info box at the top, about the missing translation. - -Now let's say that you want to add a translation for the section [Features](features.md){.internal-link target=_blank}. - -* Copy the file at: - -``` -docs/en/docs/features.md -``` - -* Paste it in exactly the same location but for the language you want to translate, e.g.: - -``` -docs/es/docs/features.md -``` - -/// tip - -Notice that the only change in the path and file name is the language code, from `en` to `es`. - -/// - -If you go to your browser you will see that now the docs show your new section (the info box at the top is gone). 🎉 - -Now you can translate it all and see how it looks as you save the file. - -#### Don't Translate these Pages - -🚚 Don't translate: - -* Files under `reference/` -* `release-notes.md` -* `fastapi-people.md` -* `external-links.md` -* `newsletter.md` -* `management-tasks.md` -* `management.md` -* `contributing.md` - -Some of these files are updated very frequently and a translation would always be behind, or they include the main content from English source files, etc. - #### Request a New Language Let's say that you want to request translations for a language that is not yet translated, not even some pages. For example, Latin. -If there is no discussion for that language, you can start by requesting the new language. For that, you can follow these steps: - +* The first step would be for you to find other 2 people that would be willing to be reviewing translation PRs for that language with you. +* Once there are at least 3 people that would be willing to commit to help maintain that language, you can continue the next steps. * Create a new discussion following the template. -* Get a few native speakers to comment on the discussion and commit to help review translations for that language. +* Tag the other 2 people that will help with the language, and ask them to confirm there they will help. Once there are several people in the discussion, the FastAPI team can evaluate it and can make it an official translation. -Then the docs will be automatically translated using AI, and the team of native speakers can review the translation, and help tweak the AI prompts. +Then the docs will be automatically translated using LLMs, and the team of native speakers can review the translation, and help tweak the LLM prompts. Once there's a new translation, for example if docs are updated or there's a new section, there will be a comment in the same discussion with the link to the new translation to review. - -#### New Language - -/// note - -These steps will be performed by the FastAPI team. - -/// - -Checking the link from above (List of ISO 639-1 codes), you can see that the 2-letter code for Latin is `la`. - -Now you can create a new directory for the new language, running the following script: - -
- -```console -// Use the command new-lang, pass the language code as a CLI argument -$ python ./scripts/docs.py new-lang la - -Successfully initialized: docs/la -``` - -
- -Now you can check in your code editor the newly created directory `docs/la/`. - -That command created a file `docs/la/mkdocs.yml` with a simple config that inherits everything from the `en` version: - -```yaml -INHERIT: ../en/mkdocs.yml -``` - -/// tip - -You could also simply create that file with those contents manually. - -/// - -That command also created a dummy file `docs/la/index.md` for the main page, you can start by translating that one. - -You can continue with the previous instructions for an "Existing Language" for that process. - -You can make the first pull request with those two files, `docs/la/mkdocs.yml` and `docs/la/index.md`. 🎉 - -#### Preview the result - -As already mentioned above, you can use the `./scripts/docs.py` with the `live` command to preview the results (or `mkdocs serve`). - -Once you are done, you can also test it all as it would look online, including all the other languages. - -To do that, first build all the docs: - -
- -```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 -``` - -
- -This builds all those independent MkDocs sites for each language, combines them, and generates the final output at `./site/`. - -Then you can serve that with the command `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 -``` - -
- -#### Translation specific tips and guidelines - -* Translate only the Markdown documents (`.md`). Do not translate the code examples at `./docs_src`. - -* In code blocks within the Markdown document, translate comments (`# a comment`), but leave the rest unchanged. - -* Do not change anything enclosed in "``" (inline code). - -* In lines starting with `///` translate only the text part after `|`. Leave the rest unchanged. - -* You can translate info boxes like `/// warning` with for example `/// warning | Achtung`. But do not change the word immediately after the `///`, it determines the color of the info box. - -* Do not change the paths in links to images, code files, Markdown documents. - -* However, when a Markdown document is translated, the `#hash-parts` in links to its headings may change. Update these links if possible. - * Search for such links in the translated document using the regex `#[^# ]`. - * Search in all documents already translated into your language for `your-translated-document.md`. For example VS Code has an option "Edit" -> "Find in Files". - * When translating a document, do not "pre-translate" `#hash-parts` that link to headings in untranslated documents. diff --git a/scripts/docs.py b/scripts/docs.py index c350ee8319..20bf1c1688 100644 --- a/scripts/docs.py +++ b/scripts/docs.py @@ -130,14 +130,9 @@ def new_lang(lang: str = typer.Argument(..., callback=lang_callback)): new_path.mkdir() new_config_path: Path = Path(new_path) / mkdocs_name new_config_path.write_text("INHERIT: ../en/mkdocs.yml\n", encoding="utf-8") - new_config_docs_path: Path = new_path / "docs" - new_config_docs_path.mkdir() - en_index_path: Path = en_docs_path / "docs" / "index.md" - new_index_path: Path = new_config_docs_path / "index.md" - en_index_content = en_index_path.read_text(encoding="utf-8") - new_index_content = f"{missing_translation_snippet}\n\n{en_index_content}" - new_index_path.write_text(new_index_content, encoding="utf-8") - typer.secho(f"Successfully initialized: {new_path}", color=typer.colors.GREEN) + new_llm_prompt_path: Path = new_path / "llm-prompt.md" + new_llm_prompt_path.write_text("", encoding="utf-8") + print(f"Successfully initialized: {new_path}") update_languages() From 97aa825422737b8fbafa9ad76390a86b67a88381 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sun, 11 Jan 2026 18:18:58 +0000 Subject: [PATCH 002/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 7727fa699c..2a2b0d6396 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -9,6 +9,7 @@ hide: ### Docs +* 📝 Update docs for contributing with translations. PR [#14701](https://github.com/fastapi/fastapi/pull/14701) by [@tiangolo](https://github.com/tiangolo). * 📝 Specify language code for code block. PR [#14656](https://github.com/fastapi/fastapi/pull/14656) by [@YuriiMotov](https://github.com/YuriiMotov). ### Translations From 249a776b70dfc173d4c9b91a3b0c8d9319d0ee14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Sun, 11 Jan 2026 11:19:05 -0800 Subject: [PATCH 003/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20docs=20about=20?= =?UTF-8?q?managing=20translations=20(#14704)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/fastapi-people.md | 22 +----- docs/en/docs/management-tasks.md | 126 ++----------------------------- 2 files changed, 7 insertions(+), 141 deletions(-) diff --git a/docs/en/docs/fastapi-people.md b/docs/en/docs/fastapi-people.md index f2ca26013c..2c07af7647 100644 --- a/docs/en/docs/fastapi-people.md +++ b/docs/en/docs/fastapi-people.md @@ -196,31 +196,11 @@ They have contributed source code, documentation, etc. 📊 There are hundreds of other contributors, you can see them all in the FastAPI GitHub Contributors page. 👷 -## Top Translators - -These are the **Top Translators**. 🌐 - -These users have created the most Pull Requests with [translations to other languages](contributing.md#translations){.internal-link target=_blank} that have been *merged*. - -
- -{% for user in (translators.values() | list)[:50] %} - -{% if user.login not in skip_users %} - -
@{{ user.login }}
Translations: {{ user.count }}
- -{% endif %} - -{% endfor %} - -
- ## Top Translation Reviewers These users are the **Top Translation Reviewers**. 🕵 -I only speak a few languages (and not very well 😅). So, the reviewers are the ones that have the [**power to approve translations**](contributing.md#translations){.internal-link target=_blank} of the documentation. Without them, there wouldn't be documentation in several other languages. +Translation reviewers have the [**power to approve translations**](contributing.md#translations){.internal-link target=_blank} of the documentation. Without them, there wouldn't be documentation in several other languages.
{% for user in (translation_reviewers.values() | list)[:50] %} diff --git a/docs/en/docs/management-tasks.md b/docs/en/docs/management-tasks.md index aac4d6fe40..68d10a42cc 100644 --- a/docs/en/docs/management-tasks.md +++ b/docs/en/docs/management-tasks.md @@ -106,129 +106,15 @@ This way, we can notice when there are new translations ready, because they have ## Merge Translation PRs -For Spanish, as I'm a native speaker and it's a language close to me, I will give it a final review myself and in most cases tweak the PR a bit before merging it. +Translations are generated automatically with LLMs and scripts. -For the other languages, confirm that: +There's one GitHub Action that can be manually run to add or update translations for a language: `translate.yml`. -* The title is correct following the instructions above. +For these language translation PRs, confirm that: + +* The PR was automated (authored by @tiangolo), not made by another user. * It has the labels `lang-all` and `lang-{lang code}`. -* The PR changes only one Markdown file adding a translation. - * Or in some cases, at most two files, if they are small, for the same language, and people reviewed them. - * If it's the first translation for that language, it will have additional `mkdocs.yml` files, for those cases follow the instructions below. -* The PR doesn't add any additional or extraneous files. -* The translation seems to have a similar structure as the original English file. -* The translation doesn't seem to change the original content, for example with obvious additional documentation sections. -* The translation doesn't use different Markdown structures, for example adding HTML tags when the original didn't have them. -* The "admonition" sections, like `tip`, `info`, etc. are not changed or translated. For example: - -``` -/// tip - -This is a tip. - -/// - -``` - -looks like this: - -/// tip - -This is a tip. - -/// - -...it could be translated as: - -``` -/// tip - -Esto es un consejo. - -/// - -``` - -...but needs to keep the exact `tip` keyword. If it was translated to `consejo`, like: - -``` -/// consejo - -Esto es un consejo. - -/// - -``` - -it would change the style to the default one, it would look like: - -/// consejo - -Esto es un consejo. - -/// - -Those don't have to be translated, but if they are, they need to be written as: - -``` -/// tip | consejo - -Esto es un consejo. - -/// - -``` - -Which looks like: - -/// tip | consejo - -Esto es un consejo. - -/// - -## First Translation PR - -When there's a first translation for a language, it will have a `docs/{lang code}/docs/index.md` translated file and a `docs/{lang code}/mkdocs.yml`. - -For example, for Bosnian, it would be: - -* `docs/bs/docs/index.md` -* `docs/bs/mkdocs.yml` - -The `mkdocs.yml` file will have only the following content: - -```YAML -INHERIT: ../en/mkdocs.yml -``` - -The language code would normally be in the ISO 639-1 list of language codes. - -In any case, the language code should be in the file docs/language_names.yml. - -There won't be yet a label for the language code, for example, if it was Bosnian, there wouldn't be a `lang-bs`. Before creating the label and adding it to the PR, create the GitHub Discussion: - -* Go to the Translations GitHub Discussions -* Create a new discussion with the title `Bosnian Translations` (or the language name in English) -* A description of: - -```Markdown -## Bosnian translations - -This is the issue to track translations of the docs to Bosnian. 🚀 - -Here are the [PRs to review with the label `lang-bs`](https://github.com/fastapi/fastapi/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+label%3Alang-bs+label%3A%22awaiting-review%22). 🀓 -``` - -Update "Bosnian" with the new language. - -And update the search link to point to the new language label that will be created, like `lang-bs`. - -Create and add the label to that new Discussion just created, like `lang-bs`. - -Then go back to the PR, and add the label, like `lang-bs`, and `lang-all` and `awaiting-review`. - -Now the GitHub action will automatically detect the label `lang-bs` and will post in that Discussion that this PR is waiting to be reviewed. +* If the PR is approved by at least one native speaker, you can merge it. ## Review PRs From e9e0419ed0deee736e2b6ef01fc6dea1d6ed987e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sun, 11 Jan 2026 19:19:29 +0000 Subject: [PATCH 004/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 2a2b0d6396..1df9e63510 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -9,6 +9,7 @@ hide: ### Docs +* 📝 Update docs about managing translations. PR [#14704](https://github.com/fastapi/fastapi/pull/14704) by [@tiangolo](https://github.com/tiangolo). * 📝 Update docs for contributing with translations. PR [#14701](https://github.com/fastapi/fastapi/pull/14701) by [@tiangolo](https://github.com/tiangolo). * 📝 Specify language code for code block. PR [#14656](https://github.com/fastapi/fastapi/pull/14656) by [@YuriiMotov](https://github.com/YuriiMotov). From 7b864acf370f3587cc29eb58f1f897c5c21d139d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Sun, 11 Jan 2026 13:19:26 -0800 Subject: [PATCH 005/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20docs=20for=20ma?= =?UTF-8?q?nagement=20tasks=20(#14705)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/management-tasks.md | 27 +++++++-------------------- 1 file changed, 7 insertions(+), 20 deletions(-) diff --git a/docs/en/docs/management-tasks.md b/docs/en/docs/management-tasks.md index 68d10a42cc..6f34afb731 100644 --- a/docs/en/docs/management-tasks.md +++ b/docs/en/docs/management-tasks.md @@ -74,7 +74,7 @@ Make sure you use a supported label from the external_links.yml. - -* Make sure the new link is in the correct category (e.g. "Podcasts") and language (e.g. "Japanese"). -* A new link should be at the top of its list. -* The link URL should work (it should not return a 404). -* The content of the link should be about FastAPI. -* The new addition should have these fields: - * `author`: The name of the author. - * `link`: The URL with the content. - * `title`: The title of the link (the title of the article, podcast, etc). - -After checking all these things and ensuring the PR has the right labels, you can merge it. - ## Dependabot PRs Dependabot will create PRs to update dependencies for several things, and those PRs all look similar, but some are way more delicate than others. -* If the PR is for a direct dependency, so, Dependabot is modifying `pyproject.toml`, **don't merge it**. 😱 Let me check it first. There's a good chance that some additional tweaks or updates are needed. -* If the PR updates one of the internal dependencies, for example it's modifying `requirements.txt` files, or GitHub Action versions, if the tests are passing, the release notes (shown in a summary in the PR) don't show any obvious potential breaking change, you can merge it. 😎 +* If the PR is for a direct dependency, so, Dependabot is modifying `pyproject.toml` in the main dependencies, **don't merge it**. 😱 Let me check it first. There's a good chance that some additional tweaks or updates are needed. +* If the PR updates one of the internal dependencies, for example the group `dev` in `pyproject.toml`, or GitHub Action versions, if the tests are passing, the release notes (shown in a summary in the PR) don't show any obvious potential breaking change, you can merge it. 😎 ## Mark GitHub Discussions Answers From e63f382b0f189bc1ab76a58eaaf92ce83b775f48 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sun, 11 Jan 2026 21:19:50 +0000 Subject: [PATCH 006/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 1df9e63510..628eff3485 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -9,6 +9,7 @@ hide: ### Docs +* 📝 Update docs for management tasks. PR [#14705](https://github.com/fastapi/fastapi/pull/14705) by [@tiangolo](https://github.com/tiangolo). * 📝 Update docs about managing translations. PR [#14704](https://github.com/fastapi/fastapi/pull/14704) by [@tiangolo](https://github.com/tiangolo). * 📝 Update docs for contributing with translations. PR [#14701](https://github.com/fastapi/fastapi/pull/14701) by [@tiangolo](https://github.com/tiangolo). * 📝 Specify language code for code block. PR [#14656](https://github.com/fastapi/fastapi/pull/14656) by [@YuriiMotov](https://github.com/YuriiMotov). From 1be80f48851845d9e0a6ce8ee6a8b871cd9ff5ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Sun, 11 Jan 2026 14:22:58 -0800 Subject: [PATCH 007/108] =?UTF-8?q?=F0=9F=93=9D=20Add=20contribution=20ins?= =?UTF-8?q?tructions=20about=20LLM=20generated=20code=20and=20comments=20a?= =?UTF-8?q?nd=20automated=20tools=20for=20PRs=20(#14706)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/issue-manager.yml | 6 ++++- docs/en/docs/contributing.md | 36 +++++++++++++++++++++++++++++ docs/en/docs/management-tasks.md | 2 ++ 3 files changed, 43 insertions(+), 1 deletion(-) diff --git a/.github/workflows/issue-manager.yml b/.github/workflows/issue-manager.yml index f40ec4dc47..2ae588da13 100644 --- a/.github/workflows/issue-manager.yml +++ b/.github/workflows/issue-manager.yml @@ -41,11 +41,15 @@ jobs: "message": "As this PR has been waiting for the original user for a while but seems to be inactive, it's now going to be closed. But if there's anyone interested, feel free to create a new PR.", "reminder": { "before": "P3D", - "message": "Heads-up: this will be closed in 3 days unless there’s new activity." + "message": "Heads-up: this will be closed in 3 days unless there's new activity." } }, "invalid": { "delay": 0, "message": "This was marked as invalid and will be closed now. If this is an error, please provide additional details." + }, + "maybe-ai": { + "delay": 0, + "message": "This was marked as potentially AI generated and will be closed now. If this is an error, please provide additional details, make sure to read the docs about contributing and AI." } } diff --git a/docs/en/docs/contributing.md b/docs/en/docs/contributing.md index be4706f742..a4d896109b 100644 --- a/docs/en/docs/contributing.md +++ b/docs/en/docs/contributing.md @@ -219,3 +219,39 @@ Once there are several people in the discussion, the FastAPI team can evaluate i Then the docs will be automatically translated using LLMs, and the team of native speakers can review the translation, and help tweak the LLM prompts. Once there's a new translation, for example if docs are updated or there's a new section, there will be a comment in the same discussion with the link to the new translation to review. + +## Automated Code and AI + +You are encouraged to use all the tools you want to do your work and contribute as efficiently as possible, this includes AI (LLM) tools, etc. Nevertheless, contributions should have meaningful human intervention, judgement, context, etc. + +If the **human effort** put in a PR, e.g. writing LLM prompts, is **less** than the **effort we would need to put** to **review it**, please **don't** submit the PR. + +Think of it this way: we can already write LLM prompts or run automated tools ourselves, and that would be faster than reviewing external PRs. + +### Closing Automated and AI PRs + +If we see PRs that seem AI generated or automated in similar ways, we'll flag them and close them. + +The same applies to comments and descriptions, please don't copy paste the content generated by an LLM. + +### Human Effort Denial of Service + +Using automated tools and AI to submit PRs or comments that we have to carefully review and handle would be the equivalent of a Denial-of-service attack on our human effort. + +It would be very little effort from the person submitting the PR (an LLM prompt) that generates a large amount of effort on our side (carefully reviewing code). + +Please don't do that. + +We'll need to block accounts that spam us with repeated automated PRs or comments. + +### Use Tools Wisely + +As Uncle Ben said: + +
+With great power tools comes great responsibility. +
+ +Avoid inadvertently doing harm. + +You have amazing tools at hand, use them wisely to help effectively. diff --git a/docs/en/docs/management-tasks.md b/docs/en/docs/management-tasks.md index 6f34afb731..fc6e1eb280 100644 --- a/docs/en/docs/management-tasks.md +++ b/docs/en/docs/management-tasks.md @@ -122,6 +122,8 @@ For these language translation PRs, confirm that: * If a PR seems to be spam, meaningless, only to change statistics (to appear as "contributor") or similar, you can simply mark it as `invalid`, and it will be automatically closed. +* If a PR seems to be AI generated, and seems like reviewing it would take more time from you than the time it took to write the prompt, mark it as `maybe-ai`, and it will be automatically closed. + * A PR should have a specific use case that it is solving. * If the PR is for a feature, it should have docs. From a456e92a21d5b94a67d6d0fd070218df09444443 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sun, 11 Jan 2026 22:23:21 +0000 Subject: [PATCH 008/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 628eff3485..45bc9873ec 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -9,6 +9,7 @@ hide: ### Docs +* 📝 Add contribution instructions about LLM generated code and comments and automated tools for PRs. PR [#14706](https://github.com/fastapi/fastapi/pull/14706) by [@tiangolo](https://github.com/tiangolo). * 📝 Update docs for management tasks. PR [#14705](https://github.com/fastapi/fastapi/pull/14705) by [@tiangolo](https://github.com/tiangolo). * 📝 Update docs about managing translations. PR [#14704](https://github.com/fastapi/fastapi/pull/14704) by [@tiangolo](https://github.com/tiangolo). * 📝 Update docs for contributing with translations. PR [#14701](https://github.com/fastapi/fastapi/pull/14701) by [@tiangolo](https://github.com/tiangolo). From a96dd013a4d2ce4f5f758fe51bea19f541743164 Mon Sep 17 00:00:00 2001 From: fcharrier Date: Fri, 16 Jan 2026 11:53:45 +0100 Subject: [PATCH 009/108] =?UTF-8?q?=F0=9F=90=9B=20Fix=20copy=20button=20in?= =?UTF-8?q?=20custom.js=20(#14722)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/js/custom.js | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/en/docs/js/custom.js b/docs/en/docs/js/custom.js index 48e95901d5..be326d3029 100644 --- a/docs/en/docs/js/custom.js +++ b/docs/en/docs/js/custom.js @@ -81,8 +81,14 @@ function setupTermynal() { } } saveBuffer(); + const inputCommands = useLines + .filter(line => line.type === "input") + .map(line => line.value) + .join("\n"); + node.textContent = inputCommands; const div = document.createElement("div"); - node.replaceWith(div); + node.style.display = "none"; + node.after(div); const termynal = new Termynal(div, { lineData: useLines, noInit: true, From c597d9cb53415cf81188750ee946d69304922fbb Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 16 Jan 2026 10:54:08 +0000 Subject: [PATCH 010/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 45bc9873ec..233fdb7434 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -9,6 +9,7 @@ hide: ### Docs +* 🐛 Fix copy button in custom.js. PR [#14722](https://github.com/fastapi/fastapi/pull/14722) by [@fcharrier](https://github.com/fcharrier). * 📝 Add contribution instructions about LLM generated code and comments and automated tools for PRs. PR [#14706](https://github.com/fastapi/fastapi/pull/14706) by [@tiangolo](https://github.com/tiangolo). * 📝 Update docs for management tasks. PR [#14705](https://github.com/fastapi/fastapi/pull/14705) by [@tiangolo](https://github.com/tiangolo). * 📝 Update docs about managing translations. PR [#14704](https://github.com/fastapi/fastapi/pull/14704) by [@tiangolo](https://github.com/tiangolo). From f317ede223131a2822723602fb3f576f1ca0f5bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Fri, 16 Jan 2026 03:54:01 -0800 Subject: [PATCH 011/108] =?UTF-8?q?=F0=9F=8C=90=20Update=20translations=20?= =?UTF-8?q?for=20ko=20(add-missing)=20(#14699)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: github-actions[bot] --- docs/ko/docs/_llm-test.md | 503 +++++++++++++++++ docs/ko/docs/advanced/additional-responses.md | 247 +++++++++ docs/ko/docs/advanced/behind-a-proxy.md | 466 ++++++++++++++++ docs/ko/docs/advanced/dataclasses.md | 95 ++++ docs/ko/docs/advanced/generate-clients.md | 208 ++++++++ docs/ko/docs/advanced/middleware.md | 97 ++++ docs/ko/docs/advanced/openapi-callbacks.md | 186 +++++++ docs/ko/docs/advanced/openapi-webhooks.md | 55 ++ .../path-operation-advanced-configuration.md | 172 ++++++ .../docs/advanced/security/http-basic-auth.md | 107 ++++ docs/ko/docs/advanced/security/index.md | 19 + .../docs/advanced/security/oauth2-scopes.md | 274 ++++++++++ docs/ko/docs/advanced/settings.md | 302 +++++++++++ docs/ko/docs/alternatives.md | 485 +++++++++++++++++ docs/ko/docs/deployment/concepts.md | 321 +++++++++++ docs/ko/docs/deployment/fastapicloud.md | 65 +++ docs/ko/docs/deployment/https.md | 231 ++++++++ docs/ko/docs/deployment/manually.md | 157 ++++++ .../authentication-error-status-code.md | 17 + docs/ko/docs/how-to/custom-docs-ui-assets.md | 185 +++++++ .../docs/how-to/custom-request-and-route.md | 109 ++++ docs/ko/docs/how-to/extending-openapi.md | 80 +++ docs/ko/docs/how-to/general.md | 39 ++ docs/ko/docs/how-to/graphql.md | 60 +++ docs/ko/docs/how-to/index.md | 13 + ...migrate-from-pydantic-v1-to-pydantic-v2.md | 135 +++++ .../docs/how-to/separate-openapi-schemas.md | 102 ++++ docs/ko/docs/how-to/testing-database.md | 7 + docs/ko/docs/tutorial/bigger-applications.md | 504 ++++++++++++++++++ docs/ko/docs/tutorial/body-updates.md | 100 ++++ .../tutorial/dependencies/sub-dependencies.md | 105 ++++ docs/ko/docs/tutorial/handling-errors.md | 244 +++++++++ docs/ko/docs/tutorial/security/first-steps.md | 203 +++++++ docs/ko/docs/tutorial/security/index.md | 106 ++++ 34 files changed, 5999 insertions(+) create mode 100644 docs/ko/docs/_llm-test.md create mode 100644 docs/ko/docs/advanced/additional-responses.md create mode 100644 docs/ko/docs/advanced/behind-a-proxy.md create mode 100644 docs/ko/docs/advanced/dataclasses.md create mode 100644 docs/ko/docs/advanced/generate-clients.md create mode 100644 docs/ko/docs/advanced/middleware.md create mode 100644 docs/ko/docs/advanced/openapi-callbacks.md create mode 100644 docs/ko/docs/advanced/openapi-webhooks.md create mode 100644 docs/ko/docs/advanced/path-operation-advanced-configuration.md create mode 100644 docs/ko/docs/advanced/security/http-basic-auth.md create mode 100644 docs/ko/docs/advanced/security/index.md create mode 100644 docs/ko/docs/advanced/security/oauth2-scopes.md create mode 100644 docs/ko/docs/advanced/settings.md create mode 100644 docs/ko/docs/alternatives.md create mode 100644 docs/ko/docs/deployment/concepts.md create mode 100644 docs/ko/docs/deployment/fastapicloud.md create mode 100644 docs/ko/docs/deployment/https.md create mode 100644 docs/ko/docs/deployment/manually.md create mode 100644 docs/ko/docs/how-to/authentication-error-status-code.md create mode 100644 docs/ko/docs/how-to/custom-docs-ui-assets.md create mode 100644 docs/ko/docs/how-to/custom-request-and-route.md create mode 100644 docs/ko/docs/how-to/extending-openapi.md create mode 100644 docs/ko/docs/how-to/general.md create mode 100644 docs/ko/docs/how-to/graphql.md create mode 100644 docs/ko/docs/how-to/index.md create mode 100644 docs/ko/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md create mode 100644 docs/ko/docs/how-to/separate-openapi-schemas.md create mode 100644 docs/ko/docs/how-to/testing-database.md create mode 100644 docs/ko/docs/tutorial/bigger-applications.md create mode 100644 docs/ko/docs/tutorial/body-updates.md create mode 100644 docs/ko/docs/tutorial/dependencies/sub-dependencies.md create mode 100644 docs/ko/docs/tutorial/handling-errors.md create mode 100644 docs/ko/docs/tutorial/security/first-steps.md create mode 100644 docs/ko/docs/tutorial/security/index.md diff --git a/docs/ko/docs/_llm-test.md b/docs/ko/docs/_llm-test.md new file mode 100644 index 0000000000..1b828c663e --- /dev/null +++ b/docs/ko/docs/_llm-test.md @@ -0,0 +1,503 @@ +# LLM 테슀튞 파음 { #llm-test-file } + +읎 묞서는 묞서륌 번역하는 LLM읎 `scripts/translate.py`의 `general_prompt`와 `docs/{language code}/llm-prompt.md`의 얞얎별 프롬프튞륌 읎핎하는지 테슀튞합니닀. 얞얎별 프롬프튞는 `general_prompt`에 추가됩니닀. + +여Ʞ에 추가된 테슀튞는 얞얎별 프롬프튞륌 섀계하는 몚든 사람읎 볎게 됩니닀. + +사용 방법은 닀음곌 같습니닀: + +* 얞얎별 프롬프튞 `docs/{language code}/llm-prompt.md`륌 쀀비합니닀. +* 읎 묞서륌 원하는 대상 ì–žì–Žë¡œ 새로 번역합니닀(예: `translate.py`의 `translate-page` 명령). 귞러멎 `docs/{language code}/docs/_llm-test.md` 아래에 번역읎 생성됩니닀. +* 번역에서 묞제가 없는지 확읞합니닀. +* 필요하닀멎 얞얎별 프롬프튞, 음반 프롬프튞, 또는 영얎 묞서륌 개선합니닀. +* 귞런 닀음 번역에서 ë‚šì•„ 있는 묞제륌 수동윌로 수정핎 좋은 번역읎 되게 합니닀. +* 좋은 번역을 둔 상태에서 닀시 번역합니닀. 읎상적읞 결곌는 LLM읎 더 읎상 번역에 변겜을 만듀지 않는 것입니닀. 읎는 음반 프롬프튞와 얞얎별 프롬프튞가 가능한 한 최선읎띌는 뜻입니닀(때때로 몇 가지 seemingly random 변겜을 할 수 있는데, ê·ž 읎유는 LLM은 결정론적 알고늬슘읎 아니Ʞ 때묞입니닀). + +테슀튞: + +## 윔드 슀니펫 { #code-snippets } + +//// tab | 테슀튞 + +닀음은 윔드 슀니펫입니닀: `foo`. 귞늬고 읎것은 또 닀륞 윔드 슀니펫입니닀: `bar`. 귞늬고 또 하나: `baz quux`. + +//// + +//// tab | 정볎 + +윔드 슀니펫의 낎용은 귞대로 두얎알 합니닀. + +`scripts/translate.py`의 음반 프롬프튞에서 `### Content of code snippets` 섹션을 찞고하섞요. + +//// + +## 따옎표 { #quotes } + +//// tab | 테슀튞 + +ì–Žì œ 제 친구가 읎렇게 썌습니닀: "If you spell incorrectly correctly, you have spelled it incorrectly". 읎에 저는 읎렇게 답했습니닀: "Correct, but 'incorrectly' is incorrectly not '"incorrectly"'"". + +/// note | ì°žê³  + +LLM은 아마 읎것을 잘못 번역할 것입니닀. 흥믞로욎 점은 재번역할 때 고정된 번역을 유지하는지 여부뿐입니닀. + +/// + +//// + +//// tab | 정볎 + +프롬프튞 섀계자는 쀑늜 따옎표륌 타읎포귞래플 따옎표로 변환할지 선택할 수 있습니닀. 귞대로 두얎도 ꎜ찮습니닀. + +예륌 듀얎 `docs/de/llm-prompt.md`의 `### Quotes` 섹션을 찞고하섞요. + +//// + +## 윔드 슀니펫의 따옎표 { #quotes-in-code-snippets } + +//// tab | 테슀튞 + +`pip install "foo[bar]"` + +윔드 슀니펫에서 묞자엎 늬터럎의 예: `"this"`, `'that'`. + +윔드 슀니펫에서 묞자엎 늬터럎의 얎렀욎 예: `f"I like {'oranges' if orange else "apples"}"` + +하드윔얎: `Yesterday, my friend wrote: "If you spell incorrectly correctly, you have spelled it incorrectly". To which I answered: "Correct, but 'incorrectly' is incorrectly not '"incorrectly"'"` + +//// + +//// tab | 정볎 + +... 하지만 윔드 슀니펫 안의 따옎표는 귞대로 유지되얎알 합니닀. + +//// + +## 윔드 랔록 { #code-blocks } + +//// tab | 테슀튞 + +Bash 윔드 예시... + +```bash +# 우죌에 읞사말 출력 +echo "Hello universe" +``` + +...귞늬고 윘솔 윔드 예시... + +```console +$ fastapi run main.py + FastAPI Starting server + Searching for package file structure +``` + +...귞늬고 또 닀륞 윘솔 윔드 예시... + +```console +// "Code" 디렉터늬 생성 +$ mkdir code +// 핎당 디렉터늬로 읎동 +$ cd code +``` + +...귞늬고 Python 윔드 예시... + +```Python +wont_work() # 읎걎 동작하지 않습니닀 😱 +works(foo="bar") # 읎걎 동작합니닀 🎉 +``` + +...읎상입니닀. + +//// + +//// tab | 정볎 + +윔드 랔록의 윔드는(죌석을 제왞하고) 수정하멎 안 됩니닀. + +`scripts/translate.py`의 음반 프롬프튞에서 `### Content of code blocks` 섹션을 찞고하섞요. + +//// + +## 탭곌 색상 박슀 { #tabs-and-colored-boxes } + +//// tab | 테슀튞 + +/// info | 정볎 +음부 텍슀튞 +/// + +/// note | ì°žê³  +음부 텍슀튞 +/// + +/// note Technical details | Ʞ술 섞부사항 +음부 텍슀튞 +/// + +/// check | 확읞 +음부 텍슀튞 +/// + +/// tip | 팁 +음부 텍슀튞 +/// + +/// warning | 겜고 +음부 텍슀튞 +/// + +/// danger | 위험 +음부 텍슀튞 +/// + +//// + +//// tab | 정볎 + +탭곌 `Info`/`Note`/`Warning`/등의 랔록은 제목 번역을 수직 막대(`|`) 뒀에 추가핎알 합니닀. + +`scripts/translate.py`의 음반 프롬프튞에서 `### Special blocks`와 `### Tab blocks` 섹션을 찞고하섞요. + +//// + +## 웹 및 낎부 링크 { #web-and-internal-links } + +//// tab | 테슀튞 + +링크 텍슀튞는 번역되얎알 하고, 링크 죌소는 변겜되지 ì•Šì•„ì•Œ 합니닀: + +* [위의 제목윌로 가는 링크](#code-snippets) +* [낎부 링크](index.md#installation){.internal-link target=_blank} +* 왞부 링크 +* 슀타음로 가는 링크 +* 슀크늜튞로 가는 링크 +* 읎믞지로 가는 링크 + +링크 텍슀튞는 번역되얎알 하고, 링크 죌소는 번역 페읎지륌 가늬쌜알 합니닀: + +* FastAPI 링크 + +//// + +//// tab | 정볎 + +링크는 번역되얎알 하지만, 죌소는 변겜되지 ì•Šì•„ì•Œ 합니닀. 예왞는 FastAPI 묞서 페읎지로 향하는 절대 링크읎며, 읎 겜우 번역 페읎지로 연결되얎알 합니닀. + +`scripts/translate.py`의 음반 프롬프튞에서 `### Links` 섹션을 찞고하섞요. + +//// + +## HTML "abbr" 요소 { #html-abbr-elements } + +//// tab | 테슀튞 + +여Ʞ HTML "abbr" 요소로 감싌 몇 가지가 있습니닀(음부는 임의로 만든 것입니닀): + +### abbr가 전첎 묞구륌 제공 { #the-abbr-gives-a-full-phrase } + +* GTD +* lt +* XWT +* PSGI + +### abbr가 섀명을 제공 { #the-abbr-gives-an-explanation } + +* cluster +* Deep Learning + +### abbr가 전첎 묞구와 섀명을 제공 { #the-abbr-gives-a-full-phrase-and-an-explanation } + +* MDN +* I/O. + +//// + +//// tab | 정볎 + +"abbr" 요소의 "title" 속성은 몇 가지 구첎적읞 지칚에 따띌 번역됩니닀. + +번역에서는(영얎 닚얎륌 섀명하Ʞ 위핎) 자첎 "abbr" 요소륌 추가할 수 있윌며, LLM은 읎륌 제거하멎 안 됩니닀. + +`scripts/translate.py`의 음반 프롬프튞에서 `### HTML abbr elements` 섹션을 찞고하섞요. + +//// + +## 제목 { #headings } + +//// tab | 테슀튞 + +### 웹앱 개발하Ʞ - 튜토늬얌 { #develop-a-webapp-a-tutorial } + +안녕하섞요. + +### 타입 힌튞와 -애너테읎션 { #type-hints-and-annotations } + +닀시 안녕하섞요. + +### super- 및 subclasses { #super-and-subclasses } + +닀시 안녕하섞요. + +//// + +//// tab | 정볎 + +제목에 대한 유음한 강한 규칙은, LLM읎 쀑ꎄ혞 안의 í•Žì‹œ 부분을 변겜하지 않아 링크가 깚지지 않게 하는 것입니닀. + +`scripts/translate.py`의 음반 프롬프튞에서 `### Headings` 섹션을 찞고하섞요. + +얞얎별 지칚은 예륌 듀얎 `docs/de/llm-prompt.md`의 `### Headings` 섹션을 찞고하섞요. + +//// + +## 묞서에서 사용되는 ìš©ì–Ž { #terms-used-in-the-docs } + +//// tab | 테슀튞 + +* 당신 +* 당신의 + +* 예: (e.g.) +* 등 (etc.) + +* `int`로서의 `foo` +* `str`로서의 `bar` +* `list`로서의 `baz` + +* 튜토늬얌 - 사용자 가읎드 +* 고꞉ 사용자 가읎드 +* SQLModel 묞서 +* API 묞서 +* 자동 묞서 + +* Data Science +* Deep Learning +* Machine Learning +* Dependency Injection +* HTTP Basic authentication +* HTTP Digest +* ISO format +* JSON Schema 표쀀 +* JSON schema +* schema definition +* Password Flow +* Mobile + +* deprecated +* designed +* invalid +* on the fly +* standard +* default +* case-sensitive +* case-insensitive + +* 애플늬쌀읎션을 서빙하닀 +* 페읎지륌 서빙하닀 + +* 앱 +* 애플늬쌀읎션 + +* 요청 +* 응답 +* 였류 응답 + +* 겜로 처늬 +* 겜로 처늬 데윔레읎터 +* 겜로 처늬 핚수 + +* body +* 요청 body +* 응답 body +* JSON body +* form body +* file body +* 핚수 body + +* parameter +* body parameter +* path parameter +* query parameter +* cookie parameter +* header parameter +* form parameter +* function parameter + +* event +* startup event +* 서버 startup +* shutdown event +* lifespan event + +* handler +* event handler +* exception handler +* 처늬하닀 + +* model +* Pydantic model +* data model +* database model +* form model +* model object + +* class +* base class +* parent class +* subclass +* child class +* sibling class +* class method + +* header +* headers +* authorization header +* `Authorization` header +* forwarded header + +* dependency injection system +* dependency +* dependable +* dependant + +* I/O bound +* CPU bound +* concurrency +* parallelism +* multiprocessing + +* env var +* environment variable +* `PATH` +* `PATH` variable + +* authentication +* authentication provider +* authorization +* authorization form +* authorization provider +* 사용자가 읞슝한닀 +* 시슀템읎 사용자륌 읞슝한닀 + +* CLI +* command line interface + +* server +* client + +* cloud provider +* cloud service + +* development +* development stages + +* dict +* dictionary +* enumeration +* enum +* enum member + +* encoder +* decoder +* encode하닀 +* decode하닀 + +* exception +* raise하닀 + +* expression +* statement + +* frontend +* backend + +* GitHub discussion +* GitHub issue + +* performance +* performance optimization + +* return type +* return value + +* security +* security scheme + +* task +* background task +* task function + +* template +* template engine + +* type annotation +* type hint + +* server worker +* Uvicorn worker +* Gunicorn Worker +* worker process +* worker class +* workload + +* deployment +* deploy하닀 + +* SDK +* software development kit + +* `APIRouter` +* `requirements.txt` +* Bearer Token +* breaking change +* bug +* button +* callable +* code +* commit +* context manager +* coroutine +* database session +* disk +* domain +* engine +* fake X +* HTTP GET method +* item +* library +* lifespan +* lock +* middleware +* mobile application +* module +* mounting +* network +* origin +* override +* payload +* processor +* property +* proxy +* pull request +* query +* RAM +* remote machine +* status code +* string +* tag +* web framework +* wildcard +* return하닀 +* validate하닀 + +//// + +//// tab | 정볎 + +읎것은 묞서에서 볎읎는 (대부분) Ʞ술 용얎의 불완전하고 비규범적읞 목록입니닀. 프롬프튞 섀계자가 ì–Žë–€ 용얎에 대핮 LLM에 추가적읞 도움읎 필요한지 파악하는 데 유용할 수 있습니닀. 예륌 듀얎, 좋은 번역을 계속 덜 좋은 번역윌로 되돌멮 때, 또는 얞얎에서 용얎의 활용/변화륌 처늬하는 데 묞제가 있을 때 도움읎 됩니닀. + +예륌 듀얎 `docs/de/llm-prompt.md`의 `### List of English terms and their preferred German translations` 섹션을 찞고하섞요. + +//// diff --git a/docs/ko/docs/advanced/additional-responses.md b/docs/ko/docs/advanced/additional-responses.md new file mode 100644 index 0000000000..a6f51f5b93 --- /dev/null +++ b/docs/ko/docs/advanced/additional-responses.md @@ -0,0 +1,247 @@ +# OpenAPI에서 추가 응답 { #additional-responses-in-openapi } + +/// warning | 겜고 + +읎는 ꜀ 고꞉ 죌제입니닀. + +**FastAPI**륌 막 시작했닀멎, 읎 낎용읎 필요 없을 수도 있습니닀. + +/// + +추가 상태 윔드, 믞디얎 타입, 섀명 등을 포핚한 추가 응답을 ì„ ì–ží•  수 있습니닀. + +읎러한 추가 응답은 OpenAPI 슀킀마에 포핚되므로 API 묞서에도 표시됩니닀. + +하지만 읎러한 추가 응답의 겜우, 상태 윔드와 윘텐잠륌 포핚하여 `JSONResponse` 같은 `Response`륌 직접 반환하도록 반드시 처늬핎알 합니닀. + +## `model`을 사용한 추가 응답 { #additional-response-with-model } + +*겜로 처늬 데윔레읎터*에 `responses` 파띌믞터륌 전달할 수 있습니닀. + +읎는 `dict`륌 받습니닀. 킀는 각 응답의 상태 윔드(예: `200`)읎고, 값은 각 응답에 대한 정볎륌 닎은 닀륞 `dict`입니닀. + +각 응답 `dict`에는 `response_model`처럌 Pydantic 몚덞을 닮는 `model` 킀가 있을 수 있습니닀. + +**FastAPI**는 ê·ž 몚덞을 사용핎 JSON Schema륌 생성하고, OpenAPI의 올바륞 위치에 포핚합니닀. + +예륌 듀얎, 상태 윔드 `404`와 Pydantic 몚덞 `Message`륌 사용하는 닀륞 응답을 선얞하렀멎 닀음곌 같읎 작성할 수 있습니닀: + +{* ../../docs_src/additional_responses/tutorial001_py39.py hl[18,22] *} + +/// note | ì°žê³  + +`JSONResponse`륌 직접 반환핎알 한닀는 점을 Ʞ억하섞요. + +/// + +/// info | 정볎 + +`model` 킀는 OpenAPI의 음부가 아닙니닀. + +**FastAPI**는 여Ʞ에서 Pydantic 몚덞을 가젞와 JSON Schema륌 생성하고 올바륞 위치에 넣습니닀. + +올바륞 위치는 닀음곌 같습니닀: + +* 값윌로 또 닀륞 JSON 객첎(`dict`)륌 가지는 `content` í‚€ 안에: + * 믞디얎 타입(예: `application/json`)을 킀로 가지며, 값윌로 또 닀륞 JSON 객첎륌 포핚하고: + * `schema` 킀가 있고, ê·ž 값읎 몚덞에서 생성된 JSON Schema입니닀. 읎것읎 올바륞 위치입니닀. + * **FastAPI**는 읎륌 직접 포핚하는 대신, OpenAPI의 닀륞 위치에 있는 전역 JSON Schemas륌 찞조하도록 여Ʞ에서 reference륌 추가합니닀. 읎렇게 하멎 닀륞 애플늬쌀읎션곌 큎띌읎얞튞가 ê·ž JSON Schema륌 직접 사용할 수 있고, 더 나은 윔드 생성 도구 등을 제공할 수 있습니닀. + +/// + +읎 *겜로 처늬*에 대핮 OpenAPI에 생성되는 응답은 닀음곌 같습니닀: + +```JSON hl_lines="3-12" +{ + "responses": { + "404": { + "description": "Additional Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Message" + } + } + } + }, + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Item" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } +} +``` + +슀킀마는 OpenAPI 슀킀마 낎부의 닀륞 위치륌 찞조합니닀: + +```JSON hl_lines="4-16" +{ + "components": { + "schemas": { + "Message": { + "title": "Message", + "required": [ + "message" + ], + "type": "object", + "properties": { + "message": { + "title": "Message", + "type": "string" + } + } + }, + "Item": { + "title": "Item", + "required": [ + "id", + "value" + ], + "type": "object", + "properties": { + "id": { + "title": "Id", + "type": "string" + }, + "value": { + "title": "Value", + "type": "string" + } + } + }, + "ValidationError": { + "title": "ValidationError", + "required": [ + "loc", + "msg", + "type" + ], + "type": "object", + "properties": { + "loc": { + "title": "Location", + "type": "array", + "items": { + "type": "string" + } + }, + "msg": { + "title": "Message", + "type": "string" + }, + "type": { + "title": "Error Type", + "type": "string" + } + } + }, + "HTTPValidationError": { + "title": "HTTPValidationError", + "type": "object", + "properties": { + "detail": { + "title": "Detail", + "type": "array", + "items": { + "$ref": "#/components/schemas/ValidationError" + } + } + } + } + } + } +} +``` + +## 죌요 응답에 대한 추가 믞디얎 타입 { #additional-media-types-for-the-main-response } + +같은 `responses` 파띌믞터륌 사용핎 동음한 죌요 응답에 대핮 닀륞 믞디얎 타입을 추가할 수도 있습니닀. + +예륌 듀얎, *겜로 처늬*가 JSON 객첎(믞디얎 타입 `application/json`) 또는 PNG 읎믞지(믞디얎 타입 `image/png`)륌 반환할 수 있닀고 선얞하Ʞ 위핎 `image/png`띌는 추가 믞디얎 타입을 추가할 수 있습니닀: + +{* ../../docs_src/additional_responses/tutorial002_py310.py hl[17:22,26] *} + +/// note | ì°žê³  + +읎믞지는 `FileResponse`륌 사용핎 직접 반환핎알 한닀는 점에 유의하섞요. + +/// + +/// info | 정볎 + +`responses` 파띌믞터에서 닀륞 믞디얎 타입을 명시적윌로 지정하지 않는 한, FastAPI는 응답읎 죌요 응답 큎래슀와 동음한 믞디얎 타입(Ʞ볞값 `application/json`)을 가진닀고 가정합니닀. + +하지만 컀슀텀 응답 큎래슀륌 지정하멎서 믞디얎 타입을 `None`윌로 섀정했닀멎, FastAPI는 연결된 몚덞읎 있는 몚든 추가 응답에 대핮 `application/json`을 사용합니닀. + +/// + +## 정볎 결합하Ʞ { #combining-information } + +`response_model`, `status_code`, `responses` 파띌믞터륌 포핚핎 여러 위치의 응답 정볎륌 결합할 수도 있습니닀. + +Ʞ볞 상태 윔드 `200`(또는 필요하닀멎 컀슀텀 윔드)을 사용하여 `response_model`을 선얞하고, 귞와 동음한 응답에 대한 추가 정볎륌 `responses`에서 OpenAPI 슀킀마에 직접 ì„ ì–ží•  수 있습니닀. + +**FastAPI**는 `responses`의 추가 정볎륌 유지하고, 몚덞의 JSON Schema와 결합합니닀. + +예륌 듀얎, Pydantic 몚덞을 사용하고 컀슀텀 `description`을 가진 상태 윔드 `404` 응답을 ì„ ì–ží•  수 있습니닀. + +또한 `response_model`을 사용하는 상태 윔드 `200` 응답을 선얞하되, 컀슀텀 `example`을 포핚할 수도 있습니닀: + +{* ../../docs_src/additional_responses/tutorial003_py39.py hl[20:31] *} + +읎 몚든 낎용은 OpenAPI에 결합되얎 포핚되고, API 묞서에 표시됩니닀: + + + +## 믞늬 정의된 응답곌 컀슀텀 응답 결합하Ʞ { #combine-predefined-responses-and-custom-ones } + +여러 *겜로 처늬*에 적용되는 믞늬 정의된 응답읎 필요할 수도 있지만, 각 *겜로 처늬*마닀 필요한 컀슀텀 응답곌 결합하고 싶을 수도 있습니닀. + +귞런 겜우 Python의 `dict` “unpacking” Ʞ법읞 `**dict_to_unpack`을 사용할 수 있습니닀: + +```Python +old_dict = { + "old key": "old value", + "second old key": "second old value", +} +new_dict = {**old_dict, "new key": "new value"} +``` + +여Ʞ서 `new_dict`는 `old_dict`의 몚든 í‚€-값 쌍에 더핮 새 í‚€-값 쌍까지 포핚합니닀: + +```Python +{ + "old key": "old value", + "second old key": "second old value", + "new key": "new value", +} +``` + +읎 Ʞ법을 사용핎 *겜로 처늬*에서 음부 믞늬 정의된 응답을 재사용하고, 추가 컀슀텀 응답곌 결합할 수 있습니닀. + +예륌 듀얎: + +{* ../../docs_src/additional_responses/tutorial004_py310.py hl[11:15,24] *} + +## OpenAPI 응답에 대한 추가 정볎 { #more-information-about-openapi-responses } + +응답에 정확히 묎엇을 포핚할 수 있는지 볎렀멎, OpenAPI 사양의 닀음 섹션을 확읞하섞요: + +* OpenAPI Responses Object: `Response Object`륌 포핚합니닀. +* OpenAPI Response Object: `responses` 파띌믞터 안의 각 응답에 읎것의 ì–Žë–€ 항목읎든 직접 포핚할 수 있습니닀. `description`, `headers`, `content`(여Ʞ에서 서로 닀륞 믞디얎 타입곌 JSON Schema륌 선얞합니닀), `links` 등을 포핚할 수 있습니닀. diff --git a/docs/ko/docs/advanced/behind-a-proxy.md b/docs/ko/docs/advanced/behind-a-proxy.md new file mode 100644 index 0000000000..92bddac51a --- /dev/null +++ b/docs/ko/docs/advanced/behind-a-proxy.md @@ -0,0 +1,466 @@ +# 프록시 뒀에서 싀행하Ʞ { #behind-a-proxy } + +많은 겜우 FastAPI 앱 앞닚에 Traefik읎나 Nginx 같은 **프록시(proxy)**륌 두고 사용합니닀. + +읎런 프록시는 HTTPS 읞슝서 처늬 등 여러 작업을 닎당할 수 있습니닀. + +## 프록시 전달 헀더 { #proxy-forwarded-headers } + +애플늬쌀읎션 앞닚의 **프록시**는 볎통 **서버**로 요청을 볎낎Ʞ 전에, 핎당 요청읎 프록시에 의핎 **전달(forwarded)**되었닀는 것을 서버가 알 수 있도록 몇몇 헀더륌 동적윌로 섀정합니닀. 읎륌 통핎 서버는 도메읞을 포핚한 원래의 (공개) URL, HTTPS 사용 여부 등 정볎륌 알 수 있습니닀. + +**서버** 프로귞랚(예: **FastAPI CLI**륌 통핎 싀행되는 **Uvicorn**)은 읎런 헀더륌 핎석할 수 있고, ê·ž 정볎륌 애플늬쌀읎션윌로 전달할 수 있습니닀. + +하지만 볎안상, 서버는 자신읎 신뢰할 수 있는 프록시 뒀에 있닀는 것을 몚륎멎 핎당 헀더륌 핎석하지 않습니닀. + +/// note | Ʞ술 섞부사항 + +프록시 헀더는 닀음곌 같습니닀: + +* X-Forwarded-For +* X-Forwarded-Proto +* X-Forwarded-Host + +/// + +### 프록시 전달 헀더 활성화하Ʞ { #enable-proxy-forwarded-headers } + +FastAPI CLI륌 *CLI 옵션* `--forwarded-allow-ips`로 싀행하고, 전달 헀더륌 읜을 수 있도록 신뢰할 IP 죌소듀을 넘Ꞟ 수 있습니닀. + +`--forwarded-allow-ips="*"`로 섀정하멎 듀얎였는 몚든 IP륌 신뢰합니닀. + +**서버**가 신뢰할 수 있는 **프록시** 뒀에 있고 프록시만 서버에 접귌한닀멎, 읎는 핎당 **프록시**의 IP가 묎엇읎든 간에 받아듀읎게 됩니닀. + +
+ +```console +$ fastapi run --forwarded-allow-ips="*" + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +### HTTPS에서 늬디렉션 { #redirects-with-https } + +예륌 듀얎, *겜로 처늬* `/items/`륌 정의했닀고 핎뎅시닀: + +{* ../../docs_src/behind_a_proxy/tutorial001_01_py39.py hl[6] *} + +큎띌읎얞튞가 `/items`로 접귌하멎, Ʞ볞적윌로 `/items/`로 늬디렉션됩니닀. + +하지만 *CLI 옵션* `--forwarded-allow-ips`륌 섀정하Ʞ 전에는 `http://localhost:8000/items/`로 늬디렉션될 수 있습니닀. + +귞런데 애플늬쌀읎션읎 `https://mysuperapp.com`에 혞슀팅되얎 있고, 늬디렉션도 `https://mysuperapp.com/items/`로 되얎알 할 수 있습니닀. + +읎때 `--proxy-headers`륌 섀정하멎 FastAPI가 올바륞 위치로 늬디렉션할 수 있습니닀. 😎 + +``` +https://mysuperapp.com/items/ +``` + +/// tip | 팁 + +HTTPS에 대핮 더 알아볎렀멎 가읎드 [HTTPS에 대하여](../deployment/https.md){.internal-link target=_blank}륌 확읞하섞요. + +/// + +### 프록시 전달 헀더가 동작하는 방식 { #how-proxy-forwarded-headers-work } + +닀음은 **프록시**가 큎띌읎얞튞와 **애플늬쌀읎션 서버** 사읎에서 전달 헀더륌 추가하는 곌정을 시각적윌로 나타낾 것입니닀: + +```mermaid +sequenceDiagram + participant Client + participant Proxy as Proxy/Load Balancer + participant Server as FastAPI Server + + Client->>Proxy: HTTPS Request
Host: mysuperapp.com
Path: /items + + Note over Proxy: Proxy adds forwarded headers + + Proxy->>Server: HTTP Request
X-Forwarded-For: [client IP]
X-Forwarded-Proto: https
X-Forwarded-Host: mysuperapp.com
Path: /items + + Note over Server: Server interprets headers
(if --forwarded-allow-ips is set) + + Server->>Proxy: HTTP Response
with correct HTTPS URLs + + Proxy->>Client: HTTPS Response +``` + +**프록시**는 원래의 큎띌읎얞튞 요청을 가로채고, **애플늬쌀읎션 서버**로 요청을 전달하Ʞ 전에 특수한 *forwarded* 헀더(`X-Forwarded-*`)륌 추가합니닀. + +읎 헀더듀은 귞렇지 않윌멎 사띌질 수 있는 원래 요청의 정볎륌 볎졎합니닀: + +* **X-Forwarded-For**: 원래 큎띌읎얞튞의 IP 죌소 +* **X-Forwarded-Proto**: 원래 프로토윜(`https`) +* **X-Forwarded-Host**: 원래 혞슀튞(`mysuperapp.com`) + +**FastAPI CLI**륌 `--forwarded-allow-ips`로 섀정하멎, 읎 헀더륌 신뢰하고 사용합니닀. 예륌 듀얎 늬디렉션에서 올바륞 URL을 생성하는 데 사용됩니닀. + +## 제거된 겜로 접두사륌 가진 프록시 { #proxy-with-a-stripped-path-prefix } + +애플늬쌀읎션에 겜로 접두사(prefix)륌 추가하는 프록시륌 둘 수도 있습니닀. + +읎런 겜우 `root_path`륌 사용핎 애플늬쌀읎션을 구성할 수 있습니닀. + +`root_path`는 (FastAPI가 Starlette륌 통핎 Ʞ반윌로 하는) ASGI 사양에서 제공하는 메컀니슘입니닀. + +`root_path`는 읎러한 특정 사례륌 처늬하는 데 사용됩니닀. + +또한 서람 애플늬쌀읎션을 마욎튞할 때 낎부적윌로도 사용됩니닀. + +겜로 접두사가 제거(stripped)되는 프록시가 있닀는 것은, 윔드에서는 `/app`에 겜로륌 선얞하지만, 위에 한 ê²¹(프록시)을 추가핎 **FastAPI** 애플늬쌀읎션을 `/api/v1` 같은 겜로 아래에 두는 것을 의믞합니닀. + +읎 겜우 원래 겜로 `/app`은 싀제로 `/api/v1/app`에서 서비슀됩니닀. + +윔드는 몚두 `/app`만 있닀고 가정하고 작성되얎 있는데도 말입니닀. + +{* ../../docs_src/behind_a_proxy/tutorial001_py39.py hl[6] *} + +귞늬고 프록시는 요청을 앱 서버(아마 FastAPI CLI륌 통핎 싀행되는 Uvicorn)로 전달하Ʞ 전에, 동적윌로 **겜로 접두사**륌 **"제거"**합니닀. 귞래서 애플늬쌀읎션은 여전히 `/app`에서 서비슀된닀고 믿게 되고, 윔드 전첎륌 `/api/v1` 접두사륌 포핚하도록 수정할 필요가 없얎집니닀. + +여Ʞ까지는 볎통 정상적윌로 동작합니닀. + +하지만 통합 묞서 UI(프론튞엔드)륌 ì—Žë©Ž, OpenAPI 슀킀마륌 `/api/v1/openapi.json`읎 아니띌 `/openapi.json`에서 가젞였렀고 합니닀. + +귞래서 람띌우저에서 싀행되는 프론튞엔드는 `/openapi.json`에 접귌하렀고 시도하지만 OpenAPI 슀킀마륌 얻지 못합니닀. + +앱에 대핮 `/api/v1` 겜로 접두사륌 가진 프록시가 있윌므로, 프론튞엔드는 `/api/v1/openapi.json`에서 OpenAPI 슀킀마륌 가젞와알 합니닀. + +```mermaid +graph LR + +browser("Browser") +proxy["Proxy on http://0.0.0.0:9999/api/v1/app"] +server["Server on http://127.0.0.1:8000/app"] + +browser --> proxy +proxy --> server +``` + +/// tip | 팁 + +IP `0.0.0.0`은 볎통 핎당 ëšžì‹ /서버에서 사용 가능한 몚든 IP에서 프로귞랚읎 늬슚한닀는 의믞로 사용됩니닀. + +/// + +묞서 UI는 또한 OpenAPI 슀킀마에서 읎 API `server`가 `/api/v1`(프록시 ë’€) 위치에 있닀고 ì„ ì–ží•Žì•Œ 합니닀. 예: + +```JSON hl_lines="4-8" +{ + "openapi": "3.1.0", + // More stuff here + "servers": [ + { + "url": "/api/v1" + } + ], + "paths": { + // More stuff here + } +} +``` + +읎 예시에서 "Proxy"는 **Traefik** 같은 것읎고, 서버는 **Uvicorn**윌로 싀행되는 FastAPI CLI처럌, FastAPI 애플늬쌀읎션을 싀행하는 구성음 수 있습니닀. + +### `root_path` 제공하Ʞ { #providing-the-root-path } + +읎륌 달성하렀멎 닀음처럌 컀맚드 띌읞 옵션 `--root-path`륌 사용할 수 있습니닀: + +
+ +```console +$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +Hypercorn을 사용한닀멎, Hypercorn에도 `--root-path` 옵션읎 있습니닀. + +/// note | Ʞ술 섞부사항 + +ASGI 사양은 읎 사용 사례륌 위핎 `root_path`륌 정의합니닀. + +귞늬고 컀맚드 띌읞 옵션 `--root-path`가 ê·ž `root_path`륌 제공합니닀. + +/// + +### 현재 `root_path` 확읞하Ʞ { #checking-the-current-root-path } + +요청마닀 애플늬쌀읎션에서 사용 쀑읞 현재 `root_path`륌 얻을 수 있는데, 읎는 `scope` 딕셔너늬(ASGI 사양의 음부)에 포핚되얎 있습니닀. + +여Ʞ서는 데몚 목적을 위핎 메시지에 포핚하고 있습니닀. + +{* ../../docs_src/behind_a_proxy/tutorial001_py39.py hl[8] *} + +ê·ž 닀음 Uvicorn을 닀음곌 같읎 시작하멎: + +
+ +```console +$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +응답은 닀음곌 비슷할 것입니닀: + +```JSON +{ + "message": "Hello World", + "root_path": "/api/v1" +} +``` + +### FastAPI 앱에서 `root_path` 섀정하Ʞ { #setting-the-root-path-in-the-fastapi-app } + +또는 `--root-path` 같은 컀맚드 띌읞 옵션(또는 동등한 방법)을 제공할 수 없는 겜우, FastAPI 앱을 생성할 때 `root_path` 파띌믞터륌 섀정할 수 있습니닀: + +{* ../../docs_src/behind_a_proxy/tutorial002_py39.py hl[3] *} + +`FastAPI`에 `root_path`륌 전달하는 것은 Uvicorn읎나 Hypercorn에 컀맚드 띌읞 옵션 `--root-path`륌 전달하는 것곌 동음합니닀. + +### `root_path`에 대하여 { #about-root-path } + +서버(Uvicorn)는 ê·ž `root_path`륌 앱에 전달하는 것 왞에는 닀륞 용도로 사용하지 않는닀는 점을 Ʞ억하섞요. + +하지만 람띌우저로 http://127.0.0.1:8000/app에 접속하멎 정상 응답을 볌 수 있습니닀: + +```JSON +{ + "message": "Hello World", + "root_path": "/api/v1" +} +``` + +따띌서 `http://127.0.0.1:8000/api/v1/app`로 접귌될 것읎띌고 Ʞ대하지는 않습니닀. + +Uvicorn은 프록시가 `http://127.0.0.1:8000/app`에서 Uvicorn에 접귌할 것을 Ʞ대하고, ê·ž 위에 `/api/v1` 접두사륌 추가하는 것은 프록시의 책임입니닀. + +## 제거된 겜로 접두사륌 가진 프록시에 대하여 { #about-proxies-with-a-stripped-path-prefix } + +겜로 접두사가 제거되는 프록시는 구성 방법 쀑 하나음 뿐읎띌는 점을 Ʞ억하섞요. + +많은 겜우 Ʞ볞값은 프록시가 겜로 접두사륌 제거하지 않는 방식음 것입니닀. + +귞런 겜우(겜로 접두사륌 제거하지 않는 겜우) 프록시는 `https://myawesomeapp.com` 같은 곳에서 늬슚하고, 람띌우저가 `https://myawesomeapp.com/api/v1/app`로 접귌하멎, 서버(예: Uvicorn)가 `http://127.0.0.1:8000`에서 늬슚하고 있을 때 프록시(겜로 접두사륌 제거하지 않는)는 동음한 겜로로 Uvicorn에 접귌합니닀: `http://127.0.0.1:8000/api/v1/app`. + +## Traefik윌로 로컬 테슀튞하Ʞ { #testing-locally-with-traefik } + +Traefik을 사용하멎, 겜로 접두사가 제거되는 구성을 로컬에서 쉜게 싀험할 수 있습니닀. + +Traefik 닀욎로드는 닚음 바읎너늬읎며, 압축 파음을 풀고 터믞널에서 바로 싀행할 수 있습니닀. + +ê·ž 닀음 닀음 낎용을 가진 `traefik.toml` 파음을 생성하섞요: + +```TOML hl_lines="3" +[entryPoints] + [entryPoints.http] + address = ":9999" + +[providers] + [providers.file] + filename = "routes.toml" +``` + +읎는 Traefik읎 9999 포튞에서 늬슚하고, 닀륞 파음 `routes.toml`을 사용하도록 지시합니닀. + +/// tip | 팁 + +표쀀 HTTP 포튞 80 대신 9999 포튞륌 사용핎서, ꎀ늬자(`sudo`) 권한윌로 싀행하지 않아도 되게 했습니닀. + +/// + +읎제 닀륞 파음 `routes.toml`을 생성하섞요: + +```TOML hl_lines="5 12 20" +[http] + [http.middlewares] + + [http.middlewares.api-stripprefix.stripPrefix] + prefixes = ["/api/v1"] + + [http.routers] + + [http.routers.app-http] + entryPoints = ["http"] + service = "app" + rule = "PathPrefix(`/api/v1`)" + middlewares = ["api-stripprefix"] + + [http.services] + + [http.services.app] + [http.services.app.loadBalancer] + [[http.services.app.loadBalancer.servers]] + url = "http://127.0.0.1:8000" +``` + +읎 파음은 Traefik읎 겜로 접두사 `/api/v1`을 사용하도록 섀정합니닀. + +귞늬고 Traefik은 요청을 `http://127.0.0.1:8000`에서 싀행 쀑읞 Uvicorn윌로 전달합니닀. + +읎제 Traefik을 시작하섞요: + +
+ +```console +$ ./traefik --configFile=traefik.toml + +INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml +``` + +
+ +귞늬고 `--root-path` 옵션을 사용핎 앱을 시작하섞요: + +
+ +```console +$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +### 응답 확읞하Ʞ { #check-the-responses } + +읎제 Uvicorn의 포튞로 된 URL읞 http://127.0.0.1:8000/app로 접속하멎 정상 응답을 볌 수 있습니닀: + +```JSON +{ + "message": "Hello World", + "root_path": "/api/v1" +} +``` + +/// tip | 팁 + +`http://127.0.0.1:8000/app`로 접귌했는데도 `/api/v1`의 `root_path`가 표시되는 것에 죌의하섞요. 읎는 옵션 `--root-path`에서 가젞옚 값입니닀. + +/// + +읎제 Traefik의 포튞가 포핚되고 겜로 접두사가 포핚된 URL http://127.0.0.1:9999/api/v1/app을 여섞요. + +동음한 응답을 얻습니닀: + +```JSON +{ + "message": "Hello World", + "root_path": "/api/v1" +} +``` + +하지만 읎번에는 프록시가 제공한 접두사 겜로 `/api/v1`읎 포핚된 URL에서의 응답입니닀. + +묌론 여Ʞ서의 아읎디얎는 몚두가 프록시륌 통핎 앱에 접귌한닀는 것읎므로, `/api/v1` 겜로 접두사가 있는 버전읎 "올바륞" 접귌입니닀. + +귞늬고 겜로 접두사가 없는 버전(`http://127.0.0.1:8000/app`)은 Uvicorn읎 직접 제공하는 것읎며, 였직 _프록시_(Traefik)가 접귌하Ʞ 위한 용도입니닀. + +읎는 프록시(Traefik)가 겜로 접두사륌 얎떻게 사용하는지, 귞늬고 서버(Uvicorn)가 옵션 `--root-path`로부터의 `root_path`륌 얎떻게 사용하는지륌 볎여쀍니닀. + +### 묞서 UI 확읞하Ʞ { #check-the-docs-ui } + +하지만 재믞있는 부분은 여Ʞ입니닀. ✹ + +앱에 접귌하는 "공식" 방법은 우늬가 정의한 겜로 접두사륌 가진 프록시륌 통핎서입니닀. 따띌서 Ʞ대하는 대로, URL에 겜로 접두사가 없는 상태에서 Uvicorn읎 직접 제공하는 docs UI륌 시도하멎, 프록시륌 통핎 접귌된닀고 가정하고 있Ʞ 때묞에 동작하지 않습니닀. + +http://127.0.0.1:8000/docs에서 확읞할 수 있습니닀: + + + +하지만 프록시(포튞 `9999`)륌 사용핎 "공식" URL읞 `/api/v1/docs`에서 docs UI에 접귌하멎, 올바륎게 동작합니닀! 🎉 + +http://127.0.0.1:9999/api/v1/docs에서 확읞할 수 있습니닀: + + + +원하던 귞대로입니닀. ✔ + +읎는 FastAPI가 읎 `root_path`륌 사용핎, OpenAPI에서 Ʞ볞 `server`륌 `root_path`가 제공한 URL로 생성하Ʞ 때묞입니닀. + +## 추가 서버 { #additional-servers } + +/// warning | 겜고 + +읎는 더 고꞉ 사용 사례입니닀. 걎너뛰얎도 ꎜ찮습니닀. + +/// + +Ʞ볞적윌로 **FastAPI**는 OpenAPI 슀킀마에서 `root_path`의 URL로 `server`륌 생성합니닀. + +하지만 예륌 듀얎 동음한 docs UI가 슀테읎징곌 프로덕션 환겜 몚두와 상혞작용하도록 하렀멎, 닀륞 대안 `servers`륌 제공할 수도 있습니닀. + +사용자 정의 `servers` 늬슀튞륌 전달했고 `root_path`(API가 프록시 뒀에 있Ʞ 때묞)가 있닀멎, **FastAPI**는 늬슀튞의 맚 앞에 읎 `root_path`륌 가진 "server"륌 삜입합니닀. + +예: + +{* ../../docs_src/behind_a_proxy/tutorial003_py39.py hl[4:7] *} + +닀음곌 같은 OpenAPI 슀킀마륌 생성합니닀: + +```JSON hl_lines="5-7" +{ + "openapi": "3.1.0", + // More stuff here + "servers": [ + { + "url": "/api/v1" + }, + { + "url": "https://stag.example.com", + "description": "Staging environment" + }, + { + "url": "https://prod.example.com", + "description": "Production environment" + } + ], + "paths": { + // More stuff here + } +} +``` + +/// tip | 팁 + +`root_path`에서 가젞옚 값읞 `/api/v1`의 `url` 값을 가진, 자동 생성된 server에 죌목하섞요. + +/// + +http://127.0.0.1:9999/api/v1/docs의 docs UI에서는 닀음처럌 볎입니닀: + + + +/// tip | 팁 + +docs UI는 선택한 server와 상혞작용합니닀. + +/// + +/// note | Ʞ술 섞부사항 + +OpenAPI 사양에서 `servers` 속성은 선택 사항입니닀. + +`servers` 파띌믞터륌 지정하지 않고 `root_path`가 `/`와 같닀멎, 생성된 OpenAPI 슀킀마의 `servers` 속성은 Ʞ볞적윌로 완전히 생략되며, 읎는 `url` 값읎 `/`읞 닚음 server와 동등합니닀. + +/// + +### `root_path`에서 자동 server 비활성화하Ʞ { #disable-automatic-server-from-root-path } + +**FastAPI**가 `root_path`륌 사용한 자동 server륌 포핚하지 않게 하렀멎, `root_path_in_servers=False` 파띌믞터륌 사용할 수 있습니닀: + +{* ../../docs_src/behind_a_proxy/tutorial004_py39.py hl[9] *} + +귞러멎 OpenAPI 슀킀마에 포핚되지 않습니닀. + +## 서람 애플늬쌀읎션 마욎튞하Ʞ { #mounting-a-sub-application } + +프록시에서 `root_path`륌 사용하멎서도, [서람 애플늬쌀읎션 - 마욎튞](sub-applications.md){.internal-link target=_blank}에 섀명된 것처럌 서람 애플늬쌀읎션을 마욎튞핎알 한닀멎, Ʞ대하는 대로 음반적윌로 수행할 수 있습니닀. + +FastAPI가 낎부적윌로 `root_path`륌 똑똑하게 사용하므로, 귞냥 동작합니닀. ✹ diff --git a/docs/ko/docs/advanced/dataclasses.md b/docs/ko/docs/advanced/dataclasses.md new file mode 100644 index 0000000000..92ad5545b3 --- /dev/null +++ b/docs/ko/docs/advanced/dataclasses.md @@ -0,0 +1,95 @@ +# Dataclasses 사용하Ʞ { #using-dataclasses } + +FastAPI는 **Pydantic** 위에 구축되얎 있윌며, 지ꞈ까지는 Pydantic 몚덞을 사용핎 요청곌 응답을 선얞하는 방법을 볎여드렞습니닀. + +하지만 FastAPI는 `dataclasses`도 같은 방식윌로 사용하는 것을 지원합니닀: + +{* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} + +읎는 **Pydantic** 덕분에 여전히 지원되는데, Pydantic읎 `dataclasses`에 대한 낎부 지원을 제공하Ʞ 때묞입니닀. + +따띌서 위 윔드처럌 Pydantic을 명시적윌로 사용하지 않더띌도, FastAPI는 Pydantic을 사용핎 표쀀 dataclasses륌 Pydantic의 dataclasses 변형윌로 변환합니닀. + +귞늬고 묌론 닀음곌 같은 Ʞ능도 동음하게 지원합니닀: + +* 데읎터 검슝 +* 데읎터 직렬화 +* 데읎터 묞서화 등 + +읎는 Pydantic 몚덞을 사용할 때와 같은 방식윌로 동작합니닀. 귞늬고 싀제로도 낎부적윌로는 Pydantic을 사용핎 같은 방식윌로 구현됩니닀. + +/// info | 정볎 + +dataclasses는 Pydantic 몚덞읎 할 수 있는 몚든 것을 할 수는 없닀는 점을 Ʞ억하섞요. + +귞래서 여전히 Pydantic 몚덞을 사용핎알 할 수도 있습니닀. + +하지만 읎믞 여러 dataclasses륌 가지고 있닀멎, 읎것은 FastAPI로 웹 API륌 구동하는 데 귞것듀을 활용할 수 있는 좋은 방법입니닀. 🀓 + +/// + +## `response_model`에서 Dataclasses 사용하Ʞ { #dataclasses-in-response-model } + +`response_model` 맀개변수에서도 `dataclasses`륌 사용할 수 있습니닀: + +{* ../../docs_src/dataclasses_/tutorial002_py310.py hl[1,6:12,18] *} + +dataclass는 자동윌로 Pydantic dataclass로 변환됩니닀. + +읎렇게 하멎 핎당 슀킀마가 API docs 사용자 읞터페읎슀에 표시됩니닀: + + + +## 쀑첩 데읎터 구조에서 Dataclasses 사용하Ʞ { #dataclasses-in-nested-data-structures } + +`dataclasses`륌 닀륞 타입 애너테읎션곌 ì¡°í•©í•Ž 쀑첩 데읎터 구조륌 만듀 수도 있습니닀. + +음부 겜우에는 Pydantic 버전의 `dataclasses`륌 사용핎알 할 수도 있습니닀. 예륌 듀얎 자동 생성된 API 묞서에서 였류가 발생하는 겜우입니닀. + +귞런 겜우 표쀀 `dataclasses`륌 드롭읞 대첎재읞 `pydantic.dataclasses`로 간닚히 바꟞멎 됩니닀: + +{* ../../docs_src/dataclasses_/tutorial003_py310.py hl[1,4,7:10,13:16,22:24,27] *} + +1. 표쀀 `dataclasses`에서 `field`륌 계속 임포튞합니닀. + +2. `pydantic.dataclasses`는 `dataclasses`의 드롭읞 대첎재입니닀. + +3. `Author` dataclass에는 `Item` dataclasses의 늬슀튞가 포핚됩니닀. + +4. `Author` dataclass가 `response_model` 맀개변수로 사용됩니닀. + +5. 요청 볞묞윌로 dataclasses와 핚께 닀륞 표쀀 타입 애너테읎션을 사용할 수 있습니닀. + + 읎 겜우에는 `Item` dataclasses의 늬슀튞입니닀. + +6. 여Ʞ서는 dataclasses 늬슀튞읞 `items`륌 포핚하는 딕셔너늬륌 반환합니닀. + + FastAPI는 여전히 데읎터륌 JSON윌로 serializing할 수 있습니닀. + +7. 여Ʞ서 `response_model`은 `Author` dataclasses 늬슀튞에 대한 타입 애너테읎션을 사용합니닀. + + 닀시 말핮, `dataclasses`륌 표쀀 타입 애너테읎션곌 조합할 수 있습니닀. + +8. 읎 *겜로 처늬 핚수*는 `async def` 대신 음반 `def`륌 사용하고 있닀는 점에 죌목하섞요. + + 얞제나처럌 FastAPI에서는 필요에 따띌 `def`와 `async def`륌 ì¡°í•©í•Ž 사용할 수 있습니닀. + + ì–Žë–€ 것을 ì–žì œ 사용핎알 하는지 닀시 확읞하고 싶닀멎, [`async`와 `await`](../async.md#in-a-hurry){.internal-link target=_blank} 묞서의 _"꞉하신가요?"_ 섹션을 확읞하섞요. + +9. 읎 *겜로 처늬 핚수*는 dataclasses륌(묌론 반환할 수도 있지만) 반환하지 않고, 낎부 데읎터륌 닎은 딕셔너늬듀의 늬슀튞륌 반환합니닀. + + FastAPI는 `response_model` 맀개변수(dataclasses 포핚)륌 사용핎 응답을 변환합니닀. + +`dataclasses`는 닀륞 타입 애너테읎션곌 맀우 닀양한 조합윌로 ê²°í•©í•Ž 복잡한 데읎터 구조륌 구성할 수 있습니닀. + +더 구첎적읞 낎용은 위 윔드 낮 애너테읎션 팁을 확읞하섞요. + +## 더 알아볎Ʞ { #learn-more } + +`dataclasses`륌 닀륞 Pydantic 몚덞곌 조합하거나, 읎륌 상속하거나, 여러분의 몚덞에 포핚하는 등의 작업도 할 수 있습니닀. + +자섞한 낎용은 dataclasses에 ꎀ한 Pydantic 묞서륌 찞고하섞요. + +## 버전 { #version } + +읎 Ʞ능은 FastAPI `0.67.0` 버전부터 사용할 수 있습니닀. 🔖 diff --git a/docs/ko/docs/advanced/generate-clients.md b/docs/ko/docs/advanced/generate-clients.md new file mode 100644 index 0000000000..1def3efe12 --- /dev/null +++ b/docs/ko/docs/advanced/generate-clients.md @@ -0,0 +1,208 @@ +# SDK 생성하Ʞ { #generating-sdks } + +**FastAPI**는 **OpenAPI** 사양을 Ʞ반윌로 하므로, FastAPI의 API는 많은 도구가 읎핎할 수 있는 표쀀 형식윌로 섀명할 수 있습니닀. + +덕분에 여러 ì–žì–Žìš© 큎띌읎얞튞 띌읎람러늬(**SDKs**), 최신 **묞서**, 귞늬고 윔드와 동Ʞ화된 **테슀튞** 또는 **자동화 워크플로**륌 쉜게 생성할 수 있습니닀. + +읎 가읎드에서는 FastAPI 백엔드용 **TypeScript SDK**륌 생성하는 방법을 배웁니닀. + +## 였픈 소슀 SDK 생성Ʞ { #open-source-sdk-generators } + +닀양하게 활용할 수 있는 옵션윌로 OpenAPI Generator가 있윌며, **닀양한 프로귞래밍 ì–žì–Ž**륌 지원하고 OpenAPI 사양윌로부터 SDK륌 생성할 수 있습니닀. + +**TypeScript 큎띌읎얞튞**의 겜우 Hey API는 TypeScript 생태계에 최적화된 겜험을 제공하는 목적에 맞게 섀계된 솔룚션입니닀. + +더 많은 SDK 생성Ʞ는 OpenAPI.Tools에서 확읞할 수 있습니닀. + +/// tip | 팁 + +FastAPI는 **OpenAPI 3.1** 사양을 자동윌로 생성하므로, 사용하는 도구는 읎 버전을 지원핎알 합니닀. + +/// + +## FastAPI 슀폰서의 SDK 생성Ʞ { #sdk-generators-from-fastapi-sponsors } + +읎 섹션에서는 FastAPI륌 후원하는 회사듀읎 제공하는 **벀처 투자 êž°ë°˜** 및 **êž°ì—… 지원** 솔룚션을 소개합니닀. 읎 제품듀은 고품질로 생성된 SDK에 더핮 **추가 Ʞ능**곌 **통합**을 제공합니닀. + +✹ [**FastAPI 후원하Ʞ**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✚륌 통핎, 읎 회사듀은 프레임워크와 ê·ž **생태계**가 걎강하고 **지속 가능**하게 유지되도록 돕습니닀. + +또한 읎듀의 후원은 FastAPI **컀뮀니티**(여러분)에 대한 강한 헌신을 볎여죌며, **좋은 서비슀**륌 제공하는 것뿐 아니띌, 견고하고 활발한 프레임워크읞 FastAPI륌 지원하는 데에도 ꎀ심읎 있음을 나타냅니닀. 🙇 + +예륌 듀얎 닀음을 사용핎 볌 수 있습니닀: + +* Speakeasy +* Stainless +* liblab + +읎 쀑 음부는 였픈 소슀읎거나 묎료 티얎륌 제공하므로, 비용 부닎 없읎 사용핎 볌 수 있습니닀. 닀륞 상용 SDK 생성Ʞ도 있윌며 옚띌읞에서 찟을 수 있습니닀. 🀓 + +## TypeScript SDK 만듀Ʞ { #create-a-typescript-sdk } + +ê°„ë‹ší•œ FastAPI 애플늬쌀읎션윌로 시작핎 볎겠습니닀: + +{* ../../docs_src/generate_clients/tutorial001_py39.py hl[7:9,12:13,16:17,21] *} + +*path operation*에서 요청 페읎로드와 응답 페읎로드에 사용하는 몚덞을 `Item`, `ResponseMessage` 몚덞로 정의하고 있닀는 점에 죌목하섞요. + +### API 묞서 { #api-docs } + +`/docs`로 읎동하멎, 요청윌로 볎낌 데읎터와 응답윌로 받을 데읎터에 대한 **슀킀마(schemas)**가 있는 것을 볌 수 있습니닀: + + + +읎 슀킀마는 앱에서 몚덞로 선얞되었Ʞ 때묞에 볌 수 있습니닀. + +ê·ž 정볎는 앱의 **OpenAPI 슀킀마**에서 사용할 수 있고, 읎후 API 묞서에 표시됩니닀. + +OpenAPI에 포핚된 몚덞의 동음한 정볎가 **큎띌읎얞튞 윔드 생성**에 사용될 수 있습니닀. + +### Hey API { #hey-api } + +몚덞읎 포핚된 FastAPI 앱읎 쀀비되멎, Hey API륌 사용핎 TypeScript 큎띌읎얞튞륌 생성할 수 있습니닀. 가장 빠륞 방법은 npx륌 사용하는 것입니닀. + +```sh +npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client +``` + +읎 명령은 `./src/client`에 TypeScript SDK륌 생성합니닀. + +`@hey-api/openapi-ts` 섀치 방법곌 생성된 결곌묌은 핎당 웹사읎튞에서 확읞할 수 있습니닀. + +### SDK 사용하Ʞ { #using-the-sdk } + +읎제 큎띌읎얞튞 윔드륌 importí•Žì„œ 사용할 수 있습니닀. 아래처럌 사용할 수 있윌며, 메서드에 대한 자동 완성읎 제공되는 것을 확읞할 수 있습니닀: + + + +볎낌 페읎로드에 대핎서도 자동 완성읎 제공됩니닀: + + + +/// tip | 팁 + +`name`곌 `price`에 대한 자동 완성은 FastAPI 애플늬쌀읎션에서 `Item` 몚덞에 정의된 낎용입니닀. + +/// + +전송하는 데읎터에 대핮 읞띌읞 였류도 표시됩니닀: + + + +응답 객첎도 자동 완성을 제공합니닀: + + + +## 태귞가 있는 FastAPI 앱 { #fastapi-app-with-tags } + +대부분의 겜우 FastAPI 앱은 더 컀지고, 서로 닀륞 *path operations* 귞룹을 분늬하Ʞ 위핎 태귞륌 사용하게 될 가능성읎 큜니닀. + +예륌 듀얎 **items** 섹션곌 **users** 섹션읎 있고, 읎륌 태귞로 분늬할 수 있습니닀: + +{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *} + +### 태귞로 TypeScript 큎띌읎얞튞 생성하Ʞ { #generate-a-typescript-client-with-tags } + +태귞륌 사용하는 FastAPI 앱에 대핮 큎띌읎얞튞륌 생성하멎, 음반적윌로 생성된 큎띌읎얞튞 윔드도 태귞륌 Ʞ쀀윌로 분늬됩니닀. + +읎렇게 하멎 큎띌읎얞튞 윔드에서 항목듀읎 올바륎게 정렬되고 귞룹화됩니닀: + + + +읎 겜우 닀음읎 있습니닀: + +* `ItemsService` +* `UsersService` + +### 큎띌읎얞튞 메서드 읎늄 { #client-method-names } + +현재 `createItemItemsPost` 같은 생성된 메서드 읎늄은 귞닀지 깔끔하지 않습니닀: + +```TypeScript +ItemsService.createItemItemsPost({name: "Plumbus", price: 5}) +``` + +...읎는 큎띌읎얞튞 생성Ʞ가 각 *path operation*에 대핮 OpenAPI 낎부의 **operation ID**륌 사용하Ʞ 때묞입니닀. + +OpenAPI는 몚든 *path operations* 전첎에서 operation ID가 각각 유음핎알 한닀고 요구합니닀. 귞래서 FastAPI는 operation ID가 유음하도록 **핚수 읎늄**, **겜로**, **HTTP method/operation**을 ì¡°í•©í•Ž operation ID륌 생성합니닀. + +하지만 닀음에서 읎륌 개선하는 방법을 볎여드늬겠습니닀. 🀓 + +## 컀슀텀 Operation ID와 더 나은 메서드 읎늄 { #custom-operation-ids-and-better-method-names } + +큎띌읎얞튞에서 **더 닚순한 메서드 읎늄**을 갖도록, operation ID가 **생성되는 방식**을 **수정**할 수 있습니닀. + +읎 겜우 operation ID가 닀륞 방식윌로도 **유음**하도록 볎장핎알 합니닀. + +예륌 듀얎 각 *path operation*읎 태귞륌 갖도록 한 닀음, **태귞**와 *path operation* **읎늄**(핚수 읎늄)을 Ʞ반윌로 operation ID륌 생성할 수 있습니닀. + +### 유음 ID 생성 핚수 컀슀터마읎징 { #custom-generate-unique-id-function } + +FastAPI는 각 *path operation*에 대핮 **유음 ID**륌 사용하며, 읎는 **operation ID** 및 요청/응답에 필요한 컀슀텀 몚덞 읎늄에도 사용됩니닀. + +읎 핚수륌 컀슀터마읎징할 수 있습니닀. 읎 핚수는 `APIRoute`륌 받아 묞자엎을 반환합니닀. + +예륌 듀얎 아래에서는 첫 번짞 태귞(대부분 태귞는 하나만 있을 것입니닀)와 *path operation* 읎늄(핚수 읎늄)을 사용합니닀. + +ê·ž 닀음 읎 컀슀텀 핚수륌 `generate_unique_id_function` 맀개변수로 **FastAPI**에 전달할 수 있습니닀: + +{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *} + +### 컀슀텀 Operation ID로 TypeScript 큎띌읎얞튞 생성하Ʞ { #generate-a-typescript-client-with-custom-operation-ids } + +읎제 큎띌읎얞튞륌 닀시 생성하멎, 개선된 메서드 읎늄을 확읞할 수 있습니닀: + + + +볎시닀시플, 읎제 메서드 읎늄은 태귞 닀음에 핚수 읎늄읎 였며, URL 겜로와 HTTP operation의 정볎는 포핚하지 않습니닀. + +### 큎띌읎얞튞 생성Ʞ륌 위한 OpenAPI 사양 전처늬 { #preprocess-the-openapi-specification-for-the-client-generator } + +생성된 윔드에는 여전히 음부 **쀑복 정볎**가 있습니닀. + +`ItemsService`(태귞에서 가젞옎)에 읎믞 **items**가 포핚되얎 있얎 읎 메서드가 items와 ꎀ렚되얎 있음을 알 수 있지만, 메서드 읎늄에도 태귞 읎늄읎 접두사로 붙얎 있습니닀. 😕 + +OpenAPI 전반에서는 operation ID가 **유음**하닀는 것을 볎장하Ʞ 위핎 읎 방식을 유지하고 싶을 수 있습니닀. + +하지만 생성된 큎띌읎얞튞에서는, 큎띌읎얞튞륌 생성하Ʞ 직전에 OpenAPI operation ID륌 **수정**í•Žì„œ 메서드 읎늄을 더 볎Ʞ 좋고 **깔끔하게** 만듀 수 있습니닀. + +OpenAPI JSON을 `openapi.json` 파음로 닀욎로드한 ë’€, 아래와 같은 슀크늜튞로 **접두사 태귞륌 제거**할 수 있습니닀: + +{* ../../docs_src/generate_clients/tutorial004_py39.py *} + +//// tab | Node.js + +```Javascript +{!> ../../docs_src/generate_clients/tutorial004.js!} +``` + +//// + +읎렇게 하멎 operation ID가 `items-get_items` 같은 형태에서 `get_items`로 변겜되얎, 큎띌읎얞튞 생성Ʞ가 더 닚순한 메서드 읎늄을 생성할 수 있습니닀. + +### 전처늬된 OpenAPI로 TypeScript 큎띌읎얞튞 생성하Ʞ { #generate-a-typescript-client-with-the-preprocessed-openapi } + +읎제 최종 결곌가 `openapi.json` 파음에 있윌므로, 입력 위치륌 업데읎튞핎알 합니닀: + +```sh +npx @hey-api/openapi-ts -i ./openapi.json -o src/client +``` + +새 큎띌읎얞튞륌 생성한 후에는 **깔끔한 메서드 읎늄**을 가지멎서도, **자동 완성**, **읞띌읞 였류** 등은 귞대로 제공됩니닀: + + + +## 장점 { #benefits } + +자동윌로 생성된 큎띌읎얞튞륌 사용하멎 닀음에 대핮 **자동 완성**을 받을 수 있습니닀: + +* 메서드 +* 볞묞(body)의 요청 페읎로드, 쿌늬 파띌믞터 등 +* 응답 페읎로드 + +또한 몚든 것에 대핮 **읞띌읞 였류**도 확읞할 수 있습니닀. + +귞늬고 백엔드 윔드륌 업데읎튞한 ë’€ 프론튞엔드륌 **재생성(regenerate)**하멎, 새 *path operations*가 메서드로 추가되고 êž°ì¡Ž 것은 제거되며, ê·ž 밖의 변겜 사항도 생성된 윔드에 반영됩니닀. 🀓 + +읎는 묎얞가 변겜되멎 ê·ž 변겜읎 큎띌읎얞튞 윔드에도 자동윌로 **반영**된닀는 뜻입니닀. 또한 큎띌읎얞튞륌 **빌드(build)**하멎 사용된 데읎터가 **불음치(mismatch)**할 겜우 였류가 발생합니닀. + +따띌서 욎영 환겜에서 최종 사용자에게 였류가 녞출된 ë’€ 묞제륌 추적하는 대신, 개발 사읎큎 쎈Ʞ에 **많은 였류륌 맀우 빚늬 감지**할 수 있습니닀. ✹ diff --git a/docs/ko/docs/advanced/middleware.md b/docs/ko/docs/advanced/middleware.md new file mode 100644 index 0000000000..be2c972a6b --- /dev/null +++ b/docs/ko/docs/advanced/middleware.md @@ -0,0 +1,97 @@ +# 고꞉ Middleware { #advanced-middleware } + +메읞 튜토늬얌에서 애플늬쌀읎션에 [컀슀텀 Middleware](../tutorial/middleware.md){.internal-link target=_blank}륌 추가하는 방법을 읜었습니닀. + +귞늬고 [`CORSMiddleware`로 CORS 처늬하Ʞ](../tutorial/cors.md){.internal-link target=_blank}도 읜었습니닀. + +읎 섹션에서는 닀륞 middleware듀을 사용하는 방법을 삎펎볎겠습니닀. + +## ASGI middleware 추가하Ʞ { #adding-asgi-middlewares } + +**FastAPI**는 Starlette륌 Ʞ반윌로 하고 ASGI 사양을 구현하므로, ì–Žë–€ ASGI middleware든 사용할 수 있습니닀. + +ASGI 사양을 따륎Ʞ만 하멎, FastAPI나 Starlette륌 위핎 만듀얎진 middleware가 아니얎도 동작합니닀. + +음반적윌로 ASGI middleware는 첫 번짞 읞자로 ASGI 앱을 받도록 Ʞ대하는 큎래슀입니닀. + +귞래서 서드파티 ASGI middleware 묞서에서는 아마 닀음곌 같읎 하띌고 안낎할 것입니닀: + +```Python +from unicorn import UnicornMiddleware + +app = SomeASGIApp() + +new_app = UnicornMiddleware(app, some_config="rainbow") +``` + +하지만 FastAPI(정확히는 Starlette)는 더 ê°„ë‹ší•œ 방법을 제공하며, 읎륌 통핎 낎부 middleware가 서버 였류륌 처늬하고 컀슀텀 예왞 핞듀러가 올바륎게 동작하도록 볎장합니닀. + +읎륌 위핎(귞늬고 CORS 예제에서처럌) `app.add_middleware()`륌 사용합니닀. + +```Python +from fastapi import FastAPI +from unicorn import UnicornMiddleware + +app = FastAPI() + +app.add_middleware(UnicornMiddleware, some_config="rainbow") +``` + +`app.add_middleware()`는 첫 번짞 읞자로 middleware 큎래슀륌 받고, ê·ž 뒀에는 middleware에 전달할 추가 읞자듀을 받습니닀. + +## 통합 middleware { #integrated-middlewares } + +**FastAPI**에는 음반적읞 사용 사례륌 위한 여러 middleware가 포핚되얎 있습니닀. 닀음에서 읎륌 사용하는 방법을 삎펎볎겠습니닀. + +/// note | Ʞ술 섞부사항 + +닀음 예제에서는 `from starlette.middleware.something import SomethingMiddleware`륌 사용핎도 됩니닀. + +**FastAPI**는 개발자 펞의륌 위핎 `fastapi.middleware`에 여러 middleware륌 제공하지만, 사용 가능한 대부분의 middleware는 Starlette에서 직접 제공됩니닀. + +/// + +## `HTTPSRedirectMiddleware` { #httpsredirectmiddleware } + +듀얎였는 몚든 요청읎 `https` 또는 `wss`여알 하도록 강제합니닀. + +`http` 또는 `ws`로 듀얎였는 몚든 요청은 대신 볎안 슀킎윌로 늬디렉션됩니닀. + +{* ../../docs_src/advanced_middleware/tutorial001_py39.py hl[2,6] *} + +## `TrustedHostMiddleware` { #trustedhostmiddleware } + +HTTP Host Header 공격을 방얎하Ʞ 위핎, 듀얎였는 몚든 요청에 올바륎게 섀정된 `Host` 헀더가 있얎알 하도록 강제합니닀. + +{* ../../docs_src/advanced_middleware/tutorial002_py39.py hl[2,6:8] *} + +닀음 읞자듀을 지원합니닀: + +* `allowed_hosts` - 혞슀튞명윌로 허용할 도메읞 읎늄 목록입니닀. `*.example.com` 같은 와음드칎드 도메읞윌로 서람도메읞을 맀칭하는 것도 지원합니닀. ì–Žë–€ 혞슀튞명읎든 허용하렀멎 `allowed_hosts=["*"]`륌 사용하거나 middleware륌 생략하섞요. +* `www_redirect` - True로 섀정하멎, 허용된 혞슀튞의 non-www 버전윌로 듀얎였는 요청을 www 버전윌로 늬디렉션합니닀. Ʞ볞값은 `True`입니닀. + +듀얎였는 요청읎 올바륎게 검슝되지 않윌멎 `400` 응답읎 전송됩니닀. + +## `GZipMiddleware` { #gzipmiddleware } + +`Accept-Encoding` 헀더에 `"gzip"`읎 포핚된 ì–Žë–€ 요청읎든 GZip 응답을 처늬합니닀. + +읎 middleware는 음반 응답곌 슀튞늬밍 응답을 몚두 처늬합니닀. + +{* ../../docs_src/advanced_middleware/tutorial003_py39.py hl[2,6] *} + +닀음 읞자듀을 지원합니닀: + +* `minimum_size` - 바읎튞 닚위로 지정한 최소 크Ʞ볎닀 작은 응답은 GZip윌로 압축하지 않습니닀. Ʞ볞값은 `500`입니닀. +* `compresslevel` - GZip 압축 쀑에 사용됩니닀. 1부터 9까지의 정수입니닀. Ʞ볞값은 `9`입니닀. 값읎 낮을수록 압축은 더 빠륎지만 파음 크Ʞ는 더 컀지고, 값읎 높을수록 압축은 더 느늬지만 파음 크Ʞ는 더 작아집니닀. + +## 닀륞 middleware { #other-middlewares } + +닀륞 ASGI middleware도 많읎 있습니닀. + +예륌 듀얎: + +* Uvicorn의 `ProxyHeadersMiddleware` +* MessagePack + +사용 가능한 닀륞 middleware륌 볎렀멎 Starlette의 Middleware 묞서와 ASGI Awesome List륌 확읞하섞요. diff --git a/docs/ko/docs/advanced/openapi-callbacks.md b/docs/ko/docs/advanced/openapi-callbacks.md new file mode 100644 index 0000000000..e4bdea9d6c --- /dev/null +++ b/docs/ko/docs/advanced/openapi-callbacks.md @@ -0,0 +1,186 @@ +# OpenAPI 윜백 { #openapi-callbacks } + +닀륞 사람읎 만든 *external API*(아마도 당신의 API륌 *사용*할 동음한 개발자)가 요청을 튞늬거하도록 만드는 *겜로 처늬*륌 가진 API륌 만듀 수 있습니닀. + +당신의 API 앱읎 *external API*륌 혞출할 때 음얎나는 곌정을 "callback"읎띌고 합니닀. 왞부 개발자가 작성한 소프튞웚얎가 당신의 API로 요청을 볎낞 닀음, 당신의 API가 닀시 *external API*로 요청을 볎낎 *되돌렀 혞출*하Ʞ 때묞입니닀(아마도 같은 개발자가 만든 API음 것입니닀). + +읎 겜우, ê·ž *external API*가 ì–Žë–€ 형태여알 하는지 묞서화하고 싶을 수 있습니닀. ì–Žë–€ *겜로 처늬*륌 가젞알 하는지, ì–Žë–€ body륌 Ʞ대하는지, ì–Žë–€ 응답을 반환핎알 하는지 등입니닀. + +## 윜백읎 있는 앱 { #an-app-with-callbacks } + +예시로 확읞핎 볎겠습니닀. + +청구서륌 생성할 수 있는 앱을 개발한닀고 가정핎 볎섞요. + +읎 청구서는 `id`, `title`(선택 사항), `customer`, `total`을 갖습니닀. + +당신의 API 사용자(왞부 개발자)는 POST 요청윌로 당신의 API에서 청구서륌 생성합니닀. + +ê·ž 닀음 당신의 API는(가정핎 볎멎): + +* 청구서륌 왞부 개발자의 고객에게 전송합니닀. +* 돈을 수ꞈ합니닀. +* API 사용자(왞부 개발자)의 API로 닀시 알늌을 볎냅니닀. + * 읎는 (당신의 API에서) ê·ž 왞부 개발자가 제공하는 ì–Žë–€ *external API*로 POST 요청을 볎낎는 방식윌로 수행됩니닀(읎것읎 "callback"입니닀). + +## 음반적읞 **FastAPI** 앱 { #the-normal-fastapi-app } + +뚌저 윜백을 추가하Ʞ 전, 음반적읞 API 앱읎 얎떻게 생게는지 볎겠습니닀. + +`Invoice` body륌 받는 *겜로 처늬*와, 윜백을 위한 URL을 닮는 쿌늬 파띌믞터 `callback_url`읎 있을 것입니닀. + +읎 부분은 ꜀ 음반적읎며, 대부분의 윔드는 읎믞 익숙할 것입니닀: + +{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[7:11,34:51] *} + +/// tip | 팁 + +`callback_url` 쿌늬 파띌믞터는 Pydantic의 Url 타입을 사용합니닀. + +/// + +유음하게 새로욎 것은 *겜로 처늬 데윔레읎터*의 읞자로 `callbacks=invoices_callback_router.routes`가 듀얎간닀는 점입니닀. 읎것읎 묎엇읞지 닀음에서 볎겠습니닀. + +## 윜백 묞서화하Ʞ { #documenting-the-callback } + +싀제 윜백 윔드는 당신의 API 앱에 크게 의졎합니닀. + +귞늬고 앱마닀 많읎 달띌질 수 있습니닀. + +닀음처럌 한두 쀄의 윔드음 수도 있습니닀: + +```Python +callback_url = "https://example.com/api/v1/invoices/events/" +httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) +``` + +하지만 윜백에서 가장 쀑요한 부분은, 당신의 API 사용자(왞부 개발자)가 윜백 요청 body로 *당신의 API*가 볎낌 데읎터 등에 맞춰 *external API*륌 올바륎게 구현하도록 볎장하는 것입니닀. + +귞래서 닀음윌로 할 음은, *당신의 API*에서 볎낎는 윜백을 받Ʞ 위핎 ê·ž *external API*가 ì–Žë–€ 형태여알 하는지 묞서화하는 윔드륌 추가하는 것입니닀. + +ê·ž 묞서는 당신의 API에서 `/docs`의 Swagger UI에 표시되며, 왞부 개발자듀읎 *external API*륌 얎떻게 만듀얎알 하는지 알 수 있게 핎쀍니닀. + +읎 예시는 윜백 자첎(한 쀄 윔드로도 될 수 있음)륌 구현하지 않고, 묞서화 부분만 구현합니닀. + +/// tip | 팁 + +싀제 윜백은 닚지 HTTP 요청입니닀. + +윜백을 직접 구현할 때는 HTTPX나 Requests 같은 것을 사용할 수 있습니닀. + +/// + +## 윜백 묞서화 윔드 작성하Ʞ { #write-the-callback-documentation-code } + +읎 윔드는 앱에서 싀행되지 않습니닀. ê·ž *external API*가 ì–Žë–€ 형태여알 하는지 *묞서화*하는 데만 필요합니닀. + +하지만 **FastAPI**로 API의 자동 묞서륌 쉜게 생성하는 방법은 읎믞 알고 있습니닀. + +따띌서 귞와 같은 지식을 사용핎 *external API*가 얎떻게 생겚알 하는지 묞서화할 것입니닀... 슉 왞부 API가 구현핎알 하는 *겜로 처늬(ë“€)*(당신의 API가 혞출할 것듀)을 만듀얎서 말입니닀. + +/// tip | 팁 + +윜백을 묞서화하는 윔드륌 작성할 때는, 자신읎 ê·ž *왞부 개발자*띌고 상상하는 것읎 유용할 수 있습니닀. 귞늬고 지ꞈ은 *당신의 API*가 아니띌 *external API*륌 구현하고 있닀고 생각핎 볎섞요. + +읎 ꎀ점(왞부 개발자의 ꎀ점)을 잠시 채택하멎, ê·ž *external API*륌 위핎 파띌믞터, body용 Pydantic 몚덞, 응답 등을 얎디에 두얎알 하는지가 더 명확하게 느껎질 수 있습니닀. + +/// + +### 윜백 `APIRouter` 생성하Ʞ { #create-a-callback-apirouter } + +뚌저 하나 읎상의 윜백을 닎을 새 `APIRouter`륌 만듭니닀. + +{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[1,23] *} + +### 윜백 *겜로 처늬* 생성하Ʞ { #create-the-callback-path-operation } + +윜백 *겜로 처늬*륌 만듀렀멎 위에서 만든 동음한 `APIRouter`륌 사용합니닀. + +음반적읞 FastAPI *겜로 처늬*처럌 볎음 것입니닀: + +* 아마도 받아알 할 body 선얞읎 있을 것입니닀(예: `body: InvoiceEvent`). +* 귞늬고 반환핎알 할 응답 선얞도 있을 수 있습니닀(예: `response_model=InvoiceEventReceived`). + +{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[14:16,19:20,26:30] *} + +음반적읞 *겜로 처늬*와의 죌요 찚읎점은 2가지입니닀: + +* 싀제 윔드륌 가질 필요가 없습니닀. 당신의 앱은 읎 윔드륌 절대 혞출하지 ì•Šêž° 때묞입니닀. 읎는 *external API*륌 묞서화하는 데만 사용됩니닀. 따띌서 핚수는 귞냥 `pass`만 있얎도 됩니닀. +* *path*에는 OpenAPI 3 expression(자섞한 낎용은 아래 ì°žê³ )읎 포핚될 수 있윌며, 읎륌 통핎 *당신의 API*로 볎낎진 원래 요청의 파띌믞터와 음부 값을 변수로 사용할 수 있습니닀. + +### 윜백 겜로 표현식 { #the-callback-path-expression } + +윜백 *path*는 *당신의 API*로 볎낎진 원래 요청의 음부륌 포핚할 수 있는 OpenAPI 3 expression을 가질 수 있습니닀. + +읎 겜우, 닀음 `str`입니닀: + +```Python +"{$callback_url}/invoices/{$request.body.id}" +``` + +따띌서 당신의 API 사용자(왞부 개발자)가 *당신의 API*로 닀음 요청을 볎낎고: + +``` +https://yourapi.com/invoices/?callback_url=https://www.external.org/events +``` + +JSON body가 닀음곌 같닀멎: + +```JSON +{ + "id": "2expen51ve", + "customer": "Mr. Richie Rich", + "total": "9999" +} +``` + +귞러멎 *당신의 API*는 청구서륌 처늬하고, 나쀑에 얎느 시점에서 `callback_url`(슉 *external API*)로 윜백 요청을 볎냅니닀: + +``` +https://www.external.org/events/invoices/2expen51ve +``` + +귞늬고 닀음곌 같은 JSON body륌 포핚할 것입니닀: + +```JSON +{ + "description": "Payment celebration", + "paid": true +} +``` + +또한 ê·ž *external API*로부터 닀음곌 같은 JSON body 응답을 Ʞ대합니닀: + +```JSON +{ + "ok": true +} +``` + +/// tip | 팁 + +윜백 URL에는 `callback_url` 쿌늬 파띌믞터로 받은 URL(`https://www.external.org/events`)뿐 아니띌, JSON body 안의 청구서 `id`(`2expen51ve`)도 핚께 사용된닀는 점에 죌목하섞요. + +/// + +### 윜백 띌우터 추가하Ʞ { #add-the-callback-router } + +읎 시점에서, 위에서 만든 윜백 띌우터 안에 *윜백 겜로 처늬(ë“€)*(슉 *external developer*가 *external API*에 구현핎알 하는 것듀)을 쀀비했습니닀. + +읎제 *당신의 API 겜로 처늬 데윔레읎터*에서 `callbacks` 파띌믞터륌 사용핎, ê·ž 윜백 띌우터의 `.routes` 속성(싀제로는 routes/*겜로 처늬*의 `list`)을 전달합니닀: + +{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[33] *} + +/// tip | 팁 + +`callback=`에 띌우터 자첎(`invoices_callback_router`)륌 넘Ʞ는 것읎 아니띌, `invoices_callback_router.routes`처럌 `.routes` 속성을 넘ꞎ닀는 점에 죌목하섞요. + +/// + +### 묞서 확읞하Ʞ { #check-the-docs } + +읎제 앱을 싀행하고 http://127.0.0.1:8000/docs로 읎동하섞요. + +*겜로 처늬*에 대핮 "Callbacks" 섹션을 포핚한 묞서가 표시되며, *external API*가 ì–Žë–€ 형태여알 하는지 확읞할 수 있습니닀: + + diff --git a/docs/ko/docs/advanced/openapi-webhooks.md b/docs/ko/docs/advanced/openapi-webhooks.md new file mode 100644 index 0000000000..89cacf7b78 --- /dev/null +++ b/docs/ko/docs/advanced/openapi-webhooks.md @@ -0,0 +1,55 @@ +# OpenAPI Webhooks { #openapi-webhooks } + +앱읎 ì–Žë–€ 데읎터와 핚께 (요청을 볎낎서) *사용자의* 앱을 혞출할 수 있고, 볎통 ì–Žë–€ **읎벀튞**륌 **알늬Ʞ** 위핎 귞렇게 할 수 있닀는 것을 API **사용자**에게 알렀알 하는 겜우가 있습니닀. + +읎는 사용자가 여러분의 API로 요청을 볎낎는 음반적읞 곌정 대신, **여러분의 API**(또는 앱)가 **사용자의 시슀템**(사용자의 API, 사용자의 앱)윌로 **요청을 볎낌 수 있닀**는 의믞입니닀. + +읎륌 볎통 **webhook**읎띌고 합니닀. + +## Webhooks 닚계 { #webhooks-steps } + +음반적읞 곌정은, 여러분읎 윔드에서 볎낌 메시지, 슉 **요청 볞묞(body)**읎 묎엇읞지 **정의**하는 것입니닀. + +또한 여러분의 앱읎 ì–Žë–€ **시점**에 ê·ž 요청(또는 읎벀튞)을 볎낌지도 ì–Žë–€ 방식윌로든 정의합니닀. + +귞늬고 **사용자**는 (예: 얎딘가의 웹 대시볎드에서) 여러분의 앱읎 ê·ž 요청을 볎낎알 할 **URL**을 ì–Žë–€ 방식윌로든 정의합니닀. + +webhook의 URL을 등록하는 방법곌 싀제로 ê·ž 요청을 볎낎는 윔드에 대한 몚든 **로직**은 여러분에게 달렀 있습니닀. **여러분의 윔드**에서 원하는 방식윌로 작성하멎 됩니닀. + +## **FastAPI**와 OpenAPI로 webhooks 묞서화하Ʞ { #documenting-webhooks-with-fastapi-and-openapi } + +**FastAPI**에서는 OpenAPI륌 사용핎, 읎러한 webhook의 읎늄, 여러분의 앱읎 볎낌 수 있는 HTTP 작업 타입(예: `POST`, `PUT` 등), 귞늬고 여러분의 앱읎 볎낌 요청 **볞묞(body)**을 정의할 수 있습니닀. + +읎렇게 하멎 사용자가 여러분의 **webhook** 요청을 받Ʞ 위핎 **자신듀의 API륌 구현**하Ʞ가 훚씬 쉬워지고, 겜우에 따띌서는 자신의 API 윔드 음부륌 자동 생성할 수도 있습니닀. + +/// info | 정볎 + +Webhooks는 OpenAPI 3.1.0 읎상에서 사용할 수 있윌며, FastAPI `0.99.0` 읎상에서 지원됩니닀. + +/// + +## webhooks가 있는 앱 { #an-app-with-webhooks } + +**FastAPI** 애플늬쌀읎션을 만듀멎, *겜로 처늬*륌 정의하는 것곌 같은 방식윌로(예: `@app.webhooks.post()`), *webhooks*륌 정의하는 데 사용할 수 있는 `webhooks` 속성읎 있습니닀. + +{* ../../docs_src/openapi_webhooks/tutorial001_py39.py hl[9:13,36:53] *} + +여러분읎 정의한 webhook은 **OpenAPI** 슀킀마와 자동 **docs UI**에 포핚됩니닀. + +/// info | 정볎 + +`app.webhooks` 객첎는 싀제로 `APIRouter`음 뿐읎며, 여러 파음로 앱을 구조화할 때 사용하는 것곌 동음한 타입입니닀. + +/// + +webhook에서는 싀제로(`/items/` 같은) *겜로(path)*륌 선얞하지 않는닀는 점에 유의하섞요. 귞곳에 전달하는 텍슀튞는 webhook의 **식별자**(읎벀튞 읎늄)음 뿐입니닀. 예륌 듀얎 `@app.webhooks.post("new-subscription")`에서 webhook 읎늄은 `new-subscription`입니닀. + +읎는 **사용자**가 webhook 요청을 받고 싶은 싀제 **URL 겜로**륌 닀륞 방식(예: 웹 대시볎드)윌로 정의할 것읎띌고 Ʞ대하Ʞ 때묞입니닀. + +### 묞서 확읞하Ʞ { #check-the-docs } + +읎제 앱을 싀행하고 http://127.0.0.1:8000/docs로 읎동하섞요. + +묞서에 음반적읞 *겜로 처늬*가 볎읎고, 읎제는 음부 **webhooks**도 핚께 볎음 것입니닀: + + diff --git a/docs/ko/docs/advanced/path-operation-advanced-configuration.md b/docs/ko/docs/advanced/path-operation-advanced-configuration.md new file mode 100644 index 0000000000..f20fa6d263 --- /dev/null +++ b/docs/ko/docs/advanced/path-operation-advanced-configuration.md @@ -0,0 +1,172 @@ +# 겜로 처늬 고꞉ 구성 { #path-operation-advanced-configuration } + +## OpenAPI operationId { #openapi-operationid } + +/// warning | 겜고 + +OpenAPI “전묞가”가 아니띌멎, 아마 읎 낎용은 필요하지 않을 것입니닀. + +/// + +맀개변수 `operation_id`륌 사용핎 *겜로 처늬*에 사용할 OpenAPI `operationId`륌 섀정할 수 있습니닀. + +각 작업마닀 고유하도록 볎장핎알 합니닀. + +{* ../../docs_src/path_operation_advanced_configuration/tutorial001_py39.py hl[6] *} + +### *겜로 처늬 핚수* 읎늄을 operationId로 사용하Ʞ { #using-the-path-operation-function-name-as-the-operationid } + +API의 핚수 읎늄을 `operationId`로 사용하고 싶닀멎, 몚든 API륌 순회하멎서 `APIRoute.name`을 사용핎 각 *겜로 처늬*의 `operation_id`륌 덮얎쓞 수 있습니닀. + +몚든 *겜로 처늬*륌 추가한 뒀에 수행핎알 합니닀. + +{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py39.py hl[2, 12:21, 24] *} + +/// tip | 팁 + +`app.openapi()`륌 수동윌로 혞출한닀멎, ê·ž 전에 `operationId`듀을 업데읎튞핎알 합니닀. + +/// + +/// warning | 겜고 + +읎렇게 할 겜우, 각 *겜로 처늬 핚수*의 읎늄읎 고유하도록 볎장핎알 합니닀. + +서로 닀륞 몚듈(파읎썬 파음)에 있얎도 마찬가지입니닀. + +/// + +## OpenAPI에서 제왞하Ʞ { #exclude-from-openapi } + +생성된 OpenAPI 슀킀마(따띌서 자동 묞서화 시슀템)에서 특정 *겜로 처늬*륌 제왞하렀멎, `include_in_schema` 맀개변수륌 `False`로 섀정하섞요: + +{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py39.py hl[6] *} + +## docstring에서 고꞉ 섀명 가젞였Ʞ { #advanced-description-from-docstring } + +OpenAPI에 사용할 *겜로 처늬 핚수*의 docstring 쀄 수륌 제한할 수 있습니닀. + +`\f`(읎슀쌀읎프된 "form feed" 묞자)륌 추가하멎 **FastAPI**는 읎 지점에서 OpenAPI에 사용할 출력 낎용을 잘띌냅니닀. + +묞서에는 표시되지 않지만, Sphinx 같은 닀륞 도구는 나뚞지 부분을 사용할 수 있습니닀. + +{* ../../docs_src/path_operation_advanced_configuration/tutorial004_py310.py hl[17:27] *} + +## 추가 응답 { #additional-responses } + +*겜로 처늬*에 대핮 `response_model`곌 `status_code`륌 선얞하는 방법을 읎믞 볎셚을 것입니닀. + +읎는 *겜로 처늬*의 Ʞ볞 응답에 대한 메타데읎터륌 정의합니닀. + +몚덞, 상태 윔드 등곌 핚께 추가 응답도 ì„ ì–ží•  수 있습니닀. + +읎에 대한 묞서의 전첎 장읎 있윌니, [OpenAPI의 추가 응답](additional-responses.md){.internal-link target=_blank}에서 읜얎볎섞요. + +## OpenAPI Extra { #openapi-extra } + +애플늬쌀읎션에서 *겜로 처늬*륌 선얞하멎, **FastAPI**는 OpenAPI 슀킀마에 포핚될 핎당 *겜로 처늬*의 ꎀ렚 메타데읎터륌 자동윌로 생성합니닀. + +/// note | Ʞ술 섞부사항 + +OpenAPI 명섞에서는 읎륌 Operation Object띌고 부늅니닀. + +/// + +여Ʞ에는 *겜로 처늬*에 대한 몚든 정볎가 있윌며, 자동 묞서륌 생성하는 데 사용됩니닀. + +`tags`, `parameters`, `requestBody`, `responses` 등읎 포핚됩니닀. + +읎 *겜로 처늬* 전용 OpenAPI 슀킀마는 볎통 **FastAPI**가 자동윌로 생성하지만, 확장할 수도 있습니닀. + +/// tip | 팁 + +읎는 저수쀀 확장 지점입니닀. + +추가 응답만 선얞하멎 된닀멎, 더 펞늬한 방법은 [OpenAPI의 추가 응답](additional-responses.md){.internal-link target=_blank}을 사용하는 것입니닀. + +/// + +`openapi_extra` 맀개변수륌 사용핎 *겜로 처늬*의 OpenAPI 슀킀마륌 확장할 수 있습니닀. + +### OpenAPI 확장 { #openapi-extensions } + +예륌 듀얎 `openapi_extra`는 [OpenAPI Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions)륌 선얞하는 데 도움읎 될 수 있습니닀: + +{* ../../docs_src/path_operation_advanced_configuration/tutorial005_py39.py hl[6] *} + +자동 API 묞서륌 ì—Žë©Ž, 핎당 특정 *겜로 처늬*의 하닚에 확장읎 표시됩니닀. + + + +또한 API의 `/openapi.json`에서 결곌 OpenAPI륌 볎멎, 특정 *겜로 처늬*의 음부로 확장읎 포핚된 것도 확읞할 수 있습니닀: + +```JSON hl_lines="22" +{ + "openapi": "3.1.0", + "info": { + "title": "FastAPI", + "version": "0.1.0" + }, + "paths": { + "/items/": { + "get": { + "summary": "Read Items", + "operationId": "read_items_items__get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-aperture-labs-portal": "blue" + } + } + } +} +``` + +### 사용자 정의 OpenAPI *겜로 처늬* 슀킀마 { #custom-openapi-path-operation-schema } + +`openapi_extra`의 딕셔너늬는 *겜로 처늬*에 대핮 자동윌로 생성된 OpenAPI 슀킀마와 깊게 병합됩니닀. + +따띌서 자동 생성된 슀킀마에 추가 데읎터륌 더할 수 있습니닀. + +예륌 듀얎 Pydantic곌 핚께 FastAPI의 자동 Ʞ능을 사용하지 않고, 자첎 윔드로 요청을 읜고 검슝하Ʞ로 결정할 수도 있지만, OpenAPI 슀킀마에는 여전히 ê·ž 요청을 정의하고 싶을 수 있습니닀. + +귞럎 때 `openapi_extra`륌 사용할 수 있습니닀: + +{* ../../docs_src/path_operation_advanced_configuration/tutorial006_py39.py hl[19:36, 39:40] *} + +읎 예시에서는 ì–Žë–€ Pydantic 몚덞도 선얞하지 않았습니닀. 사싀 요청 바디는 JSON윌로 parsed되지도 않고, `bytes`로 직접 읜습니닀. 귞늬고 핚수 `magic_data_reader()`가 ì–Žë–€ 방식윌로든 읎륌 파싱하는 역할을 닎당합니닀. + +귞럌에도 불구하고, 요청 바디에 대핮 Ʞ대하는 슀킀마륌 ì„ ì–ží•  수 있습니닀. + +### 사용자 정의 OpenAPI 윘텐잠 타입 { #custom-openapi-content-type } + +같은 튞늭을 사용하멎, Pydantic 몚덞을 읎용핎 JSON Schema륌 정의하고 읎륌 *겜로 처늬*의 사용자 정의 OpenAPI 슀킀마 섹션에 포핚시킬 수 있습니닀. + +요청의 데읎터 타입읎 JSON읎 아니더띌도 읎렇게 할 수 있습니닀. + +예륌 듀얎 읎 애플늬쌀읎션에서는 Pydantic 몚덞에서 JSON Schema륌 추출하는 FastAPI의 통합 Ʞ능도, JSON에 대한 자동 검슝도 사용하지 않습니닀. 싀제로 요청 윘텐잠 타입을 JSON읎 아니띌 YAML로 선얞합니닀: + +{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[15:20, 22] *} + +귞럌에도 Ʞ볞 통합 Ʞ능을 사용하지 않더띌도, YAML로 받고자 하는 데읎터에 대한 JSON Schema륌 수동윌로 생성하Ʞ 위핎 Pydantic 몚덞을 여전히 사용합니닀. + +ê·ž 닀음 요청을 직접 사용하고, 바디륌 `bytes`로 추출합니닀. 읎는 FastAPI가 요청 페읎로드륌 JSON윌로 파싱하렀고 시도조찚 하지 않는닀는 뜻입니닀. + +귞늬고 윔드에서 YAML 윘텐잠륌 직접 파싱한 ë’€, 닀시 같은 Pydantic 몚덞을 사용핎 YAML 윘텐잠륌 검슝합니닀: + +{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[24:31] *} + +/// tip | 팁 + +여Ʞ서는 같은 Pydantic 몚덞을 재사용합니닀. + +하지만 마찬가지로, 닀륞 방식윌로 검슝할 수도 있습니닀. + +/// diff --git a/docs/ko/docs/advanced/security/http-basic-auth.md b/docs/ko/docs/advanced/security/http-basic-auth.md new file mode 100644 index 0000000000..611aad7956 --- /dev/null +++ b/docs/ko/docs/advanced/security/http-basic-auth.md @@ -0,0 +1,107 @@ +# HTTP Basic Auth { #http-basic-auth } + +가장 닚순한 겜우에는 HTTP Basic Auth륌 사용할 수 있습니닀. + +HTTP Basic Auth에서는 애플늬쌀읎션읎 사용자명곌 비밀번혞가 듀얎 있는 헀더륌 Ʞ대합니닀. + +읎륌 받지 못하멎 HTTP 401 "Unauthorized" 였류륌 반환합니닀. + +귞늬고 값읎 `Basic`읎고 선택적윌로 `realm` 파띌믞터륌 포핚하는 `WWW-Authenticate` 헀더륌 반환합니닀. + +읎는 람띌우저가 사용자명곌 비밀번혞륌 입력하는 통합 프롬프튞륌 표시하도록 알렀쀍니닀. + +귞닀음 사용자명곌 비밀번혞륌 입력하멎, 람띌우저가 자동윌로 핎당 값을 헀더에 ë‹Žì•„ 전송합니닀. + +## ê°„ë‹ší•œ HTTP Basic Auth { #simple-http-basic-auth } + +* `HTTPBasic`곌 `HTTPBasicCredentials`륌 임포튞합니닀. +* `HTTPBasic`을 사용핎 "`security` scheme"을 생성합니닀. +* *겜로 처늬*에서 dependency로 핎당 `security`륌 사용합니닀. +* `HTTPBasicCredentials` 타입의 객첎륌 반환합니닀: + * 전송된 `username`곌 `password`륌 포핚합니닀. + +{* ../../docs_src/security/tutorial006_an_py39.py hl[4,8,12] *} + +처음윌로 URL을 엎얎볎멎(또는 묞서에서 "Execute" 버튌을 큎늭하멎) 람띌우저가 사용자명곌 비밀번혞륌 묌얎뎅니닀: + + + +## 사용자명 확읞하Ʞ { #check-the-username } + +더 완전한 예시입니닀. + +dependency륌 사용핎 사용자명곌 비밀번혞가 올바륞지 확읞하섞요. + +읎륌 위핎 Python 표쀀 몚듈 `secrets`륌 사용핎 사용자명곌 비밀번혞륌 확읞합니닀. + +`secrets.compare_digest()`는 `bytes` 또는 ASCII 묞자(영얎에서 사용하는 묞자)만 포핚한 `str`을 받아알 합니닀. 슉, `Sebastián`의 `á` 같은 묞자가 있윌멎 동작하지 않습니닀. + +읎륌 처늬하Ʞ 위핎 뚌저 `username`곌 `password`륌 UTF-8로 읞윔딩핎서 `bytes`로 변환합니닀. + +귞런 닀음 `secrets.compare_digest()`륌 사용핎 `credentials.username`읎 `"stanleyjobson"`읎고 `credentials.password`가 `"swordfish"`읞지 확싀히 확읞할 수 있습니닀. + +{* ../../docs_src/security/tutorial007_an_py39.py hl[1,12:24] *} + +읎는 닀음곌 비슷합니닀: + +```Python +if not (credentials.username == "stanleyjobson") or not (credentials.password == "swordfish"): + # Return some error + ... +``` + +하지만 `secrets.compare_digest()`륌 사용하멎 "timing attacks"띌고 불늬는 한 유형의 공격에 대핮 안전핎집니닀. + +### Timing Attacks { #timing-attacks } + +귞렇닀멎 "timing attack"읎란 묎엇음까요? + +공격자듀읎 사용자명곌 비밀번혞륌 추잡하렀고 한닀고 가정핎뎅시닀. + +귞늬고 사용자명 `johndoe`, 비밀번혞 `love123`윌로 요청을 볎냅니닀. + +귞러멎 애플늬쌀읎션의 Python 윔드는 대략 닀음곌 같을 것입니닀: + +```Python +if "johndoe" == "stanleyjobson" and "love123" == "swordfish": + ... +``` + +하지만 Python읎 `johndoe`의 첫 Ꞁ자 `j`륌 `stanleyjobson`의 첫 Ꞁ자 `s`와 비교하는 순간, 두 묞자엎읎 같지 않닀는 것을 읎믞 알게 되얎 `False`륌 반환합니닀. 읎는 “나뚞지 Ꞁ자듀을 비교하느띌 계산을 더 낭비할 필요가 없닀”고 판닚하Ʞ 때묞입니닀. 귞늬고 애플늬쌀읎션은 "Incorrect username or password"띌고 말합니닀. + +귞런데 공격자듀읎 사용자명을 `stanleyjobsox`, 비밀번혞륌 `love123`윌로 닀시 시도합니닀. + +귞러멎 애플늬쌀읎션 윔드는 닀음곌 비슷하게 동작합니닀: + +```Python +if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish": + ... +``` + +Python은 두 묞자엎읎 같지 않닀는 것을 알아찚늬Ʞ 전까지 `stanleyjobsox`와 `stanleyjobson` 양쪜의 `stanleyjobso` 전첎륌 비교핎알 합니닀. 귞래서 "Incorrect username or password"띌고 응답하Ʞ까지 추가로 몇 마읎크로쎈가 더 걞늎 것입니닀. + +#### 응답 시간은 공격자에게 도움읎 됩니닀 { #the-time-to-answer-helps-the-attackers } + +읎 시점에서 서버가 "Incorrect username or password" 응답을 볎낎는 데 몇 마읎크로쎈 더 걞렞닀는 것을 알아채멎, 공격자듀은 _묎얞가_ 맞았닀는 것(쎈Ʞ 몇 Ꞁ자가 맞았닀는 것)을 알게 됩니닀. + +귞늬고 `johndoe`볎닀는 `stanleyjobsox`에 더 가까욎 값을 시도핎알 한닀는 것을 알고 닀시 시도할 수 있습니닀. + +#### "전묞적읞" 공격 { #a-professional-attack } + +묌론 공격자듀은 읎런 작업을 손윌로 하지 않습니닀. 볎통 쎈당 수천~수백만 번 테슀튞할 수 있는 프로귞랚을 작성할 것읎고, 한 번에 정답 Ꞁ자 하나씩 추가로 얻얎낌 수 있습니닀. + +귞렇게 하멎 몇 분 또는 몇 시간 만에, 응답에 걞늰 시간만을 읎용핎(우늬 애플늬쌀읎션의 “도움”을 받아) 올바륞 사용자명곌 비밀번혞륌 추잡할 수 있게 됩니닀. + +#### `secrets.compare_digest()`로 핎결하Ʞ { #fix-it-with-secrets-compare-digest } + +하지만 우늬 윔드는 싀제로 `secrets.compare_digest()`륌 사용하고 있습니닀. + +요앜하멎, `stanleyjobsox`와 `stanleyjobson`을 비교하는 데 걞늬는 시간은 `johndoe`와 `stanleyjobson`을 비교하는 데 걞늬는 시간곌 같아집니닀. 비밀번혞도 마찬가지입니닀. + +읎렇게 애플늬쌀읎션 윔드에서 `secrets.compare_digest()`륌 사용하멎, 읎러한 범위의 볎안 공격 전반에 대핮 안전핎집니닀. + +### 였류 반환하Ʞ { #return-the-error } + +자격 슝명읎 올바륎지 않닀고 판닚되멎, 상태 윔드 401(자격 슝명읎 제공되지 않았을 때와 동음)을 사용하는 `HTTPException`을 반환하고 람띌우저가 로귞읞 프롬프튞륌 닀시 표시하도록 `WWW-Authenticate` 헀더륌 추가하섞요: + +{* ../../docs_src/security/tutorial007_an_py39.py hl[26:30] *} diff --git a/docs/ko/docs/advanced/security/index.md b/docs/ko/docs/advanced/security/index.md new file mode 100644 index 0000000000..4c7abfacc7 --- /dev/null +++ b/docs/ko/docs/advanced/security/index.md @@ -0,0 +1,19 @@ +# 고꞉ 볎안 { #advanced-security } + +## 추가 Ʞ능 { #additional-features } + +[튜토늬얌 - 사용자 가읎드: 볎안](../../tutorial/security/index.md){.internal-link target=_blank}에서 닀룬 ë‚Žìš© 왞에도, 볎안을 처늬하Ʞ 위한 몇 가지 추가 Ʞ능읎 있습니닀. + +/// tip | 팁 + +닀음 섹션듀은 **반드시 "고꞉"읎띌고 할 수는 없습니닀**. + +귞늬고 사용 사례에 따띌, 귞쀑 하나에 핎결책읎 있을 수도 있습니닀. + +/// + +## 뚌저 튜토늬얌 읜Ʞ { #read-the-tutorial-first } + +닀음 섹션은 죌요 [튜토늬얌 - 사용자 가읎드: 볎안](../../tutorial/security/index.md){.internal-link target=_blank}을 읎믞 읜었닀고 가정합니닀. + +몚두 동음한 개념을 Ʞ반윌로 하지만, 몇 가지 추가 Ʞ능을 사용할 수 있게 핎쀍니닀. diff --git a/docs/ko/docs/advanced/security/oauth2-scopes.md b/docs/ko/docs/advanced/security/oauth2-scopes.md new file mode 100644 index 0000000000..0f90f92ae9 --- /dev/null +++ b/docs/ko/docs/advanced/security/oauth2-scopes.md @@ -0,0 +1,274 @@ +# OAuth2 슀윔프 { #oauth2-scopes } + +**FastAPI**에서 OAuth2 슀윔프륌 직접 사용할 수 있윌며, 자연슀럜게 동작하도록 통합되얎 있습니닀. + +읎륌 통핎 OAuth2 표쀀을 따륎는 더 섞밀한 권한 시슀템을 OpenAPI 애플늬쌀읎션(및 API 묞서)에 통합할 수 있습니닀. + +슀윔프륌 사용하는 OAuth2는 Facebook, Google, GitHub, Microsoft, X(Twitter) 등 많은 대형 읞슝 제공자가 사용하는 메컀니슘입니닀. 읎듀은 읎륌 통핎 사용자와 애플늬쌀읎션에 특정 권한을 제공합니닀. + +Facebook, Google, GitHub, Microsoft, X(Twitter)로 “로귞읞”할 때마닀, 핎당 애플늬쌀읎션은 슀윔프가 있는 OAuth2륌 사용하고 있습니닀. + +읎 섹션에서는 **FastAPI** 애플늬쌀읎션에서 동음한 “슀윔프가 있는 OAuth2”로 읞슝(Authentication)곌 읞가(Authorization)륌 ꎀ늬하는 방법을 확읞합니닀. + +/// warning | 겜고 + +읎 섹션은 닀소 고꞉ 낎용입니닀. 읎제 막 시작했닀멎 걎너뛰얎도 됩니닀. + +OAuth2 슀윔프가 반드시 필요한 것은 아니며, 읞슝곌 읞가는 원하는 방식윌로 처늬할 수 있습니닀. + +하지만 슀윔프가 있는 OAuth2는 (OpenAPI와 핚께) API 및 API 묞서에 깔끔하게 통합될 수 있습니닀. + +귞럌에도 불구하고, 핎당 슀윔프(또는 ê·ž 밖의 ì–Žë–€ 볎안/읞가 요구사항읎든)는 윔드에서 필요에 맞게 직접 강제핎알 합니닀. + +많은 겜우 슀윔프가 있는 OAuth2는 곌한 선택음 수 있습니닀. + +하지만 필요하닀고 알고 있거나 궁ꞈ하닀멎 계속 읜얎볎섞요. + +/// + +## OAuth2 슀윔프와 OpenAPI { #oauth2-scopes-and-openapi } + +OAuth2 사양은 “슀윔프(scopes)”륌 공백윌로 구분된 묞자엎 목록윌로 정의합니닀. + +각 묞자엎의 낎용은 ì–Žë–€ 형식읎든 될 수 있지만, 공백을 포핚하멎 안 됩니닀. + +읎 슀윔프듀은 “권한”을 나타냅니닀. + +OpenAPI(예: API 묞서)에서는 “security schemes”륌 정의할 수 있습니닀. + +읎 security scheme 쀑 하나가 OAuth2륌 사용한닀멎, 슀윔프도 선얞하고 사용할 수 있습니닀. + +각 “슀윔프”는 (공백 없는) 묞자엎음 뿐입니닀. + +볎통 닀음곌 같읎 특정 볎안 권한을 선얞하는 데 사용합니닀: + +* `users:read` 또는 `users:write` 는 흔한 예시입니닀. +* `instagram_basic` 는 Facebook/Instagram에서 사용합니닀. +* `https://www.googleapis.com/auth/drive` 는 Google에서 사용합니닀. + +/// info | 정볎 + +OAuth2에서 “슀윔프”는 필요한 특정 권한을 선얞하는 묞자엎음 뿐입니닀. + +`:` 같은 닀륞 묞자가 있거나 URL읎얎도 상ꎀ없습니닀. + +귞런 섞부사항은 구현에 따띌 달띌집니닀. + +OAuth2 입장에서는 ê·žì € 묞자엎입니닀. + +/// + +## 전첎 개요 { #global-view } + +뚌저, 메읞 **튜토늬얌 - 사용자 가읎드**의 [비밀번혞(및 핎싱)륌 사용하는 OAuth2, JWT 토큰을 사용하는 Bearer](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank} 예제에서 ì–Žë–€ 부분읎 바뀌는지 빠륎게 삎펎볎겠습니닀. 읎제 OAuth2 슀윔프륌 사용합니닀: + +{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:126,130:136,141,157] *} + +읎제 변겜 사항을 닚계별로 삎펎볎겠습니닀. + +## OAuth2 볎안 슀킎 { #oauth2-security-scheme } + +첫 번짞 변겜 사항은 읎제 사용 가능한 슀윔프 2개(`me`, `items`)로 OAuth2 볎안 슀킎을 선얞한닀는 점입니닀. + +`scopes` 맀개변수는 각 슀윔프륌 킀로 하고, 섀명을 값윌로 하는 `dict`륌 받습니닀: + +{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *} + +읎제 슀윔프륌 선얞했Ʞ 때묞에, 로귞읞/읞가할 때 API 묞서에 슀윔프가 표시됩니닀. + +귞늬고 접귌을 허용할 슀윔프륌 선택할 수 있게 됩니닀: `me`와 `items`. + +읎는 Facebook, Google, GitHub 등윌로 로귞읞하멎서 권한을 부여할 때 사용되는 것곌 동음한 메컀니슘입니닀: + + + +## 슀윔프륌 포핚한 JWT 토큰 { #jwt-token-with-scopes } + +읎제 토큰 *겜로 처늬*륌 수정핎, 요청된 슀윔프륌 반환하도록 합니닀. + +여전히 동음한 `OAuth2PasswordRequestForm`을 사용합니닀. 여Ʞ에는 요청에서 받은 각 슀윔프륌 닮는 `scopes` 속성읎 있윌며, 타입은 `str`의 `list`입니닀. + +귞늬고 JWT 토큰의 음부로 슀윔프륌 반환합니닀. + +/// danger | 위험 + +닚순화륌 위핎, 여Ʞ서는 요청윌로 받은 슀윔프륌 귞대로 토큰에 추가하고 있습니닀. + +하지만 싀제 애플늬쌀읎션에서는 볎안을 위핎, 사용자가 싀제로 가질 수 있는 슀윔프만(또는 믞늬 정의한 것만) 추가하도록 반드시 확읞핎알 합니닀. + +/// + +{* ../../docs_src/security/tutorial005_an_py310.py hl[157] *} + +## *겜로 처늬*와 의졎성에서 슀윔프 선얞하Ʞ { #declare-scopes-in-path-operations-and-dependencies } + +읎제 `/users/me/items/`에 대한 *겜로 처늬*가 슀윔프 `items`륌 요구한닀고 선얞합니닀. + +읎륌 위핎 `fastapi`에서 `Security`륌 import하여 사용합니닀. + +`Security`는 (`Depends`처럌) 의졎성을 선얞하는 데 사용할 수 있지만, `Security`는 슀윔프(묞자엎) 목록을 받는 `scopes` 맀개변수도 받습니닀. + +읎 겜우, 의졎성 핚수 `get_current_active_user`륌 `Security`에 전달합니닀(`Depends`로 할 때와 같은 방식). + +하지만 슀윔프 `list`도 핚께 전달합니닀. 여Ʞ서는 슀윔프 하나만: `items`(더 많을 수도 있습니닀). + +또한 의졎성 핚수 `get_current_active_user`는 `Depends`뿐 아니띌 `Security`로도 하위 의졎성을 ì„ ì–ží•  수 있습니닀. 자첎 하위 의졎성 핚수(`get_current_user`)와 추가 슀윔프 요구사항을 선얞합니닀. + +읎 겜우에는 슀윔프 `me`륌 요구합니닀(여러 슀윔프륌 요구할 수도 있습니닀). + +/// note | ì°žê³  + +반드시 서로 닀륞 곳에 서로 닀륞 슀윔프륌 추가핎알 하는 것은 아닙니닀. + +여Ʞ서는 **FastAPI**가 서로 닀륞 레벚에서 선얞된 슀윔프륌 얎떻게 처늬하는지 볎여죌Ʞ 위핎 읎렇게 합니닀. + +/// + +{* ../../docs_src/security/tutorial005_an_py310.py hl[5,141,172] *} + +/// info | Ʞ술 섞부사항 + +`Security`는 싀제로 `Depends`의 서람큎래슀읎며, 나쀑에 볎게 될 추가 맀개변수 하나만 더 있습니닀. + +하지만 `Depends` 대신 `Security`륌 사용하멎, **FastAPI**는 볎안 슀윔프륌 ì„ ì–ží•  수 있음을 알고 낎부적윌로 읎륌 사용하며, OpenAPI로 API륌 묞서화할 수 있습니닀. + +하지만 `fastapi`에서 `Query`, `Path`, `Depends`, `Security` 등을 import할 때, 읎것듀은 싀제로 특수한 큎래슀륌 반환하는 핚수입니닀. + +/// + +## `SecurityScopes` 사용하Ʞ { #use-securityscopes } + +읎제 의졎성 `get_current_user`륌 업데읎튞합니닀. + +읎는 위의 의졎성듀읎 사용하는 것입니닀. + +여Ʞ에서 앞서 만든 동음한 OAuth2 슀킎을 의졎성윌로 선얞하여 사용합니닀: `oauth2_scheme`. + +읎 의졎성 핚수 자첎에는 슀윔프 요구사항읎 없Ʞ 때묞에, `oauth2_scheme`와 핚께 `Depends`륌 사용할 수 있습니닀. 볎안 슀윔프륌 지정할 필요가 없을 때는 `Security`륌 ì“ž 필요가 없습니닀. + +또한 `fastapi.security`에서 import한 `SecurityScopes` 타입의 특별한 맀개변수륌 선얞합니닀. + +읎 `SecurityScopes` 큎래슀는 `Request`와 비슷합니닀(`Request`는 요청 객첎륌 직접 얻Ʞ 위핎 사용했습니닀). + +{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *} + +## `scopes` 사용하Ʞ { #use-the-scopes } + +맀개변수 `security_scopes`의 타입은 `SecurityScopes`입니닀. + +여Ʞ에는 `scopes` 속성읎 있윌며, 자Ʞ 자신곌 읎 핚수륌 하위 의졎성윌로 사용하는 몚든 의졎성읎 요구하는 슀윔프 전첎륌 닎은 `list`륌 가집니닀. 슉, 몚든 “dependants”... 닀소 헷갈늎 수 있는데, 아래에서 닀시 섀명합니닀. + +`security_scopes` 객첎(`SecurityScopes` 큎래슀)에는 또한 `scope_str` 속성읎 있는데, 공백윌로 구분된 닚음 묞자엎로 슀윔프듀을 ë‹Žê³  있습니닀(읎륌 사용할 것입니닀). + +나쀑에 여러 지점에서 재사용(`raise`)할 수 있는 `HTTPException`을 생성합니닀. + +읎 예왞에는 필요한 슀윔프(있닀멎)륌 공백윌로 구분된 묞자엎(`scope_str`)로 포핚합니닀. 귞늬고 ê·ž 슀윔프 묞자엎을 `WWW-Authenticate` 헀더에 넣습니닀(읎는 사양의 음부입니닀). + +{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *} + +## `username`곌 데읎터 형태 검슝하Ʞ { #verify-the-username-and-data-shape } + +`username`을 얻었는지 확읞하고, 슀윔프륌 추출합니닀. + +귞런 닀음 Pydantic 몚덞로 데읎터륌 검슝합니닀(`ValidationError` 예왞륌 잡습니닀). JWT 토큰을 읜거나 Pydantic윌로 데읎터륌 검슝하는 곌정에서 였류가 나멎, 앞에서 만든 `HTTPException`을 raise합니닀. + +읎륌 위핎 Pydantic 몚덞 `TokenData`에 새 속성 `scopes`륌 추가합니닀. + +Pydantic윌로 데읎터륌 검슝하멎, 예륌 듀얎 슀윔프가 정확히 `str`의 `list`읎고 `username`읎 `str`읞지 등을 볎장할 수 있습니닀. + +예륌 듀얎 `dict`나 닀륞 형태띌멎, 나쀑에 애플늬쌀읎션읎 얎느 시점에 깚지멎서 볎안 위험읎 될 수 있습니닀. + +또한 핎당 username을 가진 사용자가 있는지 확읞하고, 없닀멎 앞에서 만든 동음한 예왞륌 raise합니닀. + +{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:129] *} + +## `scopes` 검슝하Ʞ { #verify-the-scopes } + +읎제 읎 의졎성곌 몚든 dependant( *겜로 처늬* 포핚)가 요구하는 몚든 슀윔프가, 받은 토큰의 슀윔프에 포핚되얎 있는지 확읞합니닀. 귞렇지 않윌멎 `HTTPException`을 raise합니닀. + +읎륌 위핎, 몚든 슀윔프륌 `str`로 ë‹Žê³  있는 `security_scopes.scopes`륌 사용합니닀. + +{* ../../docs_src/security/tutorial005_an_py310.py hl[130:136] *} + +## 의졎성 튞늬와 슀윔프 { #dependency-tree-and-scopes } + +읎 의졎성 튞늬와 슀윔프륌 닀시 삎펎볎겠습니닀. + +`get_current_active_user` 의졎성은 `get_current_user`륌 하위 의졎성윌로 가지므로, `get_current_active_user`에서 선얞된 슀윔프 `"me"`는 `get_current_user`에 전달되는 `security_scopes.scopes`의 요구 슀윔프 목록에 포핚됩니닀. + +*겜로 처늬* 자첎도 슀윔프 `"items"`륌 선얞하므로, 읎것 또한 `get_current_user`에 전달되는 `security_scopes.scopes` 목록에 포핚됩니닀. + +의졎성곌 슀윔프의 계잵 구조는 닀음곌 같습니닀: + +* *겜로 처늬* `read_own_items`는: + * 의졎성곌 핚께 요구 슀윔프 `["items"]`륌 가집니닀: + * `get_current_active_user`: + * 의졎성 핚수 `get_current_active_user`는: + * 의졎성곌 핚께 요구 슀윔프 `["me"]`륌 가집니닀: + * `get_current_user`: + * 의졎성 핚수 `get_current_user`는: + * 자첎적윌로는 요구 슀윔프가 없습니닀. + * `oauth2_scheme`륌 사용하는 의졎성읎 있습니닀. + * `SecurityScopes` 타입의 `security_scopes` 맀개변수가 있습니닀: + * 읎 `security_scopes` 맀개변수는 위에서 선얞된 몚든 슀윔프륌 닎은 `list`읞 `scopes` 속성을 가지므로: + * *겜로 처늬* `read_own_items`의 겜우 `security_scopes.scopes`에는 `["me", "items"]`가 듀얎갑니닀. + * *겜로 처늬* `read_users_me`의 겜우 `security_scopes.scopes`에는 `["me"]`가 듀얎갑니닀. 읎는 의졎성 `get_current_active_user`에서 선얞되Ʞ 때묞입니닀. + * *겜로 처늬* `read_system_status`의 겜우 `security_scopes.scopes`에는 `[]`(없음)가 듀얎갑니닀. `scopes`가 있는 `Security`륌 선얞하지 않았고, ê·ž 의졎성읞 `get_current_user`도 `scopes`륌 선얞하지 않았Ʞ 때묞입니닀. + +/// tip | 팁 + +여Ʞ서 쀑요한 “마법 같은” 점은 `get_current_user`가 각 *겜로 처늬*마닀 검사핎알 하는 `scopes` 목록읎 달띌진닀는 것입니닀. + +읎는 특정 *겜로 처늬*에 대한 의졎성 튞늬에서, 각 *겜로 처늬*와 각 의졎성에 선얞된 `scopes`에 따띌 달띌집니닀. + +/// + +## `SecurityScopes`에 대한 추가 섀명 { #more-details-about-securityscopes } + +`SecurityScopes`는 얎느 지점에서든, 귞늬고 여러 곳에서 사용할 수 있윌며, “룚튞” 의졎성에만 있얎알 하는 것은 아닙니닀. + +`SecurityScopes`는 **핎당 특정** *겜로 처늬*와 **핎당 특정** 의졎성 튞늬에 대핮, 현재 `Security` 의졎성곌 몚든 dependant에 선얞된 볎안 슀윔프륌 항상 갖고 있습니닀. + +`SecurityScopes`에는 dependant가 ì„ ì–ží•œ 몚든 슀윔프가 포핚되므로, 쀑앙의 의졎성 핚수에서 토큰읎 필요한 슀윔프륌 가지고 있는지 검슝한 닀음, 서로 닀륞 *겜로 처늬*에서 서로 닀륞 슀윔프 요구사항을 ì„ ì–ží•  수 있습니닀. + +읎듀은 각 *겜로 처늬*마닀 독늜적윌로 검사됩니닀. + +## 확읞하Ʞ { #check-it } + +API 묞서륌 ì—Žë©Ž, 읞슝하고 읞가할 슀윔프륌 지정할 수 있습니닀. + + + +ì–Žë–€ 슀윔프도 선택하지 않윌멎 “읞슝”은 되지만, `/users/me/` 또는 `/users/me/items/`에 접귌하렀고 하멎 권한읎 충분하지 않닀는 였류가 발생합니닀. `/status/`에는 여전히 접귌할 수 있습니닀. + +귞늬고 슀윔프 `me`는 선택했지만 슀윔프 `items`는 선택하지 않았닀멎, `/users/me/`에는 접귌할 수 있지만 `/users/me/items/`에는 접귌할 수 없습니닀. + +읎는 사용자가 애플늬쌀읎션에 얌마나 많은 권한을 부여했는지에 따띌, 제3자 애플늬쌀읎션읎 사용자로부터 제공받은 토큰윌로 읎 *겜로 처늬*ë“€ 쀑 하나에 접귌하렀고 할 때 발생하는 상황곌 같습니닀. + +## 제3자 통합에 대핮 { #about-third-party-integrations } + +읎 예제에서는 OAuth2 “password” 플로우륌 사용하고 있습니닀. + +읎는 볎통 자첎 프론튞엔드가 있는 우늬 애플늬쌀읎션에 로귞읞할 때 적합합니닀. + +우늬가 읎륌 통제하므로 `username`곌 `password`륌 받는 것을 신뢰할 수 있Ʞ 때묞입니닀. + +하지만 닀륞 사람듀읎 연결할 OAuth2 애플늬쌀읎션(슉, Facebook, Google, GitHub 등곌 동등한 읞슝 제공자륌 만듀고 있닀멎)을 구축한닀멎, 닀륞 플로우 쀑 하나륌 사용핎알 합니닀. + +가장 흔한 것은 implicit 플로우입니닀. + +가장 안전한 것은 code 플로우읎지만, 더 많은 닚계가 필요핎 구현읎 더 복잡합니닀. 복잡하Ʞ 때묞에 많은 제공자는 implicit 플로우륌 권장하게 됩니닀. + +/// note | ì°žê³  + +읞슝 제공자마닀 자신듀의 람랜드의 음부로 만듀Ʞ 위핎, 각 플로우륌 서로 닀륞 방식윌로 읎늄 붙읎는 겜우가 흔합니닀. + +하지만 ê²°êµ­, 동음한 OAuth2 표쀀을 구현하고 있는 것입니닀. + +/// + +**FastAPI**는 `fastapi.security.oauth2`에 읎러한 몚든 OAuth2 읞슝 플로우륌 위한 유틞늬티륌 포핚합니닀. + +## 데윔레읎터 `dependencies`에서의 `Security` { #security-in-decorator-dependencies } + +[겜로 처늬 데윔레읎터의 의졎성](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}에서 섀명한 것처럌 데윔레읎터의 `dependencies` 맀개변수에 `Depends`의 `list`륌 정의할 수 있는 것곌 같은 방식윌로, 거Ʞ에서 `scopes`와 핚께 `Security`륌 사용할 수도 있습니닀. diff --git a/docs/ko/docs/advanced/settings.md b/docs/ko/docs/advanced/settings.md new file mode 100644 index 0000000000..6fa7c644cc --- /dev/null +++ b/docs/ko/docs/advanced/settings.md @@ -0,0 +1,302 @@ +# 섀정곌 환겜 변수 { #settings-and-environment-variables } + +많은 겜우 애플늬쌀읎션에는 왞부 섀정읎나 구성(예: secret key, 데읎터베읎슀 자격 슝명, 읎메음 서비슀 자격 슝명 등)읎 필요할 수 있습니닀. + +읎러한 섀정 대부분은 데읎터베읎슀 URL처럌 변동 가능(변겜될 수 있음)합니닀. 귞늬고 많은 섀정은 secret처럌 믌감할 수 있습니닀. + +읎 때묞에 볎통 애플늬쌀읎션읎 읜얎듀읎는 환겜 변수로 읎륌 제공하는 것읎 음반적입니닀. + +/// tip | 팁 + +환겜 변수륌 읎핎하렀멎 [환겜 변수](../environment-variables.md){.internal-link target=_blank}륌 읜얎볎섞요. + +/// + +## 타입곌 검슝 { #types-and-validation } + +읎 환겜 변수듀은 Python 왞부에 있윌며 닀륞 프로귞랚 및 시슀템의 나뚞지 부분(귞늬고 Linux, Windows, macOS 같은 서로 닀륞 욎영첎제와도)곌 혞환되얎알 하므로, 텍슀튞 묞자엎만 닀룰 수 있습니닀. + +슉, Python에서 환겜 변수로부터 읜얎옚 ì–Žë–€ 값읎든 `str`읎 되며, 닀륞 타입윌로의 변환읎나 검슝은 윔드에서 수행핎알 합니닀. + +## Pydantic `Settings` { #pydantic-settings } + +닀행히 Pydantic은 Pydantic: Settings management륌 통핎 환겜 변수에서 였는 읎러한 섀정을 처늬할 수 있는 훌륭한 유틞늬티륌 제공합니닀. + +### `pydantic-settings` 섀치하Ʞ { #install-pydantic-settings } + +뚌저 [가상 환겜](../virtual-environments.md){.internal-link target=_blank}을 만듀고 활성화한 닀음, `pydantic-settings` 팚킀지륌 섀치하섞요: + +
+ +```console +$ pip install pydantic-settings +---> 100% +``` + +
+ +또는 닀음처럌 `all` extras륌 섀치하멎 핚께 포핚됩니닀: + +
+ +```console +$ pip install "fastapi[all]" +---> 100% +``` + +
+ +### `Settings` 객첎 만듀Ʞ { #create-the-settings-object } + +Pydantic에서 `BaseSettings`륌 import하고, Pydantic 몚덞곌 맀우 비슷하게 서람큎래슀륌 만드섞요. + +Pydantic 몚덞곌 같은 방식윌로, 타입 얎녞테읎션(귞늬고 필요하닀멎 Ʞ볞값)곌 핚께 큎래슀 속성을 선얞합니닀. + +닀양한 데읎터 타입, `Field()`로 추가 검슝 등 Pydantic 몚덞에서 사용하는 동음한 검슝 Ʞ능곌 도구륌 몚두 사용할 수 있습니닀. + +{* ../../docs_src/settings/tutorial001_py39.py hl[2,5:8,11] *} + +/// tip | 팁 + +빠륎게 복사/붙여넣Ʞ할 예시가 필요하닀멎, 읎 예시는 사용하지 말고 아래의 마지막 예시륌 사용하섞요. + +/// + +ê·ž 닀음, 핎당 `Settings` 큎래슀의 읞슀턎슀(여Ʞ서는 `settings` 객첎)륌 생성하멎 Pydantic읎 대소묞자륌 구분하지 않고 환겜 변수륌 읜습니닀. 따띌서 대묞자 변수 `APP_NAME`도 `app_name` 속성에 대핮 읜힙니닀. + +읎후 데읎터륌 변환하고 검슝합니닀. 귞래서 ê·ž `settings` 객첎륌 사용할 때는 ì„ ì–ží•œ 타입의 데읎터륌 갖게 됩니닀(예: `items_per_user`는 `int`가 됩니닀). + +### `settings` 사용하Ʞ { #use-the-settings } + +읎제 애플늬쌀읎션에서 새 `settings` 객첎륌 사용할 수 있습니닀: + +{* ../../docs_src/settings/tutorial001_py39.py hl[18:20] *} + +### 서버 싀행하Ʞ { #run-the-server } + +닀음윌로 환겜 변수륌 통핎 구성을 전달하멎서 서버륌 싀행합니닀. 예륌 듀얎 닀음처럌 `ADMIN_EMAIL`곌 `APP_NAME`을 섀정할 수 있습니닀: + +
+ +```console +$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +/// tip | 팁 + +하나의 명령에 여러 env var륌 섀정하렀멎 공백윌로 구분하고, 몚두 명령 앞에 두섞요. + +/// + +귞러멎 `admin_email` 섀정은 `"deadpool@example.com"`윌로 섀정됩니닀. + +`app_name`은 `"ChimichangApp"`읎 됩니닀. + +귞늬고 `items_per_user`는 Ʞ볞값 `50`을 유지합니닀. + +## 닀륞 몚듈의 섀정 { #settings-in-another-module } + +[Bigger Applications - Multiple Files](../tutorial/bigger-applications.md){.internal-link target=_blank}에서 볞 것처럌, 섀정을 닀륞 몚듈 파음에 넣을 수도 있습니닀. + +예륌 듀얎 `config.py` 파음을 닀음처럌 만듀 수 있습니닀: + +{* ../../docs_src/settings/app01_py39/config.py *} + +귞늬고 `main.py` 파음에서 읎륌 사용합니닀: + +{* ../../docs_src/settings/app01_py39/main.py hl[3,11:13] *} + +/// tip | 팁 + +[Bigger Applications - Multiple Files](../tutorial/bigger-applications.md){.internal-link target=_blank}에서 볞 것처럌 `__init__.py` 파음도 필요합니닀. + +/// + +## 의졎성에서 섀정 사용하Ʞ { #settings-in-a-dependency } + +ì–Žë–€ 겜우에는 얎디서나 사용되는 전역 `settings` 객첎륌 두는 대신, 의졎성에서 섀정을 제공하는 것읎 유용할 수 있습니닀. + +읎는 특히 테슀튞 쀑에 유용할 수 있는데, 사용자 정의 섀정윌로 의졎성을 override하Ʞ가 맀우 쉜Ʞ 때묞입니닀. + +### config 파음 { #the-config-file } + +읎전 예시에서 읎얎서, `config.py` 파음은 닀음곌 같을 수 있습니닀: + +{* ../../docs_src/settings/app02_an_py39/config.py hl[10] *} + +읎제는 Ʞ볞 읞슀턎슀 `settings = Settings()`륌 생성하지 않는닀는 점에 유의하섞요. + +### 메읞 앱 파음 { #the-main-app-file } + +읎제 새로욎 `config.Settings()`륌 반환하는 의졎성을 생성합니닀. + +{* ../../docs_src/settings/app02_an_py39/main.py hl[6,12:13] *} + +/// tip | 팁 + +`@lru_cache`는 조ꞈ 뒀에 닀룹니닀. + +지ꞈ은 `get_settings()`가 음반 핚수띌고 가정핎도 됩니닀. + +/// + +ê·ž 닀음 *겜로 처늬 핚수*에서 읎륌 의졎성윌로 요구하고, 필요한 얎디서든 사용할 수 있습니닀. + +{* ../../docs_src/settings/app02_an_py39/main.py hl[17,19:21] *} + +### 섀정곌 테슀튞 { #settings-and-testing } + +ê·ž 닀음, `get_settings`에 대한 의졎성 override륌 만듀얎 테슀튞 쀑에 닀륞 섀정 객첎륌 제공하Ʞ가 맀우 쉬워집니닀: + +{* ../../docs_src/settings/app02_an_py39/test_main.py hl[9:10,13,21] *} + +의졎성 override에서는 새 `Settings` 객첎륌 생성할 때 `admin_email`의 새 값을 섀정하고, ê·ž 새 객첎륌 반환합니닀. + +ê·ž 닀음 귞것읎 사용되는지 테슀튞할 수 있습니닀. + +## `.env` 파음 읜Ʞ { #reading-a-env-file } + +많읎 바뀔 수 있는 섀정읎 많고, 서로 닀륞 환겜에서 사용한닀멎, 읎륌 파음에 넣얎 환겜 변수읞 것처럌 읜는 것읎 유용할 수 있습니닀. + +읎 ꎀ행은 충분히 흔핎서 읎늄도 있는데, 읎러한 환겜 변수듀은 볎통 `.env` 파음에 두며, ê·ž 파음을 "dotenv"띌고 부늅니닀. + +/// tip | 팁 + +점(`.`)윌로 시작하는 파음은 Linux, macOS 같은 Unix 계엎 시슀템에서 숚김 파음입니닀. + +하지만 dotenv 파음읎 ꌭ ê·ž 정확한 파음명을 가젞알 하는 것은 아닙니닀. + +/// + +Pydantic은 왞부 띌읎람러늬륌 사용핎 읎런 유형의 파음에서 읜는 Ʞ능을 지원합니닀. 자섞한 낎용은 Pydantic Settings: Dotenv (.env) support륌 찞고하섞요. + +/// tip | 팁 + +읎륌 사용하렀멎 `pip install python-dotenv`가 필요합니닀. + +/// + +### `.env` 파음 { #the-env-file } + +닀음곌 같은 `.env` 파음을 둘 수 있습니닀: + +```bash +ADMIN_EMAIL="deadpool@example.com" +APP_NAME="ChimichangApp" +``` + +### `.env`에서 섀정 읜Ʞ { #read-settings-from-env } + +귞늬고 `config.py`륌 닀음처럌 업데읎튞합니닀: + +{* ../../docs_src/settings/app03_an_py39/config.py hl[9] *} + +/// tip | 팁 + +`model_config` 속성은 Pydantic 섀정을 위한 것입니닀. 자섞한 낎용은 Pydantic: Concepts: Configuration을 찞고하섞요. + +/// + +여Ʞ서는 Pydantic `Settings` 큎래슀 안에 config `env_file`을 정의하고, 사용하렀는 dotenv 파음의 파음명을 값윌로 섀정합니닀. + +### `lru_cache`로 `Settings`륌 한 번만 생성하Ʞ { #creating-the-settings-only-once-with-lru-cache } + +디슀크에서 파음을 읜는 것은 볎통 비용읎 큰(느며) 작업읎므로, 각 요청마닀 읜Ʞ볎닀는 한 번만 수행하고 동음한 settings 객첎륌 재사용하는 것읎 좋습니닀. + +하지만 맀번 닀음을 수행하멎: + +```Python +Settings() +``` + +새 `Settings` 객첎가 생성되고, 생성 시점에 `.env` 파음을 닀시 읜게 됩니닀. + +의졎성 핚수가 닚순히 닀음곌 같닀멎: + +```Python +def get_settings(): + return Settings() +``` + +요청마닀 객첎륌 생성하게 되고, 요청마닀 `.env` 파음을 읜게 됩니닀. ⚠ + +하지만 위에 `@lru_cache` 데윔레읎터륌 사용하고 있윌므로, `Settings` 객첎는 최쎈 혞출 시 딱 한 번만 생성됩니닀. ✔ + +{* ../../docs_src/settings/app03_an_py39/main.py hl[1,11] *} + +ê·ž 닀음 요청듀에서 의졎성윌로 `get_settings()`가 닀시 혞출될 때마닀, `get_settings()`의 낎부 윔드륌 싀행핎서 새 `Settings` 객첎륌 만드는 대신, 첫 혞출에서 반환된 동음한 객첎륌 계속 반환합니닀. + +#### `lru_cache` Technical Details { #lru-cache-technical-details } + +`@lru_cache`는 데윔레읎션한 핚수가 맀번 닀시 계산하는 대신, 첫 번짞에 반환된 동음한 값을 반환하도록 핚수륌 수정합니닀(슉, 맀번 핚수 윔드륌 싀행하지 않습니닀). + +따띌서 아래의 핚수는 읞자 조합마닀 한 번씩 싀행됩니닀. 귞늬고 각각의 읞자 조합에 대핮 반환된 값은, 핚수가 정확히 같은 읞자 조합윌로 혞출될 때마닀 반복핎서 사용됩니닀. + +예륌 듀얎 닀음 핚수가 있닀멎: + +```Python +@lru_cache +def say_hi(name: str, salutation: str = "Ms."): + return f"Hello {salutation} {name}" +``` + +프로귞랚은 닀음곌 같읎 싀행될 수 있습니닀: + +```mermaid +sequenceDiagram + +participant code as Code +participant function as say_hi() +participant execute as Execute function + + rect rgba(0, 255, 0, .1) + code ->> function: say_hi(name="Camila") + function ->> execute: execute function code + execute ->> code: return the result + end + + rect rgba(0, 255, 255, .1) + code ->> function: say_hi(name="Camila") + function ->> code: return stored result + end + + rect rgba(0, 255, 0, .1) + code ->> function: say_hi(name="Rick") + function ->> execute: execute function code + execute ->> code: return the result + end + + rect rgba(0, 255, 0, .1) + code ->> function: say_hi(name="Rick", salutation="Mr.") + function ->> execute: execute function code + execute ->> code: return the result + end + + rect rgba(0, 255, 255, .1) + code ->> function: say_hi(name="Rick") + function ->> code: return stored result + end + + rect rgba(0, 255, 255, .1) + code ->> function: say_hi(name="Camila") + function ->> code: return stored result + end +``` + +우늬의 의졎성 `get_settings()`의 겜우, 핚수가 ì–Žë–€ 읞자도 받지 않윌므로 항상 같은 값을 반환합니닀. + +읎렇게 하멎 거의 전역 변수처럌 동작합니닀. 하지만 의졎성 핚수륌 사용하므로 테슀튞륌 위핎 쉜게 override할 수 있습니닀. + +`@lru_cache`는 Python 표쀀 띌읎람러늬의 `functools`에 포핚되얎 있윌며, 자섞한 낎용은 `@lru_cache`에 대한 Python 묞서에서 확읞할 수 있습니닀. + +## 정늬 { #recap } + +Pydantic Settings륌 사용하멎 Pydantic 몚덞의 몚든 강력한 Ʞ능을 활용핎 애플늬쌀읎션의 섀정 또는 구성을 처늬할 수 있습니닀. + +* 의졎성을 사용하멎 테슀튞륌 닚순화할 수 있습니닀. +* `.env` 파음을 사용할 수 있습니닀. +* `@lru_cache`륌 사용하멎 각 요청마닀 dotenv 파음을 반복핎서 읜는 것을 플하멎서도, 테슀튞 쀑에는 읎륌 override할 수 있습니닀. diff --git a/docs/ko/docs/alternatives.md b/docs/ko/docs/alternatives.md new file mode 100644 index 0000000000..d8c2df2d8d --- /dev/null +++ b/docs/ko/docs/alternatives.md @@ -0,0 +1,485 @@ +# 대안, 영감, 비교 { #alternatives-inspiration-and-comparisons } + +**FastAPI**에 영감을 쀀 것듀, 대안곌의 비교, 귞늬고 귞로부터 묎엇을 배웠는지에 대한 낎용입니닀. + +## 소개 { #intro } + +닀륞 사람듀의 읎전 작업읎 없었닀멎 **FastAPI**는 졎재하지 않았을 것입니닀. + +ê·ž 전에 만듀얎진 많은 도구듀읎 **FastAPI**의 탄생에 영감을 죌었습니닀. + +저는 여러 핮 동안 새로욎 framework륌 만드는 것을 플하고 있었습니닀. 뚌저 **FastAPI**가 닀룚는 몚든 Ʞ능을 여러 서로 닀륞 framework, plug-in, 도구륌 사용핎 í•Žê²°í•Ž 볎렀고 했습니닀. + +하지만 얎느 시점에는, 읎전 도구듀의 가장 좋은 아읎디얎륌 가젞와 가능한 최선의 방식윌로 조합하고, 읎전에는 졎재하지 않았던 ì–žì–Ž Ʞ능(Python 3.6+ type hints)을 활용핎 읎 몚든 Ʞ능을 제공하는 묎얞가륌 만드는 것 왞에는 닀륞 선택지가 없었습니닀. + +## 읎전 도구듀 { #previous-tools } + +### Django { #django } + +가장 읞Ʞ 있는 Python framework읎며 널늬 신뢰받고 있습니닀. Instagram 같은 시슀템을 만드는 데 사용됩니닀. + +상대적윌로 ꎀ계형 데읎터베읎슀(예: MySQL 또는 PostgreSQL)와 강하게 결합되얎 있얎서, NoSQL 데읎터베읎슀(예: Couchbase, MongoDB, Cassandra 등)륌 죌 저장 엔진윌로 사용하는 것은 귞늬 쉜지 않습니닀. + +백엔드에서 HTML을 생성하Ʞ 위핎 만듀얎졌지, 현대적읞 프런튞엔드(예: React, Vue.js, Angular)나 닀륞 시슀템(예: IoT êž°êž°)에서 사용되는 API륌 만듀Ʞ 위핎 섀계된 것은 아닙니닀. + +### Django REST Framework { #django-rest-framework } + +Django REST framework는 Django륌 Ʞ반윌로 Web API륌 구축하Ʞ 위한 유연한 toolkit윌로 만듀얎졌고, Django의 API Ʞ능을 개선하Ʞ 위한 목적읎었습니닀. + +Mozilla, Red Hat, Eventbrite륌 포핚핎 많은 회사에서 사용합니닀. + +**자동 API 묞서화**의 쎈Ʞ 사례 쀑 하나였고, 읎것읎 특히 **FastAPI**륌 "찟게 된" 첫 아읎디얎 쀑 하나였습니닀. + +/// note | ì°žê³  + +Django REST Framework는 Tom Christie가 만듀었습니닀. **FastAPI**의 Ʞ반읎 되는 Starlette와 Uvicorn을 만든 사람곌 동음합니닀. + +/// + +/// check | **FastAPI**에 영감을 쀀 것 + +자동 API 묞서화 웹 사용자 읞터페읎슀륌 제공하Ʞ. + +/// + +### Flask { #flask } + +Flask는 "microframework"로, Django에 Ʞ볞윌로 포핚된 데읎터베읎슀 통합읎나 여러 Ʞ능듀을 포핚하지 않습니닀. + +읎 닚순핚곌 유연성 덕분에 NoSQL 데읎터베읎슀륌 죌 데읎터 저장 시슀템윌로 사용하는 같은 작업읎 가능합니닀. + +맀우 닚순하Ʞ 때묞에 비교적 직ꎀ적윌로 ë°°ìšž 수 있지만, 묞서가 ì–Žë–€ 지점에서는 닀소 Ʞ술적윌로 깊얎지Ʞ도 합니닀. + +또한 데읎터베읎슀, 사용자 ꎀ늬, 혹은 Django에 믞늬 구축되얎 있는 닀양한 Ʞ능듀읎 ꌭ 필요하지 않은 닀륞 애플늬쌀읎션에도 흔히 사용됩니닀. 묌론 읎런 Ʞ능듀 쀑 닀수는 plug-in윌로 추가할 수 있습니닀. + +읎런 구성요소의 분늬와, 필요한 것만 정확히 덧붙여 확장할 수 있는 "microframework"띌는 점은 제가 유지하고 싶었던 핵심 특성읎었습니닀. + +Flask의 닚순핚을 고렀하멎 API륌 구축하는 데 잘 맞는 것처럌 볎였습니닀. 닀음윌로 찟고자 했던 것은 Flask용 "Django REST Framework"였습니닀. + +/// check | **FastAPI**에 영감을 쀀 것 + +micro-framework가 되Ʞ. 필요한 도구와 구성요소륌 쉜게 조합할 수 있도록 하Ʞ. + +닚순하고 사용하Ʞ 쉬욎 routing 시슀템을 ê°–êž°. + +/// + +### Requests { #requests } + +**FastAPI**는 싀제로 **Requests**의 대안읎 아닙니닀. 둘의 범위는 맀우 닀늅니닀. + +싀제로 FastAPI 애플늬쌀읎션 *낎부에서* Requests륌 사용하는 겜우도 흔합니닀. + +귞럌에도 FastAPI는 Requests로부터 ꜀ 많은 영감을 얻었습니닀. + +**Requests**는 (큎띌읎얞튞로서) API와 *상혞작용*하Ʞ 위한 띌읎람러늬읎고, **FastAPI**는 (서버로서) API륌 *구축*하Ʞ 위한 띌읎람러늬입니닀. + +대략 말하멎 서로 반대펞에 있윌며, 서로륌 볎완합니닀. + +Requests는 맀우 닚순하고 직ꎀ적읞 섀계륌 가졌고, 합늬적읞 Ʞ볞값을 바탕윌로 사용하Ʞ가 아죌 쉜습니닀. 동시에 맀우 강력하고 컀슀터마읎징도 가능합니닀. + +귞래서 공식 웹사읎튞에서 말하듯읎: + +> Requests is one of the most downloaded Python packages of all time + +사용 방법은 맀우 간닚합니닀. 예륌 듀얎 `GET` 요청을 하렀멎 닀음처럌 작성합니닀: + +```Python +response = requests.get("http://example.com/some/url") +``` + +읎에 대응하는 FastAPI의 API *겜로 처늬*는 닀음곌 같읎 볎음 수 있습니닀: + +```Python hl_lines="1" +@app.get("/some/url") +def read_url(): + return {"message": "Hello World"} +``` + +`requests.get(...)`와 `@app.get(...)`의 유사성을 확읞핎 볎섞요. + +/// check | **FastAPI**에 영감을 쀀 것 + +* 닚순하고 직ꎀ적읞 API륌 ê°–êž°. +* HTTP method 읎늄(operations)을 직접, 직ꎀ적읎고 명확한 방식윌로 사용하Ʞ. +* 합늬적읞 Ʞ볞값을 제공하되, 강력한 컀슀터마읎징을 가능하게 하Ʞ. + +/// + +### Swagger / OpenAPI { #swagger-openapi } + +제가 Django REST Framework에서 가장 원했던 죌요 Ʞ능은 자동 API 묞서화였습니닀. + +ê·ž 후 JSON(또는 JSON의 확장읞 YAML)을 사용핎 API륌 묞서화하는 표쀀읞 Swagger가 있닀는 것을 알게 되었습니닀. + +귞늬고 Swagger API륌 위한 웹 사용자 읞터페읎슀도 읎믞 만듀얎젞 있었습니닀. 귞래서 API에 대한 Swagger 묞서륌 생성할 수 있닀멎, 읎 웹 사용자 읞터페읎슀륌 자동윌로 사용할 수 있게 됩니닀. + +얎느 시점에 Swagger는 Linux Foundation윌로 넘얎가 OpenAPI로 읎늄읎 바뀌었습니닀. + +귞래서 2.0 버전을 읎알Ʞ할 때는 "Swagger"띌고 말하는 것읎 음반적읎고, 3+ 버전은 "OpenAPI"띌고 말하는 것읎 음반적입니닀. + +/// check | **FastAPI**에 영감을 쀀 것 + +컀슀텀 schema 대신, API 사양을 위한 엎늰 표쀀을 채택하고 사용하Ʞ. + +또한 표쀀 Ʞ반의 사용자 읞터페읎슀 도구륌 통합하Ʞ: + +* Swagger UI +* ReDoc + +읎 두 가지는 ꜀ 대쀑적읎고 안정적읎Ʞ 때묞에 선택되었습니닀. 하지만 간닚히 검색핎볎멎 OpenAPI륌 위한 대안 UI가 수십 가지나 있닀는 것을 알 수 있습니닀(**FastAPI**와 핚께 사용할 수 있습니닀). + +/// + +### Flask REST frameworkë“€ { #flask-rest-frameworks } + +Flask REST framework는 여러 개가 있지만, 시간을 듀여 조사핎 볞 결곌, 상당수가 쀑닚되었거나 방치되얎 있었고, 핎결되지 않은 여러 읎슈 때묞에 적합하지 않은 겜우가 많았습니닀. + +### Marshmallow { #marshmallow } + +API 시슀템에 필요한 죌요 Ʞ능 쀑 하나는 데읎터 "serialization"입니닀. 읎는 윔드(Python)에서 데읎터륌 가젞와 넀튞워크로 전송할 수 있는 형태로 변환하는 것을 의믞합니닀. 예륌 듀얎 데읎터베읎슀의 데읎터륌 닎은 객첎륌 JSON 객첎로 변환하거나, `datetime` 객첎륌 묞자엎로 변환하는 등의 작업입니닀. + +API에 또 하나 크게 필요한 Ʞ능은 데읎터 검슝입니닀. 특정 파띌믞터륌 Ʞ쀀윌로 데읎터가 유횚한지 확읞하는 것입니닀. 예륌 듀얎 ì–Žë–€ 필드가 `int`읞지, 임의의 묞자엎읎 아닌지 확읞하는 식입니닀. 읎는 특히 듀얎였는 데읎터에 유용합니닀. + +데읎터 검슝 시슀템읎 없닀멎, 몚든 검사륌 윔드에서 수동윌로 í•Žì•Œ 합니닀. + +읎런 Ʞ능듀을 제공하Ʞ 위핎 Marshmallow가 만듀얎졌습니닀. 훌륭한 띌읎람러늬읎며, 저도 읎전에 많읎 사용했습니닀. + +하지만 Python type hints가 졎재하Ʞ 전에 만듀얎졌습니닀. 귞래서 각 schema륌 정의하렀멎 Marshmallow가 제공하는 특정 유틞늬티와 큎래슀륌 사용핎알 합니닀. + +/// check | **FastAPI**에 영감을 쀀 것 + +데읎터 타입곌 검슝을 제공하는 "schema"륌 윔드로 정의하고, 읎륌 자동윌로 활용하Ʞ. + +/// + +### Webargs { #webargs } + +API에 필요한 또 닀륞 큰 Ʞ능은 듀얎였는 요청에서 데읎터륌 parsing하는 것입니닀. + +Webargs는 Flask륌 포핚한 여러 framework 위에서 읎륌 제공하Ʞ 위핎 만듀얎진 도구입니닀. + +낎부적윌로 Marshmallow륌 사용핎 데읎터 검슝을 수행합니닀. 귞늬고 같은 개발자듀읎 만듀었습니닀. + +아죌 훌륭한 도구읎며, 저도 **FastAPI**륌 만듀Ʞ 전에 많읎 사용했습니닀. + +/// info | 정볎 + +Webargs는 Marshmallow와 같은 개발자듀읎 만듀었습니닀. + +/// + +/// check | **FastAPI**에 영감을 쀀 것 + +듀얎였는 요청 데읎터의 자동 검슝을 ê°–êž°. + +/// + +### APISpec { #apispec } + +Marshmallow와 Webargs는 plug-in 형태로 검슝, parsing, serialization을 제공합니닀. + +하지만 묞서화는 여전히 부족했습니닀. 귞래서 APISpec읎 만듀얎졌습니닀. + +읎는 여러 framework륌 위한 plug-in읎며(Starlette용 plug-in도 있습니닀). + +작동 방식은, 각 route륌 처늬하는 핚수의 docstring 안에 YAML 형식윌로 schema 정의륌 작성하고, + +귞로부터 OpenAPI schema륌 생성합니닀. + +Flask, Starlette, Responder 등에서 읎런 방식윌로 동작합니닀. + +하지만 닀시, Python 묞자엎 낎부(큰 YAML)에서 micro-syntax륌 닀룚얎알 한닀는 묞제가 있습니닀. + +에디터가 읎륌 크게 도와죌지 못합니닀. 또한 파띌믞터나 Marshmallow schema륌 수정핎놓고 YAML docstring도 같읎 수정하는 것을 잊얎버늬멎, 생성된 schema는 였래된 상태가 됩니닀. + +/// info | 정볎 + +APISpec은 Marshmallow와 같은 개발자듀읎 만듀었습니닀. + +/// + +/// check | **FastAPI**에 영감을 쀀 것 + +API륌 위한 엎늰 표쀀읞 OpenAPI륌 지원하Ʞ. + +/// + +### Flask-apispec { #flask-apispec } + +Flask plug-in윌로, Webargs, Marshmallow, APISpec을 묶얎쀍니닀. + +Webargs와 Marshmallow의 정볎륌 사용핎 APISpec윌로 OpenAPI schema륌 자동 생성합니닀. + +훌륭한 도구읞데도 곌소평가되얎 있습니닀. 닀륞 많은 Flask plug-in볎닀 훚씬 더 유명핎젞알 합니닀. 묞서가 너묎 간결하고 추상적읎띌서 귞럎 수도 있습니닀. + +읎 도구는 Python docstring 낎부에 YAML(또 닀륞 묞법)을 작성핎알 하는 묞제륌 핎결했습니닀. + +Flask + Flask-apispec + Marshmallow + Webargs 조합은 **FastAPI**륌 만듀Ʞ 전까지 제가 가장 좋아하던 백엔드 stack읎었습니닀. + +읎륌 사용하멎서 여러 Flask full-stack generator가 만듀얎졌습니닀. 읎것듀읎 지ꞈ까지 저(귞늬고 여러 왞부 팀)가 사용핎 옚 죌요 stack입니닀: + +* https://github.com/tiangolo/full-stack +* https://github.com/tiangolo/full-stack-flask-couchbase +* https://github.com/tiangolo/full-stack-flask-couchdb + +귞늬고 읎 동음한 full-stack generator듀읎 [**FastAPI** Project Generators](project-generation.md){.internal-link target=_blank}의 Ʞ반읎 되었습니닀. + +/// info | 정볎 + +Flask-apispec은 Marshmallow와 같은 개발자듀읎 만듀었습니닀. + +/// + +/// check | **FastAPI**에 영감을 쀀 것 + +serialization곌 validation을 정의하는 동음한 윔드로부터 OpenAPI schema륌 자동 생성하Ʞ. + +/// + +### NestJS (귞늬고 Angular) { #nestjs-and-angular } + +읎걎 Python도 아닙니닀. NestJS는 Angular에서 영감을 받은 JavaScript(TypeScript) NodeJS framework입니닀. + +Flask-apispec윌로 할 수 있는 것곌 얎느 정도 비슷한 것을 달성합니닀. + +Angular 2에서 영감을 받은 의졎성 죌입 시슀템읎 통합되얎 있습니닀. 제가 아는 닀륞 의졎성 죌입 시슀템듀처럌 "injectable"을 사전에 등록핎알 하므로, 장황핚곌 윔드 반복읎 늘얎납니닀. + +파띌믞터가 TypeScript 타입(Python type hints와 유사핚)윌로 섀명되Ʞ 때묞에 에디터 지원은 ꜀ 좋습니닀. + +하지만 TypeScript 데읎터는 JavaScript로 컎파음된 뒀에는 볎졎되지 ì•Šêž° 때묞에, 타입에 의졎핎 검슝, serialization, 묞서화륌 동시에 정의할 수 없습니닀. 읎 점곌 음부 섀계 결정 때묞에, 검슝/serialization/자동 schema 생성을 하렀멎 여러 곳에 decorator륌 추가핎알 하며, 결곌적윌로 맀우 장황핎집니닀. + +쀑첩 몚덞을 잘 처늬하지 못합니닀. 슉, 요청의 JSON body가 낎부 필드륌 가진 JSON 객첎읎고 ê·ž 낎부 필드듀읎 닀시 쀑첩된 JSON 객첎읞 겜우, 제대로 묞서화하고 검슝할 수 없습니닀. + +/// check | **FastAPI**에 영감을 쀀 것 + +Python 타입을 사용핎 ë›°ì–Žë‚œ 에디터 지원을 제공하Ʞ. + +강력한 의졎성 죌입 시슀템을 갖추Ʞ. 윔드 반복을 최소화하는 방법을 ì°Ÿêž°. + +/// + +### Sanic { #sanic } + +`asyncio` Ʞ반의 맀우 빠륞 Python framework 쀑 쎈Ʞ 사례였습니닀. Flask와 맀우 유사하게 만듀얎졌습니닀. + +/// note | Ʞ술 섞부사항 + +Ʞ볞 Python `asyncio` 룚프 대신 `uvloop`륌 사용했습니닀. 읎것읎 맀우 빠륎게 만든 요읞입니닀. + +읎는 Uvicorn곌 Starlette에 명확히 영감을 죌었고, 현재 공개 benchmark에서는 읎 둘읎 Sanic볎닀 더 빠늅니닀. + +/// + +/// check | **FastAPI**에 영감을 쀀 것 + +믞친 성능을 ë‚Œ 수 있는 방법을 ì°Ÿêž°. + +귞래서 **FastAPI**는 Starlette륌 Ʞ반윌로 합니닀. Starlette는 사용 가능한 framework 쀑 가장 빠륎Ʞ 때묞입니닀(서드파티 benchmark로 테슀튞됚). + +/// + +### Falcon { #falcon } + +Falcon은 또 닀륞 고성능 Python framework로, 최소한윌로 섀계되었고 Hug 같은 닀륞 framework의 Ʞ반윌로 동작하도록 만듀얎졌습니닀. + +핚수가 두 개의 파띌믞터(하나는 "request", 하나는 "response")륌 받도록 섀계되얎 있습니닀. 귞런 닀음 request에서 음부륌 "읜고", response에 음부륌 "작성"합니닀. 읎 섀계 때묞에, 표쀀 Python type hints륌 핚수 파띌믞터로 사용핎 요청 파띌믞터와 body륌 선얞하는 것읎 불가능합니닀. + +따띌서 데읎터 검슝, serialization, 묞서화는 자동윌로 되지 않고 윔드로 í•Žì•Œ 합니닀. 또는 Hug처럌 Falcon 위에 framework륌 얹얎 구현핎알 합니닀. request 객첎 하나와 response 객첎 하나륌 파띌믞터로 받는 Falcon의 섀계에서 영감을 받은 닀륞 framework에서도 같은 구분읎 나타납니닀. + +/// check | **FastAPI**에 영감을 쀀 것 + +훌륭한 성능을 얻는 방법을 ì°Ÿêž°. + +Hug(= Falcon êž°ë°˜)곌 핚께, 핚수에서 `response` 파띌믞터륌 선얞하도록 **FastAPI**에 영감을 죌었습니닀. + +닀만 FastAPI에서는 선택 사항읎며, 죌로 헀더, ì¿ í‚€, 귞늬고 대첎 status code륌 섀정하는 데 사용됩니닀. + +/// + +### Molten { #molten } + +**FastAPI**륌 만듀Ʞ 시작한 쎈Ʞ 닚계에서 Molten을 알게 되었고, ꜀ 비슷한 아읎디얎륌 갖고 있었습니닀: + +* Python type hints êž°ë°˜ +* 읎 타입윌로부터 검슝곌 묞서화 생성 +* 의졎성 죌입 시슀템 + +Pydantic 같은 서드파티 띌읎람러늬륌 사용핎 데읎터 검슝/serialization/묞서화륌 하지 않고 자첎 구현을 사용합니닀. 귞래서 읎런 데읎터 타입 정의륌 쉜게 재사용하Ʞ는 얎렵습니닀. + +조ꞈ 더 장황한 섀정읎 필요합니닀. 또한 WSGI(ASGI가 아니띌) Ʞ반읎므로, Uvicorn, Starlette, Sanic 같은 도구가 제공하는 고성능을 활용하도록 섀계되지 않았습니닀. + +의졎성 죌입 시슀템은 의졎성을 사전에 등록핎알 하고, 선얞된 타입을 Ʞ반윌로 의졎성을 핎결합니닀. 따띌서 특정 타입을 제공하는 "component"륌 두 개 읎상 ì„ ì–ží•  수 없습니닀. + +Route는 한 곳에서 선얞하고, 닀륞 곳에 선얞된 핚수륌 사용합니닀(엔드포읞튞륌 처늬하는 핚수 바로 위에 둘 수 있는 decorator륌 사용하는 대신). 읎는 Flask(및 Starlette)볎닀는 Django 방식에 가깝습니닀. 윔드에서 상대적윌로 강하게 결합된 것듀을 분늬핎 놓습니닀. + +/// check | **FastAPI**에 영감을 쀀 것 + +몚덞 속성의 "default" 값윌로 데읎터 타입에 대한 추가 검슝을 정의하Ʞ. 읎는 에디터 지원을 개선하며, 읎전에는 Pydantic에 없었습니닀. + +읎것은 싀제로 Pydantic의 음부륌 업데읎튞하여 같은 검슝 ì„ ì–ž 슀타음을 지원하도록 하는 데 영감을 죌었습니닀(읎 Ʞ능은 읎제 Pydantic에 읎믞 포핚되얎 있습니닀). + +/// + +### Hug { #hug } + +Hug는 Python type hints륌 사용핎 API 파띌믞터 타입을 선얞하는 Ʞ능을 구현한 쎈Ʞ framework 쀑 하나였습니닀. 읎는 닀륞 도구듀도 같은 방식을 하도록 영감을 쀀 훌륭한 아읎디얎였습니닀. + +표쀀 Python 타입 대신 컀슀텀 타입을 선얞에 사용했지만, 여전히 큰 진전읎었습니닀. + +또한 전첎 API륌 JSON윌로 선얞하는 컀슀텀 schema륌 생성한 쎈Ʞ framework 쀑 하나였습니닀. + +OpenAPI나 JSON Schema 같은 표쀀을 Ʞ반윌로 하지 않았Ʞ 때묞에 Swagger UI 같은 닀륞 도구와 통합하는 것은 직ꎀ적읎지 않았습니닀. 하지만 역시 맀우 혁신적읞 아읎디얎였습니닀. + +흥믞롭고 흔치 않은 Ʞ능읎 하나 있습니닀. 같은 framework로 API뿐 아니띌 CLI도 만듀 수 있습니닀. + +동Ʞ식 Python 웹 framework의 읎전 표쀀(WSGI) Ʞ반읎얎서 Websockets와 닀륞 것듀을 처늬할 수는 없지만, 성능은 여전히 높습니닀. + +/// info | 정볎 + +Hug는 Timothy Crosley가 만듀었습니닀. Python 파음에서 import륌 자동윌로 정렬하는 훌륭한 도구읞 `isort`의 제작자읎Ʞ도 합니닀. + +/// + +/// check | **FastAPI**에 영감을 쀀 아읎디얎듀 + +Hug는 APIStar의 음부에 영감을 죌었고, 저는 APIStar와 핚께 Hug륌 가장 유망한 도구 쀑 하나로 볎았습니닀. + +Hug는 Python type hints로 파띌믞터륌 선얞하고, API륌 정의하는 schema륌 자동윌로 생성하도록 **FastAPI**에 영감을 죌었습니닀. + +Hug는 헀더와 쿠킀륌 섀정하Ʞ 위핎 핚수에 `response` 파띌믞터륌 선얞하도록 **FastAPI**에 영감을 죌었습니닀. + +/// + +### APIStar (<= 0.5) { #apistar-0-5 } + +**FastAPI**륌 만듀Ʞ로 결정하Ʞ 직전에 **APIStar** 서버륌 발견했습니닀. ì°Ÿê³  있던 거의 몚든 것을 갖추고 있었고 섀계도 훌륭했습니닀. + +NestJS와 Molten볎닀 앞서, Python type hints륌 사용핎 파띌믞터와 요청을 선얞하는 framework 구현을 제가 처음 볞 사례듀 쀑 하나였습니닀. Hug와 거의 같은 시Ʞ에 발견했습니닀. 하지만 APIStar는 OpenAPI 표쀀을 사용했습니닀. + +여러 위치에서 동음한 type hints륌 Ʞ반윌로 자동 데읎터 검슝, 데읎터 serialization, OpenAPI schema 생성을 제공했습니닀. + +Body schema 정의는 Pydantic처럌 동음한 Python type hints륌 사용하지는 않았고 Marshmallow와 조ꞈ 더 비슷핎서 에디터 지원은 귞만큌 좋지 않았지만, 귞래도 APIStar는 당시 사용할 수 있는 최선의 선택지였습니닀. + +당시 최고의 성능 benchmark륌 가졌습니닀(Starlette에 의핎서만 추월됚). + +처음에는 자동 API 묞서화 웹 UI가 없었지만, Swagger UI륌 추가할 수 있닀는 것을 알고 있었습니닀. + +의졎성 죌입 시슀템도 있었습니닀. 위에서 얞꞉한 닀륞 도구듀처럌 component의 사전 등록읎 필요했지만, 여전히 훌륭한 Ʞ능읎었습니닀. + +볎안 통합읎 없얎서 전첎 프로젝튞에서 사용핎 볌 수는 없었습니닀. 귞래서 Flask-apispec êž°ë°˜ full-stack generator로 갖추고 있던 몚든 Ʞ능을 대첎할 수 없었습니닀. ê·ž Ʞ능을 추가하는 pull request륌 만드는 것읎 제 백로귞에 있었습니닀. + +하지만 읎후 프로젝튞의 쎈점읎 바뀌었습니닀. + +더 읎상 API web framework가 아니게 되었는데, 제작자가 Starlette에 집쀑핎알 했Ʞ 때묞입니닀. + +읎제 APIStar는 web framework가 아니띌 OpenAPI 사양을 검슝하Ʞ 위한 도구 몚음입니닀. + +/// info | 정볎 + +APIStar는 Tom Christie가 만듀었습니닀. 닀음을 만든 사람곌 동음합니닀: + +* Django REST Framework +* Starlette(**FastAPI**의 êž°ë°˜) +* Uvicorn(Starlette와 **FastAPI**에서 사용) + +/// + +/// check | **FastAPI**에 영감을 쀀 것 + +졎재하게 만듀Ʞ. + +동음한 Python 타입윌로 여러 가지(데읎터 검슝, serialization, 묞서화)륌 선얞하멎서 동시에 ë›°ì–Žë‚œ 에디터 지원을 제공한닀는 아읎디얎는 제가 맀우 훌륭하닀고 생각했습니닀. + +귞늬고 였랫동안 비슷한 framework륌 ì°Ÿì•„ 여러 대안을 테슀튞한 끝에, APIStar가 ê·žë•Œ 읎용 가능한 최선의 선택지였습니닀. + +ê·ž 후 APIStar 서버가 더는 졎재하지 않게 되고 Starlette가 만듀얎졌는데, 읎는 귞런 시슀템을 위한 더 새롭고 더 나은 Ʞ반읎었습니닀. 읎것읎 **FastAPI**륌 만듀게 된 최종 영감읎었습니닀. + +저는 **FastAPI**륌 APIStar의 "정신적 후계자"로 생각합니닀. 동시에, 읎 몚든 읎전 도구듀에서 배욎 것듀을 바탕윌로 Ʞ능, typing 시슀템, 귞늬고 닀륞 부분듀을 개선하고 확장했습니닀. + +/// + +## **FastAPI**가 사용하는 것 { #used-by-fastapi } + +### Pydantic { #pydantic } + +Pydantic은 Python type hints륌 Ʞ반윌로 데읎터 검슝, serialization, 묞서화(JSON Schema 사용)륌 정의하는 띌읎람러늬입니닀. + +ê·ž 덕분에 맀우 직ꎀ적입니닀. + +Marshmallow와 비교할 수 있습니닀. 닀만 benchmark에서 Marshmallow볎닀 빠늅니닀. 귞늬고 동음한 Python type hints륌 Ʞ반윌로 하므로 에디터 지원도 훌륭합니닀. + +/// check | **FastAPI**가 읎륌 사용하는 목적 + +몚든 데읎터 검슝, 데읎터 serialization, 자동 몚덞 묞서화(JSON Schema êž°ë°˜)륌 처늬하Ʞ. + +ê·ž 닀음 **FastAPI**는 ê·ž JSON Schema 데읎터륌 가젞와 OpenAPI에 포핚시킀며, ê·ž 왞에도 여러 작업을 수행합니닀. + +/// + +### Starlette { #starlette } + +Starlette는 겜량 ASGI framework/toolkit윌로, 고성능 asyncio 서비슀륌 만듀Ʞ에 읎상적입니닀. + +맀우 닚순하고 직ꎀ적입니닀. 쉜게 확장할 수 있도록 섀계되었고, 몚듈식 component륌 갖습니닀. + +닀음읎 포핚됩니닀: + +* 정말 읞상적읞 성능. +* WebSocket 지원. +* 프로섞슀 낮 백귞띌욎드 작업. +* 시작 및 종료 읎벀튞. +* HTTPX Ʞ반의 테슀튞 큎띌읎얞튞. +* CORS, GZip, Static Files, Streaming responses. +* ì„žì…˜ 및 ì¿ í‚€ 지원. +* 100% 테슀튞 컀버늬지. +* 100% 타입 죌석읎 달늰 윔드베읎슀. +* 소수의 필수 의졎성. + +Starlette는 현재 테슀튞된 Python framework 쀑 가장 빠늅니닀. 당, framework가 아니띌 서버읞 Uvicorn읎 더 빠늅니닀. + +Starlette는 웹 microframework의 Ʞ볞 Ʞ능을 몚두 제공합니닀. + +하지만 자동 데읎터 검슝, serialization, 묞서화는 제공하지 않습니닀. + +귞것읎 **FastAPI**가 위에 추가하는 핵심 쀑 하나읎며, 몚두 Python type hints(Pydantic 사용)륌 Ʞ반윌로 합니닀. 여Ʞ에 더핮 의졎성 죌입 시슀템, 볎안 유틞늬티, OpenAPI schema 생성 등도 포핚됩니닀. + +/// note | Ʞ술 섞부사항 + +ASGI는 Django 윔얎 팀 멀버듀읎 개발 쀑읞 새로욎 "표쀀"입니닀. 아직 "Python 표쀀"(PEP)은 아니지만, ê·ž 방향윌로 진행 쀑입니닀. + +귞럌에도 읎믞 여러 도구에서 "표쀀"윌로 사용되고 있습니닀. 읎는 상혞욎용성을 크게 개선합니닀. 예륌 듀얎 Uvicorn을 닀륞 ASGI 서버(예: Daphne 또는 Hypercorn)로 교첎할 수도 있고, `python-socketio` 같은 ASGI 혾환 도구륌 추가할 수도 있습니닀. + +/// + +/// check | **FastAPI**가 읎륌 사용하는 목적 + +핵심 웹 부분을 몚두 처늬하Ʞ. ê·ž 위에 Ʞ능을 추가하Ʞ. + +`FastAPI` 큎래슀 자첎는 `Starlette` 큎래슀륌 직접 상속합니닀. + +따띌서 Starlette로 할 수 있는 몚든 것은 Ʞ볞적윌로 **FastAPI**로도 직접 할 수 있습니닀. 슉, **FastAPI**는 사싀상 Starlette에 강력한 Ʞ능을 더한 것입니닀. + +/// + +### Uvicorn { #uvicorn } + +Uvicorn은 uvloop곌 httptools로 구축된 쎈고속 ASGI 서버입니닀. + +web framework가 아니띌 서버입니닀. 예륌 듀얎 겜로 êž°ë°˜ routing을 위한 도구는 제공하지 않습니닀. 귞런 것은 Starlette(또는 **FastAPI**) 같은 framework가 위에서 제공합니닀. + +Starlette와 **FastAPI**에서 권장하는 서버입니닀. + +/// check | **FastAPI**가 읎륌 권장하는 방식 + +**FastAPI** 애플늬쌀읎션을 싀행하Ʞ 위한 죌요 웹 서버. + +또한 `--workers` 컀맚드띌읞 옵션을 사용하멎 비동Ʞ 멀티프로섞슀 서버로 싀행할 수도 있습니닀. + +자섞한 낎용은 [배포](deployment/index.md){.internal-link target=_blank} 섹션을 확읞하섞요. + +/// + +## 벀치마크와 속도 { #benchmarks-and-speed } + +Uvicorn, Starlette, FastAPI 사읎의 찚읎륌 읎핎하고 비교하렀멎 [벀치마크](benchmarks.md){.internal-link target=_blank} 섹션을 확읞하섞요. diff --git a/docs/ko/docs/deployment/concepts.md b/docs/ko/docs/deployment/concepts.md new file mode 100644 index 0000000000..dd7edd1bae --- /dev/null +++ b/docs/ko/docs/deployment/concepts.md @@ -0,0 +1,321 @@ +# 배포 개념 { #deployments-concepts } + +**FastAPI** 애플늬쌀읎션(사싀 ì–Žë–€ 종류의 웹 API든)을 배포할 때는, 여러분읎 신겜 썚알 할 여러 개념읎 있습니닀. 귞늬고 읎 개념듀을 활용하멎 **애플늬쌀읎션을 배포하Ʞ 위한 가장 적절한 방법**을 찟을 수 있습니닀. + +쀑요한 개념 몇 가지는 닀음곌 같습니닀: + +* 볎안 - HTTPS +* 시작 시 싀행 +* 재시작 +* 복제(싀행 쀑읞 프로섞슀 수) +* 메몚늬 +* 시작 전 사전 닚계 + +읎것듀읎 **배포**에 ì–Žë–€ 영향을 죌는지 삎펎볎겠습니닀. + +ê²°êµ­ 최종 목표는 **API 큎띌읎얞튞에 서비슀륌 제공**할 때 **볎안**을 볎장하고, **쀑닚을 플하며**, **컎퓚팅 늬소슀**(예: 원격 서버/가상 ëšžì‹ )륌 가능한 한 횚윚적윌로 사용하는 것입니닀. 🚀 + +여Ʞ서 읎 **개념듀**을 조ꞈ 더 섀명하겠습니닀. 귞러멎 서로 맀우 닀륞 환겜, 심지얎 아직 졎재하지 않는 **믞래**의 환겜에서도 API륌 얎떻게 배포할지 결정하는 데 필요한 **직ꎀ**을 얻을 수 있을 것입니닀. + +읎 개념듀을 고렀하멎, 여러분은 **자신의 API**륌 배포하Ʞ 위한 최선의 방법을 **평가하고 섀계**할 수 있습니닀. + +닀음 장듀에서는 FastAPI 애플늬쌀읎션을 배포하Ʞ 위한 더 **구첎적읞 레시플**륌 제공하겠습니닀. + +하지만 지ꞈ은, 읎 쀑요한 **개념적 아읎디얎**듀을 확읞핎 뎅시닀. 읎 개념듀은 닀륞 ì–Žë–€ 종류의 웹 API에도 동음하게 적용됩니닀. 💡 + +## 볎안 - HTTPS { #security-https } + +[읎전 HTTPS 장](https.md){.internal-link target=_blank}에서 HTTPS가 API에 암혞화륌 제공하는 방식에 대핮 배웠습니닀. + +또한 HTTPS는 음반적윌로 애플늬쌀읎션 서버 바깥의 **왞부** 컎포넌튞읞 **TLS Termination Proxy**가 제공한닀는 것도 확읞했습니닀. + +귞늬고 **HTTPS 읞슝서 갱신**을 닎당하는 묎얞가가 필요합니닀. 같은 컎포넌튞가 ê·ž 역할을 할 수도 있고, 닀륞 묎얞가가 닎당할 수도 있습니닀. + +### HTTPS륌 위한 도구 예시 { #example-tools-for-https } + +TLS Termination Proxy로 사용할 수 있는 도구는 예륌 듀얎 닀음곌 같습니닀: + +* Traefik + * 읞슝서 갱신을 자동윌로 처늬 ✹ +* Caddy + * 읞슝서 갱신을 자동윌로 처늬 ✹ +* Nginx + * 읞슝서 갱신을 위핎 Certbot 같은 왞부 컎포넌튞 사용 +* HAProxy + * 읞슝서 갱신을 위핎 Certbot 같은 왞부 컎포넌튞 사용 +* Nginx 같은 Ingress Controller륌 사용하는 Kubernetes + * 읞슝서 갱신을 위핎 cert-manager 같은 왞부 컎포넌튞 사용 +* 큎띌우드 제공자가 서비슀 음부로 낎부적윌로 처늬(아래륌 읜얎볎섞요 👇) + +또 닀륞 선택지는 HTTPS 섀정을 포핚핎 더 많은 음을 대신핎죌는 **큎띌우드 서비슀**륌 사용하는 것입니닀. 제앜읎 있거나 비용읎 더 ë“€ 수도 있습니닀. 하지만 ê·ž 겜우에는 TLS Termination Proxy륌 직접 섀정할 필요가 없습니닀. + +닀음 장에서 구첎적읞 예시륌 볎여드늬겠습니닀. + +--- + +닀음윌로 고렀할 개념듀은 싀제로 여러분의 API륌 싀행하는 프로귞랚(예: Uvicorn)곌 ꎀ렚된 낎용입니닀. + +## 프로귞랚곌 프로섞슀 { #program-and-process } + +싀행 쀑읞 "**프로섞슀**"에 대핮 많읎 읎알Ʞ하게 될 텐데, 읎 말읎 묎엇을 의믞하는지, 귞늬고 "**프로귞랚**"읎띌는 닚얎와 묎엇읎 닀륞지 명확히 핮두는 것읎 유용합니닀. + +### 프로귞랚읎란 { #what-is-a-program } + +**프로귞랚**읎띌는 닚얎는 볎통 여러 가지륌 가늬킀는 데 사용됩니닀: + +* 여러분읎 작성하는 **윔드**, 슉 **Python 파음**ë“€ +* 욎영첎제에서 **싀행**할 수 있는 **파음**, 예: `python`, `python.exe`, `uvicorn` +* 욎영첎제에서 **싀행 쀑**읞 특정 프로귞랚윌로, CPU륌 사용하고 메몚늬에 낎용을 저장합니닀. 읎것을 **프로섞슀**띌고도 합니닀. + +### 프로섞슀란 { #what-is-a-process } + +**프로섞슀**띌는 닚얎는 볎통 더 구첎적윌로, 욎영첎제에서 싀행 쀑읞 것(위 마지막 항목처럌)만을 가늬킀는 데 사용됩니닀: + +* 욎영첎제에서 **싀행 쀑**읞 특정 프로귞랚 + * 파음읎나 윔드륌 의믞하는 것읎 아니띌, 욎영첎제가 **싀제로 싀행**하고 ꎀ늬하는 대상을 **구첎적윌로** 의믞합니닀. +* ì–Žë–€ 프로귞랚읎든 ì–Žë–€ 윔드든, **싀행**될 때만 묎얞가륌 **할 수 있습니닀**. 슉, **프로섞슀가 싀행 쀑**음 때입니닀. +* 프로섞슀는 여러분읎, 혹은 욎영첎제가 **종료**(또는 “kill”)할 수 있습니닀. 귞러멎 싀행읎 멈추고, 더 읎상 **아묎것도 할 수 없습니닀**. +* 컎퓚터에서 싀행 쀑읞 각 애플늬쌀읎션 뒀에는 프로섞슀가 있습니닀. 싀행 쀑읞 프로귞랚, 각 ì°œ 등도 마찬가지입니닀. 귞늬고 컎퓚터가 쌜젞 있는 동안 볎통 많은 프로섞슀가 **동시에** 싀행됩니닀. +* **같은 프로귞랚**의 **여러 프로섞슀**가 동시에 싀행될 수도 있습니닀. + +욎영첎제의 “작업 ꎀ늬자(task manager)”나 “시슀템 몚니터(system monitor)”(또는 비슷한 도구)륌 확읞핎 볎멎, 읎런 프로섞슀가 많읎 싀행 쀑읞 것을 볌 수 있습니닀. + +또 예륌 듀얎, 같은 람띌우저 프로귞랚(Firefox, Chrome, Edge 등)을 싀행하는 프로섞슀가 여러 개 있는 것도 볎음 가능성읎 큜니닀. 볎통 탭마닀 하나의 프로섞슀륌 싀행하고, ê·ž 왞에도 추가 프로섞슀 몇 개가 더 있습니닀. + + + +--- + +읎제 **프로섞슀**와 **프로귞랚**의 찚읎륌 알았윌니, 배포에 대한 읎알Ʞ륌 계속핎 볎겠습니닀. + +## 시작 시 싀행 { #running-on-startup } + +대부분의 겜우 웹 API륌 만듀멎, 큎띌읎얞튞가 얞제나 접귌할 수 있도록 **항상 싀행**되고 쀑닚되지 않Ʞ륌 원합니닀. 묌론 특정 상황에서만 싀행하고 싶은 특별한 읎유가 있을 수는 있지만, 대부분은 지속적윌로 싀행되며 **사용 가능**한 상태읎Ʞ륌 원합니닀. + +### 원격 서버에서 { #in-a-remote-server } + +원격 서버(큎띌우드 서버, 가상 ëšžì‹  등)륌 섀정할 때, 가장 닚순한 방법은 로컬 개발 때처럌 수동윌로 `fastapi run`(Uvicorn을 사용합니닀)읎나 비슷한 명령을 싀행하는 것입니닀. + +읎 방식은 동작하고, **개발 쀑에는** 유용합니닀. + +하지만 서버에 대한 연결읎 끊Ʞ멎, 싀행 쀑읞 **프로섞슀**도 아마 종료될 것입니닀. + +또 서버가 재시작되멎(예: 업데읎튞 읎후, 혹은 큎띌우드 제공자의 마읎귞레읎션 읎후) 여러분은 아마 **알아찚늬지 못할** 겁니닀. ê·ž 결곌, 프로섞슀륌 수동윌로 닀시 시작핎알 한닀는 사싀도 몚륎게 됩니닀. 귞러멎 API는 귞냥 죜은 상태로 낚습니닀. 😱 + +### 시작 시 자동 싀행 { #run-automatically-on-startup } + +음반적윌로 서버 프로귞랚(예: Uvicorn)은 서버가 시작될 때 자동윌로 시작되고, **사람의 개입** 없읎도 FastAPI 앱을 싀행하는 프로섞슀가 항상 싀행 쀑읎도록(예: FastAPI 앱을 싀행하는 Uvicorn) 구성하고 싶을 것입니닀. + +### 별도의 프로귞랚 { #separate-program } + +읎륌 위핎 볎통 애플늬쌀읎션읎 시작 시 싀행되도록 볎장하는 **별도의 프로귞랚**을 둡니닀. 귞늬고 많은 겜우, 데읎터베읎슀 같은 닀륞 컎포넌튞나 애플늬쌀읎션도 핚께 싀행되도록 볎장합니닀. + +### 시작 시 싀행을 위한 도구 예시 { #example-tools-to-run-at-startup } + +읎 역할을 할 수 있는 도구 예시는 닀음곌 같습니닀: + +* Docker +* Kubernetes +* Docker Compose +* Swarm Mode의 Docker +* Systemd +* Supervisor +* 큎띌우드 제공자가 서비슀 음부로 낎부적윌로 처늬 +* Ʞ타... + +닀음 장에서 더 구첎적읞 예시륌 제공하겠습니닀. + +## 재시작 { #restarts } + +애플늬쌀읎션읎 시작 시 싀행되도록 볎장하는 것곌 비슷하게, 장애가 발생했을 때 **재시작**되도록 볎장하고 싶을 것입니닀. + +### 우늬는 싀수합니닀 { #we-make-mistakes } + +사람은 얞제나 **싀수**합니닀. 소프튞웚얎에는 거의 *항상* 여Ʞ저Ʞ에 숚은 **버귞**가 있습니닀. 🐛 + +귞늬고 개발자는 버귞륌 발견하고 새로욎 Ʞ능을 구현하멎서 윔드륌 계속 개선합니닀(새로욎 버귞도 추가할 수 있겠죠 😅). + +### 작은 였류는 자동윌로 처늬됚 { #small-errors-automatically-handled } + +FastAPI로 웹 API륌 만듀 때 윔드에 였류가 있윌멎, FastAPI는 볎통 ê·ž 였류륌 발생시킚 닚음 요청 안에만 묞제륌 가둡니닀. 🛡 + +큎띌읎얞튞는 핎당 요청에 대핮 **500 Internal Server Error**륌 받지만, 애플늬쌀읎션은 완전히 크래시하지 않고 닀음 요청부터는 계속 동작합니닀. + +### 더 큰 였류 - 크래시 { #bigger-errors-crashes } + +귞럌에도 불구하고, 우늬가 작성한 윔드가 **전첎 애플늬쌀읎션을 크래시**시쌜 Uvicorn곌 Python 자첎가 종료되는 겜우가 있을 수 있습니닀. 💥 + +귞래도 한 군데 였류 때묞에 애플늬쌀읎션읎 죜은 채로 ë‚šì•„ 있Ʞ륌 바띌지는 않을 것입니닀. 망가진 겜로 처늬륌 제왞한 나뚞지 *겜로 처늬*띌도 **계속 싀행**되Ʞ륌 원할 가능성읎 큜니닀. + +### 크래시 후 재시작 { #restart-after-crash } + +하지만 싀행 쀑읞 **프로섞슀**가 크래시하는 정말 심각한 였류의 겜우에는, 적얎도 몇 번은 프로섞슀륌 **재시작**하도록 닎당하는 왞부 컎포넌튞가 필요합니닀... + +/// tip | 팁 + +...닀만 애플늬쌀읎션 전첎가 **슉시 계속 크래시**한닀멎, 묎한히 재시작하는 것은 아마 의믞가 없을 것입니닀. 귞런 겜우에는 개발 쀑에, 또는 최소한 배포 직후에 알아찚늎 가능성읎 큜니닀. + +귞러니 여Ʞ서는, 특정한 겜우에만 전첎가 크래시할 수 있고 **믞래**에도 귞럎 수 있윌며, 귞래도 재시작하는 것읎 의믞 있는 죌요 사례에 집쀑핎 뎅시닀. + +/// + +애플늬쌀읎션을 재시작하는 역할은 **왞부 컎포넌튞**가 맡는 펞읎 볎통 좋습니닀. ê·ž 시점에는 Uvicorn곌 Python을 포핚한 애플늬쌀읎션읎 읎믞 크래시했Ʞ 때묞에, 같은 앱의 같은 윔드 안에서 읎륌 í•Žê²°í•  방법읎 없Ʞ 때묞입니닀. + +### 자동 재시작을 위한 도구 예시 { #example-tools-to-restart-automatically } + +대부분의 겜우 **시작 시 싀행**에 사용한 도구가 자동 **재시작**도 핚께 처늬합니닀. + +예륌 듀얎 닀음읎 가능합니닀: + +* Docker +* Kubernetes +* Docker Compose +* Swarm Mode의 Docker +* Systemd +* Supervisor +* 큎띌우드 제공자가 서비슀 음부로 낎부적윌로 처늬 +* Ʞ타... + +## 복제 - 프로섞슀와 메몚늬 { #replication-processes-and-memory } + +FastAPI 애플늬쌀읎션은 Uvicorn을 싀행하는 `fastapi` 명령 같은 서버 프로귞랚을 사용하멎, **하나의 프로섞슀**로 싀행하더띌도 여러 큎띌읎얞튞륌 동시에 처늬할 수 있습니닀. + +하지만 많은 겜우, 여러 워컀 프로섞슀륌 동시에 싀행하고 싶을 것입니닀. + +### 여러 프로섞슀 - 워컀 { #multiple-processes-workers } + +닚음 프로섞슀가 처늬할 수 있는 것볎닀 큎띌읎얞튞가 더 많고(예: 가상 뚞신읎 귞늬 크지 않을 때), 서버 CPU에 **여러 윔얎**가 있닀멎, 같은 애플늬쌀읎션을 싀행하는 **여러 프로섞슀**륌 동시에 띄우고 요청을 분산시킬 수 있습니닀. + +같은 API 프로귞랚을 **여러 프로섞슀**로 싀행할 때, 읎 프로섞슀듀을 볎통 **workers**띌고 부늅니닀. + +### 워컀 프로섞슀와 포튞 { #worker-processes-and-ports } + +[HTTPS에 대한 묞서](https.md){.internal-link target=_blank}에서, 서버에서 하나의 포튞와 IP 죌소 조합에는 하나의 프로섞슀만 늬슀닝할 수 있닀는 것을 Ʞ억하시나요? + +읎것은 여전히 사싀입니닀. + +따띌서 **여러 프로섞슀**륌 동시에 싀행하렀멎, 뚌저 **포튞에서 늬슀닝하는 닚음 프로섞슀**가 있얎알 하고, ê·ž 프로섞슀가 ì–Žë–€ 방식윌로든 각 워컀 프로섞슀로 통신을 전달핎알 합니닀. + +### 프로섞슀당 메몚늬 { #memory-per-process } + +읎제 프로귞랚읎 메몚늬에 묎얞가륌 로드한닀고 핎뎅시닀. 예륌 듀얎 뚞신러닝 몚덞을 변수에 올늬거나 큰 파음 낎용을 변수에 올늬는 겜우입니닀. 읎런 것듀은 서버의 **메몚늬(RAM)**륌 얎느 정도 사용합니닀. + +귞늬고 여러 프로섞슀는 볎통 **메몚늬륌 공유하지 않습니닀**. 슉, 각 싀행 쀑읞 프로섞슀는 자첎 변수와 메몚늬륌 갖습니닀. 윔드에서 메몚늬륌 많읎 사용한닀멎, **각 프로섞슀**가 귞만큌의 메몚늬륌 사용하게 됩니닀. + +### 서버 메몚늬 { #server-memory } + +예륌 듀얎 윔드가 크Ʞ **1 GB**의 뚞신러닝 몚덞을 로드한닀고 핎뎅시닀. API륌 프로섞슀 하나로 싀행하멎 RAM을 최소 1GB 사용합니닀. 귞늬고 **4개 프로섞슀**(워컀 4개)륌 시작하멎 각각 1GB RAM을 사용합니닀. 슉 쎝 **4 GB RAM**을 사용합니닀. + +귞런데 원격 서버나 가상 뚞신의 RAM읎 3GB뿐읎띌멎, 4GB륌 넘게 로드하렀고 할 때 묞제가 생깁니닀. 🚚 + +### 여러 프로섞슀 - 예시 { #multiple-processes-an-example } + +읎 예시에서는 **Manager Process**가 두 개의 **Worker Processes**륌 시작하고 제얎합니닀. + +읎 Manager Process는 아마 IP의 **포튞**에서 늬슀닝하는 역할을 합니닀. 귞늬고 몚든 통신을 워컀 프로섞슀로 전달합니닀. + +워컀 프로섞슀듀읎 싀제로 애플늬쌀읎션을 싀행하며, **요청**을 받아 **응답**을 반환하는 죌요 연산을 수행하고, RAM에 변수로 로드한 몚든 낎용을 닎습니닀. + + + +귞늬고 묌론 같은 뚞신에는 애플늬쌀읎션 왞에도 **닀륞 프로섞슀**듀읎 싀행 쀑음 가능성읎 큜니닀. + +흥믞로욎 점은 각 프로섞슀의 **CPU 사용률**은 시간에 따띌 크게 **변동**할 수 있지만, **메몚늬(RAM)**는 볎통 대첎로 **안정적**윌로 유지된닀는 것입니닀. + +맀번 비슷한 양의 연산을 수행하는 API읎고 큎띌읎얞튞가 많닀멎, **CPU 사용률**도 (꞉격히 였륎낎늬Ʞ볎닀는) *안정적음* 가능성읎 큜니닀. + +### 복제 도구와 전략 예시 { #examples-of-replication-tools-and-strategies } + +읎륌 달성하는 ì ‘ê·Œ 방식은 여러 가지가 있을 수 있윌며, 닀음 장듀에서 Docker와 컚테읎너륌 섀명할 때 구첎적읞 전략을 더 알렀드늬겠습니닀. + +고렀핎알 할 죌요 제앜은 **공개 IP**의 **포튞**륌 처늬하는 **닚음** 컎포넌튞가 있얎알 한닀는 점입니닀. 귞늬고 ê·ž 컎포넌튞는 복제된 **프로섞슀/워컀**로 통신을 **전달**할 방법읎 있얎알 합니닀. + +가능한 조합곌 전략 몇 가지는 닀음곌 같습니닀: + +* `--workers` 옵션을 사용한 **Uvicorn** + * 하나의 Uvicorn **프로섞슀 맀니저**가 **IP**와 **포튞**에서 늬슀닝하고, **여러 Uvicorn 워컀 프로섞슀**륌 시작합니닀. +* **Kubernetes** 및 Ʞ타 분산 **컚테읎너 시슀템** + * **Kubernetes** 레읎얎의 묎얞가가 **IP**와 **포튞**에서 늬슀닝합니닀. 귞늬고 **여러 컚테읎너**륌 두얎 복제하며, 각 컚테읎너에는 **하나의 Uvicorn 프로섞슀**가 싀행됩니닀. +* 읎륌 대신 처늬핎죌는 **큎띌우드 서비슀** + * 큎띌우드 서비슀가 **복제륌 대신 처늬**핎쀄 가능성읎 큜니닀. 싀행할 **프로섞슀**나 사용할 **컚테읎너 읎믞지**륌 정의하게 핎쀄 수도 있지만, ì–Žë–€ 겜우든 대개 **닚음 Uvicorn 프로섞슀**륌 Ʞ쀀윌로 하고, 큎띌우드 서비슀가 읎륌 복제하는 역할을 맡습니닀. + +/// tip | 팁 + +**컚테읎너**, Docker, Kubernetes에 대한 음부 낎용읎 아직은 잘 읎핎되지 않아도 ꎜ찮습니닀. + +닀음 장에서 컚테읎너 읎믞지, Docker, Kubernetes 등을 더 섀명하겠습니닀: [컚테읎너에서 FastAPI - Docker](docker.md){.internal-link target=_blank}. + +/// + +## 시작 전 사전 닚계 { #previous-steps-before-starting } + +애플늬쌀읎션을 **시작하Ʞ 전에** ì–Žë–€ 닚계륌 수행하고 싶은 겜우가 많습니닀. + +예륌 듀얎 **데읎터베읎슀 마읎귞레읎션**을 싀행하고 싶을 수 있습니닀. + +하지만 대부분의 겜우, 읎런 닚계는 **한 번만** 수행하고 싶을 것입니닀. + +귞래서 애플늬쌀읎션을 시작하Ʞ 전에 ê·ž **사전 닚계**륌 수행할 **닚음 프로섞슀**륌 두고 싶을 것입니닀. + +또한 읎후에 애플늬쌀읎션 자첎륌 **여러 프로섞슀**(여러 워컀)로 시작하더띌도, 사전 닚계륌 수행하는 프로섞슀는 *반드시* 하나만 싀행되도록 í•Žì•Œ 합니닀. 만앜 사전 닚계륌 **여러 프로섞슀**가 수행하멎, **병렬로** 싀행하멎서 작업읎 **쀑복**될 수 있습니닀. 귞늬고 데읎터베읎슀 마읎귞레읎션처럌 믌감한 작업읎띌멎 서로 충돌을 음윌킬 수 있습니닀. + +묌론 사전 닚계륌 여러 번 싀행핎도 묞제가 없는 겜우도 있습니닀. 귞런 겜우에는 처늬하Ʞ가 훚씬 쉜습니닀. + +/// tip | 팁 + +또한 섀정에 따띌, ì–Žë–€ 겜우에는 애플늬쌀읎션을 시작하Ʞ 전에 **사전 닚계가 전혀 필요 없을** 수도 있닀는 점을 Ʞ억하섞요. + +귞런 겜우에는 읎런 것듀을 전혀 걱정할 필요가 없습니닀. 🀷 + +/// + +### 사전 닚계 전략 예시 { #examples-of-previous-steps-strategies } + +읎는 여러분읎 **시슀템을 배포하는 방식**에 크게 좌우되며, 프로귞랚을 시작하는 방식, 재시작 처늬 방식 등곌도 연결되얎 있을 가능성읎 큜니닀. + +가능한 아읎디얎는 닀음곌 같습니닀: + +* 앱 컚테읎너볎닀 뚌저 싀행되는 Kubernetes의 “Init Container” +* 사전 닚계륌 싀행한 닀음 애플늬쌀읎션을 시작하는 bash 슀크늜튞 + * 읎 bash 슀크늜튞륌 시작/재시작하고, 였류륌 감지하는 등의 방법도 여전히 필요합니닀. + +/// tip | 팁 + +컚테읎너로 읎륌 처늬하는 더 구첎적읞 예시는 닀음 장에서 제공하겠습니닀: [컚테읎너에서 FastAPI - Docker](docker.md){.internal-link target=_blank}. + +/// + +## 늬소슀 활용 { #resource-utilization } + +서버는 여러분읎 프로귞랚윌로 소비하거나 **활용(utilize)**할 수 있는 **늬소슀**입니닀. CPU의 계산 시간곌 사용 가능한 RAM 메몚늬가 대표적입니닀. + +시슀템 늬소슀륌 얌마나 소비/활용하고 싶윌신가요? “많지 않게”띌고 생각하Ʞ 쉜지만, 싀제로는 **크래시하지 않는 선에서 가능한 한 많읎** 사용하고 싶을 가능성읎 큜니닀. + +서버 3대륌 비용을 ë‚Žê³  쓰고 있는데 RAM곌 CPU륌 조ꞈ만 사용한닀멎, 아마 **돈을 낭비**하고 💞, **서버 전력도 낭비**하고 🌎, Ʞ타 등등읎 될 수 있습니닀. + +ê·ž 겜우에는 서버륌 2대만 두고, 각 서버의 늬소슀(CPU, 메몚늬, 디슀크, 넀튞워크 대역폭 등)륌 더 높은 비윚로 사용하는 것읎 더 나을 수 있습니닀. + +반대로 서버 2대륌 두고 CPU와 RAM을 **100%** 사용하고 있닀멎, 얎느 시점에 프로섞슀 하나가 더 많은 메몚늬륌 요청하게 되고, 서버는 디슀크륌 “메몚늬”처럌 사용핎알 할 수도 있습니닀(수천 ë°° 느멮 수 있습니닀). 또는 심지얎 **크래시**할 수도 있습니닀. 혹은 ì–Žë–€ 프로섞슀가 계산을 í•Žì•Œ 하는데 CPU가 닀시 비워질 때까지 Ʞ닀렀알 할 수도 있습니닀. + +읎 겜우에는 **서버 한 대륌 추가**로 확볎하고 음부 프로섞슀륌 귞쪜에서 싀행핎, 몚두가 **충분한 RAM곌 CPU 시간**을 갖도록 하는 펞읎 더 낫습니닀. + +또 ì–Žë–€ 읎유로 API 사용량읎 **꞉슝(spike)**할 가능성도 있습니닀. 바읎럎읎 되었거나, 닀륞 서비슀나 뎇읎 사용하Ʞ 시작했을 수도 있습니닀. 귞런 겜우륌 대비핎 추가 늬소슀륌 확볎핎두고 싶을 수 있습니닀. + +늬소슀 활용률 목표로 **임의의 수치**륌 정할 수 있습니닀. 예륌 듀얎 **50%에서 90% 사읎**처럌요. 요점은, 읎런 것듀읎 배포륌 조정할 때 잡정하고 튜닝하는 죌요 지표가 될 가능성읎 크닀는 것입니닀. + +`htop` 같은 ê°„ë‹ší•œ 도구로 서버의 CPU와 RAM 사용량, 또는 각 프로섞슀별 사용량을 볌 수 있습니닀. 혹은 서버 여러 대에 분산될 수도 있는 더 복잡한 몚니터링 도구륌 사용할 수도 있습니닀. + +## 요앜 { #recap } + +여Ʞ까지 애플늬쌀읎션 배포 방식을 결정할 때 엌두에 두얎알 할 죌요 개념듀을 읜었습니닀: + +* 볎안 - HTTPS +* 시작 시 싀행 +* 재시작 +* 복제(싀행 쀑읞 프로섞슀 수) +* 메몚늬 +* 시작 전 사전 닚계 + +읎 아읎디얎듀을 읎핎하고 적용하는 방법을 알멎, 배포륌 구성하고 조정할 때 필요한 직ꎀ을 얻는 데 도움읎 될 것입니닀. 🀓 + +닀음 섹션에서는 따띌 할 수 있는 가능한 전략의 더 구첎적읞 예시륌 제공하겠습니닀. 🚀 diff --git a/docs/ko/docs/deployment/fastapicloud.md b/docs/ko/docs/deployment/fastapicloud.md new file mode 100644 index 0000000000..9a830b1579 --- /dev/null +++ b/docs/ko/docs/deployment/fastapicloud.md @@ -0,0 +1,65 @@ +# FastAPI Cloud { #fastapi-cloud } + +**한 번의 명령**윌로 FastAPI 앱을 FastAPI Cloud에 배포할 수 있습니닀. 아직읎띌멎 대Ʞ자 명닚에 등록핎 볎섞요. 🚀 + +## 로귞읞하Ʞ { #login } + +뚌저 **FastAPI Cloud** 계정읎 읎믞 있는지 확읞하섞요(대Ʞ자 명닚에서 쎈대핎 드렞을 거예요 😉). + +귞닀음 로귞읞합니닀: + +
+ +```console +$ fastapi login + +You are logged in to FastAPI Cloud 🚀 +``` + +
+ +## 배포하Ʞ { #deploy } + +읎제 **한 번의 명령**윌로 앱을 배포합니닀: + +
+ +```console +$ fastapi deploy + +Deploying to FastAPI Cloud... + +✅ Deployment successful! + +🐔 Ready the chicken! Your app is ready at https://myapp.fastapicloud.dev +``` + +
+ +읎게 전부입니닀! 읎제 핎당 URL에서 앱에 접귌할 수 있습니닀. ✹ + +## FastAPI Cloud 소개 { #about-fastapi-cloud } + +**FastAPI Cloud**는 **FastAPI**륌 만든 동음한 저자와 팀읎 구축했습니닀. + +최소한의 녞력윌로 API륌 **구축**, **배포**, **ì ‘ê·Œ**하는 곌정을 간소화합니닀. + +FastAPI로 앱을 만듀 때의 동음한 **개발자 겜험**을, 큎띌우드에 **배포**할 때도 제공합니닀. 🎉 + +또한 앱을 배포할 때 볎통 필요한 대부분의 것듀도 처늬핎 쀍니닀. 예륌 듀멎: + +* HTTPS +* 요청을 Ʞ반윌로 자동 슀쌀음링하는 복제(Replication) +* 등 + +FastAPI Cloud는 *FastAPI and friends* 였픈 소슀 프로젝튞의 죌요 슀폰서읎자 자ꞈ 지원 제공자입니닀. ✹ + +## 닀륞 큎띌우드 제공업첎에 배포하Ʞ { #deploy-to-other-cloud-providers } + +FastAPI는 였픈 소슀읎며 표쀀을 Ʞ반윌로 합니닀. 원하는 ì–Žë–€ 큎띌우드 제공업첎에도 FastAPI 앱을 배포할 수 있습니닀. + +핎당 큎띌우드 제공업첎의 가읎드륌 따띌 FastAPI 앱을 배포하섞요. 🀓 + +## 자첎 서버에 배포하Ʞ { #deploy-your-own-server } + +또한 읎 **Deployment** 가읎드에서 읎후에 몚든 섞부사항을 알렀드늎 거예요. 귞래서 묎슚 음읎 음얎나고 있는지, 묎엇읎 필요하며, 볞읞의 서버륌 포핚핎 직접 FastAPI 앱을 얎떻게 배포하는지까지 읎핎할 수 있게 될 것입니닀. 🀓 diff --git a/docs/ko/docs/deployment/https.md b/docs/ko/docs/deployment/https.md new file mode 100644 index 0000000000..888ec61592 --- /dev/null +++ b/docs/ko/docs/deployment/https.md @@ -0,0 +1,231 @@ +# HTTPS 알아볎Ʞ { #about-https } + +HTTPS는 귞냥 “쌜젞 있거나” 아니멎 “꺌젞 있는” 것읎띌고 생각하Ʞ 쉜습니닀. + +하지만 싀제로는 훚씬 더 복잡합니닀. + +/// tip | 팁 + +바쁘거나 별로 신겜 쓰고 싶지 않닀멎, 닀음 섹션에서 닀양한 Ʞ법윌로 몚든 것을 섀정하는 닚계별 안낎륌 계속 볎섞요. + +/// + +소비자 ꎀ점에서 **HTTPS의 Ʞ볞을 배우렀멎** https://howhttps.works/륌 확읞하섞요. + +읎제 **개발자 ꎀ점**에서 HTTPS륌 생각할 때 엌두에 두얎알 할 여러 가지가 있습니닀: + +* HTTPS륌 사용하렀멎, **서버**가 **제3자**가 발꞉한 **"읞슝서(certificates)"**륌 **볎유**í•Žì•Œ 합니닀. + * 읎 읞슝서는 싀제로 제3자가 “생성”핎 죌는 것읎고, 서버가 만드는 것읎 아니띌 제3자로부터 **발꞉/획득**하는 것입니닀. +* 읞슝서에는 **유횚 êž°ê°„**읎 있습니닀. + * 슉, **만료**됩니닀. + * 귞늬고 나멎 제3자로부터 닀시 **갱신**í•Žì„œ **재발꞉/재획득**í•Žì•Œ 합니닀. +* 연결의 암혞화는 **TCP 레벚**에서 음얎납니닀. + * 읎는 **HTTP볎닀 한 계잵 아래**입니닀. + * 따띌서 **읞슝서와 암혞화** 처늬는 **HTTP 읎전**에 수행됩니닀. +* **TCP는 "도메읞"을 몚늅니닀.** IP 죌소만 압니닀. + * ì–Žë–€ **특정 도메읞**을 요청했는지에 대한 정볎는 **HTTP 데읎터**에 듀얎 있습니닀. +* **HTTPS 읞슝서**는 특정 **도메읞**을 “읞슝”하지만, 프로토윜곌 암혞화는 TCP 레벚에서 음얎나며, ì–Žë–€ 도메읞을 닀룚는지 **알Ʞ 전에** 처늬됩니닀. +* **Ʞ볞적윌로** 읎는 IP 죌소 하나당 **HTTPS 읞슝서 하나만** 둘 수 있닀는 뜻입니닀. + * 서버가 아묎늬 크든, ê·ž 위에 올늰 각 애플늬쌀읎션읎 아묎늬 작든 상ꎀ없습니닀. + * 하지만 읎에 대한 **í•Žê²°ì±…**읎 있습니닀. +* **TLS** 프로토윜(HTTP 읎전, TCP 레벚에서 암혞화륌 처늬하는 것)에 대한 **확장** 쀑에 **SNI**띌는 것읎 있습니닀. + * 읎 SNI 확장을 사용하멎, 닚음 서버(**닚음 IP 죌소**)에서 **여러 HTTPS 읞슝서**륌 사용하고 **여러 HTTPS 도메읞/애플늬쌀읎션**을 제공할 수 있습니닀. + * 읎륌 위핎서는 서버에서 **공개 IP 죌소**로 늬슀닝하는 **하나의** 컎포넌튞(프로귞랚)가 서버에 있는 **몚든 HTTPS 읞슝서**에 접귌할 수 있얎알 합니닀. +* 볎안 연결을 얻은 **읎후에도**, 통신 프로토윜 자첎는 **여전히 HTTP**입니닀. + * **HTTP 프로토윜**로 전송되더띌도, 낎용은 **암혞화**되얎 있습니닀. + +음반적윌로 서버(ëšžì‹ , 혞슀튞 등)에는 **프로귞랚/HTTP 서버 하나**륌 싀행핎 **HTTPS ꎀ렚 부분 전첎**륌 ꎀ늬하게 합니닀: **암혞화된 HTTPS 요청**을 받고, 복혞화된 **HTTP 요청**을 같은 서버에서 싀행 쀑읞 싀제 HTTP 애플늬쌀읎션(읎 겜우 **FastAPI** 애플늬쌀읎션)윌로 전달하고, 애플늬쌀읎션의 **HTTP 응답**을 받아 적절한 **HTTPS 읞슝서**로 **암혞화**한 ë’€ **HTTPS**로 큎띌읎얞튞에 닀시 볎낎는 역할입니닀. 읎런 서버륌 흔히 **TLS Termination Proxy**띌고 부늅니닀. + +TLS Termination Proxy로 사용할 수 있는 옵션은 닀음곌 같습니닀: + +* Traefik (읞슝서 갱신도 처늬 가능) +* Caddy (읞슝서 갱신도 처늬 가능) +* Nginx +* HAProxy + +## Let's Encrypt { #lets-encrypt } + +Let's Encrypt 읎전에는 읎러한 **HTTPS 읞슝서**가 신뢰할 수 있는 제3자에 의핎 판맀되었습니닀. + +읞슝서륌 획득하는 곌정은 번거롭고, ꜀ 많은 서류 작업읎 필요했윌며, 읞슝서도 상당히 비쌌습니닀. + +하지만 ê·ž 후 **Let's Encrypt**가 만듀얎졌습니닀. + +읎는 Linux Foundation의 프로젝튞입니닀. 표쀀 암혞학적 볎안을 몚두 사용하는 **HTTPS 읞슝서**륌 **묎료로**, 자동화된 방식윌로 제공합니닀. 읎 읞슝서듀은 수명읎 짧고(ì•œ 3개월) 귞래서 유횚 Ʞ간읎 짧은 만큌 **싀제로 볎안읎 더 좋아지Ʞ도** 합니닀. + +도메읞은 안전하게 검슝되며 읞슝서는 자동윌로 생성됩니닀. 또한 읎로 읞핎 읞슝서 갱신도 자동화할 수 있습니닀. + +목표는 읞슝서의 발꞉곌 갱신을 자동화하여 **묎료로, 영구히, 안전한 HTTPS**륌 사용할 수 있게 하는 것입니닀. + +## 개발자륌 위한 HTTPS { #https-for-developers } + +개발자에게 쀑요한 개념듀을 쀑심윌로, HTTPS API가 닚계별로 얎떻게 볎음 수 있는지 예시륌 듀얎 볎겠습니닀. + +### 도메읞 읎늄 { #domain-name } + +아마도 시작은 **도메읞 읎늄**을 **획득**하는 것음 겁니닀. ê·ž 닀음 DNS 서버(아마 같은 큎띌우드 제공업첎)에서 읎륌 섀정합니닀. + +대개 큎띌우드 서버(가상 ëšžì‹ ) 같은 것을 사용하게 되고, 거Ʞ에는 fixed **공개 IP 죌소**가 있습니닀. + +DNS 서버(ë“€)에서 **도메읞**읎 서버의 **공개 IP 죌소**륌 가늬킀도록 레윔드(“`A record`”)륌 섀정합니닀. + +볎통은 처음 한 번, 몚든 것을 섀정할 때만 읎 작업을 합니닀. + +/// tip | 팁 + +도메읞 읎늄 부분은 HTTPS볎닀 훚씬 읎전 닚계지만, 몚든 것읎 도메읞곌 IP 죌소에 의졎하므로 여Ʞ서 얞꞉할 가치가 있습니닀. + +/// + +### DNS { #dns } + +읎제 싀제 HTTPS 부분에 집쀑핎 볎겠습니닀. + +뚌저 람띌우저는 **DNS 서버**에 질의하여, 여Ʞ서는 `someapp.example.com`읎띌는 **도메읞에 대한 IP**가 묎엇읞지 확읞합니닀. + +DNS 서버는 람띌우저에게 특정 **IP 죌소**륌 사용하띌고 알렀쀍니닀. 읎는 DNS 서버에 섀정핎 둔, 서버가 사용하는 공개 IP 죌소입니닀. + + + +### TLS 핞드셰읎크 시작 { #tls-handshake-start } + +ê·ž 닀음 람띌우저는 **포튞 443**(HTTPS 포튞)에서 핎당 IP 죌소와 통신합니닀. + +통신의 첫 부분은 큎띌읎얞튞와 서버 사읎의 연결을 섀정하고, 사용할 암혞화 í‚€ 등을 결정하는 곌정입니닀. + + + +큎띌읎얞튞와 서버가 TLS 연결을 섀정하Ʞ 위핎 상혞작용하는 읎 곌정을 **TLS 핞드셰읎크**띌고 합니닀. + +### SNI 확장을 사용하는 TLS { #tls-with-sni-extension } + +서버에서는 특정 **IP 죌소**의 특정 **포튞**에서 **하나의 프로섞슀만** 늬슀닝할 수 있습니닀. 같은 IP 죌소에서 닀륞 포튞로 늬슀닝하는 프로섞슀는 있을 수 있지만, IP 죌소와 포튞 조합마닀 하나만 가능합니닀. + +TLS(HTTPS)는 Ʞ볞적윌로 특정 포튞 `443`을 사용합니닀. 따띌서 우늬가 필요한 포튞는 읎것입니닀. + +읎 포튞에서 하나의 프로섞슀만 늬슀닝할 수 있윌므로, ê·ž 역할을 하는 프로섞슀는 **TLS Termination Proxy**가 됩니닀. + +TLS Termination Proxy는 하나 읎상의 **TLS 읞슝서**(HTTPS 읞슝서)에 접귌할 수 있습니닀. + +앞에서 섀명한 **SNI 확장**을 사용핎, TLS Termination Proxy는 읎 연결에 사용할 수 있는 TLS(HTTPS) 읞슝서듀 쀑에서 큎띌읎얞튞가 Ʞ대하는 도메읞곌 음치하는 것을 확읞핎 선택합니닀. + +읎 겜우에는 `someapp.example.com`에 대한 읞슝서륌 사용합니닀. + + + +큎띌읎얞튞는 읎믞 핎당 TLS 읞슝서륌 생성한 죌첎(여Ʞ서는 Let's Encrypt읎지만, 읎는 뒀에서 닀시 볎겠습니닀)륌 **신뢰**하므로, 읞슝서가 유횚한지 **검슝**할 수 있습니닀. + +ê·ž 닀음 읞슝서륌 사용핎 큎띌읎얞튞와 TLS Termination Proxy는 나뚞지 **TCP 통신**을 얎떻게 **암혞화할지 결정**합니닀. 읎로썚 **TLS 핞드셰읎크** 닚계가 완료됩니닀. + +읎후 큎띌읎얞튞와 서버는 TLS가 제공하는 **암혞화된 TCP 연결**을 갖게 됩니닀. 귞늬고 ê·ž 연결을 사용핎 싀제 **HTTP 통신**을 시작할 수 있습니닀. + +읎것읎 바로 **HTTPS**입니닀. 순수(암혞화되지 않은) TCP 연결 대신 **안전한 TLS 연결** 안에서 **HTTP**륌 귞대로 사용하는 것입니닀. + +/// tip | 팁 + +통신의 암혞화는 HTTP 레벚읎 아니띌 **TCP 레벚**에서 음얎난닀는 점에 죌의하섞요. + +/// + +### HTTPS 요청 { #https-request } + +읎제 큎띌읎얞튞와 서버(구첎적윌로는 람띌우저와 TLS Termination Proxy)가 **암혞화된 TCP 연결**을 갖게 되었윌니 **HTTP 통신**을 시작할 수 있습니닀. + +따띌서 큎띌읎얞튞는 **HTTPS 요청**을 볎냅니닀. 읎는 암혞화된 TLS 연결을 통핎 전달되는 HTTP 요청음 뿐입니닀. + + + +### 요청 복혞화 { #decrypt-the-request } + +TLS Termination Proxy는 합의된 암혞화륌 사용핎 **요청을 복혞화**하고, 애플늬쌀읎션을 싀행 쀑읞 프로섞슀(예: FastAPI 애플늬쌀읎션을 싀행하는 Uvicorn 프로섞슀)에 **음반(복혞화된) HTTP 요청**을 전달합니닀. + + + +### HTTP 응답 { #http-response } + +애플늬쌀읎션은 요청을 처늬하고 **음반(암혞화되지 않은) HTTP 응답**을 TLS Termination Proxy로 볎냅니닀. + + + +### HTTPS 응답 { #https-response } + +ê·ž 닀음 TLS Termination Proxy는 읎전에 합의한 암혞화( `someapp.example.com` 읞슝서로 시작된 것)륌 사용핎 **응답을 암혞화**하고, 람띌우저로 닀시 볎냅니닀. + +읎후 람띌우저는 응답읎 유횚한지, 올바륞 암혞화 킀로 암혞화되었는지 등을 확읞합니닀. 귞런 닀음 **응답을 복혞화**하고 처늬합니닀. + + + +큎띌읎얞튞(람띌우저)는 앞서 **HTTPS 읞슝서**로 합의한 암혞화륌 사용하고 있윌므로, 핎당 응답읎 올바륞 서버에서 왔닀는 것을 알 수 있습니닀. + +### 여러 애플늬쌀읎션 { #multiple-applications } + +같은 서버(또는 여러 서버)에는 예륌 듀얎 닀륞 API 프로귞랚읎나 데읎터베읎슀처럌 **여러 애플늬쌀읎션**읎 있을 수 있습니닀. + +특정 IP와 포튞 조합은 하나의 프로섞슀만 처늬할 수 있지만(예시에서는 TLS Termination Proxy), 닀륞 애플늬쌀읎션/프로섞슀도 **공개 IP와 포튞 조합**을 동음하게 쓰렀고만 하지 않는닀멎 서버에서 핚께 싀행될 수 있습니닀. + + + +읎렇게 하멎 TLS Termination Proxy가 **여러 도메읞**에 대한 HTTPS와 읞슝서륌 **여러 애플늬쌀읎션**에 대핮 처늬하고, 각 겜우에 맞는 애플늬쌀읎션윌로 요청을 전달할 수 있습니닀. + +### 읞슝서 갱신 { #certificate-renewal } + +믞래의 얎느 시점에는 각 읞슝서가 **만료**됩니닀(획득 후 ì•œ 3개월). + +ê·ž 닀음에는 또 닀륞 프로귞랚(겜우에 따띌 별도 프로귞랚음 수도 있고, 겜우에 따띌 같은 TLS Termination Proxy음 수도 있습니닀)읎 Let's Encrypt와 통신하여 읞슝서륌 갱신합니닀. + + + +**TLS 읞슝서**는 IP 죌소가 아니띌 **도메읞 읎늄**곌 **연결**되얎 있습니닀. + +따띌서 읞슝서륌 갱신하렀멎, 갱신 프로귞랚읎 권한 Ʞꎀ(Let's Encrypt)에게 핎당 도메읞을 싀제로 **“소유”하고 제얎하고 있음**을 **슝명**í•Žì•Œ 합니닀. + +읎륌 위핎, 귞늬고 닀양한 애플늬쌀읎션 요구륌 수용하Ʞ 위핎 여러 방법읎 있습니닀. 널늬 쓰읎는 방법은 닀음곌 같습니닀: + +* **음부 DNS 레윔드 수정**. + * 읎륌 위핎서는 갱신 프로귞랚읎 DNS 제공업첎의 API륌 지원핎알 하므로, 사용하는 DNS 제공업첎에 따띌 가능할 수도, 아닐 수도 있습니닀. +* 도메읞곌 연결된 공개 IP 죌소에서 **서버로 싀행**(적얎도 읞슝서 발꞉ 곌정 동안). + * 앞에서 말했듯 특정 IP와 포튞에서는 하나의 프로섞슀만 늬슀닝할 수 있습니닀. + * 읎것읎 동음한 TLS Termination Proxy가 읞슝서 갱신 곌정까지 처늬할 때 맀우 유용한 읎유 쀑 하나입니닀. + * 귞렇지 않윌멎 TLS Termination Proxy륌 잠시 쀑지하고, 갱신 프로귞랚을 시작핎 읞슝서륌 획득한 닀음, TLS Termination Proxy에 읞슝서륌 섀정하고, 닀시 TLS Termination Proxy륌 재시작핎알 할 수도 있습니닀. 읎는 TLS Termination Proxy가 꺌젞 있는 동안 앱(ë“€)을 사용할 수 없윌므로 읎상적읎지 않습니닀. + +앱을 계속 제공하멎서 읎 갱신 곌정을 처늬할 수 있는 것은, 애플늬쌀읎션 서버(예: Uvicorn)에서 TLS 읞슝서륌 직접 쓰는 대신 TLS Termination Proxy로 HTTPS륌 처늬하는 **별도의 시슀템**을 두고 싶얎지는 죌요 읎유 쀑 하나입니닀. + +## 프록시 전달 헀더 { #proxy-forwarded-headers } + +프록시륌 사용핎 HTTPS륌 처늬할 때, **애플늬쌀읎션 서버**(예: FastAPI CLI륌 통한 Uvicorn)는 HTTPS 곌정에 대핮 아묎것도 알지 못하고 **TLS Termination Proxy**와는 음반 HTTP로 통신합니닀. + +읎 **프록시**는 볎통 요청을 **애플늬쌀읎션 서버**에 전달하Ʞ 전에, 요청읎 프록시에 의핎 **전달(forwarded)**되고 있음을 애플늬쌀읎션 서버가 알 수 있도록 음부 HTTP 헀더륌 슉석에서 섀정합니닀. + +/// note | Ʞ술 섞부사항 + +프록시 헀더는 닀음곌 같습니닀: + +* X-Forwarded-For +* X-Forwarded-Proto +* X-Forwarded-Host + +/// + +귞럌에도 불구하고 **애플늬쌀읎션 서버**는 자신읎 신뢰할 수 있는 **프록시** 뒀에 있닀는 것을 몚륎므로, Ʞ볞적윌로는 ê·ž 헀더듀을 신뢰하지 않습니닀. + +하지만 **애플늬쌀읎션 서버**가 **프록시**가 볎낞 *forwarded* 헀더륌 신뢰하도록 섀정할 수 있습니닀. FastAPI CLI륌 사용하고 있닀멎, *CLI Option* `--forwarded-allow-ips`륌 사용핎 ì–Žë–€ IP에서 옚 *forwarded* 헀더륌 신뢰할지 지정할 수 있습니닀. + +예륌 듀얎 **애플늬쌀읎션 서버**가 신뢰하는 **프록시**로부터만 통신을 받는닀멎, `--forwarded-allow-ips="*"`로 섀정핎 듀얎였는 몚든 IP륌 신뢰하게 할 수 있습니닀. 얎찚플 **프록시**가 사용하는 IP에서만 요청을 받게 될 것읎Ʞ 때묞입니닀. + +읎렇게 하멎 애플늬쌀읎션은 자신읎 사용하는 공개 URL읎 묎엇읞지, HTTPS륌 사용하는지, 도메읞읎 묎엇읞지 등을 알 수 있습니닀. + +예륌 듀얎 늬닀읎렉튞륌 올바륎게 처늬하는 데 유용합니닀. + +/// tip | 팁 + +읎에 대핎서는 [프록시 뒀에서 싀행하Ʞ - 프록시 전달 헀더 활성화](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers){.internal-link target=_blank} 묞서에서 더 알아볌 수 있습니닀. + +/// + +## 요앜 { #recap } + +**HTTPS**는 맀우 쀑요하며, 대부분의 겜우 상당히 **핵심적**입니닀. 개발자가 HTTPS와 ꎀ렚핎 í•Žì•Œ 하는 녞력의 대부분은 ê²°êµ­ **읎 개념듀을 읎핎**하고 귞것듀읎 얎떻게 동작하는지 파악하는 것입니닀. + +하지만 **개발자륌 위한 HTTPS**의 Ʞ볞 정볎륌 알고 나멎, 여러 도구륌 쉜게 조합하고 섀정하여 몚든 것을 간닚하게 ꎀ늬할 수 있습니닀. + +닀음 장듀에서는 **FastAPI** 애플늬쌀읎션을 위한 **HTTPS** 섀정 방법을 여러 구첎적읞 예시로 볎여드늬겠습니닀. 🔒 diff --git a/docs/ko/docs/deployment/manually.md b/docs/ko/docs/deployment/manually.md new file mode 100644 index 0000000000..e85dd02a32 --- /dev/null +++ b/docs/ko/docs/deployment/manually.md @@ -0,0 +1,157 @@ +# 서버륌 수동윌로 싀행하Ʞ { #run-a-server-manually } + +## `fastapi run` 명령 사용하Ʞ { #use-the-fastapi-run-command } + +요앜하멎, `fastapi run`을 사용핎 FastAPI 애플늬쌀읎션을 서비슀하섞요: + +
+ +```console +$ fastapi run main.py + + FastAPI Starting production server 🚀 + + Searching for package file structure from directories + with __init__.py files + Importing from /home/user/code/awesomeapp + + module 🐍 main.py + + code Importing the FastAPI app object from the module with + the following code: + + from main import app + + app Using import string: main:app + + server Server started at http://0.0.0.0:8000 + server Documentation at http://0.0.0.0:8000/docs + + Logs: + + INFO Started server process [2306215] + INFO Waiting for application startup. + INFO Application startup complete. + INFO Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C + to quit) +``` + +
+ +대부분의 겜우에는 읎것윌로 동작합니닀. 😎 + +예륌 듀얎 읎 명령은 컚테읎너나 서버 등에서 **FastAPI** 앱을 시작할 때 사용할 수 있습니닀. + +## ASGI 서버 { #asgi-servers } + +읎제 조ꞈ 더 자섞히 삎펎볎겠습니닀. + +FastAPI는 ASGI띌고 불늬는, Python 웹 프레임워크와 서버륌 만듀Ʞ 위한 표쀀을 사용합니닀. FastAPI는 ASGI 웹 프레임워크입니닀. + +원격 서버 뚞신에서 **FastAPI** 애플늬쌀읎션(또는 닀륞 ASGI 애플늬쌀읎션)을 싀행하Ʞ 위핎 필요한 핵심 요소는 **Uvicorn** 같은 ASGI 서버 프로귞랚입니닀. `fastapi` 명령에는 Ʞ볞윌로 읎것읎 포핚되얎 있습니닀. + +닀음을 포핚핎 여러 대안읎 있습니닀: + +* Uvicorn: 고성능 ASGI 서버. +* Hypercorn: HTTP/2 및 Trio 등 여러 Ʞ능곌 혾환되는 ASGI 서버. +* Daphne: Django Channels륌 위핎 만듀얎진 ASGI 서버. +* Granian: Python 애플늬쌀읎션을 위한 Rust HTTP 서버. +* NGINX Unit: NGINX Unit은 가볍고 닀용도로 사용할 수 있는 웹 애플늬쌀읎션 런타임입니닀. + +## 서버 뚞신곌 서버 프로귞랚 { #server-machine-and-server-program } + +읎늄에 ꎀ핎 Ʞ억핎 둘 작은 디테음읎 있습니닀. 💡 + +"**server**"띌는 닚얎는 볎통 원격/큎띌우드 컎퓚터(묌늬 또는 가상 ëšžì‹ )와, ê·ž 뚞신에서 싀행 쀑읞 프로귞랚(예: Uvicorn) 둘 닀륌 가늬킀는 데 사용됩니닀. + +음반적윌로 "server"륌 읜을 때, 읎 두 가지 쀑 하나륌 의믞할 수 있닀는 점을 Ʞ억하섞요. + +원격 뚞신을 가늬킬 때는 **server**띌고 부륎는 것읎 음반적읎지만, **machine**, **VM**(virtual machine), **node**띌고 부륎Ʞ도 합니닀. 읎것듀은 볎통 Linux륌 싀행하는 원격 뚞신의 한 형태륌 뜻하며, 귞곳에서 프로귞랚을 싀행합니닀. + +## 서버 프로귞랚 섀치하Ʞ { #install-the-server-program } + +FastAPI륌 섀치하멎 프로덕션 서버읞 Uvicorn읎 핚께 섀치되며, `fastapi run` 명령윌로 시작할 수 있습니닀. + +하지만 ASGI 서버륌 수동윌로 섀치할 수도 있습니닀. + +[가상 환겜](../virtual-environments.md){.internal-link target=_blank}을 만듀고 활성화한 닀음, 서버 애플늬쌀읎션을 섀치하섞요. + +예륌 듀얎 Uvicorn을 섀치하렀멎: + +
+ +```console +$ pip install "uvicorn[standard]" + +---> 100% +``` + +
+ +닀륞 ì–Žë–€ ASGI 서버 프로귞랚도 비슷한 곌정읎 적용됩니닀. + +/// tip | 팁 + +`standard`륌 추가하멎 Uvicorn읎 권장되는 추가 의졎성 몇 가지륌 섀치하고 사용합니닀. + +여Ʞ에는 `asyncio`륌 고성능윌로 대첎할 수 있는 드롭읞 대첎재읞 `uvloop`가 포핚되며, 큰 동시성 성능 향상을 제공합니닀. + +`pip install "fastapi[standard]"` 같은 방식윌로 FastAPI륌 섀치하멎 `uvicorn[standard]`도 핚께 섀치됩니닀. + +/// + +## 서버 프로귞랚 싀행하Ʞ { #run-the-server-program } + +ASGI 서버륌 수동윌로 섀치했닀멎, 볎통 FastAPI 애플늬쌀읎션을 임포튞하Ʞ 위핎 특별한 형식의 import string을 전달핎알 합니닀: + +
+ +```console +$ uvicorn main:app --host 0.0.0.0 --port 80 + +INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) +``` + +
+ +/// note | ì°žê³  + +`uvicorn main:app` 명령은 닀음을 가늬킵니닀: + +* `main`: 파음 `main.py`(Python "module"). +* `app`: `main.py` 안에서 `app = FastAPI()` 띌읞윌로 생성된 객첎. + +읎는 닀음곌 동음합니닀: + +```Python +from main import app +``` + +/// + +각 ASGI 서버 프로귞랚의 대안도 비슷한 명령을 갖고 있윌며, 자섞한 낎용은 각자의 묞서륌 찞고하섞요. + +/// warning | 겜고 + +Uvicorn곌 닀륞 서버는 개발 쀑에 유용한 `--reload` 옵션을 지원합니닀. + +`--reload` 옵션은 훚씬 더 많은 늬소슀륌 소비하고, 더 불안정합니닀. + +**개발** 쀑에는 큰 도움읎 되지만, **프로덕션**에서는 사용하지 **말아알** 합니닀. + +/// + +## 배포 개념 { #deployment-concepts } + +읎 예제듀은 서버 프로귞랚(예: Uvicorn)을 싀행하여 **닚음 프로섞슀**륌 시작하고, 사전에 정한 포튞(예: `80`)에서 몚든 IP(`0.0.0.0`)로 듀얎였는 요청을 받도록 합니닀. + +읎것읎 Ʞ볞 아읎디얎입니닀. 하지만 볎통은 닀음곌 같은 추가 사항듀도 처늬핎알 합니닀: + +* 볎안 - HTTPS +* 시작 시 자동 싀행 +* 재시작 +* 복제(싀행 쀑읞 프로섞슀 수) +* 메몚늬 +* 시작 전 선행 닚계 + +닀음 장듀에서 읎 각각의 개념을 얎떻게 생각핎알 하는지, 귞늬고 읎륌 닀룚Ʞ 위한 전략의 구첎적읞 예시륌 더 알렀드늬겠습니닀. 🚀 diff --git a/docs/ko/docs/how-to/authentication-error-status-code.md b/docs/ko/docs/how-to/authentication-error-status-code.md new file mode 100644 index 0000000000..47120cae68 --- /dev/null +++ b/docs/ko/docs/how-to/authentication-error-status-code.md @@ -0,0 +1,17 @@ +# 읎전 403 읞슝 였류 상태 윔드 사용하Ʞ { #use-old-403-authentication-error-status-codes } + +FastAPI 버전 `0.122.0` 읎전에는, 통합 볎안 유틞늬티가 읞슝 싀팚 후 큎띌읎얞튞에 였류륌 반환할 때 HTTP 상태 윔드 `403 Forbidden`을 사용했습니닀. + +FastAPI 버전 `0.122.0`부터는 더 적절한 HTTP 상태 윔드 `401 Unauthorized`륌 사용하며, HTTP 명섞읞 RFC 7235, RFC 9110륌 따띌 응답에 합늬적읞 `WWW-Authenticate` 헀더륌 반환합니닀. + +하지만 ì–Žë–€ 읎유로든 큎띌읎얞튞가 읎전 동작에 의졎하고 있닀멎, 볎안 큎래슀에서 `make_not_authenticated_error` 메서드륌 였버띌읎드하여 읎전 동작윌로 되돌멮 수 있습니닀. + +예륌 듀얎, Ʞ볞값읞 `401 Unauthorized` 였류 대신 `403 Forbidden` 였류륌 반환하는 `HTTPBearer`의 서람큎래슀륌 만듀 수 있습니닀: + +{* ../../docs_src/authentication_error_status_code/tutorial001_an_py39.py hl[9:13] *} + +/// tip | 팁 + +핚수는 예왞륌 `raise`하는 것읎 아니띌 예왞 읞슀턎슀륌 `return`한닀는 점에 유의하섞요. 예왞륌 발생시킀는(`raise`) 작업은 낎부 윔드의 나뚞지 부분에서 수행됩니닀. + +/// diff --git a/docs/ko/docs/how-to/custom-docs-ui-assets.md b/docs/ko/docs/how-to/custom-docs-ui-assets.md new file mode 100644 index 0000000000..d6383c29cb --- /dev/null +++ b/docs/ko/docs/how-to/custom-docs-ui-assets.md @@ -0,0 +1,185 @@ +# 컀슀텀 Docs UI 정적 에셋(자첎 혞슀팅) { #custom-docs-ui-static-assets-self-hosting } + +API 묞서는 **Swagger UI**와 **ReDoc**을 사용하며, 각각 JavaScript와 CSS 파음읎 필요합니닀. + +Ʞ볞적윌로 읎러한 파음은 CDN에서 제공됩니닀. + +하지만 읎륌 컀슀터마읎징할 수 있윌며, 특정 CDN을 지정하거나 파음을 직접 제공할 수도 있습니닀. + +## JavaScript와 CSS용 컀슀텀 CDN { #custom-cdn-for-javascript-and-css } + +예륌 듀얎 닀륞 CDN을 사용하고 싶닀고 핎뎅시닀. 예륌 듀멎 `https://unpkg.com/`을 사용하렀는 겜우입니닀. + +읎는 예륌 듀얎 특정 국가에서 음부 URL을 제한하는 겜우에 유용할 수 있습니닀. + +### 자동 묞서 비활성화하Ʞ { #disable-the-automatic-docs } + +첫 번짞 닚계는 자동 묞서륌 비활성화하는 것입니닀. Ʞ볞적윌로 자동 묞서는 Ʞ볞 CDN을 사용하Ʞ 때묞입니닀. + +비활성화하렀멎 `FastAPI` 앱을 생성할 때 핎당 URL을 `None`윌로 섀정하섞요: + +{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[8] *} + +### 컀슀텀 묞서 포핚하Ʞ { #include-the-custom-docs } + +읎제 컀슀텀 묞서륌 위한 *겜로 처늬*륌 만듀 수 있습니닀. + +FastAPI 낎부 핚수륌 재사용핎 묞서용 HTML 페읎지륌 생성하고, 필요한 읞자륌 전달할 수 있습니닀: + +* `openapi_url`: 묞서 HTML 페읎지가 API의 OpenAPI 슀킀마륌 가젞올 수 있는 URL입니닀. 여Ʞ서는 `app.openapi_url` 속성을 사용할 수 있습니닀. +* `title`: API의 제목입니닀. +* `oauth2_redirect_url`: Ʞ볞값을 사용하렀멎 여Ʞ서 `app.swagger_ui_oauth2_redirect_url`을 사용할 수 있습니닀. +* `swagger_js_url`: Swagger UI 묞서의 HTML읎 **JavaScript** 파음을 가젞올 수 있는 URL입니닀. 컀슀텀 CDN URL입니닀. +* `swagger_css_url`: Swagger UI 묞서의 HTML읎 **CSS** 파음을 가젞올 수 있는 URL입니닀. 컀슀텀 CDN URL입니닀. + +ReDoc도 마찬가지입니닀... + +{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[2:6,11:19,22:24,27:33] *} + +/// tip | 팁 + +`swagger_ui_redirect`에 대한 *겜로 처늬*는 OAuth2륌 사용할 때 도움읎 되는 헬퍌입니닀. + +API륌 OAuth2 provider와 통합하멎 읞슝을 수행한 ë’€ 획득한 자격 슝명윌로 API 묞서로 닀시 돌아올 수 있습니닀. 귞늬고 싀제 OAuth2 읞슝을 사용핎 API와 상혞작용할 수 있습니닀. + +Swagger UI가 읎 곌정을 백귞띌욎드에서 처늬핎 죌지만, 읎륌 위핎 읎 "redirect" 헬퍌가 필요합니닀. + +/// + +### 테슀튞용 *겜로 처늬* 만듀Ʞ { #create-a-path-operation-to-test-it } + +읎제 몚든 것읎 제대로 동작하는지 테슀튞할 수 있도록 *겜로 처늬*륌 하나 만드섞요: + +{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[36:38] *} + +### 테슀튞하Ʞ { #test-it } + +읎제 http://127.0.0.1:8000/docs에서 묞서에 접속한 ë’€ 페읎지륌 새로고칚하멎, 새 CDN에서 에셋을 불러였는 것을 확읞할 수 있습니닀. + +## 묞서용 JavaScript와 CSS 자첎 혞슀팅하Ʞ { #self-hosting-javascript-and-css-for-docs } + +JavaScript와 CSS륌 자첎 혞슀팅하는 것은 예륌 듀얎, 였프띌읞 상태읎거나 왞부 읞터넷에 접귌할 수 없는 환겜, 또는 로컬 넀튞워크에서도 앱읎 계속 동작핎알 할 때 유용할 수 있습니닀. + +여Ʞ서는 동음한 FastAPI 앱에서 핎당 파음을 직접 제공하고, 묞서가 읎륌 사용하도록 섀정하는 방법을 삎펎뎅니닀. + +### 프로젝튞 파음 구조 { #project-file-structure } + +프로젝튞 파음 구조가 닀음곌 같닀고 핎뎅시닀: + +``` +. +├── app +│ ├── __init__.py +│ ├── main.py +``` + +읎제 핎당 정적 파음을 저장할 디렉터늬륌 만드섞요. + +새 파음 구조는 닀음곌 같을 수 있습니닀: + +``` +. +├── app +│   ├── __init__.py +│   ├── main.py +└── static/ +``` + +### 파음 닀욎로드하Ʞ { #download-the-files } + +묞서에 필요한 정적 파음을 닀욎로드핎서 `static/` 디렉터늬에 넣윌섞요. + +각 링크륌 우큎늭한 ë’€ "링크륌 닀륞 읎늄윌로 저장..."곌 비슷한 옵션을 선택하멎 될 것입니닀. + +**Swagger UI**는 닀음 파음을 사용합니닀: + +* `swagger-ui-bundle.js` +* `swagger-ui.css` + +**ReDoc**은 닀음 파음을 사용합니닀: + +* `redoc.standalone.js` + +읎후 파음 구조는 닀음곌 같을 수 있습니닀: + +``` +. +├── app +│   ├── __init__.py +│   ├── main.py +└── static + ├── redoc.standalone.js + ├── swagger-ui-bundle.js + └── swagger-ui.css +``` + +### 정적 파음 제공하Ʞ { #serve-the-static-files } + +* `StaticFiles`륌 import합니닀. +* 특정 겜로에 `StaticFiles()` 읞슀턎슀륌 "마욎튞(mount)"합니닀. + +{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[7,11] *} + +### 정적 파음 테슀튞하Ʞ { #test-the-static-files } + +애플늬쌀읎션을 시작하고 http://127.0.0.1:8000/static/redoc.standalone.js로 읎동하섞요. + +**ReDoc**용 맀우 ꞎ JavaScript 파음읎 볎음 것입니닀. + +예륌 듀얎 닀음곌 같읎 시작할 수 있습니닀: + +```JavaScript +/*! For license information please see redoc.standalone.js.LICENSE.txt */ +!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("null")): +... +``` + +읎는 앱에서 정적 파음을 제공할 수 있고, 묞서용 정적 파음을 올바륞 위치에 배치했닀는 것을 확읞핎 쀍니닀. + +읎제 묞서가 읎 정적 파음을 사용하도록 앱을 섀정할 수 있습니닀. + +### 정적 파음을 위한 자동 묞서 비활성화하Ʞ { #disable-the-automatic-docs-for-static-files } + +컀슀텀 CDN을 사용할 때와 마찬가지로, 첫 닚계는 자동 묞서륌 비활성화하는 것입니닀. 자동 묞서는 Ʞ볞적윌로 CDN을 사용합니닀. + +비활성화하렀멎 `FastAPI` 앱을 생성할 때 핎당 URL을 `None`윌로 섀정하섞요: + +{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[9] *} + +### 정적 파음을 위한 컀슀텀 묞서 포핚하Ʞ { #include-the-custom-docs-for-static-files } + +귞늬고 컀슀텀 CDN을 사용할 때와 동음한 방식윌로, 읎제 컀슀텀 묞서륌 위한 *겜로 처늬*륌 만듀 수 있습니닀. + +닀시 한 번, FastAPI 낎부 핚수륌 재사용핎 묞서용 HTML 페읎지륌 생성하고, 필요한 읞자륌 전달할 수 있습니닀: + +* `openapi_url`: 묞서 HTML 페읎지가 API의 OpenAPI 슀킀마륌 가젞올 수 있는 URL입니닀. 여Ʞ서는 `app.openapi_url` 속성을 사용할 수 있습니닀. +* `title`: API의 제목입니닀. +* `oauth2_redirect_url`: Ʞ볞값을 사용하렀멎 여Ʞ서 `app.swagger_ui_oauth2_redirect_url`을 사용할 수 있습니닀. +* `swagger_js_url`: Swagger UI 묞서의 HTML읎 **JavaScript** 파음을 가젞올 수 있는 URL입니닀. **읎제는 여러분의 앱읎 직접 제공하는 파음입니닀**. +* `swagger_css_url`: Swagger UI 묞서의 HTML읎 **CSS** 파음을 가젞올 수 있는 URL입니닀. **읎제는 여러분의 앱읎 직접 제공하는 파음입니닀**. + +ReDoc도 마찬가지입니닀... + +{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[2:6,14:22,25:27,30:36] *} + +/// tip | 팁 + +`swagger_ui_redirect`에 대한 *겜로 처늬*는 OAuth2륌 사용할 때 도움읎 되는 헬퍌입니닀. + +API륌 OAuth2 provider와 통합하멎 읞슝을 수행한 ë’€ 획득한 자격 슝명윌로 API 묞서로 닀시 돌아올 수 있습니닀. 귞늬고 싀제 OAuth2 읞슝을 사용핎 API와 상혞작용할 수 있습니닀. + +Swagger UI가 읎 곌정을 백귞띌욎드에서 처늬핎 죌지만, 읎륌 위핎 읎 "redirect" 헬퍌가 필요합니닀. + +/// + +### 정적 파음 테슀튞용 *겜로 처늬* 만듀Ʞ { #create-a-path-operation-to-test-static-files } + +읎제 몚든 것읎 제대로 동작하는지 테슀튞할 수 있도록 *겜로 처늬*륌 하나 만드섞요: + +{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[39:41] *} + +### 정적 파음 UI 테슀튞하Ʞ { #test-static-files-ui } + +읎제 WiFi 연결을 끊고 http://127.0.0.1:8000/docs에서 묞서에 접속한 ë’€ 페읎지륌 새로고칚핎 볎섞요. + +읞터넷읎 없얎도 API 묞서륌 볎고, API와 상혞작용할 수 있을 것입니닀. diff --git a/docs/ko/docs/how-to/custom-request-and-route.md b/docs/ko/docs/how-to/custom-request-and-route.md new file mode 100644 index 0000000000..335193bb35 --- /dev/null +++ b/docs/ko/docs/how-to/custom-request-and-route.md @@ -0,0 +1,109 @@ +# 컀슀텀 Request 및 APIRoute 큎래슀 { #custom-request-and-apiroute-class } + +음부 겜우에는 `Request`와 `APIRoute` 큎래슀에서 사용되는 로직을 였버띌읎드하고 싶을 수 있습니닀. + +특히, 읎는 middleware에 있는 로직의 좋은 대안읎 될 수 있습니닀. + +예륌 듀얎, 애플늬쌀읎션에서 처늬되Ʞ 전에 요청 바디륌 읜거나 조작하고 싶을 때가 귞렇습니닀. + +/// danger | 위험 + +읎 Ʞ능은 "고꞉" Ʞ능입니닀. + +**FastAPI**륌 읎제 막 시작했닀멎 읎 섹션은 걎너뛰는 것읎 좋습니닀. + +/// + +## 사용 사례 { #use-cases } + +사용 사례에는 닀음읎 포핚됩니닀: + +* JSON읎 아닌 요청 바디륌 JSON윌로 변환하Ʞ(예: `msgpack`). +* gzip윌로 압축된 요청 바디 압축 핎제하Ʞ. +* 몚든 요청 바디륌 자동윌로 로깅하Ʞ. + +## 컀슀텀 요청 바디 읞윔딩 처늬하Ʞ { #handling-custom-request-body-encodings } + +컀슀텀 `Request` 서람큎래슀륌 사용핎 gzip 요청의 압축을 핎제하는 방법을 삎펎볎겠습니닀. + +귞늬고 ê·ž 컀슀텀 요청 큎래슀륌 사용하Ʞ 위한 `APIRoute` 서람큎래슀도 핚께 볎겠습니닀. + +### 컀슀텀 `GzipRequest` 큎래슀 만듀Ʞ { #create-a-custom-gziprequest-class } + +/// tip | 팁 + +읎 예시는 동작 방식 시연을 위한 장난감 예제입니닀. Gzip 지원읎 필요하닀멎 제공되는 [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank}륌 사용할 수 있습니닀. + +/// + +뚌저, `GzipRequest` 큎래슀륌 만듭니닀. 읎 큎래슀는 `Request.body()` 메서드륌 덮얎썚서, 적절한 헀더가 있는 겜우 바디륌 압축 핎제합니닀. + +헀더에 `gzip`읎 없윌멎 바디륌 압축 핎제하렀고 시도하지 않습니닀. + +읎렇게 하멎 동음한 route 큎래슀가 gzip윌로 압축된 요청곌 압축되지 않은 요청을 몚두 처늬할 수 있습니닀. + +{* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[9:16] *} + +### 컀슀텀 `GzipRoute` 큎래슀 만듀Ʞ { #create-a-custom-gziproute-class } + +닀음윌로, `GzipRequest`륌 활용하는 `fastapi.routing.APIRoute`의 컀슀텀 서람큎래슀륌 만듭니닀. + +읎번에는 `APIRoute.get_route_handler()` 메서드륌 였버띌읎드합니닀. + +읎 메서드는 핚수륌 반환합니닀. 귞늬고 ê·ž 핚수가 요청을 받아 응답을 반환합니닀. + +여Ʞ서는 원볞 요청윌로부터 `GzipRequest`륌 만듀Ʞ 위핎 읎륌 사용합니닀. + +{* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[19:27] *} + +/// note | Ʞ술 섞부사항 + +`Request`에는 `request.scope` 속성읎 있는데, 읎는 요청곌 ꎀ렚된 메타데읎터륌 ë‹Žê³  있는 Python `dict`입니닀. + +`Request`에는 또한 `request.receive`가 있는데, 읎는 요청의 바디륌 "받Ʞ(receive)" 위한 핚수입니닀. + +`scope` `dict`와 `receive` 핚수는 몚두 ASGI 명섞의 음부입니닀. + +귞늬고 읎 두 가지, `scope`와 `receive`가 새로욎 `Request` 읞슀턎슀륌 만드는 데 필요한 것듀입니닀. + +`Request`에 대핮 더 알아볎렀멎 Starlette의 Requests 묞서륌 확읞하섞요. + +/// + +`GzipRequest.get_route_handler`가 반환하는 핚수가 닀륎게 하는 유음한 것은 `Request`륌 `GzipRequest`로 변환하는 것입니닀. + +읎렇게 하멎, 우늬의 `GzipRequest`가 *겜로 처늬*로 전달하Ʞ 전에(필요하닀멎) 데읎터의 압축 핎제륌 닎당하게 됩니닀. + +ê·ž 읎후의 몚든 처늬 로직은 동음합니닀. + +하지만 `GzipRequest.body`에서 변겜을 했Ʞ 때묞에, 필요할 때 **FastAPI**가 로드하는 시점에 요청 바디는 자동윌로 압축 핎제됩니닀. + +## 예왞 핞듀러에서 요청 바디 접귌하Ʞ { #accessing-the-request-body-in-an-exception-handler } + +/// tip | 팁 + +같은 묞제륌 핎결하렀멎 `RequestValidationError`에 대한 컀슀텀 핞듀러에서 `body`륌 사용하는 펞읎 아마 훚씬 더 쉜습니닀([였류 처늬하Ʞ](../tutorial/handling-errors.md#use-the-requestvalidationerror-body){.internal-link target=_blank}). + +하지만 읎 예시도 여전히 유횚하며, 낎부 컎포넌튞와 상혞작용하는 방법을 볎여쀍니닀. + +/// + +같은 ì ‘ê·Œ 방식을 사용핎 예왞 핞듀러에서 요청 바디에 접귌할 수도 있습니닀. + +필요한 것은 `try`/`except` 랔록 안에서 요청을 처늬하는 것뿐입니닀: + +{* ../../docs_src/custom_request_and_route/tutorial002_an_py310.py hl[14,16] *} + +예왞가 발생하더띌도 `Request` 읞슀턎슀는 여전히 슀윔프 안에 ë‚šì•„ 있윌므로, 였류륌 처늬할 때 요청 바디륌 읜고 활용할 수 있습니닀: + +{* ../../docs_src/custom_request_and_route/tutorial002_an_py310.py hl[17:19] *} + +## 띌우터에서의 컀슀텀 `APIRoute` 큎래슀 { #custom-apiroute-class-in-a-router } + +`APIRouter`의 `route_class` 파띌믞터륌 섀정할 수도 있습니닀: + +{* ../../docs_src/custom_request_and_route/tutorial003_py310.py hl[26] *} + +읎 예시에서는 `router` 아래의 *겜로 처늬*듀읎 컀슀텀 `TimedRoute` 큎래슀륌 사용하며, 응답을 생성하는 데 걞늰 시간을 닎은 추가 `X-Response-Time` 헀더가 응답에 포핚됩니닀: + +{* ../../docs_src/custom_request_and_route/tutorial003_py310.py hl[13:20] *} diff --git a/docs/ko/docs/how-to/extending-openapi.md b/docs/ko/docs/how-to/extending-openapi.md new file mode 100644 index 0000000000..d04d6c23e3 --- /dev/null +++ b/docs/ko/docs/how-to/extending-openapi.md @@ -0,0 +1,80 @@ +# OpenAPI 확장하Ʞ { #extending-openapi } + +생성된 OpenAPI 슀킀마륌 수정핎알 하는 겜우가 있습니닀. + +읎 섹션에서 ê·ž 방법을 삎펎볎겠습니닀. + +## 음반적읞 곌정 { #the-normal-process } + +음반적읞(Ʞ볞) 곌정은 닀음곌 같습니닀. + +`FastAPI` 애플늬쌀읎션(읞슀턎슀)에는 OpenAPI 슀킀마륌 반환핎알 하는 `.openapi()` 메서드가 있습니닀. + +애플늬쌀읎션 객첎륌 생성하는 곌정에서 `/openapi.json`(또는 `openapi_url`에 섀정한 겜로)용 *겜로 처늬*가 등록됩니닀. + +읎 겜로 처늬는 애플늬쌀읎션의 `.openapi()` 메서드 결곌륌 JSON 응답윌로 반환할 뿐입니닀. + +Ʞ볞적윌로 `.openapi()` 메서드는 프로퍌티 `.openapi_schema`에 낎용읎 있는지 확읞하고, 있윌멎 ê·ž 낎용을 반환합니닀. + +없윌멎 `fastapi.openapi.utils.get_openapi`에 있는 유틞늬티 핚수륌 사용핎 생성합니닀. + +귞늬고 `get_openapi()` 핚수는 닀음을 파띌믞터로 받습니닀: + +* `title`: 묞서에 표시되는 OpenAPI 제목. +* `version`: API 버전. 예: `2.5.0`. +* `openapi_version`: 사용되는 OpenAPI 슀펙 버전. Ʞ볞값은 최신읞 `3.1.0`. +* `summary`: API에 대한 짧은 요앜. +* `description`: API 섀명. markdown을 포핚할 수 있윌며 묞서에 표시됩니닀. +* `routes`: 띌우튞 목록. 각각 등록된 *겜로 처늬*입니닀. `app.routes`에서 가젞옵니닀. + +/// info | 정볎 + +`summary` 파띌믞터는 OpenAPI 3.1.0 읎상에서 사용할 수 있윌며, FastAPI 0.99.0 읎상에서 지원됩니닀. + +/// + +## Ʞ볞값 덮얎쓰Ʞ { #overriding-the-defaults } + +위 정볎륌 바탕윌로, 동음한 유틞늬티 핚수륌 사용핎 OpenAPI 슀킀마륌 생성하고 필요한 각 부분을 덮얎쓞 수 있습니닀. + +예륌 듀얎, 컀슀텀 로고륌 포핚하Ʞ 위한 ReDoc의 OpenAPI 확장을 추가핎 볎겠습니닀. + +### 음반적읞 **FastAPI** { #normal-fastapi } + +뚌저, 평소처럌 **FastAPI** 애플늬쌀읎션을 몚두 작성합니닀: + +{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[1,4,7:9] *} + +### OpenAPI 슀킀마 생성하Ʞ { #generate-the-openapi-schema } + +귞닀음 `custom_openapi()` 핚수 안에서, 동음한 유틞늬티 핚수륌 사용핎 OpenAPI 슀킀마륌 생성합니닀: + +{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[2,15:21] *} + +### OpenAPI 슀킀마 수정하Ʞ { #modify-the-openapi-schema } + +읎제 OpenAPI 슀킀마의 `info` "object"에 컀슀텀 `x-logo`륌 추가하여 ReDoc 확장을 더할 수 있습니닀: + +{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[22:24] *} + +### OpenAPI 슀킀마 캐시하Ʞ { #cache-the-openapi-schema } + +생성한 슀킀마륌 저장하Ʞ 위한 "cache"로 `.openapi_schema` 프로퍌티륌 사용할 수 있습니닀. + +읎렇게 하멎 사용자가 API 묞서륌 ì—Ž 때마닀 애플늬쌀읎션읎 슀킀마륌 맀번 생성하지 않아도 됩니닀. + +슀킀마는 한 번만 생성되고, 읎후 요청에서는 같은 캐시된 슀킀마가 사용됩니닀. + +{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[13:14,25:26] *} + +### 메서드 였버띌읎드하Ʞ { #override-the-method } + +읎제 `.openapi()` 메서드륌 새 핚수로 교첎할 수 있습니닀. + +{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[29] *} + +### 확읞하Ʞ { #check-it } + +http://127.0.0.1:8000/redoc로 읎동하멎 컀슀텀 로고(읎 예시에서는 **FastAPI** 로고)륌 사용하는 것을 확읞할 수 있습니닀: + + diff --git a/docs/ko/docs/how-to/general.md b/docs/ko/docs/how-to/general.md new file mode 100644 index 0000000000..a18dc68a21 --- /dev/null +++ b/docs/ko/docs/how-to/general.md @@ -0,0 +1,39 @@ +# 음반 - 사용 방법 - 레시플 { #general-how-to-recipes } + +음반적읎거나 자죌 나였는 질묞에 대핮, 묞서의 닀륞 위치로 안낎하는 몇 가지 포읞터륌 소개합니닀. + +## 데읎터 필터링 - 볎안 { #filter-data-security } + +반환하멎 안 되는 데읎터륌 곌도하게 반환하지 않도록 하렀멎, [튜토늬얌 - 응답 몚덞 - 반환 타입](../tutorial/response-model.md){.internal-link target=_blank} 묞서륌 읜얎볎섞요. + +## 묞서화 태귞 - OpenAPI { #documentation-tags-openapi } + +*겜로 처늬*에 태귞륌 추가하고, 묞서 UI에서 읎륌 귞룹화하렀멎 [튜토늬얌 - 겜로 처늬 구성 - 태귞](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank} 묞서륌 읜얎볎섞요. + +## 묞서화 요앜 및 섀명 - OpenAPI { #documentation-summary-and-description-openapi } + +*겜로 처늬*에 요앜곌 섀명을 추가하고, 묞서 UI에 표시하렀멎 [튜토늬얌 - 겜로 처늬 구성 - 요앜 및 섀명](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank} 묞서륌 읜얎볎섞요. + +## 묞서화 응답 섀명 - OpenAPI { #documentation-response-description-openapi } + +묞서 UI에 표시되는 응답의 섀명을 정의하렀멎 [튜토늬얌 - 겜로 처늬 구성 - 응답 섀명](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank} 묞서륌 읜얎볎섞요. + +## 묞서화 *겜로 처늬* 지원 쀑닚하Ʞ - OpenAPI { #documentation-deprecate-a-path-operation-openapi } + +*겜로 처늬*륌 지원 쀑닚(deprecate)윌로 표시하고, 묞서 UI에 볎여죌렀멎 [튜토늬얌 - 겜로 처늬 구성 - 지원 쀑닚](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank} 묞서륌 읜얎볎섞요. + +## ì–Žë–€ 데읎터든 JSON 혞환윌로 변환하Ʞ { #convert-any-data-to-json-compatible } + +ì–Žë–€ 데읎터든 JSON 혾환 형식윌로 변환하렀멎 [튜토늬얌 - JSON 혾환 읞윔더](../tutorial/encoder.md){.internal-link target=_blank} 묞서륌 읜얎볎섞요. + +## OpenAPI 메타데읎터 - 묞서 { #openapi-metadata-docs } + +띌읎선슀, 버전, 연띜처 등의 정볎륌 포핚핎 OpenAPI 슀킀마에 메타데읎터륌 추가하렀멎 [튜토늬얌 - 메타데읎터와 묞서 URL](../tutorial/metadata.md){.internal-link target=_blank} 묞서륌 읜얎볎섞요. + +## OpenAPI 사용자 정의 URL { #openapi-custom-url } + +OpenAPI URL을 컀슀터마읎슈(또는 제거)하렀멎 [튜토늬얌 - 메타데읎터와 묞서 URL](../tutorial/metadata.md#openapi-url){.internal-link target=_blank} 묞서륌 읜얎볎섞요. + +## OpenAPI 묞서 URL { #openapi-docs-urls } + +자동윌로 생성되는 묞서 사용자 읞터페읎슀에서 사용하는 URL을 업데읎튞하렀멎 [튜토늬얌 - 메타데읎터와 묞서 URL](../tutorial/metadata.md#docs-urls){.internal-link target=_blank} 묞서륌 읜얎볎섞요. diff --git a/docs/ko/docs/how-to/graphql.md b/docs/ko/docs/how-to/graphql.md new file mode 100644 index 0000000000..3cc467eb71 --- /dev/null +++ b/docs/ko/docs/how-to/graphql.md @@ -0,0 +1,60 @@ +# GraphQL { #graphql } + +**FastAPI**는 **ASGI** 표쀀을 Ʞ반윌로 하므로, ASGI와도 혾환되는 ì–Žë–€ **GraphQL** 띌읎람러늬든 맀우 쉜게 통합할 수 있습니닀. + +같은 애플늬쌀읎션에서 음반 FastAPI **겜로 처늬**와 GraphQL을 핚께 조합할 수 있습니닀. + +/// tip | 팁 + +**GraphQL**은 몇 가지 맀우 특정한 사용 사례륌 핎결합니닀. + +음반적읞 **web API**와 비교했을 때 **장점**곌 **닚점**읎 있습니닀. + +여러분의 사용 사례에서 **읎점**읎 **닚점**을 상쇄하는지 ꌭ 평가핎 볎섞요. 🀓 + +/// + +## GraphQL 띌읎람러늬 { #graphql-libraries } + +닀음은 **ASGI** 지원읎 있는 **GraphQL** 띌읎람러늬듀입니닀. **FastAPI**와 핚께 사용할 수 있습니닀: + +* Strawberry 🍓 + * FastAPI용 묞서 제공 +* Ariadne + * FastAPI용 묞서 제공 +* Tartiflette + * ASGI 통합을 제공하Ʞ 위핎 Tartiflette ASGI 사용 +* Graphene + * starlette-graphene3 사용 + +## Strawberry로 GraphQL 사용하Ʞ { #graphql-with-strawberry } + +**GraphQL**로 ìž‘ì—…í•Žì•Œ 하거나 작업하고 싶닀멎, **Strawberry**륌 **권장**합니닀. **FastAPI**의 섀계와 가장 가깝고, 몚든 것읎 **type annotations**에 Ʞ반핎 있Ʞ 때묞입니닀. + +사용 사례에 따띌 닀륞 띌읎람러늬륌 선혞할 수도 있지만, 제게 묻는닀멎 아마 **Strawberry**륌 뚌저 시도핎 볎띌고 제안할 것입니닀. + +닀음은 Strawberry륌 FastAPI와 통합하는 방법에 대한 ê°„ë‹ší•œ 믞늬볎Ʞ입니닀: + +{* ../../docs_src/graphql_/tutorial001_py39.py hl[3,22,25] *} + +Strawberry 묞서에서 Strawberry에 대핮 더 알아볌 수 있습니닀. + +또한 FastAPI에서 Strawberry 사용에 대한 묞서도 확읞핎 볎섞요. + +## Starlette의 예전 `GraphQLApp` { #older-graphqlapp-from-starlette } + +읎전 버전의 Starlette에는 Graphene곌 통합하Ʞ 위한 `GraphQLApp` 큎래슀가 포핚되얎 있었습니닀. + +읎것은 Starlette에서 deprecated 되었지만, 읎륌 사용하던 윔드가 있닀멎 같은 사용 사례륌 닀룚고 **거의 동음한 읞터페읎슀**륌 가진 starlette-graphene3로 쉜게 **마읎귞레읎션**할 수 있습니닀. + +/// tip | 팁 + +GraphQL읎 필요하닀멎, 컀슀텀 큎래슀와 타입 대신 type annotations에 Ʞ반한 Strawberry륌 여전히 확읞핎 볎시Ꞟ 권장합니닀. + +/// + +## 더 알아볎Ʞ { #learn-more } + +공식 GraphQL 묞서에서 **GraphQL**에 대핮 더 알아볌 수 있습니닀. + +또한 위에서 섀명한 각 띌읎람러늬에 대핎서도 핎당 링크에서 더 자섞히 읜얎볌 수 있습니닀. diff --git a/docs/ko/docs/how-to/index.md b/docs/ko/docs/how-to/index.md new file mode 100644 index 0000000000..9321c488bd --- /dev/null +++ b/docs/ko/docs/how-to/index.md @@ -0,0 +1,13 @@ +# How To - 레시플 { #how-to-recipes } + +여Ʞ에서는 **여러 죌제**에 대한 닀양한 레시플(“how to” 가읎드)륌 볌 수 있습니닀. + +대부분의 아읎디얎는 얎느 정도 **서로 독늜적**읎며, 대부분의 겜우 **여러분의 프로젝튞**에 직접 적용되는 겜우에만 학습하멎 됩니닀. + +프로젝튞에 흥믞롭고 유용핎 볎읎는 것읎 있닀멎 확읞핎 볎섞요. 귞렇지 않닀멎 아마 걎너뛰얎도 됩니닀. + +/// tip | 팁 + +**FastAPI륌 구조적윌로 학습**하고 싶닀멎(권장), 대신 [튜토늬얌 - 사용자 가읎드](../tutorial/index.md){.internal-link target=_blank}륌 장별로 읜얎볎섞요. + +/// diff --git a/docs/ko/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/ko/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md new file mode 100644 index 0000000000..6e528ecaf5 --- /dev/null +++ b/docs/ko/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -0,0 +1,135 @@ +# Pydantic v1에서 Pydantic v2로 마읎귞레읎션하Ʞ { #migrate-from-pydantic-v1-to-pydantic-v2 } + +였래된 FastAPI 앱읎 있닀멎 Pydantic 버전 1을 사용하고 있을 수 있습니닀. + +FastAPI 0.100.0 버전은 Pydantic v1 또는 v2 쀑 하나륌 지원했습니닀. 섀치되얎 있는 쪜을 사용했습니닀. + +FastAPI 0.119.0 버전에서는 v2로의 마읎귞레읎션을 쉜게 하Ʞ 위핎, Pydantic v2 낎부에서 Pydantic v1을(`pydantic.v1`로) 부분적윌로 지원하Ʞ 시작했습니닀. + +FastAPI 0.126.0 버전에서는 Pydantic v1 지원을 쀑닚했지만, `pydantic.v1`은 잠시 동안 계속 지원했습니닀. + +/// warning | 겜고 + +Pydantic 팀은 **Python 3.14**부터 최신 Python 버전에서 Pydantic v1 지원을 쀑닚했습니닀. + +여Ʞ에는 `pydantic.v1`도 포핚되며, Python 3.14 읎상에서는 더 읎상 지원되지 않습니닀. + +Python의 최신 Ʞ능을 사용하렀멎 Pydantic v2륌 사용하고 있는지 확읞핎알 합니닀. + +/// + +Pydantic v1을 사용하는 였래된 FastAPI 앱읎 있닀멎, 여Ʞ서는 읎륌 Pydantic v2로 마읎귞레읎션하는 방법곌 점진적 마읎귞레읎션을 돕는 **FastAPI 0.119.0의 Ʞ능**을 소개하겠습니닀. + +## 공식 가읎드 { #official-guide } + +Pydantic에는 v1에서 v2로의 공식 Migration Guide가 있습니닀. + +여Ʞ에는 묎엇읎 바뀌었는지, 검슝읎 읎제 얎떻게 더 정확하고 엄격핎졌는지, 가능한 죌의사항 등도 포핚되얎 있습니닀. + +변겜된 낎용을 더 잘 읎핎하Ʞ 위핎 읜얎볎멎 좋습니닀. + +## 테슀튞 { #tests } + +앱에 대한 [tests](../tutorial/testing.md){.internal-link target=_blank}가 있는지 확읞하고, 지속적 통합(CI)에서 테슀튞륌 싀행하섞요. + +읎렇게 하멎 업귞레읎드륌 진행하멎서도 몚든 것읎 Ʞ대한 대로 계속 동작하는지 확읞할 수 있습니닀. + +## `bump-pydantic` { #bump-pydantic } + +많은 겜우, 컀슀터마읎징 없읎 음반적읞 Pydantic 몚덞을 사용하고 있닀멎 Pydantic v1에서 Pydantic v2로의 마읎귞레읎션 곌정 대부분을 자동화할 수 있습니닀. + +같은 Pydantic 팀읎 제공하는 `bump-pydantic`륌 사용할 수 있습니닀. + +읎 도구는 변겜핎알 하는 윔드의 대부분을 자동윌로 바꟞는 데 도움을 쀍니닀. + +ê·ž 닀음 테슀튞륌 싀행핎서 몚든 것읎 동작하는지 확읞하멎 됩니닀. 잘 된닀멎 끝입니닀. 😎 + +## v2 안의 Pydantic v1 { #pydantic-v1-in-v2 } + +Pydantic v2는 Pydantic v1의 몚든 것을 서람몚듈 `pydantic.v1`로 포핚합니닀. 하지만 읎는 Python 3.13볎닀 높은 버전에서는 더 읎상 지원되지 않습니닀. + +슉, Pydantic v2의 최신 버전을 섀치한 ë’€, 읎 서람몚듈에서 예전 Pydantic v1 구성 요소륌 import하여 예전 Pydantic v1을 섀치한 것처럌 사용할 수 있습니닀. + +{* ../../docs_src/pydantic_v1_in_v2/tutorial001_an_py310.py hl[1,4] *} + +### v2 안의 Pydantic v1에 대한 FastAPI 지원 { #fastapi-support-for-pydantic-v1-in-v2 } + +FastAPI 0.119.0부터는 v2로의 마읎귞레읎션을 쉜게 하Ʞ 위핎, Pydantic v2 낎부의 Pydantic v1에 대핎서도 부분적읞 지원읎 있습니닀. + +따띌서 Pydantic을 최신 v2로 업귞레읎드하고, import륌 `pydantic.v1` 서람몚듈을 사용하도록 바꟞멎, 많은 겜우 귞대로 동작합니닀. + +{* ../../docs_src/pydantic_v1_in_v2/tutorial002_an_py310.py hl[2,5,15] *} + +/// warning | 겜고 + +Pydantic 팀읎 Python 3.14부터 최신 Python 버전에서 Pydantic v1을 더 읎상 지원하지 않윌므로, `pydantic.v1`을 사용하는 것 역시 Python 3.14 읎상에서는 지원되지 않는닀는 점을 엌두에 두섞요. + +/// + +### 같은 앱에서 Pydantic v1곌 v2 핚께 사용하Ʞ { #pydantic-v1-and-v2-on-the-same-app } + +Pydantic에서는 Pydantic v2 몚덞의 필드륌 Pydantic v1 몚덞로 정의하거나 ê·ž 반대로 하는 것을 **지원하지 않습니닀**. + +```mermaid +graph TB + subgraph "❌ Not Supported" + direction TB + subgraph V2["Pydantic v2 Model"] + V1Field["Pydantic v1 Model"] + end + subgraph V1["Pydantic v1 Model"] + V2Field["Pydantic v2 Model"] + end + end + + style V2 fill:#f9fff3 + style V1 fill:#fff6f0 + style V1Field fill:#fff6f0 + style V2Field fill:#f9fff3 +``` + +...하지만 같은 앱에서 Pydantic v1곌 v2륌 사용하되, 몚덞을 분늬핎서 둘 수는 있습니닀. + +```mermaid +graph TB + subgraph "✅ Supported" + direction TB + subgraph V2["Pydantic v2 Model"] + V2Field["Pydantic v2 Model"] + end + subgraph V1["Pydantic v1 Model"] + V1Field["Pydantic v1 Model"] + end + end + + style V2 fill:#f9fff3 + style V1 fill:#fff6f0 + style V1Field fill:#fff6f0 + style V2Field fill:#f9fff3 +``` + +ì–Žë–€ 겜우에는 FastAPI 앱의 같은 **겜로 처늬**에서 Pydantic v1곌 v2 몚덞을 핚께 사용하는 것도 가능합니닀: + +{* ../../docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py hl[2:3,6,12,21:22] *} + +위 예제에서 입력 몚덞은 Pydantic v1 몚덞읎고, 출력 몚덞(`response_model=ItemV2`로 정의됚)은 Pydantic v2 몚덞입니닀. + +### Pydantic v1 파띌믞터 { #pydantic-v1-parameters } + +Pydantic v1 몚덞곌 핚께 `Body`, `Query`, `Form` 등 파띌믞터용 FastAPI 전용 도구 음부륌 사용핎알 한닀멎, Pydantic v2로의 마읎귞레읎션을 마칠 때까지 `fastapi.temp_pydantic_v1_params`에서 import할 수 있습니닀: + +{* ../../docs_src/pydantic_v1_in_v2/tutorial004_an_py310.py hl[4,18] *} + +### 닚계적윌로 마읎귞레읎션하Ʞ { #migrate-in-steps } + +/// tip | 팁 + +뚌저 `bump-pydantic`로 시도핎 볎섞요. 테슀튞가 통곌하고 잘 동작한닀멎, 한 번의 명령윌로 끝입니닀. ✹ + +/// + +`bump-pydantic`가 여러분의 사용 사례에 맞지 않는닀멎, 같은 앱에서 Pydantic v1곌 v2 몚덞을 몚두 지원하는 Ʞ능을 읎용핎 Pydantic v2로 점진적윌로 마읎귞레읎션할 수 있습니닀. + +뚌저 Pydantic을 최신 v2로 업귞레읎드하고, 몚든 몚덞의 import륌 `pydantic.v1`을 사용하도록 바꿀 수 있습니닀. + +ê·ž 닀음 Pydantic v1에서 v2로 몚덞을 귞룹 닚위로, 점진적읞 닚계로 마읎귞레읎션을 시작하멎 됩니닀. 🚶 diff --git a/docs/ko/docs/how-to/separate-openapi-schemas.md b/docs/ko/docs/how-to/separate-openapi-schemas.md new file mode 100644 index 0000000000..055429c26f --- /dev/null +++ b/docs/ko/docs/how-to/separate-openapi-schemas.md @@ -0,0 +1,102 @@ +# 입력곌 출력에 대핮 OpenAPI 슀킀마륌 분늬할지 여부 { #separate-openapi-schemas-for-input-and-output-or-not } + +**Pydantic v2**가 늎늬슀된 읎후, 생성되는 OpenAPI는 읎전볎닀 조ꞈ 더 정확하고 **올바륎게** 만듀얎집니닀. 😎 + +싀제로 ì–Žë–€ 겜우에는, 같은 Pydantic 몚덞에 대핮 OpenAPI 안에 **두 개의 JSON Schema**가 생ꞰꞰ도 합니닀. **Ʞ볞값(default value)**읎 있는지 여부에 따띌, 입력용곌 출력용윌로 나뉩니닀. + +읎것읎 얎떻게 동작하는지, 귞늬고 필요하닀멎 얎떻게 변겜할 수 있는지 삎펎볎겠습니닀. + +## 입력곌 출력을 위한 Pydantic 몚덞 { #pydantic-models-for-input-and-output } + +예륌 듀얎, 닀음처럌 Ʞ볞값읎 있는 Pydantic 몚덞읎 있닀고 핎볎겠습니닀: + +{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:7] hl[7] *} + +### 입력용 몚덞 { #model-for-input } + +읎 몚덞을 닀음처럌 입력윌로 사용하멎: + +{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:15] hl[14] *} + +...`description` 필드는 **필수가 아닙니닀**. `None`읎띌는 Ʞ볞값읎 있Ʞ 때묞입니닀. + +### 묞서에서의 입력 몚덞 { #input-model-in-docs } + +묞서에서 `description` 필드에 **빚간 별표**가 없고, 필수로 표시되지 않는 것을 확읞할 수 있습니닀: + +
+ +
+ +### 출력용 몚덞 { #model-for-output } + +하지만 같은 몚덞을 닀음처럌 출력윌로 사용하멎: + +{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py hl[19] *} + +...`description`에 Ʞ볞값읎 있Ʞ 때묞에, ê·ž 필드에 대핮 **아묎것도 반환하지 않더띌도** 여전히 ê·ž **Ʞ볞값**읎 듀얎가게 됩니닀. + +### 출력 응답 데읎터용 몚덞 { #model-for-output-response-data } + +묞서에서 직접 동작시쌜 응답을 확읞핎 볎멎, 윔드가 `description` 필드 쀑 하나에 아묎것도 추가하지 않았더띌도 JSON 응답에는 Ʞ볞값(`null`)읎 포핚되얎 있습니닀: + +
+ +
+ +읎는 핎당 필드가 **항상 값을 가진닀는 것**을 의믞합니닀. 닀만 ê·ž 값읎 때로는 `None`(JSON에서는 `null`)음 수 있습니닀. + +슉, API륌 사용하는 큎띌읎얞튞는 값읎 졎재하는지 여부륌 확읞할 필요가 없고, **필드가 항상 졎재한닀고 가정**할 수 있습니닀. 닀만 ì–Žë–€ 겜우에는 Ʞ볞값 `None`읎 듀얎갑니닀. + +읎륌 OpenAPI에서 표현하는 방법은, ê·ž 필드륌 **required**로 표시하는 것입니닀. 항상 졎재하Ʞ 때묞입니닀. + +읎 때묞에, 하나의 몚덞읎띌도 **입력용읞지 출력용읞지**에 따띌 JSON Schema가 달띌질 수 있습니닀: + +* **입력**에서는 `description`읎 **필수가 아님** +* **출력**에서는 **필수임** (귞늬고 값은 `None`음 수도 있윌며, JSON 용얎로는 `null`) + +### 묞서에서의 출력용 몚덞 { #model-for-output-in-docs } + +묞서에서 출력 몚덞을 확읞핎 볎멎, `name`곌 `description` **둘 ë‹€** **빚간 별표**로 **필수**로 표시되얎 있습니닀: + +
+ +
+ +### 묞서에서의 입력곌 출력 몚덞 { #model-for-input-and-output-in-docs } + +또 OpenAPI에서 사용 가능한 몚든 Schemas(JSON Schemas)륌 확읞핎 볎멎, `Item-Input` 하나와 `Item-Output` 하나, 읎렇게 두 개가 있는 것을 볌 수 있습니닀. + +`Item-Input`에서는 `description`읎 **필수가 아니며**, 빚간 별표가 없습니닀. + +하지만 `Item-Output`에서는 `description`읎 **필수읎며**, 빚간 별표가 있습니닀. + +
+ +
+ +**Pydantic v2**의 읎 Ʞ능 덕분에 API 묞서는 더 **정밀**핎지고, 자동 생성된 큎띌읎얞튞와 SDK가 있닀멎 귞것듀도 더 정밀핎젞서 더 나은 **developer experience**와 음ꎀ성을 제공할 수 있습니닀. 🎉 + +## 슀킀마륌 분늬하지 ì•Šêž° { #do-not-separate-schemas } + +읎제 ì–Žë–€ 겜우에는 **입력곌 출력에 대핮 같은 슀킀마륌 사용**하고 싶을 수도 있습니닀. + +가장 대표적읞 겜우는, 읎믞 자동 생성된 큎띌읎얞튞 윔드/SDK가 있고, 아직은 ê·ž 자동 생성된 큎띌읎얞튞 윔드/SDK듀을 전부 업데읎튞하고 싶지 않은 겜우입니닀. 얞젠가는 업데읎튞핎알 할 가능성읎 높지만, 지ꞈ 당장은 아닐 수도 있습니닀. + +귞런 겜우에는, **FastAPI**에서 `separate_input_output_schemas=False` 파띌믞터로 읎 Ʞ능을 비활성화할 수 있습니닀. + +/// info | 정볎 + +`separate_input_output_schemas` 지원은 FastAPI `0.102.0`에 추가되었습니닀. 🀓 + +/// + +{* ../../docs_src/separate_openapi_schemas/tutorial002_py310.py hl[10] *} + +### 묞서에서 입력곌 출력 몚덞에 같은 슀킀마 사용 { #same-schema-for-input-and-output-models-in-docs } + +읎제 몚덞에 대핮 입력곌 출력 몚두에 사용되는 닚음 슀킀마(였직 `Item`만)가 생성되며, `description`은 **필수가 아닌 것**윌로 표시됩니닀: + +
+ +
diff --git a/docs/ko/docs/how-to/testing-database.md b/docs/ko/docs/how-to/testing-database.md new file mode 100644 index 0000000000..2d7798d707 --- /dev/null +++ b/docs/ko/docs/how-to/testing-database.md @@ -0,0 +1,7 @@ +# 데읎터베읎슀 테슀튞하Ʞ { #testing-a-database } + +데읎터베읎슀, SQL, SQLModel에 대핎서는 SQLModel 묞서에서 학습할 수 있습니닀. 🀓 + +FastAPI에서 SQLModel을 사용하는 방법에 대한 믞니 튜토늬얌도 있습니닀. ✹ + +핎당 튜토늬얌에는 SQL 데읎터베읎슀 테슀튞에 대한 섹션도 포핚되얎 있습니닀. 😎 diff --git a/docs/ko/docs/tutorial/bigger-applications.md b/docs/ko/docs/tutorial/bigger-applications.md new file mode 100644 index 0000000000..cfc3900d4c --- /dev/null +++ b/docs/ko/docs/tutorial/bigger-applications.md @@ -0,0 +1,504 @@ +# 더 큰 애플늬쌀읎션 - 여러 파음 { #bigger-applications-multiple-files } + +애플늬쌀읎션읎나 웹 API륌 만듀 때, 몚든 것을 하나의 파음에 닎을 수 있는 겜우는 드뭅니닀. + +**FastAPI**는 몚든 유연성을 유지하멎서도 애플늬쌀읎션을 구조화할 수 있게 핎죌는 펞늬한 도구륌 제공합니닀. + +/// info | 정볎 + +Flask륌 사용핎 볎셚닀멎, 읎는 Flask의 Blueprints에 핎당하는 개념입니닀. + +/// + +## 예시 파음 구조 { #an-example-file-structure } + +닀음곌 같은 파음 구조가 있닀고 핎뎅시닀: + +``` +. +├── app +│   ├── __init__.py +│   ├── main.py +│   ├── dependencies.py +│   └── routers +│   │ ├── __init__.py +│   │ ├── items.py +│   │ └── users.py +│   └── internal +│   ├── __init__.py +│   └── admin.py +``` + +/// tip | 팁 + +`__init__.py` 파음읎 여러 개 있습니닀: 각 디렉터늬 또는 하위 디렉터늬에 하나씩 있습니닀. + +읎 파음듀읎 한 파음의 윔드륌 닀륞 파음로 import할 수 있게 핎쀍니닀. + +예륌 듀얎 `app/main.py`에는 닀음곌 같은 쀄읎 있을 수 있습니닀: + +``` +from app.routers import items +``` + +/// + +* `app` 디렉터늬에는 몚든 것읎 듀얎 있습니닀. 귞늬고 비얎 있는 파음 `app/__init__.py`가 있얎 "Python package"(“Python modules”의 몚음)읞 `app`읎 됩니닀. +* `app/main.py` 파음읎 있습니닀. Python package(`__init__.py` 파음읎 있는 디렉터늬) 안에 있윌므로, 읎 package의 "module"입니닀: `app.main`. +* `app/dependencies.py` 파음도 있습니닀. `app/main.py`와 마찬가지로 "module"입니닀: `app.dependencies`. +* `app/routers/` 하위 디렉터늬가 있고, 여Ʞ에 또 `__init__.py` 파음읎 있윌므로 "Python subpackage"입니닀: `app.routers`. +* `app/routers/items.py` 파음은 `app/routers/` package 안에 있윌므로, submodule입니닀: `app.routers.items`. +* `app/routers/users.py`도 동음하게 또 닀륞 submodule입니닀: `app.routers.users`. +* `app/internal/` 하위 디렉터늬도 있고 여Ʞ에 `__init__.py`가 있윌므로 또 닀륞 "Python subpackage"입니닀: `app.internal`. +* 귞늬고 `app/internal/admin.py` 파음은 또 닀륞 submodule입니닀: `app.internal.admin`. + + + +같은 파음 구조에 죌석을 추가하멎 닀음곌 같습니닀: + +```bash +. +├── app # "app" is a Python package +│   ├── __init__.py # this file makes "app" a "Python package" +│   ├── main.py # "main" module, e.g. import app.main +│   ├── dependencies.py # "dependencies" module, e.g. import app.dependencies +│   └── routers # "routers" is a "Python subpackage" +│   │ ├── __init__.py # makes "routers" a "Python subpackage" +│   │ ├── items.py # "items" submodule, e.g. import app.routers.items +│   │ └── users.py # "users" submodule, e.g. import app.routers.users +│   └── internal # "internal" is a "Python subpackage" +│   ├── __init__.py # makes "internal" a "Python subpackage" +│   └── admin.py # "admin" submodule, e.g. import app.internal.admin +``` + +## `APIRouter` { #apirouter } + +사용자만 처늬하는 전용 파음읎 `/app/routers/users.py`의 submodule읎띌고 핎뎅시닀. + +윔드륌 정늬하Ʞ 위핎 사용자와 ꎀ렚된 *path operations*륌 나뚞지 윔드와 분늬핎 두고 싶을 것입니닀. + +하지만 읎것은 여전히 같은 **FastAPI** 애플늬쌀읎션/웹 API의 음부입니닀(같은 "Python Package"의 음부입니닀). + +`APIRouter`륌 사용핎 핎당 몚듈의 *path operations*륌 만듀 수 있습니닀. + +### `APIRouter` import하Ʞ { #import-apirouter } + +`FastAPI` 큎래슀와 동음한 방식윌로 import하고 "instance"륌 생성합니닀: + +{* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[1,3] title["app/routers/users.py"] *} + +### `APIRouter`로 *path operations* 만듀Ʞ { #path-operations-with-apirouter } + +ê·ž 닀음 읎륌 사용핎 *path operations*륌 선얞합니닀. + +`FastAPI` 큎래슀륌 사용할 때와 동음한 방식윌로 사용합니닀: + +{* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[6,11,16] title["app/routers/users.py"] *} + +`APIRouter`는 "믞니 `FastAPI`" 큎래슀띌고 생각할 수 있습니닀. + +동음한 옵션듀읎 몚두 지원됩니닀. + +동음한 `parameters`, `responses`, `dependencies`, `tags` 등등. + +/// tip | 팁 + +읎 예시에서는 변수 읎늄읎 `router`읎지만, 원하는 읎늄윌로 지얎도 됩니닀. + +/// + +읎제 읎 `APIRouter`륌 메읞 `FastAPI` 앱에 포핚(include)할 것읎지만, 뚌저 dependencies와 닀륞 `APIRouter` 하나륌 확읞핎 볎겠습니닀. + +## Dependencies { #dependencies } + +애플늬쌀읎션의 여러 위치에서 사용되는 dependencies가 음부 필요하닀는 것을 알 수 있습니닀. + +귞래서 읎륌 별도의 `dependencies` 몚듈(`app/dependencies.py`)에 둡니닀. + +읎제 ê°„ë‹ší•œ dependency륌 사용핎 컀슀텀 `X-Token` 헀더륌 읜얎 볎겠습니닀: + +{* ../../docs_src/bigger_applications/app_an_py39/dependencies.py hl[3,6:8] title["app/dependencies.py"] *} + +/// tip | 팁 + +읎 예시륌 닚순화하Ʞ 위핎 임의로 만든 헀더륌 사용하고 있습니닀. + +하지만 싀제 상황에서는 통합된 [Security 유틞늬티](security/index.md){.internal-link target=_blank}륌 사용하는 것읎 더 좋은 결곌륌 얻을 수 있습니닀. + +/// + +## `APIRouter`가 있는 또 닀륞 몚듈 { #another-module-with-apirouter } + +애플늬쌀읎션의 "items"륌 처늬하는 전용 endpoint듀도 `app/routers/items.py` 몚듈에 있닀고 핎뎅시닀. + +여Ʞ에는 닀음에 대한 *path operations*가 있습니닀: + +* `/items/` +* `/items/{item_id}` + +구조는 `app/routers/users.py`와 완전히 동음합니닀. + +하지만 우늬는 조ꞈ 더 똑똑하게, 윔드륌 앜간 닚순화하고 싶습니닀. + +읎 몚듈의 몚든 *path operations*에는 닀음읎 동음하게 적용됩니닀: + +* 겜로 `prefix`: `/items`. +* `tags`: (태귞 하나: `items`). +* 추가 `responses`. +* `dependencies`: 몚두 우늬가 만든 `X-Token` dependency가 필요합니닀. + +따띌서 각 *path operation*마닀 맀번 몚두 추가하는 대신, `APIRouter`에 한 번에 추가할 수 있습니닀. + +{* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[5:10,16,21] title["app/routers/items.py"] *} + +각 *path operation*의 겜로는 닀음처럌 `/`로 시작핎알 하므로: + +```Python hl_lines="1" +@router.get("/{item_id}") +async def read_item(item_id: str): + ... +``` + +...prefix에는 마지막 `/`가 포핚되멎 안 됩니닀. + +따띌서 읎 겜우 prefix는 `/items`입니닀. + +또한 읎 router에 포핚된 몚든 *path operations*에 적용될 `tags` 목록곌 추가 `responses`도 넣을 수 있습니닀. + +귞늬고 router의 몚든 *path operations*에 추가될 `dependencies` 목록도 추가할 수 있윌며, 핎당 겜로듀로 듀얎였는 각 요청마닀 싀행/핎결됩니닀. + +/// tip | 팁 + +[*path operation decorator의 dependencies*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}와 마찬가지로, *path operation function*에 ì–Žë–€ 값도 전달되지 않습니닀. + +/// + +최종적윌로 item 겜로는 닀음곌 같습니닀: + +* `/items/` +* `/items/{item_id}` + +...의도한 귞대로입니닀. + +* 닚음 묞자엎 `"items"`륌 포핚하는 태귞 목록윌로 표시됩니닀. + * 읎 "tags"는 자동 대화형 묞서 시슀템(OpenAPI 사용)에 특히 유용합니닀. +* 몚두 믞늬 정의된 `responses`륌 포핚합니닀. +* 읎 몚든 *path operations*는 싀행되Ʞ 전에 `dependencies` 목록읎 평가/싀행됩니닀. + * 특정 *path operation*에 dependencies륌 추가로 선얞하멎 **귞것듀도 싀행됩니닀**. + * router dependencies가 뚌저 싀행되고, ê·ž 닀음에 [decorator의 `dependencies`](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, 귞늬고 음반 파띌믞터 dependencies가 싀행됩니닀. + * [`scopes`가 있는 `Security` dependencies](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}도 추가할 수 있습니닀. + +/// tip | 팁 + +`APIRouter`에 `dependencies`륌 두는 것은 예륌 듀얎 전첎 *path operations* 귞룹에 읞슝을 요구할 때 사용할 수 있습니닀. 각 겜로 처늬에 개별적윌로 dependencies륌 추가하지 않아도 됩니닀. + +/// + +/// check | 확읞 + +`prefix`, `tags`, `responses`, `dependencies` 파띌믞터는 (닀륞 많은 겜우와 마찬가지로) 윔드 쀑복을 플하도록 도와죌는 **FastAPI**의 Ʞ능입니닀. + +/// + +### dependencies import하Ʞ { #import-the-dependencies } + +읎 윔드는 몚듈 `app.routers.items`, 파음 `app/routers/items.py`에 있습니닀. + +귞늬고 dependency 핚수는 몚듈 `app.dependencies`, 파음 `app/dependencies.py`에서 가젞와알 합니닀. + +귞래서 dependencies에 대핮 `..`륌 사용하는 상대 import륌 사용합니닀: + +{* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[3] title["app/routers/items.py"] *} + +#### 상대 import가 동작하는 방식 { #how-relative-imports-work } + +/// tip | 팁 + +import가 동작하는 방식을 완벜히 알고 있닀멎, 아래 닀음 섹션윌로 넘얎가섞요. + +/// + +닀음곌 같읎 점 하나 `.`륌 ì“°ë©Ž: + +```Python +from .dependencies import get_token_header +``` + +의믞는 닀음곌 같습니닀: + +* 읎 몚듈(파음 `app/routers/items.py`)읎 속한 같은 package(디렉터늬 `app/routers/`)에서 시작핎서... +* `dependencies` 몚듈(가상의 파음 `app/routers/dependencies.py`)을 ì°Ÿê³ ... +* ê·ž 안에서 핚수 `get_token_header`륌 import합니닀. + +하지만 ê·ž 파음은 졎재하지 않습니닀. dependencies는 `app/dependencies.py` 파음에 있습니닀. + +우늬 앱/파음 구조륌 닀시 떠올렀 볎섞요: + + + +--- + +닀음처럌 점 두 개 `..`륌 ì“°ë©Ž: + +```Python +from ..dependencies import get_token_header +``` + +의믞는 닀음곌 같습니닀: + +* 읎 몚듈(파음 `app/routers/items.py`)읎 속한 같은 package(디렉터늬 `app/routers/`)에서 시작핎서... +* 상위 package(디렉터늬 `app/`)로 올띌가고... +* ê·ž 안에서 `dependencies` 몚듈(파음 `app/dependencies.py`)을 ì°Ÿê³ ... +* ê·ž 안에서 핚수 `get_token_header`륌 import합니닀. + +읎렇게 하멎 제대로 동작합니닀! 🎉 + +--- + +같은 방식윌로 점 ì„ž 개 `...`륌 사용했닀멎: + +```Python +from ...dependencies import get_token_header +``` + +의믞는 닀음곌 같습니닀: + +* 읎 몚듈(파음 `app/routers/items.py`)읎 속한 같은 package(디렉터늬 `app/routers/`)에서 시작핎서... +* 상위 package(디렉터늬 `app/`)로 올띌가고... +* ê·ž package의 상위로 또 올띌가는데(상위 package가 없습니닀, `app`읎 최상위입니닀 😱)... +* ê·ž 안에서 `dependencies` 몚듈(파음 `app/dependencies.py`)을 ì°Ÿê³ ... +* ê·ž 안에서 핚수 `get_token_header`륌 import합니닀. + +읎는 `app/` 위쪜의 ì–Žë–€ package(자신의 `__init__.py` 파음 등을 가진)에 대한 ì°žì¡°ê°€ 됩니닀. 하지만 우늬는 귞런 것읎 없습니닀. 귞래서 읎 예시에서는 에러가 발생합니닀. 🚚 + +읎제 얎떻게 동작하는지 알았윌니, 앱읎 얌마나 복잡하든 상대 import륌 사용할 수 있습니닀. 🀓 + +### 컀슀텀 `tags`, `responses`, `dependencies` 추가하Ʞ { #add-some-custom-tags-responses-and-dependencies } + +`APIRouter`에 읎믞 prefix `/items`와 `tags=["items"]`륌 추가했Ʞ 때묞에 각 *path operation*에 읎륌 추가하지 않습니닀. + +하지만 특정 *path operation*에만 적용될 _추가_ `tags`륌 더할 수도 있고, ê·ž *path operation* 전용의 추가 `responses`도 넣을 수 있습니닀: + +{* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[30:31] title["app/routers/items.py"] *} + +/// tip | 팁 + +읎 마지막 겜로 처늬는 `["items", "custom"]` 태귞 조합을 갖게 됩니닀. + +귞늬고 묞서에는 `404`용 응답곌 `403`용 응답, 두 가지 몚두가 표시됩니닀. + +/// + +## 메읞 `FastAPI` { #the-main-fastapi } + +읎제 `app/main.py` 몚듈을 뎅시닀. + +여Ʞ에서 `FastAPI` 큎래슀륌 import하고 사용합니닀. + +읎 파음은 몚든 것을 하나로 엮는 애플늬쌀읎션의 메읞 파음읎 될 것입니닀. + +귞늬고 대부분의 로직읎 각자의 특정 몚듈로 분늬되얎 있윌므로, 메읞 파음은 ꜀ 닚순핎집니닀. + +### `FastAPI` import하Ʞ { #import-fastapi } + +평소처럌 `FastAPI` 큎래슀륌 import하고 생성합니닀. + +또한 각 `APIRouter`의 dependencies와 결합될 [global dependencies](dependencies/global-dependencies.md){.internal-link target=_blank}도 ì„ ì–ží•  수 있습니닀: + +{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[1,3,7] title["app/main.py"] *} + +### `APIRouter` import하Ʞ { #import-the-apirouter } + +읎제 `APIRouter`가 있는 닀륞 submodule듀을 import합니닀: + +{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[4:5] title["app/main.py"] *} + +`app/routers/users.py`와 `app/routers/items.py` 파음은 같은 Python package `app`에 속한 submodule듀읎므로, 점 하나 `.`륌 사용핎 "상대 import"로 가젞올 수 있습니닀. + +### import가 동작하는 방식 { #how-the-importing-works } + +닀음 구묞은: + +```Python +from .routers import items, users +``` + +의믞는 닀음곌 같습니닀: + +* 읎 몚듈(파음 `app/main.py`)읎 속한 같은 package(디렉터늬 `app/`)에서 시작핎서... +* subpackage `routers`(디렉터늬 `app/routers/`)륌 ì°Ÿê³ ... +* ê·ž 안에서 submodule `items`(파음 `app/routers/items.py`)와 `users`(파음 `app/routers/users.py`)륌 import합니닀... + +`items` 몚듈에는 `router` 변수(`items.router`)가 있습니닀. 읎는 `app/routers/items.py` 파음에서 만든 것곌 동음하며 `APIRouter` 객첎입니닀. + +귞늬고 `users` 몚듈도 같은 방식입니닀. + +닀음처럌 import할 수도 있습니닀: + +```Python +from app.routers import items, users +``` + +/// info | 정볎 + +첫 번짞 버전은 "상대 import"입니닀: + +```Python +from .routers import items, users +``` + +두 번짞 버전은 "절대 import"입니닀: + +```Python +from app.routers import items, users +``` + +Python Packages와 Modules에 대핮 더 알아볎렀멎 Modules에 대한 Python 공식 묞서륌 읜얎볎섞요. + +/// + +### 읎늄 충돌 플하Ʞ { #avoid-name-collisions } + +submodule `items`륌 직접 import하고, ê·ž 안의 `router` 변수만 import하지는 않습니닀. + +읎는 submodule `users`에도 `router`띌는 읎늄의 변수가 있Ʞ 때묞입니닀. + +만앜 닀음처럌 순서대로 import했닀멎: + +```Python +from .routers.items import router +from .routers.users import router +``` + +`users`의 `router`가 `items`의 `router`륌 덮얎썚서 동시에 사용할 수 없게 됩니닀. + +따띌서 같은 파음에서 둘 ë‹€ 사용할 수 있도록 submodule듀을 직접 import합니닀: + +{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[5] title["app/main.py"] *} + +### `users`와 `items`용 `APIRouter` 포핚하Ʞ { #include-the-apirouters-for-users-and-items } + +읎제 submodule `users`와 `items`의 `router`륌 포핚핎 뎅시닀: + +{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[10:11] title["app/main.py"] *} + +/// info | 정볎 + +`users.router`는 `app/routers/users.py` 파음 안의 `APIRouter`륌 ë‹Žê³  있습니닀. + +`items.router`는 `app/routers/items.py` 파음 안의 `APIRouter`륌 ë‹Žê³  있습니닀. + +/// + +`app.include_router()`로 각 `APIRouter`륌 메읞 `FastAPI` 애플늬쌀읎션에 추가할 수 있습니닀. + +ê·ž router의 몚든 route가 애플늬쌀읎션의 음부로 포핚됩니닀. + +/// note Technical Details | Ʞ술 섞부사항 + +낎부적윌로는 `APIRouter`에 선얞된 각 *path operation*마닀 *path operation*을 싀제로 생성합니닀. + +슉, 낎부적윌로는 몚든 것읎 동음한 하나의 앱읞 것처럌 동작합니닀. + +/// + +/// check | 확읞 + +router륌 포핚(include)할 때 성능을 걱정할 필요는 없습니닀. + +읎 작업은 마읎크로쎈 닚위읎며 시작 시에만 발생합니닀. + +따띌서 성능에 영향을 죌지 않습니닀. ⚡ + +/// + +### 컀슀텀 `prefix`, `tags`, `responses`, `dependencies`로 `APIRouter` 포핚하Ʞ { #include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies } + +읎제 조직에서 `app/internal/admin.py` 파음을 받았닀고 가정핎 뎅시닀. + +여Ʞ에는 조직에서 여러 프로젝튞 간에 공유하는 ꎀ늬자용 *path operations*가 있는 `APIRouter`가 듀얎 있습니닀. + +읎 예시에서는 맀우 닚순하게 만듀겠습니닀. 하지만 조직 낮 닀륞 프로젝튞와 공유되Ʞ 때묞에, 읎륌 수정할 수 없얎 `prefix`, `dependencies`, `tags` 등을 `APIRouter`에 직접 추가할 수 없닀고 핎뎅시닀: + +{* ../../docs_src/bigger_applications/app_an_py39/internal/admin.py hl[3] title["app/internal/admin.py"] *} + +하지만 `APIRouter`륌 포핚할 때 컀슀텀 `prefix`륌 지정핎 몚든 *path operations*가 `/admin`윌로 시작하게 하고, 읎 프로젝튞에서 읎믞 가진 `dependencies`로 볎혞하고, `tags`와 `responses`도 포핚하고 싶습니닀. + +원래 `APIRouter`륌 수정하지 않고도 `app.include_router()`에 파띌믞터륌 전달핎서 읎륌 ì„ ì–ží•  수 있습니닀: + +{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[14:17] title["app/main.py"] *} + +읎렇게 하멎 원래 `APIRouter`는 수정되지 않윌므로, 조직 낮 닀륞 프로젝튞에서도 동음한 `app/internal/admin.py` 파음을 계속 공유할 수 있습니닀. + +결곌적윌로 우늬 앱에서 `admin` 몚듈의 각 *path operations*는 닀음을 갖게 됩니닀: + +* prefix `/admin`. +* tag `admin`. +* dependency `get_token_header`. +* 응답 `418`. 🍵 + +하지만 읎는 우늬 앱에서 ê·ž `APIRouter`에만 영향을 죌며, 읎륌 사용하는 닀륞 윔드에는 영향을 죌지 않습니닀. + +따띌서 닀륞 프로젝튞듀은 같은 `APIRouter`륌 닀륞 읞슝 방식윌로 사용할 수도 있습니닀. + +### *path operation* 포핚하Ʞ { #include-a-path-operation } + +*path operations*륌 `FastAPI` 앱에 직접 추가할 수도 있습니닀. + +여Ʞ서는 가능하닀는 것을 볎여죌Ʞ 위핎... 귞냥 핎뎅니닀 🀷: + +{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[21:23] title["app/main.py"] *} + +귞늬고 `app.include_router()`로 추가한 닀륞 몚든 *path operations*와 핚께 올바륎게 동작합니닀. + +/// info | 정볎 + +**ì°žê³ **: 읎는 맀우 Ʞ술적읞 섞부사항읎띌 아마 **귞냥 걎너뛰얎도 됩니닀**. + +--- + +`APIRouter`는 "mount"되는 것읎 아니며, 애플늬쌀읎션의 나뚞지 부분곌 격늬되얎 있지 않습니닀. + +읎는 OpenAPI 슀킀마와 사용자 읞터페읎슀에 귞듀의 *path operations*륌 포핚시킀고 싶Ʞ 때묞입니닀. + +나뚞지와 독늜적윌로 격늬핎 "mount"할 수 없윌므로, *path operations*는 직접 포핚되는 것읎 아니띌 "clone"(재생성)됩니닀. + +/// + +## 자동 API 묞서 확읞하Ʞ { #check-the-automatic-api-docs } + +읎제 앱을 싀행하섞요: + +
+ +```console +$ fastapi dev app/main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +귞늬고 http://127.0.0.1:8000/docs에서 묞서륌 여섞요. + +올바륞 겜로(및 prefix)와 올바륞 태귞륌 사용핎, 몚든 submodule의 겜로륌 포핚한 자동 API 묞서륌 볌 수 있습니닀: + + + +## 같은 router륌 닀륞 `prefix`로 여러 번 포핚하Ʞ { #include-the-same-router-multiple-times-with-different-prefix } + +`.include_router()`륌 사용핎 *같은* router륌 서로 닀륞 prefix로 여러 번 포핚할 수도 있습니닀. + +예륌 듀얎 `/api/v1`곌 `/api/latest`처럌 서로 닀륞 prefix로 동음한 API륌 녞출할 때 유용할 수 있습니닀. + +읎는 고꞉ 사용 방식읎띌 싀제로 필요하지 않을 수도 있지만, 필요할 때륌 위핎 제공됩니닀. + +## `APIRouter`에 닀륞 `APIRouter` 포핚하Ʞ { #include-an-apirouter-in-another } + +`APIRouter`륌 `FastAPI` 애플늬쌀읎션에 포핚할 수 있는 것곌 같은 방식윌로, 닀음을 사용핎 `APIRouter`륌 닀륞 `APIRouter`에 포핚할 수 있습니닀: + +```Python +router.include_router(other_router) +``` + +`FastAPI` 앱에 `router`륌 포핚하Ʞ 전에 수행핎알 하며, 귞래알 `other_router`의 *path operations*도 핚께 포핚됩니닀. diff --git a/docs/ko/docs/tutorial/body-updates.md b/docs/ko/docs/tutorial/body-updates.md new file mode 100644 index 0000000000..3719e1ffab --- /dev/null +++ b/docs/ko/docs/tutorial/body-updates.md @@ -0,0 +1,100 @@ +# Body - 업데읎튞 { #body-updates } + +## `PUT`윌로 교첎 업데읎튞하Ʞ { #update-replacing-with-put } + +항목을 업데읎튞하렀멎 HTTP `PUT` 작업을 사용할 수 있습니닀. + +`jsonable_encoder`륌 사용핎 입력 데읎터륌 JSON윌로 저장할 수 있는 데읎터로 변환할 수 있습니닀(예: NoSQL 데읎터베읎슀 사용 시). 예륌 듀얎 `datetime`을 `str`로 변환하는 겜우입니닀. + +{* ../../docs_src/body_updates/tutorial001_py310.py hl[28:33] *} + +`PUT`은 êž°ì¡Ž 데읎터륌 **대첎**í•Žì•Œ 하는 데읎터륌 받는 데 사용합니닀. + +### 대첎 시 죌의사항 { #warning-about-replacing } + +슉, `PUT`윌로 항목 `bar`륌 업데읎튞하멎서 닀음곌 같은 body륌 볎낞닀멎: + +```Python +{ + "name": "Barz", + "price": 3, + "description": None, +} +``` + +읎믞 저장된 속성 `"tax": 20.2`가 포핚되얎 있지 ì•Šêž° 때묞에, 입력 몚덞은 `"tax": 10.5`띌는 Ʞ볞값을 사용하게 됩니닀. + +귞늬고 데읎터는 ê·ž “새로욎” `tax` 값 `10.5`로 저장됩니닀. + +## `PATCH`로 부분 업데읎튞하Ʞ { #partial-updates-with-patch } + +HTTP `PATCH` 작업을 사용핎 데읎터륌 *부분적윌로* 업데읎튞할 수도 있습니닀. + +읎는 업데읎튞하렀는 데읎터만 볎낎고, 나뚞지는 귞대로 두는 것을 의믞합니닀. + +/// note | ì°žê³  + +`PATCH`는 `PUT`볎닀 덜 음반적윌로 사용되고 덜 알렀젞 있습니닀. + +귞늬고 많은 팀읎 부분 업데읎튞에도 `PUT`만 사용합니닀. + +여러분은 원하는 방식윌로 **자유롭게** 사용할 수 있윌며, **FastAPI**는 ì–Žë–€ 제한도 강제하지 않습니닀. + +닀만 읎 가읎드는 의도된 사용 방식읎 대략 얎떻게 되는지륌 볎여쀍니닀. + +/// + +### Pydantic의 `exclude_unset` 파띌믞터 사용하Ʞ { #using-pydantics-exclude-unset-parameter } + +부분 업데읎튞륌 받윌렀멎 Pydantic 몚덞의 `.model_dump()`에서 `exclude_unset` 파띌믞터륌 사용하는 것읎 맀우 유용합니닀. + +예: `item.model_dump(exclude_unset=True)`. + +읎는 `item` 몚덞을 만듀 때 싀제로 섀정된 데읎터만 포핚하는 `dict`륌 생성하고, Ʞ볞값은 제왞합니닀. + +ê·ž 닀음 읎륌 사용핎 (요청에서 전송되얎) 섀정된 데읎터만 포핚하고 Ʞ볞값은 생략한 `dict`륌 만듀 수 있습니닀: + +{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *} + +### Pydantic의 `update` 파띌믞터 사용하Ʞ { #using-pydantics-update-parameter } + +읎제 `.model_copy()`륌 사용핎 êž°ì¡Ž 몚덞의 복사볞을 만듀고, 업데읎튞할 데읎터가 듀얎있는 `dict`륌 `update` 파띌믞터로 전달할 수 있습니닀. + +예: `stored_item_model.model_copy(update=update_data)`: + +{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *} + +### 부분 업데읎튞 요앜 { #partial-updates-recap } + +정늬하멎, 부분 업데읎튞륌 적용하렀멎 닀음을 수행합니닀: + +* (선택 사항) `PUT` 대신 `PATCH`륌 사용합니닀. +* 저장된 데읎터륌 조회합니닀. +* ê·ž 데읎터륌 Pydantic 몚덞에 넣습니닀. +* 입력 몚덞에서 Ʞ볞값읎 제왞된 `dict`륌 생성합니닀(`exclude_unset` 사용). + * 읎렇게 하멎 몚덞의 Ʞ볞값윌로 읎믞 저장된 값을 덮얎쓰지 않고, 사용자가 싀제로 섀정한 값만 업데읎튞할 수 있습니닀. +* 저장된 몚덞의 복사볞을 만듀고, 받은 부분 업데읎튞로 핎당 속성듀을 갱신합니닀(`update` 파띌믞터 사용). +* 복사한 몚덞을 DB에 저장할 수 있는 형태로 변환합니닀(예: `jsonable_encoder` 사용). + * 읎는 몚덞의 `.model_dump()` 메서드륌 닀시 사용하는 것곌 비슷하지만, JSON윌로 변환 가능한 데읎터 타입윌로 값읎 확싀히 변환되도록 볎장합니닀(예: `datetime` → `str`). +* 데읎터륌 DB에 저장합니닀. +* 업데읎튞된 몚덞을 반환합니닀. + +{* ../../docs_src/body_updates/tutorial002_py310.py hl[28:35] *} + +/// tip | 팁 + +동음한 Ʞ법을 HTTP `PUT` 작업에서도 싀제로 사용할 수 있습니닀. + +하지만 여Ʞ의 예시는 읎런 사용 사례륌 위핎 만듀얎진 `PATCH`륌 사용합니닀. + +/// + +/// note | ì°žê³  + +입력 몚덞은 여전히 검슝된닀는 점에 유의하섞요. + +따띌서 몚든 속성을 생략할 수 있는 부분 업데읎튞륌 받윌렀멎, 몚든 속성읎 optional로 표시된(Ʞ볞값을 가지거나 `None`을 Ʞ볞값윌로 가지는) 몚덞읎 필요합니닀. + +**업데읎튞**륌 위한 “몚든 값읎 optional읞” 몚덞곌, **생성**을 위한 “필수 값읎 있는” 몚덞을 구분하렀멎 [추가 몚덞](extra-models.md){.internal-link target=_blank}에 섀명된 아읎디얎륌 사용할 수 있습니닀. + +/// diff --git a/docs/ko/docs/tutorial/dependencies/sub-dependencies.md b/docs/ko/docs/tutorial/dependencies/sub-dependencies.md new file mode 100644 index 0000000000..d81ccf00d0 --- /dev/null +++ b/docs/ko/docs/tutorial/dependencies/sub-dependencies.md @@ -0,0 +1,105 @@ +# 하위 의졎성 { #sub-dependencies } + +**하위 의졎성**을 가지는 의졎성을 만듀 수 있습니닀. + +필요한 만큌 **깊게** 쀑첩할 수도 있습니닀. + +읎것을 핎결하는 음은 **FastAPI**가 알아서 처늬합니닀. + +## 첫 번짞 의졎성 "dependable" { #first-dependency-dependable } + +닀음곌 같읎 첫 번짞 의졎성("dependable")을 만듀 수 있습니닀: + +{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[8:9] *} + +읎 의졎성은 선택적 쿌늬 파띌믞터 `q`륌 `str`로 선얞하고, 귞대로 반환합니닀. + +맀우 닚순한 예시(귞닀지 유용하진 않음)읎지만, 하위 의졎성읎 얎떻게 동작하는지에 집쀑하는 데 도움읎 됩니닀. + +## 두 번짞 의졎성 "dependable"곌 "dependant" { #second-dependency-dependable-and-dependant } + +귞닀음, 또 닀륞 의졎성 핚수("dependable")륌 만듀 수 있는데, 읎 핚수는 동시에 자Ʞ 자신의 의졎성도 선얞합니닀(귞래서 "dependant"읎Ʞ도 합니닀): + +{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[13] *} + +선얞된 파띌믞터륌 삎펎볎겠습니닀: + +* 읎 핚수 자첎가 의졎성("dependable")읎지만, 닀륞 의졎성도 하나 선얞합니닀(슉, 닀륞 묎얞가에 "의졎"합니닀). + * `query_extractor`에 의졎하며, ê·ž 반환값을 파띌믞터 `q`에 할당합니닀. +* 또한 선택적 `last_query` 쿠킀륌 `str`로 선얞합니닀. + * 사용자가 쿌늬 `q`륌 제공하지 않았닀멎, 읎전에 쿠킀에 저장핎 둔 마지막 쿌늬륌 사용합니닀. + +## 의졎성 사용하Ʞ { #use-the-dependency } + +귞닀음 닀음곌 같읎 의졎성을 사용할 수 있습니닀: + +{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[23] *} + +/// info | 정볎 + +*겜로 처늬 핚수*에서는 `query_or_cookie_extractor`띌는 의졎성 하나만 선얞하고 있닀는 점에 죌목하섞요. + +하지만 **FastAPI**는 `query_or_cookie_extractor`륌 혞출하는 동안 ê·ž 결곌륌 전달하Ʞ 위핎, 뚌저 `query_extractor`륌 í•Žê²°í•Žì•Œ 한닀는 것을 알고 있습니닀. + +/// + +```mermaid +graph TB + +query_extractor(["query_extractor"]) +query_or_cookie_extractor(["query_or_cookie_extractor"]) + +read_query["/items/"] + +query_extractor --> query_or_cookie_extractor --> read_query +``` + +## 같은 의졎성을 여러 번 사용하Ʞ { #using-the-same-dependency-multiple-times } + +같은 *겜로 처늬*에 대핮 의졎성 쀑 하나가 여러 번 선얞되는 겜우(예: 여러 의졎성읎 공통 하위 의졎성을 갖는 겜우), **FastAPI**는 ê·ž 하위 의졎성을 요청당 한 번만 혞출핎알 한닀는 것을 알고 있습니닀. + +귞늬고 같은 요청에 대핮 동음한 의졎성을 여러 번 혞출하는 대신, 반환값을 "cache"에 저장하고, ê·ž 요청에서 핎당 값읎 필요한 몚든 "dependants"에 전달합니닀. + +고꞉ 시나늬였로, 같은 요청에서 "cached" 값을 쓰는 대신 맀 닚계마닀(아마도 여러 번) 의졎성읎 혞출되얎알 한닀는 것을 알고 있닀멎, `Depends`륌 사용할 때 `use_cache=False` 파띌믞터륌 섀정할 수 있습니닀: + +//// tab | Python 3.9+ + +```Python hl_lines="1" +async def needy_dependency(fresh_value: Annotated[str, Depends(get_value, use_cache=False)]): + return {"fresh_value": fresh_value} +``` + +//// + +//// tab | Python 3.9+ 비 Annotated + +/// tip | 팁 + +가능하닀멎 `Annotated` 버전을 사용하는 것을 권장합니닀. + +/// + +```Python hl_lines="1" +async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False)): + return {"fresh_value": fresh_value} +``` + +//// + +## 정늬 { #recap } + +여Ʞ서 사용한 귞럎듯한 용얎듀을 제왞하멎, **Dependency Injection** 시슀템은 ꜀ 닚순합니닀. + +*겜로 처늬 핚수*와 같은 형태의 핚수듀음 뿐입니닀. + +하지만 여전히 맀우 강력하며, 임의로 깊게 쀑첩된 의졎성 "귞래프"(튞늬)륌 ì„ ì–ží•  수 있습니닀. + +/// tip | 팁 + +읎 닚순한 예시만 볎멎 귞닀지 유용핎 볎읎지 않을 수도 있습니닀. + +하지만 **볎안**에 ꎀ한 챕터에서 읎것읎 얌마나 유용한지 볎게 될 것입니닀. + +또한 얌마나 많은 윔드륌 아껎죌는지도 볎게 될 것입니닀. + +/// diff --git a/docs/ko/docs/tutorial/handling-errors.md b/docs/ko/docs/tutorial/handling-errors.md new file mode 100644 index 0000000000..7cc37e80c0 --- /dev/null +++ b/docs/ko/docs/tutorial/handling-errors.md @@ -0,0 +1,244 @@ +# 였류 처늬 { #handling-errors } + +API륌 사용하는 큎띌읎얞튞에 였류륌 알렀알 하는 상황은 많읎 있습니닀. + +읎 큎띌읎얞튞는 프론튞엔드가 있는 람띌우저음 수도 있고, 닀륞 사람읎 작성한 윔드음 수도 있고, IoT 장치음 수도 있습니닀. + +큎띌읎얞튞에 닀음곌 같은 낎용을 알렀알 할 수도 있습니닀: + +* 큎띌읎얞튞가 핎당 작업을 수행할 충분한 권한읎 없습니닀. +* 큎띌읎얞튞가 핎당 늬소슀에 접귌할 수 없습니닀. +* 큎띌읎얞튞가 접귌하렀고 한 항목읎 졎재하지 않습니닀. +* 등등. + +읎런 겜우 볎통 **400**번대(400에서 499) 범위의 **HTTP 상태 윔드**륌 반환합니닀. + +읎는 200번대 HTTP 상태 윔드(200에서 299)와 비슷합니닀. "200" 상태 윔드는 ì–Žë–€ 형태로든 요청읎 "성공"했음을 의믞합니닀. + +400번대 상태 윔드는 큎띌읎얞튞 잡에서 였류가 발생했음을 의믞합니닀. + +**"404 Not Found"** 였류(귞늬고 농닎듀)도 닀듀 Ʞ억하시죠? + +## `HTTPException` 사용하Ʞ { #use-httpexception } + +큎띌읎얞튞에 였류가 포핚된 HTTP 응답을 반환하렀멎 `HTTPException`을 사용합니닀. + +### `HTTPException` 가젞였Ʞ { #import-httpexception } + +{* ../../docs_src/handling_errors/tutorial001_py39.py hl[1] *} + +### 윔드에서 `HTTPException` 발생시킀Ʞ { #raise-an-httpexception-in-your-code } + +`HTTPException`은 API와 ꎀ렚된 추가 데읎터륌 가진 음반적읞 Python 예왞입니닀. + +Python 예왞읎므로 `return` 하는 것읎 아니띌 `raise` 합니닀. + +읎는 또한, *겜로 처늬 핚수* 낎부에서 혞출하는 유틞늬티 핚수 안에서 `HTTPException`을 `raise`하멎, *겜로 처늬 핚수*의 나뚞지 윔드는 싀행되지 않고 슉시 핎당 요청읎 종료되며 `HTTPException`의 HTTP 였류가 큎띌읎얞튞로 전송된닀는 뜻입니닀. + +값을 반환하는 것볎닀 예왞륌 발생시킀는 것의 읎점은 의졎성곌 볎안에 대한 섹션에서 더 분명핎집니닀. + +읎 예시에서는, 큎띌읎얞튞가 졎재하지 않는 ID로 항목을 요청하멎 상태 윔드 `404`로 예왞륌 발생시킵니닀: + +{* ../../docs_src/handling_errors/tutorial001_py39.py hl[11] *} + +### 결곌 응답 { #the-resulting-response } + +큎띌읎얞튞가 `http://example.com/items/foo`( `item_id` `"foo"`)륌 요청하멎, HTTP 상태 윔드 200곌 닀음 JSON 응답을 받습니닀: + +```JSON +{ + "item": "The Foo Wrestlers" +} +``` + +하지만 큎띌읎얞튞가 `http://example.com/items/bar`(졎재하지 않는 `item_id` `"bar"`)륌 요청하멎, HTTP 상태 윔드 404("not found" 였류)와 닀음 JSON 응답을 받습니닀: + +```JSON +{ + "detail": "Item not found" +} +``` + +/// tip | 팁 + +`HTTPException`을 발생시킬 때 `detail` 파띌믞터로 `str`만 전달할 수 있는 것읎 아니띌, JSON윌로 변환할 수 있는 ì–Žë–€ 값읎든 전달할 수 있습니닀. + +`dict`, `list` 등을 전달할 수 있습니닀. + +읎듀은 **FastAPI**가 자동윌로 처늬핎 JSON윌로 변환합니닀. + +/// + +## 컀슀텀 헀더 추가하Ʞ { #add-custom-headers } + +HTTP 였류에 컀슀텀 헀더륌 추가할 수 있윌멎 유용한 상황읎 있습니닀. 예륌 듀얎 특정 볎안 유형에서 귞렇습니닀. + +아마 윔드에서 직접 사용할 음은 거의 없을 것입니닀. + +하지만 고꞉ 시나늬였에서 필요하닀멎 컀슀텀 헀더륌 추가할 수 있습니닀: + +{* ../../docs_src/handling_errors/tutorial002_py39.py hl[14] *} + +## 컀슀텀 예왞 핞듀러 섀치하Ʞ { #install-custom-exception-handlers } + +Starlette의 동음한 예왞 유틞늬티륌 사용핎 컀슀텀 예왞 핞듀러륌 추가할 수 있습니닀. + +여러분(또는 사용하는 띌읎람러늬)읎 `raise`할 수 있는 컀슀텀 예왞 `UnicornException`읎 있닀고 가정핎 뎅시닀. + +귞늬고 읎 예왞륌 FastAPI에서 전역적윌로 처늬하고 싶닀고 핎뎅시닀. + +`@app.exception_handler()`로 컀슀텀 예왞 핞듀러륌 추가할 수 있습니닀: + +{* ../../docs_src/handling_errors/tutorial003_py39.py hl[5:7,13:18,24] *} + +여Ʞ서 `/unicorns/yolo`륌 요청하멎, *겜로 처늬*가 `UnicornException`을 `raise`합니닀. + +하지만 `unicorn_exception_handler`가 읎륌 처늬합니닀. + +따띌서 HTTP 상태 윔드 `418`곌 닀음 JSON 낎용을 가진 깔끔한 였류륌 받게 됩니닀: + +```JSON +{"message": "Oops! yolo did something. There goes a rainbow..."} +``` + +/// note | Ʞ술 섞부사항 + +`from starlette.requests import Request`와 `from starlette.responses import JSONResponse`륌 사용할 수도 있습니닀. + +**FastAPI**는 개발자의 펞의륌 위핎 `starlette.responses`륌 `fastapi.responses`로도 동음하게 제공합니닀. 하지만 사용 가능한 대부분의 응답은 Starlette에서 직접 옵니닀. `Request`도 마찬가지입니닀. + +/// + +## Ʞ볞 예왞 핞듀러 였버띌읎드하Ʞ { #override-the-default-exception-handlers } + +**FastAPI**에는 몇 가지 Ʞ볞 예왞 핞듀러가 있습니닀. + +읎 핞듀러듀은 `HTTPException`을 `raise`했을 때, 귞늬고 요청에 유횚하지 않은 데읎터가 있을 때 Ʞ볞 JSON 응답을 반환하는 역할을 합니닀. + +읎 예왞 핞듀러듀을 여러분의 것윌로 였버띌읎드할 수 있습니닀. + +### 요청 검슝 예왞 였버띌읎드하Ʞ { #override-request-validation-exceptions } + +요청에 유횚하지 않은 데읎터가 포핚되멎, **FastAPI**는 낎부적윌로 `RequestValidationError`륌 `raise`합니닀. + +귞늬고 읎에 대한 Ʞ볞 예왞 핞듀러도 포핚되얎 있습니닀. + +읎륌 였버띌읎드하렀멎 `RequestValidationError`륌 가젞였고, `@app.exception_handler(RequestValidationError)`로 예왞 핞듀러륌 데윔레읎튞핎 사용하섞요. + +예왞 핞듀러는 `Request`와 예왞륌 받습니닀. + +{* ../../docs_src/handling_errors/tutorial004_py39.py hl[2,14:19] *} + +읎제 `/items/foo`로 읎동하멎, 닀음곌 같은 Ʞ볞 JSON 였류 대신: + +```JSON +{ + "detail": [ + { + "loc": [ + "path", + "item_id" + ], + "msg": "value is not a valid integer", + "type": "type_error.integer" + } + ] +} +``` + +닀음곌 같은 텍슀튞 버전을 받게 됩니닀: + +``` +Validation errors: +Field: ('path', 'item_id'), Error: Input should be a valid integer, unable to parse string as an integer +``` + +### `HTTPException` 였류 핞듀러 였버띌읎드하Ʞ { #override-the-httpexception-error-handler } + +같은 방식윌로 `HTTPException` 핞듀러도 였버띌읎드할 수 있습니닀. + +예륌 듀얎, 읎런 였류듀에 대핮 JSON 대신 음반 텍슀튞 응답을 반환하고 싶을 수 있습니닀: + +{* ../../docs_src/handling_errors/tutorial004_py39.py hl[3:4,9:11,25] *} + +/// note | Ʞ술 섞부사항 + +`from starlette.responses import PlainTextResponse`륌 사용할 수도 있습니닀. + +**FastAPI**는 개발자의 펞의륌 위핎 `starlette.responses`륌 `fastapi.responses`로도 동음하게 제공합니닀. 하지만 사용 가능한 대부분의 응답은 Starlette에서 직접 옵니닀. + +/// + +/// warning | 겜고 + +`RequestValidationError`에는 검슝 였류가 발생한 파음 읎늄곌 쀄 정볎가 포핚되얎 있얎, 원한닀멎 ꎀ렚 정볎와 핚께 로귞에 표시할 수 있닀는 점을 유념하섞요. + +하지만 읎는 닚순히 묞자엎로 변환핎 ê·ž 정볎륌 귞대로 반환하멎 시슀템에 대한 음부 정볎륌 누섀할 수 있닀는 뜻읎Ʞ도 합니닀. 귞래서 여Ʞ의 윔드는 각 였류륌 독늜적윌로 추출핎 볎여쀍니닀. + +/// + +### `RequestValidationError`의 body 사용하Ʞ { #use-the-requestvalidationerror-body } + +`RequestValidationError`에는 유횚하지 않은 데읎터와 핚께 받은 `body`가 포핚됩니닀. + +앱을 개발하는 동안 body륌 로귞로 ë‚šêž°ê³  디버귞하거나, 사용자에게 반환하는 등윌로 사용할 수 있습니닀. + +{* ../../docs_src/handling_errors/tutorial005_py39.py hl[14] *} + +읎제 닀음처럌 유횚하지 않은 item을 볎낎볎섞요: + +```JSON +{ + "title": "towel", + "size": "XL" +} +``` + +받은 body륌 포핚핎 데읎터가 유횚하지 않닀고 알렀죌는 응답을 받게 됩니닀: + +```JSON hl_lines="12-15" +{ + "detail": [ + { + "loc": [ + "body", + "size" + ], + "msg": "value is not a valid integer", + "type": "type_error.integer" + } + ], + "body": { + "title": "towel", + "size": "XL" + } +} +``` + +#### FastAPI의 `HTTPException` vs Starlette의 `HTTPException` { #fastapis-httpexception-vs-starlettes-httpexception } + +**FastAPI**에는 자첎 `HTTPException`읎 있습니닀. + +귞늬고 **FastAPI**의 `HTTPException` 였류 큎래슀는 Starlette의 `HTTPException` 였류 큎래슀륌 상속합니닀. + +유음한 찚읎는 **FastAPI**의 `HTTPException`은 `detail` 필드에 JSON윌로 변환 가능한 ì–Žë–€ 데읎터든 받을 수 있는 반멎, Starlette의 `HTTPException`은 묞자엎만 받을 수 있닀는 점입니닀. + +따띌서 윔드에서는 평소처럌 **FastAPI**의 `HTTPException`을 계속 `raise`하멎 됩니닀. + +하지만 예왞 핞듀러륌 등록할 때는 Starlette의 `HTTPException`에 대핮 등록핎알 합니닀. + +읎렇게 하멎 Starlette 낎부 윔드의 ì–Žë–€ 부분, 또는 Starlette 확장/플러귞읞읎 Starlette `HTTPException`을 `raise`하더띌도, 여러분의 핞듀러가 읎륌 잡아서 처늬할 수 있습니닀. + +읎 예시에서는 동음한 윔드에서 두 `HTTPException`을 몚두 사용할 수 있도록, Starlette의 예왞륌 `StarletteHTTPException`윌로 읎늄을 바꿉니닀: + +```Python +from starlette.exceptions import HTTPException as StarletteHTTPException +``` + +### **FastAPI**의 예왞 핞듀러 재사용하Ʞ { #reuse-fastapis-exception-handlers } + +예왞륌 사용하멎서 **FastAPI**의 동음한 Ʞ볞 예왞 핞듀러도 핚께 사용하고 싶닀멎, `fastapi.exception_handlers`에서 Ʞ볞 예왞 핞듀러륌 가젞와 재사용할 수 있습니닀: + +{* ../../docs_src/handling_errors/tutorial006_py39.py hl[2:5,15,21] *} + +읎 예시에서는 맀우 표현력 있는 메시지로 였류륌 출력만 하고 있지만, 요지는 읎핎하셚을 겁니닀. 예왞륌 사용한 ë’€ Ʞ볞 예왞 핞듀러륌 귞대로 재사용할 수 있습니닀. diff --git a/docs/ko/docs/tutorial/security/first-steps.md b/docs/ko/docs/tutorial/security/first-steps.md new file mode 100644 index 0000000000..4c9181b31e --- /dev/null +++ b/docs/ko/docs/tutorial/security/first-steps.md @@ -0,0 +1,203 @@ +# 볎안 - 첫 닚계 { #security-first-steps } + +ì–Žë–€ 도메읞에 **backend** API가 있닀고 가정핎 볎겠습니닀. + +귞늬고 닀륞 도메읞에 **frontend**가 있거나, 같은 도메읞의 닀륞 겜로에 있거나(또는 몚바음 애플늬쌀읎션에 있을 수도 있습니닀). + +귞늬고 frontend가 **username**곌 **password**륌 사용핎 backend에 읞슝할 수 있는 방법읎 필요하닀고 핎뎅시닀. + +**FastAPI**와 핚께 **OAuth2**륌 사용핎서 읎륌 구현할 수 있습니닀. + +하지만 필요한 작은 정볎 조각듀을 ì°Ÿêž° 위핎 êžžê³  ꞎ 전첎 슀펙을 읜느띌 시간을 쓰지 않도록 하겠습니닀. + +볎안을 처늬하Ʞ 위핎 **FastAPI**가 제공하는 도구듀을 사용핎 뎅시닀. + +## 얎떻게 볎읎는지 { #how-it-looks } + +뚌저 윔드륌 귞냥 사용핎서 얎떻게 동작하는지 볎고, 귞닀음에 묎슚 음읎 음얎나는지 읎핎하러 닀시 돌아였겠습니닀. + +## `main.py` 만듀Ʞ { #create-main-py } + +예제륌 파음 `main.py`에 복사하섞요: + +{* ../../docs_src/security/tutorial001_an_py39.py *} + +## 싀행하Ʞ { #run-it } + +/// info | 정볎 + +`python-multipart` 팚킀지는 `pip install "fastapi[standard]"` 명령을 싀행하멎 **FastAPI**와 핚께 자동윌로 섀치됩니닀. + +하지만 `pip install fastapi` 명령을 사용하멎 `python-multipart` 팚킀지가 Ʞ볞윌로 포핚되지 않습니닀. + +수동윌로 섀치하렀멎, [가상 환겜](../../virtual-environments.md){.internal-link target=_blank}을 만듀고 활성화한 닀음, 아래로 섀치하섞요: + +```console +$ pip install python-multipart +``` + +읎는 **OAuth2**가 `username`곌 `password`륌 볎낎Ʞ 위핎 "form data"륌 사용하Ʞ 때묞입니닀. + +/// + +닀음윌로 예제륌 싀행하섞요: + +
+ +```console +$ fastapi dev main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +## 확읞하Ʞ { #check-it } + +대화형 묞서로 읎동하섞요: http://127.0.0.1:8000/docs. + +닀음곌 비슷한 화멎읎 볎음 것입니닀: + + + +/// check | Authorize 버튌! + +반짝읎는 새 "Authorize" 버튌읎 읎믞 있습니닀. + +귞늬고 *겜로 처늬*에는 였륞쪜 상닚에 큮멭할 수 있는 작은 자묌쇠가 있습니닀. + +/// + +귞늬고 읎륌 큎늭하멎 `username`곌 `password`(귞늬고 닀륞 선택적 필드듀)륌 입력할 수 있는 작은 읞슝 폌읎 나타납니닀: + + + +/// note | ì°žê³  + +폌에 묎엇을 입력하든 아직은 동작하지 않습니닀. 하지만 곧 여Ʞ까지 구현할 것입니닀. + +/// + +묌론 읎것은 최종 사용자륌 위한 frontend는 아니지만, 몚든 API륌 대화형윌로 묞서화하는 훌륭한 자동 도구입니닀. + +frontend 팀(귞게 볞읞음 수도 있습니닀)읎 사용할 수 있습니닀. + +서드파티 애플늬쌀읎션곌 시슀템에서도 사용할 수 있습니닀. + +귞늬고 동음한 애플늬쌀읎션을 디버귞하고, 확읞하고, 테슀튞하Ʞ 위핎 볞읞읎 사용할 수도 있습니닀. + +## `password` 플로우 { #the-password-flow } + +읎제 조ꞈ 돌아가서 읎것듀읎 묎엇읞지 읎핎핎 뎅시닀. + +`password` "flow"는 볎안곌 읞슝을 처늬하Ʞ 위핎 OAuth2에서 정의한 여러 방식("flows") 쀑 하나입니닀. + +OAuth2는 backend 또는 API가 사용자륌 읞슝하는 서버와 독늜적음 수 있도록 섀계되었습니닀. + +하지만 읎 겜우에는 같은 **FastAPI** 애플늬쌀읎션읎 API와 읞슝을 몚두 처늬합니닀. + +따띌서, 닚순화된 ꎀ점에서 닀시 정늬핎볎멎: + +* 사용자가 frontend에서 `username`곌 `password`륌 입력하고 `Enter`륌 누늅니닀. +* frontend(사용자의 람띌우저에서 싀행됚)는 핎당 `username`곌 `password`륌 우늬 API의 특정 URL로 볎냅니닀(`tokenUrl="token"`로 선얞됚). +* API는 `username`곌 `password`륌 확읞하고 "token"윌로 응답합니닀(아직 아묎것도 구현하지 않았습니닀). + * "token"은 나쀑에 읎 사용자륌 검슝하는 데 사용할 수 있는 ì–Žë–€ 낎용읎 닎ꞎ 묞자엎음 뿐입니닀. + * 볎통 token은 음정 시간읎 지나멎 만료되도록 섀정합니닀. + * 귞래서 사용자는 나쀑에 얎느 시점엔 닀시 로귞읞핎알 합니닀. + * 귞늬고 token읎 도난당하더띌도 위험읎 더 낮습니닀. 대부분의 겜우 영구적윌로 항상 동작하는 킀와는 닀늅니닀. +* frontend는 ê·ž token을 임시로 얎딘가에 저장합니닀. +* 사용자가 frontend에서 큎늭핎서 frontend 웹 앱의 닀륞 섹션윌로 읎동합니닀. +* frontend는 API에서 더 많은 데읎터륌 가젞와알 합니닀. + * 하지만 ê·ž 특정 endpoint에는 읞슝읎 필요합니닀. + * 귞래서 우늬 API에 읞슝하Ʞ 위핎 `Authorization` 헀더륌, 값은 `Bearer `에 token을 더한 형태로 볎냅니닀. + * token에 `foobar`가 듀얎 있닀멎 `Authorization` 헀더의 낎용은 `Bearer foobar`가 됩니닀. + +## **FastAPI**의 `OAuth2PasswordBearer` { #fastapis-oauth2passwordbearer } + +**FastAPI**는 읎런 볎안 Ʞ능을 구현하Ʞ 위핎, 서로 닀륞 추상화 수쀀에서 여러 도구륌 제공합니닀. + +읎 예제에서는 **OAuth2**의 **Password** 플로우와 **Bearer** token을 사용합니닀. 읎륌 위핎 `OAuth2PasswordBearer` 큎래슀륌 사용합니닀. + +/// info | 정볎 + +"bearer" token만읎 유음한 선택지는 아닙니닀. + +하지만 읎 사용 사례에는 가장 적합한 선택입니닀. + +또한 OAuth2 전묞가로서 왜 닀륞 옵션읎 더 적합한지 정확히 아는 겜우가 아니띌멎, 대부분의 사용 사례에도 가장 적합할 가능성읎 큜니닀. + +귞런 겜우륌 위핎서도 **FastAPI**는 읎륌 구성할 수 있는 도구륌 제공합니닀. + +/// + +`OAuth2PasswordBearer` 큎래슀의 읞슀턎슀륌 만듀 때 `tokenUrl` 파띌믞터륌 전달합니닀. 읎 파띌믞터에는 큎띌읎얞튞(사용자의 람띌우저에서 싀행되는 frontend)가 token을 받Ʞ 위핎 `username`곌 `password`륌 볎낌 URL읎 듀얎 있습니닀. + +{* ../../docs_src/security/tutorial001_an_py39.py hl[8] *} + +/// tip | 팁 + +여Ʞ서 `tokenUrl="token"`은 아직 만듀지 않은 상대 URL `token`을 가늬킵니닀. 상대 URL읎므로 `./token`곌 동음합니닀. + +상대 URL을 사용하므로, 예륌 듀얎 API가 `https://example.com/`에 있닀멎 `https://example.com/token`을 가늬킵니닀. 하지만 API가 `https://example.com/api/v1/`에 있닀멎 `https://example.com/api/v1/token`을 가늬킵니닀. + +상대 URL을 사용하는 것은 [프록시 뒀에서](../../advanced/behind-a-proxy.md){.internal-link target=_blank} 같은 고꞉ 사용 사례에서도 애플늬쌀읎션읎 계속 동작하도록 볎장하는 데 쀑요합니닀. + +/// + +읎 파띌믞터는 ê·ž endpoint / *겜로 처늬*륌 만듀지는 않지만, URL `/token`읎 큎띌읎얞튞가 token을 얻Ʞ 위핎 사용핎알 할 URL읎띌고 선얞합니닀. 읎 정볎는 OpenAPI에 사용되고, 읎얎서 대화형 API 묞서 시슀템에서도 사용됩니닀. + +곧 싀제 겜로 처늬륌 만듀 것입니닀. + +/// info | 정볎 + +엄격한 "Pythonista"띌멎 `token_url` 대신 `tokenUrl` 같은 파띌믞터 읎늄 슀타음읎 마음에 듀지 않을 수도 있습니닀. + +읎는 OpenAPI 슀펙에서 사용하는 읎늄곌 동음하게 맞춘 것읎Ʞ 때묞입니닀. 귞래서 읎런 볎안 슀킎에 대핮 더 조사핎알 할 때, 귞대로 복사핎서 붙여 넣얎 더 많은 정볎륌 찟을 수 있습니닀. + +/// + +`oauth2_scheme` 변수는 `OAuth2PasswordBearer`의 읞슀턎슀읎지만, "callable"읎Ʞ도 합니닀. + +닀음처럌 혞출될 수 있습니닀: + +```Python +oauth2_scheme(some, parameters) +``` + +따띌서 `Depends`와 핚께 사용할 수 있습니닀. + +### 사용하Ʞ { #use-it } + +읎제 `Depends`로 `oauth2_scheme`륌 의졎성에 전달할 수 있습니닀. + +{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *} + +읎 의졎성은 `str`을 제공하고, ê·ž 값은 *겜로 처늬 핚수*의 파띌믞터 `token`에 할당됩니닀. + +**FastAPI**는 읎 의졎성을 사용핎 OpenAPI 슀킀마(및 자동 API 묞서)에 "security scheme"륌 정의할 수 있닀는 것을 알게 됩니닀. + +/// info | Ʞ술 섞부사항 + +**FastAPI**는 (의졎성에 선얞된) `OAuth2PasswordBearer` 큎래슀륌 사용핎 OpenAPI에서 볎안 슀킎을 정의할 수 있닀는 것을 알고 있습니닀. 읎는 `OAuth2PasswordBearer`가 `fastapi.security.oauth2.OAuth2`륌 상속하고, 읎것읎 닀시 `fastapi.security.base.SecurityBase`륌 상속하Ʞ 때묞입니닀. + +OpenAPI(및 자동 API 묞서)와 통합되는 몚든 볎안 유틞늬티는 `SecurityBase`륌 상속하며, 귞래서 **FastAPI**가 읎륌 OpenAPI에 얎떻게 통합할지 알 수 있습니닀. + +/// + +## 묎엇을 하는지 { #what-it-does } + +요청에서 `Authorization` 헀더륌 ì°Ÿì•„, 값읎 `Bearer `에 ì–Žë–€ token읎 붙은 형태읞지 확읞한 ë’€, ê·ž token을 `str`로 반환합니닀. + +`Authorization` 헀더가 없거나, 값에 `Bearer ` token읎 없닀멎, 곧바로 401 상태 윔드 였류(`UNAUTHORIZED`)로 응답합니닀. + +였류륌 반환하Ʞ 위핎 token읎 졎재하는지 직접 확읞할 필요조찚 없습니닀. 핚수가 싀행되었닀멎 ê·ž token에는 `str`읎 듀얎 있닀고 확신할 수 있습니닀. + +대화형 묞서에서 읎믞 시도핎 볌 수 있습니닀: + + + +아직 token의 유횚성을 검슝하진 않지만, 읎것만윌로도 시작은 된 셈입니닀. + +## 요앜 { #recap } + +슉, 추가로 3~4쀄만윌로도 읎믞 원시적읞 형태의 볎안을 갖추게 됩니닀. diff --git a/docs/ko/docs/tutorial/security/index.md b/docs/ko/docs/tutorial/security/index.md new file mode 100644 index 0000000000..2320b06571 --- /dev/null +++ b/docs/ko/docs/tutorial/security/index.md @@ -0,0 +1,106 @@ +# 볎안 { #security } + +볎안, 읞슝(authentication), 읞가(authorization)륌 처늬하는 방법은 맀우 닀양합니닀. + +귞늬고 볎통 복잡하고 "얎렀욎" 죌제읎Ʞ도 합니닀. + +많은 프레임워크와 시슀템에서 볎안곌 읞슝만 처늬하는 데도 큰 녞력곌 윔드가 필요합니닀(많은 겜우 작성된 전첎 윔드의 50% 읎상읎 될 수도 있습니닀). + +**FastAPI**는 몚든 볎안 명섞륌 전부 공부하고 ë°°ìšž 필요 없읎, 표쀀적읞 방식윌로 쉜고 빠륎게 **볎안(Security)** 을 닀룰 수 있도록 여러 도구륌 제공합니닀. + +하지만 뚌저, 몇 가지 작은 개념을 확읞핎 볎겠습니닀. + +## ꞉하신가요? { #in-a-hurry } + +읎 용얎듀에 ꎀ심읎 없고 사용자명곌 비밀번혞 êž°ë°˜ 읞슝을 사용한 볎안을 *지ꞈ 당장* 추가하Ʞ만 하멎 된닀멎, 닀음 장듀로 넘얎가섞요. + +## OAuth2 { #oauth2 } + +OAuth2는 읞슝곌 읞가륌 처늬하는 여러 방법을 정의하는 명섞입니닀. + +상당히 방대한 명섞읎며 여러 복잡한 사용 사례륌 닀룹니닀. + +"제3자"륌 사용핎 읞슝하는 방법도 포핚합니닀. + +바로 `"Facebook, Google, X (Twitter), GitHub로 로귞읞"` 같은 시슀템듀읎 낎부적윌로 사용하는 방식입니닀. + +### OAuth 1 { #oauth-1 } + +OAuth 1도 있었는데, 읎는 OAuth2와 맀우 닀륎고 통신을 암혞화하는 방법까지 직접 명섞에 포핚했Ʞ 때묞에 더 복잡했습니닀. + +요슘에는 귞닀지 읞Ʞ 있거나 사용되지는 않습니닀. + +OAuth2는 통신을 얎떻게 암혞화할지는 명섞하지 않고, 애플늬쌀읎션읎 HTTPS로 제공될 것을 Ʞ대합니닀. + +/// tip | 팁 + +**배포**에 대한 섹션에서 Traefik곌 Let's Encrypt륌 사용핎 묎료로 HTTPS륌 섀정하는 방법을 볌 수 있습니닀. + +/// + +## OpenID Connect { #openid-connect } + +OpenID Connect는 **OAuth2**륌 Ʞ반윌로 한 또 닀륞 명섞입니닀. + +OAuth2에서 비교적 몚혞한 부분을 음부 구첎화하여 상혞 욎용성을 높읎렀는 확장입니닀. + +예륌 듀얎, Google 로귞읞은 OpenID Connect륌 사용합니닀(낎부적윌로는 OAuth2륌 사용). + +하지만 Facebook 로귞읞은 OpenID Connect륌 지원하지 않습니닀. 자첎적읞 변형의 OAuth2륌 사용합니닀. + +### OpenID("OpenID Connect"가 아님) { #openid-not-openid-connect } + +"OpenID"띌는 명섞도 있었습니닀. 읎는 **OpenID Connect**와 같은 묞제륌 핎결하렀고 했지만, OAuth2륌 Ʞ반윌로 하지 않았습니닀. + +따띌서 완전히 별도의 추가 시슀템읎었습니닀. + +요슘에는 귞닀지 읞Ʞ 있거나 사용되지는 않습니닀. + +## OpenAPI { #openapi } + +OpenAPI(읎전에는 Swagger로 알렀짐)는 API륌 구축하Ʞ 위한 공개 명섞입니닀(현재 Linux Foundation의 음부). + +**FastAPI**는 **OpenAPI**륌 Ʞ반윌로 합니닀. + +읎 덕분에 여러 자동 대화형 묞서 읞터페읎슀, 윔드 생성 등곌 같은 Ʞ능을 사용할 수 있습니닀. + +OpenAPI에는 여러 볎안 "scheme"을 정의하는 방법읎 있습니닀. + +읎륌 사용하멎 읎러한 대화형 묞서 시슀템을 포핚핎, 표쀀 êž°ë°˜ 도구듀을 몚두 활용할 수 있습니닀. + +OpenAPI는 닀음 볎안 scheme듀을 정의합니닀: + +* `apiKey`: 닀음에서 전달될 수 있는 애플늬쌀읎션 전용 í‚€: + * 쿌늬 파띌믞터 + * 헀더 + * ì¿ í‚€ +* `http`: 표쀀 HTTP 읞슝 시슀템, 예: + * `bearer`: `Authorization` 헀더에 `Bearer ` + 토큰 값을 넣는 방식. OAuth2에서 유래했습니닀. + * HTTP Basic 읞슝 + * HTTP Digest 등 +* `oauth2`: 볎안을 처늬하는 몚든 OAuth2 방식(읎륌 "flow"띌고 부늅니닀). + * 읎 flowë“€ 쀑 여러 개는 OAuth 2.0 읞슝 제공자(예: Google, Facebook, X (Twitter), GitHub 등)륌 구축하는 데 적합합니닀: + * `implicit` + * `clientCredentials` + * `authorizationCode` + * 하지만 같은 애플늬쌀읎션에서 직접 읞슝을 처늬하는 데 완벜하게 사용할 수 있는 특정 "flow"도 하나 있습니닀: + * `password`: 닀음 장듀에서 읎에 대한 예시륌 닀룹니닀. +* `openIdConnect`: OAuth2 읞슝 데읎터륌 자동윌로 탐색(discover)하는 방법을 정의합니닀. + * 읎 자동 탐색은 OpenID Connect 명섞에서 정의됩니닀. + + +/// tip | 팁 + +Google, Facebook, X (Twitter), GitHub 등 닀륞 읞슝/읞가 제공자륌 통합하는 것도 가능하며 비교적 쉜습니닀. + +가장 복잡한 묞제는 귞런 읞슝/읞가 제공자 자첎륌 구축하는 것읎지만, **FastAPI**는 얎렀욎 작업을 대신 처늬핎 죌멎서 읎륌 쉜게 할 수 있는 도구륌 제공합니닀. + +/// + +## **FastAPI** 유틞늬티 { #fastapi-utilities } + +FastAPI는 `fastapi.security` 몚듈에서 각 볎안 scheme에 대한 여러 도구륌 제공하며, 읎러한 볎안 메컀니슘을 더 쉜게 사용할 수 있게 핎쀍니닀. + +닀음 장듀에서는 **FastAPI**가 제공하는 도구륌 사용핎 API에 볎안을 추가하는 방법을 볎게 될 것입니닀. + +또한 대화형 묞서 시슀템에 얎떻게 자동윌로 통합되는지도 확읞하게 됩니닀. From 23bcfa094d9baefbf0150cbcddd1b77ec33a23fc Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 16 Jan 2026 11:54:26 +0000 Subject: [PATCH 012/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 233fdb7434..912f215f09 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -18,6 +18,7 @@ hide: ### Translations +* 🌐 Update translations for ko (add-missing). PR [#14699](https://github.com/fastapi/fastapi/pull/14699) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update translations for ko (update-outdated). PR [#14589](https://github.com/fastapi/fastapi/pull/14589) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update translations for uk (update-outdated). PR [#14587](https://github.com/fastapi/fastapi/pull/14587) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update translations for es (update-outdated). PR [#14686](https://github.com/fastapi/fastapi/pull/14686) by [@tiangolo](https://github.com/tiangolo). From fb15bba819a71df10fee28891c6c7c29fdf48d56 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Fri, 16 Jan 2026 03:57:08 -0800 Subject: [PATCH 013/108] =?UTF-8?q?=F0=9F=8C=90=20Update=20LLM=20prompt=20?= =?UTF-8?q?instructions=20file=20for=20French=20(#14618)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/fr/llm-prompt.md | 154 ++++++++++++++++++++++-------------------- 1 file changed, 79 insertions(+), 75 deletions(-) diff --git a/docs/fr/llm-prompt.md b/docs/fr/llm-prompt.md index 5ff18c4e8b..228500fe23 100644 --- a/docs/fr/llm-prompt.md +++ b/docs/fr/llm-prompt.md @@ -6,123 +6,127 @@ Language code: fr. ### Grammar to use when talking to the reader -Use the formal grammar (use «vous» instead of «tu»). +Use the formal grammar (use `vous` instead of `tu`). + +Additionally, in instructional sentences, prefer the present tense for obligations: + +- Prefer `vous devez 
` over `vous devrez 
`, unless the English source explicitly refers to a future requirement. + +- When translating “make sure (that) 
 is 
”, prefer the indicative after `vous assurer que` (e.g. `Vous devez vous assurer qu'il est 
`) instead of the subjunctive (e.g. `qu'il soit 
`). ### Quotes -1) Convert neutral double quotes («"») and English double typographic quotes («“» and «”») to French guillemets (««» and «»»). +- Convert neutral double quotes (`"`) to French guillemets (`«` and `»`). -2) In the French docs, guillemets are written without extra spaces: use «texte», not « texte ». - -3) Do not convert quotes inside code blocks, inline code, paths, URLs, or anything wrapped in backticks. +- Do not convert quotes inside code blocks, inline code, paths, URLs, or anything wrapped in backticks. Examples: - Source (English): +Source (English): - ««« - "Hello world" - “Hello Universe” - "He said: 'Hello'" - "The module is `__main__`" - »»» +``` +"Hello world" +“Hello Universe” +"He said: 'Hello'" +"The module is `__main__`" +``` - Result (French): +Result (French): - ««« - «Hello world» - «Hello Universe» - «He said: 'Hello'» - «The module is `__main__`» - »»» +``` +"Hello world" +“Hello Universe” +"He said: 'Hello'" +"The module is `__main__`" +``` ### Ellipsis -1) Make sure there is a space between an ellipsis and a word following or preceding the ellipsis. +- Make sure there is a space between an ellipsis and a word following or preceding the ellipsis. Examples: - Source (English): +Source (English): - ««« - ...as we intended. - ...this would work: - ...etc. - others... - More to come... - »»» +``` +...as we intended. +...this would work: +...etc. +others... +More to come... +``` - Result (French): +Result (French): - ««« - ... comme prévu. - ... cela fonctionnerait : - ... etc. - D'autres ... - La suite ... - »»» +``` +... comme prévu. +... cela fonctionnerait : +... etc. +D'autres ... +La suite ... +``` -2) This does not apply in URLs, code blocks, and code snippets. Do not remove or add spaces there. +- This does not apply in URLs, code blocks, and code snippets. Do not remove or add spaces there. ### Headings -1) Prefer translating headings using the infinitive form (as is common in the existing French docs): «Créer », «Utiliser », «Ajouter ». +- Prefer translating headings using the infinitive form (as is common in the existing French docs): `Créer
`, `Utiliser
`, `Ajouter
`. -2) For headings that are instructions written in imperative in English (e.g. “Go check 
”), keep them in imperative in French, using the formal grammar (e.g. «Allez voir  »). - -3) Keep heading punctuation as in the source. In particular, keep occurrences of literal « - » (space-hyphen-space) as « - » (the existing French docs use a hyphen here). +- For headings that are instructions written in imperative in English (e.g. `Go check 
`), keep them in imperative in French, using the formal grammar (e.g. `Allez voir 
`). ### French instructions about technical terms -Do not try to translate everything. In particular, keep common programming terms when that is the established usage in the French docs (e.g. «framework», «endpoint», «plug-in», «payload»). Use French where the existing docs already consistently use French (e.g. «requête», «réponse»). +Do not try to translate everything. In particular, keep common programming terms (e.g. `framework`, `endpoint`, `plug-in`, `payload`). Keep class names, function names, modules, file names, and CLI commands unchanged. ### List of English terms and their preferred French translations -Below is a list of English terms and their preferred French translations, separated by a colon («:»). Use these translations, do not use your own. If an existing translation does not use these terms, update it to use them. +Below is a list of English terms and their preferred French translations, separated by a colon (:). Use these translations, do not use your own. If an existing translation does not use these terms, update it to use them. -* «/// note | Technical Details»: «/// note | Détails techniques» -* «/// note»: «/// note | Remarque» -* «/// tip»: «/// tip | Astuce» -* «/// warning»: «/// warning | Attention» -* «/// check»: «/// check | vérifier» -* «/// info»: «/// info» +- /// note | Technical Details»: /// note | Détails techniques +- /// note: /// note | Remarque +- /// tip: /// tip | Astuce +- /// warning: /// warning | Alertes +- /// check: /// check | Vérifications +- /// info: /// info -* «the docs»: «les documents» -* «the documentation»: «la documentation» +- the docs: les documents +- the documentation: la documentation -* «framework»: «framework» (do not translate to «cadre») -* «performance»: «performance» +- Exclude from OpenAPI: Exclusion d'OpenAPI -* «type hints»: «annotations de type» -* «type annotations»: «annotations de type» +- framework: framework (do not translate to cadre) +- performance: performance -* «autocomplete»: «autocomplétion» -* «autocompletion»: «autocomplétion» +- type hints: annotations de type +- type annotations: annotations de type -* «the request» (what the client sends to the server): «la requête» -* «the response» (what the server sends back to the client): «la réponse» +- autocomplete: autocomplétion +- autocompletion: autocomplétion -* «the request body»: «le corps de la requête» -* «the response body»: «le corps de la réponse» +- the request (what the client sends to the server): la requête +- the response (what the server sends back to the client): la réponse -* «path operation»: «opération de chemin» -* «path operations» (plural): «opérations de chemin» -* «path operation function»: «fonction de chemin» -* «path operation decorator»: «décorateur d'opération de chemin» +- the request body: le corps de la requête +- the response body: le corps de la réponse -* «path parameter»: «paramÚtre de chemin» -* «query parameter»: «paramÚtre de requête» +- path operation: chemin d'accÚs +- path operations (plural): chemins d'accÚs +- path operation function: fonction de chemin d'accÚs +- path operation decorator: décorateur de chemin d'accÚs -* «the `Request`»: «`Request`» (keep as code identifier) -* «the `Response`»: «`Response`» (keep as code identifier) +- path parameter: paramÚtre de chemin +- query parameter: paramÚtre de requête -* «deployment»: «déploiement» -* «to upgrade»: «mettre à niveau» +- the `Request`: `Request` (keep as code identifier) +- the `Response`: `Response` (keep as code identifier) -* «deprecated»: «déprécié» -* «to deprecate»: «déprécier» +- deployment: déploiement +- to upgrade: mettre à niveau -* «cheat sheet»: «aide-mémoire» -* «plug-in»: «plug-in» +- deprecated: déprécié +- to deprecate: déprécier + +- cheat sheet: aide-mémoire +- plug-in: plug-in From 8fa635c718fe71fa2e761b7fb33978d756e77a45 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 16 Jan 2026 11:57:32 +0000 Subject: [PATCH 014/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 912f215f09..404a4e41d0 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -18,6 +18,7 @@ hide: ### Translations +* 🌐 Update LLM prompt instructions file for French. PR [#14618](https://github.com/fastapi/fastapi/pull/14618) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update translations for ko (add-missing). PR [#14699](https://github.com/fastapi/fastapi/pull/14699) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update translations for ko (update-outdated). PR [#14589](https://github.com/fastapi/fastapi/pull/14589) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update translations for uk (update-outdated). PR [#14587](https://github.com/fastapi/fastapi/pull/14587) by [@tiangolo](https://github.com/tiangolo). From 9fec72687f48db48d72bff6ba2aa023fe792206b Mon Sep 17 00:00:00 2001 From: Rafael de Oliveira Marques Date: Fri, 16 Jan 2026 09:27:02 -0300 Subject: [PATCH 015/108] =?UTF-8?q?=F0=9F=8C=90=20Update=20portuguese=20ll?= =?UTF-8?q?m-prompt.md=20(#14702)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Co-authored-by: Sofie Van Landeghem --- docs/pt/llm-prompt.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/pt/llm-prompt.md b/docs/pt/llm-prompt.md index 3f5208e910..dd72e8d168 100644 --- a/docs/pt/llm-prompt.md +++ b/docs/pt/llm-prompt.md @@ -10,6 +10,26 @@ Keep existing translations as they are if the term is already translated. When translating documentation into Portuguese, use neutral and widely understandable language. Although Portuguese originated in Portugal and has its largest number of speakers in Brazil, it is also an official language in several countries and regions, such as Equatorial Guinea, Mozambique, Angola, Cape Verde, and São Tomé and Príncipe. Avoid words or expressions that are specific to a single country or region. +Only keep parentheses if they exist in the source text. Do not add parentheses to terms that do not have them. + +### Avoiding Repetition in Translation + +When translating sentences, avoid unnecessary repetition of words or phrases that are implied in context. +- Merge repeated words naturally while keeping the meaning. +- Do **not** introduce extra words to replace repeated phrases unnecessarily. +- Keep translations fluent and concise, but maintain the original meaning. + +**Example:** + +Source: +Let's see how that works and how to change it if you need to do that. + +Avoid translating literally as: +Vamos ver como isso funciona e como alterar isso se você precisar fazer isso. + +Better translation: +Vamos ver como isso funciona e como alterar se você precisar. + --- For the next terms, use the following translations: @@ -22,10 +42,11 @@ For the next terms, use the following translations: * /// note: /// note | Nota * /// tip: /// tip | Dica * /// warning: /// warning | Atenção -* (you should): (você deveria) +* you should: você deveria * async context manager: gerenciador de contexto assíncrono * autocomplete: autocompletar * autocompletion: preenchimento automático +* auto-completion: preenchimento automático * bug: bug * context manager: gerenciador de contexto * cross domain: cross domain (do not translate to "domínio cruzado") From 0c7f2b66d769d05df42ea73f85205a3566ba127b Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 16 Jan 2026 12:27:29 +0000 Subject: [PATCH 016/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 404a4e41d0..d3f80fac93 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -18,6 +18,7 @@ hide: ### Translations +* 🌐 Update portuguese llm-prompt.md. PR [#14702](https://github.com/fastapi/fastapi/pull/14702) by [@ceb10n](https://github.com/ceb10n). * 🌐 Update LLM prompt instructions file for French. PR [#14618](https://github.com/fastapi/fastapi/pull/14618) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update translations for ko (add-missing). PR [#14699](https://github.com/fastapi/fastapi/pull/14699) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update translations for ko (update-outdated). PR [#14589](https://github.com/fastapi/fastapi/pull/14589) by [@tiangolo](https://github.com/tiangolo). From 536a5bafe74a77f207b57cf6fb0cf3059121fffb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Mon, 19 Jan 2026 12:40:17 -0800 Subject: [PATCH 017/108] =?UTF-8?q?=F0=9F=94=A7=20Update=20sponsors,=20Lam?= =?UTF-8?q?bdaTest=20changes=20to=20TestMu=20AI=20(#14734)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/data/sponsors.yml | 6 +++--- docs/en/docs/img/sponsors/testmu.png | Bin 0 -> 5725 bytes 2 files changed, 3 insertions(+), 3 deletions(-) create mode 100644 docs/en/docs/img/sponsors/testmu.png diff --git a/docs/en/data/sponsors.yml b/docs/en/data/sponsors.yml index 50b1145301..c0bdb15f63 100644 --- a/docs/en/data/sponsors.yml +++ b/docs/en/data/sponsors.yml @@ -65,9 +65,9 @@ bronze: # - url: https://testdriven.io/courses/tdd-fastapi/ # title: Learn to build high-quality web apps with best practices # img: https://fastapi.tiangolo.com/img/sponsors/testdriven.svg - - url: https://lambdatest.com/?utm_source=fastapi&utm_medium=partner&utm_campaign=sponsor&utm_term=opensource&utm_content=webpage - title: LambdaTest, AI-Powered Cloud-based Test Orchestration Platform - img: https://fastapi.tiangolo.com/img/sponsors/lambdatest.png + - url: https://www.testmu.ai/?utm_source=fastapi&utm_medium=partner&utm_campaign=sponsor&utm_term=opensource&utm_content=webpage + title: TestMu AI. The Native AI-Agentic Cloud Platform to Supercharge Quality Engineering. + img: https://fastapi.tiangolo.com/img/sponsors/testmu.png - url: https://requestly.com/fastapi title: All-in-one platform to Test, Mock and Intercept APIs. Built for speed, privacy and offline support. img: https://fastapi.tiangolo.com/img/sponsors/requestly.png diff --git a/docs/en/docs/img/sponsors/testmu.png b/docs/en/docs/img/sponsors/testmu.png new file mode 100644 index 0000000000000000000000000000000000000000..5603b04faed5e917bd0ea78f1684ba3c7a747718 GIT binary patch literal 5725 zcmd6L_cvT`w6`7vBf5#+iOyGzE?S}l(Pc#RE_x4%8iPa-MvdO0M2kK~8-hsG=msN1 z57FHx>-`7b-|n5Y&YZQ*oO#;bpR#wnfu1HgDU=ik2Zvl+OWhFM_rYaHOa#7LK6VU% z8;O^exepEw1?u00JK$Mn2Ocu|J}~n&@^tVGc=o~`Cmj+ zP#hfEEp2rb{ag3)7-z&_{!ZjqU!N$&bPpwh=N-56}#<+myBe0Py}CX z;uv^rh}3#TaU~cyVn{w9Da9Ujlf}e6!*dW-C;MM~^{wpiodNF@EjJ~|Bc4>$H5V0$ zOw#tzeRcwe&tJxlJUl$4wjnefPa%clo4#H8x52qbj+jrE84Iwdjw^|!q6u>Jq@9*f z(Tx{BW@lyjSYJ~*HU3oTvqw7PCB?-lo0z1Jh)10N$YZ+3R9k(aLL!l2xm|$=9HTk% z)7Z1gN>kL>*jT~d7Gxla8MQu~k+b{PIp0{|;9}|K>Hc!Zi*?fLljbh+A?X2cv(FCX zmseN(7b6Jix`4e!l`|G$Jbe6vQTaUs5j<65|DB)F=jXw(S8nqycV2wSzL}q&Ph^(& zml4uiO?*C@E!)eoxVT7h(e`3JK^GQreU#@uRa0JGcXv#AaAd@9=n7h)R&4k-E{=FB z1#M?C92^|{ZgRF(Nb?ZPwz&Zg1JIeCga@n zmm?pLO}X$nIX3oIx(IC16ZaksY5Um*!rzfA*S@{IT{K|V3Ss~K`}bP=VY-IqW{8pT zRFDT@=+4jo5Lit(l)Dxzab+m&9{#yv5{4}mtxOz=w!>q$Qw|r@DmLV!A;o!#v|%tX z@~Q43q0mWK^5Au&^k*b6i_1`t^et{>|xt zQjGll1guFnDl#L3zCW2Yd4J#Q^x^_FG6K)TxH>x{t1X)i%+2GIk|<)Y`UVC##l@+v zudgpJ3rs4bH42enZw8MaNA~w?bW#j>pRS8Upd*@ia;vHY8yXuQH|Z;$^?KX~89q2T z*!{`6jVXZ@$E3;(*VNQBc8G|8fQ^&$Rejp~_xU9y{SF=7-O5F!rAAGwtG1yxSAQu6 zoZtNZ?N&iJJ~NTNa{f`WQmS;t5AuSNk&y%j zgDH~qI7xmiEW~g2T+(>(fG{B;!R!2wv#+0DBu1uU*0Xx)1mtIyPB8oH<(azY-?opX zYEm&WYin!ywY8MVtV&HGu%4bCQO8lHwspbRuU`|l3c9LR4rxw#*B zjk-zQ{{BEVNeuw>@bIwK1{sBf8H+%n&@xFK5Y*kG7Ie`FB*mQliiO+-XLWz`&H z8%P03Y3Wy#c&x0f02FKj0tq)_1Ox;&3$1=F{yR_*?$cJ+=}!+HJtDiwq>LIG(s`ee zfw{iAz`;>cQsUy`V&mb7`HRJ3WBsJJ_~ZldPZv*}Bq{dlI^3-BZ*mHrO^`_8Fp zX=!C;W%>P#wzjsS-mB`NXX_a#XeD7O$?3)jLdJKKvcA5)N(#R(sjW>O92X@ORnHtT zJ0Cwkas?IZeZ2JqY!DwOG&GcwnHes<7>Ex7x_o4#nZy*|-hMyy>Uer{Yb(m4x?ey1 zka{Z~W?_-wKG#$La8u;0e3&6z%p&FRnei3{)3VZCG9o6$P=-_<-PJv~m9VCX$&?Yb=yLD;IN+Wa%iXxP zlF;gnI}k_VhK}bGWsmXlBCfV!7lKOQ06$J|mmk{O+uLnTl!r~l$HlRg>g9ag+B^>K z)N^yIVv7NEs(4jgQbKCW$H$jHR0ZpLx-20nIZ>hH`sLd|GAl1TJ9|+R#Kpx8J7*cPawVF7L6Bba)PD0+}pT3JK_@-)^K*_ zkN6Ydi~vt1m)Fp#??=Ro?cmwjOfKkbv|Z0)M@Zh#{IPP-PUCdh6fMr>QQl4Ot6LC0 zOKWRp9UUD$O9KN+hp}9RH8Bg+FZYG4EU4RTJ)w9e*{@%}K90ujpeM?W2%8Qt14chc zr#8PNevK-IOwP>2jgIPV4dmtKQWP7;$HWjdG&Ozf=wRO2*=dQmQH0*TdvJZRXQT^z zC^0unLr2FUFONuu16GE0T8S3ZP*FuSG)Pu>Jb6Mpng@X6O-^W7Zd~i7QuSPZ8ke-f?C<&84?zDe~&Epgjf_G^~Mn<0YiG<^(qF>*Fu;c^s28{d7NfPKEOZe%^ zE#oIoRw`>cq2DDt0iLZ|yl_7|jI6rX)zxWfYa>C12U!LO%l%iTNsI(QKR7*jK2G)& z&MZ#{f?nbV#v&#r?*5u7LAai#!`)yZq>;#goa52WdR59CPQz zuKYh?0s=B!0}HUQQV@f}XPP}(4ULS>q~U-{Ej>G;eXyfQJMm||ad!sM=z>)b7nh#8 z=L0cZB?TN35~)<2`*u%*F#Yhbsb33M-T?uc4h|bfoHjTu!N&ssjuU7|rM`F_Tbd3b zgiSo|k8FFDT!k4+Y%E^yyZHU&Gwtzj`o9iq5!|CyH zz?VSqTZrOm&ayio3#DXS?}S@;YK9abu&Sk7ad8?q|X-50WDUwZu2y++1Rnq;9Fk_$=yz#g>=H zZ{6BH4t85;o!s53lFXHu0<^x0#nlYAMy%cu|rB_jeq(yFMa5R;L;PELjx3(x{S zUf$bF1`%65o`zu&M*x4ava+YkuOKmQ6E~aVg=WA9H+Gq6Xb>r0{FXqz_*&C-{c|^X zD;IbV5<}^o;%Gd5e==`6z(-Mn5}MN47@4Fk3v(irI{z|o=9epwh+6ZFANooU08MKo zF*#2!{hs}Nuyk|XJa!ajPeo1$Aa^t({eDIR4vlVUk!c%-pirnf=N~*+dxa=#32rkpDW$2L}gI+bylFa_&PsAdoek z=K}U^fJgj)&#V~GYnL0ZHg{bKaj%-f!e|Q$3Q(;FuZ(!!GtW+p0=BKPY)-l#{AbW( z_VhHcRM+29{v0t_7kFT6E1p?)sF}>d4a{iR6fjNP@&UU=TVTd|;KuP@u3@o8*hf6n znNsdqBP~j&%lInHX*zv*&FO<;!GD}8JI{62HmyB=HaM%7{vi2O$P4gSx{9MrLmEAz zPEl?wpq1<7;=&;&CT4 zoc4*HWIWT!=I(BPXV}F)nl~@bTrGdbOYhZXSr8x0%4Y$*mD+2MRRTP5CT&J=m1d8YKDdm7gZvYES0&r`QY%d z&ro23YC-oq?uTXDqEI+Rb!yYMg$4N4#a|;&S5RWvq2E12sNOv(S_f=u1FFx!gFbq~ zpzbkoAt9l`v9ST5S%dnrAegH=%}f2j1wRI*L3%nJIQGDh5KM8#Q&krifkuhKai?CO zPU9031k317Yd=3fVsi5J;r5fCu3kPqsOa1D2BxOBs!eW3t48MMvvF~AKl@&!ZES@d z%_(f9K0ZE<3SZCq&ow10OXoPXva+(8N5D+2W*UP@R?>L!qJFZ=)YbJ~5{trCO3fmZ zoGseBA7lBOmppd+1M=0ZvnBdO@=HHBtyUT#mp&y)9^EUq?%_LLlckh{}ca1u)h=Y6LVKpd^Q#q7A_?v*f%bY*OZ0h zT0iIJv|U{**SpFijP;_wDD=POf=0Y?^FOma0rK=xA5toEg(l$3?gg&-*d z4haPX&s?)7udc4Hf6a81NhLRMf$ZMi-gpr%jahDUP1Ue#V)mkniUgqA*;-swLwV{P z?0|@OeN^J3ufYhjt$vltT5>r_MMXtsLVIy9aZ>HYkCUc5!t@1E8TnP~)tGo3}*7#ozs2 zXv>&y4>HMcM`LJz*Q&0221kQo42AN;_9A9Jc|!ss*eV*vC6}?nHtY0|Nt<1=3V&rVASz zX+bY$-6z3a_sHxrEj`_~=QRm~gag^0zHkQ0NpcnJ%E`@5U00V}*t*ruhqYv{>xKm( z?b)9J3y&9j-mhG2NK)TcQBh$d%1|5f*TV%`3cSC5*FRAV4_Cy)!wa<3*4ECu*&C`C zD97gi0M%Aiy3oCQYGGjto#$Kk67Nb=h_vtH-B(axPt*BVKLeCbOig`kXrM8zc?xv& zV?V|3ox(}^PYZ1UMomaJJx5W7l)OBV5BSY%#G!x2H7D}Z?a6u>y-vHP_iZvI9FrEp zQjG=DCYhlimH5quo>*Hea6McX1j%!HdTJom@iaLW!g?~70jd+wk^+4a+{{P)w`au5 zCSjoKw2Z~x(%0A5=^hywxw;+;2P(*^kw{sUAkIJ*c)DM}R*7Cz*#GmVh~R90MGb+# zoSmN=LMUD#ZT_xQ84KK@p&<|v5do8J`pPvlG~`!T!|5|Y&w`sY#QRV0+?=JC5Yr3?qW%ZABJ|Aw literal 0 HcmV?d00001 From db5441eba1d4c3bee11dac239a685e3c0630cda5 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 19 Jan 2026 20:40:38 +0000 Subject: [PATCH 018/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index d3f80fac93..8b338f60d0 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -30,6 +30,7 @@ hide: ### Internal +* 🔧 Update sponsors, LambdaTest changes to TestMu AI. PR [#14734](https://github.com/fastapi/fastapi/pull/14734) by [@tiangolo](https://github.com/tiangolo). * ⬆ Bump actions/cache from 4 to 5. PR [#14511](https://github.com/fastapi/fastapi/pull/14511) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump actions/upload-artifact from 5 to 6. PR [#14525](https://github.com/fastapi/fastapi/pull/14525) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump actions/download-artifact from 6 to 7. PR [#14526](https://github.com/fastapi/fastapi/pull/14526) by [@dependabot[bot]](https://github.com/apps/dependabot). From 463a3a24d7aee142bede2bcdd0ef542646b1fe3f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Mon, 19 Jan 2026 12:55:32 -0800 Subject: [PATCH 019/108] =?UTF-8?q?=F0=9F=94=A7=20Update=20sponsors:=20rem?= =?UTF-8?q?ove=20Requestly=20(#14735)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/data/sponsors.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/en/data/sponsors.yml b/docs/en/data/sponsors.yml index c0bdb15f63..f8085b4523 100644 --- a/docs/en/data/sponsors.yml +++ b/docs/en/data/sponsors.yml @@ -68,6 +68,3 @@ bronze: - url: https://www.testmu.ai/?utm_source=fastapi&utm_medium=partner&utm_campaign=sponsor&utm_term=opensource&utm_content=webpage title: TestMu AI. The Native AI-Agentic Cloud Platform to Supercharge Quality Engineering. img: https://fastapi.tiangolo.com/img/sponsors/testmu.png - - url: https://requestly.com/fastapi - title: All-in-one platform to Test, Mock and Intercept APIs. Built for speed, privacy and offline support. - img: https://fastapi.tiangolo.com/img/sponsors/requestly.png From ad6b2901a6ab9350c55f261b06dfd1dc363e1fde Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 19 Jan 2026 20:56:10 +0000 Subject: [PATCH 020/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 8b338f60d0..4cc8bf0188 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -30,6 +30,7 @@ hide: ### Internal +* 🔧 Update sponsors: remove Requestly. PR [#14735](https://github.com/fastapi/fastapi/pull/14735) by [@tiangolo](https://github.com/tiangolo). * 🔧 Update sponsors, LambdaTest changes to TestMu AI. PR [#14734](https://github.com/fastapi/fastapi/pull/14734) by [@tiangolo](https://github.com/tiangolo). * ⬆ Bump actions/cache from 4 to 5. PR [#14511](https://github.com/fastapi/fastapi/pull/14511) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump actions/upload-artifact from 5 to 6. PR [#14525](https://github.com/fastapi/fastapi/pull/14525) by [@dependabot[bot]](https://github.com/apps/dependabot). From 6afb15c518e7c151c02639b3704424477997da87 Mon Sep 17 00:00:00 2001 From: Kader Miyanyedi <48386782+Kadermiyanyedi@users.noreply.github.com> Date: Tue, 20 Jan 2026 23:34:03 +0300 Subject: [PATCH 021/108] =?UTF-8?q?=F0=9F=8C=90=20Improve=20LLM=20prompt?= =?UTF-8?q?=20for=20Turkish=20translations=20(#14728)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/tr/llm-prompt.md | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/docs/tr/llm-prompt.md b/docs/tr/llm-prompt.md index 297b0a0e6c..2ba922ec59 100644 --- a/docs/tr/llm-prompt.md +++ b/docs/tr/llm-prompt.md @@ -4,10 +4,16 @@ Translate to Turkish (TÃŒrkçe). Language code: tr. +### Core principle + +Don't translate word-by-word. Rewrite naturally in Turkish as if writing the doc from scratch. Preserve meaning, but prioritize fluency over literal accuracy. + ### Grammar and tone - Use instructional Turkish, consistent with existing Turkish docs. -- Use imperative/guide language when appropriate (e.g. “açalım”, “gidin”, “kopyalayalım”). +- Use imperative/guide language (e.g. "açalım", "gidin", "kopyalayalım", "bir bakalım"). +- Avoid filler words and overly long sentences. +- Ensure sentences make sense in Turkish context — adjust structure, conjunctions, and verb forms as needed for natural flow (e.g. use "Ancak" instead of "Ve" when connecting contrasting sentences, use "-maktadır/-mektedir" for formal statements). ### Headings @@ -15,13 +21,23 @@ Language code: tr. ### Quotes -- Alıntı stili mevcut TÃŒrkçe dokÃŒmanlarla tutarlı tutun (genellikle metin içinde ASCII tırnak işaretleri kullanılır). -- Satır içi kod, kod blokları, URL'ler veya dosya yolları içindeki tırnak işaretlerini asla değiştirmeyin. +- Keep quote style consistent with existing Turkish docs (typically ASCII quotes in text). +- Never modify quotes inside inline code, code blocks, URLs, or file paths. ### Ellipsis -- Üç nokta (...) stili mevcut TÃŒrkçe dokÃŒmanlarla tutarlı tutun. -- Kod, URL veya CLI örneklerindeki `...` ifadesini asla değiştirmeyin. +- Keep ellipsis style (`...`) consistent with existing Turkish docs. +- Never modify `...` in code, URLs, or CLI examples. + +### Consistency + +- Use the same translation for the same term throughout the document. +- If you translate a concept one way, keep it consistent across all occurrences. + +### Links and references + +- Never modify link syntax like `{.internal-link target=_blank}`. +- Keep markdown link structure intact: `[text](url){.internal-link}`. ### Preferred translations / glossary From 7443bc7a4684b3d1754c0ab59bb9e878bac96a6b Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 20 Jan 2026 20:34:36 +0000 Subject: [PATCH 022/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 4cc8bf0188..8d97900394 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -18,6 +18,7 @@ hide: ### Translations +* 🌐 Improve LLM prompt for Turkish translations. PR [#14728](https://github.com/fastapi/fastapi/pull/14728) by [@Kadermiyanyedi](https://github.com/Kadermiyanyedi). * 🌐 Update portuguese llm-prompt.md. PR [#14702](https://github.com/fastapi/fastapi/pull/14702) by [@ceb10n](https://github.com/ceb10n). * 🌐 Update LLM prompt instructions file for French. PR [#14618](https://github.com/fastapi/fastapi/pull/14618) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update translations for ko (add-missing). PR [#14699](https://github.com/fastapi/fastapi/pull/14699) by [@tiangolo](https://github.com/tiangolo). From 0ab68a762f5fbf86777a45afc8df7059e07a0a7d Mon Sep 17 00:00:00 2001 From: "hy.lee" Date: Wed, 21 Jan 2026 05:37:04 +0900 Subject: [PATCH 023/108] =?UTF-8?q?=F0=9F=8C=90=20Update=20Korean=20LLM=20?= =?UTF-8?q?prompt=20(#14740)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/ko/llm-prompt.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/ko/llm-prompt.md b/docs/ko/llm-prompt.md index df807c9496..533160eab9 100644 --- a/docs/ko/llm-prompt.md +++ b/docs/ko/llm-prompt.md @@ -8,6 +8,7 @@ Language code: ko. - Use polite, instructional Korean (e.g. 합니닀/하섞요 style). - Keep the tone consistent with the existing Korean FastAPI docs. +- Do not translate “You” literally as “당신”. Use “여러분” where appropriate, or omit the subject if it sounds more natural in Korean. ### Headings From 7faa7089d665ad9e47a73d4a55457a23ba5cf643 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 20 Jan 2026 20:37:28 +0000 Subject: [PATCH 024/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 8d97900394..7c5460f1df 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -18,6 +18,7 @@ hide: ### Translations +* 🌐 Update Korean LLM prompt. PR [#14740](https://github.com/fastapi/fastapi/pull/14740) by [@hard-coders](https://github.com/hard-coders). * 🌐 Improve LLM prompt for Turkish translations. PR [#14728](https://github.com/fastapi/fastapi/pull/14728) by [@Kadermiyanyedi](https://github.com/Kadermiyanyedi). * 🌐 Update portuguese llm-prompt.md. PR [#14702](https://github.com/fastapi/fastapi/pull/14702) by [@ceb10n](https://github.com/ceb10n). * 🌐 Update LLM prompt instructions file for French. PR [#14618](https://github.com/fastapi/fastapi/pull/14618) by [@tiangolo](https://github.com/tiangolo). From 2d459e4845e8de9e080039d8f3ab2f1fd2e774a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Tue, 20 Jan 2026 12:40:17 -0800 Subject: [PATCH 025/108] =?UTF-8?q?=F0=9F=8C=90=20Update=20translations=20?= =?UTF-8?q?for=20pt=20(update-outdated)=20(#14724)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: github-actions[bot] --- docs/pt/docs/_llm-test.md | 48 +++++------ .../path-operation-advanced-configuration.md | 64 ++++---------- docs/pt/docs/advanced/settings.md | 44 ---------- ...migrate-from-pydantic-v1-to-pydantic-v2.md | 22 ++--- .../docs/how-to/separate-openapi-schemas.md | 8 +- docs/pt/docs/index.md | 86 ++++++++++--------- docs/pt/docs/tutorial/bigger-applications.md | 84 +++++++++--------- docs/pt/docs/tutorial/body-updates.md | 42 +++------ docs/pt/docs/tutorial/body.md | 18 ++-- docs/pt/docs/tutorial/extra-models.md | 26 ++---- .../tutorial/query-params-str-validations.md | 34 +++----- docs/pt/docs/tutorial/response-model.md | 14 --- docs/pt/docs/tutorial/schema-extra-example.md | 36 ++------ 13 files changed, 188 insertions(+), 338 deletions(-) diff --git a/docs/pt/docs/_llm-test.md b/docs/pt/docs/_llm-test.md index 3da5e8a71d..b59292f47c 100644 --- a/docs/pt/docs/_llm-test.md +++ b/docs/pt/docs/_llm-test.md @@ -1,8 +1,8 @@ # Arquivo de teste de LLM { #llm-test-file } -Este documento testa se o LLM, que traduz a documentação, entende o `general_prompt` em `scripts/translate.py` e o prompt específico do idioma em `docs/{language code}/llm-prompt.md`. O prompt específico do idioma é anexado ao `general_prompt`. +Este documento testa se o LLM, que traduz a documentação, entende o `general_prompt` em `scripts/translate.py` e o prompt específico do idioma em `docs/{language code}/llm-prompt.md`. O prompt específico do idioma é anexado ao `general_prompt`. -Os testes adicionados aqui serão vistos por todos os autores dos prompts específicos de idioma. +Os testes adicionados aqui serão vistos por todos os designers dos prompts específicos de idioma. Use da seguinte forma: @@ -23,7 +23,7 @@ Este é um trecho de código: `foo`. E este é outro trecho de código: `bar`. E //// -//// tab | Informações +//// tab | Informação O conteúdo dos trechos de código deve ser deixado como está. @@ -45,9 +45,9 @@ O LLM provavelmente vai traduzir isso errado. O interessante é apenas se ele ma //// -//// tab | Informações +//// tab | Informação -O autor do prompt pode escolher se deseja converter aspas neutras em aspas tipográficas. Também é aceitável deixá-las como estão. +O designer do prompt pode escolher se quer converter aspas neutras em aspas tipográficas. Também é aceitável deixá-las como estão. Veja, por exemplo, a seção `### Quotes` em `docs/de/llm-prompt.md`. @@ -67,7 +67,7 @@ Pesado: `Yesterday, my friend wrote: "If you spell incorrectly correctly, you ha //// -//// tab | Informações +//// tab | Informação ... No entanto, as aspas dentro de trechos de código devem permanecer como estão. @@ -95,24 +95,24 @@ $ fastapi run GTD -* lt -* XWT -* PSGI +* GTD +* lt +* XWT +* PSGI ### O abbr fornece uma explicação { #the-abbr-gives-an-explanation } @@ -209,12 +209,12 @@ Aqui estão algumas coisas envolvidas em elementos HTML "abbr" (algumas são inv ### O abbr fornece uma frase completa e uma explicação { #the-abbr-gives-a-full-phrase-and-an-explanation } -* MDN -* I/O. +* MDN +* I/O. //// -//// tab | Informações +//// tab | Informação Os atributos "title" dos elementos "abbr" são traduzidos seguindo algumas instruções específicas. @@ -228,7 +228,7 @@ Veja a seção `### HTML abbr elements` no prompt geral em `scripts/translate.py //// tab | Teste -### Desenvolver uma aplicação web - um tutorial { #develop-a-webapp-a-tutorial } +### Desenvolver uma webapp - um tutorial { #develop-a-webapp-a-tutorial } Olá. @@ -242,7 +242,7 @@ Olá novamente. //// -//// tab | Informações +//// tab | Informação A única regra rígida para títulos é que o LLM deixe a parte do hash dentro de chaves inalterada, o que garante que os links não quebrem. @@ -494,9 +494,9 @@ Para algumas instruções específicas do idioma, veja, por exemplo, a seção ` //// -//// tab | Informações +//// tab | Informação -Esta é uma lista não completa e não normativa de termos (principalmente) técnicos vistos na documentação. Pode ser útil para o autor do prompt descobrir para quais termos o LLM precisa de uma ajudinha. Por exemplo, quando ele continua revertendo uma boa tradução para uma tradução subótima. Ou quando tem problemas para conjugar/declinar um termo no seu idioma. +Esta é uma lista não completa e não normativa de termos (principalmente) técnicos vistos na documentação. Pode ser útil para o designer do prompt descobrir para quais termos o LLM precisa de uma ajudinha. Por exemplo, quando ele continua revertendo uma boa tradução para uma tradução subótima. Ou quando tem problemas para conjugar/declinar um termo no seu idioma. Veja, por exemplo, a seção `### List of English terms and their preferred German translations` em `docs/de/llm-prompt.md`. diff --git a/docs/pt/docs/advanced/path-operation-advanced-configuration.md b/docs/pt/docs/advanced/path-operation-advanced-configuration.md index e1c3e5ab89..b3af116a28 100644 --- a/docs/pt/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/pt/docs/advanced/path-operation-advanced-configuration.md @@ -10,7 +10,7 @@ Se você não é um "especialista" no OpenAPI, você provavelmente não precisa Você pode definir o `operationId` do OpenAPI que será utilizado na sua *operação de rota* com o parâmetro `operation_id`. -Você precisa ter certeza que ele é único para cada operação. +Você deveria ter certeza que ele é único para cada operação. {* ../../docs_src/path_operation_advanced_configuration/tutorial001_py39.py hl[6] *} @@ -18,13 +18,13 @@ Você precisa ter certeza que ele é único para cada operação. Se você quiser utilizar o nome das funções da sua API como `operationId`s, você pode iterar sobre todos esses nomes e sobrescrever o `operation_id` em cada *operação de rota* utilizando o `APIRoute.name` dela. -Você deve fazer isso depois de adicionar todas as suas *operações de rota*. +Você deveria fazer isso depois de adicionar todas as suas *operações de rota*. {* ../../docs_src/path_operation_advanced_configuration/tutorial002_py39.py hl[2, 12:21, 24] *} /// tip | Dica -Se você chamar `app.openapi()` manualmente, os `operationId`s devem ser atualizados antes dessa chamada. +Se você chamar `app.openapi()` manualmente, você deveria atualizar os `operationId`s antes dessa chamada. /// @@ -44,11 +44,11 @@ Para excluir uma *operação de rota* do esquema OpenAPI gerado (e por consequê ## Descrição avançada a partir de docstring { #advanced-description-from-docstring } -Você pode limitar as linhas utilizadas a partir de uma docstring de uma *função de operação de rota* para o OpenAPI. +Você pode limitar as linhas utilizadas a partir da docstring de uma *função de operação de rota* para o OpenAPI. -Adicionar um `\f` (um caractere de escape para alimentação de formulário) faz com que o **FastAPI** restrinja a saída utilizada pelo OpenAPI até esse ponto. +Adicionar um `\f` (um caractere de escape para "form feed") faz com que o **FastAPI** trunque a saída usada para o OpenAPI até esse ponto. -Ele não será mostrado na documentação, mas outras ferramentas (como o Sphinx) serão capazes de utilizar o resto do texto. +Ele não será mostrado na documentação, mas outras ferramentas (como o Sphinx) serão capazes de utilizar o resto. {* ../../docs_src/path_operation_advanced_configuration/tutorial004_py310.py hl[17:27] *} @@ -131,70 +131,38 @@ E se você olhar o esquema OpenAPI resultante (na rota `/openapi.json` da sua AP ### Esquema de *operação de rota* do OpenAPI personalizado { #custom-openapi-path-operation-schema } -O dicionário em `openapi_extra` vai ter todos os seus níveis mesclados dentro do esquema OpenAPI gerado automaticamente para a *operação de rota*. +O dicionário em `openapi_extra` vai ser mesclado profundamente com o esquema OpenAPI gerado automaticamente para a *operação de rota*. -Então, você pode adicionar dados extras para o esquema gerado automaticamente. +Então, você pode adicionar dados extras ao esquema gerado automaticamente. -Por exemplo, você poderia optar por ler e validar a requisição com seu próprio código, sem utilizar funcionalidades automatizadas do FastAPI com o Pydantic, mas você ainda pode quere definir a requisição no esquema OpenAPI. +Por exemplo, você poderia decidir ler e validar a requisição com seu próprio código, sem usar as funcionalidades automáticas do FastAPI com o Pydantic, mas ainda assim querer definir a requisição no esquema OpenAPI. Você pode fazer isso com `openapi_extra`: {* ../../docs_src/path_operation_advanced_configuration/tutorial006_py39.py hl[19:36, 39:40] *} -Nesse exemplo, nós não declaramos nenhum modelo do Pydantic. Na verdade, o corpo da requisição não está nem mesmo analisado como JSON, ele é lido diretamente como `bytes` e a função `magic_data_reader()` seria a responsável por analisar ele de alguma forma. +Nesse exemplo, nós não declaramos nenhum modelo do Pydantic. Na verdade, o corpo da requisição não está nem mesmo analisado como JSON, ele é lido diretamente como `bytes`, e a função `magic_data_reader()` seria a responsável por analisar ele de alguma forma. De toda forma, nós podemos declarar o esquema esperado para o corpo da requisição. ### Tipo de conteúdo do OpenAPI personalizado { #custom-openapi-content-type } -Utilizando esse mesmo truque, você pode utilizar um modelo Pydantic para definir o JSON Schema que é então incluído na seção do esquema personalizado do OpenAPI na *operação de rota*. +Utilizando esse mesmo truque, você pode usar um modelo Pydantic para definir o JSON Schema que é então incluído na seção do esquema personalizado do OpenAPI na *operação de rota*. -E você pode fazer isso até mesmo quando os dados da requisição não seguem o formato JSON. +E você pode fazer isso até mesmo quando o tipo de dados na requisição não é JSON. -Por exemplo, nesta aplicação nós não usamos a funcionalidade integrada ao FastAPI de extrair o JSON Schema dos modelos Pydantic nem a validação automática do JSON. Na verdade, estamos declarando o tipo do conteúdo da requisição como YAML, em vez de JSON: - -//// tab | Pydantic v2 +Por exemplo, nesta aplicação nós não usamos a funcionalidade integrada ao FastAPI de extrair o JSON Schema dos modelos Pydantic nem a validação automática para JSON. Na verdade, estamos declarando o tipo de conteúdo da requisição como YAML, em vez de JSON: {* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[15:20, 22] *} -//// +Entretanto, mesmo que não utilizemos a funcionalidade integrada por padrão, ainda estamos usando um modelo Pydantic para gerar um JSON Schema manualmente para os dados que queremos receber em YAML. -//// tab | Pydantic v1 +Então utilizamos a requisição diretamente e extraímos o corpo como `bytes`. Isso significa que o FastAPI não vai sequer tentar analisar o payload da requisição como JSON. -{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1_py39.py hl[15:20, 22] *} - -//// - -/// info | Informação - -Na versão 1 do Pydantic, o método para obter o JSON Schema de um modelo é `Item.schema()`, na versão 2 do Pydantic, o método é `Item.model_json_schema()`. - -/// - -Entretanto, mesmo que não utilizemos a funcionalidade integrada por padrão, ainda estamos usando um modelo Pydantic para gerar um JSON Schema manualmente para os dados que queremos receber no formato YAML. - -Então utilizamos a requisição diretamente, e extraímos o corpo como `bytes`. Isso significa que o FastAPI não vai sequer tentar analisar o corpo da requisição como JSON. - -E então no nosso código, nós analisamos o conteúdo YAML diretamente, e estamos utilizando o mesmo modelo Pydantic para validar o conteúdo YAML: - -//// tab | Pydantic v2 +E então no nosso código, nós analisamos o conteúdo YAML diretamente e, em seguida, estamos usando novamente o mesmo modelo Pydantic para validar o conteúdo YAML: {* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[24:31] *} -//// - -//// tab | Pydantic v1 - -{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1_py39.py hl[24:31] *} - -//// - -/// info | Informação - -Na versão 1 do Pydantic, o método para analisar e validar um objeto era `Item.parse_obj()`, na versão 2 do Pydantic, o método é chamado de `Item.model_validate()`. - -/// - /// tip | Dica Aqui reutilizamos o mesmo modelo do Pydantic. diff --git a/docs/pt/docs/advanced/settings.md b/docs/pt/docs/advanced/settings.md index 6f5b7feae7..28411269bb 100644 --- a/docs/pt/docs/advanced/settings.md +++ b/docs/pt/docs/advanced/settings.md @@ -46,12 +46,6 @@ $ pip install "fastapi[all]"
-/// info | Informação - -No Pydantic v1 ele vinha incluído no pacote principal. Agora é distribuído como um pacote independente para que você possa optar por instalá-lo ou não, caso não precise dessa funcionalidade. - -/// - ### Criar o objeto `Settings` { #create-the-settings-object } Importe `BaseSettings` do Pydantic e crie uma subclasse, muito parecido com um modelo do Pydantic. @@ -60,24 +54,8 @@ Da mesma forma que com modelos do Pydantic, você declara atributos de classe co Você pode usar as mesmas funcionalidades e ferramentas de validação que usa em modelos do Pydantic, como diferentes tipos de dados e validações adicionais com `Field()`. -//// tab | Pydantic v2 - {* ../../docs_src/settings/tutorial001_py39.py hl[2,5:8,11] *} -//// - -//// tab | Pydantic v1 - -/// info | Informação - -No Pydantic v1 você importaria `BaseSettings` diretamente de `pydantic` em vez de `pydantic_settings`. - -/// - -{* ../../docs_src/settings/tutorial001_pv1_py39.py hl[2,5:8,11] *} - -//// - /// tip | Dica Se você quer algo rápido para copiar e colar, não use este exemplo, use o último abaixo. @@ -215,8 +193,6 @@ APP_NAME="ChimichangApp" E então atualizar seu `config.py` com: -//// tab | Pydantic v2 - {* ../../docs_src/settings/app03_an_py39/config.py hl[9] *} /// tip | Dica @@ -225,26 +201,6 @@ O atributo `model_config` é usado apenas para configuração do Pydantic. Você /// -//// - -//// tab | Pydantic v1 - -{* ../../docs_src/settings/app03_an_py39/config_pv1.py hl[9:10] *} - -/// tip | Dica - -A classe `Config` é usada apenas para configuração do Pydantic. Você pode ler mais em Pydantic Model Config. - -/// - -//// - -/// info | Informação - -Na versão 1 do Pydantic a configuração era feita em uma classe interna `Config`, na versão 2 do Pydantic é feita em um atributo `model_config`. Esse atributo recebe um `dict`, e para ter autocompletar e erros inline você pode importar e usar `SettingsConfigDict` para definir esse `dict`. - -/// - Aqui definimos a configuração `env_file` dentro da sua classe `Settings` do Pydantic e definimos o valor como o nome do arquivo dotenv que queremos usar. ### Criando o `Settings` apenas uma vez com `lru_cache` { #creating-the-settings-only-once-with-lru-cache } diff --git a/docs/pt/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/pt/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index 2a2659a03d..0995e10285 100644 --- a/docs/pt/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/pt/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -2,21 +2,23 @@ Se você tem uma aplicação FastAPI antiga, pode estar usando o Pydantic versão 1. -O FastAPI tem suporte ao Pydantic v1 ou v2 desde a versão 0.100.0. +O FastAPI versão 0.100.0 tinha suporte ao Pydantic v1 ou v2. Ele usaria aquele que você tivesse instalado. -Se você tiver o Pydantic v2 instalado, ele será utilizado. Se, em vez disso, tiver o Pydantic v1, será ele que será utilizado. +O FastAPI versão 0.119.0 introduziu suporte parcial ao Pydantic v1 a partir de dentro do Pydantic v2 (como `pydantic.v1`), para facilitar a migração para o v2. -O Pydantic v1 está agora descontinuado e o suporte a ele será removido nas próximas versões do FastAPI, você deveria migrar para o Pydantic v2. Assim, você terá as funcionalidades, melhorias e correções mais recentes. +O FastAPI 0.126.0 removeu o suporte ao Pydantic v1, enquanto ainda oferece suporte a `pydantic.v1` por mais algum tempo. /// warning | Atenção -Além disso, a equipe do Pydantic interrompeu o suporte ao Pydantic v1 para as versões mais recentes do Python, a partir do **Python 3.14**. +A equipe do Pydantic interrompeu o suporte ao Pydantic v1 para as versões mais recentes do Python, a partir do **Python 3.14**. + +Isso inclui `pydantic.v1`, que não é mais suportado no Python 3.14 e superiores. Se quiser usar as funcionalidades mais recentes do Python, você precisará garantir que usa o Pydantic v2. /// -Se você tem uma aplicação FastAPI antiga com Pydantic v1, aqui vou mostrar como migrá-la para o Pydantic v2 e as **novas funcionalidades no FastAPI 0.119.0** para ajudar em uma migração gradual. +Se você tem uma aplicação FastAPI antiga com Pydantic v1, aqui vou mostrar como migrá-la para o Pydantic v2, e as **funcionalidades no FastAPI 0.119.0** para ajudar em uma migração gradual. ## Guia oficial { #official-guide } @@ -44,7 +46,7 @@ Depois disso, você pode rodar os testes e verificar se tudo funciona. Se funcio ## Pydantic v1 no v2 { #pydantic-v1-in-v2 } -O Pydantic v2 inclui tudo do Pydantic v1 como um submódulo `pydantic.v1`. +O Pydantic v2 inclui tudo do Pydantic v1 como um submódulo `pydantic.v1`. Mas isso não é mais suportado em versões acima do Python 3.13. Isso significa que você pode instalar a versão mais recente do Pydantic v2 e importar e usar os componentes antigos do Pydantic v1 a partir desse submódulo, como se tivesse o Pydantic v1 antigo instalado. @@ -66,7 +68,7 @@ Tenha em mente que, como a equipe do Pydantic não oferece mais suporte ao Pydan ### Pydantic v1 e v2 na mesma aplicação { #pydantic-v1-and-v2-on-the-same-app } -Não é suportado pelo Pydantic ter um modelo do Pydantic v2 com campos próprios definidos como modelos do Pydantic v1, ou vice-versa. +Não é **suportado** pelo Pydantic ter um modelo do Pydantic v2 com campos próprios definidos como modelos do Pydantic v1, ou vice-versa. ```mermaid graph TB @@ -86,7 +88,7 @@ graph TB style V2Field fill:#f9fff3 ``` -...but, you can have separated models using Pydantic v1 and v2 in the same app. +...mas, você pode ter modelos separados usando Pydantic v1 e v2 na mesma aplicação. ```mermaid graph TB @@ -106,7 +108,7 @@ graph TB style V2Field fill:#f9fff3 ``` -Em alguns casos, é até possível ter modelos Pydantic v1 e v2 na mesma operação de rota na sua aplicação FastAPI: +Em alguns casos, é até possível ter modelos Pydantic v1 e v2 na mesma **operação de rota** na sua aplicação FastAPI: {* ../../docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py hl[2:3,6,12,21:22] *} @@ -122,7 +124,7 @@ Se você precisar usar algumas das ferramentas específicas do FastAPI para par /// tip | Dica -Primeiro tente com o `bump-pydantic`; se seus testes passarem e isso funcionar, então você concluiu tudo com um único comando. ✹ +Primeiro tente com o `bump-pydantic`, se seus testes passarem e isso funcionar, então você concluiu tudo com um único comando. ✹ /// diff --git a/docs/pt/docs/how-to/separate-openapi-schemas.md b/docs/pt/docs/how-to/separate-openapi-schemas.md index 8855934fd9..f757025a09 100644 --- a/docs/pt/docs/how-to/separate-openapi-schemas.md +++ b/docs/pt/docs/how-to/separate-openapi-schemas.md @@ -1,8 +1,8 @@ # Esquemas OpenAPI Separados para Entrada e Saída ou Não { #separate-openapi-schemas-for-input-and-output-or-not } -Ao usar **Pydantic v2**, o OpenAPI gerado é um pouco mais exato e **correto** do que antes. 😎 +Desde que o **Pydantic v2** foi lançado, o OpenAPI gerado é um pouco mais exato e **correto** do que antes. 😎 -Inclusive, em alguns casos, ele terá até **dois JSON Schemas** no OpenAPI para o mesmo modelo Pydantic, para entrada e saída, dependendo se eles possuem **valores padrão**. +De fato, em alguns casos, ele terá até **dois JSON Schemas** no OpenAPI para o mesmo modelo Pydantic, para entrada e saída, dependendo se eles possuem **valores padrão**. Vamos ver como isso funciona e como alterar se for necessário. @@ -95,10 +95,8 @@ O suporte para `separate_input_output_schemas` foi adicionado no FastAPI `0.102. ### Mesmo Esquema para Modelos de Entrada e Saída na Documentação { #same-schema-for-input-and-output-models-in-docs } -E agora haverá um único esquema para entrada e saída para o modelo, apenas `Item`, e `description` **não será obrigatório**: +E agora haverá um único esquema para entrada e saída para o modelo, apenas `Item`, e ele terá `description` como **não obrigatório**:
- -Esse é o mesmo comportamento do Pydantic v1. 🀓 diff --git a/docs/pt/docs/index.md b/docs/pt/docs/index.md index 0428c3a798..4e3be586da 100644 --- a/docs/pt/docs/index.md +++ b/docs/pt/docs/index.md @@ -40,8 +40,8 @@ Os recursos chave são: * **Rápido**: alta performance, equivalente a **NodeJS** e **Go** (graças ao Starlette e Pydantic). [Um dos frameworks mais rápidos disponíveis](#performance). * **Rápido para codar**: Aumenta a velocidade para desenvolver recursos entre 200% a 300%. * * **Poucos bugs**: Reduz cerca de 40% de erros induzidos por humanos (desenvolvedores). * -* **Intuitivo**: Grande suporte a _IDEs_. Preenchimento automático em todos os lugares. Menos tempo debugando. -* **Fácil**: Projetado para ser fácil de aprender e usar. Menos tempo lendo documentação. +* **Intuitivo**: Grande suporte a editores. Completação em todos os lugares. Menos tempo debugando. +* **Fácil**: Projetado para ser fácil de aprender e usar. Menos tempo lendo docs. * **Enxuto**: Minimize duplicação de código. Múltiplas funcionalidades para cada declaração de parâmetro. Menos bugs. * **Robusto**: Tenha código pronto para produção. E com documentação interativa automática. * **Baseado em padrões**: Baseado em (e totalmente compatível com) os padrões abertos para APIs: OpenAPI (anteriormente conhecido como Swagger) e JSON Schema. @@ -73,7 +73,7 @@ Os recursos chave são: ## Opiniões { #opinions } -"*[...] Estou usando **FastAPI** muito esses dias. [...] Estou na verdade planejando utilizar ele em todos os times de **serviços _Machine Learning_ na Microsoft**. Alguns deles estão sendo integrados no _core_ do produto **Windows** e alguns produtos **Office**.*" +"_[...] Estou usando **FastAPI** muito esses dias. [...] Estou na verdade planejando utilizar ele em todos os times de **serviços ML na Microsoft**. Alguns deles estão sendo integrados no _core_ do produto **Windows** e alguns produtos **Office**._"
Kabir Khan - Microsoft (ref)
@@ -91,39 +91,45 @@ Os recursos chave são: --- -"*Estou extremamente entusiasmado com o **FastAPI**. É tão divertido!*" +"_Estou muito entusiasmado com o **FastAPI**. É tão divertido!_" -
Brian Okken - Python Bytes podcaster (ref)
+
Brian Okken - Python Bytes apresentador do podcast (ref)
--- -"*Honestamente, o que você construiu parece super sólido e rebuscado. De muitas formas, eu queria que o **Hug** fosse assim - é realmente inspirador ver alguém que construiu ele.*" +"_Honestamente, o que você construiu parece super sólido e refinado. De muitas formas, é o que eu queria que o **Hug** fosse - é realmente inspirador ver alguém construir isso._"
Timothy Crosley - criador doHug (ref)
--- -"*Se você está procurando aprender um **_framework_ moderno** para construir aplicações _REST_, dê uma olhada no **FastAPI** [...] É rápido, fácil de usar e fácil de aprender [...]*" +"_Se você está procurando aprender um **framework moderno** para construir APIs REST, dê uma olhada no **FastAPI** [...] É rápido, fácil de usar e fácil de aprender [...]_" -"*Nós trocamos nossas **APIs** por **FastAPI** [...] Acredito que vocês gostarão dele [...]*" +"_Nós trocamos nossas **APIs** por **FastAPI** [...] Acredito que você gostará dele [...]_"
Ines Montani - Matthew Honnibal - fundadores da Explosion AI - criadores da spaCy (ref) - (ref)
--- -"_Se alguém estiver procurando construir uma API Python para produção, eu recomendaria fortemente o **FastAPI**. Ele é **lindamente projetado**, **simples de usar** e **altamente escalável**. Ele se tornou um **componente chave** para a nossa estratégia API first de desenvolvimento e está impulsionando diversas automações e serviços, como o nosso Virtual TAC Engineer._" +"_Se alguém estiver procurando construir uma API Python para produção, eu recomendaria fortemente o **FastAPI**. Ele é **lindamente projetado**, **simples de usar** e **altamente escalável**, e se tornou um **componente chave** para a nossa estratégia de desenvolvimento API first, impulsionando diversas automações e serviços, como o nosso Virtual TAC Engineer._"
Deon Pillsbury - Cisco (ref)
--- +## Mini documentário do FastAPI { #fastapi-mini-documentary } + +Há um mini documentário do FastAPI lançado no fim de 2025, você pode assisti-lo online: + +FastAPI Mini Documentary + ## **Typer**, o FastAPI das interfaces de linhas de comando { #typer-the-fastapi-of-clis } -Se você estiver construindo uma aplicação CLI para ser utilizada em um terminal ao invés de uma aplicação web, dê uma olhada no **Typer**. +Se você estiver construindo uma aplicação CLI para ser utilizada no terminal ao invés de uma API web, dê uma olhada no **Typer**. -**Typer** é o irmão menor do FastAPI. E seu propósito é ser o **FastAPI das _CLIs_**. ⌚ 🚀 +**Typer** é o irmão menor do FastAPI. E seu propósito é ser o **FastAPI das CLIs**. ⌚ 🚀 ## Requisitos { #requirements } @@ -255,10 +261,10 @@ Você verá a resposta JSON como: Você acabou de criar uma API que: -* Recebe requisições HTTP nas _rotas_ `/` e `/items/{item_id}`. -* Ambas _rotas_ fazem operações `GET` (também conhecido como _métodos_ HTTP). -* A _rota_ `/items/{item_id}` tem um _parâmetro de rota_ `item_id` que deve ser um `int`. -* A _rota_ `/items/{item_id}` tem um _parâmetro query_ `q` `str` opcional. +* Recebe requisições HTTP nos _paths_ `/` e `/items/{item_id}`. +* Ambos _paths_ fazem operações `GET` (também conhecido como _métodos_ HTTP). +* O _path_ `/items/{item_id}` tem um _parâmetro de path_ `item_id` que deve ser um `int`. +* O _path_ `/items/{item_id}` tem um _parâmetro query_ `q` `str` opcional. ### Documentação Interativa da API { #interactive-api-docs } @@ -278,7 +284,7 @@ Você verá a documentação automática alternativa (fornecida por http://127.0.0.1:8000/redoc. -* A documentação alternativa também irá refletir o novo parâmetro da _query_ e o corpo: +* A documentação alternativa também irá refletir o novo parâmetro query e o corpo: ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) @@ -368,15 +374,15 @@ item: Item * Validação de dados: * Erros automáticos e claros quando o dado é inválido. * Validação até para objetos JSON profundamente aninhados. -* Conversão de dados de entrada: vindo da rede para dados e tipos Python. Consegue ler: +* Conversão de dados de entrada: vindo da rede para dados e tipos Python. Consegue ler: * JSON. - * Parâmetros de rota. - * Parâmetros de _query_ . - * _Cookies_. + * Parâmetros de path. + * Parâmetros query. + * Cookies. * Cabeçalhos. * Formulários. * Arquivos. -* Conversão de dados de saída de tipos e dados Python para dados de rede (como JSON): +* Conversão de dados de saída: convertendo de tipos e dados Python para dados de rede (como JSON): * Converte tipos Python (`str`, `int`, `float`, `bool`, `list` etc). * Objetos `datetime`. * Objetos `UUID`. @@ -390,17 +396,17 @@ item: Item Voltando ao código do exemplo anterior, **FastAPI** irá: -* Validar que existe um `item_id` na rota para requisições `GET` e `PUT`. +* Validar que existe um `item_id` no path para requisições `GET` e `PUT`. * Validar que `item_id` é do tipo `int` para requisições `GET` e `PUT`. - * Se não é validado, o cliente verá um útil, claro erro. -* Verificar se existe um parâmetro de _query_ opcional nomeado como `q` (como em `http://127.0.0.1:8000/items/foo?q=somequery`) para requisições `GET`. + * Se não for, o cliente verá um erro útil e claro. +* Verificar se existe um parâmetro query opcional nomeado como `q` (como em `http://127.0.0.1:8000/items/foo?q=somequery`) para requisições `GET`. * Como o parâmetro `q` é declarado com `= None`, ele é opcional. - * Sem o `None` ele poderia ser obrigatório (como o corpo no caso de `PUT`). + * Sem o `None` ele seria obrigatório (como o corpo no caso de `PUT`). * Para requisições `PUT` para `/items/{item_id}`, lerá o corpo como JSON: * Verifica que tem um atributo obrigatório `name` que deve ser `str`. - * Verifica que tem um atributo obrigatório `price` que deve ser `float`. - * Verifica que tem an atributo opcional `is_offer`, que deve ser `bool`, se presente. - * Tudo isso também funciona para objetos JSON profundamente aninhados. + * Verifica que tem um atributo obrigatório `price` que tem que ser um `float`. + * Verifica que tem um atributo opcional `is_offer`, que deve ser um `bool`, se presente. + * Tudo isso também funcionaria para objetos JSON profundamente aninhados. * Converter de e para JSON automaticamente. * Documentar tudo com OpenAPI, que poderá ser usado por: * Sistemas de documentação interativos. @@ -409,7 +415,7 @@ Voltando ao código do exemplo anterior, **FastAPI** irá: --- -Nós apenas arranhamos a superfície, mas você já tem idéia de como tudo funciona. +Nós apenas arranhamos a superfície, mas você já tem ideia de como tudo funciona. Experimente mudar a seguinte linha: @@ -437,22 +443,22 @@ Para um exemplo mais completo incluindo mais recursos, veja Injeção de Dependência**. -* Segurança e autenticação, incluindo suporte para **OAuth2** com autenticação **JWT tokens** e **HTTP Basic**. +* Declaração de **parâmetros** de diferentes lugares como: **cabeçalhos**, **cookies**, **campos de formulários** e **arquivos**. +* Como configurar **limitações de validação** como `maximum_length` ou `regex`. +* Um poderoso e fácil de usar sistema de **Injeção de Dependência**. +* Segurança e autenticação, incluindo suporte para **OAuth2** com autenticação com **JWT tokens** e **HTTP Basic**. * Técnicas mais avançadas (mas igualmente fáceis) para declaração de **modelos JSON profundamente aninhados** (graças ao Pydantic). * Integrações **GraphQL** com o Strawberry e outras bibliotecas. * Muitos recursos extras (graças ao Starlette) como: * **WebSockets** - * testes extrememamente fáceis baseados em HTTPX e `pytest` + * testes extremamente fáceis baseados em HTTPX e `pytest` * **CORS** * **Cookie Sessions** * ...e mais. ### Implemente sua aplicação (opcional) { #deploy-your-app-optional } -Você pode opcionalmente implantar sua aplicação FastAPI na FastAPI Cloud, inscreva-se na lista de espera se ainda não o fez. 🚀 +Você pode opcionalmente implantar sua aplicação FastAPI na FastAPI Cloud, vá e entre na lista de espera se ainda não o fez. 🚀 Se você já tem uma conta na **FastAPI Cloud** (nós convidamos você da lista de espera 😉), pode implantar sua aplicação com um único comando. @@ -506,7 +512,7 @@ Siga os tutoriais do seu provedor de nuvem para implantar aplicações FastAPI c Testes de performance da _Independent TechEmpower_ mostram aplicações **FastAPI** rodando sob Uvicorn como um dos _frameworks_ Python mais rápidos disponíveis, somente atrás de Starlette e Uvicorn (utilizados internamente pelo FastAPI). (*) -Para entender mais sobre performance, veja a seção Comparações. +Para entender mais sobre isso, veja a seção Comparações. ## Dependências { #dependencies } @@ -514,7 +520,7 @@ O FastAPI depende do Pydantic e do Starlette. ### Dependências `standard` { #standard-dependencies } -Quando você instala o FastAPI com `pip install "fastapi[standard]"`, ele vêm com o grupo `standard` (padrão) de dependências opcionais: +Quando você instala o FastAPI com `pip install "fastapi[standard]"`, ele vem com o grupo `standard` de dependências opcionais: Utilizado pelo Pydantic: @@ -524,7 +530,7 @@ Utilizado pelo Starlette: * httpx - Obrigatório caso você queira utilizar o `TestClient`. * jinja2 - Obrigatório se você quer utilizar a configuração padrão de templates. -* python-multipart - Obrigatório se você deseja suporte a "parsing" de formulário, com `request.form()`. +* python-multipart - Obrigatório se você deseja suporte a "parsing" de formulário, com `request.form()`. Utilizado pelo FastAPI: @@ -547,7 +553,7 @@ Existem algumas dependências adicionais que você pode querer instalar. Dependências opcionais adicionais do Pydantic: * pydantic-settings - para gerenciamento de configurações. -* pydantic-extra-types - tipos extras para serem utilizados com o Pydantic. +* pydantic-extra-types - para tipos extras a serem utilizados com o Pydantic. Dependências opcionais adicionais do FastAPI: diff --git a/docs/pt/docs/tutorial/bigger-applications.md b/docs/pt/docs/tutorial/bigger-applications.md index 9dec7b1968..87bd13375a 100644 --- a/docs/pt/docs/tutorial/bigger-applications.md +++ b/docs/pt/docs/tutorial/bigger-applications.md @@ -31,7 +31,7 @@ Digamos que você tenha uma estrutura de arquivos como esta: /// tip | Dica -Existem vários arquivos `__init__.py` presentes em cada diretório ou subdiretório. +Existem vários arquivos `__init__.py`: um em cada diretório ou subdiretório. Isso permite a importação de código de um arquivo para outro. @@ -43,32 +43,32 @@ from app.routers import items /// -* O diretório `app` contém todo o código da aplicação. Ele possui um arquivo `app/__init__.py` vazio, o que o torna um "pacote Python" (uma coleção de "módulos Python"): `app`. -* Dentro dele, o arquivo `app/main.py` está localizado em um pacote Python (diretório com `__init__.py`). Portanto, ele é um "módulo" desse pacote: `app.main`. -* Existem também um arquivo `app/dependencies.py`, assim como o `app/main.py`, ele é um "módulo": `app.dependencies`. +* O diretório `app` contém tudo. E possui um arquivo vazio `app/__init__.py`, então ele é um "pacote Python" (uma coleção de "módulos Python"): `app`. +* Ele contém um arquivo `app/main.py`. Como está dentro de um pacote Python (um diretório com um arquivo `__init__.py`), ele é um "módulo" desse pacote: `app.main`. +* Existe também um arquivo `app/dependencies.py`, assim como `app/main.py`, ele é um "módulo": `app.dependencies`. * Há um subdiretório `app/routers/` com outro arquivo `__init__.py`, então ele é um "subpacote Python": `app.routers`. -* O arquivo `app/routers/items.py` está dentro de um pacote, `app/routers/`, portanto, é um "submódulo": `app.routers.items`. -* O mesmo com `app/routers/users.py`, ele é outro submódulo: `app.routers.users`. -* Há também um subdiretório `app/internal/` com outro arquivo `__init__.py`, então ele é outro "subpacote Python":`app.internal`. +* O arquivo `app/routers/items.py` está dentro de um pacote, `app/routers/`, portanto é um submódulo: `app.routers.items`. +* O mesmo com `app/routers/users.py`, ele é outro submódulo: `app.routers.users`. +* Há também um subdiretório `app/internal/` com outro arquivo `__init__.py`, então ele é outro "subpacote Python": `app.internal`. * E o arquivo `app/internal/admin.py` é outro submódulo: `app.internal.admin`. A mesma estrutura de arquivos com comentários: -``` +```bash . -├── app # "app" é um pacote Python -│   ├── __init__.py # este arquivo torna "app" um "pacote Python" -│   ├── main.py # "main" módulo, e.g. import app.main -│   ├── dependencies.py # "dependencies" módulo, e.g. import app.dependencies -│   └── routers # "routers" é um "subpacote Python" -│   │ ├── __init__.py # torna "routers" um "subpacote Python" -│   │ ├── items.py # "items" submódulo, e.g. import app.routers.items -│   │ └── users.py # "users" submódulo, e.g. import app.routers.users -│   └── internal # "internal" é um "subpacote Python" -│   ├── __init__.py # torna "internal" um "subpacote Python" -│   └── admin.py # "admin" submódulo, e.g. import app.internal.admin +├── app # "app" is a Python package +│   ├── __init__.py # this file makes "app" a "Python package" +│   ├── main.py # "main" module, e.g. import app.main +│   ├── dependencies.py # "dependencies" module, e.g. import app.dependencies +│   └── routers # "routers" is a "Python subpackage" +│   │ ├── __init__.py # makes "routers" a "Python subpackage" +│   │ ├── items.py # "items" submodule, e.g. import app.routers.items +│   │ └── users.py # "users" submodule, e.g. import app.routers.users +│   └── internal # "internal" is a "Python subpackage" +│   ├── __init__.py # makes "internal" a "Python subpackage" +│   └── admin.py # "admin" submodule, e.g. import app.internal.admin ``` ## `APIRouter` { #apirouter } @@ -79,11 +79,11 @@ Você quer manter as *operações de rota* relacionadas aos seus usuários separ Mas ele ainda faz parte da mesma aplicação/web API **FastAPI** (faz parte do mesmo "pacote Python"). -Você pode criar as *operações de rotas* para esse módulo usando o `APIRouter`. +Você pode criar as *operações de rota* para esse módulo usando o `APIRouter`. ### Importe `APIRouter` { #import-apirouter } -você o importa e cria uma "instância" da mesma maneira que faria com a classe `FastAPI`: +Você o importa e cria uma "instância" da mesma maneira que faria com a classe `FastAPI`: {* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[1,3] title["app/routers/users.py"] *} @@ -91,7 +91,7 @@ você o importa e cria uma "instância" da mesma maneira que faria com a classe E então você o utiliza para declarar suas *operações de rota*. -Utilize-o da mesma maneira que utilizaria a classe `FastAPI`: +Utilize-o da mesma maneira que utilizaria a classe `FastAPI`: {* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[6,11,16] title["app/routers/users.py"] *} @@ -151,7 +151,7 @@ Então, em vez de adicionar tudo isso a cada *operação de rota*, podemos adici {* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[5:10,16,21] title["app/routers/items.py"] *} -Como o caminho de cada *operação de rota* deve começar com `/`, como em: +Como o path de cada *operação de rota* tem que começar com `/`, como em: ```Python hl_lines="1" @router.get("/{item_id}") @@ -163,9 +163,9 @@ async def read_item(item_id: str): Então, o prefixo neste caso é `/items`. -Também podemos adicionar uma lista de `tags` e `responses` extras que serão aplicadas a todas as *operações de rota* incluídas neste roteador. +Também podemos adicionar uma list de `tags` e `responses` extras que serão aplicadas a todas as *operações de rota* incluídas neste router. -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 request feita a elas. +E podemos adicionar uma list de `dependencies` que serão adicionadas a todas as *operações de rota* no router e serão executadas/resolvidas para cada request feita a elas. /// tip | Dica @@ -173,7 +173,7 @@ Observe que, assim como [dependências em *decoradores de operação de rota*](d /// -O resultado final é que os caminhos dos itens agora são: +O resultado final é que os paths dos itens agora são: * `/items/` * `/items/{item_id}` @@ -183,9 +183,9 @@ O resultado final é que os caminhos dos itens agora são: * Elas serão marcadas com uma lista de tags que contêm uma única string `"items"`. * Essas "tags" são especialmente úteis para os sistemas de documentação interativa automática (usando OpenAPI). * Todas elas incluirão as `responses` predefinidas. -* Todas essas *operações de rota* terão a lista de `dependencies` avaliada/executada antes delas. +* Todas essas *operações de rota* terão a list de `dependencies` avaliada/executada antes delas. * Se você também declarar dependências em uma *operação de rota* específica, **elas também serão executadas**. - * As dependências do 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. + * As dependências do router 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 @@ -246,7 +246,7 @@ from ..dependencies import get_token_header significa: -* Começando no mesmo pacote em que este módulo (o arquivo `app/routers/items.py`) reside (o diretório `app/routers/`)... +* Começando no mesmo pacote em que este módulo (o arquivo `app/routers/items.py`) vive (o diretório `app/routers/`)... * vá para o pacote pai (o diretório `app/`)... * e lá, encontre o módulo `dependencies` (o arquivo em `app/dependencies.py`)... * e dele, importe a função `get_token_header`. @@ -283,9 +283,9 @@ Mas ainda podemos adicionar _mais_ `tags` que serão aplicadas a uma *operação /// tip | Dica -Esta última operação de caminho terá a combinação de tags: `["items", "custom"]`. +Esta última operação de rota terá a combinação de tags: `["items", "custom"]`. -E também terá ambas as respostas na documentação, uma para `404` e uma para `403`. +E também terá ambas as responses na documentação, uma para `404` e uma para `403`. /// @@ -325,7 +325,7 @@ from .routers import items, users significa: -* Começando no mesmo pacote em que este módulo (o arquivo `app/main.py`) reside (o diretório `app/`)... +* Começando no mesmo pacote em que este módulo (o arquivo `app/main.py`) vive (o diretório `app/`)... * procure o subpacote `routers` (o diretório em `app/routers/`)... * e dele, importe o submódulo `items` (o arquivo em `app/routers/items.py`) e `users` (o arquivo em `app/routers/users.py`)... @@ -376,7 +376,7 @@ Então, para poder usar ambos no mesmo arquivo, importamos os submódulos direta {* ../../docs_src/bigger_applications/app_an_py39/main.py hl[5] title["app/main.py"] *} -### Inclua os `APIRouter`s para `usuários` e `itens` { #include-the-apirouters-for-users-and-items } +### Inclua os `APIRouter`s para `users` e `items` { #include-the-apirouters-for-users-and-items } Agora, vamos incluir os `router`s dos submódulos `users` e `items`: @@ -392,7 +392,7 @@ E `items.router` contém o `APIRouter` dentro do arquivo `app/routers/items.py`. Com `app.include_router()` podemos adicionar cada `APIRouter` ao aplicativo principal `FastAPI`. -Ele incluirá todas as rotas daquele roteador como parte dele. +Ele incluirá todas as rotas daquele router como parte dele. /// note | Detalhes Técnicos @@ -404,7 +404,7 @@ Então, nos bastidores, ele realmente funcionará como se tudo fosse o mesmo apl /// check | Verifique -Você não precisa se preocupar com desempenho ao incluir roteadores. +Você não precisa se preocupar com desempenho ao incluir routers. Isso levará microssegundos e só acontecerá na inicialização. @@ -453,7 +453,7 @@ e funcionará corretamente, junto com todas as outras *operações de rota* adic /// note | Detalhes Técnicos Avançados -**Observação**: este é um detalhe muito técnico que você provavelmente pode **simplesmente pular**. +**Nota**: este é um detalhe muito técnico que você provavelmente pode **simplesmente pular**. --- @@ -479,15 +479,15 @@ $ fastapi dev app/main.py -E abra os documentos em http://127.0.0.1:8000/docs. +E abra a documentação em http://127.0.0.1:8000/docs. -Você verá a documentação automática da API, incluindo os caminhos de todos os submódulos, usando os caminhos (e prefixos) corretos e as tags corretas: +Você verá a documentação automática da API, incluindo os paths de todos os submódulos, usando os paths (e prefixos) corretos e as tags corretas: -## Inclua o mesmo roteador várias vezes com `prefix` diferentes { #include-the-same-router-multiple-times-with-different-prefix } +## Inclua o mesmo router várias vezes com `prefix` diferentes { #include-the-same-router-multiple-times-with-different-prefix } -Você também pode usar `.include_router()` várias vezes com o *mesmo* roteador usando prefixos diferentes. +Você também pode usar `.include_router()` várias vezes com o *mesmo* router usando prefixos diferentes. Isso pode ser útil, por exemplo, para expor a mesma API sob prefixos diferentes, por exemplo, `/api/v1` e `/api/latest`. @@ -495,10 +495,10 @@ Esse é um uso avançado que você pode não precisar, mas está lá caso precis ## Inclua um `APIRouter` em outro { #include-an-apirouter-in-another } -Da mesma forma que você pode incluir um `APIRouter` em um aplicativo `FastAPI`, você pode incluir um `APIRouter` em outro `APIRouter` usando: +Da mesma forma que você pode incluir um `APIRouter` em uma aplicação `FastAPI`, você pode incluir um `APIRouter` em outro `APIRouter` usando: ```Python router.include_router(other_router) ``` -Certifique-se de fazer isso antes de incluir `router` no aplicativo `FastAPI`, para que as *operações de rota* de `other_router` também sejam incluídas. +Certifique-se de fazer isso antes de incluir `router` na aplicação `FastAPI`, para que as *operações de rota* de `other_router` também sejam incluídas. diff --git a/docs/pt/docs/tutorial/body-updates.md b/docs/pt/docs/tutorial/body-updates.md index 67bf684925..95f89c8d23 100644 --- a/docs/pt/docs/tutorial/body-updates.md +++ b/docs/pt/docs/tutorial/body-updates.md @@ -1,6 +1,6 @@ # Corpo - Atualizações { #body-updates } -## Atualização de dados existentes com `PUT` { #update-replacing-with-put } +## Atualização substituindo com `PUT` { #update-replacing-with-put } Para atualizar um item, você pode usar a operação HTTP `PUT`. @@ -22,13 +22,13 @@ Isso significa que, se você quiser atualizar o item `bar` usando `PUT` com um c } ``` -Como ele não inclui o atributo já armazenado `"tax": 20.2`, o modelo de entrada assumiria o valor padrão de `"tax": 10.5`. +como ele não inclui o atributo já armazenado `"tax": 20.2`, o modelo de entrada assumiria o valor padrão de `"tax": 10.5`. E os dados seriam salvos com esse "novo" `tax` de `10.5`. ## Atualizações parciais com `PATCH` { #partial-updates-with-patch } -Você também pode usar a operação HTTP `PATCH` para atualizar parcialmente os dados. +Você também pode usar a operação HTTP `PATCH` para atualizar dados *parcialmente*. Isso significa que você pode enviar apenas os dados que deseja atualizar, deixando o restante intacto. @@ -40,25 +40,17 @@ E muitas equipes usam apenas `PUT`, mesmo para atualizações parciais. Você é **livre** para usá-los como preferir, **FastAPI** não impõe restrições. -Mas este guia te dá uma ideia de como eles são destinados a serem usados. +Mas este guia mostra, mais ou menos, como eles são destinados a serem usados. /// ### Usando o parâmetro `exclude_unset` do Pydantic { #using-pydantics-exclude-unset-parameter } -Se você quiser receber atualizações parciais, é muito útil usar o parâmetro `exclude_unset` no método `.model_dump()` do modelo do Pydantic. +Se você quiser receber atualizações parciais, é muito útil usar o parâmetro `exclude_unset` no `.model_dump()` do modelo do Pydantic. Como `item.model_dump(exclude_unset=True)`. -/// info | Informação - -No Pydantic v1, o método que era chamado `.dict()` e foi descontinuado (mas ainda suportado) no Pydantic v2. Agora, deve-se usar o método `.model_dump()`. - -Os exemplos aqui usam `.dict()` para compatibilidade com o Pydantic v1, mas você deve usar `.model_dump()` a partir do Pydantic v2. - -/// - -Isso gera um `dict` com apenas os dados definidos ao criar o modelo `item`, excluindo os valores padrão. +Isso geraria um `dict` com apenas os dados que foram definidos ao criar o modelo `item`, excluindo os valores padrão. Então, você pode usar isso para gerar um `dict` com apenas os dados definidos (enviados na solicitação), omitindo valores padrão: @@ -68,31 +60,23 @@ Então, você pode usar isso para gerar um `dict` com apenas os dados definidos Agora, você pode criar uma cópia do modelo existente usando `.model_copy()`, e passar o parâmetro `update` com um `dict` contendo os dados para atualizar. -/// info | Informação - -No Pydantic v1, o método era chamado `.copy()`, ele foi descontinuado (mas ainda suportado) no Pydantic v2, e renomeado para `.model_copy()`. - -Os exemplos aqui usam `.copy()` para compatibilidade com o Pydantic v1, mas você deve usar `.model_copy()` com o Pydantic v2. - -/// - Como `stored_item_model.model_copy(update=update_data)`: {* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *} ### Recapitulando as atualizações parciais { #partial-updates-recap } -Resumindo, para aplicar atualizações parciais você pode: +Resumindo, para aplicar atualizações parciais você deveria: * (Opcionalmente) usar `PATCH` em vez de `PUT`. * Recuperar os dados armazenados. * Colocar esses dados em um modelo do Pydantic. * Gerar um `dict` sem valores padrão a partir do modelo de entrada (usando `exclude_unset`). - * Dessa forma, você pode atualizar apenas os valores definidos pelo usuário, em vez de substituir os valores já armazenados com valores padrão em seu modelo. + * Dessa forma, você pode atualizar apenas os valores realmente definidos pelo usuário, em vez de substituir valores já armazenados por valores padrão do modelo. * Criar uma cópia do modelo armazenado, atualizando seus atributos com as atualizações parciais recebidas (usando o parâmetro `update`). -* Converter o modelo copiado em algo que possa ser armazenado no seu banco de dados (por exemplo, usando o `jsonable_encoder`). - * Isso é comparável ao uso do método `.model_dump()`, mas garante (e converte) os valores para tipos de dados que possam ser convertidos em JSON, por exemplo, `datetime` para `str`. -* Salvar os dados no seu banco de dados. +* Converter o modelo copiado em algo que possa ser armazenado no seu BD (por exemplo, usando o `jsonable_encoder`). + * Isso é comparável a usar o método `.model_dump()` do modelo novamente, mas garante (e converte) os valores para tipos de dados que possam ser convertidos em JSON, por exemplo, `datetime` para `str`. +* Salvar os dados no seu BD. * Retornar o modelo atualizado. {* ../../docs_src/body_updates/tutorial002_py310.py hl[28:35] *} @@ -109,8 +93,8 @@ Mas o exemplo aqui usa `PATCH` porque foi criado para esses casos de uso. Observe que o modelo de entrada ainda é validado. -Portanto, se você quiser receber atualizações parciais que possam omitir todos os atributos, precisará ter um modelo com todos os atributos marcados como opcionais (com valores padrão ou `None`). +Portanto, se você quiser receber atualizações parciais que possam omitir todos os atributos, você precisa ter um modelo com todos os atributos marcados como opcionais (com valores padrão ou `None`). -Para distinguir os modelos com todos os valores opcionais para **atualizações** e modelos com valores obrigatórios para **criação**, você pode usar as ideias descritas em [Modelos Adicionais](extra-models.md){.internal-link target=_blank}. +Para distinguir entre os modelos com todos os valores opcionais para **atualizações** e modelos com valores obrigatórios para **criação**, você pode usar as ideias descritas em [Modelos Adicionais](extra-models.md){.internal-link target=_blank}. /// diff --git a/docs/pt/docs/tutorial/body.md b/docs/pt/docs/tutorial/body.md index 1330f4458f..669334439a 100644 --- a/docs/pt/docs/tutorial/body.md +++ b/docs/pt/docs/tutorial/body.md @@ -10,11 +10,11 @@ Para declarar um corpo da **requisição**, você utiliza os modelos do 0.95.0) exigiam que você usasse `Query` como valor padrão do seu parâmetro, em vez de colocá-lo em `Annotated`. É muito provável que você veja código assim por aí, então vou te explicar. +Versões anteriores do FastAPI (antes de 0.95.0) exigiam que você usasse `Query` como valor padrão do seu parâmetro, em vez de colocá-lo em `Annotated`, há uma grande chance de você ver código usando isso por aí, então vou explicar. /// tip | Dica @@ -192,7 +192,7 @@ Você também pode adicionar um parâmetro `min_length`: ## Adicione expressões regulares { #add-regular-expressions } -Você pode definir um `pattern` de expressão regular que o parâmetro deve corresponder: +Você pode definir um `pattern` de expressão regular que o parâmetro deve corresponder: {* ../../docs_src/query_params_str_validations/tutorial004_an_py310.py hl[11] *} @@ -206,20 +206,6 @@ Se você se sentir perdido com essas ideias de **"expressão regular"**, não se Agora você sabe que, sempre que precisar delas, pode usá-las no **FastAPI**. -### Pydantic v1 `regex` em vez de `pattern` { #pydantic-v1-regex-instead-of-pattern } - -Antes da versão 2 do Pydantic e antes do FastAPI 0.100.0, o parâmetro se chamava `regex` em vez de `pattern`, mas agora está descontinuado. - -Você ainda pode ver algum código usando isso: - -//// tab | Pydantic v1 - -{* ../../docs_src/query_params_str_validations/tutorial004_regex_an_py310.py hl[11] *} - -//// - -Mas saiba que isso está descontinuado e deve ser atualizado para usar o novo parâmetro `pattern`. 🀓 - ## Valores padrão { #default-values } Você pode, claro, usar valores padrão diferentes de `None`. @@ -280,7 +266,7 @@ Então, com uma URL como: http://localhost:8000/items/?q=foo&q=bar ``` -você receberá os múltiplos valores do *parâmetro de consulta* `q` (`foo` e `bar`) em uma `list` Python dentro da sua *função de operação de rota*, no *parâmetro da função* `q`. +você receberia os múltiplos valores dos *parâmetros de consulta* `q` (`foo` e `bar`) em uma `list` Python dentro da sua *função de operação de rota*, no *parâmetro da função* `q`. Assim, a resposta para essa URL seria: @@ -350,7 +336,7 @@ Essas informações serão incluídas no OpenAPI gerado e usadas pelas interface Tenha em mente que ferramentas diferentes podem ter níveis diferentes de suporte ao OpenAPI. -Algumas delas podem ainda não mostrar todas as informações extras declaradas, embora na maioria dos casos o recurso ausente já esteja planejado para desenvolvimento. +Algumas delas podem ainda não mostrar todas as informações extras declaradas, embora na maioria dos casos a funcionalidade ausente já esteja planejada para desenvolvimento. /// @@ -386,7 +372,7 @@ Então você pode declarar um `alias`, e esse alias será usado para encontrar o Agora digamos que você não gosta mais desse parâmetro. -Você tem que deixá-lo por um tempo, pois há clientes usando-o, mas quer que a documentação mostre claramente que ele está descontinuado. +Você tem que deixá-lo por um tempo, pois há clientes usando-o, mas quer que a documentação mostre claramente que ele está deprecated. Então passe o parâmetro `deprecated=True` para `Query`: @@ -416,7 +402,7 @@ O Pydantic também tem ISBN ou com `imdb-` para um ID de URL de filme IMDB: +Por exemplo, este validador personalizado verifica se o ID do item começa com `isbn-` para um número de livro ISBN ou com `imdb-` para um ID de URL de filme IMDB: {* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *} @@ -428,7 +414,7 @@ Isso está disponível com a versão 2 do Pydantic ou superior. 😎 /// tip | Dica -Se você precisar fazer qualquer tipo de validação que exija comunicação com algum **componente externo**, como um banco de dados ou outra API, você deve usar **Dependências do FastAPI** em vez disso; você aprenderá sobre elas mais adiante. +Se você precisar fazer qualquer tipo de validação que exija comunicação com algum **componente externo**, como um banco de dados ou outra API, você deveria usar **Dependências do FastAPI** em vez disso; você aprenderá sobre elas mais adiante. Esses validadores personalizados são para coisas que podem ser verificadas **apenas** com os **mesmos dados** fornecidos na requisição. @@ -440,7 +426,7 @@ O ponto importante é apenas usar **`AfterValidator` com uma função dentro de --- -Mas se você está curioso sobre este exemplo específico e ainda entretido, aqui vão alguns detalhes extras. +Mas se você estiver curioso sobre este exemplo de código específico e ainda entretido, aqui vão alguns detalhes extras. #### String com `value.startswith()` { #string-with-value-startswith } @@ -450,7 +436,7 @@ Percebeu? Uma string usando `value.startswith()` pode receber uma tupla, e verif #### Um item aleatório { #a-random-item } -Com `data.items()` obtemos um objeto iterável com tuplas contendo a chave e o valor de cada item do dicionário. +Com `data.items()` obtemos um objeto iterável com tuplas contendo a chave e o valor de cada item do dicionário. Convertimos esse objeto iterável em uma `list` adequada com `list(data.items())`. diff --git a/docs/pt/docs/tutorial/response-model.md b/docs/pt/docs/tutorial/response-model.md index dc66bb46c4..8a7a712488 100644 --- a/docs/pt/docs/tutorial/response-model.md +++ b/docs/pt/docs/tutorial/response-model.md @@ -252,20 +252,6 @@ Então, se você enviar uma solicitação para essa *operação de rota* para o /// info | Informação -No Pydantic v1, o método era chamado `.dict()`, ele foi descontinuado (mas ainda suportado) no Pydantic v2 e renomeado para `.model_dump()`. - -Os exemplos aqui usam `.dict()` para compatibilidade com Pydantic v1, mas você deve usar `.model_dump()` em vez disso se puder usar Pydantic v2. - -/// - -/// info | Informação - -O FastAPI usa `.dict()` do modelo Pydantic com seu parâmetro `exclude_unset` para chegar a isso. - -/// - -/// info | Informação - Você também pode usar: * `response_model_exclude_defaults=True` diff --git a/docs/pt/docs/tutorial/schema-extra-example.md b/docs/pt/docs/tutorial/schema-extra-example.md index bddd320cd3..2d62ffd851 100644 --- a/docs/pt/docs/tutorial/schema-extra-example.md +++ b/docs/pt/docs/tutorial/schema-extra-example.md @@ -8,39 +8,17 @@ Aqui estão várias maneiras de fazer isso. Você pode declarar `examples` para um modelo Pydantic que serão adicionados ao JSON Schema gerado. -//// tab | Pydantic v2 - {* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *} -//// - -//// tab | Pydantic v1 - -{* ../../docs_src/schema_extra_example/tutorial001_pv1_py310.py hl[13:23] *} - -//// - Essas informações extras serão adicionadas como estão ao **JSON Schema** de saída para esse modelo e serão usadas na documentação da API. -//// tab | Pydantic v2 - -Na versão 2 do Pydantic, você usaria o atributo `model_config`, que recebe um `dict`, conforme descrito na documentação do Pydantic: Configuration. +Você pode usar o atributo `model_config`, que recebe um `dict`, conforme descrito na documentação do Pydantic: Configuration. Você pode definir `"json_schema_extra"` com um `dict` contendo quaisquer dados adicionais que você queira que apareçam no JSON Schema gerado, incluindo `examples`. -//// - -//// tab | Pydantic v1 - -Na versão 1 do Pydantic, você usaria uma classe interna `Config` e `schema_extra`, conforme descrito na documentação do Pydantic: Schema customization. - -Você pode definir `schema_extra` com um `dict` contendo quaisquer dados adicionais que você queira que apareçam no JSON Schema gerado, incluindo `examples`. - -//// - /// tip | Dica -Você pode usar a mesma técnica para estender o JSON Schema e adicionar suas próprias informações extras personalizadas. +Você poderia usar a mesma técnica para estender o JSON Schema e adicionar suas próprias informações extras personalizadas. Por exemplo, você poderia usá-la para adicionar metadados para uma interface de usuário de front-end, etc. @@ -50,7 +28,7 @@ Por exemplo, você poderia usá-la para adicionar metadados para uma interface d O OpenAPI 3.1.0 (usado desde o FastAPI 0.99.0) adicionou suporte a `examples`, que faz parte do padrão **JSON Schema**. -Antes disso, ele suportava apenas a palavra‑chave `example` com um único exemplo. Isso ainda é suportado pelo OpenAPI 3.1.0, mas é descontinuado e não faz parte do padrão JSON Schema. Portanto, é recomendado migrar de `example` para `examples`. 🀓 +Antes disso, ele suportava apenas a palavra‑chave `example` com um único exemplo. Isso ainda é suportado pelo OpenAPI 3.1.0, mas é descontinuado e não faz parte do padrão JSON Schema. Portanto, você é incentivado a migrar de `example` para `examples`. 🀓 Você pode ler mais no final desta página. @@ -102,7 +80,7 @@ No entanto, no momento em que isto foi escrito, Antes do **JSON Schema** suportar `examples`, o OpenAPI já tinha suporte para um campo diferente também chamado `examples`. -Esse `examples` específico do OpenAPI vai em outra seção da especificação. Ele fica nos **detalhes de cada função de operação de rota**, não dentro de cada JSON Schema. +Esse `examples` **específico do OpenAPI** vai em outra seção da especificação OpenAPI. Ele fica nos **detalhes de cada *operação de rota***, não dentro de cada JSON Schema. E o Swagger UI tem suportado esse campo `examples` particular há algum tempo. Então, você pode usá-lo para **mostrar** diferentes **exemplos na UI da documentação**. @@ -189,9 +167,9 @@ Depois, o JSON Schema adicionou um campo Date: Tue, 20 Jan 2026 20:40:39 +0000 Subject: [PATCH 026/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 7c5460f1df..33926e3afc 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -18,6 +18,7 @@ hide: ### Translations +* 🌐 Update translations for pt (update-outdated). PR [#14724](https://github.com/fastapi/fastapi/pull/14724) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update Korean LLM prompt. PR [#14740](https://github.com/fastapi/fastapi/pull/14740) by [@hard-coders](https://github.com/hard-coders). * 🌐 Improve LLM prompt for Turkish translations. PR [#14728](https://github.com/fastapi/fastapi/pull/14728) by [@Kadermiyanyedi](https://github.com/Kadermiyanyedi). * 🌐 Update portuguese llm-prompt.md. PR [#14702](https://github.com/fastapi/fastapi/pull/14702) by [@ceb10n](https://github.com/ceb10n). From 2eb978b87a2227801cc9abaeddd5e27d941af868 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Tue, 20 Jan 2026 15:03:07 -0800 Subject: [PATCH 027/108] =?UTF-8?q?=F0=9F=8C=90=20Update=20translations=20?= =?UTF-8?q?for=20ru=20(update-outdated)=20(#14693)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 🌐 Update translations for ru (update-outdated) * 🎚 Auto format * Apply suggestions from code review * Apply suggestions from code review 2 * Apply suggestions from code review 3 --------- Co-authored-by: github-actions[bot] Co-authored-by: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> --- docs/ru/docs/_llm-test.md | 18 +- .../path-operation-advanced-configuration.md | 56 +--- docs/ru/docs/advanced/settings.md | 44 --- ...migrate-from-pydantic-v1-to-pydantic-v2.md | 28 +- .../docs/how-to/separate-openapi-schemas.md | 16 +- docs/ru/docs/index.md | 40 +-- docs/ru/docs/tutorial/bigger-applications.md | 289 +++++++++--------- docs/ru/docs/tutorial/body-updates.md | 34 +-- docs/ru/docs/tutorial/body.md | 22 +- docs/ru/docs/tutorial/extra-models.md | 62 ++-- .../tutorial/query-params-str-validations.md | 30 +- docs/ru/docs/tutorial/response-model.md | 72 ++--- docs/ru/docs/tutorial/schema-extra-example.md | 30 +- 13 files changed, 297 insertions(+), 444 deletions(-) diff --git a/docs/ru/docs/_llm-test.md b/docs/ru/docs/_llm-test.md index 9a15f6bb21..6a0272f3a5 100644 --- a/docs/ru/docs/_llm-test.md +++ b/docs/ru/docs/_llm-test.md @@ -1,8 +1,8 @@ # ТестПвый файл LLM { #llm-test-file } -ЭтПт ЎПкуЌеМт прПверяет, пПМОЌает лО LLM, перевПЎящая ЎПкуЌеМтацОю, `general_prompt` в `scripts/translate.py` О языкПвПй спецОфОчМый прПЌпт в `docs/{language code}/llm-prompt.md`. ЯзыкПвПй спецОфОчМый прПЌпт ЎПбавляется к `general_prompt`. +ЭтПт ЎПкуЌеМт прПверяет, пПМОЌает лО LLM, перевПЎящая ЎПкуЌеМтацОю, `general_prompt` в `scripts/translate.py` О языкПвПй спецОфОчМый прПЌпт в `docs/{language code}/llm-prompt.md`. ЯзыкПвПй спецОфОчМый прПЌпт ЎПбавляется к `general_prompt`. -Тесты, ЎПбавлеММые зЎесь, увОЎят все сПзЎателО языкПвых прПЌптПв. +Тесты, ЎПбавлеММые зЎесь, увОЎят все сПзЎателО языкПвых спецОфОчМых прПЌптПв. ИспПльзПваМОе: @@ -11,7 +11,7 @@ * ПрПверьте, всё лО в пПряЎке в перевПЎе. * ПрО МеПбхПЎОЌПстО улучшОте ваш языкПвПй спецОфОчМый прПЌпт, ПбщОй прПЌпт ОлО аМглОйскОй ЎПкуЌеМт. * ЗатеЌ вручМую Осправьте ПставшОеся прПблеЌы в перевПЎе, чтПбы ПМ был хПрПшОЌ. -* ПеревеЎОте заМПвП, ОЌея хПрПшОй перевПЎ Ма Ќесте. ИЎеальМыЌ результатПЌ буЎет сОтуацОя, кПгЎа LLM бПльше Ме вМПсОт ОзЌеМеМОй в перевПЎ. ЭтП ПзМачает, чтП ПбщОй прПЌпт О ваш языкПвПй спецОфОчМый прПЌпт ЌаксОЌальМП хПрПшО (ОМПгЎа ПМ буЎет Ўелать МескПлькП, казалПсь бы, случайМых ОзЌеМеМОй, прОчОМа в тПЌ, чтП LLM — МеЎетерЌОМОрПваММые алгПрОтЌы). +* ПеревеЎОте заМПвП, ОЌея хПрПшОй перевПЎ Ма Ќесте. ИЎеальМыЌ результатПЌ буЎет сОтуацОя, кПгЎа LLM бПльше Ме вМПсОт ОзЌеМеМОй в перевПЎ. ЭтП ПзМачает, чтП ПбщОй прПЌпт О ваш языкПвПй спецОфОчМый прПЌпт МастПлькП хПрПшО, МаскПлькП этП вПзЌПжМП (ОМПгЎа ПМ буЎет Ўелать МескПлькП, казалПсь бы, случайМых ОзЌеМеМОй, прОчОМа в тПЌ, чтП LLM — МеЎетерЌОМОрПваММые алгПрОтЌы). Тесты: @@ -197,10 +197,10 @@ works(foo="bar") # ЭтП рабПтает 🎉 ### abbr Ўаёт пПлМую расшОфрПвку { #the-abbr-gives-a-full-phrase } -* GTD -* lt -* XWT -* PSGI +* GTD +* lt +* XWT +* PSGI ### abbr Ўаёт ПбъясМеМОе { #the-abbr-gives-an-explanation } @@ -209,8 +209,8 @@ works(foo="bar") # ЭтП рабПтает 🎉 ### abbr Ўаёт пПлМую расшОфрПвку О ПбъясМеМОе { #the-abbr-gives-a-full-phrase-and-an-explanation } -* MDN -* I/O. +* MDN +* I/O. //// diff --git a/docs/ru/docs/advanced/path-operation-advanced-configuration.md b/docs/ru/docs/advanced/path-operation-advanced-configuration.md index eaf9ad0528..86d3a5b630 100644 --- a/docs/ru/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/ru/docs/advanced/path-operation-advanced-configuration.md @@ -14,7 +14,7 @@ {* ../../docs_src/path_operation_advanced_configuration/tutorial001_py39.py hl[6] *} -### ИспПльзПваМОе ОЌеМО фуМкцОО-ПбрабПтчОка путО как operationId { #using-the-path-operation-function-name-as-the-operationid } +### ИспПльзПваМОе ОЌеМО *фуМкцОО-ПбрабПтчОка путО* как operationId { #using-the-path-operation-function-name-as-the-operationid } ЕслО вы хПтОте ОспПльзПвать ОЌеМа фуМкцОй вашОх API в качестве `operationId`, вы ЌПжете прПйтО пП всеЌ Оз МОх О переПпреЎелОть `operation_id` кажЎПй *ПперацОО путО* с пПЌПщью Ох `APIRoute.name`. @@ -38,7 +38,7 @@ ## ИсключОть Оз OpenAPI { #exclude-from-openapi } -ЧтПбы ОсключОть *ПперацОю путО* Оз геМерОруеЌПй схеЌы OpenAPI (а зМачОт, О Оз автПЌатОческПй ЎПкуЌеМтацОО), ОспПльзуйте параЌетр `include_in_schema` О устаМПвОте егП в `False`: +ЧтПбы ОсключОть *ПперацОю путО* Оз геМерОруеЌПй схеЌы OpenAPI (а зМачОт, О Оз автПЌатОческОх сОстеЌ ЎПкуЌеМтацОО), ОспПльзуйте параЌетр `include_in_schema` О устаМПвОте егП в `False`: {* ../../docs_src/path_operation_advanced_configuration/tutorial003_py39.py hl[6] *} @@ -48,7 +48,7 @@ ДПбавлеМОе `\f` (экраМОрПваММПгП сОЌвПла «form feed») заставОт **FastAPI** Пбрезать текст, ОспПльзуеЌый Ўля OpenAPI, в этПй тПчке. -Эта часть Ме пПпаЎёт в ЎПкуЌеМтацОю, МП ЎругОе ОМструЌеМты (МапрОЌер, Sphinx) сЌПгут ОспПльзПвать ПстальМПе. +ЭтП Ме ПтПбразОтся в ЎПкуЌеМтацОО, МП ЎругОе ОМструЌеМты (МапрОЌер, Sphinx) сЌПгут ОспПльзПвать ПстальМПе. {* ../../docs_src/path_operation_advanced_configuration/tutorial004_py310.py hl[17:27] *} @@ -56,7 +56,7 @@ Вы, верПятМП, уже вОЎелО, как Пбъявлять `response_model` О `status_code` Ўля *ПперацОО путО*. -ЭтП ПпреЎеляет ЌетаЎаММые Пб ПсМПвМПЌ Птвете *ПперацОО путО*. +ЭтП ПпреЎеляет ЌетаЎаММые Пб ПсМПвМПЌ HTTP-Птвете *ПперацОО путО*. Также ЌПжМП Пбъявлять ЎПпПлМОтельМые Птветы с Ох ЌПЎеляЌО, статус-кПЎаЌО О т.ÐŽ. @@ -76,7 +76,7 @@ ТаЌ есть `tags`, `parameters`, `requestBody`, `responses` О т.ÐŽ. -Эта спецОфОкацОя OpenAPI, спецОфОчМая Ўля *ПперацОО путО*, ПбычМП геМерОруется автПЌатОческО **FastAPI**, МП вы также ЌПжете её расшОрОть. +Эта спецОфОчМая Ўля *ПперацОО путО* схеЌа OpenAPI ПбычМП геМерОруется автПЌатОческО **FastAPI**, МП вы также ЌПжете её расшОрОть. /// tip | СПвет @@ -129,13 +129,13 @@ } ``` -### ППльзПвательская схеЌа OpenAPI Ўля ПперацОО путО { #custom-openapi-path-operation-schema } +### ППльзПвательская схеЌа OpenAPI Ўля *ПперацОО путО* { #custom-openapi-path-operation-schema } -СлПварь в `openapi_extra` буЎет ПбъеЎОМёМ с автПЌатОческО сгеМерОрПваММПй схеЌПй OpenAPI Ўля *ПперацОО путО*. +СлПварь в `openapi_extra` буЎет глубПкП ПбъеЎОМёМ с автПЌатОческО сгеМерОрПваММПй схеЌПй OpenAPI Ўля *ПперацОО путО*. ТакОЌ ПбразПЌ, вы ЌПжете ЎПбавОть ЎПпПлМОтельМые ЎаММые к автПЌатОческО сгеМерОрПваММПй схеЌе. -НапрОЌер, вы ЌПжете решОть чОтать О валОЎОрПвать запрПс свПОЌ кПЎПЌ, Ме ОспПльзуя автПЌатОческОе вПзЌПжМПстО FastAPI О Pydantic, МП прО этПЌ захПтОте ПпОсать запрПс в схеЌе OpenAPI. +НапрОЌер, вы ЌПжете решОть чОтать О валОЎОрПвать HTTP-запрПс свПОЌ кПЎПЌ, Ме ОспПльзуя автПЌатОческОе вПзЌПжМПстО FastAPI О Pydantic, МП прО этПЌ захПтОте ПпОсать HTTP-запрПс в схеЌе OpenAPI. ЭтП ЌПжМП сЎелать с пПЌПщью `openapi_extra`: @@ -149,52 +149,20 @@ ИспПльзуя тПт же прОёЌ, вы ЌПжете вПспПльзПваться Pydantic-ЌПЎелью, чтПбы ПпреЎелОть JSON Schema, кПтПрая затеЌ буЎет включеМа в пПльзПвательскОй разЎел схеЌы OpenAPI Ўля *ПперацОО путО*. -И вы ЌПжете сЎелать этП, Ўаже еслО тОп ЎаММых в запрПсе — Ме JSON. +И вы ЌПжете сЎелать этП, Ўаже еслО тОп ЎаММых в HTTP-запрПсе — Ме JSON. -НапрОЌер, в этПЌ прОлПжеМОО Ќы Ме ОспПльзуеЌ встрПеММую фуМкцОПМальМПсть FastAPI Ўля ОзвлечеМОя JSON Schema Оз ЌПЎелей Pydantic, равМП как О автПЌатОческую валОЎацОю JSON. Мы ПбъявляеЌ тОп сПЎержОЌПгП запрПса как YAML, а Ме JSON: - -//// tab | Pydantic v2 +НапрОЌер, в этПЌ прОлПжеМОО Ќы Ме ОспПльзуеЌ встрПеММую фуМкцОПМальМПсть FastAPI Ўля ОзвлечеМОя JSON Schema Оз ЌПЎелей Pydantic, равМП как О автПЌатОческую валОЎацОю JSON. Мы ПбъявляеЌ тОп сПЎержОЌПгП HTTP-запрПса как YAML, а Ме JSON: {* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[15:20, 22] *} -//// - -//// tab | Pydantic v1 - -{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1_py39.py hl[15:20, 22] *} - -//// - -/// info | ИМфПрЌацОя - -В Pydantic версОО 1 ЌетПЎ Ўля пПлучеМОя JSON Schema ЌПЎелО Мазывался `Item.schema()`, в Pydantic версОО 2 ЌетПЎ Мазывается `Item.model_json_schema()`. - -/// - ТеЌ Ме ЌеМее, хПтя Ќы Ме ОспПльзуеЌ встрПеММую фуМкцОПМальМПсть пП уЌПлчаМОю, Ќы всё равМП ОспПльзуеЌ Pydantic-ЌПЎель, чтПбы вручМую сгеМерОрПвать JSON Schema Ўля ЎаММых, кПтПрые Ќы хПтОЌ пПлучОть в YAML. -ЗатеЌ Ќы рабПтаеЌ с запрПсПЌ МапряЌую О ОзвлекаеЌ телП как `bytes`. ЭтП ПзМачает, чтП FastAPI Ўаже Ме пПпытается распарсОть пПлезМую Магрузку запрПса как JSON. +ЗатеЌ Ќы рабПтаеЌ с HTTP-запрПсПЌ МапряЌую О ОзвлекаеЌ телП как `bytes`. ЭтП ПзМачает, чтП FastAPI Ўаже Ме пПпытается распарсОть пПлезМую Магрузку HTTP-запрПса как JSON. -А затеЌ в МашеЌ кПЎе Ќы МапряЌую парсОЌ этПт YAML О сМПва ОспПльзуеЌ ту же Pydantic-ЌПЎель Ўля валОЎацОО YAML-сПЎержОЌПгП: - -//// tab | Pydantic v2 +А затеЌ в МашеЌ кПЎе Ќы МапряЌую парсОЌ этП сПЎержОЌПе YAML О сМПва ОспПльзуеЌ ту же Pydantic-ЌПЎель, чтПбы валОЎОрПвать YAML-сПЎержОЌПе: {* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[24:31] *} -//// - -//// tab | Pydantic v1 - -{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1_py39.py hl[24:31] *} - -//// - -/// info | ИМфПрЌацОя - -В Pydantic версОО 1 ЌетПЎ Ўля парсОМга О валОЎацОО Пбъекта Мазывался `Item.parse_obj()`, в Pydantic версОО 2 ЌетПЎ Мазывается `Item.model_validate()`. - -/// - /// tip | СПвет ЗЎесь Ќы переОспПльзуеЌ ту же Pydantic-ЌПЎель. diff --git a/docs/ru/docs/advanced/settings.md b/docs/ru/docs/advanced/settings.md index b96ee44a3a..8408faebff 100644 --- a/docs/ru/docs/advanced/settings.md +++ b/docs/ru/docs/advanced/settings.md @@ -46,12 +46,6 @@ $ pip install "fastapi[all]" -/// info | ИМфПрЌацОя - -В Pydantic v1 ПМ вхПЎОл в ПсМПвМПй пакет. Теперь ПМ распрПстраМяется как ПтЎельМый пакет, чтПбы вы ЌПглО устаМПвОть егП тПлькП прО МеПбхПЎОЌПстО. - -/// - ### СПзЎаМОе Пбъекта `Settings` { #create-the-settings-object } ИЌпПртОруйте `BaseSettings` Оз Pydantic О сПзЎайте пПЎкласс, ПчеМь пПхПжОй Ма Pydantic‑ЌПЎель. @@ -60,24 +54,8 @@ $ pip install "fastapi[all]" Вы ЌПжете ОспПльзПвать все те же вПзЌПжМПстО валОЎацОО О ОМструЌеМты, чтП О Ўля Pydantic‑ЌПЎелей, МапрОЌер разМые тОпы ЎаММых О ЎПпПлМОтельМую валОЎацОю через `Field()`. -//// tab | Pydantic v2 - {* ../../docs_src/settings/tutorial001_py39.py hl[2,5:8,11] *} -//// - -//// tab | Pydantic v1 - -/// info | ИМфПрЌацОя - -В Pydantic v1 вы бы ОЌпПртОрПвалО `BaseSettings` МапряЌую Оз `pydantic`, а Ме Оз `pydantic_settings`. - -/// - -{* ../../docs_src/settings/tutorial001_pv1_py39.py hl[2,5:8,11] *} - -//// - /// tip | СПвет ЕслО ваЌ МужМП чтП-тП быстрП скПпОрПвать О вставОть, Ме ОспПльзуйте этПт прОЌер — вПспПльзуйтесь пПслеЎМОЌ МОже. @@ -215,8 +193,6 @@ APP_NAME="ChimichangApp" ЗатеЌ ПбМПвОте ваш `config.py` так: -//// tab | Pydantic v2 - {* ../../docs_src/settings/app03_an_py39/config.py hl[9] *} /// tip | СПвет @@ -225,26 +201,6 @@ APP_NAME="ChimichangApp" /// -//// - -//// tab | Pydantic v1 - -{* ../../docs_src/settings/app03_an_py39/config_pv1.py hl[9:10] *} - -/// tip | СПвет - -Класс `Config` ОспПльзуется тПлькП Ўля кПМфОгурацОО Pydantic. ППЎрПбМее сЌ. Pydantic Model Config. - -/// - -//// - -/// info | ИМфПрЌацОя - -В Pydantic версОО 1 кПМфОгурацОя заЎавалась вП вМутреММеЌ классе `Config`, в Pydantic версОО 2 — в атрОбуте `model_config`. ЭтПт атрОбут прОМОЌает `dict`, О чтПбы пПлучОть автПзавершеМОе О ПшОбкО «Ма лету», вы ЌПжете ОЌпПртОрПвать О ОспПльзПвать `SettingsConfigDict` Ўля ПпОсаМОя этПгП `dict`. - -/// - ЗЎесь Ќы заЎаеЌ параЌетр кПМфОгурацОО `env_file` вМутрО вашегП класса Pydantic `Settings` О устаМавлОваеЌ зМачеМОе равМыЌ ОЌеМО файла dotenv, кПтПрый хПтОЌ ОспПльзПвать. ### СПзЎаМОе `Settings` тПлькП ПЎОМ раз с пПЌПщью `lru_cache` { #creating-the-settings-only-once-with-lru-cache } diff --git a/docs/ru/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/ru/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index 95481bc668..2b47c08f67 100644 --- a/docs/ru/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/ru/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -2,21 +2,23 @@ ЕслО у вас старПе прОлПжеМОе FastAPI, вПзЌПжМП, вы ОспПльзуете Pydantic версОО 1. -FastAPI пПЎЎержОвает О Pydantic v1, О v2 МачОМая с версОО 0.100.0. +FastAPI версОО 0.100.0 пПЎЎержОвал лОбП Pydantic v1, лОбП v2. ОМ ОспПльзПвал ту версОю, кПтПрая была устаМПвлеМа. -ЕслО у вас был устаМПвлеМ Pydantic v2, ОспПльзПвался ПМ. ЕслО вЌестП этПгП был устаМПвлеМ Pydantic v1 — ОспПльзПвался ПМ. +FastAPI версОО 0.119.0 ЎПбавОл частОчМую пПЎЎержку Pydantic v1 ОзМутрО Pydantic v2 (как `pydantic.v1`), чтПбы упрПстОть ЌОграцОю Ма v2. -Сейчас Pydantic v1 ПбъявлеМ устаревшОЌ, О пПЎЎержка егП буЎет уЎалеМа в слеЎующОх версОях FastAPI, пПэтПЌу ваЌ слеЎует **перейтО Ма Pydantic v2**. Так вы пПлучОте пПслеЎМОе вПзЌПжМПстО, улучшеМОя О ОсправлеМОя. +FastAPI 0.126.0 убрал пПЎЎержку Pydantic v1, прО этПЌ ещё МекПтПрПе вреЌя прПЎПлжал пПЎЎержОвать `pydantic.v1`. /// warning | ПреЎупрежЎеМОе -КрПЌе тПгП, кПЌаМЎа Pydantic прекратОла пПЎЎержку Pydantic v1 Ўля пПслеЎМОх версОй Python, МачОМая с **Python 3.14**. +КПЌаМЎа Pydantic прекратОла пПЎЎержку Pydantic v1 Ўля пПслеЎМОх версОй Python, МачОМая с **Python 3.14**. + +ЭтП включает `pydantic.v1`, кПтПрый бПльше Ме пПЎЎержОвается в Python 3.14 О выше. ЕслО вы хПтОте ОспПльзПвать пПслеЎМОе вПзЌПжМПстО Python, ваЌ МужМП убеЎОться, чтП вы ОспПльзуете Pydantic v2. /// -ЕслО у вас старПе прОлПжеМОе FastAPI с Pydantic v1, зЎесь я пПкажу, как ЌОгрОрПвать Ма Pydantic v2, О **МПвые вПзЌПжМПстО в FastAPI 0.119.0**, кПтПрые пПЌПгут выпПлМОть пПстепеММую ЌОграцОю. +ЕслО у вас старПе прОлПжеМОе FastAPI с Pydantic v1, зЎесь я пПкажу, как ЌОгрОрПвать Ма Pydantic v2, О **вПзЌПжМПстО FastAPI 0.119.0**, кПтПрые пПЌПгут выпПлМОть пПстепеММую ЌОграцОю. ## ОфОцОальМПе рукПвПЎствП { #official-guide } @@ -38,13 +40,13 @@ FastAPI пПЎЎержОвает О Pydantic v1, О v2 МачОМая с вер Вы ЌПжете ОспПльзПвать `bump-pydantic` Пт тПй же кПЌаМЎы Pydantic. -ЭтПт ОМструЌеМт пПЌПжет автПЌатОческО вМестО бПльшую часть МеПбхПЎОЌых ОзЌеМеМОй в кПЎ. +ЭтПт ОМструЌеМт пПЌПжет автПЌатОческО ОзЌеМОть бПльшую часть кПЎа, кПтПрый МужМП ОзЌеМОть. -ППсле этПгП запустОте тесты О прПверьте, чтП всё рабПтает. ЕслО Ўа — Ма этПЌ всё. 😎 +ППсле этПгП вы ЌПжете запустОть тесты О прПверОть, чтП всё рабПтает. ЕслО Ўа — Ма этПЌ всё. 😎 ## Pydantic v1 в v2 { #pydantic-v1-in-v2 } -Pydantic v2 включает всё Оз Pydantic v1 как пПЎЌПЎуль `pydantic.v1`. +Pydantic v2 включает всё Оз Pydantic v1 как пПЎЌПЎуль `pydantic.v1`. НП этП бПльше Ме пПЎЎержОвается в версОях Python выше 3.13. ЭтП ПзМачает, чтП вы ЌПжете устаМПвОть пПслеЎМюю версОю Pydantic v2 О ОЌпПртОрПвать О ОспПльзПвать старые кПЌпПМеМты Pydantic v1 Оз этПгП пПЎЌПЎуля так, как еслО бы у вас был устаМПвлеМ старый Pydantic v1. @@ -52,7 +54,7 @@ Pydantic v2 включает всё Оз Pydantic v1 как пПЎЌПЎуль ` ### ППЎЎержка FastAPI Ўля Pydantic v1 вМутрО v2 { #fastapi-support-for-pydantic-v1-in-v2 } -НачОМая с FastAPI 0.119.0, есть также частОчМая пПЎЎержка Pydantic v1 в сПставе Pydantic v2, чтПбы упрПстОть ЌОграцОю Ма v2. +НачОМая с FastAPI 0.119.0, есть также частОчМая пПЎЎержка Pydantic v1 ОзМутрО Pydantic v2, чтПбы упрПстОть ЌОграцОю Ма v2. ТакОЌ ПбразПЌ, вы ЌПжете ПбМПвОть Pydantic ЎП пПслеЎМей версОО 2 О сЌеМОть ОЌпПрты Ма пПЎЌПЎуль `pydantic.v1` — вП ЌМПгОх случаях всё прПстП зарабПтает. @@ -106,7 +108,7 @@ graph TB style V2Field fill:#f9fff3 ``` -В МекПтПрых случаях ЌПжМП ОспПльзПвать О ЌПЎелО Pydantic v1, О v2 в ПЎМПй О тПй же ПперацОО путО (ПбрабПтчОке путО) вашегП прОлПжеМОя FastAPI: +В МекПтПрых случаях ЌПжМП ОспПльзПвать О ЌПЎелО Pydantic v1, О v2 в ПЎМПй О тПй же **ПперацОО путО** (ПбрабПтчОке путО) вашегП прОлПжеМОя FastAPI: {* ../../docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py hl[2:3,6,12,21:22] *} @@ -122,12 +124,12 @@ graph TB /// tip | СПвет -СМачала пПпрПбуйте `bump-pydantic`. ЕслО тесты прПхПЎят О всё рабПтает, вы справОлОсь ПЎМПй кПЌаМЎПй. ✹ +СМачала пПпрПбуйте `bump-pydantic`: еслО тесты прПхПЎят О всё рабПтает, вы справОлОсь ПЎМПй кПЌаМЎПй. ✹ /// ЕслО `bump-pydantic` Ме пПЎхПЎОт Ўля вашегП случая, вы ЌПжете ОспПльзПвать пПЎЎержку ПЎМПвреЌеММПй рабПты ЌПЎелей Pydantic v1 О v2 в ПЎМПЌ прОлПжеМОО, чтПбы ЌОгрОрПвать Ма Pydantic v2 пПстепеММП. -СМачала ПбМПвОте Pydantic ЎП пПслеЎМей 2-й версОО О ОзЌеМОте ОЌпПрты так, чтПбы все вашО ЌПЎелО ОспПльзПвалО `pydantic.v1`. +СМачала вы ЌПжете ПбМПвОть Pydantic ЎП пПслеЎМей 2-й версОО О ОзЌеМОть ОЌпПрты так, чтПбы все вашО ЌПЎелО ОспПльзПвалО `pydantic.v1`. -ЗатеЌ МачМОте ЌОгрОрПвать вашО ЌПЎелО с Pydantic v1 Ма v2 группаЌО, пПэтапМП. 🚶 +ЗатеЌ вы ЌПжете Мачать ЌОгрОрПвать вашО ЌПЎелО с Pydantic v1 Ма v2 группаЌО, пПэтапМП. 🚶 diff --git a/docs/ru/docs/how-to/separate-openapi-schemas.md b/docs/ru/docs/how-to/separate-openapi-schemas.md index 5b12140167..8f6c83e7ec 100644 --- a/docs/ru/docs/how-to/separate-openapi-schemas.md +++ b/docs/ru/docs/how-to/separate-openapi-schemas.md @@ -2,7 +2,7 @@ ПрО ОспПльзПваМОО **Pydantic v2** сгеМерОрПваММый OpenAPI стаМПвОтся чуть бПлее тПчМыЌ О **кПрректМыЌ**, чеЌ раМьше. 😎 -На саЌПЌ Ўеле, в МекПтПрых случаях в OpenAPI буЎет Ўаже **Ўве JSON схеЌы** Ўля ПЎМПй О тПй же Pydantic‑ЌПЎелО: Ўля вхПЎа О Ўля выхПЎа — в завОсОЌПстО Пт МалОчОя **зМачеМОй пП уЌПлчаМОю**. +На саЌПЌ Ўеле, в МекПтПрых случаях в OpenAPI буЎет Ўаже **Ўве JSON-схеЌы** Ўля ПЎМПй О тПй же Pydantic‑ЌПЎелО: Ўля вхПЎа О Ўля выхПЎа — в завОсОЌПстО Пт МалОчОя **зМачеМОй пП уЌПлчаМОю**. ППсЌПтрОЌ, как этП рабПтает, О как этП ОзЌеМОть прО МеПбхПЎОЌПстО. @@ -34,7 +34,7 @@ {* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py hl[19] *} - тП, пПскПльку у `description` есть зМачеМОе пП уЌПлчаМОю, Ўаже еслО вы **МОчегП Ме верМёте** Ўля этПгП пПля, ПМП всё равМП буЎет ОЌеть этП **зМачеМОе пП уЌПлчаМОю**. + тП, пПскПльку у `description` есть зМачеМОе пП уЌПлчаМОю, еслО вы **МОчегП Ме верМёте** Ўля этПгП пПля, ПМП всё равМП буЎет ОЌеть этП **зМачеМОе пП уЌПлчаМОю**. ### МПЎель Ўля ЎаММых Птвета { #model-for-output-response-data } @@ -46,13 +46,13 @@ ЭтП ПзМачает, чтП у МегП **всегЎа буЎет какПе‑тП зМачеМОе**, прПстП ОМПгЎа этП зМачеМОе ЌПжет быть `None` (ОлО `null` в JSON). -СлеЎПвательМП, клОеМтаЌ, ОспПльзующОЌ ваш API, Ме МужМП прПверять МалОчОе этПгП зМачеМОя: ПМО ЌПгут **ОсхПЎОть Оз тПгП, чтП пПле всегЎа прОсутствует**, а в МекПтПрых случаях ОЌеет зМачеМОе пП уЌПлчаМОю `None`. +ЭтП ПзМачает, чтП клОеМтаЌ, ОспПльзующОЌ ваш API, Ме МужМП прПверять, существует лО этП зМачеМОе ОлО Мет: ПМО ЌПгут **ОсхПЎОть Оз тПгП, чтП пПле всегЎа прОсутствует**, МП в МекПтПрых случаях ПМП буЎет ОЌеть зМачеМОе пП уЌПлчаМОю `None`. В OpenAPI этП ПпОсывается теЌ, чтП пПле пПЌечается как **ПбязательМПе**, пПскПльку ПМП всегЎа прОсутствует. Из‑за этПгП JSON Schema Ўля ЌПЎелО ЌПжет ПтлОчаться в завОсОЌПстО Пт ОспПльзПваМОя Ўля **вхПЎа** ОлО **выхПЎа**: -* Ўля **вхПЎа** `description` Ме буЎет ПбязательМыЌ +* Ўля **вхПЎа** `description` **Ме буЎет ПбязательМыЌ** * Ўля **выхПЎа** ПМП буЎет **ПбязательМыЌ** (О прО этПЌ ЌПжет быть `None`, ОлО, в терЌОМах JSON, `null`) ### ВыхПЎМая ЌПЎель в ЎПкуЌеМтацОО { #model-for-output-in-docs } @@ -81,9 +81,9 @@ ОЎМакП бывают случаО, кПгЎа вы хПтОте ОЌеть **ПЎМу О ту же схеЌу Ўля вхПЎа О выхПЎа**. -ГлавМый сцеМарОй — кПгЎа у вас уже есть сгеМерОрПваММый клОеМтскОй кПЎ/SDK, О вы пПка Ме хПтОте ПбМПвлять весь этПт автПгеМерОруеЌый кПЎ/SDK (раМП ОлО пПзЎМП вы этП сЎелаете, МП Ме сейчас). +ГлавМый сцеМарОй — кПгЎа у вас уже есть сгеМерОрПваММый клОеМтскОй кПЎ/SDK, О вы пПка Ме хПтОте ПбМПвлять весь этПт автПгеМерОруеЌый клОеМтскОй кПЎ/SDK, верПятМП, вы захПтОте сЎелать этП в какПй-тП ЌПЌеМт, МП, вПзЌПжМП, Ме пряЌП сейчас. -В такПЌ случае вы ЌПжете ПтключОть эту фуМкцОПМальМПсть в FastAPI с пПЌПщью параЌетра `separate_input_output_schemas=False`. +В такПЌ случае вы ЌПжете ПтключОть эту фуМкцОПМальМПсть в **FastAPI** с пПЌПщью параЌетра `separate_input_output_schemas=False`. /// info | ИМфПрЌацОя @@ -95,10 +95,8 @@ ### ОЎМа О та же схеЌа Ўля вхПЎМПй О выхПЎМПй ЌПЎелей в ЎПкуЌеМтацОО { #same-schema-for-input-and-output-models-in-docs } -Теперь Ўля этПй ЌПЎелО буЎет ПЎМа Пбщая схеЌа О Ўля вхПЎа, О Ўля выхПЎа — тПлькП `Item`, О в Мей `description` буЎет **Ме ПбязательМыЌ**: +И теперь Ўля ЌПЎелО буЎет ПЎМа Пбщая схеЌа О Ўля вхПЎа, О Ўля выхПЎа — тПлькП `Item`, О в Мей `description` буЎет **Ме ПбязательМыЌ**:
- -ЭтП тП же пПвеЎеМОе, чтП О в Pydantic v1. 🀓 diff --git a/docs/ru/docs/index.md b/docs/ru/docs/index.md index b562cbe5bc..02b1c9a286 100644 --- a/docs/ru/docs/index.md +++ b/docs/ru/docs/index.md @@ -5,10 +5,10 @@

- FastAPI + FastAPI

- ЀрейЌвПрк FastAPI: высПкая прПОзвПЎОтельМПсть, прПст в ОзучеМОО, быстрый в разрабПтке, гПтПв к прПЎакшМ + ЀрейЌвПрк FastAPI: высПкая прПОзвПЎОтельМПсть, прПст в ОзучеМОО, пПзвПляет быстрП пОсать кПЎ, гПтПв к прПЎакшМ

@@ -40,7 +40,7 @@ FastAPI — этП сПвреЌеММый, быстрый (высПкПпрПО * **СкПрПсть**: ОчеМь высПкая прПОзвПЎОтельМПсть, Ма урПвМе **NodeJS** О **Go** (благПЎаря Starlette О Pydantic). [ОЎОМ Оз саЌых быстрых ЎПступМых фрейЌвПркПв Python](#performance). * **БыстрПта разрабПткО**: УвелОчьте скПрПсть разрабПткО фОч прОЌерМП Ма 200–300%. * * **МеМьше ПшОбПк**: СПкратОте прОЌерМП Ма 40% кПлОчествП ПшОбПк, вызваММых челПвекПЌ (разрабПтчОкПЌ). * -* **ИМтуОтОвМПсть**: ОтлОчМая пПЎЎержка реЎактПра кПЎа. АвтПзавершеМОе везЎе. МеМьше вреЌеМО Ма ПтлаЎку. +* **ИМтуОтОвМПсть**: ОтлОчМая пПЎЎержка реЎактПра кПЎа. АвтПзавершеМОе везЎе. МеМьше вреЌеМО Ма ПтлаЎку. * **ПрПстПта**: РазрабПтаМ так, чтПбы егП былП легкП ОспПльзПвать О ПсваОвать. МеМьше вреЌеМО Ма чтеМОе ЎПкуЌеМтацОО. * **КраткПсть**: МОМОЌОзОруйте ЎублОрПваМОе кПЎа. НескПлькП вПзЌПжМПстей Оз кажЎПгП ПбъявлеМОя параЌетрПв. МеМьше ПшОбПк. * **НаЎежМПсть**: ППлучОте кПЎ, гПтПвый к прПЎакшМ. С автПЌатОческПй ОМтерактОвМПй ЎПкуЌеМтацОей. @@ -117,6 +117,12 @@ FastAPI — этП сПвреЌеММый, быстрый (высПкПпрПО --- +## МОМО-ЎПкуЌеМтальМый фОльЌ П FastAPI { #fastapi-mini-documentary } + +В кПМце 2025 гПЎа вышел ЌОМО-ЎПкуЌеМтальМый фОльЌ П FastAPI, вы ЌПжете пПсЌПтреть егП ПМлайМ: + +FastAPI Mini Documentary + ## **Typer**, FastAPI Ўля CLI { #typer-the-fastapi-of-clis } @@ -257,7 +263,7 @@ INFO: Application startup complete. * ППлучает HTTP-запрПсы пП _путяЌ_ `/` О `/items/{item_id}`. * Оба _путО_ ОспПльзуют `GET` ПперацОО (также ОзвестМые как HTTP _ЌетПЎы_). -* _Путь_ `/items/{item_id}` ОЌеет _параЌетр путО_ `item_id`, кПтПрый ЎПлжеМ быть `int`. +* _Путь_ `/items/{item_id}` ОЌеет _path-параЌетр_ `item_id`, кПтПрый ЎПлжеМ быть `int`. * _Путь_ `/items/{item_id}` ОЌеет МеПбязательМый `str` _параЌетр запрПса_ `q`. ### ИМтерактОвМая ЎПкуЌеМтацОя API { #interactive-api-docs } @@ -278,9 +284,9 @@ INFO: Application startup complete. ## ПрОЌер ПбМПвлеМОя { #example-upgrade } -Теперь ОзЌеМОте файл `main.py`, чтПбы прОМОЌать телП запрПса Оз `PUT` запрПса. +Теперь ОзЌеМОте файл `main.py`, чтПбы прОМОЌать телП запрПса Оз `PUT` HTTP-запрПса. -ОбъявОте телП, ОспПльзуя стаМЎартМые тОпы Python, спасОбП Pydantic. +ОбъявОте телП запрПса, ОспПльзуя стаМЎартМые тОпы Python, спасОбП Pydantic. ```Python hl_lines="4 9-12 25-27" from typing import Union @@ -318,7 +324,7 @@ def update_item(item_id: int, item: Item): ПерейЎОте Ма http://127.0.0.1:8000/docs. -* ИМтерактОвМая ЎПкуЌеМтацОя API буЎет автПЌатОческО ПбМПвлеМа, включая МПвПе телП: +* ИМтерактОвМая ЎПкуЌеМтацОя API буЎет автПЌатОческО ПбМПвлеМа, включая МПвПе телП запрПса: ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) @@ -334,13 +340,13 @@ def update_item(item_id: int, item: Item): Теперь ПткрПйте http://127.0.0.1:8000/redoc. -* АльтерМатОвМая ЎПкуЌеМтацОя также ПтразОт МПвый параЌетр запрПса О телП: +* АльтерМатОвМая ЎПкуЌеМтацОя также ПтразОт МПвый параЌетр запрПса О телП запрПса: ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) ### ППЎвеЎёЌ ОтПгО { #recap } -Итак, вы Пбъявляете **ПЎОМ раз** тОпы параЌетрПв, тела запрПса О т.ÐŽ. как параЌетры фуМкцОО. +Итак, вы Пбъявляете **ПЎОМ раз** тОпы параЌетрПв, телП запрПса О т.ÐŽ. как параЌетры фуМкцОО. Вы Ўелаете этП с пПЌПщью стаМЎартМых сПвреЌеММых тОпПв Python. @@ -390,13 +396,13 @@ item: Item ВПзвращаясь к преЎыЎущеЌу прОЌеру кПЎа, **FastAPI** буЎет: -* ВалОЎОрПвать МалОчОе `item_id` в путО Ўля `GET` О `PUT` запрПсПв. -* ВалОЎОрПвать, чтП `item_id` ОЌеет тОп `int` Ўля `GET` О `PUT` запрПсПв. +* ВалОЎОрПвать МалОчОе `item_id` в путО Ўля `GET` О `PUT` HTTP-запрПсПв. +* ВалОЎОрПвать, чтП `item_id` ОЌеет тОп `int` Ўля `GET` О `PUT` HTTP-запрПсПв. * ЕслО этП Ме так, клОеМт увОЎОт пПлезМую пПМятМую ПшОбку. -* ПрПверять, есть лО МеПбязательМый параЌетр запрПса с ОЌеМеЌ `q` (МапрОЌер, `http://127.0.0.1:8000/items/foo?q=somequery`) Ўля `GET` запрПсПв. +* ПрПверять, есть лО МеПбязательМый параЌетр запрПса с ОЌеМеЌ `q` (МапрОЌер, `http://127.0.0.1:8000/items/foo?q=somequery`) Ўля `GET` HTTP-запрПсПв. * ППскПльку параЌетр `q` ПбъявлеМ с `= None`, ПМ МеПбязателеМ. * Без `None` ПМ был бы ПбязательМыЌ (как телП запрПса в случае с `PUT`). -* Для `PUT` запрПсПв к `/items/{item_id}` чОтать телП запрПса как JSON: +* Для `PUT` HTTP-запрПсПв к `/items/{item_id}` чОтать телП запрПса как JSON: * ПрПверять, чтП есть ПбязательМый атрОбут `name`, кПтПрый ЎПлжеМ быть `str`. * ПрПверять, чтП есть ПбязательМый атрОбут `price`, кПтПрый ЎПлжеМ быть `float`. * ПрПверять, чтП есть МеПбязательМый атрОбут `is_offer`, кПтПрый ЎПлжеМ быть `bool`, еслО ПМ прОсутствует. @@ -435,11 +441,11 @@ item: Item БПлее пПлМый прОЌер с ЎПпПлМОтельМыЌО вПзЌПжМПстяЌО сЌ. в УчебМОк - РукПвПЎствП пПльзПвателя. -**ОстПрПжМП, спПйлер**: учебМОк - рукПвПЎствП включает: +**ОстПрПжМП, спПйлер**: учебМОк - рукПвПЎствП пПльзПвателя включает: * ОбъявлеМОе **параЌетрПв** Оз ЎругОх ОстПчМОкПв: **HTTP-загПлПвкО**, **cookies**, **пПля фПрЌы** О **файлы**. * Как заЎать **ПграМОчеМОя валОЎацОО** врПЎе `maximum_length` ОлО `regex`. -* ОчеМь ЌПщМую О прПстую в ОспПльзПваМОО сОстеЌу **вМеЎреМОя завОсОЌПстей**. +* ОчеМь ЌПщМую О прПстую в ОспПльзПваМОО сОстеЌу **вМеЎреМОя завОсОЌПстей**. * БезПпасМПсть О аутеМтОфОкацОю, включая пПЎЎержку **OAuth2** с **JWT тПкеМаЌО** О **HTTP Basic** аутеМтОфОкацОю. * БПлее прПЎвОМутые (МП стПль же прПстые) прОёЌы ПбъявлеМОя **глубПкП влПжеММых JSON-ЌПЎелей** (спасОбП Pydantic). * ИМтеграцОю **GraphQL** с Strawberry О ЎругОЌО бОблОПтекаЌО. @@ -524,11 +530,11 @@ FastAPI завОсОт Пт Pydantic О Starlette. * httpx — ПбязателеМ, еслО вы хПтОте ОспПльзПвать `TestClient`. * jinja2 — ПбязателеМ, еслО вы хПтОте ОспПльзПвать кПМфОгурацОю шаблПМПв пП уЌПлчаМОю. -* python-multipart — ПбязателеМ, еслО вы хПтОте пПЎЎержОвать «парсОМг» фПрЌ через `request.form()`. +* python-multipart - ПбязателеМ, еслО вы хПтОте пПЎЎержОвать «парсОМг» фПрЌ через `request.form()`. ИспПльзуется FastAPI: -* uvicorn — сервер, кПтПрый загружает О ПбслужОвает ваше прОлПжеМОе. Включает `uvicorn[standard]`, сПЎержащОй МекПтПрые завОсОЌПстО (МапрОЌер, `uvloop`), МужМые Ўля высПкПй прПОзвПЎОтельМПстО. +* uvicorn — сервер, кПтПрый загружает О «ПтЎаёт» ваше прОлПжеМОе. Включает `uvicorn[standard]`, сПЎержащОй МекПтПрые завОсОЌПстО (МапрОЌер, `uvloop`), МужМые Ўля высПкПй прПОзвПЎОтельМПстО. * `fastapi-cli[standard]` — чтПбы преЎПставОть кПЌаМЎу `fastapi`. * Включает `fastapi-cloud-cli`, кПтПрый пПзвПляет разверМуть ваше прОлПжеМОе FastAPI в FastAPI Cloud. diff --git a/docs/ru/docs/tutorial/bigger-applications.md b/docs/ru/docs/tutorial/bigger-applications.md index 5e5d6ada94..76304523c9 100644 --- a/docs/ru/docs/tutorial/bigger-applications.md +++ b/docs/ru/docs/tutorial/bigger-applications.md @@ -1,4 +1,4 @@ -# БПльшОе прОлПжеМОя, в кПтПрых ЌМПгП файлПв { #bigger-applications-multiple-files } +# БПльшОе прОлПжеМОя — МескПлькП файлПв { #bigger-applications-multiple-files } ПрО пПстрПеМОО прОлПжеМОя ОлО веб-API МаЌ реЎкП уЎается пПЌестОть всё в ПЎОМ файл. @@ -31,7 +31,7 @@ /// tip | ППЎсказка -ОбратОте вМОЌаМОе, чтП в кажЎПЌ каталПге О пПЎкаталПге ОЌеется файл `__init__.py` +Есть МескПлькП файлПв `__init__.py`: пП ПЎМПЌу в кажЎПЌ каталПге ОлО пПЎкаталПге. ЭтП как раз тП, чтП пПзвПляет ОЌпПртОрПвать кПЎ Оз ПЎМПгП файла в ЎругПй. @@ -43,61 +43,63 @@ from app.routers import items /// -* Всё пПЌещается в каталПге `app`. В МёЌ также МахПЎОтся пустПй файл `app/__init__.py`. ТакОЌ ПбразПЌ, `app` является "Python-пакетПЌ" (кПллекцОей ЌПЎулей Python). -* ОМ сПЎержОт файл `app/main.py`. ДаММый файл является частью пакета (т.е. МахПЎОтся вМутрО каталПга, сПЎержащегП файл `__init__.py`), О, сППтветствеММП, ПМ является ЌПЎулеЌ пакета: `app.main`. +* Всё пПЌещается в каталПге `app`. В МёЌ также МахПЎОтся пустПй файл `app/__init__.py`. ТакОЌ ПбразПЌ, `app` является "Python-пакетПЌ" (кПллекцОей "Python-ЌПЎулей"): `app`. +* ОМ сПЎержОт файл `app/main.py`. ДаММый файл является частью Python-пакета (т.е. МахПЎОтся вМутрО каталПга, сПЎержащегП файл `__init__.py`), О, сППтветствеММП, ПМ является ЌПЎулеЌ этПгП пакета: `app.main`. * ОМ также сПЎержОт файл `app/dependencies.py`, кПтПрый также, как О `app/main.py`, является ЌПЎулеЌ: `app.dependencies`. -* ЗЎесь также МахПЎОтся пПЎкаталПг `app/routers/`, сПЎержащОй `__init__.py`. ОМ является суб-пакетПЌ: `app.routers`. -* Ѐайл `app/routers/items.py` МахПЎОтся вМутрО пакета `app/routers/`. ТакОЌ ПбразПЌ, ПМ является суб-ЌПЎулеЌ: `app.routers.items`. -* ТПчМП также `app/routers/users.py` является ещё ПЎМОЌ суб-ЌПЎулеЌ: `app.routers.users`. -* ППЎкаталПг `app/internal/`, сПЎержащОй файл `__init__.py`, является ещё ПЎМОЌ суб-пакетПЌ: `app.internal`. -* А файл `app/internal/admin.py` является ещё ПЎМОЌ суб-ЌПЎулеЌ: `app.internal.admin`. +* ЗЎесь также МахПЎОтся пПЎкаталПг `app/routers/`, сПЎержащОй `__init__.py`. ОМ является Python-пПЎпакетПЌ: `app.routers`. +* Ѐайл `app/routers/items.py` МахПЎОтся вМутрО пакета `app/routers/`. ТакОЌ ПбразПЌ, ПМ является пПЎЌПЎулеЌ: `app.routers.items`. +* ТПчМП так же `app/routers/users.py` является ещё ПЎМОЌ пПЎЌПЎулеЌ: `app.routers.users`. +* ППЎкаталПг `app/internal/`, сПЎержащОй файл `__init__.py`, является ещё ПЎМОЌ Python-пПЎпакетПЌ: `app.internal`. +* А файл `app/internal/admin.py` является ещё ПЎМОЌ пПЎЌПЎулеЌ: `app.internal.admin`. Та же саЌая файлПвая структура прОлПжеМОя, МП с кПЌЌеМтарОяЌО: -``` +```bash . ├── app # "app" пакет │   ├── __init__.py # этПт файл превращает "app" в "Python-пакет" │   ├── main.py # ЌПЎуль "main", Мапр.: import app.main │   ├── dependencies.py # ЌПЎуль "dependencies", Мапр.: import app.dependencies -│   └── routers # суб-пакет "routers" -│   │ ├── __init__.py # превращает "routers" в суб-пакет -│   │ ├── items.py # суб-ЌПЎуль "items", Мапр.: import app.routers.items -│   │ └── users.py # суб-ЌПЎуль "users", Мапр.: import app.routers.users -│   └── internal # суб-пакет "internal" -│   ├── __init__.py # превращает "internal" в суб-пакет -│   └── admin.py # суб-ЌПЎуль "admin", Мапр.: import app.internal.admin +│   └── routers # пПЎпакет "routers" +│   │ ├── __init__.py # превращает "routers" в пПЎпакет +│   │ ├── items.py # пПЎЌПЎуль "items", Мапр.: import app.routers.items +│   │ └── users.py # пПЎЌПЎуль "users", Мапр.: import app.routers.users +│   └── internal # пПЎпакет "internal" +│   ├── __init__.py # превращает "internal" в пПЎпакет +│   └── admin.py # пПЎЌПЎуль "admin", Мапр.: import app.internal.admin ``` ## `APIRouter` { #apirouter } -Давайте преЎпПлПжОЌ, чтП Ўля рабПты с пПльзПвателяЌО ОспПльзуется ПтЎельМый файл (суб-ЌПЎуль) `/app/routers/users.py`. +Давайте преЎпПлПжОЌ, чтП Ўля рабПты с пПльзПвателяЌО ОспПльзуется ПтЎельМый файл (пПЎЌПЎуль) `/app/routers/users.py`. -Для лучшей ПргаМОзацОО прОлПжеМОя, вы хПтОте ПтЎелОть ПперацОО путО, связаММые с пПльзПвателяЌО, Пт ПстальМПгП кПЎа. +Вы хПтОте ПтЎелОть *ПперацОО путО*, связаММые с пПльзПвателяЌО, Пт ПстальМПгП кПЎа, чтПбы сПхраМОть пПряЎПк. -НП так, чтПбы этО ПперацОО пП-прежМеЌу ПставалОсь частью **FastAPI** прОлПжеМОя/веб-API (частью ПЎМПгП пакета) +НП этП всё равМП часть тПгП же прОлПжеМОя/веб-API Ма **FastAPI** (часть тПгП же «Python-пакета»). -С пПЌПщью `APIRouter` вы ЌПжете сПзЎать *ПперацОО путО* (*эМЎпПОМты*) Ўля ЎаММПгП ЌПЎуля. +С пПЌПщью `APIRouter` вы ЌПжете сПзЎать *ПперацОО путО* Ўля этПгП ЌПЎуля. ### ИЌпПрт `APIRouter` { #import-apirouter } -ТПчМП также, как О в случае с классПЌ `FastAPI`, ваЌ МужМП ОЌпПртОрПвать О сПзЎать Пбъект класса `APIRouter`. +ТПчМП так же, как О в случае с классПЌ `FastAPI`, ваЌ МужМП ОЌпПртОрПвать О сПзЎать егП «экзеЌпляр»: {* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[1,3] title["app/routers/users.py"] *} -### СПзЎаМОе *эМЎпПОМтПв* с пПЌПщью `APIRouter` { #path-operations-with-apirouter } +### *ОперацОО путО* с `APIRouter` { #path-operations-with-apirouter } -В ЎальМейшеЌ ОспПльзуйте `APIRouter` Ўля ПбъявлеМОя *эМЎпПОМтПв*, тПчМП также, как вы ОспПльзуете класс `FastAPI`: +И затеЌ вы ОспПльзуете егП, чтПбы ПбъявОть вашО *ПперацОО путО*. + +ИспПльзуйте егП так же, как вы ОспПльзПвалО бы класс `FastAPI`: {* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[6,11,16] title["app/routers/users.py"] *} -Вы ЌПжете ЎуЌать Пб `APIRouter` как Пб "уЌеМьшеММПй версОО" класса FastAPI`. +Вы ЌПжете ЎуЌать Пб `APIRouter` как Пб «ЌОМО-классе `FastAPI`». -`APIRouter` пПЎЎержОвает все те же саЌые ПпцОО. +ППЎЎержОваются все те же ПпцОО. -`APIRouter` пПЎЎержОвает все те же саЌые параЌетры, такОе как `parameters`, `responses`, `dependencies`, `tags`, О т. ÐŽ. +Все те же `parameters`, `responses`, `dependencies`, `tags` О т.ÐŽ. /// tip | ППЎсказка @@ -105,21 +107,21 @@ from app.routers import items /// -Мы сПбОраеЌся пПЎключОть ЎаММый `APIRouter` к МашеЌу ПсМПвМПЌу прОлПжеМОю Ма `FastAPI`, МП сМачала Ўавайте прПверОЌ завОсОЌПстО О сПзЎаЎОЌ ещё ПЎОМ ЌПЎуль с `APIRouter`. +Мы сПбОраеЌся пПЎключОть ЎаММый `APIRouter` к МашеЌу ПсМПвМПЌу прОлПжеМОю Ма `FastAPI`, МП сМачала Ўавайте прПверОЌ завОсОЌПстО О ещё ПЎОМ `APIRouter`. ## ЗавОсОЌПстО { #dependencies } -НаЌ пПМаЎПбятся МекПтПрые завОсОЌПстО, кПтПрые Ќы буЎеЌ ОспПльзПвать в разМых Ќестах МашегП прОлПжеМОя. +Мы вОЎОЌ, чтП МаЌ пПМаЎПбятся МекПтПрые завОсОЌПстО, кПтПрые буЎут ОспПльзПваться в МескПлькОх Ќестах прОлПжеМОя. -Мы пПЌестОЌ Ох в ПтЎельМый ЌПЎуль `dependencies` (`app/dependencies.py`). +ППэтПЌу Ќы пПЌестОЌ Ох в ПтЎельМый ЌПЎуль `dependencies` (`app/dependencies.py`). -Теперь Ќы вПспПльзуеЌся прПстПй завОсОЌПстью, чтПбы прПчОтать кастПЌОзОрПваММый `X-Token` Оз загПлПвка: +Теперь Ќы вПспПльзуеЌся прПстПй завОсОЌПстью, чтПбы прПчОтать кастПЌМый HTTP-загПлПвПк `X-Token`: {* ../../docs_src/bigger_applications/app_an_py39/dependencies.py hl[3,6:8] title["app/dependencies.py"] *} /// tip | ППЎсказка -Для прПстПты Ќы вПспПльзПвалОсь МекОЌ вППбражаеЌыЌ загПлПвПкПЌ. +Для прПстПты Ќы вПспПльзПвалОсь выЎуЌаММыЌ загПлПвкПЌ. В реальМых случаях Ўля пПлучеМОя МаОлучшОх результатПв ОспПльзуйте ОМтегрОрПваММые [утОлОты безПпасМПстО](security/index.md){.internal-link target=_blank}. @@ -127,30 +129,29 @@ from app.routers import items ## Ещё ПЎОМ ЌПЎуль с `APIRouter` { #another-module-with-apirouter } -Давайте также преЎпПлПжОЌ, чтП у вас есть *эМЎпПОМты*, ПтвечающОе за ПбрабПтку "items", О ПМО МахПЎятся в ЌПЎуле `app/routers/items.py`. +Давайте также преЎпПлПжОЌ, чтП у вас есть эМЎпПОМты, ПтвечающОе за ПбрабПтку «items» в вашеЌ прОлПжеМОО, О ПМО МахПЎятся в ЌПЎуле `app/routers/items.py`. -У вас ПпреЎелеМы слеЎующОе *ПперацОО путО* (*эМЎпПОМты*): +У вас ПпреЎелеМы *ПперацОО путО* Ўля: * `/items/` * `/items/{item_id}` -Тут всё тПчМП также, как О в сОтуацОО с `app/routers/users.py`. +Тут всё та же структура, как О в случае с `app/routers/users.py`. -НП теперь Ќы хПтОЌ пПступОть МеЌМПгП уЌМее О слегка упрПстОть кПЎ. +НП Ќы хПтОЌ пПступОть уЌМее О слегка упрПстОть кПЎ. -Мы зМаеЌ, чтП все *эМЎпПОМты* ЎаММПгП ЌПЎуля ОЌеют МекПтПрые ПбщОе свПйства: +Мы зМаеЌ, чтП все *ПперацОО путО* этПгП ЌПЎуля ОЌеют ПЎОМакПвые: -* ПрефОкс путО: `/items`. -* ТегО: (ПЎОМ еЎОМствеММый тег: `items`). -* ДПпПлМОтельМые Птветы (responses) -* ЗавОсОЌПстО: ОспПльзПваМОе сПзЎаММПй МаЌО завОсОЌПстО `X-token` +* `prefix` путО: `/items`. +* `tags`: (ПЎОМ еЎОМствеММый тег: `items`). +* ДПпПлМОтельМые `responses`. +* `dependencies`: всеЌ ОЌ МужМа та завОсОЌПсть `X-Token`, кПтПрую Ќы сПзЎалО. -ТакОЌ ПбразПЌ, вЌестП тПгП чтПбы ЎПбавлять все этО свПйства в фуМкцОю кажЎПгП ПтЎельМПгП *эМЎпПОМта*, -Ќы ЎПбавОЌ Ох в `APIRouter`. +ТакОЌ ПбразПЌ, вЌестП тПгП чтПбы ЎПбавлять всё этП в кажЎую *ПперацОю путО*, Ќы ЌПжеЌ ЎПбавОть этП в `APIRouter`. {* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[5:10,16,21] title["app/routers/items.py"] *} -Так как кажЎый *эМЎпПОМт* МачОМается с сОЌвПла `/`: +Так как путь кажЎПй *ПперацОО путО* ЎПлжеМ МачОМаться с `/`, как зЎесь: ```Python hl_lines="1" @router.get("/{item_id}") @@ -162,73 +163,74 @@ async def read_item(item_id: str): В МашеЌ случае префОксПЌ является `/items`. -Мы также ЌПжеЌ ЎПбавОть в Маш ЌаршрутОзатПр (router) спОсПк `тегПв` (`tags`) О ЎПпПлМОтельМых `ПтветПв` (`responses`), кПтПрые являются ПбщОЌО Ўля кажЎПгП *эМЎпПОМта*. +Мы также ЌПжеЌ ЎПбавОть спОсПк `tags` О ЎПпПлМОтельМые `responses`, кПтПрые буЎут прОЌеМяться кП всеЌ *ПперацОяЌ путО*, включёММыЌ в этПт ЌаршрутОзатПр. -И ещё Ќы ЌПжеЌ ЎПбавОть в Маш ЌаршрутОзатПр спОсПк `завОсОЌПстей`, кПтПрые ЎПлжМы вызываться прО кажЎПЌ ПбращеМОО к *эМЎпПОМтаЌ*. +И ещё Ќы ЌПжеЌ ЎПбавОть спОсПк `dependencies`, кПтПрые буЎут ЎПбавлеМы кП всеЌ *ПперацОяЌ путО* в ЌаршрутОзатПре О буЎут выпПлМяться/разрешаться Ўля кажЎПгП HTTP-запрПса к МОЌ. /// tip | ППЎсказка -ОбратОте вМОЌаМОе, чтП также, как О в случае с завОсОЌПстяЌО в ЎекПратПрах *эМЎпПОМтПв* ([завОсОЌПстО в ЎекПратПрах ПперацОй путО](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}), МОкакПгП зМачеМОя в *фуМкцОю эМЎпПОМта* переЎаМП Ме буЎет. +ОбратОте вМОЌаМОе, чтП так же, как О в случае с [завОсОЌПстяЌО в ЎекПратПрах *ПперацОй путО*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, МОкакПе зМачеМОе Ме буЎет переЎаМП в вашу *фуМкцОю-ПбрабПтчОк путО*. /// -В результате Ќы пПлучОЌ слеЎующОе эМЎпПОМты: +В результате путО Ўля items теперь такОе: * `/items/` * `/items/{item_id}` ...как Ќы О плаМОрПвалО. -* ОМО буЎут пПЌечеМы тегаЌО Оз заЎаММПгП спОска, в МашеЌ случае этП `"items"`. - * ЭтО тегО ПсПбеММП пПлезМы Ўля сОстеЌы автПЌатОческПй ОМтерактОвМПй ЎПкуЌеМтацОО (с ОспПльзПваМОеЌ OpenAPI). -* КажЎый Оз МОх буЎет включать преЎПпреЎелеММые Птветы `responses`. -* КажЎый *эМЎпПОМт* буЎет ОЌеть спОсПк завОсОЌПстей (`dependencies`), ОспПлМяеЌых переЎ вызПвПЌ *эМЎпПОМта*. - * ЕслО вы ПпреЎелОлО завОсОЌПстО в саЌПй ПперацОО путО, **тП ПМа также буЎет выпПлМеМа**. - * СМачала выпПлМяются завОсОЌПстО ЌаршрутОзатПра, затеЌ вызываются [завОсОЌПстО в ЎекПратПре](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, О, МакПМец, ПбычМые параЌетрОческОе завОсОЌПстО. - * Вы также ЌПжете ЎПбавОть [завОсОЌПстО `Security` с `scopes`](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}. +* ОМО буЎут пПЌечеМы спОскПЌ тегПв, сПЎержащОЌ ПЎМу стрПку `"items"`. + * ЭтО «тегО» ПсПбеММП пПлезМы Ўля сОстеЌ автПЌатОческПй ОМтерактОвМПй ЎПкуЌеМтацОО (с ОспПльзПваМОеЌ OpenAPI). +* Все ПМО буЎут включать преЎПпреЎелёММые `responses`. +* Все этО *ПперацОО путО* буЎут ОЌеть спОсПк `dependencies`, вычОсляеЌых/выпПлМяеЌых переЎ МОЌО. + * ЕслО вы также ПбъявОте завОсОЌПстО в кПМкретМПй *ПперацОО путО*, **ПМО тПже буЎут выпПлМеМы**. + * СМачала выпПлМяются завОсОЌПстО ЌаршрутОзатПра, затеЌ [`dependencies` в ЎекПратПре](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, О затеЌ ПбычМые параЌетрОческОе завОсОЌПстО. + * Вы также ЌПжете ЎПбавОть [`Security`-завОсОЌПстО с `scopes`](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}. /// tip | ППЎсказка -НапрОЌер, с пПЌПщью завОсОЌПстей в `APIRouter` Ќы ЌПжеЌ пПтребПвать аутеМтОфОкацОО Ўля ЎПступа кП всей группе *эМЎпПОМтПв*, Ме указывая завОсОЌПстО Ўля кажЎПй ПтЎельМПй фуМкцОО *эМЎпПОМта*. +НапрОЌер, с пПЌПщью завОсОЌПстей в `APIRouter` Ќы ЌПжеЌ пПтребПвать аутеМтОфОкацОО Ўля ЎПступа кП всей группе *ПперацОй путО*. Даже еслО завОсОЌПстО Ме ЎПбавляются пП ПтЎельМПстО к кажЎПй Оз МОх. /// /// check | ЗаЌетка -ПараЌетры `prefix`, `tags`, `responses` О `dependencies` ПтМПсятся к фуМкцОПМалу **FastAPI**, пПЌПгающеЌу Озбежать ЎублОрПваМОя кПЎа. +ПараЌетры `prefix`, `tags`, `responses` О `dependencies` — этП (как О вП ЌМПгОх ЎругОх случаях) прПстП вПзЌПжМПсть **FastAPI**, пПЌПгающая Озбежать ЎублОрПваМОя кПЎа. /// ### ИЌпПрт завОсОЌПстей { #import-the-dependencies } -Наш кПЎ МахПЎОтся в ЌПЎуле `app.routers.items` (файл `app/routers/items.py`). +ЭтПт кПЎ МахПЎОтся в ЌПЎуле `app.routers.items`, в файле `app/routers/items.py`. -И МаЌ МужМП вызвать фуМкцОю завОсОЌПстО Оз ЌПЎуля `app.dependencies` (файл `app/dependencies.py`). +И МаЌ МужМП пПлучОть фуМкцОю завОсОЌПстО Оз ЌПЎуля `app.dependencies`, файла `app/dependencies.py`. -Мы ОспПльзуеЌ ПперацОю ПтМПсОтельМПгП ОЌпПрта `..` Ўля ОЌпПрта завОсОЌПстО: +ППэтПЌу Ќы ОспПльзуеЌ ПтМПсОтельМый ОЌпПрт с `..` Ўля завОсОЌПстей: {* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[3] title["app/routers/items.py"] *} -#### Как рабПтает ПтМПсОтельМый ОЌпПрт? { #how-relative-imports-work } +#### Как рабПтает ПтМПсОтельМый ОЌпПрт { #how-relative-imports-work } /// tip | ППЎсказка -ЕслО вы прекрасМП зМаете, как рабПтает ОЌпПрт в Python, тП перехПЎОте к слеЎующеЌу разЎелу. +ЕслО вы прекрасМП зМаете, как рабПтает ОЌпПрт, перехПЎОте к слеЎующеЌу разЎелу МОже. /// -ОЎМа тПчка `.`, как в ЎаММПЌ прОЌере: +ОЎМа тПчка `.`, как зЎесь: ```Python from .dependencies import get_token_header ``` + ПзМачает: -* НачМОте с пакета, в кПтПрПЌ МахПЎОтся ЎаММый ЌПЎуль (файл `app/routers/items.py` распПлПжеМ в каталПге `app/routers/`)... -* ... МайЎОте ЌПЎуль `dependencies` (файл `app/routers/dependencies.py`)... -* ... О ОЌпПртОруйте Оз МегП фуМкцОю `get_token_header`. +* Начать в тПЌ же пакете, в кПтПрПЌ МахПЎОтся этПт ЌПЎуль (файл `app/routers/items.py`) (каталПг `app/routers/`)... +* МайтО ЌПЎуль `dependencies` (вППбражаеЌый файл `app/routers/dependencies.py`)... +* О ОЌпПртОрПвать Оз МегП фуМкцОю `get_token_header`. -К сПжалеМОю, такПгП файла Ме существует, О МашО завОсОЌПстО МахПЎятся в файле `app/dependencies.py`. +НП такПгП файла Ме существует, МашО завОсОЌПстО МахПЎятся в файле `app/dependencies.py`. ВспПЌМОте, как выгляЎОт файлПвая структура МашегП прОлПжеМОя: @@ -236,7 +238,7 @@ from .dependencies import get_token_header --- -Две тПчкО `..`, как в ЎаММПЌ прОЌере: +Две тПчкО `..`, как зЎесь: ```Python from ..dependencies import get_token_header @@ -244,12 +246,12 @@ from ..dependencies import get_token_header ПзМачают: -* НачМОте с пакета, в кПтПрПЌ МахПЎОтся ЎаММый ЌПЎуль (файл `app/routers/items.py` МахПЎОтся в каталПге `app/routers/`)... -* ... перейЎОте в рПЎОтельскОй пакет (каталПг `app/`)... -* ... МайЎОте в МёЌ ЌПЎуль `dependencies` (файл `app/dependencies.py`)... -* ... О ОЌпПртОруйте Оз МегП фуМкцОю `get_token_header`. +* Начать в тПЌ же пакете, в кПтПрПЌ МахПЎОтся этПт ЌПЎуль (файл `app/routers/items.py`) (каталПг `app/routers/`)... +* перейтО в рПЎОтельскОй пакет (каталПг `app/`)... +* О таЌ МайтО ЌПЎуль `dependencies` (файл `app/dependencies.py`)... +* О ОЌпПртОрПвать Оз МегП фуМкцОю `get_token_header`. -ЭтП рабПтает верМП! 🎉 +ЭтП рабПтает кПрректМП! 🎉 --- @@ -261,29 +263,29 @@ from ...dependencies import get_token_header тП этП бы ПзМачалП: -* НачМОте с пакета, в кПтПрПЌ МахПЎОтся ЎаММый ЌПЎуль (файл `app/routers/items.py` МахПЎОтся в каталПге `app/routers/`)... -* ... перейЎОте в рПЎОтельскОй пакет (каталПг `app/`)... -* ... затеЌ перейЎОте в рПЎОтельскОй пакет текущегП пакета (такПгП пакета Ме существует, `app` МахПЎОтся Ма саЌПЌ верхМеЌ урПвМе 😱)... -* ... МайЎОте в МёЌ ЌПЎуль `dependencies` (файл `app/dependencies.py`)... -* ... О ОЌпПртОруйте Оз МегП фуМкцОю `get_token_header`. +* Начать в тПЌ же пакете, в кПтПрПЌ МахПЎОтся этПт ЌПЎуль (файл `app/routers/items.py`) распПлПжеМ в (каталПге `app/routers/`)... +* перейтО в рПЎОтельскОй пакет (каталПг `app/`)... +* затеЌ перейтО в рПЎОтельскОй пакет этПгП пакета (рПЎОтельскПгП пакета Мет, `app` — верхМОй урПвеМь 😱)... +* О таЌ МайтО ЌПЎуль `dependencies` (файл `app/dependencies.py`)... +* О ОЌпПртОрПвать Оз МегП фуМкцОю `get_token_header`. -ЭтП буЎет ПтМПсОться к МекПтПрПЌу пакету, МахПЎящеЌуся Ма ПЎОМ урПвеМь выше чеЌ `app/` О сПЎержащеЌу свПй сПбствеММый файл `__init__.py`. НП МОчегП такПгП у Мас Мет. ППэтПЌу этП прОвеЎет к ПшОбке в МашеЌ прОЌере. 🚚 +ЭтП ссылалПсь бы Ма какПй-тП пакет выше `app/`, сП свПОЌ файлПЌ `__init__.py` О т.п. НП у Мас такПгП Мет. ППэтПЌу этП вызвалП бы ПшОбку в МашеЌ прОЌере. 🚚 -Теперь вы зМаете, как рабПтает ОЌпПрт в Python, О сЌПжете ОспПльзПвать ПтМПсОтельМПе ОЌпПртОрПваМОе в свПОх сПбствеММых прОлПжеМОях любПгП урПвМя слПжМПстО. 🀓 +НП теперь вы зМаете, как этП рабПтает, так чтП ЌПжете ОспПльзПвать ПтМПсОтельМые ОЌпПрты в свПОх прОлПжеМОях, МезавОсОЌП Пт тПгП, МаскПлькП ПМО слПжМые. 🀓 -### ДПбавлеМОе пПльзПвательскОх тегПв (`tags`), ПтветПв (`responses`) О завОсОЌПстей (`dependencies`) { #add-some-custom-tags-responses-and-dependencies } +### ДПбавлеМОе пПльзПвательскОх `tags`, `responses` О `dependencies` { #add-some-custom-tags-responses-and-dependencies } -Мы Ме буЎеЌ ЎПбавлять префОкс `/items` О спОсПк тегПв `tags=["items"]` Ўля кажЎПгП *эМЎпПОМта*, т.к. Ќы уже Ох ЎПбавОлО с пПЌПщью `APIRouter`. +Мы Ме ЎПбавляеЌ префОкс `/items` О `tags=["items"]` к кажЎПй *ПперацОО путО*, пПтПЌу чтП Ќы ЎПбавОлО Ох в `APIRouter`. -НП пПЌОЌП этПгП Ќы ЌПжеЌ ЎПбавОть МПвые тегО Ўля кажЎПгП ПтЎельМПгП *эМЎпПОМта*, а также МекПтПрые ЎПпПлМОтельМые Птветы (`responses`), характерМые Ўля ЎаММПгП *эМЎпПОМта*: +НП Ќы всё равМП ЌПжеЌ ЎПбавОть _ещё_ `tags`, кПтПрые буЎут прОЌеМяться к кПМкретМПй *ПперацОО путО*, а также ЎПпПлМОтельМые `responses`, спецОфОчМые Ўля этПй *ПперацОО путО*: {* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[30:31] title["app/routers/items.py"] *} /// tip | ППЎсказка -ППслеЎМОй *эМЎпПОМт* буЎет ОЌеть слеЎующую кПЌбОМацОю тегПв: `["items", "custom"]`. +Эта пПслеЎМяя ПперацОя путО буЎет ОЌеть кПЌбОМацОю тегПв: `["items", "custom"]`. -А также в егП ЎПкуЌеМтацОО буЎут сПЎержаться Пба Птвета: ПЎОМ Ўля `404` О ЎругПй Ўля `403`. +И в ЎПкуЌеМтацОО у Меё буЎут Пба Птвета: ПЎОМ Ўля `404` О ПЎОМ Ўля `403`. /// @@ -293,29 +295,29 @@ from ...dependencies import get_token_header ИЌеММП сюЎа вы ОЌпПртОруете О ОЌеММП зЎесь вы ОспПльзуете класс `FastAPI`. -ЭтП ПсМПвМПй файл вашегП прОлПжеМОя, кПтПрый ПбъеЎОМяет всё в ПЎМП целПе. +ЭтП ПсМПвМПй файл вашегП прОлПжеМОя, кПтПрый связывает всё вПеЎОМП. -И теперь, кПгЎа бПльшая часть лПгОкО прОлПжеМОя разЎелеМа Ма ПтЎельМые ЌПЎулО, ПсМПвМПй файл `app/main.py` буЎет ЎПстатПчМП прПстыЌ. +И так как бПльшая часть вашей лПгОкО теперь буЎет МахПЎОться в ПтЎельМых спецОфОчМых ЌПЎулях, ПсМПвМПй файл буЎет ЎПвПльМП прПстыЌ. ### ИЌпПрт `FastAPI` { #import-fastapi } -Вы ОЌпПртОруете О сПзЎаете класс `FastAPI` как ПбычМП. +Вы ОЌпПртОруете О сПзЎаёте класс `FastAPI` как ПбычМП. -Мы Ўаже ЌПжеЌ ПбъявОть [глПбальМые завОсОЌПстО](dependencies/global-dependencies.md){.internal-link target=_blank}, кПтПрые буЎут ПбъеЎОМеМы с завОсОЌПстяЌО Ўля кажЎПгП ПтЎельМПгП ЌаршрутОзатПра: +И Ќы Ўаже ЌПжеЌ ПбъявОть [глПбальМые завОсОЌПстО](dependencies/global-dependencies.md){.internal-link target=_blank}, кПтПрые буЎут ПбъеЎОМеМы с завОсОЌПстяЌО Ўля кажЎПгП `APIRouter`: {* ../../docs_src/bigger_applications/app_an_py39/main.py hl[1,3,7] title["app/main.py"] *} ### ИЌпПрт `APIRouter` { #import-the-apirouter } -Теперь Ќы ОЌпПртОруеЌ ЎругОе суб-ЌПЎулО, сПЎержащОе `APIRouter`: +Теперь Ќы ОЌпПртОруеЌ ЎругОе пПЎЌПЎулО, сПЎержащОе `APIRouter`: {* ../../docs_src/bigger_applications/app_an_py39/main.py hl[4:5] title["app/main.py"] *} -Так как файлы `app/routers/users.py` О `app/routers/items.py` являются суб-ЌПЎуляЌО ПЎМПгП О тПгП же Python-пакета `app`, тП Ќы сЌПжеЌ Ох ОЌпПртОрПвать, вПспПльзПвавшОсь ПперацОей ПтМПсОтельМПгП ОЌпПрта `.`. +Так как файлы `app/routers/users.py` О `app/routers/items.py` являются пПЎЌПЎуляЌО, вхПЎящОЌО в ПЎОМ О тПт же Python-пакет `app`, Ќы ЌПжеЌ ОспПльзПвать ПЎМу тПчку `.` Ўля ОЌпПрта через «ПтМПсОтельМые ОЌпПрты». -### Как рабПтает ОЌпПрт? { #how-the-importing-works } +### Как рабПтает ОЌпПрт { #how-the-importing-works } -ДаММая стрПка кПЎа: +ЭтПт фрагЌеМт: ```Python from .routers import items, users @@ -323,15 +325,15 @@ from .routers import items, users ПзМачает: -* НачМОте с пакета, в кПтПрПЌ сПЎержОтся ЎаММый ЌПЎуль (файл `app/main.py` сПЎержОтся в каталПге `app/`)... -* ... МайЎОте суб-пакет `routers` (каталПг `app/routers/`)... -* ... О Оз МегП ОЌпПртОруйте суб-ЌПЎулО `items` (файл `app/routers/items.py`) О `users` (файл `app/routers/users.py`)... +* Начать в тПЌ же пакете, в кПтПрПЌ МахПЎОтся этПт ЌПЎуль (файл `app/main.py`) распПлПжеМ в (каталПге `app/`)... +* МайтО пПЎпакет `routers` (каталПг `app/routers/`)... +* О ОЌпПртОрПвать Оз МегП пПЎЌПЎулО `items` (файл `app/routers/items.py`) О `users` (файл `app/routers/users.py`)... -В ЌПЎуле `items` сПЎержОтся переЌеММая `router` (`items.router`), та саЌая, кПтПрую Ќы сПзЎалО в файле `app/routers/items.py`, ПМа является ПбъектПЌ класса `APIRouter`. +В ЌПЎуле `items` буЎет переЌеММая `router` (`items.router`). ЭтП та же саЌая, кПтПрую Ќы сПзЎалО в файле `app/routers/items.py`, этП Пбъект `APIRouter`. -И затеЌ Ќы сЎелаеЌ тП же саЌПе Ўля ЌПЎуля `users`. +И затеЌ Ќы ЎелаеЌ тП же саЌПе Ўля ЌПЎуля `users`. -Мы также ЌПглО бы ОЌпПртОрПвать О ЎругОЌ ЌетПЎПЌ: +Мы также ЌПглО бы ОЌпПртОрПвать Ох так: ```Python from app.routers import items, users @@ -339,44 +341,44 @@ from app.routers import items, users /// info | ПрОЌечаМОе -Первая версОя является прОЌерПЌ ПтМПсОтельМПгП ОЌпПрта: +Первая версОя — этП «ПтМПсОтельМый ОЌпПрт»: ```Python from .routers import items, users ``` -ВтПрая версОя является прОЌерПЌ абсПлютМПгП ОЌпПрта: +ВтПрая версОя — этП «абсПлютМый ОЌпПрт»: ```Python from app.routers import items, users ``` -УзМать бПльше П пакетах О ЌПЎулях в Python вы ЌПжете Оз ПфОцОальМПй ЎПкуЌеМтацОО Python П ЌПЎулях +ЧтПбы узМать бПльше П Python-пакетах О ЌПЎулях, прПчОтайте ПфОцОальМую ЎПкуЌеМтацОю Python П ЌПЎулях. /// -### Избегайте кПМфлОктПв ОЌеМ { #avoid-name-collisions } +### Избегайте кПМфлОктПв ОЌёМ { #avoid-name-collisions } -ВЌестП тПгП чтПбы ОЌпПртОрПвать тПлькП переЌеММую `router`, Ќы ОЌпПртОруеЌ МепПсреЎствеММП суб-ЌПЎуль `items`. +Мы ОЌпПртОруеЌ пПЎЌПЎуль `items` МапряЌую, вЌестП тПгП чтПбы ОЌпПртОрПвать тПлькП егП переЌеММую `router`. -Мы ЎелаеЌ этП пПтПЌу, чтП у Мас есть ещё ПЎМа переЌеММая `router` в суб-ЌПЎуле `users`. +ЭтП пПтПЌу, чтП у Мас также есть Ўругая переЌеММая с ОЌеМеЌ `router` в пПЎЌПЎуле `users`. -ЕслО бы Ќы ОЌпПртОрПвалО Ох ПЎМу за ЎругПй, как пПказаМП в прОЌере: +ЕслО бы Ќы ОЌпПртОрПвалО Ох ПЎМу за ЎругПй, как зЎесь: ```Python from .routers.items import router from .routers.users import router ``` -тП переЌеММая `router` Оз `users` перепОсал бы переЌеММую `router` Оз `items`, О у Мас Ме былП бы вПзЌПжМПстО ОспПльзПвать Ох ПЎМПвреЌеММП. +тП `router` Оз `users` перезапОсал бы `router` Оз `items`, О Ќы Ме сЌПглО бы ОспПльзПвать Ох ПЎМПвреЌеММП. -ППэтПЌу, Ўля тПгП чтПбы ОспПльзПвать Пбе этО переЌеММые в ПЎМПЌ файле, Ќы ОЌпПртОрПвалО сППтветствующОе суб-ЌПЎулО: +ППэтПЌу, чтПбы ОЌеть вПзЌПжМПсть ОспПльзПвать Пбе в ПЎМПЌ файле, Ќы ОЌпПртОруеЌ пПЎЌПЎулО МапряЌую: {* ../../docs_src/bigger_applications/app_an_py39/main.py hl[5] title["app/main.py"] *} -### ППЎключеМОе ЌаршрутОзатПрПв (`APIRouter`) Ўля `users` О Ўля `items` { #include-the-apirouters-for-users-and-items } +### ППЎключеМОе `APIRouter` Ўля `users` О `items` { #include-the-apirouters-for-users-and-items } -Давайте пПЎключОЌ ЌаршрутОзатПры (`router`) Оз суб-ЌПЎулей `users` О `items`: +Теперь Ўавайте пПЎключОЌ `router` Оз пПЎЌПЎулей `users` О `items`: {* ../../docs_src/bigger_applications/app_an_py39/main.py hl[10:11] title["app/main.py"] *} @@ -388,79 +390,78 @@ from .routers.users import router /// -С пПЌПщью `app.include_router()` Ќы ЌПжеЌ ЎПбавОть кажЎый Оз ЌаршрутОзатПрПв (`APIRouter`) в ПсМПвМПе прОлПжеМОе `FastAPI`. +С пПЌПщью `app.include_router()` Ќы ЌПжеЌ ЎПбавОть кажЎый `APIRouter` в ПсМПвМПе прОлПжеМОе `FastAPI`. -ОМ пПЎключОт все Ќаршруты заЎаММПгП ЌаршрутОзатПра к МашеЌу прОлПжеМОю. +ОМ включОт все Ќаршруты этПгП ЌаршрутОзатПра как часть прОлПжеМОя. /// note | ТехМОческОе ЎеталО -ЀактОческО, вМутрО ПМ сПзЎаст все *ПперацОО путО* Ўля кажЎПй ПперацОО путО ПбъявлеММПй в `APIRouter`. +ЀактОческО, вМутрО ПМ сПзЎаст *ПперацОю путО* Ўля кажЎПй *ПперацОО путО*, ПбъявлеММПй в `APIRouter`. -И пПЎ капПтПЌ всё буЎет рабПтать так, как буЎтП бы Ќы ОЌееЌ ЎелП с ПЎМОЌ файлПЌ прОлПжеМОя. +Так чтП пПЎ капПтПЌ всё буЎет рабПтать так, как буЎтП всё былП ПЎМОЌ прОлПжеМОеЌ. /// /// check | ЗаЌетка -ПрО пПЎключеМОО ЌаршрутОзатПрПв Ме стПОт беспПкПОться П прПОзвПЎОтельМПстО. +ПрО пПЎключеМОО ЌаршрутОзатПрПв Ме МужМП беспПкПОться П прПОзвПЎОтельМПстО. -ОперацОя пПЎключеМОя зайЌёт ЌОкрПсекуМЎы О пПМаЎПбОтся тПлькП прО запуске прОлПжеМОя. +ЭтП зайЌёт ЌОкрПсекуМЎы О прПОзПйЎёт тПлькП прО старте. -ТакОЌ ПбразПЌ, этП Ме пПвлОяет Ма прПОзвПЎОтельМПсть. ⚡ +Так чтП этП Ме пПвлОяет Ма прПОзвПЎОтельМПсть. ⚡ /// -### ППЎключеМОе `APIRouter` с пПльзПвательскОЌО префОксПЌ (`prefix`), тегаЌО (`tags`), ПтветаЌО (`responses`), О завОсОЌПстяЌО (`dependencies`) { #include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies } +### ППЎключеМОе `APIRouter` с пПльзПвательскОЌО `prefix`, `tags`, `responses` О `dependencies` { #include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies } Теперь Ўавайте преЎставОЌ, чтП ваша ПргаМОзацОя переЎала ваЌ файл `app/internal/admin.py`. -ОМ сПЎержОт `APIRouter` с МекПтПрыЌО *эМЎпПОтаЌО* аЎЌОМОстрОрПваМОя, кПтПрые ваша ПргаМОзацОя ОспПльзует Ўля МескПлькОх прПектПв. +ОМ сПЎержОт `APIRouter` с МекПтПрыЌО аЎЌОМОстратОвМыЌО *ПперацОяЌО путО*, кПтПрые ваша ПргаМОзацОя ОспПльзует в МескПлькОх прПектах. -В ЎаММПЌ прОЌере этП сЎелать ПчеМь прПстП. НП Ўавайте преЎпПлПжОЌ, чтП пПскПльку файл ОспПльзуется Ўля МескПлькОх прПектПв, -тП Ќы Ме ЌПжеЌ ЌПЎОфОцОрПвать егП, ЎПбавляя префОксы (`prefix`), завОсОЌПстО (`dependencies`), тегО (`tags`), О т.ÐŽ. МепПсреЎствеММП в `APIRouter`: +Для этПгП прОЌера всё буЎет ПчеМь прПстП. НП ЎПпустОЌ, чтП пПскПльку ПМ ОспПльзуется сПвЌестМП с ЎругОЌО прПектаЌО в ПргаМОзацОО, Ќы Ме ЌПжеЌ ЌПЎОфОцОрПвать егП О ЎПбавОть `prefix`, `dependencies`, `tags` О т.ÐŽ. МепПсреЎствеММП в `APIRouter`: {* ../../docs_src/bigger_applications/app_an_py39/internal/admin.py hl[3] title["app/internal/admin.py"] *} -НП, МесЌПтря Ма этП, Ќы хПтОЌ ОспПльзПвать кастПЌМый префОкс (`prefix`) Ўля пПЎключеММПгП ЌаршрутОзатПра (`APIRouter`), в результате чегП, кажЎая *ПперацОя путО* буЎет МачОМаться с `/admin`. Также Ќы хПтОЌ защОтОть Маш ЌаршрутОзатПр с пПЌПщью завОсОЌПстей, сПзЎаММых Ўля МашегП прПекта. И ещё Ќы хПтОЌ включОть тегО (`tags`) О Птветы (`responses`). +НП Ќы всё равМП хПтОЌ заЎать пПльзПвательскОй `prefix` прО пПЎключеМОО `APIRouter`, чтПбы все егП *ПперацОО путО* МачОМалОсь с `/admin`, хПтОЌ защОтОть егП с пПЌПщью `dependencies`, кПтПрые у Мас уже есть Ўля этПгП прПекта, О хПтОЌ включОть `tags` О `responses`. -Мы ЌПжеЌ прОЌеМОть все вышеперечОслеММые МастрПйкО, Ме ОзЌеМяя МачальМый `APIRouter`. НаЌ всегП лОшь МужМП переЎать МужМые параЌетры в `app.include_router()`. +Мы ЌПжеЌ ПбъявОть всё этП, Ме ОзЌеМяя ОсхПЎМый `APIRouter`, переЎав этО параЌетры в `app.include_router()`: {* ../../docs_src/bigger_applications/app_an_py39/main.py hl[14:17] title["app/main.py"] *} -ТакОЌ ПбразПЌ, ПрОгОМальМый `APIRouter` Ме буЎет ЌПЎОфОцОрПваМ, О Ќы сЌПжеЌ ОспПльзПвать файл `app/internal/admin.py` сразу в МескПлькОх прПектах ПргаМОзацОО. +ТакОЌ ПбразПЌ ОсхПЎМый `APIRouter` Ме буЎет ЌПЎОфОцОрПваМ, О Ќы сЌПжеЌ ОспПльзПвать файл `app/internal/admin.py` сразу в МескПлькОх прПектах ПргаМОзацОО. -В результате, в МашеЌ прОлПжеМОО кажЎый *эМЎпПОМт* ЌПЎуля `admin` буЎет ОЌеть: +В результате в МашеЌ прОлПжеМОО кажЎая Оз *ПперацОй путО* Оз ЌПЎуля `admin` буЎет ОЌеть: * ПрефОкс `/admin`. * Тег `admin`. * ЗавОсОЌПсть `get_token_header`. * Ответ `418`. 🍵 -ЭтП буЎет ОЌеть ЌестП ОсключОтельМП Ўля `APIRouter` в МашеЌ прОлПжеМОО, О Ме затрПМет любПй ЎругПй кПЎ, ОспПльзующОй егП. +НП этП пПвлОяет тПлькП Ма этПт `APIRouter` в МашеЌ прОлПжеМОО, а Ме Ма любПй ЎругПй кПЎ, кПтПрый егП ОспПльзует. -НапрОЌер, ЎругОе прПекты, ЌПгут ОспПльзПвать тПт же саЌый `APIRouter` с ЎругОЌО ЌетПЎаЌО аутеМтОфОкацОО. +Так чтП, МапрОЌер, ЎругОе прПекты ЌПгут ОспПльзПвать тПт же `APIRouter` с ЎругОЌ ЌетПЎПЌ аутеМтОфОкацОО. -### ППЎключеМОе ПтЎельМПгП *эМЎпПОМта* { #include-a-path-operation } +### ППЎключеМОе *ПперацОО путО* { #include-a-path-operation } -Мы также ЌПжеЌ ЎПбавОть *эМЎпПОМт* МепПсреЎствеММП в ПсМПвМПе прОлПжеМОе `FastAPI`. +Мы также ЌПжеЌ ЎПбавлять *ПперацОО путО* МапряЌую в прОлПжеМОе `FastAPI`. -ЗЎесь Ќы этП ЎелаеЌ ... прПстП, чтПбы пПказать, чтП этП вПзЌПжМП 🀷: +ЗЎесь Ќы ЎелаеЌ этП... прПстП чтПбы пПказать, чтП ЌПжеЌ 🀷: {* ../../docs_src/bigger_applications/app_an_py39/main.py hl[21:23] title["app/main.py"] *} -О этП буЎет рабПтать кПрректМП вЌесте с ЎругОЌО *эМЎпПОМтаЌО*, ЎПбавлеММыЌО с пПЌПщью `app.include_router()`. +О этП буЎет рабПтать кПрректМП вЌесте сП всеЌО ЎругОЌО *ПперацОяЌО путО*, ЎПбавлеММыЌО через `app.include_router()`. -/// info | СлПжМые техМОческОе ЎеталО +/// info | ОчеМь техМОческОе ЎеталО -**ПрОЌечаМОе**: этП слПжМая техМОческая Ўеталь, кПтПрую, скПрее всегП, **вы ЌПжете прПпустОть**. +**ПрОЌечаМОе**: этП ПчеМь техМОческая Ўеталь, кПтПрую, верПятМП, ЌПжМП **прПстП прПпустОть**. --- -МаршрутОзатПры (`APIRouter`) Ме "ЌПМтОруются" пП-ПтЎельМПстО О Ме ОзПлОруются Пт ПстальМПгП прОлПжеМОя. +`APIRouter` Ме «ЌПМтОруются», ПМО Ме ОзПлОрПваМы Пт ПстальМПгП прОлПжеМОя. -ЭтП прПОсхПЎОт пПтПЌу, чтП МужМП включОть Ох *эМЎпПОМты* в OpenAPI схеЌу О в ОМтерфейс пПльзПвателя. +ЭтП пПтПЌу, чтП Ќы хПтОЌ включОть Ох *ПперацОО путО* в OpenAPI-схеЌу О пПльзПвательскОе ОМтерфейсы. -В сОлу тПгП, чтП Ќы Ме ЌПжеЌ Ох ОзПлОрПвать О "прОЌПМтОрПвать" МезавОсОЌП Пт ПстальМых, *эМЎпПОМты* клПМОруются (пересПзЎаются) О Ме пПЎключаются МапряЌую. +Так как Ќы Ме ЌПжеЌ прПстП ОзПлОрПвать Ох О «сЌПМтОрПвать» МезавОсОЌП Пт ПстальМПгП, *ПперацОО путО* «клПМОруются» (пересПзЎаются), а Ме включаются МапряЌую. /// @@ -480,24 +481,24 @@ $ fastapi dev app/main.py ОткрПйте ЎПкуЌеМтацОю пП аЎресу http://127.0.0.1:8000/docs. -Вы увОЎОте автПЌатОческую API ЎПкуЌеМтацОю. ОМа включает в себя Ќаршруты Оз суб-ЌПЎулей, ОспПльзуя верМые Ќаршруты, префОксы О тегО: +Вы увОЎОте автПЌатОческую ЎПкуЌеМтацОю API, включая путО Оз всех пПЎЌПЎулей, с ОспПльзПваМОеЌ кПрректМых путей (О префОксПв) О кПрректМых тегПв: -## ППЎключеМОе существующегП Ќаршрута через МПвый префОкс (`prefix`) { #include-the-same-router-multiple-times-with-different-prefix } +## ППЎключеМОе ПЎМПгП О тПгП же ЌаршрутОзатПра МескПлькП раз с разМыЌО `prefix` { #include-the-same-router-multiple-times-with-different-prefix } -Вы ЌПжете ОспПльзПвать `.include_router()` МескПлькП раз с ПЎМОЌ О теЌ же ЌаршрутПЌ, прОЌеМОв разлОчМые префОксы. +Вы ЌПжете ОспПльзПвать `.include_router()` МескПлькП раз с *ПЎМОЌ О теЌ же* ЌаршрутОзатПрПЌ, ОспПльзуя разМые префОксы. -ЭтП ЌПжет быть пПлезМыЌ, еслО МужМП преЎПставОть ЎПступ к ПЎМПЌу О тПЌу же API через разлОчМые префОксы, МапрОЌер, `/api/v1` О `/api/latest`. +ЭтП ЌПжет быть пПлезМП, МапрОЌер, чтПбы преЎПставОть ЎПступ к ПЎМПЌу О тПЌу же API с разМыЌО префОксаЌО, МапрОЌер `/api/v1` О `/api/latest`. -ЭтП прПЎвОМутый спПсПб, кПтПрый ваЌ ЌПжет О Ме прОгПЎОтся. Мы прОвПЎОЌ егП Ма случай, еслО вЎруг ваЌ этП пПМаЎПбОтся. +ЭтП прПЎвОМутПе ОспПльзПваМОе, кПтПрПе ваЌ ЌПжет О Ме пПМаЎПбОться, МП ПМП есть Ма случай, еслО пПМаЎПбОтся. -## ВключеМОе ПЎМПгП ЌаршрутОзатПра (`APIRouter`) в ЎругПй { #include-an-apirouter-in-another } +## ППЎключеМОе `APIRouter` в ЎругПй `APIRouter` { #include-an-apirouter-in-another } -ТПчМП так же, как вы включаете `APIRouter` в прОлПжеМОе `FastAPI`, вы ЌПжете включОть `APIRouter` в ЎругПй `APIRouter`: +ТПчМП так же, как вы ЌПжете пПЎключОть `APIRouter` к прОлПжеМОю `FastAPI`, вы ЌПжете пПЎключОть `APIRouter` к ЎругПЌу `APIRouter`, ОспПльзуя: ```Python router.include_router(other_router) ``` -УЎПстПверьтесь, чтП вы сЎелалО этП ЎП тПгП, как пПЎключОть ЌаршрутОзатПр (`router`) к вашеЌу `FastAPI` прОлПжеМОю, О *эМЎпПОМты* ЌаршрутОзатПра `other_router` былО также пПЎключеМы. +УбеЎОтесь, чтП вы сЎелалО этП ЎП пПЎключеМОя `router` к прОлПжеМОю `FastAPI`, чтПбы *ПперацОО путО* Оз `other_router` также былО пПЎключеМы. diff --git a/docs/ru/docs/tutorial/body-updates.md b/docs/ru/docs/tutorial/body-updates.md index 73f4e66c76..4a7adb2559 100644 --- a/docs/ru/docs/tutorial/body-updates.md +++ b/docs/ru/docs/tutorial/body-updates.md @@ -2,13 +2,13 @@ ## ОбМПвлеМОе с заЌеМПй прО пПЌПщО `PUT` { #update-replacing-with-put } -Для пПлМПгП ПбМПвлеМОя элеЌеМта ЌПжМП вПспПльзПваться ПперацОей HTTP `PUT`. +ЧтПбы ПбМПвОть элеЌеМт, вы ЌПжете ОспПльзПвать ПперацОю HTTP `PUT`. Вы ЌПжете ОспПльзПвать `jsonable_encoder`, чтПбы преПбразПвать вхПЎМые ЎаММые в ЎаММые, кПтПрые ЌПжМП сПхраМОть как JSON (МапрОЌер, в NoSQL-базе ЎаММых). НапрОЌер, преПбразПваМОе `datetime` в `str`. {* ../../docs_src/body_updates/tutorial001_py310.py hl[28:33] *} -`PUT` ОспПльзуется Ўля пПлучеМОя ЎаММых, кПтПрые ЎПлжМы пПлМПстью заЌеМОть существующОе ЎаММые. +`PUT` ОспПльзуется Ўля пПлучеМОя ЎаММых, кПтПрые ЎПлжМы заЌеМОть существующОе ЎаММые. ### ПреЎупрежЎеМОе П заЌеМе { #warning-about-replacing } @@ -24,11 +24,11 @@ пПскПльку ПМП Ме включает уже сПхраМеММый атрОбут `"tax": 20.2`, вхПЎМая ЌПЎель прОЌет зМачеМОе пП уЌПлчаМОю `"tax": 10.5`. -И ЎаММые буЎут сПхраМеМы с этОЌ "МПвыЌ" `tax`, равМыЌ `10,5`. +И ЎаММые буЎут сПхраМеМы с этОЌ «МПвыЌ» `tax`, равМыЌ `10.5`. ## ЧастОчМПе ПбМПвлеМОе с пПЌПщью `PATCH` { #partial-updates-with-patch } -Также ЌПжМП ОспПльзПвать HTTP `PATCH` ПперацОю Ўля *частОчМПгП* ПбМПвлеМОя ЎаММых. +Также ЌПжМП ОспПльзПвать ПперацОю HTTP `PATCH` Ўля *частОчМПгП* ПбМПвлеМОя ЎаММых. ЭтП ПзМачает, чтП ЌПжМП переЎавать тПлькП те ЎаММые, кПтПрые МеПбхПЎОЌП ПбМПвОть, Пставляя ПстальМые МетрПМутыЌО. @@ -46,19 +46,13 @@ ### ИспПльзПваМОе параЌетра `exclude_unset` в Pydantic { #using-pydantics-exclude-unset-parameter } -ЕслО МеПбхПЎОЌП выпПлМОть частОчМПе ПбМПвлеМОе, тП ПчеМь пПлезМП ОспПльзПвать параЌетр `exclude_unset` в ЌетПЎе `.model_dump()` ЌПЎелО Pydantic. +ЕслО вы хПтОте пПлучать частОчМые ПбМПвлеМОя, ПчеМь пПлезМП ОспПльзПвать параЌетр `exclude_unset` в `.model_dump()` ЌПЎелО Pydantic. НапрОЌер, `item.model_dump(exclude_unset=True)`. -/// info | ИМфПрЌацОя +В результате буЎет сгеМерОрПваМ `dict`, сПЎержащОй тПлькП те ЎаММые, кПтПрые былО заЎаМы прО сПзЎаМОО ЌПЎелО `item`, без учета зМачеМОй пП уЌПлчаМОю. -В Pydantic v1 ЌетПЎ Мазывался `.dict()`, в Pydantic v2 ПМ пПЌечеМ как устаревшОй (МП все еще пПЎЎержОвается) О переОЌеМПваМ в `.model_dump()`. - -ПрОЌеры зЎесь ОспПльзуют `.dict()` Ўля сПвЌестОЌПстО с Pydantic v1, МП еслО вы ЌПжете ОспПльзПвать Pydantic v2, лучше ОспПльзуйте `.model_dump()`. - -/// - -В результате буЎет сгеМерОрПваМ слПварь, сПЎержащОй тПлькП те ЎаММые, кПтПрые былО заЎаМы прО сПзЎаМОО ЌПЎелО `item`, без учета зМачеМОй пП уЌПлчаМОю. ЗатеЌ вы ЌПжете ОспПльзПвать этП Ўля сПзЎаМОя слПваря тПлькП с теЌО ЎаММыЌО, кПтПрые былО устаМПвлеМы (ПтправлеМы в запрПсе), Ппуская зМачеМОя пП уЌПлчаМОю: +ЗатеЌ вы ЌПжете ОспПльзПвать этП Ўля сПзЎаМОя `dict` тПлькП с теЌО ЎаММыЌО, кПтПрые былО устаМПвлеМы (ПтправлеМы в запрПсе), Ппуская зМачеМОя пП уЌПлчаМОю: {* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *} @@ -66,14 +60,6 @@ Теперь ЌПжМП сПзЎать кПпОю существующей ЌПЎелО, ОспПльзуя `.model_copy()`, О переЎать параЌетр `update` с `dict`, сПЎержащОЌ ЎаММые Ўля ПбМПвлеМОя. -/// info | ИМфПрЌацОя - -В Pydantic v1 ЌетПЎ Мазывался `.copy()`, в Pydantic v2 ПМ пПЌечеМ как устаревшОй (МП все еще пПЎЎержОвается) О переОЌеМПваМ в `.model_copy()`. - -ПрОЌеры зЎесь ОспПльзуют `.copy()` Ўля сПвЌестОЌПстО с Pydantic v1, МП еслО вы ЌПжете ОспПльзПвать Pydantic v2, лучше ОспПльзуйте `.model_copy()`. - -/// - НапрОЌер, `stored_item_model.model_copy(update=update_data)`: {* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *} @@ -84,9 +70,9 @@ * (ОпцОПМальМП) ОспПльзПвать `PATCH` вЌестП `PUT`. * Извлечь сПхраМёММые ЎаММые. -* ППЌестОть этО ЎаММые в Pydantic ЌПЎель. +* ППЌестОть этО ЎаММые в Pydantic-ЌПЎель. * СгеМерОрПвать `dict` без зМачеМОй пП уЌПлчаМОю Оз вхПЎМПй ЌПЎелО (с ОспПльзПваМОеЌ `exclude_unset`). - * ТакОЌ ПбразПЌ, ЌПжМП ПбМПвлять тПлькП те зМачеМОя, кПтПрые ЎействОтельМП устаМПвлеМы пПльзПвателеЌ, вЌестП тПгП чтПбы переПпреЎелять зМачеМОя, уже сПхраМеММые в ЌПЎелО пП уЌПлчаМОю. + * ТакОЌ ПбразПЌ, ЌПжМП ПбМПвлять тПлькП те зМачеМОя, кПтПрые ЎействОтельМП устаМПвлеМы пПльзПвателеЌ, вЌестП тПгП чтПбы переПпреЎелять уже сПхраМеММые зМачеМОя зМачеМОяЌО пП уЌПлчаМОю Оз вашей ЌПЎелО. * СПзЎать кПпОю храМОЌПй ЌПЎелО, ПбМПвОв ее атрОбуты пПлучеММыЌО частОчМыЌО ПбМПвлеМОяЌО (с пПЌПщью параЌетра `update`). * ПреПбразПвать скПпОрПваММую ЌПЎель в тП, чтП ЌПжет быть сПхраМеМП в вашей БД (МапрОЌер, с пПЌПщью `jsonable_encoder`). * ЭтП сравМОЌП с пПвтПрМыЌ ОспПльзПваМОеЌ ЌетПЎа ЌПЎелО `.model_dump()`, МП прО этПЌ прПОсхПЎОт прПверка (О преПбразПваМОе) зМачеМОй в тОпы ЎаММых, кПтПрые ЌПгут быть преПбразПваМы в JSON, МапрОЌер, `datetime` в `str`. @@ -97,7 +83,7 @@ /// tip | ППЎсказка -Эту же техМОку ЌПжМП ОспПльзПвать О Ўля ПперацОО HTTP `PUT`. +На саЌПЌ Ўеле эту же техМОку ЌПжМП ОспПльзПвать О Ўля ПперацОО HTTP `PUT`. НП в прОвеЎеММПЌ прОЌере ОспПльзуется `PATCH`, пПскПльку ПМ был сПзЎаМ ОЌеММП Ўля такОх случаев ОспПльзПваМОя. diff --git a/docs/ru/docs/tutorial/body.md b/docs/ru/docs/tutorial/body.md index b61f3e7a09..537d7ebc96 100644 --- a/docs/ru/docs/tutorial/body.md +++ b/docs/ru/docs/tutorial/body.md @@ -32,9 +32,10 @@ {* ../../docs_src/body/tutorial001_py310.py hl[5:9] *} + Так же, как прО ПбъявлеМОО параЌетрПв запрПса: кПгЎа атрОбут ЌПЎелО ОЌеет зМачеМОе пП уЌПлчаМОю, ПМ Ме ПбязателеМ. ИМаче ПМ ПбязателеМ. ИспПльзуйте `None`, чтПбы сЎелать егП прПстП МеПбязательМыЌ. -НапрОЌер, ЌПЎель выше ПпОсывает такПй JSON "Пбъект" (ОлО Python `dict`): +НапрОЌер, ЌПЎель выше ПпОсывает такПй JSON "`object`" (ОлО Python `dict`): ```JSON { @@ -45,7 +46,7 @@ } ``` -...так как `description` О `tax` являются МеПбязательМыЌО (сП зМачеМОеЌ пП уЌПлчаМОю `None`), такПй JSON "Пбъект" тПже буЎет кПрректМыЌ: +...так как `description` О `tax` являются МеПбязательМыЌО (сП зМачеМОеЌ пП уЌПлчаМОю `None`), такПй JSON "`object`" тПже буЎет кПрректМыЌ: ```JSON { @@ -73,7 +74,7 @@ * ПереЎаст пПлучеММые ЎаММые в параЌетр `item`. * ППскПльку вМутрО фуМкцОО вы ПбъявОлО егП с тОпПЌ `Item`, у вас буЎет пПЎЎержка сП стПрПМы реЎактПра кПЎа (автПзавершеМОе О т. п.) Ўля всех атрОбутПв О Ох тОпПв. * СгеМерОрует ПпреЎелеМОя JSON Schema Ўля вашей ЌПЎелО; вы ЌПжете ОспПльзПвать Ох О в ЎругОх Ќестах, еслО этП ОЌеет сЌысл Ўля вашегП прПекта. -* ЭтО схеЌы буЎут частью сгеМерОрПваММПй схеЌы OpenAPI О буЎут ОспПльзПваться автПЌатОческПй ЎПкуЌеМтацОей UIs. +* ЭтО схеЌы буЎут частью сгеМерОрПваММПй схеЌы OpenAPI О буЎут ОспПльзПваться автПЌатОческПй ЎПкуЌеМтацОей UIs. ## АвтПЌатОческая ЎПкуЌеМтацОя { #automatic-docs } @@ -127,14 +128,6 @@ JSON Schema вашОх ЌПЎелей буЎет частью сгеМерОрП {* ../../docs_src/body/tutorial002_py310.py *} -/// info | ИМфПрЌацОя - -В Pydantic v1 ЌетПЎ Мазывался `.dict()`, в Pydantic v2 ПМ был пПЌечеМ как устаревшОй (МП всё ещё пПЎЎержОвается) О переОЌеМПваМ в `.model_dump()`. - -ПрОЌеры зЎесь ОспПльзуют `.dict()` Ўля сПвЌестОЌПстО с Pydantic v1, МП еслО вы ЌПжете ОспПльзПвать Pydantic v2, ОспПльзуйте `.model_dump()`. - -/// - ## ТелП запрПса + параЌетры путО { #request-body-path-parameters } Вы ЌПжете ПЎМПвреЌеММП ПбъявОть параЌетры путО О телП запрПса. @@ -143,6 +136,7 @@ JSON Schema вашОх ЌПЎелей буЎет частью сгеМерОрП {* ../../docs_src/body/tutorial003_py310.py hl[15:16] *} + ## ТелП запрПса + параЌетры путО + параЌетры запрПса { #request-body-path-query-parameters } Вы также ЌПжете ПЎМПвреЌеММП ПбъявОть параЌетры **тела**, **путО** О **запрПса**. @@ -153,7 +147,7 @@ JSON Schema вашОх ЌПЎелей буЎет частью сгеМерОрП ПараЌетры фуМкцОО буЎут распПзМаМы слеЎующОЌ ПбразПЌ: -* ЕслО параЌетр также ПбъявлеМ в **путО**, ПМ буЎет ОспПльзПваться как параЌетр путО. +* ЕслО параЌетр также ПбъявлеМ в **путО**, ПМ буЎет ОспПльзПваться как path-параЌетр. * ЕслО параЌетр ОЌеет **скалярМый тОп** (МапрОЌер, `int`, `float`, `str`, `bool` О т. п.), ПМ буЎет ОМтерпретОрПваМ как параЌетр **запрПса**. * ЕслО параЌетр ПбъявлеМ как тОп **ЌПЎелО Pydantic**, ПМ буЎет ОМтерпретОрПваМ как **телП** запрПса. @@ -161,7 +155,7 @@ JSON Schema вашОх ЌПЎелей буЎет частью сгеМерОрП FastAPI пПМОЌает, чтП зМачеМОе `q` Ме является ПбязательМыЌ Оз-за зМачеМОя пП уЌПлчаМОю `= None`. -АММПтацОО тОпПв `str | None` (Python 3.10+) ОлО `Union[str, None]` (Python 3.9+) Ме ОспПльзуются FastAPI Ўля ПпреЎелеМОя ПбязательМПстО; ПМ узМает, чтП параЌетр Ме ПбязателеМ, пПтПЌу чтП у МегП есть зМачеМОе пП уЌПлчаМОю `= None`. +АММПтацОО тОпПв `str | None` (Python 3.10+) ОлО `Union` в `Union[str, None]` (Python 3.9+) Ме ОспПльзуются FastAPI Ўля ПпреЎелеМОя ПбязательМПстО; ПМ узМает, чтП параЌетр Ме ПбязателеМ, пПтПЌу чтП у МегП есть зМачеМОе пП уЌПлчаМОю `= None`. НП ЎПбавлеМОе аММПтацОй тОпПв пПзвПлОт вашеЌу реЎактПру кПЎа лучше вас пПЎЎержОвать О ПбМаружОвать ПшОбкО. @@ -169,4 +163,4 @@ FastAPI пПМОЌает, чтП зМачеМОе `q` Ме является Пб ## Без Pydantic { #without-pydantic } -ЕслО вы Ме хПтОте ОспПльзПвать ЌПЎелО Pydantic, вы также ЌПжете ОспПльзПвать параЌетры **Body**. СЌ. разЎел ЎПкуЌеМтацОО [ТелП — НескПлькП параЌетрПв: ЕЎОМОчМые зМачеМОя в теле](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}. +ЕслО вы Ме хПтОте ОспПльзПвать ЌПЎелО Pydantic, вы также ЌПжете ОспПльзПвать параЌетры **Body**. СЌ. разЎел ЎПкуЌеМтацОО [ТелП запрПса - НескПлькП параЌетрПв: ЕЎОМОчМые зМачеМОя в теле](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}. diff --git a/docs/ru/docs/tutorial/extra-models.md b/docs/ru/docs/tutorial/extra-models.md index 2f0ce4e33e..03156f2b4e 100644 --- a/docs/ru/docs/tutorial/extra-models.md +++ b/docs/ru/docs/tutorial/extra-models.md @@ -22,21 +22,13 @@ {* ../../docs_src/extra_models/tutorial001_py310.py hl[7,9,14,20,22,27:28,31:33,38:39] *} -/// info | ИМфПрЌацОя +### ПрП `**user_in.model_dump()` { #about-user-in-model-dump } -В Pydantic v1 ЌетПЎ Мазывался `.dict()`, в Pydantic v2 ПМ пПЌечеМ как устаревшОй (МП всё ещё пПЎЎержОвается) О переОЌеМПваМ в `.model_dump()`. +#### `.model_dump()` Оз Pydantic { #pydantics-model-dump } -В прОЌерах зЎесь ОспПльзуется `.dict()` Ўля сПвЌестОЌПстО с Pydantic v1, МП еслО вы ОспПльзуете Pydantic v2, слеЎует ОспПльзПвать `.model_dump()`. +`user_in` — этП Pydantic-ЌПЎель класса `UserIn`. -/// - -### ПрП `**user_in.dict()` { #about-user-in-dict } - -#### `.dict()` Оз Pydantic { #pydantics-dict } - -`user_in` - этП Pydantic-ЌПЎель класса `UserIn`. - -У Pydantic-ЌПЎелей есть ЌетПЎ `.dict()`, кПтПрый вПзвращает `dict` с ЎаММыЌО ЌПЎелО. +У Pydantic-ЌПЎелей есть ЌетПЎ `.model_dump()`, кПтПрый вПзвращает `dict` с ЎаММыЌО ЌПЎелО. ППэтПЌу, еслО Ќы сПзЎаЎОЌ Pydantic-Пбъект `user_in` такОЌ спПсПбПЌ: @@ -47,10 +39,10 @@ user_in = UserIn(username="john", password="secret", email="john.doe@example.com О затеЌ вызПвеЌ: ```Python -user_dict = user_in.dict() +user_dict = user_in.model_dump() ``` -тП теперь у Мас есть `dict` с ЎаММыЌО ЌПЎелО в переЌеММПй `user_dict` (этП `dict` вЌестП Пбъекта Pydantic-ЌПЎелО). +тП теперь у Мас есть `dict` с ЎаММыЌО в переЌеММПй `user_dict` (этП `dict` вЌестП Пбъекта Pydantic-ЌПЎелО). И еслО Ќы вызПвеЌ: @@ -58,7 +50,7 @@ user_dict = user_in.dict() print(user_dict) ``` -Ќы ЌПжеЌ пПлучОть `dict` с такОЌО ЎаММыЌО: +Ќы пПлучОЌ Python `dict` с: ```Python { @@ -71,7 +63,7 @@ print(user_dict) #### РаспакПвка `dict` { #unpacking-a-dict } -ЕслО Ќы вПзьЌёЌ `dict` МапПЎПбОе `user_dict` О переЎаЎОЌ егП в фуМкцОю (ОлО класс), ОспПльзуя `**user_dict`, Python распакует егП. ОМ переЎаст ключО О зМачеМОя `user_dict` МапряЌую как аргуЌеМты тОпа ключ-зМачеМОе. +ЕслО Ќы вПзьЌёЌ `dict` МапПЎПбОе `user_dict` О переЎаЎОЌ егП в фуМкцОю (ОлО класс), ОспПльзуя `**user_dict`, Python егП "распакует". ОМ переЎаст ключО О зМачеМОя `user_dict` МапряЌую как аргуЌеМты тОпа ключ-зМачеМОе. ППэтПЌу, прПЎПлжая ПпОсаММый выше прОЌер с `user_dict`, МапОсаМОе такПгП кПЎа: @@ -79,7 +71,7 @@ print(user_dict) UserInDB(**user_dict) ``` -БуЎет рабПтать так же, как прОЌерМП такПй кПЎ: +буЎет эквОвалеМтМП: ```Python UserInDB( @@ -90,7 +82,7 @@ UserInDB( ) ``` -ИлО, еслО Ўля бПльшей тПчМПстО Ќы МапряЌую ОспПльзуеЌ `user_dict` с любыЌ пПтеМцОальМыЌ сПЎержОЌыЌ, тП этПт прОЌер буЎет выгляЎеть так: +ИлО, бПлее тПчМП, еслО ОспПльзПвать `user_dict` МапряЌую, с любыЌ сПЎержОЌыЌ, кПтПрПе ПМ ЌПжет ОЌеть в буЎущеЌ: ```Python UserInDB( @@ -101,22 +93,22 @@ UserInDB( ) ``` -#### Pydantic-ЌПЎель Оз сПЎержОЌПгП ЎругПй ЌПЎелО { #a-pydantic-model-from-the-contents-of-another } +#### Pydantic-ЌПЎель Оз сПЎержОЌПгП ЎругПй { #a-pydantic-model-from-the-contents-of-another } -Как в прОЌере выше Ќы пПлучОлО `user_dict` Оз `user_in.dict()`, этПт кПЎ: +Как в прОЌере выше Ќы пПлучОлО `user_dict` Оз `user_in.model_dump()`, этПт кПЎ: ```Python -user_dict = user_in.dict() +user_dict = user_in.model_dump() UserInDB(**user_dict) ``` буЎет равМПзМачеМ такПЌу: ```Python -UserInDB(**user_in.dict()) +UserInDB(**user_in.model_dump()) ``` -...пПтПЌу чтП `user_in.dict()` - этП `dict`, О затеЌ Ќы указываеЌ, чтПбы Python егП "распакПвал", кПгЎа переЎаёЌ егП в `UserInDB` О ставОЌ переЎ МОЌ `**`. +...пПтПЌу чтП `user_in.model_dump()` — этП `dict`, О затеЌ Ќы указываеЌ, чтПбы Python егП "распакПвал", кПгЎа переЎаёЌ егП в `UserInDB` с префОксПЌ `**`. ТакОЌ ПбразПЌ Ќы пПлучаеЌ Pydantic-ЌПЎель Ма ПсМПве ЎаММых Оз ЎругПй Pydantic-ЌПЎелО. @@ -125,10 +117,10 @@ UserInDB(**user_in.dict()) И затеЌ, еслО Ќы ЎПбавОЌ ЎПпПлМОтельМый ОЌеМПваММый аргуЌеМт `hashed_password=hashed_password` как зЎесь: ```Python -UserInDB(**user_in.dict(), hashed_password=hashed_password) +UserInDB(**user_in.model_dump(), hashed_password=hashed_password) ``` -... тП Ќы пПлучОЌ чтП-тП пПЎПбМПе: +...тП в ОтПге пПлучОтся чтП-тП пПЎПбМПе: ```Python UserInDB( @@ -142,13 +134,13 @@ UserInDB( /// warning | ПреЎупрежЎеМОе -ВспПЌПгательМые фуМкцОО `fake_password_hasher` О `fake_save_user` ОспПльзуются тПлькП Ўля ЎеЌПМстрацОО вПзЌПжМПгП пПтПка ЎаММых О, кПМечМП, Ме ПбеспечОвают МастПящую безПпасМПсть. +ВспПЌПгательМые ЎПпПлМОтельМые фуМкцОО `fake_password_hasher` О `fake_save_user` ОспПльзуются тПлькП Ўля ЎеЌПМстрацОО вПзЌПжМПгП пПтПка ЎаММых О, кПМечМП, Ме ПбеспечОвают МастПящую безПпасМПсть. /// ## СПкратОте ЎублОрПваМОе { #reduce-duplication } -СПкращеМОе ЎублОрПваМОя кПЎа - этП ПЎМа Оз главМых ОЎей **FastAPI**. +СПкращеМОе ЎублОрПваМОя кПЎа — этП ПЎМа Оз главМых ОЎей **FastAPI**. ППскПльку ЎублОрПваМОе кПЎа пПвышает рОск пПявлеМОя багПв, прПблеЌ с безПпасМПстью, прПблеЌ ЎесОМхрПМОзацОО кПЎа (кПгЎа вы ПбМПвляете кПЎ в ПЎМПЌ Ќесте, МП Ме ПбМПвляете в ЎругПЌ), О т.ÐŽ. @@ -166,7 +158,7 @@ UserInDB( ## `Union` ОлО `anyOf` { #union-or-anyof } -Вы ЌПжете ПпреЎелОть Птвет как `Union` Оз Ўвух ОлО бПлее тОпПв. ЭтП ПзМачает, чтП Птвет ЎПлжеМ сППтветствПвать ПЎМПЌу Оз МОх. +Вы ЌПжете ПбъявОть HTTP-Птвет как `Union` Оз Ўвух ОлО бПлее тОпПв. ЭтП ПзМачает, чтП HTTP-Птвет ЌПжет быть любыЌ Оз МОх. ОМ буЎет ПпреЎелёМ в OpenAPI как `anyOf`. @@ -174,7 +166,7 @@ UserInDB( /// note | ПрОЌечаМОе -ПрО ПбъявлеМОО `Union`, сМачала указывайте МаОбПлее ЎетальМые тОпы, затеЌ ЌеМее ЎетальМые. В прОЌере МОже бПлее ЎетальМый `PlaneItem` стПОт переЎ `CarItem` в `Union[PlaneItem, CarItem]`. +ПрО ПбъявлеМОО `Union` сМачала указывайте МаОбПлее спецОфОчМый тОп, затеЌ ЌеМее спецОфОчМый. В прОЌере МОже бПлее спецОфОчМый `PlaneItem` стПОт переЎ `CarItem` в `Union[PlaneItem, CarItem]`. /// @@ -192,19 +184,19 @@ UserInDB( some_variable: PlaneItem | CarItem ``` -НП еслО Ќы пПЌещаеЌ егП в `response_model=PlaneItem | CarItem` Ќы пПлучОЌ ПшОбку, пПтПЌу чтП Python пПпытается прПОзвестО **МекПрректМую ПперацОю** ЌежЎу `PlaneItem` О `CarItem` вЌестП тПгП, чтПбы ОМтерпретОрПвать этП как аММПтацОю тОпа. +НП еслО Ќы пПЌестОЌ этП в прОсваОваМОе `response_model=PlaneItem | CarItem`, Ќы пПлучОЌ ПшОбку, пПтПЌу чтП Python пПпытается прПОзвестО **МекПрректМую ПперацОю** ЌежЎу `PlaneItem` О `CarItem` вЌестП тПгП, чтПбы ОМтерпретОрПвать этП как аММПтацОю тОпа. ## СпОсПк ЌПЎелей { #list-of-models } -ТакОЌ же ПбразПЌ вы ЌПжете ПпреЎелять Птветы как спОскО ПбъектПв. +ТакОЌ же ПбразПЌ вы ЌПжете Пбъявлять HTTP-Птветы, вПзвращающОе спОскО ПбъектПв. -Для этПгП ОспПльзуйте `typing.List` Оз стаМЎартМПй бОблОПтекО Python (ОлО прПстП `list` в Python 3.9 О выше): +Для этПгП ОспПльзуйте стаМЎартМый `typing.List` в Python (ОлО прПстП `list` в Python 3.9 О выше): {* ../../docs_src/extra_models/tutorial004_py39.py hl[18] *} ## Ответ с прПОзвПльМыЌ `dict` { #response-with-arbitrary-dict } -Вы также ЌПжете ПпреЎелОть Птвет, ОспПльзуя прПОзвПльМый ПЎМПурПвМевый `dict` О ПпреЎеляя тПлькП тОпы ключей О зМачеМОй без ОспПльзПваМОя Pydantic-ЌПЎелей. +Вы также ЌПжете ПбъявОть HTTP-Птвет, ОспПльзуя ПбычМый прПОзвПльМый `dict`, ПбъявОв тПлькП тОп ключей О зМачеМОй, без ОспПльзПваМОя Pydantic-ЌПЎелО. ЭтП пПлезМП, еслО вы зараМее Ме зМаете кПрректМых МазваМОй пПлей/атрОбутПв (кПтПрые буЎут МужМы прО ОспПльзПваМОО Pydantic-ЌПЎелО). @@ -214,6 +206,6 @@ some_variable: PlaneItem | CarItem ## РезюЌе { #recap } -ИспПльзуйте МескПлькП Pydantic-ЌПЎелей О свПбПЎМП прОЌеМяйте МаслеЎПваМОе Ўля кажЎПй Оз МОх. +ИспПльзуйте МескПлькП Pydantic-ЌПЎелей О свПбПЎМП прОЌеМяйте МаслеЎПваМОе Ўля кажЎПгП случая. -ВаЌ Ме ПбязательМП ОЌеть еЎОМствеММую ЌПЎель ЎаММых Ўля кажЎПй сущМПстО, еслО эта сущМПсть ЎПлжМа ОЌеть вПзЌПжМПсть быть в разМых "сПстПяМОях". Как в случае с "сущМПстью" пПльзПвателя, у кПтПрПгП есть сПстПяМОя с пПляЌО `password`, `password_hash` О без парПля. +ВаЌ Ме ПбязательМП ОЌеть еЎОМствеММую ЌПЎель ЎаММых Ўля кажЎПй сущМПстО, еслО эта сущМПсть ЎПлжМа ОЌеть вПзЌПжМПсть быть в разМых "сПстПяМОях". Как в случае с "сущМПстью" пПльзПвателя, у кПтПрПгП есть сПстПяМОе, включающее `password`, `password_hash` О ПтсутствОе парПля. diff --git a/docs/ru/docs/tutorial/query-params-str-validations.md b/docs/ru/docs/tutorial/query-params-str-validations.md index 3a4ecc37dc..2bc2fb22c5 100644 --- a/docs/ru/docs/tutorial/query-params-str-validations.md +++ b/docs/ru/docs/tutorial/query-params-str-validations.md @@ -8,7 +8,7 @@ Query-параЌетр `q` ОЌеет тОп `str | None`, этП ПзМачает, чтП ПМ ОЌеет тОп `str`, МП также ЌПжет быть `None`. ЗМачеМОе пП уЌПлчаМОю ЎействОтельМП `None`, пПэтПЌу FastAPI буЎет зМать, чтП ПМ Ме ПбязателеМ. -/// note | ТехМОческОе ЎеталО +/// note | ПрОЌечаМОе FastAPI пПйЌёт, чтП зМачеМОе `q` Ме ПбязательМП, Оз‑за зМачеМОя пП уЌПлчаМОю `= None`. @@ -177,7 +177,7 @@ q: str = Query(default="rick") **ЗМачеМОе пП уЌПлчаМОю** у **параЌетра фуМкцОО** — этП **МастПящее зМачеМОе пП уЌПлчаМОю**, чтП бПлее ОМтуОтОвМП Ўля Python. 😌 -Вы ЌПжете **вызвать** эту же фуМкцОю в **ЎругОх Ќестах** без FastAPI, О ПМа буЎет **рабПтать как ПжОЎается**. ЕслО есть **ПбязательМый** параЌетр (без зМачеМОя пП уЌПлчаМОю), ваш **реЎактПр кПЎа** сППбщОт Пб ПшОбке, **Python** тПже пПжалуется, еслО вы запустОте её без переЎачО ПбязательМПгП параЌетра. +Вы ЌПжете **вызвать** эту же фуМкцОю в **ЎругОх Ќестах** без FastAPI, О ПМа буЎет **рабПтать как ПжОЎается**. ЕслО есть **ПбязательМый** параЌетр (без зМачеМОя пП уЌПлчаМОю), ваш **реЎактПр** сППбщОт Пб ПшОбке, **Python** тПже пПжалуется, еслО вы запустОте её без переЎачО ПбязательМПгП параЌетра. ЕслО вы Ме ОспПльзуете `Annotated`, а прОЌеМяете **(устаревшОй) стОль сП зМачеМОеЌ пП уЌПлчаМОю**, тП прО вызПве этПй фуМкцОО без FastAPI в **ЎругОх Ќестах** ваЌ МужМП **пПЌМОть** П тПЌ, чтП МаЎП переЎать аргуЌеМты, чтПбы всё рабПталП кПрректМП, ОМаче зМачеМОя буЎут Ме такОЌО, как вы ПжОЎаете (МапрОЌер, вЌестП `str` буЎет `QueryInfo` ОлО чтП-тП пПЎПбМПе). И МО реЎактПр, МО Python Ме буЎут ругаться прО саЌПЌ вызПве фуМкцОО — ПшОбка прПявОтся лОшь прО ПперацОях вМутрО. @@ -191,7 +191,7 @@ q: str = Query(default="rick") ## РегулярМые выражеМОя { #add-regular-expressions } -Вы ЌПжете ПпреЎелОть регулярМПе выражеМОе `pattern`, кПтПрПЌу ЎПлжеМ сППтветствПвать параЌетр: +Вы ЌПжете ПпреЎелОть регулярМПе выражеМОе `pattern`, кПтПрПЌу ЎПлжеМ сППтветствПвать параЌетр: {* ../../docs_src/query_params_str_validations/tutorial004_an_py310.py hl[11] *} @@ -205,20 +205,6 @@ q: str = Query(default="rick") Теперь вы зМаете, чтП кПгЎа ПМО пПМаЎПбятся, вы сЌПжете ОспПльзПвать Ох в **FastAPI**. -### `regex` Оз Pydantic v1 вЌестП `pattern` { #pydantic-v1-regex-instead-of-pattern } - -ДП Pydantic версОО 2 О ЎП FastAPI 0.100.0 этПт параЌетр Мазывался `regex`, а Ме `pattern`, МП сейчас ПМ устарел. - -Вы всё ещё ЌПжете встретОть такПй кПЎ: - -//// tab | Pydantic v1 - -{* ../../docs_src/query_params_str_validations/tutorial004_regex_an_py310.py hl[11] *} - -//// - -ИЌейте в вОЎу, чтП этП устарелП, О кПЎ слеЎует ПбМПвОть Ма ОспПльзПваМОе МПвПгП параЌетра `pattern`. 🀓 - ## ЗМачеМОя пП уЌПлчаМОю { #default-values } КПМечМП, ЌПжМП ОспПльзПвать О ЎругОе зМачеМОя пП уЌПлчаМОю, Ме тПлькП `None`. @@ -279,7 +265,7 @@ q: Annotated[str | None, Query(min_length=3)] = None http://localhost:8000/items/?q=foo&q=bar ``` -вы пПлучОте ЌМПжествеММые зМачеМОя query-параЌетра `q` (`foo` О `bar`) в вОЎе Python-`list` вМутрО вашей *фуМкцОО ПбрабПткО путО*, в *параЌетре фуМкцОО* `q`. +вы пПлучОте ЌМПжествеММые зМачеМОя *query-параЌетрПв* `q` (`foo` О `bar`) в вОЎе Python-`list` вМутрО вашей *фуМкцОО-ПбрабПтчОка путО*, в *параЌетре фуМкцОО* `q`. ТакОЌ ПбразПЌ, Птвет Ма этПт URL буЎет: @@ -331,7 +317,7 @@ http://localhost:8000/items/ {* ../../docs_src/query_params_str_validations/tutorial013_an_py39.py hl[9] *} -/// note | ТехМОческОе ЎеталО +/// note | ПрОЌечаМОе ИЌейте в вОЎу, чтП в этПЌ случае FastAPI Ме буЎет прПверять сПЎержОЌПе спОска. @@ -345,7 +331,7 @@ http://localhost:8000/items/ Эта ОМфПрЌацОя буЎет включеМа в сгеМерОрПваММую OpenAPI-схеЌу О ОспПльзПваМа ОМтерфейсаЌО ЎПкуЌеМтацОО О вМешМОЌО ОМструЌеМтаЌО. -/// note | ТехМОческОе ЎеталО +/// note | ПрОЌечаМОе ППЌМОте, чтП разМые ОМструЌеМты ЌПгут ОЌеть разМый урПвеМь пПЎЎержкО OpenAPI. @@ -415,7 +401,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems /// -НапрОЌер, эта кастПЌМая прПверка убежЎается, чтП ID элеЌеМта МачОМается с `isbn-` Ўля МПЌера кМОгО ISBN ОлО с `imdb-` Ўля ID URL фОльЌа Ма IMDB: +НапрОЌер, эта кастПЌМая прПверка убежЎается, чтП ID элеЌеМта МачОМается с `isbn-` Ўля МПЌера кМОгО ISBN ОлО с `imdb-` Ўля ID URL фОльЌа Ма IMDB: {* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *} @@ -455,7 +441,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems ЗатеЌ с `random.choice()` ЌПжМП пПлучОть **случайМПе зМачеМОе** Оз спОска — тП есть кПртеж вОЎа `(id, name)`. ЭтП буЎет чтП‑тП врПЎе `("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy")`. -ППсле этПгП Ќы **распакПвываеЌ** этО Ўва зМачеМОя кПртежа в переЌеММые `id` О `name`. +ППсле этПгП Ќы **прОсваОваеЌ этО Ўва зМачеМОя** кПртежа переЌеММыЌ `id` О `name`. Так чтП, еслО пПльзПватель Ме переЎал ID элеЌеМта, ПМ всё равМП пПлучОт случайМую рекПЌеМЎацОю. diff --git a/docs/ru/docs/tutorial/response-model.md b/docs/ru/docs/tutorial/response-model.md index 07308c1db2..22a811cd57 100644 --- a/docs/ru/docs/tutorial/response-model.md +++ b/docs/ru/docs/tutorial/response-model.md @@ -6,11 +6,11 @@ {* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *} -FastAPI буЎет ОспПльзПвать этПт тОп Птвета Ўля: +FastAPI буЎет ОспПльзПвать этПт вПзвращаеЌый тОп, чтПбы: -* **ВалОЎацОО** вПзвращаеЌых ЎаММых. - * ЕслО ЎаММые МевалОЎМы (МапрОЌер, Птсутствует пПле), этП ПзМачает, чтП кПЎ *вашегП* прОлПжеМОя рабПтает МекПрректМП О вПзвращает Ме тП, чтП ЎПлжеМ. В такПЌ случае буЎет вПзвращеМа ПшОбка сервера вЌестП МеправОльМых ЎаММых. Так вы О вашО клОеМты ЌПжете быть увереМы, чтП пПлучОте ПжОЎаеЌые ЎаММые О ПжОЎаеЌую структуру. -* ДПбавлеМОя **JSON Schema** Ўля Птвета в OpenAPI *ПперацОО путО*. +* **ВалОЎОрПвать** вПзвращаеЌые ЎаММые. + * ЕслО ЎаММые МевалОЎМы (МапрОЌер, Птсутствует пПле), этП ПзМачает, чтП кПЎ *вашегП* прОлПжеМОя рабПтает МекПрректМП О вПзвращает Ме тП, чтП ЎПлжеМ. В такПЌ случае буЎет вПзвращеМа ПшОбка сервера вЌестП МеправОльМых ЎаММых. Так вы О вашО клОеМты ЌПжете быть увереМы, чтП пПлучОте ПжОЎаеЌые ЎаММые О ПжОЎаеЌую структуру ЎаММых. +* ДПбавОть **JSON Schema** Ўля Птвета в OpenAPI *ПперацОО путО*. * ЭтП буЎет ОспПльзПваМП **автПЌатОческПй ЎПкуЌеМтацОей**. * ЭтП также буЎет ОспПльзПваМП ОМструЌеМтаЌО автПЌатОческПй геМерацОО клОеМтскПгП кПЎа. @@ -23,7 +23,7 @@ FastAPI буЎет ОспПльзПвать этПт тОп Птвета Ўля: Бывают случаО, кПгЎа ваЌ МужМП ОлО хПчется вПзвращать ЎаММые, кПтПрые Ме в тПчМПстО сППтветствуют ПбъявлеММПЌу тОпу. -НапрОЌер, вы ЌПжете хПтеть **вПзвращать слПварь (dict)** ОлО Пбъект Оз базы ЎаММых, МП **ПбъявОть егП как Pydantic-ЌПЎель**. ТПгЎа Pydantic-ЌПЎель выпПлМОт ЎПкуЌеМтОрПваМОе ЎаММых, валОЎацОю О т.п. Ўля Пбъекта, кПтПрый вы верМулО (МапрОЌер, слПваря ОлО Пбъекта Оз базы ЎаММых). +НапрОЌер, вы ЌПжете хПтеть **вПзвращать слПварь** ОлО Пбъект Оз базы ЎаММых, МП **ПбъявОть егП как Pydantic-ЌПЎель**. ТПгЎа Pydantic-ЌПЎель выпПлМОт ЎПкуЌеМтОрПваМОе ЎаММых, валОЎацОю О т.п. Ўля Пбъекта, кПтПрый вы верМулО (МапрОЌер, слПваря ОлО Пбъекта Оз базы ЎаММых). ЕслО вы ЎПбавОте аММПтацОю вПзвращаеЌПгП тОпа, ОМструЌеМты О реЎактПры кПЎа МачМут жалПваться (О буЎут правы), чтП фуМкцОя вПзвращает тОп (МапрОЌер, dict), ПтлОчМый Пт ПбъявлеММПгП (МапрОЌер, Pydantic-ЌПЎель). @@ -47,13 +47,13 @@ FastAPI буЎет ОспПльзПвать этПт тОп Птвета Ўля: `response_model` прОМОЌает тПт же тОп, чтП вы бы ПбъявОлО Ўля пПля Pydantic-ЌПЎелО, тП есть этП ЌПжет быть ПЎМа Pydantic-ЌПЎель, а ЌПжет быть, МапрОЌер, `list` Pydantic-ЌПЎелей, как `List[Item]`. -FastAPI буЎет ОспПльзПвать `response_model` Ўля ЎПкуЌеМтацОО, валОЎацОО О т. п., а также Ўля **кПМвертацОО О фОльтрацОО выхПЎМых ЎаММых** к ПбъявлеММПЌу тОпу. +FastAPI буЎет ОспПльзПвать этПт `response_model` Ўля ЎПкуЌеМтОрПваМОя, валОЎацОО ЎаММых О т.п., а также Ўля **кПМвертацОО О фОльтрацОО выхПЎМых ЎаММых** к ПбъявлеММПЌу тОпу. /// tip | СПвет -ЕслО у вас в реЎактПре кПЎа, mypy О т. п. включеМы стрПгОе прПверкО тОпПв, вы ЌПжете ПбъявОть вПзвращаеЌый тОп фуМкцОО как `Any`. +ЕслО у вас в реЎактПре кПЎа, mypy О т.п. включеМы стрПгОе прПверкО тОпПв, вы ЌПжете ПбъявОть вПзвращаеЌый тОп фуМкцОО как `Any`. -Так вы сППбщОте реЎактПру, чтП МаЌереММП вПзвращаете чтП угПЎМП. НП FastAPI всё равМП выпПлМОт ЎПкуЌеМтацОю ЎаММых, валОЎацОю, фОльтрацОю О т.ÐŽ. с пПЌПщью `response_model`. +Так вы сППбщОте реЎактПру, чтП МаЌереММП вПзвращаете чтП угПЎМП. НП FastAPI всё равМП выпПлМОт ЎПкуЌеМтОрПваМОе, валОЎацОю, фОльтрацОю ЎаММых О т.ÐŽ. с пПЌПщью `response_model`. /// @@ -61,7 +61,7 @@ FastAPI буЎет ОспПльзПвать `response_model` Ўля ЎПкуЌе ЕслО вы ПбъявОте О вПзвращаеЌый тОп, О `response_model`, прОПрОтет буЎет у `response_model`, ОЌеММП егП ОспПльзует FastAPI. -Так вы ЌПжете ЎПбавОть кПрректМые аММПтацОО тОпПв к свПОЌ фуМкцОяЌ, Ўаже еслО фактОческО вПзвращаете тОп, ПтлОчМый Пт ЌПЎелО Птвета, чтПбы ОЌО пПльзПвалОсь реЎактПр О ОМструЌеМты врПЎе mypy. И прО этПЌ FastAPI прПЎПлжОт выпПлМять валОЎацОю ЎаММых, ЎПкуЌеМтацОю О т.ÐŽ. с ОспПльзПваМОеЌ `response_model`. +Так вы ЌПжете ЎПбавОть кПрректМые аММПтацОО тОпПв к свПОЌ фуМкцОяЌ, Ўаже еслО фактОческО вПзвращаете тОп, ПтлОчМый Пт ЌПЎелО Птвета, чтПбы ОЌО пПльзПвалОсь реЎактПр кПЎа О ОМструЌеМты врПЎе mypy. И прО этПЌ FastAPI прПЎПлжОт выпПлМять валОЎацОю ЎаММых, ЎПкуЌеМтацОю О т.ÐŽ. с ОспПльзПваМОеЌ `response_model`. Вы также ЌПжете указать `response_model=None`, чтПбы ПтключОть сПзЎаМОе ЌПЎелО Птвета Ўля ЎаММПй *ПперацОО путО*. ЭтП ЌПжет пПМаЎПбОться, еслО вы ЎПбавляете аММПтацОО тОпПв Ўля вещей, Ме являющОхся валОЎМыЌО пПляЌО Pydantic. ПрОЌер вы увОЎОте МОже. @@ -75,7 +75,7 @@ FastAPI буЎет ОспПльзПвать `response_model` Ўля ЎПкуЌе ЧтПбы ОспПльзПвать `EmailStr`, сМачала устаМПвОте `email-validator`. -СПзЎайте [вОртуальМПе ПкружеМОе](../virtual-environments.md){.internal-link target=_blank}, актОвОруйте егП О затеЌ устаМПвОте пакет, МапрОЌер: +УбеЎОтесь, чтП вы сПзЎалО [вОртуальМПе ПкружеМОе](../virtual-environments.md){.internal-link target=_blank}, актОвОрПвалО егП, а затеЌ устаМПвОте пакет, МапрОЌер: ```console $ pip install email-validator @@ -105,7 +105,7 @@ $ pip install "pydantic[email]" /// -## ДПбавОть ЌПЎель Ўля Птвета { #add-an-output-model } +## ДПбавОть выхПЎМую ЌПЎель { #add-an-output-model } ВЌестП этПгП Ќы ЌПжеЌ сПзЎать вхПЎМую ЌПЎель с парПлеЌ в ПткрытПЌ вОЎе О выхПЎМую ЌПЎель без МегП: @@ -123,7 +123,7 @@ $ pip install "pydantic[email]" ### `response_model` ОлО вПзвращаеЌый тОп { #response-model-or-return-type } -В этПЌ случае, пПскПльку Ўве ЌПЎелО разлОчаются, еслО бы Ќы аММПтОрПвалО вПзвращаеЌый тОп фуМкцОО как `UserOut`, реЎактПр О ОМструЌеМты пПжалПвалОсь бы, чтП Ќы вПзвращаеЌ МеверМый тОп, так как этП разМые классы. +В этПЌ случае, пПскПльку Ўве ЌПЎелО разлОчаются, еслО бы Ќы аММПтОрПвалО вПзвращаеЌый тОп фуМкцОО как `UserOut`, реЎактПр кПЎа О ОМструЌеМты пПжалПвалОсь бы, чтП Ќы вПзвращаеЌ МеверМый тОп, так как этП разМые классы. ППэтПЌу в этПЌ прОЌере Ќы ЎПлжМы ПбъявОть тОп Птвета в параЌетре `response_model`. @@ -135,33 +135,33 @@ $ pip install "pydantic[email]" Мы хПтОЌ, чтПбы FastAPI прПЎПлжал **фОльтрПвать** ЎаММые с пПЌПщью ЌПЎелО Птвета. Так чтП, Ўаже еслО фуМкцОя вПзвращает бПльше ЎаММых, в Птвет буЎут включеМы тПлькП пПля, ПбъявлеММые в ЌПЎелО Птвета. -В преЎыЎущеЌ прОЌере, пПскПльку классы былО разМыЌО, МаЌ прОшлПсь ОспПльзПвать параЌетр `response_model`. НП этП также ПзМачает, чтП Ќы теряеЌ пПЎЎержку Пт реЎактПра О ОМструЌеМтПв, прПверяющОх вПзвращаеЌый тОп фуМкцОО. +В преЎыЎущеЌ прОЌере, пПскПльку классы былО разМыЌО, МаЌ прОшлПсь ОспПльзПвать параЌетр `response_model`. НП этП также ПзМачает, чтП Ќы теряеЌ пПЎЎержку Пт реЎактПра кПЎа О ОМструЌеМтПв, прПверяющОх вПзвращаеЌый тОп фуМкцОО. ОЎМакП в бПльшОМстве такОх случаев МаЌ МужМП лОшь **ПтфОльтрПвать/убрать** МекПтПрые ЎаММые, как в этПЌ прОЌере. -И в этОх случаях Ќы ЌПжеЌ ОспПльзПвать классы О МаслеЎПваМОе, чтПбы вПспПльзПваться **аММПтацОяЌО тОпПв** фуМкцОй Ўля лучшей пПЎЎержкО в реЎактПре О ОМструЌеМтах О прО этПЌ пПлучОть **фОльтрацОю ЎаММых** Пт FastAPI. +И в этОх случаях Ќы ЌПжеЌ ОспПльзПвать классы О МаслеЎПваМОе, чтПбы вПспПльзПваться **аММПтацОяЌО тОпПв** фуМкцОй Ўля лучшей пПЎЎержкО в реЎактПре кПЎа О ОМструЌеМтах О прО этПЌ пПлучОть **фОльтрацОю ЎаММых** Пт FastAPI. {* ../../docs_src/response_model/tutorial003_01_py310.py hl[7:10,13:14,18] *} -Так Ќы пПлучаеЌ пПЎЎержку ОМструЌеМтПв (реЎактПры, mypy) — кПЎ кПрректеМ с тПчкО зреМОя тОпПв — О ПЎМПвреЌеММП пПлучаеЌ фОльтрацОю ЎаММых Пт FastAPI. +Так Ќы пПлучаеЌ пПЎЎержку ОМструЌеМтПв — реЎактПрПв кПЎа О mypy, так как этПт кПЎ кПрректеМ с тПчкО зреМОя тОпПв — О ПЎМПвреЌеММП пПлучаеЌ фОльтрацОю ЎаММых Пт FastAPI. Как этП рабПтает? Давайте разберёЌся. 🀓 ### АММПтацОО тОпПв О ОМструЌеМты { #type-annotations-and-tooling } -СМачала пПсЌПтрОЌ, как этП увОЎят реЎактПры, mypy О ЎругОе ОМструЌеМты. +СМачала пПсЌПтрОЌ, как этП увОЎят реЎактПр кПЎа, mypy О ЎругОе ОМструЌеМты. -`BaseUser` сПЎержОт базПвые пПля. ЗатеЌ `UserIn` МаслеЎуется Пт `BaseUser` О ЎПбавляет пПле `password`, тП есть ПМ включает все пПля ПбеОх ЌПЎелей. +`BaseUser` сПЎержОт базПвые пПля. ЗатеЌ `UserIn` МаслеЎуется Пт `BaseUser` О ЎПбавляет пПле `password`, тП есть ПМ буЎет включать все пПля ПбеОх ЌПЎелей. Мы аММПтОруеЌ вПзвращаеЌый тОп фуМкцОО как `BaseUser`, МП фактОческО вПзвращаеЌ экзеЌпляр `UserIn`. -РеЎактПр, mypy О ЎругОе ОМструЌеМты Ме буЎут вПзражать, пПтПЌу чтП с тПчкО зреМОя тОпПв `UserIn` — пПЎкласс `BaseUser`, чтП ПзМачает, чтП этП *валОЎМый* тОп везЎе, гЎе ПжОЎается чтП-тП, являющееся `BaseUser`. +РеЎактПр кПЎа, mypy О ЎругОе ОМструЌеМты Ме буЎут вПзражать, пПтПЌу чтП с тПчкО зреМОя тОпПв `UserIn` — пПЎкласс `BaseUser`, чтП ПзМачает, чтП этП *валОЎМый* тОп везЎе, гЎе ПжОЎается чтП-тП, являющееся `BaseUser`. ### ЀОльтрацОя ЎаММых FastAPI { #fastapi-data-filtering } -Теперь, Ўля FastAPI: ПМ увОЎОт вПзвращаеЌый тОп О убеЎОтся, чтП тП, чтП вы вПзвращаете, включает **тПлькП** пПля, ПбъявлеММые в этПЌ тОпе. +Теперь Ўля FastAPI: ПМ увОЎОт вПзвращаеЌый тОп О убеЎОтся, чтП тП, чтП вы вПзвращаете, включает **тПлькП** пПля, ПбъявлеММые в этПЌ тОпе. -FastAPI Ўелает МескПлькП вещей вМутрО вЌесте с Pydantic, чтПбы гараМтОрПвать, чтП те же правОла МаслеЎПваМОя классПв Ме ОспПльзуются Ўля фОльтрацОО вПзвращаеЌых ЎаММых, ОМаче вы ЌПглО бы верМуть гПразЎП бПльше ЎаММых, чеЌ ПжОЎалО. +FastAPI Ўелает МескПлькП вещей вМутрО вЌесте с Pydantic, чтПбы гараМтОрПвать, чтП те же правОла МаслеЎПваМОя классПв Ме ОспПльзуются Ўля фОльтрацОО вПзвращаеЌых ЎаММых, ОМаче вы ЌПглО бы в ОтПге верМуть МаЌМПгП бПльше ЎаММых, чеЌ ПжОЎалО. ТакОЌ ПбразПЌ вы пПлучаете лучшее Оз ПбПОх ЌОрПв: аММПтацОО тОпПв с **пПЎЎержкПй ОМструЌеМтПв** О **фОльтрацОю ЎаММых**. @@ -171,17 +171,17 @@ FastAPI Ўелает МескПлькП вещей вМутрО вЌесте с -И Пбе ЌПЎелО ОспПльзуются в ОМтерактОвМПй ЎПкуЌеМтацОО API: +И Пбе ЌПЎелО буЎут ОспПльзПваться в ОМтерактОвМПй ЎПкуЌеМтацОО API: ## ДругОе аММПтацОО вПзвращаеЌых тОпПв { #other-return-type-annotations } -Бывают случаО, кПгЎа вы вПзвращаете чтП-тП, чтП Ме является валОЎМыЌ пПлеЌ Pydantic, О аММПтОруете этП в фуМкцОО тПлькП раЎО пПЎЎержкО ОМструЌеМтПв (реЎактПр, mypy О т. ÐŽ.). +Бывают случаО, кПгЎа вы вПзвращаете чтП-тП, чтП Ме является валОЎМыЌ пПлеЌ Pydantic, О аММПтОруете этП в фуМкцОО тПлькП раЎО пПЎЎержкО ОМструЌеМтПв (реЎактПр кПЎа, mypy О т.ÐŽ.). ### ВПзврат Response МапряЌую { #return-a-response-directly } -СаЌый распрПстраМёММый случай — [вПзвращать Response МапряЌую, как ПпОсаМП Ўалее в разЎелах Ўля прПЎвОМутых](../advanced/response-directly.md){.internal-link target=_blank}. +СаЌый распрПстраМёММый случай — [вПзвращать Response МапряЌую, как ПпОсаМП Ўалее в разЎелах ЎПкуЌеМтацОО Ўля прПЎвОМутых](../advanced/response-directly.md){.internal-link target=_blank}. {* ../../docs_src/response_model/tutorial003_02_py39.py hl[8,10:11] *} @@ -195,7 +195,7 @@ FastAPI Ўелает МескПлькП вещей вМутрО вЌесте с {* ../../docs_src/response_model/tutorial003_03_py39.py hl[8:9] *} -ЭтП тПже срабПтает, так как `RedirectResponse` — пПЎкласс `Response`, О FastAPI автПЌатОческО ПбрабПтает этПт случай. +ЭтП тПже срабПтает, так как `RedirectResponse` — пПЎкласс `Response`, О FastAPI автПЌатОческО ПбрабПтает этПт прПстПй случай. ### НекПрректМые аММПтацОО вПзвращаеЌых тОпПв { #invalid-return-type-annotations } @@ -209,15 +209,15 @@ FastAPI Ўелает МескПлькП вещей вМутрО вЌесте с ### ОтключОть ЌПЎель Птвета { #disable-response-model } -ПрПЎПлжая прОЌер выше, вы ЌПжете Ме хПтеть ОспПльзПвать стаМЎартМую валОЎацОю ЎаММых, ЎПкуЌеМтацОю, фОльтрацОю О т.ÐŽ., выпПлМяеЌые FastAPI. +ПрПЎПлжая прОЌер выше, вы ЌПжете Ме хПтеть ОспПльзПвать стаМЎартМые валОЎацОю ЎаММых, ЎПкуЌеМтОрПваМОе, фОльтрацОю О т.п., выпПлМяеЌые FastAPI. -НП прО этПЌ вы ЌПжете хПтеть сПхраМОть аММПтацОю вПзвращаеЌПгП тОпа в фуМкцОО, чтПбы пПльзПваться пПЎЎержкПй ОМструЌеМтПв (реЎактПры, прПверкО тОпПв врПЎе mypy). +НП прО этПЌ вы ЌПжете хПтеть сПхраМОть аММПтацОю вПзвращаеЌПгП тОпа в фуМкцОО, чтПбы пПльзПваться пПЎЎержкПй ОМструЌеМтПв врПЎе реЎактПрПв кПЎа О ОМструЌеМтПв прПверкО тОпПв (МапрОЌер, mypy). В этПЌ случае вы ЌПжете ПтключОть геМерацОю ЌПЎелО Птвета, устаМПвОв `response_model=None`: {* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *} -Так FastAPI прПпустОт геМерацОю ЌПЎелО Птвета, О вы сЌПжете ОспПльзПвать любые аММПтацОО вПзвращаеЌых тОпПв, Ме влОяя Ма ваше прОлПжеМОе FastAPI. 🀓 +Так FastAPI прПпустОт геМерацОю ЌПЎелО Птвета, О вы сЌПжете ОспПльзПвать любые аММПтацОО вПзвращаеЌых тОпПв, кПтПрые ваЌ МужМы, без влОяМОя Ма ваше прОлПжеМОе FastAPI. 🀓 ## ПараЌетры кПЎОрПваМОя ЌПЎелО Птвета { #response-model-encoding-parameters } @@ -252,20 +252,6 @@ FastAPI Ўелает МескПлькП вещей вМутрО вЌесте с /// info | ИМфПрЌацОя -В Pydantic v1 ЌетПЎ Мазывался `.dict()`, в Pydantic v2 ПМ был пПЌечеМ как устаревшОй (МП всё ещё пПЎЎержОвается) О переОЌеМПваМ в `.model_dump()`. - -ПрОЌеры зЎесь ОспПльзуют `.dict()` Ўля сПвЌестОЌПстО с Pydantic v1, МП еслО вы ОспПльзуете Pydantic v2, прОЌеМяйте `.model_dump()`. - -/// - -/// info | ИМфПрЌацОя - -FastAPI ОспПльзует ЌетПЎ `.dict()` у Pydantic-ЌПЎелей с параЌетрПЌ `exclude_unset`, чтПбы ЎПбОться такПгП пПвеЎеМОя. - -/// - -/// info | ИМфПрЌацОя - Вы также ЌПжете ОспПльзПвать: * `response_model_exclude_defaults=True` @@ -312,7 +298,7 @@ FastAPI ЎПстатПчМП уЌеМ (Ма саЌПЌ Ўеле, этП Pydantic ОбратОте вМОЌаМОе, чтП зМачеМОя пП уЌПлчаМОю ЌПгут быть любыЌО, Ме тПлькП `None`. -ЭтП ЌПжет быть спОсПк (`[]`), чОслП с плавающей тПчкПй `10.5` О т. ÐŽ. +ЭтП ЌПжет быть спОсПк (`[]`), чОслП с плавающей тПчкПй `10.5` О т.ÐŽ. /// @@ -346,7 +332,7 @@ FastAPI ЎПстатПчМП уЌеМ (Ма саЌПЌ Ўеле, этП Pydantic #### ИспПльзПваМОе `list` вЌестП `set` { #using-lists-instead-of-sets } -ЕслО вы забылО ОспПльзПвать `set` О прОЌеМОлО `list` ОлО `tuple`, FastAPI всё равМП преПбразует этП в `set`, О всё буЎет рабПтать кПрректМП: +ЕслО вы забылО ОспПльзПвать `set` О прОЌеМОлО `list` ОлО `tuple` вЌестП МегП, FastAPI всё равМП преПбразует этП в `set`, О всё буЎет рабПтать кПрректМП: {* ../../docs_src/response_model/tutorial006_py310.py hl[29,35] *} diff --git a/docs/ru/docs/tutorial/schema-extra-example.md b/docs/ru/docs/tutorial/schema-extra-example.md index 5891f0d12d..e4a97c8801 100644 --- a/docs/ru/docs/tutorial/schema-extra-example.md +++ b/docs/ru/docs/tutorial/schema-extra-example.md @@ -8,36 +8,14 @@ Вы ЌПжете ПбъявОть `examples` Ўля ЌПЎелО Pydantic, кПтПрые буЎут ЎПбавлеМы в сгеМерОрПваММую JSON Schema. -//// tab | Pydantic v2 - {* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *} -//// - -//// tab | Pydantic v1 - -{* ../../docs_src/schema_extra_example/tutorial001_pv1_py310.py hl[13:23] *} - -//// - Эта ЎПпПлМОтельМая ОМфПрЌацОя буЎет ЎПбавлеМа как есть в выхПЎМую **JSON Schema** этПй ЌПЎелО О буЎет ОспПльзПваться в ЎПкуЌеМтацОО API. -//// tab | Pydantic v2 - -В Pydantic версОО 2 вы буЎете ОспПльзПвать атрОбут `model_config`, кПтПрый прОМОЌает `dict`, как ПпОсаМП в ДПкуЌеМтацОО Pydantic: КПМфОгурацОя. +Вы ЌПжете ОспПльзПвать атрОбут `model_config`, кПтПрый прОМОЌает `dict`, как ПпОсаМП в ДПкуЌеМтацОО Pydantic: КПМфОгурацОя. Вы ЌПжете заЎать `"json_schema_extra"` с `dict`, сПЎержащОЌ любые ЎПпПлМОтельМые ЎаММые, кПтПрые вы хПтОте вОЎеть в сгеМерОрПваММПй JSON Schema, включая `examples`. -//// - -//// tab | Pydantic v1 - -В Pydantic версОО 1 вы буЎете ОспПльзПвать вМутреММОй класс `Config` О `schema_extra`, как ПпОсаМП в ДПкуЌеМтацОО Pydantic: НастрПйка схеЌы. - -Вы ЌПжете заЎать `schema_extra` сП `dict`, сПЎержащОЌ любые ЎПпПлМОтельМые ЎаММые, кПтПрые вы хПтОте вОЎеть в сгеМерОрПваММПй JSON Schema, включая `examples`. - -//// - /// tip | ППЎсказка Вы ЌПжете ОспПльзПвать тПт же прОёЌ, чтПбы расшОрОть JSON Schema О ЎПбавОть свПю сПбствеММую ЎПпПлМОтельМую ОМфПрЌацОю. @@ -124,7 +102,7 @@ OpenAPI 3.1.0 (ОспПльзуется МачОМая с FastAPI 0.99.0) ЎПб КлючО `dict` ОЎеМтОфОцОруют кажЎый прОЌер, а кажЎПе зМачеМОе — этП ещё ПЎОМ `dict`. -КажЎый кПМкретМый прОЌер‑`dict` в `examples` ЌПжет сПЎержать: +КажЎый кПМкретМый прОЌер `dict` в `examples` ЌПжет сПЎержать: * `summary`: КраткПе ПпОсаМОе прОЌера. * `description`: ППЎрПбМПе ПпОсаМОе, кПтПрПе ЌПжет сПЎержать текст в Markdown. @@ -135,7 +113,7 @@ OpenAPI 3.1.0 (ОспПльзуется МачОМая с FastAPI 0.99.0) ЎПб {* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *} -### OpenAPI-прОЌеры в UI ЎПкуЌеМтацОО { #openapi-examples-in-the-docs-ui } +### OpenAPI-прОЌеры в UI ЎПкуЌеМтацОО { #openapi-examples-in-the-docs-ui } С `openapi_examples`, ЎПбавлеММыЌ в `Body()`, страМОца `/docs` буЎет выгляЎеть так: @@ -213,7 +191,7 @@ OpenAPI также ЎПбавОла пПля `example` О `examples` в Ўруг ### Swagger UI О спецОфОчМые Ўля OpenAPI `examples` { #swagger-ui-and-openapi-specific-examples } -РаМьше, пПскПльку Swagger UI Ме пПЎЎержОвал МескПлькП прОЌерПв JSON Schema (пП сПстПяМОю Ма 2023-08-26), у пПльзПвателей Ме былП спПсПба пПказать МескПлькП прОЌерПв в ЎПкуЌеМтацОО. +Теперь, пПскПльку Swagger UI Ме пПЎЎержОвал МескПлькП прОЌерПв JSON Schema (пП сПстПяМОю Ма 2023-08-26), у пПльзПвателей Ме былП спПсПба пПказать МескПлькП прОЌерПв в ЎПкуЌеМтацОО. ЧтПбы решОть этП, FastAPI `0.103.0` **ЎПбавОл пПЎЎержку** ПбъявлеМОя тПгП же старПгП, **спецОфОчМПгП Ўля OpenAPI**, пПля `examples` с МПвыЌ параЌетрПЌ `openapi_examples`. 🀓 From e0abd210f64110de77c09909245e9652a4fec78e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 20 Jan 2026 23:03:31 +0000 Subject: [PATCH 028/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 33926e3afc..f4572ffe8b 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -18,6 +18,7 @@ hide: ### Translations +* 🌐 Update translations for ru (update-outdated). PR [#14693](https://github.com/fastapi/fastapi/pull/14693) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update translations for pt (update-outdated). PR [#14724](https://github.com/fastapi/fastapi/pull/14724) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update Korean LLM prompt. PR [#14740](https://github.com/fastapi/fastapi/pull/14740) by [@hard-coders](https://github.com/hard-coders). * 🌐 Improve LLM prompt for Turkish translations. PR [#14728](https://github.com/fastapi/fastapi/pull/14728) by [@Kadermiyanyedi](https://github.com/Kadermiyanyedi). From b9b75ba5f1a51c2edcae3df4dffa2b0f1a2353d0 Mon Sep 17 00:00:00 2001 From: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> Date: Thu, 22 Jan 2026 10:07:05 +0300 Subject: [PATCH 029/108] =?UTF-8?q?=F0=9F=8C=90=20Update=20LLM=20prompt=20?= =?UTF-8?q?for=20Russian=20translations=20(#14733)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add some specific translations --- docs/ru/llm-prompt.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/ru/llm-prompt.md b/docs/ru/llm-prompt.md index 6a437bdd14..9131a5d3b4 100644 --- a/docs/ru/llm-prompt.md +++ b/docs/ru/llm-prompt.md @@ -90,5 +90,12 @@ For the following technical terms, use these specific translations to ensure con * serve (meaning providing access to something): «ПтЎавать» (or `преЎПставлять ЎПступ к`) * recap (noun): резюЌе * utility function: вспПЌПгательМая фуМкцОя +* fast to code: пПзвПляет быстрП пОсать кПЎ +* Tutorial - User Guide: УчебМОк - РукПвПЎствП пПльзПвателя +* submodule: пПЎЌПЎуль +* subpackage: пПЎпакет +* router: рПутер +* building, deploying, accessing (when describing features of FastAPI Cloud): сПзЎаМОe Пбраза, развертываМОе О ЎПступ +* type checker tool: ОМструЌеМт прПверкО тОпПв Do not add whitespace in `т.ÐŽ.`, `т.п.`. From 6e47171e9cb79a4616014cb9fce5b88912a820ee Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 22 Jan 2026 07:07:28 +0000 Subject: [PATCH 030/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index f4572ffe8b..62b611f8a9 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -18,6 +18,7 @@ hide: ### Translations +* 🌐 Update LLM prompt for Russian translations. PR [#14733](https://github.com/fastapi/fastapi/pull/14733) by [@YuriiMotov](https://github.com/YuriiMotov). * 🌐 Update translations for ru (update-outdated). PR [#14693](https://github.com/fastapi/fastapi/pull/14693) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update translations for pt (update-outdated). PR [#14724](https://github.com/fastapi/fastapi/pull/14724) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update Korean LLM prompt. PR [#14740](https://github.com/fastapi/fastapi/pull/14740) by [@hard-coders](https://github.com/hard-coders). From 509afeb475e602bd11f2ffa165ccd0ed3d10a19f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Thu, 22 Jan 2026 01:27:31 -0800 Subject: [PATCH 031/108] =?UTF-8?q?=F0=9F=8C=90=20Update=20translations=20?= =?UTF-8?q?for=20de=20(update-outdated)=20(#14690)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 🌐 Update translations for de (update-outdated) * Apply suggestions from code review --------- Co-authored-by: github-actions[bot] Co-authored-by: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> --- docs/de/docs/_llm-test.md | 2 +- docs/de/docs/tutorial/bigger-applications.md | 26 ++++++++++---------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/de/docs/_llm-test.md b/docs/de/docs/_llm-test.md index bc7ce363c7..0b95fe3a8d 100644 --- a/docs/de/docs/_llm-test.md +++ b/docs/de/docs/_llm-test.md @@ -189,7 +189,7 @@ Siehe Abschnitt `### Links` im allgemeinen Prompt in `scripts/translate.py`. //// -## HTML „abbr“-Elemente { #html-abbr-elements } +## HTML-„abbr“-Elemente { #html-abbr-elements } //// tab | Test diff --git a/docs/de/docs/tutorial/bigger-applications.md b/docs/de/docs/tutorial/bigger-applications.md index 963baf44d5..d478d77c27 100644 --- a/docs/de/docs/tutorial/bigger-applications.md +++ b/docs/de/docs/tutorial/bigger-applications.md @@ -56,19 +56,19 @@ from app.routers import items Die gleiche Dateistruktur mit Kommentaren: -``` +```bash . -├── app # „app“ ist ein Python-Package -│   ├── __init__.py # diese Datei macht „app“ zu einem „Python-Package“ -│   ├── main.py # „main“-Modul, z. B. import app.main -│   ├── dependencies.py # „dependencies“-Modul, z. B. import app.dependencies -│   └── routers # „routers“ ist ein „Python-Subpackage“ -│   │ ├── __init__.py # macht „routers“ zu einem „Python-Subpackage“ -│   │ ├── items.py # „items“-Submodul, z. B. import app.routers.items -│   │ └── users.py # „users“-Submodul, z. B. import app.routers.users -│   └── internal # „internal“ ist ein „Python-Subpackage“ -│   ├── __init__.py # macht „internal“ zu einem „Python-Subpackage“ -│   └── admin.py # „admin“-Submodul, z. B. import app.internal.admin +├── app # "app" ist ein Python-Package +│   ├── __init__.py # diese Datei macht "app" zu einem "Python-Package" +│   ├── main.py # "main"-Modul, z. B. import app.main +│   ├── dependencies.py # "dependencies"-Modul, z. B. import app.dependencies +│   └── routers # "routers" ist ein "Python-Subpackage" +│   │ ├── __init__.py # macht "routers" zu einem "Python-Subpackage" +│   │ ├── items.py # "items"-Submodul, z. B. import app.routers.items +│   │ └── users.py # "users"-Submodul, z. B. import app.routers.users +│   └── internal # "internal" ist ein "Python-Subpackage" +│   ├── __init__.py # macht "internal" zu einem "Python-Subpackage" +│   └── admin.py # "admin"-Submodul, z. B. import app.internal.admin ``` ## `APIRouter` { #apirouter } @@ -479,7 +479,7 @@ $ fastapi dev app/main.py -und öffnen Sie die Dokumentation unter http://127.0.0.1:8000/docs. +Und öffnen Sie die Dokumentation unter http://127.0.0.1:8000/docs. Sie sehen die automatische API-Dokumentation, einschließlich der Pfade aller Submodule, mit den richtigen Pfaden (und PrÀfixen) und den richtigen Tags: From f1a39cab12c615ba50b21f32159e523baa560424 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 22 Jan 2026 09:27:58 +0000 Subject: [PATCH 032/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 62b611f8a9..1cd2b887f6 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -18,6 +18,7 @@ hide: ### Translations +* 🌐 Update translations for de (update-outdated). PR [#14690](https://github.com/fastapi/fastapi/pull/14690) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update LLM prompt for Russian translations. PR [#14733](https://github.com/fastapi/fastapi/pull/14733) by [@YuriiMotov](https://github.com/YuriiMotov). * 🌐 Update translations for ru (update-outdated). PR [#14693](https://github.com/fastapi/fastapi/pull/14693) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update translations for pt (update-outdated). PR [#14724](https://github.com/fastapi/fastapi/pull/14724) by [@tiangolo](https://github.com/tiangolo). From 74cc27fd5aa1e9376d30105fe014ab8b2b1319b1 Mon Sep 17 00:00:00 2001 From: Sofie Van Landeghem Date: Thu, 22 Jan 2026 17:32:34 +0100 Subject: [PATCH 033/108] =?UTF-8?q?=F0=9F=94=A7=20Ensure=20that=20an=20edi?= =?UTF-8?q?t=20to=20`uv.lock`=20gets=20the=20`internal`=20label=20(#14759)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit add uv.lock to files for labeling the PR with 'internal' --- .github/labeler.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/labeler.yml b/.github/labeler.yml index cdaefbf2d8..57c5e1120f 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -31,6 +31,7 @@ internal: - .pre-commit-config.yaml - pdm_build.py - requirements*.txt + - uv.lock - docs/en/data/sponsors.yml - docs/en/overrides/main.html - all-globs-to-all-files: From 597b435ae7f0c4694f654bce6c7c27206aa690ef Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 22 Jan 2026 16:33:00 +0000 Subject: [PATCH 034/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 1cd2b887f6..f1321b7809 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -36,6 +36,7 @@ hide: ### Internal +* 🔧 Ensure that an edit to `uv.lock` gets the `internal` label. PR [#14759](https://github.com/fastapi/fastapi/pull/14759) by [@svlandeg](https://github.com/svlandeg). * 🔧 Update sponsors: remove Requestly. PR [#14735](https://github.com/fastapi/fastapi/pull/14735) by [@tiangolo](https://github.com/tiangolo). * 🔧 Update sponsors, LambdaTest changes to TestMu AI. PR [#14734](https://github.com/fastapi/fastapi/pull/14734) by [@tiangolo](https://github.com/tiangolo). * ⬆ Bump actions/cache from 4 to 5. PR [#14511](https://github.com/fastapi/fastapi/pull/14511) by [@dependabot[bot]](https://github.com/apps/dependabot). From eaf07c5d849ce4564b8708b4965a232fd026f1fe Mon Sep 17 00:00:00 2001 From: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> Date: Sun, 25 Jan 2026 00:16:10 +0300 Subject: [PATCH 035/108] =?UTF-8?q?=F0=9F=8C=90=20Update=20translations=20?= =?UTF-8?q?for=20ko=20(update=20outdated,=20found=20by=20fixer=20tool)=20(?= =?UTF-8?q?#14738)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Update outdated pages found by fixer tool * Re-translate with updated prompt (fixed translation for `you`) * Re-translate with `gtpt-5` model * Re-translate with new preferred translation for `burger` * Re-translate with new preferred translations for `app` and `command` --- docs/ko/docs/async.md | 372 ++++++++++++++------------ docs/ko/docs/fastapi-cli.md | 96 +++---- docs/ko/docs/features.md | 176 ++++++------ docs/ko/docs/help-fastapi.md | 199 +++++++------- docs/ko/docs/history-design-future.md | 82 +++--- 5 files changed, 468 insertions(+), 457 deletions(-) diff --git a/docs/ko/docs/async.md b/docs/ko/docs/async.md index ec503d5406..36f1ca6bf1 100644 --- a/docs/ko/docs/async.md +++ b/docs/ko/docs/async.md @@ -1,18 +1,18 @@ -# 동시성곌 async / await +# 동시성곌 async / await { #concurrency-and-async-await } -*겜로 작동 핚수*에서의 `async def` 묞법에 대한 섞부사항곌 비동Ʞ 윔드, 동시성 및 병렬성에 대한 배겜 +*겜로 처늬 핚수*에서의 `async def` 묞법에 대한 섞부사항곌 비동Ʞ 윔드, 동시성 및 병렬성에 대한 배겜 -## 바쁘신 겜우 +## 바쁘신가요? { #in-a-hurry } -요앜 +TL;DR: -닀음곌 같읎 `await`륌 사용핎 혞출하는 제3의 띌읎람러늬륌 사용하는 겜우: +닀음곌 같읎 `await`륌 사용핎 혞출하띌고 안낎하는 제3자 띌읎람러늬륌 사용하는 겜우: ```Python results = await some_library() ``` -닀음처럌 *겜로 작동 핚수*륌 `async def`륌 사용핎 선얞하십시였: +닀음처럌 *겜로 처늬 핚수*륌 `async def`륌 사용핎 선얞하십시였: ```Python hl_lines="2" @app.get('/') @@ -29,7 +29,7 @@ async def read_results(): --- -데읎터베읎슀, API, 파음시슀템 등곌 의사소통하는 제3의 띌읎람러늬륌 사용하고, 귞것읎 `await`륌 지원하지 않는 겜우(현재 거의 몚든 데읎터베읎슀 띌읎람러늬가 귞러합니닀), *겜로 작동 핚수*륌 음반적읞 `def`륌 사용핎 선얞하십시였: +데읎터베읎슀, API, 파음시슀템 등곌 의사소통하는 제3자 띌읎람러늬륌 사용하고, 귞것읎 `await` 사용을 지원하지 않는 겜우(현재 대부분의 데읎터베읎슀 띌읎람러늬가 귞러합니닀), *겜로 처늬 핚수*륌 음반적읞 `def`륌 사용핎 선얞하십시였: ```Python hl_lines="2" @app.get('/') @@ -40,23 +40,23 @@ def results(): --- -만앜 당신의 응용프로귞랚읎 (얎짞서읞지) 닀륞 묎엇곌 의사소통하고 귞것읎 응답하Ʞ륌 Ʞ닀늎 필요가 없닀멎 `async def`륌 사용하십시였. +만앜 여러분의 애플늬쌀읎션읎 (얎짞서읞지) 닀륞 ì–Žë–€ 것곌도 통신하고 ê·ž 응답을 Ʞ닀늎 필요가 없닀멎, 낎부에서 `await`륌 사용할 필요가 없더띌도 `async def`륌 사용하섞요. --- -몚륎겠닀멎, 귞냥 `def`륌 사용하십시였. +잘 몚륎겠닀멎, 음반적읞 `def`륌 사용하섞요. --- -**ì°žê³ **: *겜로 작동 핚수*에서 필요한만큌 `def`와 `async def`륌 혌용할 수 있고, 가장 알맞은 것을 선택핎서 정의할 수 있습니닀. FastAPI가 자첎적윌로 알맞은 작업을 수행할 것입니닀. +**ì°žê³ **: *겜로 처늬 핚수*에서 필요한 만큌 `def`와 `async def`륌 혌용할 수 있윌며, 각각에 대핮 가장 알맞은 옵션을 선택핎 정의하멎 됩니닀. FastAPI가 올바륎게 처늬합니닀. -얎찌되었든, 상Ʞ ì–Žë– í•œ 겜우띌도, FastAPI는 여전히 비동Ʞ적윌로 작동하고 맀우 빠늅니닀. +얎욌든 위의 ì–Žë–€ 겜우에서도 FastAPI는 여전히 비동Ʞ적윌로 동작하며 맀우 빠늅니닀. -귞러나 상Ʞ 작업을 수행핚윌로썚 얎느 정도의 성능 최적화가 가능합니닀. +하지만 위의 닚계륌 따륎멎, 몇 가지 성능 최적화륌 할 수 있습니닀. -## Ʞ술적 섞부사항 +## Ʞ술적 섞부사항 { #technical-details } -최신 파읎썬 버전은 `async`와 `await` 묞법곌 핚께 **“윔룚틎”**읎띌고 하는 것을 사용하는 **“비동Ʞ 윔드”**륌 지원합니닀. +최신 파읎썬 버전은 **“윔룚틎”**읎띌고 하는 것을 사용하는 **“비동Ʞ 윔드”**륌 **`async` 및 `await`** 묞법곌 핚께 지원합니닀. 아래 섹션듀에서 핎당 묞장을 부분별로 삎펎볎겠습니닀: @@ -64,251 +64,283 @@ def results(): * **`async`와 `await`** * **윔룚틎** -## 비동Ʞ 윔드 +## 비동Ʞ 윔드 { #asynchronous-code } -비동Ʞ 윔드란 ì–žì–Ž 💬 가 윔드의 얎느 한 부분에서, 컎퓚터 / 프로귞랚🀖에게 *닀륞 묎얞가*가 얎딘가에서 끝날 때까지 Ʞ닀렀알한닀고 말하는 방식입니닀. *닀륞 묎얞가*가 “느며-파음" 📝 읎띌고 불늰닀고 가정핎뎅시닀. +비동Ʞ 윔드는 ì–žì–Ž 💬 가 윔드의 얎느 한 부분에서 컎퓚터/프로귞랚 🀖 에게, 얎느 시점에는 얎딘가에서 *닀륞 묎얞가*가 끝날 때까지 Ʞ닀렀알 한닀고 말할 수 있는 방법읎 있닀는 의믞입니닀. ê·ž *닀륞 묎얞가*륌 "slow-file" 📝 읎띌고 핎볎겠습니닀. -따띌서 “느며-파음” 📝읎 끝날때까지 컎퓚터는 닀륞 작업을 수행할 수 있습니닀. +따띌서 ê·ž 시간 동안 컎퓚터는 "slow-file" 📝 읎 끝나는 동안 닀륞 작업을 하러 갈 수 있습니닀. -ê·ž 닀음 컎퓚터 / 프로귞랚 🀖 은 닀시 Ʞ닀늬고 있Ʞ 때묞에 Ʞ회가 있을 때마닀 닀시 돌아였거나, 혹은 당시에 수행핎알하는 작업듀읎 완료될 때마닀 닀시 돌아옵니닀. 귞늬고 귞것 🀖 은 Ʞ닀늬고 있던 작업 쀑 얎느 것읎 읎믞 완료되었는지, 귞것 🀖 읎 핎알하는 몚든 작업을 수행하멎서 확읞합니닀. +ê·ž 닀음 컎퓚터/프로귞랚 🀖 은 닀시 Ʞ닀늬는 쀑읎Ʞ 때묞에 Ʞ회가 있을 때마닀 돌아였거나, 혹은 ê·ž 시점에 í•Žì•Œ 할 작업을 몚두 끝낌 때마닀 돌아옵니닀. 귞늬고 Ʞ닀늬던 작업 쀑 읎믞 끝난 것읎 있는지 확읞하멎서, í•Žì•Œ 했던 작업을 수행합니닀. -닀음윌로, 귞것 🀖 은 완료할 첫번짞 작업에 착수하고(우늬의 "느며-파음" 📝 읎띌고 가정합시닀) 귞에 대핮 수행핎알하는 작업을 계속합니닀. +닀음윌로, 완료된 첫 번짞 작업(우늬의 "slow-file" 📝 읎띌고 핎볎겠습니닀)을 가젞와서, 귞에 대핮 í•Žì•Œ 했던 작업을 계속합니닀. -"닀륞 묎얞가륌 Ʞ닀늬는 것"은 음반적윌로 비교적 "느며" (프로섞서와 RAM 메몚늬 속도에 비핎) I/O 작업을 의믞합니닀. 예륌 듀멎 닀음의 것듀을 Ʞ닀늬는 것입니닀: +읎 "닀륞 묎얞가륌 Ʞ닀늬는 것"은 음반적윌로 프로섞서와 RAM 메몚늬 속도에 비핎 상대적윌로 "느며" I/O 작업을 의믞합니닀. 예륌 듀얎 닀음을 Ʞ닀늬는 것입니닀: -* 넀튞워크륌 통핎 큎띌읎얞튞로부터 전송되는 데읎터 -* 넀튞워크륌 통핎 큎띌읎얞튞가 수신할, 당신의 프로귞랚윌로부터 전송되는 데읎터 -* 시슀템읎 읜고 프로귞랚에 전달할 디슀크 낎의 파음 ë‚Žìš© -* 당신의 프로귞랚읎 시슀템에 전달하는, 디슀크에 작성될 ë‚Žìš© +* 넀튞워크륌 통핎 큎띌읎얞튞가 데읎터륌 볎낎는 것 +* 넀튞워크륌 통핎 큎띌읎얞튞가 여러분의 프로귞랚읎 볎낞 데읎터륌 받는 것 +* 시슀템읎 디슀크의 파음 낎용을 읜얎서 프로귞랚에 전달하는 것 +* 프로귞랚읎 시슀템에 전달한 낎용을 디슀크에 쓰는 것 * 원격 API 작업 -* 완료될 데읎터베읎슀 작업 -* 결곌륌 반환하는 데읎터베읎슀 쿌늬 -* Ʞ타 +* 데읎터베읎슀 작업읎 완료되는 것 +* 데읎터베읎슀 쿌늬가 결곌륌 반환하는 것 +* Ʞ타 등등 -수행 시간의 대부분읎 I/O 작업을 Ʞ닀늬는데에 소요되Ʞ 때묞에, "I/O에 묶읞" 작업읎띌고 불늜니닀. +싀행 시간의 대부분읎 I/O 작업을 Ʞ닀늬는 데 소비되Ʞ 때묞에, 읎륌 "I/O bound" 작업읎띌고 부늅니닀. -읎것은 "비동Ʞ"띌고 불늬는데 컎퓚터 / 프로귞랚읎 작업 결곌륌 가지고 음을 수행할 수 있도록, 느며 작업에 "동Ʞ화"되얎 아묎것도 하지 않윌멎서 작업읎 완료될 정확한 시점만을 Ʞ닀늎 필요가 없Ʞ 때묞입니닀. +읎것은 컎퓚터/프로귞랚읎 느며 작업곌 "동Ʞ화"되얎, 아묎것도 하지 않은 채 ê·ž 작업읎 끝나는 정확한 시점만 Ʞ닀렞닀가 결곌륌 가젞와 음을 계속할 필요가 없Ʞ 때묞에 "비동Ʞ"띌고 불늜니닀. -읎 대신에, "비동Ʞ" 시슀템에서는, 작업은 음닚 완료되멎, 컎퓚터 / 프로귞랚읎 수행하고 있는 음을 완료하고 읎후 닀시 돌아와서 귞것의 결곌륌 받아 읎륌 사용핎 작업을 지속할 때까지 잠시 (몇 마읎크로쎈) 대Ʞ할 수 있습니닀. +대신 "비동Ʞ" 시슀템에서는, 작업읎 끝나멎 컎퓚터/프로귞랚읎 하러 갔던 음을 마칠 때까지 잠시(몇 마읎크로쎈) 쀄에서 Ʞ닀렞닀가, 닀시 돌아와 결곌륌 받아 읎륌 사용핎 작업을 계속할 수 있습니닀. -"동Ʞ"("비동Ʞ"의 반대)는 컎퓚터 / 프로귞랚읎 상읎한 작업듀간 전환을 하Ʞ 전에 귞것읎 대Ʞ륌 동반하게 될지띌도 몚든 순서륌 따륎Ʞ 때묞에 "순찚"띌는 용얎로도 흔히 불늜니닀. +"동Ʞ"(“비동Ʞ”의 반대)는 볎통 "순찚"띌는 용얎로도 불늬는데, 컎퓚터/프로귞랚읎 닀륞 작업윌로 전환하Ʞ 전에 몚든 닚계륌 순서대로 따륎Ʞ 때묞읎며, ê·ž 닚계듀에 Ʞ닀늌읎 포핚되얎 있더띌도 마찬가지입니닀. -### 동시성곌 버거 +### 동시성곌 햄버거 { #concurrency-and-burgers } -위에서 섀명한 **비동Ʞ** 윔드에 대한 개념은 종종 **"동시성"**읎띌고도 불늜니닀. 읎것은 **"병렬성"**곌는 닀늅니닀. +위에서 섀명한 **비동Ʞ** 윔드에 대한 개념은 때때로 **"동시성"**읎띌고도 불늜니닀. 읎는 **"병렬성"**곌는 닀늅니닀. -**동시성**곌 **병렬성**은 몚두 "동시에 음얎나는 서로 닀륞 음듀"곌 ꎀ렚읎 있습니닀. +**동시성**곌 **병렬성**은 몚두 "대략 같은 시간에 음얎나는 서로 닀륞 음듀"곌 ꎀ렚읎 있습니닀. 하지만 *동시성*곌 *병렬성*의 섞부적읞 개념에는 ꜀ 찚읎가 있습니닀. -찚읎륌 확읞하Ʞ 위핎, 닀음의 버거에 대한 읎알Ʞ륌 상상핎볎십시였: +찚읎륌 볎Ʞ 위핎, 닀음의 햄버거 읎알Ʞ륌 상상핎볎섞요: -### 동시 버거 +### 동시 햄버거 { #concurrent-burgers } -당신은 짝사랑 상대 😍 와 팚슀튞푞드 🍔 륌 뚹윌러 갔습니닀. 당신은 점원 💁 읎 당신 앞에 있는 사람듀의 죌묞을 받을 동안 쀄을 서서 Ʞ닀늬고 있습니닀. +여러분은 짝사랑 상대와 팚슀튞푞드륌 뚹윌러 갔고, 점원읎 여러분 앞 사람듀의 죌묞을 받는 동안 쀄을 서서 Ʞ닀늜니닀. 😍 -읎제 당신의 순서가 되얎서, 당신은 당신곌 짝사랑 상대 😍 륌 위한 두 개의 고꞉슀러욎 버거 🍔 륌 죌묞합니닀. + -당신읎 돈을 냅니닀 💞. +읎제 여러분 찚례가 되얎, 여러분곌 짝사랑 상대륌 위핎 맀우 고꞉슀러욎 햄버거 2개륌 죌묞합니닀. 🍔🍔 -점원 💁 은 죌방 👚‍🍳 에 요늬륌 하띌고 전달하고, 따띌서 귞듀은 당신의 버거 🍔 륌 쀀비핎알한닀는 사싀을 알게됩니닀(귞듀읎 지ꞈ은 당신 앞 고객듀의 죌묞을 쀀비하고 있을지띌도 말입니닀). + -점원 💁 은 당신의 순서가 적힌 번혞표륌 쀍니닀. +점원은 죌방의 요늬사에게 묎얞가륌 말핮, (지ꞈ은 앞선 손님듀의 죌묞을 쀀비하고 있더띌도) 여러분의 햄버거륌 쀀비핎알 한닀는 것을 알게 합니닀. -Ʞ닀늬는 동안, 당신은 짝사랑 상대 😍 와 핚께 테읎랔을 고륎고, 자늬에 앉아 였랫동안 (당신읎 죌묞한 버거는 ꜀나 고꞉슀럜Ʞ 때묞에 쀀비하는데 시간읎 조ꞈ 걞늜니닀 ✚🍔✚) 대화륌 나눕니닀. + -짝사랑 상대 😍 와 테읎랔에 앉아서 버거 🍔 륌 Ʞ닀늬는 동안, ê·ž 사람 😍 읎 얌마나 멋지고, 사랑슀럜고, 똑똑한지 감탄하며 시간을 볎냅니닀 ✚😍✚. +여러분읎 돈을 냅니닀. 💞 -짝사랑 상대 😍 와 Ʞ닀늬멎서 얘Ʞ하는 동안, 때때로, 당신은 당신의 찚례가 되었는지 볎Ʞ 위핎 칎욎터의 번혞륌 확읞합니닀. +점원은 여러분 ì°šë¡€ 번혞륌 쀍니닀. -귞러닀 얎느 순간, 당신의 찚례가 됩니닀. 칎욎터에 가서, 버거 🍔 륌 받고, 테읎랔로 닀시 돌아옵니닀. + -당신곌 짝사랑 상대 😍 는 버거 🍔 륌 뚹윌며 좋은 시간을 볎냅니닀 ✹. +Ʞ닀늬는 동안, 여러분은 짝사랑 상대와 핚께 자늬륌 고륎고 앉아 였랫동안 대화륌 나눕니닀(여러분의 햄버거는 맀우 고꞉슀럜Ʞ 때묞에 쀀비하는 데 시간읎 좀 걞늜니닀). + +짝사랑 상대와 테읎랔에 앉아 햄버거륌 Ʞ닀늬는 동안, ê·ž 사람읎 얌마나 멋지고 귀엜고 똑똑한지 감탄하며 시간을 볎낌 수 있습니닀 ✚😍✚. + + + +Ʞ닀늬며 대화하는 동안, 때때로 여러분은 칎욎터에 표시되는 번혞륌 확읞핎 여러분 찚례읞지 뎅니닀. + +귞러닀 얎느 순간 마칚낎 여러분 찚례가 됩니닀. 여러분은 칎욎터에 가서 햄버거륌 받고, 테읎랔로 돌아옵니닀. + + + +여러분곌 짝사랑 상대는 햄버거륌 뚹윌며 좋은 시간을 볎냅니닀. ✹ + + + +/// info | 정볎 + +아늄닀욎 음러슀튞: Ketrina Thompson. 🎚 + +/// --- -당신읎 읎 읎알Ʞ에서 컎퓚터 / 프로귞랚 🀖 읎띌고 상상핎볎십시였. +읎 읎알Ʞ에서 여러분읎 컎퓚터/프로귞랚 🀖 읎띌고 상상핎볎섞요. -쀄을 서서 Ʞ닀늬는 동안, 당신은 아묎것도 하지 않고 😎 당신의 찚례륌 Ʞ닀늬며, ì–Žë– í•œ "생산적읞" 음도 하지 않습니닀. 하지만 점원 💁 읎 (음식을 쀀비하지는 않고) 죌묞을 받Ʞ만 하Ʞ 때묞에 쀄읎 빚늬 쀄얎듀얎서 ꎜ찮습니닀. +쀄을 서 있는 동안, 여러분은 귞냥 쉬고 😎, 찚례륌 Ʞ닀늬며, 귞닀지 "생산적읞" 음을 하지 않습니닀. 하지만 점원은 죌묞만 받지(음식을 쀀비하진 ì•Šêž°) 때묞에 쀄읎 빠륎게 쀄얎듀얎 ꎜ찮습니닀. -귞닀음, 당신읎 찚례가 였멎, 당신은 싀제로 "생산적읞" 음 🀓 을 합니닀. 당신은 메뉎륌 볎고, 묎엇을 뚹을지 결정하고, 짝사랑 상대 😍 의 선택을 묻고, 돈을 ë‚Žê³  💞 , 맞는 칎드륌 냈는지 확읞하고, 비용읎 제대로 지불되었는지 확읞하고, 죌묞읎 제대로 듀얎갔는지 확읞을 하는 작업 등등을 수행합니닀. +ê·ž 닀음 여러분 찚례가 되멎, 여러분은 싀제로 "생산적읞" 음을 합니닀. 메뉎륌 처늬하고, 묎엇을 뚹을지 결정하고, 짝사랑 상대의 선택을 확읞하고, 결제하고, 올바륞 현ꞈ읎나 칎드륌 냈는지 확읞하고, 정확히 청구되었는지 확읞하고, 죌묞에 올바륞 항목듀읎 듀얎갔는지 확읞하는 등등을 합니닀. -하지만 읎후에는, 버거 🍔 륌 아직 받지 못했음에도, 버거가 쀀비될 때까지 Ʞ닀렀알 🕙 하Ʞ 때묞에 점원 💁 곌의 작업은 "음시정지" ⏞ 상태입니닀. +하지만 ê·ž 닀음에는, 아직 햄버거륌 받지 못했더띌도, 햄버거가 쀀비될 때까지 Ʞ닀렀알 🕙 하므로 점원곌의 작업은 "음시정지" ⏞ 상태입니닀. -하지만 번혞표륌 받고 칎욎터에서 나와 테읎랔에 앉윌멎, 당신은 짝사랑 상대 😍 와 ê·ž "작업" ⏯ 🀓 에 번갈아가며 🔀 집쀑합니닀. 귞러멎 당신은 닀시 짝사랑 상대 😍 에게 작업을 거는 맀우 "생산적읞" 음 🀓 을 합니닀. +하지만 번혞륌 듀고 칎욎터에서 벗얎나 테읎랔에 앉윌멎, 여러분은 짝사랑 상대에게 ꎀ심을 전환 🔀 하고, 귞에 대한 "작업" ⏯ 🀓 을 할 수 있습니닀. 귞러멎 여러분은 닀시 짝사랑 상대에게 작업을 거는 맀우 "생산적읞" 음을 하게 됩니닀 😍. -점원 💁 읎 칎욎터 화멎에 당신의 번혞륌 표시핚윌로썚 "버거 🍔 가 쀀비되었습니닀"띌고 핮도, 당신은 슉시 뛰쳐나가지는 않을 것입니닀. 당신은 당신의 번혞륌 갖고있고, 닀륞 사람듀은 귞듀의 번혞륌 갖고있Ʞ 때묞에, 아묎도 당신의 버거 🍔 륌 훔쳐가지 않는닀는 사싀을 알Ʞ 때묞입니닀. +ê·ž 닀음 점원 💁 읎 칎욎터 화멎에 여러분 번혞륌 띄워 "햄버거륌 만듀었얎요"띌고 말하지만, 표시된 번혞가 여러분 찚례로 바뀌었닀고 í•Žì„œ 슉시 믞친 듯읎 뛰얎가지는 않습니닀. 여러분은 여러분 번혞륌 갖고 있고, 닀륞 사람듀은 귞듀의 번혞륌 갖고 있윌니, 아묎도 여러분 햄버거륌 훔쳐갈 수 없닀는 것을 알Ʞ 때묞입니닀. -귞래서 당신은 짝사랑 상대 😍 가 읎알Ʞ륌 끝낌 때까지 Ʞ닀늰 후 (현재 작업 완료 ⏯ / 진행 쀑읞 작업 처늬 🀓 ), 정쀑하게 믞소짓고 버거륌 가지러 가겠닀고 말합니닀 ⏞. +귞래서 여러분은 짝사랑 상대가 읎알Ʞ륌 끝낌 때까지 Ʞ닀늰 닀음(현재 작업 ⏯ / 처늬 쀑읞 작업 🀓 을 끝낎고), 부드럜게 믞소 지윌며 햄버거륌 가지러 가겠닀고 말합니닀 ⏞. -귞닀음 당신은 칎욎터에 가서 🔀 , 쎈Ʞ 작업을 읎제 완료하고 ⏯ , 버거 🍔 륌 받고, 감사하닀고 말하고 테읎랔로 가젞옵니닀. 읎로썚 칎욎터와의 상혞작용 닚계 / 작업읎 종료됩니닀 ⏹. +ê·ž 닀음 여러분은 칎욎터로 가서 🔀, 읎제 끝난 쎈Ʞ 작업 ⏯ 윌로 돌아와 햄버거륌 받고, 감사 읞사륌 하고, 테읎랔로 가젞옵니닀. 읎로썚 칎욎터와 상혞작용하는 ê·ž 닚계/작업읎 끝납니닀 ⏹. 귞늬고 읎는 새로욎 작업읞 "햄버거 뚹Ʞ" 🔀 ⏯ 륌 만듀지만, 읎전 작업읞 "햄버거 받Ʞ"는 끝났습니닀 ⏹. -읎전 작업읞 "버거 받Ʞ"가 종료되멎 ⏹ "버거 뚹Ʞ"띌는 새로욎 작업읎 생성됩니닀 🔀 ⏯. +### 병렬 햄버거 { #parallel-burgers } -### 병렬 버거 +읎제 읎것읎 "동시 햄버거"가 아니띌 "병렬 햄버거"띌고 상상핎뎅시닀. -읎제 "동시 버거"가 아닌 "병렬 버거"륌 상상핎볎십시였. +여러분은 짝사랑 상대와 핚께 병렬 팚슀튞푞드륌 뚹윌러 갑니닀. -당신은 짝사랑 상대 😍 와 핚께 병렬 팚슀튞푞드 🍔 륌 뚹윌러 갔습니닀. +여러분은 여러 명(예: 8명)의 점원읎 동시에 요늬사읎Ʞ도 하여 여러분 앞 사람듀의 죌묞을 받는 동안 쀄을 서 있습니닀. -당신은 여러명(8명읎띌고 가정합니닀)의 점원읎 당신 앞 사람듀의 죌묞을 받윌며 동시에 요늬 👩‍🍳👚‍🍳👩‍🍳👚‍🍳👩‍🍳👚‍🍳👩‍🍳👚‍🍳 도 하는 동안 쀄을 서서 Ʞ닀늜니닀. +여러분 앞의 몚든 사람듀은, 8명의 점원 각각읎 닀음 죌묞을 받Ʞ 전에 바로 햄버거륌 쀀비하러 가Ʞ 때묞에, 칎욎터륌 떠나지 않고 햄버거가 쀀비될 때까지 Ʞ닀늜니닀. -당신 앞 몚든 사람듀읎 버거가 쀀비될 때까지 칎욎터에서 떠나지 않고 Ʞ닀늜니닀 🕙 . 왜냐하멎 8명의 직원듀읎 닀음 죌묞을 받Ʞ 전에 버거륌 쀀비하러 가Ʞ 때묞입니닀. + -마칚낎 당신의 찚례가 왔고, 당신은 당신곌 짝사랑 상대 😍 륌 위한 두 개의 고꞉슀러욎 버거 🍔 륌 죌묞합니닀. +마칚낎 여러분 찚례가 되얎, 여러분곌 짝사랑 상대륌 위핎 맀우 고꞉슀러욎 햄버거 2개륌 죌묞합니닀. -당신읎 비용을 지불합니닀 💞 . +여러분읎 돈을 냅니닀 💞. -점원읎 죌방에 갑니닀 👚‍🍳 . + -당신은 번혞표가 없Ʞ 때묞에 누구도 당신의 버거 🍔 륌 대신 가젞갈 수 없도록 칎욎터에 서서 Ʞ닀늜니닀 🕙 . +점원은 죌방윌로 갑니닀. -당신곌 짝사랑 상대 😍 는 닀륞 사람읎 새치Ʞ핎서 버거륌 가젞가지 못하게 하느띌 바쁘Ʞ 때묞에 🕙 , 짝사랑 상대에게 죌의륌 Ʞ욞음 수 없습니닀 😞 . +여러분은 번혞표가 없윌므로, 닀륞 사람읎 여러분볎닀 뚌저 햄버거륌 가젞가지 못하도록 칎욎터 앞에 서서 Ʞ닀늜니닀 🕙. -읎것은 "동Ʞ" 작업읎고, 당신은 점원/요늬사 👚‍🍳 와 "동Ʞ화" 되었습니닀. 당신은 Ʞ닀늬고 🕙 , 점원/요늬사 👚‍🍳 가 버거 🍔 쀀비륌 완료한 후 당신에게 죌거나, 누군가가 귞것을 가젞가는 ê·ž 순간에 ê·ž 곳에 있얎알합니닀. + -칎욎터 앞에서 였랫동안 Ʞ닀늰 후에 🕙 , 점원/요늬사 👚‍🍳 가 당신의 버거 🍔 륌 가지고 돌아옵니닀. +여러분곌 짝사랑 상대는 햄버거가 나였멎 닀륞 사람읎 끌얎듀얎 가젞가지 못하게 하느띌 바쁘Ʞ 때묞에, 짝사랑 상대에게 집쀑할 수 없습니닀. 😞 -당신은 버거륌 받고 짝사랑 상대와 핚께 테읎랔로 돌아옵니닀. +읎것은 "동Ʞ" 작업읎며, 여러분은 점원/요늬사 👚‍🍳 와 "동Ʞ화"되얎 있습니닀. 점원/요늬사 👚‍🍳 가 햄버거륌 완성핎 여러분에게 죌는 정확한 순간에 ê·ž 자늬에 있얎알 하므로, 여러분은 Ʞ닀렀알 🕙 하고, 귞렇지 않윌멎 닀륞 사람읎 가젞갈 수도 있습니닀. -닚지 뚹Ʞ만 하닀가, ë‹€ 뚹었습니닀 🍔 ⏹. + -칎욎터 앞에서 Ʞ닀늬멎서 🕙 너묎 많은 시간을 허비했Ʞ 때묞에 대화륌 하거나 작업을 걞 시간읎 거의 없었습니닀 😞 . +귞러닀 점원/요늬사 👚‍🍳 가 칎욎터 앞에서 였랫동안 Ʞ닀늰 🕙 끝에 마칚낎 햄버거륌 가지고 돌아옵니닀. + + + +여러분은 햄버거륌 받아 짝사랑 상대와 테읎랔로 갑니닀. + +귞냥 뚹고, 끝입니닀. ⏹ + + + +대부분의 시간을 칎욎터 앞에서 Ʞ닀늬는 데 🕙 썌Ʞ 때묞에, 대화하거나 작업을 걞 시간은 많지 않았습니닀. 😞 + +/// info | 정볎 + +아늄닀욎 음러슀튞: Ketrina Thompson. 🎚 + +/// --- -읎 병렬 버거 시나늬였에서, 당신은 Ʞ닀늬고 🕙 , 였랜 시간동안 "칎욎터에서 Ʞ닀늬는" 🕙 데에 죌의륌 Ʞ욞읎는 ⏯ 두 개의 프로섞서(당신곌 짝사랑 상대😍)륌 가진 컎퓚터 / 프로귞랚 🀖 입니닀. +읎 병렬 햄버거 시나늬였에서, 여러분은 두 개의 프로섞서(여러분곌 짝사랑 상대)륌 가진 컎퓚터/프로귞랚 🀖 읎며, 둘 ë‹€ Ʞ닀늬고 🕙 였랫동안 "칎욎터에서 Ʞ닀늬Ʞ" 🕙 에 죌의륌 ⏯ Ʞ욞입니닀. -팚슀튞푞드점에는 8개의 프로섞서(점원/요늬사) 👩‍🍳👚‍🍳👩‍🍳👚‍🍳👩‍🍳👚‍🍳👩‍🍳👚‍🍳 가 있습니닀. 동시 버거는 당 두 개(한 명의 직원곌 한 명의 요늬사) 💁 👚‍🍳 만을 가지고 있었습니닀. +팚슀튞푞드점에는 8개의 프로섞서(점원/요늬사)가 있습니닀. 동시 햄버거 가게는 2개(점원 1명, 요늬사 1명)만 있었을 것입니닀. -하지만 여전히, 병렬 버거 예시가 최선은 아닙니닀 😞 . +하지만 여전히 최종 겜험은 귞닀지 좋지 않습니닀. 😞 --- -읎 예시는 버거🍔 읎알Ʞ와 결읎 같습니닀. +읎것읎 햄버거의 병렬 버전에 핎당하는 읎알Ʞ입니닀. 🍔 -더 "현싀적읞" 예시로, 은행을 상상핎볎십시였. +좀 더 "현싀적읞" 예시로, 은행을 상상핎볎섞요. -최귌까지, 대닀수의 은행에는 닀수의 은행원듀 👚‍💌👚‍💌👚‍💌👚‍💌 곌 ꞎ 쀄 🕙🕙🕙🕙🕙🕙🕙🕙 읎 있습니닀. +최귌까지 대부분의 은행에는 여러 은행원 👚‍💌👚‍💌👚‍💌👚‍💌 곌 ꞎ 쀄 🕙🕙🕙🕙🕙🕙🕙🕙 읎 있었습니닀. -몚든 은행원듀은 한 명 한 명의 고객듀을 찚례로 상대합니닀 👚‍💌⏯ . +몚든 은행원읎 한 고객씩 순서대로 몚든 음을 처늬합니닀 👚‍💌⏯. -귞늬고 당신은 였랫동안 쀄에서 Ʞ닀렀알하고 🕙 , 귞렇지 않윌멎 당신의 찚례륌 잃게 됩니닀. +귞늬고 여러분은 였랫동안 쀄에서 Ʞ닀렀알 🕙 하며, 귞렇지 않윌멎 찚례륌 잃습니닀. -아마 당신은 은행 🏊 심부늄에 짝사랑 상대 😍 륌 데렀가고 싶지는 않을 것입니닀. +아마 은행 🏊 업묎륌 볎러 갈 때 짝사랑 상대 😍 륌 데렀가고 싶지는 않을 것입니닀. -### 버거 예시의 ê²°ë¡  +### 햄버거 예시의 ê²°ë¡  { #burger-conclusion } -"짝사랑 상대와의 팚슀튞푞드점 버거" 시나늬였에서, 였랜 Ʞ닀늌 🕙 읎 있Ʞ 때묞에 동시 시슀템 ⏞🔀⏯ 을 사용하는 것읎 더 합늬적입니닀. +"짝사랑 상대와의 팚슀튞푞드점 햄버거" 시나늬였에서는 Ʞ닀늌 🕙 읎 많Ʞ 때묞에, 동시 시슀템 ⏞🔀⏯ 을 사용하는 것읎 훚씬 더 합늬적입니닀. -대닀수의 웹 응용프로귞랚의 겜우가 귞러합니닀. +대부분의 웹 애플늬쌀읎션읎 귞렇습니닀. -맀우 많은 수의 유저가 있지만, 서버는 귞듀의 요청을 전송하Ʞ 위핎 ê·žë‹¥-좋지-않은 연결을 Ʞ닀렀알 합니닀 🕙 . +맀우 많은 사용자듀읎 있고, 서버는 귞듀의 좋지 않은 연결을 통핎 요청읎 전송되Ʞ륌 Ʞ닀늜니닀 🕙. -귞늬고 응답읎 돌아올 때까지 닀시 Ʞ닀렀알 합니닀 🕙 . +귞늬고 응답읎 돌아였Ʞ륌 닀시 Ʞ닀늜니닀 🕙. -읎 "Ʞ닀늌" 🕙 은 마읎크로쎈 닚위읎지만, 몚두 더핎지멎, 결국에는 맀우 ꞎ 대Ʞ시간읎 됩니닀. +읎 "Ʞ닀늌" 🕙 은 마읎크로쎈 닚위로 잡정되지만, 몚두 합치멎 ê²°êµ­ ꜀ 많은 대Ʞ 시간읎 됩니닀. -따띌서 웹 API륌 위핎 비동Ʞ ⏞🔀⏯ 윔드륌 사용하는 것읎 합늬적입니닀. +귞래서 웹 API에는 비동Ʞ ⏞🔀⏯ 윔드륌 사용하는 것읎 맀우 합늬적입니닀. -대부분의 졎재하는 유명한 파읎썬 프레임워크 (Flask와 Django 등)은 새로욎 비동Ʞ Ʞ능듀읎 파읎썬에 졎재하Ʞ 전에 만듀얎졌습니닀. 귞래서, 귞듀의 배포 방식은 병렬 싀행곌 새로욎 Ʞ능만큌 강력하지는 않은 예전 버전의 비동Ʞ 싀행을 지원합니닀. +읎러한 종류의 비동Ʞ성은 NodeJS가 읞Ʞ 있는 읎유(비록 NodeJS가 병렬은 아니지만)읎자, 프로귞래밍 얞얎로서 Go의 강점입니닀. -비동Ʞ 웹 파읎썬(ASGI)에 대한 죌요 명섞가 웹소쌓을 지원하Ʞ 위핎 Django에서 개발 되었음에도 귞렇습니닀. +귞늬고 읎것읎 **FastAPI**로 얻는 것곌 같은 수쀀의 성능입니닀. -읎러한 종류의 비동Ʞ성은 (NodeJS는 병렬적읎지 않음에도) NodeJS가 사랑받는 읎유읎고, 프로귞래밍 얞얎로서의 Go의 강점입니닀. +또한 병렬성곌 비동Ʞ성을 동시에 사용할 수 있윌므로, 대부분의 테슀튞된 NodeJS 프레임워크볎닀 더 높은 성능을 얻고, C에 더 가까욎 컎파음 얞얎읞 Go와 동등한 성능을 얻을 수 있습니닀 (몚두 Starlette 덕분입니닀). -귞늬고 **FastAPI**륌 사용핚윌로썚 동음한 성능을 ë‚Œ 수 있습니닀. +### 동시성읎 병렬성볎닀 더 나은가요? { #is-concurrency-better-than-parallelism } -또한 병렬성곌 비동Ʞ성을 동시에 사용할 수 있Ʞ 때묞에, 대부분의 테슀튞가 완료된 NodeJS 프레임워크볎닀 더 높은 성능을 얻고 C에 더 가까욎 컎파음 얞얎읞 Go와 동등한 성능을 얻을 수 있습니닀(몚두 Starlette 덕분입니닀). +아니요! 귞게 읎 읎알Ʞ의 교훈은 아닙니닀. -### 동시성읎 병렬성볎닀 더 나은가? +동시성은 병렬성곌 닀늅니닀. 귞늬고 많은 Ʞ닀늌읎 포핚되는 **특정한** 시나늬였에서는 더 낫습니닀. ê·ž 때묞에 웹 애플늬쌀읎션 개발에서는 음반적윌로 병렬성볎닀 훚씬 더 낫습니닀. 하지만 몚든 것에 핎당하진 않습니닀. -귞렇지 않습니닀! 귞것읎 읎알Ʞ의 교훈은 아닙니닀. +귞래서 균형을 맞추Ʞ 위핎, 닀음의 짧은 읎알Ʞ륌 상상핎볎섞요: -동시성은 병렬성곌 닀늅니닀. 귞늬고 귞것은 많은 대Ʞ륌 필요로하는 **특정한** 시나늬였에서는 더 낫습니닀. 읎로 읞핎, 웹 응용프로귞랚 개발에서 동시성읎 병렬성볎닀 음반적윌로 훚씬 낫습니닀. 하지만 몚든 겜우에 귞런 것은 아닙니닀. - -따띌서, 균형을 맞추Ʞ 위핎, 닀음의 짧은 읎알Ʞ륌 상상핎볎십시였: - -> 당신은 크고, 더러욎 집을 청소핎알합니닀. +> 여러분은 크고 더러욎 집을 청소핎알 합니닀. *ë„€, 읎게 전부입니닀*. --- -얎디에도 대Ʞ 🕙 는 없고, 집안 곳곳에서 핎알하는 많은 작업듀만 있습니닀. +얎디에도 Ʞ닀늌 🕙 은 없고, 집의 여러 장소에서 í•Žì•Œ 할 음읎 많을 뿐입니닀. -버거 예시처럌 처음에는 ê±°ì‹€, ê·ž 닀음은 부엌곌 같은 식윌로 순서륌 정할 수도 있윌나, 묎엇도 Ʞ닀늬지 🕙 않고 계속핎서 청소 작업만 수행하Ʞ 때묞에, 순서는 아묎런 영향을 믞치지 않습니닀. +햄버거 예시처럌 거싀부터, ê·ž 닀음은 부엌처럌 순서륌 정할 수도 있지만, ì–Žë–€ 것도 Ʞ닀늬지 🕙 않고 계속 청소만 하Ʞ 때묞에, 순서는 아묎런 영향을 죌지 않습니닀. -순서가 있든 없든 동음한 시간읎 소요될 것읎고(동시성) 동음한 양의 작업을 하게 될 것입니닀. +순서가 있든 없든(동시성) 끝낮는 데 걞늬는 시간은 같고, 같은 양의 음을 하게 됩니닀. -하지만 읎 겜우에서, 8명의 전(前)-점원/요늬사읎멎서-현(珟)-청소부 👩‍🍳👚‍🍳👩‍🍳👚‍🍳👩‍🍳👚‍🍳👩‍🍳👚‍🍳 륌 고용할 수 있고, ê·žë“€ 각자(귞늬고 당신)가 집의 한 부분씩 맡아 청소륌 한닀멎, 당신은 **병렬적**윌로 작업을 수행할 수 있고, 조ꞈ의 도움읎 있닀멎, 훚씬 더 빚늬 끝낌 수 있습니닀. +하지만 읎 겜우, 전(前) 점원/요늬사읎자 현(珟) 청소부가 된 8명을 데렀올 수 있고, 각자(귞늬고 여러분)가 집의 구역을 하나씩 맡아 청소한닀멎, 추가 도움곌 핚께 몚든 음을 **병렬**로 수행하여 훚씬 더 빚늬 끝낌 수 있습니닀. -읎 시나늬였에서, (당신을 포핚한) 각각의 청소부듀은 프로섞서가 될 것읎고, 각자의 역할을 수행합니닀. +읎 시나늬였에서 (여러분을 포핚한) 각 청소부는 프로섞서가 되얎, 맡은 음을 수행합니닀. -싀행 시간의 대부분읎 대Ʞ가 아닌 싀제 작업에 소요되고, 컎퓚터에서 작업은 CPU에서 읎룚얎지므로, 읎러한 묞제륌 "CPU에 묶였"닀고 합니닀. +귞늬고 싀행 시간의 대부분읎 Ʞ닀늌읎 아니띌 싀제 작업에 쓰읎고, 컎퓚터에서 작업은 CPU가 수행하므로, 읎런 묞제륌 "CPU bound"띌고 부늅니닀. --- -CPU에 묶읞 연산에 ꎀ한 흔한 예시는 복잡한 수학 처늬륌 필요로 하는 겜우입니닀. +CPU bound 작업의 흔한 예시는 복잡한 수학 처늬가 필요한 것듀입니닀. 예륌 듀얎: -* **였디였** 또는 **읎믞지** 처늬. -* **컎퓚터 비전**: 하나의 읎믞지는 수백개의 픜셀로 구성되얎있고, 각 픜셀은 3개의 값 / 색을 갖고 있윌며, 음반적윌로 핎당 픜셀듀에 대핮 동시에 묎얞가륌 계산핎알하는 처늬. -* **뚞신러닝**: 음반적윌로 많은 "행렬"곌 "벡터" 곱셈읎 필요합니닀. 거대한 슀프레드 시튞에 수듀읎 있고 ê·ž 수듀을 동시에 곱핎알 한닀고 생각핎볎십시였. -* **딥러닝**: 뚞신러닝의 하위영역윌로, 동음한 예시가 적용됩니닀. 닚지 읎 겜우에는 하나의 슀프레드 시튞에 곱핎알할 수듀읎 있는 것읎 아니띌, 거대한 섞튞의 슀프레드 시튞듀읎 있고, 많은 겜우에, 읎 몚덞듀을 만듀고 사용하Ʞ 위핎 특수한 프로섞서륌 사용합니닀. +* **였디였** 또는 **읎믞지** 처늬 +* **컎퓚터 비전**: 읎믞지는 수백만 개의 픜셀로 구성되며, 각 픜셀은 3개의 값/색을 갖습니닀. 볎통 ê·ž 픜셀듀에 대핮 동시에 묎얞가륌 계산핎알 합니닀. +* **뚞신러닝**: 볎통 많은 "matrix"와 "vector" 곱셈읎 필요합니닀. 숫자가 있는 거대한 슀프레드시튞륌 생각하고, ê·ž 몚든 수륌 동시에 곱한닀고 생각핎볎섞요. +* **딥러닝**: 뚞신러닝의 하위 분알읎므로 동음하게 적용됩니닀. 닀만 곱핎알 할 숫자가 있는 슀프레드시튞가 하나가 아니띌, 아죌 큰 집합읎며, 많은 겜우 ê·ž 몚덞을 만듀고/또는 사용하Ʞ 위핎 특별한 프로섞서륌 사용합니닀. -### 동시성 + 병렬성: 웹 + 뚞신러닝 +### 동시성 + 병렬성: 웹 + 뚞신러닝 { #concurrency-parallelism-web-machine-learning } -**FastAPI**륌 사용하멎 웹 개발에서는 맀우 흔한 동시성의 읎점을 (NodeJS의 죌된 맀력만큌) 얻을 수 있습니닀. +**FastAPI**륌 사용하멎 웹 개발에서 맀우 흔한 동시성의 읎점을( NodeJS의 죌요 맀력곌 같은) 얻을 수 있습니닀. -뿐만 아니띌 뚞신러닝 시슀템곌 같읎 **CPU에 묶읞** 작업을 위핎 병렬성곌 멀티프로섞싱(닀수의 프로섞슀륌 병렬적윌로 동작시킀는 것)을 읎용하는 것도 가능합니닀. +또한 뚞신러닝 시슀템처럌 **CPU bound** 워크로드에 대핮 병렬성곌 멀티프로섞싱(여러 프로섞슀륌 병렬로 싀행)을 활용할 수도 있습니닀. -파읎썬읎 **데읎터 사읎얞슀**, 뚞신러닝곌 특히 딥러닝에 의 죌된 얞얎띌는 ê°„ë‹ší•œ 사싀에 더핎서, 읎것은 FastAPI륌 데읎터 사읎얞슀 / 뚞신러닝 웹 API와 응용프로귞랚에 (닀륞 것듀볎닀) 좋은 선택지가 되게 합니닀. +읎것은 파읎썬읎 **데읎터 사읎얞슀**, 뚞신러닝, 특히 딥러닝의 죌요 얞얎띌는 닚순한 사싀곌 더핎젞, FastAPI륌 데읎터 사읎얞슀/뚞신러닝 웹 API 및 애플늬쌀읎션(ê·ž 왞에도 많은 것듀)에 맀우 잘 맞는 선택윌로 만듀얎 쀍니닀. -배포시 병렬을 얎떻게 가능하게 하는지 알고싶닀멎, [배포](deployment/index.md){.internal-link target=_blank}묞서륌 찞고하십시였. +프로덕션에서 읎 병렬성을 얎떻게 달성하는지 볎렀멎 [배포](deployment/index.md){.internal-link target=_blank} 섹션을 찞고하섞요. -## `async`와 `await` +## `async`와 `await` { #async-and-await } -최신 파읎썬 버전에는 비동Ʞ 윔드륌 정의하는 맀우 직ꎀ적읞 방법읎 있습니닀. 읎는 읎것을 평범한 "순찚적" 윔드로 볎읎게 하고, 적절한 순간에 당신을 위핎 "대Ʞ"합니닀. +최신 파읎썬 버전에는 비동Ʞ 윔드륌 정의하는 맀우 직ꎀ적읞 방법읎 있습니닀. 읎 방법은 읎륌 평범한 "순찚" 윔드처럌 볎읎게 하고, 적절한 순간에 여러분을 위핎 "Ʞ닀늌"을 수행합니닀. -연산읎 결곌륌 전달하Ʞ 전에 대Ʞ륌 핎알하고 새로욎 파읎썬 Ʞ능듀을 지원한닀멎, 읎렇게 윔드륌 작성할 수 있습니닀: +결곌륌 죌Ʞ 전에 Ʞ닀늌읎 필요한 작업읎 있고, 읎러한 새로욎 파읎썬 Ʞ능을 지원한닀멎, 닀음곌 같읎 작성할 수 있습니닀: ```Python burgers = await get_burgers(2) ``` -여Ʞ서 핵심은 `await`입니닀. 읎것은 파읎썬에게 `burgers` 결곌륌 저장하Ʞ 읎전에 `get_burgers(2)`의 작업읎 완료되Ʞ륌 🕙 Ʞ닀늬띌고 ⏞ 말합니닀. 읎로 읞핎, 파읎썬은 귞동안 (닀륞 요청을 받는 것곌 같은) 닀륞 작업을 수행핎도 된닀는 것을 🔀 ⏯ 알게될 것입니닀. +여Ʞ서 핵심은 `await`입니닀. 읎는 파읎썬에게 `get_burgers(2)`가 ê·ž 음을 끝낌 때까지 🕙 Ʞ닀늬도록 ⏞ 말하고, ê·ž 결곌륌 `burgers`에 저장하Ʞ 전에 완료되Ʞ륌 Ʞ닀늬띌고 합니닀. 읎륌 통핎 파읎썬은 귞동안(예: 닀륞 요청을 받는 것처럌) 닀륞 음을 하러 갈 수 있닀는 것 🔀 ⏯ 을 알게 됩니닀. -`await`가 동작하Ʞ 위핎, 읎것은 비동Ʞ륌 지원하는 핚수 낎부에 있얎알 합니닀. 읎륌 위핎서 핚수륌 `async def`륌 사용핎 정의하Ʞ만 하멎 됩니닀: +`await`가 동작하렀멎, 읎 비동Ʞ성을 지원하는 핚수 낎부에 있얎알 합니닀. 귞러렀멎 `async def`로 선얞하Ʞ만 하멎 됩니닀: ```Python hl_lines="1" async def get_burgers(number: int): - # Do some asynchronous stuff to create the burgers + # 햄버거륌 만듀Ʞ 위한 비동Ʞ 처늬륌 수행 return burgers ``` -...`def`륌 사용하는 대신: +...`def` 대신: ```Python hl_lines="2" -# This is not asynchronous +# 비동Ʞ가 아닙니닀 def get_sequential_burgers(number: int): - # Do some sequential stuff to create the burgers + # 햄버거륌 만듀Ʞ 위한 순찚 처늬륌 수행 return burgers ``` -`async def`륌 사용하멎, 파읎썬은 핎당 핚수 낎에서 `await` 표현에 죌의핎알한닀는 사싀곌, 핎당 핚수의 싀행을 "음시정지"⏞하고 닀시 돌아였Ʞ 전까지 닀륞 작업을 수행🔀할 수 있닀는 것을 알게됩니닀. +`async def`륌 사용하멎, 파읎썬은 ê·ž 핚수 낎부에서 `await` 표현식에 죌의핎알 하며, ê·ž 핚수의 싀행을 "음시정지" ⏞ 하고 닀시 돌아였Ʞ 전에 닀륞 음을 하러 갈 수 있닀는 것 🔀 을 알게 됩니닀. -`async def`f 핚수륌 혞출하고자 할 때, "대Ʞ"핎알합니닀. 따띌서, 아래는 동작하지 않습니닀. +`async def` 핚수륌 혞출하고자 할 때는, ê·ž 핚수륌 "await" í•Žì•Œ 합니닀. 따띌서 아래는 동작하지 않습니닀: ```Python -# This won't work, because get_burgers was defined with: async def +# 동작하지 않습니닀. get_burgers는 async def로 정의되었습니닀 burgers = get_burgers(2) ``` --- -따띌서, `await`f륌 사용핎서 혞출할 수 있는 띌읎람러늬륌 사용한닀멎, 닀음곌 같읎 `async def`륌 사용하는 *겜로 작동 핚수*륌 생성핎알 합니닀: +따띌서, `await`로 혞출할 수 있닀고 말하는 띌읎람러늬륌 사용한닀멎, 닀음곌 같읎 귞것을 사용하는 *겜로 처늬 핚수*륌 `async def`로 만듀얎알 합니닀: ```Python hl_lines="2-3" @app.get('/burgers') @@ -317,94 +349,96 @@ async def read_burgers(): return burgers ``` -### 더 섞부적읞 Ʞ술적 사항 +### 더 섞부적읞 Ʞ술적 사항 { #more-technical-details } -`await`가 `async def`륌 사용하는 핚수 낎부에서만 사용읎 가능하닀는 것을 눈치채셚을 것입니닀. +`await`는 `async def`로 정의된 핚수 낎부에서만 사용할 수 있닀는 것을 눈치채셚을 것입니닀. -하지만 동시에, `async def`로 정의된 핚수듀은 "대Ʞ"되얎알만 합니닀. 따띌서, `async def`륌 사용한 핚수듀은 역시 `async def`륌 사용한 핚수 낎부에서만 혞출될 수 있습니닀. +하지만 동시에, `async def`로 정의된 핚수는 "await" 되얎알 합니닀. 따띌서 `async def`륌 가진 핚수는 `async def`로 정의된 핚수 낎부에서만 혞출될 수 있습니닀. -귞렇닀멎 닭읎 뚌저냐, 달걀읎 뚌저냐, 첫 `async` 핚수륌 얎떻게 혞출할 수 있겠습니까? +귞렇닀멎, 닭읎 뚌저냐 달걀읎 뚌저냐처럌, 첫 번짞 `async` 핚수는 얎떻게 혞출할 수 있을까요? -**FastAPI**륌 사용핎 작업한닀멎 읎것을 걱정하지 않아도 됩니닀. 왜냐하멎 ê·ž "첫" 핚수는 당신의 *겜로 작동 핚수*가 될 것읎고, FastAPI는 얎떻게 올바륎게 처늬할지 알고있Ʞ 때묞입니닀. +**FastAPI**로 작업한닀멎 걱정할 필요가 없습니닀. ê·ž "첫" 핚수는 여러분의 *겜로 처늬 핚수*가 될 것읎고, FastAPI는 올바륎게 처늬하는 방법을 알고 있Ʞ 때묞입니닀. -하지만 FastAPI륌 사용하지 않고 `async` / `await`륌 사용하고 싶닀멎, 읎 역시 가능합니닀. +하지만 FastAPI 없읎 `async` / `await`륌 사용하고 싶닀멎, 귞것도 가능합니닀. -### 당신만의 비동Ʞ 윔드 작성하Ʞ +### 여러분만의 async 윔드 작성하Ʞ { #write-your-own-async-code } -Starlette(귞늬고 FastAPI)는 AnyIO륌 Ʞ반윌로 하고있고, 따띌서 파읎썬 표쀀 띌읎람러늬읞 asyncio 및 Trio와 혞환됩니닀. +Starlette(귞늬고 **FastAPI**)는 AnyIO륌 Ʞ반윌로 하고 있윌며, 파읎썬 표쀀 띌읎람러늬 asyncio와 Trio 몚두와 혞환됩니닀. -특히, 윔드에서 고꞉ 팚턎읎 필요한 고꞉ 동시성을 사용하는 겜우 직접적윌로 AnyIO륌 사용할 수 있습니닀. +특히, 윔드에서 더 고꞉ 팚턎읎 필요한 고꞉ 동시성 사용 사례에서는 직접 AnyIO륌 사용할 수 있습니닀. -FastAPI륌 사용하지 않더띌도, 높은 혞환성 및 AnyIO의 읎점(예: *구조화된 동시성*)을 췚하Ʞ 위핎 AnyIO륌 사용핎 비동Ʞ 응용프로귞랚을 작성할 수 있습니닀. +귞늬고 FastAPI륌 사용하지 않더띌도, 높은 혞환성을 확볎하고 ê·ž 읎점(예: *structured concurrency*)을 얻Ʞ 위핎 AnyIO로 여러분만의 async 애플늬쌀읎션을 작성할 수도 있습니닀. -### 비동Ʞ 윔드의 닀륞 형태 +저는 AnyIO 위에 얇은 레읎얎로 또 닀륞 띌읎람러늬륌 만듀었는데, 타입 얎녞테읎션을 조ꞈ 개선하고 더 나은 **자동완성**, **읞띌읞 였류** 등을 얻Ʞ 위한 것입니닀. 또한 **읎핎**하고 **여러분만의 async 윔드**륌 작성하도록 돕는 친절한 소개와 튜토늬얌도 제공합니닀: Asyncer. 특히 **async 윔드와 음반**(blocking/동Ʞ) 윔드륌 **결합**í•Žì•Œ 한닀멎 아죌 유용합니닀. -파읎썬에서 `async`와 `await`륌 사용하게 된 것은 비교적 최귌의 음입니닀. +### 비동Ʞ 윔드의 닀륞 형태 { #other-forms-of-asynchronous-code } -하지만 읎로 읞핎 비동Ʞ 윔드 작업읎 훚씬 간닚핎졌습니닀. +`async`와 `await`륌 사용하는 읎 슀타음은 얞얎에서 비교적 최귌에 추가되었습니닀. -같은 (또는 거의 유사한) 묞법은 최신 버전의 자바슀크늜튞(람띌우저와 NodeJS)에도 추가되었습니닀. +하지만 비동Ʞ 윔드륌 닀룚는 음을 훚씬 더 쉜게 만듀얎 쀍니닀. -하지만 ê·ž 읎전에, 비동Ʞ 윔드륌 처늬하는 것은 ꜀ 복잡하고 얎렀욎 음읎었습니닀. +거의 동음한 묞법읎 최귌 람띌우저와 NodeJS의 최신 JavaScript에도 포핚되었습니닀. -파읎썬의 예전 버전읎띌멎, 슀레드 또는 Gevent륌 사용할 수 있을 것입니닀. 하지만 윔드륌 읎핎하고, 디버깅하고, 읎에 대핮 생각하는게 훚씬 복잡합니닀. +하지만 ê·ž 읎전에는 비동Ʞ 윔드륌 처늬하는 것읎 훚씬 더 복잡하고 얎렀웠습니닀. -예전 버전의 NodeJS / 람띌우저 자바슀크늜튞띌멎, "윜백 핚수"륌 사용했을 것입니닀. 귞늬고 읎로 읞핎 "윜백 지옥"에 빠지게 될 수 있습니닀. +읎전 버전의 파읎썬에서는 슀레드 또는 Gevent륌 사용할 수 있었을 것입니닀. 하지만 윔드륌 읎핎하고, 디버깅하고, 읎에 대핮 생각하는 것읎 훚씬 더 복잡합니닀. -## 윔룚틎 +읎전 버전의 NodeJS/람띌우저 JavaScript에서는 "callback"을 사용했을 것입니닀. 읎는 "callback hell"로 읎얎집니닀. -**윔룚틎**은 `async def` 핚수가 반환하는 것을 칭하는 맀우 고꞉슀러욎 용얎음 뿐입니닀. 파읎썬은 귞것읎 시작되고 얎느 시점에서 완료되지만 낎부에 `await`가 있을 때마닀 낎부적윌로 음시정지⏞될 수도 있는 핚수와 유사한 것읎띌는 사싀을 알고있습니닀. +## 윔룚틎 { #coroutines } -귞러나 `async` 및 `await`와 핚께 비동Ʞ 윔드륌 사용하는 읎 몚든 Ʞ능듀은 "윔룚틎"윌로 간닚히 요앜됩니닀. 읎것은 Go의 죌된 핵심 Ʞ능읞 "고룚틎"에 견쀄 수 있습니닀. +**윔룚틎**은 `async def` 핚수가 반환하는 것에 대한 맀우 고꞉슀러욎 용얎음 뿐입니닀. 파읎썬은 귞것읎 핚수와 비슷한 묎얞가로서 시작할 수 있고, 얎느 시점에 끝나지만, 낎부에 `await`가 있을 때마닀 낎부적윌로도 음시정지 ⏞ 될 수 있닀는 것을 알고 있습니닀. -## ê²°ë¡  +하지만 `async` 및 `await`와 핚께 비동Ʞ 윔드륌 사용하는 읎 몚든 Ʞ능은 종종 "윔룚틎"을 사용한닀고 요앜됩니닀. 읎는 Go의 죌요 핵심 Ʞ능읞 "Goroutines"에 비견됩니닀. -상Ʞ 묞장을 닀시 한 번 뎅시닀: +## ê²°ë¡  { #conclusion } -> 최신 파읎썬 버전은 **`async` 및 `await`** 묞법곌 핚께 **“윔룚틎”**읎띌고 하는 것을 사용하는 **“비동Ʞ 윔드”**륌 지원합니닀. +위의 같은 묞장을 닀시 뎅시닀: -읎제 읎 말을 조ꞈ 더 읎핎할 수 있을 것입니닀. ✹ +> 최신 파읎썬 버전은 **“윔룚틎”**읎띌고 하는 것을 사용하는 **“비동Ʞ 윔드”**륌 **`async` 및 `await`** 묞법곌 핚께 지원합니닀. -읎것읎 (Starlette을 통핎) FastAPI륌 강하게 하멎서 귞것읎 읞상적읞 성능을 ë‚Œ 수 있게 합니닀. +읎제 더 읎핎가 될 것입니닀. ✹ -## 맀우 섞부적읞 Ʞ술적 사항 +읎 몚든 것읎 FastAPI(Starlette을 통핎)륌 구동하고, 읞상적읞 성능을 낎게 하는 원동력입니닀. + +## 맀우 섞부적읞 Ʞ술적 사항 { #very-technical-details } /// warning | 겜고 -읎 부분은 넘얎가도 됩니닀. +읎 부분은 아마 걎너뛰얎도 됩니닀. 읎것듀은 **FastAPI**가 낎부적윌로 얎떻게 동작하는지에 대한 맀우 섞부적읞 Ʞ술사항입니닀. -만앜 Ʞ술적 지식(윔룚틎, 슀레드, 랔록킹 등)읎 있고 FastAPI가 얎떻게 `async def` vs `def`륌 닀룚는지 궁ꞈ하닀멎, 계속하십시였. +(윔룚틎, 슀레드, 랔로킹 등) 같은 Ʞ술 지식읎 ꜀ 있고 FastAPI가 `async def`와 음반 `def`륌 얎떻게 처늬하는지 궁ꞈ하닀멎, 계속 읜얎볎섞요. /// -### 겜로 작동 핚수 +### 겜로 처늬 핚수 { #path-operation-functions } -겜로 작동 핚수륌 `async def` 대신 음반적읞 `def`로 선얞하는 겜우, (서버륌 찚닚하는 것처럌) 귞것을 직접 혞출하는 대신 대Ʞ쀑읞 왞부 슀레드풀에서 싀행됩니닀. +*겜로 처늬 핚수*륌 `async def` 대신 음반적읞 `def`로 선얞하멎, (서버륌 랔로킹할 수 있윌므로 직접 혞출하는 대신) 왞부 슀레드풀에서 싀행되고 ê·ž 결곌륌 await 합니닀. -만앜 상Ʞ에 묘사된대로 동작하지 않는 비동Ʞ 프로귞랚을 사용핎왔고 앜간의 성능 향상 (ì•œ 100 나녞쎈)을 위핎 `def`륌 사용핎서 계산만을 위한 사소한 *겜로 작동 핚수*륌 정의핎왔닀멎, **FastAPI**는 읎와는 반대띌는 것에 죌의하십시였. 읎러한 겜우에, *겜로 작동 핚수*가 랔로킹 I/O륌 수행하는 윔드륌 사용하지 않는 한 `async def`륌 사용하는 펞읎 더 낫습니닀. +위에서 섀명한 방식윌로 동작하지 않는 닀륞 async 프레임워크륌 사용핎볞 적읎 있고, 아죌 작은 성능 향상(ì•œ 100 나녞쎈)을 위핎 계산만 하는 사소한 *겜로 처늬 핚수*륌 음반 `def`로 정의하곀 했닀멎, **FastAPI**에서는 ê·ž 횚곌가 정반대가 될 수 있닀는 점에 유의하섞요. 읎런 겜우에는 *겜로 처늬 핚수*에서 랔로킹 I/O 륌 수행하는 윔드륌 사용하지 않는 한 `async def`륌 사용하는 펞읎 더 낫습니닀. -하지만 두 겜우 몚두, FastAPI가 당신읎 전에 사용하던 프레임워크볎닀 [더 빠륌](index.md#_11){.internal-link target=_blank} (최소한 비견될) 확률읎 높습니닀. +귞럌에도 두 겜우 몚두, **FastAPI**는 읎전에 사용하던 프레임워크볎닀 [여전히 더 빠륌](index.md#performance){.internal-link target=_blank} 가능성읎 높습니닀(또는 최소한 비슷합니닀). -### 의졎성 +### 의졎성 { #dependencies } -의졎성에도 동음하게 적용됩니닀. 의졎성읎 `async def`가 아닌 표쀀 `def` 핚수띌멎, 왞부 슀레드풀에서 싀행됩니닀. +[의졎성](tutorial/dependencies/index.md){.internal-link target=_blank}에도 동음하게 적용됩니닀. 의졎성읎 `async def` 대신 표쀀 `def` 핚수띌멎, 왞부 슀레드풀에서 싀행됩니닀. -### 하위-의졎성 +### 하위 의졎성 { #sub-dependencies } -핚수 정의시 맀개변수로 서로륌 필요로하는 닀수의 의졎성곌 하위-의졎성을 가질 수 있고, ê·ž 쀑 음부는 `async def`로, 닀륞 음부는 음반적읞 `def`로 생성되었을 수 있습니닀. 읎것은 여전히 잘 동작하고, 음반적읞 `def`로 생성된 것듀은 "대Ʞ"되는 대신에 (슀레드풀로부터) 왞부 슀레드에서 혞출됩니닀. +서로륌 필요로 하는 여러 의졎성곌 [하위 의졎성](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank}을 핚수 정의의 맀개변수로 가질 수 있윌며, 귞쀑 음부는 `async def`로, 닀륞 음부는 음반 `def`로 생성되었을 수 있습니닀. 귞래도 정상 동작하며, 음반 `def`로 생성된 것듀은 "await"되는 대신 (슀레드풀에서) 왞부 슀레드에서 혞출됩니닀. -### 닀륞 유틞늬티 핚수 +### 닀륞 유틞늬티 핚수 { #other-utility-functions } -직접 혞출되는 닀륞 몚든 유틞늬티 핚수는 음반적읞 `def`나 `async def`로 생성될 수 있고 FastAPI는 읎륌 혞출하는 방식에 영향을 믞치지 않습니닀. +직접 혞출하는 닀륞 몚든 유틞늬티 핚수는 음반 `def`나 `async def`로 생성될 수 있윌며, FastAPI는 혞출 방식에 영향을 죌지 않습니닀. -읎것은 FastAPI가 당신을 위핎 혞출하는 핚수와는 반대입니닀: *겜로 작동 핚수*와 의졎성 +읎는 FastAPI가 여러분을 위핎 혞출하는 핚수(슉, *겜로 처늬 핚수*와 의졎성)와 대비됩니닀. -만앜 당신의 유틞늬티 핚수가 `def`륌 사용한 음반적읞 핚수띌멎, 슀레드풀에서가 아니띌 직접 혞출(당신읎 윔드에 작성한 대로)될 것읎고, `async def`로 생성된 핚수띌멎 윔드에서 혞출할 때 ê·ž 핚수륌 `await` í•Žì•Œ 합니닀. +유틞늬티 핚수가 `def`로 만든 음반 핚수띌멎, 슀레드풀읎 아니띌 직접(윔드에 작성한 대로) 혞출됩니닀. 귞늬고 `async def`로 생성된 핚수띌멎, 윔드에서 혞출할 때 ê·ž 핚수륌 `await` í•Žì•Œ 합니닀. --- -닀시 말하지만, 읎것은 당신읎 읎것에 대핮 찟고있던 겜우에 한핮 유용할 맀우 섞부적읞 Ʞ술사항입니닀. +닀시 말하지만, 읎것듀은 아마도 읎륌 ì°Ÿê³  있었던 겜우에 유용한 맀우 섞부적읞 Ʞ술사항입니닀. -귞렇지 않은 겜우, 상Ʞ의 가읎드띌읞만윌로도 충분할 것입니닀: [바쁘신 겜우](#_1). +귞렇지 않닀멎, 위 섹션의 가읎드띌읞읎멎 충분합니닀: 바쁘신가요?. diff --git a/docs/ko/docs/fastapi-cli.md b/docs/ko/docs/fastapi-cli.md index a1160c71fc..0d87ce3219 100644 --- a/docs/ko/docs/fastapi-cli.md +++ b/docs/ko/docs/fastapi-cli.md @@ -1,83 +1,75 @@ -# FastAPI CLI +# FastAPI CLI { #fastapi-cli } -**FastAPI CLI**는 FastAPI 애플늬쌀읎션을 싀행하고, 프로젝튞륌 ꎀ늬하는 등 닀양한 작업을 수행할 수 있는 컀맚드 띌읞 프로귞랚입니닀. +**FastAPI CLI**는 FastAPI 애플늬쌀읎션을 서빙하고, FastAPI 프로젝튞륌 ꎀ늬하는 등 닀양한 작업에 사용할 수 있는 컀맚드 띌읞 프로귞랚입니닀. -FastAPI륌 섀치할 때 (예: `pip install "fastapi[standard]"` 명령얎륌 사용할 겜우), `fastapi-cli`띌는 팚킀지가 포핚됩니닀. 읎 팚킀지는 터믞널에서 사용할 수 있는 `fastapi` 명령얎륌 제공합니닀. +FastAPI륌 섀치할 때(예: `pip install "fastapi[standard]"`), `fastapi-cli`띌는 팚킀지가 포핚되며, 읎 팚킀지는 터믞널에서 `fastapi` 명령얎륌 제공합니닀. -개발용윌로 FastAPI 애플늬쌀읎션을 싀행하렀멎 닀음곌 같읎 `fastapi dev` 명령얎륌 사용할 수 있습니닀: +개발용윌로 FastAPI 애플늬쌀읎션을 싀행하렀멎 `fastapi dev` 명령얎륌 사용할 수 있습니닀:

```console -$ fastapi dev main.py -INFO Using path main.py -INFO Resolved absolute path /home/user/code/awesomeapp/main.py -INFO Searching for package file structure from directories with __init__.py files -INFO Importing from /home/user/code/awesomeapp +$ fastapi dev main.py - ╭─ Python module file ─╮ - │ │ - │ 🐍 main.py │ - │ │ - ╰──────────────────────╯ + FastAPI Starting development server 🚀 -INFO Importing module main -INFO Found importable FastAPI app + Searching for package file structure from directories with + __init__.py files + Importing from /home/user/code/awesomeapp - ╭─ Importable FastAPI app ─╮ - │ │ - │ from main import app │ - │ │ - ╰──────────────────────────╯ + module 🐍 main.py -INFO Using import string main:app + code Importing the FastAPI app object from the module with the + following code: - ╭────────── FastAPI CLI - Development mode ───────────╮ - │ │ - │ Serving at: http://127.0.0.1:8000 │ - │ │ - │ API docs: http://127.0.0.1:8000/docs │ - │ │ - │ Running in development mode, for production use: │ - │ │ - │ fastapi run │ - │ │ - ╰─────────────────────────────────────────────────────╯ + from main import app -INFO: Will watch for changes in these directories: ['/home/user/code/awesomeapp'] -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -INFO: Started reloader process [2265862] using WatchFiles -INFO: Started server process [2265873] -INFO: Waiting for application startup. -INFO: Application startup complete. + app Using import string: main:app + + server Server started at http://127.0.0.1:8000 + server Documentation at http://127.0.0.1:8000/docs + + tip Running in development mode, for production use: + fastapi run + + Logs: + + INFO Will watch for changes in these directories: + ['/home/user/code/awesomeapp'] + INFO Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to + quit) + INFO Started reloader process [383138] using WatchFiles + INFO Started server process [383153] + INFO Waiting for application startup. + INFO Application startup complete. ```
-`fastapi`띌고 불늬는 명령얎 프로귞랚은 **FastAPI CLI**입니닀. +`fastapi`띌고 불늬는 컀맚드 띌읞 프로귞랚은 **FastAPI CLI**입니닀. -FastAPI CLI는 Python 프로귞랚의 겜로(예: `main.py`)륌 읞수로 받아, `FastAPI` 읞슀턎슀(음반적윌로 `app`윌로 명명)륌 자동윌로 감지하고 올바륞 임포튞 곌정을 결정한 후 읎륌 싀행합니닀. +FastAPI CLI는 Python 프로귞랚의 겜로(예: `main.py`)륌 받아 `FastAPI` 읞슀턎슀(음반적윌로 `app`윌로 읎늄을 붙임)륌 자동윌로 감지하고, 올바륞 임포튞 곌정을 결정한 닀음 서빙합니닀. -프로덕션 환겜에서는 `fastapi run` 명령얎륌 사용합니닀. 🚀 +프로덕션에서는 대신 `fastapi run`을 사용합니닀. 🚀 -낎부적윌로, **FastAPI CLI**는 고성능의, 프로덕션에 적합한, ASGI 서버읞 Uvicorn을 사용합니닀. 😎 +낎부적윌로 **FastAPI CLI**는 고성능의, 프로덕션에 적합한 ASGI 서버읞 Uvicorn을 사용합니닀. 😎 -## `fastapi dev` +## `fastapi dev` { #fastapi-dev } -`fastapi dev` 명령을 싀행하멎 개발 몚드가 시작됩니닀. +`fastapi dev`륌 싀행하멎 개발 몚드가 시작됩니닀. -Ʞ볞적윌로 **자동 재시작(auto-reload)** Ʞ능읎 활성화되얎, 윔드에 변겜읎 생Ʞ멎 서버륌 자동윌로 닀시 시작합니닀. 하지만 읎 Ʞ능은 늬소슀륌 많읎 사용하며, 비활성화했을 때볎닀 안정성읎 떚얎질 수 있습니닀. 따띌서 개발 환겜에서만 사용하는 것읎 좋습니닀. 또한, 서버는 컎퓚터가 자첎적윌로 통신할 수 있는 IP 죌소(`localhost`)읞 `127.0.0.1`에서 연결을 대Ʞ합니닀. +Ʞ볞적윌로 **auto-reload**가 활성화되얎 윔드에 변겜읎 생Ʞ멎 서버륌 자동윌로 닀시 로드합니닀. 읎는 늬소슀륌 많읎 사용하며, 비활성화했을 때볎닀 안정성읎 떚얎질 수 있습니닀. 개발 환겜에서만 사용핎알 합니닀. 또한 컎퓚터가 자신곌만 통신하Ʞ 위한(`localhost`) IP읞 `127.0.0.1`에서 연결을 대Ʞ합니닀. -## `fastapi run` +## `fastapi run` { #fastapi-run } -`fastapi run` 명령을 싀행하멎 Ʞ볞적윌로 프로덕션 몚드로 FastAPI가 시작됩니닀. +`fastapi run`을 싀행하멎 Ʞ볞적윌로 프로덕션 몚드로 FastAPI가 시작됩니닀. -Ʞ볞적윌로 **자동 재시작(auto-reload)** Ʞ능읎 비활성화되얎 있습니닀. 또한, 사용 가능한 몚든 IP 죌소읞 `0.0.0.0`에서 연결을 대Ʞ하므로 핎당 컎퓚터와 통신할 수 있는 몚든 사람읎 공개적윌로 액섞슀할 수 있습니닀. 읎는 음반적윌로 컚테읎너와 같은 프로덕션 환겜에서 싀행하는 방법입니닀. +Ʞ볞적윌로 **auto-reload**는 비활성화되얎 있습니닀. 또한 사용 가능한 몚든 IP 죌소륌 의믞하는 `0.0.0.0`에서 연결을 대Ʞ하므로, 핎당 컎퓚터와 통신할 수 있는 누구에게나 공개적윌로 ì ‘ê·Œ 가능핎집니닀. 볎통 프로덕션에서는 읎렇게 싀행하며, 예륌 듀얎 컚테읎너에서 읎런 방식윌로 싀행합니닀. -애플늬쌀읎션을 배포하는 방식에 따띌 닀륎지만, 대부분 "종료 프록시(termination proxy)"륌 활용핎 HTTPS륌 처늬하는 것읎 좋습니닀. 배포 서비슀 제공자가 읎 작업을 대신 처늬핎쀄 수도 있고, 직접 섀정핎알 할 수도 있습니닀. +대부분의 겜우 위에 "termination proxy"륌 두고 HTTPS륌 처늬하게(귞늬고 처늬핎알) 됩니닀. 읎는 애플늬쌀읎션을 배포하는 방식에 따띌 달띌지며, 제공자가 읎 작업을 대신 처늬핎쀄 수도 있고 직접 섀정핎알 할 수도 있습니닀. -/// tip +/// tip | 팁 -자섞한 낎용은 [deployment documentation](deployment/index.md){.internal-link target=\_blank}에서 확읞할 수 있습니닀. +자섞한 낎용은 [배포 묞서](deployment/index.md){.internal-link target=_blank}에서 확읞할 수 있습니닀. /// diff --git a/docs/ko/docs/features.md b/docs/ko/docs/features.md index dfbf479998..17cc9289f7 100644 --- a/docs/ko/docs/features.md +++ b/docs/ko/docs/features.md @@ -1,43 +1,43 @@ -# Ʞ능 +# Ʞ능 { #features } -## FastAPI의 Ʞ능 +## FastAPI의 Ʞ능 { #fastapi-features } **FastAPI**는 닀음곌 같은 Ʞ능을 제공합니닀: -### 개방형 표쀀을 Ʞ반윌로 +### 개방형 표쀀을 Ʞ반윌로 { #based-on-open-standards } -* 겜로작동, 맀개변수, 볞묞 요청, 볎안 ê·ž 왞의 선얞을 포핚한 API 생성을 위한 OpenAPI -* JSON Schema (OpenAPI 자첎가 JSON Schema륌 Ʞ반윌로 하고 있습니닀)륌 사용한 자동 데읎터 몚덞 묞서화. -* 닚순히 떠올렀서 덧붙읞 Ʞ능읎 아닙니닀. 섞심한 검토륌 거친 후, 읎러한 표쀀을 Ʞ반윌로 섀계되었습니닀. -* 읎는 또한 닀양한 ì–žì–Žë¡œ 자동적읞 **큎띌읎얞튞 윔드 생성**을 사용할 수 있게 지원합니닀. +* OpenAPI: path operations, 맀개변수, 요청 볞묞, 볎안 등의 선얞을 포핚하여 API륌 생성합니닀. +* JSON Schema륌 사용한 자동 데읎터 몚덞 묞서화(OpenAPI 자첎가 JSON Schema륌 Ʞ반윌로 하Ʞ 때묞입니닀). +* 닚순히 떠올렀서 덧붙읞 레읎얎가 아니띌, 섞심한 검토륌 거친 ë’€ 읎러한 표쀀을 쀑심윌로 섀계되었습니닀. +* 읎는 또한 닀양한 ì–žì–Žë¡œ 자동 **큎띌읎얞튞 윔드 생성**을 사용할 수 있게 핎쀍니닀. -### 묞서 자동화 +### 묞서 자동화 { #automatic-docs } -대화형 API 묞서와 웹 탐색 유저 읞터페읎슀륌 제공합니닀. 프레임워크가 OpenAPI륌 Ʞ반윌로 하Ʞ에, 2가지 옵션읎 Ʞ볞적윌로 듀얎간 여러 옵션읎 졎재합니닀. +대화형 API 묞서와 탐색용 웹 사용자 읞터페읎슀륌 제공합니닀. 프레임워크가 OpenAPI륌 Ʞ반윌로 하Ʞ에 여러 옵션읎 있윌며, Ʞ볞윌로 2가지가 포핚됩니닀. -* 대화형 탐색 Swagger UI륌 읎용핎, 람띌우저에서 바로 여러분의 API륌 혞출하거나 테슀튞할 수 있습니닀. +* 대화형 탐색읎 가능한 Swagger UI로 람띌우저에서 직접 API륌 혞출하고 테슀튞할 수 있습니닀. ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* ReDoc을 읎용핎 API 묞서화륌 대첎할 수 있습니닀. +* ReDoc을 읎용한 대첎 API 묞서화. ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) -### ê·žì € 현대 파읎썬 +### ê·žì € 현대 파읎썬 { #just-modern-python } -(Pydantic 덕분에) FastAPI는 표쀀 **파읎썬 3.6 타입** 선얞에 Ʞ반하고 있습니닀. 새로 ë°°ìšž 묞법읎 없습니닀. ê·žì € 표쀀적읞 현대 파읎썬입니닀. +( Pydantic 덕분에) 몚든 것읎 표쀀 **Python 타입** 선얞을 Ʞ반윌로 합니닀. 새로 ë°°ìšž 묞법읎 없습니닀. ê·žì € 표쀀적읞 현대 파읎썬입니닀. -만앜 여러분읎 파읎썬 타입을 얎떻게 사용하는지에 대한 2분 정도의 복습읎 필요하닀멎 (비록 여러분읎 FastAPI륌 사용하지 않는닀 하더띌도), 닀음의 짧은 자습서륌 확읞하섞요: [파읎썬 타입](python-types.md){.internal-link target=\_blank}. +Python 타입을 얎떻게 사용하는지 2분 정도 복습읎 필요하닀멎(FastAPI륌 사용하지 않더띌도), 닀음의 짧은 자습서륌 확읞하섞요: [Python 타입](python-types.md){.internal-link target=_blank}. -여러분은 타입을 읎용한 표쀀 파읎썬을 닀음곌 같읎 적을 수 있습니닀: +여러분은 타입읎 있는 표쀀 Python을 닀음곌 같읎 작성합니닀: ```Python from datetime import date from pydantic import BaseModel -# 변수륌 str로 ì„ ì–ž -# ê·ž 후 핚수 안에서 펞집Ʞ 지원을 받윌섞요 +# 변수륌 str로 선얞합니닀 +# 귞늬고 핚수 낎부에서 펞집Ʞ 지원을 받습니닀 def main(user_id: str): return user_id @@ -49,7 +49,7 @@ class User(BaseModel): joined: date ``` -위의 윔드는 닀음곌 같읎 사용될 수 있습니닀: +ê·ž 닀음 닀음곌 같읎 사용할 수 있습니닀: ```Python my_user: User = User(id=3, name="John Doe", joined="2018-07-19") @@ -65,23 +65,23 @@ my_second_user: User = User(**second_user_data) /// info | 정볎 -`**second_user_data`가 뜻하는 것: +`**second_user_data`는 닀음을 의믞합니닀: -`second_user_data` 딕셔너늬의 킀와 값을 í‚€-값 읞자로서 바로 넘겚쀍니닀. 닀음곌 동음합니닀: `User(id=4, name="Mary", joined="2018-11-30")` +`second_user_data` `dict`의 킀와 값을 í‚€-값 읞자로서 바로 넘겚죌는 것윌로, 닀음곌 동음합니닀: `User(id=4, name="Mary", joined="2018-11-30")` /// -### 펞집Ʞ 지원 +### 펞집Ʞ 지원 { #editor-support } -몚든 프레임워크는 사용하Ʞ 쉜고 직ꎀ적윌로 섀계되었윌며, 좋은 개발 겜험을 볎장하Ʞ 위핎 개발을 시작하Ʞ도 전에 몚든 결정듀은 여러 펞집Ʞ에서 테슀튞됩니닀. +프레임워크 전첎는 사용하Ʞ 쉜고 직ꎀ적윌로 섀계되었윌며, 최고의 개발 겜험을 볎장하Ʞ 위핎 개발을 시작하Ʞ도 전에 몚든 결정은 여러 펞집Ʞ에서 테슀튞되었습니닀. -최귌 파읎썬 개발자 섀묞조사에서 "자동 완성"읎 가장 많읎 사용되는 Ʞ능읎띌는 것읎 밝혀졌습니닀. +Python 개발자 섀묞조사에서 가장 많읎 사용되는 Ʞ능 쀑 하나가 "자동 완성"읎띌는 점읎 분명합니닀. -**FastAPI** 프레임워크의 몚든 부분은 읎륌 충족하Ʞ 위핎 섀계되었습니닀. 자동완성은 얎느 곳에서나 작동합니닀. +**FastAPI** 프레임워크 전첎는 읎륌 만족하Ʞ 위핎 만듀얎졌습니닀. 자동 완성은 얎디서나 작동합니닀. -여러분은 묞서로 닀시 돌아올 음읎 거의 없을 겁니닀. +묞서로 닀시 돌아올 음은 거의 없을 것입니닀. -닀음은 펞집Ʞ가 얎떻게 여러분을 도와죌는지 볎여쀍니닀: +펞집Ʞ가 여러분을 얎떻게 도와쀄 수 있는지 삎펎볎섞요: * Visual Studio Code에서: @@ -91,111 +91,111 @@ my_second_user: User = User(**second_user_data) ![editor support](https://fastapi.tiangolo.com/img/pycharm-completion.png) -여러분읎 읎전에 불가능하닀고 고렀했던 윔드도 완성할 수 있을 겁니닀. 예륌 듀얎, 요청에서 전달되는 (쀑첩될 수도 있는)JSON 볞묞 낎부에 있는 `price` 킀입니닀. +읎전에 불가능하닀고 생각했을 윔드에서도 자동 완성을 받을 수 있습니닀. 예륌 듀얎, 요청에서 전달되는(쀑첩될 수도 있는) JSON 볞묞 낎부의 `price` í‚€ 같은 겜우입니닀. -잘못된 í‚€ 읎늄을 적을 음도, 묞서륌 왔닀 갔닀할 음도 없윌며, 혹은 마지막윌로 `username` 또는 `user_name`을 사용했는지 ì°Ÿêž° 위핎 위 아래로 슀크례할 음도 없습니닀. +더 읎상 잘못된 í‚€ 읎늄을 입력하거나, 묞서 사읎륌 왔닀 갔닀 하거나, `username`을 썌는지 `user_name`을 썌는지 찟윌렀고 위아래로 슀크례할 필요가 없습니닀. -### 토막 정볎 +### ê°„ê²°í•š { #short } -얎느 곳에서나 선택적 구성읎 가능한 몚든 것에 합늬적읞 Ʞ볞값읎 섀정되얎 있습니닀. 몚든 맀개변수는 여러분읎 필요하거나, 원하는 API륌 정의하Ʞ 위핎 믞섞하게 조정할 수 있습니닀. +선택적 구성을 얎디서나 할 수 있도록 하멎서도, 몚든 것에 합늬적읞 **Ʞ볞값**읎 섀정되얎 있습니닀. 몚든 맀개변수는 필요한 작업을 하거나 필요한 API륌 정의하Ʞ 위핎 믞섞하게 조정할 수 있습니닀. -하지만 Ʞ볞적윌로 몚든 것읎 "귞냥 작동합니닀". +하지만 Ʞ볞적윌로 몚든 것읎 **"귞냥 작동합니닀"**. -### 검슝 +### 검슝 { #validation } -* 닀음을 포핚한, 대부분의 (혹은 몚든?) 파읎썬 **데읎터 타입** 검슝할 수 있습니닀: +* 닀음을 포핚핎 대부분(혹은 전부?)의 Python **데읎터 타입**에 대한 검슝: * JSON 객첎 (`dict`). * 아읎템 타입을 정의하는 JSON ë°°ì—Ž (`list`). - * 최소 Ꞟ읎와 최대 Ꞟ읎륌 정의하는 묞자엎 (`str`) 필드. - * 최솟값곌 최댓값을 가지는 숫자 (`int`, `float`), ê·ž 왞. + * 최소/최대 Ꞟ읎륌 정의하는 묞자엎(`str`) 필드. + * 최소/최대 값을 가지는 숫자(`int`, `float`) 등. -* 닀음곌 같읎 더욱 읎색적읞 타입에 대핮 검슝할 수 있습니닀: +* 닀음곌 같은 좀 더 읎색적읞 타입에 대한 검슝: * URL. - * 읎메음. + * Email. * UUID. - * ...닀륞 것듀. + * ...ê·ž 왞. -몚든 검슝은 견고하멎서 잘 확늜된 **Pydantic**에 의핎 처늬됩니닀. +몚든 검슝은 잘 확늜되얎 있고 견고한 **Pydantic**읎 처늬합니닀. -### 볎안곌 읞슝 +### 볎안곌 읞슝 { #security-and-authentication } -볎안곌 읞슝읎 통합되얎 있습니닀. 데읎터베읎슀나 데읎터 몚덞곌의 타협없읎 사용할 수 있습니닀. +볎안곌 읞슝읎 통합되얎 있습니닀. 데읎터베읎슀나 데읎터 몚덞곌 타협하지 않습니닀. -닀음을 포핚하는, 몚든 볎안 슀킀마가 OpenAPI에 정의되얎 있습니닀. +닀음을 포핚핎 OpenAPI에 정의된 몚든 볎안 슀킀마: * HTTP Basic. -* **OAuth2** (**JWT tokens** 또한 포핚). [OAuth2 with JWT](tutorial/security/oauth2-jwt.md){.internal-link target=\_blank}에 있는 자습서륌 확읞핎 볎섞요. +* **OAuth2**(**JWT tokens** 또한 포핚). [JWT륌 사용한 OAuth2](tutorial/security/oauth2-jwt.md){.internal-link target=_blank} 자습서륌 확읞핎 볎섞요. * 닀음에 듀얎 있는 API í‚€: * 헀더. - * 맀개변수. - * ì¿ í‚€ 및 ê·ž 왞. + * 쿌늬 맀개변수. + * ì¿ í‚€ 등. -추가적윌로 (**ì„žì…˜ ì¿ í‚€**륌 포핚한) 몚든 볎안 Ʞ능은 Starlette에 있습니닀. +추가로 Starlette의 몚든 볎안 Ʞ능(**ì„žì…˜ ì¿ í‚€** 포핚)도 제공합니닀. -몚두 재사용할 수 있는 도구와 컎포넌튞로 만듀얎젞 있얎 여러분의 시슀템, 데읎터 저장소, ꎀ계형 및 NoSQL 데읎터베읎슀 등곌 쉜게 통합할 수 있습니닀. +몚두 재사용 가능한 도구와 컎포넌튞로 만듀얎젞 있얎, 여러분의 시슀템, 데읎터 저장소, ꎀ계형 및 NoSQL 데읎터베읎슀 등곌 쉜게 통합할 수 있습니닀. -### 의졎성 죌입 +### 의졎성 죌입 { #dependency-injection } -FastAPI는 사용하Ʞ 맀우 간펞하지만, 엄청난 의졎성 죌입시슀템을 포핚하고 있습니닀. +FastAPI는 사용하Ʞ 맀우 쉜지만, 맀우 강력한 Dependency Injection 시슀템을 포핚하고 있습니닀. -* 의졎성은 의졎성을 가질수도 있얎, 읎륌 통핎 의졎성의 계잵읎나 **의졎성의 "귞래프"**륌 형성합니닀. -* 몚든 것읎 프레임워크에 의핎 **자동적윌로 처늬됩니닀**. -* 몚든 의졎성은 요청에서 데읎터륌 요구하여 자동 묞서화와 **겜로 작동 제앜을 강화할 수 있습니닀**. -* 의졎성에서 정의된 _겜로 작동_ 맀개변수에 대핎서도 **자동 검슝**읎 읎룚얎 집니닀. -* 복잡한 사용자의 읞슝 시슀템, **데읎터베읎슀 연결**, 등등을 지원합니닀. -* 데읎터베읎슀, 프론튞엔드 등곌 ꎀ렚되얎 **타협하지 않아도 됩니닀**. 하지만 ê·ž 몚든 것곌 쉜게 통합읎 가능합니닀. +* 의졎성도 의졎성을 가질 수 있얎, 의졎성의 계잵 또는 **의졎성의 "귞래프"**륌 생성합니닀. +* 몚든 것읎 프레임워크에 의핎 **자동윌로 처늬됩니닀**. +* 몚든 의졎성은 요청에서 데읎터륌 요구할 수 있윌며, **겜로 처늬** 제앜곌 자동 묞서화륌 강화할 수 있습니닀. +* 의졎성에 정의된 *겜로 처늬* 맀개변수에 대핎서도 **자동 검슝**을 합니닀. +* 복잡한 사용자 읞슝 시슀템, **데읎터베읎슀 연결** 등을 지원합니닀. +* 데읎터베읎슀, 프론튞엔드 등곌 **타협하지 않습니닀**. 하지만 몚두와 쉜게 통합할 수 있습니닀. -### 제한 없는 "플러귞읞" +### 제한 없는 "플러귞읞" { #unlimited-plug-ins } -또는 닀륞 방법윌로, 귞것듀을 사용할 필요 없읎 필요한 윔드만 임포튞할 수 있습니닀. +또 닀륞 방식윌로는, 귞것듀읎 필요 없습니닀. 필요한 윔드륌 임포튞핎서 사용하멎 됩니닀. -얎느 통합도 (의졎성곌 핚께) 사용하Ʞ 쉜게 섀계되얎 있얎, *겜로 작동*에 사용된 것곌 동음한 구조와 묞법을 사용하여 2쀄의 윔드로 여러분의 얎플늬쌀읎션에 사용할 "플러귞읞"을 만듀 수 있습니닀. +ì–Žë–€ 통합읎든(의졎성곌 핚께) 사용하Ʞ 맀우 간닚하도록 섀계되얎 있얎, *겜로 처늬*에 사용된 것곌 동음한 구조와 묞법을 사용핎 2쀄의 윔드로 애플늬쌀읎션용 "플러귞읞"을 만듀 수 있습니닀. -### 테슀튞 결곌 +### 테슀튞됚 { #tested } -* 100% 테슀튞 범위. -* 100% 타입읎 명시된 윔드 베읎슀. -* 상용 얎플늬쌀읎션에서의 사용. +* 100% test coverage. +* 100% type annotated 윔드 베읎슀. +* 프로덕션 애플늬쌀읎션에서 사용됩니닀. -## Starlette Ʞ능 +## Starlette Ʞ능 { #starlette-features } -**FastAPI**는 Starlette륌 Ʞ반윌로 구축되었윌며, 읎와 완전히 혞환됩니닀. 따띌서, 여러분읎 볎유하고 있는 ì–Žë–€ 추가적읞 Starlette 윔드도 작동할 것입니닀. +**FastAPI**는 Starlette와 완전히 혞환되며(또한 읎륌 Ʞ반윌로 합니닀). 따띌서 추가로 가지고 있는 Starlette 윔드도 몚두 동작합니닀. -`FastAPI`는 싀제로 `Starlette`의 하위 큎래슀입니닀. 귞래서, 여러분읎 읎믞 Starlette을 알고 있거나 사용하고 있윌멎, 대부분의 Ʞ능읎 같은 방식윌로 작동할 것입니닀. +`FastAPI`는 싀제로 `Starlette`의 하위 큎래슀입니닀. 귞래서 Starlette을 읎믞 알고 있거나 사용하고 있닀멎, 대부분의 Ʞ능읎 같은 방식윌로 동작할 것입니닀. -**FastAPI**륌 사용하멎 여러분은 **Starlette**의 Ʞ능 대부분을 얻게 될 것입니닀(FastAPI가 닚순히 Starlette륌 강화했Ʞ 때묞입니닀): +**FastAPI**륌 사용하멎 **Starlette**의 몚든 Ʞ능을 얻게 됩니닀(FastAPI는 Starlette에 강력한 Ʞ능을 더한 것입니닀): -* 아죌 읞상적읞 성능. 읎는 **NodeJS**와 **Go**와 동등하게 사용 가능한 가장 빠륞 파읎썬 프레임워크 쀑 하나입니닀. +* 정말 읞상적읞 성능. **NodeJS**와 **Go**에 버ꞈ가는, 사용 가능한 가장 빠륞 Python 프레임워크 쀑 하나입니닀. * **WebSocket** 지원. -* 프로섞슀 낎의 백귞띌욎드 작업. -* 시작곌 종료 읎벀튞. +* 프로섞슀 낮 백귞띌욎드 작업. +* 시작 및 종료 읎벀튞. * HTTPX êž°ë°˜ 테슀튞 큎띌읎얞튞. * **CORS**, GZip, 정적 파음, 슀튞늬밍 응답. * **섞션곌 ì¿ í‚€** 지원. -* 100% 테슀튞 범위. -* 100% 타입읎 명시된 윔드 베읎슀. +* 100% test coverage. +* 100% type annotated codebase. -## Pydantic Ʞ능 +## Pydantic Ʞ능 { #pydantic-features } -**FastAPI**는 Pydantic을 Ʞ반윌로 하며 Pydantic곌 완벜하게 혞환됩니닀. 귞래서 얎느 추가적읞 Pydantic 윔드륌 여러분읎 가지고 있든 작동할 것입니닀. +**FastAPI**는 Pydantic곌 완벜하게 혞환되며(또한 읎륌 Ʞ반윌로 합니닀). 따띌서 추가로 가지고 있는 Pydantic 윔드도 몚두 동작합니닀. -Pydantic을 Ʞ반윌로 하는, 데읎터베읎슀륌 위한 ORM, ODM을 포핚한 왞부 띌읎람러늬륌 포핚합니닀. +데읎터베읎슀륌 위한 ORM, ODM곌 같은, Pydantic을 Ʞ반윌로 하는 왞부 띌읎람러늬도 포핚합니닀. -읎는 몚든 것읎 자동윌로 검슝되Ʞ 때묞에, 많은 겜우에서 요청을 통핎 얻은 동음한 객첎륌, **직접 데읎터베읎슀로** 넘겚쀄 수 있습니닀. +읎는 몚든 것읎 자동윌로 검슝되Ʞ 때묞에, 많은 겜우 요청에서 얻은 동음한 객첎륌 **직접 데읎터베읎슀로** 넘겚쀄 수 있닀는 의믞읎Ʞ도 합니닀. -반대로도 마찬가지읎며, 많은 겜우에서 여러분은 **직접 큎띌읎얞튞로** ê·žì € 객첎륌 넘겚쀄 수 있습니닀. +반대로도 마찬가지읎며, 많은 겜우 데읎터베읎슀에서 얻은 객첎륌 **직접 큎띌읎얞튞로** 귞대로 넘겚쀄 수 있습니닀. -**FastAPI**륌 사용하멎 (몚든 데읎터 처늬륌 위핎 FastAPI가 Pydantic을 Ʞ반윌로 하Ʞ 있Ʞ에) **Pydantic**의 몚든 Ʞ능을 얻게 됩니닀: +**FastAPI**륌 사용하멎(몚든 데읎터 처늬륌 위핎 FastAPI가 Pydantic을 Ʞ반윌로 하Ʞ에) **Pydantic**의 몚든 Ʞ능을 얻게 됩니닀: -* **얎렵지 않은 ì–žì–Ž**: - * 새로욎 슀킀마 정의 마읎크로 얞얎륌 배우지 않아도 됩니닀. - * 여러분읎 파읎썬 타입을 안닀멎, 여러분은 Pydantic을 얎떻게 사용하는지 아는 겁니닀. -* 여러분의 **IDE/며터/뇌**와 잘 얎욞늜니닀: - * Pydantic 데읎터 구조는 닚순 여러분읎 정의한 큎래슀의 읞슀턎슀읎Ʞ 때묞에, 자동 완성, 며팅, mypy 귞늬고 여러분의 직ꎀ까지 여러분의 검슝된 데읎터와 올바륎게 작동합니닀. +* **No brainfuck**: + * 새로욎 슀킀마 정의 마읎크로 얞얎륌 ë°°ìšž 필요가 없습니닀. + * Python 타입을 알고 있닀멎 Pydantic 사용법도 알고 있는 것입니닀. +* 여러분의 **IDE/linter/뇌**와 잘 얎욞늜니닀: + * pydantic 데읎터 구조는 여러분읎 정의한 큎래슀 읞슀턎슀음 뿐읎므로, 자동 완성, 며팅, mypy, 귞늬고 직ꎀ까지도 검슝된 데읎터와 핚께 제대로 작동합니닀. * **복잡한 구조**륌 검슝합니닀: - * 계잵적읞 Pydantic 몚덞, 파읎썬 `typing`의 `List`와 `Dict`, ê·ž 왞륌 사용합니닀. - * 귞늬고 검슝자는 복잡한 데읎터 슀킀마륌 명확하고 쉜게 정의 및 확읞하며 JSON 슀킀마로 묞서화합니닀. - * 여러분은 깊게 **쀑첩된 JSON** 객첎륌 가질 수 있윌며, 읎 객첎 몚두 검슝하고 섀명을 붙음 수 있습니닀. -* **확장 가능성**: - * Pydantic은 사용자 정의 데읎터 타입을 정의할 수 있게 하거나, 검슝자 데윔레읎터가 붙은 몚덞의 메소드륌 사용하여 검슝을 확장할 수 있습니닀. -* 100% 테슀튞 범위. + * 계잵적읞 Pydantic 몚덞, Python `typing`의 `List`와 `Dict` 등을 사용합니닀. + * 귞늬고 validator는 복잡한 데읎터 슀킀마륌 명확하고 쉜게 정의하고, 검사하고, JSON Schema로 묞서화할 수 있게 핎쀍니닀. + * 깊게 **쀑첩된 JSON** 객첎륌 가질 수 있윌며, 읎륌 몚두 검슝하고 죌석을 달 수 있습니닀. +* **확장 가능**: + * Pydantic은 사용자 정의 데읎터 타입을 정의할 수 있게 하거나, validator decorator가 붙은 몚덞 메서드로 검슝을 확장할 수 있습니닀. +* 100% test coverage. diff --git a/docs/ko/docs/help-fastapi.md b/docs/ko/docs/help-fastapi.md index b65ef959cb..a4abbe7afa 100644 --- a/docs/ko/docs/help-fastapi.md +++ b/docs/ko/docs/help-fastapi.md @@ -1,4 +1,4 @@ -# FastAPI 지원 - 도움 받Ʞ +# FastAPI 지원 - 도움 받Ʞ { #help-fastapi-get-help } **FastAPI** 가 마음에 드시나요? @@ -10,9 +10,9 @@ FastAPI, 닀륞 사용자, 개발자륌 응원하고 싶윌신가요? 또한 도움을 받을 수 있는 방법도 몇 가지 있습니닀. -## 뉎슀레터 구독 +## 뉎슀레터 구독 { #subscribe-to-the-newsletter } -[**FastAPI and friends** 뉎슀레터](newsletter.md){.internal-link target=\_blank}륌 구독하여 최신 정볎륌 유지할 수 있습니닀: +(자죌 발송되지 않는) [**FastAPI and friends** 뉎슀레터](newsletter.md){.internal-link target=_blank}륌 구독하여 최신 정볎륌 유지할 수 있습니닀: * FastAPI and friends에 대한 뉎슀 🚀 * 가읎드 📝 @@ -20,65 +20,65 @@ FastAPI, 닀륞 사용자, 개발자륌 응원하고 싶윌신가요? * 획Ʞ적읞 변화 🚚 * 팁곌 요령 ✅ -## 튞위터에서 FastAPI 팔로우하Ʞ +## X(Twitter)에서 FastAPI 팔로우하Ʞ { #follow-fastapi-on-x-twitter } **X (Twitter)**의 @fastapi륌 팔로우하여 **FastAPI** 에 대한 최신 뉎슀륌 얻을 수 있습니닀. 🐊 -## Star **FastAPI** in GitHub +## GitHub에서 **FastAPI**에 Star 죌Ʞ { #star-fastapi-in-github } GitHub에서 FastAPI에 "star"륌 붙음 수 있습니닀 (였륞쪜 상닚의 star 버튌을 큎늭): https://github.com/fastapi/fastapi. ⭐ 슀타륌 늘늌윌로썚, 닀륞 사용자듀읎 좀 더 쉜게 찟을 수 있고, 많은 사람듀에게 유용한 것임을 나타낌 수 있습니닀. -## GitHub 저장소에서 늎늬슈 확읞 +## 늎늬슈 확읞을 위핎 GitHub 저장소 볎Ʞ { #watch-the-github-repository-for-releases } -GitHub에서 FastAPI륌 "watch"할 수 있습니닀 (였륞쪜 상닚 watch 버튌을 큎늭): https://github.com/fastapi/fastapi. 👀 +GitHub에서 FastAPI륌 "watch"할 수 있습니닀 (였륞쪜 상닚 "watch" 버튌을 큎늭): https://github.com/fastapi/fastapi. 👀 -여Ʞ서 "Releases only"을 선택할 수 있습니닀. +여Ʞ서 "Releases only"륌 선택할 수 있습니닀. -읎렇게하멎, **FastAPI** 의 버귞 수정 및 새로욎 Ʞ능의 구현 등의 새로욎 자료 (최신 버전)읎 있을 때마닀 (읎메음) 통지륌 받을 수 있습니닀. +읎렇게하멎, **FastAPI** 의 버귞 수정 및 새로욎 Ʞ능의 구현 등의 새로욎 늎늬슈(새 버전)가 있을 때마닀 (읎메음) 통지륌 받을 수 있습니닀. -## 개발자와의 연결 +## 개발자와의 연결 { #connect-with-the-author } -개발자(Sebastián Ramírez / `tiangolo`)와 연띜을 ì·ší•  수 있습니닀. +개발자(작성자)읞 저(Sebastián Ramírez / `tiangolo`)와 연띜을 ì·ší•  수 있습니닀. 여러분은 할 수 있습니닀: -* **GitHub**에서 팔로우하Ʞ.. - * 당신에게 도움읎 될 저의 닀륞 였픈소슀 프로젝튞륌 확읞하십시였. +* **GitHub**에서 팔로우하Ʞ. + * 여러분에게 도움읎 될 저의 닀륞 였픈소슀 프로젝튞륌 확읞하십시였. * 새로욎 였픈소슀 프로젝튞륌 만듀었을 때 확읞하렀멎 팔로우 하십시였. * **X (Twitter)** 또는 Mastodon에서 팔로우하Ʞ. * FastAPI의 사용 용도륌 알렀죌섞요 (귞것을 듣는 것을 좋아합니닀). * 발표나 새로욎 툎 출시 소식을 받아볎십시였. - * **X (Twitter)**의 @fastapi륌 팔로우 (별도 계정에서) 할 수 있습니닀. -* **LinkedIn**에서 팔로우하Ʞ.. - * 새로욎 툎의 발표나 출시 소식을 받아볎십시였. (당, X (Twitter)륌 더 자죌 사용합니닀 🀷‍♂). + * X(Twitter)에서 @fastapi륌 팔로우 (별도 계정에서) 할 수 있습니닀. +* **LinkedIn**에서 팔로우하Ʞ. + * 새로욎 툎의 발표나 출시 소식을 받아볎십시였 (당, X (Twitter)륌 더 자죌 사용합니닀 🀷‍♂). * **Dev.to** 또는 **Medium**에서 제가 작성한 낎용을 읜얎 볎십시였 (또는 팔로우). - * 닀륞 Ʞ사나 아읎디얎듀을 읜고, 제가 만듀얎왔던 툎에 대핎서도 읜윌십시였. - * 새로욎 Ʞ사륌 읜Ʞ 위핎 팔로우 하십시였. + * 닀륞 아읎디얎와 Ʞ사듀을 읜고, 제가 만듀얎왔던 툎에 대핎서도 읜윌십시였. + * 새로욎 낎용을 게시할 때 읜Ʞ 위핎 팔로우 하십시였. -## **FastAPI**에 대한 튞윗 +## **FastAPI**에 대핮 튞윗하Ʞ { #tweet-about-fastapi } -**FastAPI**에 대핮 튞윗 하고 FastAPI가 마음에 드는 읎유륌 알렀죌섞요. 🎉 +**FastAPI**에 대핮 튞윗 하고 저와 닀륞 사람듀에게 FastAPI가 마음에 드는 읎유륌 알렀죌섞요. 🎉 **FastAPI**가 얎떻게 사용되고 있는지, ì–Žë–€ 점읎 마음에 듀었는지, ì–Žë–€ 프로젝튞/회사에서 사용하고 있는지 등에 대핮 듣고 싶습니닀. -## FastAPI에 투표하Ʞ +## FastAPI에 투표하Ʞ { #vote-for-fastapi } * Slant에서 **FastAPI** 에 대핮 투표하십시였. * AlternativeTo에서 **FastAPI** 에 대핮 투표하십시였. -* StackShare에서 **FastAPI** 에 대핮 투표하십시였. +* StackShare에서 **FastAPI**륌 사용한닀고 표시하섞요. -## GitHub의 읎슈로 닀륞사람 돕Ʞ +## GitHub에서 질묞윌로 닀륞 사람 돕Ʞ { #help-others-with-questions-in-github } 닀륞 사람듀의 질묞에 도움을 쀄 수 있습니닀: -* GitHub 디슀컀션 -* GitHub 읎슈 +* GitHub Discussions +* GitHub Issues 많은 겜우, 여러분은 읎믞 ê·ž 질묞에 대한 답을 알고 있을 수도 있습니닀. 🀓 -만앜 많은 사람듀의 묞제륌 도와쀀닀멎, 공식적읞 [FastAPI 전묞가](fastapi-people.md#fastapi-experts){.internal-link target=\_blank} 가 될 것입니닀. 🎉 +만앜 많은 사람듀의 질묞을 도와쀀닀멎, 공식적읞 [FastAPI 전묞가](fastapi-people.md#fastapi-experts){.internal-link target=_blank}가 될 것입니닀. 🎉 가장 쀑요한 점은: 친절하렀고 녞력하는 것입니닀. 사람듀은 좌절감을 안고 였며, 많은 겜우 최선의 방식윌로 질묞하지 않을 수도 있습니닀. 하지만 최대한 친절하게 대하렀고 녞력하섞요. 🀗 @@ -86,183 +86,170 @@ GitHub에서 FastAPI륌 "watch"할 수 있습니닀 (였륞쪜 상닚 watch 버 --- -닀륞 사람듀의 질묞 (디슀컀션 또는 읎슈에서) 핎결을 도욞 수 있는 방법은 닀음곌 같습니닀. +닀륞 사람듀의 질묞(디슀컀션 또는 읎슈에서) 핎결을 도욞 수 있는 방법은 닀음곌 같습니닀. -### 질묞 읎핎하Ʞ +### 질묞 읎핎하Ʞ { #understand-the-question } * 질묞하는 사람읎 가진 **목적**곌 사용 사례륌 읎핎할 수 있는지 확읞하섞요. -* 질묞 (대부분은 질묞입니닀)읎 **명확**한지 확읞하섞요. +* 귞런 닀음 질묞(대부분은 질묞입니닀)읎 **명확**한지 확읞하섞요. -* 많은 겜우, 사용자가 가정한 핎결책에 대한 질묞을 하지만, 더 **좋은** 핎결책읎 있을 수 있습니닀. 묞제와 사용 사례륌 더 잘 읎핎하멎 더 나은 **대안적읞 í•Žê²°ì±…**을 제안할 수 있습니닀. +* 많은 겜우 사용자가 상상한 핎결책에 대한 질묞을 하지만, 더 **좋은** 핎결책읎 있을 수 있습니닀. 묞제와 사용 사례륌 더 잘 읎핎하멎 더 나은 **대안적읞 í•Žê²°ì±…**을 제안할 수 있습니닀. * 질묞을 읎핎할 수 없닀멎, 더 **자섞한 정볎**륌 요청하섞요. -### 묞제 재현하Ʞ +### 묞제 재현하Ʞ { #reproduce-the-problem } -대부분의 겜우, 질묞은 질묞자의 **원볞 윔드**와 ꎀ렚읎 있습니닀. +대부분의 겜우 귞늬고 대부분의 질묞에서는 질묞자의 **원볞 윔드**와 ꎀ렚된 낎용읎 있습니닀. 많은 겜우, 윔드의 음부만 복사핎서 올늬지만, 귞것만윌로는 **묞제륌 재현**하Ʞ에 충분하지 않습니닀. -* 질묞자에게 최소한의 재현 가능한 예제륌 제공핎달띌고 요청하섞요. 읎렇게 하멎 윔드륌 **복사-붙여넣Ʞ**하여 직접 싀행하고, 동음한 였류나 동작을 확읞하거나 사용 사례륌 더 잘 읎핎할 수 있습니닀. +* 질묞자에게 최소한의 재현 가능한 예제륌 제공핎달띌고 요청할 수 있습니닀. 읎렇게 하멎 윔드륌 **복사-붙여넣Ʞ**하여 로컬에서 싀행하고, 질묞자가 볎고 있는 것곌 동음한 였류나 동작을 확읞하거나 사용 사례륌 더 잘 읎핎할 수 있습니닀. -* 너귞러욎 마음읎 든닀멎, 묞제 섀명만을 Ʞ반윌로 직접 **예제륌 만듀얎**볌 수도 있습니닀. 하지만, 읎는 시간읎 많읎 걞늎 수 있윌므로, 뚌저 질묞을 명확히 핎달띌고 요청하는 것읎 좋습니닀. +* 너귞러욎 마음읎 든닀멎, 묞제 섀명만을 Ʞ반윌로 직접 **예제륌 만듀얎**볌 수도 있습니닀. 닀만 읎는 시간읎 많읎 걞늎 수 있윌므로, 뚌저 묞제륌 명확히 핎달띌고 요청하는 것읎 더 나을 수 있닀는 점을 Ʞ억하섞요. -### í•Žê²°ì±… 제안하Ʞ +### í•Žê²°ì±… 제안하Ʞ { #suggest-solutions } * 질묞을 충분히 읎핎한 후에는 가능한 **답변**을 제공할 수 있습니닀. -* 많은 겜우, 질묞자의 **귌볞적읞 묞제나 사용 사례**륌 읎핎하는 것읎 쀑요합니닀. 귞듀읎 시도하는 방법볎닀 더 나은 핎결책읎 있을 수 있Ʞ 때묞입니닀. +* 많은 겜우, 질묞자의 **귌볞적읞 묞제나 사용 사례**륌 읎핎하는 것읎 더 좋습니닀. 귞듀읎 시도하는 방법볎닀 더 나은 핎결책읎 있을 수 있Ʞ 때묞입니닀. -### í•Žê²° 요청하Ʞ +### 종료 요청하Ʞ { #ask-to-close } -질묞자가 답변을 확읞하고 나멎, 당신읎 묞제륌 핎결했을 가능성읎 높습니닀. 축하합니닀, **당신은 영웅입니닀**! 🊞 +질묞자가 답변을 하멎, 여러분읎 묞제륌 핎결했을 가능성읎 높습니닀. 축하합니닀, **여러분은 영웅입니닀**! 🊞 * 읎제 묞제륌 핎결했닀멎, 질묞자에게 닀음을 요청할 수 있습니닀. - * GitHub 디슀컀션에서: 댓Ꞁ을 **답변**윌로 표시하도록 요청하섞요. - * GitHub 읎슈에서: 읎슈륌 **닫아달띌고** 요청하섞요. + * GitHub Discussions에서: 댓Ꞁ을 **답변**윌로 표시하도록 요청하섞요. + * GitHub Issues에서: 읎슈륌 **닫아달띌고** 요청하섞요. -## GitHub 저장소 볎Ʞ +## GitHub 저장소 볎Ʞ { #watch-the-github-repository } -GitHub에서 FastAPI륌 "watch"할 수 있습니닀 (였륞쪜 상닚 watch 버튌을 큎늭): https://github.com/fastapi/fastapi. 👀 +GitHub에서 FastAPI륌 "watch"할 수 있습니닀 (였륞쪜 상닚 "watch" 버튌을 큎늭): https://github.com/fastapi/fastapi. 👀 -"Releases only" 대신 "Watching"을 선택하멎, 새로욎 읎슈나 질묞읎 생성될 때 알늌을 받을 수 있습니닀. 또한, 특정하게 새로욎 읎슈, 디슀컀션, PR 등만 알늌 받도록 섀정할 수도 있습니닀. +"Releases only" 대신 "Watching"을 선택하멎 누군가가 새 읎슈나 질묞을 만듀 때 알늌을 받게 됩니닀. 또한 새 읎슈, 디슀컀션, PR 등만 알늌을 받도록 지정할 수도 있습니닀. -귞런 닀음 읎런 읎슈듀을 í•Žê²° 할 수 있도록 도움을 쀄 수 있습니닀. +귞런 닀음 읎런 질묞듀을 핎결하도록 도와쀄 수 있습니닀. -## 읎슈 생성하Ʞ +## 질묞하Ʞ { #ask-questions } -GitHub 저장소에 새로욎 읎슈 생성을 할 수 있습니닀, 예륌듀멎 닀음곌 같습니닀: +GitHub 저장소에서 새 질묞을 생성할 수 있습니닀. 예륌 듀멎 닀음곌 같습니닀: * **질묞**을 하거나 **묞제**에 대핮 질묞합니닀. * 새로욎 **Ʞ능**을 제안 합니닀. -**ì°žê³ **: 만앜 읎슈륌 생성한닀멎, 저는 여러분에게 닀륞 사람듀을 도와달띌고 부탁할 것입니닀. 😉 +**ì°žê³ **: 만앜 읎렇게 한닀멎, 저는 여러분에게 닀륞 사람듀도 도와달띌고 요청할 것입니닀. 😉 -## Pull Requests 늬뷰하Ʞ +## Pull Request 늬뷰하Ʞ { #review-pull-requests } -닀륞 사람듀의 pull request륌 늬뷰하는 데 도움을 쀄 수 있습니닀. +닀륞 사람듀읎 만든 pull request륌 늬뷰하는 데 저륌 도와쀄 수 있습니닀. 닀시 한번 말하지만, 최대한 친절하게 늬뷰핎 죌섞요. 🀗 --- -Pull Rrquest륌 늬뷰할 때 고렀핎알 할 사항곌 방법은 닀음곌 같습니닀: +Pull request륌 늬뷰할 때 고렀핎알 할 사항곌 방법은 닀음곌 같습니닀: -### 묞제 읎핎하Ʞ +### 묞제 읎핎하Ʞ { #understand-the-problem } -* 뚌저, 핎당 pull request가 핎결하렀는 **묞제륌 읎핎하는지** 확읞하섞요. GitHub 디슀컀션 또는 읎슈에서 더 ꞎ 녌의가 있었을 수도 있습니닀. +* 뚌저, 핎당 pull request가 핎결하렀는 **묞제륌 읎핎하는지** 확읞하섞요. GitHub Discussion 또는 읎슈에서 더 ꞎ 녌의가 있었을 수도 있습니닀. -* Pull request가 필요하지 않을 가능성도 있습니닀. **닀륞 방식**윌로 묞제륌 í•Žê²°í•  수 있닀멎, ê·ž 방법을 제안하거나 질묞할 수 있습니닀. +* Pull request가 싀제로 필요하지 않을 가능성도 큜니닀. 묞제가 **닀륞 방식**윌로 핎결될 수 있Ʞ 때묞입니닀. 귞런 겜우 ê·ž 방법을 제안하거나 질묞할 수 있습니닀. -### 슀타음에 너묎 신겜 쓰지 ì•Šêž° +### 슀타음에 너묎 신겜 쓰지 ì•Šêž° { #dont-worry-about-style } -* 컀밋 메시지 슀타음 같은 것에 너묎 신겜 쓰지 않아도 됩니닀. 저는 직접 컀밋을 수정하여 squash and merge륌 수행할 것입니닀. +* 컀밋 메시지 슀타음 같은 것에 너묎 신겜 쓰지 마섞요. 저는 컀밋을 수동윌로 ì¡°ì •í•Žì„œ squash and merge륌 할 것입니닀. * 윔드 슀타음 규칙도 걱정할 필요 없습니닀. 읎믞 자동화된 도구듀읎 읎륌 검사하고 있습니닀. -슀타음읎나 음ꎀ성 ꎀ렚 요청읎 필요한 겜우, 제가 직접 요청하거나 필요한 변겜 사항을 추가 컀밋윌로 수정할 것입니닀. +귞늬고 닀륞 슀타음읎나 음ꎀ성 ꎀ렚 필요 사항읎 있닀멎, 제가 직접 요청하거나 필요한 변겜 사항을 위에 컀밋윌로 추가할 것입니닀. -### 윔드 확읞하Ʞ +### 윔드 확읞하Ʞ { #check-the-code } -* 윔드륌 읜고, **녌늬적윌로 타당**한지 확읞한 후 로컬에서 싀행하여 묞제가 핎결되는지 확읞하섞요. +* 윔드륌 확읞하고 읜얎서 말읎 되는지 볎고, **로컬에서 싀행**핮 싀제로 묞제가 핎결되는지 확읞하섞요. -* 귞런 닀음, 확읞했닀고 **댓Ꞁ**을 낚겚 죌섞요. 귞래알 제가 검토했음을 알 수 있습니닀. +* 귞런 닀음 귞렇게 했닀고 **댓Ꞁ**로 낚겚 죌섞요. 귞래알 제가 정말로 확읞했음을 알 수 있습니닀. -/// info +/// info | 정볎 불행히도, 제가 닚순히 여러 개의 승읞만윌로 PR을 신뢰할 수는 없습니닀. -3개, 5개 읎상의 승읞읎 달늰 PR읎 싀제로는 깚젞 있거나, 버귞가 있거나, 죌장하는 묞제륌 핎결하지 못하는 겜우가 여러 번 있었습니닀. 😅 +여러 번, 섀명읎 귞럎듯핎서읞지 3개, 5개 읎상의 승읞읎 달늰 PR읎 있었지만, 제가 확읞핎볎멎 싀제로는 깚젞 있거나, 버귞가 있거나, 죌장하는 묞제륌 핎결하지 못하는 겜우가 있었습니닀. 😅 따띌서, 정말로 윔드륌 읜고 싀행한 ë’€, 댓Ꞁ로 확읞 낎용을 낚겚 죌는 것읎 맀우 쀑요합니닀. 🀓 /// -* PR을 더 닚순하게 만듀 수 있닀멎 귞렇게 요청할 수 있지만, 너묎 까닀로욞 필요는 없습니닀. 죌ꎀ적읞 견핎가 많읎 있을 수 있Ʞ 때묞입니닀 (귞늬고 저도 제 견핎가 있을 거예요 🙈). 따띌서 핵심적읞 부분에 집쀑하는 것읎 좋습니닀. +* PR을 더 닚순하게 만듀 수 있닀멎 귞렇게 요청할 수 있지만, 너묎 까닀로욞 필요는 없습니닀. 죌ꎀ적읞 견핎가 많읎 있을 수 있Ʞ 때묞입니닀(귞늬고 저도 제 견핎가 있을 거예요 🙈). 따띌서 핵심적읞 부분에 집쀑하는 것읎 좋습니닀. -### 테슀튞 +### 테슀튞 { #tests } * PR에 **테슀튞**가 포핚되얎 있는지 확읞하는 데 도움을 죌섞요. -* PR을 적용하Ʞ 전에 테슀튞가 **싀팚**하는지 확읞하섞요. 🚚 +* PR 전에는 테슀튞가 **싀팚**하는지 확읞하섞요. 🚚 -* PR을 적용한 후 테슀튞가 **통곌**하는지 확읞하섞요. ✅ +* 귞런 닀음 PR 후에는 테슀튞가 **통곌**하는지 확읞하섞요. ✅ -* 많은 PR에는 테슀튞가 없습니닀. 테슀튞륌 추가하도록 **상Ʞ**시쌜쀄 수도 있고, 직접 테슀튞륌 **제안**할 수도 있습니닀. 읎는 시간읎 많읎 소요되는 부분 쀑 하나읎며, ê·ž 부분을 많읎 도와쀄 수 있습니닀. +* 많은 PR에는 테슀튞가 없습니닀. 테슀튞륌 추가하도록 **상Ʞ**시쌜쀄 수도 있고, 직접 테슀튞륌 **제안**할 수도 있습니닀. 읎는 시간읎 가장 많읎 드는 것듀 쀑 하나읎며, ê·ž 부분을 많읎 도와쀄 수 있습니닀. * 귞늬고 시도한 낎용을 댓Ꞁ로 낚겚죌섞요. 귞러멎 제가 확읞했닀는 걞 알 수 있습니닀. 🀓 -## Pull Request륌 만드십시였 +## Pull Request 만듀Ʞ { #create-a-pull-request } -Pull Requests륌 읎용하여 소슀윔드에 [컚튞늬뷰튞](contributing.md){.internal-link target=\_blank} 할 수 있습니닀. 예륌 듀멎 닀음곌 같습니닀: +Pull Requests륌 읎용하여 소슀 윔드에 [êž°ì—¬](contributing.md){.internal-link target=_blank}할 수 있습니닀. 예륌 듀멎 닀음곌 같습니닀: * 묞서에서 발견한 였타륌 수정할 때. -* FastAPI ꎀ렚 묞서, 비디였 또는 팟캐슀튞륌 작성했거나 발견하여 읎 파음을 펞집하여 공유할 때. +* FastAPI에 대한 Ꞁ, 비디였, 팟캐슀튞륌 작성했거나 발견했닀멎 읎 파음을 펞집하여 공유할 때. * 핎당 섹션의 시작 부분에 링크륌 추가핎알 합니닀. -* 당신의 ì–žì–Žë¡œ [묞서 번역하는데](contributing.md#translations){.internal-link target=\_blank} Ʞ여할 때. +* 여러분의 ì–žì–Žë¡œ [묞서 번역에](contributing.md#translations){.internal-link target=_blank} 도움을 쀄 때. * 닀륞 사람읎 작성한 번역을 검토하는 것도 도욞 수 있습니닀. -* 새로욎 묞서의 섹션을 제안할 때. -* êž°ì¡Ž 묞제/버귞륌 수정할 때. +* 새로욎 묞서 섹션을 제안할 때. +* êž°ì¡Ž 읎슈/버귞륌 수정할 때. * 테슀튞륌 반드시 추가핎알 합니닀. -* 새로욎 feature륌 추가할 때. +* 새로욎 Ʞ능을 추가할 때. * 테슀튞륌 반드시 추가핎알 합니닀. - * ꎀ렚 묞서가 필요하닀멎 반드시 추가핎알 합니닀. + * ꎀ렚 묞서가 있닀멎 반드시 추가핎알 합니닀. -## FastAPI 유지 ꎀ늬에 도움 죌Ʞ +## FastAPI 유지 ꎀ늬 돕Ʞ { #help-maintain-fastapi } -**FastAPI**의 유지 ꎀ늬륌 도와죌섞요! 🀓 +**FastAPI** 유지륌 도와죌섞요! 🀓 -할 음읎 많고, ê·ž 쀑 대부분은 **여러분**읎 할 수 있습니닀. +할 음읎 많고, 귞쀑 대부분은 **여러분**읎 할 수 있습니닀. 지ꞈ 할 수 있는 죌요 작업은: -* [GitHub에서 닀륞 사람듀의 질묞에 도움 죌Ʞ](#github_1){.internal-link target=_blank} (위의 섹션을 찞조하섞요). -* [Pull Request 늬뷰하Ʞ](#pull-requests){.internal-link target=_blank} (위의 섹션을 찞조하섞요). +* [GitHub에서 질묞윌로 닀륞 사람 돕Ʞ](#help-others-with-questions-in-github){.internal-link target=_blank} (위의 섹션을 찞조하섞요). +* [Pull Request 늬뷰하Ʞ](#review-pull-requests){.internal-link target=_blank} (위의 섹션을 찞조하섞요). -읎 두 작업읎 **가장 많은 시간을 소몚**하는 음입니닀. 귞것읎 FastAPI 유지 ꎀ늬의 죌요 작업입니닀. +읎 두 작업읎 **가장 많은 시간을 소몚**합니닀. 읎것읎 FastAPI륌 유지 ꎀ늬하는 죌요 작업입니닀. -읎 작업을 도와죌신닀멎, **FastAPI 유지 ꎀ늬에 도움을 죌는 것**읎며 귞것읎 **더 빠륎고 더 잘 발전하는 것**을 볎장하는 것입니닀. 🚀 +읎 작업을 도와죌신닀멎, **FastAPI 유지륌 돕는 것**읎며 FastAPI가 **더 빠륎고 더 잘 발전하는 것**을 볎장하는 것입니닀. 🚀 -## 채팅에 찞여하십시였 +## 채팅에 찞여하Ʞ { #join-the-chat } -👥 디슀윔드 채팅 서버 👥 에 가입하고 FastAPI 컀뮀니티에서 닀륞 사람듀곌 얎욞늬섞요. +👥 Discord 채팅 서버 👥 에 찞여핎서 FastAPI 컀뮀니티의 닀륞 사람듀곌 얎욞늬섞요. -/// tip +/// tip | 팁 -질묞읎 있는 겜우, GitHub 디슀컀션 에서 질묞하십시였, [FastAPI Experts](fastapi-people.md#fastapi-experts){.internal-link target=_blank} 의 도움을 받을 가능성읎 높습니닀. +질묞은 GitHub Discussions에서 하섞요. [FastAPI Experts](fastapi-people.md#fastapi-experts){.internal-link target=_blank}로부터 도움을 받을 가능성읎 훚씬 높습니닀. -닀륞 음반적읞 대화에서만 채팅을 사용하십시였. +채팅은 닀륞 음반적읞 대화륌 위핎서만 사용하섞요. /// -### 질묞을 위핎 채팅을 사용하지 마십시였 +### 질묞을 위핎 채팅을 사용하지 마섞요 { #dont-use-the-chat-for-questions } -채팅은 더 많은 "자유로욎 대화"륌 허용하Ʞ 때묞에, 너묎 음반적읞 질묞읎나 대답하Ʞ 얎렀욎 질묞을 쉜게 질묞을 할 수 있윌므로, 답변을 받지 못할 수 있습니닀. +채팅은 더 많은 "자유로욎 대화"륌 허용하Ʞ 때묞에, 너묎 음반적읞 질묞읎나 답하Ʞ 얎렀욎 질묞을 쉜게 할 수 있얎 답변을 받지 못할 수도 있닀는 점을 Ʞ억하섞요. -GitHub 읎슈에서의 템플늿은 올바륞 질묞을 작성하도록 안낎하여 더 쉜게 좋은 답변을 얻거나 질묞하Ʞ 전에 슀슀로 묞제륌 í•Žê²°í•  수도 있습니닀. 귞늬고 GitHub에서는 시간읎 조ꞈ 걞늬더띌도 항상 몚든 것에 답할 수 있습니닀. 채팅 시슀템에서는 개읞적윌로 귞렇게 할 수 없습니닀. 😅 +GitHub에서는 템플늿읎 올바륞 질묞을 작성하도록 안낎하여 더 쉜게 좋은 답변을 얻거나, 질묞하Ʞ 전에 슀슀로 묞제륌 í•Žê²°í•  수도 있습니닀. 귞늬고 GitHub에서는 시간읎 조ꞈ 걞늬더띌도 제가 항상 몚든 것에 답하도록 볎장할 수 있습니닀. 채팅 시슀템에서는 제가 개읞적윌로 귞렇게 할 수 없습니닀. 😅 -채팅 시슀템에서의 대화 또한 GitHub에서 처럌 쉜게 검색할 수 없Ʞ 때묞에 대화 쀑에 질묞곌 답변읎 손싀될 수 있습니닀. 귞늬고 GitHub 읎슈에 있는 것만 [FastAPI Expert](fastapi-people.md#fastapi-experts){.internal-link target=_blank}가 되는 것윌로 간죌되므로, GitHub 읎슈에서 더 많은 ꎀ심을 받을 것입니닀. +채팅 시슀템에서의 대화 또한 GitHub만큌 쉜게 검색할 수 없Ʞ 때묞에, 질묞곌 답변읎 대화 속에서 사띌질 수 있습니닀. 귞늬고 GitHub에 있는 것만 [FastAPI Expert](fastapi-people.md#fastapi-experts){.internal-link target=_blank}가 되는 것윌로 읞정되므로, GitHub에서 더 많은 ꎀ심을 받게 될 가능성읎 큜니닀. -반멎, 채팅 시슀템에는 수천 명의 사용자가 있Ʞ 때묞에, 거의 항상 대화 상대륌 찟을 가능성읎 높습니닀. 😄 +반멎, 채팅 시슀템에는 수천 명의 사용자가 있윌므로, 거의 항상 대화 상대륌 찟을 가능성읎 높습니닀. 😄 -## 개발자 슀폰서가 되십시였 +## 개발자 슀폰서 되Ʞ { #sponsor-the-author } -GitHub 슀폰서 륌 통핎 개발자륌 겜제적윌로 지원할 수 있습니닀. - -감사하닀는 말로 컀플륌 ☕ 한잔 사쀄 수 있습니닀. 😄 - -또한 FastAPI의 싀버 또는 곚드 슀폰서가 될 수 있습니닀. 🏅🎉 - -## FastAPI륌 강화하는 도구의 슀폰서가 되십시였 - -묞서에서 볎았듯읎, FastAPI는 Starlette곌 Pydantic 띌는 거읞의 얎깚에 타고 있습니닀. - -닀음의 슀폰서가 될 수 있습니닀 - -* Samuel Colvin (Pydantic) -* Encode (Starlette, Uvicorn) +여러분의 **제품/회사**가 **FastAPI**에 의졎하거나 ꎀ렚되얎 있고, FastAPI 사용자륌 대상윌로 알늬고 싶닀멎 GitHub sponsors륌 통핎 개발자(저)륌 슀폰서할 수 있습니닀. 티얎에 따띌 묞서에 배지 같은 추가 혜택을 받을 수도 있습니닀. 🎁 --- diff --git a/docs/ko/docs/history-design-future.md b/docs/ko/docs/history-design-future.md index 98f01d70d3..d972001215 100644 --- a/docs/ko/docs/history-design-future.md +++ b/docs/ko/docs/history-design-future.md @@ -1,81 +1,79 @@ -# 역사, 디자읞 귞늬고 믞래 +# 역사, 디자읞 귞늬고 믞래 { #history-design-and-future } -얎느 날, [한 FastAPI 사용자](https://github.com/fastapi/fastapi/issues/3#issuecomment-454956920)가 읎렇게 묌었습니닀: +얌마 전, 한 **FastAPI** 사용자가 읎렇게 묌었습니닀: -> 읎 프로젝튞의 역사륌 알렀 죌싀 수 있나요? 몇 죌 만에 멋진 결곌륌 낾 것 같아요. [...] +> 읎 프로젝튞의 역사는 묎엇읞가요? 몇 죌 만에 아묎 데서도 갑자Ʞ 나타나 엄청나게 좋아진 것처럌 볎읎넀요 [...] 여Ʞ서 ê·ž 역사에 대핮 간닚히 섀명하겠습니닀. ---- +## 대안 { #alternatives } -## 대안 +저는 여러 핮 동안 복잡한 요구사항(뚞신러닝, 분산 시슀템, 비동Ʞ 작업, NoSQL 데읎터베읎슀 등)을 가진 API륌 만듀멎서 여러 개발 팀을 읎끌얎 왔습니닀. -저는 여러 핮 동안 뚞신러닝, 분산 시슀템, 비동Ʞ 작업, NoSQL 데읎터베읎슀 같은 복잡한 요구사항을 가진 API륌 개발하며 여러 팀을 읎끌얎 왔습니닀. +ê·ž 곌정에서 많은 대안을 조사하고, 테슀튞하고, 사용핎알 했습니닀. -읎 곌정에서 많은 대안을 조사하고, 테슀튞하며, 사용핎알 했습니닀. **FastAPI**의 역사는 ê·ž 읎전에 나왔던 여러 도구의 역사와 밀접하게 연ꎀ되얎 있습니닀. +**FastAPI**의 역사는 상당 부분 ê·ž 읎전에 있던 도구듀의 역사입니닀. [대안](alternatives.md){.internal-link target=_blank} 섹션에서 얞꞉된 것처럌: -> **FastAPI**는 읎전에 나왔던 많은 도구듀의 ë…žë ¥ 없읎는 졎재하지 않았을 것입니닀. -> -> 읎전에 개발된 여러 도구듀읎 읎 프로젝튞에 영감을 죌었습니닀. -> -> 저는 였랫동안 새로욎 프레임워크륌 만드는 것을 플하고자 했습니닀. 처음에는 **FastAPI**가 제공하는 Ʞ능듀을 닀양한 프레임워크와 플러귞읞, 도구듀을 ì¡°í•©í•Ž 핎결하렀 했습니닀. -> -> 하지만 결국에는 읎 몚든 Ʞ능을 통합하는 도구가 필요핎졌습니닀. 읎전 도구듀로부터 최고의 아읎디얎듀을 몚윌고, 읎륌 최적의 방식윌로 조합핎알만 했습니닀. 읎는 :term:Python 3.6+ 타입 힌튾 와 같은, 읎전에는 사용할 수 없었던 ì–žì–Ž Ʞ능읎 가능했Ʞ 때묞입니닀. +
---- +**FastAPI**는 닀륞 사람듀읎 읎전에 핎옚 작업읎 없었닀멎 졎재하지 않았을 것입니닀. -## 조사 +ê·ž 전에 만듀얎진 많은 도구듀읎 읎것의 탄생에 영감을 죌었습니닀. -여러 대안을 사용핎 볎며 닀양한 도구에서 배욎 점듀을 몚아 저와 개발팀에게 가장 적합한 방식을 찟았습니닀. +저는 여러 핮 동안 새로욎 프레임워크륌 만드는 것을 플하고 있었습니닀. 처음에는 **FastAPI**가 닀룚는 몚든 Ʞ능을 여러 닀륞 프레임워크, 플러귞읞, 도구듀을 사용핎 핎결하렀고 했습니닀. -예륌 듀얎, 표쀀 :term:Python 타입 힌튾 에 Ʞ반하는 것읎 읎상적읎띌는 점읎 명확했습니닀. +하지만 얎느 시점에는, 읎전 도구듀의 최고의 아읎디얎륌 가젞와 가능한 한 최선의 방식윌로 조합하고, 읎전에는 졎재하지 않았던 ì–žì–Ž Ʞ능(Python 3.6+ type hints)을 사용핎 읎 몚든 Ʞ능을 제공하는 묎얞가륌 만드는 것 왞에는 닀륞 선택지가 없었습니닀. -또한, 읎믞 졎재하는 표쀀을 활용하는 것읎 가장 좋은 접귌법읎띌 판닚했습니닀. +
-귞래서 **FastAPI**의 윔드륌 작성하Ʞ 전에 몇 달 동안 OpenAPI, JSON Schema, OAuth2 명섞륌 연구하며 읎듀의 ꎀ계와 겹치는 부분, 찚읎점을 읎핎했습니닀. +## 조사 { #investigation } ---- +읎전의 몚든 대안을 사용핎 볎멎서, 각 도구로부터 ë°°ìšž Ʞ회륌 얻었고, 아읎디얎륌 가젞와 제가 음핎옚 개발 팀듀곌 저 자신에게 가장 적합하닀고 찟은 방식윌로 조합할 수 있었습니닀. -## 디자읞 +예륌 듀얎, 읎상적윌로는 표쀀 Python 타입 힌튞에 Ʞ반핎알 한닀는 점읎 분명했습니닀. -ê·ž 후, **FastAPI** 사용자가 될 개발자로서 사용하고 싶은 개발자 "API"륌 디자읞했습니닀. +또한, 가장 좋은 접귌법은 읎믞 졎재하는 표쀀을 사용하는 것읎었습니닀. -[Python Developer Survey](https://www.jetbrains.com/research/python-developers-survey-2018/#development-tools)에 따륎멎 ì•œ 80%의 Python 개발자가 PyCharm, VS Code, Jedi êž°ë°˜ 펞집Ʞ 등에서 개발합니닀. 읎 곌정에서 여러 아읎디얎륌 테슀튞했습니닀. +귞래서 **FastAPI**의 윔딩을 시작하Ʞ도 전에, OpenAPI, JSON Schema, OAuth2 등곌 같은 명섞륌 몇 달 동안 공부했습니닀. 읎듀의 ꎀ계, 겹치는 부분, 찚읎점을 읎핎하Ʞ 위핎서였습니닀. -대부분의 닀륞 펞집Ʞ도 유사하게 동작하Ʞ 때묞에, **FastAPI**의 읎점은 거의 몚든 펞집Ʞ에서 누멮 수 있습니닀. +## 디자읞 { #design } -읎 곌정을 통핎 윔드 쀑복을 최소화하고, 몚든 곳에서 자동 완성, 타입 검사, 에러 확읞 Ʞ능읎 제공되는 최적의 방식을 찟아냈습니닀. +ê·ž 닀음에는 (FastAPI륌 사용하는 개발자로서) 사용자로서 갖고 싶었던 개발자 "API"륌 디자읞하는 데 시간을 썌습니닀. -읎 몚든 것은 개발자듀에게 최고의 개발 겜험을 제공하Ʞ 위핎 섀계되었습니닀. +가장 읞Ʞ 있는 Python 펞집Ʞ듀: PyCharm, VS Code, Jedi êž°ë°˜ 펞집Ʞ에서 여러 아읎디얎륌 테슀튞했습니닀. ---- +ì•œ 80%의 사용자륌 포핚하는 최귌 Python Developer Survey에 따륎멎 귞렇습니닀. -## 필요조걎 +슉, **FastAPI**는 Python 개발자의 80%가 사용하는 펞집Ʞ듀로 특별히 테슀튞되었습니닀. 귞늬고 대부분의 닀륞 펞집Ʞ도 유사하게 동작하는 겜향읎 있윌므로, ê·ž 몚든 읎점은 사싀상 몚든 펞집Ʞ에서 동작핎알 합니닀. -여러 대안을 테슀튞한 후, [Pydantic](https://docs.pydantic.dev/)을 사용하Ʞ로 결정했습니닀. +귞렇게 í•Žì„œ 윔드 쀑복을 가능한 한 많읎 쀄읎고, 얎디서나 자동 완성, 타입 및 에러 검사 등을 제공하는 최선의 방법을 찟을 수 있었습니닀. -읎후 저는 **Pydantic**읎 JSON Schema와 완벜히 혞환되도록 개선하고, 닀양한 제앜 조걎 선얞을 지원하며, 여러 펞집Ʞ에서의 자동 완성곌 타입 검사 Ʞ능을 향상하Ʞ 위핎 Ʞ여했습니닀. +몚든 개발자에게 최고의 개발 겜험을 제공하는 방식윌로 말입니닀. -또한, 또 닀륞 죌요 필요조걎읎었던 [Starlette](https://www.starlette.dev/)에도 Ʞ여했습니닀. +## 필요조걎 { #requirements } ---- +여러 대안을 테슀튞한 후, 장점 때묞에 **Pydantic**을 사용하Ʞ로 결정했습니닀. -## 개발 +ê·ž 후, JSON Schema륌 완전히 쀀수하도록 하고, 제앜 조걎 선얞을 정의하는 닀양한 방식을 지원하며, 여러 펞집Ʞ에서의 테슀튞륌 바탕윌로 펞집Ʞ 지원(타입 검사, 자동 완성)을 개선하Ʞ 위핎 Ʞ여했습니닀. -**FastAPI**륌 개발하Ʞ 시작할 슈음에는 대부분의 쀀비가 읎믞 완료된 상태였습니닀. 섀계가 정의되었고, 필요조걎곌 도구가 쀀비되었윌며, 표쀀곌 명섞에 대한 지식도 충분했습니닀. +개발 곌정에서, 또 닀륞 핵심 필요조걎읞 **Starlette**에도 Ʞ여했습니닀. ---- +## 개발 { #development } -## 믞래 +**FastAPI** 자첎륌 만듀Ʞ 시작했을 때쯀에는, 대부분의 조각듀읎 읎믞 갖춰젞 있었고, 디자읞은 정의되얎 있었윌며, 필요조걎곌 도구는 쀀비되얎 있었고, 표쀀곌 명섞에 대한 지식도 명확하고 최신 상태였습니닀. -현시점에서 **FastAPI**가 많은 사람듀에게 유용하닀는 것읎 명백핎졌습니닀. +## 믞래 { #future } -여러 용도에 더 적합한 도구로서 êž°ì¡Ž 대안볎닀 선혞되고 있습니닀. -읎믞 많은 개발자와 팀듀읎 **FastAPI**에 의졎핎 프로젝튞륌 진행 쀑입니닀 (저와 제 팀도 마찬가지입니닀). +읎 시점에는, **FastAPI**가 ê·ž 아읎디얎와 핚께 많은 사람듀에게 유용하닀는 것읎 읎믞 분명합니닀. -하지만 여전히 개선핎알 할 점곌 추가할 Ʞ능듀읎 많읎 ë‚šì•„ 있습니닀. +많은 사용 사례에 더 잘 맞Ʞ 때묞에 읎전 대안듀볎닀 선택되고 있습니닀. + +많은 개발자와 팀읎 읎믞 자신의 프로젝튞륌 위핎 **FastAPI**에 의졎하고 있습니닀(저와 제 팀도 포핚핎서요). + +하지만 여전히, 앞윌로 나올 개선 사항곌 Ʞ능듀읎 많읎 있습니닀. + +**FastAPI**의 믞래는 밝습니닀. -**FastAPI**는 밝은 믞래로 나아가고 있습니닀. 귞늬고 [여러분의 도움](help-fastapi.md){.internal-link target=_blank}은 큰 힘읎 됩니닀. From 442d007e761fdee34ec01d2365d138d0a746c971 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sat, 24 Jan 2026 21:16:33 +0000 Subject: [PATCH 036/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index f1321b7809..cf84ae9b53 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -18,6 +18,7 @@ hide: ### Translations +* 🌐 Update translations for ko (update outdated, found by fixer tool). PR [#14738](https://github.com/fastapi/fastapi/pull/14738) by [@YuriiMotov](https://github.com/YuriiMotov). * 🌐 Update translations for de (update-outdated). PR [#14690](https://github.com/fastapi/fastapi/pull/14690) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update LLM prompt for Russian translations. PR [#14733](https://github.com/fastapi/fastapi/pull/14733) by [@YuriiMotov](https://github.com/YuriiMotov). * 🌐 Update translations for ru (update-outdated). PR [#14693](https://github.com/fastapi/fastapi/pull/14693) by [@tiangolo](https://github.com/tiangolo). From 7a0589466c1c0129ff7291ea0b663d52859d651d Mon Sep 17 00:00:00 2001 From: JUNG SEUNGHOON Date: Sun, 25 Jan 2026 06:17:54 +0900 Subject: [PATCH 037/108] =?UTF-8?q?=F0=9F=8C=90=20Update=20`llm-prompt.md`?= =?UTF-8?q?=20for=20Korean=20language=20(#14763)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(ko): refine 'burger' to '햄버거' and update glossary * Update docs/ko/llm-prompt.md Co-authored-by: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> * Add app and command to glossary Update glossary: add 애플늬쌀읎션 (app) and 명령얎 (command) --------- Co-authored-by: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> --- docs/ko/llm-prompt.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/ko/llm-prompt.md b/docs/ko/llm-prompt.md index 533160eab9..be2f5be5de 100644 --- a/docs/ko/llm-prompt.md +++ b/docs/ko/llm-prompt.md @@ -33,6 +33,9 @@ Use the following preferred translations when they apply in documentation prose: - response (HTTP): 응답 - path operation: 겜로 처늬 - path operation function: 겜로 처늬 핚수 +- app: 애플늬쌀읎션 +- command: 명령얎 +- burger: 햄버거 (NOT 버거) ### `///` admonitions From 8c32e91c10cbf13da8be4d27f03d9fdaa9a6730c Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sat, 24 Jan 2026 21:18:15 +0000 Subject: [PATCH 038/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index cf84ae9b53..1fefe908ba 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -18,6 +18,7 @@ hide: ### Translations +* 🌐 Update `llm-prompt.md` for Korean language. PR [#14763](https://github.com/fastapi/fastapi/pull/14763) by [@seuthootDev](https://github.com/seuthootDev). * 🌐 Update translations for ko (update outdated, found by fixer tool). PR [#14738](https://github.com/fastapi/fastapi/pull/14738) by [@YuriiMotov](https://github.com/YuriiMotov). * 🌐 Update translations for de (update-outdated). PR [#14690](https://github.com/fastapi/fastapi/pull/14690) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update LLM prompt for Russian translations. PR [#14733](https://github.com/fastapi/fastapi/pull/14733) by [@YuriiMotov](https://github.com/YuriiMotov). From a3dccaeb14ed511ed548d88254b96131299851bf Mon Sep 17 00:00:00 2001 From: Vineet Kumar <108144301+whyvineet@users.noreply.github.com> Date: Thu, 29 Jan 2026 13:53:25 +0530 Subject: [PATCH 039/108] =?UTF-8?q?=F0=9F=93=9D=20Fix=20minor=20typos=20in?= =?UTF-8?q?=20release=20notes=20(#14780)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 📝 Fix typos in release notes --- docs/en/docs/release-notes.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 1fefe908ba..62dae4da71 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -283,7 +283,7 @@ hide: ### Refactors -* 🔥 Remove dangling extra condiitonal no longer needed. PR [#14435](https://github.com/fastapi/fastapi/pull/14435) by [@tiangolo](https://github.com/tiangolo). +* 🔥 Remove dangling extra conditional no longer needed. PR [#14435](https://github.com/fastapi/fastapi/pull/14435) by [@tiangolo](https://github.com/tiangolo). * ♻ Refactor internals, update `is_coroutine` check to reuse internal supported variants (unwrap, check class). PR [#14434](https://github.com/fastapi/fastapi/pull/14434) by [@tiangolo](https://github.com/tiangolo). ### Translations @@ -418,7 +418,7 @@ hide: ### Docs -* 📝 Upate docs for advanced dependencies with `yield`, noting the changes in 0.121.0, adding `scope`. PR [#14287](https://github.com/fastapi/fastapi/pull/14287) by [@tiangolo](https://github.com/tiangolo). +* 📝 Update docs for advanced dependencies with `yield`, noting the changes in 0.121.0, adding `scope`. PR [#14287](https://github.com/fastapi/fastapi/pull/14287) by [@tiangolo](https://github.com/tiangolo). ### Internal @@ -2646,7 +2646,7 @@ Read more in the [advisory: Content-Type Header ReDoS](https://github.com/tiango * 🌐 Add Japanese translation for `docs/ja/docs/tutorial/handling-errors.md`. PR [#1953](https://github.com/tiangolo/fastapi/pull/1953) by [@SwftAlpc](https://github.com/SwftAlpc). * 🌐 Add Japanese translation for `docs/ja/docs/tutorial/response-status-code.md`. PR [#1942](https://github.com/tiangolo/fastapi/pull/1942) by [@SwftAlpc](https://github.com/SwftAlpc). * 🌐 Add Japanese translation for `docs/ja/docs/tutorial/extra-models.md`. PR [#1941](https://github.com/tiangolo/fastapi/pull/1941) by [@SwftAlpc](https://github.com/SwftAlpc). -* 🌐 Add Japanese tranlsation for `docs/ja/docs/tutorial/schema-extra-example.md`. PR [#1931](https://github.com/tiangolo/fastapi/pull/1931) by [@SwftAlpc](https://github.com/SwftAlpc). +* 🌐 Add Japanese translation for `docs/ja/docs/tutorial/schema-extra-example.md`. PR [#1931](https://github.com/tiangolo/fastapi/pull/1931) by [@SwftAlpc](https://github.com/SwftAlpc). * 🌐 Add Japanese translation for `docs/ja/docs/tutorial/body-nested-models.md`. PR [#1930](https://github.com/tiangolo/fastapi/pull/1930) by [@SwftAlpc](https://github.com/SwftAlpc). * 🌐 Add Japanese translation for `docs/ja/docs/tutorial/body-fields.md`. PR [#1923](https://github.com/tiangolo/fastapi/pull/1923) by [@SwftAlpc](https://github.com/SwftAlpc). * 🌐 Add German translation for `docs/de/docs/tutorial/index.md`. PR [#9502](https://github.com/tiangolo/fastapi/pull/9502) by [@fhabers21](https://github.com/fhabers21). @@ -4022,7 +4022,7 @@ You hopefully updated to a supported version of Python a while ago. If you haven ### Fixes * 🐛 Fix `RuntimeError` raised when `HTTPException` has a status code with no content. PR [#5365](https://github.com/tiangolo/fastapi/pull/5365) by [@iudeen](https://github.com/iudeen). -* 🐛 Fix empty reponse body when default `status_code` is empty but the a `Response` parameter with `response.status_code` is set. PR [#5360](https://github.com/tiangolo/fastapi/pull/5360) by [@tmeckel](https://github.com/tmeckel). +* 🐛 Fix empty response body when default `status_code` is empty but the a `Response` parameter with `response.status_code` is set. PR [#5360](https://github.com/tiangolo/fastapi/pull/5360) by [@tmeckel](https://github.com/tmeckel). ### Docs From 9348a5e2cf55440ff3da3bd4b7876acd3b3f57e5 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 29 Jan 2026 08:23:48 +0000 Subject: [PATCH 040/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 62dae4da71..975bf774e9 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -9,6 +9,7 @@ hide: ### Docs +* 📝 Fix minor typos in release notes. PR [#14780](https://github.com/fastapi/fastapi/pull/14780) by [@whyvineet](https://github.com/whyvineet). * 🐛 Fix copy button in custom.js. PR [#14722](https://github.com/fastapi/fastapi/pull/14722) by [@fcharrier](https://github.com/fcharrier). * 📝 Add contribution instructions about LLM generated code and comments and automated tools for PRs. PR [#14706](https://github.com/fastapi/fastapi/pull/14706) by [@tiangolo](https://github.com/tiangolo). * 📝 Update docs for management tasks. PR [#14705](https://github.com/fastapi/fastapi/pull/14705) by [@tiangolo](https://github.com/tiangolo). From c9629e0eb245836b7ecd7b12c1eb7ef12dbdb1ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Sat, 31 Jan 2026 10:32:27 -0800 Subject: [PATCH 041/108] =?UTF-8?q?=F0=9F=8C=90=20Update=20translations=20?= =?UTF-8?q?for=20tr=20(update-outdated)=20(#14745)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: github-actions[bot] --- docs/tr/docs/about/index.md | 2 +- docs/tr/docs/advanced/index.md | 31 +- docs/tr/docs/advanced/security/index.md | 12 +- docs/tr/docs/advanced/testing-websockets.md | 10 +- docs/tr/docs/advanced/wsgi.md | 24 +- docs/tr/docs/benchmarks.md | 36 +- docs/tr/docs/deployment/cloud.md | 25 +- docs/tr/docs/deployment/index.md | 22 +- docs/tr/docs/how-to/general.md | 40 +- docs/tr/docs/how-to/index.md | 10 +- docs/tr/docs/index.md | 427 ++++++++++-------- docs/tr/docs/learn/index.md | 4 +- docs/tr/docs/project-generation.md | 102 +---- docs/tr/docs/python-types.md | 455 +++++++++++++------- docs/tr/docs/resources/index.md | 4 +- docs/tr/docs/tutorial/cookie-params.md | 34 +- docs/tr/docs/tutorial/first-steps.md | 333 +++++++------- docs/tr/docs/tutorial/path-params.md | 190 ++++---- docs/tr/docs/tutorial/query-params.md | 94 ++-- docs/tr/docs/tutorial/request-forms.md | 48 ++- docs/tr/docs/tutorial/static-files.md | 38 +- 21 files changed, 1089 insertions(+), 852 deletions(-) diff --git a/docs/tr/docs/about/index.md b/docs/tr/docs/about/index.md index e9dee5217c..a638fb0cf8 100644 --- a/docs/tr/docs/about/index.md +++ b/docs/tr/docs/about/index.md @@ -1,3 +1,3 @@ -# Hakkında +# Hakkında { #about } FastAPI, tasarımı, ilham kaynağı ve daha fazlası hakkında. 🀓 diff --git a/docs/tr/docs/advanced/index.md b/docs/tr/docs/advanced/index.md index 836e63c8ab..3995109e25 100644 --- a/docs/tr/docs/advanced/index.md +++ b/docs/tr/docs/advanced/index.md @@ -1,36 +1,21 @@ -# Gelişmiş Kullanıcı Rehberi +# Gelişmiş Kullanıcı Rehberi { #advanced-user-guide } -## Ek Özellikler +## Ek Özellikler { #additional-features } -[Tutorial - User Guide](../tutorial/index.md){.internal-link target=_blank} sayfası **FastAPI**'ın tÃŒm ana özelliklerini tanıtmaya yetecektir. +Ana [Tutorial - User Guide](../tutorial/index.md){.internal-link target=_blank} sayfası, **FastAPI**'ın tÃŒm temel özelliklerini tanımanız için yeterli olmalıdır. -Ä°lerleyen bölÃŒmlerde diğer seçenekler, konfigÃŒrasyonlar ve ek özellikleri göreceğiz. +Sonraki bölÃŒmlerde diğer seçenekleri, konfigÃŒrasyonları ve ek özellikleri göreceksiniz. /// tip | Ä°pucu Sonraki bölÃŒmler **mutlaka "gelişmiş" olmak zorunda değildir**. -Kullanım şeklinize bağlı olarak, çözÃŒmÃŒnÃŒz bu bölÃŒmlerden birinde olabilir. +Ve kullanım amacınıza bağlı olarak, çözÃŒm bunlardan birinde olabilir. /// -## Önce Öğreticiyi Okuyun +## Önce Tutorial'ı Okuyun { #read-the-tutorial-first } -[Tutorial - User Guide](../tutorial/index.md){.internal-link target=_blank} sayfasındaki bilgilerle **FastAPI**'nın çoğu özelliğini kullanabilirsiniz. +Ana [Tutorial - User Guide](../tutorial/index.md){.internal-link target=_blank} sayfasındaki bilgilerle **FastAPI**'nın çoğu özelliğini yine de kullanabilirsiniz. -Sonraki bölÃŒmler bu sayfayı okuduğunuzu ve bu ana fikirleri bildiğinizi varsayarak hazırlanmıştır. - -## Diğer Kurslar - -[Tutorial - User Guide](../tutorial/index.md){.internal-link target=_blank} sayfası ve bu **Gelişmiş Kullanıcı Rehberi**, öğretici bir kılavuz (bir kitap gibi) şeklinde yazılmıştır ve **FastAPI'ı öğrenmek** için yeterli olsa da, ek kurslarla desteklemek isteyebilirsiniz. - -Belki de öğrenme tarzınıza daha iyi uyduğu için başka kursları tercih edebilirsiniz. - -Bazı kurs sağlayıcıları ✹ [**FastAPI destekçileridir**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✹, bu FastAPI ve **ekosisteminin** sÃŒrekli ve sağlıklı bir şekilde **gelişmesini** sağlar. - -Ayrıca, size **iyi bir öğrenme deneyimi** sağlamakla kalmayıp, **iyi ve sağlıklı bir framework** olan FastAPI'a ve ve **topluluğuna** (yani size) olan gerçek bağlılıklarını gösterir. - -Onların kurslarını denemek isteyebilirsiniz: - -* Talk Python Training -* Test-Driven Development +Ve sonraki bölÃŒmler, onu zaten okuduğunuzu ve bu temel fikirleri bildiğinizi varsayar. diff --git a/docs/tr/docs/advanced/security/index.md b/docs/tr/docs/advanced/security/index.md index 709f74c721..9b30781f29 100644 --- a/docs/tr/docs/advanced/security/index.md +++ b/docs/tr/docs/advanced/security/index.md @@ -1,6 +1,6 @@ -# Gelişmiş GÃŒvenlik +# Gelişmiş GÃŒvenlik { #advanced-security } -## Ek Özellikler +## Ek Özellikler { #additional-features } [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. @@ -8,12 +8,12 @@ Sonraki bölÃŒmler **mutlaka "gelişmiş" olmak zorunda değildir**. -Kullanım şeklinize bağlı olarak, çözÃŒmÃŒnÃŒz bu bölÃŒmlerden birinde olabilir. +Ve kullanım durumunuza göre, çözÃŒm bu bölÃŒmlerden birinde olabilir. /// -## Önce Öğreticiyi Okuyun +## Önce Öğreticiyi Okuyun { #read-the-tutorial-first } -Sonraki bölÃŒmler [Tutorial - User Guide: Security](../../tutorial/security/index.md){.internal-link target=_blank} sayfasını okuduğunuzu varsayarak hazırlanmıştır. +Sonraki bölÃŒmler, ana [Tutorial - User Guide: Security](../../tutorial/security/index.md){.internal-link target=_blank} sayfasını zaten okuduğunuzu varsayar. -Bu bölÃŒmler aynı kavramlara dayanır, ancak bazı ek işlevsellikler sağlar. +Hepsi aynı kavramlara dayanır, ancak bazı ek işlevselliklere izin verir. diff --git a/docs/tr/docs/advanced/testing-websockets.md b/docs/tr/docs/advanced/testing-websockets.md index effe557d19..da12abadb8 100644 --- a/docs/tr/docs/advanced/testing-websockets.md +++ b/docs/tr/docs/advanced/testing-websockets.md @@ -1,13 +1,13 @@ -# WebSockets'i Test Etmek +# WebSockets'i Test Etmek { #testing-websockets } -WebSockets testi yapmak için `TestClient`'ı kullanabilirsiniz. +WebSockets'i test etmek için aynı `TestClient`'ı kullanabilirsiniz. -Bu işlem için, `TestClient`'ı bir `with` ifadesinde kullanarak WebSocket'e bağlanabilirsiniz: +Bunun için `TestClient`'ı bir `with` ifadesinde kullanarak WebSocket'e bağlanırsınız: -{* ../../docs_src/app_testing/tutorial002.py hl[27:31] *} +{* ../../docs_src/app_testing/tutorial002_py39.py hl[27:31] *} /// note | Not -Daha fazla detay için Starlette'in Websockets'i Test Etmek dokÃŒmantasyonunu inceleyin. +Daha fazla detay için Starlette'in WebSockets'i test etme dokÃŒmantasyonuna bakın. /// diff --git a/docs/tr/docs/advanced/wsgi.md b/docs/tr/docs/advanced/wsgi.md index 00815a4b2f..442f83a59a 100644 --- a/docs/tr/docs/advanced/wsgi.md +++ b/docs/tr/docs/advanced/wsgi.md @@ -1,32 +1,32 @@ -# WSGI - Flask, Django ve Daha Fazlasını FastAPI ile Kullanma +# WSGI'yi Dahil Etme - Flask, Django ve Diğerleri { #including-wsgi-flask-django-others } -WSGI uygulamalarını [Sub Applications - Mounts](sub-applications.md){.internal-link target=_blank}, [Behind a Proxy](behind-a-proxy.md){.internal-link target=_blank} bölÃŒmlerinde gördÌğÌnÃŒz gibi bağlayabilirsiniz. +WSGI uygulamalarını [Sub Applications - Mounts](sub-applications.md){.internal-link target=_blank}, [Behind a Proxy](behind-a-proxy.md){.internal-link target=_blank} bölÃŒmlerinde gördÌğÌnÃŒz gibi mount edebilirsiniz. -Bunun için `WSGIMiddleware` ile Flask, Django vb. WSGI uygulamanızı sarmalayabilir ve FastAPI'ya bağlayabilirsiniz. +Bunun için `WSGIMiddleware`'ı kullanabilir ve bunu WSGI uygulamanızı (örneğin Flask, Django vb.) sarmalamak için kullanabilirsiniz. -## `WSGIMiddleware` Kullanımı +## `WSGIMiddleware` Kullanımı { #using-wsgimiddleware } -`WSGIMiddleware`'ı projenize dahil edin. +`WSGIMiddleware`'ı import etmeniz gerekir. -Ardından WSGI (örneğin Flask) uygulamanızı middleware ile sarmalayın. +Ardından WSGI (örn. Flask) uygulamasını middleware ile sarmalayın. -Son olarak da bir yol altında bağlama işlemini gerçekleştirin. +Ve sonra bunu bir path'in altına mount edin. -{* ../../docs_src/wsgi/tutorial001.py hl[2:3,23] *} +{* ../../docs_src/wsgi/tutorial001_py39.py hl[2:3,3] *} -## Kontrol Edelim +## Kontrol Edelim { #check-it } -Artık `/v1/` yolunun altındaki her istek Flask uygulaması tarafından işlenecektir. +Artık `/v1/` path'i altındaki her request Flask uygulaması tarafından işlenecektir. Geri kalanı ise **FastAPI** tarafından işlenecektir. -Eğer uygulamanızı çalıştırıp http://localhost:8000/v1/ adresine giderseniz, Flask'tan gelen yanıtı göreceksiniz: +Eğer uygulamanızı çalıştırıp http://localhost:8000/v1/ adresine giderseniz, Flask'tan gelen response'u göreceksiniz: ```txt Hello, World from Flask! ``` -Eğer http://localhost:8000/v2/ adresine giderseniz, FastAPI'dan gelen yanıtı göreceksiniz: +Ve eğer http://localhost:8000/v2 adresine giderseniz, FastAPI'dan gelen response'u göreceksiniz: ```JSON { diff --git a/docs/tr/docs/benchmarks.md b/docs/tr/docs/benchmarks.md index eb5472869a..f2b8585856 100644 --- a/docs/tr/docs/benchmarks.md +++ b/docs/tr/docs/benchmarks.md @@ -1,34 +1,34 @@ -# Kıyaslamalar +# Kıyaslamalar { #benchmarks } -Bağımsız TechEmpower kıyaslamaları gösteriyor ki en hızlı Python frameworklerinden birisi olan Uvicorn ile çalıştırılan **FastAPI** uygulamaları, sadece Starlette ve Uvicorn'dan daha dÌşÌk sıralamada (FastAPI bu frameworklerin ÃŒzerine kurulu) yer alıyor. (*) +Bağımsız TechEmpower kıyaslamaları, Uvicorn altında çalışan **FastAPI** uygulamalarının mevcut en hızlı Python frameworklerinden biri olduğunu, yalnızca Starlette ve Uvicorn'un kendilerinin altında yer aldığını gösteriyor (FastAPI bunları dahili olarak kullanır). Fakat kıyaslamaları ve karşılaştırmaları incelerken şunları aklınızda bulundurmalısınız. -## Kıyaslamalar ve Hız +## Kıyaslamalar ve Hız { #benchmarks-and-speed } -Kıyaslamaları incelediğinizde, farklı özelliklere sahip araçların eşdeğer olarak karşılaştırıldığını yaygın bir şekilde görebilirsiniz. +Kıyaslamalara baktığınızda, farklı tÃŒrlerdeki birkaç aracın eşdeğermiş gibi karşılaştırıldığını görmek yaygındır. Özellikle, (diğer birçok araç arasında) Uvicorn, Starlette ve FastAPI'ın birlikte karşılaştırıldığını görebilirsiniz. -Aracın çözdÌğÌ problem ne kadar basitse, performansı o kadar iyi olacaktır. Ancak kıyaslamaların çoğu, aracın sağladığı ek özellikleri test etmez. +Aracın çözdÌğÌ problem ne kadar basitse, elde edeceği performans o kadar iyi olur. Ayrıca kıyaslamaların çoğu, aracın sağladığı ek özellikleri test etmez. Hiyerarşi şöyledir: * **Uvicorn**: bir ASGI sunucusu - * **Starlette**: (Uvicorn'u kullanır) bir web mikroframeworkÃŒ - * **FastAPI**: (Starlette'i kullanır) veri doğrulama vb. çeşitli ek özelliklere sahip, API oluşturmak için kullanılan bir API mikroframeworkÃŒ + * **Starlette**: (Uvicorn'u kullanır) bir web mikroframework'ÃŒ + * **FastAPI**: (Starlette'i kullanır) veri doğrulama vb. ile API'lar oluşturmak için çeşitli ek özelliklere sahip bir API mikroframework'ÃŒ * **Uvicorn**: - * Sunucunun kendisi dışında ekstra bir kod içermediği için en iyi performansa sahip olacaktır. - * Doğrudan Uvicorn ile bir uygulama yazmazsınız. Bu, yazdığınız kodun en azından Starlette tarafından sağlanan tÃŒm kodu (veya **FastAPI**) az çok içermesi gerektiği anlamına gelir. Eğer bunu yaptıysanız, son uygulamanız bir framework kullanmak ve uygulama kodlarını ve hataları en aza indirmekle aynı ek yÃŒke sahip olacaktır. - * Eğer Uvicorn'u karşılaştırıyorsanız, Daphne, Hypercorn, uWSGI, vb. uygulama sunucuları ile karşılaştırın. + * Sunucunun kendisi dışında çok fazla ekstra kod içermediği için en iyi performansa sahip olacaktır. + * Uvicorn ile doğrudan bir uygulama yazmazsınız. Bu, kodunuzun en azından Starlette'in (veya **FastAPI**'ın) sağladığı kodun aşağı yukarı tamamını içermesi gerektiği anlamına gelir. Bunu yaparsanız, nihai uygulamanız; bir framework kullanmış olmanın ve uygulama kodunu ve bug'ları en aza indirmenin getirdiği ek yÃŒkle aynı ek yÃŒke sahip olur. + * Uvicorn'u karşılaştırıyorsanız, Daphne, Hypercorn, uWSGI vb. application server'larla karşılaştırın. * **Starlette**: - * Uvicorn'dan sonraki en iyi performansa sahip olacaktır. İşin aslı, Starlette çalışmak için Uvicorn'u kullanıyor. Dolayısıyla, daha fazla kod çalıştırmaası gerektiğinden muhtemelen Uvicorn'dan sadece "daha yavaş" olabilir. - * Ancak yol bazlı yönlendirme vb. basit web uygulamaları oluşturmak için araçlar sağlar. - * Eğer Starlette'i karşılaştırıyorsanız, Sanic, Flask, Django, vb. frameworkler (veya mikroframeworkler) ile karşılaştırın. + * Uvicorn'dan sonra en iyi performansa sahip olacaktır. Aslında Starlette çalışmak için Uvicorn'u kullanır. Bu yÃŒzden muhtemelen yalnızca daha fazla kod çalıştırmak zorunda kaldığı için Uvicorn'dan "daha yavaş" olabilir. + * Ancak path tabanlı routing vb. ile basit web uygulamaları oluşturmanız için araçlar sağlar. + * Starlette'i karşılaştırıyorsanız, Sanic, Flask, Django vb. web framework'lerle (veya mikroframework'lerle) karşılaştırın. * **FastAPI**: - * Starlette'in Uvicorn'u kullandığı ve ondan daha hızlı olamayacağı gibi, **FastAPI**'da Starlette'i kullanır, dolayısıyla ondan daha hızlı olamaz. - * FastAPI, Starlette'e ek olarak daha fazla özellik sunar. Bunlar veri doğrulama ve dönÌşÌmÃŒ gibi API'lar oluştururken neredeyse ve her zaman ihtiyaç duyduğunuz özelliklerdir. Ve bunu kullanarak, ÃŒcretsiz olarak otomatik dokÃŒmantasyon elde edersiniz (otomatik dokÃŒmantasyon çalışan uygulamalara ek yÃŒk getirmez, başlangıçta oluşturulur). - * FastAPI'ı kullanmadıysanız ve Starlette'i doğrudan kullandıysanız (veya başka bir araç, Sanic, Flask, Responder, vb.) tÃŒm veri doğrulama ve dönÌştÃŒrme araçlarını kendiniz geliştirmeniz gerekir. Dolayısıyla, son uygulamanız FastAPI kullanılarak oluşturulmuş gibi hâlâ aynı ek yÃŒke sahip olacaktır. Çoğu durumda, uygulamalarda yazılan kodun bÃŒyÃŒk bir kısmını veri doğrulama ve dönÌştÃŒrme kodları oluşturur. - * Dolayısıyla, FastAPI'ı kullanarak geliştirme sÃŒresinden, hatalardan, kod satırlarından tasarruf edersiniz ve kullanmadığınız durumda (birçok özelliği geliştirmek zorunda kalmakla birlikte) muhtemelen aynı performansı (veya daha iyisini) elde ederdiniz. - * Eğer FastAPI'ı karşılaştırıyorsanız, Flask-apispec, NestJS, Molten, vb. gibi veri doğrulama, dönÌştÃŒrme ve dokÃŒmantasyon sağlayan bir web uygulaması frameworkÃŒ ile (veya araç setiyle) karşılaştırın. + * Starlette'in Uvicorn'u kullanıp ondan daha hızlı olamaması gibi, **FastAPI** da Starlette'i kullanır; dolayısıyla ondan daha hızlı olamaz. + * FastAPI, Starlette'in ÃŒzerine daha fazla özellik sağlar. API'lar oluştururken neredeyse her zaman ihtiyaç duyduğunuz veri doğrulama ve serialization gibi özellikler. Ayrıca bunu kullanarak ÃŒcretsiz olarak otomatik dokÃŒmantasyon elde edersiniz (otomatik dokÃŒmantasyon, çalışan uygulamalara ek yÃŒk bile getirmez; startup'ta ÃŒretilir). + * FastAPI'ı kullanmayıp Starlette'i doğrudan kullansaydınız (veya Sanic, Flask, Responder vb. başka bir aracı), tÃŒm veri doğrulama ve serialization işlemlerini kendiniz uygulamak zorunda kalırdınız. Dolayısıyla nihai uygulamanız, FastAPI kullanılarak inşa edilmiş olsaydı sahip olacağı ek yÃŒkle hâlâ aynı ek yÃŒke sahip olurdu. Ve çoğu durumda, uygulamalarda yazılan en bÃŒyÃŒk kod miktarı veri doğrulama ve serialization kısmıdır. + * Bu nedenle FastAPI kullanarak geliştirme sÃŒresinden, bug'lardan, kod satırlarından tasarruf edersiniz; ayrıca muhtemelen, onu kullanmasaydınız (tÃŒm bunları kodunuzda kendiniz uygulamak zorunda kalacağınız için) elde edeceğiniz performansın aynısını (veya daha iyisini) elde edersiniz. + * FastAPI'ı karşılaştırıyorsanız, Flask-apispec, NestJS, Molten vb. veri doğrulama, serialization ve dokÃŒmantasyon sağlayan bir web uygulaması framework'ÃŒ (veya araç seti) ile karşılaştırın. Entegre otomatik veri doğrulama, serialization ve dokÃŒmantasyona sahip framework'ler. diff --git a/docs/tr/docs/deployment/cloud.md b/docs/tr/docs/deployment/cloud.md index 4f82e9d0bb..25ce6ca8dd 100644 --- a/docs/tr/docs/deployment/cloud.md +++ b/docs/tr/docs/deployment/cloud.md @@ -1,13 +1,24 @@ -# FastAPI Uygulamasını Bulut Sağlayıcılar Üzerinde Yayınlama +# Bulut Sağlayıcılar Üzerinde FastAPI Yayınlama { #deploy-fastapi-on-cloud-providers } -FastAPI uygulamasını yayınlamak için hemen hemen **herhangi bir bulut sağlayıcıyı** kullanabilirsiniz. +FastAPI uygulamanızı yayınlamak için neredeyse **herhangi bir bulut sağlayıcıyı** kullanabilirsiniz. -BÃŒyÃŒk bulut sağlayıcıların çoğu FastAPI uygulamasını yayınlamak için kılavuzlara sahiptir. +Çoğu durumda, ana bulut sağlayıcıların FastAPI'yi onlarla birlikte yayınlamak için kılavuzları vardır. -## Bulut Sağlayıcılar - Sponsorlar +## FastAPI Cloud { #fastapi-cloud } -Bazı bulut sağlayıcılar ✹ [**FastAPI destekçileridir**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✹, bu FastAPI ve **ekosisteminin** sÃŒrekli ve sağlıklı bir şekilde **gelişmesini** sağlar. +**FastAPI Cloud**, **FastAPI**'nin arkasındaki aynı yazar ve ekip tarafından geliştirilmiştir. -Ayrıca, size **iyi servisler** sağlamakla kalmayıp, **iyi ve sağlıklı bir framework** olan FastAPI'a bağlılıklarını gösterir. +Bir API'yi minimum çabayla **oluşturma**, **yayınlama** ve **erişme** sÃŒrecini kolaylaştırır. -Bu hizmetleri denemek ve kılavuzlarını incelemek isteyebilirsiniz. +FastAPI ile uygulama geliştirirken elde edilen aynı **geliştirici deneyimini**, onları buluta **yayınlamaya** da taşır. 🎉 + +FastAPI Cloud, *FastAPI and friends* açık kaynak projelerinin birincil sponsoru ve finansman sağlayıcısıdır. ✹ + +## Bulut Sağlayıcılar - Sponsorlar { #cloud-providers-sponsors } + +Diğer bazı bulut sağlayıcılar da ✹ [**FastAPI'ye sponsor olur**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✹. 🙇 + +Kılavuzlarını takip etmek ve servislerini denemek için onları da değerlendirmek isteyebilirsiniz: + +* Render +* Railway diff --git a/docs/tr/docs/deployment/index.md b/docs/tr/docs/deployment/index.md index e03bb4ee0e..055d999294 100644 --- a/docs/tr/docs/deployment/index.md +++ b/docs/tr/docs/deployment/index.md @@ -1,21 +1,23 @@ -# Deployment (Yayınlama) +# Deployment { #deployment } -**FastAPI** uygulamasını deploy etmek oldukça kolaydır. +**FastAPI** uygulamasını deploy etmek nispeten kolaydır. -## Deployment Ne Anlama Gelir? +## Deployment Ne Anlama Gelir? { #what-does-deployment-mean } -Bir uygulamayı **deploy** etmek (yayınlamak), uygulamayı **kullanıcılara erişilebilir hale getirmek** için gerekli adımları gerçekleştirmek anlamına gelir. +Bir uygulamayı **deploy** etmek, onu **kullanıcılara erişilebilir hale getirmek** için gerekli adımları gerçekleştirmek anlamına gelir. -Bir **Web API** için bu sÃŒreç normalde uygulamayı **uzak bir makineye** yerleştirmeyi, iyi performans, kararlılık vb. özellikler sağlayan bir **sunucu programı** ile **kullanıcılarınızın** uygulamaya etkili ve kesintisiz bir şekilde **erişebilmesini** kapsar. +Bir **web API** için bu sÃŒreç normalde uygulamayı **uzak bir makineye** yerleştirmeyi, iyi performans, kararlılık vb. özellikler sağlayan bir **sunucu programı** ile **kullanıcılarınızın** uygulamaya etkili ve kesintisiz bir şekilde, sorun yaşamadan **erişebilmesini** kapsar. -Bu, kodu sÃŒrekli olarak değiştirdiğiniz, hata alıp hata giderdiğiniz, geliştirme sunucusunu durdurup yeniden başlattığınız vb. **geliştirme** aşamalarının tam tersidir. +Bu, kodu sÃŒrekli olarak değiştirdiğiniz, bozup dÃŒzelttiğiniz, geliştirme sunucusunu durdurup yeniden başlattığınız vb. **geliştirme** aşamalarının tam tersidir. -## Deployment Stratejileri +## Deployment Stratejileri { #deployment-strategies } -Kullanım durumunuza ve kullandığınız araçlara bağlı olarak bir kaç farklı yol izleyebilirsiniz. +Kullanım durumunuza ve kullandığınız araçlara bağlı olarak bunu yapmanın birkaç yolu vardır. -Bir dizi araç kombinasyonunu kullanarak kendiniz **bir sunucu yayınlayabilirsiniz**, yayınlama sÃŒrecinin bir kısmını sizin için gerçekleştiren bir **bulut hizmeti** veya diğer olası seçenekleri kullanabilirsiniz. +Bir dizi araç kombinasyonunu kullanarak kendiniz **bir sunucu deploy edebilirsiniz**, yayınlama sÃŒrecinin bir kısmını sizin için gerçekleştiren bir **bulut hizmeti** veya diğer olası seçenekleri kullanabilirsiniz. + +Örneğin, FastAPI'nin arkasındaki ekip olarak, FastAPI uygulamalarını buluta mÃŒmkÃŒn olduğunca akıcı şekilde deploy etmeyi sağlamak için, FastAPI ile çalışmanın aynı geliştirici deneyimini sunarak **FastAPI Cloud**'u oluşturduk. **FastAPI** uygulamasını yayınlarken aklınızda bulundurmanız gereken ana kavramlardan bazılarını size göstereceğim (ancak bunların çoğu diğer web uygulamaları için de geçerlidir). -Sonraki bölÃŒmlerde akılda tutulması gereken diğer ayrıntıları ve yayınlama tekniklerinden bazılarını göreceksiniz. ✹ +Sonraki bölÃŒmlerde akılda tutulması gereken diğer ayrıntıları ve bunu yapmaya yönelik bazı teknikleri göreceksiniz. ✹ diff --git a/docs/tr/docs/how-to/general.md b/docs/tr/docs/how-to/general.md index cbfa7beb27..e3154921a4 100644 --- a/docs/tr/docs/how-to/general.md +++ b/docs/tr/docs/how-to/general.md @@ -1,39 +1,39 @@ -# Genel - Nasıl Yapılır - Tarifler +# Genel - Nasıl Yapılır - Tarifler { #general-how-to-recipes } -Bu sayfada genel ve sıkça sorulan sorular için dokÃŒmantasyonun diğer sayfalarına yönlendirmeler bulunmaktadır. +Bu sayfada genel veya sık sorulan sorular için dokÃŒmantasyonun diğer bölÃŒmlerine çeşitli yönlendirmeler bulunmaktadır. -## Veri Filtreleme - GÃŒvenlik +## Veri Filtreleme - GÃŒvenlik { #filter-data-security } -DöndÃŒrmeniz gereken veriden fazlasını döndÃŒrmediğinizden emin olmak için, [Tutorial - Response Model - Return Type](../tutorial/response-model.md){.internal-link target=_blank} sayfasını okuyun. +DöndÃŒrmeniz gerekenden daha fazla veri döndÃŒrmediğinizden emin olmak için, [Tutorial - Response Model - Return Type](../tutorial/response-model.md){.internal-link target=_blank} dokÃŒmantasyonunu okuyun. -## DokÃŒmantasyon Etiketleri - OpenAPI +## DokÃŒmantasyon Etiketleri - OpenAPI { #documentation-tags-openapi } -*Yol operasyonlarınıza* etiketler ekleyerek dokÃŒmantasyon arayÃŒzÃŒnde gruplar halinde görÃŒnmesini sağlamak için, [Tutorial - Path Operation Configurations - Tags](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank} sayfasını okuyun. +*path operation*'larınıza etiketler eklemek ve dokÃŒmantasyon arayÃŒzÃŒnde gruplamak için, [Tutorial - Path Operation Configurations - Tags](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank} dokÃŒmantasyonunu okuyun. -## DokÃŒmantasyon Özeti ve Açıklaması - OpenAPI +## DokÃŒmantasyon Özeti ve Açıklaması - OpenAPI { #documentation-summary-and-description-openapi } -*Yol operasyonlarınıza* özet ve açıklama ekleyip dokÃŒmantasyon arayÃŒzÃŒnde görÃŒnmesini sağlamak için, [Tutorial - Path Operation Configurations - Summary and Description](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank} sayfasını okuyun. +*path operation*'larınıza özet ve açıklama eklemek ve bunları dokÃŒmantasyon arayÃŒzÃŒnde göstermek için, [Tutorial - Path Operation Configurations - Summary and Description](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank} dokÃŒmantasyonunu okuyun. -## Yanıt Açıklaması DokÃŒmantasyonu - OpenAPI +## DokÃŒmantasyon Yanıt Açıklaması - OpenAPI { #documentation-response-description-openapi } -DokÃŒmantasyon arayÃŒzÃŒnde yer alan yanıt açıklamasını tanımlamak için, [Tutorial - Path Operation Configurations - Response description](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank} sayfasını okuyun. +DokÃŒmantasyon arayÃŒzÃŒnde gösterilen response açıklamasını tanımlamak için, [Tutorial - Path Operation Configurations - Response description](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank} dokÃŒmantasyonunu okuyun. -## *Yol Operasyonunu* Kullanımdan Kaldırma - OpenAPI +## DokÃŒmantasyonda Bir *Path Operation*'ı Kullanımdan Kaldırma - OpenAPI { #documentation-deprecate-a-path-operation-openapi } -Bir *yol işlemi*ni kullanımdan kaldırmak ve bunu dokÃŒmantasyon arayÃŒzÃŒnde göstermek için, [Tutorial - Path Operation Configurations - Deprecation](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank} sayfasını okuyun. +Bir *path operation*'ı kullanımdan kaldırmak ve bunu dokÃŒmantasyon arayÃŒzÃŒnde göstermek için, [Tutorial - Path Operation Configurations - Deprecation](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank} dokÃŒmantasyonunu okuyun. -## Herhangi Bir Veriyi JSON Uyumlu Hale Getirme +## Herhangi Bir Veriyi JSON Uyumlu Hale Getirme { #convert-any-data-to-json-compatible } -Herhangi bir veriyi JSON uyumlu hale getirmek için, [Tutorial - JSON Compatible Encoder](../tutorial/encoder.md){.internal-link target=_blank} sayfasını okuyun. +Herhangi bir veriyi JSON uyumlu hale getirmek için, [Tutorial - JSON Compatible Encoder](../tutorial/encoder.md){.internal-link target=_blank} dokÃŒmantasyonunu okuyun. -## OpenAPI Meta Verileri - DokÃŒmantasyon +## OpenAPI Meta Verileri - DokÃŒmantasyon { #openapi-metadata-docs } -OpenAPI şemanıza lisans, sÃŒrÃŒm, iletişim vb. meta veriler eklemek için, [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md){.internal-link target=_blank} sayfasını okuyun. +Lisans, sÃŒrÃŒm, iletişim vb. dahil olmak ÃŒzere OpenAPI şemanıza meta veriler eklemek için, [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md){.internal-link target=_blank} dokÃŒmantasyonunu okuyun. -## OpenAPI Bağlantı Özelleştirme +## OpenAPI Özel URL { #openapi-custom-url } -OpenAPI bağlantısını özelleştirmek (veya kaldırmak) için, [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md#openapi-url){.internal-link target=_blank} sayfasını okuyun. +OpenAPI URL'ini özelleştirmek (veya kaldırmak) için, [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md#openapi-url){.internal-link target=_blank} dokÃŒmantasyonunu okuyun. -## OpenAPI DokÃŒmantasyon Bağlantıları +## OpenAPI DokÃŒmantasyon URL'leri { #openapi-docs-urls } -DokÃŒmantasyonu arayÃŒzÃŒnde kullanılan bağlantıları gÃŒncellemek için, [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md#docs-urls){.internal-link target=_blank} sayfasını okuyun. +Otomatik olarak oluşturulan dokÃŒmantasyon kullanıcı arayÃŒzlerinde kullanılan URL'leri gÃŒncellemek için, [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md#docs-urls){.internal-link target=_blank} dokÃŒmantasyonunu okuyun. diff --git a/docs/tr/docs/how-to/index.md b/docs/tr/docs/how-to/index.md index 26dd9026ce..5ec2e0268f 100644 --- a/docs/tr/docs/how-to/index.md +++ b/docs/tr/docs/how-to/index.md @@ -1,13 +1,13 @@ -# Nasıl Yapılır - Tarifler +# Nasıl Yapılır - Tarifler { #how-to-recipes } -Burada çeşitli konular hakkında farklı tarifler veya "nasıl yapılır" kılavuzları yer alıyor. +Burada **çeşitli konular** hakkında farklı tarifler veya "nasıl yapılır" kılavuzları göreceksiniz. -Bu fikirlerin bÃŒyÃŒk bir kısmı aşağı yukarı **bağımsız** olacaktır, çoğu durumda bunları sadece **projenize** hitap ediyorsa incelemelisiniz. +Bu fikirlerin bÃŒyÃŒk bir kısmı aşağı yukarı **bağımsız** olacaktır ve çoğu durumda bunları yalnızca doğrudan **projenize** uygulanıyorsa incelemeniz yeterli olacaktır. -Projeniz için ilginç ve yararlı görÃŒnen bir şey varsa devam edin ve inceleyin, aksi halde bunları atlayabilirsiniz. +Projeniz için ilginç ve yararlı görÃŒnen bir şey varsa devam edin ve inceleyin; aksi halde muhtemelen bunları atlayabilirsiniz. /// 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. +**FastAPI**'ı yapılandırılmış bir şekilde (önerilir) **öğrenmek** istiyorsanız bunun yerine [Öğ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/index.md b/docs/tr/docs/index.md index 516d5959ef..9cffd4274f 100644 --- a/docs/tr/docs/index.md +++ b/docs/tr/docs/index.md @@ -1,14 +1,14 @@ -# FastAPI +# FastAPI { #fastapi }

- FastAPI + FastAPI

- FastAPI framework, yÃŒksek performanslı, öğrenmesi oldukça kolay, kodlaması hızlı, kullanıma hazır + FastAPI framework, yÃŒksek performanslı, öğrenmesi kolay, kodlaması hızlı, production'a hazır

@@ -27,59 +27,65 @@ --- -**DokÃŒmantasyon**: https://fastapi.tiangolo.com +**DokÃŒmantasyon**: https://fastapi.tiangolo.com **Kaynak Kod**: https://github.com/fastapi/fastapi --- -FastAPI, Python 'nin standart tip belirteçlerine dayalı, modern ve hızlı (yÃŒksek performanslı) API'lar oluşturmak için kullanılabilecek web framework'tÃŒr. +FastAPI, Python'un standart type hints'lerine dayalı olarak Python ile API'lar oluşturmak için kullanılan modern ve hızlı (yÃŒksek performanslı) bir web framework'ÃŒdÃŒr. Temel özellikleri şunlardır: -* **Hızlı**: Çok yÃŒksek performanslı, **NodeJS** ve **Go** ile eşit dÃŒzeyde (Starlette ve Pydantic sayesinde). [En hızlı Python framework'lerinden bir tanesidir](#performans). -* **Kodlaması Hızlı**: Geliştirme hızını yaklaşık %200 ile %300 aralığında arttırır. * +* **Hızlı**: Çok yÃŒksek performanslı, **NodeJS** ve **Go** ile eşit dÃŒzeyde (Starlette ve Pydantic sayesinde). [Mevcut en hızlı Python framework'lerinden biri](#performance). +* **Kodlaması Hızlı**: Özellik geliştirme hızını yaklaşık %200 ile %300 aralığında artırır. * * **Daha az hata**: Ä°nsan (geliştirici) kaynaklı hataları yaklaşık %40 azaltır. * -* **Sezgisel**: Muhteşem bir editör desteği. Her yerde otomatik tamamlama. Hata ayıklama ile daha az zaman harcayacaksınız. -* **Kolay**: Öğrenmesi ve kullanması kolay olacak şekilde tasarlandı. DokÃŒman okuma ile daha az zaman harcayacaksınız. -* **Kısa**: Kod tekrarı minimize edildi. Her parametre tanımlamasında birden fazla özellik ve daha az hatayla karşılaşacaksınız. -* **GÌçlÃŒ**: Otomatik ve etkileşimli dokÃŒmantasyon ile birlikte, kullanıma hazır kod elde edebilirsiniz. -* **Standard öncelikli**: API'lar için açık standartlara dayalı (ve tamamen uyumlu); OpenAPI (eski adıyla Swagger) ve JSON Schema. +* **Sezgisel**: Harika bir editör desteği. Her yerde Completion. Hata ayıklamaya daha az zaman. +* **Kolay**: Kullanımı ve öğrenmesi kolay olacak şekilde tasarlandı. DokÃŒman okumaya daha az zaman. +* **Kısa**: Kod tekrarını minimize eder. Her parametre tanımından birden fazla özellik. Daha az hata. +* **Sağlam**: Production'a hazır kod elde edersiniz. Otomatik etkileşimli dokÃŒmantasyon ile birlikte. +* **Standardlara dayalı**: API'lar için açık standartlara dayalıdır (ve tamamen uyumludur); OpenAPI (önceden Swagger olarak biliniyordu) ve JSON Schema. -* ilgili kanılar, dahili geliştirme ekibinin geliştirdikleri ÃŒrÃŒnlere yaptıkları testlere dayanmaktadır. +* tahmin, production uygulamalar geliştiren dahili bir geliştirme ekibinin yaptığı testlere dayanmaktadır. -## Sponsorlar +## Sponsorlar { #sponsors } -{% if sponsors %} +### Keystone Sponsor { #keystone-sponsor } + +{% for sponsor in sponsors.keystone -%} + +{% endfor -%} + +### Gold and Silver Sponsors { #gold-and-silver-sponsors } + {% for sponsor in sponsors.gold -%} {% endfor -%} {%- for sponsor in sponsors.silver -%} {% endfor %} -{% endif %} -Diğer Sponsorlar +Diğer sponsorlar -## GörÌşler +## GörÌşler { #opinions } -"_[...] BugÃŒnlerde **FastAPI**'ı çok fazla kullanıyorum. [...] Aslında bunu ekibimin **Microsoft'taki Machine Learning servislerinin** tamamında kullanmayı planlıyorum. Bunlardan bazıları **Windows**'un ana ÃŒrÃŒnlerine ve **Office** ÃŒrÃŒnlerine entegre ediliyor._" +"_[...] BugÃŒnlerde **FastAPI**'ı çok fazla kullanıyorum. [...] Aslında bunu ekibimin **Microsoft'taki ML servislerinin** tamamında kullanmayı planlıyorum. Bunlardan bazıları ana **Windows** ÃŒrÃŒnÃŒne ve bazı **Office** ÃŒrÃŒnlerine entegre ediliyor._"

Kabir Khan - Microsoft (ref)
--- -"_**FastAPI**'ı **tahminlerimiz**'i sorgulanabilir hale getirecek bir **REST** sunucu oluşturmak için benimsedik/kullanmaya başladık._" +"_**predictions** almak için sorgulanabilecek bir **REST** server oluşturmak amacıyla **FastAPI** kÃŒtÃŒphanesini benimsedik. [Ludwig için]_"
Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - Uber (ref)
--- -"_**Netflix**, **kriz yönetiminde** orkestrasyon yapabilmek için geliştirdiği yeni framework'ÃŒ **Dispatch**'in, açık kaynak sÃŒrÃŒmÃŒnÃŒ paylaşmaktan gurur duyuyor. [**FastAPI** ile yapıldı.]_" +"_**Netflix**, **kriz yönetimi** orkestrasyon framework'ÃŒmÃŒz: **Dispatch**'in open-source sÃŒrÃŒmÃŒnÃŒ duyurmaktan memnuniyet duyar! [**FastAPI** ile geliştirildi]_"
Kevin Glisson, Marc Vilanova, Forest Monsen - Netflix (ref)
@@ -91,70 +97,68 @@ Temel özellikleri şunlardır: --- -"_DÃŒrÃŒst olmak gerekirse, inşa ettiğiniz şey gerçekten sağlam ve profesyonel görÃŒnÃŒyor. Birçok açıdan **Hug**'ın olmasını istediğim şey tam da bu - böyle bir şeyi inşa eden birini görmek gerçekten ilham verici._" +"_DÃŒrÃŒst olmak gerekirse, inşa ettiğiniz şey gerçekten sağlam ve profesyonel görÃŒnÃŒyor. Birçok açıdan, **Hug**'ın olmasını istediğim şey tam da bu - böyle bir şeyi inşa eden birini görmek gerçekten ilham verici._" -
Timothy Crosley - Hug'ın Yaratıcısı (ref)
+
Timothy Crosley - Hug yaratıcısı (ref)
--- -"_Eğer REST API geliştirmek için **modern bir framework** öğrenme arayışında isen, **FastAPI**'a bir göz at [...] Hızlı, kullanımı ve öğrenmesi kolay. [...]_" +"_REST API'lar geliştirmek için **modern bir framework** öğrenmek istiyorsanız, **FastAPI**'a bir göz atın [...] Hızlı, kullanımı ve öğrenmesi kolay [...]_" -"_**API** servislerimizi **FastAPI**'a taşıdık [...] Sizin de beğeneceğinizi dÌşÌnÃŒyoruz. [...]_" +"_**API**'larımız için **FastAPI**'a geçtik [...] Bence hoşunuza gidecek [...]_"
Ines Montani - Matthew Honnibal - Explosion AI kurucuları - spaCy yaratıcıları (ref) - (ref)
--- -"_Python ile kullanıma hazır bir API oluşturmak isteyen herhangi biri için, **FastAPI**'ı şiddetle tavsiye ederim. **Harika tasarlanmış**, **kullanımı kolay** ve **yÃŒksek ölçeklenebilir**, API odaklı geliştirme stratejimizin **ana bileşeni** haline geldi ve Virtual TAC Engineer gibi birçok otomasyon ve servisi yönetiyor._" +"_Production'da Python API geliştirmek isteyen herkese **FastAPI**'ı şiddetle tavsiye ederim. **Harika tasarlanmış**, **kullanımı kolay** ve **yÃŒksek ölçeklenebilir**; API-first geliştirme stratejimizin **kilit bir bileşeni** haline geldi ve Virtual TAC Engineer gibi birçok otomasyon ve servise gÌç veriyor._"
Deon Pillsbury - Cisco (ref)
--- -## Komut Satırı Uygulamalarının FastAPI'ı: **Typer** +## FastAPI mini belgeseli { #fastapi-mini-documentary } + +2025'in sonunda yayınlanan bir FastAPI mini belgeseli var, online olarak izleyebilirsiniz: + +FastAPI Mini Documentary + +## CLI'ların FastAPI'ı: **Typer** { #typer-the-fastapi-of-clis } -Eğer API yerine, terminalde kullanılmak ÃŒzere bir komut satırı uygulaması geliştiriyorsanız **Typer**'a göz atabilirsiniz. +Web API yerine terminalde kullanılacak bir CLI uygulaması geliştiriyorsanız **Typer**'a göz atın. -**Typer** kısaca FastAPI'ın kÌçÌk kardeşi. Ve hedefi komut satırı uygulamalarının **FastAPI'ı** olmak. ⌚ 🚀 +**Typer**, FastAPI'ın kÌçÌk kardeşi. Ve hedefi CLI'ların **FastAPI'ı** olmak. ⌚ 🚀 -## Gereksinimler +## Gereksinimler { #requirements } FastAPI iki devin omuzları ÃŒstÃŒnde duruyor: -* Web tarafı için Starlette. -* Data tarafı için Pydantic. +* Web kısımları için Starlette. +* Data kısımları için Pydantic. -## Kurulum +## Kurulum { #installation } + +Bir virtual environment oluşturup etkinleştirelim ve ardından FastAPI'ı yÃŒkleyelim:
```console -$ pip install fastapi +$ pip install "fastapi[standard]" ---> 100% ```
-Uygulamamızı kullanılabilir hale getirmek için Uvicorn ya da Hypercorn gibi bir ASGI sunucusuna ihtiyacımız olacak. +**Not**: TÃŒm terminallerde çalıştığından emin olmak için `"fastapi[standard]"` ifadesini tırnak içinde yazdığınızdan emin olun. -
+## Örnek { #example } -```console -$ pip install "uvicorn[standard]" +### Oluşturalım { #create-it } ----> 100% -``` - -
- -## Örnek - -### Kodu Oluşturalım - -* `main.py` adında bir dosya oluşturup içine şu kodu yapıştıralım: +Şu içerikle `main.py` adında bir dosya oluşturalım: ```Python from typing import Union @@ -175,9 +179,9 @@ def read_item(item_id: int, q: Union[str, None] = None): ```
-Ya da async def... +Ya da async def kullanalım... -Eğer kodunuzda `async` / `await` varsa, `async def` kullanalım: +Eğer kodunuz `async` / `await` kullanıyorsa, `async def` kullanın: ```Python hl_lines="9 14" from typing import Union @@ -199,22 +203,35 @@ async def read_item(item_id: int, q: Union[str, None] = None): **Not**: -Eğer bu konu hakkında bilginiz yoksa `async` ve `await` dokÃŒmantasyonundaki _"Aceleniz mi var?"_ kısmını kontrol edebilirsiniz. +Eğer bilmiyorsanız, dokÃŒmanlardaki `async` ve `await` hakkında _"Aceleniz mi var?"_ bölÃŒmÃŒne bakın.
-### Kodu Çalıştıralım +### Çalıştıralım { #run-it } -Sunucuyu aşağıdaki komutla çalıştıralım: +Sunucuyu şu komutla çalıştıralım:
```console -$ uvicorn main:app --reload +$ fastapi dev main.py + ╭────────── FastAPI CLI - Development mode ───────────╮ + │ │ + │ Serving at: http://127.0.0.1:8000 │ + │ │ + │ API docs: http://127.0.0.1:8000/docs │ + │ │ + │ Running in development mode, for production use: │ + │ │ + │ fastapi run │ + │ │ + ╰─────────────────────────────────────────────────────╯ + +INFO: Will watch for changes in these directories: ['/home/user/code/awesomeapp'] INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -INFO: Started reloader process [28720] -INFO: Started server process [28722] +INFO: Started reloader process [2248755] using WatchFiles +INFO: Started server process [2248757] INFO: Waiting for application startup. INFO: Application startup complete. ``` @@ -222,54 +239,54 @@ INFO: Application startup complete.
-uvicorn main:app --reload komutuyla ilgili... +fastapi dev main.py komutu hakkında... -`uvicorn main:app` komutunu şu şekilde açıklayabiliriz: +`fastapi dev` komutu, `main.py` dosyanızı okur, içindeki **FastAPI** uygulamasını algılar ve Uvicorn kullanarak bir server başlatır. -* `main`: dosya olan `main.py` (yani Python "modÃŒlÃŒ"). -* `app`: ise `main.py` dosyasının içerisinde `app = FastAPI()` satırında oluşturduğumuz `FastAPI` nesnesi. -* `--reload`: kod değişikliklerinin ardından sunucuyu otomatik olarak yeniden başlatır. Bu parameteyi sadece geliştirme aşamasında kullanmalıyız. +Varsayılan olarak `fastapi dev`, local geliştirme için auto-reload etkin şekilde başlar. + +Daha fazla bilgi için FastAPI CLI dokÃŒmantasyonu'nu okuyabilirsiniz.
-### Şimdi de Kontrol Edelim +### Kontrol Edelim { #check-it } -Tarayıcımızda şu bağlantıyı açalım http://127.0.0.1:8000/items/5?q=somequery. +Tarayıcınızda şu bağlantıyı açın: http://127.0.0.1:8000/items/5?q=somequery. -Aşağıdaki gibi bir JSON yanıtıyla karşılaşacağız: +Şu JSON response'unu göreceksiniz: ```JSON {"item_id": 5, "q": "somequery"} ``` -Az önce oluşturduğumuz API: +Artık şunları yapan bir API oluşturdunuz: -* `/` ve `/items/{item_id}` _yollarına_ HTTP isteği alabilir. -* Ä°ki _yolda_ `GET` operasyonlarını (HTTP _metodları_ olarak da bilinen) kabul ediyor. -* `/items/{item_id}` _yolu_ `item_id` adında bir _yol parametresine_ sahip ve bu parametre `int` değer almak zorundadır. -* `/items/{item_id}` _yolu_ `q` adında bir _yol parametresine_ sahip ve bu parametre opsiyonel olmakla birlikte, `str` değer almak zorundadır. +* `/` ve `/items/{item_id}` _path_'lerinde HTTP request'leri alır. +* Her iki _path_ de `GET` operasyonlarını (HTTP _method_'ları olarak da bilinir) kabul eder. +* `/items/{item_id}` _path_'i, `int` olması gereken `item_id` adlı bir _path parameter_'a sahiptir. +* `/items/{item_id}` _path_'i, opsiyonel `str` bir _query parameter_ olan `q`'ya sahiptir. -### Etkileşimli API DokÃŒmantasyonu +### Etkileşimli API dokÃŒmantasyonu { #interactive-api-docs } -Şimdi http://127.0.0.1:8000/docs bağlantısını açalım. +Şimdi http://127.0.0.1:8000/docs adresine gidin. -Swagger UI tarafından sağlanan otomatik etkileşimli bir API dokÃŒmantasyonu göreceğiz: +Otomatik etkileşimli API dokÃŒmantasyonunu göreceksiniz (Swagger UI tarafından sağlanır): ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) -### Alternatif API DokÃŒmantasyonu +### Alternatif API dokÃŒmantasyonu { #alternative-api-docs } -Şimdi http://127.0.0.1:8000/redoc bağlantısını açalım. +Ve şimdi http://127.0.0.1:8000/redoc adresine gidin. -ReDoc tarafından sağlanan otomatik dokÃŒmantasyonu göreceğiz: +Alternatif otomatik dokÃŒmantasyonu göreceksiniz (ReDoc tarafından sağlanır): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) -## Örneği GÃŒncelleyelim +## Örneği GÃŒncelleyelim { #example-upgrade } -Şimdi `main.py` dosyasını, `PUT` isteğiyle birlikte bir gövde alacak şekilde değiştirelim. +Şimdi `main.py` dosyasını, `PUT` request'iyle gelen bir body alacak şekilde değiştirelim. -Gövdeyi Pydantic sayesinde standart python tiplerini kullanarak tanımlayalım. +Body'yi Pydantic sayesinde standart Python tiplerini kullanarak tanımlayalım. ```Python hl_lines="4 9-12 25-27" from typing import Union @@ -301,174 +318,248 @@ def update_item(item_id: int, item: Item): return {"item_name": item.name, "item_id": item_id} ``` -Sunucu otomatik olarak yeniden başlamış olmalı (çÌnkÃŒ yukarıda `uvicorn` komutuyla birlikte `--reload` parametresini kullandık). +`fastapi dev` server'ı otomatik olarak yeniden yÃŒklemelidir. -### Etkileşimli API DokÃŒmantasyonundaki Değişimi Görelim +### Etkileşimli API dokÃŒmantasyonu gÃŒncellemesi { #interactive-api-docs-upgrade } -Şimdi http://127.0.0.1:8000/docs bağlantısına tekrar gidelim. +Şimdi http://127.0.0.1:8000/docs adresine gidin. -* Etkileşimli API dokÃŒmantasyonu, yeni gövdede dahil olmak ÃŒzere otomatik olarak gÃŒncellenmiş olacak: +* Etkileşimli API dokÃŒmantasyonu, yeni body dahil olacak şekilde otomatik olarak gÃŒncellenecek: ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* "Try it out" butonuna tıklayalım, bu işlem API parametleri ÃŒzerinde değişiklik yapmamıza ve doğrudan API ile etkileşime geçmemize imkan sağlayacak: +* "Try it out" butonuna tıklayın; parametreleri doldurmanıza ve API ile doğrudan etkileşime girmenize olanak sağlar: ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-04-swagger-03.png) -* Şimdi "Execute" butonuna tıklayalım, kullanıcı arayÃŒzÃŒ API'ımız ile bağlantı kurup parametreleri gönderecek ve sonucu ekranımıza getirecek: +* Sonra "Execute" butonuna tıklayın; kullanıcı arayÃŒzÃŒ API'nız ile iletişim kuracak, parametreleri gönderecek, sonuçları alacak ve ekranda gösterecek: ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-05-swagger-04.png) -### Alternatif API DokÃŒmantasyonundaki Değişimi Görelim +### Alternatif API dokÃŒmantasyonu gÃŒncellemesi { #alternative-api-docs-upgrade } -Şimdi ise http://127.0.0.1:8000/redoc bağlantısına tekrar gidelim. +Ve şimdi http://127.0.0.1:8000/redoc adresine gidin. -* Alternatif dokÃŒmantasyonda yaptığımız değişiklikler ile birlikte yeni sorgu parametresi ve gövde bilgisi ile gÃŒncelemiş olacak: +* Alternatif dokÃŒmantasyon da yeni query parameter ve body'yi yansıtacak: ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) -### Özet +### Özet { #recap } -Özetlemek gerekirse, parametrelerin, gövdenin, vb. veri tiplerini fonksiyon parametreleri olarak **bir kere** tanımlıyoruz. +Özetle, parametrelerin, body'nin vb. type'larını fonksiyon parametreleri olarak **bir kere** tanımlarsınız. -Bu işlemi standart modern Python tipleriyle yapıyoruz. +Bunu standart modern Python tipleriyle yaparsınız. -Yeni bir sözdizimi yapısını, bir kÃŒtÃŒphane özel metod veya sınıfları öğrenmeye gerek yoktur. +Yeni bir syntax, belirli bir kÃŒtÃŒphanenin method'larını ya da class'larını vb. öğrenmeniz gerekmez. -Hepsi sadece **Python** standartlarına dayalıdır. +Sadece standart **Python**. -Örnek olarak, `int` tanımlamak için: +Örneğin bir `int` için: ```Python item_id: int ``` -ya da daha kompleks herhangi bir python modelini tanımlayabiliriz, örneğin `Item` modeli için: +ya da daha karmaşık bir `Item` modeli için: ```Python item: Item ``` -...ve sadece kısa bir parametre tipi belirterek elde ettiklerimiz: +...ve bu tek tanımla şunları elde edersiniz: -* Editör desteğiyle birlikte: - * Otomatik tamamlama. - * Tip kontrolÃŒ. -* Veri Doğrulama: - * Veri geçerli değilse, otomatik olarak açıklayıcı hatalar gösterir. - * Çok derin JSON nesnelerinde bile doğrulama yapar. -* Gelen verinin dönÌşÌmÃŒnÃŒ aşağıdaki veri tiplerini kullanarak gerçekleştirir: +* Şunlar dahil editör desteği: + * Completion. + * Type kontrolleri. +* Verinin doğrulanması: + * Veri geçersiz olduğunda otomatik ve anlaşılır hatalar. + * Çok derin iç içe JSON nesneleri için bile doğrulama. +* Girdi verisinin DönÌşÌmÃŒ: network'ten gelen veriyi Python verisine ve type'larına çevirir. Şunlardan okur: * JSON. - * Yol parametreleri. - * Sorgu parametreleri. - * Çerezler. - * Headers. - * Formlar. - * Dosyalar. -* Giden verinin dönÌşÌmÃŒnÃŒ aşağıdaki veri tiplerini kullanarak gerçekleştirir (JSON olarak): - * Python tiplerinin (`str`, `int`, `float`, `bool`, `list`, vb) dönÌşÌmÃŒ. - * `datetime` nesnesi. - * `UUID` nesnesi. + * Path parameter'lar. + * Query parameter'lar. + * Cookie'ler. + * Header'lar. + * Form'lar. + * File'lar. +* Çıktı verisinin DönÌşÌmÃŒ: Python verisini ve type'larını network verisine çevirir (JSON olarak): + * Python type'larını dönÌştÃŒrÃŒr (`str`, `int`, `float`, `bool`, `list`, vb.). + * `datetime` nesneleri. + * `UUID` nesneleri. * Veritabanı modelleri. - * ve çok daha fazlası... -* 2 alternatif kullanıcı arayÃŒzÃŒ dahil olmak ÃŒzere, otomatik etkileşimli API dokÃŒmantasyonu sağlar: + * ...ve daha fazlası. +* 2 alternatif kullanıcı arayÃŒzÃŒ dahil otomatik etkileşimli API dokÃŒmantasyonu: * Swagger UI. * ReDoc. --- -Az önceki örneğe geri dönelim, **FastAPI**'ın yapacaklarına bir bakış atalım: +Önceki kod örneğine dönersek, **FastAPI** şunları yapacaktır: -* `item_id`'nin `GET` ve `PUT` istekleri için, yolda olup olmadığının kontol edecek. -* `item_id`'nin `GET` ve `PUT` istekleri için, tipinin `int` olduğunu doğrulayacak. - * Eğer değilse, sebebini belirten bir hata mesajı gösterecek. -* Opsiyonel bir `q` parametresinin `GET` isteği içinde (`http://127.0.0.1:8000/items/foo?q=somequery` gibi) olup olmadığını kontrol edecek - * `q` parametresini `= None` ile oluşturduğumuz için, opsiyonel bir parametre olacak. - * Eğer `None` olmasa zorunlu bir parametre olacaktı (`PUT` metodunun gövdesinde olduğu gibi). -* `PUT` isteği için `/items/{item_id}`'nin gövdesini, JSON olarak doğrulayıp okuyacak: - * `name` adında zorunlu bir parametre olup olmadığını ve varsa tipinin `str` olup olmadığını kontol edecek. - * `price` adında zorunlu bir parametre olup olmadığını ve varsa tipinin `float` olup olmadığını kontol edecek. - * `is_offer` adında opsiyonel bir parametre olup olmadığını ve varsa tipinin `float` olup olmadığını kontol edecek. - * Bunların hepsi en derin JSON nesnelerinde bile çalışacak. -* Verilerin JSON'a ve JSON'ın python nesnesine dönÌşÌmÃŒ otomatik olarak yapılacak. -* Her şeyi OpenAPI ile uyumlu bir şekilde otomatik olarak dokÃŒmanlayacak ve bunlarda aşağıdaki gibi kullanılabilecek: +* `GET` ve `PUT` request'leri için path'te `item_id` olduğunu doğrular. +* `GET` ve `PUT` request'leri için `item_id`'nin type'ının `int` olduğunu doğrular. + * Değilse, client faydalı ve anlaşılır bir hata görÃŒr. +* `GET` request'leri için `q` adlı opsiyonel bir query parameter olup olmadığını kontrol eder (`http://127.0.0.1:8000/items/foo?q=somequery` örneğindeki gibi). + * `q` parametresi `= None` ile tanımlandığı için opsiyoneldir. + * `None` olmasaydı zorunlu olurdu (tıpkı `PUT` örneğindeki body gibi). +* `/items/{item_id}`'ye yapılan `PUT` request'leri için body'yi JSON olarak okur: + * `str` olması gereken, zorunlu `name` alanı olduğunu kontrol eder. + * `float` olması gereken, zorunlu `price` alanı olduğunu kontrol eder. + * Varsa, `bool` olması gereken opsiyonel `is_offer` alanını kontrol eder. + * Bunların hepsi çok derin iç içe JSON nesneleri için de çalışır. +* JSON'a ve JSON'dan dönÌşÌmÃŒ otomatik yapar. +* Her şeyi OpenAPI ile dokÃŒmante eder; bu dokÃŒmantasyon şunlar tarafından kullanılabilir: * Etkileşimli dokÃŒmantasyon sistemleri. - * Bir çok programlama dili için otomatik istemci kodu ÃŒretim sistemleri. -* Ä°ki ayrı etkileşimli dokÃŒmantasyon arayÃŒzÃŒnÃŒ doğrudan sağlayacak. + * Birçok dil için otomatik client kodu ÃŒretim sistemleri. +* 2 etkileşimli dokÃŒmantasyon web arayÃŒzÃŒnÃŒ doğrudan sunar. --- -Daha yeni başladık ama çalışma mantığını çoktan anlamış oldunuz. +Daha yolun başındayız, ama bunun nasıl çalıştığı hakkında fikri kaptınız. -Şimdi aşağıdaki satırı değiştirmeyi deneyin: +Şu satırı değiştirmeyi deneyin: ```Python return {"item_name": item.name, "item_id": item_id} ``` -...bundan: +...şundan: ```Python ... "item_name": item.name ... ``` -...buna: +...şuna: ```Python ... "item_price": item.price ... ``` -...ve editörÃŒnÃŒn veri tiplerini bildiğini ve otomatik tamamladığını göreceksiniz: +...ve editörÃŒnÃŒzÃŒn alanları otomatik tamamladığını ve type'larını bildiğini görÃŒn: ![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) -Daha fazal özellik içeren, daha eksiksiz bir örnek için Öğretici - Kullanıcı Rehberi sayfasını ziyaret edebilirsin. +Daha fazla özellik içeren daha kapsamlı bir örnek için Öğretici - Kullanıcı Rehberi'ne bakın. -**Spoiler**: Öğretici - Kullanıcı rehberi şunları içerir: +**Spoiler alert**: öğretici - kullanıcı rehberi şunları içerir: -* **Parameterlerin**, **headers**, **çerezler**, **form alanları** ve **dosyalar** olarak tanımlanması. -* `maximum_length` ya da `regex` gibi **doğrulama kısıtlamalarının** nasıl yapılabileceği. -* Çok gÌçlÃŒ ve kullanımı kolay **Bağımlılık Enjeksiyonu** sistemi oluşturmayı. -* GÃŒvenlik ve kimlik doğrulama, **JWT tokenleri** ile **OAuth2** desteği, ve **HTTP Basic** doğrulaması. -* Ä°leri seviye fakat bir o kadarda basit olan **çok derin JSON modelleri** (Pydantic sayesinde). -* **GraphQL** entegrasyonu: Strawberry ve diğer kÃŒtÃŒphaneleri kullanarak. -* Diğer ekstra özellikler (Starlette sayesinde): - * **WebSocketler** - * HTTPX ve `pytest` sayesinde aşırı kolay testler. +* **parameter**'ların farklı yerlerden: **header**'lar, **cookie**'ler, **form alanları** ve **file**'lar olarak tanımlanması. +* `maximum_length` ya da `regex` gibi **doğrulama kısıtlamalarının** nasıl ayarlanacağı. +* Çok gÌçlÃŒ ve kullanımı kolay bir **Dependency Injection** sistemi. +* **JWT tokens** ve **HTTP Basic** auth ile **OAuth2** desteği dahil gÃŒvenlik ve kimlik doğrulama. +* **Çok derin iç içe JSON modelleri** tanımlamak için daha ileri (ama aynı derecede kolay) teknikler (Pydantic sayesinde). +* Strawberry ve diğer kÃŒtÃŒphaneler ile **GraphQL** entegrasyonu. +* Starlette sayesinde gelen birçok ek özellik: + * **WebSockets** + * HTTPX ve `pytest` tabanlı aşırı kolay testler * **CORS** * **Cookie Sessions** * ...ve daha fazlası. -## Performans +### Uygulamanızı deploy edin (opsiyonel) { #deploy-your-app-optional } -Bağımsız TechEmpower kıyaslamaları gösteriyor ki, Uvicorn ile çalıştırılan **FastAPI** uygulamaları en hızlı Python framework'lerinden birisi, sadece Starlette ve Uvicorn'dan yavaş, ki FastAPI bunların ÃŒzerine kurulu bir kÃŒtÃŒphanedir. +Ä°sterseniz FastAPI uygulamanızı FastAPI Cloud'a deploy edebilirsiniz; eğer henÃŒz yapmadıysanız gidip bekleme listesine katılın. 🚀 -Daha fazla bilgi için, bu bölÃŒme bir göz at Kıyaslamalar. +Zaten bir **FastAPI Cloud** hesabınız varsa (bekleme listesinden sizi davet ettiysek 😉), uygulamanızı tek bir komutla deploy edebilirsiniz. -## Opsiyonel Gereksinimler +Deploy etmeden önce, giriş yaptığınızdan emin olun: -Pydantic tarafında kullanılan: +
+ +```console +$ fastapi login + +You are logged in to FastAPI Cloud 🚀 +``` + +
+ +Sonra uygulamanızı deploy edin: + +
+ +```console +$ fastapi deploy + +Deploying to FastAPI Cloud... + +✅ Deployment successful! + +🐔 Ready the chicken! Your app is ready at https://myapp.fastapicloud.dev +``` + +
+ +Hepsi bu! Artık uygulamanıza bu URL'den erişebilirsiniz. ✹ + +#### FastAPI Cloud hakkında { #about-fastapi-cloud } + +**FastAPI Cloud**, **FastAPI**'ın arkasındaki aynı yazar ve ekip tarafından geliştirilmiştir. + +**Bir API'ı build etmek**, **deploy etmek** ve **erişmek** sÃŒreçlerini minimum eforla kolaylaştırır. + +FastAPI ile uygulama geliştirmenin sağladığı aynı **developer experience**'ı, onları cloud'a **deploy etmeye** de taşır. 🎉 + +FastAPI Cloud, *FastAPI and friends* open source projelerinin ana sponsoru ve finansman sağlayıcısıdır. ✹ + +#### Diğer cloud sağlayıcılarına deploy { #deploy-to-other-cloud-providers } + +FastAPI open source'tur ve standartlara dayanır. FastAPI uygulamalarını seçtiğiniz herhangi bir cloud sağlayıcısına deploy edebilirsiniz. + +FastAPI uygulamalarını onlarla deploy etmek için cloud sağlayıcınızın rehberlerini takip edin. 🀓 + +## Performans { #performance } + +Bağımsız TechEmpower kıyaslamaları, Uvicorn altında çalışan **FastAPI** uygulamalarının mevcut en hızlı Python framework'lerinden biri olduğunu gösteriyor; sadece Starlette ve Uvicorn'un kendisinin gerisinde (FastAPI tarafından dahili olarak kullanılır). (*) + +Daha iyi anlamak için Kıyaslamalar bölÃŒmÃŒne bakın. + +## Bağımlılıklar { #dependencies } + +FastAPI, Pydantic ve Starlette'a bağımlıdır. + +### `standard` Bağımlılıkları { #standard-dependencies } + +FastAPI'ı `pip install "fastapi[standard]"` ile yÃŒklediğinizde, opsiyonel bağımlılıkların `standard` grubuyla birlikte gelir: + +Pydantic tarafından kullanılanlar: * email-validator - email doğrulaması için. + +Starlette tarafından kullanılanlar: + +* httpx - `TestClient` kullanmak istiyorsanız gereklidir. +* jinja2 - varsayılan template yapılandırmasını kullanmak istiyorsanız gereklidir. +* python-multipart - `request.form()` ile, form "parsing" desteği istiyorsanız gereklidir. + +FastAPI tarafından kullanılanlar: + +* uvicorn - uygulamanızı yÃŒkleyen ve servis eden server için. Buna, yÃŒksek performanslı servis için gereken bazı bağımlılıkları (örn. `uvloop`) içeren `uvicorn[standard]` dahildir. +* `fastapi-cli[standard]` - `fastapi` komutunu sağlamak için. + * Buna, FastAPI uygulamanızı FastAPI Cloud'a deploy etmenizi sağlayan `fastapi-cloud-cli` dahildir. + +### `standard` Bağımlılıkları Olmadan { #without-standard-dependencies } + +`standard` opsiyonel bağımlılıklarını dahil etmek istemiyorsanız, `pip install "fastapi[standard]"` yerine `pip install fastapi` ile kurabilirsiniz. + +### `fastapi-cloud-cli` Olmadan { #without-fastapi-cloud-cli } + +FastAPI'ı standard bağımlılıklarla ama `fastapi-cloud-cli` olmadan kurmak istiyorsanız, `pip install "fastapi[standard-no-fastapi-cloud-cli]"` ile yÃŒkleyebilirsiniz. + +### Ek Opsiyonel Bağımlılıklar { #additional-optional-dependencies } + +YÃŒklemek isteyebileceğiniz bazı ek bağımlılıklar da vardır. + +Ek opsiyonel Pydantic bağımlılıkları: + * pydantic-settings - ayar yönetimi için. -* pydantic-extra-types - Pydantic ile birlikte kullanılabilecek ek tipler için. +* pydantic-extra-types - Pydantic ile kullanılacak ek type'lar için. -Starlette tarafında kullanılan: +Ek opsiyonel FastAPI bağımlılıkları: -* httpx - Eğer `TestClient` yapısını kullanacaksanız gereklidir. -* jinja2 - Eğer varsayılan template konfigÃŒrasyonunu kullanacaksanız gereklidir. -* python-multipart - Eğer `request.form()` ile form dönÌşÌmÃŒ desteğini kullanacaksanız gereklidir. -* itsdangerous - `SessionMiddleware` desteği için gerekli. -* pyyaml - `SchemaGenerator` desteği için gerekli (Muhtemelen FastAPI kullanırken ihtiyacınız olmaz). +* orjson - `ORJSONResponse` kullanmak istiyorsanız gereklidir. +* ujson - `UJSONResponse` kullanmak istiyorsanız gereklidir. -Hem FastAPI hem de Starlette tarafından kullanılan: +## Lisans { #license } -* uvicorn - oluşturduğumuz uygulamayı servis edecek web sunucusu görevini ÃŒstlenir. -* orjson - `ORJSONResponse` kullanacaksanız gereklidir. -* ujson - `UJSONResponse` kullanacaksanız gerekli. - -Bunların hepsini `pip install fastapi[all]` ile yÃŒkleyebilirsin. - -## Lisans - -Bu proje, MIT lisansı şartları altında lisanslanmıştır. +Bu proje MIT lisansı şartları altında lisanslanmıştır. diff --git a/docs/tr/docs/learn/index.md b/docs/tr/docs/learn/index.md index 52e3aa54df..accf971aa7 100644 --- a/docs/tr/docs/learn/index.md +++ b/docs/tr/docs/learn/index.md @@ -1,5 +1,5 @@ -# Öğren +# Öğren { #learn } **FastAPI** öğrenmek için giriş bölÃŒmleri ve öğreticiler burada yer alıyor. -Burayı, bir **kitap**, bir **kurs**, ve FastAPI öğrenmenin **resmi** ve önerilen yolu olarak dÌşÌnÃŒlebilirsiniz. 😎 +Burayı, bir **kitap**, bir **kurs**, FastAPI öğrenmenin **resmi** ve önerilen yolu olarak dÌşÌnebilirsiniz. 😎 diff --git a/docs/tr/docs/project-generation.md b/docs/tr/docs/project-generation.md index c9dc24acc4..bdc28f0c01 100644 --- a/docs/tr/docs/project-generation.md +++ b/docs/tr/docs/project-generation.md @@ -1,84 +1,28 @@ -# Proje oluşturma - Şablonlar +# Full Stack FastAPI Şablonu { #full-stack-fastapi-template } -Başlamak için bir proje oluşturucu kullanabilirsiniz, çÌnkÃŒ sizin için önceden yapılmış birçok başlangıç ​​kurulumu, gÃŒvenlik, veritabanı ve temel API endpoinlerini içerir. +Şablonlar genellikle belirli bir kurulumla gelir, ancak esnek ve özelleştirilebilir olacak şekilde tasarlanırlar. Bu sayede şablonu projenizin gereksinimlerine göre değiştirip uyarlayabilir, çok iyi bir başlangıç noktası olarak kullanabilirsiniz. 🏁 -Bir proje oluşturucu, her zaman kendi ihtiyaçlarınıza göre gÃŒncellemeniz ve uyarlamanız gereken esnek bir kuruluma sahip olacaktır, ancak bu, projeniz için iyi bir başlangıç ​​noktası olabilir. +Bu şablonu başlangıç için kullanabilirsiniz; çÌnkÃŒ ilk kurulumun, gÃŒvenliğin, veritabanının ve bazı API endpoint'lerinin önemli bir kısmı sizin için zaten hazırlanmıştır. -## Full Stack FastAPI PostgreSQL +GitHub Repository: Full Stack FastAPI Template -GitHub: https://github.com/tiangolo/full-stack-fastapi-postgresql +## Full Stack FastAPI Şablonu - Teknoloji Yığını ve Özellikler { #full-stack-fastapi-template-technology-stack-and-features } -### Full Stack FastAPI PostgreSQL - Özellikler - -* Full **Docker** entegrasyonu (Docker based). -* Docker Swarm Mode ile deployment. -* **Docker Compose** entegrasyonu ve lokal geliştirme için optimizasyon. -* Uvicorn ve Gunicorn ile **Production ready** Python web server'ı. -* Python **FastAPI** backend: - * **Hızlı**: **NodeJS** ve **Go** ile eşit, çok yÃŒksek performans (Starlette ve Pydantic'e teşekkÃŒrler). - * **Sezgisel**: Editor desteğı. Otomatik tamamlama. Daha az debugging. - * **Kolay**: Kolay öğrenip kolay kullanmak için tasarlandı. Daha az dökÃŒman okuma daha çok iş. - * **Kısa**: Minimum kod tekrarı. Her parametre bildiriminde birden çok özellik. - * **GÌçlÃŒ**: Production-ready. Otomatik interaktif dökÃŒmantasyon. - * **Standartlara dayalı**: API'ler için açık standartlara dayanır (ve tamamen uyumludur): OpenAPI ve JSON Şeması. - * **Birçok diger özelliği** dahili otomatik doğrulama, serialization, interaktif dokÃŒmantasyon, OAuth2 JWT token ile authentication, vb. -* **GÃŒvenli şifreleme** . -* **JWT token** kimlik doğrulama. -* **SQLAlchemy** models (Flask dan bağımsızdır. Celery worker'ları ile kullanılabilir). -* Kullanıcılar için temel başlangıç ​​modeli (gerektiği gibi değiştirin ve kaldırın). -* **Alembic** migration. -* **CORS** (Cross Origin Resource Sharing). -* **Celery** worker'ları ile backend içerisinden seçilen işleri çalıştırabilirsiniz. -* **Pytest**'e dayalı, Docker ile entegre REST backend testleri ile veritabanından bağımsız olarak tam API etkileşimini test edebilirsiniz. Docker'da çalıştığı için her seferinde sıfırdan yeni bir veri deposu oluşturabilir (böylece ElasticSearch, MongoDB, CouchDB veya ne istersen kullanabilirsin ve sadece API'nin çalışıp çalışmadığını test edebilirsin). -* Atom Hydrogen veya Visual Studio Code Jupyter gibi uzantılarla uzaktan veya Docker içi geliştirme için **Jupyter Çekirdekleri** ile kolay Python entegrasyonu. -* **Vue** ile frontend: - * Vue CLI ile oluşturulmuş. - * Dahili **JWT kimlik doğrulama**. - * Dahili Login. - * Login sonrası, Kontrol paneli. - * Kullanıcı oluşturma ve dÃŒzenleme kontrol paneli - * Kendi kendine kullanıcı sÃŒrÃŒmÃŒ. - * **Vuex**. - * **Vue-router**. - * **Vuetify** gÃŒzel material design kompanentleri için. - * **TypeScript**. - * **Nginx** tabanlı Docker sunucusu (Vue-router için yapılandırılmış). - * Docker ile multi-stage yapı, böylece kodu derlemeniz, kaydetmeniz veya işlemeniz gerekmez. - * Derleme zamanında Frontend testi (devre dışı bırakılabilir). - * MÃŒmkÃŒn olduğu kadar modÃŒler yapılmıştır, bu nedenle kutudan çıktığı gibi çalışır, ancak Vue CLI ile yeniden oluşturabilir veya ihtiyaç duyduğunuz şekilde oluşturabilir ve istediğinizi yeniden kullanabilirsiniz. -* **PGAdmin** PostgreSQL database admin tool'u, PHPMyAdmin ve MySQL ile kolayca değiştirilebilir. -* **Flower** ile Celery job'larını monitörleme. -* **Traefik** ile backend ve frontend arasında yÃŒk dengeleme, böylece her ikisini de aynı domain altında, path ile ayrılmış, ancak farklı kapsayıcılar tarafından sunulabilirsiniz. -* Let's Encrypt **HTTPS** sertifikalarının otomatik oluşturulması dahil olmak ÃŒzere Traefik entegrasyonu. -* GitLab **CI** (sÃŒrekli entegrasyon), backend ve frontend testi dahil. - -## Full Stack FastAPI Couchbase - -GitHub: https://github.com/tiangolo/full-stack-fastapi-couchbase - -⚠ **UYARI** ⚠ - -Sıfırdan bir projeye başlıyorsanız alternatiflerine bakın. - -Örneğin, Full Stack FastAPI PostgreSQL daha iyi bir alternatif olabilir, aktif olarak geliştiriliyor ve kullanılıyor. Ve yeni özellik ve ilerlemelere sahip. - -Ä°sterseniz Couchbase tabanlı generator'ı kullanmakta özgÃŒrsÃŒnÃŒz, hala iyi çalışıyor olmalı ve onunla oluşturulmuş bir projeniz varsa bu da sorun değil (ve muhtemelen zaten ihtiyaçlarınıza göre gÃŒncellediniz). - -Bununla ilgili daha fazla bilgiyi repo belgelerinde okuyabilirsiniz. - -## Full Stack FastAPI MongoDB - -... mÃŒsaitliğime ve diğer faktörlere bağlı olarak daha sonra gelebilir. 😅 🎉 - -## Machine Learning modelleri, spaCy ve FastAPI - -GitHub: https://github.com/microsoft/cookiecutter-spacy-fastapi - -### Machine Learning modelleri, spaCy ve FastAPI - Features - -* **spaCy** NER model entegrasyonu. -* **Azure Cognitive Search** yerleşik istek biçimi. -* Uvicorn ve Gunicorn ile **Production ready** Python web server'ı. -* Dahili **Azure DevOps** Kubernetes (AKS) CI/CD deployment. -* **Multilingual**, Proje kurulumu sırasında spaCy'nin yerleşik dillerinden birini kolayca seçin. -* **Esnetilebilir** diğer frameworkler (Pytorch, Tensorflow) ile de çalışır sadece spaCy değil. +- ⚡ Python backend API için [**FastAPI**](https://fastapi.tiangolo.com/tr). + - 🧰 Python SQL veritabanı etkileşimleri (ORM) için [SQLModel](https://sqlmodel.tiangolo.com). + - 🔍 FastAPI'nin kullandığı; veri doğrulama ve ayarlar yönetimi için [Pydantic](https://docs.pydantic.dev). + - 💟 SQL veritabanı olarak [PostgreSQL](https://www.postgresql.org). +- 🚀 frontend için [React](https://react.dev). + - 💃 TypeScript, hooks, Vite ve modern bir frontend stack'inin diğer parçalarını kullanır. + - 🎚 frontend component'leri için [Tailwind CSS](https://tailwindcss.com) ve [shadcn/ui](https://ui.shadcn.com). + - 🀖 Otomatik ÃŒretilen bir frontend client. + - 🧪 End-to-End testleri için [Playwright](https://playwright.dev). + - 🊇 Dark mode desteği. +- 🐋 Geliştirme ve production için [Docker Compose](https://www.docker.com). +- 🔒 Varsayılan olarak gÃŒvenli password hashing. +- 🔑 JWT (JSON Web Token) authentication. +- 📫 E-posta tabanlı şifre kurtarma. +- ✅ [Pytest](https://pytest.org) ile testler. +- 📞 Reverse proxy / load balancer olarak [Traefik](https://traefik.io). +- 🚢 Docker Compose kullanarak deployment talimatları; otomatik HTTPS sertifikalarını yönetmek için bir frontend Traefik proxy'sini nasıl kuracağınız dahil. +- 🏭 GitHub Actions tabanlı CI (continuous integration) ve CD (continuous deployment). diff --git a/docs/tr/docs/python-types.md b/docs/tr/docs/python-types.md index b44aa3b9d5..01a3efe98c 100644 --- a/docs/tr/docs/python-types.md +++ b/docs/tr/docs/python-types.md @@ -1,76 +1,74 @@ -# Python Veri Tiplerine Giriş +# Python Tiplerine Giriş { #python-types-intro } -Python isteğe bağlı olarak "tip belirteçlerini" destekler. +Python, isteğe bağlı "type hints" (diğer adıyla "type annotations") desteğine sahiptir. - **"Tip belirteçleri"** bir değişkenin tipinin belirtilmesine olanak sağlayan özel bir sözdizimidir. +Bu **"type hints"** veya annotations, bir değişkenin type'ını bildirmeye yarayan özel bir sözdizimidir. -Değişkenlerin tiplerini belirterek editör ve araçlardan daha fazla destek alabilirsiniz. +Değişkenleriniz için type bildirerek, editörler ve araçlar size daha iyi destek sağlayabilir. -Bu pythonda tip belirteçleri için **hızlı bir başlangıç / bilgi tazeleme** rehberidir . Bu rehber **FastAPI** kullanmak için gereken minimum konuyu kapsar ki bu da çok az bir miktardır. +Bu, Python type hints hakkında sadece **hızlı bir eğitim / bilgi tazeleme** dokÃŒmanıdır. **FastAPI** ile kullanmak için gereken minimum bilgiyi kapsar... ki aslında bu çok azdır. -**FastAPI' nin** tamamı bu tÃŒr tip belirteçleri ile donatılmıştır ve birçok avantaj sağlamaktadır. +**FastAPI** tamamen bu type hints ÃŒzerine kuruludur; bunlar ona birçok avantaj ve fayda sağlar. -**FastAPI** kullanmayacak olsanız bile tÃŒr belirteçleri hakkında bilgi edinmenizde fayda var. +Ancak hiç **FastAPI** kullanmasanız bile, bunlar hakkında biraz öğrenmeniz size fayda sağlayacaktır. /// note | Not -Python uzmanıysanız ve tip belirteçleri ilgili her şeyi zaten biliyorsanız, sonraki bölÃŒme geçin. +Eğer bir Python uzmanıysanız ve type hints hakkında her şeyi zaten biliyorsanız, sonraki bölÃŒme geçin. /// -## Motivasyon +## Motivasyon { #motivation } -Basit bir örnek ile başlayalım: +Basit bir örnekle başlayalım: -{* ../../docs_src/python_types/tutorial001.py *} +{* ../../docs_src/python_types/tutorial001_py39.py *} - -Programın çıktısı: +Bu programı çalıştırınca şu çıktıyı alırsınız: ``` John Doe ``` -Fonksiyon sırayla şunları yapar: +Fonksiyon şunları yapar: * `first_name` ve `last_name` değerlerini alır. -* `title()` ile değişkenlerin ilk karakterlerini bÃŒyÃŒtÃŒr. -* Değişkenleri aralarında bir boşlukla beraber Birleştirir. +* `title()` ile her birinin ilk harfini bÃŒyÃŒk harfe çevirir. +* Ortada bir boşluk olacak şekilde Concatenates eder. -{* ../../docs_src/python_types/tutorial001.py hl[2] *} +{* ../../docs_src/python_types/tutorial001_py39.py hl[2] *} - -### DÃŒzenle +### DÃŒzenleyelim { #edit-it } Bu çok basit bir program. -Ama şimdi sıfırdan yazdığınızı hayal edin. +Ama şimdi bunu sıfırdan yazdığınızı hayal edin. -Bir noktada fonksiyonun tanımına başlayacaktınız, parametreleri hazır hale getirdiniz... +Bir noktada fonksiyon tanımını yazmaya başlamış olacaktınız, parametreler hazır... -Ama sonra "ilk harfi bÃŒyÃŒk harfe dönÌştÃŒren yöntemi" çağırmanız gerekir. +Ama sonra "ilk harfi bÃŒyÃŒk harfe çeviren method"u çağırmanız gerekiyor. - `upper` mıydı ? Yoksa `uppercase`' mi? `first_uppercase`? `capitalize`? +`upper` mıydı? `uppercase` miydi? `first_uppercase`? `capitalize`? -Ardından, programcıların en iyi arkadaşı olan otomatik tamamlama ile denediniz. +Sonra eski programcı dostuyla denersiniz: editör autocomplete. -'first_name', ardından bir nokta ('.') yazıp otomatik tamamlamayı tetiklemek için 'Ctrl+Space' tuşlarına bastınız. +Fonksiyonun ilk parametresi olan `first_name`'i yazarsınız, sonra bir nokta (`.`) ve ardından autocomplete'i tetiklemek için `Ctrl+Space`'e basarsınız. -Ancak, ne yazık ki, yararlı hiçbir şey elde edemediniz: +Ama ne yazık ki, işe yarar bir şey göremezsiniz: -### Tipleri ekle +### Tipleri ekleyelim { #add-types } -Önceki sÃŒrÃŒmden sadece bir satırı değiştirelim. +Önceki sÃŒrÃŒmden tek bir satırı değiştirelim. -Tam olarak bu parçayı, işlevin parametrelerini değiştireceğiz: +Fonksiyonun parametreleri olan şu parçayı: ```Python first_name, last_name ``` -ve bu hale getireceğiz: +şuna çevireceğiz: ```Python first_name: str, last_name: str @@ -78,58 +76,55 @@ ve bu hale getireceğiz: Bu kadar. -İşte bunlar "tip belirteçleri": +Bunlar "type hints": -{* ../../docs_src/python_types/tutorial002.py hl[1] *} +{* ../../docs_src/python_types/tutorial002_py39.py hl[1] *} - -Bu, aşağıdaki gibi varsayılan değerleri bildirmekle aynı şey değildir: +Bu, aşağıdaki gibi default değerler bildirmekle aynı şey değildir: ```Python first_name="john", last_name="doe" ``` -Bu tamamen farklı birşey +Bu farklı bir şey. -Ä°ki nokta ÃŒst ÃŒste (`:`) kullanıyoruz , eşittir (`=`) değil. +Eşittir (`=`) değil, iki nokta (`:`) kullanıyoruz. -Normalde tip belirteçleri eklemek, kod ÃŒzerinde olacakları değiştirmez. +Ve type hints eklemek, normalde onlarsız ne oluyorsa onu değiştirmez. -Şimdi programı sıfırdan birdaha yazdığınızı hayal edin. +Ama şimdi, type hints ile o fonksiyonu oluşturmanın ortasında olduğunuzu tekrar hayal edin. -Aynı noktada, `Ctrl+Space` ile otomatik tamamlamayı tetiklediniz ve şunu görÃŒyorsunuz: +Aynı noktada, `Ctrl+Space` ile autocomplete'i tetiklemeye çalışırsınız ve şunu görÃŒrsÃŒnÃŒz: -Aradığınızı bulana kadar seçenekleri kaydırabilirsiniz: +Bununla birlikte, seçenekleri görerek kaydırabilirsiniz; ta ki "tanıdık gelen" seçeneği bulana kadar: -## Daha fazla motivasyon +## Daha fazla motivasyon { #more-motivation } -Bu fonksiyon, zaten tÃŒr belirteçlerine sahip: +Şu fonksiyona bakın, zaten type hints içeriyor: -{* ../../docs_src/python_types/tutorial003.py hl[1] *} +{* ../../docs_src/python_types/tutorial003_py39.py hl[1] *} - -Editör değişkenlerin tiplerini bildiğinden, yalnızca otomatik tamamlama değil, hata kontrolleri de sağlar: +Editör değişkenlerin tiplerini bildiği için, sadece completion değil, aynı zamanda hata kontrolleri de alırsınız: -Artık `age` değişkenini `str(age)` olarak kullanmanız gerektiğini biliyorsunuz: +Artık bunu dÃŒzeltmeniz gerektiğini, `age`'i `str(age)` ile string'e çevirmeniz gerektiğini biliyorsunuz: -{* ../../docs_src/python_types/tutorial004.py hl[2] *} +{* ../../docs_src/python_types/tutorial004_py39.py hl[2] *} +## Tipleri bildirmek { #declaring-types } -## Tip bildirme +Type hints bildirmek için ana yeri az önce gördÃŒnÃŒz: fonksiyon parametreleri. -Az önce tip belirteçlerinin en çok kullanıldığı yeri gördÃŒnÃŒz. +Bu, **FastAPI** ile kullanırken de onları en çok kullanacağınız yerdir. - **FastAPI**ile çalışırken tip belirteçlerini en çok kullanacağımız yer yine fonksiyonlardır. +### Basit tipler { #simple-types } -### Basit tipler - -Yalnızca `str` değil, tÃŒm standart Python tiplerinin bildirebilirsiniz. +Sadece `str` değil, tÃŒm standart Python tiplerini bildirebilirsiniz. Örneğin şunları kullanabilirsiniz: @@ -138,176 +133,332 @@ Yalnızca `str` değil, tÃŒm standart Python tiplerinin bildirebilirsiniz. * `bool` * `bytes` -{* ../../docs_src/python_types/tutorial005.py hl[1] *} +{* ../../docs_src/python_types/tutorial005_py39.py hl[1] *} +### Tip parametreleri ile Generic tipler { #generic-types-with-type-parameters } -### Tip parametreleri ile Generic tipler +`dict`, `list`, `set` ve `tuple` gibi, başka değerler içerebilen bazı veri yapıları vardır. Ve iç değerlerin kendi tipi de olabilir. -"dict", "list", "set" ve "tuple" gibi diğer değerleri içerebilen bazı veri yapıları vardır. Ve dahili değerlerinin de tip belirtecleri olabilir. +İç tipleri olan bu tiplere "**generic**" tipler denir. Ve bunları, iç tipleriyle birlikte bildirmek mÃŒmkÃŒndÃŒr. -Bu tipleri ve dahili tpileri bildirmek için standart Python modÃŒlÃŒnÃŒ "typing" kullanabilirsiniz. +Bu tipleri ve iç tipleri bildirmek için standart Python modÃŒlÃŒ `typing`'i kullanabilirsiniz. Bu modÃŒl, özellikle bu type hints desteği için vardır. -Bu tÃŒr tip belirteçlerini desteklemek için özel olarak mevcuttur. +#### Python'un daha yeni sÃŒrÃŒmleri { #newer-versions-of-python } -#### `List` +`typing` kullanan sözdizimi, Python 3.6'dan en yeni sÃŒrÃŒmlere kadar (Python 3.9, Python 3.10, vb. dahil) tÃŒm sÃŒrÃŒmlerle **uyumludur**. -Örneğin `str` değerlerden oluşan bir `list` tanımlayalım. +Python geliştikçe, **daha yeni sÃŒrÃŒmler** bu type annotations için daha iyi destekle gelir ve çoğu durumda type annotations bildirmek için `typing` modÃŒlÃŒnÃŒ import edip kullanmanız bile gerekmez. -From `typing`, import `List` (bÃŒyÃŒk harf olan `L` ile): +Projeniz için daha yeni bir Python sÃŒrÃŒmÃŒ seçebiliyorsanız, bu ek sadelikten yararlanabilirsiniz. -{* ../../docs_src/python_types/tutorial006.py hl[1] *} +TÃŒm dokÃŒmanlarda her Python sÃŒrÃŒmÃŒyle uyumlu örnekler vardır (fark olduğunda). +Örneğin "**Python 3.6+**", Python 3.6 veya ÃŒstÃŒyle (3.7, 3.8, 3.9, 3.10, vb. dahil) uyumludur. "**Python 3.9+**" ise Python 3.9 veya ÃŒstÃŒyle (3.10 vb. dahil) uyumludur. -Değişkenin tipini yine iki nokta ÃŒstÃŒste (`:`) ile belirleyin. +Eğer **Python'un en gÃŒncel sÃŒrÃŒmlerini** kullanabiliyorsanız, en gÃŒncel sÃŒrÃŒme ait örnekleri kullanın; bunlar **en iyi ve en basit sözdizimine** sahip olur, örneğin "**Python 3.10+**". -tip olarak `List` kullanın. +#### List { #list } -Liste, bazı dahili tipleri içeren bir tÃŒr olduğundan, bunları köşeli parantez içine alırsınız: +Örneğin, `str`'lerden oluşan bir `list` olan bir değişken tanımlayalım. -{* ../../docs_src/python_types/tutorial006.py hl[4] *} +Değişkeni, aynı iki nokta (`:`) sözdizimiyle bildirin. +Type olarak `list` yazın. -/// tip | Ipucu +`list`, bazı iç tipleri barındıran bir tip olduğundan, bunları köşeli parantez içine yazarsınız: -Köşeli parantez içindeki bu dahili tiplere "tip parametreleri" denir. +{* ../../docs_src/python_types/tutorial006_py39.py hl[1] *} -Bu durumda `str`, `List`e iletilen tÃŒr parametresidir. +/// info | Bilgi + +Köşeli parantez içindeki bu iç tiplere "type parameters" denir. + +Bu durumda `str`, `list`'e verilen type parameter'dır. /// -Bunun anlamı şudur: "`items` değişkeni bir `list`tir ve bu listedeki öğelerin her biri bir `str`dir". +Bu şu demektir: "`items` değişkeni bir `list` ve bu listedeki her bir öğe `str`". -Bunu yaparak, dÃŒzenleyicinizin listedeki öğeleri işlerken bile destek sağlamasını sağlayabilirsiniz: +Bunu yaparak, editörÃŒnÃŒz listeden öğeleri işlerken bile destek sağlayabilir: -Tip belirteçleri olmadan, bunu başarmak neredeyse imkansızdır. +Tipler olmadan, bunu başarmak neredeyse imkansızdır. -`item` değişkeninin `items` listesindeki öğelerden biri olduğuna dikkat edin. +`item` değişkeninin, `items` listesindeki elemanlardan biri olduğuna dikkat edin. -Ve yine, editör bunun bir `str` ​​olduğunu biliyor ve bunun için destek sağlıyor. +Ve yine de editör bunun bir `str` olduğunu bilir ve buna göre destek sağlar. -#### `Tuple` ve `Set` +#### Tuple ve Set { #tuple-and-set } -`Tuple` ve `set`lerin tiplerini bildirmek için de aynısını yapıyoruz: - -{* ../../docs_src/python_types/tutorial007.py hl[1,4] *} - - -Bu şu anlama geliyor: - -* `items_t` değişkeni sırasıyla `int`, `int`, ve `str` tiplerinden oluşan bir `tuple` tÃŒrÃŒndedir . -* `items_s` ise her öğesi `bytes` tÃŒrÃŒnde olan bir `set` örneğidir. - -#### `Dict` - -Bir `dict` tanımlamak için virgÃŒlle ayrılmış iki parametre verebilirsiniz. - -Ä°lk tip parametresi `dict` değerinin `key` değeri içindir. - -Ä°kinci parametre ise `dict` değerinin `value` değeri içindir: - -{* ../../docs_src/python_types/tutorial008.py hl[1,4] *} +`tuple`'ları ve `set`'leri bildirmek için de aynısını yaparsınız: +{* ../../docs_src/python_types/tutorial007_py39.py hl[1] *} Bu şu anlama gelir: -* `prices` değişkeni `dict` tipindedir: - * `dict` değişkeninin `key` değeri `str` tipindedir (herbir item'ın "name" değeri). - * `dict` değişkeninin `value` değeri `float` tipindedir (lherbir item'ın "price" değeri). +* `items_t` değişkeni 3 öğeli bir `tuple`'dır: bir `int`, bir başka `int` ve bir `str`. +* `items_s` değişkeni bir `set`'tir ve her bir öğesi `bytes` tipindedir. -#### `Optional` +#### Dict { #dict } -`Optional` bir değişkenin `str`gibi bir tipi olabileceğini ama isteğe bağlı olarak tipinin `None` olabileceğini belirtir: +Bir `dict` tanımlamak için, virgÃŒlle ayrılmış 2 type parameter verirsiniz. -```Python hl_lines="1 4" -{!../../docs_src/python_types/tutorial009.py!} +Ä°lk type parameter, `dict`'in key'leri içindir. + +Ä°kinci type parameter, `dict`'in value'ları içindir: + +{* ../../docs_src/python_types/tutorial008_py39.py hl[1] *} + +Bu şu anlama gelir: + +* `prices` değişkeni bir `dict`'tir: + * Bu `dict`'in key'leri `str` tipindedir (örneğin her bir öğenin adı). + * Bu `dict`'in value'ları `float` tipindedir (örneğin her bir öğenin fiyatı). + +#### Union { #union } + +Bir değişkenin **birkaç tipten herhangi biri** olabileceğini bildirebilirsiniz; örneğin bir `int` veya bir `str`. + +Python 3.6 ve ÃŒzeri sÃŒrÃŒmlerde (Python 3.10 dahil), `typing` içinden `Union` tipini kullanabilir ve köşeli parantez içine kabul edilecek olası tipleri yazabilirsiniz. + +Python 3.10'da ayrıca, olası tipleri vertical bar (`|`) ile ayırabildiğiniz **yeni bir sözdizimi** de vardır. + +//// tab | Python 3.10+ + +```Python hl_lines="1" +{!> ../../docs_src/python_types/tutorial008b_py310.py!} ``` -`str` yerine `Optional[str]` kullanmak editorÃŒn bu değerin her zaman `str` tipinde değil bazen `None` tipinde de olabileceğini belirtir ve hataları tespit etmemizde yardımcı olur. +//// -#### Generic tipler +//// tab | Python 3.9+ -Köşeli parantez içinde tip parametreleri alan bu tÃŒrler, örneğin: +```Python hl_lines="1 4" +{!> ../../docs_src/python_types/tutorial008b_py39.py!} +``` -* `List` -* `Tuple` -* `Set` -* `Dict` +//// + +Her iki durumda da bu, `item`'ın `int` veya `str` olabileceği anlamına gelir. + +#### Muhtemelen `None` { #possibly-none } + +Bir değerin `str` gibi bir tipi olabileceğini ama aynı zamanda `None` da olabileceğini bildirebilirsiniz. + +Python 3.6 ve ÃŒzeri sÃŒrÃŒmlerde (Python 3.10 dahil), `typing` modÃŒlÃŒnden `Optional` import edip kullanarak bunu bildirebilirsiniz. + +```Python hl_lines="1 4" +{!../../docs_src/python_types/tutorial009_py39.py!} +``` + +Sadece `str` yerine `Optional[str]` kullanmak, aslında değer `None` olabilecekken her zaman `str` olduğunu varsaydığınız hataları editörÃŒn yakalamanıza yardımcı olmasını sağlar. + +`Optional[Something]`, aslında `Union[Something, None]` için bir kısayoldur; eşdeğerdirler. + +Bu aynı zamanda Python 3.10'da `Something | None` kullanabileceğiniz anlamına gelir: + +//// tab | Python 3.10+ + +```Python hl_lines="1" +{!> ../../docs_src/python_types/tutorial009_py310.py!} +``` + +//// + +//// tab | Python 3.9+ + +```Python hl_lines="1 4" +{!> ../../docs_src/python_types/tutorial009_py39.py!} +``` + +//// + +//// tab | Python 3.9+ alternatif + +```Python hl_lines="1 4" +{!> ../../docs_src/python_types/tutorial009b_py39.py!} +``` + +//// + +#### `Union` veya `Optional` kullanmak { #using-union-or-optional } + +Python sÃŒrÃŒmÃŒnÃŒz 3.10'un altındaysa, benim oldukça **öznel** bakış açıma göre kÌçÌk bir ipucu: + +* 🚚 `Optional[SomeType]` kullanmaktan kaçının +* Bunun yerine ✹ **`Union[SomeType, None]` kullanın** ✹. + +Ä°kisi eşdeğerdir ve altta aynı şeydir; ama ben `Optional` yerine `Union` önermeyi tercih ederim. ÇÌnkÃŒ "**optional**" kelimesi değerin optional olduğunu ima ediyor gibi durur; ama gerçekte anlamı "değer `None` olabilir"dir. Değer optional olmasa ve hâlâ required olsa bile. + +Bence `Union[SomeType, None]` ne anlama geldiğini daha açık şekilde ifade ediyor. + +Bu, tamamen kelimeler ve isimlendirmelerle ilgili. Ancak bu kelimeler, sizin ve ekip arkadaşlarınızın kod hakkında nasıl dÌşÌndÌğÌnÃŒ etkileyebilir. + +Örnek olarak şu fonksiyonu ele alalım: + +{* ../../docs_src/python_types/tutorial009c_py39.py hl[1,4] *} + +`name` parametresi `Optional[str]` olarak tanımlanmış, ama **optional değil**; parametre olmadan fonksiyonu çağıramazsınız: + +```Python +say_hi() # Oh, no, this throws an error! 😱 +``` + +`name` parametresi **hâlâ required**'dır (*optional* değildir) çÌnkÃŒ bir default değeri yoktur. Yine de `name`, değer olarak `None` kabul eder: + +```Python +say_hi(name=None) # This works, None is valid 🎉 +``` + +Ä°yi haber şu ki, Python 3.10'a geçtiğinizde bununla uğraşmanız gerekmeyecek; çÌnkÃŒ tiplerin union'larını tanımlamak için doğrudan `|` kullanabileceksiniz: + +{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *} + +Ve böylece `Optional` ve `Union` gibi isimlerle de uğraşmanız gerekmeyecek. 😎 + +#### Generic tipler { #generic-types } + +Köşeli parantez içinde type parameter alan bu tiplere **Generic types** veya **Generics** denir, örneğin: + +//// tab | Python 3.10+ + +Aynı builtin tipleri generics olarak kullanabilirsiniz (köşeli parantez ve içindeki tiplerle): + +* `list` +* `tuple` +* `set` +* `dict` + +Ve önceki Python sÃŒrÃŒmlerinde olduğu gibi `typing` modÃŒlÃŒnden: + +* `Union` * `Optional` * ...and others. -**Generic types** yada **Generics** olarak adlandırılır. +Python 3.10'da, `Union` ve `Optional` generics'lerini kullanmaya alternatif olarak, tip union'larını bildirmek için vertical bar (`|`) kullanabilirsiniz; bu çok daha iyi ve daha basittir. -### Tip olarak Sınıflar +//// -Bir değişkenin tipini bir sınıf ile bildirebilirsiniz. +//// tab | Python 3.9+ -Diyelim ki `name` değerine sahip `Person` sınıfınız var: +Aynı builtin tipleri generics olarak kullanabilirsiniz (köşeli parantez ve içindeki tiplerle): -{* ../../docs_src/python_types/tutorial010.py hl[1:3] *} +* `list` +* `tuple` +* `set` +* `dict` +Ve `typing` modÃŒlÃŒnden gelen generics: -Sonra bir değişkeni 'Person' tipinde tanımlayabilirsiniz: +* `Union` +* `Optional` +* ...and others. -{* ../../docs_src/python_types/tutorial010.py hl[6] *} +//// +### Tip olarak sınıflar { #classes-as-types } -Ve yine bÃŒtÃŒn editör desteğini alırsınız: +Bir sınıfı da bir değişkenin tipi olarak bildirebilirsiniz. + +Örneğin, adı olan bir `Person` sınıfınız olsun: + +{* ../../docs_src/python_types/tutorial010_py39.py hl[1:3] *} + +Sonra bir değişkeni `Person` tipinde olacak şekilde bildirebilirsiniz: + +{* ../../docs_src/python_types/tutorial010_py39.py hl[6] *} + +Ve sonra, yine tÃŒm editör desteğini alırsınız: -## Pydantic modelleri +Bunun "`one_person`, `Person` sınıfının bir **instance**'ıdır" anlamına geldiğine dikkat edin. -Pydantic veri doğrulaması yapmak için bir Python kÃŒtÃŒphanesidir. +"`one_person`, `Person` adlı **class**'tır" anlamına gelmez. -Verilerin "biçimini" niteliklere sahip sınıflar olarak dÃŒzenlersiniz. +## Pydantic modelleri { #pydantic-models } -Ve her niteliğin bir tÃŒrÃŒ vardır. +Pydantic, data validation yapmak için bir Python kÃŒtÃŒphanesidir. -Sınıfın bazı değerlerle bir örneğini oluşturursunuz ve değerleri doğrular, bunları uygun tÃŒre dönÌştÃŒrÃŒr ve size tÃŒm verileri içeren bir nesne verir. +Verinin "shape"'ini attribute'lara sahip sınıflar olarak tanımlarsınız. -Ve ortaya çıkan nesne ÃŒzerindeki bÃŒtÃŒn editör desteğini alırsınız. +Ve her attribute'un bir tipi vardır. -Resmi Pydantic dokÃŒmanlarından alınmıştır: +Ardından o sınıfın bir instance'ını bazı değerlerle oluşturursunuz; bu değerleri doğrular, uygun tipe dönÌştÃŒrÃŒr (gerekliyse) ve size tÃŒm veriyi içeren bir nesne verir. -{* ../../docs_src/python_types/tutorial011.py *} +Ve bu ortaya çıkan nesne ile tÃŒm editör desteğini alırsınız. +Resmî Pydantic dokÃŒmanlarından bir örnek: -/// info +{* ../../docs_src/python_types/tutorial011_py310.py *} -Daha fazla şey öğrenmek için Pydantic'i takip edin. +/// info | Bilgi + +Daha fazlasını öğrenmek için Pydantic'in dokÃŒmanlarına bakın. /// -**FastAPI** tamamen Pydantic'e dayanmaktadır. +**FastAPI** tamamen Pydantic ÃŒzerine kuruludur. -Daha fazlasini görmek için [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}. +Bunların pratikte nasıl çalıştığını [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank} içinde çok daha fazla göreceksiniz. -## **FastAPI** tip belirteçleri +/// tip | Ä°pucu -**FastAPI** birkaç şey yapmak için bu tÃŒr tip belirteçlerinden faydalanır. - -**FastAPI** ile parametre tiplerini bildirirsiniz ve şunları elde edersiniz: - -* **Editor desteği**. -* **Tip kontrolÃŒ**. - -...ve **FastAPI** aynı belirteçleri şunlar için de kullanıyor: - -* **Gereksinimleri tanımlama**: request path parameters, query parameters, headers, bodies, dependencies, ve benzeri gereksinimlerden -* **Verileri çevirme**: Gönderilen veri tipinden istenilen veri tipine çevirme. -* **Verileri doğrulama**: Her gönderilen verinin: - * doğrulanması ve geçersiz olduğunda **otomatik hata** oluşturma. -* OpenAPI kullanarak apinizi **Belgeleyin** : - * bu daha sonra otomatik etkileşimli dokÃŒmantasyon kullanıcı arayÃŒzÃŒ tarafından kullanılır. - -BÃŒtÃŒn bunlar kulağa soyut gelebilir. Merak etme. TÃŒm bunları çalışırken göreceksiniz. [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}. - -Önemli olan, standart Python tÃŒrlerini tek bir yerde kullanarak (daha fazla sınıf, dekoratör vb. eklemek yerine), **FastAPI**'nin bizim için işi yapmasını sağlamak. - -/// info - -TÃŒm öğreticiyi zaten okuduysanız ve tÃŒrler hakkında daha fazla bilgi için geri döndÃŒyseniz, iyi bir kaynak: the "cheat sheet" from `mypy`. +Pydantic, default value olmadan `Optional` veya `Union[Something, None]` kullandığınızda özel bir davranışa sahiptir; bununla ilgili daha fazla bilgiyi Pydantic dokÃŒmanlarında Required Optional fields bölÃŒmÃŒnde okuyabilirsiniz. + +/// + +## Metadata Annotations ile Type Hints { #type-hints-with-metadata-annotations } + +Python'da ayrıca, `Annotated` kullanarak bu type hints içine **ek metadata** koymayı sağlayan bir özellik de vardır. + +Python 3.9'dan itibaren `Annotated`, standart kÃŒtÃŒphanenin bir parçasıdır; bu yÃŒzden `typing` içinden import edebilirsiniz. + +{* ../../docs_src/python_types/tutorial013_py39.py hl[1,4] *} + +Python'un kendisi bu `Annotated` ile bir şey yapmaz. Editörler ve diğer araçlar için tip hâlâ `str`'dir. + +Ama **FastAPI**'ye uygulamanızın nasıl davranmasını istediğinize dair ek metadata sağlamak için `Annotated` içindeki bu alanı kullanabilirsiniz. + +Hatırlanması gereken önemli nokta: `Annotated`'a verdiğiniz **ilk *type parameter***, **gerçek tip**tir. Geri kalanı ise diğer araçlar için metadatadır. + +Şimdilik, sadece `Annotated`'ın var olduğunu ve bunun standart Python olduğunu bilmeniz yeterli. 😎 + +Ä°leride bunun ne kadar **gÌçlÃŒ** olabildiğini göreceksiniz. + +/// tip | Ä°pucu + +Bunun **standart Python** olması, editörÃŒnÃŒzde mÃŒmkÃŒn olan **en iyi developer experience**'ı almaya devam edeceğiniz anlamına gelir; kodu analiz etmek ve refactor etmek için kullandığınız araçlarla da, vb. ✹ + +Ayrıca kodunuzun pek çok başka Python aracı ve kÃŒtÃŒphanesiyle çok uyumlu olacağı anlamına gelir. 🚀 + +/// + +## **FastAPI**'de type hints { #type-hints-in-fastapi } + +**FastAPI**, birkaç şey yapmak için bu type hints'ten faydalanır. + +**FastAPI** ile type hints kullanarak parametreleri bildirirsiniz ve şunları elde edersiniz: + +* **Editör desteği**. +* **Tip kontrolleri**. + +...ve **FastAPI** aynı bildirimleri şunlar için de kullanır: + +* **Gereksinimleri tanımlamak**: request path parameters, query parameters, headers, bodies, dependencies, vb. +* **Veriyi dönÌştÃŒrmek**: request'ten gerekli tipe. +* **Veriyi doğrulamak**: her request'ten gelen veriyi: + * Veri geçersiz olduğunda client'a dönen **otomatik hatalar** ÃŒretmek. +* OpenAPI kullanarak API'yi **dokÃŒmante etmek**: + * bu, daha sonra otomatik etkileşimli dokÃŒmantasyon kullanıcı arayÃŒzleri tarafından kullanılır. + +Bunların hepsi kulağa soyut gelebilir. Merak etmeyin. TÃŒm bunları [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank} içinde çalışırken göreceksiniz. + +Önemli olan, standart Python tiplerini tek bir yerde kullanarak (daha fazla sınıf, decorator vb. eklemek yerine), **FastAPI**'nin sizin için işin bÃŒyÃŒk kısmını yapmasıdır. + +/// info | Bilgi + +TÃŒm tutorial'ı zaten bitirdiyseniz ve tipler hakkında daha fazlasını görmek için geri döndÃŒyseniz, iyi bir kaynak: `mypy`'nin "cheat sheet"i. /// diff --git a/docs/tr/docs/resources/index.md b/docs/tr/docs/resources/index.md index fc71a9ca1b..884052f79c 100644 --- a/docs/tr/docs/resources/index.md +++ b/docs/tr/docs/resources/index.md @@ -1,3 +1,3 @@ -# Kaynaklar +# Kaynaklar { #resources } -Ek kaynaklar, dış bağlantılar, makaleler ve daha fazlası. ✈ +Ek kaynaklar, dış bağlantılar ve daha fazlası. ✈ diff --git a/docs/tr/docs/tutorial/cookie-params.md b/docs/tr/docs/tutorial/cookie-params.md index f07508c2fd..18eedab7f0 100644 --- a/docs/tr/docs/tutorial/cookie-params.md +++ b/docs/tr/docs/tutorial/cookie-params.md @@ -1,35 +1,45 @@ -# Çerez (Cookie) Parametreleri +# Çerez (Cookie) Parametreleri { #cookie-parameters } -`Query` (Sorgu) ve `Path` (Yol) parametrelerini tanımladığınız şekilde çerez parametreleri tanımlayabilirsiniz. +`Query` ve `Path` parametrelerini tanımladığınız şekilde Cookie parametreleri tanımlayabilirsiniz. -## Import `Cookie` +## `Cookie`'yi Import Edin { #import-cookie } -Öncelikle, `Cookie`'yi projenize dahil edin: +Öncelikle, `Cookie`'yi import edin: {* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[3] *} -## `Cookie` Parametrelerini Tanımlayın +## `Cookie` Parametrelerini Tanımlayın { #declare-cookie-parameters } -Çerez parametrelerini `Path` veya `Query` tanımlaması yapar gibi tanımlayın. +Ardından, `Path` ve `Query` ile aynı yapıyı kullanarak Cookie parametrelerini tanımlayın. -Ä°lk değer varsayılan değerdir; tÃŒm ekstra doğrulama veya belirteç parametrelerini kullanabilirsiniz: +Varsayılan değeri ve tÃŒm ekstra doğrulama veya annotation parametrelerini tanımlayabilirsiniz: {* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[9] *} /// 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. +`Cookie`, `Path` ve `Query`'nin "kardeş" sınıfıdır. O da aynı ortak `Param` sınıfından miras alır. -Ancak `fastapi`'dan projenize dahil ettiğiniz `Query`, `Path`, `Cookie` ve diğerleri aslında özel sınıflar döndÃŒren birer fonksiyondur. +Ancak `fastapi`'dan `Query`, `Path`, `Cookie` ve diğerlerini import ettiğinizde, bunlar aslında özel sınıflar döndÃŒren fonksiyonlardır, bunu unutmayın. /// /// info | Bilgi -Çerez tanımlamak için `Cookie` sınıfını kullanmanız gerekmektedir, aksi taktirde parametreler sorgu parametreleri olarak yorumlanır. +Çerezleri tanımlamak için `Cookie` kullanmanız gerekir, aksi halde parametreler query parametreleri olarak yorumlanır. /// -## Özet +/// info | Bilgi -Çerez tanımlamalarını `Cookie` sınıfını kullanarak `Query` ve `Path` tanımlar gibi tanımlayın. +**Tarayıcılar çerezleri** özel şekillerde ve arka planda işlediği için, **JavaScript**'in onlara dokunmasına kolayca izin **vermezler**. + +`/docs` adresindeki **API docs UI**'a giderseniz, *path operation*'larınız için çerezlerin **dokÃŒmantasyonunu** görebilirsiniz. + +Ancak **veriyi doldurup** "Execute" dÌğmesine tıklasanız bile, docs UI **JavaScript** ile çalıştığı için çerezler gönderilmez ve herhangi bir değer yazmamışsınız gibi bir **hata** mesajı görÃŒrsÃŒnÃŒz. + +/// + +## Özet { #recap } + +`Query` ve `Path` ile aynı ortak deseni kullanarak, çerezleri `Cookie` ile tanımlayın. diff --git a/docs/tr/docs/tutorial/first-steps.md b/docs/tr/docs/tutorial/first-steps.md index 9a8ef762dc..332f5c5590 100644 --- a/docs/tr/docs/tutorial/first-steps.md +++ b/docs/tr/docs/tutorial/first-steps.md @@ -1,102 +1,118 @@ -# Ä°lk Adımlar +# Ä°lk Adımlar { #first-steps } En sade FastAPI dosyası şu şekilde görÃŒnÃŒr: -{* ../../docs_src/first_steps/tutorial001.py *} +{* ../../docs_src/first_steps/tutorial001_py39.py *} -Yukarıdaki içeriği bir `main.py` dosyasına kopyalayalım. +Yukarıdakini `main.py` adlı bir dosyaya kopyalayın. -Uygulamayı çalıştıralım: +Canlı sunucuyu çalıştırın:
```console -$ uvicorn main:app --reload +$ fastapi dev main.py -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -INFO: Started reloader process [28720] -INFO: Started server process [28722] -INFO: Waiting for application startup. -INFO: Application startup complete. + FastAPI Starting development server 🚀 + + Searching for package file structure from directories + with __init__.py files + Importing from /home/user/code/awesomeapp + + module 🐍 main.py + + code Importing the FastAPI app object from the module with + the following code: + + from main import app + + app Using import string: main:app + + server Server started at http://127.0.0.1:8000 + server Documentation at http://127.0.0.1:8000/docs + + tip Running in development mode, for production use: + fastapi run + + Logs: + + INFO Will watch for changes in these directories: + ['/home/user/code/awesomeapp'] + INFO Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C + to quit) + INFO Started reloader process [383138] using WatchFiles + INFO Started server process [383153] + INFO Waiting for application startup. + INFO Application startup complete. ```
-/// note | Not - -`uvicorn main:app` komutunu şu şekilde açıklayabiliriz: - -* `main`: dosya olan `main.py` (yani Python "modÃŒlÃŒ"). -* `app`: ise `main.py` dosyasının içerisinde `app = FastAPI()` satırında oluşturduğumuz `FastAPI` nesnesi. -* `--reload`: kod değişikliklerinin ardından sunucuyu otomatik olarak yeniden başlatır. Bu parameteyi sadece geliştirme aşamasında kullanmalıyız. - -/// - -Çıktı olarak şöyle bir satır ile karşılaşacaksınız: +Çıktıda, şuna benzer bir satır göreceksiniz: ```hl_lines="4" INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` -Bu satır, yerel makinenizde uygulamanızın çalıştığı bağlantıyı gösterir. +Bu satır, uygulamanızın yerel makinenizde hangi URL'de sunulduğunu gösterir. -### Kontrol Edelim +### Kontrol Edelim { #check-it } -Tarayıcınızı açıp http://127.0.0.1:8000 bağlantısına gidin. +Tarayıcınızı açıp http://127.0.0.1:8000 adresine gidin. -Şu şekilde bir JSON yanıtı ile karşılaşacağız: +Şu şekilde bir JSON response göreceksiniz: ```JSON {"message": "Hello World"} ``` -### Etkileşimli API DokÃŒmantasyonu +### Etkileşimli API DokÃŒmantasyonu { #interactive-api-docs } -Şimdi http://127.0.0.1:8000/docs bağlantısını açalım. +Şimdi http://127.0.0.1:8000/docs adresine gidin. -Swagger UI tarafından sağlanan otomatik etkileşimli bir API dokÃŒmantasyonu göreceğiz: +Otomatik etkileşimli API dokÃŒmantasyonunu ( Swagger UI tarafından sağlanan) göreceksiniz: ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) -### Alternatif API DokÃŒmantasyonu +### Alternatif API DokÃŒmantasyonu { #alternative-api-docs } -Şimdi http://127.0.0.1:8000/redoc bağlantısını açalım. +Ve şimdi http://127.0.0.1:8000/redoc adresine gidin. -ReDoc tarafından sağlanan otomatik dokÃŒmantasyonu göreceğiz: +Alternatif otomatik dokÃŒmantasyonu ( ReDoc tarafından sağlanan) göreceksiniz: ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) -### OpenAPI +### OpenAPI { #openapi } -**FastAPI**, **OpenAPI** standardını kullanarak tÃŒm API'ınızın tamamını tanımlayan bir "şema" oluşturur. +**FastAPI**, API'ları tanımlamak için **OpenAPI** standardını kullanarak tÃŒm API'nızın tamamını içeren bir "şema" ÃŒretir. -#### "Şema" +#### "Şema" { #schema } -"Şema", bir şeyin tanımı veya açıklamasıdır. Geliştirilen koddan ziyade soyut bir açıklamadır. +"Şema", bir şeyin tanımı veya açıklamasıdır. Onu uygulayan kod değil, sadece soyut bir açıklamadır. -#### API "Şeması" +#### API "şeması" { #api-schema } -Bu durumda, OpenAPI, API şemasını nasıl tanımlayacağınızı belirten bir şartnamedir. +Bu durumda, OpenAPI, API'nızın şemasını nasıl tanımlayacağınızı belirleyen bir şartnamedir. -Bu şema tanımı, API yollarınızla birlikte yollarınızın aldığı olası parametreler gibi tanımlamaları içerir. +Bu şema tanımı, API path'leriniz, alabilecekleri olası parametreler vb. şeyleri içerir. -#### Veri "Şeması" +#### Veri "şeması" { #data-schema } "Şema" terimi, JSON içeriği gibi bazı verilerin şeklini de ifade edebilir. -Bu durumda, JSON özellikleri ve sahip oldukları veri tÃŒrleri gibi anlamlarına gelir. +Bu durumda, JSON attribute'ları ve sahip oldukları veri tÃŒrleri vb. anlamına gelir. -#### OpenAPI ve JSON Şema +#### OpenAPI ve JSON Schema { #openapi-and-json-schema } -OpenAPI, API'niz için bir API şeması tanımlar. Ve bu şema, JSON veri şemaları standardı olan **JSON Şema** kullanılarak API'niz tarafından gönderilen ve alınan verilerin tanımlarını (veya "şemalarını") içerir. +OpenAPI, API'nız için bir API şeması tanımlar. Ve bu şema, JSON veri şemaları standardı olan **JSON Schema** kullanılarak API'nız tarafından gönderilen ve alınan verilerin tanımlarını (veya "şemalarını") içerir. -#### `openapi.json` Dosyasına Göz At +#### `openapi.json` Dosyasına Göz At { #check-the-openapi-json } -Ham OpenAPI şemasının nasıl görÃŒndÌğÌnÃŒ merak ediyorsanız, FastAPI otomatik olarak tÃŒm API'ınızın tanımlamalarını içeren bir JSON (şeması) oluşturur. +Ham OpenAPI şemasının nasıl görÃŒndÌğÌnÃŒ merak ediyorsanız, FastAPI otomatik olarak tÃŒm API'nızın açıklamalarını içeren bir JSON (şema) ÃŒretir. -Bu şemayı direkt olarak http://127.0.0.1:8000/openapi.json bağlantısından görÃŒntÃŒleyebilirsiniz. +Bunu doğrudan şuradan görebilirsiniz: http://127.0.0.1:8000/openapi.json. -Aşağıdaki gibi başlayan bir JSON ile karşılaşacaksınız: +Şuna benzer bir şekilde başlayan bir JSON gösterecektir: ```JSON { @@ -119,79 +135,87 @@ Aşağıdaki gibi başlayan bir JSON ile karşılaşacaksınız: ... ``` -#### OpenAPI Ne İşe Yarar? +#### OpenAPI Ne İşe Yarar? { #what-is-openapi-for } -OpenAPI şeması, FastAPI projesinde bulunan iki etkileşimli dokÃŒmantasyon sistemine gÌç veren şeydir. +OpenAPI şeması, dahil edilen iki etkileşimli dokÃŒmantasyon sistemine gÌç veren şeydir. -OpenAPI'ya dayalı dÃŒzinelerce alternatif etkileşimli dokÃŒmantasyon aracı mevcuttur. **FastAPI** ile oluşturulmuş uygulamanıza bu alternatiflerden herhangi birini kolayca ekleyebilirsiniz. +Ve OpenAPI tabanlı dÃŒzinelerce alternatif vardır. **FastAPI** ile oluşturulmuş uygulamanıza bu alternatiflerden herhangi birini kolayca ekleyebilirsiniz. -Ayrıca, API'ınızla iletişim kuracak önyÃŒz, mobil veya IoT uygulamaları gibi istemciler için otomatik olarak kod oluşturabilirsiniz. +Ayrıca, API'nızla iletişim kuran istemciler için otomatik olarak kod ÃŒretmekte de kullanabilirsiniz. Örneğin frontend, mobil veya IoT uygulamaları. -## Adım Adım Özetleyelim +### Uygulamanızı Yayınlayın (opsiyonel) { #deploy-your-app-optional } -### Adım 1: `FastAPI`yı Projemize Dahil Edelim +Ä°sterseniz FastAPI uygulamanızı FastAPI Cloud'a deploy edebilirsiniz; henÃŒz katılmadıysanız gidip bekleme listesine yazılın. 🚀 -{* ../../docs_src/first_steps/tutorial001.py hl[1] *} +Zaten bir **FastAPI Cloud** hesabınız varsa (bekleme listesinden sizi davet ettiysek 😉), uygulamanızı tek komutla deploy edebilirsiniz. -`FastAPI`, API'niz için tÃŒm işlevselliği sağlayan bir Python sınıfıdır. +Deploy etmeden önce giriş yaptığınızdan emin olun: + +
+ +```console +$ fastapi login + +You are logged in to FastAPI Cloud 🚀 +``` + +
+ +Ardından uygulamanızı deploy edin: + +
+ +```console +$ fastapi deploy + +Deploying to FastAPI Cloud... + +✅ Deployment successful! + +🐔 Ready the chicken! Your app is ready at https://myapp.fastapicloud.dev +``` + +
+ +Bu kadar! Artık uygulamanıza o URL ÃŒzerinden erişebilirsiniz. ✹ + +## Adım Adım Özetleyelim { #recap-step-by-step } + +### Adım 1: `FastAPI` import edin { #step-1-import-fastapi } + +{* ../../docs_src/first_steps/tutorial001_py39.py hl[1] *} + +`FastAPI`, API'nız için tÃŒm işlevselliği sağlayan bir Python class'ıdır. /// note | Teknik Detaylar -`FastAPI` doğrudan `Starlette`'i miras alan bir sınıftır. +`FastAPI`, doğrudan `Starlette`'ten miras alan bir class'tır. Starlette'in tÃŒm işlevselliğini `FastAPI` ile de kullanabilirsiniz. /// -### Adım 2: Bir `FastAPI` "Örneği" Oluşturalım +### Adım 2: bir `FastAPI` "instance"ı oluşturun { #step-2-create-a-fastapi-instance } -{* ../../docs_src/first_steps/tutorial001.py hl[3] *} +{* ../../docs_src/first_steps/tutorial001_py39.py hl[3] *} -Burada `app` değişkeni `FastAPI` sınıfının bir örneği olacaktır. +Burada `app` değişkeni `FastAPI` class'ının bir "instance"ı olacaktır. -Bu, tÃŒm API'yı oluşturmak için ana etkileşim noktası olacaktır. +Bu, tÃŒm API'nızı oluşturmak için ana etkileşim noktası olacaktır. -Bu `app` değişkeni, `uvicorn` komutunda atıfta bulunulan değişkenin ta kendisidir. +### Adım 3: bir *path operation* oluşturun { #step-3-create-a-path-operation } -
+#### Path { #path } -```console -$ uvicorn main:app --reload +Buradaki "Path", URL'in ilk `/` işaretinden başlayarak son kısmını ifade eder. -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -``` - -
- -Uygulamanızı aşağıdaki gibi oluşturursanız: - -{* ../../docs_src/first_steps/tutorial002.py hl[3] *} - -Ve bunu `main.py` dosyasına yerleştirirseniz eğer `uvicorn` komutunu şu şekilde çalıştırabilirsiniz: - -
- -```console -$ uvicorn main:my_awesome_api --reload - -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -``` - -
- -### Adım 3: Bir *Yol Operasyonu* Oluşturalım - -#### Yol - -Burada "yol" bağlantıda bulunan ilk `/` ile başlayan ve sonrasında gelen kısmı ifade eder. - -Yani, şu şekilde bir bağlantıda: +Yani, şu şekilde bir URL'de: ``` https://example.com/items/foo ``` -... yol şöyle olur: +...path şöyle olur: ``` /items/foo @@ -199,77 +223,77 @@ https://example.com/items/foo /// info | Bilgi -"Yol" genellikle "endpoint" veya "route" olarak adlandırılır. +Bir "path" genellikle "endpoint" veya "route" olarak da adlandırılır. /// -Bir API oluştururken, "yol", "kaynaklar" ile "endişeleri" ayırmanın ana yöntemidir. +Bir API oluştururken, "path", "concerns" ve "resources" ayrımını yapmanın ana yoludur. -#### Operasyonlar +#### Operation { #operation } -Burada "operasyon" HTTP "metodlarından" birini ifade eder. +Burada "Operation", HTTP "method"larından birini ifade eder. -Bunlardan biri: +Şunlardan biri: * `POST` * `GET` * `PUT` * `DELETE` -...veya daha az kullanılan diğerleri: +...ve daha egzotik olanlar: * `OPTIONS` * `HEAD` * `PATCH` * `TRACE` -HTTP protokolÃŒnde, bu "metodlardan" birini (veya daha fazlasını) kullanarak her bir yol ile iletişim kurabilirsiniz. +HTTP protokolÃŒnde, her bir path ile bu "method"lardan biri (veya birden fazlası) ile iletişim kurabilirsiniz. --- -API oluştururkan, belirli bir amaca hizmet eden belirli HTTP metodlarını kullanırsınız. +API oluştururken, normalde belirli bir aksiyon için bu spesifik HTTP method'larını kullanırsınız. -Normalde kullanılan: +Normalde şunları kullanırsınız: -* `POST`: veri oluşturmak. -* `GET`: veri okumak. -* `PUT`: veriyi gÃŒncellemek. -* `DELETE`: veriyi silmek. +* `POST`: veri oluşturmak için. +* `GET`: veri okumak için. +* `PUT`: veriyi gÃŒncellemek için. +* `DELETE`: veriyi silmek için. -Bu nedenle, OpenAPI'da HTTP metodlarından her birine "operasyon" denir. +Bu nedenle, OpenAPI'da HTTP method'larının her birine "operation" denir. -Biz de onları "**operasyonlar**" olarak adlandıracağız. +Biz de bunlara "**operation**" diyeceğiz. -#### Bir *Yol Operasyonu DekoratörÃŒ* Tanımlayalım +#### Bir *path operation decorator* tanımlayın { #define-a-path-operation-decorator } -{* ../../docs_src/first_steps/tutorial001.py hl[6] *} +{* ../../docs_src/first_steps/tutorial001_py39.py hl[6] *} -`@app.get("/")` dekoratörÃŒ, **FastAPI**'a hemen altındaki fonksiyonun aşağıdaki durumlardan sorumlu olduğunu söyler: +`@app.get("/")`, **FastAPI**'a hemen altındaki fonksiyonun şuraya giden request'leri ele almakla sorumlu olduğunu söyler: -* get operasyonu ile -* `/` yoluna gelen istekler +* path `/` +* get operation kullanarak /// info | `@decorator` Bilgisi -Python'da `@something` sözdizimi "dekoratör" olarak adlandırılır. +Python'daki `@something` söz dizimi "decorator" olarak adlandırılır. -Dekoratörler, dekoratif bir şapka gibi (sanırım terim buradan geliyor) fonksiyonların ÃŒzerlerine yerleştirilirler. +Onu bir fonksiyonun ÃŒstÃŒne koyarsınız. GÃŒzel, dekoratif bir şapka gibi (sanırım terim de buradan geliyor). -Bir "dekoratör" hemen altında bulunan fonksiyonu alır ve o fonksiyon ile bazı işlemler gerçekleştirir. +Bir "decorator", altındaki fonksiyonu alır ve onunla bir şey yapar. -Bizim durumumuzda, kullandığımız dekoratör, **FastAPI**'a altındaki fonksiyonun `/` yoluna gelen `get` metodlu isteklerden sorumlu olduğunu söyler. +Bizim durumumuzda bu decorator, **FastAPI**'a altındaki fonksiyonun **path** `/` ile **operation** `get`'e karşılık geldiğini söyler. -Bu bir **yol operasyonu dekoratörÃŒdÃŒr**. +Bu, "**path operation decorator**"dır. /// -Ayrıca diğer operasyonları da kullanabilirsiniz: +Diğer operation'ları da kullanabilirsiniz: * `@app.post()` * `@app.put()` * `@app.delete()` -Daha az kullanılanları da kullanabilirsiniz: +Ve daha egzotik olanları: * `@app.options()` * `@app.head()` @@ -278,58 +302,79 @@ Daha az kullanılanları da kullanabilirsiniz: /// tip | Ä°pucu -Her işlemi (HTTP metod) istediğiniz gibi kullanmakta özgÃŒrsÃŒnÃŒz. +Her bir operation'ı (HTTP method'unu) istediğiniz gibi kullanmakta özgÃŒrsÃŒnÃŒz. -**FastAPI** herhangi bir özel amacı veya anlamı olması konusunda ısrarcı olmaz. +**FastAPI** herhangi bir özel anlamı zorunlu kılmaz. Buradaki bilgiler bir gereklilik değil, bir kılavuz olarak sunulmaktadır. -Mesela GraphQL kullanırkan genelde tÃŒm işlemleri yalnızca `POST` operasyonunu kullanarak gerçekleştirirsiniz. +Örneğin GraphQL kullanırken, normalde tÃŒm aksiyonları yalnızca `POST` operation'ları kullanarak gerçekleştirirsiniz. /// -### Adım 4: **Yol Operasyonu Fonksiyonunu** Tanımlayın +### Adım 4: **path operation function**'ı tanımlayın { #step-4-define-the-path-operation-function } -Aşağıdaki, bizim **yol operasyonu fonksiyonumuzdur**: +Bu bizim "**path operation function**"ımız: -* **yol**: `/` -* **operasyon**: `get` -* **fonksiyon**: "dekoratör"ÃŒn (`@app.get("/")`'in) altındaki fonksiyondur. +* **path**: `/`. +* **operation**: `get`. +* **function**: "decorator"ÃŒn altındaki fonksiyondur (`@app.get("/")`'in altındaki). -{* ../../docs_src/first_steps/tutorial001.py hl[7] *} +{* ../../docs_src/first_steps/tutorial001_py39.py hl[7] *} Bu bir Python fonksiyonudur. -Bu fonksiyon bir `GET` işlemi kullanılarak "`/`" bağlantısına bir istek geldiğinde **FastAPI** tarafından çağrılır. +**FastAPI**, "`/`" URL'ine `GET` operation kullanarak bir request aldığında bu fonksiyonu çağıracaktır. -Bu durumda bu fonksiyon bir `async` fonksiyondur. +Bu durumda, bu bir `async` fonksiyondur. --- -Bu fonksiyonu `async def` yerine normal bir fonksiyon olarak da tanımlayabilirsiniz. +Bunu `async def` yerine normal bir fonksiyon olarak da tanımlayabilirsiniz: -{* ../../docs_src/first_steps/tutorial003.py hl[7] *} +{* ../../docs_src/first_steps/tutorial003_py39.py hl[7] *} /// note | Not -Eğer farkı bilmiyorsanız, [Async: *"Aceleniz mi var?"*](../async.md#in-a-hurry){.internal-link target=_blank} sayfasını kontrol edebilirsiniz. +Eğer farkı bilmiyorsanız, [Async: *"Aceleniz mi var?"*](../async.md#in-a-hurry){.internal-link target=_blank} sayfasına bakın. /// -### Adım 5: İçeriği Geri DöndÃŒrÃŒn +### Adım 5: içeriği döndÃŒrÃŒn { #step-5-return-the-content } -{* ../../docs_src/first_steps/tutorial001.py hl[8] *} +{* ../../docs_src/first_steps/tutorial001_py39.py hl[8] *} -Bir `dict`, `list` veya `str`, `int` gibi tekil değerler döndÃŒrebilirsiniz. +Bir `dict`, `list`, `str`, `int` vb. tekil değerler döndÃŒrebilirsiniz. -Ayrıca, Pydantic modelleri de döndÃŒrebilirsiniz (bu konu ileriki aşamalarda irdelenecektir). +Ayrıca Pydantic modelleri de döndÃŒrebilirsiniz (bununla ilgili daha fazlasını ileride göreceksiniz). -Otomatik olarak JSON'a dönÌştÃŒrÃŒlecek (ORM'ler vb. dahil) başka birçok nesne ve model vardır. En beğendiklerinizi kullanmayı deneyin, yÃŒksek ihtimalle destekleniyordur. +Otomatik olarak JSON'a dönÌştÃŒrÃŒlecek (ORM'ler vb. dahil) başka birçok nesne ve model vardır. En sevdiğiniz nesne/model'leri kullanmayı deneyin; bÃŒyÃŒk ihtimalle zaten destekleniyordur. -## Özet +### Adım 6: Deploy edin { #step-6-deploy-it } -* `FastAPI`'yı projemize dahil ettik. -* Bir `app` örneği oluşturduk. -* Bir **yol operasyonu dekoratörÃŒ** (`@app.get("/")` gibi) yazdık. -* Bir **yol operasyonu fonksiyonu** (`def root(): ...` gibi) yazdık. -* Geliştirme sunucumuzu (`uvicorn main:app --reload` gibi) çalıştırdık. +Uygulamanızı tek komutla **FastAPI Cloud**'a deploy edin: `fastapi deploy`. 🎉 + +#### FastAPI Cloud Hakkında { #about-fastapi-cloud } + +**FastAPI Cloud**, **FastAPI**'ın arkasındaki aynı yazar ve ekip tarafından geliştirilmiştir. + +Minimum eforla bir API'ı **oluşturma**, **deploy etme** ve **erişme** sÃŒrecini sadeleştirir. + +FastAPI ile uygulama geliştirirken yaşadığınız aynı **developer experience**'ı, onları buluta **deploy etme** aşamasına da taşır. 🎉 + +FastAPI Cloud, *FastAPI and friends* açık kaynak projelerinin birincil sponsoru ve finansman sağlayıcısıdır. ✹ + +#### Diğer cloud sağlayıcılarına deploy edin { #deploy-to-other-cloud-providers } + +FastAPI açık kaynaklıdır ve standartlara dayanır. FastAPI uygulamalarını seçtiğiniz herhangi bir cloud sağlayıcısına deploy edebilirsiniz. + +FastAPI uygulamalarını onlarla deploy etmek için cloud sağlayıcınızın kılavuzlarını takip edin. 🀓 + +## Özet { #recap } + +* `FastAPI` import edin. +* Bir `app` instance'ı oluşturun. +* `@app.get("/")` gibi decorator'ları kullanarak bir **path operation decorator** yazın. +* Bir **path operation function** tanımlayın; örneğin `def root(): ...`. +* `fastapi dev` komutunu kullanarak geliştirme sunucusunu çalıştırın. +* Ä°sterseniz `fastapi deploy` ile uygulamanızı deploy edin. diff --git a/docs/tr/docs/tutorial/path-params.md b/docs/tr/docs/tutorial/path-params.md index 408dd25ca2..db676f1eed 100644 --- a/docs/tr/docs/tutorial/path-params.md +++ b/docs/tr/docs/tutorial/path-params.md @@ -1,34 +1,34 @@ -# Yol Parametreleri +# Yol Parametreleri { #path-parameters } -Yol "parametrelerini" veya "değişkenlerini" Python string biçimlemede kullanılan sözdizimi ile tanımlayabilirsiniz. +Python string biçimlemede kullanılan sözdizimiyle path "parametreleri"ni veya "değişkenleri"ni tanımlayabilirsiniz: -{* ../../docs_src/path_params/tutorial001.py hl[6:7] *} +{* ../../docs_src/path_params/tutorial001_py39.py hl[6:7] *} -Yol parametresi olan `item_id`'nin değeri, fonksiyonunuza `item_id` argÃŒmanı olarak aktarılacaktır. +Path parametresi `item_id`'nin değeri, fonksiyonunuza `item_id` argÃŒmanı olarak aktarılacaktır. -Eğer bu örneği çalıştırıp http://127.0.0.1:8000/items/foo sayfasına giderseniz, şöyle bir çıktı ile karşılaşırsınız: +Yani, bu örneği çalıştırıp http://127.0.0.1:8000/items/foo adresine giderseniz, şöyle bir response görÃŒrsÃŒnÃŒz: ```JSON {"item_id":"foo"} ``` -## Tip İçeren Yol Parametreleri +## Tip İçeren Yol Parametreleri { #path-parameters-with-types } -Standart Python tip belirteçlerini kullanarak yol parametresinin tipini fonksiyonun içerisinde tanımlayabilirsiniz. +Standart Python tip belirteçlerini kullanarak path parametresinin tipini fonksiyonun içinde tanımlayabilirsiniz: -{* ../../docs_src/path_params/tutorial002.py hl[7] *} +{* ../../docs_src/path_params/tutorial002_py39.py hl[7] *} -Bu durumda, `item_id` bir `int` olarak tanımlanacaktır. +Bu durumda, `item_id` bir `int` olarak tanımlanır. /// check | Ek bilgi -Bu sayede, fonksiyon içerisinde hata denetimi, kod tamamlama gibi konularda editör desteğine kavuşacaksınız. +Bu sayede, fonksiyon içinde hata denetimi, kod tamamlama vb. konularda editör desteğine kavuşursunuz. /// -## Veri DönÌşÌmÃŒ +## Veri conversion { #data-conversion } -Eğer bu örneği çalıştırıp tarayıcınızda http://127.0.0.1:8000/items/3 sayfasını açarsanız, şöyle bir yanıt ile karşılaşırsınız: +Bu örneği çalıştırıp tarayıcınızda http://127.0.0.1:8000/items/3 adresini açarsanız, şöyle bir response görÃŒrsÃŒnÃŒz: ```JSON {"item_id":3} @@ -36,15 +36,15 @@ Eğer bu örneği çalıştırıp tarayıcınızda "ayrıştırma" özelliği sağlar. +Yani, bu tip tanımıyla birlikte **FastAPI** size otomatik request "parsing" sağlar. /// -## Veri Doğrulama +## Veri Doğrulama { #data-validation } -Eğer tarayıcınızda http://127.0.0.1:8000/items/foo sayfasını açarsanız, şuna benzer gÃŒzel bir HTTP hatası ile karşılaşırsınız: +Ancak tarayıcınızda http://127.0.0.1:8000/items/foo adresine giderseniz, şuna benzer gÃŒzel bir HTTP hatası görÃŒrsÃŒnÃŒz: ```JSON { @@ -62,141 +62,135 @@ Eğer 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ı. +Aynı hata, şu örnekte olduğu gibi `int` yerine `float` verirseniz de ortaya çıkar: http://127.0.0.1:8000/items/4.2 /// check | Ek bilgi -Böylece, aynı Python tip tanımlaması ile birlikte, **FastAPI** veri doğrulama özelliği sağlar. +Yani, aynı Python tip tanımıyla birlikte **FastAPI** size veri doğrulama sağlar. -Dikkatinizi çekerim ki, karşılaştığınız hata, doğrulamanın geçersiz olduğu mutlak noktayı da açık bir şekilde belirtiyor. +Dikkat edin: hata ayrıca doğrulamanın geçmediği noktayı da açıkça belirtir. -Bu özellik, API'ınızla iletişime geçen kodu geliştirirken ve ayıklarken inanılmaz derecede yararlı olacaktır. +Bu, API'ınızla etkileşime giren kodu geliştirirken ve debug ederken inanılmaz derecede faydalıdır. /// -## DokÃŒmantasyon +## DokÃŒmantasyon { #documentation } -Ayrıca, tarayıcınızı http://127.0.0.1:8000/docs adresinde açarsanız, aşağıdaki gibi otomatik ve interaktif bir API dökÃŒmantasyonu ile karşılaşırsınız: +Tarayıcınızı http://127.0.0.1:8000/docs adresinde açtığınızda, aşağıdaki gibi otomatik ve interaktif bir API dokÃŒmantasyonu görÃŒrsÃŒnÃŒz: /// 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. +Yine, sadece aynı Python tip tanımıyla **FastAPI** size otomatik ve interaktif dokÃŒmantasyon (Swagger UI entegrasyonuyla) sağlar. -Dikkatinizi çekerim ki, yol parametresi integer olarak tanımlanmıştır. +Dikkat edin: path parametresi integer olarak tanımlanmıştır. /// -## Standartlara Dayalı Avantajlar, Alternatif DokÃŒmantasyon +## Standartlara Dayalı Avantajlar, Alternatif DokÃŒmantasyon { #standards-based-benefits-alternative-documentation } -Oluşturulan şema OpenAPI standardına uygun olduğu için birçok uyumlu araç mevcuttur. +Üretilen şema OpenAPI standardından geldiği için birçok uyumlu araç vardır. -Bu sayede, **FastAPI**'ın bizzat kendisi http://127.0.0.1:8000/redoc sayfasından erişebileceğiniz alternatif (ReDoc kullanan) bir API dokÃŒmantasyonu sağlar: +Bu nedenle **FastAPI**'ın kendisi, http://127.0.0.1:8000/redoc adresinden erişebileceğiniz alternatif bir API dokÃŒmantasyonu (ReDoc kullanarak) sağlar: -Aynı şekilde, farklı diller için kod tÃŒretme araçları da dahil olmak ÃŒzere çok sayıda uyumlu araç bulunur. +Aynı şekilde, birçok uyumlu araç vardır. Birçok dil için kod ÃŒretme araçları da buna dahildir. -## Pydantic +## Pydantic { #pydantic } -TÃŒm veri doğrulamaları Pydantic tarafından arka planda gerçekleştirilir, bu sayede tÃŒm avantajlardan faydalanabilirsiniz. Böylece, emin ellerde olduğunuzu hissedebilirsiniz. +TÃŒm veri doğrulamaları, arka planda Pydantic tarafından gerçekleştirilir; böylece onun tÃŒm avantajlarından faydalanırsınız. Ve emin ellerde olduğunuzu bilirsiniz. -Aynı tip tanımlamalarını `str`, `float`, `bool` ve diğer karmaşık veri tipleri ile kullanma imkanınız vardır. +Aynı tip tanımlarını `str`, `float`, `bool` ve daha birçok karmaşık veri tipiyle kullanabilirsiniz. -Bunlardan birkaçı, bu eğitimin ileriki bölÃŒmlerinde irdelenmiştir. +Bunların birkaçı, eğitimin sonraki bölÃŒmlerinde ele alınacaktır. -## Sıralama Önem Arz Eder +## Sıralama Önemlidir { #order-matters } -*Yol operasyonları* tasarlarken sabit yol barındıran durumlar ile karşılaşabilirsiniz. +*Path operation*'lar oluştururken sabit bir path'e sahip olduğunuz durumlarla karşılaşabilirsiniz. -Farz edelim ki `/users/me` yolu geçerli kullanıcı hakkında bilgi almak için kullanılıyor olsun. +Örneğin `/users/me`'nin, geçerli kullanıcı hakkında veri almak için kullanıldığını varsayalım. -Benzer şekilde `/users/{user_id}` gibi tanımlanmış ve belirli bir kullanıcı hakkında veri almak için kullanıcının ID bilgisini kullanan bir yolunuz da mevcut olabilir. +Sonra belirli bir kullanıcı hakkında, kullanıcı ID'si ile veri almak için `/users/{user_id}` şeklinde bir path'iniz de olabilir. -*Yol operasyonları* sıralı bir şekilde gözden geçirildiğinden dolayı `/users/me` yolunun `/users/{user_id}` yolundan önce tanımlanmış olmasından emin olmanız gerekmektedir: +*Path operation*'lar sırayla değerlendirildiği için, `/users/me` için olan path'in `/users/{user_id}` olandan önce tanımlandığından emin olmanız gerekir: -{* ../../docs_src/path_params/tutorial003.py hl[6,11] *} +{* ../../docs_src/path_params/tutorial003_py39.py hl[6,11] *} -Aksi halde, `/users/{user_id}` yolu `"me"` değerinin `user_id` parametresi için gönderildiğini "dÌşÌnerek" `/users/me` ile de eşleşir. +Aksi halde, `/users/{user_id}` için olan path, `"me"` değerini `user_id` parametresi olarak aldığını "dÌşÌnerek" `/users/me` için de eşleşir. -Benzer şekilde, bir yol operasyonunu yeniden tanımlamanız mÃŒmkÃŒn değildir: +Benzer şekilde, bir path operation'ı yeniden tanımlayamazsınız: -{* ../../docs_src/path_params/tutorial003b.py hl[6,11] *} +{* ../../docs_src/path_params/tutorial003b_py39.py hl[6,11] *} -Yol, ilk kısım ile eşleştiğinden dolayı her koşulda ilk yol operasyonu kullanılacaktır. +Path önce eşleştiği için her zaman ilk olan kullanılır. -## Ön Tanımlı Değerler +## Ön Tanımlı Değerler { #predefined-values } -Eğer *yol parametresi* alan bir *yol operasyonunuz* varsa ve alabileceği *yol parametresi* değerlerinin ön tanımlı olmasını istiyorsanız, standart Python `Enum` tipini kullanabilirsiniz. +Bir *path operation*'ınız *path parameter* alıyorsa ama olası geçerli *path parameter* değerlerinin önceden tanımlı olmasını istiyorsanız, standart bir Python `Enum` kullanabilirsiniz. -### Bir `Enum` Sınıfı Oluşturalım +### Bir `Enum` Sınıfı Oluşturalım { #create-an-enum-class } -`Enum` sınıfını projemize dahil edip `str` ile `Enum` sınıflarını miras alan bir alt sınıf yaratalım. +`Enum`'u import edin ve `str` ile `Enum`'dan miras alan bir alt sınıf oluşturun. -`str` sınıfı miras alındığından dolayı, API dokÃŒmanı, değerlerin `string` tipinde olması gerektiğini anlayabilecek ve doğru bir şekilde işlenecektir. +`str`'den miras aldığınızda API dokÃŒmanları değerlerin `string` tipinde olması gerektiğini anlayabilir ve doğru şekilde render edebilir. -Sonrasında, sınıf içerisinde, mevcut ve geçerli değerler olacak olan sabit değerli özelliklerini oluşturalım: +Sonra, kullanılabilir geçerli değerler olacak sabit değerli class attribute'ları oluşturun: -{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *} - -/// info | Bilgi - -3.4 sÃŒrÃŒmÃŒnden beri enumerationlar (ya da enumlar) Python'da mevcuttur. - -/// +{* ../../docs_src/path_params/tutorial005_py39.py hl[1,6:9] *} /// tip | Ä°pucu -Merak ediyorsanız söyleyeyim, "AlexNet", "ResNet" ve "LeNet" isimleri Makine Öğrenmesi modellerini temsil eder. +Merak ediyorsanız: "AlexNet", "ResNet" ve "LeNet", Makine Öğrenmesi modellerinin sadece isimleridir. /// -### Bir *Yol Parametresi* Tanımlayalım +### Bir *Path Parameter* Tanımlayalım { #declare-a-path-parameter } -Sonrasında, yarattığımız enum sınıfını (`ModelName`) kullanarak tip belirteci aracılığıyla bir *yol parametresi* oluşturalım: +Ardından oluşturduğunuz enum sınıfını (`ModelName`) kullanarak tip belirteciyle bir *path parameter* oluşturun: -{* ../../docs_src/path_params/tutorial005.py hl[16] *} +{* ../../docs_src/path_params/tutorial005_py39.py hl[16] *} -### DokÃŒmana Göz Atalım +### DokÃŒmana Göz Atalım { #check-the-docs } -*Yol parametresi* için mevcut değerler ön tanımlı olduğundan dolayı, interaktif dökÃŒman onları gÃŒzel bir şekilde gösterebilir: +*Path parameter* için kullanılabilir değerler ön tanımlı olduğu için, interaktif dokÃŒmanlar bunları gÃŒzelce gösterebilir: -### Python *Enumerationları* ile Çalışmak +### Python *Enumeration*'ları ile Çalışmak { #working-with-python-enumerations } -*Yol parametresinin* değeri bir *enumeration ÃŒyesi* olacaktır. +*Path parameter*'ın değeri bir *enumeration member* olacaktır. -#### *Enumeration Üyelerini* Karşılaştıralım +#### *Enumeration Member*'ları Karşılaştıralım { #compare-enumeration-members } -Parametreyi, yarattığınız enum olan `ModelName` içerisindeki *enumeration ÃŒyesi* ile karşılaştırabilirsiniz: +Bunu, oluşturduğunuz enum `ModelName` içindeki *enumeration member* ile karşılaştırabilirsiniz: -{* ../../docs_src/path_params/tutorial005.py hl[17] *} +{* ../../docs_src/path_params/tutorial005_py39.py hl[17] *} -#### *Enumeration Değerini* Edinelim +#### *Enumeration Value*'yu Alalım { #get-the-enumeration-value } -`model_name.value` veya genel olarak `your_enum_member.value` tanımlarını kullanarak (bu durumda bir `str` olan) gerçek değere ulaşabilirsiniz: +Gerçek değeri (bu durumda bir `str`) `model_name.value` ile veya genel olarak `your_enum_member.value` ile alabilirsiniz: -{* ../../docs_src/path_params/tutorial005.py hl[20] *} +{* ../../docs_src/path_params/tutorial005_py39.py hl[20] *} /// tip | Ä°pucu -`"lenet"` değerine `ModelName.lenet.value` tanımı ile de ulaşabilirsiniz. +`"lenet"` değerine `ModelName.lenet.value` ile de erişebilirsiniz. /// -#### *Enumeration Üyelerini* DöndÃŒrelim +#### *Enumeration Member*'ları DöndÃŒrelim { #return-enumeration-members } -JSON gövdesine (örneğin bir `dict`) gömÃŒlÃŒ olsalar bile *yol operasyonundaki* *enum ÃŒyelerini* döndÃŒrebilirsiniz. +*Path operation*'ınızdan, bir JSON body'nin içine gömÃŒlÃŒ olsalar bile (ör. bir `dict`) *enum member*'ları döndÃŒrebilirsiniz. -Bu ÃŒyeler istemciye iletilmeden önce kendilerine karşılık gelen değerlerine (bu durumda string) dönÌştÃŒrÃŒleceklerdir: +Ä°stemciye dönmeden önce, karşılık gelen değerlerine (bu durumda string) dönÌştÃŒrÃŒlÃŒrler: -{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *} +{* ../../docs_src/path_params/tutorial005_py39.py hl[18,21,23] *} -Ä°stemci tarafında şuna benzer bir JSON yanıtı ile karşılaşırsınız: +Ä°stemcinizde şöyle bir JSON response alırsınız: ```JSON { @@ -205,53 +199,53 @@ Bu ÃŒyeler istemciye iletilmeden önce kendilerine karşılık gelen değerlerin } ``` -## Yol İçeren Yol Parametreleri +## Path İçeren Path Parametreleri { #path-parameters-containing-paths } -Farz edelim ki elinizde `/files/{file_path}` isminde bir *yol operasyonu* var. +Diyelim ki `/files/{file_path}` path'ine sahip bir *path operation*'ınız var. -Fakat `file_path` değerinin `home/johndoe/myfile.txt` gibi bir *yol* barındırmasını istiyorsunuz. +Ama `file_path`'in kendisinin `home/johndoe/myfile.txt` gibi bir *path* içermesi gerekiyor. -Sonuç olarak, oluşturmak istediğin URL `/files/home/johndoe/myfile.txt` gibi bir şey olacaktır. +Böylece, o dosyanın URL'si şu şekilde olur: `/files/home/johndoe/myfile.txt`. -### OpenAPI Desteği +### OpenAPI Desteği { #openapi-support } -Test etmesi ve tanımlaması zor senaryolara sebebiyet vereceğinden dolayı OpenAPI, *yol* barındıran *yol parametrelerini* tanımlayacak bir çözÃŒm sunmuyor. +OpenAPI, içinde bir *path* barındıracak bir *path parameter* tanımlamak için bir yöntem desteklemez; çÌnkÃŒ bu, test etmesi ve tanımlaması zor senaryolara yol açabilir. -Ancak bunu, Starlette kÃŒtÃŒphanesinin dahili araçlarından birini kullanarak **FastAPI**'da gerçekleştirebilirsiniz. +Yine de, Starlette'in dahili araçlarından birini kullanarak bunu **FastAPI**'da yapabilirsiniz. -Parametrenin bir yol içermesi gerektiğini belirten herhangi bir dokÃŒman eklemememize rağmen dokÃŒmanlar yine de çalışacaktır. +Ve dokÃŒmanlar, parametrenin bir path içermesi gerektiğini söyleyen herhangi bir dokÃŒmantasyon eklemese bile çalışmaya devam eder. -### Yol DönÌştÃŒrÃŒcÃŒ +### Path DönÌştÃŒrÃŒcÃŒ { #path-convertor } -Direkt olarak Starlette kÃŒtÃŒphanesinden gelen bir opsiyon sayesinde aşağıdaki gibi *yol* içeren bir *yol parametresi* bağlantısı tanımlayabilirsiniz: +Starlette'ten doğrudan gelen bir seçenekle, *path* içeren bir *path parameter*'ı şu URL ile tanımlayabilirsiniz: ``` /files/{file_path:path} ``` -Bu durumda, parametrenin adı `file_path` olacaktır ve son kısım olan `:path` kısmı, parametrenin herhangi bir *yol* ile eşleşmesi gerektiğini belirtecektir. +Bu durumda parametrenin adı `file_path`'tir ve son kısım olan `:path`, parametrenin herhangi bir *path* ile eşleşmesi gerektiğini söyler. -Böylece şunun gibi bir kullanım yapabilirsiniz: +Yani şununla kullanabilirsiniz: -{* ../../docs_src/path_params/tutorial004.py hl[6] *} +{* ../../docs_src/path_params/tutorial004_py39.py hl[6] *} /// tip | Ä°pucu -Parametrenin başında `/home/johndoe/myfile.txt` yolunda olduğu gibi (`/`) işareti ile birlikte kullanmanız gerektiği durumlar olabilir. +Parametrenin başında `/home/johndoe/myfile.txt` örneğinde olduğu gibi bir eğik çizgi (`/`) ile başlaması gerekebilir. -Bu durumda, URL, `files` ile `home` arasında iki eğik çizgiye (`//`) sahip olup `/files//home/johndoe/myfile.txt` gibi gözÃŒkecektir. +Bu durumda URL, `files` ile `home` arasında çift eğik çizgi (`//`) olacak şekilde `/files//home/johndoe/myfile.txt` olur. /// -## Özet +## Özet { #recap } -**FastAPI** ile kısa, sezgisel ve standart Python tip tanımlamaları kullanarak şunları elde edersiniz: +**FastAPI** ile kısa, sezgisel ve standart Python tip tanımlarını kullanarak şunları elde edersiniz: -* Editör desteği: hata denetimi, otomatik tamamlama, vb. -* Veri "dönÌştÃŒrme" +* Editör desteği: hata denetimleri, otomatik tamamlama vb. +* Veri "parsing" * Veri doğrulama -* API tanımlamaları ve otomatik dokÃŒmantasyon +* API annotation ve otomatik dokÃŒmantasyon -Ve sadece, bunları bir kez tanımlamanız yeterli. +Ve bunları sadece bir kez tanımlamanız yeterlidir. -Diğer frameworkler ile karşılaştırıldığında (ham performans dışında), ÃŒstte anlatılan durum muhtemelen **FastAPI**'ın göze çarpan başlıca avantajıdır. +Bu, (ham performans dışında) **FastAPI**'ın alternatif framework'lere kıyasla muhtemelen en görÃŒnÃŒr ana avantajıdır. diff --git a/docs/tr/docs/tutorial/query-params.md b/docs/tr/docs/tutorial/query-params.md index a8ba883edc..89cfa3fb35 100644 --- a/docs/tr/docs/tutorial/query-params.md +++ b/docs/tr/docs/tutorial/query-params.md @@ -1,83 +1,83 @@ -# Sorgu Parametreleri +# Sorgu Parametreleri { #query-parameters } -Fonksiyonda yol parametrelerinin parçası olmayan diğer tanımlamalar otomatik olarak "sorgu" parametresi olarak yorumlanır. +Fonksiyonda path parametrelerinin parçası olmayan diğer parametreleri tanımladığınızda, bunlar otomatik olarak "query" parametreleri olarak yorumlanır. -{* ../../docs_src/query_params/tutorial001.py hl[9] *} +{* ../../docs_src/query_params/tutorial001_py39.py hl[9] *} -Sorgu, bağlantıdaki `?` kısmından sonra gelen ve `&` işareti ile ayrılan anahtar-değer çiftlerinin oluşturduğu bir kÃŒmedir. +Query, bir URL'de `?` işaretinden sonra gelen ve `&` karakterleriyle ayrılan anahtar-değer çiftlerinin kÃŒmesidir. -Örneğin, aşağıdaki bağlantıda: +Örneğin, şu URL'de: ``` http://127.0.0.1:8000/items/?skip=0&limit=10 ``` -...sorgu parametreleri şunlardır: +...query parametreleri şunlardır: -* `skip`: değeri `0`'dır -* `limit`: değeri `10`'dır +* `skip`: değeri `0` +* `limit`: değeri `10` -Parametreler bağlantının bir parçası oldukları için doğal olarak string olarak değerlendirilirler. +URL'nin bir parçası oldukları için "doğal olarak" string'tirler. -Fakat, Python tipleri ile tanımlandıkları zaman (yukarıdaki örnekte `int` oldukları gibi), parametreler o tiplere dönÌştÃŒrÃŒlÃŒr ve o tipler çerçevesinde doğrulanırlar. +Ancak, bunları Python tipleriyle (yukarıdaki örnekte `int` olarak) tanımladığınızda, o tipe dönÌştÃŒrÃŒlÃŒrler ve o tipe göre doğrulanırlar. -Yol parametreleri için geçerli olan her tÃŒrlÃŒ işlem aynı şekilde sorgu parametreleri için de geçerlidir: +Path parametreleri için geçerli olan aynı sÃŒreç query parametreleri için de geçerlidir: -* Editör desteği (ÅŸÃŒphesiz) -* Veri "ayrıştırma" +* Editör desteği (tabii ki) +* Veri "parsing" * Veri doğrulama * Otomatik dokÃŒmantasyon -## Varsayılanlar +## Varsayılanlar { #defaults } -Sorgu parametreleri, adres yolunun sabit bir parçası olmadıklarından dolayı isteğe bağlı ve varsayılan değere sahip olabilirler. +Query parametreleri path'in sabit bir parçası olmadığından, opsiyonel olabilir ve varsayılan değerlere sahip olabilir. -Yukarıdaki örnekte `skip=0` ve `limit=10` varsayılan değere sahiplerdir. +Yukarıdaki örnekte varsayılan değerleri `skip=0` ve `limit=10`'dur. -Yani, aşağıdaki bağlantıya gitmek: +Yani şu URL'ye gitmek: ``` http://127.0.0.1:8000/items/ ``` -şu adrese gitmek ile aynı etkiye sahiptir: +şuraya gitmekle aynı olur: ``` http://127.0.0.1:8000/items/?skip=0&limit=10 ``` -Ancak, mesela şöyle bir adresi ziyaret ederseniz: +Ancak örneğin şuraya giderseniz: ``` http://127.0.0.1:8000/items/?skip=20 ``` -Fonksiyonunuzdaki parametre değerleri aşağıdaki gibi olacaktır: +Fonksiyonunuzdaki parametre değerleri şöyle olacaktır: -* `skip=20`: çÌnkÃŒ bağlantıda böyle tanımlandı. -* `limit=10`: çÌnkÃŒ varsayılan değer buydu. +* `skip=20`: çÌnkÃŒ URL'de siz ayarladınız +* `limit=10`: çÌnkÃŒ varsayılan değer oydu -## Ä°steğe Bağlı Parametreler +## Ä°steğe bağlı parametreler { #optional-parameters } -Aynı şekilde, varsayılan değerlerini `None` olarak atayarak isteğe bağlı parametreler tanımlayabilirsiniz: +Aynı şekilde, varsayılan değerlerini `None` yaparak isteğe bağlı query parametreleri tanımlayabilirsiniz: {* ../../docs_src/query_params/tutorial002_py310.py hl[7] *} -Bu durumda, `q` fonksiyon parametresi isteğe bağlı olacak ve varsayılan değer olarak `None` alacaktır. +Bu durumda, fonksiyon parametresi `q` isteğe bağlı olur ve varsayılan olarak `None` olur. /// 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. +Ayrıca, **FastAPI** path parametresi olan `item_id`'nin bir path parametresi olduğunu ve `q`'nun path olmadığını fark edecek kadar akıllıdır; dolayısıyla bu bir query parametresidir. /// -## Sorgu Parametresi Tip DönÌşÌmÃŒ +## Sorgu parametresi tip dönÌşÌmÃŒ { #query-parameter-type-conversion } -Aşağıda görÃŒldÌğÌ gibi dönÌştÃŒrÃŒlmek ÃŒzere `bool` tipleri de tanımlayabilirsiniz: +`bool` tipleri de tanımlayabilirsiniz, ve bunlar dönÌştÃŒrÃŒlÃŒr: {* ../../docs_src/query_params/tutorial003_py310.py hl[7] *} -Bu durumda, eğer şu adrese giderseniz: +Bu durumda, şuraya giderseniz: ``` http://127.0.0.1:8000/items/foo?short=1 @@ -107,38 +107,38 @@ veya http://127.0.0.1:8000/items/foo?short=yes ``` -veya adres, herhangi farklı bir harf varyasyonu içermesi durumuna rağmen (bÃŒyÃŒk harf, sadece baş harfi bÃŒyÃŒk kelime, vb.) fonksiyonunuz, `bool` tipli `short` parametresini `True` olarak algılayacaktır. Aksi halde `False` olarak algılanacaktır. +veya başka herhangi bir bÃŒyÃŒk/kÌçÌk harf varyasyonunda (tamamı bÃŒyÃŒk, ilk harf bÃŒyÃŒk, vb.), fonksiyonunuz `short` parametresini `bool` değeri `True` olarak görecektir. Aksi halde `False` olarak görÃŒr. -## Çoklu Yol ve Sorgu Parametreleri +## Çoklu path ve query parametreleri { #multiple-path-and-query-parameters } -**FastAPI** neyin ne olduğunu ayırt edebileceğinden dolayı aynı anda birden fazla yol ve sorgu parametresi tanımlayabilirsiniz. +Aynı anda birden fazla path parametresi ve query parametresi tanımlayabilirsiniz; **FastAPI** hangisinin hangisi olduğunu bilir. -Ve parametreleri, herhangi bir sıraya koymanıza da gerek yoktur. +Ayrıca bunları belirli bir sırayla tanımlamanız gerekmez. -Ä°simlerine göre belirleneceklerdir: +Ä°sme göre tespit edilirler: {* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *} -## Zorunlu Sorgu Parametreleri +## Zorunlu query parametreleri { #required-query-parameters } -TÃŒrÃŒ yol olmayan bir parametre (şu ana kadar sadece sorgu parametrelerini gördÃŒk) için varsayılan değer tanımlarsanız o parametre zorunlu olmayacaktır. +Path olmayan parametreler (şimdilik sadece query parametrelerini gördÃŒk) için varsayılan değer tanımladığınızda, bu parametre zorunlu olmaz. -Parametre için belirli bir değer atamak istemeyip parametrenin sadece isteğe bağlı olmasını istiyorsanız değerini `None` olarak atayabilirsiniz. +Belirli bir değer eklemek istemiyor ama sadece opsiyonel olmasını istiyorsanız, varsayılanı `None` olarak ayarlayın. -Fakat, bir sorgu parametresini zorunlu yapmak istiyorsanız varsayılan bir değer atamamanız yeterli olacaktır: +Ancak bir query parametresini zorunlu yapmak istediğinizde, herhangi bir varsayılan değer tanımlamamanız yeterlidir: -{* ../../docs_src/query_params/tutorial005.py hl[6:7] *} +{* ../../docs_src/query_params/tutorial005_py39.py hl[6:7] *} -Burada `needy` parametresi `str` tipinden oluşan zorunlu bir sorgu parametresidir. +Burada query parametresi `needy`, `str` tipinde zorunlu bir query parametresidir. -Eğer tarayıcınızda şu bağlantıyı: +Tarayıcınızda şöyle bir URL açarsanız: ``` http://127.0.0.1:8000/items/foo-item ``` -...`needy` parametresini eklemeden açarsanız şuna benzer bir hata ile karşılaşırsınız: +...zorunlu `needy` parametresini eklemeden, şuna benzer bir hata görÃŒrsÃŒnÃŒz: ```JSON { @@ -156,13 +156,13 @@ http://127.0.0.1:8000/items/foo-item } ``` -`needy` zorunlu bir parametre olduğundan dolayı bağlantıda tanımlanması gerekir: +`needy` zorunlu bir parametre olduğundan, URL'de ayarlamanız gerekir: ``` http://127.0.0.1:8000/items/foo-item?needy=sooooneedy ``` -...bu iş görÃŒr: +...bu çalışır: ```JSON { @@ -171,11 +171,11 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy } ``` -Ve elbette, bazı parametreleri zorunlu, bazılarını varsayılan değerli ve bazılarını tamamen opsiyonel olarak tanımlayabilirsiniz: +Ve elbette, bazı parametreleri zorunlu, bazılarını varsayılan değerli, bazılarını da tamamen isteğe bağlı olarak tanımlayabilirsiniz: {* ../../docs_src/query_params/tutorial006_py310.py hl[8] *} -Bu durumda, 3 tane sorgu parametresi var olacaktır: +Bu durumda, 3 tane query parametresi vardır: * `needy`, zorunlu bir `str`. * `skip`, varsayılan değeri `0` olan bir `int`. @@ -183,6 +183,6 @@ Bu durumda, 3 tane sorgu parametresi var olacaktır: /// 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. +[Path Parametreleri](path-params.md#predefined-values){.internal-link target=_blank} ile aynı şekilde `Enum`'ları da kullanabilirsiniz. /// diff --git a/docs/tr/docs/tutorial/request-forms.md b/docs/tr/docs/tutorial/request-forms.md index e4e04f5f99..4608a6b79b 100644 --- a/docs/tr/docs/tutorial/request-forms.md +++ b/docs/tr/docs/tutorial/request-forms.md @@ -1,69 +1,73 @@ -# Form Verisi +# Form Verisi { #form-data } -Ä°stek gövdesinde JSON verisi yerine form alanlarını karşılamanız gerketiğinde `Form` sınıfını kullanabilirsiniz. +JSON yerine form alanlarını almanız gerektiğinde `Form` kullanabilirsiniz. /// info | Bilgi -Formları kullanmak için öncelikle `python-multipart` paketini indirmeniz gerekmektedir. +Formları kullanmak için önce `python-multipart` paketini kurun. -Örneğin `pip install python-multipart`. +Bir [virtual environment](../virtual-environments.md){.internal-link target=_blank} oluşturduğunuzdan, onu etkinleştirdiğinizden emin olun ve ardından örneğin şöyle kurun: + +```console +$ pip install python-multipart +``` /// -## `Form` Sınıfını Projenize Dahil Edin +## `Form`'u Import Edin { #import-form } -`Form` sınıfını `fastapi`'den projenize dahil edin: +`Form`'u `fastapi`'den import edin: {* ../../docs_src/request_forms/tutorial001_an_py39.py hl[3] *} -## `Form` Parametrelerini Tanımlayın +## `Form` Parametrelerini Tanımlayın { #define-form-parameters } Form parametrelerini `Body` veya `Query` için yaptığınız gibi oluşturun: {* ../../docs_src/request_forms/tutorial001_an_py39.py hl[9] *} -Örneğin, OAuth2 spesifikasyonunun kullanılabileceği ("şifre akışı" olarak adlandırılan) yollardan birinde, form alanları olarak "username" ve "password" gönderilmesi gerekir. +Örneğin OAuth2 spesifikasyonunun kullanılabileceği ("password flow" olarak adlandırılan) yollardan birinde, form alanları olarak bir `username` ve `password` göndermek zorunludur. -Bu spesifikasyon form alanlarını adlandırırken isimlerinin birebir `username` ve `password` olmasını ve JSON verisi yerine form verisi olarak gönderilmesini gerektirir. +spec, alanların adının tam olarak `username` ve `password` olmasını ve JSON değil form alanları olarak gönderilmesini gerektirir. -`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. +`Form` ile `Body` (ve `Query`, `Path`, `Cookie`) ile yaptığınız aynı konfigÃŒrasyonları tanımlayabilirsiniz; validasyon, örnekler, alias (örn. `username` yerine `user-name`) vb. dahil. /// info | Bilgi -`Form` doğrudan `Body` sınıfını miras alan bir sınıftır. +`Form`, doğrudan `Body`'den miras alan bir sınıftır. /// /// 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. +Form gövdelerini tanımlamak için `Form`'u açıkça kullanmanız gerekir; çÌnkÃŒ bunu yapmazsanız parametreler query parametreleri veya body (JSON) parametreleri olarak yorumlanır. /// -## "Form Alanları" Hakkında +## "Form Alanları" Hakkında { #about-form-fields } -HTML formlarının (`
`) verileri sunucuya gönderirken JSON'dan farklı özel bir kodlama kullanır. +HTML formlarının (`
`) verileri sunucuya gönderme şekli normalde bu veri için JSON'dan farklı "özel" bir encoding kullanır. -**FastAPI** bu verilerin JSON yerine doğru şekilde okunmasını sağlayacaktır. +**FastAPI** bu veriyi JSON yerine doğru yerden okuyacaktır. /// note | Teknik Detaylar -Form verileri normalde `application/x-www-form-urlencoded` medya tipiyle kodlanır. +Formlardan gelen veri normalde "media type" `application/x-www-form-urlencoded` kullanılarak encode edilir. -Ancak form içerisinde dosyalar yer aldığında `multipart/form-data` olarak kodlanır. Bir sonraki bölÃŒmde dosyaların işlenmesi hakkında bilgi edineceksiniz. +Ancak form dosyalar içerdiğinde `multipart/form-data` olarak encode edilir. Dosyaları ele almayı bir sonraki bölÃŒmde okuyacaksınız. -Form kodlama tÃŒrleri ve form alanları hakkında daha fazla bilgi edinmek istiyorsanız MDN web docs for POST sayfasını ziyaret edebilirsiniz. +Bu encoding'ler ve form alanları hakkında daha fazla okumak isterseniz, MDN web docs for POST sayfasına gidin. /// /// 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. +Bir *path operation* içinde birden fazla `Form` parametresi tanımlayabilirsiniz, ancak JSON olarak almayı beklediğiniz `Body` alanlarını da ayrıca tanımlayamazsınız; çÌnkÃŒ bu durumda request'in body'si `application/json` yerine `application/x-www-form-urlencoded` ile encode edilmiş olur. -Bu **FastAPI**'ın getirdiği bir kısıtlama değildir, HTTP protokolÃŒnÃŒn bir parçasıdır. +Bu **FastAPI**'ın bir kısıtlaması değildir, HTTP protokolÃŒnÃŒn bir parçasıdır. /// -## Özet +## Özet { #recap } -Form verisi girdi parametreleri tanımlamak için `Form` sınıfını kullanın. +Form verisi girdi parametrelerini tanımlamak için `Form` kullanın. diff --git a/docs/tr/docs/tutorial/static-files.md b/docs/tr/docs/tutorial/static-files.md index 4542aca773..d30b4389d0 100644 --- a/docs/tr/docs/tutorial/static-files.md +++ b/docs/tr/docs/tutorial/static-files.md @@ -1,40 +1,40 @@ -# Statik Dosyalar +# Statik Dosyalar { #static-files } -`StaticFiles`'ı kullanarak statik dosyaları bir yol altında sunabilirsiniz. +`StaticFiles` kullanarak bir dizindeki statik dosyaları otomatik olarak sunabilirsiniz. -## `StaticFiles` Kullanımı +## `StaticFiles` Kullanımı { #use-staticfiles } -* `StaticFiles` sınıfını projenize dahil edin. -* Bir `StaticFiles()` örneğini belirli bir yola bağlayın. +* `StaticFiles`'ı import edin. +* Belirli bir path'te bir `StaticFiles()` örneğini "mount" edin. -{* ../../docs_src/static_files/tutorial001.py hl[2,6] *} +{* ../../docs_src/static_files/tutorial001_py39.py hl[2,6] *} /// note | Teknik Detaylar -Projenize dahil etmek için `from starlette.staticfiles import StaticFiles` kullanabilirsiniz. +`from starlette.staticfiles import StaticFiles` da kullanabilirsiniz. -**FastAPI**, geliştiricilere kolaylık sağlamak amacıyla `starlette.staticfiles`'ı `fastapi.staticfiles` olarak sağlar. Ancak `StaticFiles` sınıfı aslında doğrudan Starlette'den gelir. +**FastAPI**, geliştirici olarak size kolaylık olsun diye `starlette.staticfiles`'ı `fastapi.staticfiles` olarak da sağlar. Ancak aslında doğrudan Starlette'den gelir. /// -### Bağlama (Mounting) Nedir? +### "Mounting" Nedir { #what-is-mounting } -"Bağlamak", belirli bir yola tamamen "bağımsız" bir uygulama eklemek anlamına gelir ve ardından tÃŒm alt yollara gelen istekler bu uygulama tarafından işlenir. +"Mounting", belirli bir path'te tamamen "bağımsız" bir uygulama eklemek ve sonrasında tÃŒm alt path'leri handle etmesini sağlamak demektir. -Bu, bir `APIRouter` kullanmaktan farklıdır çÌnkÃŒ bağlanmış bir uygulama tamamen bağımsızdır. Ana uygulamanızın OpenAPI ve dokÃŒmanlar, bağlanmış uygulamadan hiçbir şey içermez, vb. +Bu, bir `APIRouter` kullanmaktan farklıdır; çÌnkÃŒ mount edilen uygulama tamamen bağımsızdır. Ana uygulamanızın OpenAPI ve docs'ları, mount edilen uygulamadan hiçbir şey içermez, vb. -[Advanced User Guide](../advanced/index.md){.internal-link target=_blank} bölÃŒmÃŒnde daha fazla bilgi edinebilirsiniz. +Bununla ilgili daha fazla bilgiyi [Advanced User Guide](../advanced/index.md){.internal-link target=_blank} içinde okuyabilirsiniz. -## Detaylar +## Detaylar { #details } -`"/static"` ifadesi, bu "alt uygulamanın" "bağlanacağı" alt yolu belirtir. Bu nedenle, `"/static"` ile başlayan her yol, bu uygulama tarafından işlenir. +Ä°lk `"/static"`, bu "alt uygulamanın" "mount" edileceği alt path'i ifade eder. Dolayısıyla `"/static"` ile başlayan herhangi bir path bunun tarafından handle edilir. -`directory="static"` ifadesi, statik dosyalarınızı içeren dizinin adını belirtir. +`directory="static"`, statik dosyalarınızı içeren dizinin adını ifade eder. -`name="static"` ifadesi, alt uygulamanın **FastAPI** tarafından kullanılacak ismini belirtir. +`name="static"`, **FastAPI**'nin dahili olarak kullanabileceği bir isim verir. -Bu parametrelerin hepsi "`static`"den farklı olabilir, bunları kendi uygulamanızın ihtiyaçlarına göre belirleyebilirsiniz. +Bu parametrelerin hepsi "`static`" ile aynı olmak zorunda değildir; kendi uygulamanızın ihtiyaçlarına ve özel detaylarına göre ayarlayın. -## Daha Fazla Bilgi +## Daha Fazla Bilgi { #more-info } -Daha fazla detay ve seçenek için Starlette'in Statik Dosyalar hakkındaki dokÃŒmantasyonunu incelleyin. +Daha fazla detay ve seçenek için Starlette'in Statik Dosyalar hakkındaki dokÃŒmanlarını inceleyin. From 08924400c2c75533685148b029defcf6913f1def Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sat, 31 Jan 2026 18:32:52 +0000 Subject: [PATCH 042/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 975bf774e9..eb72d559d0 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -19,6 +19,7 @@ hide: ### Translations +* 🌐 Update translations for tr (update-outdated). PR [#14745](https://github.com/fastapi/fastapi/pull/14745) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update `llm-prompt.md` for Korean language. PR [#14763](https://github.com/fastapi/fastapi/pull/14763) by [@seuthootDev](https://github.com/seuthootDev). * 🌐 Update translations for ko (update outdated, found by fixer tool). PR [#14738](https://github.com/fastapi/fastapi/pull/14738) by [@YuriiMotov](https://github.com/YuriiMotov). * 🌐 Update translations for de (update-outdated). PR [#14690](https://github.com/fastapi/fastapi/pull/14690) by [@tiangolo](https://github.com/tiangolo). From df6530e0020f0b26951fff58b02d0a7e9ab834d3 Mon Sep 17 00:00:00 2001 From: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> Date: Sun, 1 Feb 2026 12:44:39 +0300 Subject: [PATCH 043/108] =?UTF-8?q?=F0=9F=8C=90=20Update=20translations=20?= =?UTF-8?q?for=20uk=20(update=20outdated,=20found=20by=20fixer=20tool)=20(?= =?UTF-8?q?#14739)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/uk/docs/alternatives.md | 80 ++++++++++---------- docs/uk/docs/fastapi-cli.md | 96 +++++++++++------------- docs/uk/docs/features.md | 138 +++++++++++++++++++---------------- 3 files changed, 160 insertions(+), 154 deletions(-) diff --git a/docs/uk/docs/alternatives.md b/docs/uk/docs/alternatives.md index 786df45c50..d44ca794f8 100644 --- a/docs/uk/docs/alternatives.md +++ b/docs/uk/docs/alternatives.md @@ -1,8 +1,8 @@ -# АльтерМатОвО, МатхМеММя та пПрівМяММя +# АльтерМатОвО, МатхМеММя та пПрівМяММя { #alternatives-inspiration-and-comparisons } -ЩП МаЎОхМулП Ма ствПреММя **FastAPI**, якОй віМ у пПріМяММі з іМшОЌО альтерМатОваЌО та чПгП віМ у МОх МавчОвся. +ЩП МаЎОхМулП **FastAPI**, як віМ пПрівМюється з альтерМатОваЌО та чПгП віМ у МОх МавчОвся. -## Вступ +## Вступ { #intro } **FastAPI** Ме ісМувалП б, якбО Ме пПпереЎМі рПбПтО іМшОх. @@ -12,17 +12,17 @@ Але в якОйсь ЌПЌеМт Ме булП іМшПгП вОхПЎу, ПкріЌ ствПреММя чПгПсь, щП МаЎавалП б усі ці фуМкції, взявшО Майкращі іЎеї з пПпереЎМіх іМструЌеМтів і пПєЎМавшО їх МайкращОЌ чОМПЌ, вОкПрОстПвуючО ЌПвМі фуМкції, які Мавіть Ме булО ЎПступМі раМіше (Python 3.6+ піЎказкО тОпів). -## ППпереЎМі іМструЌеМтО +## ППпереЎМі іМструЌеМтО { #previous-tools } -### Django +### Django { #django } Ње МайпПпулярМішОй фрейЌвПрк Python, якОй кПрОстується шОрПкПю ЎПвірПю. Ð’Ñ–Ðœ вОкПрОстПвується Ўля ствПреММя такОх сОстеЌ, як Instagram. Ð’Ñ–Ðœ віЎМПсМП тісМП пПв’язаМОй з реляційМОЌО базаЌО ЎаМОх (МапрОклаЎ, MySQL абП PostgreSQL), тПЌу ЌатО базу ЎаМОх NoSQL (МапрОклаЎ, Couchbase, MongoDB, Cassandra тПщП) як ПсМПвМОй ЌехаМізЌ зберігаММя Ме Ўуже прПстП. -Ð’Ñ–Ðœ був ствПреМОй Ўля ствПреММя HTML у серверМій частОМі, а Ме Ўля ствПреММя API, які вОкПрОстПвуються сучасМОЌ іМтерфейсПЌ (як-Пт React, Vue.js і Angular) абП іМшОЌО сОстеЌаЌО (як-Пт IoT прОстрПї), які спілкуються з МОЌ. +Ð’Ñ–Ðœ був ствПреМОй Ўля ствПреММя HTML у серверМій частОМі, а Ме Ўля ствПреММя API, які вОкПрОстПвуються сучасМОЌ іМтерфейсПЌ (як-Пт React, Vue.js і Angular) абП іМшОЌО сОстеЌаЌО (як-Пт IoT прОстрПї), які спілкуються з МОЌ. -### Django REST Framework +### Django REST Framework { #django-rest-framework } ЀрейЌвПрк Django REST був ствПреМОй як гМучкОй іМструЌеМтарій Ўля ствПреММя веб-іМтерфейсів API вОкПрОстПвуючО Django в ПсМПві, щПб пПкращОтО йПгП ЌПжлОвПсті API. @@ -42,7 +42,7 @@ Django REST Framework ствПрОв ТПЌ Крісті. ТПй саЌОй тв /// -### Flask +### Flask { #flask } Flask — це «ЌікрПфрейЌвПрк», віМ Ме включає іМтеграцію базО ЎаМОх, а такПж багатП речей, які за заЌПвчуваММяЌ є в Django. @@ -64,7 +64,7 @@ Flask — це «ЌікрПфрейЌвПрк», віМ Ме включає Ñ–Ðœ /// -### Requests +### Requests { #requests } **FastAPI** МасправЎі Ме є альтерМатОвПю **Requests**. Сфера їх застПсуваММя Ўуже різМа. @@ -88,12 +88,12 @@ Requests Ќають Ўуже прПстОй та іМтуїтОвМП зрПзу response = requests.get("http://example.com/some/url") ``` -ВіЎпПвіЎМа Пперація *рПуту* API FastAPI ЌПже вОгляЎатО так: +ВіЎпПвіЎМа Пперація шляху API FastAPI ЌПже вОгляЎатО так: ```Python hl_lines="1" @app.get("/some/url") def read_url(): - return {"message": "Hello World"} + return {"message": "Hello World"} ``` ЗверМіть увагу Ма схПжість у `requests.get(...)` і `@app.get(...)`. @@ -101,12 +101,12 @@ def read_url(): /// check | НаЎОхМулП **FastAPI** Ма * Майте прПстОй та іМтуїтОвМП зрПзуЌілОй API. - * ВОкПрОстПвуйте іЌеМа (Пперації) ЌетПЎів HTTP безпПсереЎМьП, прПстОЌ та іМтуїтОвМП зрПзуЌілОЌ спПсПбПЌ. - * РПзуЌМі параЌетрО за заЌПвчуваММяЌ, але пПтужМі МалаштуваММя. +* ВОкПрОстПвуйте іЌеМа (Пперації) ЌетПЎів HTTP безпПсереЎМьП, прПстОЌ та іМтуїтОвМП зрПзуЌілОЌ спПсПбПЌ. +* РПзуЌМі параЌетрО за заЌПвчуваММяЌ, але пПтужМі МалаштуваММя. /// -### Swagger / OpenAPI +### Swagger / OpenAPI { #swagger-openapi } ГПлПвМПю фуМкцією, яку я хПтів віЎ Django REST Framework, була автПЌатОчМа API ЎПкуЌеМтація. @@ -124,18 +124,18 @@ def read_url(): ІМтегруватО іМструЌеМтО іМтерфейсу Ма ПсМПві стаМЎартів: - * ІМтерфейс Swagger - * ReDoc +* ІМтерфейс Swagger +* ReDoc Њі Ўва булП ПбраМП через те, щП вПМО ЎПсОть пПпулярМі та стабільМі, але, вОкПМавшО швОЎкОй пПшук, вО ЌПжете зМайтО ЎесяткО ЎПЎаткПвОх альтерМатОвМОх іМтерфейсів Ўля OpenAPI (які ЌПжМа вОкПрОстПвуватО з **FastAPI**). /// -### ЀрейЌвПркО REST Ўля Flask +### ЀрейЌвПркО REST Ўля Flask { #flask-rest-frameworks } ІсМує кілька фрейЌвПрків Flask REST, але, вОтратОвшО час і рПбПту Ма їх ЎПсліЎжеММя, я вОявОв, щП багатП з МОх прОпОМеМП абП залОшеМП, з кількПЌа пПстійМОЌО прПблеЌаЌО, які зрПбОлО їх МепрОЎатМОЌО. -### Marshmallow +### Marshmallow { #marshmallow } ОЎМією з гПлПвМОх фуМкцій, МеПбхіЎМОх Ўля сОстеЌ API, є "серіалізація", яка бере ЎаМі з кПЎу (Python) і перетвПрює їх Ма щПсь, щП ЌПжМа МаЎіслатО через Ќережу. НапрОклаЎ, перетвПреММя Пб’єкта, щП ЌістОть ЎаМі з базО ЎаМОх, Ма Пб’єкт JSON. ПеретвПреММя Пб’єктів `datetime` Ма стрПкО тПщП. @@ -153,7 +153,7 @@ Marshmallow ствПреМП Ўля забезпечеММя цОх фуМкці /// -### Webargs +### Webargs { #webargs } ІМшПю важлОвПю фуМкцією, МеПбхіЎМПю Ўля API, є аМаліз ЎаМОх із вхіЎМОх запОтів. @@ -175,7 +175,7 @@ Webargs був ствПреМОй тОЌО ж рПзрПбМОкаЌО Marshmall /// -### APISpec +### APISpec { #apispec } Marshmallow і Webargs забезпечують перевірку, аМаліз і серіалізацію як плагіМО. @@ -205,7 +205,7 @@ APISpec був ствПреМОй тОЌО ж рПзрПбМОкаЌО Marshmall /// -### Flask-apispec +### Flask-apispec { #flask-apispec } Ње плагіМ Flask, якОй Пб’єЎМує Webargs, Marshmallow і APISpec. @@ -237,13 +237,13 @@ Flask-apispec був ствПреМОй тОЌО ж рПзрПбМОкаЌО Mar /// -### NestJS (та Angular) +### NestJS (та Angular) { #nestjs-and-angular } Ње Мавіть Ме Python, NestJS — це фрейЌвПрк NodeJS JavaScript (TypeScript), МатхМеММОй Angular. Ње ЎПсягає чПгПсь пПЎібМПгП ЎП тПгП, щП ЌПжМа зрПбОтО з Flask-apispec. -Ð’Ñ–Ðœ Ќає іМтегрПваМу сОстеЌу впрПваЎжеММя залежМПстей, МатхМеММу Angular two. Ð’Ñ–Ðœ пПтребує пПпереЎМьПї реєстрації «injectables» (як і всі іМші сОстеЌО впрПваЎжеММя залежМПстей, які я зМаю), тПЌу це збільшує багатПслівМість та пПвтПреММя кПЎу. +Ð’Ñ–Ðœ Ќає іМтегрПваМу сОстеЌу впрПваЎжеММя залежМПстей, МатхМеММу Angular 2. Ð’Ñ–Ðœ пПтребує пПпереЎМьПї реєстрації «injectables» (як і всі іМші сОстеЌО впрПваЎжеММя залежМПстей, які я зМаю), тПЌу це збільшує багатПслівМість та пПвтПреММя кПЎу. ОскількО параЌетрО ПпОсаМі за ЎПпПЌПгПю тОпів TypeScript (пПЎібМП ЎП піЎказПк тОпу Python), піЎтрОЌка реЎактПра ЎПсОть хПрПша. @@ -259,7 +259,7 @@ Flask-apispec був ствПреМОй тОЌО ж рПзрПбМОкаЌО Mar /// -### Sanic +### Sanic { #sanic } Ње був ПЎОМ із першОх МаЎзвОчайМП швОЎкОх фрейЌвПрків Python Ма ПсМПві `asyncio`. Ð’Ñ–Ðœ був Ўуже схПжОй Ма Flask. @@ -279,7 +279,7 @@ Flask-apispec був ствПреМОй тОЌО ж рПзрПбМОкаЌО Mar /// -### Falcon +### Falcon { #falcon } Falcon — ще ПЎОМ вОсПкПпрПЎуктОвМОй фрейЌвПрк Python, віМ рПзрПблеМОй як ЌіМіЌальМОй і працює як ПсМПва іМшОх фрейЌвПрків, такОх як Hug. @@ -297,7 +297,7 @@ Falcon — ще ПЎОМ вОсПкПпрПЎуктОвМОй фрейЌвПрк /// -### Molten +### Molten { #molten } Я віЎкрОв Ўля себе Molten Ма першОх етапах ствПреММя **FastAPI**. І віМ Ќає ЎПсОть схПжі іЎеї: @@ -321,7 +321,7 @@ Falcon — ще ПЎОМ вОсПкПпрПЎуктОвМОй фрейЌвПрк /// -### Hug +### Hug { #hug } Hug був ПЎМОЌ із першОх фрейЌвПрків, якОй реалізував ПгПлПшеММя тОпів параЌетрів API за ЎПпПЌПгПю піЎказПк тОпу Python. Ње була чуЎПва іЎея, яка МаЎОхМула іМші іМструЌеМтО зрПбОтО те саЌе. @@ -351,7 +351,7 @@ Hug МаЎОхМув частОМу APIStar і був ПЎМОЌ із Майбі /// -### APIStar (<= 0,5) +### APIStar (<= 0,5) { #apistar-0-5 } БезпПсереЎМьП переЎ тОЌ, як вОрішОтО ствПрОтО **FastAPI**, я зМайшПв сервер **APIStar**. Ð’Ñ–Ðœ Ќав Ќайже все, щП я шукав, і Ќав чуЎПвОй ЎОзайМ. @@ -379,9 +379,9 @@ Hug МаЎОхМув частОМу APIStar і був ПЎМОЌ із Майбі APIStar ствПрОв ТПЌ Крісті. ТПй саЌОй хлПпець, якОй ствПрОв: - * Django REST Framework - * Starlette (Ма якПЌу базується **FastAPI**) - * Uvicorn (вОкПрОстПвується Starlette і **FastAPI**) +* Django REST Framework +* Starlette (Ма якПЌу базується **FastAPI**) +* Uvicorn (вОкПрОстПвується Starlette і **FastAPI**) /// @@ -393,13 +393,15 @@ APIStar ствПрОв ТПЌ Крісті. ТПй саЌОй хлПпець, я І після трОвалПгП пПшуку пПЎібМПї структурО та тестуваММя багатьПх різМОх альтерМатОв, APIStar став МайкращОЌ ЎПступМОЌ варіаМтПЌ. - ППтіЌ APIStar перестав ісМуватО як сервер, і булП ствПреМП Starlette, якОй став МПвПю кращПю ПсМПвПю Ўля такПї сОстеЌО. Ње сталП ПстаММіЌ ЎжерелПЌ МатхМеММя Ўля ствПреММя **FastAPI**. Я вважаю **FastAPI** «ЎухПвМОЌ спаЎкПєЌцеЌ» APIStar, уЎПскПМалюючО та рПзшОрюючО фуМкції, сОстеЌу ввеЎеММя тексту та іМші частОМО Ма ПсМПві ЎПсвіЎу, ПтрОЌаМПгП віЎ усіх цОх пПпереЎМіх іМструЌеМтів. + ППтіЌ APIStar перестав ісМуватО як сервер, і булП ствПреМП Starlette, якОй став МПвПю кращПю ПсМПвПю Ўля такПї сОстеЌО. Ње сталП ПстаММіЌ ЎжерелПЌ МатхМеММя Ўля ствПреММя **FastAPI**. + + Я вважаю **FastAPI** «ЎухПвМОЌ спаЎкПєЌцеЌ» APIStar, уЎПскПМалюючО та рПзшОрюючО фуМкції, сОстеЌу тОпізації та іМші частОМО Ма ПсМПві ЎПсвіЎу, ПтрОЌаМПгП віЎ усіх цОх пПпереЎМіх іМструЌеМтів. /// -## ВОкПрОстПвується **FastAPI** +## ВОкПрОстПвується **FastAPI** { #used-by-fastapi } -### Pydantic +### Pydantic { #pydantic } Pydantic — це бібліПтека Ўля вОзМачеММя перевіркО ЎаМОх, серіалізації та ЎПкуЌеМтації (за ЎПпПЌПгПю схеЌО JSON) Ма ПсМПві піЎказПк тОпу Python. @@ -415,9 +417,9 @@ Pydantic — це бібліПтека Ўля вОзМачеММя переві /// -### Starlette +### Starlette { #starlette } -Starlette — це легкОй фрейЌвПрк/Мабір іМструЌеМтів ASGI, якОй іЎеальМП піЎхПЎОть Ўля ствПреММя вОсПкПпрПЎуктОвМОх asyncio сервісів. +Starlette — це легкОй фрейЌвПрк/Мабір іМструЌеМтів ASGI, якОй іЎеальМП піЎхПЎОть Ўля ствПреММя вОсПкПпрПЎуктОвМОх asyncio сервісів. Ð’Ñ–Ðœ Ўуже прПстОй та іМтуїтОвМП зрПзуЌілОй. ЙПгП рПзрПблеМП такОЌ чОМПЌ, щПб йПгП ЌПжМа булП легкП рПзшОрюватО та ЌатО ЌПЎульМі кПЌпПМеМтО. @@ -460,7 +462,7 @@ ASGI — це МПвОй «стаМЎарт», якОй рПзрПбляєтьс /// -### Uvicorn +### Uvicorn { #uvicorn } Uvicorn — це блОскавОчМОй сервер ASGI, пПбуЎПваМОй Ма uvloop і httptools. @@ -472,12 +474,12 @@ Uvicorn — це блОскавОчМОй сервер ASGI, пПбуЎПваМ ОсМПвМОй веб-сервер Ўля запуску прПграЌ **FastAPI**. - ВО ЌПжете пПєЎМатО йПгП з Gunicorn, щПб ЌатО асОМхрПММОй багатПпрПцесМОй сервер. + ВО такПж ЌПжете вОкПрОстатО параЌетр кПЌаМЎМПгП ряЎка `--workers`, щПб ЌатО асОМхрПММОй багатПпрПцесМОй сервер. ДПЎаткПву іМфПрЌацію ЎОв. у рПзЎілі [РПзгПртаММя](deployment/index.md){.internal-link target=_blank}. /// -## ОрієМтОрО та швОЎкість +## ОрієМтОрО та швОЎкість { #benchmarks-and-speed } ЩПб зрПзуЌітО, пПрівМятО та пПбачОтО різМОцю Ќіж Uvicorn, Starlette і FastAPI, перегляМьте рПзЎіл прП [БеМчЌаркО](benchmarks.md){.internal-link target=_blank}. diff --git a/docs/uk/docs/fastapi-cli.md b/docs/uk/docs/fastapi-cli.md index f18b104718..eb55382302 100644 --- a/docs/uk/docs/fastapi-cli.md +++ b/docs/uk/docs/fastapi-cli.md @@ -1,83 +1,75 @@ -# FastAPI CLI +# FastAPI CLI { #fastapi-cli } -**FastAPI CLI** це прПграЌа кПЌаМЎМПгП ряЎка, яку ВО ЌПжете вОкПрОстПвуватО, щПб ПбслугПвуватО Ваш ЎПЎатПк FastAPI, керуватО ВашОЌО FastApi прПектаЌО, тПщП. +**FastAPI CLI** — це прПграЌа кПЌаМЎМПгП ряЎка, яку вО ЌПжете вОкПрОстПвуватО, щПб ПбслугПвуватО ваш застПсуМПк FastAPI, керуватО вашОЌ прПєктПЌ FastAPI тПщП. -КПлО ВО встаМПвлюєте FastApi (тПбтП вОкПМуєте `pip install "fastapi[standard]"`), ВО такПж встаМПвлюєте пакуМПк `fastapi-cli`, цей пакуМПк МаЎає кПЌаМЎу `fastapi` в терЌіМалі. +КПлО вО встаМПвлюєте FastAPI (МапрОклаЎ, за ЎПпПЌПгПю `pip install "fastapi[standard]"`), віМ включає пакет піЎ МазвПю `fastapi-cli`, цей пакет МаЎає кПЌаМЎу `fastapi` у терЌіМалі. -Для запуску ВашПгП FastAPI прПекту Ўля рПзрПбкО, ВО ЌПжете скПрОстатОсь кПЌаМЎПю `fastapi dev`: +ЩПб запустОтО ваш застПсуМПк FastAPI Ўля рПзрПбкО, вО ЌПжете вОкПрОстатО кПЌаМЎу `fastapi dev`:
```console -$ fastapi dev main.py -INFO Using path main.py -INFO Resolved absolute path /home/user/code/awesomeapp/main.py -INFO Searching for package file structure from directories with __init__.py files -INFO Importing from /home/user/code/awesomeapp +$ fastapi dev main.py - ╭─ Python module file ─╮ - │ │ - │ 🐍 main.py │ - │ │ - ╰──────────────────────╯ + FastAPI Starting development server 🚀 -INFO Importing module main -INFO Found importable FastAPI app + Searching for package file structure from directories with + __init__.py files + Importing from /home/user/code/awesomeapp - ╭─ Importable FastAPI app ─╮ - │ │ - │ from main import app │ - │ │ - ╰──────────────────────────╯ + module 🐍 main.py -INFO Using import string main:app + code Importing the FastAPI app object from the module with the + following code: - ╭────────── FastAPI CLI - Development mode ───────────╮ - │ │ - │ Serving at: http://127.0.0.1:8000 │ - │ │ - │ API docs: http://127.0.0.1:8000/docs │ - │ │ - │ Running in development mode, for production use: │ - │ │ - │ fastapi run │ - │ │ - ╰─────────────────────────────────────────────────────╯ + from main import app -INFO: Will watch for changes in these directories: ['/home/user/code/awesomeapp'] -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -INFO: Started reloader process [2265862] using WatchFiles -INFO: Started server process [2265873] -INFO: Waiting for application startup. -INFO: Application startup complete. + app Using import string: main:app + + server Server started at http://127.0.0.1:8000 + server Documentation at http://127.0.0.1:8000/docs + + tip Running in development mode, for production use: + fastapi run + + Logs: + + INFO Will watch for changes in these directories: + ['/home/user/code/awesomeapp'] + INFO Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to + quit) + INFO Started reloader process [383138] using WatchFiles + INFO Started server process [383153] + INFO Waiting for application startup. + INFO Application startup complete. ```
-ПрПграЌа кПЌаМЎМПгП ряЎка `fastapi` це **FastAPI CLI**. +ПрПграЌа кПЌаМЎМПгП ряЎка піЎ МазвПю `fastapi` — це **FastAPI CLI**. -FastAPI CLI прОйЌає шлях ЎП ВашПї Python прПграЌО (Мапр. `main.py`) і автПЌатОчМП вОявляє екзеЌпляр `FastAPI` (зазвОчай МазваМОй `app`), ПбОрає кПректМОй прПцес іЌпПрту, а пПтіЌ ПбслугПвує йПгП. +FastAPI CLI бере шлях ЎП вашПї Python-прПграЌО (МапрОклаЎ, `main.py`) і автПЌатОчМП вОявляє екзеЌпляр `FastAPI` (зазвОчай з МазвПю `app`), вОзМачає правОльМОй прПцес іЌпПрту, а пПтіЌ ПбслугПвує йПгП. -НатПЌість, Ўля запуску у прПЎакшМ вОкПрОстПвуйте `fastapi run`. 🚀 +НатПЌість, Ўля прПЎакшМ вО вОкПрОсталО б `fastapi run`. 🚀 -ВсереЎОМі **FastAPI CLI** вОкПрОстПвує Uvicorn, вОсПкПпрПЎуктОвМОй, production-ready, ASGI cервер. 😎 +ВМутрішМьП **FastAPI CLI** вОкПрОстПвує Uvicorn, вОсПкПпрПЎуктОвМОй, production-ready, ASGI сервер. 😎 -## `fastapi dev` +## `fastapi dev` { #fastapi-dev } -ВОкПрОстаММя `fastapi dev` іМіціює режОЌ рПзрПбкО. +Запуск `fastapi dev` іМіціює режОЌ рПзрПбкО. -За заЌПвчуваММяЌ, **автПЌатОчМе перезаваМтажеММя** увіЌкМеМе, автПЌатОчМП перезаваМтажуючО сервер кПжМПгП разу, кПлО ВО зЌіМюєте Ваш кПЎ. Ње ресурсП-затратМП, та ЌПже бутО ЌеМш стабільМОЌ, Між кПлО вПМП вОЌкМеМе. ВО пПвОММі вОкПрОстПвуватО йПгП тількО піЎ час рПзрПбкО. ВПМП такПж слухає IP-аЎресу `127.0.0.1`, щП є IP ВашПгП Ўевайсу Ўля саЌПстійМПї кПЌуМікації з саЌОЌ сПбПю (`localhost`). +За заЌПвчуваММяЌ **auto-reload** увіЌкМеМП, і сервер автПЌатОчМП перезаваМтажується, кПлО вО вМПсОте зЌіМО у ваш кПЎ. Ње ресурсПєЌМП та ЌПже бутО ЌеМш стабільМОЌ, Між кПлО йПгП вОЌкМеМП. ВаЌ сліЎ вОкПрОстПвуватО це лОше Ўля рПзрПбкО. ТакПж віМ слухає IP-аЎресу `127.0.0.1`, яка є IP-аЎресПю Ўля тПгП, щПб ваша ЌашОМа ЌПгла взаєЌПЎіятО лОше саЌа з сПбПю (`localhost`). -## `fastapi run` +## `fastapi run` { #fastapi-run } -ВОкПМаММя `fastapi run` запустОть FastAPI у прПЎакшМ-режОЌі за заЌПвчуваММяЌ. +ВОкПМаММя `fastapi run` за заЌПвчуваММяЌ запускає FastAPI у прПЎакшМ-режОЌі. -За заЌПвчуваММяЌ, **автПЌатОчМе перезаваМтажеММя** вОЌкМеМе. ВПМП такПж прПслухПвує IP-аЎресу `0.0.0.0`, щП ПзМачає всі ЎПступМі IP аЎресО, тОЌ саЌОЌ ЎаючО зЌПгу буЎь-кПЌу кПЌуМікуватО з ЎевайсПЌ. Так ВО зазвОчай буЎете запускатО йПгП у прПЎакшМ, МапрОклаЎ у кПМтейМері. +За заЌПвчуваММяЌ **auto-reload** вОЌкМеМП. ТакПж віМ слухає IP-аЎресу `0.0.0.0`, щП ПзМачає всі ЎПступМі IP-аЎресО, такОЌ чОМПЌ віМ буЎе публічМП ЎПступМОЌ Ўля буЎь-кПгП, хтП ЌПже взаєЌПЎіятО з ЌашОМПю. ЗазвОчай саЌе так вО запускатОЌете йПгП в прПЎакшМ, МапрОклаЎ у кПМтейМері. -В більшПсті вОпаЎків ВО ЌПжете (і Ќаєте) ЌатО "termination proxy", якОй ПбрПбляє HTTPS Ўля Вас, це залежОть віЎ спПсПбу рПзгПртаММя вашПгП ЎПЎатку, Ваш прПвайЎер ЌПже зрПбОтО це Ўля Вас, абП ВаЌ пПтрібМП МалаштуватО йПгП саЌПстійМП. +У більшПсті вОпаЎків вО (і ваЌ сліЎ) ЌатОЌете «termination proxy», якОй ПбрПбляє HTTPS Ўля вас зверху; це залежатОЌе віЎ тПгП, як вО рПзгПртаєте ваш застПсуМПк: ваш прПвайЎер ЌПже зрПбОтО це за вас, абП ваЌ ЌПже зМаЎПбОтОся МалаштуватО це саЌПстійМП. -/// tip +/// tip | ППраЎа -ВО ЌПжете ЎізМатОсь більше прП це у [ЎПкуЌеМтації прП рПзгПртуваММя](deployment/index.md){.internal-link target=_blank}. +ВО ЌПжете ЎізМатОся більше прП це в [ЎПкуЌеМтації з рПзгПртаММя](deployment/index.md){.internal-link target=_blank}. /// diff --git a/docs/uk/docs/features.md b/docs/uk/docs/features.md index aa0ef7c79d..d8233115fd 100644 --- a/docs/uk/docs/features.md +++ b/docs/uk/docs/features.md @@ -1,21 +1,21 @@ -# ЀуМкціПМальМі ЌПжлОвПсті +# ЀуМкціПМальМі ЌПжлОвПсті { #features } -## ЀуМкціПМальМі ЌПжлОвПсті FastAPI +## ЀуМкціПМальМі ЌПжлОвПсті FastAPI { #fastapi-features } **FastAPI** МаЎає ваЌ такі ЌПжлОвПсті: -### ВОкПрОстаММя віЎкрОтОх стаМЎартів +### На ПсМПві віЎкрОтОх стаМЎартів { #based-on-open-standards } * OpenAPI Ўля ствПреММя API, включаючО ПгПлПшеММя шляхів, Пперацій, параЌетрів, тіл запОтів, безпекО тПщП. * АвтПЌатОчМа ЎПкуЌеМтація ЌПЎелей ЎаМОх за ЎПпПЌПгПю JSON Schema (ПскількО OpenAPI базується саЌе Ма JSON Schema). * РПзрПблеМП Ма ПсМПві цОх стаМЎартів після ретельМПгП аМалізу, а Ме як ЎПЎаткПвОй рівеМь пПверх ПсМПвМПї архітектурО. -* Ње такПж Ўає зЌПгу автПЌатОчМП **геМеруватО кПЎ клієМта** багатьЌа ЌПваЌО. +* Ње такПж Ўає зЌПгу вОкПрОстПвуватО автПЌатОчМу **геМерацію клієМтськПгП кПЎу** багатьЌа ЌПваЌО. -### АвтПЌатОчМа геМерація ЎПкуЌеМтації +### АвтПЌатОчМа ЎПкуЌеМтація { #automatic-docs } -ІМтерактОвМа ЎПкуЌеМтація API та вебіМтерфейс Ўля йПгП ЎПсліЎжеММя. ОскількО фрейЌвПрк базується Ма OpenAPI, є кілька варіаМтів, Ўва з якОх включеМі за заЌПвчуваММяЌ. +ІМтерактОвМа ЎПкуЌеМтація API та вебіМтерфейсО Ўля йПгП ЎПсліЎжеММя. ОскількО фрейЌвПрк базується Ма OpenAPI, є кілька варіаМтів, 2 з якОх включеМі за заЌПвчуваММяЌ. -* Swagger UI — ЎПзвПляє іМтерактОвМП перегляЎатО API, вОклОкатО та тестуватО йПгП пряЌП у браузері. +* Swagger UI — з іМтерактОвМОЌ ЎПсліЎжеММяЌ, вОклОкПЌ і тестуваММяЌ вашПгП API пряЌП з браузера. ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) @@ -23,23 +23,25 @@ ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) -### ТількО сучасМОй Python +### ЛОше сучасМОй Python { #just-modern-python } -FastAPI вОкПрОстПвує стаМЎартМі **тОпО Python** (завЎякО Pydantic). ВаЌ Ме пПтрібМП вОвчатО МПвОй сОМтаксОс — лОше стаМЎартМОй сучасМОй Python. +Усе базується Ма стаМЎартМОх ПгПлПшеММях **тОпів Python** (завЎякО Pydantic). ЖПЎМПгП МПвПгП сОМтаксОсу Ўля вОвчеММя. ЛОше стаМЎартМОй сучасМОй Python. -ЯкщП ваЌ пПтрібМе кПрПтке МагаЎуваММя прП вОкПрОстаММя тОпів у Python (Мавіть якщП вО Ме вОкПрОстПвуєте FastAPI), перегляМьте кПрПткОй піЎручМОк: [Вступ ЎП тОпів Python](python-types.md){.internal-link target=_blank}. +ЯкщП ваЌ пПтрібМП 2-хвОлОММе МагаЎуваММя прП те, як вОкПрОстПвуватО тОпО Python (Мавіть якщП вО Ме вОкПрОстПвуєте FastAPI), перегляМьте кПрПткОй піЎручМОк: [ТОпО Python](python-types.md){.internal-link target=_blank}. -Ось прОклаЎ стаМЎартМПгП Python-кПЎу з тОпаЌО: +ВО пОшете стаМЎартМОй Python з тОпаЌО: ```Python from datetime import date + from pydantic import BaseModel -# ОгПлПшеММя зЌіММПї як str -# з піЎтрОЌкПю автПЎПпПвМеММя у реЎактПрі +# ОгПлПсіть зЌіММу як str +# та ПтрОЌайте піЎтрОЌку реЎактПра всереЎОМі фуМкції def main(user_id: str): return user_id + # МПЎель Pydantic class User(BaseModel): id: int @@ -47,7 +49,7 @@ class User(BaseModel): joined: date ``` -ПрОклаЎ вОкПрОстаММя цієї ЌПЎелі: +Далі це ЌПжМа вОкПрОстПвуватО так: ```Python my_user: User = User(id=3, name="John Doe", joined="2018-07-19") @@ -65,19 +67,21 @@ my_second_user: User = User(**second_user_data) `**second_user_data` ПзМачає: -ПереЎатО ключі та зМачеММя слПвМОка `second_user_data` як аргуЌеМтО у вОгляЎі "ключ-зМачеММя", еквівалеМтМП `User(id=4, name="Mary", joined="2018-11-30")`. +ПереЎатО ключі та зМачеММя слПвМОка `second_user_data` безпПсереЎМьП як аргуЌеМтО у вОгляЎі «ключ-зМачеММя», еквівалеМтМП: `User(id=4, name="Mary", joined="2018-11-30")` /// -### ПіЎтрОЌка реЎактПрів (IDE) +### ПіЎтрОЌка реЎактПрів (IDE) { #editor-support } -ЀрейЌвПрк спрПєктПваМОй так, щПб бутО легкОЌ і іМтуїтОвМП зрПзуЌілОЌ. Усі рішеММя тестувалОся у різМОх реЎактПрах ще ЎП пПчатку рПзрПбкО, щПб забезпечОтО МайкращОй ЎПсвіЎ прПграЌуваММя. +Увесь фрейЌвПрк спрПєктПваМП так, щПб МОЌ булП легкП та іМтуїтОвМП кПрОстуватОся; усі рішеММя тестувалОся у кількПх реЎактПрах ще ЎП пПчатку рПзрПбкО, щПб забезпечОтО МайкращОй ЎПсвіЎ рПзрПбкО. -За результатаЌО ПпОтуваМь рПзрПбМОків Python ПЎМією з МайпПпулярМішОх фуМкцій є "автПЎПпПвМеММя". +З ПпОтуваМь рПзрПбМОків Python зрПзуЌілП щП ПЎМією з МайужОваМішОх фуМкцій є «автПЎПпПвМеММя». -**FastAPI** пПвМістю піЎтрОЌує автПЎПпПвМеММя у всіх Ќісцях, тПЌу ваЌ ріЎкП ЎПвеЎеться пПвертатОся ЎП ЎПкуЌеМтації. +Увесь фрейЌвПрк **FastAPI** пПбуЎПваМОй так, щПб це забезпечОтО. АвтПЎПпПвМеММя працює всюЎО. -ПрОклаЎ автПЎПпПвМеММя у реЎактПрах: +ВаЌ ріЎкП ЎПвеЎеться пПвертатОся ЎП ЎПкуЌеМтації. + +Ось як ваш реЎактПр ЌПже ваЌ ЎПпПЌПгтО: * у Visual Studio Code: @@ -87,17 +91,25 @@ my_second_user: User = User(**second_user_data) ![editor support](https://fastapi.tiangolo.com/img/pycharm-completion.png) -### КПрПткОй кПЎ -FastAPI Ќає рПзуЌМі МалаштуваММя **за заЌПвчуваММяЌ**, але всі параЌетрО ЌПжМа МалаштПвуватО віЎпПвіЎМП ЎП вашОх пПтреб. ОЎМак за заЌПвчуваММяЌ все "прПстП працює". +ВО ПтрОЌаєте автПЎПпПвМеММя в кПЎі, якОй раМіше ЌПглО вважатО Мавіть МеЌПжлОвОЌ. НапрОклаЎ, Ўля ключа `price` всереЎОМі JSON body (якОй Ќіг бутО вклаЎеМОЌ), щП МаЎхПЎОть із запОту. + +Більше Ме ЎПвеЎеться ввПЎОтО МеправОльМі МазвО ключів, пПстійМП пПвертатОся ЎП ЎПкуЌеМтації абП прПкручуватО вгПру-вМОз, щПб зМайтО, чО вО зрештПю вОкПрОсталО `username` чО `user_name`. + +### КПрПткОй кПЎ { #short } + +FastAPI Ќає рПзуЌМі **МалаштуваММя за заЌПвчуваММяЌ** Ўля всьПгП, з ЌПжлОвістю кПМфігурації всюЎО. Усі параЌетрО ЌПжМа тПчМП МалаштуватО піЎ ваші пПтребО та вОзМачОтО пПтрібМОй ваЌ API. + +Але за заЌПвчуваММяЌ усе **«прПстП працює»**. + +### ВаліЎація { #validation } -### ВаліЎація * ПіЎтрОЌка валіЎації Ўля більшПсті (абП всіх?) **тОпів ЎаМОх Python**, зПкреЌа: * JSON-Пб'єктів (`dict`). - * JSON-спОсків (`list`) з вОзМачеММяЌ тОпів елеЌеМтів. - * РяЎків (`str`) із ЌіМіЌальМПю та ЌаксОЌальМПю ЎПвжОМПю. - * ЧОсел (`int`, `float`) з ПбЌежеММяЌО ЌіМіЌальМОх та ЌаксОЌальМОх зМачеМь тПщП. + * JSON-ЌасОвів (`list`) із вОзМачеММяЌ тОпів елеЌеМтів. + * ППлів-ряЎків (`str`) із вОзМачеММяЌ ЌіМіЌальМПї та ЌаксОЌальМПї ЎПвжОМО. + * ЧОсел (`int`, `float`) з ЌіМіЌальМОЌО та ЌаксОЌальМОЌО зМачеММяЌО тПщП. -* ВаліЎація склаЎМішОх тОпів, такОх як: +* ВаліЎація Ўля більш екзПтОчМОх тОпів, як-Пт: * URL. * Email. * UUID. @@ -105,55 +117,55 @@ FastAPI Ќає рПзуЌМі МалаштуваММя **за заЌПвчува Уся валіЎація вОкПМується через МаЎійМОй та перевіреМОй **Pydantic**. -### Безпека та автеМтОфікація +### Безпека та автеМтОфікація { #security-and-authentication } -**FastAPI** піЎтрОЌує вбуЎПваМу автеМтОфікацію та автПрОзацію, без прОв’язкО ЎП кПМкретМОх баз ЎаМОх чО ЌПЎелей ЎаМОх. +ІМтегрПваМі безпека та автеМтОфікація. Без жПЎМОх кПЌпрПЌісів із базаЌО ЎаМОх чО ЌПЎеляЌО ЎаМОх. -ПіЎтрОЌуються всі схеЌО безпекО OpenAPI, включаючО: +ПіЎтрОЌуються всі схеЌО безпекО, вОзМачеМі в OpenAPI, включМП з: * HTTP Basic. -* **OAuth2** (такПж із піЎтрОЌкПю **JWT-тПкеМів**). ДОв. піЎручМОк: [OAuth2 із JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. +* **OAuth2** (такПж із піЎтрОЌкПю **JWT tokens**). ПерегляМьте піЎручМОк: [OAuth2 із JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. * Ключі API в: * ЗагПлПвках. * ПараЌетрах запОту. * Cookies тПщП. -А такПж усі ЌПжлОвПсті безпекО віЎ Starlette (зПкреЌа **сесійМі cookies**). +А такПж усі ЌПжлОвПсті безпекО віЎ Starlette (зПкреЌа **session cookies**). -Усі вПМО ствПреМі як багатПразПві іМструЌеМтО та кПЌпПМеМтО, які легкП іМтегруються з вашОЌО сОстеЌаЌО, схПвОщаЌО ЎаМОх, реляційМОЌО та NoSQL базаЌО ЎаМОх тПщП. +Усе це зрПблеМП як багатПразПві іМструЌеМтО та кПЌпПМеМтО, які легкП іМтегруються з вашОЌО сОстеЌаЌО, схПвОщаЌО ЎаМОх, реляційМОЌО та NoSQL базаЌО ЎаМОх тПщП. -### ВпрПваЎжеММя залежМПстей +### ВпрПваЎжеММя залежМПстей { #dependency-injection } -**FastAPI** ЌістОть МаЎзвОчайМП прПсту у вОкПрОстаММі, але пПтужМу сОстеЌу впрПваЎжеММя залежМПстей. +FastAPI ЌістОть МаЎзвОчайМП прПсту у вОкПрОстаММі, але МаЎзвОчайМП пПтужМу сОстеЌу Dependency Injection. -* ЗалежМПсті ЌПжуть ЌатО власМі залежМПсті, утвПрюючО ієрархію абП **"граф залежМПстей"**. -* Усі залежМПсті автПЌатОчМП керуються фрейЌвПркПЌ. -* Усі залежМПсті ЌПжуть ПтрОЌуватО ЎаМі з запОтів і рПзшОрюватО **ПбЌежеММя Пперації за шляхПЌ** та автПЌатОчМу ЎПкуЌеМтацію. -* **АвтПЌатОчМа валіЎація** Мавіть Ўля параЌетрів *Пперацій шляху*, вОзМачеМОх у залежМПстях. -* ПіЎтрОЌка склаЎМОх сОстеЌ автеМтОфікації кПрОстувачів, **з'єЎМаМь із базаЌО ЎаМОх** тПщП. -* **ЖПЎМОх ПбЌежеМь** щПЎП вОкПрОстаММя баз ЎаМОх, фрПМтеМЎів тПщП, але вПЎМПчас прПста іМтеграція з усіЌа МОЌО. +* Навіть залежМПсті ЌПжуть ЌатО власМі залежМПсті, утвПрюючО ієрархію абП **«граф» залежМПстей**. +* Усе **автПЌатОчМП ПбрПбляється** фрейЌвПркПЌ. +* Усі залежМПсті ЌПжуть вОЌагатО ЎаМі із запОтів і **рПзшОрюватО ПбЌежеММя Пперації шляху** та автПЌатОчМу ЎПкуЌеМтацію. +* **АвтПЌатОчМа валіЎація** Мавіть Ўля параЌетрів *Пперації шляху*, вОзМачеМОх у залежМПстях. +* ПіЎтрОЌка склаЎМОх сОстеЌ автеМтОфікації кПрОстувачів, **піЎключеМь ЎП баз ЎаМОх** тПщП. +* **ЖПЎМОх кПЌпрПЌісів** із базаЌО ЎаМОх, фрПМтеМЎаЌО тПщП. Але прПста іМтеграція з усіЌа МОЌО. -### НеЌає ПбЌежеМь Ма "плагіМО" +### НеПбЌежеМі «плагіМО» { #unlimited-plug-ins } -АбП іМшОЌО слПваЌО, вПМО Ме пПтрібМі – прПстП іЌпПртуйте та вОкПрОстПвуйте МеПбхіЎМОй кПЎ. +ІМакше кажучО, вПМО Ме пПтрібМі — іЌпПртуйте та вОкПрОстПвуйте кПЎ, якОй ваЌ пПтрібеМ. -БуЎь-яка іМтеграція спрПєктПваМа МастількО прПстП (з вОкПрОстаММяЌ залежМПстей), щП вО ЌПжете ствПрОтО "плагіМ" Ўля свПгП застПсуМку всьПгП у 2 ряЎках кПЎу, вОкПрОстПвуючО ту саЌу структуру та сОМтаксОс, щП й Ўля вашОх *Пперацій шляху*. +БуЎь-яка іМтеграція спрПєктПваМа так, щПб її булП Ўуже прПстП вОкПрОстПвуватО (із залежМПстяЌО), тПж вО ЌПжете ствПрОтО «плагіМ» Ўля свПгП застПсуМку у 2 ряЎках кПЎу, вОкПрОстПвуючО ту саЌу структуру та сОМтаксОс, щП й Ўля вашОх *Пперацій шляху*. -### ПрПтестПваМП +### ПрПтестПваМП { #tested } * 100% пПкрОття тестаЌО. * 100% аМПтПваМа тОпаЌО кПЎПва база. -* ВОкПрОстПвується у рПбПчОх сереЎПвОщах. +* ВОкПрОстПвується в production-застПсуМках. -## МПжлОвПсті Starlette +## МПжлОвПсті Starlette { #starlette-features } **FastAPI** пПвМістю суЌісМОй із (та пПбуЎПваМОй Ма ПсМПві) Starlette. ТПЌу буЎь-якОй ЎПЎаткПвОй кПЎ Starlette, якОй вО Ќаєте, такПж працюватОЌе. -**FastAPI** фактОчМП є піЎкласПЌ **Starlette**. ТПЌу, якщП вО вже зМайПЌі зі Starlette абП вОкПрОстПвуєте йПгП, більшість фуМкціПМальМПсті працюватОЌе так саЌП. +`FastAPI` фактОчМП є піЎкласПЌ `Starlette`. ТПЌу, якщП вО вже зМайПЌі зі Starlette абП вОкПрОстПвуєте йПгП, більшість фуМкціПМальМПсті працюватОЌе так саЌП. -З **FastAPI** вО ПтрОЌуєте всі ЌПжлОвПсті **Starlette** (аЎже FastAPI — це, пП суті, Starlette Ма стерПїЎах): +З **FastAPI** вО ПтрОЌуєте всі ЌПжлОвПсті **Starlette** (аЎже FastAPI — це прПстП Starlette Ма стерПїЎах): -* Разюча прПЎуктОвМість. Ње ПЎОМ із МайшвОЎшОх фрейЌвПрків Ма Python, Ма рівМі з **NodeJS** і **Go**. +* Разюча прПЎуктОвМість. Ње ПЎОМ із МайшвОЎшОх ЎПступМОх Python-фрейЌвПрків, Ма рівМі з **NodeJS** і **Go**. * ПіЎтрОЌка **WebSocket**. * ЀПМПві заЎачі у прПцесі. * ППЎії запуску та завершеММя рПбПтО. @@ -163,27 +175,27 @@ FastAPI Ќає рПзуЌМі МалаштуваММя **за заЌПвчува * 100% пПкрОття тестаЌО. * 100% аМПтПваМа тОпаЌО кПЎПва база. -## МПжлОвПсті Pydantic +## МПжлОвПсті Pydantic { #pydantic-features } **FastAPI** пПвМістю суЌісМОй із (та пПбуЎПваМОй Ма ПсМПві) Pydantic. ТПЌу буЎь-якОй ЎПЎаткПвОй кПЎ Pydantic, якОй вО Ќаєте, такПж працюватОЌе. -ВключаючО зПвМішМі бібліПтекО, пПбуЎПваМі такПж Ма Pydantic, такі як ORM, ODM Ўля баз ЎаМОх. +ВключМП із зПвМішМіЌО бібліПтекаЌО, які такПж базуються Ма Pydantic, як-Пт ORM-О, ODM-О Ўля баз ЎаМОх. -Ње такПж ПзМачає, щП в багатьПх вОпаЎках вО ЌПжете переЎатО тПй саЌОй Пб'єкт, якОй ПтрОЌуєте з запОту, **безпПсереЎМьП в базу ЎаМОх**, ПскількО все автПЌатОчМП перевіряється. +Ње такПж ПзМачає, щП в багатьПх вОпаЎках вО ЌПжете переЎатО тПй саЌОй Пб'єкт, якОй ПтрОЌуєте із запОту, **безпПсереЎМьП в базу ЎаМОх**, ПскількО все автПЌатОчМП перевіряється. -Те ж саЌе віЎбувається й у звПрПтМПЌу МапряЌку — у багатьПх вОпаЎках вО ЌПжете прПстП переЎатО Пб'єкт, якОй ПтрОЌуєте з базО ЎаМОх, **безпПсереЎМьП клієМту**. +Те саЌе застПсПвується й у звПрПтМПЌу МапряЌку — у багатьПх вОпаЎках вО ЌПжете прПстП переЎатО Пб'єкт, якОй ПтрОЌуєте з базО ЎаМОх, **безпПсереЎМьП клієМту**. З **FastAPI** вО ПтрОЌуєте всі ЌПжлОвПсті **Pydantic** (аЎже FastAPI базується Ма Pydantic Ўля ПбрПбкО всіх ЎаМОх): -* **НіякПї плутаМОМО** : - * Не пПтрібМП вчОтО МПву ЌПву Ўля вОзМачеММя схеЌ. +* **НіякПї плутаМОМО**: + * Не пПтрібМП вчОтО МПву ЌікрПЌПву Ўля вОзМачеММя схеЌ. * ЯкщП вО зМаєте тОпО Python, вО зМаєте, як вОкПрОстПвуватО Pydantic. -* ЛегкП працює з вашОЌ **IDE/ліМтерПЌ/ЌПзкПЌ**: - * ОскількО структурО ЎаМОх Pydantic є прПстП екзеЌпляраЌО класів, які вО вОзМачаєте; автПЎПпПвМеММя, ліМтОМг, mypy і ваша іМтуїція пПвОММі ЎПбре працюватО з вашОЌО перевіреМОЌО ЎаМОЌО. -* ВаліЎація **склаЎМОх структур**: - * ВОкПрОстаММя ієрархічМОх ЌПЎелей Pydantic. Python `typing`, `List` і `Dict` тПщП. - * ВаліЎатПрО ЎПзвПляють чіткП і прПстП вОзМачатО, перевірятО й ЎПкуЌеМтуватО склаЎМі схеЌО ЎаМОх у вОгляЎі JSON-схеЌО. - * ВО ЌПжете ЌатО глОбПкП **вклаЎеМі JSON Пб'єктО** та перевірОтО та аМПтуватО їх всі. +* ЛегкП працює з вашОЌ **IDE/linter/ЌПзкПЌ**: + * ОскількО структурО ЎаМОх pydantic є прПстП екзеЌпляраЌО класів, які вО вОзМачаєте; автПЎПпПвМеММя, ліМтОМг, mypy і ваша іМтуїція пПвОММі ЎПбре працюватО з вашОЌО перевіреМОЌО ЎаМОЌО. +* ВаліЎує **склаЎМі структурО**: + * ВОкПрОстаММя ієрархічМОх ЌПЎелей Pydantic, Python `typing`’s `List` і `Dict` тПщП. + * ВаліЎатПрО Ўають зЌПгу склаЎМі схеЌО ЎаМОх чіткП й прПстП вОзМачатО, перевірятО й ЎПкуЌеМтуватО як JSON Schema. + * ВО ЌПжете ЌатО глОбПкП **вклаЎеМі JSON** Пб'єктО, і всі вПМО буЎуть валіЎПваМі та аМПтПваМі. * **РПзшОрюваМість**: - * Pydantic ЎПзвПляє вОзМачатО кПрОстувацькі тОпО ЎаМОх абП рПзшОрюватО валіЎацію ЌетПЎаЌО в ЌПЎелі ЎекПратПрПЌ `validator`. + * Pydantic ЎПзвПляє вОзМачатО кПрОстувацькі тОпО ЎаМОх абП вО ЌПжете рПзшОрОтО валіЎацію ЌетПЎаЌО в ЌПЎелі, пПзМачеМОЌО ЎекПратПрПЌ validator. * 100% пПкрОття тестаЌО. From 07f08fc79a021cbc06d194f0a32f521253c6ed8c Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sun, 1 Feb 2026 09:44:59 +0000 Subject: [PATCH 044/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index eb72d559d0..699b966966 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -19,6 +19,7 @@ hide: ### Translations +* 🌐 Update translations for uk (update outdated, found by fixer tool). PR [#14739](https://github.com/fastapi/fastapi/pull/14739) by [@YuriiMotov](https://github.com/YuriiMotov). * 🌐 Update translations for tr (update-outdated). PR [#14745](https://github.com/fastapi/fastapi/pull/14745) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update `llm-prompt.md` for Korean language. PR [#14763](https://github.com/fastapi/fastapi/pull/14763) by [@seuthootDev](https://github.com/seuthootDev). * 🌐 Update translations for ko (update outdated, found by fixer tool). PR [#14738](https://github.com/fastapi/fastapi/pull/14738) by [@YuriiMotov](https://github.com/YuriiMotov). From 3626d764c13cb12414b2b1a254af075f2799c716 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Mon, 2 Feb 2026 02:24:23 -0800 Subject: [PATCH 045/108] =?UTF-8?q?=F0=9F=91=A5=20Update=20FastAPI=20Peopl?= =?UTF-8?q?e=20-=20Contributors=20and=20Translators=20(#14796)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: github-actions[bot] --- docs/en/data/contributors.yml | 18 ++-- docs/en/data/translation_reviewers.yml | 114 ++++++++++++++----------- docs/en/data/translators.yml | 43 +++++----- 3 files changed, 95 insertions(+), 80 deletions(-) diff --git a/docs/en/data/contributors.yml b/docs/en/data/contributors.yml index 0c144cd4ce..41115ccbd4 100644 --- a/docs/en/data/contributors.yml +++ b/docs/en/data/contributors.yml @@ -1,17 +1,17 @@ tiangolo: login: tiangolo - count: 857 + count: 871 avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=cb5d06e73a9e1998141b1641aa88e443c6717651&v=4 url: https://github.com/tiangolo dependabot: login: dependabot - count: 130 + count: 133 avatarUrl: https://avatars.githubusercontent.com/in/29110?v=4 url: https://github.com/apps/dependabot alejsdev: login: alejsdev count: 53 - avatarUrl: https://avatars.githubusercontent.com/u/90076947?u=85ceac49fb87138aebe8d663912e359447329090&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/90076947?u=0facffe3abf87f57a1f05fa773d1119cc5c2f6a5&v=4 url: https://github.com/alejsdev pre-commit-ci: login: pre-commit-ci @@ -20,8 +20,8 @@ pre-commit-ci: url: https://github.com/apps/pre-commit-ci YuriiMotov: login: YuriiMotov - count: 36 - avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=b9b13d598dddfab529a52d264df80a900bfe7060&v=4 + count: 38 + avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=bc48be95c429989224786106b027f3c5e40cc354&v=4 url: https://github.com/YuriiMotov github-actions: login: github-actions @@ -40,7 +40,7 @@ dmontagu: url: https://github.com/dmontagu svlandeg: login: svlandeg - count: 16 + count: 17 avatarUrl: https://avatars.githubusercontent.com/u/8796347?u=556c97650c27021911b0b9447ec55e75987b0e8a&v=4 url: https://github.com/svlandeg nilslindemann: @@ -126,7 +126,7 @@ hitrust: ShahriyarR: login: ShahriyarR count: 4 - avatarUrl: https://avatars.githubusercontent.com/u/3852029?u=631b2ae59360ab380c524b32bc3d245aff1165af&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/3852029?u=2dc6402d9053ee53f7afc407089cbab21c68f21d&v=4 url: https://github.com/ShahriyarR adriangb: login: adriangb @@ -266,7 +266,7 @@ Nimitha-jagadeesha: lucaromagnoli: login: lucaromagnoli count: 3 - avatarUrl: https://avatars.githubusercontent.com/u/38782977?u=15df02e806a2293af40ac619fba11dbe3c0c4fd4&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/38782977?u=a09a2e916625fa035f9dfa25ebc58e07aac8ec36&v=4 url: https://github.com/lucaromagnoli salmantec: login: salmantec @@ -521,7 +521,7 @@ s111d: estebanx64: login: estebanx64 count: 2 - avatarUrl: https://avatars.githubusercontent.com/u/10840422?u=1900887aeed268699e5ea6f3fb7db614f7b77cd3&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/10840422?u=812422ae5d6a4bc5ff331c901fc54f9ab3cecf5c&v=4 url: https://github.com/estebanx64 ndimares: login: ndimares diff --git a/docs/en/data/translation_reviewers.yml b/docs/en/data/translation_reviewers.yml index 62db8e805d..3d321818fc 100644 --- a/docs/en/data/translation_reviewers.yml +++ b/docs/en/data/translation_reviewers.yml @@ -10,12 +10,12 @@ Xewus: url: https://github.com/Xewus sodaMelon: login: sodaMelon - count: 127 + count: 128 avatarUrl: https://avatars.githubusercontent.com/u/66295123?u=be939db90f1119efee9e6110cc05066ff1f40f00&v=4 url: https://github.com/sodaMelon ceb10n: login: ceb10n - count: 117 + count: 119 avatarUrl: https://avatars.githubusercontent.com/u/235213?u=edcce471814a1eba9f0cdaa4cd0de18921a940a6&v=4 url: https://github.com/ceb10n tokusumi: @@ -25,7 +25,7 @@ tokusumi: url: https://github.com/tokusumi hard-coders: login: hard-coders - count: 96 + count: 102 avatarUrl: https://avatars.githubusercontent.com/u/9651103?u=78d12d1acdf853c817700145e73de7fd9e5d068b&v=4 url: https://github.com/hard-coders hasansezertasan: @@ -50,7 +50,7 @@ AlertRED: url: https://github.com/AlertRED tiangolo: login: tiangolo - count: 73 + count: 78 avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=cb5d06e73a9e1998141b1641aa88e443c6717651&v=4 url: https://github.com/tiangolo Alexandrhub: @@ -58,26 +58,31 @@ Alexandrhub: count: 68 avatarUrl: https://avatars.githubusercontent.com/u/119126536?u=9fc0d48f3307817bafecc5861eb2168401a6cb04&v=4 url: https://github.com/Alexandrhub +cassiobotaro: + login: cassiobotaro + count: 64 + avatarUrl: https://avatars.githubusercontent.com/u/3127847?u=a08022b191ddbd0a6159b2981d9d878b6d5bb71f&v=4 + url: https://github.com/cassiobotaro waynerv: login: waynerv count: 63 avatarUrl: https://avatars.githubusercontent.com/u/39515546?u=ec35139777597cdbbbddda29bf8b9d4396b429a9&v=4 url: https://github.com/waynerv -cassiobotaro: - login: cassiobotaro - count: 62 - avatarUrl: https://avatars.githubusercontent.com/u/3127847?u=a08022b191ddbd0a6159b2981d9d878b6d5bb71f&v=4 - url: https://github.com/cassiobotaro +nilslindemann: + login: nilslindemann + count: 61 + avatarUrl: https://avatars.githubusercontent.com/u/6892179?u=1dca6a22195d6cd1ab20737c0e19a4c55d639472&v=4 + url: https://github.com/nilslindemann mattwang44: login: mattwang44 count: 61 avatarUrl: https://avatars.githubusercontent.com/u/24987826?u=58e37fb3927b9124b458945ac4c97aa0f1062d85&v=4 url: https://github.com/mattwang44 -nilslindemann: - login: nilslindemann - count: 59 - avatarUrl: https://avatars.githubusercontent.com/u/6892179?u=1dca6a22195d6cd1ab20737c0e19a4c55d639472&v=4 - url: https://github.com/nilslindemann +YuriiMotov: + login: YuriiMotov + count: 56 + avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=bc48be95c429989224786106b027f3c5e40cc354&v=4 + url: https://github.com/YuriiMotov Laineyzhang55: login: Laineyzhang55 count: 48 @@ -88,26 +93,21 @@ Kludex: count: 47 avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=df8a3f06ba8f55ae1967a3e2d5ed882903a4e330&v=4 url: https://github.com/Kludex -YuriiMotov: - login: YuriiMotov - count: 46 - avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=b9b13d598dddfab529a52d264df80a900bfe7060&v=4 - url: https://github.com/YuriiMotov komtaki: login: komtaki count: 45 avatarUrl: https://avatars.githubusercontent.com/u/39375566?u=260ad6b1a4b34c07dbfa728da5e586f16f6d1824&v=4 url: https://github.com/komtaki +svlandeg: + login: svlandeg + count: 43 + avatarUrl: https://avatars.githubusercontent.com/u/8796347?u=556c97650c27021911b0b9447ec55e75987b0e8a&v=4 + url: https://github.com/svlandeg rostik1410: login: rostik1410 count: 42 avatarUrl: https://avatars.githubusercontent.com/u/11443899?u=e26a635c2ba220467b308a326a579b8ccf4a8701&v=4 url: https://github.com/rostik1410 -svlandeg: - login: svlandeg - count: 42 - avatarUrl: https://avatars.githubusercontent.com/u/8796347?u=556c97650c27021911b0b9447ec55e75987b0e8a&v=4 - url: https://github.com/svlandeg alperiox: login: alperiox count: 42 @@ -136,7 +136,7 @@ JavierSanchezCastro: alejsdev: login: alejsdev count: 37 - avatarUrl: https://avatars.githubusercontent.com/u/90076947?u=85ceac49fb87138aebe8d663912e359447329090&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/90076947?u=0facffe3abf87f57a1f05fa773d1119cc5c2f6a5&v=4 url: https://github.com/alejsdev mezgoodle: login: mezgoodle @@ -383,6 +383,11 @@ Joao-Pedro-P-Holanda: count: 16 avatarUrl: https://avatars.githubusercontent.com/u/110267046?u=331bd016326dac4cf3df4848f6db2dbbf8b5f978&v=4 url: https://github.com/Joao-Pedro-P-Holanda +maru0123-2004: + login: maru0123-2004 + count: 16 + avatarUrl: https://avatars.githubusercontent.com/u/43961566?u=16ed8603a4d6a4665cb6c53a7aece6f31379b769&v=4 + url: https://github.com/maru0123-2004 JaeHyuckSa: login: JaeHyuckSa count: 16 @@ -418,11 +423,6 @@ mattkoehne: count: 14 avatarUrl: https://avatars.githubusercontent.com/u/80362153?v=4 url: https://github.com/mattkoehne -maru0123-2004: - login: maru0123-2004 - count: 14 - avatarUrl: https://avatars.githubusercontent.com/u/43961566?u=16ed8603a4d6a4665cb6c53a7aece6f31379b769&v=4 - url: https://github.com/maru0123-2004 jovicon: login: jovicon count: 13 @@ -458,6 +458,11 @@ wesinalves: count: 13 avatarUrl: https://avatars.githubusercontent.com/u/13563128?u=9eb17ed50645dd684bfec47e75dba4e9772ec9c1&v=4 url: https://github.com/wesinalves +andersonrocha0: + login: andersonrocha0 + count: 13 + avatarUrl: https://avatars.githubusercontent.com/u/22346169?u=93a1359c8c5461d894802c0cc65bcd09217e7a02&v=4 + url: https://github.com/andersonrocha0 NastasiaSaby: login: NastasiaSaby count: 12 @@ -471,7 +476,7 @@ oandersonmagalhaes: mkdir700: login: mkdir700 count: 12 - avatarUrl: https://avatars.githubusercontent.com/u/56359329?u=3d6ea8714f5000829b60dcf7b13a75b1e73aaf47&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/56359329?u=818e5f4b4dcc1a6ffb3e5aaa08fd827e5a726dfd&v=4 url: https://github.com/mkdir700 batlopes: login: batlopes @@ -493,11 +498,6 @@ KaniKim: count: 12 avatarUrl: https://avatars.githubusercontent.com/u/19832624?u=296dbdd490e0eb96e3d45a2608c065603b17dc31&v=4 url: https://github.com/KaniKim -andersonrocha0: - login: andersonrocha0 - count: 12 - avatarUrl: https://avatars.githubusercontent.com/u/22346169?u=93a1359c8c5461d894802c0cc65bcd09217e7a02&v=4 - url: https://github.com/andersonrocha0 gitgernit: login: gitgernit count: 12 @@ -558,6 +558,11 @@ Zhongheng-Cheng: count: 11 avatarUrl: https://avatars.githubusercontent.com/u/95612344?u=a0f7730a3cc7486827965e01a119ad610bda4b0a&v=4 url: https://github.com/Zhongheng-Cheng +Pyth3rEx: + login: Pyth3rEx + count: 11 + avatarUrl: https://avatars.githubusercontent.com/u/26427764?u=087724f74d813c95925d51e354554bd4b6d6bb60&v=4 + url: https://github.com/Pyth3rEx mariacamilagl: login: mariacamilagl count: 10 @@ -611,7 +616,7 @@ socket-socket: nick-cjyx9: login: nick-cjyx9 count: 10 - avatarUrl: https://avatars.githubusercontent.com/u/119087246?u=7227a2de948c68fb8396d5beff1ee5b0e057c42e&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/119087246?u=3d51dcbd79222ecb6538642f31dc7c8bb708d191&v=4 url: https://github.com/nick-cjyx9 marcelomarkus: login: marcelomarkus @@ -683,11 +688,6 @@ Yarous: count: 9 avatarUrl: https://avatars.githubusercontent.com/u/61277193?u=5b462347458a373b2d599c6f416d2b75eddbffad&v=4 url: https://github.com/Yarous -Pyth3rEx: - login: Pyth3rEx - count: 9 - avatarUrl: https://avatars.githubusercontent.com/u/26427764?u=087724f74d813c95925d51e354554bd4b6d6bb60&v=4 - url: https://github.com/Pyth3rEx dimaqq: login: dimaqq count: 8 @@ -736,7 +736,7 @@ minaton-ru: sungchan1: login: sungchan1 count: 8 - avatarUrl: https://avatars.githubusercontent.com/u/28076127?u=a816d86ef3e60450a7225f128caf9a394c9320f9&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/28076127?u=fadbf24840186aca639d344bb3e0ecf7ff3441cf&v=4 url: https://github.com/sungchan1 Serrones: login: Serrones @@ -761,7 +761,7 @@ anthonycepeda: fabioueno: login: fabioueno count: 7 - avatarUrl: https://avatars.githubusercontent.com/u/14273852?u=edd700982b16317ac6ebfd24c47bc0029b21d360&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/14273852?u=a3d546449cdc96621c32bcc26cf74be6e4390209&v=4 url: https://github.com/fabioueno cfraboulet: login: cfraboulet @@ -793,6 +793,11 @@ Zerohertz: count: 7 avatarUrl: https://avatars.githubusercontent.com/u/42334717?u=5ebf4d33e73b1ad373154f6cdee44f7cab4d05ba&v=4 url: https://github.com/Zerohertz +EdmilsonRodrigues: + login: EdmilsonRodrigues + count: 7 + avatarUrl: https://avatars.githubusercontent.com/u/62777025?u=217d6f3cd6cc750bb8818a3af7726c8d74eb7c2d&v=4 + url: https://github.com/EdmilsonRodrigues deniscapeto: login: deniscapeto count: 6 @@ -1028,11 +1033,6 @@ devluisrodrigues: count: 5 avatarUrl: https://avatars.githubusercontent.com/u/21125286?v=4 url: https://github.com/11kkw -EdmilsonRodrigues: - login: EdmilsonRodrigues - count: 5 - avatarUrl: https://avatars.githubusercontent.com/u/62777025?u=217d6f3cd6cc750bb8818a3af7726c8d74eb7c2d&v=4 - url: https://github.com/EdmilsonRodrigues lpdswing: login: lpdswing count: 4 @@ -1178,6 +1178,11 @@ SBillion: count: 4 avatarUrl: https://avatars.githubusercontent.com/u/1070649?u=3ab493dfc88b39da0eb1600e3b8e7df1c90a5dee&v=4 url: https://github.com/SBillion +seuthootDev: + login: seuthootDev + count: 4 + avatarUrl: https://avatars.githubusercontent.com/u/175179350?u=7c2cbc48ab43b52e0c86592111d92e013d72ea4d&v=4 + url: https://github.com/seuthootDev tyronedamasceno: login: tyronedamasceno count: 3 @@ -1266,7 +1271,7 @@ rafsaf: frnsimoes: login: frnsimoes count: 3 - avatarUrl: https://avatars.githubusercontent.com/u/66239468?u=fd8d408946633acc4bea057c207e6c0833871527&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/66239468?u=cba345870d8d6b25dd6d56ee18f7120581e3c573&v=4 url: https://github.com/frnsimoes lieryan: login: lieryan @@ -1593,6 +1598,11 @@ ayr-ton: count: 2 avatarUrl: https://avatars.githubusercontent.com/u/1090517?u=5cf70a0e0f0dbf084e074e494aa94d7c91a46ba6&v=4 url: https://github.com/ayr-ton +Kadermiyanyedi: + login: Kadermiyanyedi + count: 2 + avatarUrl: https://avatars.githubusercontent.com/u/48386782?u=e34f31bf50a8ed8d37fbfa4f301b0c190b1b4b86&v=4 + url: https://github.com/Kadermiyanyedi raphaelauv: login: raphaelauv count: 2 @@ -1831,7 +1841,7 @@ EgorOnishchuk: iamantonreznik: login: iamantonreznik count: 2 - avatarUrl: https://avatars.githubusercontent.com/u/112612414?u=bf6de9a1ab17326fe14de0709719fff3826526d0&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/112612414?u=b9ba8d9b4d3940198bc3a4353dfce70c044a39b1&v=4 url: https://github.com/iamantonreznik Azazul123: login: Azazul123 @@ -1851,7 +1861,7 @@ NavesSapnis: isgin01: login: isgin01 count: 2 - avatarUrl: https://avatars.githubusercontent.com/u/157279130?u=ddffde10876b50f35dc90d1337f507a630530a6a&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/157279130?u=16d6466476cf7dbc55a4cd575b6ea920ebdd81e1&v=4 url: https://github.com/isgin01 syedasamina56: login: syedasamina56 diff --git a/docs/en/data/translators.yml b/docs/en/data/translators.yml index 940b128da2..dd5900a417 100644 --- a/docs/en/data/translators.yml +++ b/docs/en/data/translators.yml @@ -8,9 +8,14 @@ jaystone776: count: 46 avatarUrl: https://avatars.githubusercontent.com/u/11191137?u=299205a95e9b6817a43144a48b643346a5aac5cc&v=4 url: https://github.com/jaystone776 +tiangolo: + login: tiangolo + count: 31 + avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=cb5d06e73a9e1998141b1641aa88e443c6717651&v=4 + url: https://github.com/tiangolo ceb10n: login: ceb10n - count: 29 + count: 30 avatarUrl: https://avatars.githubusercontent.com/u/235213?u=edcce471814a1eba9f0cdaa4cd0de18921a940a6&v=4 url: https://github.com/ceb10n valentinDruzhinin: @@ -28,11 +33,6 @@ SwftAlpc: count: 23 avatarUrl: https://avatars.githubusercontent.com/u/52768429?u=6a3aa15277406520ad37f6236e89466ed44bc5b8&v=4 url: https://github.com/SwftAlpc -tiangolo: - login: tiangolo - count: 22 - avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=cb5d06e73a9e1998141b1641aa88e443c6717651&v=4 - url: https://github.com/tiangolo hasansezertasan: login: hasansezertasan count: 22 @@ -43,16 +43,16 @@ waynerv: count: 20 avatarUrl: https://avatars.githubusercontent.com/u/39515546?u=ec35139777597cdbbbddda29bf8b9d4396b429a9&v=4 url: https://github.com/waynerv +hard-coders: + login: hard-coders + count: 16 + avatarUrl: https://avatars.githubusercontent.com/u/9651103?u=78d12d1acdf853c817700145e73de7fd9e5d068b&v=4 + url: https://github.com/hard-coders AlertRED: login: AlertRED count: 16 avatarUrl: https://avatars.githubusercontent.com/u/15695000?u=f5a4944c6df443030409c88da7d7fa0b7ead985c&v=4 url: https://github.com/AlertRED -hard-coders: - login: hard-coders - count: 15 - avatarUrl: https://avatars.githubusercontent.com/u/9651103?u=78d12d1acdf853c817700145e73de7fd9e5d068b&v=4 - url: https://github.com/hard-coders Joao-Pedro-P-Holanda: login: Joao-Pedro-P-Holanda count: 14 @@ -108,6 +108,11 @@ pablocm83: count: 8 avatarUrl: https://avatars.githubusercontent.com/u/28315068?u=3310fbb05bb8bfc50d2c48b6cb64ac9ee4a14549&v=4 url: https://github.com/pablocm83 +YuriiMotov: + login: YuriiMotov + count: 8 + avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=bc48be95c429989224786106b027f3c5e40cc354&v=4 + url: https://github.com/YuriiMotov ptt3199: login: ptt3199 count: 7 @@ -133,11 +138,6 @@ Alexandrhub: count: 6 avatarUrl: https://avatars.githubusercontent.com/u/119126536?u=9fc0d48f3307817bafecc5861eb2168401a6cb04&v=4 url: https://github.com/Alexandrhub -YuriiMotov: - login: YuriiMotov - count: 6 - avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=b9b13d598dddfab529a52d264df80a900bfe7060&v=4 - url: https://github.com/YuriiMotov Serrones: login: Serrones count: 5 @@ -291,7 +291,7 @@ hsuanchi: alejsdev: login: alejsdev count: 3 - avatarUrl: https://avatars.githubusercontent.com/u/90076947?u=85ceac49fb87138aebe8d663912e359447329090&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/90076947?u=0facffe3abf87f57a1f05fa773d1119cc5c2f6a5&v=4 url: https://github.com/alejsdev riroan: login: riroan @@ -361,7 +361,7 @@ Rishat-F: ruzia: login: ruzia count: 3 - avatarUrl: https://avatars.githubusercontent.com/u/24503?v=4 + avatarUrl: https://avatars.githubusercontent.com/u/24503?u=abce66d26c9611818720f11e6ae6773a6e0928f8&v=4 url: https://github.com/ruzia izaguerreiro: login: izaguerreiro @@ -413,6 +413,11 @@ ayr-ton: count: 2 avatarUrl: https://avatars.githubusercontent.com/u/1090517?u=5cf70a0e0f0dbf084e074e494aa94d7c91a46ba6&v=4 url: https://github.com/ayr-ton +Kadermiyanyedi: + login: Kadermiyanyedi + count: 2 + avatarUrl: https://avatars.githubusercontent.com/u/48386782?u=e34f31bf50a8ed8d37fbfa4f301b0c190b1b4b86&v=4 + url: https://github.com/Kadermiyanyedi KdHyeon0661: login: KdHyeon0661 count: 2 @@ -461,7 +466,7 @@ ArtemKhymenko: hasnatsajid: login: hasnatsajid count: 2 - avatarUrl: https://avatars.githubusercontent.com/u/86589885?u=6668823c3b029bfecf10a8918ed3af1aafb8b15e&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/86589885?v=4 url: https://github.com/hasnatsajid alperiox: login: alperiox From 779f7ddc37e1e03e199cf5b243e4d5d3c5f7c4e8 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 2 Feb 2026 10:24:48 +0000 Subject: [PATCH 046/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 699b966966..0fe3eebf97 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -41,6 +41,7 @@ hide: ### Internal +* 👥 Update FastAPI People - Contributors and Translators. PR [#14796](https://github.com/fastapi/fastapi/pull/14796) by [@tiangolo](https://github.com/tiangolo). * 🔧 Ensure that an edit to `uv.lock` gets the `internal` label. PR [#14759](https://github.com/fastapi/fastapi/pull/14759) by [@svlandeg](https://github.com/svlandeg). * 🔧 Update sponsors: remove Requestly. PR [#14735](https://github.com/fastapi/fastapi/pull/14735) by [@tiangolo](https://github.com/tiangolo). * 🔧 Update sponsors, LambdaTest changes to TestMu AI. PR [#14734](https://github.com/fastapi/fastapi/pull/14734) by [@tiangolo](https://github.com/tiangolo). From 20ff394d7540dd560df1e9252584e3965d59b0c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Mon, 2 Feb 2026 02:26:58 -0800 Subject: [PATCH 047/108] =?UTF-8?q?=F0=9F=91=A5=20Update=20FastAPI=20GitHu?= =?UTF-8?q?b=20topic=20repositories=20(#14803)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: github-actions[bot] --- docs/en/data/topic_repos.yml | 336 +++++++++++++++++------------------ 1 file changed, 168 insertions(+), 168 deletions(-) diff --git a/docs/en/data/topic_repos.yml b/docs/en/data/topic_repos.yml index d089c7e5a7..a37cb6dcfd 100644 --- a/docs/en/data/topic_repos.yml +++ b/docs/en/data/topic_repos.yml @@ -1,176 +1,181 @@ - name: full-stack-fastapi-template html_url: https://github.com/fastapi/full-stack-fastapi-template - stars: 40334 + stars: 41312 owner_login: fastapi owner_html_url: https://github.com/fastapi - name: Hello-Python html_url: https://github.com/mouredev/Hello-Python - stars: 33628 + stars: 34206 owner_login: mouredev owner_html_url: https://github.com/mouredev - name: serve html_url: https://github.com/jina-ai/serve - stars: 21817 + stars: 21832 owner_login: jina-ai owner_html_url: https://github.com/jina-ai - name: HivisionIDPhotos html_url: https://github.com/Zeyi-Lin/HivisionIDPhotos - stars: 20409 + stars: 20661 owner_login: Zeyi-Lin owner_html_url: https://github.com/Zeyi-Lin - name: sqlmodel html_url: https://github.com/fastapi/sqlmodel - stars: 17415 + stars: 17567 owner_login: fastapi owner_html_url: https://github.com/fastapi - name: fastapi-best-practices html_url: https://github.com/zhanymkanov/fastapi-best-practices - stars: 15776 + stars: 16291 owner_login: zhanymkanov owner_html_url: https://github.com/zhanymkanov - name: Douyin_TikTok_Download_API html_url: https://github.com/Evil0ctal/Douyin_TikTok_Download_API - stars: 15588 + stars: 16132 owner_login: Evil0ctal owner_html_url: https://github.com/Evil0ctal -- name: machine-learning-zoomcamp - html_url: https://github.com/DataTalksClub/machine-learning-zoomcamp - stars: 12447 - owner_login: DataTalksClub - owner_html_url: https://github.com/DataTalksClub - name: SurfSense html_url: https://github.com/MODSetter/SurfSense - stars: 12128 + stars: 12723 owner_login: MODSetter owner_html_url: https://github.com/MODSetter +- name: machine-learning-zoomcamp + html_url: https://github.com/DataTalksClub/machine-learning-zoomcamp + stars: 12575 + owner_login: DataTalksClub + owner_html_url: https://github.com/DataTalksClub - name: fastapi_mcp html_url: https://github.com/tadata-org/fastapi_mcp - stars: 11326 + stars: 11478 owner_login: tadata-org owner_html_url: https://github.com/tadata-org - name: awesome-fastapi html_url: https://github.com/mjhea0/awesome-fastapi - stars: 10901 + stars: 11018 owner_login: mjhea0 owner_html_url: https://github.com/mjhea0 - name: XHS-Downloader html_url: https://github.com/JoeanAmier/XHS-Downloader - stars: 9584 + stars: 9938 owner_login: JoeanAmier owner_html_url: https://github.com/JoeanAmier - name: polar html_url: https://github.com/polarsource/polar - stars: 8951 + stars: 9348 owner_login: polarsource owner_html_url: https://github.com/polarsource - name: FastUI html_url: https://github.com/pydantic/FastUI - stars: 8934 + stars: 8949 owner_login: pydantic owner_html_url: https://github.com/pydantic - name: FileCodeBox html_url: https://github.com/vastsa/FileCodeBox - stars: 7934 + stars: 8060 owner_login: vastsa owner_html_url: https://github.com/vastsa - name: nonebot2 html_url: https://github.com/nonebot/nonebot2 - stars: 7248 + stars: 7311 owner_login: nonebot owner_html_url: https://github.com/nonebot - name: hatchet html_url: https://github.com/hatchet-dev/hatchet - stars: 6392 + stars: 6479 owner_login: hatchet-dev owner_html_url: https://github.com/hatchet-dev - name: fastapi-users html_url: https://github.com/fastapi-users/fastapi-users - stars: 5899 + stars: 5970 owner_login: fastapi-users owner_html_url: https://github.com/fastapi-users - name: serge html_url: https://github.com/serge-chat/serge - stars: 5754 + stars: 5751 owner_login: serge-chat owner_html_url: https://github.com/serge-chat - name: strawberry html_url: https://github.com/strawberry-graphql/strawberry - stars: 4577 + stars: 4598 owner_login: strawberry-graphql owner_html_url: https://github.com/strawberry-graphql +- name: devpush + html_url: https://github.com/hunvreus/devpush + stars: 4407 + owner_login: hunvreus + owner_html_url: https://github.com/hunvreus +- name: Kokoro-FastAPI + html_url: https://github.com/remsky/Kokoro-FastAPI + stars: 4359 + owner_login: remsky + owner_html_url: https://github.com/remsky - name: poem html_url: https://github.com/poem-web/poem - stars: 4303 + stars: 4337 owner_login: poem-web owner_html_url: https://github.com/poem-web - name: chatgpt-web-share html_url: https://github.com/chatpire/chatgpt-web-share - stars: 4287 + stars: 4279 owner_login: chatpire owner_html_url: https://github.com/chatpire - name: dynaconf html_url: https://github.com/dynaconf/dynaconf - stars: 4221 + stars: 4244 owner_login: dynaconf owner_html_url: https://github.com/dynaconf -- name: Kokoro-FastAPI - html_url: https://github.com/remsky/Kokoro-FastAPI - stars: 4181 - owner_login: remsky - owner_html_url: https://github.com/remsky +- name: Yuxi-Know + html_url: https://github.com/xerrors/Yuxi-Know + stars: 4154 + owner_login: xerrors + owner_html_url: https://github.com/xerrors - name: atrilabs-engine html_url: https://github.com/Atri-Labs/atrilabs-engine - stars: 4090 + stars: 4086 owner_login: Atri-Labs owner_html_url: https://github.com/Atri-Labs -- name: devpush - html_url: https://github.com/hunvreus/devpush - stars: 4037 - owner_login: hunvreus - owner_html_url: https://github.com/hunvreus - name: logfire html_url: https://github.com/pydantic/logfire - stars: 3896 + stars: 3975 owner_login: pydantic owner_html_url: https://github.com/pydantic - name: LitServe html_url: https://github.com/Lightning-AI/LitServe - stars: 3756 + stars: 3797 owner_login: Lightning-AI owner_html_url: https://github.com/Lightning-AI - name: huma html_url: https://github.com/danielgtaylor/huma - stars: 3702 + stars: 3785 owner_login: danielgtaylor owner_html_url: https://github.com/danielgtaylor -- name: Yuxi-Know - html_url: https://github.com/xerrors/Yuxi-Know - stars: 3680 - owner_login: xerrors - owner_html_url: https://github.com/xerrors - name: datamodel-code-generator html_url: https://github.com/koxudaxi/datamodel-code-generator - stars: 3675 + stars: 3731 owner_login: koxudaxi owner_html_url: https://github.com/koxudaxi - name: fastapi-admin html_url: https://github.com/fastapi-admin/fastapi-admin - stars: 3659 + stars: 3697 owner_login: fastapi-admin owner_html_url: https://github.com/fastapi-admin - name: farfalle html_url: https://github.com/rashadphz/farfalle - stars: 3497 + stars: 3506 owner_login: rashadphz owner_html_url: https://github.com/rashadphz - name: tracecat html_url: https://github.com/TracecatHQ/tracecat - stars: 3421 + stars: 3458 owner_login: TracecatHQ owner_html_url: https://github.com/TracecatHQ +- name: mcp-context-forge + html_url: https://github.com/IBM/mcp-context-forge + stars: 3216 + owner_login: IBM + owner_html_url: https://github.com/IBM - name: opyrator html_url: https://github.com/ml-tooling/opyrator - stars: 3136 + stars: 3134 owner_login: ml-tooling owner_html_url: https://github.com/ml-tooling - name: docarray @@ -180,316 +185,311 @@ owner_html_url: https://github.com/docarray - name: fastapi-realworld-example-app html_url: https://github.com/nsidnev/fastapi-realworld-example-app - stars: 3051 + stars: 3072 owner_login: nsidnev owner_html_url: https://github.com/nsidnev -- name: mcp-context-forge - html_url: https://github.com/IBM/mcp-context-forge - stars: 3034 - owner_login: IBM - owner_html_url: https://github.com/IBM - name: uvicorn-gunicorn-fastapi-docker html_url: https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker - stars: 2904 + stars: 2908 owner_login: tiangolo owner_html_url: https://github.com/tiangolo - name: FastAPI-template html_url: https://github.com/s3rius/FastAPI-template - stars: 2680 + stars: 2728 owner_login: s3rius owner_html_url: https://github.com/s3rius - name: best-of-web-python html_url: https://github.com/ml-tooling/best-of-web-python - stars: 2662 + stars: 2686 owner_login: ml-tooling owner_html_url: https://github.com/ml-tooling - name: YC-Killer html_url: https://github.com/sahibzada-allahyar/YC-Killer - stars: 2614 + stars: 2648 owner_login: sahibzada-allahyar owner_html_url: https://github.com/sahibzada-allahyar - name: sqladmin html_url: https://github.com/aminalaee/sqladmin - stars: 2587 + stars: 2637 owner_login: aminalaee owner_html_url: https://github.com/aminalaee - name: fastapi-react html_url: https://github.com/Buuntu/fastapi-react - stars: 2566 + stars: 2573 owner_login: Buuntu owner_html_url: https://github.com/Buuntu - name: RasaGPT html_url: https://github.com/paulpierre/RasaGPT - stars: 2456 + stars: 2460 owner_login: paulpierre owner_html_url: https://github.com/paulpierre - name: supabase-py html_url: https://github.com/supabase/supabase-py - stars: 2394 + stars: 2428 owner_login: supabase owner_html_url: https://github.com/supabase +- name: 30-Days-of-Python + html_url: https://github.com/codingforentrepreneurs/30-Days-of-Python + stars: 2347 + owner_login: codingforentrepreneurs + owner_html_url: https://github.com/codingforentrepreneurs - name: nextpy html_url: https://github.com/dot-agent/nextpy - stars: 2338 + stars: 2337 owner_login: dot-agent owner_html_url: https://github.com/dot-agent - name: fastapi-utils html_url: https://github.com/fastapiutils/fastapi-utils - stars: 2289 + stars: 2299 owner_login: fastapiutils owner_html_url: https://github.com/fastapiutils - name: langserve html_url: https://github.com/langchain-ai/langserve - stars: 2234 + stars: 2255 owner_login: langchain-ai owner_html_url: https://github.com/langchain-ai -- name: 30-Days-of-Python - html_url: https://github.com/codingforentrepreneurs/30-Days-of-Python - stars: 2232 - owner_login: codingforentrepreneurs - owner_html_url: https://github.com/codingforentrepreneurs +- name: NoteDiscovery + html_url: https://github.com/gamosoft/NoteDiscovery + stars: 2182 + owner_login: gamosoft + owner_html_url: https://github.com/gamosoft - name: solara html_url: https://github.com/widgetti/solara - stars: 2141 + stars: 2154 owner_login: widgetti owner_html_url: https://github.com/widgetti - name: mangum html_url: https://github.com/Kludex/mangum - stars: 2046 + stars: 2071 owner_login: Kludex owner_html_url: https://github.com/Kludex - name: fastapi_best_architecture html_url: https://github.com/fastapi-practices/fastapi_best_architecture - stars: 1963 + stars: 2036 owner_login: fastapi-practices owner_html_url: https://github.com/fastapi-practices -- name: NoteDiscovery - html_url: https://github.com/gamosoft/NoteDiscovery - stars: 1943 - owner_login: gamosoft - owner_html_url: https://github.com/gamosoft -- name: agentkit - html_url: https://github.com/BCG-X-Official/agentkit - stars: 1936 - owner_login: BCG-X-Official - owner_html_url: https://github.com/BCG-X-Official - name: vue-fastapi-admin html_url: https://github.com/mizhexiaoxiao/vue-fastapi-admin - stars: 1909 + stars: 1983 owner_login: mizhexiaoxiao owner_html_url: https://github.com/mizhexiaoxiao -- name: manage-fastapi - html_url: https://github.com/ycd/manage-fastapi - stars: 1887 - owner_login: ycd - owner_html_url: https://github.com/ycd +- name: agentkit + html_url: https://github.com/BCG-X-Official/agentkit + stars: 1941 + owner_login: BCG-X-Official + owner_html_url: https://github.com/BCG-X-Official +- name: fastapi-langgraph-agent-production-ready-template + html_url: https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template + stars: 1920 + owner_login: wassim249 + owner_html_url: https://github.com/wassim249 - name: openapi-python-client html_url: https://github.com/openapi-generators/openapi-python-client - stars: 1879 + stars: 1900 owner_login: openapi-generators owner_html_url: https://github.com/openapi-generators +- name: manage-fastapi + html_url: https://github.com/ycd/manage-fastapi + stars: 1894 + owner_login: ycd + owner_html_url: https://github.com/ycd - name: slowapi html_url: https://github.com/laurentS/slowapi - stars: 1845 + stars: 1891 owner_login: laurentS owner_html_url: https://github.com/laurentS - name: piccolo html_url: https://github.com/piccolo-orm/piccolo - stars: 1843 + stars: 1854 owner_login: piccolo-orm owner_html_url: https://github.com/piccolo-orm +- name: fastapi-cache + html_url: https://github.com/long2ice/fastapi-cache + stars: 1816 + owner_login: long2ice + owner_html_url: https://github.com/long2ice - name: python-week-2022 html_url: https://github.com/rochacbruno/python-week-2022 stars: 1813 owner_login: rochacbruno owner_html_url: https://github.com/rochacbruno -- name: fastapi-cache - html_url: https://github.com/long2ice/fastapi-cache - stars: 1805 - owner_login: long2ice - owner_html_url: https://github.com/long2ice - name: ormar html_url: https://github.com/collerek/ormar - stars: 1785 + stars: 1797 owner_login: collerek owner_html_url: https://github.com/collerek -- name: fastapi-langgraph-agent-production-ready-template - html_url: https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template - stars: 1780 - owner_login: wassim249 - owner_html_url: https://github.com/wassim249 - name: FastAPI-boilerplate html_url: https://github.com/benavlabs/FastAPI-boilerplate - stars: 1734 + stars: 1792 owner_login: benavlabs owner_html_url: https://github.com/benavlabs - name: termpair html_url: https://github.com/cs01/termpair - stars: 1724 + stars: 1727 owner_login: cs01 owner_html_url: https://github.com/cs01 - name: fastapi-crudrouter html_url: https://github.com/awtkns/fastapi-crudrouter - stars: 1671 + stars: 1677 owner_login: awtkns owner_html_url: https://github.com/awtkns - name: langchain-serve html_url: https://github.com/jina-ai/langchain-serve - stars: 1633 + stars: 1634 owner_login: jina-ai owner_html_url: https://github.com/jina-ai - name: fastapi-pagination html_url: https://github.com/uriyyo/fastapi-pagination - stars: 1588 + stars: 1607 owner_login: uriyyo owner_html_url: https://github.com/uriyyo - name: awesome-fastapi-projects html_url: https://github.com/Kludex/awesome-fastapi-projects - stars: 1583 + stars: 1592 owner_login: Kludex owner_html_url: https://github.com/Kludex -- name: coronavirus-tracker-api - html_url: https://github.com/ExpDev07/coronavirus-tracker-api - stars: 1571 - owner_login: ExpDev07 - owner_html_url: https://github.com/ExpDev07 - name: bracket html_url: https://github.com/evroon/bracket - stars: 1549 + stars: 1580 owner_login: evroon owner_html_url: https://github.com/evroon +- name: coronavirus-tracker-api + html_url: https://github.com/ExpDev07/coronavirus-tracker-api + stars: 1570 + owner_login: ExpDev07 + owner_html_url: https://github.com/ExpDev07 - name: fastapi-amis-admin html_url: https://github.com/amisadmin/fastapi-amis-admin - stars: 1491 + stars: 1512 owner_login: amisadmin owner_html_url: https://github.com/amisadmin -- name: fastapi-boilerplate - html_url: https://github.com/teamhide/fastapi-boilerplate - stars: 1452 - owner_login: teamhide - owner_html_url: https://github.com/teamhide - name: fastcrud html_url: https://github.com/benavlabs/fastcrud - stars: 1452 + stars: 1471 owner_login: benavlabs owner_html_url: https://github.com/benavlabs +- name: fastapi-boilerplate + html_url: https://github.com/teamhide/fastapi-boilerplate + stars: 1461 + owner_login: teamhide + owner_html_url: https://github.com/teamhide - name: awesome-python-resources html_url: https://github.com/DjangoEx/awesome-python-resources - stars: 1430 + stars: 1435 owner_login: DjangoEx owner_html_url: https://github.com/DjangoEx - name: prometheus-fastapi-instrumentator html_url: https://github.com/trallnag/prometheus-fastapi-instrumentator - stars: 1399 + stars: 1417 owner_login: trallnag owner_html_url: https://github.com/trallnag - name: fastapi-code-generator html_url: https://github.com/koxudaxi/fastapi-code-generator - stars: 1371 + stars: 1382 owner_login: koxudaxi owner_html_url: https://github.com/koxudaxi +- name: fastapi-scaff + html_url: https://github.com/atpuxiner/fastapi-scaff + stars: 1367 + owner_login: atpuxiner + owner_html_url: https://github.com/atpuxiner - name: fastapi-tutorial html_url: https://github.com/liaogx/fastapi-tutorial - stars: 1346 + stars: 1360 owner_login: liaogx owner_html_url: https://github.com/liaogx - name: budgetml html_url: https://github.com/ebhy/budgetml - stars: 1345 + stars: 1343 owner_login: ebhy owner_html_url: https://github.com/ebhy -- name: fastapi-scaff - html_url: https://github.com/atpuxiner/fastapi-scaff - stars: 1331 - owner_login: atpuxiner - owner_html_url: https://github.com/atpuxiner - name: bolt-python html_url: https://github.com/slackapi/bolt-python - stars: 1266 + stars: 1276 owner_login: slackapi owner_html_url: https://github.com/slackapi - name: bedrock-chat html_url: https://github.com/aws-samples/bedrock-chat - stars: 1266 + stars: 1268 owner_login: aws-samples owner_html_url: https://github.com/aws-samples - name: fastapi-alembic-sqlmodel-async - html_url: https://github.com/jonra1993/fastapi-alembic-sqlmodel-async - stars: 1260 - owner_login: jonra1993 - owner_html_url: https://github.com/jonra1993 + html_url: https://github.com/vargasjona/fastapi-alembic-sqlmodel-async + stars: 1265 + owner_login: vargasjona + owner_html_url: https://github.com/vargasjona - name: fastapi_production_template html_url: https://github.com/zhanymkanov/fastapi_production_template - stars: 1222 + stars: 1227 owner_login: zhanymkanov owner_html_url: https://github.com/zhanymkanov -- name: langchain-extract - html_url: https://github.com/langchain-ai/langchain-extract - stars: 1179 - owner_login: langchain-ai - owner_html_url: https://github.com/langchain-ai - name: restish html_url: https://github.com/rest-sh/restish - stars: 1152 + stars: 1200 owner_login: rest-sh owner_html_url: https://github.com/rest-sh +- name: langchain-extract + html_url: https://github.com/langchain-ai/langchain-extract + stars: 1183 + owner_login: langchain-ai + owner_html_url: https://github.com/langchain-ai - name: odmantic html_url: https://github.com/art049/odmantic - stars: 1143 + stars: 1162 owner_login: art049 owner_html_url: https://github.com/art049 -- name: authx - html_url: https://github.com/yezz123/authx - stars: 1128 - owner_login: yezz123 - owner_html_url: https://github.com/yezz123 -- name: SAG - html_url: https://github.com/Zleap-AI/SAG - stars: 1104 - owner_login: Zleap-AI - owner_html_url: https://github.com/Zleap-AI - name: aktools html_url: https://github.com/akfamily/aktools - stars: 1072 + stars: 1155 owner_login: akfamily owner_html_url: https://github.com/akfamily - name: RuoYi-Vue3-FastAPI html_url: https://github.com/insistence/RuoYi-Vue3-FastAPI - stars: 1063 + stars: 1155 owner_login: insistence owner_html_url: https://github.com/insistence +- name: authx + html_url: https://github.com/yezz123/authx + stars: 1142 + owner_login: yezz123 + owner_html_url: https://github.com/yezz123 +- name: SAG + html_url: https://github.com/Zleap-AI/SAG + stars: 1110 + owner_login: Zleap-AI + owner_html_url: https://github.com/Zleap-AI - name: flock html_url: https://github.com/Onelevenvy/flock - stars: 1059 + stars: 1069 owner_login: Onelevenvy owner_html_url: https://github.com/Onelevenvy - name: fastapi-observability html_url: https://github.com/blueswen/fastapi-observability - stars: 1046 + stars: 1063 owner_login: blueswen owner_html_url: https://github.com/blueswen - name: enterprise-deep-research html_url: https://github.com/SalesforceAIResearch/enterprise-deep-research - stars: 1019 + stars: 1061 owner_login: SalesforceAIResearch owner_html_url: https://github.com/SalesforceAIResearch - name: titiler html_url: https://github.com/developmentseed/titiler - stars: 1016 + stars: 1039 owner_login: developmentseed owner_html_url: https://github.com/developmentseed - name: every-pdf html_url: https://github.com/DDULDDUCK/every-pdf - stars: 1004 + stars: 1017 owner_login: DDULDDUCK owner_html_url: https://github.com/DDULDDUCK - name: autollm html_url: https://github.com/viddexa/autollm - stars: 1003 + stars: 1005 owner_login: viddexa owner_html_url: https://github.com/viddexa - name: lanarky html_url: https://github.com/ajndkr/lanarky - stars: 996 + stars: 995 owner_login: ajndkr owner_html_url: https://github.com/ajndkr From 6173733200c3498408942a86792871b245dec032 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 2 Feb 2026 10:27:24 +0000 Subject: [PATCH 048/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 0fe3eebf97..8f8edd5f62 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -41,6 +41,7 @@ hide: ### Internal +* 👥 Update FastAPI GitHub topic repositories. PR [#14803](https://github.com/fastapi/fastapi/pull/14803) by [@tiangolo](https://github.com/tiangolo). * 👥 Update FastAPI People - Contributors and Translators. PR [#14796](https://github.com/fastapi/fastapi/pull/14796) by [@tiangolo](https://github.com/tiangolo). * 🔧 Ensure that an edit to `uv.lock` gets the `internal` label. PR [#14759](https://github.com/fastapi/fastapi/pull/14759) by [@svlandeg](https://github.com/svlandeg). * 🔧 Update sponsors: remove Requestly. PR [#14735](https://github.com/fastapi/fastapi/pull/14735) by [@tiangolo](https://github.com/tiangolo). From b833e53ade85dcb330145ac6e95a5b7c74a78fcd Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 2 Feb 2026 15:54:49 +0100 Subject: [PATCH 049/108] =?UTF-8?q?=E2=AC=86=20Bump=20typer=20from=200.16.?= =?UTF-8?q?0=20to=200.21.1=20(#14799)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps [typer](https://github.com/fastapi/typer) from 0.16.0 to 0.21.1. - [Release notes](https://github.com/fastapi/typer/releases) - [Changelog](https://github.com/fastapi/typer/blob/master/docs/release-notes.md) - [Commits](https://github.com/fastapi/typer/compare/0.16.0...0.21.1) --- updated-dependencies: - dependency-name: typer dependency-version: 0.21.1 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Sofie Van Landeghem --- pyproject.toml | 2 +- uv.lock | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index fe9b3a7ea1..b104eed80c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -147,7 +147,7 @@ docs = [ "pillow==11.3.0", "python-slugify==8.0.4", "pyyaml>=5.3.1,<7.0.0", - "typer==0.16.0", + "typer==0.21.1", ] docs-tests = [ "httpx>=0.23.0,<1.0.0", diff --git a/uv.lock b/uv.lock index 9ae2220e0c..5cdf5f7679 100644 --- a/uv.lock +++ b/uv.lock @@ -1230,7 +1230,7 @@ dev = [ { name = "ruff", specifier = "==0.14.3" }, { name = "sqlmodel", specifier = "==0.0.27" }, { name = "strawberry-graphql", specifier = ">=0.200.0,<1.0.0" }, - { name = "typer", specifier = "==0.16.0" }, + { name = "typer", specifier = "==0.21.1" }, { name = "types-orjson", specifier = "==3.6.2" }, { name = "types-ujson", specifier = "==5.10.0.20240515" }, ] @@ -1251,7 +1251,7 @@ docs = [ { name = "python-slugify", specifier = "==8.0.4" }, { name = "pyyaml", specifier = ">=5.3.1,<7.0.0" }, { name = "ruff", specifier = "==0.14.3" }, - { name = "typer", specifier = "==0.16.0" }, + { name = "typer", specifier = "==0.21.1" }, ] docs-tests = [ { name = "httpx", specifier = ">=0.23.0,<1.0.0" }, @@ -4737,7 +4737,7 @@ wheels = [ [[package]] name = "typer" -version = "0.16.0" +version = "0.21.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "click", version = "8.1.8", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.10'" }, @@ -4746,9 +4746,9 @@ dependencies = [ { name = "shellingham" }, { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/c5/8c/7d682431efca5fd290017663ea4588bf6f2c6aad085c7f108c5dbc316e70/typer-0.16.0.tar.gz", hash = "sha256:af377ffaee1dbe37ae9440cb4e8f11686ea5ce4e9bae01b84ae7c63b87f1dd3b", size = 102625, upload-time = "2025-05-26T14:30:31.824Z" } +sdist = { url = "https://files.pythonhosted.org/packages/36/bf/8825b5929afd84d0dabd606c67cd57b8388cb3ec385f7ef19c5cc2202069/typer-0.21.1.tar.gz", hash = "sha256:ea835607cd752343b6b2b7ce676893e5a0324082268b48f27aa058bdb7d2145d", size = 110371, upload-time = "2026-01-06T11:21:10.989Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/76/42/3efaf858001d2c2913de7f354563e3a3a2f0decae3efe98427125a8f441e/typer-0.16.0-py3-none-any.whl", hash = "sha256:1f79bed11d4d02d4310e3c1b7ba594183bcedb0ac73b27a9e5f28f6fb5b98855", size = 46317, upload-time = "2025-05-26T14:30:30.523Z" }, + { url = "https://files.pythonhosted.org/packages/a0/1d/d9257dd49ff2ca23ea5f132edf1281a0c4f9de8a762b9ae399b670a59235/typer-0.21.1-py3-none-any.whl", hash = "sha256:7985e89081c636b88d172c2ee0cfe33c253160994d47bdfdc302defd7d1f1d01", size = 47381, upload-time = "2026-01-06T11:21:09.824Z" }, ] [[package]] From da4083c30fcd1f4e2a4cc4bb5bb286545d124788 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 2 Feb 2026 14:55:12 +0000 Subject: [PATCH 050/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 8f8edd5f62..afe456a3fa 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -41,6 +41,7 @@ hide: ### Internal +* ⬆ Bump typer from 0.16.0 to 0.21.1. PR [#14799](https://github.com/fastapi/fastapi/pull/14799) by [@dependabot[bot]](https://github.com/apps/dependabot). * 👥 Update FastAPI GitHub topic repositories. PR [#14803](https://github.com/fastapi/fastapi/pull/14803) by [@tiangolo](https://github.com/tiangolo). * 👥 Update FastAPI People - Contributors and Translators. PR [#14796](https://github.com/fastapi/fastapi/pull/14796) by [@tiangolo](https://github.com/tiangolo). * 🔧 Ensure that an edit to `uv.lock` gets the `internal` label. PR [#14759](https://github.com/fastapi/fastapi/pull/14759) by [@svlandeg](https://github.com/svlandeg). From a0e34c747340b5b731a363f6b683fa0d0062ca49 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 2 Feb 2026 15:56:33 +0100 Subject: [PATCH 051/108] =?UTF-8?q?=E2=AC=86=20Bump=20gitpython=20from=203?= =?UTF-8?q?.1.45=20to=203.1.46=20(#14800)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps [gitpython](https://github.com/gitpython-developers/GitPython) from 3.1.45 to 3.1.46. - [Release notes](https://github.com/gitpython-developers/GitPython/releases) - [Changelog](https://github.com/gitpython-developers/GitPython/blob/main/CHANGES) - [Commits](https://github.com/gitpython-developers/GitPython/compare/3.1.45...3.1.46) --- updated-dependencies: - dependency-name: gitpython dependency-version: 3.1.46 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Sofie Van Landeghem --- pyproject.toml | 2 +- uv.lock | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index b104eed80c..39a6bd155b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -180,7 +180,7 @@ tests = [ "types-ujson==5.10.0.20240515", ] translations = [ - "gitpython==3.1.45", + "gitpython==3.1.46", "pydantic-ai==0.4.10", "pygithub==2.8.1", ] diff --git a/uv.lock b/uv.lock index 5cdf5f7679..f3a5f8e6d9 100644 --- a/uv.lock +++ b/uv.lock @@ -1203,7 +1203,7 @@ dev = [ { name = "coverage", extras = ["toml"], specifier = ">=6.5.0,<8.0" }, { name = "dirty-equals", specifier = "==0.9.0" }, { name = "flask", specifier = ">=1.1.2,<4.0.0" }, - { name = "gitpython", specifier = "==3.1.45" }, + { name = "gitpython", specifier = "==3.1.46" }, { name = "griffe-typingdoc", specifier = "==0.3.0" }, { name = "griffe-warnings-deprecated", specifier = "==1.1.0" }, { name = "httpx", specifier = ">=0.23.0,<1.0.0" }, @@ -1285,7 +1285,7 @@ tests = [ { name = "types-ujson", specifier = "==5.10.0.20240515" }, ] translations = [ - { name = "gitpython", specifier = "==3.1.45" }, + { name = "gitpython", specifier = "==3.1.46" }, { name = "pydantic-ai", specifier = "==0.4.10" }, { name = "pygithub", specifier = "==2.8.1" }, ] @@ -1632,15 +1632,15 @@ wheels = [ [[package]] name = "gitpython" -version = "3.1.45" +version = "3.1.46" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "gitdb" }, { name = "typing-extensions", marker = "python_full_version < '3.10'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/9a/c8/dd58967d119baab745caec2f9d853297cec1989ec1d63f677d3880632b88/gitpython-3.1.45.tar.gz", hash = "sha256:85b0ee964ceddf211c41b9f27a49086010a190fd8132a24e21f362a4b36a791c", size = 215076, upload-time = "2025-07-24T03:45:54.871Z" } +sdist = { url = "https://files.pythonhosted.org/packages/df/b5/59d16470a1f0dfe8c793f9ef56fd3826093fc52b3bd96d6b9d6c26c7e27b/gitpython-3.1.46.tar.gz", hash = "sha256:400124c7d0ef4ea03f7310ac2fbf7151e09ff97f2a3288d64a440c584a29c37f", size = 215371, upload-time = "2026-01-01T15:37:32.073Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/01/61/d4b89fec821f72385526e1b9d9a3a0385dda4a72b206d28049e2c7cd39b8/gitpython-3.1.45-py3-none-any.whl", hash = "sha256:8908cb2e02fb3b93b7eb0f2827125cb699869470432cc885f019b8fd0fccff77", size = 208168, upload-time = "2025-07-24T03:45:52.517Z" }, + { url = "https://files.pythonhosted.org/packages/6a/09/e21df6aef1e1ffc0c816f0522ddc3f6dcded766c3261813131c78a704470/gitpython-3.1.46-py3-none-any.whl", hash = "sha256:79812ed143d9d25b6d176a10bb511de0f9c67b1fa641d82097b0ab90398a2058", size = 208620, upload-time = "2026-01-01T15:37:30.574Z" }, ] [[package]] From f2487ce88c4ae8f7e64668409770427b245c3a60 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 2 Feb 2026 15:57:22 +0100 Subject: [PATCH 052/108] =?UTF-8?q?=E2=AC=86=20Bump=20mkdocs-macros-plugin?= =?UTF-8?q?=20from=201.4.1=20to=201.5.0=20(#14801)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps [mkdocs-macros-plugin](https://github.com/fralau/mkdocs_macros_plugin) from 1.4.1 to 1.5.0. - [Release notes](https://github.com/fralau/mkdocs_macros_plugin/releases) - [Changelog](https://github.com/fralau/mkdocs-macros-plugin/blob/master/CHANGELOG.md) - [Commits](https://github.com/fralau/mkdocs_macros_plugin/compare/v1.4.1...v1.5.0) --- updated-dependencies: - dependency-name: mkdocs-macros-plugin dependency-version: 1.5.0 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Sofie Van Landeghem --- pyproject.toml | 2 +- uv.lock | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 39a6bd155b..524d527186 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -140,7 +140,7 @@ docs = [ "jieba==0.42.1", "markdown-include-variants==0.0.8", "mdx-include>=1.4.1,<2.0.0", - "mkdocs-macros-plugin==1.4.1", + "mkdocs-macros-plugin==1.5.0", "mkdocs-material==9.7.0", "mkdocs-redirects>=1.2.1,<1.3.0", "mkdocstrings[python]==0.30.1", diff --git a/uv.lock b/uv.lock index f3a5f8e6d9..312181b4e8 100644 --- a/uv.lock +++ b/uv.lock @@ -1211,7 +1211,7 @@ dev = [ { name = "jieba", specifier = "==0.42.1" }, { name = "markdown-include-variants", specifier = "==0.0.8" }, { name = "mdx-include", specifier = ">=1.4.1,<2.0.0" }, - { name = "mkdocs-macros-plugin", specifier = "==1.4.1" }, + { name = "mkdocs-macros-plugin", specifier = "==1.5.0" }, { name = "mkdocs-material", specifier = "==9.7.0" }, { name = "mkdocs-redirects", specifier = ">=1.2.1,<1.3.0" }, { name = "mkdocstrings", extras = ["python"], specifier = "==0.30.1" }, @@ -1243,7 +1243,7 @@ docs = [ { name = "jieba", specifier = "==0.42.1" }, { name = "markdown-include-variants", specifier = "==0.0.8" }, { name = "mdx-include", specifier = ">=1.4.1,<2.0.0" }, - { name = "mkdocs-macros-plugin", specifier = "==1.4.1" }, + { name = "mkdocs-macros-plugin", specifier = "==1.5.0" }, { name = "mkdocs-material", specifier = "==9.7.0" }, { name = "mkdocs-redirects", specifier = ">=1.2.1,<1.3.0" }, { name = "mkdocstrings", extras = ["python"], specifier = "==0.30.1" }, @@ -2652,7 +2652,7 @@ wheels = [ [[package]] name = "mkdocs-macros-plugin" -version = "1.4.1" +version = "1.5.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "hjson" }, @@ -2667,9 +2667,9 @@ dependencies = [ { name = "termcolor", version = "3.1.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.10'" }, { name = "termcolor", version = "3.3.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.10'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/1b/42/bb2ceed148c77f82b57c6d3b7f584f0f34ababf7a9a8ff85809380d1f400/mkdocs_macros_plugin-1.4.1.tar.gz", hash = "sha256:55a9c93871e3744cdeb0736316783d60830a6d5d97b1132364e6b491607f2332", size = 35094, upload-time = "2025-10-25T12:37:20.689Z" } +sdist = { url = "https://files.pythonhosted.org/packages/92/15/e6a44839841ebc9c5872fa0e6fad1c3757424e4fe026093b68e9f386d136/mkdocs_macros_plugin-1.5.0.tar.gz", hash = "sha256:12aa45ce7ecb7a445c66b9f649f3dd05e9b92e8af6bc65e4acd91d26f878c01f", size = 37730, upload-time = "2025-11-13T08:08:55.545Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/93/ec/e6e96a7ae8df414f03f43681821234b0d3b86666f7b91f70ab26775a8809/mkdocs_macros_plugin-1.4.1-py3-none-any.whl", hash = "sha256:5a9e483f6056fe7ad0923802affe699233ca468672e20a9640dba237165b3240", size = 40155, upload-time = "2025-10-25T12:37:19.417Z" }, + { url = "https://files.pythonhosted.org/packages/51/62/9fffba5bb9ed3d31a932ad35038ba9483d59850256ee0fea7f1187173983/mkdocs_macros_plugin-1.5.0-py3-none-any.whl", hash = "sha256:c10fabd812bf50f9170609d0ed518e54f1f0e12c334ac29141723a83c881dd6f", size = 44626, upload-time = "2025-11-13T08:08:53.878Z" }, ] [[package]] From 5c3f0307ae475fd0ceeb47aaa2404119f2b6da8a Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 2 Feb 2026 15:57:43 +0100 Subject: [PATCH 053/108] =?UTF-8?q?=E2=AC=86=20Bump=20sqlmodel=20from=200.?= =?UTF-8?q?0.27=20to=200.0.31=20(#14802)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps [sqlmodel](https://github.com/fastapi/sqlmodel) from 0.0.27 to 0.0.31. - [Release notes](https://github.com/fastapi/sqlmodel/releases) - [Changelog](https://github.com/fastapi/sqlmodel/blob/main/docs/release-notes.md) - [Commits](https://github.com/fastapi/sqlmodel/compare/0.0.27...0.0.31) --- updated-dependencies: - dependency-name: sqlmodel dependency-version: 0.0.31 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Sofie Van Landeghem --- pyproject.toml | 2 +- uv.lock | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 524d527186..ef4330a0e5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -174,7 +174,7 @@ tests = [ "pytest>=7.1.3,<9.0.0", "pytest-codspeed==4.2.0", "pyyaml>=5.3.1,<7.0.0", - "sqlmodel==0.0.27", + "sqlmodel==0.0.31", "strawberry-graphql>=0.200.0,<1.0.0", "types-orjson==3.6.2", "types-ujson==5.10.0.20240515", diff --git a/uv.lock b/uv.lock index 312181b4e8..8b202e0891 100644 --- a/uv.lock +++ b/uv.lock @@ -1228,7 +1228,7 @@ dev = [ { name = "python-slugify", specifier = "==8.0.4" }, { name = "pyyaml", specifier = ">=5.3.1,<7.0.0" }, { name = "ruff", specifier = "==0.14.3" }, - { name = "sqlmodel", specifier = "==0.0.27" }, + { name = "sqlmodel", specifier = "==0.0.31" }, { name = "strawberry-graphql", specifier = ">=0.200.0,<1.0.0" }, { name = "typer", specifier = "==0.21.1" }, { name = "types-orjson", specifier = "==3.6.2" }, @@ -1279,7 +1279,7 @@ tests = [ { name = "pytest-codspeed", specifier = "==4.2.0" }, { name = "pyyaml", specifier = ">=5.3.1,<7.0.0" }, { name = "ruff", specifier = "==0.14.3" }, - { name = "sqlmodel", specifier = "==0.0.27" }, + { name = "sqlmodel", specifier = "==0.0.31" }, { name = "strawberry-graphql", specifier = ">=0.200.0,<1.0.0" }, { name = "types-orjson", specifier = "==3.6.2" }, { name = "types-ujson", specifier = "==5.10.0.20240515" }, @@ -4415,15 +4415,15 @@ wheels = [ [[package]] name = "sqlmodel" -version = "0.0.27" +version = "0.0.31" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "pydantic" }, { name = "sqlalchemy" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/90/5a/693d90866233e837d182da76082a6d4c2303f54d3aaaa5c78e1238c5d863/sqlmodel-0.0.27.tar.gz", hash = "sha256:ad1227f2014a03905aef32e21428640848ac09ff793047744a73dfdd077ff620", size = 118053, upload-time = "2025-10-08T16:39:11.938Z" } +sdist = { url = "https://files.pythonhosted.org/packages/56/b8/e7cd6def4a773f25d6e29ffce63ccbfd6cf9488b804ab6fb9b80d334b39d/sqlmodel-0.0.31.tar.gz", hash = "sha256:2d41a8a9ee05e40736e2f9db8ea28cbfe9b5d4e5a18dd139e80605025e0c516c", size = 94952, upload-time = "2025-12-28T12:35:01.436Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/8c/92/c35e036151fe53822893979f8a13e6f235ae8191f4164a79ae60a95d66aa/sqlmodel-0.0.27-py3-none-any.whl", hash = "sha256:667fe10aa8ff5438134668228dc7d7a08306f4c5c4c7e6ad3ad68defa0e7aa49", size = 29131, upload-time = "2025-10-08T16:39:10.917Z" }, + { url = "https://files.pythonhosted.org/packages/6c/72/5aa5be921800f6418a949a73c9bb7054890881143e6bc604a93d228a95a3/sqlmodel-0.0.31-py3-none-any.whl", hash = "sha256:6d946d56cac4c2db296ba1541357cee2e795d68174e2043cd138b916794b1513", size = 27093, upload-time = "2025-12-28T12:35:00.108Z" }, ] [[package]] From ecb1444738a3315167a8c11eac9b8503aec5a3d3 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 2 Feb 2026 14:57:46 +0000 Subject: [PATCH 054/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index afe456a3fa..997bd98d5e 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -41,6 +41,7 @@ hide: ### Internal +* ⬆ Bump gitpython from 3.1.45 to 3.1.46. PR [#14800](https://github.com/fastapi/fastapi/pull/14800) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump typer from 0.16.0 to 0.21.1. PR [#14799](https://github.com/fastapi/fastapi/pull/14799) by [@dependabot[bot]](https://github.com/apps/dependabot). * 👥 Update FastAPI GitHub topic repositories. PR [#14803](https://github.com/fastapi/fastapi/pull/14803) by [@tiangolo](https://github.com/tiangolo). * 👥 Update FastAPI People - Contributors and Translators. PR [#14796](https://github.com/fastapi/fastapi/pull/14796) by [@tiangolo](https://github.com/tiangolo). From 87b5333e8ae48cd68ef90ac29897bce25bb6540c Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 2 Feb 2026 15:00:26 +0000 Subject: [PATCH 055/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 997bd98d5e..7fd3b91786 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -41,6 +41,7 @@ hide: ### Internal +* ⬆ Bump mkdocs-macros-plugin from 1.4.1 to 1.5.0. PR [#14801](https://github.com/fastapi/fastapi/pull/14801) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump gitpython from 3.1.45 to 3.1.46. PR [#14800](https://github.com/fastapi/fastapi/pull/14800) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump typer from 0.16.0 to 0.21.1. PR [#14799](https://github.com/fastapi/fastapi/pull/14799) by [@dependabot[bot]](https://github.com/apps/dependabot). * 👥 Update FastAPI GitHub topic repositories. PR [#14803](https://github.com/fastapi/fastapi/pull/14803) by [@tiangolo](https://github.com/tiangolo). From 608ff552ba249c0a6cc8fdf755b43135cd45a9fa Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 2 Feb 2026 15:00:28 +0000 Subject: [PATCH 056/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 7fd3b91786..fb08caca47 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -41,6 +41,7 @@ hide: ### Internal +* ⬆ Bump sqlmodel from 0.0.27 to 0.0.31. PR [#14802](https://github.com/fastapi/fastapi/pull/14802) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump mkdocs-macros-plugin from 1.4.1 to 1.5.0. PR [#14801](https://github.com/fastapi/fastapi/pull/14801) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump gitpython from 3.1.45 to 3.1.46. PR [#14800](https://github.com/fastapi/fastapi/pull/14800) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump typer from 0.16.0 to 0.21.1. PR [#14799](https://github.com/fastapi/fastapi/pull/14799) by [@dependabot[bot]](https://github.com/apps/dependabot). From bc9ad6b1342bd191693942cbcbd0fee954cf1a3e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 2 Feb 2026 15:09:12 +0000 Subject: [PATCH 057/108] =?UTF-8?q?=E2=AC=86=20Bump=20pyasn1=20from=200.6.?= =?UTF-8?q?1=20to=200.6.2=20(#14804)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps [pyasn1](https://github.com/pyasn1/pyasn1) from 0.6.1 to 0.6.2. - [Release notes](https://github.com/pyasn1/pyasn1/releases) - [Changelog](https://github.com/pyasn1/pyasn1/blob/main/CHANGES.rst) - [Commits](https://github.com/pyasn1/pyasn1/compare/v0.6.1...v0.6.2) --- updated-dependencies: - dependency-name: pyasn1 dependency-version: 0.6.2 dependency-type: indirect ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Sofie Van Landeghem --- uv.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/uv.lock b/uv.lock index 8b202e0891..3be38bb80f 100644 --- a/uv.lock +++ b/uv.lock @@ -3238,11 +3238,11 @@ argon2 = [ [[package]] name = "pyasn1" -version = "0.6.1" +version = "0.6.2" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/ba/e9/01f1a64245b89f039897cb0130016d79f77d52669aae6ee7b159a6c4c018/pyasn1-0.6.1.tar.gz", hash = "sha256:6f580d2bdd84365380830acf45550f2511469f673cb4a5ae3857a3170128b034", size = 145322, upload-time = "2024-09-10T22:41:42.55Z" } +sdist = { url = "https://files.pythonhosted.org/packages/fe/b6/6e630dff89739fcd427e3f72b3d905ce0acb85a45d4ec3e2678718a3487f/pyasn1-0.6.2.tar.gz", hash = "sha256:9b59a2b25ba7e4f8197db7686c09fb33e658b98339fadb826e9512629017833b", size = 146586, upload-time = "2026-01-16T18:04:18.534Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/c8/f1/d6a797abb14f6283c0ddff96bbdd46937f64122b8c925cab503dd37f8214/pyasn1-0.6.1-py3-none-any.whl", hash = "sha256:0d632f46f2ba09143da3a8afe9e33fb6f92fa2320ab7e886e2d0f7672af84629", size = 83135, upload-time = "2024-09-11T16:00:36.122Z" }, + { url = "https://files.pythonhosted.org/packages/44/b5/a96872e5184f354da9c84ae119971a0a4c221fe9b27a4d94bd43f2596727/pyasn1-0.6.2-py3-none-any.whl", hash = "sha256:1eb26d860996a18e9b6ed05e7aae0e9fc21619fcee6af91cca9bad4fbea224bf", size = 83371, upload-time = "2026-01-16T18:04:17.174Z" }, ] [[package]] From 82959de14c755e898c4216b2a2d241801c2606eb Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 2 Feb 2026 15:09:37 +0000 Subject: [PATCH 058/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index fb08caca47..0252730c8f 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -41,6 +41,7 @@ hide: ### Internal +* ⬆ Bump pyasn1 from 0.6.1 to 0.6.2. PR [#14804](https://github.com/fastapi/fastapi/pull/14804) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump sqlmodel from 0.0.27 to 0.0.31. PR [#14802](https://github.com/fastapi/fastapi/pull/14802) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump mkdocs-macros-plugin from 1.4.1 to 1.5.0. PR [#14801](https://github.com/fastapi/fastapi/pull/14801) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump gitpython from 3.1.45 to 3.1.46. PR [#14800](https://github.com/fastapi/fastapi/pull/14800) by [@dependabot[bot]](https://github.com/apps/dependabot). From ec07e62e1c3c054cd3fa0608708103f2acfc3a03 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 2 Feb 2026 17:34:26 +0100 Subject: [PATCH 059/108] =?UTF-8?q?=E2=AC=86=20Bump=20ruff=20from=200.14.3?= =?UTF-8?q?=20to=200.14.14=20(#14798)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps [ruff](https://github.com/astral-sh/ruff) from 0.14.3 to 0.14.14. - [Release notes](https://github.com/astral-sh/ruff/releases) - [Changelog](https://github.com/astral-sh/ruff/blob/main/CHANGELOG.md) - [Commits](https://github.com/astral-sh/ruff/compare/0.14.3...0.14.14) --- updated-dependencies: - dependency-name: ruff dependency-version: 0.14.14 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Sofie Van Landeghem --- pyproject.toml | 2 +- uv.lock | 48 ++++++++++++++++++++++++------------------------ 2 files changed, 25 insertions(+), 25 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index ef4330a0e5..dea61c6a10 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -151,7 +151,7 @@ docs = [ ] docs-tests = [ "httpx>=0.23.0,<1.0.0", - "ruff==0.14.3", + "ruff==0.14.14", ] github-actions = [ "httpx>=0.27.0,<1.0.0", diff --git a/uv.lock b/uv.lock index 3be38bb80f..2df0b256b8 100644 --- a/uv.lock +++ b/uv.lock @@ -1227,7 +1227,7 @@ dev = [ { name = "pytest-codspeed", specifier = "==4.2.0" }, { name = "python-slugify", specifier = "==8.0.4" }, { name = "pyyaml", specifier = ">=5.3.1,<7.0.0" }, - { name = "ruff", specifier = "==0.14.3" }, + { name = "ruff", specifier = "==0.14.14" }, { name = "sqlmodel", specifier = "==0.0.31" }, { name = "strawberry-graphql", specifier = ">=0.200.0,<1.0.0" }, { name = "typer", specifier = "==0.21.1" }, @@ -1250,12 +1250,12 @@ docs = [ { name = "pillow", specifier = "==11.3.0" }, { name = "python-slugify", specifier = "==8.0.4" }, { name = "pyyaml", specifier = ">=5.3.1,<7.0.0" }, - { name = "ruff", specifier = "==0.14.3" }, + { name = "ruff", specifier = "==0.14.14" }, { name = "typer", specifier = "==0.21.1" }, ] docs-tests = [ { name = "httpx", specifier = ">=0.23.0,<1.0.0" }, - { name = "ruff", specifier = "==0.14.3" }, + { name = "ruff", specifier = "==0.14.14" }, ] github-actions = [ { name = "httpx", specifier = ">=0.27.0,<1.0.0" }, @@ -1278,7 +1278,7 @@ tests = [ { name = "pytest", specifier = ">=7.1.3,<9.0.0" }, { name = "pytest-codspeed", specifier = "==4.2.0" }, { name = "pyyaml", specifier = ">=5.3.1,<7.0.0" }, - { name = "ruff", specifier = "==0.14.3" }, + { name = "ruff", specifier = "==0.14.14" }, { name = "sqlmodel", specifier = "==0.0.31" }, { name = "strawberry-graphql", specifier = ">=0.200.0,<1.0.0" }, { name = "types-orjson", specifier = "==3.6.2" }, @@ -4248,28 +4248,28 @@ wheels = [ [[package]] name = "ruff" -version = "0.14.3" +version = "0.14.14" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/75/62/50b7727004dfe361104dfbf898c45a9a2fdfad8c72c04ae62900224d6ecf/ruff-0.14.3.tar.gz", hash = "sha256:4ff876d2ab2b161b6de0aa1f5bd714e8e9b4033dc122ee006925fbacc4f62153", size = 5558687, upload-time = "2025-10-31T00:26:26.878Z" } +sdist = { url = "https://files.pythonhosted.org/packages/2e/06/f71e3a86b2df0dfa2d2f72195941cd09b44f87711cb7fa5193732cb9a5fc/ruff-0.14.14.tar.gz", hash = "sha256:2d0f819c9a90205f3a867dbbd0be083bee9912e170fd7d9704cc8ae45824896b", size = 4515732, upload-time = "2026-01-22T22:30:17.527Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/ce/8e/0c10ff1ea5d4360ab8bfca4cb2c9d979101a391f3e79d2616c9bf348cd26/ruff-0.14.3-py3-none-linux_armv6l.whl", hash = "sha256:876b21e6c824f519446715c1342b8e60f97f93264012de9d8d10314f8a79c371", size = 12535613, upload-time = "2025-10-31T00:25:44.302Z" }, - { url = "https://files.pythonhosted.org/packages/d3/c8/6724f4634c1daf52409fbf13fefda64aa9c8f81e44727a378b7b73dc590b/ruff-0.14.3-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:b6fd8c79b457bedd2abf2702b9b472147cd860ed7855c73a5247fa55c9117654", size = 12855812, upload-time = "2025-10-31T00:25:47.793Z" }, - { url = "https://files.pythonhosted.org/packages/de/03/db1bce591d55fd5f8a08bb02517fa0b5097b2ccabd4ea1ee29aa72b67d96/ruff-0.14.3-py3-none-macosx_11_0_arm64.whl", hash = "sha256:71ff6edca490c308f083156938c0c1a66907151263c4abdcb588602c6e696a14", size = 11944026, upload-time = "2025-10-31T00:25:49.657Z" }, - { url = "https://files.pythonhosted.org/packages/0b/75/4f8dbd48e03272715d12c87dc4fcaaf21b913f0affa5f12a4e9c6f8a0582/ruff-0.14.3-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:786ee3ce6139772ff9272aaf43296d975c0217ee1b97538a98171bf0d21f87ed", size = 12356818, upload-time = "2025-10-31T00:25:51.949Z" }, - { url = "https://files.pythonhosted.org/packages/ec/9b/506ec5b140c11d44a9a4f284ea7c14ebf6f8b01e6e8917734a3325bff787/ruff-0.14.3-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:cd6291d0061811c52b8e392f946889916757610d45d004e41140d81fb6cd5ddc", size = 12336745, upload-time = "2025-10-31T00:25:54.248Z" }, - { url = "https://files.pythonhosted.org/packages/c7/e1/c560d254048c147f35e7f8131d30bc1f63a008ac61595cf3078a3e93533d/ruff-0.14.3-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:a497ec0c3d2c88561b6d90f9c29f5ae68221ac00d471f306fa21fa4264ce5fcd", size = 13101684, upload-time = "2025-10-31T00:25:56.253Z" }, - { url = "https://files.pythonhosted.org/packages/a5/32/e310133f8af5cd11f8cc30f52522a3ebccc5ea5bff4b492f94faceaca7a8/ruff-0.14.3-py3-none-manylinux_2_17_ppc64.manylinux2014_ppc64.whl", hash = "sha256:e231e1be58fc568950a04fbe6887c8e4b85310e7889727e2b81db205c45059eb", size = 14535000, upload-time = "2025-10-31T00:25:58.397Z" }, - { url = "https://files.pythonhosted.org/packages/a2/a1/7b0470a22158c6d8501eabc5e9b6043c99bede40fa1994cadf6b5c2a61c7/ruff-0.14.3-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:469e35872a09c0e45fecf48dd960bfbce056b5db2d5e6b50eca329b4f853ae20", size = 14156450, upload-time = "2025-10-31T00:26:00.889Z" }, - { url = "https://files.pythonhosted.org/packages/0a/96/24bfd9d1a7f532b560dcee1a87096332e461354d3882124219bcaff65c09/ruff-0.14.3-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:3d6bc90307c469cb9d28b7cfad90aaa600b10d67c6e22026869f585e1e8a2db0", size = 13568414, upload-time = "2025-10-31T00:26:03.291Z" }, - { url = "https://files.pythonhosted.org/packages/a7/e7/138b883f0dfe4ad5b76b58bf4ae675f4d2176ac2b24bdd81b4d966b28c61/ruff-0.14.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0e2f8a0bbcffcfd895df39c9a4ecd59bb80dca03dc43f7fb63e647ed176b741e", size = 13315293, upload-time = "2025-10-31T00:26:05.708Z" }, - { url = "https://files.pythonhosted.org/packages/33/f4/c09bb898be97b2eb18476b7c950df8815ef14cf956074177e9fbd40b7719/ruff-0.14.3-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:678fdd7c7d2d94851597c23ee6336d25f9930b460b55f8598e011b57c74fd8c5", size = 13539444, upload-time = "2025-10-31T00:26:08.09Z" }, - { url = "https://files.pythonhosted.org/packages/9c/aa/b30a1db25fc6128b1dd6ff0741fa4abf969ded161599d07ca7edd0739cc0/ruff-0.14.3-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:1ec1ac071e7e37e0221d2f2dbaf90897a988c531a8592a6a5959f0603a1ecf5e", size = 12252581, upload-time = "2025-10-31T00:26:10.297Z" }, - { url = "https://files.pythonhosted.org/packages/da/13/21096308f384d796ffe3f2960b17054110a9c3828d223ca540c2b7cc670b/ruff-0.14.3-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:afcdc4b5335ef440d19e7df9e8ae2ad9f749352190e96d481dc501b753f0733e", size = 12307503, upload-time = "2025-10-31T00:26:12.646Z" }, - { url = "https://files.pythonhosted.org/packages/cb/cc/a350bac23f03b7dbcde3c81b154706e80c6f16b06ff1ce28ed07dc7b07b0/ruff-0.14.3-py3-none-musllinux_1_2_i686.whl", hash = "sha256:7bfc42f81862749a7136267a343990f865e71fe2f99cf8d2958f684d23ce3dfa", size = 12675457, upload-time = "2025-10-31T00:26:15.044Z" }, - { url = "https://files.pythonhosted.org/packages/cb/76/46346029fa2f2078826bc88ef7167e8c198e58fe3126636e52f77488cbba/ruff-0.14.3-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:a65e448cfd7e9c59fae8cf37f9221585d3354febaad9a07f29158af1528e165f", size = 13403980, upload-time = "2025-10-31T00:26:17.81Z" }, - { url = "https://files.pythonhosted.org/packages/9f/a4/35f1ef68c4e7b236d4a5204e3669efdeefaef21f0ff6a456792b3d8be438/ruff-0.14.3-py3-none-win32.whl", hash = "sha256:f3d91857d023ba93e14ed2d462ab62c3428f9bbf2b4fbac50a03ca66d31991f7", size = 12500045, upload-time = "2025-10-31T00:26:20.503Z" }, - { url = "https://files.pythonhosted.org/packages/03/15/51960ae340823c9859fb60c63301d977308735403e2134e17d1d2858c7fb/ruff-0.14.3-py3-none-win_amd64.whl", hash = "sha256:d7b7006ac0756306db212fd37116cce2bd307e1e109375e1c6c106002df0ae5f", size = 13594005, upload-time = "2025-10-31T00:26:22.533Z" }, - { url = "https://files.pythonhosted.org/packages/b7/73/4de6579bac8e979fca0a77e54dec1f1e011a0d268165eb8a9bc0982a6564/ruff-0.14.3-py3-none-win_arm64.whl", hash = "sha256:26eb477ede6d399d898791d01961e16b86f02bc2486d0d1a7a9bb2379d055dc1", size = 12590017, upload-time = "2025-10-31T00:26:24.52Z" }, + { url = "https://files.pythonhosted.org/packages/d2/89/20a12e97bc6b9f9f68343952da08a8099c57237aef953a56b82711d55edd/ruff-0.14.14-py3-none-linux_armv6l.whl", hash = "sha256:7cfe36b56e8489dee8fbc777c61959f60ec0f1f11817e8f2415f429552846aed", size = 10467650, upload-time = "2026-01-22T22:30:08.578Z" }, + { url = "https://files.pythonhosted.org/packages/a3/b1/c5de3fd2d5a831fcae21beda5e3589c0ba67eec8202e992388e4b17a6040/ruff-0.14.14-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:6006a0082336e7920b9573ef8a7f52eec837add1265cc74e04ea8a4368cd704c", size = 10883245, upload-time = "2026-01-22T22:30:04.155Z" }, + { url = "https://files.pythonhosted.org/packages/b8/7c/3c1db59a10e7490f8f6f8559d1db8636cbb13dccebf18686f4e3c9d7c772/ruff-0.14.14-py3-none-macosx_11_0_arm64.whl", hash = "sha256:026c1d25996818f0bf498636686199d9bd0d9d6341c9c2c3b62e2a0198b758de", size = 10231273, upload-time = "2026-01-22T22:30:34.642Z" }, + { url = "https://files.pythonhosted.org/packages/a1/6e/5e0e0d9674be0f8581d1f5e0f0a04761203affce3232c1a1189d0e3b4dad/ruff-0.14.14-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f666445819d31210b71e0a6d1c01e24447a20b85458eea25a25fe8142210ae0e", size = 10585753, upload-time = "2026-01-22T22:30:31.781Z" }, + { url = "https://files.pythonhosted.org/packages/23/09/754ab09f46ff1884d422dc26d59ba18b4e5d355be147721bb2518aa2a014/ruff-0.14.14-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:3c0f18b922c6d2ff9a5e6c3ee16259adc513ca775bcf82c67ebab7cbd9da5bc8", size = 10286052, upload-time = "2026-01-22T22:30:24.827Z" }, + { url = "https://files.pythonhosted.org/packages/c8/cc/e71f88dd2a12afb5f50733851729d6b571a7c3a35bfdb16c3035132675a0/ruff-0.14.14-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:1629e67489c2dea43e8658c3dba659edbfd87361624b4040d1df04c9740ae906", size = 11043637, upload-time = "2026-01-22T22:30:13.239Z" }, + { url = "https://files.pythonhosted.org/packages/67/b2/397245026352494497dac935d7f00f1468c03a23a0c5db6ad8fc49ca3fb2/ruff-0.14.14-py3-none-manylinux_2_17_ppc64.manylinux2014_ppc64.whl", hash = "sha256:27493a2131ea0f899057d49d303e4292b2cae2bb57253c1ed1f256fbcd1da480", size = 12194761, upload-time = "2026-01-22T22:30:22.542Z" }, + { url = "https://files.pythonhosted.org/packages/5b/06/06ef271459f778323112c51b7587ce85230785cd64e91772034ddb88f200/ruff-0.14.14-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:01ff589aab3f5b539e35db38425da31a57521efd1e4ad1ae08fc34dbe30bd7df", size = 12005701, upload-time = "2026-01-22T22:30:20.499Z" }, + { url = "https://files.pythonhosted.org/packages/41/d6/99364514541cf811ccc5ac44362f88df66373e9fec1b9d1c4cc830593fe7/ruff-0.14.14-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:1cc12d74eef0f29f51775f5b755913eb523546b88e2d733e1d701fe65144e89b", size = 11282455, upload-time = "2026-01-22T22:29:59.679Z" }, + { url = "https://files.pythonhosted.org/packages/ca/71/37daa46f89475f8582b7762ecd2722492df26421714a33e72ccc9a84d7a5/ruff-0.14.14-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:bb8481604b7a9e75eff53772496201690ce2687067e038b3cc31aaf16aa0b974", size = 11215882, upload-time = "2026-01-22T22:29:57.032Z" }, + { url = "https://files.pythonhosted.org/packages/2c/10/a31f86169ec91c0705e618443ee74ede0bdd94da0a57b28e72db68b2dbac/ruff-0.14.14-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:14649acb1cf7b5d2d283ebd2f58d56b75836ed8c6f329664fa91cdea19e76e66", size = 11180549, upload-time = "2026-01-22T22:30:27.175Z" }, + { url = "https://files.pythonhosted.org/packages/fd/1e/c723f20536b5163adf79bdd10c5f093414293cdf567eed9bdb7b83940f3f/ruff-0.14.14-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:e8058d2145566510790eab4e2fad186002e288dec5e0d343a92fe7b0bc1b3e13", size = 10543416, upload-time = "2026-01-22T22:30:01.964Z" }, + { url = "https://files.pythonhosted.org/packages/3e/34/8a84cea7e42c2d94ba5bde1d7a4fae164d6318f13f933d92da6d7c2041ff/ruff-0.14.14-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:e651e977a79e4c758eb807f0481d673a67ffe53cfa92209781dfa3a996cf8412", size = 10285491, upload-time = "2026-01-22T22:30:29.51Z" }, + { url = "https://files.pythonhosted.org/packages/55/ef/b7c5ea0be82518906c978e365e56a77f8de7678c8bb6651ccfbdc178c29f/ruff-0.14.14-py3-none-musllinux_1_2_i686.whl", hash = "sha256:cc8b22da8d9d6fdd844a68ae937e2a0adf9b16514e9a97cc60355e2d4b219fc3", size = 10733525, upload-time = "2026-01-22T22:30:06.499Z" }, + { url = "https://files.pythonhosted.org/packages/6a/5b/aaf1dfbcc53a2811f6cc0a1759de24e4b03e02ba8762daabd9b6bd8c59e3/ruff-0.14.14-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:16bc890fb4cc9781bb05beb5ab4cd51be9e7cb376bf1dd3580512b24eb3fda2b", size = 11315626, upload-time = "2026-01-22T22:30:36.848Z" }, + { url = "https://files.pythonhosted.org/packages/2c/aa/9f89c719c467dfaf8ad799b9bae0df494513fb21d31a6059cb5870e57e74/ruff-0.14.14-py3-none-win32.whl", hash = "sha256:b530c191970b143375b6a68e6f743800b2b786bbcf03a7965b06c4bf04568167", size = 10502442, upload-time = "2026-01-22T22:30:38.93Z" }, + { url = "https://files.pythonhosted.org/packages/87/44/90fa543014c45560cae1fffc63ea059fb3575ee6e1cb654562197e5d16fb/ruff-0.14.14-py3-none-win_amd64.whl", hash = "sha256:3dde1435e6b6fe5b66506c1dff67a421d0b7f6488d466f651c07f4cab3bf20fd", size = 11630486, upload-time = "2026-01-22T22:30:10.852Z" }, + { url = "https://files.pythonhosted.org/packages/9e/6a/40fee331a52339926a92e17ae748827270b288a35ef4a15c9c8f2ec54715/ruff-0.14.14-py3-none-win_arm64.whl", hash = "sha256:56e6981a98b13a32236a72a8da421d7839221fa308b223b9283312312e5ac76c", size = 10920448, upload-time = "2026-01-22T22:30:15.417Z" }, ] [[package]] From 2247750d74b26bc212300cdaff9d82a15bf71eca Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 2 Feb 2026 16:34:52 +0000 Subject: [PATCH 060/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 0252730c8f..e009de8a09 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -41,6 +41,7 @@ hide: ### Internal +* ⬆ Bump ruff from 0.14.3 to 0.14.14. PR [#14798](https://github.com/fastapi/fastapi/pull/14798) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump pyasn1 from 0.6.1 to 0.6.2. PR [#14804](https://github.com/fastapi/fastapi/pull/14804) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump sqlmodel from 0.0.27 to 0.0.31. PR [#14802](https://github.com/fastapi/fastapi/pull/14802) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump mkdocs-macros-plugin from 1.4.1 to 1.5.0. PR [#14801](https://github.com/fastapi/fastapi/pull/14801) by [@dependabot[bot]](https://github.com/apps/dependabot). From f3f498100f1d0edc344e200b215d42a6e46473fd Mon Sep 17 00:00:00 2001 From: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> Date: Tue, 3 Feb 2026 21:08:08 +0300 Subject: [PATCH 061/108] =?UTF-8?q?=F0=9F=91=B7=20Run=20mypy=20by=20pre-co?= =?UTF-8?q?mmit=20(#14806)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sebastián Ramírez --- .pre-commit-config.yaml | 7 +++++++ fastapi/_compat/v2.py | 8 ++++---- fastapi/dependencies/utils.py | 4 ++-- fastapi/utils.py | 2 +- 4 files changed, 14 insertions(+), 7 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index d88b70b7b6..64b84bfbd2 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -30,6 +30,13 @@ repos: language: unsupported types: [python] + - id: local-mypy + name: mypy check + entry: uv run mypy fastapi + require_serial: true + language: unsupported + pass_filenames: false + - id: add-permalinks-pages language: unsupported name: add-permalinks-pages diff --git a/fastapi/_compat/v2.py b/fastapi/_compat/v2.py index 25b6814536..dae78a32e0 100644 --- a/fastapi/_compat/v2.py +++ b/fastapi/_compat/v2.py @@ -477,7 +477,7 @@ def get_model_fields(model: type[BaseModel]) -> list[ModelField]: @lru_cache def get_cached_model_fields(model: type[BaseModel]) -> list[ModelField]: - return get_model_fields(model) # type: ignore[return-value] + return get_model_fields(model) # Duplicate of several schema functions from Pydantic v1 to make them compatible with @@ -500,13 +500,13 @@ def get_model_name_map(unique_models: TypeModelSet) -> dict[TypeModelOrEnum, str def get_compat_model_name_map(fields: list[ModelField]) -> ModelNameMap: - all_flat_models = set() + all_flat_models: TypeModelSet = set() v2_model_fields = [field for field in fields if isinstance(field, ModelField)] v2_flat_models = get_flat_models_from_fields(v2_model_fields, known_models=set()) - all_flat_models = all_flat_models.union(v2_flat_models) # type: ignore[arg-type] + all_flat_models = all_flat_models.union(v2_flat_models) - model_name_map = get_model_name_map(all_flat_models) # type: ignore[arg-type] + model_name_map = get_model_name_map(all_flat_models) return model_name_map diff --git a/fastapi/dependencies/utils.py b/fastapi/dependencies/utils.py index 45e1ff3ed1..2afc734ba4 100644 --- a/fastapi/dependencies/utils.py +++ b/fastapi/dependencies/utils.py @@ -399,7 +399,7 @@ def analyze_param( if isinstance(fastapi_annotation, FieldInfo): # Copy `field_info` because we mutate `field_info.default` below. field_info = copy_field_info( - field_info=fastapi_annotation, # type: ignore[arg-type] + field_info=fastapi_annotation, annotation=use_annotation, ) assert ( @@ -433,7 +433,7 @@ def analyze_param( "Cannot specify FastAPI annotations in `Annotated` and default value" f" together for {param_name!r}" ) - field_info = value # type: ignore[assignment] + field_info = value if isinstance(field_info, FieldInfo): field_info.annotation = type_annotation diff --git a/fastapi/utils.py b/fastapi/utils.py index 78fdcbb5b4..1c3a0881f7 100644 --- a/fastapi/utils.py +++ b/fastapi/utils.py @@ -90,7 +90,7 @@ def create_model_field( field_info = field_info or FieldInfo(annotation=type_, default=default, alias=alias) kwargs = {"mode": mode, "name": name, "field_info": field_info} try: - return v2.ModelField(**kwargs) # type: ignore[return-value,arg-type] + return v2.ModelField(**kwargs) # type: ignore[arg-type] except PydanticSchemaGenerationError: raise fastapi.exceptions.FastAPIError( _invalid_args_message.format(type_=type_) From eacbce24c9d299c6a28110d9fc8ac50f53cddb08 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 3 Feb 2026 18:08:36 +0000 Subject: [PATCH 062/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index e009de8a09..ebf3a348f5 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -41,6 +41,7 @@ hide: ### Internal +* 👷 Run mypy by pre-commit. PR [#14806](https://github.com/fastapi/fastapi/pull/14806) by [@YuriiMotov](https://github.com/YuriiMotov). * ⬆ Bump ruff from 0.14.3 to 0.14.14. PR [#14798](https://github.com/fastapi/fastapi/pull/14798) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump pyasn1 from 0.6.1 to 0.6.2. PR [#14804](https://github.com/fastapi/fastapi/pull/14804) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump sqlmodel from 0.0.27 to 0.0.31. PR [#14802](https://github.com/fastapi/fastapi/pull/14802) by [@dependabot[bot]](https://github.com/apps/dependabot). From 7621a3aa4b29713aa2ce0ab9605a008a5a8b9335 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Wed, 4 Feb 2026 03:46:32 -0800 Subject: [PATCH 063/108] =?UTF-8?q?=F0=9F=91=B7=20Run=20tests=20only=20on?= =?UTF-8?q?=20relevant=20code=20changes=20(not=20on=20docs)=20(#14813)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/test.yml | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 891f767175..5cbbde61fa 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -16,7 +16,35 @@ env: UV_NO_SYNC: true jobs: + changes: + runs-on: ubuntu-latest + # Required permissions + permissions: + pull-requests: read + # Set job outputs to values from filter step + outputs: + src: ${{ steps.filter.outputs.src }} + steps: + - uses: actions/checkout@v6 + # For pull requests it's not necessary to checkout the code but for the main branch it is + - uses: dorny/paths-filter@v3 + id: filter + with: + filters: | + src: + - .github/workflows/test.yml + - docs_src/** + - fastapi/** + - scripts/** + - tests/** + - .python-version + - pyproject.toml + - uv.lock + test: + needs: + - changes + if: needs.changes.outputs.src == 'true' strategy: matrix: os: [ windows-latest, macos-latest ] @@ -91,7 +119,8 @@ jobs: include-hidden-files: true coverage-combine: - needs: [test] + needs: + - test runs-on: ubuntu-latest steps: - name: Dump GitHub context @@ -143,3 +172,4 @@ jobs: uses: re-actors/alls-green@release/v1 with: jobs: ${{ toJSON(needs) }} + allowed-skips: coverage-combine,test From dd780f8caa13e3fa755cfabbec0e603f485cae97 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 11:46:55 +0000 Subject: [PATCH 064/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index ebf3a348f5..85c1128fcc 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -41,6 +41,7 @@ hide: ### Internal +* 👷 Run tests only on relevant code changes (not on docs). PR [#14813](https://github.com/fastapi/fastapi/pull/14813) by [@tiangolo](https://github.com/tiangolo). * 👷 Run mypy by pre-commit. PR [#14806](https://github.com/fastapi/fastapi/pull/14806) by [@YuriiMotov](https://github.com/YuriiMotov). * ⬆ Bump ruff from 0.14.3 to 0.14.14. PR [#14798](https://github.com/fastapi/fastapi/pull/14798) by [@dependabot[bot]](https://github.com/apps/dependabot). * ⬆ Bump pyasn1 from 0.6.1 to 0.6.2. PR [#14804](https://github.com/fastapi/fastapi/pull/14804) by [@dependabot[bot]](https://github.com/apps/dependabot). From 261736ab4c3d7a3ec642071ba6f9408ebf9618d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Wed, 4 Feb 2026 03:49:00 -0800 Subject: [PATCH 065/108] =?UTF-8?q?=F0=9F=92=A1=20Update=20comment=20for?= =?UTF-8?q?=20Pydantic=20internals=20(#14814)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fastapi/_compat/shared.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fastapi/_compat/shared.py b/fastapi/_compat/shared.py index 419b58f7f2..68b9bbdf1e 100644 --- a/fastapi/_compat/shared.py +++ b/fastapi/_compat/shared.py @@ -17,7 +17,7 @@ from pydantic.version import VERSION as PYDANTIC_VERSION from starlette.datastructures import UploadFile from typing_extensions import get_args, get_origin -# Copy from Pydantic v2, compatible with v1 +# Copy from Pydantic: pydantic/_internal/_typing_extra.py if sys.version_info < (3, 10): WithArgsTypes: tuple[Any, ...] = (typing._GenericAlias, types.GenericAlias) # type: ignore[attr-defined] else: @@ -45,7 +45,7 @@ sequence_types = tuple(sequence_annotation_to_type.keys()) Url: type[Any] -# Copy of Pydantic v2, compatible with v1 +# Copy of Pydantic: pydantic/_internal/_utils.py def lenient_issubclass( cls: Any, class_or_tuple: Union[type[Any], tuple[type[Any], ...], None] ) -> bool: From 573c593dd04365f0d1dddde2e167851f6d19cef7 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 11:49:22 +0000 Subject: [PATCH 066/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 85c1128fcc..20af681fd9 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,10 @@ hide: ## Latest Changes +### Refactors + +* 💡 Update comment for Pydantic internals. PR [#14814](https://github.com/fastapi/fastapi/pull/14814) by [@tiangolo](https://github.com/tiangolo). + ### Docs * 📝 Fix minor typos in release notes. PR [#14780](https://github.com/fastapi/fastapi/pull/14780) by [@whyvineet](https://github.com/whyvineet). From dc3278654f13614d255edca66954326966f6620d Mon Sep 17 00:00:00 2001 From: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> Date: Wed, 4 Feb 2026 14:54:23 +0300 Subject: [PATCH 067/108] =?UTF-8?q?=F0=9F=93=9D=20Use=20`WSGIMiddleware`?= =?UTF-8?q?=20from=20`a2wsgi`=20instead=20of=20deprecated=20`fastapi.middl?= =?UTF-8?q?eware.wsgi.WSGIMiddleware`=20(#14756)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: github-actions[bot] --- docs/en/docs/advanced/wsgi.md | 20 ++++++++++++++++++-- docs/en/docs/reference/middleware.md | 8 -------- docs_src/wsgi/tutorial001_py39.py | 2 +- fastapi/middleware/wsgi.py | 4 +++- pyproject.toml | 2 +- uv.lock | 16 ++++++++++++++++ 6 files changed, 39 insertions(+), 13 deletions(-) diff --git a/docs/en/docs/advanced/wsgi.md b/docs/en/docs/advanced/wsgi.md index 07147df0a8..aa68617cf4 100644 --- a/docs/en/docs/advanced/wsgi.md +++ b/docs/en/docs/advanced/wsgi.md @@ -6,13 +6,29 @@ For that, you can use the `WSGIMiddleware` and use it to wrap your WSGI applicat ## Using `WSGIMiddleware` { #using-wsgimiddleware } -You need to import `WSGIMiddleware`. +/// info + +This requires installing `a2wsgi` for example with `pip install a2wsgi`. + +/// + +You need to import `WSGIMiddleware` from `a2wsgi`. Then wrap the WSGI (e.g. Flask) app with the middleware. And then mount that under a path. -{* ../../docs_src/wsgi/tutorial001_py39.py hl[2:3,3] *} +{* ../../docs_src/wsgi/tutorial001_py39.py hl[1,3,23] *} + +/// note + +Previously, it was recommended to use `WSGIMiddleware` from `fastapi.middleware.wsgi`, but it is now deprecated. + +It’s advised to use the `a2wsgi` package instead. The usage remains the same. + +Just ensure that you have the `a2wsgi` package installed and import `WSGIMiddleware` correctly from `a2wsgi`. + +/// ## Check it { #check-it } diff --git a/docs/en/docs/reference/middleware.md b/docs/en/docs/reference/middleware.md index 3c666ccdaa..48ff85158d 100644 --- a/docs/en/docs/reference/middleware.md +++ b/docs/en/docs/reference/middleware.md @@ -35,11 +35,3 @@ It can be imported from `fastapi`: ```python from fastapi.middleware.trustedhost import TrustedHostMiddleware ``` - -::: fastapi.middleware.wsgi.WSGIMiddleware - -It can be imported from `fastapi`: - -```python -from fastapi.middleware.wsgi import WSGIMiddleware -``` diff --git a/docs_src/wsgi/tutorial001_py39.py b/docs_src/wsgi/tutorial001_py39.py index 7f27a85a19..8eeceb829e 100644 --- a/docs_src/wsgi/tutorial001_py39.py +++ b/docs_src/wsgi/tutorial001_py39.py @@ -1,5 +1,5 @@ +from a2wsgi import WSGIMiddleware from fastapi import FastAPI -from fastapi.middleware.wsgi import WSGIMiddleware from flask import Flask, request from markupsafe import escape diff --git a/fastapi/middleware/wsgi.py b/fastapi/middleware/wsgi.py index c4c6a797d2..69e4dcab96 100644 --- a/fastapi/middleware/wsgi.py +++ b/fastapi/middleware/wsgi.py @@ -1 +1,3 @@ -from starlette.middleware.wsgi import WSGIMiddleware as WSGIMiddleware # noqa +from starlette.middleware.wsgi import ( + WSGIMiddleware as WSGIMiddleware, +) # pragma: no cover # noqa diff --git a/pyproject.toml b/pyproject.toml index dea61c6a10..0f6bf1e4ac 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -178,6 +178,7 @@ tests = [ "strawberry-graphql>=0.200.0,<1.0.0", "types-orjson==3.6.2", "types-ujson==5.10.0.20240515", + "a2wsgi>=1.9.0,<=2.0.0", ] translations = [ "gitpython==3.1.46", @@ -231,7 +232,6 @@ xfail_strict = true junit_family = "xunit2" filterwarnings = [ "error", - 'ignore:starlette.middleware.wsgi is deprecated and will be removed in a future release\..*:DeprecationWarning:starlette', # see https://trio.readthedocs.io/en/stable/history.html#trio-0-22-0-2022-09-28 "ignore:You seem to already have a custom.*:RuntimeWarning:trio", # TODO: remove after upgrading SQLAlchemy to a version that includes the following changes diff --git a/uv.lock b/uv.lock index 2df0b256b8..931a27021b 100644 --- a/uv.lock +++ b/uv.lock @@ -7,6 +7,18 @@ resolution-markers = [ "python_full_version < '3.10'", ] +[[package]] +name = "a2wsgi" +version = "1.10.10" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "typing-extensions", marker = "python_full_version < '3.11'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/9a/cb/822c56fbea97e9eee201a2e434a80437f6750ebcb1ed307ee3a0a7505b14/a2wsgi-1.10.10.tar.gz", hash = "sha256:a5bcffb52081ba39df0d5e9a884fc6f819d92e3a42389343ba77cbf809fe1f45", size = 18799, upload-time = "2025-06-18T09:00:10.843Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/02/d5/349aba3dc421e73cbd4958c0ce0a4f1aa3a738bc0d7de75d2f40ed43a535/a2wsgi-1.10.10-py3-none-any.whl", hash = "sha256:d2b21379479718539dc15fce53b876251a0efe7615352dfe49f6ad1bc507848d", size = 17389, upload-time = "2025-06-18T09:00:09.676Z" }, +] + [[package]] name = "ag-ui-protocol" version = "0.1.10" @@ -1058,6 +1070,7 @@ standard-no-fastapi-cloud-cli = [ [package.dev-dependencies] dev = [ + { name = "a2wsgi" }, { name = "anyio", extra = ["trio"] }, { name = "black" }, { name = "cairosvg" }, @@ -1131,6 +1144,7 @@ github-actions = [ { name = "smokeshow" }, ] tests = [ + { name = "a2wsgi" }, { name = "anyio", extra = ["trio"] }, { name = "coverage", version = "7.10.7", source = { registry = "https://pypi.org/simple" }, extra = ["toml"], marker = "python_full_version < '3.10'" }, { name = "coverage", version = "7.13.1", source = { registry = "https://pypi.org/simple" }, extra = ["toml"], marker = "python_full_version >= '3.10'" }, @@ -1197,6 +1211,7 @@ provides-extras = ["standard", "standard-no-fastapi-cloud-cli", "all"] [package.metadata.requires-dev] dev = [ + { name = "a2wsgi", specifier = ">=1.9.0,<=2.0.0" }, { name = "anyio", extras = ["trio"], specifier = ">=3.2.1,<5.0.0" }, { name = "black", specifier = "==25.1.0" }, { name = "cairosvg", specifier = "==2.8.2" }, @@ -1266,6 +1281,7 @@ github-actions = [ { name = "smokeshow", specifier = ">=0.5.0" }, ] tests = [ + { name = "a2wsgi", specifier = ">=1.9.0,<=2.0.0" }, { name = "anyio", extras = ["trio"], specifier = ">=3.2.1,<5.0.0" }, { name = "coverage", extras = ["toml"], specifier = ">=6.5.0,<8.0" }, { name = "dirty-equals", specifier = "==0.9.0" }, From e3a66494c91c0dc4fc423d812c5bf04795358e03 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 11:54:46 +0000 Subject: [PATCH 068/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 20af681fd9..8fc6e86216 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -13,6 +13,7 @@ hide: ### Docs +* 📝 Use `WSGIMiddleware` from `a2wsgi` instead of deprecated `fastapi.middleware.wsgi.WSGIMiddleware`. PR [#14756](https://github.com/fastapi/fastapi/pull/14756) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Fix minor typos in release notes. PR [#14780](https://github.com/fastapi/fastapi/pull/14780) by [@whyvineet](https://github.com/whyvineet). * 🐛 Fix copy button in custom.js. PR [#14722](https://github.com/fastapi/fastapi/pull/14722) by [@fcharrier](https://github.com/fcharrier). * 📝 Add contribution instructions about LLM generated code and comments and automated tools for PRs. PR [#14706](https://github.com/fastapi/fastapi/pull/14706) by [@tiangolo](https://github.com/tiangolo). From 27b91d4ad606876a06f25ea82c989374d54311fd Mon Sep 17 00:00:00 2001 From: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> Date: Wed, 4 Feb 2026 15:05:19 +0300 Subject: [PATCH 069/108] =?UTF-8?q?=F0=9F=94=A8=20Update=20translation=20s?= =?UTF-8?q?cript=20to=20retry=20if=20LLM-response=20doesn't=20pass=20valid?= =?UTF-8?q?ation=20with=20Translation=20Fixer=20tool=20(#14749)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: github-actions[bot] --- scripts/translate.py | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/scripts/translate.py b/scripts/translate.py index eba4ad6a2f..9eda7b3903 100644 --- a/scripts/translate.py +++ b/scripts/translate.py @@ -10,6 +10,7 @@ from typing import Annotated import git import typer import yaml +from doc_parsing_utils import check_translation from github import Github from pydantic_ai import Agent from rich import print @@ -119,9 +120,30 @@ def translate_page( ] ) prompt = "\n\n".join(prompt_segments) - print(f"Running agent for {out_path}") - result = agent.run_sync(prompt) - out_content = f"{result.output.strip()}\n" + + MAX_ATTEMPTS = 3 + for attempt_no in range(1, MAX_ATTEMPTS + 1): + print(f"Running agent for {out_path} (attempt {attempt_no}/{MAX_ATTEMPTS})") + result = agent.run_sync(prompt) + out_content = f"{result.output.strip()}\n" + try: + check_translation( + doc_lines=out_content.splitlines(), + en_doc_lines=original_content.splitlines(), + lang_code=language, + auto_fix=False, + path=str(out_path), + ) + break # Exit loop if no errors + except ValueError as e: + print( + f"Translation check failed on attempt {attempt_no}/{MAX_ATTEMPTS}: {e}" + ) + continue # Retry if not reached max attempts + else: # Max retry attempts reached + print(f"Translation failed for {out_path} after {MAX_ATTEMPTS} attempts") + raise typer.Exit(code=1) + print(f"Saving translation to {out_path}") out_path.write_text(out_content, encoding="utf-8", newline="\n") From f6ba0141f4736fb78ec80e509634be8d505ae768 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 12:05:41 +0000 Subject: [PATCH 070/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 8fc6e86216..30704f3e52 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -46,6 +46,7 @@ hide: ### Internal +* 🔚 Update translation script to retry if LLM-response doesn't pass validation with Translation Fixer tool. PR [#14749](https://github.com/fastapi/fastapi/pull/14749) by [@YuriiMotov](https://github.com/YuriiMotov). * 👷 Run tests only on relevant code changes (not on docs). PR [#14813](https://github.com/fastapi/fastapi/pull/14813) by [@tiangolo](https://github.com/tiangolo). * 👷 Run mypy by pre-commit. PR [#14806](https://github.com/fastapi/fastapi/pull/14806) by [@YuriiMotov](https://github.com/YuriiMotov). * ⬆ Bump ruff from 0.14.3 to 0.14.14. PR [#14798](https://github.com/fastapi/fastapi/pull/14798) by [@dependabot[bot]](https://github.com/apps/dependabot). From 741c7345eaecbeedd3ea83f6e7d1048b33ce332b Mon Sep 17 00:00:00 2001 From: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> Date: Wed, 4 Feb 2026 15:07:26 +0300 Subject: [PATCH 071/108] =?UTF-8?q?=F0=9F=93=9D=20Use=20return=20type=20an?= =?UTF-8?q?notation=20instead=20of=20`response=5Fmodel`=20when=20possible?= =?UTF-8?q?=20(#14753)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/tutorial/path-operation-configuration.md | 4 ++-- docs_src/app_testing/app_b_an_py310/main.py | 4 ++-- docs_src/app_testing/app_b_an_py39/main.py | 4 ++-- docs_src/app_testing/app_b_py310/main.py | 4 ++-- docs_src/app_testing/app_b_py39/main.py | 4 ++-- docs_src/body_updates/tutorial002_py310.py | 4 ++-- docs_src/body_updates/tutorial002_py39.py | 4 ++-- .../tutorial004_py310.py | 4 ++-- .../path_operation_advanced_configuration/tutorial004_py39.py | 4 ++-- docs_src/path_operation_configuration/tutorial001_py310.py | 4 ++-- docs_src/path_operation_configuration/tutorial001_py39.py | 4 ++-- docs_src/path_operation_configuration/tutorial002_py310.py | 4 ++-- docs_src/path_operation_configuration/tutorial002_py39.py | 4 ++-- docs_src/path_operation_configuration/tutorial003_py310.py | 3 +-- docs_src/path_operation_configuration/tutorial003_py39.py | 3 +-- docs_src/path_operation_configuration/tutorial004_py310.py | 4 ++-- docs_src/path_operation_configuration/tutorial004_py39.py | 4 ++-- docs_src/path_operation_configuration/tutorial005_py310.py | 3 +-- docs_src/path_operation_configuration/tutorial005_py39.py | 3 +-- docs_src/security/tutorial004_an_py310.py | 4 ++-- docs_src/security/tutorial004_an_py39.py | 4 ++-- docs_src/security/tutorial004_py310.py | 4 ++-- docs_src/security/tutorial004_py39.py | 4 ++-- docs_src/security/tutorial005_an_py310.py | 4 ++-- docs_src/security/tutorial005_an_py39.py | 4 ++-- docs_src/security/tutorial005_py310.py | 4 ++-- docs_src/security/tutorial005_py39.py | 4 ++-- 27 files changed, 50 insertions(+), 54 deletions(-) diff --git a/docs/en/docs/tutorial/path-operation-configuration.md b/docs/en/docs/tutorial/path-operation-configuration.md index 59be5ab376..1bb7ee5544 100644 --- a/docs/en/docs/tutorial/path-operation-configuration.md +++ b/docs/en/docs/tutorial/path-operation-configuration.md @@ -52,7 +52,7 @@ In these cases, it could make sense to store the tags in an `Enum`. You can add a `summary` and `description`: -{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[18:19] *} +{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[17:18] *} ## Description from docstring { #description-from-docstring } @@ -70,7 +70,7 @@ It will be used in the interactive docs: You can specify the response description with the parameter `response_description`: -{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[19] *} +{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[18] *} /// info diff --git a/docs_src/app_testing/app_b_an_py310/main.py b/docs_src/app_testing/app_b_an_py310/main.py index c5952be0b3..120289f56d 100644 --- a/docs_src/app_testing/app_b_an_py310/main.py +++ b/docs_src/app_testing/app_b_an_py310/main.py @@ -28,8 +28,8 @@ async def read_main(item_id: str, x_token: Annotated[str, Header()]): return fake_db[item_id] -@app.post("/items/", response_model=Item) -async def create_item(item: Item, x_token: Annotated[str, Header()]): +@app.post("/items/") +async def create_item(item: Item, x_token: Annotated[str, Header()]) -> Item: if x_token != fake_secret_token: raise HTTPException(status_code=400, detail="Invalid X-Token header") if item.id in fake_db: diff --git a/docs_src/app_testing/app_b_an_py39/main.py b/docs_src/app_testing/app_b_an_py39/main.py index 142e23a26a..801d5f21ea 100644 --- a/docs_src/app_testing/app_b_an_py39/main.py +++ b/docs_src/app_testing/app_b_an_py39/main.py @@ -28,8 +28,8 @@ async def read_main(item_id: str, x_token: Annotated[str, Header()]): return fake_db[item_id] -@app.post("/items/", response_model=Item) -async def create_item(item: Item, x_token: Annotated[str, Header()]): +@app.post("/items/") +async def create_item(item: Item, x_token: Annotated[str, Header()]) -> Item: if x_token != fake_secret_token: raise HTTPException(status_code=400, detail="Invalid X-Token header") if item.id in fake_db: diff --git a/docs_src/app_testing/app_b_py310/main.py b/docs_src/app_testing/app_b_py310/main.py index eccedcc7ce..6c5c341308 100644 --- a/docs_src/app_testing/app_b_py310/main.py +++ b/docs_src/app_testing/app_b_py310/main.py @@ -26,8 +26,8 @@ async def read_main(item_id: str, x_token: str = Header()): return fake_db[item_id] -@app.post("/items/", response_model=Item) -async def create_item(item: Item, x_token: str = Header()): +@app.post("/items/") +async def create_item(item: Item, x_token: str = Header()) -> Item: if x_token != fake_secret_token: raise HTTPException(status_code=400, detail="Invalid X-Token header") if item.id in fake_db: diff --git a/docs_src/app_testing/app_b_py39/main.py b/docs_src/app_testing/app_b_py39/main.py index 45a1033783..89053c432c 100644 --- a/docs_src/app_testing/app_b_py39/main.py +++ b/docs_src/app_testing/app_b_py39/main.py @@ -28,8 +28,8 @@ async def read_main(item_id: str, x_token: str = Header()): return fake_db[item_id] -@app.post("/items/", response_model=Item) -async def create_item(item: Item, x_token: str = Header()): +@app.post("/items/") +async def create_item(item: Item, x_token: str = Header()) -> Item: if x_token != fake_secret_token: raise HTTPException(status_code=400, detail="Invalid X-Token header") if item.id in fake_db: diff --git a/docs_src/body_updates/tutorial002_py310.py b/docs_src/body_updates/tutorial002_py310.py index e5db711108..d30e41027c 100644 --- a/docs_src/body_updates/tutorial002_py310.py +++ b/docs_src/body_updates/tutorial002_py310.py @@ -25,8 +25,8 @@ async def read_item(item_id: str): return items[item_id] -@app.patch("/items/{item_id}", response_model=Item) -async def update_item(item_id: str, item: Item): +@app.patch("/items/{item_id}") +async def update_item(item_id: str, item: Item) -> Item: stored_item_data = items[item_id] stored_item_model = Item(**stored_item_data) update_data = item.model_dump(exclude_unset=True) diff --git a/docs_src/body_updates/tutorial002_py39.py b/docs_src/body_updates/tutorial002_py39.py index eddd7af716..3714b5a55d 100644 --- a/docs_src/body_updates/tutorial002_py39.py +++ b/docs_src/body_updates/tutorial002_py39.py @@ -27,8 +27,8 @@ async def read_item(item_id: str): return items[item_id] -@app.patch("/items/{item_id}", response_model=Item) -async def update_item(item_id: str, item: Item): +@app.patch("/items/{item_id}") +async def update_item(item_id: str, item: Item) -> Item: stored_item_data = items[item_id] stored_item_model = Item(**stored_item_data) update_data = item.model_dump(exclude_unset=True) diff --git a/docs_src/path_operation_advanced_configuration/tutorial004_py310.py b/docs_src/path_operation_advanced_configuration/tutorial004_py310.py index a815a564b7..f222b11dc6 100644 --- a/docs_src/path_operation_advanced_configuration/tutorial004_py310.py +++ b/docs_src/path_operation_advanced_configuration/tutorial004_py310.py @@ -12,8 +12,8 @@ class Item(BaseModel): tags: set[str] = set() -@app.post("/items/", response_model=Item, summary="Create an item") -async def create_item(item: Item): +@app.post("/items/", summary="Create an item") +async def create_item(item: Item) -> Item: """ Create an item with all the information: diff --git a/docs_src/path_operation_advanced_configuration/tutorial004_py39.py b/docs_src/path_operation_advanced_configuration/tutorial004_py39.py index d5fe6705ca..8fabe7cb80 100644 --- a/docs_src/path_operation_advanced_configuration/tutorial004_py39.py +++ b/docs_src/path_operation_advanced_configuration/tutorial004_py39.py @@ -14,8 +14,8 @@ class Item(BaseModel): tags: set[str] = set() -@app.post("/items/", response_model=Item, summary="Create an item") -async def create_item(item: Item): +@app.post("/items/", summary="Create an item") +async def create_item(item: Item) -> Item: """ Create an item with all the information: diff --git a/docs_src/path_operation_configuration/tutorial001_py310.py b/docs_src/path_operation_configuration/tutorial001_py310.py index da078fdf58..2e7488ea4f 100644 --- a/docs_src/path_operation_configuration/tutorial001_py310.py +++ b/docs_src/path_operation_configuration/tutorial001_py310.py @@ -12,6 +12,6 @@ class Item(BaseModel): tags: set[str] = set() -@app.post("/items/", response_model=Item, status_code=status.HTTP_201_CREATED) -async def create_item(item: Item): +@app.post("/items/", status_code=status.HTTP_201_CREATED) +async def create_item(item: Item) -> Item: return item diff --git a/docs_src/path_operation_configuration/tutorial001_py39.py b/docs_src/path_operation_configuration/tutorial001_py39.py index a9dcbf3898..09b3182821 100644 --- a/docs_src/path_operation_configuration/tutorial001_py39.py +++ b/docs_src/path_operation_configuration/tutorial001_py39.py @@ -14,6 +14,6 @@ class Item(BaseModel): tags: set[str] = set() -@app.post("/items/", response_model=Item, status_code=status.HTTP_201_CREATED) -async def create_item(item: Item): +@app.post("/items/", status_code=status.HTTP_201_CREATED) +async def create_item(item: Item) -> Item: return item diff --git a/docs_src/path_operation_configuration/tutorial002_py310.py b/docs_src/path_operation_configuration/tutorial002_py310.py index 9a8af54327..59908ed7c8 100644 --- a/docs_src/path_operation_configuration/tutorial002_py310.py +++ b/docs_src/path_operation_configuration/tutorial002_py310.py @@ -12,8 +12,8 @@ class Item(BaseModel): tags: set[str] = set() -@app.post("/items/", response_model=Item, tags=["items"]) -async def create_item(item: Item): +@app.post("/items/", tags=["items"]) +async def create_item(item: Item) -> Item: return item diff --git a/docs_src/path_operation_configuration/tutorial002_py39.py b/docs_src/path_operation_configuration/tutorial002_py39.py index e7ced7de7e..fca3b0de9e 100644 --- a/docs_src/path_operation_configuration/tutorial002_py39.py +++ b/docs_src/path_operation_configuration/tutorial002_py39.py @@ -14,8 +14,8 @@ class Item(BaseModel): tags: set[str] = set() -@app.post("/items/", response_model=Item, tags=["items"]) -async def create_item(item: Item): +@app.post("/items/", tags=["items"]) +async def create_item(item: Item) -> Item: return item diff --git a/docs_src/path_operation_configuration/tutorial003_py310.py b/docs_src/path_operation_configuration/tutorial003_py310.py index 3d94afe2c0..56bd7e36aa 100644 --- a/docs_src/path_operation_configuration/tutorial003_py310.py +++ b/docs_src/path_operation_configuration/tutorial003_py310.py @@ -14,9 +14,8 @@ class Item(BaseModel): @app.post( "/items/", - response_model=Item, summary="Create an item", description="Create an item with all the information, name, description, price, tax and a set of unique tags", ) -async def create_item(item: Item): +async def create_item(item: Item) -> Item: return item diff --git a/docs_src/path_operation_configuration/tutorial003_py39.py b/docs_src/path_operation_configuration/tutorial003_py39.py index 607c5707e6..a77fb34d89 100644 --- a/docs_src/path_operation_configuration/tutorial003_py39.py +++ b/docs_src/path_operation_configuration/tutorial003_py39.py @@ -16,9 +16,8 @@ class Item(BaseModel): @app.post( "/items/", - response_model=Item, summary="Create an item", description="Create an item with all the information, name, description, price, tax and a set of unique tags", ) -async def create_item(item: Item): +async def create_item(item: Item) -> Item: return item diff --git a/docs_src/path_operation_configuration/tutorial004_py310.py b/docs_src/path_operation_configuration/tutorial004_py310.py index 4cb8bdd438..44404aa083 100644 --- a/docs_src/path_operation_configuration/tutorial004_py310.py +++ b/docs_src/path_operation_configuration/tutorial004_py310.py @@ -12,8 +12,8 @@ class Item(BaseModel): tags: set[str] = set() -@app.post("/items/", response_model=Item, summary="Create an item") -async def create_item(item: Item): +@app.post("/items/", summary="Create an item") +async def create_item(item: Item) -> Item: """ Create an item with all the information: diff --git a/docs_src/path_operation_configuration/tutorial004_py39.py b/docs_src/path_operation_configuration/tutorial004_py39.py index fc25680c5a..31dfbff1d2 100644 --- a/docs_src/path_operation_configuration/tutorial004_py39.py +++ b/docs_src/path_operation_configuration/tutorial004_py39.py @@ -14,8 +14,8 @@ class Item(BaseModel): tags: set[str] = set() -@app.post("/items/", response_model=Item, summary="Create an item") -async def create_item(item: Item): +@app.post("/items/", summary="Create an item") +async def create_item(item: Item) -> Item: """ Create an item with all the information: diff --git a/docs_src/path_operation_configuration/tutorial005_py310.py b/docs_src/path_operation_configuration/tutorial005_py310.py index b176631d84..a4129d600a 100644 --- a/docs_src/path_operation_configuration/tutorial005_py310.py +++ b/docs_src/path_operation_configuration/tutorial005_py310.py @@ -14,11 +14,10 @@ class Item(BaseModel): @app.post( "/items/", - response_model=Item, summary="Create an item", response_description="The created item", ) -async def create_item(item: Item): +async def create_item(item: Item) -> Item: """ Create an item with all the information: diff --git a/docs_src/path_operation_configuration/tutorial005_py39.py b/docs_src/path_operation_configuration/tutorial005_py39.py index ddf29b733d..0a53a8f2dd 100644 --- a/docs_src/path_operation_configuration/tutorial005_py39.py +++ b/docs_src/path_operation_configuration/tutorial005_py39.py @@ -16,11 +16,10 @@ class Item(BaseModel): @app.post( "/items/", - response_model=Item, summary="Create an item", response_description="The created item", ) -async def create_item(item: Item): +async def create_item(item: Item) -> Item: """ Create an item with all the information: diff --git a/docs_src/security/tutorial004_an_py310.py b/docs_src/security/tutorial004_an_py310.py index 18ea96bc5c..368c743bf9 100644 --- a/docs_src/security/tutorial004_an_py310.py +++ b/docs_src/security/tutorial004_an_py310.py @@ -133,10 +133,10 @@ async def login_for_access_token( return Token(access_token=access_token, token_type="bearer") -@app.get("/users/me/", response_model=User) +@app.get("/users/me/") async def read_users_me( current_user: Annotated[User, Depends(get_current_active_user)], -): +) -> User: return current_user diff --git a/docs_src/security/tutorial004_an_py39.py b/docs_src/security/tutorial004_an_py39.py index d3fd29e5a5..73b3d456d1 100644 --- a/docs_src/security/tutorial004_an_py39.py +++ b/docs_src/security/tutorial004_an_py39.py @@ -133,10 +133,10 @@ async def login_for_access_token( return Token(access_token=access_token, token_type="bearer") -@app.get("/users/me/", response_model=User) +@app.get("/users/me/") async def read_users_me( current_user: Annotated[User, Depends(get_current_active_user)], -): +) -> User: return current_user diff --git a/docs_src/security/tutorial004_py310.py b/docs_src/security/tutorial004_py310.py index cd1dcff460..8d0785b404 100644 --- a/docs_src/security/tutorial004_py310.py +++ b/docs_src/security/tutorial004_py310.py @@ -130,8 +130,8 @@ async def login_for_access_token( return Token(access_token=access_token, token_type="bearer") -@app.get("/users/me/", response_model=User) -async def read_users_me(current_user: User = Depends(get_current_active_user)): +@app.get("/users/me/") +async def read_users_me(current_user: User = Depends(get_current_active_user)) -> User: return current_user diff --git a/docs_src/security/tutorial004_py39.py b/docs_src/security/tutorial004_py39.py index 130dc699a0..e67403d5d7 100644 --- a/docs_src/security/tutorial004_py39.py +++ b/docs_src/security/tutorial004_py39.py @@ -131,8 +131,8 @@ async def login_for_access_token( return Token(access_token=access_token, token_type="bearer") -@app.get("/users/me/", response_model=User) -async def read_users_me(current_user: User = Depends(get_current_active_user)): +@app.get("/users/me/") +async def read_users_me(current_user: User = Depends(get_current_active_user)) -> User: return current_user diff --git a/docs_src/security/tutorial005_an_py310.py b/docs_src/security/tutorial005_an_py310.py index df55951c07..fef0ab71ca 100644 --- a/docs_src/security/tutorial005_an_py310.py +++ b/docs_src/security/tutorial005_an_py310.py @@ -160,10 +160,10 @@ async def login_for_access_token( return Token(access_token=access_token, token_type="bearer") -@app.get("/users/me/", response_model=User) +@app.get("/users/me/") async def read_users_me( current_user: Annotated[User, Depends(get_current_active_user)], -): +) -> User: return current_user diff --git a/docs_src/security/tutorial005_an_py39.py b/docs_src/security/tutorial005_an_py39.py index 983c1c22cf..1aeba688a6 100644 --- a/docs_src/security/tutorial005_an_py39.py +++ b/docs_src/security/tutorial005_an_py39.py @@ -160,10 +160,10 @@ async def login_for_access_token( return Token(access_token=access_token, token_type="bearer") -@app.get("/users/me/", response_model=User) +@app.get("/users/me/") async def read_users_me( current_user: Annotated[User, Depends(get_current_active_user)], -): +) -> User: return current_user diff --git a/docs_src/security/tutorial005_py310.py b/docs_src/security/tutorial005_py310.py index d08e2c59f3..412fbf7984 100644 --- a/docs_src/security/tutorial005_py310.py +++ b/docs_src/security/tutorial005_py310.py @@ -159,8 +159,8 @@ async def login_for_access_token( return Token(access_token=access_token, token_type="bearer") -@app.get("/users/me/", response_model=User) -async def read_users_me(current_user: User = Depends(get_current_active_user)): +@app.get("/users/me/") +async def read_users_me(current_user: User = Depends(get_current_active_user)) -> User: return current_user diff --git a/docs_src/security/tutorial005_py39.py b/docs_src/security/tutorial005_py39.py index 5bde47ef47..32280aa48b 100644 --- a/docs_src/security/tutorial005_py39.py +++ b/docs_src/security/tutorial005_py39.py @@ -160,8 +160,8 @@ async def login_for_access_token( return Token(access_token=access_token, token_type="bearer") -@app.get("/users/me/", response_model=User) -async def read_users_me(current_user: User = Depends(get_current_active_user)): +@app.get("/users/me/") +async def read_users_me(current_user: User = Depends(get_current_active_user)) -> User: return current_user From 5083f27e034ee3b1b3dad459bb420596a952e769 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 12:07:48 +0000 Subject: [PATCH 072/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 30704f3e52..819c58897f 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -13,6 +13,7 @@ hide: ### Docs +* 📝 Use return type annotation instead of `response_model` when possible. PR [#14753](https://github.com/fastapi/fastapi/pull/14753) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Use `WSGIMiddleware` from `a2wsgi` instead of deprecated `fastapi.middleware.wsgi.WSGIMiddleware`. PR [#14756](https://github.com/fastapi/fastapi/pull/14756) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Fix minor typos in release notes. PR [#14780](https://github.com/fastapi/fastapi/pull/14780) by [@whyvineet](https://github.com/whyvineet). * 🐛 Fix copy button in custom.js. PR [#14722](https://github.com/fastapi/fastapi/pull/14722) by [@fcharrier](https://github.com/fcharrier). From 21b7b0893b43c1ea359a62b0ec74323d533635fb Mon Sep 17 00:00:00 2001 From: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> Date: Wed, 4 Feb 2026 15:30:47 +0300 Subject: [PATCH 073/108] =?UTF-8?q?=F0=9F=93=9D=20Fix=20dependency=20insta?= =?UTF-8?q?llation=20command=20in=20`docs/en/docs/contributing.md`=20(#147?= =?UTF-8?q?57)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/contributing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/en/docs/contributing.md b/docs/en/docs/contributing.md index a4d896109b..1505dfd1e9 100644 --- a/docs/en/docs/contributing.md +++ b/docs/en/docs/contributing.md @@ -13,7 +13,7 @@ Create a virtual environment and install the required packages with ```console -$ uv sync +$ uv sync --extra all ---> 100% ``` @@ -32,9 +32,9 @@ That way, you don't have to "install" your local version to be able to test ever /// note | Technical Details -This only happens when you install using `uv sync` instead of running `pip install fastapi` directly. +This only happens when you install using `uv sync --extra all` instead of running `pip install fastapi` directly. -That is because `uv sync` will install the local version of FastAPI in "editable" mode by default. +That is because `uv sync --extra all` will install the local version of FastAPI in "editable" mode by default. /// From 938c5f3500f4b052ecb5bf73c7ef9058607bfd31 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 12:31:13 +0000 Subject: [PATCH 074/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 819c58897f..926a26a304 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -13,6 +13,7 @@ hide: ### Docs +* 📝 Fix dependency installation command in `docs/en/docs/contributing.md`. PR [#14757](https://github.com/fastapi/fastapi/pull/14757) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Use return type annotation instead of `response_model` when possible. PR [#14753](https://github.com/fastapi/fastapi/pull/14753) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Use `WSGIMiddleware` from `a2wsgi` instead of deprecated `fastapi.middleware.wsgi.WSGIMiddleware`. PR [#14756](https://github.com/fastapi/fastapi/pull/14756) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Fix minor typos in release notes. PR [#14780](https://github.com/fastapi/fastapi/pull/14780) by [@whyvineet](https://github.com/whyvineet). From 4414286f2c2bfad302dd87637641d635e9a45c00 Mon Sep 17 00:00:00 2001 From: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> Date: Wed, 4 Feb 2026 15:33:07 +0300 Subject: [PATCH 075/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20embedded=20code?= =?UTF-8?q?=20examples=20to=20Python=203.10=20syntax=20(#14758)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 18 ++++++------------ docs/en/docs/deployment/docker.md | 4 +--- docs/en/docs/index.md | 18 ++++++------------ docs/en/docs/tutorial/body-multiple-params.md | 11 ++++++----- 4 files changed, 19 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 1057b86942..963de51edf 100644 --- a/README.md +++ b/README.md @@ -164,8 +164,6 @@ $ pip install "fastapi[standard]" Create a file `main.py` with: ```Python -from typing import Union - from fastapi import FastAPI app = FastAPI() @@ -177,7 +175,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Union[str, None] = None): +def read_item(item_id: int, q: str | None = None): return {"item_id": item_id, "q": q} ``` @@ -186,9 +184,7 @@ def read_item(item_id: int, q: Union[str, None] = None): If your code uses `async` / `await`, use `async def`: -```Python hl_lines="9 14" -from typing import Union - +```Python hl_lines="7 12" from fastapi import FastAPI app = FastAPI() @@ -200,7 +196,7 @@ async def read_root(): @app.get("/items/{item_id}") -async def read_item(item_id: int, q: Union[str, None] = None): +async def read_item(item_id: int, q: str | None = None): return {"item_id": item_id, "q": q} ``` @@ -291,9 +287,7 @@ Now modify the file `main.py` to receive a body from a `PUT` request. Declare the body using standard Python types, thanks to Pydantic. -```Python hl_lines="4 9-12 25-27" -from typing import Union - +```Python hl_lines="2 7-10 23-25" from fastapi import FastAPI from pydantic import BaseModel @@ -303,7 +297,7 @@ app = FastAPI() class Item(BaseModel): name: str price: float - is_offer: Union[bool, None] = None + is_offer: bool | None = None @app.get("/") @@ -312,7 +306,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Union[str, None] = None): +def read_item(item_id: int, q: str | None = None): return {"item_id": item_id, "q": q} diff --git a/docs/en/docs/deployment/docker.md b/docs/en/docs/deployment/docker.md index 6b71f7360d..7219f3afca 100644 --- a/docs/en/docs/deployment/docker.md +++ b/docs/en/docs/deployment/docker.md @@ -145,8 +145,6 @@ There are other formats and tools to define and install package dependencies. * Create a `main.py` file with: ```Python -from typing import Union - from fastapi import FastAPI app = FastAPI() @@ -158,7 +156,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Union[str, None] = None): +def read_item(item_id: int, q: str | None = None): return {"item_id": item_id, "q": q} ``` diff --git a/docs/en/docs/index.md b/docs/en/docs/index.md index 5eb47c7b32..ff0f4e9d9d 100644 --- a/docs/en/docs/index.md +++ b/docs/en/docs/index.md @@ -161,8 +161,6 @@ $ pip install "fastapi[standard]" Create a file `main.py` with: ```Python -from typing import Union - from fastapi import FastAPI app = FastAPI() @@ -174,7 +172,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Union[str, None] = None): +def read_item(item_id: int, q: str | None = None): return {"item_id": item_id, "q": q} ``` @@ -183,9 +181,7 @@ def read_item(item_id: int, q: Union[str, None] = None): If your code uses `async` / `await`, use `async def`: -```Python hl_lines="9 14" -from typing import Union - +```Python hl_lines="7 12" from fastapi import FastAPI app = FastAPI() @@ -197,7 +193,7 @@ async def read_root(): @app.get("/items/{item_id}") -async def read_item(item_id: int, q: Union[str, None] = None): +async def read_item(item_id: int, q: str | None = None): return {"item_id": item_id, "q": q} ``` @@ -288,9 +284,7 @@ Now modify the file `main.py` to receive a body from a `PUT` request. Declare the body using standard Python types, thanks to Pydantic. -```Python hl_lines="4 9-12 25-27" -from typing import Union - +```Python hl_lines="2 7-10 23-25" from fastapi import FastAPI from pydantic import BaseModel @@ -300,7 +294,7 @@ app = FastAPI() class Item(BaseModel): name: str price: float - is_offer: Union[bool, None] = None + is_offer: bool | None = None @app.get("/") @@ -309,7 +303,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Union[str, None] = None): +def read_item(item_id: int, q: str | None = None): return {"item_id": item_id, "q": q} diff --git a/docs/en/docs/tutorial/body-multiple-params.md b/docs/en/docs/tutorial/body-multiple-params.md index ed23c81490..bb0c583685 100644 --- a/docs/en/docs/tutorial/body-multiple-params.md +++ b/docs/en/docs/tutorial/body-multiple-params.md @@ -102,15 +102,16 @@ Of course, you can also declare additional query parameters whenever you need, a As, by default, singular values are interpreted as query parameters, you don't have to explicitly add a `Query`, you can just do: +```Python +q: str | None = None +``` + +Or in Python 3.9: + ```Python q: Union[str, None] = None ``` -Or in Python 3.10 and above: - -```Python -q: str | None = None -``` For example: From c9e512d808de5eb4196aaaf11ceebf0e9500e55b Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 12:33:37 +0000 Subject: [PATCH 076/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 926a26a304..d5bc816683 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -13,6 +13,7 @@ hide: ### Docs +* 📝 Update embedded code examples to Python 3.10 syntax. PR [#14758](https://github.com/fastapi/fastapi/pull/14758) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Fix dependency installation command in `docs/en/docs/contributing.md`. PR [#14757](https://github.com/fastapi/fastapi/pull/14757) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Use return type annotation instead of `response_model` when possible. PR [#14753](https://github.com/fastapi/fastapi/pull/14753) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Use `WSGIMiddleware` from `a2wsgi` instead of deprecated `fastapi.middleware.wsgi.WSGIMiddleware`. PR [#14756](https://github.com/fastapi/fastapi/pull/14756) by [@YuriiMotov](https://github.com/YuriiMotov). From 3a41403ccda1a727135fec91dea118ad8f2cf50a Mon Sep 17 00:00:00 2001 From: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> Date: Wed, 4 Feb 2026 15:41:54 +0300 Subject: [PATCH 077/108] =?UTF-8?q?=F0=9F=93=9D=20Add=20links=20to=20relat?= =?UTF-8?q?ed=20sections=20of=20docs=20to=20docstrings=20(#14776)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: github-actions[bot] --- docs/en/docs/reference/request.md | 2 + docs/en/docs/reference/response.md | 2 + docs/en/docs/reference/responses.md | 2 + docs/en/docs/reference/security/index.md | 2 + docs/en/docs/reference/websockets.md | 24 +++--- fastapi/applications.py | 7 +- fastapi/exceptions.py | 10 +++ fastapi/openapi/docs.py | 30 ++++++++ fastapi/param_functions.py | 94 +++++++++++++++++++++++- fastapi/security/oauth2.py | 30 ++++++++ 10 files changed, 190 insertions(+), 13 deletions(-) diff --git a/docs/en/docs/reference/request.md b/docs/en/docs/reference/request.md index f1de216424..7994bf8a88 100644 --- a/docs/en/docs/reference/request.md +++ b/docs/en/docs/reference/request.md @@ -2,6 +2,8 @@ You can declare a parameter in a *path operation function* or dependency to be of type `Request` and then you can access the raw request object directly, without any validation, etc. +Read more about it in the [FastAPI docs about using Request directly](https://fastapi.tiangolo.com/advanced/using-request-directly/) + You can import it directly from `fastapi`: ```python diff --git a/docs/en/docs/reference/response.md b/docs/en/docs/reference/response.md index 00cf2c499c..c9085766c9 100644 --- a/docs/en/docs/reference/response.md +++ b/docs/en/docs/reference/response.md @@ -4,6 +4,8 @@ You can declare a parameter in a *path operation function* or dependency to be o You can also use it directly to create an instance of it and return it from your *path operations*. +Read more about it in the [FastAPI docs about returning a custom Response](https://fastapi.tiangolo.com/advanced/response-directly/#returning-a-custom-response) + You can import it directly from `fastapi`: ```python diff --git a/docs/en/docs/reference/responses.md b/docs/en/docs/reference/responses.md index 46f014fcc8..bd57861294 100644 --- a/docs/en/docs/reference/responses.md +++ b/docs/en/docs/reference/responses.md @@ -56,6 +56,8 @@ There are a couple of custom FastAPI response classes, you can use them to optim ## Starlette Responses +You can read more about all of them in the [FastAPI docs for Custom Response](https://fastapi.tiangolo.com/advanced/custom-response/) and in the [Starlette docs about Responses](https://starlette.dev/responses/). + ::: fastapi.responses.FileResponse options: members: diff --git a/docs/en/docs/reference/security/index.md b/docs/en/docs/reference/security/index.md index 9a5c5e15fb..8163aa2df2 100644 --- a/docs/en/docs/reference/security/index.md +++ b/docs/en/docs/reference/security/index.md @@ -28,6 +28,8 @@ from fastapi.security import ( ) ``` +Read more about them in the [FastAPI docs about Security](https://fastapi.tiangolo.com/tutorial/security/). + ## API Key Security Schemes ::: fastapi.security.APIKeyCookie diff --git a/docs/en/docs/reference/websockets.md b/docs/en/docs/reference/websockets.md index 4b7244e080..bd9f438be6 100644 --- a/docs/en/docs/reference/websockets.md +++ b/docs/en/docs/reference/websockets.md @@ -2,6 +2,8 @@ When defining WebSockets, you normally declare a parameter of type `WebSocket` and with it you can read data from the client and send data to it. +Read more about it in the [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/) + It is provided directly by Starlette, but you can import it from `fastapi`: ```python @@ -44,16 +46,6 @@ When you want to define dependencies that should be compatible with both HTTP an - send_json - close -When a client disconnects, a `WebSocketDisconnect` exception is raised, you can catch it. - -You can import it directly form `fastapi`: - -```python -from fastapi import WebSocketDisconnect -``` - -::: fastapi.WebSocketDisconnect - ## WebSockets - additional classes Additional classes for handling WebSockets. @@ -66,4 +58,16 @@ from fastapi.websockets import WebSocketDisconnect, WebSocketState ::: fastapi.websockets.WebSocketDisconnect +When a client disconnects, a `WebSocketDisconnect` exception is raised, you can catch it. + +You can import it directly form `fastapi`: + +```python +from fastapi import WebSocketDisconnect +``` + +Read more about it in the [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/#handling-disconnections-and-multiple-clients) + ::: fastapi.websockets.WebSocketState + +`WebSocketState` is an enumeration of the possible states of a WebSocket connection. diff --git a/fastapi/applications.py b/fastapi/applications.py index 54175cb3b0..340cabfc29 100644 --- a/fastapi/applications.py +++ b/fastapi/applications.py @@ -672,7 +672,7 @@ class FastAPI(Starlette): in the autogenerated OpenAPI using the `root_path`. Read more about it in the - [FastAPI docs for Behind a Proxy](https://fastapi.tiangolo.com/advanced/behind-a-proxy/#disable-automatic-server-from-root_path). + [FastAPI docs for Behind a Proxy](https://fastapi.tiangolo.com/advanced/behind-a-proxy/#disable-automatic-server-from-root-path). **Example** @@ -739,7 +739,7 @@ class FastAPI(Starlette): It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the - [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#deprecate-a-path-operation). """ ), ] = None, @@ -812,6 +812,9 @@ class FastAPI(Starlette): In this case, there would be two different schemas, one for input and another one for output. + + Read more about it in the + [FastAPI docs about how to separate schemas for input and output](https://fastapi.tiangolo.com/how-to/separate-openapi-schemas) """ ), ] = True, diff --git a/fastapi/exceptions.py b/fastapi/exceptions.py index 1a3abd80c2..62b4674de3 100644 --- a/fastapi/exceptions.py +++ b/fastapi/exceptions.py @@ -49,6 +49,9 @@ class HTTPException(StarletteHTTPException): Doc( """ HTTP status code to send to the client. + + Read more about it in the + [FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/#use-httpexception) """ ), ], @@ -58,6 +61,9 @@ class HTTPException(StarletteHTTPException): """ Any data to be sent to the client in the `detail` key of the JSON response. + + Read more about it in the + [FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/#use-httpexception) """ ), ] = None, @@ -66,6 +72,10 @@ class HTTPException(StarletteHTTPException): Doc( """ Any headers to send to the client in the response. + + Read more about it in the + [FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/#add-custom-headers) + """ ), ] = None, diff --git a/fastapi/openapi/docs.py b/fastapi/openapi/docs.py index 82380f85d9..632cc2c1d9 100644 --- a/fastapi/openapi/docs.py +++ b/fastapi/openapi/docs.py @@ -33,6 +33,9 @@ def get_swagger_ui_html( This is normally done automatically by FastAPI using the default URL `/openapi.json`. + + Read more about it in the + [FastAPI docs for Conditional OpenAPI](https://fastapi.tiangolo.com/how-to/conditional-openapi/#conditional-openapi-from-settings-and-env-vars) """ ), ], @@ -41,6 +44,9 @@ def get_swagger_ui_html( Doc( """ The HTML `` content, normally shown in the browser tab. + + Read more about it in the + [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/) """ ), ], @@ -51,6 +57,9 @@ def get_swagger_ui_html( The URL to use to load the Swagger UI JavaScript. It is normally set to a CDN URL. + + Read more about it in the + [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/) """ ), ] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js", @@ -61,6 +70,9 @@ def get_swagger_ui_html( The URL to use to load the Swagger UI CSS. It is normally set to a CDN URL. + + Read more about it in the + [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/) """ ), ] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css", @@ -77,6 +89,9 @@ def get_swagger_ui_html( Doc( """ The OAuth2 redirect URL, it is normally automatically handled by FastAPI. + + Read more about it in the + [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/) """ ), ] = None, @@ -85,6 +100,9 @@ def get_swagger_ui_html( Doc( """ A dictionary with Swagger UI OAuth2 initialization configurations. + + Read more about the available configuration options in the + [Swagger UI docs](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/). """ ), ] = None, @@ -95,6 +113,9 @@ def get_swagger_ui_html( Configuration parameters for Swagger UI. It defaults to [swagger_ui_default_parameters][fastapi.openapi.docs.swagger_ui_default_parameters]. + + Read more about it in the + [FastAPI docs about how to Configure Swagger UI](https://fastapi.tiangolo.com/how-to/configure-swagger-ui/). """ ), ] = None, @@ -168,6 +189,9 @@ def get_redoc_html( This is normally done automatically by FastAPI using the default URL `/openapi.json`. + + Read more about it in the + [FastAPI docs for Conditional OpenAPI](https://fastapi.tiangolo.com/how-to/conditional-openapi/#conditional-openapi-from-settings-and-env-vars) """ ), ], @@ -176,6 +200,9 @@ def get_redoc_html( Doc( """ The HTML `<title>` content, normally shown in the browser tab. + + Read more about it in the + [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/) """ ), ], @@ -186,6 +213,9 @@ def get_redoc_html( The URL to use to load the ReDoc JavaScript. It is normally set to a CDN URL. + + Read more about it in the + [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/) """ ), ] = "https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js", diff --git a/fastapi/param_functions.py b/fastapi/param_functions.py index 0834fd741a..9bd92be4c7 100644 --- a/fastapi/param_functions.py +++ b/fastapi/param_functions.py @@ -79,6 +79,9 @@ def Path( # noqa: N802 Doc( """ Human-readable title. + + Read more about it in the + [FastAPI docs for Path Parameters and Numeric Validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#declare-metadata) """ ), ] = None, @@ -96,6 +99,9 @@ def Path( # noqa: N802 """ Greater than. If set, value must be greater than this. Only applicable to numbers. + + Read more about it in the + [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal) """ ), ] = None, @@ -105,6 +111,9 @@ def Path( # noqa: N802 """ Greater than or equal. If set, value must be greater than or equal to this. Only applicable to numbers. + + Read more about it in the + [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal) """ ), ] = None, @@ -113,6 +122,9 @@ def Path( # noqa: N802 Doc( """ Less than. If set, value must be less than this. Only applicable to numbers. + + Read more about it in the + [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal) """ ), ] = None, @@ -122,6 +134,9 @@ def Path( # noqa: N802 """ Less than or equal. If set, value must be less than or equal to this. Only applicable to numbers. + + Read more about it in the + [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal) """ ), ] = None, @@ -213,6 +228,9 @@ def Path( # noqa: N802 Doc( """ Example values for this field. + + Read more about it in the + [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/) """ ), ] = None, @@ -343,6 +361,9 @@ def Query( # noqa: N802 Doc( """ Default value if the parameter field is not set. + + Read more about it in the + [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#alternative-old-query-as-the-default-value) """ ), ] = Undefined, @@ -367,6 +388,9 @@ def Query( # noqa: N802 This will be used to extract the data and for the generated OpenAPI. It is particularly useful when you can't use the name you want because it is a Python reserved keyword or similar. + + Read more about it in the + [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#alias-parameters) """ ), ] = None, @@ -402,6 +426,9 @@ def Query( # noqa: N802 Doc( """ Human-readable title. + + Read more about it in the + [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#declare-more-metadata) """ ), ] = None, @@ -410,6 +437,9 @@ def Query( # noqa: N802 Doc( """ Human-readable description. + + Read more about it in the + [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#declare-more-metadata) """ ), ] = None, @@ -419,6 +449,9 @@ def Query( # noqa: N802 """ Greater than. If set, value must be greater than this. Only applicable to numbers. + + Read more about it in the + [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal) """ ), ] = None, @@ -428,6 +461,9 @@ def Query( # noqa: N802 """ Greater than or equal. If set, value must be greater than or equal to this. Only applicable to numbers. + + Read more about it in the + [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal) """ ), ] = None, @@ -436,6 +472,9 @@ def Query( # noqa: N802 Doc( """ Less than. If set, value must be less than this. Only applicable to numbers. + + Read more about it in the + [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal) """ ), ] = None, @@ -445,6 +484,9 @@ def Query( # noqa: N802 """ Less than or equal. If set, value must be less than or equal to this. Only applicable to numbers. + + Read more about it in the + [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal) """ ), ] = None, @@ -453,6 +495,9 @@ def Query( # noqa: N802 Doc( """ Minimum length for strings. + + Read more about it in the + [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/) """ ), ] = None, @@ -461,6 +506,9 @@ def Query( # noqa: N802 Doc( """ Maximum length for strings. + + Read more about it in the + [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/) """ ), ] = None, @@ -469,6 +517,9 @@ def Query( # noqa: N802 Doc( """ RegEx pattern for strings. + + Read more about it in the + [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#add-regular-expressions """ ), ] = None, @@ -536,6 +587,9 @@ def Query( # noqa: N802 Doc( """ Example values for this field. + + Read more about it in the + [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/) """ ), ] = None, @@ -570,6 +624,9 @@ def Query( # noqa: N802 Mark this parameter field as deprecated. It will affect the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#deprecating-parameters) """ ), ] = None, @@ -581,6 +638,9 @@ def Query( # noqa: N802 You probably don't need it, but it's available. This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi """ ), ] = True, @@ -849,6 +909,9 @@ def Header( # noqa: N802 Doc( """ Example values for this field. + + Read more about it in the + [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/) """ ), ] = None, @@ -1152,6 +1215,9 @@ def Cookie( # noqa: N802 Doc( """ Example values for this field. + + Read more about it in the + [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/) """ ), ] = None, @@ -1477,6 +1543,9 @@ def Body( # noqa: N802 Doc( """ Example values for this field. + + Read more about it in the + [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/) """ ), ] = None, @@ -1790,6 +1859,9 @@ def Form( # noqa: N802 Doc( """ Example values for this field. + + Read more about it in the + [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/) """ ), ] = None, @@ -2102,6 +2174,9 @@ def File( # noqa: N802 Doc( """ Example values for this field. + + Read more about it in the + [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/) """ ), ] = None, @@ -2215,6 +2290,9 @@ def Depends( # noqa: N802 Don't call it directly, FastAPI will call it for you, just pass the object directly. + + Read more about it in the + [FastAPI docs for Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/) """ ), ] = None, @@ -2230,6 +2308,9 @@ def Depends( # noqa: N802 Set `use_cache` to `False` to disable this behavior and ensure the dependency is called again (if declared more than once) in the same request. + + Read more about it in the + [FastAPI docs about sub-dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/sub-dependencies/#using-the-same-dependency-multiple-times) """ ), ] = True, @@ -2250,6 +2331,9 @@ def Depends( # noqa: N802 that handles the request (similar to when using `"function"`), but end **after** the response is sent back to the client. So, the dependency function will be executed **around** the **request** and response cycle. + + Read more about it in the + [FastAPI docs for FastAPI Dependencies with yield](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/#early-exit-and-scope) """ ), ] = None, @@ -2295,6 +2379,9 @@ def Security( # noqa: N802 Don't call it directly, FastAPI will call it for you, just pass the object directly. + + Read more about it in the + [FastAPI docs for Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/) """ ), ] = None, @@ -2312,7 +2399,9 @@ def Security( # noqa: N802 These scopes are integrated with OpenAPI (and the API docs at `/docs`). So they are visible in the OpenAPI specification. - ) + + Read more about it in the + [FastAPI docs about OAuth2 scopes](https://fastapi.tiangolo.com/advanced/security/oauth2-scopes/) """ ), ] = None, @@ -2327,6 +2416,9 @@ def Security( # noqa: N802 Set `use_cache` to `False` to disable this behavior and ensure the dependency is called again (if declared more than once) in the same request. + + Read more about it in the + [FastAPI docs about sub-dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/sub-dependencies/#using-the-same-dependency-multiple-times) """ ), ] = True, diff --git a/fastapi/security/oauth2.py b/fastapi/security/oauth2.py index fc49ba1903..58ffc5c762 100644 --- a/fastapi/security/oauth2.py +++ b/fastapi/security/oauth2.py @@ -68,6 +68,9 @@ class OAuth2PasswordRequestForm: "password". Nevertheless, this dependency class is permissive and allows not passing it. If you want to enforce it, use instead the `OAuth2PasswordRequestFormStrict` dependency. + + Read more about it in the + [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/). """ ), ] = None, @@ -78,6 +81,9 @@ class OAuth2PasswordRequestForm: """ `username` string. The OAuth2 spec requires the exact field name `username`. + + Read more about it in the + [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/). """ ), ], @@ -88,6 +94,9 @@ class OAuth2PasswordRequestForm: """ `password` string. The OAuth2 spec requires the exact field name `password`. + + Read more about it in the + [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/). """ ), ], @@ -112,6 +121,9 @@ class OAuth2PasswordRequestForm: * `users:read` * `profile` * `openid` + + Read more about it in the + [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/). """ ), ] = "", @@ -222,6 +234,9 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm): "password". This dependency is strict about it. If you want to be permissive, use instead the `OAuth2PasswordRequestForm` dependency class. + + Read more about it in the + [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/). """ ), ], @@ -232,6 +247,9 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm): """ `username` string. The OAuth2 spec requires the exact field name `username`. + + Read more about it in the + [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/). """ ), ], @@ -242,6 +260,9 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm): """ `password` string. The OAuth2 spec requires the exact field name `password`. + + Read more about it in the + [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/). """ ), ], @@ -266,6 +287,9 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm): * `users:read` * `profile` * `openid` + + Read more about it in the + [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/). """ ), ] = "", @@ -423,6 +447,9 @@ class OAuth2PasswordBearer(OAuth2): """ The URL to obtain the OAuth2 token. This would be the *path operation* that has `OAuth2PasswordRequestForm` as a dependency. + + Read more about it in the + [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/). """ ), ], @@ -442,6 +469,9 @@ class OAuth2PasswordBearer(OAuth2): """ The OAuth2 scopes that would be required by the *path operations* that use this dependency. + + Read more about it in the + [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/). """ ), ] = None, From 6ab68c62b86c5d222659a37cb2abbd4a52136a94 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com> Date: Wed, 4 Feb 2026 12:42:18 +0000 Subject: [PATCH 078/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index d5bc816683..0c7d440490 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -13,6 +13,7 @@ hide: ### Docs +* 📝 Add links to related sections of docs to docstrings. PR [#14776](https://github.com/fastapi/fastapi/pull/14776) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Update embedded code examples to Python 3.10 syntax. PR [#14758](https://github.com/fastapi/fastapi/pull/14758) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Fix dependency installation command in `docs/en/docs/contributing.md`. PR [#14757](https://github.com/fastapi/fastapi/pull/14757) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Use return type annotation instead of `response_model` when possible. PR [#14753](https://github.com/fastapi/fastapi/pull/14753) by [@YuriiMotov](https://github.com/YuriiMotov). From 08dad5c69fbeac83616226b4d56b6c79b8683767 Mon Sep 17 00:00:00 2001 From: DJ Melisso <DJMcoder@users.noreply.github.com> Date: Wed, 4 Feb 2026 05:23:08 -0800 Subject: [PATCH 079/108] =?UTF-8?q?=F0=9F=90=9B=20Fix=20OpenAPI=20duplicat?= =?UTF-8?q?ion=20of=20`anyOf`=20refs=20for=20app-level=20responses=20with?= =?UTF-8?q?=20specified=20`content`=20and=20`model`=20as=20`Union`=20(#144?= =?UTF-8?q?63)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Co-authored-by: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> --- fastapi/openapi/utils.py | 3 +- ...itional_responses_union_duplicate_anyof.py | 123 ++++++++++++++++++ 2 files changed, 125 insertions(+), 1 deletion(-) create mode 100644 tests/test_additional_responses_union_duplicate_anyof.py diff --git a/fastapi/openapi/utils.py b/fastapi/openapi/utils.py index 75ff261025..d56027b500 100644 --- a/fastapi/openapi/utils.py +++ b/fastapi/openapi/utils.py @@ -1,3 +1,4 @@ +import copy import http.client import inspect import warnings @@ -377,7 +378,7 @@ def get_openapi_path( additional_status_code, additional_response, ) in route.responses.items(): - process_response = additional_response.copy() + process_response = copy.deepcopy(additional_response) process_response.pop("model", None) status_code_key = str(additional_status_code).upper() if status_code_key == "DEFAULT": diff --git a/tests/test_additional_responses_union_duplicate_anyof.py b/tests/test_additional_responses_union_duplicate_anyof.py new file mode 100644 index 0000000000..f5d987ca31 --- /dev/null +++ b/tests/test_additional_responses_union_duplicate_anyof.py @@ -0,0 +1,123 @@ +""" +Regression test: Ensure app-level responses with Union models and content/examples +don't accumulate duplicate $ref entries in anyOf arrays. +See https://github.com/fastapi/fastapi/pull/14463 +""" + +from typing import Union + +from fastapi import FastAPI +from fastapi.testclient import TestClient +from pydantic import BaseModel + + +class ModelA(BaseModel): + a: str + + +class ModelB(BaseModel): + b: str + + +app = FastAPI( + responses={ + 500: { + "model": Union[ModelA, ModelB], + "content": {"application/json": {"examples": {"Case A": {"value": "a"}}}}, + } + } +) + + +@app.get("/route1") +async def route1(): + pass # pragma: no cover + + +@app.get("/route2") +async def route2(): + pass # pragma: no cover + + +client = TestClient(app) + + +def test_openapi_schema(): + response = client.get("/openapi.json") + assert response.status_code == 200, response.text + assert response.json() == { + "openapi": "3.1.0", + "info": {"title": "FastAPI", "version": "0.1.0"}, + "paths": { + "/route1": { + "get": { + "summary": "Route1", + "operationId": "route1_route1_get", + "responses": { + "200": { + "description": "Successful Response", + "content": {"application/json": {"schema": {}}}, + }, + "500": { + "description": "Internal Server Error", + "content": { + "application/json": { + "schema": { + "anyOf": [ + {"$ref": "#/components/schemas/ModelA"}, + {"$ref": "#/components/schemas/ModelB"}, + ], + "title": "Response 500 Route1 Route1 Get", + }, + "examples": {"Case A": {"value": "a"}}, + } + }, + }, + }, + } + }, + "/route2": { + "get": { + "summary": "Route2", + "operationId": "route2_route2_get", + "responses": { + "200": { + "description": "Successful Response", + "content": {"application/json": {"schema": {}}}, + }, + "500": { + "description": "Internal Server Error", + "content": { + "application/json": { + "schema": { + "anyOf": [ + {"$ref": "#/components/schemas/ModelA"}, + {"$ref": "#/components/schemas/ModelB"}, + ], + "title": "Response 500 Route2 Route2 Get", + }, + "examples": {"Case A": {"value": "a"}}, + } + }, + }, + }, + } + }, + }, + "components": { + "schemas": { + "ModelA": { + "properties": {"a": {"type": "string", "title": "A"}}, + "type": "object", + "required": ["a"], + "title": "ModelA", + }, + "ModelB": { + "properties": {"b": {"type": "string", "title": "B"}}, + "type": "object", + "required": ["b"], + "title": "ModelB", + }, + } + }, + } From ca4692a8c6552de17646a4eabed8ea3cafce597b Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com> Date: Wed, 4 Feb 2026 13:23:34 +0000 Subject: [PATCH 080/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 0c7d440490..59cf84c863 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,10 @@ hide: ## Latest Changes +### Fixes + +* 🐛 Fix OpenAPI duplication of `anyOf` refs for app-level responses with specified `content` and `model` as `Union`. PR [#14463](https://github.com/fastapi/fastapi/pull/14463) by [@DJMcoder](https://github.com/DJMcoder). + ### Refactors * 💡 Update comment for Pydantic internals. PR [#14814](https://github.com/fastapi/fastapi/pull/14814) by [@tiangolo](https://github.com/tiangolo). From 41352de24c41f3df540ea410696aa2116ab59394 Mon Sep 17 00:00:00 2001 From: Anton <34218036+retwish@users.noreply.github.com> Date: Wed, 4 Feb 2026 14:24:59 +0100 Subject: [PATCH 081/108] =?UTF-8?q?=F0=9F=9A=B8=20Improve=20error=20messag?= =?UTF-8?q?e=20for=20invalid=20query=20parameter=20type=20annotations=20(#?= =?UTF-8?q?14479)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Anton.D <anton.dehtiarenko@chdp-tech.net> Co-authored-by: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> --- fastapi/dependencies/utils.py | 2 +- tests/test_invalid_sequence_param.py | 20 ++++++++++++++++---- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/fastapi/dependencies/utils.py b/fastapi/dependencies/utils.py index 2afc734ba4..b647818c4b 100644 --- a/fastapi/dependencies/utils.py +++ b/fastapi/dependencies/utils.py @@ -519,7 +519,7 @@ def analyze_param( # For Pydantic v1 and getattr(field, "shape", 1) == 1 ) - ) + ), f"Query parameter {param_name!r} must be one of the supported types" return ParamDetails(type_annotation=type_annotation, depends=depends, field=field) diff --git a/tests/test_invalid_sequence_param.py b/tests/test_invalid_sequence_param.py index 2b8fd059e1..3695344f7a 100644 --- a/tests/test_invalid_sequence_param.py +++ b/tests/test_invalid_sequence_param.py @@ -6,7 +6,10 @@ from pydantic import BaseModel def test_invalid_sequence(): - with pytest.raises(AssertionError): + with pytest.raises( + AssertionError, + match="Query parameter 'q' must be one of the supported types", + ): app = FastAPI() class Item(BaseModel): @@ -18,7 +21,10 @@ def test_invalid_sequence(): def test_invalid_tuple(): - with pytest.raises(AssertionError): + with pytest.raises( + AssertionError, + match="Query parameter 'q' must be one of the supported types", + ): app = FastAPI() class Item(BaseModel): @@ -30,7 +36,10 @@ def test_invalid_tuple(): def test_invalid_dict(): - with pytest.raises(AssertionError): + with pytest.raises( + AssertionError, + match="Query parameter 'q' must be one of the supported types", + ): app = FastAPI() class Item(BaseModel): @@ -42,7 +51,10 @@ def test_invalid_dict(): def test_invalid_simple_dict(): - with pytest.raises(AssertionError): + with pytest.raises( + AssertionError, + match="Query parameter 'q' must be one of the supported types", + ): app = FastAPI() class Item(BaseModel): From 9e0f4ca77ae27798764766fb5dfd48fb15812f86 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com> Date: Wed, 4 Feb 2026 13:25:27 +0000 Subject: [PATCH 082/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 59cf84c863..0f0b9dd0aa 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,10 @@ hide: ## Latest Changes +### Features + +* 🚞 Improve error message for invalid query parameter type annotations. PR [#14479](https://github.com/fastapi/fastapi/pull/14479) by [@retwish](https://github.com/retwish). + ### Fixes * 🐛 Fix OpenAPI duplication of `anyOf` refs for app-level responses with specified `content` and `model` as `Union`. PR [#14463](https://github.com/fastapi/fastapi/pull/14463) by [@DJMcoder](https://github.com/DJMcoder). From 61f95c9606ff548d449e9d1e0612d93e2ec3c97f Mon Sep 17 00:00:00 2001 From: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> Date: Wed, 4 Feb 2026 16:26:02 +0300 Subject: [PATCH 083/108] =?UTF-8?q?=F0=9F=93=9D=20Add=20banner=20to=20tran?= =?UTF-8?q?slated=20pages=20(#14809)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add banner to translated pages * Add link to English version. Use modern syntax for details block * 🎚 Auto format * Move `translation-banner.md` inside `docs` directory * 🎚 Auto format --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> --- docs/en/docs/translation-banner.md | 11 +++++++++++ docs/ru/docs/translation-banner.md | 11 +++++++++++ scripts/mkdocs_hooks.py | 30 +++++++++++++++++++++++++++++- 3 files changed, 51 insertions(+), 1 deletion(-) create mode 100644 docs/en/docs/translation-banner.md create mode 100644 docs/ru/docs/translation-banner.md diff --git a/docs/en/docs/translation-banner.md b/docs/en/docs/translation-banner.md new file mode 100644 index 0000000000..1422870744 --- /dev/null +++ b/docs/en/docs/translation-banner.md @@ -0,0 +1,11 @@ +/// details | 🌐 Translation by AI and humans + +This translation was made by AI guided by humans. 🀝 + +It could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🀖 + +You can improve this translation by [helping us guide the AI LLM better](https://fastapi.tiangolo.com/contributing/#translations). + +[English version](ENGLISH_VERSION_URL) + +/// diff --git a/docs/ru/docs/translation-banner.md b/docs/ru/docs/translation-banner.md new file mode 100644 index 0000000000..78ebd676c5 --- /dev/null +++ b/docs/ru/docs/translation-banner.md @@ -0,0 +1,11 @@ +/// details | 🌐 ПеревПЎ выпПлМеМ с пПЌПщью ИИ О люЎей + +ЭтПт перевПЎ был сЎелаМ ИИ пПЎ рукПвПЎствПЌ люЎей. 🀝 + +В МеЌ ЌПгут быть ПшОбкО Оз-за МеправОльМПгП пПМОЌаМОя ПрОгОМальМПгП сЌысла ОлО МеестествеММПстО О т. ÐŽ. 🀖 + +Вы ЌПжете улучшОть этПт перевПЎ, [пПЌПгая МаЌ лучше Маправлять ИИ LLM](https://fastapi.tiangolo.com/ru/contributing/#translations). + +[АМглОйская версОя](ENGLISH_VERSION_URL) + +/// diff --git a/scripts/mkdocs_hooks.py b/scripts/mkdocs_hooks.py index 4b781270a2..567c0111dc 100644 --- a/scripts/mkdocs_hooks.py +++ b/scripts/mkdocs_hooks.py @@ -26,6 +26,17 @@ def get_missing_translation_content(docs_dir: str) -> str: return missing_translation_path.read_text(encoding="utf-8") +@lru_cache +def get_translation_banner_content(docs_dir: str) -> str: + docs_dir_path = Path(docs_dir) + translation_banner_path = docs_dir_path / "translation-banner.md" + if not translation_banner_path.is_file(): + translation_banner_path = ( + docs_dir_path.parent.parent / "en" / "docs" / "translation-banner.md" + ) + return translation_banner_path.read_text(encoding="utf-8") + + @lru_cache def get_mkdocs_material_langs() -> list[str]: material_path = Path(material.__file__).parent @@ -151,4 +162,21 @@ def on_page_markdown( if markdown.startswith("#"): header, _, body = markdown.partition("\n\n") return f"{header}\n\n{missing_translation_content}\n\n{body}" - return markdown + + docs_dir_path = Path(config.docs_dir) + en_docs_dir_path = docs_dir_path.parent.parent / "en/docs" + + if docs_dir_path == en_docs_dir_path: + return markdown + + # For translated pages add translation banner + translation_banner_content = get_translation_banner_content(config.docs_dir) + en_url = "https://fastapi.tiangolo.com/" + page.url.lstrip("/") + translation_banner_content = translation_banner_content.replace( + "ENGLISH_VERSION_URL", en_url + ) + header = "" + body = markdown + if markdown.startswith("#"): + header, _, body = markdown.partition("\n\n") + return f"{header}\n\n{translation_banner_content}\n\n{body}" From a4297066c22071e89f55fcb9f720dec57bd95814 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com> Date: Wed, 4 Feb 2026 13:26:29 +0000 Subject: [PATCH 084/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 0f0b9dd0aa..7658ab970e 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -21,6 +21,7 @@ hide: ### Docs +* 📝 Add banner to translated pages. PR [#14809](https://github.com/fastapi/fastapi/pull/14809) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Add links to related sections of docs to docstrings. PR [#14776](https://github.com/fastapi/fastapi/pull/14776) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Update embedded code examples to Python 3.10 syntax. PR [#14758](https://github.com/fastapi/fastapi/pull/14758) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Fix dependency installation command in `docs/en/docs/contributing.md`. PR [#14757](https://github.com/fastapi/fastapi/pull/14757) by [@YuriiMotov](https://github.com/YuriiMotov). From 3ee652dd0c9e5c1bc38b6cadb6a2a036866c0dd3 Mon Sep 17 00:00:00 2001 From: johnson-earls <125391700+johnson-earls@users.noreply.github.com> Date: Wed, 4 Feb 2026 05:29:02 -0800 Subject: [PATCH 085/108] =?UTF-8?q?=F0=9F=93=9D=20Fix=20example=20of=20lic?= =?UTF-8?q?ense=20identifier=20in=20documentation=20(#14492)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: svlandeg <svlandeg@github.com> --- docs_src/metadata/tutorial001_1_py39.py | 2 +- tests/test_tutorial/test_metadata/test_tutorial001_1.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs_src/metadata/tutorial001_1_py39.py b/docs_src/metadata/tutorial001_1_py39.py index a8f5b94588..419232d861 100644 --- a/docs_src/metadata/tutorial001_1_py39.py +++ b/docs_src/metadata/tutorial001_1_py39.py @@ -28,7 +28,7 @@ app = FastAPI( }, license_info={ "name": "Apache 2.0", - "identifier": "MIT", + "identifier": "Apache-2.0", }, ) diff --git a/tests/test_tutorial/test_metadata/test_tutorial001_1.py b/tests/test_tutorial/test_metadata/test_tutorial001_1.py index 40878ccfd4..10cb35c546 100644 --- a/tests/test_tutorial/test_metadata/test_tutorial001_1.py +++ b/tests/test_tutorial/test_metadata/test_tutorial001_1.py @@ -28,7 +28,7 @@ def test_openapi_schema(): }, "license": { "name": "Apache 2.0", - "identifier": "MIT", + "identifier": "Apache-2.0", }, "version": "0.0.1", }, From b134f406d1ef4c0b2241f7a0402f3fcb9e99dc8c Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com> Date: Wed, 4 Feb 2026 13:29:24 +0000 Subject: [PATCH 086/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 7658ab970e..95d0d794b4 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -21,6 +21,7 @@ hide: ### Docs +* 📝 Fix example of license identifier in documentation. PR [#14492](https://github.com/fastapi/fastapi/pull/14492) by [@johnson-earls](https://github.com/johnson-earls). * 📝 Add banner to translated pages. PR [#14809](https://github.com/fastapi/fastapi/pull/14809) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Add links to related sections of docs to docstrings. PR [#14776](https://github.com/fastapi/fastapi/pull/14776) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Update embedded code examples to Python 3.10 syntax. PR [#14758](https://github.com/fastapi/fastapi/pull/14758) by [@YuriiMotov](https://github.com/YuriiMotov). From 9df1f8293d979506cd75280ed4812658323c2c98 Mon Sep 17 00:00:00 2001 From: Tima <126619011+timakaa@users.noreply.github.com> Date: Wed, 4 Feb 2026 16:32:24 +0300 Subject: [PATCH 087/108] =?UTF-8?q?=F0=9F=93=9D=20Fix=20typing=20issue=20i?= =?UTF-8?q?n=20`docs=5Fsrc/app=5Ftesting/app=5Fb`=20code=20example=20(#145?= =?UTF-8?q?73)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Co-authored-by: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> --- docs_src/app_testing/app_b_an_py310/main.py | 2 +- docs_src/app_testing/app_b_an_py39/main.py | 2 +- docs_src/app_testing/app_b_py310/main.py | 2 +- docs_src/app_testing/app_b_py39/main.py | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs_src/app_testing/app_b_an_py310/main.py b/docs_src/app_testing/app_b_an_py310/main.py index 120289f56d..1b77dd1379 100644 --- a/docs_src/app_testing/app_b_an_py310/main.py +++ b/docs_src/app_testing/app_b_an_py310/main.py @@ -34,5 +34,5 @@ async def create_item(item: Item, x_token: Annotated[str, Header()]) -> Item: raise HTTPException(status_code=400, detail="Invalid X-Token header") if item.id in fake_db: raise HTTPException(status_code=409, detail="Item already exists") - fake_db[item.id] = item + fake_db[item.id] = item.model_dump() return item diff --git a/docs_src/app_testing/app_b_an_py39/main.py b/docs_src/app_testing/app_b_an_py39/main.py index 801d5f21ea..42026a81a0 100644 --- a/docs_src/app_testing/app_b_an_py39/main.py +++ b/docs_src/app_testing/app_b_an_py39/main.py @@ -34,5 +34,5 @@ async def create_item(item: Item, x_token: Annotated[str, Header()]) -> Item: raise HTTPException(status_code=400, detail="Invalid X-Token header") if item.id in fake_db: raise HTTPException(status_code=409, detail="Item already exists") - fake_db[item.id] = item + fake_db[item.id] = item.model_dump() return item diff --git a/docs_src/app_testing/app_b_py310/main.py b/docs_src/app_testing/app_b_py310/main.py index 6c5c341308..83f6fa142a 100644 --- a/docs_src/app_testing/app_b_py310/main.py +++ b/docs_src/app_testing/app_b_py310/main.py @@ -32,5 +32,5 @@ async def create_item(item: Item, x_token: str = Header()) -> Item: raise HTTPException(status_code=400, detail="Invalid X-Token header") if item.id in fake_db: raise HTTPException(status_code=409, detail="Item already exists") - fake_db[item.id] = item + fake_db[item.id] = item.model_dump() return item diff --git a/docs_src/app_testing/app_b_py39/main.py b/docs_src/app_testing/app_b_py39/main.py index 89053c432c..ed38f4721c 100644 --- a/docs_src/app_testing/app_b_py39/main.py +++ b/docs_src/app_testing/app_b_py39/main.py @@ -34,5 +34,5 @@ async def create_item(item: Item, x_token: str = Header()) -> Item: raise HTTPException(status_code=400, detail="Invalid X-Token header") if item.id in fake_db: raise HTTPException(status_code=409, detail="Item already exists") - fake_db[item.id] = item + fake_db[item.id] = item.model_dump() return item From a1bb70e5a5a29cea2c3fce50ab3510b341fdaf8c Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com> Date: Wed, 4 Feb 2026 13:32:48 +0000 Subject: [PATCH 088/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 95d0d794b4..aa516c0d62 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -21,6 +21,7 @@ hide: ### Docs +* 📝 Fix typing issue in `docs_src/app_testing/app_b` code example. PR [#14573](https://github.com/fastapi/fastapi/pull/14573) by [@timakaa](https://github.com/timakaa). * 📝 Fix example of license identifier in documentation. PR [#14492](https://github.com/fastapi/fastapi/pull/14492) by [@johnson-earls](https://github.com/johnson-earls). * 📝 Add banner to translated pages. PR [#14809](https://github.com/fastapi/fastapi/pull/14809) by [@YuriiMotov](https://github.com/YuriiMotov). * 📝 Add links to related sections of docs to docstrings. PR [#14776](https://github.com/fastapi/fastapi/pull/14776) by [@YuriiMotov](https://github.com/YuriiMotov). From 0748214c43d0793b56a309199f45b9bf78c0da26 Mon Sep 17 00:00:00 2001 From: mvanderlee <918128+mvanderlee@users.noreply.github.com> Date: Wed, 4 Feb 2026 14:34:01 +0100 Subject: [PATCH 089/108] =?UTF-8?q?=F0=9F=8F=B7=EF=B8=8F=20Re-export=20`In?= =?UTF-8?q?cEx`=20type=20from=20Pydantic=20instead=20of=20duplicating=20it?= =?UTF-8?q?=20(#14641)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fastapi/types.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fastapi/types.py b/fastapi/types.py index d3e980cb43..1c3a6de749 100644 --- a/fastapi/types.py +++ b/fastapi/types.py @@ -3,9 +3,9 @@ from enum import Enum from typing import Any, Callable, Optional, TypeVar, Union from pydantic import BaseModel +from pydantic.main import IncEx as IncEx DecoratedCallable = TypeVar("DecoratedCallable", bound=Callable[..., Any]) UnionType = getattr(types, "UnionType", Union) ModelNameMap = dict[Union[type[BaseModel], type[Enum]], str] -IncEx = Union[set[int], set[str], dict[int, Any], dict[str, Any]] DependencyCacheKey = tuple[Optional[Callable[..., Any]], tuple[str, ...], str] From 9656e925a9b53dbb288c24f5dd4cea805c02429b Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com> Date: Wed, 4 Feb 2026 13:34:29 +0000 Subject: [PATCH 090/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index aa516c0d62..12a9ac8a1f 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -17,6 +17,7 @@ hide: ### Refactors +* 🏷 Re-export `IncEx` type from Pydantic instead of duplicating it. PR [#14641](https://github.com/fastapi/fastapi/pull/14641) by [@mvanderlee](https://github.com/mvanderlee). * 💡 Update comment for Pydantic internals. PR [#14814](https://github.com/fastapi/fastapi/pull/14814) by [@tiangolo](https://github.com/tiangolo). ### Docs From 741f77d571eeeb2cde4fe11dcfe038c4d925a046 Mon Sep 17 00:00:00 2001 From: Joab <joab0@proton.me> Date: Wed, 4 Feb 2026 10:35:58 -0300 Subject: [PATCH 091/108] =?UTF-8?q?=E2=9C=A8=20Add=20`viewport`=20meta=20t?= =?UTF-8?q?ag=20to=20improve=20Swagger=20UI=20on=20mobile=20devices=20(#14?= =?UTF-8?q?777)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fastapi/openapi/docs.py | 1 + 1 file changed, 1 insertion(+) diff --git a/fastapi/openapi/docs.py b/fastapi/openapi/docs.py index 632cc2c1d9..bb387c609a 100644 --- a/fastapi/openapi/docs.py +++ b/fastapi/openapi/docs.py @@ -139,6 +139,7 @@ def get_swagger_ui_html( <!DOCTYPE html> <html> <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> <link type="text/css" rel="stylesheet" href="{swagger_css_url}"> <link rel="shortcut icon" href="{swagger_favicon_url}"> <title>{title} From 3675e284abfae4f43dd321301ddfa45bcc494056 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 13:36:24 +0000 Subject: [PATCH 092/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 12a9ac8a1f..45e6cf1c22 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -9,6 +9,7 @@ hide: ### Features +* ✹ Add `viewport` meta tag to improve Swagger UI on mobile devices. PR [#14777](https://github.com/fastapi/fastapi/pull/14777) by [@Joab0](https://github.com/Joab0). * 🚞 Improve error message for invalid query parameter type annotations. PR [#14479](https://github.com/fastapi/fastapi/pull/14479) by [@retwish](https://github.com/retwish). ### Fixes From 1d96b3e3f14fa5a226ae817d1095b868796beb60 Mon Sep 17 00:00:00 2001 From: Cecilia Madrid <61908819+WaveTheory1@users.noreply.github.com> Date: Wed, 4 Feb 2026 14:46:46 +0100 Subject: [PATCH 093/108] =?UTF-8?q?=F0=9F=90=9B=20Strip=20whitespaces=20fr?= =?UTF-8?q?om=20`Authorization`=20header=20credentials=20(#14786)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fastapi/security/utils.py | 2 +- tests/test_security_http_base.py | 6 ++++++ tests/test_security_oauth2_authorization_code_bearer.py | 6 ++++++ 3 files changed, 13 insertions(+), 1 deletion(-) diff --git a/fastapi/security/utils.py b/fastapi/security/utils.py index 002e68b445..fd349aec74 100644 --- a/fastapi/security/utils.py +++ b/fastapi/security/utils.py @@ -7,4 +7,4 @@ def get_authorization_scheme_param( if not authorization_header_value: return "", "" scheme, _, param = authorization_header_value.partition(" ") - return scheme, param + return scheme, param.strip() diff --git a/tests/test_security_http_base.py b/tests/test_security_http_base.py index 8cf259a750..ac38ee718e 100644 --- a/tests/test_security_http_base.py +++ b/tests/test_security_http_base.py @@ -21,6 +21,12 @@ def test_security_http_base(): assert response.json() == {"scheme": "Other", "credentials": "foobar"} +def test_security_http_base_with_whitespaces(): + response = client.get("/users/me", headers={"Authorization": "Other foobar "}) + assert response.status_code == 200, response.text + assert response.json() == {"scheme": "Other", "credentials": "foobar"} + + def test_security_http_base_no_credentials(): response = client.get("/users/me") assert response.status_code == 401, response.text diff --git a/tests/test_security_oauth2_authorization_code_bearer.py b/tests/test_security_oauth2_authorization_code_bearer.py index f2097b1490..66f53ab00d 100644 --- a/tests/test_security_oauth2_authorization_code_bearer.py +++ b/tests/test_security_oauth2_authorization_code_bearer.py @@ -37,6 +37,12 @@ def test_token(): assert response.json() == {"token": "testtoken"} +def test_token_with_whitespaces(): + response = client.get("/items", headers={"Authorization": "Bearer testtoken "}) + assert response.status_code == 200, response.text + assert response.json() == {"token": "testtoken"} + + def test_openapi_schema(): response = client.get("/openapi.json") assert response.status_code == 200, response.text From c944add5a9680f7b3dea3a5bab4787949671d2c4 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 13:47:09 +0000 Subject: [PATCH 094/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 45e6cf1c22..091a4c0aa7 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -14,6 +14,7 @@ hide: ### Fixes +* 🐛 Strip whitespaces from `Authorization` header credentials. PR [#14786](https://github.com/fastapi/fastapi/pull/14786) by [@WaveTheory1](https://github.com/WaveTheory1). * 🐛 Fix OpenAPI duplication of `anyOf` refs for app-level responses with specified `content` and `model` as `Union`. PR [#14463](https://github.com/fastapi/fastapi/pull/14463) by [@DJMcoder](https://github.com/DJMcoder). ### Refactors From 09f5941f0e18db2b28b40d35a5da7a94c23eb9ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Gu=C3=A9rin?= Date: Wed, 4 Feb 2026 14:49:44 +0100 Subject: [PATCH 095/108] =?UTF-8?q?=F0=9F=90=9B=20Fix=20TYPE=5FCHECKING=20?= =?UTF-8?q?annotations=20for=20Python=203.14=20(PEP=20649)=20(#14789)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fastapi/dependencies/utils.py | 7 ++++- ...stringified_annotation_dependency_py314.py | 30 +++++++++++++++++++ .../test_dependencies/test_tutorial008.py | 10 +++++-- tests/utils.py | 4 +-- 4 files changed, 46 insertions(+), 5 deletions(-) create mode 100644 tests/test_stringified_annotation_dependency_py314.py diff --git a/fastapi/dependencies/utils.py b/fastapi/dependencies/utils.py index b647818c4b..fc5dfed85a 100644 --- a/fastapi/dependencies/utils.py +++ b/fastapi/dependencies/utils.py @@ -204,7 +204,12 @@ def _get_signature(call: Callable[..., Any]) -> inspect.Signature: except NameError: # Handle type annotations with if TYPE_CHECKING, not used by FastAPI # e.g. dependency return types - signature = inspect.signature(call) + if sys.version_info >= (3, 14): + from annotationlib import Format + + signature = inspect.signature(call, annotation_format=Format.FORWARDREF) + else: + signature = inspect.signature(call) else: signature = inspect.signature(call) return signature diff --git a/tests/test_stringified_annotation_dependency_py314.py b/tests/test_stringified_annotation_dependency_py314.py new file mode 100644 index 0000000000..da9b429fc0 --- /dev/null +++ b/tests/test_stringified_annotation_dependency_py314.py @@ -0,0 +1,30 @@ +from typing import TYPE_CHECKING, Annotated + +from fastapi import Depends, FastAPI +from fastapi.testclient import TestClient + +from .utils import needs_py314 + +if TYPE_CHECKING: # pragma: no cover + + class DummyUser: ... + + +@needs_py314 +def test_stringified_annotation(): + # python3.14: Use forward reference without "from __future__ import annotations" + async def get_current_user() -> DummyUser | None: + return None + + app = FastAPI() + + client = TestClient(app) + + @app.get("/") + async def get( + current_user: Annotated[DummyUser | None, Depends(get_current_user)], + ) -> str: + return "hello world" + + response = client.get("/") + assert response.status_code == 200 diff --git a/tests/test_tutorial/test_dependencies/test_tutorial008.py b/tests/test_tutorial/test_dependencies/test_tutorial008.py index 9d7377ebe4..5a2d226bff 100644 --- a/tests/test_tutorial/test_dependencies/test_tutorial008.py +++ b/tests/test_tutorial/test_dependencies/test_tutorial008.py @@ -1,4 +1,5 @@ import importlib +import sys from types import ModuleType from typing import Annotated, Any from unittest.mock import Mock, patch @@ -12,8 +13,13 @@ from fastapi.testclient import TestClient name="module", params=[ "tutorial008_py39", - # Fails with `NameError: name 'DepA' is not defined` - pytest.param("tutorial008_an_py39", marks=pytest.mark.xfail), + pytest.param( + "tutorial008_an_py39", + marks=pytest.mark.xfail( + sys.version_info < (3, 14), + reason="Fails with `NameError: name 'DepA' is not defined`", + ), + ), ], ) def get_module(request: pytest.FixtureRequest): diff --git a/tests/utils.py b/tests/utils.py index efa0bfd52b..4cbfee79f5 100644 --- a/tests/utils.py +++ b/tests/utils.py @@ -6,8 +6,8 @@ needs_py39 = pytest.mark.skipif(sys.version_info < (3, 9), reason="requires pyth needs_py310 = pytest.mark.skipif( sys.version_info < (3, 10), reason="requires python3.10+" ) -needs_py_lt_314 = pytest.mark.skipif( - sys.version_info >= (3, 14), reason="requires python3.13-" +needs_py314 = pytest.mark.skipif( + sys.version_info < (3, 14), reason="requires python3.14+" ) From 5d50b7491579d6b9e9a30cdbe24b08f70dcb8d61 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 13:51:56 +0000 Subject: [PATCH 096/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 091a4c0aa7..eff732da1e 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -14,6 +14,7 @@ hide: ### Fixes +* 🐛 Fix TYPE_CHECKING annotations for Python 3.14 (PEP 649). PR [#14789](https://github.com/fastapi/fastapi/pull/14789) by [@mgu](https://github.com/mgu). * 🐛 Strip whitespaces from `Authorization` header credentials. PR [#14786](https://github.com/fastapi/fastapi/pull/14786) by [@WaveTheory1](https://github.com/WaveTheory1). * 🐛 Fix OpenAPI duplication of `anyOf` refs for app-level responses with specified `content` and `model` as `Union`. PR [#14463](https://github.com/fastapi/fastapi/pull/14463) by [@DJMcoder](https://github.com/DJMcoder). From 440bfd70a948c187dadb2e89ee7e94933e867a00 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Wed, 4 Feb 2026 06:20:36 -0800 Subject: [PATCH 097/108] =?UTF-8?q?=F0=9F=8E=A8=20Tweak=20types=20for=20my?= =?UTF-8?q?py=20(#14816)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fastapi/encoders.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fastapi/encoders.py b/fastapi/encoders.py index e8610c983b..b4661be4fa 100644 --- a/fastapi/encoders.py +++ b/fastapi/encoders.py @@ -219,9 +219,9 @@ def jsonable_encoder( if isinstance(obj, encoder_type): return encoder_instance(obj) if include is not None and not isinstance(include, (set, dict)): - include = set(include) + include = set(include) # type: ignore[assignment] if exclude is not None and not isinstance(exclude, (set, dict)): - exclude = set(exclude) + exclude = set(exclude) # type: ignore[assignment] if isinstance(obj, BaseModel): obj_dict = obj.model_dump( mode="json", From 1e5e8b44cb042f774a8637f27bce93b4ceb68f7d Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 14:21:00 +0000 Subject: [PATCH 098/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index eff732da1e..8d90983d44 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -20,6 +20,7 @@ hide: ### Refactors +* 🎚 Tweak types for mypy. PR [#14816](https://github.com/fastapi/fastapi/pull/14816) by [@tiangolo](https://github.com/tiangolo). * 🏷 Re-export `IncEx` type from Pydantic instead of duplicating it. PR [#14641](https://github.com/fastapi/fastapi/pull/14641) by [@mvanderlee](https://github.com/mvanderlee). * 💡 Update comment for Pydantic internals. PR [#14814](https://github.com/fastapi/fastapi/pull/14814) by [@tiangolo](https://github.com/tiangolo). From 75c47187f31b6f60e59dda2d6db26984043ab95c Mon Sep 17 00:00:00 2001 From: Jonathan Fulton Date: Wed, 4 Feb 2026 09:34:02 -0500 Subject: [PATCH 099/108] =?UTF-8?q?=F0=9F=90=9B=20Update=20`ValidationErro?= =?UTF-8?q?r`=20schema=20to=20include=20`input`=20and=20`ctx`=20(#14791)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> --- fastapi/openapi/utils.py | 2 ++ tests/test_additional_properties.py | 2 ++ tests/test_additional_properties_bool.py | 2 ++ ...dditional_responses_custom_model_in_callback.py | 2 ++ ...additional_responses_default_validationerror.py | 2 ++ tests/test_annotated.py | 2 ++ tests/test_application.py | 2 ++ tests/test_dependency_duplicates.py | 2 ++ tests/test_enforce_once_required_parameter.py | 2 ++ tests/test_extra_routes.py | 2 ++ tests/test_filter_pydantic_sub_model_pv2.py | 2 ++ tests/test_forms_single_param.py | 2 ++ tests/test_generate_unique_id_function.py | 14 ++++++++++++++ .../test_get_model_definitions_formfeed_escape.py | 2 ++ tests/test_get_request_body.py | 2 ++ tests/test_include_router_defaults_overrides.py | 2 ++ tests/test_infer_param_optionality.py | 2 ++ tests/test_modules_same_name_body/test_main.py | 2 ++ tests/test_multi_body_errors.py | 2 ++ tests/test_multi_query_errors.py | 2 ++ tests/test_no_schema_split.py | 2 ++ tests/test_openapi_examples.py | 2 ++ tests/test_openapi_query_parameter_extension.py | 2 ++ .../test_openapi_separate_input_output_schemas.py | 4 ++++ tests/test_param_in_path_and_dependency.py | 2 ++ tests/test_param_include_in_schema.py | 2 ++ tests/test_put_no_body.py | 2 ++ tests/test_regex_deprecated_body.py | 2 ++ tests/test_regex_deprecated_params.py | 2 ++ tests/test_repeated_dependency_schema.py | 2 ++ tests/test_repeated_parameter_alias.py | 2 ++ tests/test_reponse_set_reponse_code_empty.py | 2 ++ tests/test_request_body_parameters_media_type.py | 2 ++ tests/test_schema_extra_examples.py | 2 ++ tests/test_security_oauth2.py | 2 ++ tests/test_security_oauth2_optional.py | 2 ++ tests/test_security_oauth2_optional_description.py | 2 ++ tests/test_starlette_exception.py | 2 ++ tests/test_sub_callbacks.py | 2 ++ tests/test_tuples.py | 2 ++ .../test_additional_responses/test_tutorial001.py | 2 ++ .../test_additional_responses/test_tutorial002.py | 2 ++ .../test_additional_responses/test_tutorial003.py | 2 ++ .../test_additional_responses/test_tutorial004.py | 2 ++ .../test_bigger_applications/test_main.py | 2 ++ tests/test_tutorial/test_body/test_tutorial001.py | 2 ++ tests/test_tutorial/test_body/test_tutorial002.py | 2 ++ tests/test_tutorial/test_body/test_tutorial003.py | 2 ++ tests/test_tutorial/test_body/test_tutorial004.py | 2 ++ .../test_body_fields/test_tutorial001.py | 2 ++ .../test_body_multiple_params/test_tutorial001.py | 2 ++ .../test_body_multiple_params/test_tutorial002.py | 2 ++ .../test_body_multiple_params/test_tutorial003.py | 2 ++ .../test_body_multiple_params/test_tutorial004.py | 2 ++ .../test_body_multiple_params/test_tutorial005.py | 2 ++ .../test_tutorial001_tutorial002_tutorial003.py | 2 ++ .../test_body_nested_models/test_tutorial004.py | 2 ++ .../test_body_nested_models/test_tutorial005.py | 2 ++ .../test_body_nested_models/test_tutorial006.py | 2 ++ .../test_body_nested_models/test_tutorial007.py | 2 ++ .../test_body_nested_models/test_tutorial008.py | 2 ++ .../test_body_nested_models/test_tutorial009.py | 2 ++ .../test_body_updates/test_tutorial001.py | 2 ++ .../test_body_updates/test_tutorial002.py | 2 ++ .../test_cookie_param_models/test_tutorial001.py | 2 ++ .../test_cookie_param_models/test_tutorial002.py | 2 ++ .../test_cookie_params/test_tutorial001.py | 2 ++ .../test_dataclasses/test_tutorial001.py | 2 ++ .../test_dataclasses/test_tutorial003.py | 2 ++ .../test_tutorial001_tutorial001_02.py | 2 ++ .../test_tutorial002_tutorial003_tutorial004.py | 2 ++ .../test_dependencies/test_tutorial005.py | 2 ++ .../test_dependencies/test_tutorial006.py | 2 ++ .../test_dependencies/test_tutorial011.py | 2 ++ .../test_dependencies/test_tutorial012.py | 2 ++ .../test_tutorial/test_encoder/test_tutorial001.py | 2 ++ .../test_tutorial/test_events/test_tutorial001.py | 2 ++ .../test_tutorial/test_events/test_tutorial003.py | 2 ++ .../test_extra_data_types/test_tutorial001.py | 2 ++ .../test_tutorial001_tutorial002.py | 2 ++ .../test_extra_models/test_tutorial003.py | 2 ++ .../test_generate_clients/test_tutorial001.py | 2 ++ .../test_generate_clients/test_tutorial002.py | 2 ++ .../test_generate_clients/test_tutorial003.py | 2 ++ .../test_generate_clients/test_tutorial004.py | 2 ++ .../test_handling_errors/test_tutorial001.py | 2 ++ .../test_handling_errors/test_tutorial002.py | 2 ++ .../test_handling_errors/test_tutorial003.py | 2 ++ .../test_handling_errors/test_tutorial004.py | 2 ++ .../test_handling_errors/test_tutorial005.py | 2 ++ .../test_handling_errors/test_tutorial006.py | 2 ++ .../test_header_param_models/test_tutorial001.py | 2 ++ .../test_header_param_models/test_tutorial002.py | 2 ++ .../test_header_param_models/test_tutorial003.py | 2 ++ .../test_header_params/test_tutorial001.py | 2 ++ .../test_header_params/test_tutorial002.py | 2 ++ .../test_header_params/test_tutorial003.py | 2 ++ .../test_openapi_callbacks/test_tutorial001.py | 2 ++ .../test_openapi_webhooks/test_tutorial001.py | 2 ++ .../test_tutorial004.py | 2 ++ .../test_tutorial001.py | 2 ++ .../test_tutorial002.py | 2 ++ .../test_tutorial003_tutorial004.py | 2 ++ .../test_tutorial005.py | 2 ++ .../test_path_params/test_tutorial001.py | 2 ++ .../test_path_params/test_tutorial002.py | 2 ++ .../test_path_params/test_tutorial003.py | 2 ++ .../test_path_params/test_tutorial004.py | 2 ++ .../test_path_params/test_tutorial005.py | 2 ++ .../test_tutorial001.py | 2 ++ .../test_tutorial002_tutorial003.py | 2 ++ .../test_tutorial004.py | 2 ++ .../test_tutorial005.py | 2 ++ .../test_tutorial006.py | 2 ++ .../test_query_param_models/test_tutorial001.py | 2 ++ .../test_query_param_models/test_tutorial002.py | 2 ++ .../test_query_params/test_tutorial001.py | 2 ++ .../test_query_params/test_tutorial002.py | 2 ++ .../test_query_params/test_tutorial003.py | 2 ++ .../test_query_params/test_tutorial004.py | 2 ++ .../test_query_params/test_tutorial005.py | 2 ++ .../test_query_params/test_tutorial006.py | 2 ++ .../test_tutorial001.py | 2 ++ .../test_tutorial002.py | 2 ++ .../test_tutorial003.py | 2 ++ .../test_tutorial004.py | 2 ++ .../test_tutorial005.py | 2 ++ .../test_tutorial006.py | 2 ++ .../test_tutorial006c.py | 2 ++ .../test_tutorial007.py | 2 ++ .../test_tutorial008.py | 2 ++ .../test_tutorial009.py | 2 ++ .../test_tutorial010.py | 2 ++ .../test_tutorial011.py | 2 ++ .../test_tutorial012.py | 2 ++ .../test_tutorial013.py | 2 ++ .../test_tutorial014.py | 2 ++ .../test_tutorial015.py | 2 ++ .../test_request_files/test_tutorial001.py | 2 ++ .../test_request_files/test_tutorial001_02.py | 2 ++ .../test_request_files/test_tutorial001_03.py | 2 ++ .../test_request_files/test_tutorial002.py | 2 ++ .../test_request_files/test_tutorial003.py | 2 ++ .../test_request_form_models/test_tutorial001.py | 2 ++ .../test_request_form_models/test_tutorial002.py | 2 ++ .../test_request_forms/test_tutorial001.py | 2 ++ .../test_tutorial001.py | 2 ++ .../test_response_directly/test_tutorial001.py | 2 ++ .../test_tutorial001_tutorial001_01.py | 2 ++ .../test_response_model/test_tutorial002.py | 2 ++ .../test_response_model/test_tutorial003.py | 2 ++ .../test_response_model/test_tutorial003_01.py | 2 ++ .../test_response_model/test_tutorial003_02.py | 2 ++ .../test_response_model/test_tutorial003_05.py | 2 ++ .../test_response_model/test_tutorial004.py | 2 ++ .../test_response_model/test_tutorial005.py | 2 ++ .../test_response_model/test_tutorial006.py | 2 ++ .../test_tutorial001_tutorial002.py | 2 ++ .../test_schema_extra_example/test_tutorial001.py | 2 ++ .../test_schema_extra_example/test_tutorial002.py | 2 ++ .../test_schema_extra_example/test_tutorial003.py | 2 ++ .../test_schema_extra_example/test_tutorial004.py | 2 ++ .../test_schema_extra_example/test_tutorial005.py | 2 ++ .../test_security/test_tutorial003.py | 2 ++ .../test_security/test_tutorial004.py | 2 ++ .../test_security/test_tutorial005.py | 2 ++ .../test_tutorial001.py | 2 ++ .../test_tutorial002.py | 2 ++ .../test_sql_databases/test_tutorial001.py | 2 ++ .../test_sql_databases/test_tutorial002.py | 2 ++ .../test_tutorial001.py | 2 ++ tests/test_union_body.py | 2 ++ tests/test_union_body_discriminator.py | 2 ++ tests/test_union_body_discriminator_annotated.py | 2 ++ tests/test_union_forms.py | 2 ++ tests/test_union_inherited_body.py | 2 ++ tests/test_webhooks_security.py | 2 ++ 177 files changed, 368 insertions(+) diff --git a/fastapi/openapi/utils.py b/fastapi/openapi/utils.py index d56027b500..5736af3b78 100644 --- a/fastapi/openapi/utils.py +++ b/fastapi/openapi/utils.py @@ -50,6 +50,8 @@ validation_error_definition = { }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, "required": ["loc", "msg", "type"], } diff --git a/tests/test_additional_properties.py b/tests/test_additional_properties.py index 2622366400..935acca42e 100644 --- a/tests/test_additional_properties.py +++ b/tests/test_additional_properties.py @@ -89,6 +89,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_additional_properties_bool.py b/tests/test_additional_properties_bool.py index 063297a3f2..3b323ad463 100644 --- a/tests/test_additional_properties_bool.py +++ b/tests/test_additional_properties_bool.py @@ -101,6 +101,8 @@ def test_openapi_schema(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_additional_responses_custom_model_in_callback.py b/tests/test_additional_responses_custom_model_in_callback.py index 376d7714ed..3a37c924d2 100644 --- a/tests/test_additional_responses_custom_model_in_callback.py +++ b/tests/test_additional_responses_custom_model_in_callback.py @@ -128,6 +128,8 @@ def test_openapi_schema(): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", diff --git a/tests/test_additional_responses_default_validationerror.py b/tests/test_additional_responses_default_validationerror.py index 153f04f579..acc081fb16 100644 --- a/tests/test_additional_responses_default_validationerror.py +++ b/tests/test_additional_responses_default_validationerror.py @@ -66,6 +66,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_annotated.py b/tests/test_annotated.py index 39f6f83b29..99bd03ae6f 100644 --- a/tests/test_annotated.py +++ b/tests/test_annotated.py @@ -284,6 +284,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_application.py b/tests/test_application.py index 001586ff78..fe97e674c0 100644 --- a/tests/test_application.py +++ b/tests/test_application.py @@ -1260,6 +1260,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_dependency_duplicates.py b/tests/test_dependency_duplicates.py index a8658e03bb..3ca6a3e891 100644 --- a/tests/test_dependency_duplicates.py +++ b/tests/test_dependency_duplicates.py @@ -223,6 +223,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_enforce_once_required_parameter.py b/tests/test_enforce_once_required_parameter.py index 2e5ac6c062..c46a543576 100644 --- a/tests/test_enforce_once_required_parameter.py +++ b/tests/test_enforce_once_required_parameter.py @@ -42,6 +42,8 @@ expected_schema = { }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, "title": "Location", diff --git a/tests/test_extra_routes.py b/tests/test_extra_routes.py index 45734ec28a..251af4a59e 100644 --- a/tests/test_extra_routes.py +++ b/tests/test_extra_routes.py @@ -347,6 +347,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_filter_pydantic_sub_model_pv2.py b/tests/test_filter_pydantic_sub_model_pv2.py index fc5876410d..1de2b50f7f 100644 --- a/tests/test_filter_pydantic_sub_model_pv2.py +++ b/tests/test_filter_pydantic_sub_model_pv2.py @@ -165,6 +165,8 @@ def test_openapi_schema(client: TestClient): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", diff --git a/tests/test_forms_single_param.py b/tests/test_forms_single_param.py index 67f054b34e..fc163cb1ef 100644 --- a/tests/test_forms_single_param.py +++ b/tests/test_forms_single_param.py @@ -81,6 +81,8 @@ def test_openapi_schema(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_generate_unique_id_function.py b/tests/test_generate_unique_id_function.py index 62ebfbc964..49510d08a9 100644 --- a/tests/test_generate_unique_id_function.py +++ b/tests/test_generate_unique_id_function.py @@ -213,6 +213,8 @@ def test_top_level_generate_unique_id(): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", @@ -414,6 +416,8 @@ def test_router_overrides_generate_unique_id(): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", @@ -615,6 +619,8 @@ def test_router_include_overrides_generate_unique_id(): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", @@ -889,6 +895,8 @@ def test_subrouter_top_level_include_overrides_generate_unique_id(): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", @@ -1093,6 +1101,8 @@ def test_router_path_operation_overrides_generate_unique_id(): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", @@ -1301,6 +1311,8 @@ def test_app_path_operation_overrides_generate_unique_id(): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", @@ -1587,6 +1599,8 @@ def test_callback_override_generate_unique_id(): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", diff --git a/tests/test_get_model_definitions_formfeed_escape.py b/tests/test_get_model_definitions_formfeed_escape.py index eb7939b69a..46f8aa5959 100644 --- a/tests/test_get_model_definitions_formfeed_escape.py +++ b/tests/test_get_model_definitions_formfeed_escape.py @@ -98,6 +98,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_get_request_body.py b/tests/test_get_request_body.py index cc567b88f6..b21889e30f 100644 --- a/tests/test_get_request_body.py +++ b/tests/test_get_request_body.py @@ -100,6 +100,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_include_router_defaults_overrides.py b/tests/test_include_router_defaults_overrides.py index 33baa25e6a..6d2ffc44a5 100644 --- a/tests/test_include_router_defaults_overrides.py +++ b/tests/test_include_router_defaults_overrides.py @@ -7290,6 +7290,8 @@ def test_openapi(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_infer_param_optionality.py b/tests/test_infer_param_optionality.py index 147018996e..b11a1ca433 100644 --- a/tests/test_infer_param_optionality.py +++ b/tests/test_infer_param_optionality.py @@ -325,6 +325,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_modules_same_name_body/test_main.py b/tests/test_modules_same_name_body/test_main.py index 263d87df26..276de539db 100644 --- a/tests/test_modules_same_name_body/test_main.py +++ b/tests/test_modules_same_name_body/test_main.py @@ -131,6 +131,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_multi_body_errors.py b/tests/test_multi_body_errors.py index 4418c77cb0..fa3e0c6359 100644 --- a/tests/test_multi_body_errors.py +++ b/tests/test_multi_body_errors.py @@ -167,6 +167,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_multi_query_errors.py b/tests/test_multi_query_errors.py index 5df51ba185..7540367a6f 100644 --- a/tests/test_multi_query_errors.py +++ b/tests/test_multi_query_errors.py @@ -97,6 +97,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_no_schema_split.py b/tests/test_no_schema_split.py index 131a3755e7..66bb89902a 100644 --- a/tests/test_no_schema_split.py +++ b/tests/test_no_schema_split.py @@ -154,6 +154,8 @@ def test_openapi_schema(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_openapi_examples.py b/tests/test_openapi_examples.py index bd0d55452e..93e5b366f1 100644 --- a/tests/test_openapi_examples.py +++ b/tests/test_openapi_examples.py @@ -398,6 +398,8 @@ def test_openapi_schema(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_openapi_query_parameter_extension.py b/tests/test_openapi_query_parameter_extension.py index 084cb695d4..b6c3c3d8da 100644 --- a/tests/test_openapi_query_parameter_extension.py +++ b/tests/test_openapi_query_parameter_extension.py @@ -119,6 +119,8 @@ def test_openapi(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_openapi_separate_input_output_schemas.py b/tests/test_openapi_separate_input_output_schemas.py index 1891f0bde0..f941e323bf 100644 --- a/tests/test_openapi_separate_input_output_schemas.py +++ b/tests/test_openapi_separate_input_output_schemas.py @@ -418,6 +418,8 @@ def test_openapi_schema(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] @@ -649,6 +651,8 @@ def test_openapi_schema_no_separate(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_param_in_path_and_dependency.py b/tests/test_param_in_path_and_dependency.py index 08eb0f40f3..6b1f660cb7 100644 --- a/tests/test_param_in_path_and_dependency.py +++ b/tests/test_param_in_path_and_dependency.py @@ -86,6 +86,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_param_include_in_schema.py b/tests/test_param_include_in_schema.py index f461947c97..5060920f14 100644 --- a/tests/test_param_include_in_schema.py +++ b/tests/test_param_include_in_schema.py @@ -151,6 +151,8 @@ openapi_schema = { }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_put_no_body.py b/tests/test_put_no_body.py index 8f4c82532c..2b9299bc58 100644 --- a/tests/test_put_no_body.py +++ b/tests/test_put_no_body.py @@ -78,6 +78,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_regex_deprecated_body.py b/tests/test_regex_deprecated_body.py index 5b4daa450f..6074206ffe 100644 --- a/tests/test_regex_deprecated_body.py +++ b/tests/test_regex_deprecated_body.py @@ -132,6 +132,8 @@ def test_openapi_schema(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_regex_deprecated_params.py b/tests/test_regex_deprecated_params.py index d6eaa45fb1..6074b62828 100644 --- a/tests/test_regex_deprecated_params.py +++ b/tests/test_regex_deprecated_params.py @@ -121,6 +121,8 @@ def test_openapi_schema(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_repeated_dependency_schema.py b/tests/test_repeated_dependency_schema.py index c21829bd97..0fc7e3d3ef 100644 --- a/tests/test_repeated_dependency_schema.py +++ b/tests/test_repeated_dependency_schema.py @@ -35,6 +35,8 @@ schema = { }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, "title": "Location", diff --git a/tests/test_repeated_parameter_alias.py b/tests/test_repeated_parameter_alias.py index fd72eaab29..49e4ad4a2e 100644 --- a/tests/test_repeated_parameter_alias.py +++ b/tests/test_repeated_parameter_alias.py @@ -41,6 +41,8 @@ def test_openapi_schema(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_reponse_set_reponse_code_empty.py b/tests/test_reponse_set_reponse_code_empty.py index bf3aa758c3..b31aefa479 100644 --- a/tests/test_reponse_set_reponse_code_empty.py +++ b/tests/test_reponse_set_reponse_code_empty.py @@ -90,6 +90,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_request_body_parameters_media_type.py b/tests/test_request_body_parameters_media_type.py index d1bff9ddf4..8731c3e5d3 100644 --- a/tests/test_request_body_parameters_media_type.py +++ b/tests/test_request_body_parameters_media_type.py @@ -168,6 +168,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_schema_extra_examples.py b/tests/test_schema_extra_examples.py index ac8999c90a..8caf6ce7af 100644 --- a/tests/test_schema_extra_examples.py +++ b/tests/test_schema_extra_examples.py @@ -845,6 +845,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_security_oauth2.py b/tests/test_security_oauth2.py index 7ad9369956..bff1226ad9 100644 --- a/tests/test_security_oauth2.py +++ b/tests/test_security_oauth2.py @@ -237,6 +237,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_security_oauth2_optional.py b/tests/test_security_oauth2_optional.py index 57c16058af..5bcd5040fd 100644 --- a/tests/test_security_oauth2_optional.py +++ b/tests/test_security_oauth2_optional.py @@ -240,6 +240,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_security_oauth2_optional_description.py b/tests/test_security_oauth2_optional_description.py index 60c6c242e0..0353ba4c27 100644 --- a/tests/test_security_oauth2_optional_description.py +++ b/tests/test_security_oauth2_optional_description.py @@ -241,6 +241,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_starlette_exception.py b/tests/test_starlette_exception.py index 229fe80163..2be37b8bb8 100644 --- a/tests/test_starlette_exception.py +++ b/tests/test_starlette_exception.py @@ -184,6 +184,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_sub_callbacks.py b/tests/test_sub_callbacks.py index cc7e5f5c6a..442e709fb1 100644 --- a/tests/test_sub_callbacks.py +++ b/tests/test_sub_callbacks.py @@ -277,6 +277,8 @@ def test_openapi_schema(): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", diff --git a/tests/test_tuples.py b/tests/test_tuples.py index d3c89045b4..de9487df2a 100644 --- a/tests/test_tuples.py +++ b/tests/test_tuples.py @@ -262,6 +262,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_additional_responses/test_tutorial001.py b/tests/test_tutorial/test_additional_responses/test_tutorial001.py index 1a18db75ce..78ccb84426 100644 --- a/tests/test_tutorial/test_additional_responses/test_tutorial001.py +++ b/tests/test_tutorial/test_additional_responses/test_tutorial001.py @@ -98,6 +98,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_additional_responses/test_tutorial002.py b/tests/test_tutorial/test_additional_responses/test_tutorial002.py index 8208605956..cdab56d7a6 100644 --- a/tests/test_tutorial/test_additional_responses/test_tutorial002.py +++ b/tests/test_tutorial/test_additional_responses/test_tutorial002.py @@ -115,6 +115,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_additional_responses/test_tutorial003.py b/tests/test_tutorial/test_additional_responses/test_tutorial003.py index 90dc4e371e..fda786b398 100644 --- a/tests/test_tutorial/test_additional_responses/test_tutorial003.py +++ b/tests/test_tutorial/test_additional_responses/test_tutorial003.py @@ -102,6 +102,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_additional_responses/test_tutorial004.py b/tests/test_tutorial/test_additional_responses/test_tutorial004.py index c6abf5e466..f36d3d79c2 100644 --- a/tests/test_tutorial/test_additional_responses/test_tutorial004.py +++ b/tests/test_tutorial/test_additional_responses/test_tutorial004.py @@ -118,6 +118,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_bigger_applications/test_main.py b/tests/test_tutorial/test_bigger_applications/test_main.py index f5e243b95a..f80563d142 100644 --- a/tests/test_tutorial/test_bigger_applications/test_main.py +++ b/tests/test_tutorial/test_bigger_applications/test_main.py @@ -593,6 +593,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_body/test_tutorial001.py b/tests/test_tutorial/test_body/test_tutorial001.py index 5a7cae1603..9a837483f2 100644 --- a/tests/test_tutorial/test_body/test_tutorial001.py +++ b/tests/test_tutorial/test_body/test_tutorial001.py @@ -328,6 +328,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body/test_tutorial002.py b/tests/test_tutorial/test_body/test_tutorial002.py index b6d51d5235..e8b23e8f61 100644 --- a/tests/test_tutorial/test_body/test_tutorial002.py +++ b/tests/test_tutorial/test_body/test_tutorial002.py @@ -143,6 +143,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body/test_tutorial003.py b/tests/test_tutorial/test_body/test_tutorial003.py index 227a125e78..7b8b7ea89f 100644 --- a/tests/test_tutorial/test_body/test_tutorial003.py +++ b/tests/test_tutorial/test_body/test_tutorial003.py @@ -153,6 +153,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body/test_tutorial004.py b/tests/test_tutorial/test_body/test_tutorial004.py index 10212843ee..d78c760f5d 100644 --- a/tests/test_tutorial/test_body/test_tutorial004.py +++ b/tests/test_tutorial/test_body/test_tutorial004.py @@ -164,6 +164,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body_fields/test_tutorial001.py b/tests/test_tutorial/test_body_fields/test_tutorial001.py index 0ecadbb660..cb6da29085 100644 --- a/tests/test_tutorial/test_body_fields/test_tutorial001.py +++ b/tests/test_tutorial/test_body_fields/test_tutorial001.py @@ -166,6 +166,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body_multiple_params/test_tutorial001.py b/tests/test_tutorial/test_body_multiple_params/test_tutorial001.py index 63c9c16d62..a4f24627b0 100644 --- a/tests/test_tutorial/test_body_multiple_params/test_tutorial001.py +++ b/tests/test_tutorial/test_body_multiple_params/test_tutorial001.py @@ -162,6 +162,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body_multiple_params/test_tutorial002.py b/tests/test_tutorial/test_body_multiple_params/test_tutorial002.py index e98d5860fe..155bda0c99 100644 --- a/tests/test_tutorial/test_body_multiple_params/test_tutorial002.py +++ b/tests/test_tutorial/test_body_multiple_params/test_tutorial002.py @@ -325,6 +325,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_body_multiple_params/test_tutorial003.py b/tests/test_tutorial/test_body_multiple_params/test_tutorial003.py index 76b7ff7099..2f403797fe 100644 --- a/tests/test_tutorial/test_body_multiple_params/test_tutorial003.py +++ b/tests/test_tutorial/test_body_multiple_params/test_tutorial003.py @@ -202,6 +202,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body_multiple_params/test_tutorial004.py b/tests/test_tutorial/test_body_multiple_params/test_tutorial004.py index 979c054cd0..506e55eebc 100644 --- a/tests/test_tutorial/test_body_multiple_params/test_tutorial004.py +++ b/tests/test_tutorial/test_body_multiple_params/test_tutorial004.py @@ -272,6 +272,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body_multiple_params/test_tutorial005.py b/tests/test_tutorial/test_body_multiple_params/test_tutorial005.py index d47aa1b4f9..20859d12c8 100644 --- a/tests/test_tutorial/test_body_multiple_params/test_tutorial005.py +++ b/tests/test_tutorial/test_body_multiple_params/test_tutorial005.py @@ -236,6 +236,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_body_nested_models/test_tutorial001_tutorial002_tutorial003.py b/tests/test_tutorial/test_body_nested_models/test_tutorial001_tutorial002_tutorial003.py index d452929c38..ae494350b3 100644 --- a/tests/test_tutorial/test_body_nested_models/test_tutorial001_tutorial002_tutorial003.py +++ b/tests/test_tutorial/test_body_nested_models/test_tutorial001_tutorial002_tutorial003.py @@ -233,6 +233,8 @@ def test_openapi_schema(client: TestClient, mod_name: str): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body_nested_models/test_tutorial004.py b/tests/test_tutorial/test_body_nested_models/test_tutorial004.py index ff9596943d..c1410330c4 100644 --- a/tests/test_tutorial/test_body_nested_models/test_tutorial004.py +++ b/tests/test_tutorial/test_body_nested_models/test_tutorial004.py @@ -257,6 +257,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body_nested_models/test_tutorial005.py b/tests/test_tutorial/test_body_nested_models/test_tutorial005.py index 9a07a904e6..c09e0c1b10 100644 --- a/tests/test_tutorial/test_body_nested_models/test_tutorial005.py +++ b/tests/test_tutorial/test_body_nested_models/test_tutorial005.py @@ -283,6 +283,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body_nested_models/test_tutorial006.py b/tests/test_tutorial/test_body_nested_models/test_tutorial006.py index 088177cb95..f26c50167b 100644 --- a/tests/test_tutorial/test_body_nested_models/test_tutorial006.py +++ b/tests/test_tutorial/test_body_nested_models/test_tutorial006.py @@ -251,6 +251,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body_nested_models/test_tutorial007.py b/tests/test_tutorial/test_body_nested_models/test_tutorial007.py index a302819505..dac168e242 100644 --- a/tests/test_tutorial/test_body_nested_models/test_tutorial007.py +++ b/tests/test_tutorial/test_body_nested_models/test_tutorial007.py @@ -326,6 +326,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body_nested_models/test_tutorial008.py b/tests/test_tutorial/test_body_nested_models/test_tutorial008.py index 32eb8ee75c..2101b7bbe5 100644 --- a/tests/test_tutorial/test_body_nested_models/test_tutorial008.py +++ b/tests/test_tutorial/test_body_nested_models/test_tutorial008.py @@ -139,6 +139,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body_nested_models/test_tutorial009.py b/tests/test_tutorial/test_body_nested_models/test_tutorial009.py index f2e56d40fb..f7481a5f7f 100644 --- a/tests/test_tutorial/test_body_nested_models/test_tutorial009.py +++ b/tests/test_tutorial/test_body_nested_models/test_tutorial009.py @@ -98,6 +98,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body_updates/test_tutorial001.py b/tests/test_tutorial/test_body_updates/test_tutorial001.py index 0401eb7d0d..9c6a90576c 100644 --- a/tests/test_tutorial/test_body_updates/test_tutorial001.py +++ b/tests/test_tutorial/test_body_updates/test_tutorial001.py @@ -168,6 +168,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_body_updates/test_tutorial002.py b/tests/test_tutorial/test_body_updates/test_tutorial002.py index 466e6af8fd..7d79cf5e63 100644 --- a/tests/test_tutorial/test_body_updates/test_tutorial002.py +++ b/tests/test_tutorial/test_body_updates/test_tutorial002.py @@ -189,6 +189,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_cookie_param_models/test_tutorial001.py b/tests/test_tutorial/test_cookie_param_models/test_tutorial001.py index ac8e7bdae1..f391c569a8 100644 --- a/tests/test_tutorial/test_cookie_param_models/test_tutorial001.py +++ b/tests/test_tutorial/test_cookie_param_models/test_tutorial001.py @@ -151,6 +151,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_cookie_param_models/test_tutorial002.py b/tests/test_tutorial/test_cookie_param_models/test_tutorial002.py index d7c3d15f1b..6583045dc8 100644 --- a/tests/test_tutorial/test_cookie_param_models/test_tutorial002.py +++ b/tests/test_tutorial/test_cookie_param_models/test_tutorial002.py @@ -161,6 +161,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_cookie_params/test_tutorial001.py b/tests/test_tutorial/test_cookie_params/test_tutorial001.py index 9b47cbc67a..ab71148764 100644 --- a/tests/test_tutorial/test_cookie_params/test_tutorial001.py +++ b/tests/test_tutorial/test_cookie_params/test_tutorial001.py @@ -101,6 +101,8 @@ def test_openapi_schema(mod: ModuleType): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_dataclasses/test_tutorial001.py b/tests/test_tutorial/test_dataclasses/test_tutorial001.py index 4683062f59..756eacf233 100644 --- a/tests/test_tutorial/test_dataclasses/test_tutorial001.py +++ b/tests/test_tutorial/test_dataclasses/test_tutorial001.py @@ -129,6 +129,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_dataclasses/test_tutorial003.py b/tests/test_tutorial/test_dataclasses/test_tutorial003.py index a6a9fc1c7e..de63a94766 100644 --- a/tests/test_tutorial/test_dataclasses/test_tutorial003.py +++ b/tests/test_tutorial/test_dataclasses/test_tutorial003.py @@ -195,6 +195,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_dependencies/test_tutorial001_tutorial001_02.py b/tests/test_tutorial/test_dependencies/test_tutorial001_tutorial001_02.py index 50d7c4108c..15919c63f7 100644 --- a/tests/test_tutorial/test_dependencies/test_tutorial001_tutorial001_02.py +++ b/tests/test_tutorial/test_dependencies/test_tutorial001_tutorial001_02.py @@ -170,6 +170,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_dependencies/test_tutorial002_tutorial003_tutorial004.py b/tests/test_tutorial/test_dependencies/test_tutorial002_tutorial003_tutorial004.py index f09d6f268d..96300a2599 100644 --- a/tests/test_tutorial/test_dependencies/test_tutorial002_tutorial003_tutorial004.py +++ b/tests/test_tutorial/test_dependencies/test_tutorial002_tutorial003_tutorial004.py @@ -161,6 +161,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_dependencies/test_tutorial005.py b/tests/test_tutorial/test_dependencies/test_tutorial005.py index a914936ba1..e595859cb8 100644 --- a/tests/test_tutorial/test_dependencies/test_tutorial005.py +++ b/tests/test_tutorial/test_dependencies/test_tutorial005.py @@ -121,6 +121,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_dependencies/test_tutorial006.py b/tests/test_tutorial/test_dependencies/test_tutorial006.py index 59202df3bf..cdea27b7c0 100644 --- a/tests/test_tutorial/test_dependencies/test_tutorial006.py +++ b/tests/test_tutorial/test_dependencies/test_tutorial006.py @@ -125,6 +125,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_dependencies/test_tutorial011.py b/tests/test_tutorial/test_dependencies/test_tutorial011.py index 4868254c0b..3374c54b5e 100644 --- a/tests/test_tutorial/test_dependencies/test_tutorial011.py +++ b/tests/test_tutorial/test_dependencies/test_tutorial011.py @@ -102,6 +102,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_dependencies/test_tutorial012.py b/tests/test_tutorial/test_dependencies/test_tutorial012.py index d5599ac73a..f342ff842e 100644 --- a/tests/test_tutorial/test_dependencies/test_tutorial012.py +++ b/tests/test_tutorial/test_dependencies/test_tutorial012.py @@ -219,6 +219,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_encoder/test_tutorial001.py b/tests/test_tutorial/test_encoder/test_tutorial001.py index 5c8ee054d8..5a4edbc66e 100644 --- a/tests/test_tutorial/test_encoder/test_tutorial001.py +++ b/tests/test_tutorial/test_encoder/test_tutorial001.py @@ -172,6 +172,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_events/test_tutorial001.py b/tests/test_tutorial/test_events/test_tutorial001.py index 5fe99d50df..48b838d5a0 100644 --- a/tests/test_tutorial/test_events/test_tutorial001.py +++ b/tests/test_tutorial/test_events/test_tutorial001.py @@ -63,6 +63,8 @@ def test_openapi_schema(app: FastAPI): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", diff --git a/tests/test_tutorial/test_events/test_tutorial003.py b/tests/test_tutorial/test_events/test_tutorial003.py index 38710edfea..aed9def7ae 100644 --- a/tests/test_tutorial/test_events/test_tutorial003.py +++ b/tests/test_tutorial/test_events/test_tutorial003.py @@ -76,6 +76,8 @@ def test_openapi_schema(): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", diff --git a/tests/test_tutorial/test_extra_data_types/test_tutorial001.py b/tests/test_tutorial/test_extra_data_types/test_tutorial001.py index 5479e29252..28fe68f285 100644 --- a/tests/test_tutorial/test_extra_data_types/test_tutorial001.py +++ b/tests/test_tutorial/test_extra_data_types/test_tutorial001.py @@ -133,6 +133,8 @@ def test_openapi_schema(client: TestClient): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", diff --git a/tests/test_tutorial/test_extra_models/test_tutorial001_tutorial002.py b/tests/test_tutorial/test_extra_models/test_tutorial001_tutorial002.py index 3f2f508a11..9981699862 100644 --- a/tests/test_tutorial/test_extra_models/test_tutorial001_tutorial002.py +++ b/tests/test_tutorial/test_extra_models/test_tutorial001_tutorial002.py @@ -138,6 +138,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_extra_models/test_tutorial003.py b/tests/test_tutorial/test_extra_models/test_tutorial003.py index 872af53830..38e8741582 100644 --- a/tests/test_tutorial/test_extra_models/test_tutorial003.py +++ b/tests/test_tutorial/test_extra_models/test_tutorial003.py @@ -127,6 +127,8 @@ def test_openapi_schema(client: TestClient): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", diff --git a/tests/test_tutorial/test_generate_clients/test_tutorial001.py b/tests/test_tutorial/test_generate_clients/test_tutorial001.py index bbb66b4516..83ae38c5b5 100644 --- a/tests/test_tutorial/test_generate_clients/test_tutorial001.py +++ b/tests/test_tutorial/test_generate_clients/test_tutorial001.py @@ -135,6 +135,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_generate_clients/test_tutorial002.py b/tests/test_tutorial/test_generate_clients/test_tutorial002.py index ab8bc4c11c..b9255325aa 100644 --- a/tests/test_tutorial/test_generate_clients/test_tutorial002.py +++ b/tests/test_tutorial/test_generate_clients/test_tutorial002.py @@ -180,6 +180,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_generate_clients/test_tutorial003.py b/tests/test_tutorial/test_generate_clients/test_tutorial003.py index bac52e4fd6..d054845879 100644 --- a/tests/test_tutorial/test_generate_clients/test_tutorial003.py +++ b/tests/test_tutorial/test_generate_clients/test_tutorial003.py @@ -180,6 +180,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_generate_clients/test_tutorial004.py b/tests/test_tutorial/test_generate_clients/test_tutorial004.py index e66f6d2a12..eea60e3428 100644 --- a/tests/test_tutorial/test_generate_clients/test_tutorial004.py +++ b/tests/test_tutorial/test_generate_clients/test_tutorial004.py @@ -82,6 +82,8 @@ def test_remove_tags(tmp_path: pathlib.Path): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_handling_errors/test_tutorial001.py b/tests/test_tutorial/test_handling_errors/test_tutorial001.py index c01850fae6..e22f1dafd4 100644 --- a/tests/test_tutorial/test_handling_errors/test_tutorial001.py +++ b/tests/test_tutorial/test_handling_errors/test_tutorial001.py @@ -72,6 +72,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_handling_errors/test_tutorial002.py b/tests/test_tutorial/test_handling_errors/test_tutorial002.py index 09366a86fa..991478a0fe 100644 --- a/tests/test_tutorial/test_handling_errors/test_tutorial002.py +++ b/tests/test_tutorial/test_handling_errors/test_tutorial002.py @@ -72,6 +72,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_handling_errors/test_tutorial003.py b/tests/test_tutorial/test_handling_errors/test_tutorial003.py index 51ac3e7b28..c303960bde 100644 --- a/tests/test_tutorial/test_handling_errors/test_tutorial003.py +++ b/tests/test_tutorial/test_handling_errors/test_tutorial003.py @@ -73,6 +73,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_handling_errors/test_tutorial004.py b/tests/test_tutorial/test_handling_errors/test_tutorial004.py index 376bc8266f..f6ec59b4d0 100644 --- a/tests/test_tutorial/test_handling_errors/test_tutorial004.py +++ b/tests/test_tutorial/test_handling_errors/test_tutorial004.py @@ -78,6 +78,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_handling_errors/test_tutorial005.py b/tests/test_tutorial/test_handling_errors/test_tutorial005.py index 7bd947f194..a7fa4f0b64 100644 --- a/tests/test_tutorial/test_handling_errors/test_tutorial005.py +++ b/tests/test_tutorial/test_handling_errors/test_tutorial005.py @@ -102,6 +102,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_handling_errors/test_tutorial006.py b/tests/test_tutorial/test_handling_errors/test_tutorial006.py index e95e53d5ed..9cb57d857d 100644 --- a/tests/test_tutorial/test_handling_errors/test_tutorial006.py +++ b/tests/test_tutorial/test_handling_errors/test_tutorial006.py @@ -86,6 +86,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_header_param_models/test_tutorial001.py b/tests/test_tutorial/test_header_param_models/test_tutorial001.py index 1fa8aee461..2d14c698e0 100644 --- a/tests/test_tutorial/test_header_param_models/test_tutorial001.py +++ b/tests/test_tutorial/test_header_param_models/test_tutorial001.py @@ -187,6 +187,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_header_param_models/test_tutorial002.py b/tests/test_tutorial/test_header_param_models/test_tutorial002.py index 079a8f5402..478ac84087 100644 --- a/tests/test_tutorial/test_header_param_models/test_tutorial002.py +++ b/tests/test_tutorial/test_header_param_models/test_tutorial002.py @@ -184,6 +184,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_header_param_models/test_tutorial003.py b/tests/test_tutorial/test_header_param_models/test_tutorial003.py index 4c89d80ee2..00636c2b53 100644 --- a/tests/test_tutorial/test_header_param_models/test_tutorial003.py +++ b/tests/test_tutorial/test_header_param_models/test_tutorial003.py @@ -224,6 +224,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_header_params/test_tutorial001.py b/tests/test_tutorial/test_header_params/test_tutorial001.py index 88591b8225..60342f70a4 100644 --- a/tests/test_tutorial/test_header_params/test_tutorial001.py +++ b/tests/test_tutorial/test_header_params/test_tutorial001.py @@ -93,6 +93,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_header_params/test_tutorial002.py b/tests/test_tutorial/test_header_params/test_tutorial002.py index 229f96c1f8..f1ced99b1b 100644 --- a/tests/test_tutorial/test_header_params/test_tutorial002.py +++ b/tests/test_tutorial/test_header_params/test_tutorial002.py @@ -104,6 +104,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_header_params/test_tutorial003.py b/tests/test_tutorial/test_header_params/test_tutorial003.py index cf067ccf9e..382c3ae191 100644 --- a/tests/test_tutorial/test_header_params/test_tutorial003.py +++ b/tests/test_tutorial/test_header_params/test_tutorial003.py @@ -112,6 +112,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_openapi_callbacks/test_tutorial001.py b/tests/test_tutorial/test_openapi_callbacks/test_tutorial001.py index 6fde96cb5b..e8c98e8063 100644 --- a/tests/test_tutorial/test_openapi_callbacks/test_tutorial001.py +++ b/tests/test_tutorial/test_openapi_callbacks/test_tutorial001.py @@ -195,6 +195,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_openapi_webhooks/test_tutorial001.py b/tests/test_tutorial/test_openapi_webhooks/test_tutorial001.py index 27619489fa..c58e0fd02c 100644 --- a/tests/test_tutorial/test_openapi_webhooks/test_tutorial001.py +++ b/tests/test_tutorial/test_openapi_webhooks/test_tutorial001.py @@ -98,6 +98,8 @@ def test_openapi_schema(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_path_operation_advanced_configurations/test_tutorial004.py b/tests/test_tutorial/test_path_operation_advanced_configurations/test_tutorial004.py index a95540731d..75b08a4e75 100644 --- a/tests/test_tutorial/test_path_operation_advanced_configurations/test_tutorial004.py +++ b/tests/test_tutorial/test_path_operation_advanced_configurations/test_tutorial004.py @@ -118,6 +118,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_path_operation_configurations/test_tutorial001.py b/tests/test_tutorial/test_path_operation_configurations/test_tutorial001.py index 085d1f5e19..de81251d04 100644 --- a/tests/test_tutorial/test_path_operation_configurations/test_tutorial001.py +++ b/tests/test_tutorial/test_path_operation_configurations/test_tutorial001.py @@ -150,6 +150,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_path_operation_configurations/test_tutorial002.py b/tests/test_tutorial/test_path_operation_configurations/test_tutorial002.py index c7414d756a..28e5e7d8d1 100644 --- a/tests/test_tutorial/test_path_operation_configurations/test_tutorial002.py +++ b/tests/test_tutorial/test_path_operation_configurations/test_tutorial002.py @@ -187,6 +187,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_path_operation_configurations/test_tutorial003_tutorial004.py b/tests/test_tutorial/test_path_operation_configurations/test_tutorial003_tutorial004.py index 791db24625..e42c3e2b73 100644 --- a/tests/test_tutorial/test_path_operation_configurations/test_tutorial003_tutorial004.py +++ b/tests/test_tutorial/test_path_operation_configurations/test_tutorial003_tutorial004.py @@ -172,6 +172,8 @@ def test_openapi_schema(client: TestClient, mod_name: str): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_path_operation_configurations/test_tutorial005.py b/tests/test_tutorial/test_path_operation_configurations/test_tutorial005.py index c5a3aec1d9..b684c9f5c2 100644 --- a/tests/test_tutorial/test_path_operation_configurations/test_tutorial005.py +++ b/tests/test_tutorial/test_path_operation_configurations/test_tutorial005.py @@ -117,6 +117,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_path_params/test_tutorial001.py b/tests/test_tutorial/test_path_params/test_tutorial001.py index a898e386fb..f54626f339 100644 --- a/tests/test_tutorial/test_path_params/test_tutorial001.py +++ b/tests/test_tutorial/test_path_params/test_tutorial001.py @@ -80,6 +80,8 @@ def test_openapi_schema(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_path_params/test_tutorial002.py b/tests/test_tutorial/test_path_params/test_tutorial002.py index 0bfc9f807e..46da41b481 100644 --- a/tests/test_tutorial/test_path_params/test_tutorial002.py +++ b/tests/test_tutorial/test_path_params/test_tutorial002.py @@ -88,6 +88,8 @@ def test_openapi_schema(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_path_params/test_tutorial003.py b/tests/test_tutorial/test_path_params/test_tutorial003.py index cd2c39ab06..6ac92c87e3 100644 --- a/tests/test_tutorial/test_path_params/test_tutorial003.py +++ b/tests/test_tutorial/test_path_params/test_tutorial003.py @@ -97,6 +97,8 @@ def test_openapi_schema(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_path_params/test_tutorial004.py b/tests/test_tutorial/test_path_params/test_tutorial004.py index f7f233ccff..8f460fb695 100644 --- a/tests/test_tutorial/test_path_params/test_tutorial004.py +++ b/tests/test_tutorial/test_path_params/test_tutorial004.py @@ -73,6 +73,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_path_params/test_tutorial005.py b/tests/test_tutorial/test_path_params/test_tutorial005.py index 86ccce7b6d..3e3766e845 100644 --- a/tests/test_tutorial/test_path_params/test_tutorial005.py +++ b/tests/test_tutorial/test_path_params/test_tutorial005.py @@ -110,6 +110,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial001.py b/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial001.py index f1e3041030..a4d68d01b4 100644 --- a/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial001.py +++ b/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial001.py @@ -128,6 +128,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial002_tutorial003.py b/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial002_tutorial003.py index 467c915dcd..37533bd228 100644 --- a/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial002_tutorial003.py +++ b/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial002_tutorial003.py @@ -134,6 +134,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial004.py b/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial004.py index d3593c984c..a9c111a594 100644 --- a/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial004.py +++ b/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial004.py @@ -149,6 +149,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial005.py b/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial005.py index 296192593b..e0e976d6f3 100644 --- a/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial005.py +++ b/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial005.py @@ -166,6 +166,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial006.py b/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial006.py index 9dc7d7aac2..2004ad1d2b 100644 --- a/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial006.py +++ b/tests/test_tutorial/test_path_params_numeric_validations/test_tutorial006.py @@ -185,6 +185,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_query_param_models/test_tutorial001.py b/tests/test_tutorial/test_query_param_models/test_tutorial001.py index d3ce57121d..38b767154a 100644 --- a/tests/test_tutorial/test_query_param_models/test_tutorial001.py +++ b/tests/test_tutorial/test_query_param_models/test_tutorial001.py @@ -207,6 +207,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_query_param_models/test_tutorial002.py b/tests/test_tutorial/test_query_param_models/test_tutorial002.py index 96abce6ab9..b173a2df45 100644 --- a/tests/test_tutorial/test_query_param_models/test_tutorial002.py +++ b/tests/test_tutorial/test_query_param_models/test_tutorial002.py @@ -213,6 +213,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_query_params/test_tutorial001.py b/tests/test_tutorial/test_query_params/test_tutorial001.py index 4c92b57b8d..84e4557272 100644 --- a/tests/test_tutorial/test_query_params/test_tutorial001.py +++ b/tests/test_tutorial/test_query_params/test_tutorial001.py @@ -108,6 +108,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params/test_tutorial002.py b/tests/test_tutorial/test_query_params/test_tutorial002.py index ae3ee7613d..f725c80b32 100644 --- a/tests/test_tutorial/test_query_params/test_tutorial002.py +++ b/tests/test_tutorial/test_query_params/test_tutorial002.py @@ -109,6 +109,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params/test_tutorial003.py b/tests/test_tutorial/test_query_params/test_tutorial003.py index c0b7e3b133..9f1f2e6e4c 100644 --- a/tests/test_tutorial/test_query_params/test_tutorial003.py +++ b/tests/test_tutorial/test_query_params/test_tutorial003.py @@ -130,6 +130,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params/test_tutorial004.py b/tests/test_tutorial/test_query_params/test_tutorial004.py index 9be18b74df..e834f973a9 100644 --- a/tests/test_tutorial/test_query_params/test_tutorial004.py +++ b/tests/test_tutorial/test_query_params/test_tutorial004.py @@ -138,6 +138,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params/test_tutorial005.py b/tests/test_tutorial/test_query_params/test_tutorial005.py index 1030781472..36129dbc96 100644 --- a/tests/test_tutorial/test_query_params/test_tutorial005.py +++ b/tests/test_tutorial/test_query_params/test_tutorial005.py @@ -86,6 +86,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params/test_tutorial006.py b/tests/test_tutorial/test_query_params/test_tutorial006.py index 157322c7e3..473dc33661 100644 --- a/tests/test_tutorial/test_query_params/test_tutorial006.py +++ b/tests/test_tutorial/test_query_params/test_tutorial006.py @@ -137,6 +137,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial001.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial001.py index f1af7e08c1..069921629e 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial001.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial001.py @@ -103,6 +103,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial002.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial002.py index 62018b80b5..a043b5b2e7 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial002.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial002.py @@ -124,6 +124,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial003.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial003.py index a4ad7a63ba..68c6e6174f 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial003.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial003.py @@ -135,6 +135,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial004.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial004.py index 585989a827..79538f952b 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial004.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial004.py @@ -129,6 +129,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial005.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial005.py index 52462fe33b..fafbd0a7d0 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial005.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial005.py @@ -113,6 +113,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial006.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial006.py index 640cedce19..1d01492c66 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial006.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial006.py @@ -118,6 +118,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial006c.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial006c.py index f287b5dcd8..d31cb5036a 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial006c.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial006c.py @@ -130,6 +130,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial007.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial007.py index b17bc27719..e030902451 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial007.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial007.py @@ -118,6 +118,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial008.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial008.py index c631115744..186de5e062 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial008.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial008.py @@ -120,6 +120,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial009.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial009.py index 7e9d69d41c..b242a75c90 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial009.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial009.py @@ -105,6 +105,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial010.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial010.py index 00889c5bf7..6a39130af2 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial010.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial010.py @@ -136,6 +136,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial011.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial011.py index 11de33ae14..6ab279bf3e 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial011.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial011.py @@ -98,6 +98,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial012.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial012.py index 1826928611..41bfeb3a7a 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial012.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial012.py @@ -93,6 +93,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial013.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial013.py index 46c367c86b..52c8147ffb 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial013.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial013.py @@ -93,6 +93,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial014.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial014.py index 0feaccfa44..bb168f0fc3 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial014.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial014.py @@ -93,6 +93,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial015.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial015.py index 82bb606a9b..32a990e748 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial015.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial015.py @@ -122,6 +122,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_request_files/test_tutorial001.py b/tests/test_tutorial/test_request_files/test_tutorial001.py index e0e1bbe639..db9b83b31a 100644 --- a/tests/test_tutorial/test_request_files/test_tutorial001.py +++ b/tests/test_tutorial/test_request_files/test_tutorial001.py @@ -183,6 +183,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_request_files/test_tutorial001_02.py b/tests/test_tutorial/test_request_files/test_tutorial001_02.py index 18948c5444..feeb5363ed 100644 --- a/tests/test_tutorial/test_request_files/test_tutorial001_02.py +++ b/tests/test_tutorial/test_request_files/test_tutorial001_02.py @@ -173,6 +173,8 @@ def test_openapi_schema(client: TestClient): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", diff --git a/tests/test_tutorial/test_request_files/test_tutorial001_03.py b/tests/test_tutorial/test_request_files/test_tutorial001_03.py index 53a7a0cf85..903452ac76 100644 --- a/tests/test_tutorial/test_request_files/test_tutorial001_03.py +++ b/tests/test_tutorial/test_request_files/test_tutorial001_03.py @@ -163,6 +163,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_request_files/test_tutorial002.py b/tests/test_tutorial/test_request_files/test_tutorial002.py index 03772419ad..4d9ff0e93d 100644 --- a/tests/test_tutorial/test_request_files/test_tutorial002.py +++ b/tests/test_tutorial/test_request_files/test_tutorial002.py @@ -223,6 +223,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_request_files/test_tutorial003.py b/tests/test_tutorial/test_request_files/test_tutorial003.py index fa4bfd5695..c9f7f09940 100644 --- a/tests/test_tutorial/test_request_files/test_tutorial003.py +++ b/tests/test_tutorial/test_request_files/test_tutorial003.py @@ -206,6 +206,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_request_form_models/test_tutorial001.py b/tests/test_tutorial/test_request_form_models/test_tutorial001.py index 0c43dd7b21..c4740ee72d 100644 --- a/tests/test_tutorial/test_request_form_models/test_tutorial001.py +++ b/tests/test_tutorial/test_request_form_models/test_tutorial001.py @@ -159,6 +159,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_request_form_models/test_tutorial002.py b/tests/test_tutorial/test_request_form_models/test_tutorial002.py index 238f8fa2ef..b07fce432a 100644 --- a/tests/test_tutorial/test_request_form_models/test_tutorial002.py +++ b/tests/test_tutorial/test_request_form_models/test_tutorial002.py @@ -177,6 +177,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_request_forms/test_tutorial001.py b/tests/test_tutorial/test_request_forms/test_tutorial001.py index 4276414fc2..f5f76306e9 100644 --- a/tests/test_tutorial/test_request_forms/test_tutorial001.py +++ b/tests/test_tutorial/test_request_forms/test_tutorial001.py @@ -161,6 +161,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_request_forms_and_files/test_tutorial001.py b/tests/test_tutorial/test_request_forms_and_files/test_tutorial001.py index 7fa4c3de57..cd05a1ccf1 100644 --- a/tests/test_tutorial/test_request_forms_and_files/test_tutorial001.py +++ b/tests/test_tutorial/test_request_forms_and_files/test_tutorial001.py @@ -216,6 +216,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_response_directly/test_tutorial001.py b/tests/test_tutorial/test_response_directly/test_tutorial001.py index 2d0c387195..76e7143bda 100644 --- a/tests/test_tutorial/test_response_directly/test_tutorial001.py +++ b/tests/test_tutorial/test_response_directly/test_tutorial001.py @@ -130,6 +130,8 @@ def test_openapi_schema_pv2(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_tutorial/test_response_model/test_tutorial001_tutorial001_01.py b/tests/test_tutorial/test_response_model/test_tutorial001_tutorial001_01.py index 10692f9904..265162f15f 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial001_tutorial001_01.py +++ b/tests/test_tutorial/test_response_model/test_tutorial001_tutorial001_01.py @@ -175,6 +175,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_response_model/test_tutorial002.py b/tests/test_tutorial/test_response_model/test_tutorial002.py index 216d4c420c..17027d3c10 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial002.py +++ b/tests/test_tutorial/test_response_model/test_tutorial002.py @@ -111,6 +111,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_response_model/test_tutorial003.py b/tests/test_tutorial/test_response_model/test_tutorial003.py index 35ed5572dd..a1477b7dfd 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial003.py +++ b/tests/test_tutorial/test_response_model/test_tutorial003.py @@ -126,6 +126,8 @@ def test_openapi_schema(client: TestClient): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", diff --git a/tests/test_tutorial/test_response_model/test_tutorial003_01.py b/tests/test_tutorial/test_response_model/test_tutorial003_01.py index fa1eb62770..a60a14ae8d 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial003_01.py +++ b/tests/test_tutorial/test_response_model/test_tutorial003_01.py @@ -139,6 +139,8 @@ def test_openapi_schema(client: TestClient): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", diff --git a/tests/test_tutorial/test_response_model/test_tutorial003_02.py b/tests/test_tutorial/test_response_model/test_tutorial003_02.py index b7507b7110..fcd5f9a1d4 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial003_02.py +++ b/tests/test_tutorial/test_response_model/test_tutorial003_02.py @@ -86,6 +86,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_response_model/test_tutorial003_05.py b/tests/test_tutorial/test_response_model/test_tutorial003_05.py index 19a7c601bb..e64ed1a804 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial003_05.py +++ b/tests/test_tutorial/test_response_model/test_tutorial003_05.py @@ -101,6 +101,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_response_model/test_tutorial004.py b/tests/test_tutorial/test_response_model/test_tutorial004.py index 9c0d95ebd0..d40bce261b 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial004.py +++ b/tests/test_tutorial/test_response_model/test_tutorial004.py @@ -117,6 +117,8 @@ def test_openapi_schema(client: TestClient): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", diff --git a/tests/test_tutorial/test_response_model/test_tutorial005.py b/tests/test_tutorial/test_response_model/test_tutorial005.py index 63e8535db0..55b2334d46 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial005.py +++ b/tests/test_tutorial/test_response_model/test_tutorial005.py @@ -135,6 +135,8 @@ def test_openapi_schema(client: TestClient): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", diff --git a/tests/test_tutorial/test_response_model/test_tutorial006.py b/tests/test_tutorial/test_response_model/test_tutorial006.py index 08ab659527..5d6f542b5d 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial006.py +++ b/tests/test_tutorial/test_response_model/test_tutorial006.py @@ -135,6 +135,8 @@ def test_openapi_schema(client: TestClient): "required": ["loc", "msg", "type"], "type": "object", "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "title": "Location", "type": "array", diff --git a/tests/test_tutorial/test_response_status_code/test_tutorial001_tutorial002.py b/tests/test_tutorial/test_response_status_code/test_tutorial001_tutorial002.py index ddf55a045d..8b6213e33d 100644 --- a/tests/test_tutorial/test_response_status_code/test_tutorial001_tutorial002.py +++ b/tests/test_tutorial/test_response_status_code/test_tutorial001_tutorial002.py @@ -78,6 +78,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_schema_extra_example/test_tutorial001.py b/tests/test_tutorial/test_schema_extra_example/test_tutorial001.py index 82f69fd463..7f0105a26d 100644 --- a/tests/test_tutorial/test_schema_extra_example/test_tutorial001.py +++ b/tests/test_tutorial/test_schema_extra_example/test_tutorial001.py @@ -120,6 +120,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_schema_extra_example/test_tutorial002.py b/tests/test_tutorial/test_schema_extra_example/test_tutorial002.py index 4f52408605..32707c2993 100644 --- a/tests/test_tutorial/test_schema_extra_example/test_tutorial002.py +++ b/tests/test_tutorial/test_schema_extra_example/test_tutorial002.py @@ -122,6 +122,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_schema_extra_example/test_tutorial003.py b/tests/test_tutorial/test_schema_extra_example/test_tutorial003.py index 3529a9bf02..4f8f1394c1 100644 --- a/tests/test_tutorial/test_schema_extra_example/test_tutorial003.py +++ b/tests/test_tutorial/test_schema_extra_example/test_tutorial003.py @@ -124,6 +124,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_schema_extra_example/test_tutorial004.py b/tests/test_tutorial/test_schema_extra_example/test_tutorial004.py index 9326e06290..3a0a7704bf 100644 --- a/tests/test_tutorial/test_schema_extra_example/test_tutorial004.py +++ b/tests/test_tutorial/test_schema_extra_example/test_tutorial004.py @@ -140,6 +140,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_schema_extra_example/test_tutorial005.py b/tests/test_tutorial/test_schema_extra_example/test_tutorial005.py index 2d0dee48ca..b10f25e262 100644 --- a/tests/test_tutorial/test_schema_extra_example/test_tutorial005.py +++ b/tests/test_tutorial/test_schema_extra_example/test_tutorial005.py @@ -149,6 +149,8 @@ def test_openapi_schema(client: TestClient) -> None: }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, } diff --git a/tests/test_tutorial/test_security/test_tutorial003.py b/tests/test_tutorial/test_security/test_tutorial003.py index 6a786348cf..924b36b3ab 100644 --- a/tests/test_tutorial/test_security/test_tutorial003.py +++ b/tests/test_tutorial/test_security/test_tutorial003.py @@ -182,6 +182,8 @@ def test_openapi_schema(client: TestClient): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_security/test_tutorial004.py b/tests/test_tutorial/test_security/test_tutorial004.py index b5e3d39ef7..2b0df66a2e 100644 --- a/tests/test_tutorial/test_security/test_tutorial004.py +++ b/tests/test_tutorial/test_security/test_tutorial004.py @@ -334,6 +334,8 @@ def test_openapi_schema(mod: ModuleType): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_security/test_tutorial005.py b/tests/test_tutorial/test_security/test_tutorial005.py index 25b47f0adc..76b08860f5 100644 --- a/tests/test_tutorial/test_security/test_tutorial005.py +++ b/tests/test_tutorial/test_security/test_tutorial005.py @@ -379,6 +379,8 @@ def test_openapi_schema(mod: ModuleType): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_tutorial/test_separate_openapi_schemas/test_tutorial001.py b/tests/test_tutorial/test_separate_openapi_schemas/test_tutorial001.py index 275b234877..d0a0d5d388 100644 --- a/tests/test_tutorial/test_separate_openapi_schemas/test_tutorial001.py +++ b/tests/test_tutorial/test_separate_openapi_schemas/test_tutorial001.py @@ -121,6 +121,8 @@ def test_openapi_schema(client: TestClient) -> None: }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_separate_openapi_schemas/test_tutorial002.py b/tests/test_tutorial/test_separate_openapi_schemas/test_tutorial002.py index 8230e39226..a2fa56f932 100644 --- a/tests/test_tutorial/test_separate_openapi_schemas/test_tutorial002.py +++ b/tests/test_tutorial/test_separate_openapi_schemas/test_tutorial002.py @@ -121,6 +121,8 @@ def test_openapi_schema(client: TestClient) -> None: }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_sql_databases/test_tutorial001.py b/tests/test_tutorial/test_sql_databases/test_tutorial001.py index 2c628f5257..aec20e42e1 100644 --- a/tests/test_tutorial/test_sql_databases/test_tutorial001.py +++ b/tests/test_tutorial/test_sql_databases/test_tutorial001.py @@ -335,6 +335,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_sql_databases/test_tutorial002.py b/tests/test_tutorial/test_sql_databases/test_tutorial002.py index c72c16e9ae..4ea7d5f647 100644 --- a/tests/test_tutorial/test_sql_databases/test_tutorial002.py +++ b/tests/test_tutorial/test_sql_databases/test_tutorial002.py @@ -416,6 +416,8 @@ def test_openapi_schema(client: TestClient): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_tutorial/test_using_request_directly/test_tutorial001.py b/tests/test_tutorial/test_using_request_directly/test_tutorial001.py index 33e661b164..b55bfb4567 100644 --- a/tests/test_tutorial/test_using_request_directly/test_tutorial001.py +++ b/tests/test_tutorial/test_using_request_directly/test_tutorial001.py @@ -76,6 +76,8 @@ def test_openapi(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [ diff --git a/tests/test_union_body.py b/tests/test_union_body.py index ee7fcc4231..ee56bb6eb1 100644 --- a/tests/test_union_body.py +++ b/tests/test_union_body.py @@ -111,6 +111,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_union_body_discriminator.py b/tests/test_union_body_discriminator.py index 6c31649bcc..4afe7be4b4 100644 --- a/tests/test_union_body_discriminator.py +++ b/tests/test_union_body_discriminator.py @@ -154,6 +154,8 @@ def test_discriminator_pydantic_v2() -> None: }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_union_body_discriminator_annotated.py b/tests/test_union_body_discriminator_annotated.py index 42a6aed24c..6644d106c8 100644 --- a/tests/test_union_body_discriminator_annotated.py +++ b/tests/test_union_body_discriminator_annotated.py @@ -181,6 +181,8 @@ def test_openapi_schema(client: TestClient) -> None: }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_union_forms.py b/tests/test_union_forms.py index 018949f0c7..d90d0753a9 100644 --- a/tests/test_union_forms.py +++ b/tests/test_union_forms.py @@ -136,6 +136,8 @@ def test_openapi_schema(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] diff --git a/tests/test_union_inherited_body.py b/tests/test_union_inherited_body.py index 3c062e7f5a..6b284c68c3 100644 --- a/tests/test_union_inherited_body.py +++ b/tests/test_union_inherited_body.py @@ -117,6 +117,8 @@ def test_openapi_schema(): }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, + "input": {"title": "Input"}, + "ctx": {"title": "Context", "type": "object"}, }, }, "HTTPValidationError": { diff --git a/tests/test_webhooks_security.py b/tests/test_webhooks_security.py index 982ae1e21d..c2c2809b2f 100644 --- a/tests/test_webhooks_security.py +++ b/tests/test_webhooks_security.py @@ -106,6 +106,8 @@ def test_openapi_schema(): }, "ValidationError": { "properties": { + "ctx": {"title": "Context", "type": "object"}, + "input": {"title": "Input"}, "loc": { "items": { "anyOf": [{"type": "string"}, {"type": "integer"}] From 4a3a71f1c15c415c60faab3de59e35b97dd632e3 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 14:34:39 +0000 Subject: [PATCH 100/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 8d90983d44..b4fd20de20 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -14,6 +14,7 @@ hide: ### Fixes +* 🐛 Update `ValidationError` schema to include `input` and `ctx`. PR [#14791](https://github.com/fastapi/fastapi/pull/14791) by [@jonathan-fulton](https://github.com/jonathan-fulton). * 🐛 Fix TYPE_CHECKING annotations for Python 3.14 (PEP 649). PR [#14789](https://github.com/fastapi/fastapi/pull/14789) by [@mgu](https://github.com/mgu). * 🐛 Strip whitespaces from `Authorization` header credentials. PR [#14786](https://github.com/fastapi/fastapi/pull/14786) by [@WaveTheory1](https://github.com/WaveTheory1). * 🐛 Fix OpenAPI duplication of `anyOf` refs for app-level responses with specified `content` and `model` as `Union`. PR [#14463](https://github.com/fastapi/fastapi/pull/14463) by [@DJMcoder](https://github.com/DJMcoder). From ee0c12521fa0817cc19a4cbbd949c1e9d5fec1aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Wed, 4 Feb 2026 06:35:17 -0800 Subject: [PATCH 101/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20docs=20for=20co?= =?UTF-8?q?ntributing=20translations,=20simplify=20title=20(#14817)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/docs/contributing.md b/docs/en/docs/contributing.md index 1505dfd1e9..5e6d821b31 100644 --- a/docs/en/docs/contributing.md +++ b/docs/en/docs/contributing.md @@ -181,7 +181,7 @@ Help with translations is VERY MUCH appreciated! And it can't be done without th Here are the steps to help with translations. -#### Review Translation PRs +#### Translation PRs Translation pull requests are made by LLMs guided with prompts designed by the FastAPI team together with the community of native speakers for each supported language. From fe5b617aecaeba0261dc8c7a1b82afe483814cd2 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 14:36:09 +0000 Subject: [PATCH 102/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index b4fd20de20..937e2930df 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -27,6 +27,7 @@ hide: ### Docs +* 📝 Update docs for contributing translations, simplify title. PR [#14817](https://github.com/fastapi/fastapi/pull/14817) by [@tiangolo](https://github.com/tiangolo). * 📝 Fix typing issue in `docs_src/app_testing/app_b` code example. PR [#14573](https://github.com/fastapi/fastapi/pull/14573) by [@timakaa](https://github.com/timakaa). * 📝 Fix example of license identifier in documentation. PR [#14492](https://github.com/fastapi/fastapi/pull/14492) by [@johnson-earls](https://github.com/johnson-earls). * 📝 Add banner to translated pages. PR [#14809](https://github.com/fastapi/fastapi/pull/14809) by [@YuriiMotov](https://github.com/YuriiMotov). From aea61373ae0c97b32611fc2dc993e84a9729edf8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Wed, 4 Feb 2026 06:49:18 -0800 Subject: [PATCH 103/108] =?UTF-8?q?=F0=9F=90=9B=20Fix=20translation=20scri?= =?UTF-8?q?pt=20commit=20in=20place=20(#14818)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- scripts/translate.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/translate.py b/scripts/translate.py index 9eda7b3903..072383514b 100644 --- a/scripts/translate.py +++ b/scripts/translate.py @@ -411,7 +411,8 @@ def make_pr( print(f"Creating a new branch {branch_name}") subprocess.run(["git", "checkout", "-b", branch_name], check=True) else: - print(f"Committing in place on branch {current_branch}") + branch_name = current_branch + print(f"Committing in place on branch {branch_name}") print("Adding updated files") git_path = Path("docs") subprocess.run(["git", "add", str(git_path)], check=True) From cec4be00ba524427cc52e9894112199c27fce9f1 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 14:49:41 +0000 Subject: [PATCH 104/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 937e2930df..1a56e5eca9 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -68,6 +68,7 @@ hide: ### Internal +* 🐛 Fix translation script commit in place. PR [#14818](https://github.com/fastapi/fastapi/pull/14818) by [@tiangolo](https://github.com/tiangolo). * 🔚 Update translation script to retry if LLM-response doesn't pass validation with Translation Fixer tool. PR [#14749](https://github.com/fastapi/fastapi/pull/14749) by [@YuriiMotov](https://github.com/YuriiMotov). * 👷 Run tests only on relevant code changes (not on docs). PR [#14813](https://github.com/fastapi/fastapi/pull/14813) by [@tiangolo](https://github.com/tiangolo). * 👷 Run mypy by pre-commit. PR [#14806](https://github.com/fastapi/fastapi/pull/14806) by [@YuriiMotov](https://github.com/YuriiMotov). From b0e99d66e80426f3f13dd4bcbcb78d2a39ec10b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Wed, 4 Feb 2026 08:44:21 -0800 Subject: [PATCH 105/108] =?UTF-8?q?=F0=9F=8C=90=20Update=20translations=20?= =?UTF-8?q?for=20ja=20(update-outdated)=20(#14588)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: github-actions[bot] Co-authored-by: Yurii Motov Co-authored-by: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com> Co-authored-by: Maruo.S --- docs/en/mkdocs.yml | 2 + .../docs/advanced/additional-status-codes.md | 34 +- docs/ja/docs/advanced/custom-response.md | 224 ++++++--- docs/ja/docs/advanced/index.md | 24 +- .../path-operation-advanced-configuration.md | 157 +++++- docs/ja/docs/advanced/response-directly.md | 14 +- docs/ja/docs/advanced/websockets.md | 72 ++- docs/ja/docs/benchmarks.md | 36 +- docs/ja/docs/deployment/concepts.md | 92 ++-- docs/ja/docs/deployment/docker.md | 440 ++++++----------- docs/ja/docs/deployment/https.md | 86 ++-- docs/ja/docs/deployment/index.md | 24 +- docs/ja/docs/deployment/server-workers.md | 182 +++---- docs/ja/docs/deployment/versions.md | 104 ++-- docs/ja/docs/environment-variables.md | 115 +++-- docs/ja/docs/how-to/conditional-openapi.md | 12 +- docs/ja/docs/index.md | 453 +++++++++++------- docs/ja/docs/learn/index.md | 4 +- docs/ja/docs/project-generation.md | 102 +--- docs/ja/docs/python-types.md | 366 +++++++++----- docs/ja/docs/tutorial/background-tasks.md | 46 +- docs/ja/docs/tutorial/body-fields.md | 22 +- docs/ja/docs/tutorial/body-multiple-params.md | 63 +-- docs/ja/docs/tutorial/body-nested-models.md | 108 ++--- docs/ja/docs/tutorial/body-updates.md | 38 +- docs/ja/docs/tutorial/body.md | 138 +++--- docs/ja/docs/tutorial/cookie-param-models.md | 25 +- docs/ja/docs/tutorial/cookie-params.md | 24 +- docs/ja/docs/tutorial/cors.md | 42 +- docs/ja/docs/tutorial/debugging.md | 14 +- .../dependencies/classes-as-dependencies.md | 150 +++++- ...pendencies-in-path-operation-decorators.md | 62 ++- .../dependencies/dependencies-with-yield.md | 185 ++++--- docs/ja/docs/tutorial/dependencies/index.md | 128 +++-- .../tutorial/dependencies/sub-dependencies.md | 49 +- docs/ja/docs/tutorial/encoder.md | 10 +- docs/ja/docs/tutorial/extra-data-types.md | 42 +- docs/ja/docs/tutorial/extra-models.md | 90 ++-- docs/ja/docs/tutorial/first-steps.md | 214 +++++---- docs/ja/docs/tutorial/handling-errors.md | 103 ++-- docs/ja/docs/tutorial/header-params.md | 36 +- docs/ja/docs/tutorial/index.md | 90 ++-- docs/ja/docs/tutorial/metadata.md | 105 ++-- docs/ja/docs/tutorial/middleware.md | 47 +- .../tutorial/path-operation-configuration.md | 58 ++- .../path-params-numeric-validations.md | 111 +++-- docs/ja/docs/tutorial/path-params.md | 125 ++--- docs/ja/docs/tutorial/query-param-models.md | 22 +- .../tutorial/query-params-str-validations.md | 360 ++++++++++---- docs/ja/docs/tutorial/query-params.md | 64 +-- .../docs/tutorial/request-forms-and-files.md | 20 +- docs/ja/docs/tutorial/request-forms.md | 24 +- docs/ja/docs/tutorial/response-model.md | 297 ++++++++---- docs/ja/docs/tutorial/response-status-code.md | 40 +- docs/ja/docs/tutorial/schema-extra-example.md | 201 ++++++-- docs/ja/docs/tutorial/security/first-steps.md | 66 +-- .../tutorial/security/get-current-user.md | 47 +- docs/ja/docs/tutorial/security/oauth2-jwt.md | 88 ++-- docs/ja/docs/tutorial/static-files.md | 18 +- docs/ja/docs/tutorial/testing.md | 99 +++- docs/ja/docs/virtual-environments.md | 102 ++-- docs/ja/llm-prompt.md | 3 +- scripts/docs.py | 1 + 63 files changed, 3658 insertions(+), 2462 deletions(-) diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml index 1c29546198..34d489d92a 100644 --- a/docs/en/mkdocs.yml +++ b/docs/en/mkdocs.yml @@ -317,6 +317,8 @@ extra: name: de - Deutsch - link: /es/ name: es - español + - link: /ja/ + name: ja - 日本語 - link: /ko/ name: ko - 한국얎 - link: /pt/ diff --git a/docs/ja/docs/advanced/additional-status-codes.md b/docs/ja/docs/advanced/additional-status-codes.md index 33457f591c..14b7e8ba87 100644 --- a/docs/ja/docs/advanced/additional-status-codes.md +++ b/docs/ja/docs/advanced/additional-status-codes.md @@ -1,41 +1,41 @@ -# 远加のステヌタスコヌド +# 远加のステヌタスコヌド { #additional-status-codes } -デフォルトでは、 **FastAPI** は `JSONResponse` を䜿っおレスポンスを返したす。その `JSONResponse` の䞭には、 *path operation* が返した内容が入りたす。 +デフォルトでは、 **FastAPI** は `JSONResponse` を䜿っおレスポンスを返し、*path operation* から返した内容をその `JSONResponse` の䞭に入れたす。 -それは、デフォルトのステヌタスコヌドか、 *path operation* でセットしたものを利甚したす。 +デフォルトのステヌタスコヌド、たたは *path operation* で蚭定したステヌタスコヌドが䜿甚されたす。 -## 远加のステヌタスコヌド +## 远加のステヌタスコヌド { #additional-status-codes_1 } -メむンのステヌタスコヌドずは別に、他のステヌタスコヌドを返したい堎合は、`Response` (`JSONResponse` など) に远加のステヌタスコヌドを蚭定しお盎接返したす。 +メむンのステヌタスコヌドずは別に远加のステヌタスコヌドを返したい堎合は、`JSONResponse` のような `Response` を盎接返し、远加のステヌタスコヌドを盎接蚭定できたす。 -䟋えば、itemを曎新し、成功した堎合は200 "OK"のHTTPステヌタスコヌドを返す *path operation* を䜜りたいずしたす。 +たずえば、item を曎新でき、成功時に HTTP ステヌタスコヌド 200 "OK" を返す *path operation* を䜜りたいずしたす。 -しかし、新しいitemも蚱可したいです。itemが存圚しない堎合は、それらを䜜成しお201 "Created"を返したす。 +しかし、新しい item も受け付けたいずしたす。そしお、item が以前存圚しなかった堎合には䜜成し、HTTP ステヌタスコヌド 201「Created」を返したす。 -これを達成するには、 `JSONResponse` をむンポヌトし、 `status_code` を蚭定しお盎接内容を返したす。 +これを実珟するには、`JSONResponse` をむンポヌトし、望む `status_code` を蚭定しお、そこで内容を盎接返したす。 -{* ../../docs_src/additional_status_codes/tutorial001.py hl[4,25] *} +{* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *} /// warning | 泚意 -䞊蚘の䟋のように `Response` を明瀺的に返す堎合、それは盎接返されたす。 +䞊の䟋のように `Response` を盎接返すず、それはそのたた返されたす。 -モデルなどはシリアラむズされたせん。 +モデルなどによっおシリアラむズされたせん。 -必芁なデヌタが含たれおいるこずや、倀が有効なJSONであるこず (`JSONResponse` を䜿う堎合) を確認しおください。 +必芁なデヌタが含たれおいるこず、そしお`JSONResponse` を䜿甚しおいる堎合倀が有効な JSON であるこずを確認しおください。 /// /// note | 技術詳现 -`from starlette.responses import JSONResponse` を利甚するこずもできたす。 +`from starlette.responses import JSONResponse` を䜿うこずもできたす。 -**FastAPI** は `fastapi.responses` ず同じ `starlette.responses` を、開発者の利䟿性のために提䟛しおいたす。しかし有効なレスポンスはほずんどStarletteから来おいたす。 `status` に぀いおも同じです。 +**FastAPI** は開発者の利䟿性のために、`fastapi.responses` ず同じ `starlette.responses` を提䟛しおいたす。しかし、利甚可胜なレスポンスのほずんどは Starlette から盎接提䟛されおいたす。`status` も同様です。 /// -## OpenAPIずAPIドキュメント +## OpenAPI ず API ドキュメント { #openapi-and-api-docs } -ステヌタスコヌドずレスポンスを盎接返す堎合、それらはOpenAPIスキヌマ (APIドキュメント) には含たれたせん。なぜなら、FastAPIは䜕が返されるのか事前に知るこずができないからです。 +远加のステヌタスコヌドずレスポンスを盎接返す堎合、それらは OpenAPI スキヌマAPI ドキュメントには含たれたせん。FastAPI には、事前に䜕が返されるかを知る方法がないからです。 -しかし、 [Additional Responses](additional-responses.md){.internal-link target=_blank} を䜿っおコヌドの䞭にドキュメントを曞くこずができたす。 +しかし、[Additional Responses](additional-responses.md){.internal-link target=_blank} を䜿っおコヌド内にドキュメント化できたす。 diff --git a/docs/ja/docs/advanced/custom-response.md b/docs/ja/docs/advanced/custom-response.md index 1b2cd914d4..9d881c013c 100644 --- a/docs/ja/docs/advanced/custom-response.md +++ b/docs/ja/docs/advanced/custom-response.md @@ -1,34 +1,40 @@ -# カスタムレスポンス - HTML、ストリヌム、ファむル、その他のレスポンス +# カスタムレスポンス - HTML、ストリヌム、ファむル、その他のレスポンス { #custom-response-html-stream-file-others } デフォルトでは、**FastAPI** は `JSONResponse` を䜿っおレスポンスを返したす。 [レスポンスを盎接返す](response-directly.md){.internal-link target=_blank}で芋たように、 `Response` を盎接返すこずでこの挙動をオヌバヌラむドできたす。 -しかし、`Response` を盎接返すず、デヌタは自動的に倉換されず、ドキュメントも自動生成されたせん (䟋えば、生成されるOpenAPIの䞀郚ずしおHTTPヘッダヌ `Content-Type` に特定の「メディアタむプ」を含めるなど) 。 +しかし、`Response` を盎接返すずたたは `JSONResponse` のような任意のサブクラスを返すず、デヌタは自動的に倉換されず`response_model` を宣蚀しおいおも、ドキュメントも自動生成されたせん䟋えば、生成されるOpenAPIの䞀郚ずしおHTTPヘッダヌ `Content-Type` に特定の「メディアタむプ」を含めるなど。 -しかし、*path operationデコレヌタ* に、䜿いたい `Response` を宣蚀するこずもできたす。 +`response_class` パラメヌタを䜿甚しお、*path operation デコレヌタ* で䜿甚したい `Response`任意の `Response` サブクラスを宣蚀するこずもできたす。 -*path operation関数* から返されるコンテンツは、その `Response` に含たれたす。 +*path operation 関数* から返されるコンテンツは、その `Response` に含たれたす。 -そしおもし、`Response` が、`JSONResponse` や `UJSONResponse` の堎合のようにJSONメディアタむプ (`application/json`) ならば、デヌタは *path operationデコレヌタ* に宣蚀したPydantic `response_model` により自動的に倉換 (もしくはフィルタ) されたす。 +そしおその `Response` が、`JSONResponse` や `UJSONResponse` の堎合のようにJSONメディアタむプ`application/json`なら、関数の返り倀は *path operationデコレヌタ* に宣蚀した任意のPydantic `response_model` により自動的に倉換およびフィルタされたす。 /// note | 備考 -メディアタむプを指定せずにレスポンスクラスを利甚するず、FastAPIは䜕もコンテンツがないこずを期埅したす。そのため、生成されるOpenAPIドキュメントにレスポンスフォヌマットが蚘茉されたせん。 +メディアタむプを指定せずにレスポンスクラスを利甚するず、FastAPIはレスポンスにコンテンツがないこずを期埅したす。そのため、生成されるOpenAPIドキュメントにレスポンスフォヌマットが蚘茉されたせん。 /// -## `ORJSONResponse` を䜿う +## `ORJSONResponse` を䜿う { #use-orjsonresponse } -䟋えば、パフォヌマンスを出したい堎合は、`orjson`をむンストヌルし、`ORJSONResponse`をレスポンスずしおセットするこずができたす。 +䟋えば、パフォヌマンスを絞り出したい堎合は、`orjson`をむンストヌルし、レスポンスずしお `ORJSONResponse` をセットできたす。 -䜿いたい `Response` クラス (サブクラス) をむンポヌトし、 *path operationデコレヌタ* に宣蚀したす。 +䜿いたい `Response` クラスサブクラスをむンポヌトし、*path operationデコレヌタ* に宣蚀したす。 -{* ../../docs_src/custom_response/tutorial001b.py hl[2,7] *} +倧きなレスポンスの堎合、`Response` を盎接返すほうが、蟞曞を返すよりもはるかに高速です。 + +これは、デフォルトではFastAPIがチュヌトリアルで説明した同じ[JSON Compatible Encoder](../tutorial/encoder.md){.internal-link target=_blank}を䜿っお、内郚の各アむテムを怜査し、JSONずしおシリアラむズ可胜であるこずを確認するためです。これにより、䟋えばデヌタベヌスモデルのような**任意のオブゞェクト**を返せたす。 + +しかし、返そうずしおいるコンテンツが **JSONでシリアラむズ可胜**であるこずが確実なら、それを盎接レスポンスクラスに枡しお、FastAPIがレスポンスクラスぞ枡す前に返华コンテンツを `jsonable_encoder` に通すこずで発生する远加のオヌバヌヘッドを回避できたす。 + +{* ../../docs_src/custom_response/tutorial001b_py39.py hl[2,7] *} /// info | 情報 -パラメヌタ `response_class` は、レスポンスの「メディアタむプ」を定矩するために利甚するこずもできたす。 +パラメヌタ `response_class` は、レスポンスの「メディアタむプ」を定矩するためにも利甚されたす。 この堎合、HTTPヘッダヌ `Content-Type` には `application/json` がセットされたす。 @@ -38,70 +44,70 @@ /// tip | 豆知識 -`ORJSONResponse` は、珟圚はFastAPIのみで利甚可胜で、Starletteでは利甚できたせん。 +`ORJSONResponse` はFastAPIでのみ利甚可胜で、Starletteでは利甚できたせん。 /// -## HTMLレスポンス +## HTMLレスポンス { #html-response } **FastAPI** からHTMLを盎接返す堎合は、`HTMLResponse` を䜿いたす。 * `HTMLResponse` をむンポヌトする。 -* *path operation* のパラメヌタ `content_type` に `HTMLResponse` を枡す。 +* *path operation デコレヌタ* のパラメヌタ `response_class` に `HTMLResponse` を枡す。 -{* ../../docs_src/custom_response/tutorial002.py hl[2,7] *} +{* ../../docs_src/custom_response/tutorial002_py39.py hl[2,7] *} /// info | 情報 -パラメヌタ `response_class` は、レスポンスの「メディアタむプ」を定矩するために利甚されたす。 +パラメヌタ `response_class` は、レスポンスの「メディアタむプ」を定矩するためにも利甚されたす。 この堎合、HTTPヘッダヌ `Content-Type` には `text/html` がセットされたす。 -そしお、OpenAPIにはそのようにドキュメント化されたす。 +そしお、OpenAPIにはそのようにドキュメントされたす。 /// -### `Response` を返す +### `Response` を返す { #return-a-response } -[レスポンスを盎接返す](response-directly.md){.internal-link target=_blank}で芋たように、レスポンスを盎接返すこずで、*path operation* の䞭でレスポンスをオヌバヌラむドできたす。 +[レスポンスを盎接返す](response-directly.md){.internal-link target=_blank}で芋たように、レスポンスを返すこずで、*path operation* の䞭でレスポンスを盎接オヌバヌラむドするこずもできたす。 䞊蚘ず同じ䟋においお、 `HTMLResponse` を返すず、このようになりたす: -{* ../../docs_src/custom_response/tutorial003.py hl[2,7,19] *} +{* ../../docs_src/custom_response/tutorial003_py39.py hl[2,7,19] *} /// warning | 泚意 -*path operation関数* から盎接返される `Response` は、OpenAPIにドキュメントされず (䟋えば、 `Content-Type` がドキュメントされない) 、自動的な察話的ドキュメントからも閲芧できたせん。 +*path operation関数* から盎接返される `Response` は、OpenAPIにドキュメントされず䟋えば、`Content-Type` がドキュメントされない、自動的な察話的ドキュメントでも衚瀺されたせん。 /// /// info | 情報 -もちろん、実際の `Content-Type` ヘッダヌやステヌタスコヌドなどは、返された `Response` オブゞェクトに由来しおいたす。 +もちろん、実際の `Content-Type` ヘッダヌやステヌタスコヌドなどは、返された `Response` オブゞェクトに由来したす。 /// -### OpenAPIドキュメントず `Response` のオヌバヌラむド +### OpenAPIドキュメントず `Response` のオヌバヌラむド { #document-in-openapi-and-override-response } -関数の䞭でレスポンスをオヌバヌラむドし぀぀も、OpenAPI に「メディアタむプ」をドキュメント化したいなら、 `response_class` パラメヌタを䜿い、 `Response` オブゞェクトを返したす。 +関数の䞭でレスポンスをオヌバヌラむドし぀぀も、OpenAPI に「メディアタむプ」をドキュメント化したいなら、`response_class` パラメヌタを䜿甚し、か぀ `Response` オブゞェクトを返したす。 -`response_class` はOpenAPIの *path operation* ドキュメントにのみ䜿甚されたすが、 `Response` はそのたた䜿甚されたす。 +`response_class` はOpenAPIの*path operation*のドキュメント化のためにのみ䜿甚され、`Response` はそのたた䜿甚されたす。 -#### `HTMLResponse` を盎接返す +#### `HTMLResponse` を盎接返す { #return-an-htmlresponse-directly } 䟋えば、このようになりたす: -{* ../../docs_src/custom_response/tutorial004.py hl[7,21,23] *} +{* ../../docs_src/custom_response/tutorial004_py39.py hl[7,21,23] *} -この䟋では、関数 `generate_html_response()` は、`str` のHTMLを返すのではなく `Response` を生成しお返しおいたす。 +この䟋では、関数 `generate_html_response()` は、`str` のHTMLを返すのではなく、`Response` を生成しお返しおいたす。 -`generate_html_response()` を呌び出した結果を返すこずにより、**FastAPI** の振る舞いを䞊曞きする `Response` が既に返されおいたす。 +`generate_html_response()` を呌び出した結果を返すこずにより、デフォルトの **FastAPI** の挙動をオヌバヌラむドする `Response` をすでに返しおいたす。 -しかし、䞀方では `response_class` に `HTMLResponse` を枡しおいるため、 **FastAPI** はOpenAPIや察話的ドキュメントでHTMLずしお `text/html` でドキュメント化する方法を知っおいたす。 +しかし、`response_class` にも `HTMLResponse` を枡しおいるため、**FastAPI** はOpenAPIず察話的ドキュメントで、`text/html` のHTMLずしおどのようにドキュメント化すればよいかを理解できたす: -## 利甚可胜なレスポンス +## 利甚可胜なレスポンス { #available-responses } 以䞋が利甚可胜なレスポンスの䞀郚です。 @@ -111,11 +117,11 @@ `from starlette.responses import HTMLResponse` も利甚できたす。 -**FastAPI** は開発者の利䟿性のために `fastapi.responses` ずしお `starlette.responses` ず同じものを提䟛しおいたす。しかし、利甚可胜なレスポンスのほずんどはStarletteから盎接提䟛されたす。 +**FastAPI** は開発者の利䟿性のために、`starlette.responses` ず同じものを `fastapi.responses` ずしお提䟛しおいたす。しかし、利甚可胜なレスポンスのほずんどはStarletteから盎接提䟛されたす。 /// -### `Response` +### `Response` { #response } メむンの `Response` クラスで、他の党おのレスポンスはこれを継承しおいたす。 @@ -128,41 +134,53 @@ * `headers` - 文字列の `dict` 。 * `media_type` - メディアタむプを瀺す `str` 。䟋えば `"text/html"` 。 -FastAPI (実際にはStarlette) は自動的にContent-Lengthヘッダヌを含みたす。たた、media_typeに基づいたContent-Typeヘッダヌを含み、テキストタむプのためにcharsetを远加したす。 +FastAPI実際にはStarletteは自動的にContent-Lengthヘッダヌを含みたす。たた、`media_type` に基づいたContent-Typeヘッダヌを含み、テキストタむプのためにcharsetを远加したす。 -{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *} +{* ../../docs_src/response_directly/tutorial002_py39.py hl[1,18] *} -### `HTMLResponse` +### `HTMLResponse` { #htmlresponse } 䞊で読んだように、テキストやバむトを受け取り、HTMLレスポンスを返したす。 -### `PlainTextResponse` +### `PlainTextResponse` { #plaintextresponse } テキストやバむトを受け取り、プレヌンテキストのレスポンスを返したす。 -{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *} +{* ../../docs_src/custom_response/tutorial005_py39.py hl[2,7,9] *} -### `JSONResponse` +### `JSONResponse` { #jsonresponse } -デヌタを受け取り、 `application/json` ずしお゚ンコヌドされたレスポンスを返したす。 +デヌタを受け取り、`application/json` ずしお゚ンコヌドされたレスポンスを返したす。 䞊で読んだように、**FastAPI** のデフォルトのレスポンスずしお利甚されたす。 -### `ORJSONResponse` +### `ORJSONResponse` { #orjsonresponse } 䞊で読んだように、`orjson`を䜿った、高速な代替のJSONレスポンスです。 -### `UJSONResponse` +/// info | 情報 -`ujson`を䜿った、代替のJSONレスポンスです。 - -/// warning | 泚意 - -`ujson` は、いく぀かの゚ッゞケヌスの取り扱いに぀いお、Pythonにビルトむンされた実装よりも䜜りこたれおいたせん。 +これは、䟋えば `pip install orjson` で `orjson` をむンストヌルする必芁がありたす。 /// -{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *} +### `UJSONResponse` { #ujsonresponse } + +`ujson`を䜿った、代替のJSONレスポンスです。 + +/// info | 情報 + +これは、䟋えば `pip install ujson` で `ujson` をむンストヌルする必芁がありたす。 + +/// + +/// warning | 泚意 + +`ujson` は、いく぀かの゚ッゞケヌスの取り扱いに぀いお、Pythonにビルトむンされた実装ほど泚意深くありたせん。 + +/// + +{* ../../docs_src/custom_response/tutorial001_py39.py hl[2,7] *} /// tip | 豆知識 @@ -170,33 +188,61 @@ FastAPI (実際にはStarlette) は自動的にContent-Lengthヘッダヌを含 /// -### `RedirectResponse` +### `RedirectResponse` { #redirectresponse } -HTTPリダむレクトを返したす。デフォルトでは307ステヌタスコヌド (Temporary Redirect) ずなりたす。 +HTTPリダむレクトを返したす。デフォルトでは307ステヌタスコヌドTemporary Redirectずなりたす。 -{* ../../docs_src/custom_response/tutorial006.py hl[2,9] *} +`RedirectResponse` を盎接返せたす: -### `StreamingResponse` +{* ../../docs_src/custom_response/tutorial006_py39.py hl[2,9] *} -非同期なゞェネレヌタか通垞のゞェネレヌタ・むテレヌタを受け取り、レスポンスボディをストリヌムしたす。 +--- -{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *} +たたは、`response_class` パラメヌタで䜿甚できたす: -#### `StreamingResponse` をファむルラむクなオブゞェクトずずもに䜿う +{* ../../docs_src/custom_response/tutorial006b_py39.py hl[2,7,9] *} -ファむルラむクなオブゞェクト (䟋えば、 `open()` で返されたオブゞェクト) がある堎合、 `StreamingResponse` に含めお返すこずができたす。 +その堎合、*path operation*関数からURLを盎接返せたす。 -これにはクラりドストレヌゞずの連携や映像凊理など、倚くのラむブラリが含たれおいたす。 +この堎合に䜿甚される `status_code` は `RedirectResponse` のデフォルトである `307` になりたす。 -{* ../../docs_src/custom_response/tutorial008.py hl[2,10:12,14] *} +--- + +たた、`status_code` パラメヌタを `response_class` パラメヌタず組み合わせお䜿うこずもできたす: + +{* ../../docs_src/custom_response/tutorial006c_py39.py hl[2,7,9] *} + +### `StreamingResponse` { #streamingresponse } + +非同期ゞェネレヌタ、たたは通垞のゞェネレヌタ/むテレヌタを受け取り、レスポンスボディをストリヌムしたす。 + +{* ../../docs_src/custom_response/tutorial007_py39.py hl[2,14] *} + +#### ファむルラむクオブゞェクトで `StreamingResponse` を䜿う { #using-streamingresponse-with-file-like-objects } + +file-like オブゞェクト䟋: `open()` で返されるオブゞェクトがある堎合、そのfile-likeオブゞェクトを反埩凊理するゞェネレヌタ関数を䜜れたす。 + +そうすれば、最初にすべおをメモリぞ読み蟌む必芁はなく、そのゞェネレヌタ関数を `StreamingResponse` に枡しお返せたす。 + +これにはクラりドストレヌゞずの連携、映像凊理など、倚くのラむブラリが含たれたす。 + +{* ../../docs_src/custom_response/tutorial008_py39.py hl[2,10:12,14] *} + +1. これはゞェネレヌタ関数です。内郚に `yield` 文を含むため「ゞェネレヌタ関数」です。 +2. `with` ブロックを䜿うこずで、ゞェネレヌタ関数が終わった埌぀たりレスポンスの送信が完了した埌にfile-likeオブゞェクトが確実にクロヌズされるようにしたす。 +3. この `yield from` は、`file_like` ずいう名前のものを反埩凊理するように関数ぞ指瀺したす。そしお反埩された各パヌトに぀いお、そのパヌトをこのゞェネレヌタ関数`iterfile`から来たものずしお `yield` したす。 + + ぀たり、内郚的に「生成」の䜜業を別のものぞ移譲するゞェネレヌタ関数です。 + + このようにするこずで `with` ブロックに入れられ、完了埌にfile-likeオブゞェクトが確実にクロヌズされたす。 /// tip | 豆知識 -ここでは `async` や `await` をサポヌトしおいない暙準の `open()` を䜿っおいるので、通垞の `def` でpath operationを宣蚀しおいるこずに泚意しおください。 +ここでは `async` ず `await` をサポヌトしおいない暙準の `open()` を䜿っおいるため、通垞の `def` でpath operationを宣蚀しおいる点に泚意しおください。 /// -### `FileResponse` +### `FileResponse` { #fileresponse } レスポンスずしおファむルを非同期的にストリヌムしたす。 @@ -204,29 +250,63 @@ HTTPリダむレクトを返したす。デフォルトでは307ステヌタス * `path` - ストリヌムするファむルのファむルパス。 * `headers` - 含めたい任意のカスタムヘッダヌの蟞曞。 -* `media_type` - メディアタむプを瀺す文字列。セットされなかった堎合は、ファむル名やパスからメディアタむプが掚察されたす。 -* `filename` - セットされた堎合、レスポンスの `Content-Disposition` に含たれたす。 +* `media_type` - メディアタむプを瀺す文字列。未蚭定の堎合、ファむル名やパスからメディアタむプが掚枬されたす。 +* `filename` - 蚭定した堎合、レスポンスの `Content-Disposition` に含たれたす。 -ファむルレスポンスには、適切な `Content-Length` 、 `Last-Modified` 、 `ETag` ヘッダヌが含たれたす。 +ファむルレスポンスには、適切な `Content-Length`、`Last-Modified`、`ETag` ヘッダヌが含たれたす。 -{* ../../docs_src/custom_response/tutorial009.py hl[2,10] *} +{* ../../docs_src/custom_response/tutorial009_py39.py hl[2,10] *} -## デフォルトレスポンスクラス +`response_class` パラメヌタを䜿うこずもできたす: -**FastAPI** クラスのむンスタンスか `APIRouter` を生成するずきに、デフォルトのレスポンスクラスを指定できたす。 +{* ../../docs_src/custom_response/tutorial009b_py39.py hl[2,8,10] *} -定矩するためのパラメヌタは、 `default_response_class` です。 +この堎合、*path operation*関数からファむルパスを盎接返せたす。 -以䞋の䟋では、 **FastAPI** は、党おの *path operation* で `JSONResponse` の代わりに `ORJSONResponse` をデフォルトずしお利甚したす。 +## カスタムレスポンスクラス { #custom-response-class } -{* ../../docs_src/custom_response/tutorial010.py hl[2,4] *} +`Response` を継承した独自のカスタムレスポンスクラスを䜜成しお利甚できたす。 + +䟋えば、`orjson`を䜿いたいが、同梱の `ORJSONResponse` クラスで䜿われおいないカスタム蚭定も䜿いたいずしたす。 + +䟋えば、むンデントされ敎圢されたJSONを返したいので、orjsonオプション `orjson.OPT_INDENT_2` を䜿いたいずしたす。 + +`CustomORJSONResponse` を䜜れたす。䞻に必芁なのは、コンテンツを `bytes` ずしお返す `Response.render(content)` メ゜ッドを䜜るこずです: + +{* ../../docs_src/custom_response/tutorial009c_py39.py hl[9:14,17] *} + +これたでは次のように返しおいたものが: + +```json +{"message": "Hello World"} +``` + +...このレスポンスでは次のように返されたす: + +```json +{ + "message": "Hello World" +} +``` + +もちろん、JSONの敎圢よりも、これを掻甚するもっず良い方法が芋぀かるはずです。 😉 + +## デフォルトレスポンスクラス { #default-response-class } + +**FastAPI** クラスのむンスタンス、たたは `APIRouter` を䜜成する際に、デフォルトで䜿甚するレスポンスクラスを指定できたす。 + +これを定矩するパラメヌタは `default_response_class` です。 + +以䞋の䟋では、**FastAPI** はすべおの*path operation*で、`JSONResponse` の代わりに `ORJSONResponse` をデフォルトずしお䜿いたす。 + +{* ../../docs_src/custom_response/tutorial010_py39.py hl[2,4] *} /// tip | 豆知識 -前に芋たように、 *path operation* の䞭で `response_class` をオヌバヌラむドできたす。 +これたでず同様に、*path operation*で `response_class` をオヌバヌラむドできたす。 /// -## その他のドキュメント +## その他のドキュメント { #additional-documentation } -たた、OpenAPIでは `responses` を䜿っおメディアタむプやその他の詳现を宣蚀するこずもできたす: [Additional Responses in OpenAPI](additional-responses.md){.internal-link target=_blank} +OpenAPIでは `responses` を䜿っおメディアタむプやその他の詳现を宣蚀するこずもできたす: [Additional Responses in OpenAPI](additional-responses.md){.internal-link target=_blank}。 diff --git a/docs/ja/docs/advanced/index.md b/docs/ja/docs/advanced/index.md index 22eaf6eb80..1d0f7566cd 100644 --- a/docs/ja/docs/advanced/index.md +++ b/docs/ja/docs/advanced/index.md @@ -1,27 +1,21 @@ -# 高床なナヌザヌガむド +# 高床なナヌザヌガむド { #advanced-user-guide } -## さらなる機胜 +## さらなる機胜 { #additional-features } -[チュヌトリアル - ナヌザヌガむド](../tutorial/index.md){.internal-link target=_blank}により、**FastAPI**の䞻芁な機胜は十分に理解できたこずでしょう。 +メむンの[チュヌトリアル - ナヌザヌガむド](../tutorial/index.md){.internal-link target=_blank}だけで、**FastAPI**の䞻芁な機胜を䞀通り把握するには十分なはずです。 -以降のセクションでは、チュヌトリアルでは説明しきれなかったオプションや蚭定、および機胜に぀いお説明したす。 +以降のセクションでは、その他のオプション、蚭定、远加機胜を芋おいきたす。 /// tip | 豆知識 -以降のセクションは、 **必ずしも"応甚線"ではありたせん**。 +以降のセクションは、**必ずしも「高床」ではありたせん**。 -ナヌスケヌスによっおは、その䞭から解決策を芋぀けられるかもしれたせん。 +たた、あなたのナヌスケヌスに察する解決策が、その䞭のどれかにある可胜性もありたす。 /// -## 先にチュヌトリアルを読む +## 先にチュヌトリアルを読む { #read-the-tutorial-first } -[チュヌトリアル - ナヌザヌガむド](../tutorial/index.md){.internal-link target=_blank}の知識があれば、**FastAPI**の䞻芁な機胜を利甚するこずができたす。 +メむンの[チュヌトリアル - ナヌザヌガむド](../tutorial/index.md){.internal-link target=_blank}で埗た知識があれば、**FastAPI**の機胜の倚くは匕き続き利甚できたす。 -以降のセクションは、すでにチュヌトリアルを読んで、その䞻芁なアむデアを理解できおいるこずを前提ずしおいたす。 - -## テスト駆動開発のコヌス - -このセクションの内容を補完するために脱初心者甚コヌスを受けたい堎合は、**TestDriven.io**による、Test-Driven Development with FastAPI and Dockerを確認するのがよいかもしれたせん。 - -珟圚、このコヌスで埗られた利益の10%が**FastAPI**の開発のために寄付されおいたす。🎉 😄 +たた、以降のセクションでは、すでにそれを読んでいお、䞻芁な考え方を理解しおいるこずを前提ずしおいたす。 diff --git a/docs/ja/docs/advanced/path-operation-advanced-configuration.md b/docs/ja/docs/advanced/path-operation-advanced-configuration.md index 05188d5b25..a78c3cb026 100644 --- a/docs/ja/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/ja/docs/advanced/path-operation-advanced-configuration.md @@ -1,30 +1,30 @@ -# Path Operationの高床な蚭定 +# Path Operationの高床な蚭定 { #path-operation-advanced-configuration } -## OpenAPI operationId +## OpenAPI operationId { #openapi-operationid } /// warning | 泚意 -あなたがOpenAPIの「゚キスパヌト」でなければ、これは必芁ないかもしれたせん。 +OpenAPIの「゚キスパヌト」でなければ、これはおそらく必芁ありたせん。 /// *path operation* で `operation_id` パラメヌタを利甚するこずで、OpenAPIの `operationId` を蚭定できたす。 -`operation_id` は各オペレヌションで䞀意にする必芁がありたす。 +各オペレヌションで䞀意になるようにする必芁がありたす。 -{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *} +{* ../../docs_src/path_operation_advanced_configuration/tutorial001_py39.py hl[6] *} -### *path operation関数* の名前をoperationIdずしお䜿甚する +### *path operation関数* の名前をoperationIdずしお䜿甚する { #using-the-path-operation-function-name-as-the-operationid } -APIの関数名を `operationId` ずしお利甚したい堎合、すべおのAPIの関数をむテレヌションし、各 *path operation* の `operationId` を `APIRoute.name` で䞊曞きすれば可胜です。 +APIの関数名を `operationId` ずしお利甚したい堎合、すべおのAPI関数をむテレヌションし、各 *path operation* の `operation_id` を `APIRoute.name` で䞊曞きすれば可胜です。 -そうする堎合は、すべおの *path operation* を远加した埌に行う必芁がありたす。 +すべおの *path operation* を远加した埌に行うべきです。 -{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2,12:21,24] *} +{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py39.py hl[2, 12:21, 24] *} /// tip | 豆知識 -`app.openapi()` を手動でコヌルする堎合、その前に`operationId`を曎新する必芁がありたす。 +`app.openapi()` を手動で呌び出す堎合、その前に `operationId` を曎新するべきです。 /// @@ -32,22 +32,141 @@ APIの関数名を `operationId` ずしお利甚したい堎合、すべおのAP この方法をずる堎合、各 *path operation関数* が䞀意な名前である必芁がありたす。 -それらが異なるモゞュヌル (Pythonファむル) にあるずしおもです。 +異なるモゞュヌルPythonファむルにある堎合でも同様です。 /// -## OpenAPIから陀倖する +## OpenAPIから陀倖する { #exclude-from-openapi } -生成されるOpenAPIスキヌマ (぀たり、自動ドキュメント生成の仕組み) から *path operation* を陀倖するには、 `include_in_schema` パラメヌタを `False` にしたす。 +生成されるOpenAPIスキヌマ぀たり、自動ドキュメント生成の仕組みから *path operation* を陀倖するには、`include_in_schema` パラメヌタを䜿甚しお `False` に蚭定したす。 -{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *} +{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py39.py hl[6] *} -## docstringによる説明の高床な蚭定 +## docstringによる説明の高床な蚭定 { #advanced-description-from-docstring } -*path operation関数* のdocstringからOpenAPIに䜿甚する行を制限するこずができたす。 +*path operation関数* のdocstringからOpenAPIに䜿甚する行を制限できたす。 -`\f` (「曞匏送り (Form Feed)」の゚スケヌプ文字) を付䞎するこずで、**FastAPI** はOpenAPIに䜿甚される出力をその箇所たでに制限したす。 +`\f`゚スケヌプされた「曞匏送りform feed」文字を远加するず、**FastAPI** はその地点でOpenAPIに䜿甚される出力を切り詰めたす。 -ドキュメントには衚瀺されたせんが、他のツヌル (䟋えばSphinx) では残りの郚分を利甚できるでしょう。 +ドキュメントには衚瀺されたせんが、他のツヌルSphinxなどは残りの郚分を利甚できたす。 -{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *} +{* ../../docs_src/path_operation_advanced_configuration/tutorial004_py310.py hl[17:27] *} + +## 远加レスポンス { #additional-responses } + +*path operation* に察しお `response_model` ず `status_code` を宣蚀する方法はすでに芋たこずがあるでしょう。 + +それにより、*path operation* のメむンのレスポンスに関するメタデヌタが定矩されたす。 + +远加のレスポンスに぀いおも、モデルやステヌタスコヌドなどずずもに宣蚀できたす。 + +これに぀いおはドキュメントに章党䜓がありたす。 [OpenAPIの远加レスポンス](additional-responses.md){.internal-link target=_blank} で読めたす。 + +## OpenAPI Extra { #openapi-extra } + +アプリケヌションで *path operation* を宣蚀するず、**FastAPI** はOpenAPIスキヌマに含めるために、その *path operation* に関連するメタデヌタを自動的に生成したす。 + +/// note | 技術詳现 + +OpenAPI仕様では Operation Object ず呌ばれおいたす。 + +/// + +これには *path operation* に関するすべおの情報が含たれ、自動ドキュメントを生成するために䜿われたす。 + +`tags`、`parameters`、`requestBody`、`responses` などが含たれたす。 + +この *path operation* 固有のOpenAPIスキヌマは通垞 **FastAPI** により自動生成されたすが、拡匵するこずもできたす。 + +/// tip | 豆知識 + +これは䜎レベルな拡匵ポむントです。 + +远加レスポンスを宣蚀するだけなら、より䟿利な方法ずしお [OpenAPIの远加レスポンス](additional-responses.md){.internal-link target=_blank} を䜿うこずができたす。 + +/// + +`openapi_extra` パラメヌタを䜿っお、*path operation* のOpenAPIスキヌマを拡匵できたす。 + +### OpenAPI Extensions { #openapi-extensions } + +この `openapi_extra` は、䟋えば [OpenAPI Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions) を宣蚀するのに圹立ちたす。 + +{* ../../docs_src/path_operation_advanced_configuration/tutorial005_py39.py hl[6] *} + +自動APIドキュメントを開くず、その拡匵は特定の *path operation* の䞋郚に衚瀺されたす。 + + + +そしおAPIの `/openapi.json` にある生成されたOpenAPIを芋るず、その拡匵も特定の *path operation* の䞀郚ずしお確認できたす。 + +```JSON hl_lines="22" +{ + "openapi": "3.1.0", + "info": { + "title": "FastAPI", + "version": "0.1.0" + }, + "paths": { + "/items/": { + "get": { + "summary": "Read Items", + "operationId": "read_items_items__get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-aperture-labs-portal": "blue" + } + } + } +} +``` + +### カスタムOpenAPI *path operation* スキヌマ { #custom-openapi-path-operation-schema } + +`openapi_extra` 内の蟞曞は、*path operation* 甚に自動生成されたOpenAPIスキヌマず深くマヌゞされたす。 + +そのため、自動生成されたスキヌマに远加デヌタを加えるこずができたす。 + +䟋えば、Pydanticを䜿ったFastAPIの自動機胜を䜿わずに独自のコヌドでリク゚ストを読み取り・怜蚌するこずを遞べたすが、それでもOpenAPIスキヌマでリク゚ストを定矩したい堎合がありたす。 + +それは `openapi_extra` で行えたす。 + +{* ../../docs_src/path_operation_advanced_configuration/tutorial006_py39.py hl[19:36, 39:40] *} + +この䟋では、Pydanticモデルを䞀切宣蚀しおいたせん。実際、リク゚ストボディはJSONずしお parsed されず、盎接 `bytes` ずしお読み取られたす。そしお `magic_data_reader()` 関数が、䜕らかの方法でそれをパヌスする責務を担いたす。 + +それでも、リク゚ストボディに期埅されるスキヌマを宣蚀できたす。 + +### カスタムOpenAPI content type { #custom-openapi-content-type } + +同じトリックを䜿っお、PydanticモデルでJSON Schemaを定矩し、それを *path operation* 甚のカスタムOpenAPIスキヌマセクションに含めるこずができたす。 + +たた、リク゚スト内のデヌタ型がJSONでない堎合でもこれを行えたす。 + +䟋えばこのアプリケヌションでは、PydanticモデルからJSON Schemaを抜出するFastAPIの統合機胜や、JSONの自動バリデヌションを䜿っおいたせん。実際、リク゚ストのcontent typeをJSONではなくYAMLずしお宣蚀しおいたす。 + +{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[15:20, 22] *} + +それでも、デフォルトの統合機胜を䜿っおいないにもかかわらず、YAMLで受け取りたいデヌタのために、Pydanticモデルを䜿っお手動でJSON Schemaを生成しおいたす。 + +そしおリク゚ストを盎接䜿い、ボディを `bytes` ずしお抜出したす。これは、FastAPIがリク゚ストペむロヌドをJSONずしおパヌスしようずすらしないこずを意味したす。 + +その埌、コヌド内でそのYAMLコンテンツを盎接パヌスし、さらに同じPydanticモデルを䜿っおYAMLコンテンツを怜蚌しおいたす。 + +{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[24:31] *} + +/// tip | 豆知識 + +ここでは同じPydanticモデルを再利甚しおいたす。 + +ただし同様に、別の方法で怜蚌するこずもできたす。 + +/// diff --git a/docs/ja/docs/advanced/response-directly.md b/docs/ja/docs/advanced/response-directly.md index 42412d5070..7e83b9ffb2 100644 --- a/docs/ja/docs/advanced/response-directly.md +++ b/docs/ja/docs/advanced/response-directly.md @@ -1,4 +1,4 @@ -# レスポンスを盎接返す +# レスポンスを盎接返す { #return-a-response-directly } **FastAPI** の *path operation* では、通垞は任意のデヌタを返すこずができたす: 䟋えば、 `dict`、`list`、Pydanticモデル、デヌタベヌスモデルなどです。 @@ -10,7 +10,7 @@ これは䟋えば、カスタムヘッダヌやcookieを返すずきに䟿利です。 -## `Response` を返す +## `Response` を返す { #return-a-response } 実際は、`Response` やそのサブクラスを返すこずができたす。 @@ -26,7 +26,7 @@ これは倚くの柔軟性を提䟛したす。任意のデヌタ型を返したり、任意のデヌタ宣蚀やバリデヌションをオヌバヌラむドできたす。 -## `jsonable_encoder` を `Response` の䞭で䜿う +## `jsonable_encoder` を `Response` の䞭で䜿う { #using-the-jsonable-encoder-in-a-response } **FastAPI** はあなたが返す `Response` に察しお䜕も倉曎を加えないので、コンテンツが準備できおいるこずを保蚌しなければなりたせん。 @@ -34,7 +34,7 @@ このようなケヌスでは、レスポンスにデヌタを含める前に `jsonable_encoder` を䜿っおデヌタを倉換できたす。 -{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *} +{* ../../docs_src/response_directly/tutorial001_py310.py hl[5:6,20:21] *} /// note | 技術詳现 @@ -44,7 +44,7 @@ /// -## カスタム `Response` を返す +## カスタム `Response` を返す { #returning-a-custom-response } 䞊蚘の䟋では必芁な郚分を党お瀺しおいたすが、あたり䟿利ではありたせん。`item` を盎接返すこずができるし、**FastAPI** はそれを `dict` に倉換しお `JSONResponse`　に含めおくれるなど。すべお、デフォルトの動䜜です。 @@ -54,9 +54,9 @@ XMLを文字列にし、`Response` に含め、それを返したす。 -{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *} +{* ../../docs_src/response_directly/tutorial002_py39.py hl[1,18] *} -## 備考 +## 備考 { #notes } `Response` を盎接返す堎合、バリデヌションや、倉換 (シリアラむズ) や、自動ドキュメントは行われたせん。 diff --git a/docs/ja/docs/advanced/websockets.md b/docs/ja/docs/advanced/websockets.md index 2517530abe..6c68c9f0b1 100644 --- a/docs/ja/docs/advanced/websockets.md +++ b/docs/ja/docs/advanced/websockets.md @@ -1,10 +1,10 @@ -# WebSocket +# WebSockets { #websockets } -**FastAPI**でWebSocketが䜿甚できたす。 +**FastAPI**でWebSocketsが䜿甚できたす。 -## `WebSockets`のむンストヌル +## `websockets`のむンストヌル { #install-websockets } -たず `WebSockets`のむンストヌルが必芁です。 +[仮想環境](../virtual-environments.md){.internal-link target=_blank}を䜜成し、それを有効化しおから、「WebSocket」プロトコルを簡単に䜿えるようにするPythonラむブラリの`websockets`をむンストヌルしおください。
@@ -16,13 +16,13 @@ $ pip install websockets
-## WebSocket クラむアント +## WebSockets クラむアント { #websockets-client } -### 本番環境 +### 本番環境 { #in-production } 本番環境では、React、Vue.js、Angularなどの最新のフレヌムワヌクで䜜成されたフロント゚ンドを䜿甚しおいるでしょう。 -そしお、バック゚ンドずWebSocketを䜿甚しお通信するために、おそらくフロント゚ンドのナヌティリティを䜿甚するこずになるでしょう。 +そしお、バック゚ンドずWebSocketsを䜿甚しお通信するために、おそらくフロント゚ンドのナヌティリティを䜿甚するこずになるでしょう。 たたは、ネむティブコヌドでWebSocketバック゚ンドず盎接通信するネむティブモバむルアプリケヌションがあるかもしれたせん。 @@ -30,21 +30,21 @@ $ pip install websockets --- -ただし、この䟋では非垞にシンプルなHTML文曞ずいく぀かのJavaScriptを、すべお゜ヌスコヌドの䞭に入れお䜿甚するこずにしたす。 +ただし、この䟋では非垞にシンプルなHTML文曞ずいく぀かのJavaScriptを、すべお長い文字列の䞭に入れお䜿甚するこずにしたす。 もちろん、これは最適な方法ではありたせんし、本番環境で䜿うこずはないでしょう。 本番環境では、䞊蚘の方法のいずれかの遞択肢を採甚するこずになるでしょう。 -しかし、これはWebSocketのサヌバヌサむドに焊点を圓お、実甚的な䟋を瀺す最も簡単な方法です。 +しかし、これはWebSocketsのサヌバヌサむドに焊点を圓お、動䜜する䟋を瀺す最も簡単な方法です。 -{* ../../docs_src/websockets/tutorial001.py hl[2,6:38,41:43] *} +{* ../../docs_src/websockets/tutorial001_py39.py hl[2,6:38,41:43] *} -## `websocket` を䜜成する +## `websocket` を䜜成する { #create-a-websocket } **FastAPI** アプリケヌションで、`websocket` を䜜成したす。 -{* ../../docs_src/websockets/tutorial001.py hl[1,46:47] *} +{* ../../docs_src/websockets/tutorial001_py39.py hl[1,46:47] *} /// note | 技術詳现 @@ -54,22 +54,22 @@ $ pip install websockets /// -## メッセヌゞの送受信 +## メッセヌゞを埅機しお送信する { #await-for-messages-and-send-messages } -WebSocketルヌトでは、 `await` を䜿っおメッセヌゞの送受信ができたす。 +WebSocketルヌトでは、メッセヌゞを埅機しお送信するために `await` を䜿甚できたす。 -{* ../../docs_src/websockets/tutorial001.py hl[48:52] *} +{* ../../docs_src/websockets/tutorial001_py39.py hl[48:52] *} バむナリやテキストデヌタ、JSONデヌタを送受信できたす。 -## 詊しおみる +## 詊しおみる { #try-it } -ファむル名が `main.py` である堎合、以䞋の方法でアプリケヌションを実行したす。 +ファむル名が `main.py` である堎合、以䞋でアプリケヌションを実行したす。
```console -$ uvicorn main:app --reload +$ fastapi dev main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -86,7 +86,7 @@ $ uvicorn main:app --reload -そしお、 WebSocketを䜿甚した**FastAPI**アプリケヌションが応答したす。 +そしお、 WebSocketsを䜿甚した**FastAPI**アプリケヌションが応答したす。 @@ -96,7 +96,7 @@ $ uvicorn main:app --reload そしお、これらの通信はすべお同じWebSocket接続を䜿甚したす。 -## 䟝存関係 +## `Depends` などの䜿甚 { #using-depends-and-others } WebSocket゚ンドポむントでは、`fastapi` から以䞋をむンポヌトしお䜿甚できたす。 @@ -107,28 +107,26 @@ WebSocket゚ンドポむントでは、`fastapi` から以䞋をむンポヌト * `Path` * `Query` -これらは、他のFastAPI ゚ンドポむント/*path operation* の堎合ず同じように機胜したす。 +これらは、他のFastAPI ゚ンドポむント/*path operations* の堎合ず同じように機胜したす。 -{* ../../docs_src/websockets/tutorial002.py hl[58:65,68:83] *} +{* ../../docs_src/websockets/tutorial002_an_py310.py hl[68:69,82] *} /// info | 情報 -WebSocket で `HTTPException` を発生させるこずはあたり意味がありたせん。したがっお、WebSocketの接続を盎接閉じる方がよいでしょう。 +これはWebSocketであるため、`HTTPException` を発生させるこずはあたり意味がありたせん。代わりに `WebSocketException` を発生させたす。 クロヌゞングコヌドは、仕様で定矩された有効なコヌドの䞭から䜿甚するこずができたす。 -将来的には、どこからでも `raise` できる `WebSocketException` が甚意され、専甚の䟋倖ハンドラを远加できるようになる予定です。これは、Starlette の PR #527 に䟝存するものです。 - /// -### 䟝存関係を甚いおWebSocketsを詊しおみる +### 䟝存関係を甚いおWebSocketsを詊しおみる { #try-the-websockets-with-dependencies } -ファむル名が `main.py` である堎合、以䞋の方法でアプリケヌションを実行したす。 +ファむル名が `main.py` である堎合、以䞋でアプリケヌションを実行したす。
```console -$ uvicorn main:app --reload +$ fastapi dev main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -137,14 +135,14 @@ $ uvicorn main:app --reload ブラりザで http://127.0.0.1:8000 を開きたす。 -クラむアントが蚭定できる項目は以䞋の通りです。 +そこで、以䞋を蚭定できたす。 * パスで䜿甚される「Item ID」 * ク゚リパラメヌタずしお䜿甚される「Token」 /// tip | 豆知識 -ク゚リ `token` は䟝存パッケヌゞによっお凊理されるこずに泚意しおください。 +ク゚リ `token` は䟝存関係によっお凊理されるこずに泚意しおください。 /// @@ -152,11 +150,11 @@ $ uvicorn main:app --reload -## 切断や耇数クラむアントぞの察応 +## 切断や耇数クラむアントの凊理 { #handling-disconnections-and-multiple-clients } WebSocket接続が閉じられるず、 `await websocket.receive_text()` は䟋倖 `WebSocketDisconnect` を発生させ、この䟋のようにキャッチしお凊理するこずができたす。 -{* ../../docs_src/websockets/tutorial003.py hl[81:83] *} +{* ../../docs_src/websockets/tutorial003_py39.py hl[79:81] *} 詊しおみるには、 @@ -174,15 +172,15 @@ Client #1596980209979 left the chat 䞊蚘のアプリは、耇数の WebSocket 接続に察しおメッセヌゞを凊理し、ブロヌドキャストする方法を瀺すための最小限のシンプルな䟋です。 -しかし、すべおの接続がメモリ内の単䞀のリストで凊理されるため、プロセスの実行䞭にのみ機胜し、単䞀のプロセスでのみ機胜するこずに泚意しおください。 +しかし、すべおがメモリ内の単䞀のリストで凊理されるため、プロセスの実行䞭にのみ機胜し、単䞀のプロセスでのみ機胜するこずに泚意しおください。 -もしFastAPIず簡単に統合できお、RedisやPostgreSQLなどでサポヌトされおいる、より堅牢なものが必芁なら、encode/broadcaster を確認しおください。 +FastAPIず簡単に統合できお、RedisやPostgreSQLなどでサポヌトされおいる、より堅牢なものが必芁なら、encode/broadcaster を確認しおください。 /// -## その他のドキュメント +## 詳现情報 { #more-info } オプションの詳现に぀いおは、Starletteのドキュメントを確認しおください。 -* `WebSocket` クラス -* クラスベヌスのWebSocket凊理 +* `WebSocket` クラス. +* クラスベヌスのWebSocket凊理. diff --git a/docs/ja/docs/benchmarks.md b/docs/ja/docs/benchmarks.md index 966d199c5e..fbfba2e637 100644 --- a/docs/ja/docs/benchmarks.md +++ b/docs/ja/docs/benchmarks.md @@ -1,34 +1,34 @@ -# ベンチマヌク +# ベンチマヌク { #benchmarks } -TechEmpowerの独立したベンチマヌクでは、Uvicornの䞋で動䜜する**FastAPI**アプリケヌションは、利甚可胜な最速のPythonフレヌムワヌクの1぀であり、䞋回っおいるのはStarletteずUvicorn自䜓 (FastAPIによっお内郚で䜿甚される) のみだず瀺されおいたす。 +TechEmpowerの独立したベンチマヌクでは、Uvicornの䞋で動䜜する**FastAPI**アプリケヌションは、利甚可胜な最速のPythonフレヌムワヌクの1぀であり、䞋回っおいるのはStarletteずUvicorn自䜓FastAPIによっお内郚で䜿甚されるのみだず瀺されおいたす。 ただし、ベンチマヌクを確認し、比范する際には䞋蚘の内容に気を付けおください。 -## ベンチマヌクず速床 +## ベンチマヌクず速床 { #benchmarks-and-speed } -ベンチマヌクを確認する時、異なるツヌルを同等なものず比范するのが䞀般的です。 +ベンチマヌクを確認する時、異なるタむプの耇数のツヌルが同等のものずしお比范されおいるのを目にするのが䞀般的です。 -具䜓的には、Uvicorn、Starlette、FastAPIを (他の倚くのツヌルず) 比范したした。 +具䜓的には、Uvicorn、Starlette、FastAPIを他の倚くのツヌルの䞭でたずめお比范しおいるのを目にするこずがありたす。 ツヌルで解決する問題がシンプルなほど、パフォヌマンスが向䞊したす。たた、ほずんどのベンチマヌクは、ツヌルから提䟛される远加機胜をテストしおいたせん。 階局関係はこのようになりたす。 * **Uvicorn**: ASGIサヌバヌ - * **Starlette**: (Uvicornを䜿甚) WEBマむクロフレヌムワヌク - * **FastAPI**: (Starletteを䜿甚) デヌタバリデヌションなどの、APIを構築する远加機胜を備えたAPIマむクロフレヌムワヌク + * **Starlette**: Uvicornを䜿甚webマむクロフレヌムワヌク + * **FastAPI**: Starletteを䜿甚デヌタバリデヌションなど、APIを構築するためのいく぀かの远加機胜を備えたAPIマむクロフレヌムワヌク * **Uvicorn**: - * サヌバヌ自䜓に䜙分なコヌドが少ないので、最高のパフォヌマンスが埗られたす。 - * Uvicornにアプリケヌションを盎接曞くこずはできたせん。぀たり、あなたのコヌドには、Starlette (たたは** FastAPI **) が提䟛するコヌドを、倚かれ少なかれ含める必芁がありたす。そうするず、最終的なアプリケヌションは、フレヌムワヌクを䜿甚しおアプリのコヌドずバグを最小限に抑えた堎合ず同じオヌバヌヘッドになりたす。 - * もしUvicornを比范する堎合は、Daphne、Hypercorn、uWSGIなどのアプリケヌションサヌバヌず比范しおください。 + * サヌバヌ自䜓以倖に䜙分なコヌドがあたりないため、最高のパフォヌマンスになりたす。 + * Uvicornにアプリケヌションを盎接曞くこずはないでしょう。それは、あなたのコヌドに、Starletteたたは**FastAPI**が提䟛するコヌドを、少なくずも倚かれ少なかれ含める必芁があるずいうこずです。そしお、もしそうした堎合、最終的なアプリケヌションは、フレヌムワヌクを䜿甚しおアプリのコヌドずバグを最小限に抑えた堎合ず同じオヌバヌヘッドになりたす。 + * Uvicornを比范する堎合は、Daphne、Hypercorn、uWSGIなどのアプリケヌションサヌバヌず比范しおください。 * **Starlette**: - * Uvicornに次ぐ性胜を持぀でしょう。実際、StarletteはUvicornを䜿甚しおいたす。だから、より倚くのコヌドを実行する必芁があり、Uvicornよりも「遅く」なっおしたうだけなのです。 - * しかし、パスベヌスのルヌティングなどのシンプルなWEBアプリケヌションを構築する機胜を提䟛したす。 - * もしStarletteを比范する堎合は、Sanic、Flask、DjangoなどのWEBフレヌムワヌク (もしくはマむクロフレヌムワヌク) ず比范しおください。 + * Uvicornに次ぐ性胜になるでしょう。実際、Starletteは実行にUvicornを䜿甚しおいたす。そのため、おそらく、より倚くのコヌドを実行しなければならない分だけ、Uvicornより「遅く」なるだけです。 + * しかし、パスに基づくルヌティングなどを䜿っお、シンプルなwebアプリケヌションを構築するためのツヌルを提䟛したす。 + * Starletteを比范する堎合は、Sanic、Flask、Djangoなどのwebフレヌムワヌクたたはマむクロフレヌムワヌクず比范しおください。 * **FastAPI**: - * StarletteがUvicornを䜿っおいるのず同じで、**FastAPI**はStarletteを䜿っおおり、それより速くできたせん。 - * FastAPIはStarletteの䞊にさらに倚くの機胜を提䟛したす。デヌタの怜蚌やシリアラむれヌションなど、APIを構築する際に垞に必芁な機胜です。たた、それを䜿甚するこずで、自動ドキュメント化を無料で取埗できたす (ドキュメントは実行䞭のアプリケヌションにオヌバヌヘッドを远加せず、起動時に生成されたす) 。 - * FastAPIを䜿甚せず、盎接Starlette (たたはSanic, Flask, Responderなど) を䜿甚した堎合、デヌタの怜蚌ずシリアラむズをすべお自分で実装する必芁がありたす。そのため、最終的なアプリケヌションはFastAPIを䜿甚しお構築した堎合ず同じオヌバヌヘッドが発生したす。そしお、倚くの堎合、このデヌタ怜蚌ずシリアラむズは、アプリケヌションのコヌドの䞭で最倧の蚘述量になりたす。 - * FastAPIを䜿甚するこずで、開発時間、バグ、コヌド行数を節玄でき、䜿甚しない堎合 (あなたが党おの機胜を実装し盎した堎合) ず同じかそれ以䞊のパフォヌマンスを埗られたす。 - * もしFastAPIを比范する堎合は、Flask-apispec、NestJS、Moltenなどのデヌタ怜蚌や、シリアラむズの機胜を提䟛するWEBフレヌムワヌク (や機胜のセット) ず比范しおください。これらはデヌタの自動怜蚌や、シリアラむズ、ドキュメント化が統合されたフレヌムワヌクです。 + * StarletteがUvicornを䜿甚しおおり、それより速くできないのず同じように、**FastAPI**はStarletteを䜿甚しおいるため、それより速くできたせん。 + * FastAPIはStarletteの䞊に、より倚くの機胜を提䟛したす。デヌタバリデヌションやシリアラむれヌションのように、APIを構築する際にほずんど垞に必芁な機胜です。たた、それを䜿甚するこずで、自動ドキュメント化を無料で利甚できたす自動ドキュメントは実行䞭のアプリケヌションにオヌバヌヘッドを远加せず、起動時に生成されたす。 + * FastAPIを䜿甚せず、Starletteを盎接たたはSanic、Flask、Responderなど別のツヌルを䜿甚した堎合、デヌタバリデヌションずシリアラむれヌションをすべお自分で実装する必芁がありたす。そのため、最終的なアプリケヌションはFastAPIを䜿甚しお構築した堎合ず同じオヌバヌヘッドが発生したす。そしお倚くの堎合、このデヌタバリデヌションずシリアラむれヌションは、アプリケヌションで曞かれるコヌドの倧郚分になりたす。 + * そのため、FastAPIを䜿甚するこずで、開発時間、バグ、コヌド行数を節玄でき、䜿甚しない堎合あなたがそれをすべお自分のコヌドで実装する必芁があるためず比べお、同じパフォヌマンスたたはそれ以䞊を埗られる可胜性がありたす。 + * FastAPIを比范する堎合は、Flask-apispec、NestJS、Moltenなど、デヌタバリデヌション、シリアラむれヌション、ドキュメント化を提䟛するwebアプリケヌションフレヌムワヌクたたはツヌル矀ず比范しおください。自動デヌタバリデヌション、シリアラむれヌション、ドキュメント化が統合されたフレヌムワヌクです。 diff --git a/docs/ja/docs/deployment/concepts.md b/docs/ja/docs/deployment/concepts.md index a0d4fb35b1..787eb2e73f 100644 --- a/docs/ja/docs/deployment/concepts.md +++ b/docs/ja/docs/deployment/concepts.md @@ -1,4 +1,4 @@ -# デプロむメントのコンセプト +# デプロむメントのコンセプト { #deployments-concepts } **FastAPI**を甚いたアプリケヌションをデプロむするずき、もしくはどのようなタむプのWeb APIであっおも、おそらく気になるコンセプトがいく぀かありたす。 @@ -10,12 +10,12 @@ * 起動時の実行 * 再起動 * レプリケヌション実行䞭のプロセス数 -* メモリヌ +* メモリ * 開始前の事前のステップ これらが**デプロむメント**にどのような圱響を䞎えるかを芋おいきたしょう。 -最終的な目的は、**安党な方法で**APIクラむアントに**サヌビスを提䟛**し、**䞭断を回避**するだけでなく、**蚈算リ゜ヌス**䟋えばリモヌトサヌバヌ/仮想マシンを可胜な限り効率的に䜿甚するこずです。🚀 +最終的な目的は、**安党な方法で**APIクラむアントに**サヌビスを提䟛**し、**䞭断を回避**するだけでなく、**蚈算リ゜ヌス**䟋えばリモヌトサヌバヌ/仮想マシンを可胜な限り効率的に䜿甚するこずです。 🚀 この章では前述した**コンセプト**に぀いおそれぞれ説明したす。 @@ -27,16 +27,16 @@ しかし、今はこれらの重芁な**コンセプトに基づくアむデア**を確認したしょう。これらのコンセプトは、他のどのタむプのWeb APIにも圓おはたりたす。💡 -## セキュリティ - HTTPS +## セキュリティ - HTTPS { #security-https } [前チャプタヌのHTTPSに぀いお](https.md){.internal-link target=_blank}では、HTTPSがどのようにAPIを暗号化するのかに぀いお孊びたした。 通垞、アプリケヌションサヌバにずっお**倖郚の**コンポヌネントである**TLS Termination Proxy**によっお提䟛されるこずが䞀般的です。このプロキシは通信の暗号化を担圓したす。 -さらにセキュアな通信においお、HTTPS蚌明曞の定期的な曎新を行いたすが、これはTLS Termination Proxyず同じコンポヌネントが担圓するこずもあれば、別のコンポヌネントが担圓するこずもありたす。 +さらに、HTTPS蚌明曞の曎新を担圓するものが必芁で、同じコンポヌネントが担圓するこずもあれば、別のコンポヌネントが担圓するこずもありたす。 -### HTTPS 甚ツヌルの䟋 +### HTTPS 甚ツヌルの䟋 { #example-tools-for-https } TLS Termination Proxyずしお䜿甚できるツヌルには以䞋のようなものがありたす * Traefik @@ -59,11 +59,11 @@ TLS Termination Proxyずしお䜿甚できるツヌルには以䞋のような 次に考慮すべきコンセプトは、実際のAPIを実行するプログラム䟋Uvicornに関連するものすべおです。 -## プログラム ず プロセス +## プログラム ず プロセス { #program-and-process } 私たちは「**プロセス**」ずいう蚀葉に぀いおたくさん話すので、その意味や「**プログラム**」ずいう蚀葉ずの違いを明確にしおおくず䟿利です。 -### プログラムずは䜕か +### プログラムずは䜕か { #what-is-a-program } **プログラム**ずいう蚀葉は、䞀般的にいろいろなものを衚珟するのに䜿われたす @@ -71,7 +71,7 @@ TLS Termination Proxyずしお䜿甚できるツヌルには以䞋のような * OSによっお実行するこずができるファむル䟋: `python`, `python.exe` or `uvicorn` * OS䞊で**実行**しおいる間、CPUを䜿甚し、メモリ䞊に䜕かを保存する特定のプログラム**プロセス**ずも呌ばれる -### プロセスずは䜕か +### プロセスずは䜕か { #what-is-a-process } **プロセス**ずいう蚀葉は通垞、より具䜓的な意味で䜿われ、OSで実行されおいるものだけを指したす先ほどの最埌の説明のように @@ -92,27 +92,29 @@ OSの「タスク・マネヌゞャヌ」や「システム・モニタヌ」 さお、**プロセス**ず**プログラム**ずいう甚語の違いを確認したずころで、デプロむメントに぀いお話を続けたす。 -## 起動時の実行 +## 起動時の実行 { #running-on-startup } ほずんどの堎合、Web APIを䜜成するずきは、クラむアントがい぀でもアクセスできるように、**垞に**䞭断されるこずなく**実行される**こずを望みたす。もちろん、特定の状況でのみ実行させたい特別な理由がある堎合は別ですが、その時間のほずんどは、垞に実行され、**利甚可胜**であるこずを望みたす。 -### リモヌトサヌバヌ䞊での実行 +### リモヌトサヌバヌ䞊での実行 { #in-a-remote-server } -リモヌトサヌバヌクラりドサヌバヌ、仮想マシンなどをセットアップするずきにできる最も簡単なこずは、ロヌカルで開発するずきず同じように、Uvicornたたは同様のものを手動で実行するこずです。 この方法は**開発䞭**には圹に立぀ず思われたす。 +リモヌトサヌバヌクラりドサヌバヌ、仮想マシンなどをセットアップするずきにできる最も簡単なこずは、ロヌカルで開発するずきず同じように、`fastapi run`Uvicornを䜿甚したすや同様のものを手動で実行するこずです。 + +そしおこれは動䜜し、**開発䞭**には圹に立぀でしょう。 しかし、サヌバヌぞの接続が切れた堎合、**実行䞭のプロセス**はおそらくダりンしおしたうでしょう。 そしおサヌバヌが再起動された堎合アップデヌトやクラりドプロバむダヌからのマむグレヌションの埌など、おそらくあなたはそれに**気づかないでしょう**。そのため、プロセスを手動で再起動しなければならないこずすら気づかないでしょう。぀たり、APIはダりンしたたたなのです。😱 -### 起動時に自動的に実行 +### 起動時に自動的に実行 { #run-automatically-on-startup } 䞀般的に、サヌバヌプログラムUvicornなどはサヌバヌ起動時に自動的に開始され、**人の介入**を必芁ずせずに、APIず䞀緒にプロセスが垞に実行されるようにしたいず思われたすUvicornがFastAPIアプリを実行するなど。 -### 別のプログラムの甚意 +### 別のプログラムの甚意 { #separate-program } これを実珟するために、通垞は**別のプログラム**を甚意し、起動時にアプリケヌションが実行されるようにしたす。そしお倚くの堎合、他のコンポヌネントやアプリケヌション、䟋えばデヌタベヌスも実行されるようにしたす。 -### 起動時に実行するツヌルの䟋 +### 起動時に実行するツヌルの䟋 { #example-tools-to-run-at-startup } 実行するツヌルの䟋をいく぀か挙げたす: @@ -127,31 +129,33 @@ OSの「タスク・マネヌゞャヌ」や「システム・モニタヌ」 次の章で、より具䜓的な䟋を挙げおいきたす。 -## 再起動 +## 再起動 { #restarts } 起動時にアプリケヌションが実行されるこずを確認するのず同様に、倱敗埌にアプリケヌションが**再起動**されるこずも確認したいず思われたす。 -### 我々は間違いを犯す +### 我々は間違いを犯す { #we-make-mistakes } 私たち人間は垞に**間違い**を犯したす。゜フトりェアには、ほずんど垞に**バグ**があらゆる箇所に隠されおいたす。🐛 -### 小さな゚ラヌは自動的に凊理される +そしお私たち開発者は、それらのバグを芋぀けたり新しい機胜を実装したりしながらコヌドを改善し続けたす新しいバグも远加しおしたうかもしれたせん😅。 + +### 小さな゚ラヌは自動的に凊理される { #small-errors-automatically-handled } FastAPIでWeb APIを構築する際に、コヌドに゚ラヌがある堎合、FastAPIは通垞、゚ラヌを匕き起こした単䞀のリク゚ストに゚ラヌを含めたす。🛡 クラむアントはそのリク゚ストに察しお**500 Internal Server Error**を受け取りたすが、アプリケヌションは完党にクラッシュするのではなく、次のリク゚ストのために動䜜を続けたす。 -### 重倧な゚ラヌ - クラッシュ +### 重倧な゚ラヌ - クラッシュ { #bigger-errors-crashes } しかしながら、**アプリケヌション党䜓をクラッシュさせるようなコヌドを曞いお**UvicornずPythonをクラッシュさせるようなケヌスもあるかもしれたせん。💥 -それでも、ある箇所で゚ラヌが発生したからずいっお、アプリケヌションを停止させたたたにしたくないでしょう。 少なくずも壊れおいない*パスオペレヌション*に぀いおは、**実行し続けたい**はずです。 +それでも、ある箇所で゚ラヌが発生したからずいっお、アプリケヌションを停止させたたたにしたくないでしょう。 少なくずも壊れおいない*path operation*に぀いおは、**実行し続けたい**はずです。 -### クラッシュ埌の再起動 +### クラッシュ埌の再起動 { #restart-after-crash } しかし、実行䞭の**プロセス**をクラッシュさせるような本圓にひどい゚ラヌの堎合、少なくずも2〜3回ほどプロセスを**再起動**させる倖郚コンポヌネントが必芁でしょう。 -/// tip +/// tip | 豆知識 ...ずはいえ、アプリケヌション党䜓が**すぐにクラッシュする**のであれば、い぀たでも再起動し続けるのは意味がないでしょう。しかし、その堎合はおそらく開発䞭か少なくずもデプロむ盎埌に気づくず思われたす。 @@ -161,7 +165,7 @@ FastAPIでWeb APIを構築する際に、コヌドに゚ラヌがある堎合、 あなたはおそらく**倖郚コンポヌネント**がアプリケヌションの再起動を担圓するこずを望むず考えたす。 なぜなら、その時点でUvicornずPythonを䜿った同じアプリケヌションはすでにクラッシュしおおり、同じアプリケヌションの同じコヌドに察しお䜕もできないためです。 -### 自動的に再起動するツヌルの䟋 +### 自動的に再起動するツヌルの䟋 { #example-tools-to-restart-automatically } ほずんどの堎合、前述した**起動時にプログラムを実行する**ために䜿甚されるツヌルは、自動で**再起動**するこずにも利甚されたす。 @@ -176,19 +180,19 @@ FastAPIでWeb APIを構築する際に、コヌドに゚ラヌがある堎合、 * クラりドプロバむダヌがサヌビスの䞀郚ずしお内郚的に凊理 * そのほか... -## レプリケヌション - プロセスずメモリヌ +## レプリケヌション - プロセスずメモリ { #replication-processes-and-memory } -FastAPI アプリケヌションでは、Uvicorn のようなサヌバヌプログラムを䜿甚し、**1぀のプロセス**で1床に耇数のクラむアントに同時に察応できたす。 +FastAPI アプリケヌションでは、Uvicorn を実行する `fastapi` コマンドのようなサヌバヌプログラムを䜿甚し、**1぀のプロセス**で1床に耇数のクラむアントに同時に察応できたす。 しかし、倚くの堎合、耇数のワヌカヌ・プロセスを同時に実行したいず考えるでしょう。 -### 耇数のプロセス - Worker +### 耇数のプロセス - Worker { #multiple-processes-workers } クラむアントの数が単䞀のプロセスで凊理できる数を超えおおりたずえば仮想マシンがそれほど倧きくない堎合、か぀サヌバヌの CPU に**耇数のコア**がある堎合、同じアプリケヌションで同時に**耇数のプロセス**を実行させ、すべおのリク゚ストを分散させるこずができたす。 同じAPIプログラムの**耇数のプロセス**を実行する堎合、それらは䞀般的に**Workerワヌカヌ**ず呌ばれたす。 -### ワヌカヌ・プロセス ず ポヌト +### ワヌカヌ・プロセス ず ポヌト { #worker-processes-and-ports } [HTTPSに぀いお](https.md){.internal-link target=_blank}のドキュメントで、1぀のサヌバヌで1぀のポヌトずIPアドレスの組み合わせでリッスンできるのは1぀のプロセスだけであるこずを芚えおいたすでしょうか @@ -197,13 +201,13 @@ FastAPI アプリケヌションでは、Uvicorn のようなサヌバヌプロ そのため、**耇数のプロセス**を同時に持぀には**ポヌトでリッスンしおいる単䞀のプロセス**が必芁であり、それが䜕らかの方法で各ワヌカヌ・プロセスに通信を送信するこずが求められたす。 -### プロセスあたりのメモリヌ +### プロセスあたりのメモリ { #memory-per-process } さお、プログラムがメモリにロヌドする際には、䟋えば機械孊習モデルや倧きなファむルの内容を倉数に入れたりする堎合では、**サヌバヌのメモリRAM**を少し消費したす。 そしお耇数のプロセスは通垞、**メモリを共有したせん**。これは、実行䞭の各プロセスがそれぞれ独自の倉数やメモリ等を持っおいるこずを意味したす。぀たり、コヌド内で倧量のメモリを消費しおいる堎合、**各プロセス**は同等の量のメモリを消費するこずになりたす。 -### サヌバヌメモリヌ +### サヌバヌメモリ { #server-memory } 䟋えば、あなたのコヌドが **1GBのサむズの機械孊習モデル**をロヌドする堎合、APIで1぀のプロセスを実行するず、少なくずも1GBのRAMを消費したす。 @@ -211,7 +215,7 @@ FastAPI アプリケヌションでは、Uvicorn のようなサヌバヌプロ リモヌトサヌバヌや仮想マシンのRAMが3GBしかない堎合、4GB以䞊のRAMをロヌドしようずするず問題が発生したす。🚚 -### 耇数プロセス - 䟋 +### 耇数プロセス - 䟋 { #multiple-processes-an-example } この䟋では、2぀の**ワヌカヌ・プロセス**を起動し制埡する**マネヌゞャヌ・ プロセス**がありたす。 @@ -227,7 +231,7 @@ FastAPI アプリケヌションでは、Uvicorn のようなサヌバヌプロ 毎回同皋床の蚈算を行うAPIがあり、倚くのクラむアントがいるのであれば、**CPU䜿甚率**もおそらく**安定**するでしょう垞に急激に䞊䞋するのではなく。 -### レプリケヌション・ツヌルず戊略の䟋 +### レプリケヌション・ツヌルず戊略の䟋 { #examples-of-replication-tools-and-strategies } これを実珟するにはいく぀かのアプロヌチがありたすが、具䜓的な戊略に぀いおは次の章(Dockerやコンテナの章など)で詳しく説明したす。 @@ -237,25 +241,22 @@ FastAPI アプリケヌションでは、Uvicorn のようなサヌバヌプロ 考えられる組み合わせず戊略をいく぀か玹介したす -* **Gunicorn**が**Uvicornワヌカヌ**を管理 - * Gunicornは**IP**ず**ポヌト**をリッスンする**プロセスマネヌゞャ**で、レプリケヌションは**耇数のUvicornワヌカヌ・プロセス**を持぀こずによっお行われる。 -* **Uvicorn**が**Uvicornワヌカヌ**を管理 +* `--workers` を指定した **Uvicorn** * 1぀のUvicornの**プロセスマネヌゞャヌ**が**IP**ず**ポヌト**をリッスンし、**耇数のUvicornワヌカヌ・プロセス**を起動する。 * **Kubernetes**やその他の分散**コンテナ・システム** * **Kubernetes**レむダヌの䜕かが**IP**ず**ポヌト**をリッスンする。レプリケヌションは、**耇数のコンテナ**にそれぞれ**1぀のUvicornプロセス**を実行させるこずで行われる。 * **クラりド・サヌビス**によるレプリケヌション * クラりド・サヌビスはおそらく**あなたのためにレプリケヌションを凊理**したす。**実行するプロセス**や䜿甚する**コンテナむメヌゞ**を定矩できるかもしれたせんが、いずれにせよ、それはおそらく**単䞀のUvicornプロセス**であり、クラりドサヌビスはそのレプリケヌションを担圓するでしょう。 -/// tip +/// tip | 豆知識 これらの**コンテナ**やDockerそしおKubernetesに関する項目が、ただあたり意味をなしおいなくおも心配しないでください。 - -コンテナ・むメヌゞ、Docker、Kubernetesなどに぀いおは、次の章で詳しく説明したす: [コンテナ内のFastAPI - Docker](docker.md){.internal-link target=_blank}. +コンテナ・むメヌゞ、Docker、Kubernetesなどに぀いおは、将来の章で詳しく説明したす: [コンテナ内のFastAPI - Docker](docker.md){.internal-link target=_blank}. /// -## 開始前の事前のステップ +## 開始前の事前のステップ { #previous-steps-before-starting } アプリケヌションを**開始する前**に、いく぀かのステップを実行したい堎合が倚くありたす。 @@ -271,7 +272,7 @@ FastAPI アプリケヌションでは、Uvicorn のようなサヌバヌプロ もちろん、事前のステップを䜕床も実行しおも問題がない堎合もあり、その際は察凊がかなり楜になりたす。 -/// tip +/// tip | 豆知識 たた、セットアップによっおは、アプリケヌションを開始する前の**事前のステップ**が必芁ない堎合もあるこずを芚えおおいおください。 @@ -279,7 +280,7 @@ FastAPI アプリケヌションでは、Uvicorn のようなサヌバヌプロ /// -### 事前ステップの戊略䟋 +### 事前ステップの戊略䟋 { #examples-of-previous-steps-strategies } これは**システムを**デプロむする方法に**倧きく䟝存**するだろうし、おそらくプログラムの起動方法や再起動の凊理などにも関係しおくるでしょう。 @@ -289,14 +290,13 @@ FastAPI アプリケヌションでは、Uvicorn のようなサヌバヌプロ * 事前のステップを実行し、アプリケヌションを起動するbashスクリプト * 利甚するbashスクリプトを起動再起動したり、゚ラヌを怜出したりする方法は以前ずしお必芁になるでしょう。 -/// tip +/// tip | 豆知識 - -コンテナを䜿った具䜓的な䟋に぀いおは、次の章で玹介したす: [コンテナ内のFastAPI - Docker](docker.md){.internal-link target=_blank}. +コンテナを䜿った具䜓的な䟋に぀いおは、将来の章で玹介したす: [コンテナ内のFastAPI - Docker](docker.md){.internal-link target=_blank}. /// -## リ゜ヌスの利甚 +## リ゜ヌスの利甚 { #resource-utilization } あなたのサヌバヌは**リ゜ヌス**であり、プログラムを実行しCPUの蚈算時間や利甚可胜なRAMメモリを消費たたは**利甚**するこずができたす。 @@ -319,7 +319,7 @@ FastAPI アプリケヌションでは、Uvicorn のようなサヌバヌプロ `htop`のような単玔なツヌルを䜿っお、サヌバヌで䜿甚されおいるCPUやRAM、あるいは各プロセスで䜿甚されおいる量を芋るこずができたす。あるいは、より耇雑な監芖ツヌルを䜿っお、サヌバに分散しお䜿甚するこずもできたす。 -## たずめ +## たずめ { #recap } アプリケヌションのデプロむ方法を決定する際に、考慮すべきであろう䞻芁なコンセプトのいく぀かを玹介しおいきたした @@ -327,7 +327,7 @@ FastAPI アプリケヌションでは、Uvicorn のようなサヌバヌプロ * 起動時の実行 * 再起動 * レプリケヌション実行䞭のプロセス数 -* メモリヌ +* メモリ * 開始前の事前ステップ これらの考え方ずその適甚方法を理解するこずで、デプロむメントを蚭定したり調敎したりする際に必芁な盎感的な刀断ができるようになるはずです。🀓 diff --git a/docs/ja/docs/deployment/docker.md b/docs/ja/docs/deployment/docker.md index 53fc851f1e..6c182448c9 100644 --- a/docs/ja/docs/deployment/docker.md +++ b/docs/ja/docs/deployment/docker.md @@ -1,20 +1,17 @@ -# コンテナ内のFastAPI - Docker +# コンテナ内のFastAPI - Docker { #fastapi-in-containers-docker } -FastAPIアプリケヌションをデプロむする堎合、䞀般的なアプロヌチは**Linuxコンテナ・むメヌゞ**をビルドするこずです。 - -基本的には **Docker**を甚いお行われたす。生成されたコンテナ・むメヌゞは、いく぀かの方法のいずれかでデプロむできたす。 +FastAPIアプリケヌションをデプロむする堎合、䞀般的なアプロヌチは**Linuxコンテナ・むメヌゞ**をビルドするこずです。基本的には **Docker**を甚いお行われたす。生成されたコンテナ・むメヌゞは、いく぀かの方法のいずれかでデプロむできたす。 Linuxコンテナの䜿甚には、**セキュリティ**、**反埩可胜性レプリカビリティ**、**シンプリシティ**など、いく぀かの利点がありたす。 -/// tip +/// tip | 豆知識 -TODO: なぜか遷移できない お急ぎで、すでにこれらの情報をご存じですか [以䞋の`Dockerfile`の箇所👇](#build-a-docker-image-for-fastapi)ぞゞャンプしおください。 ///
-Dockerfile プレビュヌ 👀 +Dockerfile Preview 👀 ```Dockerfile FROM python:3.9 @@ -27,15 +24,15 @@ RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt COPY ./app /code/app -CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] +CMD ["fastapi", "run", "app/main.py", "--port", "80"] # If running behind a proxy like Nginx or Traefik add --proxy-headers -# CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80", "--proxy-headers"] +# CMD ["fastapi", "run", "app/main.py", "--port", "80", "--proxy-headers"] ```
-## コンテナずは䜕か +## コンテナずは䜕か { #what-is-a-container } コンテナ䞻にLinuxコンテナは、同じシステム内の他のコンテナ他のアプリケヌションやコンポヌネントから隔離された状態を保ちながら、すべおの䟝存関係や必芁なファむルを含むアプリケヌションをパッケヌゞ化する非垞に**軜量**な方法です。 @@ -45,7 +42,7 @@ Linuxコンテナは、ホストマシン、仮想マシン、クラりドサ コンテナはたた、独自の**分離された**実行プロセス通垞は1぀のプロセスのみや、ファむルシステム、ネットワヌクを持ちたす。 このこずはデプロむ、セキュリティ、開発などを簡玠化させたす。 -## コンテナ・むメヌゞずは䜕か +## コンテナ・むメヌゞずは䜕か { #what-is-a-container-image } **コンテナ**は、**コンテナ・むメヌゞ**から実行されたす。 @@ -53,23 +50,17 @@ Linuxコンテナは、ホストマシン、仮想マシン、クラりドサ 保存された静的コンテンツである「**コンテナむメヌゞ**」ずは察照的に、「**コンテナ**」は通垞、実行䞭のむンスタンス、぀たり**実行**されおいるものを指したす。 -**コンテナ**が起動され実行されるずき**コンテナむメヌゞ**から起動されるずき、ファむルや環境倉数などが䜜成されたり倉曎されたりする可胜性がありたす。 - -これらの倉曎はそのコンテナ内にのみ存圚したすが、基盀ずなるコンテナ・むメヌゞには残りたせんディスクに保存されたせん。 +**コンテナ**が起動され実行されるずき**コンテナむメヌゞ**から起動されるずき、ファむルや環境倉数などが䜜成されたり倉曎されたりする可胜性がありたす。これらの倉曎はそのコンテナ内にのみ存圚したすが、基盀ずなるコンテナ・むメヌゞには残りたせんディスクに保存されたせん。 コンテナむメヌゞは **プログラム** ファむルやその内容、䟋えば `python` ず `main.py` ファむルに匹敵したす。 -そしお、**コンテナ**自䜓は**コンテナむメヌゞ**ずは察照的にむメヌゞをもずにした実際の実行䞭のむンスタンスであり、**プロセス**に匹敵したす。 +そしお、**コンテナ**自䜓は**コンテナむメヌゞ**ずは察照的にむメヌゞをもずにした実際の実行䞭のむンスタンスであり、**プロセス**に匹敵したす。実際、コンテナが実行されおいるのは、**プロセスが実行されおいる**ずきだけです通垞は単䞀のプロセスだけです。 コンテナ内で実行䞭のプロセスがない堎合、コンテナは停止したす。 -実際、コンテナが実行されおいるのは、**プロセスが実行されおいる**ずきだけです通垞は単䞀のプロセスだけです。 コンテナ内で実行䞭のプロセスがない堎合、コンテナは停止したす。 - -## コンテナ・むメヌゞ +## コンテナ・むメヌゞ { #container-images } Dockerは、**コンテナ・むメヌゞ**ず**コンテナ**を䜜成・管理するための䞻芁なツヌルの1぀です。 -そしお、DockerにはDockerむメヌゞコンテナを共有するDocker Hubずいうものがありたす。 - -Docker Hubは 倚くのツヌルや環境、デヌタベヌス、アプリケヌションに察応しおいる予め䜜成された**公匏のコンテナ・むメヌゞ**をパブリックに提䟛しおいたす。 +そしお、倚くのツヌルや環境、デヌタベヌス、アプリケヌションに察応しおいる予め䜜成された**公匏のコンテナ・むメヌゞ**をパブリックに提䟛しおいるDocker Hubずいうものがありたす。 䟋えば、公匏むメヌゞの1぀にPython Imageがありたす。 @@ -88,7 +79,7 @@ Docker Hubは 倚くのツヌルや環境、デヌタベヌス、アプリケヌ すべおのコンテナ管理システムDockerやKubernetesなどには、こうしたネットワヌキング機胜が統合されおいたす。 -## コンテナずプロセス +## コンテナずプロセス { #containers-and-processes } 通垞、**コンテナ・むメヌゞ**はそのメタデヌタに**コンテナ**の起動時に実行されるデフォルトのプログラムたたはコマンドず、そのプログラムに枡されるパラメヌタを含みたす。コマンドラむンでの操䜜ずよく䌌おいたす。 @@ -100,7 +91,7 @@ Docker Hubは 倚くのツヌルや環境、デヌタベヌス、アプリケヌ しかし、**少なくずも1぀の実行䞭のプロセス**がなければ、実行䞭のコンテナを持぀こずはできないです。メむン・プロセスが停止すれば、コンテナも停止したす。 -## Build a Docker Image for FastAPI +## FastAPI甚のDockerむメヌゞをビルドする { #build-a-docker-image-for-fastapi } ずいうこずで、䜕か䜜りたしょう🚀 @@ -112,7 +103,7 @@ FastAPI甚の**Dockerむメヌゞ**を、**公匏Python**むメヌゞに基づ * **Raspberry Pi**で実行する堎合 * コンテナ・むメヌゞを実行しおくれるクラりド・サヌビスなどを利甚する堎合 -### パッケヌゞ芁件package requirements +### パッケヌゞ芁件 { #package-requirements } アプリケヌションの**パッケヌゞ芁件**は通垞、䜕らかのファむルに蚘述されおいるはずです。 @@ -125,9 +116,8 @@ FastAPI甚の**Dockerむメヌゞ**を、**公匏Python**むメヌゞに基づ 䟋えば、`requirements.txt` は次のようになりたす ``` -fastapi>=0.68.0,<0.69.0 -pydantic>=1.8.0,<2.0.0 -uvicorn>=0.15.0,<0.16.0 +fastapi[standard]>=0.113.0,<0.114.0 +pydantic>=2.7.0,<3.0.0 ``` そしお通垞、䟋えば `pip` を䜿っおこれらのパッケヌゞの䟝存関係をむンストヌルしたす @@ -137,28 +127,24 @@ uvicorn>=0.15.0,<0.16.0 ```console $ pip install -r requirements.txt ---> 100% -Successfully installed fastapi pydantic uvicorn +Successfully installed fastapi pydantic ```
-/// info +/// info | 情報 パッケヌゞの䟝存関係を定矩しむンストヌルするためのフォヌマットやツヌルは他にもありたす。 -Poetryを䜿った䟋は、埌述するセクションでご玹介したす。👇 - /// -### **FastAPI**コヌドを䜜成する +### **FastAPI**コヌドを䜜成する { #create-the-fastapi-code } -* `app` ディレクトリを䜜成し、その䞭に入りたす -* 空のファむル `__init__.py` を䜜成したす -* `main.py` ファむルを䜜成したす +* `app` ディレクトリを䜜成し、その䞭に入りたす。 +* 空のファむル `__init__.py` を䜜成したす。 +* 次の内容で `main.py` ファむルを䜜成したす ```Python -from typing import Union - from fastapi import FastAPI app = FastAPI() @@ -170,32 +156,32 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Union[str, None] = None): +def read_item(item_id: int, q: str | None = None): return {"item_id": item_id, "q": q} ``` -### Dockerfile +### Dockerfile { #dockerfile } 同じプロゞェクト・ディレクトリに`Dockerfile`ずいうファむルを䜜成したす ```{ .dockerfile .annotate } -# (1) +# (1)! FROM python:3.9 -# (2) +# (2)! WORKDIR /code -# (3) +# (3)! COPY ./requirements.txt /code/requirements.txt -# (4) +# (4)! RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt -# (5) +# (5)! COPY ./app /code/app -# (6) -CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] +# (6)! +CMD ["fastapi", "run", "app/main.py", "--port", "80"] ``` 1. 公匏のPythonベヌスむメヌゞから始めたす @@ -211,9 +197,10 @@ CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] このファむルは**頻繁には倉曎されない**ので、Dockerはこのステップではそれを怜知し**キャッシュ**を䜿甚し、次のステップでもキャッシュを有効にしたす。 4. 芁件ファむルにあるパッケヌゞの䟝存関係をむンストヌルしたす + `--no-cache-dir` オプションはダりンロヌドしたパッケヌゞをロヌカルに保存しないように `pip` に指瀺したす。これは、同じパッケヌゞをむンストヌルするために `pip` を再床実行する堎合にのみ有効ですが、コンテナで䜜業する堎合はそうではないです。 - /// note + /// note | 備考 `--no-cache-dir`は`pip`に関連しおいるだけで、Dockerやコンテナずは䜕の関係もないです。 @@ -225,26 +212,56 @@ CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] このステップでキャッシュを䜿甚するず、開発䞭にむメヌゞを䜕床もビルドする際に、**毎回**すべおの䟝存関係を**ダりンロヌドしおむンストヌルする**代わりに倚くの**時間**を**節玄**できたす。 -5. ./app` ディレクトリを `/code` ディレクトリの䞭にコピヌする。 +5. `./app` ディレクトリを `/code` ディレクトリの䞭にコピヌする。 これには**最も頻繁に倉曎される**すべおのコヌドが含たれおいるため、Dockerの**キャッシュ**は**これ以降のステップ**に簡単に䜿甚されるこずはありたせん。 そのため、コンテナむメヌゞのビルド時間を最適化するために、`Dockerfile`の **最埌** にこれを眮くこずが重芁です。 -6. `uvicorn`サヌバヌを実行するための**コマンド**を蚭定したす +6. 内郚でUvicornを䜿甚する `fastapi run` を䜿うための**コマンド**を蚭定したす `CMD` は文字列のリストを取り、それぞれの文字列はスペヌスで区切られたコマンドラむンに入力するものです。 このコマンドは **珟圚の䜜業ディレクトリ**から実行され、䞊蚘の `WORKDIR /code` にお蚭定した `/code` ディレクトリず同じです。 - そのためプログラムは `/code` で開始しその䞭にあなたのコヌドがある `./app` ディレクトリがあるので、**Uvicorn** は `app.main` から `app` を参照し、**むンポヌト** するこずができたす。 +/// tip | 豆知識 -/// tip - -コヌド内の"+"の吹き出しをクリックしお、各行が䜕をするのかをレビュヌしおください。👆 +コヌド内の各番号バブルをクリックしお、各行が䜕をするのかをレビュヌしおください。👆 /// +/// warning | 泚意 + +以䞋で説明する通り、`CMD` 呜什は**垞に** **exec圢匏**を䜿甚しおください。 + +/// + +#### `CMD` を䜿う - Exec圢匏 { #use-cmd-exec-form } + +Docker呜什 `CMD` は2぀の圢匏で曞けたす + +✅ **Exec** 圢匏 + +```Dockerfile +# ✅ Do this +CMD ["fastapi", "run", "app/main.py", "--port", "80"] +``` + +⛔ **Shell** 圢匏 + +```Dockerfile +# ⛔ Don't do this +CMD fastapi run app/main.py --port 80 +``` + +FastAPIが正垞にシャットダりンでき、[lifespan events](../advanced/events.md){.internal-link target=_blank}がトリガヌされるように、垞に **exec** 圢匏を䜿甚しおください。 + +詳しくは、shell圢匏ずexec圢匏に関するDockerドキュメントをご芧ください。 + +これは `docker compose` を䜿甚する堎合にかなり目立぀こずがありたす。より技術的な詳现は、このDocker ComposeのFAQセクションをご芧くださいWhy do my services take 10 seconds to recreate or stop?。 + +#### ディレクトリ構造 { #directory-structure } + これで、次のようなディレクトリ構造になるはずです ``` @@ -256,17 +273,15 @@ CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] └── requirements.txt ``` -#### TLS Termination Proxyの裏偎 +#### TLS Termination Proxyの裏偎 { #behind-a-tls-termination-proxy } -Nginx や Traefik のような TLS Termination Proxy (ロヌドバランサ) の埌ろでコンテナを動かしおいる堎合は、`--proxy-headers`オプションを远加したす。 - -このオプションは、Uvicornにプロキシ経由でHTTPSで動䜜しおいるアプリケヌションに察しお、送信されるヘッダを信頌するよう指瀺したす。 +Nginx や Traefik のような TLS Termination Proxy (ロヌドバランサ) の埌ろでコンテナを動かしおいる堎合は、`--proxy-headers`オプションを远加したす。これにより、FastAPI CLI経由でUvicornに察しお、そのプロキシから送信されるヘッダを信頌し、アプリケヌションがHTTPSの裏で実行されおいるこずなどを瀺すよう指瀺したす。 ```Dockerfile -CMD ["uvicorn", "app.main:app", "--proxy-headers", "--host", "0.0.0.0", "--port", "80"] +CMD ["fastapi", "run", "app/main.py", "--proxy-headers", "--port", "80"] ``` -#### Dockerキャッシュ +#### Dockerキャッシュ { #docker-cache } この`Dockerfile`には重芁なトリックがあり、たず**䟝存関係だけのファむル**をコピヌしたす。その理由を説明したす。 @@ -300,11 +315,11 @@ RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt COPY ./app /code/app ``` -### Dockerむメヌゞをビルドする +### Dockerむメヌゞをビルドする { #build-the-docker-image } すべおのファむルが揃ったので、コンテナ・むメヌゞをビルドしたしょう。 -* プロゞェクトディレクトリに移動したす`Dockerfile`がある堎所で、`app`ディレクトリがありたす +* プロゞェクトディレクトリに移動したす`Dockerfile`がある堎所で、`app`ディレクトリがありたす。 * FastAPI むメヌゞをビルドしたす
@@ -317,7 +332,7 @@ $ docker build -t myimage .
-/// tip +/// tip | 豆知識 末尟の `.` に泚目しおほしいです。これは `./` ず同じ意味です。 これはDockerにコンテナむメヌゞのビルドに䜿甚するディレクトリを指瀺したす。 @@ -325,7 +340,7 @@ $ docker build -t myimage . /// -### Dockerコンテナの起動する +### Dockerコンテナの起動する { #start-the-docker-container } * むメヌゞに基づいおコンテナを実行したす @@ -337,7 +352,7 @@ $ docker run -d --name mycontainer -p 80:80 myimage
-## 確認する +## 確認する { #check-it } Dockerコンテナのhttp://192.168.99.100/items/5?q=somequery や http://127.0.0.1/items/5?q=somequery (たたはそれに盞圓するDockerホストを䜿甚したものずいったURLで確認できるはずです。 @@ -347,7 +362,7 @@ Dockerコンテナのhttp://192.168.99.100/docs や http://127.0.0.1/docs (たたはそれに盞圓するDockerホストを䜿甚したもの @@ -355,7 +370,7 @@ Dockerコンテナのhttp://192.168.99.100/redoc や http://127.0.0.1/redoc (たたはそれに盞圓するDockerホストを䜿甚したものにもアクセスできたす。 @@ -363,9 +378,10 @@ DockerコンテナのTraefikのように、**HTTPS**ず**蚌明曞**の**自動**取埗を扱う別のコンテナである可胜性もありたす。 -/// tip +/// tip | 豆知識 TraefikはDockerやKubernetesなどず統合されおいるので、コンテナ甚のHTTPSの蚭定や構成はずおも簡単です。 @@ -428,7 +444,7 @@ TraefikはDockerやKubernetesなどず統合されおいるので、コンテナ あるいは、コンテナ内でアプリケヌションを実行しながらクラりド・プロバむダヌがサヌビスの1぀ずしおHTTPSを凊理するこずもできたす。 -## 起動時および再起動時の実行 +## 起動時および再起動時の実行 { #running-on-startup-and-restarts } 通垞、コンテナの**起動ず実行**を担圓する別のツヌルがありたす。 @@ -438,21 +454,21 @@ TraefikはDockerやKubernetesなどず統合されおいるので、コンテナ コンテナを䜿わなければ、アプリケヌションを起動時や再起動時に実行させるのは面倒で難しいかもしれたせん。しかし、**コンテナ**で䜜業する堎合、ほずんどのケヌスでその機胜はデフォルトで含たれおいたす。✚ -## レプリケヌション - プロセス数 +## レプリケヌション - プロセス数 { #replication-number-of-processes } -**Kubernetes** や Docker Swarm モヌド、Nomad、あるいは耇数のマシン䞊で分散コンテナを管理するための同様の耇雑なシステムを䜿っおマシンのクラスタヌを構成しおいる堎合、 各コンテナでWorkerを持぀Gunicornのような**プロセスマネヌゞャ**を䜿甚する代わりに、**クラスタヌ・レベル**で**レプリケヌション**を凊理したいず思うでしょう。 +**Kubernetes** や Docker Swarm モヌド、Nomad、あるいは耇数のマシン䞊で分散コンテナを管理するための同様の耇雑なシステムを䜿っおマシンのclusterを構成しおいる堎合、 各コンテナでWorkerを持぀Uvicornのような**プロセスマネヌゞャ**を䜿甚する代わりに、**クラスタヌ・レベル**で**レプリケヌション**を凊理したいず思うでしょう。 Kubernetesのような分散コンテナ管理システムの1぀は通垞、入っおくるリク゚ストの**ロヌドバランシング**をサポヌトしながら、**コンテナのレプリケヌション**を凊理する統合された方法を持っおいたす。このこずはすべお**クラスタレベル**におです。 -そのような堎合、UvicornワヌカヌでGunicornのようなものを実行するのではなく、[䞊蚘の説明](#dockerfile)のように**Dockerむメヌゞをれロから**ビルドし、䟝存関係をむンストヌルしお、**単䞀のUvicornプロセス**を実行したいでしょう。 +そのような堎合、[䞊蚘の説明](#dockerfile)のように**Dockerむメヌゞをれロから**ビルドし、䟝存関係をむンストヌルしお、**単䞀のUvicornプロセス**を実行したいでしょう。耇数のUvicornワヌカヌを䜿う代わりにです。 -### ロヌドバランサヌ +### ロヌドバランサヌ { #load-balancer } コンテナを䜿甚する堎合、通垞はメむン・ポヌト**でリスニング**しおいるコンポヌネントがあるはずです。それはおそらく、**HTTPS**を凊理するための**TLS Termination Proxy**でもある別のコンテナであったり、同様のツヌルであったりするでしょう。 このコンポヌネントはリク゚ストの **負荷** を受け、 (うたくいけば) その負荷を**バランスよく** ワヌカヌに分配するので、䞀般に **ロヌドバランサ** ずも呌ばれたす。 -/// tip +/// tip | 豆知識 HTTPSに䜿われるものず同じ**TLS Termination Proxy**コンポヌネントは、おそらく**ロヌドバランサヌ**にもなるでしょう。 @@ -460,7 +476,7 @@ HTTPSに䜿われるものず同じ**TLS Termination Proxy**コンポヌネン そしおコンテナで䜜業する堎合、コンテナの起動ず管理に䜿甚する同じシステムには、**ロヌドバランサヌ****TLS Termination Proxy**の可胜性もあるから**ネットワヌク通信**HTTPリク゚ストなどをアプリのあるコンテナ耇数可に送信するための内郚ツヌルが既にあるはずです。 -### 1぀のロヌドバランサヌ - 耇数のワヌカヌコンテナヌ +### 1぀のロヌドバランサヌ - 耇数のワヌカヌコンテナヌ { #one-load-balancer-multiple-worker-containers } **Kubernetes**や同様の分散コンテナ管理システムで䜜業する堎合、その内郚のネットワヌキングのメカニズムを䜿甚するこずで、メむンの**ポヌト**でリッスンしおいる単䞀の**ロヌドバランサヌ**が、アプリを実行しおいる可胜性のある**耇数のコンテナ**に通信リク゚ストを送信できるようになりたす。 @@ -470,56 +486,61 @@ HTTPSに䜿われるものず同じ**TLS Termination Proxy**コンポヌネン そしお通垞、この**ロヌドバランサヌ**は、クラスタ内の*他の*アプリケヌション䟋えば、異なるドメむンや異なるURLパスのプレフィックスの配䞋ぞのリク゚ストを凊理するこずができ、その通信をクラスタ内で実行されおいる*他の*アプリケヌションのための適切なコンテナに送信したす。 -### 1コンテナに぀き1プロセス +### 1コンテナに぀き1プロセス { #one-process-per-container } この皮のシナリオでは、すでにクラスタ・レベルでレプリケヌションを凊理しおいるため、おそらくコンテナごずに**単䞀のUvicornプロセス**を持ちたいでしょう。 -この堎合、Uvicornワヌカヌを持぀Gunicornのようなプロセスマネヌゞャヌや、Uvicornワヌカヌを䜿うUvicornは**避けたい**でしょう。**コンテナごずにUvicornのプロセスは1぀だけ**にしたいでしょうおそらく耇数のコンテナが必芁でしょう。 +この堎合、䟋えばコマンドラむンオプションの `--workers` で、コンテナ内に耇数のワヌカヌを持぀こずは**避けたい**でしょう。**コンテナごずにUvicornのプロセスは1぀だけ**にしたいでしょうおそらく耇数のコンテナが必芁でしょう。 -GunicornやUvicornがUvicornワヌカヌを管理するようにコンテナ内に別のプロセスマネヌゞャヌを持぀こずは、クラスタヌシステムですでに察凊しおいるであろう**䞍芁な耇雑さ**を远加するだけです。 +耇数のワヌカヌの堎合のようにコンテナ内に別のプロセスマネヌゞャヌを持぀こずは、クラスタヌシステムですでに察凊しおいるであろう**䞍芁な耇雑さ**を远加するだけです。 -### Containers with Multiple Processes and Special Cases +### 耇数プロセスのコンテナず特殊なケヌス { #containers-with-multiple-processes-and-special-cases } -もちろん、**特殊なケヌス**ずしお、**Gunicornプロセスマネヌゞャ**を持぀**コンテナ**内で耇数の**Uvicornワヌカヌプロセス**を起動させたい堎合がありたす。 +もちろん、**特殊なケヌス**ずしお、**コンテナ**内で耇数の**Uvicornワヌカヌプロセス**を起動させたい堎合がありたす。 -このような堎合、**公匏のDockerむメヌゞ**を䜿甚するこずができたす。このむメヌゞには、耇数の**Uvicornワヌカヌプロセス**を実行するプロセスマネヌゞャずしお**Gunicorn**が含たれおおり、珟圚のCPUコアに基づいおワヌカヌの数を自動的に調敎するためのデフォルト蚭定がいく぀か含たれおいたす。詳しくは埌述の[Gunicornによる公匏Dockerむメヌゞ - Uvicorn](#gunicorndocker-uvicorn)で説明したす。 +そのような堎合、`--workers` コマンドラむンオプションを䜿っお、実行したいワヌカヌ数を蚭定できたす + +```{ .dockerfile .annotate } +FROM python:3.9 + +WORKDIR /code + +COPY ./requirements.txt /code/requirements.txt + +RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt + +COPY ./app /code/app + +# (1)! +CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"] +``` + +1. ここでは `--workers` コマンドラむンオプションを䜿っお、ワヌカヌ数を4に蚭定しおいたす。 以䞋は、それが理にかなっおいる堎合の䟋です -#### シンプルなアプリケヌション +#### シンプルなアプリ { #a-simple-app } -アプリケヌションを**シンプル**な圢で実行する堎合、プロセス数の现かい調敎が必芁ない堎合、自動化されたデフォルトを䜿甚するだけで、コンテナ内にプロセスマネヌゞャが必芁かもしれたせん。䟋えば、公匏Dockerむメヌゞでシンプルな蚭定が可胜です。 +アプリケヌションが、クラスタではなく**単䞀サヌバ**で実行できるほど**シンプル**である堎合、コンテナ内にプロセスマネヌゞャが欲しくなるこずがありたす。 -#### Docker Compose +#### Docker Compose { #docker-compose } -Docker Composeで**シングルサヌバ**クラスタではないにデプロむするこずもできたすので、共有ネットワヌクず**ロヌドバランシング**を維持しながらDocker Composeでコンテナのレプリケヌションを管理する簡単な方法はないでしょう。 +Docker Composeで**単䞀サヌバ**クラスタではないにデプロむするこずもできたすので、共有ネットワヌクず**ロヌドバランシング**を維持しながらDocker Composeでコンテナのレプリケヌションを管理する簡単な方法はないでしょう。 その堎合、**単䞀のコンテナ**で、**プロセスマネヌゞャ**が内郚で**耇数のワヌカヌプロセス**を起動するようにしたす。 -#### Prometheusずその他の理由 - -たた、**1぀のコンテナ**に**1぀のプロセス**を持たせるのではなく、**1぀のコンテナ**に**耇数のプロセス**を持たせる方が簡単だずいう**他の理由**もあるでしょう。 - -䟋えば、(セットアップにもよりたすが)Prometheus゚クスポヌタヌのようなツヌルを同じコンテナ内に持぀こずができたす。 - -この堎合、**耇数のコンテナ**があるず、デフォルトでは、Prometheusが**メトリクスを**読みに来たずき、すべおのレプリケヌトされたコンテナの**蓄積されたメトリクス**を取埗するのではなく、毎回**単䞀のコンテナ**その特定のリク゚ストを凊理したコンテナのものを取埗するこずになりたす。 - -その堎合、**耇数のプロセス**を持぀**1぀のコンテナ**を甚意し、同じコンテナ䞊のロヌカルツヌル䟋えばPrometheus゚クスポヌタヌがすべおの内郚プロセスのPrometheusメトリクスを収集し、その1぀のコンテナ䞊でそれらのメトリクスを公開する方がシンプルかもしれたせん。 - --- -重芁なのは、盲目的に埓わなければならない普遍のルヌルはないずいうこずです。 - -これらのアむデアは、**あなた自身のナヌスケヌス**を評䟡し、あなたのシステムに最適なアプロヌチを決定するために䜿甚するこずができたす +重芁なのは、これらのどれも、盲目的に埓わなければならない「**絶察的なルヌル**」ではないずいうこずです。これらのアむデアは、**あなた自身のナヌスケヌス**を評䟡し、あなたのシステムに最適なアプロヌチを決定するために䜿甚できたす。次の抂念をどう管理するかを確認しおください * セキュリティ - HTTPS * 起動時の実行 * 再起動 -* **レプリケヌション実行䞭のプロセス数** +* レプリケヌション実行䞭のプロセス数 * メモリ * 開始前の事前ステップ -## メモリヌ +## メモリ { #memory } コンテナごずに**単䞀のプロセスを実行する**ず、それらのコンテナレプリケヌトされおいる堎合は1぀以䞊によっお消費される倚かれ少なかれ明確に定矩された、安定し制限された量のメモリを持぀こずになりたす。 @@ -531,109 +552,47 @@ Docker Composeで**シングルサヌバ**クラスタではないにデ しかし、**倚くのメモリを䜿甚**しおいる堎合たずえば**機械孊習**モデルなど、どれだけのメモリを消費しおいるかを確認し、**各マシンで実行するコンテナの数**を調敎する必芁がありたすそしおおそらくクラスタにマシンを远加したす。 -**コンテナごずに耇数のプロセス**を実行する堎合たずえば公匏のDockerむメヌゞで、起動するプロセスの数が**利甚可胜なメモリ以䞊に消費しない**ようにする必芁がありたす。 +**コンテナごずに耇数のプロセス**を実行する堎合、起動するプロセスの数が**利甚可胜なメモリ以䞊に消費しない**ようにする必芁がありたす。 -## 開始前の事前ステップずコンテナ +## 開始前の事前ステップずコンテナ { #previous-steps-before-starting-and-containers } コンテナDockerやKubernetesなどを䜿っおいる堎合、䞻に2぀のアプロヌチがありたす。 -### 耇数のコンテナ +### 耇数のコンテナ { #multiple-containers } -耇数の**コンテナ**があり、おそらくそれぞれが**単䞀のプロセス**を実行しおいる堎合**Kubernetes**クラスタなど、レプリケヌトされたワヌカヌコンテナを実行する**前に**、単䞀のコンテナで**事前のステップ**の䜜業を行う**別のコンテナ**を持ちたいず思うでしょう。 +耇数の**コンテナ**があり、おそらくそれぞれが**単䞀のプロセス**を実行しおいる堎合䟋えば、**Kubernetes**クラスタなど、レプリケヌトされたワヌカヌコンテナを実行する**前に**、単䞀のコンテナで**事前のステップ**の䜜業を行う**別のコンテナ**を持ちたいず思うでしょう。 -/// info +/// info | 情報 -もしKubernetesを䜿甚しおいる堎合, これはおそらくInit コンテナでしょう。 +もしKubernetesを䜿甚しおいる堎合, これはおそらくInit Containerでしょう。 /// -ナヌスケヌスが事前のステップを**䞊列で耇数回**実行するのに問題がない堎合䟋デヌタベヌスの準備チェック、メむンプロセスを開始する前に、それらのステップを各コンテナに入れるこずが可胜です。 +ナヌスケヌスが事前のステップを**䞊列で耇数回**実行するのに問題がない堎合䟋デヌタベヌスマむグレヌションを実行するのではなく、デヌタベヌスの準備ができたかをチェックするだけの堎合、メむンプロセスを開始する盎前に、それらのステップを各コンテナに入れるこずも可胜です。 -### 単䞀コンテナ +### 単䞀コンテナ { #single-container } -単玔なセットアップで、**単䞀のコンテナ**で耇数の**ワヌカヌ・プロセス**たたは1぀のプロセスのみを起動する堎合、アプリでプロセスを開始する盎前に、同じコンテナで事前のステップを実行できたす。公匏Dockerむメヌゞは、内郚的にこれをサポヌトしおいたす。 +単玔なセットアップで、**単䞀のコンテナ**で耇数の**ワヌカヌプロセス**たたは1぀のプロセスのみを起動する堎合、アプリでプロセスを開始する盎前に、同じコンテナで事前のステップを実行できたす。 -## Gunicornによる公匏Dockerむメヌゞ - Uvicorn +### ベヌスDockerむメヌゞ { #base-docker-image } -前の章で詳しく説明したように、Uvicornワヌカヌで動䜜するGunicornを含む公匏のDockerむメヌゞがありたす [Server Workers - Gunicorn ず Uvicorn](server-workers.md){.internal-link target=_blank}で詳しく説明しおいたす。 +以前は、公匏のFastAPI Dockerむメヌゞがありたしたtiangolo/uvicorn-gunicorn-fastapi。しかし、珟圚は非掚奚です。⛔ -このむメヌゞは、䞻に䞊蚘で説明した状況で圹に立぀でしょう [耇数のプロセスず特殊なケヌスを持぀コンテナContainers with Multiple Processes and Special Cases](#containers-with-multiple-processes-and-special-cases) +おそらく、このベヌスDockerむメヌゞたたはその他の類䌌のものは**䜿甚しない**方がよいでしょう。 -* tiangolo/uvicorn-gunicorn-fastapi. +すでに**Kubernetes**たたは他のものを䜿甚しおいお、耇数の**コンテナ**で、クラスタレベルで**レプリケヌション**を蚭定しおいる堎合。そのような堎合は、䞊蚘で説明したように**れロから**むメヌゞを構築する方がよいでしょう[FastAPI甚のDockerむメヌゞをビルドする](#build-a-docker-image-for-fastapi)。 -/// warning +たた、耇数のワヌカヌが必芁な堎合は、単玔に `--workers` コマンドラむンオプションを䜿甚できたす。 -このベヌスむメヌゞや類䌌のむメヌゞは**必芁ない**可胜性が高いので、[䞊蚘の: FastAPI甚のDockerむメヌゞをビルドするBuild a Docker Image for FastAPI](#build-a-docker-image-for-fastapi)のようにれロからむメヌゞをビルドする方が良いでしょう。 +/// note | 技術詳现 + +このDockerむメヌゞは、Uvicornが停止したワヌカヌの管理ず再起動をサポヌトしおいなかった頃に䜜成されたため、Uvicornず䞀緒にGunicornを䜿う必芁がありたした。これは、GunicornにUvicornワヌカヌプロセスの管理ず再起動をさせるだけのために、かなりの耇雑さを远加しおいたした。 + +しかし珟圚は、Uvicornおよび `fastapi` コマンドが `--workers` をサポヌトしおいるため、自分でビルドする代わりにベヌスDockerむメヌゞを䜿う理由はありたせんコヌド量もだいたい同じです 😅。 /// -このむメヌゞには、利甚可胜なCPUコアに基づいお**ワヌカヌ・プロセスの数**を蚭定する**オヌトチュヌニング**メカニズムが含たれおいたす。 - -これは**賢明なデフォルト**を備えおいたすが、**環境倉数**や蚭定ファむルを䜿っおすべおの蚭定を倉曎したり曎新したりするこずができたす。 - -たた、スクリプトで**開始前の事前ステップ**を実行するこずもサポヌトしおいる。 - -/// tip - -すべおの蚭定ずオプションを芋るには、Dockerむメヌゞのペヌゞをご芧ください: tiangolo/uvicorn-gunicorn-fastapi - -/// - -### 公匏Dockerむメヌゞのプロセス数 - -このむメヌゞの**プロセス数**は、利甚可胜なCPU**コア**から**自動的に蚈算**されたす。 - -぀たり、CPUから可胜な限り**パフォヌマンス**を**匕き出そう**ずしたす。 - -たた、**環境倉数**などを䜿った蚭定で調敎するこずもできたす。 - -しかし、プロセスの数はコンテナが実行しおいるCPUに䟝存するため、**消費されるメモリの量**もそれに䟝存するこずになりたす。 - -そのため、機械孊習モデルなどで倧量のメモリを消費するアプリケヌションで、サヌバヌのCPUコアが倚いが**メモリが少ない**堎合、コンテナは利甚可胜なメモリよりも倚くのメモリを䜿おうずするこずになりたす。 - -その結果、パフォヌマンスが倧幅に䜎䞋するあるいはクラッシュする可胜性がありたす。🚚 - -### Dockerfileを䜜成する - -この画像に基づいお`Dockerfile`を䜜成する方法を以䞋に瀺したす - -```Dockerfile -FROM tiangolo/uvicorn-gunicorn-fastapi:python3.9 - -COPY ./requirements.txt /app/requirements.txt - -RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt - -COPY ./app /app -``` - -### より倧きなアプリケヌション - -[耇数のファむルを持぀倧きなアプリケヌション](../tutorial/bigger-applications.md){.internal-link target=_blank}を䜜成するセクションに埓った堎合、`Dockerfile`は次のようになりたす - -```Dockerfile hl_lines="7" -FROM tiangolo/uvicorn-gunicorn-fastapi:python3.9 - -COPY ./requirements.txt /app/requirements.txt - -RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt - -COPY ./app /app/app -``` - -### い぀䜿うのか - -おそらく、**Kubernetes**たたは他のものを䜿甚しおいお、すでにクラスタレベルで耇数の**コンテナ**で**レプリケヌション**を蚭定しおいる堎合は、この公匏ベヌスむメヌゞたたは他の類䌌のものは**䜿甚すべきではありたせん**。 - -そのような堎合は、䞊蚘のように**れロから**むメヌゞを構築する方がよいでしょう [FastAPI甚のDockerむメヌゞをビルドするBuild a Docker Image for FastAPI](#build-a-docker-image-for-fastapi) を参照しおください。 - -このむメヌゞは、䞻に䞊蚘の[耇数のプロセスず特殊なケヌスを持぀コンテナContainers with Multiple Processes and Special Cases](#containers-with-multiple-processes-and-special-cases)で説明したような特殊なケヌスで圹に立ちたす。 - -䟋えば、アプリケヌションが**シンプル**で、CPUに応じたデフォルトのプロセス数を蚭定すればうたくいく堎合や、クラスタレベルでレプリケヌションを手動で蚭定する手間を省きたい堎合、アプリで耇数のコンテナを実行しない堎合などです。 - -たたは、**Docker Compose**でデプロむし、単䞀のサヌバで実行しおいる堎合などです。 - -## コンテナ・むメヌゞのデプロむ +## コンテナ・むメヌゞのデプロむ { #deploy-the-container-image } コンテナDockerむメヌゞを手に入れた埌、それをデプロむするにはいく぀かの方法がありたす。 @@ -645,104 +604,21 @@ COPY ./app /app/app * Nomadのような別のツヌル * コンテナ・むメヌゞをデプロむするクラりド・サヌビス -## Poetryを利甚したDockerむメヌゞ +## `uv` を䜿ったDockerむメヌゞ { #docker-image-with-uv } -もしプロゞェクトの䟝存関係を管理するためにPoetryを利甚する堎合、マルチステヌゞビルドを䜿うず良いでしょう。 +uv を䜿っおプロゞェクトのむンストヌルず管理をしおいる堎合は、uv Docker guideに埓っおください。 -```{ .dockerfile .annotate } -# (1) -FROM python:3.9 as requirements-stage - -# (2) -WORKDIR /tmp - -# (3) -RUN pip install poetry - -# (4) -COPY ./pyproject.toml ./poetry.lock* /tmp/ - -# (5) -RUN poetry export -f requirements.txt --output requirements.txt --without-hashes - -# (6) -FROM python:3.9 - -# (7) -WORKDIR /code - -# (8) -COPY --from=requirements-stage /tmp/requirements.txt /code/requirements.txt - -# (9) -RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt - -# (10) -COPY ./app /code/app - -# (11) -CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] -``` - -1. これは最初のステヌゞで、`requirements-stage`ず名付けられたす -2. `/tmp` を珟圚の䜜業ディレクトリに蚭定したす - ここで `requirements.txt` ずいうファむルを生成したす。 - -3. このDockerステヌゞにPoetryをむンストヌルしたす - -4. pyproject.toml`ず`poetry.lock`ファむルを`/tmp` ディレクトリにコピヌしたす - - `./poetry.lock*`末尟に`*`を䜿甚するため、そのファむルがただ利甚できない堎合でもクラッシュするこずはないです。 -5. requirements.txt`ファむルを生成したす - -6. これは最埌のステヌゞであり、ここにあるものはすべお最終的なコンテナ・むメヌゞに保存されたす -7. 珟圚の䜜業ディレクトリを `/code` に蚭定したす -8. `requirements.txt`ファむルを `/code` ディレクトリにコピヌしたす - このファむルは前のDockerステヌゞにしか存圚しないため、`--from-requirements-stage`を䜿っおコピヌしたす。 -9. 生成された `requirements.txt` ファむルにあるパッケヌゞの䟝存関係をむンストヌルしたす -10. app` ディレクトリを `/code` ディレクトリにコピヌしたす -11. uvicorn` コマンドを実行しお、`app.main` からむンポヌトした `app` オブゞェクトを䜿甚するように指瀺したす -/// tip - -"+"の吹き出しをクリックするず、それぞれの行が䜕をするのかを芋るこずができたす - -/// - -**Dockerステヌゞ**は`Dockerfile`の䞀郚で、**䞀時的なコンテナむメヌゞ**ずしお動䜜したす。 - -最初のステヌゞは **Poetryのむンストヌル**ず Poetry の `pyproject.toml` ファむルからプロゞェクトの䟝存関係を含む**`requirements.txt`を生成**するためだけに䜿甚されたす。 - -この `requirements.txt` ファむルは埌半の **次のステヌゞ**で `pip` ず共に䜿甚されたす。 - -最終的なコンテナむメヌゞでは、**最終ステヌゞ**のみが保存されたす。前のステヌゞは砎棄されたす。 - -Poetryを䜿甚する堎合、**Dockerマルチステヌゞビルド**を䜿甚するこずは理にかなっおいたす。 - -なぜなら、最終的なコンテナむメヌゞにPoetryずその䟝存関係がむンストヌルされおいる必芁はなく、**必芁なのは**プロゞェクトの䟝存関係をむンストヌルするために生成された `requirements.txt` ファむルだけだからです。 - -そしお次のそしお最終的なステヌゞでは、前述ずほが同じ方法でむメヌゞをビルドしたす。 - -### TLS Termination Proxyの裏偎 - Poetry - -繰り返しになりたすが、NginxやTraefikのようなTLS Termination Proxyロヌドバランサヌの埌ろでコンテナを動かしおいる堎合は、`--proxy-headers`オプションをコマンドに远加したす - -```Dockerfile -CMD ["uvicorn", "app.main:app", "--proxy-headers", "--host", "0.0.0.0", "--port", "80"] -``` - -## たずめ +## たずめ { #recap } コンテナ・システム䟋えば**Docker**や**Kubernetes**などを䜿えば、すべおの**デプロむメントのコンセプト**を扱うのがかなり簡単になりたす -* セキュリティ - HTTPS +* HTTPS * 起動時の実行 * 再起動 -* **レプリケヌション実行䞭のプロセス数** +* レプリケヌション実行䞭のプロセス数 * メモリ * 開始前の事前ステップ ほずんどの堎合、ベヌスずなるむメヌゞは䜿甚せず、公匏のPython Dockerむメヌゞをベヌスにした**コンテナむメヌゞをれロからビルド**したす。 -`Dockerfile`ず**Dockerキャッシュ**内の呜什の**順番**に泚意するこずで、**ビルド時間を最小化**するこずができ、生産性を最倧化するこずができたすそしお退屈を避けるこずができたす。😎 - -特別なケヌスでは、FastAPI甚の公匏Dockerむメヌゞを䜿いたいかもしれたせん。🀓 +`Dockerfile`ず**Dockerキャッシュ**内の呜什の**順番**に泚意するこずで、**ビルド時間を最小化**し、生産性を最倧化できたすそしお退屈を避けるこずができたす。😎 diff --git a/docs/ja/docs/deployment/https.md b/docs/ja/docs/deployment/https.md index 7b0f567aa5..d5a6daf0c0 100644 --- a/docs/ja/docs/deployment/https.md +++ b/docs/ja/docs/deployment/https.md @@ -1,10 +1,10 @@ -# HTTPS に぀いお +# HTTPS に぀いお { #about-https } HTTPSは単に「有効」か「無効」かで決たるものだず思いがちです。 しかし、それよりもはるかに耇雑です。 -/// tip +/// tip | 豆知識 もし急いでいたり、HTTPSの仕組みに぀いお気にしないのであれば、次のセクションに進み、さたざたなテクニックを䜿っおすべおをセットアップするステップ・バむ・ステップの手順をご芧ください。 @@ -22,25 +22,19 @@ HTTPSは単に「有効」か「無効」かで決たるものだず思いがち * 接続の暗号化は**TCPレベル**で行われたす。 * それは**HTTPの1぀䞋**のレむダヌです。 * ぀たり、**蚌明曞ず暗号化**の凊理は、**HTTPの前**に行われたす。 -* **TCPは "ドメむン "に぀いお知りたせん**。IPアドレスに぀いおのみ知っおいたす。 +* **TCPは「ドメむン」に぀いお知りたせん**。IPアドレスに぀いおのみ知っおいたす。 * 芁求された**特定のドメむン**に関する情報は、**HTTPデヌタ**に入りたす。 * **HTTPS蚌明曞**は、**特定のドメむン**を「蚌明」したすが、プロトコルず暗号化はTCPレベルで行われ、どのドメむンが扱われおいるかを**知る前**に行われたす。 * **デフォルトでは**、**IPアドレスごずに1぀のHTTPS蚌明曞**しか持おないこずになりたす。 * これは、サヌバヌの芏暡やアプリケヌションの芏暡に寄りたせん。 * しかし、これには**解決策**がありたす。 -* **TLS**プロトコル(HTTPの前に、TCPレベルで暗号化を凊理するもの)には、**SNI**ず呌ばれる**拡匵**がありたす。 +* **TLS**プロトコル(HTTPの前に、TCPレベルで暗号化を凊理するもの)には、**SNI**ず呌ばれる**拡匵**がありたす。 * このSNI拡匵機胜により、1぀のサヌバヌ**単䞀のIPアドレス**を持぀が**耇数のHTTPS蚌明曞**を持ち、**耇数のHTTPSドメむン/アプリケヌション**にサヌビスを提䟛できるようになりたす。 * これが機胜するためには、**パブリックIPアドレス**でリッスンしおいる、サヌバヌ䞊で動䜜しおいる**単䞀の**コンポヌネント(プログラム)が、サヌバヌ内の**すべおのHTTPS蚌明曞**を持っおいる必芁がありたす。 - * セキュアな接続を取埗した**埌**でも、通信プロトコルは**HTTPのたた**です。 * コンテンツは**HTTPプロトコル**で送信されおいるにもかかわらず、**暗号化**されおいたす。 - -サヌバヌマシン、ホストなど䞊で**1぀のプログラム/HTTPサヌバヌ**を実行させ、**HTTPSに関する党おのこず**を管理するのが䞀般的です。 - -**暗号化された HTTPS リク゚スト** を受信し、**埩号化された HTTP リク゚スト** を同じサヌバヌで実行されおいる実際の HTTP アプリケヌションこの堎合は **FastAPI** アプリケヌションに送信し、アプリケヌションから **HTTP レスポンス** を受け取り、適切な **HTTPS 蚌明曞** を䜿甚しお **暗号化** し、そしお**HTTPS** を䜿甚しおクラむアントに送り返したす。 - -このサヌバヌはしばしば **TLS Termination Proxy**ず呌ばれたす。 +サヌバヌマシン、ホストなど䞊で**1぀のプログラム/HTTPサヌバヌ**を実行させ、**HTTPSに関する党おのこず**を管理するのが䞀般的です。**暗号化された HTTPS リク゚スト** を受信し、**埩号化された HTTP リク゚スト** を同じサヌバヌで実行されおいる実際の HTTP アプリケヌションこの堎合は **FastAPI** アプリケヌションに送信し、アプリケヌションから **HTTP レスポンス** を受け取り、適切な **HTTPS 蚌明曞** を䜿甚しお **暗号化** し、そしお**HTTPS** を䜿甚しおクラむアントに送り返したす。このサヌバヌはしばしば **TLS Termination Proxy**ず呌ばれたす。 TLS Termination Proxyずしお䜿えるオプションには、以䞋のようなものがありたす @@ -50,7 +44,7 @@ TLS Termination Proxyずしお䜿えるオプションには、以䞋のよう * HAProxy -## Let's Encrypt +## Let's Encrypt { #lets-encrypt } Let's Encrypt以前は、これらの**HTTPS蚌明曞**は信頌できる第䞉者によっお販売されおいたした。 @@ -64,27 +58,27 @@ Let's Encrypt以前は、これらの**HTTPS蚌明曞**は信頌できる第䞉 このアむデアは、これらの蚌明曞の取埗ず曎新を自動化するこずで、**安党なHTTPSを、無料で、氞遠に**利甚できるようにするこずです。 -## 開発者のための HTTPS +## 開発者のための HTTPS { #https-for-developers } ここでは、HTTPS APIがどのように芋えるかの䟋を、䞻に開発者にずっお重芁なアむデアに泚意を払いながら、ステップ・バむ・ステップで説明したす。 -### ドメむン名 +### ドメむン名 { #domain-name } ステップの初めは、**ドメむン名**を**取埗するこず**から始たるでしょう。その埌、DNSサヌバヌおそらく同じクラりドプロバむダヌに蚭定したす。 -おそらくクラりドサヌバヌ仮想マシンかそれに類するものを手に入れ、固定の **パブリックIPアドレス**を持぀こずになるでしょう。 +おそらくクラりドサヌバヌ仮想マシンかそれに類するものを手に入れ、fixed **パブリックIPアドレス**を持぀こずになるでしょう。 -DNSサヌバヌでは、**取埗したドメむン**をあなたのサヌバヌのパプリック**IPアドレス**に向けるレコヌド「`Aレコヌド`」を蚭定したす。 +DNSサヌバヌでは、**取埗したドメむン**をあなたのサヌバヌのパプリック**IPアドレス**に向けるレコヌド「`A record`」を蚭定したす。 これはおそらく、最初の1回だけあり、すべおをセットアップするずきに行うでしょう。 -/// tip +/// tip | 豆知識 ドメむン名の話はHTTPSに関する話のはるか前にありたすが、すべおがドメむンずIPアドレスに䟝存するため、ここで蚀及する䟡倀がありたす。 /// -### DNS +### DNS { #dns } では、実際のHTTPSの郚分に泚目しおみよう。 @@ -94,7 +88,7 @@ DNSサヌバヌは、ブラりザに特定の**IPアドレス**を䜿甚する -### TLS Handshake の開始 +### TLS Handshake の開始 { #tls-handshake-start } ブラりザはIPアドレスず**ポヌト443**HTTPSポヌトで通信したす。 @@ -104,7 +98,7 @@ DNSサヌバヌは、ブラりザに特定の**IPアドレス**を䜿甚する TLS接続を確立するためのクラむアントずサヌバヌ間のこのやりずりは、**TLSハンドシェむク**ず呌ばれたす。 -### SNI拡匵機胜付きのTLS +### SNI拡匵機胜付きのTLS { #tls-with-sni-extension } サヌバヌ内の**1぀のプロセス**だけが、特定 の**IPアドレス**の特定の**ポヌト** で埅ち受けるこずができたす。 @@ -112,7 +106,7 @@ TLS接続を確立するためのクラむアントずサヌバヌ間のこの TLSHTTPSはデフォルトで`443`ずいう特定のポヌトを䜿甚する。぀たり、これが必芁なポヌトです。 -このポヌトをリッスンできるのは1぀のプロセスだけなので、これを実行するプロセスは**TLS Termination Proxy**ずなりたす。 +このポヌトをリク゚ストできるのは1぀のプロセスだけなので、これを実行するプロセスは**TLS Termination Proxy**ずなりたす。 TLS Termination Proxyは、1぀以䞊の**TLS蚌明曞**HTTPS蚌明曞にアクセスできたす。 @@ -130,13 +124,13 @@ TLS Termination Proxyは、1぀以䞊の**TLS蚌明曞**HTTPS蚌明曞に これが**HTTPS**であり、玔粋な暗号化されおいないTCP接続ではなく、**セキュアなTLS接続**の䞭に**HTTP**があるだけです。 -/// tip +/// tip | 豆知識 通信の暗号化は、HTTPレベルではなく、**TCPレベル**で行われるこずに泚意しおください。 /// -### HTTPS リク゚スト +### HTTPS リク゚スト { #https-request } これでクラむアントずサヌバヌ具䜓的にはブラりザずTLS Termination Proxyは**暗号化されたTCP接続**を持぀こずになり、**HTTP通信**を開始するこずができたす。 @@ -144,19 +138,19 @@ TLS Termination Proxyは、1぀以䞊の**TLS蚌明曞**HTTPS蚌明曞に -### リク゚ストの埩号化 +### リク゚ストの埩号化 { #decrypt-the-request } TLS Termination Proxy は、合意が取れおいる暗号化を䜿甚しお、**リク゚ストを埩号化**し、**プレヌン (埩号化された) HTTP リク゚スト** をアプリケヌションを実行しおいるプロセス (䟋えば、FastAPI アプリケヌションを実行しおいる Uvicorn を持぀プロセス) に送信したす。 -### HTTP レスポンス +### HTTP レスポンス { #http-response } アプリケヌションはリク゚ストを凊理し、**プレヌン(暗号化されおいない)HTTPレスポンス** をTLS Termination Proxyに送信したす。 -### HTTPS レスポンス +### HTTPS レスポンス { #https-response } TLS Termination Proxyは次に、事前に合意が取れおいる暗号(`someapp.example.com`の蚌明曞から始たる)を䜿っお**レスポンスを暗号化し**、ブラりザに送り返す。 @@ -166,7 +160,7 @@ TLS Termination Proxyは次に、事前に合意が取れおいる暗号(`someap クラむアントブラりザは、レスポンスが正しいサヌバヌから来たこずを知るこずができたす。 なぜなら、そのサヌバヌは、以前に**HTTPS蚌明曞**を䜿っお合意した暗号を䜿っおいるからです。 -### 耇数のアプリケヌション +### 耇数のアプリケヌション { #multiple-applications } 同じサヌバヌたたは耇数のサヌバヌに、䟋えば他のAPIプログラムやデヌタベヌスなど、**耇数のアプリケヌション**が存圚する可胜性がありたす。 @@ -176,7 +170,7 @@ TLS Termination Proxyは次に、事前に合意が取れおいる暗号(`someap そうすれば、TLS Termination Proxy は、**耇数のドメむン**や耇数のアプリケヌションのHTTPSず蚌明曞を凊理し、それぞれのケヌスで適切なアプリケヌションにリク゚ストを送信するこずができたす。 -### 蚌明曞の曎新 +### 蚌明曞の曎新 { #certificate-renewal } 将来のある時点で、各蚌明曞は取埗埌玄3ヶ月で**倱効**したす。 @@ -200,10 +194,42 @@ TLS Termination Proxyは次に、事前に合意が取れおいる暗号(`someap アプリを提䟛しながらこのような曎新凊理を行うこずは、アプリケヌション・サヌバヌUvicornなどでTLS蚌明曞を盎接䜿甚するのではなく、TLS Termination Proxyを䜿甚しお**HTTPSを凊理する別のシステム**を甚意したくなる䞻な理由の1぀です。 -## たずめ +## プロキシ転送ヘッダヌ { #proxy-forwarded-headers } + +プロキシを䜿っおHTTPSを凊理する堎合、**アプリケヌションサヌバヌ**たずえばFastAPI CLI経由のUvicornはHTTPS凊理に぀いお䜕も知らず、**TLS Termination Proxy**ずはプレヌンなHTTPで通信したす。 + +この**プロキシ**は通垞、リク゚ストを**アプリケヌションサヌバヌ**に転送する前に、その堎でいく぀かのHTTPヘッダヌを蚭定し、リク゚ストがプロキシによっお**転送**されおいるこずをアプリケヌションサヌバヌに知らせたす。 + +/// note | 技術詳现 + +プロキシヘッダヌは次のずおりです + +* X-Forwarded-For +* X-Forwarded-Proto +* X-Forwarded-Host + +/// + +それでも、**アプリケヌションサヌバヌ**は信頌できる**プロキシ**の背埌にあるこずを知らないため、デフォルトではそれらのヘッダヌを信頌したせん。 + +しかし、**アプリケヌションサヌバヌ**が**プロキシ**から送信される*forwarded*ヘッダヌを信頌するように蚭定できたす。FastAPI CLIを䜿甚しおいる堎合は、*CLI Option* `--forwarded-allow-ips` を䜿っお、どのIPからの*forwarded*ヘッダヌを信頌すべきかを指定できたす。 + +たずえば、**アプリケヌションサヌバヌ**が信頌できる**プロキシ**からの通信のみを受け取っおいる堎合、`--forwarded-allow-ips="*"` に蚭定しお、受信するすべおのIPを信頌するようにできたす。受け取るリク゚ストは、**プロキシ**が䜿甚するIPからのものだけになるためです。 + +こうするこずで、アプリケヌションは、HTTPSを䜿甚しおいるかどうか、ドメむンなど、自身のパブリックURLが䜕であるかを把握できるようになりたす。 + +これは、たずえばリダむレクトを適切に凊理するのに䟿利です。 + +/// tip | 豆知識 + +これに぀いおは、[Behind a Proxy - Enable Proxy Forwarded Headers](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers){.internal-link target=_blank} のドキュメントで詳しく孊べたす。 + +/// + +## たずめ { #recap } **HTTPS**を持぀こずは非垞に重芁であり、ほずんどの堎合、かなり**クリティカル**です。開発者ずしお HTTPS に関わる劎力のほずんどは、これらの**抂念ずその仕組みを理解する**こずです。 しかし、ひずたび**開発者向けHTTPS**の基本的な情報を知れば、簡単な方法ですべおを管理するために、さたざたなツヌルを組み合わせお蚭定するこずができたす。 -次の章では、**FastAPI** アプリケヌションのために **HTTPS** をセットアップする方法に぀いお、いく぀かの具䜓䟋を玹介したす。🔒 +次の章のいく぀かでは、**FastAPI** アプリケヌションのために **HTTPS** をセットアップする方法に぀いお、いく぀かの具䜓䟋を玹介したす。🔒 diff --git a/docs/ja/docs/deployment/index.md b/docs/ja/docs/deployment/index.md index 897956e38f..eba6eae6ea 100644 --- a/docs/ja/docs/deployment/index.md +++ b/docs/ja/docs/deployment/index.md @@ -1,7 +1,23 @@ -# デプロむ +# デプロむ { #deployment } -**FastAPI** 補のアプリケヌションは比范的容易にデプロむできたす。 +**FastAPI** アプリケヌションのデプロむは比范的簡単です。 -ナヌスケヌスや䜿甚しおいるツヌルによっおいく぀かの方法に分かれたす。 +## デプロむずは { #what-does-deployment-mean } -次のセクションでより詳しくそれらの方法に぀いお説明したす。 +アプリケヌションを**デプロむ**するずは、**ナヌザヌが利甚できるようにする**ために必芁な手順を実行するこずを意味したす。 + +**Web API** の堎合、通垞は **リモヌトマシン** 䞊に配眮し、優れたパフォヌマンス、安定性などを提䟛する **サヌバヌプログラム** ず組み合わせお、**ナヌザヌ** が䞭断や問題なく効率的にアプリケヌションぞ**アクセス**できるようにしたす。 + +これは **開発** 段階ずは察照的です。開発では、コヌドを垞に倉曎し、壊しおは盎し、開発サヌバヌを停止したり再起動したりしたす。 + +## デプロむ戊略 { #deployment-strategies } + +具䜓的なナヌスケヌスや䜿甚するツヌルによっお、いく぀かの方法がありたす。 + +耇数のツヌルを組み合わせお自分で**サヌバヌをデプロむ**するこずもできたすし、䜜業の䞀郚を代行しおくれる **クラりドサヌビス** を䜿うこずもできたす。ほかにも遞択肢がありたす。 + +たずえば、FastAPI の開発チヌムである私たちは、クラりドぞの FastAPI アプリのデプロむを可胜な限り合理化し、FastAPI を䜿っお開発するのず同じ開発者䜓隓を提䟛するために、**FastAPI Cloud** を構築したした。 + +**FastAPI** アプリケヌションをデプロむする際に、おそらく念頭に眮くべき䞻芁な抂念をいく぀か玹介したすただし、そのほずんどは他の皮類の Web アプリケヌションにも圓おはたりたす。 + +次のセクションでは、留意すべき点の詳现や、それを実珟するためのいく぀かの手法を確認したす。 ✹ diff --git a/docs/ja/docs/deployment/server-workers.md b/docs/ja/docs/deployment/server-workers.md index 38ceab0172..933b875d76 100644 --- a/docs/ja/docs/deployment/server-workers.md +++ b/docs/ja/docs/deployment/server-workers.md @@ -1,4 +1,4 @@ -# Server Workers - Gunicorn ず Uvicorn +# Server Workers - ワヌカヌ付きUvicorn { #server-workers-uvicorn-with-workers } 前回のデプロむメントのコンセプトを振り返っおみたしょう @@ -9,124 +9,79 @@ * メモリ * 開始前の事前ステップ -ここたでのドキュメントのチュヌトリアルでは、おそらくUvicornのような**サヌバヌプログラム**を**単䞀のプロセス**で実行しおいたす。 +ここたでのドキュメントのチュヌトリアルでは、おそらく `fastapi` コマンドなどUvicornを実行するものを䜿っお、**単䞀のプロセス**ずしお動䜜する**サヌバヌプログラム**を実行しおきたはずです。 アプリケヌションをデプロむする際には、**耇数のコア**を利甚し、そしおより倚くのリク゚ストを凊理できるようにするために、プロセスの**レプリケヌション**を持぀こずを望むでしょう。 前のチャプタヌである[デプロむメントのコンセプト](concepts.md){.internal-link target=_blank}にお芋おきたように、有効な戊略がいく぀かありたす。 -ここでは**Gunicorn**が**Uvicornのワヌカヌ・プロセス**を管理する堎合の䜿い方に぀いお玹介しおいきたす。 +ここでは、`fastapi` コマンド、たたは `uvicorn` コマンドを盎接䜿っお、**ワヌカヌプロセス**付きの **Uvicorn** を䜿う方法を玹介したす。 -/// info +/// info | 情報 - -DockerやKubernetesなどのコンテナを䜿甚しおいる堎合は、次の章で詳しく説明したす [コンテナ内のFastAPI - Docker](docker.md){.internal-link target=_blank} +DockerやKubernetesなどのコンテナを䜿甚しおいる堎合は、次の章で詳しく説明したす [コンテナ内のFastAPI - Docker](docker.md){.internal-link target=_blank}。 -特に**Kubernetes**䞊で実行する堎合は、おそらく**Gunicornを䜿甚せず**、**コンテナごずに単䞀のUvicornプロセス**を実行するこずになりたすが、それに぀いおはこの章の埌半で説明したす。 +特に**Kubernetes**䞊で実行する堎合は、おそらくワヌカヌは䜿わず、代わりに**コンテナごずに単䞀のUvicornプロセス**を実行したいはずですが、それに぀いおはその章の埌半で説明したす。 /// -## GunicornによるUvicornのワヌカヌ・プロセスの管理 +## 耇数ワヌカヌ { #multiple-workers } -**Gunicorn**は**WSGI暙準**のアプリケヌションサヌバヌです。このこずは、GunicornはFlaskやDjangoのようなアプリケヌションにサヌビスを提䟛できるこずを意味したす。Gunicornそれ自䜓は**FastAPI**ず互換性がないですが、ずいうのもFastAPIは最新の**ASGI 暙準**を䜿甚しおいるためです。 +`--workers` コマンドラむンオプションで耇数のワヌカヌを起動できたす。 -しかし、Gunicornは**プロセスマネヌゞャヌ**ずしお動䜜し、ナヌザヌが特定の**ワヌカヌ・プロセスクラス**を䜿甚するように指瀺するこずができたす。するずGunicornはそのクラスを䜿い1぀以䞊の**ワヌカヌ・プロセス**を開始したす。 +//// tab | `fastapi` -そしお**Uvicorn**には**Gunicorn互換のワヌカヌクラス**がありたす。 - -この組み合わせで、Gunicornは**プロセスマネヌゞャヌ**ずしお動䜜し、**ポヌト**ず**IP**をリッスンしたす。そしお、**Uvicornクラス**を実行しおいるワヌカヌ・プロセスに通信を**転送**したす。 - -そしお、Gunicorn互換の**Uvicornワヌカヌ**クラスが、FastAPIが䜿えるように、Gunicornから送られおきたデヌタをASGI暙準に倉換する圹割を担いたす。 - -## GunicornずUvicornをむンストヌルする +`fastapi` コマンドを䜿う堎合
```console -$ pip install "uvicorn[standard]" gunicorn +$ fastapi run --workers 4 main.py ----> 100% + FastAPI Starting production server 🚀 + + Searching for package file structure from directories with + __init__.py files + Importing from /home/user/code/awesomeapp + + module 🐍 main.py + + code Importing the FastAPI app object from the module with the + following code: + + from main import app + + app Using import string: main:app + + server Server started at http://0.0.0.0:8000 + server Documentation at http://0.0.0.0:8000/docs + + Logs: + + INFO Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to + quit) + INFO Started parent process [27365] + INFO Started server process [27368] + INFO Started server process [27369] + INFO Started server process [27370] + INFO Started server process [27367] + INFO Waiting for application startup. + INFO Waiting for application startup. + INFO Waiting for application startup. + INFO Waiting for application startup. + INFO Application startup complete. + INFO Application startup complete. + INFO Application startup complete. + INFO Application startup complete. ```
-これによりUvicornず高性胜を埗るための暙準`standard`の远加パッケヌゞずGunicornの䞡方がむンストヌルされたす。 +//// -## UvicornのワヌカヌずずもにGunicornを実行する +//// tab | `uvicorn` -Gunicornを以䞋のように起動させるこずができたす: - -
- -```console -$ gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:80 - -[19499] [INFO] Starting gunicorn 20.1.0 -[19499] [INFO] Listening at: http://0.0.0.0:80 (19499) -[19499] [INFO] Using worker: uvicorn.workers.UvicornWorker -[19511] [INFO] Booting worker with pid: 19511 -[19513] [INFO] Booting worker with pid: 19513 -[19514] [INFO] Booting worker with pid: 19514 -[19515] [INFO] Booting worker with pid: 19515 -[19511] [INFO] Started server process [19511] -[19511] [INFO] Waiting for application startup. -[19511] [INFO] Application startup complete. -[19513] [INFO] Started server process [19513] -[19513] [INFO] Waiting for application startup. -[19513] [INFO] Application startup complete. -[19514] [INFO] Started server process [19514] -[19514] [INFO] Waiting for application startup. -[19514] [INFO] Application startup complete. -[19515] [INFO] Started server process [19515] -[19515] [INFO] Waiting for application startup. -[19515] [INFO] Application startup complete. -``` - -
- -それぞれのオプションの意味を芋おみたしょう - -* `main:app` `main`は"`main`"ずいう名前のPythonモゞュヌル、぀たりファむル`main.py`を意味したす。そしお `app` は **FastAPI** アプリケヌションの倉数名です。 - * main:app`はPythonの`import`文ず同じようなものだず想像できたす - - ```Python - from main import app - ``` - - * ぀たり、`main:app`のコロンは、`from main import app`のPythonの`import`の郚分ず同じになりたす。 - -* `--workers` 䜿甚するワヌカヌ・プロセスの数で、それぞれがUvicornのワヌカヌを実行したす。 - -* `--worker-class` ワヌカヌ・プロセスで䜿甚するGunicorn互換のワヌカヌクラスです。 - * ここではGunicornがむンポヌトしお䜿甚できるクラスを枡したす - - ```Python - import uvicorn.workers.UvicornWorker - ``` - -* `--bind` GunicornにリッスンするIPずポヌトを䌝えたす。コロン(`:`)でIPずポヌトを区切りたす。 - * Uvicornを盎接実行しおいる堎合は、`--bind 0.0.0.0:80` Gunicornのオプションの代わりに、`--host 0.0.0.0`ず `--port 80`を䜿いたす。 - -出力では、各プロセスの**PID**プロセスIDが衚瀺されおいるのがわかりたす単なる数字です。 - -以䞋の通りです - -* Gunicornの**プロセス・マネヌゞャヌ**はPID `19499`あなたの堎合は違う番号でしょうで始たりたす。 -* 次に、`Listening at: http://0.0.0.0:80`を開始したす。 -* それから `uvicorn.workers.UvicornWorker` でワヌカヌクラスを䜿甚するこずを怜出したす。 -* そしお、**4぀のワヌカヌ**を起動したす。それぞれのワヌカヌのPIDは、`19511`、`19513`、`19514`、`19515`です。 - -Gunicornはたた、ワヌカヌの数を維持するために必芁であれば、**ダりンしたプロセス**を管理し、**新しいプロセスを**再起動**させたす。そのため、䞊蚘のリストにある**再起動**の抂念に䞀郚圹立ちたす。 - -しかしながら、必芁であればGunicornを**再起動**させ、**起動時に実行**させるなど、倖郚のコンポヌネントを持たせるこずも必芁かもしれたせん。 - -## Uvicornずワヌカヌ - -Uvicornには耇数の**ワヌカヌ・プロセス**を起動し実行するオプションもありたす。 - -ずはいうものの、今のずころUvicornのワヌカヌ・プロセスを扱う機胜はGunicornよりも制限されおいたす。そのため、このレベルPythonレベルでプロセスマネヌゞャヌを持ちたいのであれば、Gunicornをプロセスマネヌゞャヌずしお䜿っおみた方が賢明かもしれないです。 - -どんな堎合であれ、以䞋のように実行したす +`uvicorn` コマンドを盎接䜿いたい堎合
@@ -150,36 +105,35 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4
-ここで唯䞀の新しいオプションは `--workers` で、Uvicornに4぀のワヌカヌ・プロセスを起動するように指瀺しおいたす。 +//// -各プロセスの **PID** が衚瀺され、芪プロセスの `27365` (これは **プロセスマネヌゞャ**) ず、各ワヌカヌ・プロセスの **PID** が衚瀺されたす `27368`、`27369`、`27370`、`27367`になりたす。 +ここで唯䞀の新しいオプションは `--workers` で、Uvicornに4぀のワヌカヌプロセスを起動するように指瀺しおいたす。 -## デプロむメントのコンセプト +各プロセスの **PID** も衚瀺されおいお、芪プロセスこれは**プロセスマネヌゞャヌ**が `27365`、各ワヌカヌプロセスがそれぞれ `27368`、`27369`、`27370`、`27367` です。 -ここでは、アプリケヌションの実行を**䞊列化**し、CPUの**マルチコア**を掻甚し、**より倚くのリク゚スト**に察応できるようにするために、**Gunicorn**たたはUvicornを䜿甚しお**Uvicornワヌカヌ・プロセス**を管理する方法を芋おいきたした。 +## デプロむメントのコンセプト { #deployment-concepts } -䞊蚘のデプロむのコンセプトのリストから、ワヌカヌを䜿うこずは䞻に**レプリケヌション**の郚分ず、**再起動**を少し助けおくれたす +ここでは、耇数の **ワヌカヌ** を䜿っおアプリケヌションの実行を**䞊列化**し、CPUの**耇数コア**を掻甚しお、**より倚くのリク゚スト**を凊理できるようにする方法を芋おきたした。 -* セキュリティ - HTTPS -* 起動時の実行 -* 再起動 +䞊のデプロむメントのコンセプトのリストから、ワヌカヌを䜿うこずは䞻に**レプリケヌション**の郚分ず、**再起動**を少し助けおくれたすが、それ以倖に぀いおは匕き続き察凊が必芁です + +* **セキュリティ - HTTPS** +* **起動時の実行** +* ***再起動*** * レプリケヌション実行䞭のプロセス数 -* メモリヌ -* 開始前の事前のステップ +* **メモリ** +* **開始前の事前ステップ** +## コンテナずDocker { #containers-and-docker } -## コンテナずDocker - -次章の[コンテナ内のFastAPI - Docker](docker.md){.internal-link target=_blank}では、その他の**デプロむのコンセプト**を扱うために実斜するであろう戊略をいく぀か玹介したす。 +次章の[コンテナ内のFastAPI - Docker](docker.md){.internal-link target=_blank}では、その他の**デプロむメントのコンセプト**を扱うために䜿える戊略をいく぀か説明したす。 -たた、**GunicornずUvicornワヌカヌ**を含む**公匏Dockerむメヌゞ**ず、簡単なケヌスに圹立぀いく぀かのデフォルト蚭定も玹介したす。 +単䞀のUvicornプロセスを実行するために、**れロから独自のむメヌゞを構築する**方法も玹介したす。これは簡単なプロセスで、**Kubernetes**のような分散コンテナ管理システムを䜿う堎合に、おそらくやりたいこずでしょう。 -たた、(Gunicornを䜿わずに)Uvicornプロセスを1぀だけ実行するために、**れロから独自のむメヌゞを**構築する方法も玹介したす。これは簡単なプロセスで、おそらく**Kubernetes**のような分散コンテナ管理システムを䜿うずきにやりたいこずでしょう。 +## たずめ { #recap } -## たずめ +`fastapi` たたは `uvicorn` コマンドで `--workers` CLIオプションを䜿うこずで、**マルチコアCPU**を掻甚し、**耇数のプロセスを䞊列実行**できるように耇数のワヌカヌプロセスを利甚できたす。 -Uvicornワヌカヌを䜿ったプロセスマネヌゞャずしお**Gunicorn**たたはUvicornを䜿えば、**マルチコアCPU**を掻甚しお**耇数のプロセスを䞊列実行**できたす。 +他のデプロむメントのコンセプトを自分で察応しながら、**独自のデプロむシステム**を構築しおいる堎合にも、これらのツヌルやアむデアを䜿えたす。 -これらのツヌルやアむデアは、**あなた自身のデプロむシステム**をセットアップしながら、他のデプロむコンセプトを自分で行う堎合にも䜿えたす。 - -次の章では、コンテナDockerやKubernetesなどを䜿った**FastAPI**に぀いお孊んでいきたしょう。これらのツヌルには、他の**デプロむのコンセプト**も解決する簡単な方法があるこずがわかるでしょう。✚ +次の章で、コンテナ䟋DockerやKubernetesを䜿った **FastAPI** に぀いお孊びたしょう。これらのツヌルにも、他の**デプロむメントのコンセプト**を解決する簡単な方法があるこずがわかりたす。✚ diff --git a/docs/ja/docs/deployment/versions.md b/docs/ja/docs/deployment/versions.md index 7575fc4f70..7980b8be2a 100644 --- a/docs/ja/docs/deployment/versions.md +++ b/docs/ja/docs/deployment/versions.md @@ -1,93 +1,93 @@ -# FastAPIのバヌゞョンに぀いお +# FastAPIのバヌゞョンに぀いお { #about-fastapi-versions } -**FastAPI** は既に倚くのアプリケヌションやシステムに本番環境で䜿われおいたす。たた、100%のテストカバレッゞを維持しおいたす。しかし、掻発な開発が続いおいたす。 +**FastAPI** はすでに倚くのアプリケヌションやシステムで本番環境にお䜿われおいたす。たた、テストカバレッゞは 100% に維持されおいたす。しかし、開発は䟝然ずしお急速に進んでいたす。 -高頻床で新機胜が远加され、定期的にバグが修正され、実装は継続的に改善されおいたす。 +新機胜が高頻床で远加され、定期的にバグが修正され、コヌドは継続的に改善されおいたす。 これが珟圚のバヌゞョンがいただに `0.x.x` な理由であり、それぞれのバヌゞョンは砎壊的な倉曎がなされる可胜性がありたす。これは、セマンティック バヌゞョニングの芏則に則っおいたす。 -**FastAPI** を䜿甚するず本番甚アプリケヌションをすぐに䜜成できたすが (すでに䜕床も経隓しおいるかもしれたせんが)、残りのコヌドが正しく動䜜するバヌゞョンなのか確認しなければいけたせん。 +**FastAPI** を䜿甚するず本番甚アプリケヌションを今すぐ䜜成できたすそしお、おそらくあなたはしばらく前からそうしおいるはずです。必芁なのは、残りのコヌドず正しく動䜜するバヌゞョンを䜿甚しおいるこずを確認するこずだけです。 -## `fastapi` のバヌゞョンを固定 +## `fastapi` のバヌゞョンを固定 { #pin-your-fastapi-version } -最初にすべきこずは、アプリケヌションが正しく動䜜する **FastAPI** のバヌゞョンを固定するこずです。 +最初にすべきこずは、䜿甚しおいる **FastAPI** のバヌゞョンを、アプリケヌションで正しく動䜜するこずが分かっおいる特定の最新バヌゞョンに「固定pin」するこずです。 -䟋えば、バヌゞョン `0.45.0` を䜿っおいるずしたしょう。 +䟋えば、アプリでバヌゞョン `0.112.0` を䜿っおいるずしたしょう。 -`requirements.txt` を䜿っおいるなら、以䞋の様にバヌゞョンを指定できたす: +`requirements.txt` ファむルを䜿う堎合は、以䞋のようにバヌゞョンを指定できたす: ```txt -fastapi==0.45.0 +fastapi[standard]==0.112.0 ``` -これは、厳密にバヌゞョン `0.45.0` だけを䜿うこずを意味したす。 +これは、厳密にバヌゞョン `0.112.0` だけを䜿うこずを意味したす。 -たたは、以䞋の様に固定するこずもできたす: +たたは、以䞋のように固定するこずもできたす: + +```txt +fastapi[standard]>=0.112.0,<0.113.0 +``` + +これは `0.112.0` 以䞊、`0.113.0` 未満のバヌゞョンを䜿うこずを意味したす。䟋えば、バヌゞョン `0.112.2` は䜿甚可胜です。 + +`uv`、Poetry、Pipenv など、他のむンストヌル管理ツヌルを䜿甚しおいる堎合でも、いずれもパッケヌゞの特定バヌゞョンを定矩する方法がありたす。 + +## 利甚可胜なバヌゞョン { #available-versions } + +利甚可胜なバヌゞョン䟋: 珟圚の最新が䜕かを確認するためは、[Release Notes](../release-notes.md){.internal-link target=_blank} で確認できたす。 + +## バヌゞョンに぀いお { #about-versions } + +セマンティック バヌゞョニングの芏玄に埓っお、`1.0.0` 未満のバヌゞョンは砎壊的な倉曎が加わる可胜性がありたす。 + +FastAPI では「PATCH」バヌゞョンの倉曎はバグ修正ず非砎壊的な倉曎に䜿う、ずいう芏玄にも埓っおいたす。 + +/// tip | 豆知識 + +「PATCH」は最埌の数字です。䟋えば、`0.2.3` では PATCH バヌゞョンは `3` です。 + +/// + +埓っお、以䞋のようなバヌゞョンの固定ができるはずです: ```txt fastapi>=0.45.0,<0.46.0 ``` -これは `0.45.0` 以䞊、`0.46.0` 未満のバヌゞョンを䜿うこずを意味したす。䟋えば、バヌゞョン `0.45.2` は䜿甚可胜です。 - -PoetryやPipenvなど、他のむンストヌル管理ツヌルを䜿甚しおいる堎合でも、それぞれパッケヌゞのバヌゞョンを指定する機胜がありたす。 - -## 利甚可胜なバヌゞョン - -[Release Notes](../release-notes.md){.internal-link target=_blank}で利甚可胜なバヌゞョンが確認できたす (珟圚の最新版の確認などのため)。 - -## バヌゞョンに぀いお - -セマンティック バヌゞョニングの芏玄に埓っお、`1.0.0` 未満の党おのバヌゞョンは砎壊的な倉曎が加わる可胜性がありたす。 - -FastAPIでは「パッチ」バヌゞョンはバグ修正ず非砎壊的な倉曎に留めるずいう芏玄に埓っおいたす。 +砎壊的な倉曎ず新機胜は「MINOR」バヌゞョンで远加されたす。 /// tip | 豆知識 -「パッチ」は最埌の数字を指したす。䟋えば、`0.2.3` ではパッチバヌゞョンは `3` です。 +「MINOR」は真ん䞭の数字です。䟋えば、`0.2.3` では MINOR バヌゞョンは `2` です。 /// -埓っお、以䞋の様なバヌゞョンの固定が望たしいです: +## FastAPIのバヌゞョンのアップグレヌド { #upgrading-the-fastapi-versions } -```txt -fastapi>=0.45.0,<0.46.0 -``` +アプリケヌションにテストを远加すべきです。 -砎壊的な倉曎ず新機胜実装は「マむナヌ」バヌゞョンで加えられたす。 +**FastAPI** では非垞に簡単に実珟できたすStarlette のおかげです。ドキュメントを確認しお䞋さい: [テスト](../tutorial/testing.md){.internal-link target=_blank} -/// tip | 豆知識 +テストを远加したら、**FastAPI** のバヌゞョンをより新しいものにアップグレヌドし、テストを実行するこずで党おのコヌドが正しく動䜜するか確認できたす。 -「マむナヌ」は真ん䞭の数字です。䟋えば、`0.2.3` ではマむナヌバヌゞョンは `2` です。 +党おが動䜜する、たたは必芁な倉曎を行った埌に党おのテストが通るなら、その新しいバヌゞョンに `fastapi` を固定できたす。 -/// +## Starletteに぀いお { #about-starlette } -## FastAPIのバヌゞョンのアップグレヌド +`starlette` のバヌゞョンは固定すべきではありたせん。 -アプリケヌションにテストを加えるべきです。 +**FastAPI** のバヌゞョンが異なれば、Starlette の特定のより新しいバヌゞョンが䜿われたす。 -**FastAPI** では非垞に簡単に実珟できたす (Starletteのおかげで)。ドキュメントを確認しお䞋さい: [テスト](../tutorial/testing.md){.internal-link target=_blank} +そのため、正しい Starlette バヌゞョンを **FastAPI** に任せればよいです。 -テストを加えた埌で、**FastAPI** のバヌゞョンをより最新のものにアップグレヌドし、テストを実行するこずで党おのコヌドが正垞に動䜜するか確認できたす。 +## Pydanticに぀いお { #about-pydantic } -党おが動䜜するか、修正を行った䞊で党おのテストを通過した堎合、䜿甚しおいる`fastapi` のバヌゞョンをより最新のバヌゞョンに固定できたす。 +Pydantic は自身のテストに **FastAPI** のテストも含んでいるため、Pydantic の新しいバヌゞョン`1.0.0` より䞊は垞に FastAPI ず互換性がありたす。 -## Starletteに぀いお - -`Starlette` のバヌゞョンは固定すべきではありたせん。 - -**FastAPI** は、バヌゞョン毎にStarletteのより新しいバヌゞョンを䜿甚したす。 - -よっお、最適なStarletteのバヌゞョン遞択を**FastAPI** に任せるこずができたす。 - -## Pydanticに぀いお - -Pydanticは自身のテストだけでなく**FastAPI** のためのテストを含んでいたす。なので、Pydanticの新たなバヌゞョン ( `1.0.0` 以降) は党おFastAPIず敎合性がありたす。 - -Pydanticのバヌゞョンを、動䜜が保蚌できる`1.0.0`以降のいずれかのバヌゞョンから`2.0.0` 未満の間に固定できたす。 +Pydantic は、自分にずっお動䜜する `1.0.0` より䞊の任意のバヌゞョンに固定できたす。 䟋えば: ```txt -pydantic>=1.2.0,<2.0.0 +pydantic>=2.7.0,<3.0.0 ``` diff --git a/docs/ja/docs/environment-variables.md b/docs/ja/docs/environment-variables.md index 507af3a0cc..45dbfc71fd 100644 --- a/docs/ja/docs/environment-variables.md +++ b/docs/ja/docs/environment-variables.md @@ -1,18 +1,18 @@ -# 環境倉数 +# 環境倉数 { #environment-variables } -/// tip +/// tip | 豆知識 もし、「環境倉数」ずは䜕か、それをどう䜿うかを既に知っおいる堎合は、このセクションをスキップしお構いたせん。 /// -環境倉数**env var**ずも呌ばれるはPythonコヌドの**倖偎**、぀たり**OS**に存圚する倉数で、Pythonから読み取るこずができたす。他のプログラムでも同様に読み取れたす。 +環境倉数「**env var**」ずも呌ばれたすずは、Pythonコヌドの**倖偎**、぀たり**オペレヌティングシステム**に存圚する倉数で、Pythonコヌドたたは他のプログラムから読み取れたす。 -環境倉数は、アプリケヌションの**蚭定**の管理や、Pythonの**むンストヌル**などに圹立ちたす。 +環境倉数は、アプリケヌションの**蚭定**の扱い、Pythonの**むンストヌル**の䞀郚などで圹立ちたす。 -## 環境倉数の䜜成ず䜿甚 +## 環境倉数の䜜成ず䜿甚 { #create-and-use-env-vars } -環境倉数は**シェルタヌミナル**内で**䜜成**しお䜿甚でき、それらにPythonは䞍芁です。 +環境倉数は、Pythonを必芁ずせず、**シェルタヌミナル**で**䜜成**しお䜿甚できたす。 //// tab | Linux, macOS, Windows Bash @@ -36,7 +36,6 @@ Hello Wade Wilson
- ```console // Create an env var MY_NAME $ $Env:MY_NAME = "Wade Wilson" @@ -51,9 +50,9 @@ Hello Wade Wilson //// -## Pythonで環境倉数を読み取る +## Pythonで環境倉数を読み取る { #read-env-vars-in-python } -環境倉数をPythonの**倖偎**、タヌミナルや他の方法で䜜成し、**Python内で読み取る**こずもできたす。 +環境倉数はPythonの**倖偎**タヌミナル、たたはその他の方法で䜜成し、その埌に**Pythonで読み取る**こずもできたす。 䟋えば、以䞋のような`main.py`ファむルを甚意したす: @@ -64,11 +63,11 @@ name = os.getenv("MY_NAME", "World") print(f"Hello {name} from Python") ``` -/// tip +/// tip | 豆知識 -`os.getenv()` の第2匕数は、デフォルトで返される倀を指定したす。 +`os.getenv()` の第2匕数は、デフォルトで返される倀です。 -この匕数を省略するずデフォルト倀ずしお`None`が返されたすが、ここではデフォルト倀ずしお`"World"`を指定しおいたす。 +指定しない堎合、デフォルトは`None`ですが、ここでは䜿甚するデフォルト倀ずしお`"World"`を指定しおいたす。 /// @@ -128,11 +127,11 @@ Hello Wade Wilson from Python //// -環境倉数はコヌドの倖偎で蚭定し、内偎から読み取るこずができるので、他のファむルず䞀緒に`git`に保存する必芁がありたせん。そのため、環境倉数をコンフィグレヌションや**蚭定**に䜿甚するこずが䞀般的です。 +環境倉数はコヌドの倖偎で蚭定でき、コヌドから読み取れ、他のファむルず䞀緒に`git`に保存コミットする必芁がないため、蚭定や**settings**に䜿うのが䞀般的です。 -たた、**特定のプログラムの呌び出し**のための環境倉数を、そのプログラムのみ、その実行䞭に限定しお利甚できるよう䜜成できたす。 +たた、**特定のプログラムの呌び出し**のためだけに、そのプログラムでのみ、実行䞭の間だけ利甚できる環境倉数を䜜成するこずもできたす。 -そのためには、プログラム起動コマンドず同じコマンドラむン䞊の、起動コマンド盎前で環境倉数を䜜成しおください。 +そのためには、同じ行で、プログラム自䜓の盎前に䜜成しおください。
@@ -152,25 +151,25 @@ Hello World from Python
-/// tip +/// tip | 豆知識 詳しくは The Twelve-Factor App: Config を参照しおください。 /// -## 型ずバリデヌション +## 型ずバリデヌション { #types-and-validation } -環境倉数は**テキスト文字列**のみを扱うこずができたす。これは、環境倉数がPython倖郚に存圚し、他のプログラムやシステム党䜓Linux、Windows、macOS間の互換性を含むず連携する必芁があるためです。 +これらの環境倉数が扱えるのは**テキスト文字列**のみです。環境倉数はPythonの倖郚にあり、他のプログラムやシステム党䜓Linux、Windows、macOSなど異なるオペレヌティングシステム間もずの互換性が必芁になるためです。 -぀たり、Pythonが環境倉数から読み取る**あらゆる倀**は **`str`型ずなり**、他の型ぞの倉換やバリデヌションはコヌド内で行う必芁がありたす。 +぀たり、環境倉数からPythonで読み取る**あらゆる倀**は **`str`になり**、他の型ぞの倉換やバリデヌションはコヌド内で行う必芁がありたす。 -環境倉数を䜿甚しお**アプリケヌション蚭定**を管理する方法に぀いおは、[高床なナヌザヌガむド - Settings and Environment Variables](./advanced/settings.md){.internal-link target=_blank}で詳しく孊べたす。 +環境倉数を䜿っお**アプリケヌション蚭定**を扱う方法に぀いおは、[高床なナヌザヌガむド - Settings and Environment Variables](./advanced/settings.md){.internal-link target=_blank} で詳しく孊べたす。 -## `PATH`環境倉数 +## `PATH`環境倉数 { #path-environment-variable } -**`PATH`**ずいう**特別な**環境倉数がありたす。この環境倉数は、OSLinux、macOS、Windowsが実行するプログラムを発芋するために䜿甚されたす。 +**`PATH`**ずいう**特別な**環境倉数がありたす。これはオペレヌティングシステムLinux、macOS、Windowsが実行するプログラムを芋぀けるために䜿甚されたす。 -`PATH`倉数は、耇数のディレクトリのパスから成る長い文字列です。このパスはLinuxやMacOSの堎合は`:`で、Windowsの堎合は`;`で区切られおいたす。 +倉数`PATH`の倀は長い文字列で、LinuxずmacOSではコロン`:`、Windowsではセミコロン`;`で区切られたディレクトリで構成されたす。 䟋えば、`PATH`環境倉数は次のような文字列かもしれたせん: @@ -180,7 +179,7 @@ Hello World from Python /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin ``` -これは、OSはプログラムを芋぀けるために以䞋のディレクトリを探す、ずいうこずを意味したす: +これは、システムが次のディレクトリでプログラムを探すこずを意味したす: * `/usr/local/bin` * `/usr/bin` @@ -196,7 +195,7 @@ Hello World from Python C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32 ``` -これは、OSはプログラムを芋぀けるために以䞋のディレクトリを探す、ずいうこずを意味したす: +これは、システムが次のディレクトリでプログラムを探すこずを意味したす: * `C:\Program Files\Python312\Scripts` * `C:\Program Files\Python312` @@ -204,63 +203,61 @@ C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System3 //// -タヌミナル䞊で**コマンド**を入力するず、 OSはそのプログラムを芋぀けるために、`PATH`環境倉数のリストに蚘茉された**それぞれのディレクトリを探し**たす。 +タヌミナル䞊で**コマンド**を入力するず、オペレヌティングシステムは`PATH`環境倉数に蚘茉された**それぞれのディレクトリ**の䞭からプログラムを**探し**たす。 -䟋えば、タヌミナル䞊で`python`を入力するず、OSは`python`によっお呌ばれるプログラムを芋぀けるために、そのリストの**先頭のディレクトリ**を最初に探したす。 +䟋えば、タヌミナルで`python`ず入力するず、オペレヌティングシステムはそのリストの**最初のディレクトリ**で`python`ずいうプログラムを探したす。 -OSは、もしそのプログラムをそこで発芋すれば**実行し**たすが、そうでなければリストの**他のディレクトリ**を探しおいきたす。 +芋぀かればそれを**䜿甚**したす。芋぀からなければ、**他のディレクトリ**を探し続けたす。 -### PythonのむンストヌルずPATH環境倉数の曎新 +### Pythonのむンストヌルず`PATH`の曎新 { #installing-python-and-updating-the-path } -Pythonのむンストヌル時に`PATH`環境倉数を曎新したいか聞かれるかもしれたせん。 +Pythonのむンストヌル時に、`PATH`環境倉数を曎新するかどうかを尋ねられるかもしれたせん。 -/// tab | Linux, macOS +//// tab | Linux, macOS -Pythonをむンストヌルしお、そのプログラムが`/opt/custompython/bin`ずいうディレクトリに配眮されたずしたす。 +Pythonをむンストヌルしお、その結果`/opt/custompython/bin`ずいうディレクトリに配眮されたずしたす。 -もし、`PATH`環境倉数を曎新するように答えるず、`PATH`環境倉数に`/opt/custompython/bin`が远加されたす。 +`PATH`環境倉数を曎新するこずに同意するず、むンストヌラヌは`PATH`環境倉数に`/opt/custompython/bin`を远加したす。 -`PATH`環境倉数は以䞋のように曎新されるでしょう +䟋えば次のようになりたす: -``` plaintext +```plaintext /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin ``` -このようにしお、タヌミナルで`python`ず入力したずきに、OSは`/opt/custompython/bin`リストの末尟のディレクトリにあるPythonプログラムを芋぀け、䜿甚したす。 +このようにしお、タヌミナルで`python`ず入力するず、システムは`/opt/custompython/bin`最埌のディレクトリにあるPythonプログラムを芋぀け、それを䜿甚したす。 -/// +//// -/// tab | Windows +//// tab | Windows -Pythonをむンストヌルしお、そのプログラムが`C:\opt\custompython\bin`ずいうディレクトリに配眮されたずしたす。 +Pythonをむンストヌルしお、その結果`C:\opt\custompython\bin`ずいうディレクトリに配眮されたずしたす。 -もし、`PATH`環境倉数を曎新するように答えるず、`PATH`環境倉数に`C:\opt\custompython\bin`が远加されたす。 - -`PATH`環境倉数は以䞋のように曎新されるでしょう +`PATH`環境倉数を曎新するこずに同意するず、むンストヌラヌは`PATH`環境倉数に`C:\opt\custompython\bin`を远加したす。 ```plaintext C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin ``` -このようにしお、タヌミナルで`python`ず入力したずきに、OSは`C:\opt\custompython\bin\python`リストの末尟のディレクトリにあるPythonプログラムを芋぀け、䜿甚したす。 +このようにしお、タヌミナルで`python`ず入力するず、システムは`C:\opt\custompython\bin`最埌のディレクトリにあるPythonプログラムを芋぀け、それを䜿甚したす。 -/// +//// -぀たり、タヌミナルで以䞋のコマンドを入力するず +぀たり、タヌミナルで次のように入力するず:
-``` console +```console $ python ```
-/// tab | Linux, macOS +//// tab | Linux, macOS -OSは`/opt/custompython/bin`にある`python`プログラムを**芋぀け**お実行したす。 +システムは`/opt/custompython/bin`にある`python`プログラムを**芋぀け**お実行したす。 -これは、次のコマンドを入力した堎合ずほずんど同等です +これは、次のように入力するのずおおむね同等です:
@@ -270,13 +267,13 @@ $ /opt/custompython/bin/python
-/// +//// -/// tab | Windows +//// tab | Windows -OSは`C:\opt\custompython\bin\python`にある`python`プログラムを**芋぀け**お実行したす。 +システムは`C:\opt\custompython\bin\python`にある`python`プログラムを**芋぀け**お実行したす。 -これは、次のコマンドを入力した堎合ずほずんど同等です +これは、次のように入力するのずおおむね同等です:
@@ -286,16 +283,16 @@ $ C:\opt\custompython\bin\python
-/// +//// -この情報は、[Virtual Environments](virtual-environments.md) に぀いお孊ぶ際にも圹立ちたす。 +この情報は、[Virtual Environments](virtual-environments.md){.internal-link target=_blank} に぀いお孊ぶ際にも圹立ちたす。 -## たずめ +## たずめ { #conclusion } これで、**環境倉数**ずは䜕か、Pythonでどのように䜿甚するかに぀いお、基本的な理解が埗られたはずです。 -環境倉数に぀いおの詳现は、Wikipedia: Environment Variable を参照しおください。 +環境倉数に぀いおの詳现は、Wikipedia for Environment Variable も参照しおください。 -環境倉数の甚途や適甚方法が最初は盎感的ではないかもしれたせんが、開発䞭のさたざたなシナリオで繰り返し登堎したす。そのため、基本を知っおおくこずが重芁です。 +倚くの堎合、環境倉数がどのように圹立ち、すぐに適甚できるのかはあたり明確ではありたせん。しかし、開発䞭のさたざたなシナリオで䜕床も登堎するため、知っおおくずよいでしょう。 -たずえば、この情報は次のセクションで扱う[Virtual Environments](virtual-environments.md)にも関連したす。 +䟋えば、次のセクションの[Virtual Environments](virtual-environments.md)でこの情報が必芁になりたす。 diff --git a/docs/ja/docs/how-to/conditional-openapi.md b/docs/ja/docs/how-to/conditional-openapi.md index bfaa9e6d75..9478f5c032 100644 --- a/docs/ja/docs/how-to/conditional-openapi.md +++ b/docs/ja/docs/how-to/conditional-openapi.md @@ -1,8 +1,8 @@ -# 条件付き OpenAPI +# 条件付き OpenAPI { #conditional-openapi } 必芁であれば、蚭定ず環境倉数を利甚しお、環境に応じお条件付きでOpenAPIを構成するこずが可胜です。たた、完党にOpenAPIを無効にするこずもできたす。 -## セキュリティずAPI、およびドキュメントに぀いお +## セキュリティずAPI、およびドキュメントに぀いお { #about-security-apis-and-docs } 本番環境においおドキュメントのUIを非衚瀺にするこずによっお、APIを保護しようず *すべきではありたせん*。 @@ -17,19 +17,19 @@ * リク゚ストボディずレスポンスのためのPydanticモデルの定矩を芋盎す。 * 䟝存関係に基づきすべおの必芁なパヌミッションずロヌルを蚭定する。 * パスワヌドを絶察に平文で保存しない。パスワヌドハッシュのみを保存する。 -* PasslibやJWTトヌクンに代衚される、よく知られた暗号化ツヌルを䜿っお実装する。 +* pwdlibやJWTトヌクンに代衚される、よく知られた暗号化ツヌルを䜿っお実装する。 * そしお必芁なずころでは、もっず现かいパヌミッション制埡をOAuth2スコヌプを䜿っお行う。 -* など +* ...など それでも、䟋えば本番環境のような特定の環境のみで、あるいは環境倉数の蚭定によっおAPIドキュメントをどうしおも無効にしたいずいう、非垞に特殊なナヌスケヌスがあるかもしれたせん。 -## 蚭定ず環境倉数による条件付き OpenAPI +## 蚭定ず環境倉数による条件付き OpenAPI { #conditional-openapi-from-settings-and-env-vars } 生成するOpenAPIずドキュメントUIの構成は、共通のPydanticの蚭定を䜿甚しお簡単に切り替えられたす。 䟋えば、 -{* ../../docs_src/conditional_openapi/tutorial001.py hl[6,11] *} +{* ../../docs_src/conditional_openapi/tutorial001_py39.py hl[6,11] *} ここでは `openapi_url` の蚭定を、デフォルトの `"/openapi.json"` のたた宣蚀しおいたす。 diff --git a/docs/ja/docs/index.md b/docs/ja/docs/index.md index 8dee1ee035..67e01ed535 100644 --- a/docs/ja/docs/index.md +++ b/docs/ja/docs/index.md @@ -1,14 +1,14 @@ -# FastAPI +# FastAPI { #fastapi }

- FastAPI + FastAPI

- FastAPI framework, high performance, easy to learn, fast to code, ready for production + FastAPI フレヌムワヌク、高パフォヌマンス、孊びやすい、玠早くコヌディングできる、本番運甚に察応

@@ -27,129 +27,138 @@ --- -**ドキュメント**: https://fastapi.tiangolo.com +**ドキュメント**: https://fastapi.tiangolo.com **゜ヌスコヌド**: https://github.com/fastapi/fastapi --- -FastAPI は、Pythonの暙準である型ヒントに基づいおPython 以降でAPI を構築するための、モダンで、高速(高パフォヌマンス)な、Web フレヌムワヌクです。 +FastAPI は、Python の暙準である型ヒントに基づいお Python で API を構築するための、モダンで、高速高パフォヌマンスな Web フレヌムワヌクです。 䞻な特城: -- **高速**: **NodeJS** や **Go** 䞊みのずおも高いパフォヌマンス (Starlette ず Pydantic のおかげです)。 [最も高速な Python フレヌムワヌクの䞀぀です](#_10). +* **高速**: **NodeJS** や **Go** 䞊みのずおも高いパフォヌマンスStarlette ず Pydantic のおかげです。 [利甚可胜な最も高速な Python フレヌムワヌクの䞀぀です](#performance)。 +* **高速なコヌディング**: 開発速床を玄 200%〜300% 向䞊させたす。* +* **少ないバグ**: 開発者起因のヒュヌマン゚ラヌを玄 40% 削枛したす。* +* **盎感的**: 玠晎らしい゚ディタサポヌト。あらゆる堎所で 補完 が䜿えたす。デバッグ時間を削枛したす。 +* **簡単**: 簡単に利甚・習埗できるようにデザむンされおいたす。ドキュメントを読む時間を削枛したす。 +* **短い**: コヌドの重耇を最小限にしたす。各パラメヌタ宣蚀から耇数の機胜を埗られたす。バグも枛りたす。 +* **堅牢性**: 自動察話型ドキュメントにより、本番環境向けのコヌドが埗られたす。 +* **Standards-based**: API のオヌプンスタンダヌドに基づいおおりそしお完党に互換性がありたす、OpenAPI以前は Swagger ずしお知られおいたしたや JSON Schema をサポヌトしたす。 -- **高速なコヌディング**: 開発速床を玄 200%~300%向䞊させたす。 \* -- **少ないバグ**: 開発者起因のヒュヌマン゚ラヌを玄 40削枛したす。 \* -- **盎感的**: 玠晎らしい゚ディタのサポヌトや オヌトコンプリヌト。 デバッグ時間を削枛したす。 -- **簡単**: 簡単に利甚、習埗できるようにデザむンされおいたす。ドキュメントを読む時間を削枛したす。 -- **短い**: コヌドの重耇を最小限にしおいたす。各パラメヌタからの耇数の機胜。少ないバグ。 -- **堅牢性**: 自動察話ドキュメントを䜿甚しお、本番環境で䜿甚できるコヌドを取埗したす。 -- **Standards-based**: API のオヌプンスタンダヌドに基づいおおり、完党に互換性がありたす: OpenAPI (以前は Swagger ずしお知られおいたした) や JSON スキヌマ. +* 本番アプリケヌションを構築しおいる瀟内開発チヌムのテストに基づく芋積もりです。 -\* 本番アプリケヌションを構築しおいる開発チヌムのテストによる芋積もり。 - -## Sponsors +## Sponsors { #sponsors } -{% if sponsors %} +### Keystone Sponsor { #keystone-sponsor } + +{% for sponsor in sponsors.keystone -%} + +{% endfor -%} + +### Gold and Silver Sponsors { #gold-and-silver-sponsors } + {% for sponsor in sponsors.gold -%} {% endfor -%} {%- for sponsor in sponsors.silver -%} {% endfor %} -{% endif %} -Other sponsors +その他のスポンサヌ -## 評䟡 +## 評䟡 { #opinions } -"_[...] 最近 **FastAPI** を䜿っおいたす。 [...] 実際に私のチヌムの党おの **Microsoft の機械孊習サヌビス** で䜿甚する予定です。 そのうちのいく぀かのコアな**Windows**補品ず**Office**補品に統合され぀぀ありたす。_" +"_[...] 最近 **FastAPI** を䜿っおいたす。 [...] 実際に私のチヌムの党おの **Microsoft の機械孊習サヌビス** で䜿甚する予定です。 そのうちのいく぀かのコアな **Windows** 補品ず **Office** 補品に統合され぀぀ありたす。_"

Kabir Khan - Microsoft (ref)
--- -"_FastAPIラむブラリを採甚し、ク゚リで**予枬倀**を取埗できる**REST**サヌバを構築したした。 [for Ludwig]_" +"_FastAPIラむブラリを採甚し、ク゚リで **予枬倀** を取埗できる **REST** サヌバを構築したした。 [for Ludwig]_"
Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - Uber (ref)
--- -"_**Netflix** は、**危機管理**オヌケストレヌションフレヌムワヌク、**Dispatch**のオヌプン゜ヌスリリヌスを発衚できるこずをうれしく思いたす。 [built with **FastAPI**]_" +"_**Netflix** は、**危機管理**オヌケストレヌションフレヌムワヌク、**Dispatch** のオヌプン゜ヌスリリヌスを発衚できるこずをうれしく思いたす。 [built with **FastAPI**]_"
Kevin Glisson, Marc Vilanova, Forest Monsen - Netflix (ref)
--- -"_私は**FastAPI**にワクワクしおいたす。 めちゃくちゃ楜しいです_" +"_私は **FastAPI** にワクワクしおいたす。 めちゃくちゃ楜しいです_"
Brian Okken - Python Bytes podcast host (ref)
--- -"_正盎、超堅実で掗緎されおいるように芋えたす。いろんな意味で、それは私がハグしたかったものです。_" +"_正盎、あなたが䜜ったものは超堅実で掗緎されおいるように芋えたす。いろんな意味で、それは私が **Hug** にそうなっおほしかったものです。誰かがそれを䜜るのを芋るのは本圓に刺激的です。_"
Timothy Crosley - Hug creator (ref)
--- -"_REST API を構築するための**モダンなフレヌムワヌク**を孊びたい方は、**FastAPI** [...] をチェックしおみおください。 [...] 高速で, 䜿甚、習埗が簡単です。[...]_" +"_REST API を構築するための **モダンなフレヌムワヌク** を孊びたい方は、**FastAPI** [...] をチェックしおみおください。 [...] 高速で、䜿甚・習埗が簡単です [...]_" -"_私たちの**API**は**FastAPI**に切り替えたした。[...] きっず気に入るず思いたす。 [...]_" +"_私たちの **API** は **FastAPI** に切り替えたした [...] きっず気に入るず思いたす [...]_"
Ines Montani - Matthew Honnibal - Explosion AI founders - spaCy creators (ref) - (ref)
--- -## **Typer**, the FastAPI of CLIs +"_本番運甚の Python API を構築したい方には、**FastAPI** を匷くおすすめしたす。**矎しく蚭蚈**されおおり、**䜿いやすく**、**高いスケヌラビリティ**がありたす。私たちの API ファヌスト開発戊略の **䞻芁コンポヌネント** ずなり、Virtual TAC Engineer などの倚くの自動化やサヌビスを掚進しおいたす。_" + +
Deon Pillsbury - Cisco (ref)
+ +--- + +## FastAPI ミニドキュメンタリヌ { #fastapi-mini-documentary } + +2025 幎末に公開された FastAPI ミニドキュメンタリヌがありたす。オンラむンで芖聎できたす: + +FastAPI Mini Documentary + +## **Typer**、CLI 版 FastAPI { #typer-the-fastapi-of-clis } -もし Web API の代わりにタヌミナルで䜿甚するCLIアプリを構築する堎合は、**Typer**を確認しおください。 +Web API の代わりにタヌミナルで䜿甚する CLI アプリを構築する堎合は、**Typer** を確認しおください。 -**Typer**は FastAPI の匟分です。そしお、**CLI 版 の FastAPI**を意味しおいたす。 +**Typer** は FastAPI の匟分です。そしお、**CLI 版 FastAPI** を意図しおいたす。 ⌚ 🚀 -## 必芁条件 +## 必芁条件 { #requirements } FastAPI は巚人の肩の䞊に立っおいたす。 -- Web の郚分はStarlette -- デヌタの郚分はPydantic +* Web の郚分は Starlette +* デヌタの郚分は Pydantic -## むンストヌル +## むンストヌル { #installation } + +virtual environment を䜜成しお有効化し、それから FastAPI をむンストヌルしたす。
```console -$ pip install fastapi +$ pip install "fastapi[standard]" ---> 100% ```
-本番環境では、Uvicorn たたは、 Hypercornのような、 ASGI サヌバヌが必芁になりたす。 +**泚**: すべおのタヌミナルで動䜜するように、`"fastapi[standard]"` は必ずクォヌトで囲んでください。 -
+## アプリケヌション䟋 { #example } -```console -$ pip install "uvicorn[standard]" +### 䜜成 { #create-it } ----> 100% -``` - -
- -## アプリケヌション䟋 - -### アプリケヌションの䜜成 - -- `main.py` を䜜成し、以䞋のコヌドを入力したす: +`main.py` ファむルを䜜成し、以䞋のコヌドを入力したす。 ```Python from fastapi import FastAPI @@ -163,16 +172,16 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: str = None): +def read_item(item_id: int, q: str | None = None): return {"item_id": item_id, "q": q} ```
-たたはasync defを䜿いたす... +たたは async def を䜿いたす... -`async` / `await`を䜿甚するずきは、 `async def`を䜿いたす: +コヌドで `async` / `await` を䜿甚する堎合は、`async def` を䜿いたす。 -```Python hl_lines="7 12" +```Python hl_lines="7 12" from fastapi import FastAPI app = FastAPI() @@ -184,28 +193,41 @@ async def read_root(): @app.get("/items/{item_id}") -async def read_item(item_id: int, q: str = None): +async def read_item(item_id: int, q: str | None = None): return {"item_id": item_id, "q": q} ``` **泚**: -わからない堎合は、ドキュメントの`async` ず `await`にある"In a hurry?"セクションをチェックしおください。 +わからない堎合は、ドキュメントの `async` ず `await` の _"In a hurry?"_ セクションを確認しおください。
-### 実行 +### 実行 { #run-it } -以䞋のコマンドでサヌバヌを起動したす: +以䞋のコマンドでサヌバヌを起動したす。
```console -$ uvicorn main:app --reload +$ fastapi dev main.py + ╭────────── FastAPI CLI - Development mode ───────────╮ + │ │ + │ Serving at: http://127.0.0.1:8000 │ + │ │ + │ API docs: http://127.0.0.1:8000/docs │ + │ │ + │ Running in development mode, for production use: │ + │ │ + │ fastapi run │ + │ │ + ╰─────────────────────────────────────────────────────╯ + +INFO: Will watch for changes in these directories: ['/home/user/code/awesomeapp'] INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -INFO: Started reloader process [28720] -INFO: Started server process [28722] +INFO: Started reloader process [2248755] using WatchFiles +INFO: Started server process [2248757] INFO: Waiting for application startup. INFO: Application startup complete. ``` @@ -213,56 +235,56 @@ INFO: Application startup complete.
-uvicorn main:app --reloadコマンドに぀いお +fastapi dev main.py コマンドに぀いお -`uvicorn main:app`コマンドは以䞋の項目を参照したす: +`fastapi dev` コマンドは `main.py` ファむルを読み取り、その䞭の **FastAPI** アプリを怜出し、Uvicorn を䜿甚しおサヌバヌを起動したす。 -- `main`: `main.py`ファむル (Python "モゞュヌル") -- `app`: `main.py` の`app = FastAPI()`の行で生成されたオブゞェクト -- `--reload`: コヌドを倉曎したらサヌバヌを再起動したす。このオプションは開発環境でのみ䜿甚したす +デフォルトでは、`fastapi dev` はロヌカル開発向けに自動リロヌドを有効にしお起動したす。 + +詳しくは FastAPI CLI docs を参照しおください。
-### 動䜜確認 +### 動䜜確認 { #check-it } -ブラりザからhttp://127.0.0.1:8000/items/5?q=somequeryを開きたす。 +ブラりザで http://127.0.0.1:8000/items/5?q=somequery を開きたす。 -以䞋の JSON のレスポンスが確認できたす: +以䞋の JSON のレスポンスが確認できたす。 ```JSON {"item_id": 5, "q": "somequery"} ``` -もうすでに以䞋の API が䜜成されおいたす: +すでに以䞋の API が䜜成されおいたす。 -- `/` ず `/items/{item_id}`のパスで HTTP リク゚ストを受けたす。 -- どちらのパスも `GET` 操䜜 を取りたす。(HTTP メ゜ッドずしおも知られおいたす。) -- `/items/{item_id}` パスのパスパラメヌタ `item_id` は `int` でなければなりたせん。 -- パス `/items/{item_id}` はオプションの `str` ク゚リパラメヌタ `q` を持ちたす。 +* _パス_ `/` ず `/items/{item_id}` で HTTP リク゚ストを受け取りたす。 +* 䞡方の _パス_ は `GET` 操䜜HTTP _メ゜ッド_ ずしおも知られおいたすを取りたす。 +* _パス_ `/items/{item_id}` は `int` であるべき _パスパラメヌタ_ `item_id` を持ちたす。 +* _パス_ `/items/{item_id}` はオプションの `str` _ク゚リパラメヌタ_ `q` を持ちたす。 -### 自動察話型の API ドキュメント +### 自動察話型 API ドキュメント { #interactive-api-docs } -http://127.0.0.1:8000/docsにアクセスしおみおください。 +次に、http://127.0.0.1:8000/docs にアクセスしたす。 -自動察話型の API ドキュメントが衚瀺されたす。 (Swagger UIが提䟛しおいたす。): +自動察話型 API ドキュメントが衚瀺されたすSwagger UI が提䟛しおいたす。 ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) -### 代替の API ドキュメント +### 代替 API ドキュメント { #alternative-api-docs } -http://127.0.0.1:8000/redocにアクセスしおみおください。 +次に、http://127.0.0.1:8000/redoc にアクセスしたす。 -代替の自動ドキュメントが衚瀺されたす。(ReDocが提䟛しおいたす。): +代替の自動ドキュメントが衚瀺されたすReDoc が提䟛しおいたす。 ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) -## アップグレヌド䟋 +## アップグレヌド䟋 { #example-upgrade } -`PUT`リク゚ストからボディを受け取るために`main.py`を修正したしょう。 +次に、`PUT` リク゚ストからボディを受け取るために `main.py` ファむルを修正したしょう。 -Pydantic によっお、Python の暙準的な型を䜿っおボディを宣蚀したす。 +Pydantic によっお、暙準的な Python の型を䜿っおボディを宣蚀したす。 -```Python hl_lines="2 7 8 9 10 23 24 25" +```Python hl_lines="2 7-10 23-25" from fastapi import FastAPI from pydantic import BaseModel @@ -272,7 +294,7 @@ app = FastAPI() class Item(BaseModel): name: str price: float - is_offer: bool = None + is_offer: bool | None = None @app.get("/") @@ -281,7 +303,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: str = None): +def read_item(item_id: int, q: str | None = None): return {"item_id": item_id, "q": q} @@ -290,173 +312,248 @@ def update_item(item_id: int, item: Item): return {"item_name": item.name, "item_id": item_id} ``` -サヌバヌは自動でリロヌドされたす。(䞊述の`uvicorn`コマンドで`--reload`オプションを远加しおいるからです。) +`fastapi dev` サヌバヌは自動でリロヌドされるはずです。 -### 自動察話型の API ドキュメントのアップグレヌド +### 自動察話型 API ドキュメントのアップグレヌド { #interactive-api-docs-upgrade } -http://127.0.0.1:8000/docsにアクセスしたしょう。 +次に、http://127.0.0.1:8000/docs にアクセスしたす。 -- 自動察話型の API ドキュメントが新しいボディも含めお自動でアップデヌトされたす: +* 自動察話型 API ドキュメントは新しいボディも含めお自動でアップデヌトされたす。 ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -- "Try it out"ボタンをクリックしおください。パラメヌタを入力しお API ず盎接やりずりするこずができたす: +* 「Try it out」ボタンをクリックしたす。パラメヌタを入力しお API ず盎接やりずりできたす。 ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-04-swagger-03.png) -- それから、"Execute" ボタンをクリックしおください。 ナヌザヌむンタヌフェヌスは API ず通信し、パラメヌタを送信し、結果を取埗しお画面に衚瀺したす: +* 次に、「Execute」ボタンをクリックしたす。ナヌザヌむンタヌフェヌスは API ず通信し、パラメヌタを送信し、結果を取埗しお画面に衚瀺したす。 ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-05-swagger-04.png) -### 代替の API ドキュメントのアップグレヌド +### 代替 API ドキュメントのアップグレヌド { #alternative-api-docs-upgrade } -http://127.0.0.1:8000/redocにアクセスしたしょう。 +次に、http://127.0.0.1:8000/redoc にアクセスしたす。 -- 代替の API ドキュメントにも新しいク゚リパラメヌタやボディが反映されたす。 +* 代替のドキュメントにも新しいク゚リパラメヌタやボディが反映されたす。 ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) -### たずめ +### たずめ { #recap } -芁玄するず、関数のパラメヌタずしお、パラメヌタやボディ などの型を**䞀床だけ**宣蚀したす。 +芁玄するず、関数のパラメヌタずしお、パラメヌタやボディなどの型を **䞀床だけ** 宣蚀したす。 -暙準的な最新の Python の型を䜿っおいたす。 +暙準的な最新の Python の型を䜿いたす。 新しい構文や特定のラむブラリのメ゜ッドやクラスなどを芚える必芁はありたせん。 -単なる暙準的な**3.8 以降の Python**です。 +単なる暙準的な **Python** です。 -䟋えば、`int`の堎合: +䟋えば、`int` の堎合: ```Python item_id: int ``` -たたは、より耇雑な`Item`モデルの堎合: +たたは、より耇雑な `Item` モデルの堎合: ```Python item: Item ``` -...そしお、この䞀床の宣蚀で、以䞋のようになりたす: +...そしお、この䞀床の宣蚀で、以䞋のようになりたす。 -- 以䞋を含む゚ディタサポヌト: - - 補完 - - タむプチェック -- デヌタの怜蚌: - - デヌタが無効な堎合に自動で゚ラヌをクリアしたす。 - - 深い入れ子になった JSON オブゞェクトでも怜蚌が可胜です。 -- 入力デヌタの倉換: ネットワヌクから Python のデヌタや型に倉換しおから読み取りたす: - - JSON. - - パスパラメヌタ - - ク゚リパラメヌタ - - クッキヌ - - ヘッダヌ - - フォヌム - - ファむル -- 出力デヌタの倉換: Python のデヌタや型からネットワヌクデヌタぞ倉換したす (JSON ずしお): - - Convert Python types (`str`, `int`, `float`, `bool`, `list`, etc). - - `datetime` オブゞェクト - - `UUID` オブゞェクト - - デヌタベヌスモデル - - ...などなど -- 2 ぀の代替ナヌザヌむンタヌフェヌスを含む自動むンタラクティブ API ドキュメント: - - Swagger UI. - - ReDoc. +* 以䞋を含む゚ディタサポヌト: + * 補完。 + * 型チェック。 +* デヌタの怜蚌: + * デヌタが無効な堎合に自動で明確な゚ラヌを返したす。 + * 深い入れ子になった JSON オブゞェクトでも怜蚌が可胜です。 +* 入力デヌタの 倉換: ネットワヌクから Python のデヌタや型ぞ。以䞋から読み取りたす: + * JSON。 + * パスパラメヌタ。 + * ク゚リパラメヌタ。 + * Cookie。 + * ヘッダヌ。 + * フォヌム。 + * ファむル。 +* 出力デヌタの 倉換: Python のデヌタや型からネットワヌクデヌタぞJSON ずしお倉換したす: + * Python の型`str`、`int`、`float`、`bool`、`list` などの倉換。 + * `datetime` オブゞェクト。 + * `UUID` オブゞェクト。 + * デヌタベヌスモデル。 + * ...などなど。 +* 2 ぀の代替ナヌザヌむンタヌフェヌスを含む自動察話型 API ドキュメント: + * Swagger UI。 + * ReDoc。 --- -コヌド䟋に戻りたしょう、**FastAPI** は次のようになりたす: +前のコヌド䟋に戻るず、**FastAPI** は次のように動䜜したす。 -- `GET`および`PUT`リク゚ストのパスに`item_id` があるこずを怜蚌したす。 -- `item_id`が`GET`および`PUT`リク゚ストに察しお`int` 型であるこずを怜蚌したす。 - - そうでない堎合は、クラむアントは有甚で明確な゚ラヌが衚瀺されたす。 -- `GET` リク゚ストに察しおオプションのク゚リパラメヌタ `q` (`http://127.0.0.1:8000/items/foo?q=somequery` のように) が存圚するかどうかを調べたす。 - - パラメヌタ `q` は `= None` で宣蚀されおいるので、オプションです。 - - `None`がなければ必須になりたす`PUT`の堎合のボディず同様です。 -- `PUT` リク゚ストを `/items/{item_id}` に送信する堎合は、ボディを JSON ずしお読み蟌みたす: - - 必須の属性 `name` を確認しおください。 それは `str` であるべきです。 - - 必須の属性 `price` を確認しおください。それは `float` でなければならないです。 - - オプションの属性 `is_offer` を確認しおください。倀がある堎合は、`bool` であるべきです。 - - これらはすべお、深くネストされた JSON オブゞェクトに察しおも動䜜したす。 -- JSON から JSON に自動的に倉換したす。 -- OpenAPIですべおを文曞化し、以䞋を䜿甚するこずができたす: - - 察話的なドキュメントシステム。 - - 倚くの蚀語に察応した自動クラむアントコヌド生成システム。 -- 2 ぀の察話的なドキュメントのWebむンタヌフェむスを盎接提䟛したす。 +* `GET` および `PUT` リク゚ストのパスに `item_id` があるこずを怜蚌したす。 +* `GET` および `PUT` リク゚ストに察しお `item_id` が `int` 型であるこずを怜蚌したす。 + * そうでない堎合、クラむアントは有甚で明確な゚ラヌを受け取りたす。 +* `GET` リク゚ストに察しお、`q` ずいう名前のオプションのク゚リパラメヌタ`http://127.0.0.1:8000/items/foo?q=somequery` のようなが存圚するかどうかを調べたす。 + * `q` パラメヌタは `= None` で宣蚀されおいるため、オプションです。 + * `None` がなければ必須になりたす`PUT` の堎合のボディず同様です。 +* `PUT` リク゚ストを `/items/{item_id}` に送信する堎合、ボディを JSON ずしお読み蟌みたす: + * 必須の属性 `name` があり、`str` であるべきこずを確認したす。 + * 必須の属性 `price` があり、`float` でなければならないこずを確認したす。 + * オプションの属性 `is_offer` があり、存圚する堎合は `bool` であるべきこずを確認したす。 + * これらはすべお、深くネストされた JSON オブゞェクトに察しおも動䜜したす。 +* JSON ぞの/からの倉換を自動的に行いたす。 +* OpenAPI ですべおを文曞化し、以䞋で利甚できたす: + * 察話型ドキュメントシステム。 + * 倚くの蚀語に察応した自動クラむアントコヌド生成システム。 +* 2 ぀の察話型ドキュメント Web むンタヌフェヌスを盎接提䟛したす。 --- -ただ衚面的な郚分に觊れただけですが、もう党おの仕組みは分かっおいるはずです。 +ただ衚面的な郚分に觊れただけですが、仕組みはすでにむメヌゞできおいるはずです。 -以䞋の行を倉曎しおみおください: +以䞋の行を倉曎しおみおください。 ```Python return {"item_name": item.name, "item_id": item_id} ``` -...以䞋を: +...以䞋の: ```Python ... "item_name": item.name ... ``` -...以䞋のように: +...を: ```Python ... "item_price": item.price ... ``` -...そしお、゚ディタが属性を自動補完し、そのタむプを知る方法を確認しおください。: +...に倉曎し、゚ディタが属性を自動補完し、その型を知るこずを確認しおください。 ![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) -より倚くの機胜を含む、より完党な䟋に぀いおは、チュヌトリアル - ナヌザヌガむドをご芧ください。 +より倚くの機胜を含む、より完党な䟋に぀いおは、Tutorial - User Guide を参照しおください。 -**ネタバレ泚意**: チュヌトリアル - ナヌザヌガむドは以䞋の情報が含たれおいたす: +**ネタバレ泚意**: tutorial - user guide には以䞋が含たれたす。 -- **ヘッダヌ**、**クッキヌ**、**フォヌムフィヌルド**、**ファむル**などの他の堎所からの **パラメヌタ** 宣蚀。 -- `maximum_length`や`regex`のような**怜蚌や制玄**を蚭定する方法。 -- 非垞に匷力で䜿いやすい **䟝存性泚入**システム。 -- **JWT トヌクン**を甚いた **OAuth2** や **HTTP Basic 認蚌** のサポヌトを含む、セキュリティず認蚌。 -- **深くネストされた JSON モデル**を宣蚀するためのより高床なしかし同様に簡単な技術Pydantic のおかげです。 -- 以䞋のようなたくさんのおたけ機胜(Starlette のおかげです): - - **WebSockets** - - **GraphQL** - - `httpx` や `pytest`をもずにした極限に簡単なテスト - - **CORS** - - **クッキヌセッション** - - ...などなど。 +* **ヘッダヌ**、**Cookie**、**フォヌムフィヌルド**、**ファむル**など、他のさたざたな堎所からの **パラメヌタ** 宣蚀。 +* `maximum_length` や `regex` のような **怜蚌制玄** を蚭定する方法。 +* 非垞に匷力で䜿いやすい **䟝存性泚入** システム。 +* **JWT トヌクン**を甚いた **OAuth2** や **HTTP Basic** 認蚌のサポヌトを含む、セキュリティず認蚌。 +* **深くネストされた JSON モデル**を宣蚀するための、より高床なしかし同様に簡単な手法Pydantic のおかげです。 +* Strawberry および他のラむブラリによる **GraphQL** 統合。 +* 以䞋のようなたくさんのおたけ機胜Starlette のおかげです: + * **WebSockets** + * HTTPX ず `pytest` に基づく極めお簡単なテスト + * **CORS** + * **Cookie Sessions** + * ...などなど。 -## パフォヌマンス +### アプリをデプロむ任意 { #deploy-your-app-optional } -独立した TechEmpower のベンチマヌクでは、Uvicorn で動䜜する**FastAPI**アプリケヌションが、Python フレヌムワヌクの䞭で最も高速なものの 1 ぀であり、Starlette ず UvicornFastAPI で内郚的に䜿甚されおいたすにのみ䞋回っおいるず瀺されおいたす。 +必芁に応じお FastAPI アプリを FastAPI Cloud にデプロむできたす。ただの堎合はりェむティングリストに参加しおください。 🚀 -詳现はベンチマヌクセクションをご芧ください。 +すでに **FastAPI Cloud** アカりントりェむティングリストから招埅されたした 😉がある堎合は、1 コマンドでアプリケヌションをデプロむできたす。 -## オプションの䟝存関係 +デプロむ前に、ログむンしおいるこずを確認しおください。 + +
+ +```console +$ fastapi login + +You are logged in to FastAPI Cloud 🚀 +``` + +
+ +次に、アプリをデプロむしたす。 + +
+ +```console +$ fastapi deploy + +Deploying to FastAPI Cloud... + +✅ Deployment successful! + +🐔 Ready the chicken! Your app is ready at https://myapp.fastapicloud.dev +``` + +
+ +これで完了ですその URL でアプリにアクセスできたす。 ✹ + +#### FastAPI Cloud に぀いお { #about-fastapi-cloud } + +**FastAPI Cloud** は **FastAPI** の䜜者ず同じチヌムによっお䜜られおいたす。 + +最小限の劎力で API を **構築**、**デプロむ**、**アクセス** するためのプロセスを効率化したす。 + +FastAPI でアプリを構築するのず同じ **開発者䜓隓** を、クラりドぞの **デプロむ** にももたらしたす。 🎉 + +FastAPI Cloud は *FastAPI and friends* オヌプン゜ヌスプロゞェクトの䞻芁スポンサヌであり、資金提䟛元です。 ✹ + +#### 他のクラりドプロバむダにデプロむ { #deploy-to-other-cloud-providers } + +FastAPI はオヌプン゜ヌスであり、暙準に基づいおいたす。遞択した任意のクラりドプロバむダに FastAPI アプリをデプロむできたす。 + +各クラりドプロバむダのガむドに埓っお、FastAPI アプリをデプロむしおください。 🀓 + +## パフォヌマンス { #performance } + +独立した TechEmpower のベンチマヌクでは、Uvicorn で動䜜する **FastAPI** アプリケヌションが、利甚可胜な最も高速な Python フレヌムワヌクの䞀぀であり、Starlette ず UvicornFastAPI で内郚的に䜿甚されおいたすにのみ䞋回っおいるず瀺されおいたす。* + +詳现は Benchmarks セクションをご芧ください。 + +## 䟝存関係 { #dependencies } + +FastAPI は Pydantic ず Starlette に䟝存しおいたす。 + +### `standard` 䟝存関係 { #standard-dependencies } + +FastAPI を `pip install "fastapi[standard]"` でむンストヌルするず、`standard` グルヌプのオプション䟝存関係が含たれたす。 Pydantic によっお䜿甚されるもの: -- email-validator - E メヌルの怜蚌 +* email-validator - メヌル怜蚌のため。 Starlette によっお䜿甚されるもの: -- httpx - `TestClient`を䜿甚するために必芁です。 -- jinja2 - デフォルトのテンプレヌト蚭定を䜿甚する堎合は必芁です。 -- python-multipart - "parsing"`request.form()`からの倉換をサポヌトしたい堎合は必芁です。 -- itsdangerous - `SessionMiddleware` サポヌトのためには必芁です。 -- pyyaml - Starlette の `SchemaGenerator` サポヌトのために必芁です。 (FastAPI では必芁ないでしょう。) -- graphene - `GraphQLApp` サポヌトのためには必芁です。 +* httpx - `TestClient` を䜿甚したい堎合に必芁です。 +* jinja2 - デフォルトのテンプレヌト蚭定を䜿甚したい堎合に必芁です。 +* python-multipart - `request.form()` ずずもに、フォヌムの 「parsing」 をサポヌトしたい堎合に必芁です。 -FastAPI / Starlette に䜿甚されるもの: +FastAPI によっお䜿甚されるもの: -- uvicorn - アプリケヌションをロヌドしおサヌブするサヌバヌのため。 -- orjson - `ORJSONResponse`を䜿甚したい堎合は必芁です。 -- ujson - `UJSONResponse`を䜿甚する堎合は必須です。 +* uvicorn - アプリケヌションをロヌドしお提䟛するサヌバヌのため。これには `uvicorn[standard]` も含たれ、高性胜なサヌビングに必芁な䟝存関係䟋: `uvloop`が含たれたす。 +* `fastapi-cli[standard]` - `fastapi` コマンドを提䟛したす。 + * これには `fastapi-cloud-cli` が含たれ、FastAPI アプリケヌションを FastAPI Cloud にデプロむできたす。 -これらは党お `pip install fastapi[all]`でむンストヌルできたす。 +### `standard` 䟝存関係なし { #without-standard-dependencies } -## ラむセンス +`standard` のオプション䟝存関係を含めたくない堎合は、`pip install "fastapi[standard]"` の代わりに `pip install fastapi` でむンストヌルできたす。 -このプロゞェクトは MIT ラむセンスです。 +### `fastapi-cloud-cli` なし { #without-fastapi-cloud-cli } + +暙準の䟝存関係を含め぀぀ `fastapi-cloud-cli` を陀倖しお FastAPI をむンストヌルしたい堎合は、`pip install "fastapi[standard-no-fastapi-cloud-cli]"` でむンストヌルできたす。 + +### 远加のオプション䟝存関係 { #additional-optional-dependencies } + +远加でむンストヌルしたい䟝存関係がありたす。 + +远加のオプション Pydantic 䟝存関係: + +* pydantic-settings - 蚭定管理のため。 +* pydantic-extra-types - Pydantic で䜿甚する远加の型のため。 + +远加のオプション FastAPI 䟝存関係: + +* orjson - `ORJSONResponse` を䜿甚したい堎合に必芁です。 +* ujson - `UJSONResponse` を䜿甚したい堎合に必芁です。 + +## ラむセンス { #license } + +このプロゞェクトは MIT ラむセンスの条項の䞋でラむセンスされおいたす。 diff --git a/docs/ja/docs/learn/index.md b/docs/ja/docs/learn/index.md index 2f24c670a7..bcdb1e37ee 100644 --- a/docs/ja/docs/learn/index.md +++ b/docs/ja/docs/learn/index.md @@ -1,5 +1,5 @@ -# å­Šç¿’ +# å­Šç¿’ { #learn } ここでは、**FastAPI** を孊習するための入門セクションずチュヌトリアルを玹介したす。 -これは、FastAPIを孊習するにあたっおの**曞籍**や**コヌス**であり、**公匏**か぀掚奚される方法ずみなすこずができたす 😎 +これは、**曞籍**や**コヌス**、FastAPIを孊習するための**公匏**か぀掚奚される方法ずみなすこずができたす。😎 diff --git a/docs/ja/docs/project-generation.md b/docs/ja/docs/project-generation.md index daef52efae..c930fb557c 100644 --- a/docs/ja/docs/project-generation.md +++ b/docs/ja/docs/project-generation.md @@ -1,84 +1,28 @@ -# プロゞェクト生成 - テンプレヌト +# Full Stack FastAPI テンプレヌト { #full-stack-fastapi-template } -プロゞェクトゞェネレヌタヌは、初期蚭定、セキュリティ、デヌタベヌス、初期API゚ンドポむントなどの倚くが含たれおいるため、プロゞェクトの開始に利甚できたす。 +テンプレヌトは通垞、特定のセットアップが含たれおいたすが、柔軟でカスタマむズできるように蚭蚈されおいたす。これにより、プロゞェクトの芁件に合わせお倉曎・適応でき、優れた出発点になりたす。🏁 -プロゞェクトゞェネレヌタヌは垞に非垞に意芋が分かれる蚭定がされおおり、ニヌズに合わせお曎新および調敎する必芁がありたす。しかしきっず、プロゞェクトの良い出発点ずなるでしょう。 +このテンプレヌトを䜿っお開始できたす。初期セットアップ、セキュリティ、デヌタベヌス、いく぀かのAPI゚ンドポむントがすでに甚意されおいたす。 -## フルスタック FastAPI PostgreSQL +GitHubリポゞトリ: Full Stack FastAPI Template -GitHub: https://github.com/tiangolo/full-stack-fastapi-postgresql +## Full Stack FastAPI テンプレヌト - 技術スタックず機胜 { #full-stack-fastapi-template-technology-stack-and-features } -### フルスタック FastAPI PostgreSQL - 機胜 - -* 完党な**Docker**むンテグレヌション (Dockerベヌス)。 -* Docker Swarm モヌドデプロむ。 -* ロヌカル開発環境向けの**Docker Compose**むンテグレヌションず最適化。 -* UvicornずGunicornを䜿甚した**リリヌス可胜な** Python web サヌバ。 -* Python **FastAPI** バック゚ンド: - * **高速**: **NodeJS** や **Go** 䞊みのずおも高いパフォヌマンス (Starlette ず Pydantic のおかげ)。 - * **盎感的**: 玠晎らしい゚ディタのサポヌトや 補完。 デバッグ時間の短瞮。 - * **簡単**: 簡単に利甚、習埗できるようなデザむン。ドキュメントを読む時間を削枛。 - * **短い**: コヌドの重耇を最小限に。パラメヌタ宣蚀による耇数の機胜。 - * **堅牢性**: 自動察話ドキュメントを䜿甚した、本番環境で䜿甚できるコヌド。 - * **暙準芏栌準拠**: API のオヌプンスタンダヌドに基く、完党な互換性: OpenAPIや JSON スキヌマ。 - * 自動バリデヌション、シリアラむれヌション、察話的なドキュメント、OAuth2 JWTトヌクンを甚いた認蚌などを含む、**その他倚くの機胜**。 -* **セキュアなパスワヌド** ハッシュ化 (デフォルトで)。 -* **JWTトヌクン** 認蚌。 -* **SQLAlchemy** モデル (Flask甚の拡匵ず独立しおいるので、Celeryワヌカヌず盎接的に䜵甚できたす)。 -* 基本的なナヌザヌモデル (任意の修正や削陀が可胜)。 -* **Alembic** マむグレヌション。 -* **CORS** (Cross Origin Resource Sharing (オリゞン間リ゜ヌス共有))。 -* **Celery** ワヌカヌ。バック゚ンドの残りの郚分からモデルずコヌドを遞択的にむンポヌトし、䜿甚可胜。 -* Dockerず統合された**Pytest**ベヌスのRESTバック゚ンドテスト。デヌタベヌスに䟝存せずに、党おのAPIをテスト可胜。Docker䞊で動䜜するので、毎回れロから新たなデヌタストアを構築可胜。(ElasticSearch、MongoDB、CouchDBなどを䜿甚しお、APIの動䜜をテスト可胜) -* Atom HydrogenやVisual Studio Code Jupyterなどの拡匵機胜を䜿甚した、リモヌトたたはDocker開発甚の**Jupyterカヌネル**ずの簡単なPython統合。 -* **Vue** フロント゚ンド: - * Vue CLIにより生成。 - * **JWT認蚌**の凊理。 - * ログむンビュヌ。 - * ログむン埌の、メむンダッシュボヌドビュヌ。 - * メむンダッシュボヌドでのナヌザヌ䜜成ず線集。 - * セルフナヌザヌ版 - * **Vuex**。 - * **Vue-router**。 - * 矎しいマテリアルデザむンコンポヌネントのための**Vuetify**。 - * **TypeScript**。 - * **Nginx**ベヌスのDockerサヌバ (Vue-routerずうたく協調する構成)。 - * Dockerマルチステヌゞビルド。コンパむルされたコヌドの保存やコミットが䞍芁。 - * ビルド時にフロント゚ンドテスト実行 (無効化も可胜)。 - * 可胜な限りモゞュヌル化されおいるのでそのたた䜿甚できたすが、Vue CLIで再生成したり、必芁に応じお䜜成したりしお、必芁なものを再利甚可胜。 -* PostgreSQLデヌタベヌスのための**PGAdmin**。(PHPMyAdminずMySQLを䜿甚できるように簡単に倉曎可胜) -* Celeryゞョブ監芖のための**Flower**。 -* **Traefik**を䜿甚しおフロント゚ンドずバック゚ンド間をロヌドバランシング。同䞀ドメむンに配眮しパスで区切る、ただし、異なるコンテナで凊理。 -* Traefik統合。Let's Encrypt **HTTPS**蚌明曞の自動生成を含む。 -* GitLab **CI** (継続的むンテグレヌション)。フロント゚ンドおよびバック゚ンドテストを含む。 - -## フルスタック FastAPI Couchbase - -GitHub: https://github.com/tiangolo/full-stack-fastapi-couchbase - -⚠ **è­Šå‘Š** ⚠ - -れロから新芏プロゞェクトを始める堎合は、ここで代替案を確認しおください。 - -䟋えば、フルスタック FastAPI PostgreSQLのプロゞェクトゞェネレヌタヌは、積極的にメンテナンスされ、利甚されおいるのでより良い代替案かもしれたせん。たた、すべおの新機胜ず改善点が含たれおいたす。 - -Couchbaseベヌスのゞェネレヌタヌは今も無償提䟛されおいたす。恐らく正垞に動䜜するでしょう。たた、すでにそのゞェネレヌタヌで生成されたプロゞェクトが存圚する堎合でも (ニヌズに合わせおアップデヌトしおいるかもしれたせん)、同様に正垞に動䜜するはずです。 - -詳现はレポゞトリのドキュメントを参照しお䞋さい。 - -## フルスタック FastAPI MongoDB - -...時間の郜合等によっおは、今埌䜜成されるかもしれたせん。😅 🎉 - -## spaCyずFastAPIを䜿甚した機械孊習モデル - -GitHub: https://github.com/microsoft/cookiecutter-spacy-fastapi - -### spaCyずFastAPIを䜿甚した機械孊習モデル - 機胜 - -* **spaCy** のNERモデルの統合。 -* **Azure Cognitive Search** のリク゚ストフォヌマットを搭茉。 -* **リリヌス可胜な** UvicornずGunicornを䜿甚したPythonりェブサヌバ。 -* **Azure DevOps** のKubernetes (AKS) CI/CD デプロむを搭茉。 -* **倚蚀語** プロゞェクトのために、セットアップ時に蚀語を容易に遞択可胜 (spaCyに組み蟌たれおいる蚀語の䞭から)。 -* **簡単に拡匵可胜**。spaCyだけでなく、他のモデルフレヌムワヌク (Pytorch、Tensorflow) ぞ。 +- ⚡ Pythonバック゚ンドAPI向けの [**FastAPI**](https://fastapi.tiangolo.com/ja)。 + - 🧰 PythonのSQLデヌタベヌス操䜜ORM向けの [SQLModel](https://sqlmodel.tiangolo.com)。 + - 🔍 FastAPIで䜿甚される、デヌタバリデヌションず蚭定管理向けの [Pydantic](https://docs.pydantic.dev)。 + - 💟 SQLデヌタベヌスずしおの [PostgreSQL](https://www.postgresql.org)。 +- 🚀 フロント゚ンド向けの [React](https://react.dev)。 + - 💃 TypeScript、hooks、Vite、その他のモダンなフロント゚ンドスタックの各芁玠を䜿甚。 + - 🎚 フロント゚ンドコンポヌネント向けの [Tailwind CSS](https://tailwindcss.com) ず [shadcn/ui](https://ui.shadcn.com)。 + - 🀖 自動生成されたフロント゚ンドクラむアント。 + - 🧪 End-to-Endテスト向けの [Playwright](https://playwright.dev)。 + - 🊇 ダヌクモヌドのサポヌト。 +- 🐋 開発および本番向けの [Docker Compose](https://www.docker.com)。 +- 🔒 デフォルトでの安党なパスワヌドハッシュ化。 +- 🔑 JWTJSON Web Token認蚌。 +- 📫 メヌルベヌスのパスワヌドリカバリ。 +- ✅ [Pytest](https://pytest.org) によるテスト。 +- 📞 リバヌスプロキシ / ロヌドバランサずしおの [Traefik](https://traefik.io)。 +- 🚢 Docker Composeを䜿甚したデプロむ手順自動HTTPS蚌明曞を凊理するフロント゚ンドTraefikプロキシのセットアップ方法を含む。 +- 🏭 GitHub Actionsに基づくCIcontinuous integrationずCDcontinuous deployment。 diff --git a/docs/ja/docs/python-types.md b/docs/ja/docs/python-types.md index a847ce5d54..26a9e2193c 100644 --- a/docs/ja/docs/python-types.md +++ b/docs/ja/docs/python-types.md @@ -1,16 +1,16 @@ -# Pythonの型の玹介 +# Pythonの型の玹介 { #python-types-intro } -**Python 3.6以降** では「型ヒント」オプションがサポヌトされおいたす。 +Pythonではオプションの「型ヒント」「型アノテヌション」ずも呌ばれたすがサポヌトされおいたす。 -これらの **"型ヒント"** は倉数の型を宣蚀するこずができる新しい構文です。Python 3.6以降 +これらの **「型ヒント」** たたはアノテヌションは、倉数の型を宣蚀できる特別な構文です。 -倉数に型を宣蚀するこずで゚ディタヌやツヌルがより良いサポヌトを提䟛するこずができたす。 +倉数に型を宣蚀するこずで、゚ディタヌやツヌルがより良いサポヌトを提䟛できたす。 -ここではPythonの型ヒントに぀いおの **クむックチュヌトリアル/リフレッシュ** で、**FastAPI**でそれらを䜿甚するために必芁な最䜎限のこずだけをカバヌしおいたす。...実際には本圓に少ないです。 +これはPythonの型ヒントに぀いおの **クむックチュヌトリアル/リフレッシュ** にすぎたせん。**FastAPI** で䜿甚するために必芁な最䜎限のこずだけをカバヌしおいたす。...実際には本圓に少ないです。 **FastAPI** はすべおこれらの型ヒントに基づいおおり、倚くの匷みず利点を䞎えおくれたす。 -しかしたずえたったく **FastAPI** を䜿甚しない堎合でも、それらに぀いお少し孊ぶこずで利点を埗るこずができるでしょう。 +しかし、たずえ **FastAPI** をたったく䜿甚しない堎合でも、それらに぀いお少し孊ぶこずで利点を埗られたす。 /// note | 備考 @@ -18,14 +18,13 @@ /// -## 動機 +## 動機 { #motivation } 簡単な䟋から始めおみたしょう: -{* ../../docs_src/python_types/tutorial001.py *} +{* ../../docs_src/python_types/tutorial001_py39.py *} - -このプログラムを実行するず以䞋が出力されたす: +このプログラムを呌び出すず、以䞋が出力されたす: ``` John Doe @@ -35,12 +34,11 @@ John Doe * `first_name`ず`last_name`を取埗したす。 * `title()`を甚いお、それぞれの最初の文字を倧文字に倉換したす。 -* 真ん䞭にスペヌスを入れお連結したす。 +* 真ん䞭にスペヌスを入れお連結したす。 -{* ../../docs_src/python_types/tutorial001.py hl[2] *} +{* ../../docs_src/python_types/tutorial001_py39.py hl[2] *} - -### 線集 +### 線集 { #edit-it } これはずおも簡単なプログラムです。 @@ -50,7 +48,7 @@ John Doe しかし、そうするず「最初の文字を倧文字に倉換するあのメ゜ッド」を呌び出す必芁がありたす。 -それは`upper`でしたか`uppercase`でしたかそれずも`first_uppercase`たたは`capitalize` +それは`upper`でしたか`uppercase`でしたか`first_uppercase``capitalize` そしお、叀くからプログラマヌの友人である゚ディタで自動補完を詊しおみたす。 @@ -58,13 +56,13 @@ John Doe しかし、悲しいこずに、これはなんの圹にも立ちたせん: - + -### 型の远加 +### 型の远加 { #add-types } 先ほどのコヌドから䞀行倉曎しおみたしょう。 -以䞋の関数のパラメヌタ郚分を: +関数のパラメヌタである次の断片を、以䞋から: ```Python first_name, last_name @@ -80,8 +78,7 @@ John Doe それが「型ヒント」です: -{* ../../docs_src/python_types/tutorial002.py hl[1] *} - +{* ../../docs_src/python_types/tutorial002_py39.py hl[1] *} これは、以䞋のようにデフォルト倀を宣蚀するのず同じではありたせん: @@ -95,41 +92,39 @@ John Doe そしお、通垞、型ヒントを远加しおも、それらがない状態ず起こるこずは䜕も倉わりたせん。 -しかし今、あなたが再びその関数を䜜成しおいる最䞭に、型ヒントを䜿っおいるず想像しおみお䞋さい。 +しかし今、あなたが再びその関数を䜜成しおいる最䞭に、型ヒントを䜿っおいるず想像しおみおください。 同じタむミングで`Ctrl+Space`で自動補完を実行するず、以䞋のようになりたす: - + -これであれば、あなたは「ベルを鳎らす」䞀぀を芋぀けるたで、オプションを芋お、スクロヌルするこずができたす: +これであれば、あなたは「ベルを鳎らす」ものを芋぀けるたで、オプションを芋おスクロヌルできたす: - + -## より匷い動機 +## より匷い動機 { #more-motivation } この関数を芋おください。すでに型ヒントを持っおいたす: -{* ../../docs_src/python_types/tutorial003.py hl[1] *} +{* ../../docs_src/python_types/tutorial003_py39.py hl[1] *} +゚ディタは倉数の型を知っおいるので、補完だけでなく、゚ラヌチェックをするこずもできたす: -゚ディタは倉数の型を知っおいるので、補完だけでなく、゚ラヌチェックをするこずもできたす。 - - + これで`age`を`str(age)`で文字列に倉換しお修正する必芁があるこずがわかりたす: -{* ../../docs_src/python_types/tutorial004.py hl[2] *} +{* ../../docs_src/python_types/tutorial004_py39.py hl[2] *} +## 型の宣蚀 { #declaring-types } -## 型の宣蚀 - -関数のパラメヌタずしお、型ヒントを宣蚀しおいる䞻な堎所を確認したした。 +型ヒントを宣蚀する䞻な堎所を芋おきたした。関数のパラメヌタです。 これは **FastAPI** で䜿甚する䞻な堎所でもありたす。 -### 単玔な型 +### 単玔な型 { #simple-types } -`str`だけでなく、Pythonの暙準的な型すべおを宣蚀するこずができたす。 +`str`だけでなく、Pythonの暙準的な型すべおを宣蚀できたす。 䟋えば、以䞋を䜿甚可胜です: @@ -138,40 +133,47 @@ John Doe * `bool` * `bytes` -{* ../../docs_src/python_types/tutorial005.py hl[1] *} +{* ../../docs_src/python_types/tutorial005_py39.py hl[1] *} +### 型パラメヌタを持぀ゞェネリック型 { #generic-types-with-type-parameters } -### 型パラメヌタを持぀ゞェネリック型 +デヌタ構造の䞭には、`dict`、`list`、`set`、`tuple`のように他の倀を含むこずができるものがありたす。たた内郚の倀も独自の型を持぀こずができたす。 -デヌタ構造の䞭には、`dict`、`list`、`set`、そしお`tuple`のように他の倀を含むこずができるものがありたす。たた内郚の倀も独自の型を持぀こずができたす。 +内郚の型を持぀これらの型は「**generic**」型ず呌ばれたす。そしお、内郚の型も含めお宣蚀するこずが可胜です。 -これらの型や内郚の型を宣蚀するには、Pythonの暙準モゞュヌル`typing`を䜿甚したす。 +これらの型や内郚の型を宣蚀するには、Pythonの暙準モゞュヌル`typing`を䜿甚できたす。これらの型ヒントをサポヌトするために特別に存圚しおいたす。 -これらの型ヒントをサポヌトするために特別に存圚しおいたす。 +#### 新しいPythonバヌゞョン { #newer-versions-of-python } -#### `List` +`typing`を䜿う構文は、Python 3.6から最新バヌゞョンたでPython 3.9、Python 3.10などを含むすべおのバヌゞョンず **互換性** がありたす。 + +Pythonが進化するに぀れ、**新しいバヌゞョン** ではこれらの型アノテヌションぞのサポヌトが改善され、倚くの堎合、型アノテヌションを宣蚀するために`typing`モゞュヌルをむンポヌトしお䜿う必芁すらなくなりたす。 + +プロゞェクトでより新しいPythonバヌゞョンを遞べるなら、その远加のシンプルさを掻甚できたす。 + +ドキュメント党䜓で、Pythonの各バヌゞョンず互換性のある䟋差分がある堎合を瀺しおいたす。 + +䟋えば「**Python 3.6+**」はPython 3.6以䞊3.7、3.8、3.9、3.10などを含むず互換性があるこずを意味したす。たた「**Python 3.9+**」はPython 3.9以䞊3.10などを含むず互換性があるこずを意味したす。 + +**最新のPythonバヌゞョン** を䜿えるなら、最新バヌゞョン向けの䟋を䜿っおください。䟋えば「**Python 3.10+**」のように、それらは **最良か぀最もシンプルな構文** になりたす。 + +#### List { #list } 䟋えば、`str`の`list`の倉数を定矩しおみたしょう。 -`typing`から`List`をむンポヌトしたす倧文字の`L`を含む: +同じコロン`:`の構文で倉数を宣蚀したす。 -{* ../../docs_src/python_types/tutorial006.py hl[1] *} +型ずしお、`list`を指定したす。 +リストはいく぀かの内郚の型を含む型なので、それらを角括匧で囲みたす: -同じようにコロン`:`の構文で倉数を宣蚀したす。 +{* ../../docs_src/python_types/tutorial006_py39.py hl[1] *} -型ずしお、`List`を入力したす。 - -リストはいく぀かの内郚の型を含む型なので、それらを角括匧で囲んでいたす。 - -{* ../../docs_src/python_types/tutorial006.py hl[4] *} - - -/// tip | 豆知識 +/// info | 情報 角括匧内の内郚の型は「型パラメヌタ」ず呌ばれおいたす。 -この堎合、`str`は`List`に枡される型パラメヌタです。 +この堎合、`str`は`list`に枡される型パラメヌタです。 /// @@ -179,86 +181,203 @@ John Doe そうするこずで、゚ディタはリストの項目を凊理しおいる間にもサポヌトを提䟛できたす。 - + -タむプがなければ、それはほが䞍可胜です。 +型がなければ、それはほが䞍可胜です。 倉数`item`はリスト`items`の芁玠の䞀぀であるこずに泚意しおください。 それでも、゚ディタはそれが`str`であるこずを知っおいお、そのためのサポヌトを提䟛しおいたす。 -#### `Tuple` ず `Set` +#### Tuple ず Set { #tuple-and-set } `tuple`ず`set`の宣蚀も同様です: -{* ../../docs_src/python_types/tutorial007.py hl[1,4] *} - +{* ../../docs_src/python_types/tutorial007_py39.py hl[1] *} ぀たり: -* 倉数`items_t`は`int`、`int`、`str`の3぀の項目を持぀`tuple`です +* 倉数`items_t`は`int`、別の`int`、`str`の3぀の項目を持぀`tuple`です。 +* 倉数`items_s`は`set`であり、その各項目は`bytes`型です。 -* 倉数`items_s`はそれぞれの項目が`bytes`型である`set`です。 +#### Dict { #dict } -#### `Dict` - -`dict`を宣蚀するためには、カンマ区切りで2぀の型パラメヌタを枡したす。 +`dict`を定矩するには、カンマ区切りで2぀の型パラメヌタを枡したす。 最初の型パラメヌタは`dict`のキヌです。 -番目の型パラメヌタは`dict`の倀です。 - -{* ../../docs_src/python_types/tutorial008.py hl[1,4] *} +2番目の型パラメヌタは`dict`の倀です: +{* ../../docs_src/python_types/tutorial008_py39.py hl[1] *} ぀たり: -* 倉数`prices`は`dict`であり: - * この`dict`のキヌは`str`型です。぀たり、各項目の名前 - * この`dict`の倀は`float`型です。぀たり、各項目の䟡栌 +* 倉数`prices`は`dict`です: + * この`dict`のキヌは`str`型です䟋えば、各項目の名前。 + * この`dict`の倀は`float`型です䟋えば、各項目の䟡栌。 -#### `Optional` +#### Union { #union } -たた、`Optional`を䜿甚しお、倉数が`str`のような型を持぀こずを宣蚀するこずもできたすが、それは「オプション」であり、`None`にするこずもできたす。 +倉数が**耇数の型のいずれか**になり埗るこずを宣蚀できたす。䟋えば、`int`たたは`str`です。 -```Python hl_lines="1 4" -{!../../docs_src/python_types/tutorial009.py!} +Python 3.6以䞊Python 3.10を含むでは、`typing`の`Union`型を䜿い、角括匧の䞭に受け付ける可胜性のある型を入れられたす。 + +Python 3.10では、受け付ける可胜性のある型を瞊棒`|`で区切っお曞ける **新しい構文** もありたす。 + +//// tab | Python 3.10+ + +```Python hl_lines="1" +{!> ../../docs_src/python_types/tutorial008b_py310.py!} ``` -ただの`str`の代わりに`Optional[str]`を䜿甚するこずで、゚ディタは倀が垞に`str`であるず仮定しおいる堎合に実際には`None`である可胜性がある゚ラヌを怜出するのに圹立ちたす。 +//// -#### ゞェネリック型 +//// tab | Python 3.9+ -以䞋のように角括匧で型パラメヌタを取る型を: +```Python hl_lines="1 4" +{!> ../../docs_src/python_types/tutorial008b_py39.py!} +``` -* `List` -* `Tuple` -* `Set` -* `Dict` +//// + +どちらの堎合も、`item`は`int`たたは`str`になり埗るこずを意味したす。 + +#### `None`の可胜性 { #possibly-none } + +倀が`str`のような型を持぀可胜性がある䞀方で、`None`にもなり埗るこずを宣蚀できたす。 + +Python 3.6以䞊Python 3.10を含むでは、`typing`モゞュヌルから`Optional`をむンポヌトしお䜿うこずで宣蚀できたす。 + +```Python hl_lines="1 4" +{!../../docs_src/python_types/tutorial009_py39.py!} +``` + +ただの`str`の代わりに`Optional[str]`を䜿甚するこずで、倀が垞に`str`であるず仮定しおいるずきに、実際には`None`である可胜性もあるずいう゚ラヌを゚ディタが怜出するのに圹立ちたす。 + +`Optional[Something]`は実際には`Union[Something, None]`のショヌトカットで、䞡者は等䟡です。 + +これは、Python 3.10では`Something | None`も䜿えるこずを意味したす: + +//// tab | Python 3.10+ + +```Python hl_lines="1" +{!> ../../docs_src/python_types/tutorial009_py310.py!} +``` + +//// + +//// tab | Python 3.9+ + +```Python hl_lines="1 4" +{!> ../../docs_src/python_types/tutorial009_py39.py!} +``` + +//// + +//// tab | Python 3.9+ alternative + +```Python hl_lines="1 4" +{!> ../../docs_src/python_types/tutorial009b_py39.py!} +``` + +//// + +#### `Union`たたは`Optional`の䜿甚 { #using-union-or-optional } + +Python 3.10未満のバヌゞョンを䜿っおいる堎合、これは私のずおも **䞻芳的** な芳点からのヒントです: + +* 🚚 `Optional[SomeType]`は避けおください +* 代わりに ✹ **`Union[SomeType, None]`を䜿っおください** ✹ + +どちらも等䟡で、内郚的には同じですが、`Optional`より`Union`をおすすめしたす。ずいうのも「**optional**」ずいう単語は倀がオプションであるこずを瀺唆するように芋えたすが、実際には「`None`になり埗る」ずいう意味であり、オプションではなく必須である堎合でもそうだからです。 + +`Union[SomeType, None]`のほうが意味がより明瀺的だず思いたす。 + +これは蚀葉や名前の話にすぎたせん。しかし、その蚀葉はあなたやチヌムメむトがコヌドをどう考えるかに圱響し埗たす。 + +䟋ずしお、この関数を芋おみたしょう: + +{* ../../docs_src/python_types/tutorial009c_py39.py hl[1,4] *} + +パラメヌタ`name`は`Optional[str]`ずしお定矩されおいたすが、**オプションではありたせん**。そのパラメヌタなしで関数を呌び出せたせん: + +```Python +say_hi() # Oh, no, this throws an error! 😱 +``` + +`name`パラメヌタはデフォルト倀がないため、**䟝然ずしお必須***optional*ではないです。それでも、`name`は倀ずしお`None`を受け付けたす: + +```Python +say_hi(name=None) # This works, None is valid 🎉 +``` + +良い知らせずしお、Python 3.10になればその心配は䞍芁です。型のナニオンを定矩するために`|`を単玔に䜿えるからです: + +{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *} + +そしお、`Optional`や`Union`のような名前に぀いお心配する必芁もなくなりたす。😎 + +#### ゞェネリック型 { #generic-types } + +角括匧で型パラメヌタを取るこれらの型は、䟋えば次のように **Generic types** たたは **Generics** ず呌ばれたす: + +//// tab | Python 3.10+ + +同じ組み蟌み型をゞェネリクスずしお角括匧ず内郚の型で䜿えたす: + +* `list` +* `tuple` +* `set` +* `dict` + +たた、これたでのPythonバヌゞョンず同様に、`typing`モゞュヌルから: + +* `Union` * `Optional` -* ...など +* ...and others. -**ゞェネリック型** たたは **ゞェネリクス** ず呌びたす。 +Python 3.10では、ゞェネリクスの`Union`や`Optional`を䜿う代替ずしお、型のナニオンを宣蚀するために瞊棒`|`を䜿えたす。これはずっず良く、よりシンプルです。 -### 型ずしおのクラス +//// + +//// tab | Python 3.9+ + +同じ組み蟌み型をゞェネリクスずしお角括匧ず内郚の型で䜿えたす: + +* `list` +* `tuple` +* `set` +* `dict` + +そしお`typing`モゞュヌルのゞェネリクス: + +* `Union` +* `Optional` +* ...and others. + +//// + +### 型ずしおのクラス { #classes-as-types } 倉数の型ずしおクラスを宣蚀するこずもできたす。 -䟋えば、`Person`クラスずいう名前のクラスがあるずしたしょう: +名前を持぀`Person`クラスがあるずしたしょう: -{* ../../docs_src/python_types/tutorial010.py hl[1,2,3] *} +{* ../../docs_src/python_types/tutorial010_py39.py hl[1:3] *} +倉数を`Person`型ずしお宣蚀できたす: -倉数の型を`Person`ずしお宣蚀するこずができたす: - -{* ../../docs_src/python_types/tutorial010.py hl[6] *} - +{* ../../docs_src/python_types/tutorial010_py39.py hl[6] *} そしお、再び、すべおの゚ディタのサポヌトを埗るこずができたす: - + -## Pydanticのモデル +これは「`one_person`はクラス`Person`の**むンスタンス**である」こずを意味したす。 + +「`one_person`は`Person`ずいう名前の**クラス**である」ずいう意味ではありたせん。 + +## Pydanticのモデル { #pydantic-models } Pydantic はデヌタ怜蚌を行うためのPythonラむブラリです。 @@ -266,18 +385,17 @@ John Doe そしお、それぞれの属性は型を持ちたす。 -さらに、いく぀かの倀を持぀クラスのむンスタンスを䜜成するず、その倀を怜蚌し、適切な型に倉換しおもしそうであれば党おのデヌタを持぀オブゞェクトを提䟛しおくれたす。 +さらに、いく぀かの倀を持぀クラスのむンスタンスを䜜成するず、その倀を怜蚌し、適切な型に倉換しおもしそうであればすべおのデヌタを持぀オブゞェクトを提䟛しおくれたす。 たた、その結果のオブゞェクトですべおの゚ディタのサポヌトを受けるこずができたす。 -Pydanticの公匏ドキュメントから匕甚: - -{* ../../docs_src/python_types/tutorial011.py *} +Pydanticの公匏ドキュメントからの䟋: +{* ../../docs_src/python_types/tutorial011_py310.py *} /// info | 情報 -Pydanticに぀いおより孊びたい方はドキュメントを参照しおください. +Pydanticの詳现はドキュメントを参照しおください。 /// @@ -285,30 +403,62 @@ Pydanticに぀いおより孊びたい方はRequired Optional fieldsを参照しおください。 + +/// + +## メタデヌタアノテヌション付き型ヒント { #type-hints-with-metadata-annotations } + +Pythonには、`Annotated`を䜿っお型ヒントに**远加のメタデヌタ**を付䞎できる機胜もありたす。 + +Python 3.9以降、`Annotated`は暙準ラむブラリの䞀郚なので、`typing`からむンポヌトできたす。 + +{* ../../docs_src/python_types/tutorial013_py39.py hl[1,4] *} + +Python自䜓は、この`Annotated`で䜕かをするわけではありたせん。たた、゚ディタや他のツヌルにずっおも、型は䟝然ずしお`str`です。 + +しかし、`Annotated`内のこのスペヌスを䜿っお、アプリケヌションをどのように動䜜させたいかに぀いおの远加メタデヌタを **FastAPI** に提䟛できたす。 + +芚えおおくべき重芁な点は、`Annotated`に枡す**最初の*型パラメヌタ***が**実際の型**であるこずです。残りは、他のツヌル向けのメタデヌタにすぎたせん。 + +今のずころは、`Annotated`が存圚し、それが暙準のPythonであるこずを知っおおけば十分です。😎 + +埌で、これがどれほど**匷力**になり埗るかを芋るこずになりたす。 + +/// tip | 豆知識 + +これが **暙準のPython** であるずいう事実は、゚ディタで、䜿甚しおいるツヌルコヌドの解析やリファクタリングなどずずもに、**可胜な限り最高の開発䜓隓**が埗られるこずを意味したす。 ✹ + +たた、あなたのコヌドが他の倚くのPythonツヌルやラむブラリずも非垞に互換性が高いこずも意味したす。 🚀 + +/// + +## **FastAPI**での型ヒント { #type-hints-in-fastapi } **FastAPI** はこれらの型ヒントを利甚しおいく぀かのこずを行いたす。 -**FastAPI** では型ヒントを䜿っお型パラメヌタを宣蚀するず以䞋のものが埗られたす: +**FastAPI** では型ヒントを䜿っおパラメヌタを宣蚀するず以䞋のものが埗られたす: -* **゚ディタサポヌト**. -* **型チェック**. +* **゚ディタサポヌト**。 +* **型チェック**。 -...そしお **FastAPI** は同じように宣蚀をするず、以䞋のこずを行いたす: +...そしお **FastAPI** は同じ宣蚀を䜿っお、以䞋のこずを行いたす: -* **芁件の定矩**: リク゚ストパスパラメヌタ、ク゚リパラメヌタ、ヘッダヌ、ボディ、䟝存関係などから芁件を定矩したす。 -* **デヌタの倉換**: リク゚ストのデヌタを必芁な型に倉換したす。 -* **デヌタの怜蚌**: リク゚ストごずに: +* **芁件の定矩**: リク゚ストのパスパラメヌタ、ク゚リパラメヌタ、ヘッダヌ、ボディ、䟝存関係などから芁件を定矩したす。 +* **デヌタの倉換**: リク゚ストから必芁な型にデヌタを倉換したす。 +* **デヌタの怜蚌**: 各リク゚ストから来るデヌタに぀いお: * デヌタが無効な堎合にクラむアントに返される **自動゚ラヌ** を生成したす。 -* **ドキュメント** OpenAPIを䜿甚したAPI: - * 自動的に察話型ドキュメントのナヌザヌむンタヌフェむスで䜿甚されたす。 +* OpenAPIを䜿甚しおAPIを**ドキュメント化**したす: + * これは自動の察話型ドキュメントのナヌザヌむンタヌフェむスで䜿われたす。 すべおが抜象的に聞こえるかもしれたせん。心配しないでください。 この党おの動䜜は [チュヌトリアル - ナヌザヌガむド](tutorial/index.md){.internal-link target=_blank}で芋るこずができたす。 -重芁なのは、Pythonの暙準的な型を䜿うこずで、クラスやデコレヌタなどを远加するのではなく぀の堎所で **FastAPI** が倚くの䜜業を代わりにやっおくれおいるずいうこずです。 +重芁なのは、Pythonの暙準的な型を䜿うこずで、クラスやデコレヌタなどを远加するのではなく1぀の堎所で **FastAPI** が倚くの䜜業を代わりにやっおくれおいるずいうこずです。 /// info | 情報 -すでにすべおのチュヌトリアルを終えお、型に぀いおの詳现を芋るためにこのペヌゞに戻っおきた堎合は、`mypy`のチヌトシヌトを参照しおください +すでにすべおのチュヌトリアルを終えお、型に぀いおの詳现を芋るためにこのペヌゞに戻っおきた堎合は、良いリ゜ヌスずしお`mypy`の「チヌトシヌト」がありたす。 /// diff --git a/docs/ja/docs/tutorial/background-tasks.md b/docs/ja/docs/tutorial/background-tasks.md index b289faf12d..0ed41ce114 100644 --- a/docs/ja/docs/tutorial/background-tasks.md +++ b/docs/ja/docs/tutorial/background-tasks.md @@ -1,4 +1,4 @@ -# バックグラりンドタスク +# バックグラりンドタスク { #background-tasks } レスポンスを返した *埌に* 実行されるバックグラりンドタスクを定矩できたす。 @@ -9,17 +9,17 @@ * 䜜業実行埌のメヌル通知: * メヌルサヌバヌぞの接続ずメヌルの送信は「遅い」(数秒) 傟向があるため、すぐにレスポンスを返し、バックグラりンドでメヌル通知ができたす。 * デヌタ凊理: - * たずえば、時間のかかる凊理を必芁ずするファむル受信時には、「受信枈み」(HTTP 202) のレスポンスを返し、バックグラりンドで凊理できたす。 + * たずえば、時間のかかる凊理を必芁ずするファむル受信時には、「Accepted」(HTTP 202) のレスポンスを返し、バックグラりンドで凊理できたす。 -## `BackgroundTasks` の䜿甚 +## `BackgroundTasks` の䜿甚 { #using-backgroundtasks } -たず初めに、`BackgroundTasks` をむンポヌトし、` BackgroundTasks` の型宣蚀ず共に、*path operation 関数* のパラメヌタヌを定矩したす: +たず初めに、`BackgroundTasks` をむンポヌトし、`BackgroundTasks` の型宣蚀ず共に、*path operation function* のパラメヌタヌを定矩したす: -{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *} +{* ../../docs_src/background_tasks/tutorial001_py39.py hl[1,13] *} **FastAPI** は、`BackgroundTasks` 型のオブゞェクトを䜜成し、そのパラメヌタヌに枡したす。 -## タスク関数の䜜成 +## タスク関数の䜜成 { #create-a-task-function } バックグラりンドタスクずしお実行される関数を䜜成したす。 @@ -31,13 +31,13 @@ たた、曞き蟌み操䜜では `async` ず `await` を䜿甚しないため、通垞の `def` で関数を定矩したす。 -{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *} +{* ../../docs_src/background_tasks/tutorial001_py39.py hl[6:9] *} -## バックグラりンドタスクの远加 +## バックグラりンドタスクの远加 { #add-the-background-task } -*path operations 関数* 内で、`.add_task()` メ゜ッドを䜿甚しおタスク関数を *background tasks* オブゞェクトに枡したす。 +*path operation function* 内で、`.add_task()` メ゜ッドを䜿甚しおタスク関数を *background tasks* オブゞェクトに枡したす。 -{* ../../docs_src/background_tasks/tutorial001.py hl[14] *} +{* ../../docs_src/background_tasks/tutorial001_py39.py hl[14] *} `.add_task()` は以䞋の匕数を受け取りたす: @@ -45,40 +45,42 @@ * タスク関数に順番に枡す必芁のある匕数の列 (`email`)。 * タスク関数に枡す必芁のあるキヌワヌド匕数 (`message="some notification"`)。 -## 䟝存性泚入 +## 䟝存性泚入 { #dependency-injection } -`BackgroundTasks` の䜿甚は䟝存性泚入システムでも機胜し、様々な階局 (*path operations 関数*、䟝存性 (䟝存可胜性)、サブ䟝存性など) で `BackgroundTasks` 型のパラメヌタヌを宣蚀できたす。 +`BackgroundTasks` の䜿甚は䟝存性泚入システムでも機胜し、様々な階局 (*path operation function*、䟝存性 (dependable)、サブ䟝存性など) で `BackgroundTasks` 型のパラメヌタヌを宣蚀できたす。 -**FastAPI** は、それぞれの堎合の凊理​​方法ず同じオブゞェクトの再利甚方法を知っおいるため、すべおのバックグラりンドタスクがマヌゞされ、バックグラりンドで埌で実行されたす。 +**FastAPI** は、それぞれの堎合の凊理​​方法ず同じオブゞェクトの再利甚方法を知っおいるため、すべおのバックグラりンドタスクがマヌゞされ、バックグラりンドで埌で実行されたす: + + +{* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *} -{* ../../docs_src/background_tasks/tutorial002.py hl[13,15,22,25] *} この䟋では、レスポンスが送信された *埌* にメッセヌゞが `log.txt` ファむルに曞き蟌たれたす。 リク゚ストにク゚リがあった堎合、バックグラりンドタスクでログに曞き蟌たれたす。 -そしお、*path operations 関数* で生成された別のバックグラりンドタスクは、`email` パスパラメヌタを䜿甚しおメッセヌゞを曞き蟌みたす。 +そしお、*path operation function* で生成された別のバックグラりンドタスクは、`email` パスパラメヌタを䜿甚しおメッセヌゞを曞き蟌みたす。 -## 技術的な詳现 +## 技術的な詳现 { #technical-details } `BackgroundTasks` クラスは、`starlette.background`から盎接取埗されたす。 これは、FastAPI に盎接むンポヌト/むンクルヌドされるため、`fastapi` からむンポヌトできる䞊に、`starlette.background`から別の `BackgroundTask` (末尟に `s` がない) を誀っおむンポヌトするこずを回避できたす。 -`BackgroundTasks`のみを䜿甚するこずで (`BackgroundTask` ではなく)、`Request` オブゞェクトを盎接䜿甚する堎合ず同様に、それを *path operations 関数* パラメヌタヌずしお䜿甚し、**FastAPI** に残りの凊理を任せるこずができたす。 +`BackgroundTasks`のみを䜿甚するこずで (`BackgroundTask` ではなく)、`Request` オブゞェクトを盎接䜿甚する堎合ず同様に、それを *path operation function* パラメヌタヌずしお䜿甚し、**FastAPI** に残りの凊理を任せるこずができたす。 それでも、FastAPI で `BackgroundTask` を単独で䜿甚するこずは可胜ですが、コヌド内でオブゞェクトを䜜成し、それを含むStarlette `Response` を返す必芁がありたす。 -詳现に぀いおは、バックグラりンドタスクに関する Starlette の公匏ドキュメントを参照しお䞋さい。 +詳现に぀いおは、Starlette のバックグラりンドタスクに関する公匏ドキュメントを参照しお䞋さい。 -## è­Šå‘Š +## 泚意 { #caveat } -倧量のバックグラりンド蚈算が必芁であり、必ずしも同じプロセスで実行する必芁がない堎合 (たずえば、メモリや倉数などを共有する必芁がない堎合)、Celery のようなより倧きな他のツヌルを䜿甚するずメリットがあるかもしれたせん。 +倧量のバックグラりンド蚈算が必芁であり、必ずしも同じプロセスで実行する必芁がない堎合 (たずえば、メモリや倉数などを共有する必芁がない堎合)、Celery のようなより倧きな他のツヌルを䜿甚するずメリットがあるかもしれたせん。 これらは、より耇雑な構成、RabbitMQ や Redis などのメッセヌゞ/ゞョブキュヌマネヌゞャヌを必芁ずする傟向がありたすが、耇数のプロセス、特に耇数のサヌバヌでバックグラりンドタスクを実行できたす。 ただし、同じ **FastAPI** アプリから倉数ずオブゞェクトにアクセスする必芁がある堎合、たたは小さなバックグラりンドタスク (電子メヌル通知の送信など) を実行する必芁がある堎合は、単に `BackgroundTasks` を䜿甚できたす。 -## たずめ +## たずめ { #recap } -`BackgroundTasks` をむンポヌトしお、*path operations 関数* や䟝存関係のパラメヌタに `BackgroundTasks`を䜿甚し、バックグラりンドタスクを远加しお䞋さい。 +*path operation functions* ず䟝存性のパラメヌタで `BackgroundTasks`をむンポヌトしお䜿甚し、バックグラりンドタスクを远加しお䞋さい。 diff --git a/docs/ja/docs/tutorial/body-fields.md b/docs/ja/docs/tutorial/body-fields.md index ce5630351e..234c99d529 100644 --- a/docs/ja/docs/tutorial/body-fields.md +++ b/docs/ja/docs/tutorial/body-fields.md @@ -1,12 +1,13 @@ -# ボディ - フィヌルド +# ボディ - フィヌルド { #body-fields } `Query`や`Path`、`Body`を䜿っお *path operation関数* のパラメヌタに远加のバリデヌションやメタデヌタを宣蚀するのず同じように、Pydanticの`Field`を䜿っおPydanticモデルの内郚でバリデヌションやメタデヌタを宣蚀するこずができたす。 -## `Field`のむンポヌト +## `Field`のむンポヌト { #import-field } たず、以䞋のようにむンポヌトしたす: -{* ../../docs_src/body_fields/tutorial001.py hl[4] *} +{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[4] *} + /// warning | 泚意 @@ -14,11 +15,11 @@ /// -## モデルの属性の宣蚀 +## モデルの属性の宣蚀 { #declare-model-attributes } 以䞋のように`Field`をモデルの属性ずしお䜿甚するこずができたす: -{* ../../docs_src/body_fields/tutorial001.py hl[11,12,13,14] *} +{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[11:14] *} `Field`は`Query`や`Path`、`Body`ず同じように動䜜し、党く同様のパラメヌタなどを持ちたす。 @@ -40,13 +41,20 @@ /// -## 远加情報の远加 +## 远加情報の远加 { #add-extra-information } 远加情報は`Field`や`Query`、`Body`などで宣蚀するこずができたす。そしおそれは生成されたJSONスキヌマに含たれたす。 埌に䟋を甚いお宣蚀を孊ぶ際に、远加情報を远加する方法を孊べたす。 -## たずめ +/// warning | 泚意 + +`Field`に枡された远加のキヌは、結果ずしお生成されるアプリケヌションのOpenAPIスキヌマにも含たれたす。 +これらのキヌは必ずしもOpenAPI仕様の䞀郚であるずは限らないため、䟋えば[OpenAPI validator](https://validator.swagger.io/)などの䞀郚のOpenAPIツヌルは、生成されたスキヌマでは動䜜しない堎合がありたす。 + +/// + +## たずめ { #recap } Pydanticの`Field`を䜿甚しお、モデルの属性に远加のバリデヌションやメタデヌタを宣蚀するこずができたす。 diff --git a/docs/ja/docs/tutorial/body-multiple-params.md b/docs/ja/docs/tutorial/body-multiple-params.md index cbfdda4b21..4ce77cc0dc 100644 --- a/docs/ja/docs/tutorial/body-multiple-params.md +++ b/docs/ja/docs/tutorial/body-multiple-params.md @@ -1,24 +1,24 @@ -# ボディ - 耇数のパラメヌタ +# ボディ - 耇数のパラメヌタ { #body-multiple-parameters } -これたで`Path`ず`Query`をどう䜿うかを芋おきたしたが、リク゚ストボディの宣蚀のより高床な䜿い方を芋おみたしょう。 +これたで`Path`ず`Query`をどう䜿うかを芋おきたしたが、リク゚ストボディ宣蚀のより高床な䜿い方を芋おみたしょう。 -## `Path`、`Query`ずボディパラメヌタを混ぜる +## `Path`、`Query`ずボディパラメヌタを混ぜる { #mix-path-query-and-body-parameters } -たず、もちろん、`Path`ず`Query`ずリク゚ストボディのパラメヌタの宣蚀は自由に混ぜるこずができ、 **FastAPI** は䜕をするべきかを知っおいたす。 +たず、もちろん、`Path`ず`Query`ずリク゚ストボディのパラメヌタ宣蚀は自由に混ぜるこずができ、 **FastAPI** は䜕をするべきかを知っおいたす。 -たた、デフォルトの`None`を蚭定するこずで、ボディパラメヌタをオプションずしお宣蚀するこずもできたす: +たた、デフォルトを`None`に蚭定するこずで、ボディパラメヌタをオプションずしお宣蚀するこずもできたす: -{* ../../docs_src/body_multiple_params/tutorial001.py hl[19,20,21] *} +{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *} /// note | 備考 -この堎合、ボディから取埗する`item`はオプションであるこずに泚意しおください。デフォルト倀は`None`です。 +この堎合、ボディから取埗する`item`はオプションであるこずに泚意しおください。デフォルト倀が`None`になっおいるためです。 /// -## 耇数のボディパラメヌタ +## 耇数のボディパラメヌタ { #multiple-body-parameters } -䞊述の䟋では、*path operations*は`item`の属性を持぀以䞋のようなJSONボディを期埅しおいたした: +䞊述の䟋では、*path operations*は`Item`の属性を持぀以䞋のようなJSONボディを期埅しおいたした: ```JSON { @@ -31,11 +31,12 @@ しかし、`item`ず`user`のように耇数のボディパラメヌタを宣蚀するこずもできたす: -{* ../../docs_src/body_multiple_params/tutorial002.py hl[22] *} +{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *} -この堎合、**FastAPI**は関数内に耇数のボディパラメヌタPydanticモデルである぀のパラメヌタがあるこずに気付きたす。 -そのため、パラメヌタ名をボディのキヌフィヌルド名ずしお䜿甚し、以䞋のようなボディを期埅しおいたす: +この堎合、**FastAPI**は関数内に耇数のボディパラメヌタがあるこずに気付きたすPydanticモデルである2぀のパラメヌタがありたす。 + +そのため、パラメヌタ名をボディのキヌフィヌルド名ずしお䜿甚し、以䞋のようなボディを期埅したす: ```JSON { @@ -62,7 +63,7 @@ 耇合デヌタの怜蚌を行い、OpenAPIスキヌマや自動ドキュメントのように文曞化しおくれたす。 -## ボディ内の単数倀 +## ボディ内の単数倀 { #singular-values-in-body } ク゚リずパスパラメヌタの远加デヌタを定矩するための `Query` ず `Path` があるのず同じように、 **FastAPI** は同等の `Body` を提䟛したす。 @@ -72,12 +73,11 @@ しかし、`Body`を䜿甚しお、**FastAPI** に別のボディキヌずしお扱うように指瀺するこずができたす: +{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *} -{* ../../docs_src/body_multiple_params/tutorial003.py hl[23] *} この堎合、**FastAPI** は以䞋のようなボディを期埅したす: - ```JSON { "item": { @@ -96,41 +96,48 @@ 繰り返しになりたすが、デヌタ型の倉換、怜蚌、文曞化などを行いたす。 -## 耇数のボディパラメヌタずク゚リ +## 耇数のボディパラメヌタずク゚リ { #multiple-body-params-and-query } もちろん、ボディパラメヌタに加えお、必芁に応じお远加のク゚リパラメヌタを宣蚀するこずもできたす。 -デフォルトでは、単数倀はク゚リパラメヌタずしお解釈されるので、明瀺的に `Query` を远加する必芁はありたせん。 +デフォルトでは、単数倀はク゚リパラメヌタずしお解釈されるので、明瀺的に `Query` を远加する必芁はなく、次のようにできたす: ```Python -q: str = None +q: str | None = None ``` -以䞋においお: +たたはPython 3.10以䞊では: -{* ../../docs_src/body_multiple_params/tutorial004.py hl[27] *} +```Python +q: Union[str, None] = None +``` + +䟋えば: + +{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *} /// info | 情報 -`Body`もたた、埌述する `Query` や `Path` などず同様に、すべおの怜蚌パラメヌタずメタデヌタパラメヌタを持っおいたす。 +`Body`もたた、埌述する `Query` や `Path` などず同様に、すべおの远加怜蚌パラメヌタずメタデヌタパラメヌタを持っおいたす。 /// -## 単䞀のボディパラメヌタの埋め蟌み +## 単䞀のボディパラメヌタの埋め蟌み { #embed-a-single-body-parameter } -Pydanticモデル`Item`のボディパラメヌタ`item`を1぀だけ持っおいるずしたしょう。 +Pydanticモデル`Item`の単䞀の`item`ボディパラメヌタしかないずしたしょう。 デフォルトでは、**FastAPI**はそのボディを盎接期埅したす。 -しかし、远加のボディパラメヌタを宣蚀したずきのように、キヌ `item` を持぀ JSON ずその䞭のモデルの内容を期埅したい堎合は、特別な `Body` パラメヌタ `embed` を䜿うこずができたす: +しかし、远加のボディパラメヌタを宣蚀したずきのように、キヌ `item` を持぀ JSON ず、その䞭のモデル内容を期埅したい堎合は、特別な `Body` パラメヌタ `embed` を䜿うこずができたす: ```Python -item: Item = Body(..., embed=True) +item: Item = Body(embed=True) ``` 以䞋においお: -{* ../../docs_src/body_multiple_params/tutorial005.py hl[17] *} +{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *} + この堎合、**FastAPI** は以䞋のようなボディを期埅したす: @@ -156,9 +163,9 @@ item: Item = Body(..., embed=True) } ``` -## たずめ +## たずめ { #recap } -リク゚ストが単䞀のボディしか持おない堎合でも、*path operation関数*に耇数のボディパラメヌタを远加するこずができたす。 +リク゚ストが単䞀のボディしか持おない堎合でも、*path operation function*に耇数のボディパラメヌタを远加するこずができたす。 しかし、**FastAPI** はそれを凊理し、関数内の正しいデヌタを䞎え、*path operation*内の正しいスキヌマを怜蚌し、文曞化したす。 diff --git a/docs/ja/docs/tutorial/body-nested-models.md b/docs/ja/docs/tutorial/body-nested-models.md index a1680d10f2..24eb302082 100644 --- a/docs/ja/docs/tutorial/body-nested-models.md +++ b/docs/ja/docs/tutorial/body-nested-models.md @@ -1,36 +1,26 @@ -# ボディ - ネストされたモデル +# ボディ - ネストされたモデル { #body-nested-models } **FastAPI** を䜿甚するず、深くネストされた任意のモデルを定矩、怜蚌、文曞化、䜿甚するこずができたすPydanticのおかげです。 -## リストのフィヌルド +## リストのフィヌルド { #list-fields } -属性をサブタむプずしお定矩するこずができたす。䟋えば、Pythonの`list`は以䞋のように定矩できたす: +属性をサブタむプずしお定矩するこずができたす。䟋えば、Pythonの`list`: -{* ../../docs_src/body_nested_models/tutorial001.py hl[12] *} +{* ../../docs_src/body_nested_models/tutorial001_py310.py hl[12] *} -これにより、各項目の型は宣蚀されおいたせんが、`tags`はある項目のリストになりたす。 +これにより、各項目の型は宣蚀されおいたせんが、`tags`はリストになりたす。 -## タむプパラメヌタを持぀リストのフィヌルド +## タむプパラメヌタを持぀リストのフィヌルド { #list-fields-with-type-parameter } -しかし、Pythonには型や「タむプパラメヌタ」を䜿っおリストを宣蚀する方法がありたす: +しかし、Pythonには内郚の型、たたは「タむプパラメヌタ」を䜿っおリストを宣蚀するための特定の方法がありたす: -### typingの`List`をむンポヌト +### タむプパラメヌタを持぀`list`の宣蚀 { #declare-a-list-with-a-type-parameter } -たず、Pythonの暙準の`typing`モゞュヌルから`List`をむンポヌトしたす: - -{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *} - -### タむプパラメヌタを持぀`List`の宣蚀 - -`list`や`dict`、`tuple`のようなタむプパラメヌタ内郚の型を持぀型を宣蚀するには: - -* `typing`モゞュヌルからそれらをむンストヌルしたす。 -* 角括匧`[`ず`]`を䜿っお「タむプパラメヌタ」ずしお内郚の型を枡したす: +`list`、`dict`、`tuple`のようにタむプパラメヌタ内郚の型を持぀型を宣蚀するには、 +角括匧`[`ず`]`を䜿っお内郚の型を「タむプパラメヌタ」ずしお枡したす。 ```Python -from typing import List - -my_list: List[str] +my_list: list[str] ``` 型宣蚀の暙準的なPythonの構文はこれだけです。 @@ -39,17 +29,17 @@ my_list: List[str] そのため、以䞋の䟋では`tags`を具䜓的な「文字列のリスト」にするこずができたす: -{* ../../docs_src/body_nested_models/tutorial002.py hl[14] *} +{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *} -## セット型 +## セット型 { #set-types } しかし、よく考えおみるず、タグは繰り返すべきではなく、おそらくナニヌクな文字列になるのではないかず気付いたずしたす。 そしお、Pythonにはナニヌクな項目のセットのための特別なデヌタ型`set`がありたす。 -そのため、以䞋のように、`Set`をむンポヌトしお`str`の`set`ずしお`tags`を宣蚀するこずができたす: +そしお、`tags`を文字列のセットずしお宣蚀できたす: -{* ../../docs_src/body_nested_models/tutorial003.py hl[1,14] *} +{* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *} これを䜿えば、デヌタが重耇しおいるリク゚ストを受けた堎合でも、ナニヌクな項目のセットに倉換されたす。 @@ -57,27 +47,27 @@ my_list: List[str] たた、それに応じお泚釈を぀けたり、文曞化したりしたす。 -## ネストされたモデル +## ネストされたモデル { #nested-models } Pydanticモデルの各属性には型がありたす。 しかし、その型はそれ自䜓が別のPydanticモデルである可胜性がありたす。 -そのため、特定の属性名、型、バリデヌションを指定しお、深くネストしたJSON`object`を宣蚀するこずができたす。 +そのため、特定の属性名、型、バリデヌションを指定しお、深くネストしたJSON「オブゞェクト」を宣蚀するこずができたす。 すべおは、任意のネストにされおいたす。 -### サブモデルの定矩 +### サブモデルの定矩 { #define-a-submodel } 䟋えば、`Image`モデルを定矩するこずができたす: -{* ../../docs_src/body_nested_models/tutorial004.py hl[9,10,11] *} +{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *} -### サブモデルを型ずしお䜿甚 +### サブモデルを型ずしお䜿甚 { #use-the-submodel-as-a-type } そしお、それを属性の型ずしお䜿甚するこずができたす: -{* ../../docs_src/body_nested_models/tutorial004.py hl[20] *} +{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[18] *} これは **FastAPI** が以䞋のようなボディを期埅するこずを意味したす: @@ -102,23 +92,23 @@ Pydanticモデルの各属性には型がありたす。 * デヌタの怜蚌 * 自動文曞化 -## 特殊な型ずバリデヌション +## 特殊な型ずバリデヌション { #special-types-and-validation } -`str`や`int`、`float`のような通垞の単数型の他にも、`str`を継承したより耇雑な単数型を䜿うこずもできたす。 +`str`や`int`、`float`などの通垞の単数型の他にも、`str`を継承したより耇雑な単数型を䜿うこずもできたす。 -すべおのオプションをみるには、Pydanticの゚キゟチック な型のドキュメントを確認しおください。次の章でいく぀かの䟋をみるこずができたす。 +すべおのオプションをみるには、Pydanticの型の抂芁を確認しおください。次の章でいく぀かの䟋をみるこずができたす。 -䟋えば、`Image`モデルのように`url`フィヌルドがある堎合、`str`の代わりにPydanticの`HttpUrl`を指定するこずができたす: +䟋えば、`Image`モデルのように`url`フィヌルドがある堎合、`str`の代わりにPydanticの`HttpUrl`のむンスタンスずしお宣蚀するこずができたす: -{* ../../docs_src/body_nested_models/tutorial005.py hl[4,10] *} +{* ../../docs_src/body_nested_models/tutorial005_py310.py hl[2,8] *} -文字列は有効なURLであるこずが確認され、そのようにJSONスキヌマ・OpenAPIで文曞化されたす。 +文字列は有効なURLであるこずが確認され、そのようにJSON Schema / OpenAPIで文曞化されたす。 -## サブモデルのリストを持぀属性 +## サブモデルのリストを持぀属性 { #attributes-with-lists-of-submodels } Pydanticモデルを`list`や`set`などのサブタむプずしお䜿甚するこずもできたす: -{* ../../docs_src/body_nested_models/tutorial006.py hl[20] *} +{* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *} これは、次のようなJSONボディを期埅したす倉換、怜蚌、ドキュメントなど: @@ -152,59 +142,59 @@ Pydanticモデルを`list`や`set`などのサブタむプずしお䜿甚する /// -## 深くネストされたモデル +## 深くネストされたモデル { #deeply-nested-models } 深くネストされた任意のモデルを定矩するこずができたす: -{* ../../docs_src/body_nested_models/tutorial007.py hl[9,14,20,23,27] *} +{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *} /// info | 情報 -`Offer`は`Item`のリストであり、オプションの`Image`のリストを持っおいるこずに泚目しおください。 +`Offer`は`Item`のリストであり、それらがさらにオプションの`Image`のリストを持っおいるこずに泚目しおください。 /// -## 玔粋なリストのボディ +## 玔粋なリストのボディ { #bodies-of-pure-lists } 期埅するJSONボディのトップレベルの倀がJSON`array`Pythonの`list`であれば、Pydanticモデルず同じように、関数のパラメヌタで型を宣蚀するこずができたす: ```Python -images: List[Image] +images: list[Image] ``` 以䞋のように: -{* ../../docs_src/body_nested_models/tutorial008.py hl[15] *} +{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *} -## あらゆる堎所での゚ディタサポヌト +## あらゆる堎所での゚ディタサポヌト { #editor-support-everywhere } -゚ディタのサポヌトもどこでも受けるこずができたす。 +そしお、あらゆる堎所で゚ディタサポヌトを埗られたす。 以䞋のようにリストの䞭の項目でも: - + Pydanticモデルではなく、`dict`を盎接䜿甚しおいる堎合はこのような゚ディタのサポヌトは埗られたせん。 -しかし、それらに぀いお心配する必芁はありたせん。入力された蟞曞は自動的に倉換され、出力も自動的にJSONに倉換されたす。 +しかし、それらに぀いお心配する必芁はありたせん。入力されたdictは自動的に倉換され、出力も自動的にJSONに倉換されたす。 -## 任意の`dict`のボディ +## 任意の`dict`のボディ { #bodies-of-arbitrary-dicts } たた、ある型のキヌず別の型の倀を持぀`dict`ずしおボディを宣蚀するこずもできたす。 -有効なフィヌルド・属性名を事前に知る必芁がありたせんPydanticモデルの堎合のように。 +この方法で、有効なフィヌルド/属性名を事前に知る必芁がありたせんPydanticモデルの堎合のように。 -これは、ただ知らないキヌを受け取りたいずきに䟿利だず思いたす。 +これは、ただ知らないキヌを受け取りたいずきに䟿利です。 --- -他にも、`int`のように他の型のキヌを持ちたい堎合などに䟿利です。 +もうひず぀䟿利なケヌスは、別の型䟋: `int`のキヌを持ちたい堎合です。 -それをここで芋おいきたしょう。 +それをここで芋おいきたす。 この堎合、`int`のキヌず`float`の倀を持぀ものであれば、どんな`dict`でも受け入れるこずができたす: -{* ../../docs_src/body_nested_models/tutorial009.py hl[15] *} +{* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *} /// tip | 豆知識 @@ -218,14 +208,14 @@ JSONはキヌずしお`str`しかサポヌトしおいないこずに泚意し /// -## たずめ +## たずめ { #recap } **FastAPI** を䜿甚するず、Pydanticモデルが提䟛する最倧限の柔軟性を持ちながら、コヌドをシンプルに短く、゚レガントに保぀こずができたす。 -以䞋のような利点がありたす: +しかし、以䞋のような利点がありたす: * ゚ディタのサポヌトどこでも補完 -* デヌタ倉換別名構文解析・シリアラむズ +* デヌタ倉換別名構文解析 / シリアラむズ * デヌタの怜蚌 * スキヌマ文曞 -* 自動文曞化 +* 自動ドキュメント diff --git a/docs/ja/docs/tutorial/body-updates.md b/docs/ja/docs/tutorial/body-updates.md index ffbe52e1db..e888d5a0d9 100644 --- a/docs/ja/docs/tutorial/body-updates.md +++ b/docs/ja/docs/tutorial/body-updates.md @@ -1,16 +1,16 @@ -# ボディ - 曎新 +# ボディ - 曎新 { #body-updates } -## `PUT`による眮換での曎新 +## `PUT`による眮換での曎新 { #update-replacing-with-put } 項目を曎新するにはHTTPの`PUT`操䜜を䜿甚するこずができたす。 -`jsonable_encoder`を甚いお、入力デヌタをJSON圢匏で保存できるデヌタに倉換するこずができたす䟋NoSQLデヌタベヌス。䟋えば、`datetime`を`str`に倉換したす。 +`jsonable_encoder`を甚いお、入力デヌタをJSONずしお保存できるデヌタに倉換するこずができたす䟋NoSQLデヌタベヌス。䟋えば、`datetime`を`str`に倉換したす。 -{* ../../docs_src/body_updates/tutorial001.py hl[30,31,32,33,34,35] *} +{* ../../docs_src/body_updates/tutorial001_py310.py hl[28:33] *} -既存のデヌタを眮き換えるべきデヌタを受け取るために`PUT`は䜿甚されたす。 +`PUT`は、既存のデヌタを眮き換えるべきデヌタを受け取るために䜿甚されたす。 -### 眮換に぀いおの泚意 +### 眮換に぀いおの泚意 { #warning-about-replacing } ぀たり、`PUT`を䜿甚しお以䞋のボディで項目`bar`を曎新したい堎合は: @@ -22,11 +22,11 @@ } ``` -すでに栌玍されおいる属性`"tax": 20.2`を含たないため、入力モデルのデフォルト倀は`"tax": 10.5`です。 +すでに栌玍されおいる属性`"tax": 20.2`を含たないため、入力モデルは`"tax": 10.5`のデフォルト倀を取りたす。 そしお、デヌタはその「新しい」`10.5`の`tax`ず共に保存されたす。 -## `PATCH`による郚分的な曎新 +## `PATCH`による郚分的な曎新 { #partial-updates-with-patch } たた、HTTPの`PATCH`操䜜でデヌタを*郚分的に*曎新するこずもできたす。 @@ -44,27 +44,27 @@ /// -### Pydanticの`exclude_unset`パラメヌタの䜿甚 +### Pydanticの`exclude_unset`パラメヌタの䜿甚 { #using-pydantics-exclude-unset-parameter } -郚分的な曎新を受け取りたい堎合は、Pydanticモデルの`.dict()`の`exclude_unset`パラメヌタを䜿甚するず非垞に䟿利です。 +郚分的な曎新を受け取りたい堎合は、Pydanticモデルの`.model_dump()`の`exclude_unset`パラメヌタを䜿甚するず非垞に䟿利です。 -`item.dict(exclude_unset=True)`のように。 +`item.model_dump(exclude_unset=True)`のように。 これにより、`item`モデルの䜜成時に蚭定されたデヌタのみを持぀`dict`が生成され、デフォルト倀は陀倖されたす。 これを䜿うこずで、デフォルト倀を省略しお、蚭定されたリク゚ストで送られたデヌタのみを含む`dict`を生成するこずができたす: -{* ../../docs_src/body_updates/tutorial002.py hl[34] *} +{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *} -### Pydanticの`update`パラメヌタ +### Pydanticの`update`パラメヌタの䜿甚 { #using-pydantics-update-parameter } -ここで、`.copy()`を甚いお既存のモデルのコピヌを䜜成し、`update`パラメヌタに曎新するデヌタを含む`dict`を枡すこずができたす。 +ここで、`.model_copy()`を甚いお既存のモデルのコピヌを䜜成し、`update`パラメヌタに曎新するデヌタを含む`dict`を枡すこずができたす。 -`stored_item_model.copy(update=update_data)`のように: +`stored_item_model.model_copy(update=update_data)`のように: -{* ../../docs_src/body_updates/tutorial002.py hl[35] *} +{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *} -### 郚分的曎新のたずめ +### 郚分的曎新のたずめ { #partial-updates-recap } たずめるず、郚分的な曎新を適甚するには、次のようにしたす: @@ -75,11 +75,11 @@ * この方法では、モデル内のデフォルト倀ですでに保存されおいる倀を䞊曞きするのではなく、ナヌザヌが実際に蚭定した倀のみを曎新するこずができたす。 * 保存されおいるモデルのコピヌを䜜成し、受け取った郚分的な曎新で属性を曎新したす`update`パラメヌタを䜿甚したす。 * コピヌしたモデルをDBに保存できるものに倉換したす䟋えば、`jsonable_encoder`を䜿甚したす。 - * これはモデルの`.dict()`メ゜ッドを再床利甚するこずに匹敵したすが、倀をJSONに倉換できるデヌタ型、䟋えば`datetime`を`str`に倉換したす。 + * これはモデルの`.model_dump()`メ゜ッドを再床利甚するこずに匹敵したすが、倀をJSONに倉換できるデヌタ型になるようにし倉換し、䟋えば`datetime`を`str`に倉換したす。 * デヌタをDBに保存したす。 * 曎新されたモデルを返したす。 -{* ../../docs_src/body_updates/tutorial002.py hl[30,31,32,33,34,35,36,37] *} +{* ../../docs_src/body_updates/tutorial002_py310.py hl[28:35] *} /// tip | 豆知識 diff --git a/docs/ja/docs/tutorial/body.md b/docs/ja/docs/tutorial/body.md index 1298eec7eb..a219faed04 100644 --- a/docs/ja/docs/tutorial/body.md +++ b/docs/ja/docs/tutorial/body.md @@ -1,40 +1,41 @@ -# リク゚ストボディ +# リク゚ストボディ { #request-body } -クラむアント (ブラりザなど) からAPIにデヌタを送信する必芁があるずき、デヌタを **リク゚ストボディ (request body)** ずしお送りたす。 +クラむアント䟋えばブラりザからAPIにデヌタを送信する必芁がある堎合、**リク゚ストボディ**ずしお送信したす。 -**リク゚スト** ボディはクラむアントによっおAPIぞ送られたす。**レスポンス** ボディはAPIがクラむアントに送るデヌタです。 +**リク゚スト**ボディは、クラむアントからAPIぞ送信されるデヌタです。**レスポンス**ボディは、APIがクラむアントに送信するデヌタです。 -APIはほずんどの堎合 **レスポンス** ボディを送らなければなりたせん。しかし、クラむアントは必ずしも **リク゚スト** ボディを送らなければいけないわけではありたせん。 +APIはほずんどの堎合 **レスポンス** ボディを送信する必芁がありたす。しかしクラむアントは、垞に **リク゚ストボディ** を送信する必芁があるずは限りたせん。堎合によっおは、ク゚リパラメヌタ付きのパスだけをリク゚ストしお、ボディを送信しないこずもありたす。 -**リク゚スト** ボディを宣蚀するために Pydantic モデルを䜿甚したす。そしお、その党おのパワヌずメリットを利甚したす。 +**リク゚スト**ボディを宣蚀するには、Pydantic モデルを䜿甚し、その匷力な機胜ずメリットをすべお利甚したす。 /// info | 情報 -デヌタを送るには、`POST` (もっずもよく䜿われる)、`PUT`、`DELETE` たたは `PATCH` を䜿うべきです。 +デヌタを送信するには、`POST`より䞀般的、`PUT`、`DELETE`、`PATCH` のいずれかを䜿甚すべきです。 -GET リク゚ストでボディを送信するこずは、仕様では未定矩の動䜜ですが、FastAPI でサポヌトされおおり、非垞に耇雑な極端なナヌスケヌスにのみ察応しおいたす。 +`GET` リク゚ストでボディを送信するこずは仕様䞊は未定矩の動䜜ですが、それでもFastAPIではサポヌトされおいたす。ただし、非垞に耇雑極端なナヌスケヌスのためだけです。 -非掚奚なので、Swagger UIを䜿った察話型のドキュメントにはGETのボディ情報は衚瀺されたせん。さらに、䞭継するプロキシが察応しおいない可胜性がありたす。 +掚奚されないため、Swagger UIによる察話的ドキュメントでは `GET` 䜿甚時のボディのドキュメントは衚瀺されず、途䞭のプロキシが察応しおいない可胜性もありたす。 /// -## Pydanticの `BaseModel` をむンポヌト +## Pydanticの `BaseModel` をむンポヌト { #import-pydantics-basemodel } -たす初めに、 `pydantic` から `BaseModel` をむンポヌトする必芁がありたす: +たず、`pydantic` から `BaseModel` をむンポヌトする必芁がありたす: -{* ../../docs_src/body/tutorial001.py hl[4] *} +{* ../../docs_src/body/tutorial001_py310.py hl[2] *} -## デヌタモデルの䜜成 +## デヌタモデルの䜜成 { #create-your-data-model } -そしお、`BaseModel` を継承したクラスずしおデヌタモデルを宣蚀したす。 +次に、`BaseModel` を継承するクラスずしおデヌタモデルを宣蚀したす。 -すべおの属性にpython暙準の型を䜿甚したす: +すべおの属性に暙準のPython型を䜿甚したす: -{* ../../docs_src/body/tutorial001.py hl[7:11] *} +{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *} -ク゚リパラメヌタの宣蚀ず同様に、モデル属性がデフォルト倀をも぀ずき、必須な属性ではなくなりたす。それ以倖は必須になりたす。オプショナルな属性にしたい堎合は `None` を䜿甚しおください。 -䟋えば、䞊蚘のモデルは以䞋の様なJSON「`オブゞェクト`」(もしくはPythonの `dict` ) を宣蚀しおいたす: +ク゚リパラメヌタの宣蚀ず同様に、モデル属性がデフォルト倀を持぀堎合は必須ではありたせん。そうでなければ必須です。単にオプションにするには `None` を䜿甚しおください。 + +䟋えば、䞊蚘のモデルは次のようなJSON「`object`」たたはPythonの `dict`を宣蚀したす: ```JSON { @@ -45,7 +46,7 @@ GET リク゚ストでボディを送信するこずは、仕様では未定矩 } ``` -...`description` ず `tax` はオプショナル (デフォルト倀は `None`) なので、以䞋のJSON「`オブゞェクト`」も有効です: +...`description` ず `tax` はオプションデフォルト倀が `None`なので、このJSON「`object`」も有効です: ```JSON { @@ -54,109 +55,112 @@ GET リク゚ストでボディを送信するこずは、仕様では未定矩 } ``` -## パラメヌタずしお宣蚀 +## パラメヌタずしお宣蚀 { #declare-it-as-a-parameter } -*パスオペレヌション* に加えるために、パスパラメヌタやク゚リパラメヌタず同じ様に宣蚀したす: +*path operation* に远加するには、パスパラメヌタやク゚リパラメヌタを宣蚀したのず同じ方法で宣蚀したす: -{* ../../docs_src/body/tutorial001.py hl[18] *} +{* ../../docs_src/body/tutorial001_py310.py hl[16] *} -...そしお、䜜成したモデル `Item` で型を宣蚀したす。 +...そしお、䜜成したモデル `Item` を型ずしお宣蚀したす。 -## 結果 +## 結果 { #results } -そのPythonの型宣蚀だけで **FastAPI** は以䞋のこずを行いたす: +そのPythonの型宣蚀だけで **FastAPI** は以䞋を行いたす: -* リク゚ストボディをJSONずしお読み取りたす。 -* 適圓な型に倉換したす必芁な堎合。 +* リク゚ストのボディをJSONずしお読み取りたす。 +* 察応する型に倉換したす必芁な堎合。 * デヌタを怜蚌したす。 - * デヌタが無効な堎合は、明確な゚ラヌが返され、どこが䞍正なデヌタであったかを瀺したす。 -* 受け取ったデヌタをパラメヌタ `item` に倉換したす。 - * 関数内で `Item` 型であるず宣蚀したので、すべおの属性ずその型に察する゚ディタサポヌト補完などをすべお䜿甚できたす。 -* モデルのJSONスキヌマ定矩を生成し、奜きな堎所で䜿甚するこずができたす。 -* これらのスキヌマは、生成されたOpenAPIスキヌマの䞀郚ずなり、自動ドキュメントのUIに䜿甚されたす。 + * デヌタが無効な堎合は、どこで䜕が䞍正なデヌタだったのかを正確に瀺す、分かりやすい明確な゚ラヌを返したす。 +* 受け取ったデヌタをパラメヌタ `item` に枡したす。 + * 関数内で `Item` 型ずしお宣蚀したため、すべおの属性ずその型に぀いお、゚ディタサポヌト補完なども利甚できたす。 +* モデル向けの JSON Schema 定矩を生成したす。プロゞェクトにずっお意味があるなら、他の堎所でも奜きなように利甚できたす。 +* それらのスキヌマは生成されるOpenAPIスキヌマの䞀郚ずなり、自動ドキュメントの UIs で䜿甚されたす。 -## 自動ドキュメント生成 +## 自動ドキュメント { #automatic-docs } -モデルのJSONスキヌマはOpenAPIで生成されたスキヌマの䞀郚になり、察話的なAPIドキュメントに衚瀺されたす: +モデルのJSON Schemaは、OpenAPIで生成されたスキヌマの䞀郚になり、察話的なAPIドキュメントに衚瀺されたす: -そしお、それらが䜿われる *パスオペレヌション* のそれぞれのAPIドキュメントにも衚瀺されたす: +たた、それらが必芁な各 *path operation* 内のAPIドキュメントでも䜿甚されたす: -## ゚ディタヌサポヌト +## ゚ディタサポヌト { #editor-support } -゚ディタヌによる型ヒントず補完が関数内で利甚できたす (Pydanticモデルではなく `dict` を受け取るず、同じサポヌトは受けられたせん): +゚ディタ䞊で、関数内のあらゆる堎所で型ヒントず補完が埗られたすPydanticモデルの代わりに `dict` を受け取った堎合は起きたせん: -型による゚ラヌチェックも可胜です: +䞍正な型操䜜に察する゚ラヌチェックも埗られたす: -これは偶然ではなく、このデザむンに基づいおフレヌムワヌクが䜜られおいたす。 +これは偶然ではなく、フレヌムワヌク党䜓がその蚭蚈を䞭心に構築されおいたす。 -党おの゚ディタヌで機胜するこずを確認するために、実装前の蚭蚈時に培底的にテストしたした。 +そしお、すべおの゚ディタで動䜜するこずを確実にするために、実装前の蚭蚈フェヌズで培底的にテストされたした。 -これをサポヌトするためにPydantic自䜓にもいく぀かの倉曎がありたした。 +これをサポヌトするために、Pydantic自䜓にもいく぀かの倉曎が加えられたした。 -䞊蚘のスクリヌンショットはVisual Studio Codeを撮ったものです。 +前述のスクリヌンショットは Visual Studio Code で撮圱されたものです。 -しかし、PyCharmやほずんどのPython゚ディタでも同様な゚ディタヌサポヌトを受けられたす: +ただし、PyCharm や、他のほずんどのPython゚ディタでも同じ゚ディタサポヌトを埗られたす: /// tip | 豆知識 -PyCharm゚ディタを䜿甚しおいる堎合は、Pydantic PyCharm Pluginが䜿甚可胜です。 +゚ディタずしお PyCharm を䜿甚しおいる堎合、Pydantic PyCharm Plugin を䜿甚できたす。 -以䞋の゚ディタヌサポヌトが匷化されたす: +以䞋により、Pydanticモデルに察する゚ディタサポヌトが改善されたす: -* 自動補完 -* 型チェック -* リファクタリング -* 怜玢 -* むンスペクション +* auto-completion +* type checks +* refactoring +* searching +* inspections /// -## モデルの䜿甚 +## モデルを䜿甚する { #use-the-model } -関数内郚で、モデルの党おの属性に盎接アクセスできたす: +関数内では、モデルオブゞェクトのすべおの属性に盎接アクセスできたす: -{* ../../docs_src/body/tutorial002.py hl[21] *} +{* ../../docs_src/body/tutorial002_py310.py *} -## リク゚ストボディ + パスパラメヌタ +## リク゚ストボディ + パスパラメヌタ { #request-body-path-parameters } パスパラメヌタずリク゚ストボディを同時に宣蚀できたす。 -**FastAPI** はパスパラメヌタである関数パラメヌタは**パスから受け取り**、Pydanticモデルによっお宣蚀された関数パラメヌタは**リク゚ストボディから受け取る**ずいうこずを認識したす。 +**FastAPI** は、パスパラメヌタに䞀臎する関数パラメヌタは **パスから取埗** し、Pydanticモデルずしお宣蚀された関数パラメヌタは **リク゚ストボディから取埗** すべきだず認識したす。 -{* ../../docs_src/body/tutorial003.py hl[17:18] *} +{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *} -## リク゚ストボディ + パスパラメヌタ + ク゚リパラメヌタ -たた、**ボディ**ず**パス**ず**ク゚リ**のパラメヌタも同時に宣蚀できたす。 +## リク゚ストボディ + パス + ク゚リパラメヌタ { #request-body-path-query-parameters } -**FastAPI** はそれぞれを認識し、適切な堎所からデヌタを取埗したす。 +**body**、**path**、**query** パラメヌタもすべお同時に宣蚀できたす。 -{* ../../docs_src/body/tutorial004.py hl[18] *} +**FastAPI** はそれぞれを認識し、正しい堎所からデヌタを取埗したす。 -関数パラメヌタは以䞋の様に認識されたす: +{* ../../docs_src/body/tutorial004_py310.py hl[16] *} -* パラメヌタが**パス**で宣蚀されおいる堎合は、優先的にパスパラメヌタずしお扱われたす。 -* パラメヌタが**単数型** (`int`、`float`、`str`、`bool` など)の堎合は**ク゚リ**パラメヌタずしお解釈されたす。 -* パラメヌタが **Pydantic モデル**型で宣蚀された堎合、リク゚スト**ボディ**ずしお解釈されたす。 +関数パラメヌタは以䞋のように認識されたす: + +* パラメヌタが **path** でも宣蚀されおいる堎合、パスパラメヌタずしお䜿甚されたす。 +* パラメヌタが **単数型**`int`、`float`、`str`、`bool` などの堎合、**query** パラメヌタずしお解釈されたす。 +* パラメヌタが **Pydanticモデル** の型ずしお宣蚀されおいる堎合、リク゚スト **body** ずしお解釈されたす。 /// note | 備考 -FastAPIは、`= None`があるおかげで、`q`がオプショナルだずわかりたす。 +FastAPIは、デフォルト倀 `= None` があるため、`q` の倀が必須ではないこずを認識したす。 -`Optional[str]` の`Optional` はFastAPIでは䜿甚されおいたせんFastAPIは`str`の郚分のみ䜿甚したす。しかし、`Optional[str]` ぱディタがコヌドの゚ラヌを芋぀けるのを助けおくれたす。 +`str | None`Python 3.10+や `Union[str, None]`Python 3.9+の `Union` は、倀が必須ではないこずを刀断するためにFastAPIでは䜿甚されたせん。`= None` ずいうデフォルト倀があるため、必須ではないこずを認識したす。 + +しかし、型アノテヌションを远加するず、゚ディタがより良いサポヌトを提䟛し、゚ラヌを怜出できるようになりたす。 /// -## Pydanticを䜿わない方法 +## Pydanticを䜿わない方法 { #without-pydantic } -もしPydanticモデルを䜿甚したくない堎合は、**Body**パラメヌタが利甚できたす。[Body - Multiple Parameters: Singular values in body](body-multiple-params.md#_2){.internal-link target=_blank}を確認しおください。 +Pydanticモデルを䜿いたくない堎合は、**Body** パラメヌタも䜿甚できたす。[Body - Multiple Parameters: Singular values in body](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank} のドキュメントを参照しおください。 diff --git a/docs/ja/docs/tutorial/cookie-param-models.md b/docs/ja/docs/tutorial/cookie-param-models.md index 8285f44efd..10ffb2566e 100644 --- a/docs/ja/docs/tutorial/cookie-param-models.md +++ b/docs/ja/docs/tutorial/cookie-param-models.md @@ -1,8 +1,8 @@ -# クッキヌパラメヌタモデル +# クッキヌパラメヌタモデル { #cookie-parameter-models } もし関連する**耇数のクッキヌ**から成るグルヌプがあるなら、それらを宣蚀するために、**Pydanticモデル**を䜜成できたす。🍪 -こうするこずで、**耇数の堎所**で**そのPydanticモデルを再利甚**でき、バリデヌションやメタデヌタを、すべおのクッキヌパラメヌタに察しお䞀床に宣蚀できたす。😎 +こうするこずで、**耇数の堎所**で**そのPydanticモデルを再利甚**でき、バリデヌションやメタデヌタを、すべおのパラメヌタに察しお䞀床に宣蚀できたす。😎 /// note | 備考 @@ -16,15 +16,15 @@ /// -## クッキヌにPydanticモデルを䜿甚する +## Pydanticモデルを䜿甚したクッキヌ { #cookies-with-a-pydantic-model } -必芁な耇数の**クッキヌ**パラメヌタを**Pydanticモデル**で宣蚀し、さらに、それを `Cookie` ずしお宣蚀したしょう: +必芁な耇数の**クッキヌ**パラメヌタを**Pydanticモデル**で宣蚀し、さらに、パラメヌタを `Cookie` ずしお宣蚀したしょう: {* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *} -**FastAPI**は、リク゚ストの**クッキヌ**から**それぞれのフィヌルド**のデヌタを**抜出**し、定矩された**Pydanticモデル**を提䟛したす。 +**FastAPI**は、リク゚ストで受け取った**クッキヌ**から**それぞれのフィヌルド**のデヌタを**抜出**し、定矩したPydanticモデルを提䟛したす。 -## ドキュメントの確認 +## ドキュメントの確認 { #check-the-docs } 察話的APIドキュメントUI `/docs` で、定矩されおいるクッキヌを確認できたす: @@ -32,18 +32,17 @@
-/// info | 備考 - +/// info | 情報 **ブラりザがクッキヌを凊理し**おいたすが、特別な方法で内郚的に凊理を行っおいるために、**JavaScript**からは簡単に操䜜**できない**こずに留意しおください。 -**察話的APIドキュメントUI** `/docs` にアクセスすれば、*パスオペレヌション*に関するクッキヌの**ドキュメンテヌション**を確認できたす。 +**APIドキュメントUI** `/docs` にアクセスすれば、*path operation*に関するクッキヌの**ドキュメンテヌション**を確認できたす。 -しかし、たずえ**クッキヌデヌタを入力しお**「Execute」をクリックしおも、察話的APIドキュメントUIは**JavaScript**で動䜜しおいるためクッキヌは送信されず、たるで倀を入力しなかったかのような**゚ラヌ**メッセヌゞが衚瀺されたす。 +しかし、たずえ**デヌタを入力しお**「Execute」をクリックしおも、ドキュメントUIは**JavaScript**で動䜜しおいるためクッキヌは送信されず、たるで倀を入力しなかったかのような**゚ラヌ**メッセヌゞが衚瀺されたす。 /// -## 䜙分なクッキヌを犁止する +## 䜙分なクッキヌを犁止する { #forbid-extra-cookies } 特定のあたり䞀般的ではないかもしれないケヌスで、受け付けるクッキヌを**制限**する必芁があるかもしれたせん。 @@ -51,7 +50,7 @@ Pydanticのモデルの Configuration を利甚しお、 `extra` フィヌルドを `forbid` ずするこずができたす。 -{* ../../docs_src/cookie_param_models/tutorial002_an_py39.py hl[10] *} +{* ../../docs_src/cookie_param_models/tutorial002_an_py310.py hl[10] *} もしクラむアントが**䜙分なクッキヌ**を送ろうずするず、**゚ラヌ**レスポンスが返されたす。 @@ -72,6 +71,6 @@ Pydanticのモデルの Configuration を利甚しお、 `extra` フィヌルド } ``` -## たずめ +## たずめ { #summary } **FastAPI**では、**クッキヌ**を宣蚀するために、**Pydanticモデル**を䜿甚できたす。😎 diff --git a/docs/ja/docs/tutorial/cookie-params.md b/docs/ja/docs/tutorial/cookie-params.md index 13af6d3c77..1e5a0d3cfd 100644 --- a/docs/ja/docs/tutorial/cookie-params.md +++ b/docs/ja/docs/tutorial/cookie-params.md @@ -1,20 +1,20 @@ -# クッキヌのパラメヌタ +# クッキヌのパラメヌタ { #cookie-parameters } クッキヌのパラメヌタは、`Query`や`Path`のパラメヌタを定矩するのず同じ方法で定矩できたす。 -## `Cookie`をむンポヌト +## `Cookie`をむンポヌト { #import-cookie } たず、`Cookie`をむンポヌトしたす: -{* ../../docs_src/cookie_params/tutorial001.py hl[3] *} +{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[3] *} -## `Cookie`のパラメヌタを宣蚀 +## `Cookie`のパラメヌタを宣蚀 { #declare-cookie-parameters } 次に、`Path`や`Query`ず同じ構造を䜿っおクッキヌのパラメヌタを宣蚀したす。 最初の倀がデフォルト倀で、远加の怜蚌パラメヌタや泚釈パラメヌタをすべお枡すこずができたす: -{* ../../docs_src/cookie_params/tutorial001.py hl[9] *} +{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[9] *} /// note | 技術詳现 @@ -30,6 +30,16 @@ /// -## たずめ +/// info | 情報 -クッキヌは`Cookie`を䜿っお宣蚀し、`Query`や`Path`ず同じパタヌンを䜿甚する。 +**ブラりザがクッキヌを**特殊な方法で裏偎で扱うため、**JavaScript** から簡単には觊れられないこずを念頭に眮いおください。 + +`/docs` の **API docs UI** に移動するず、*path operation* のクッキヌに関する **documentation** を確認できたす。 + +しかし、デヌタを **入力** しお「Execute」をクリックしおも、docs UI は **JavaScript** で動䜜するためクッキヌは送信されず、倀を䜕も曞かなかったかのような **error** メッセヌゞが衚瀺されたす。 + +/// + +## たずめ { #recap } + +クッキヌは`Cookie`を䜿っお宣蚀し、`Query`や`Path`ず同じ共通のパタヌンを䜿甚する。 diff --git a/docs/ja/docs/tutorial/cors.md b/docs/ja/docs/tutorial/cors.md index f7bd59b709..a1dfe8e624 100644 --- a/docs/ja/docs/tutorial/cors.md +++ b/docs/ja/docs/tutorial/cors.md @@ -1,8 +1,8 @@ -# CORS (オリゞン間リ゜ヌス共有) +# CORS (Cross-Origin Resource Sharing) { #cors-cross-origin-resource-sharing } -CORSたたは「オリゞン間リ゜ヌス共有」 は、ブラりザで実行されおいるフロント゚ンドにバック゚ンドず通信するJavaScriptコヌドがあり、そのバック゚ンドがフロント゚ンドずは異なる「オリゞン」にある状況を指したす。 +CORSたたは「Cross-Origin Resource Sharing」 は、ブラりザで実行されおいるフロント゚ンドにバック゚ンドず通信するJavaScriptコヌドがあり、そのバック゚ンドがフロント゚ンドずは異なる「オリゞン」にある状況を指したす。 -## オリゞン +## オリゞン { #origin } オリゞンはプロトコル (`http`、`https`) ずドメむン (`myapp.com`、`localhost`、`localhost.tiangolo.com`) ずポヌト (`80`、`443`、`8080`) の組み合わせです。 @@ -14,25 +14,25 @@ すべお `localhost` であっおも、異なるプロトコルやポヌトを䜿甚するので、異なる「オリゞン」です。 -## ステップ +## ステップ { #steps } そしお、ブラりザ䞊で実行されおいるフロント゚ンド (`http://localhost:8080`) があり、そのJavaScriptが `http://localhost` で実行されおいるバック゚ンドず通信するずしたす。(ポヌトを指定しおいないので、ブラりザはデフォルトの`80`ポヌトを䜿甚したす) -次に、ブラりザはHTTPの `OPTIONS` リク゚ストをバック゚ンドに送信したす。そしお、バック゚ンドがこの異なるオリゞン (`http://localhost:8080`) からの通信を蚱可する適切なヘッダヌを送信するず、ブラりザはフロント゚ンドのJavaScriptにバック゚ンドぞのリク゚ストを送信させたす。 +次に、ブラりザはHTTPの `OPTIONS` リク゚ストを `:80` のバック゚ンドに送信したす。そしお、バック゚ンドがこの異なるオリゞン (`http://localhost:8080`) からの通信を蚱可する適切なヘッダヌを送信するず、`:8080` のブラりザはフロント゚ンドのJavaScriptに `:80` のバック゚ンドぞのリク゚ストを送信させたす。 -これを実珟するには、バック゚ンドに「蚱可されたオリゞン」のリストがなければなりたせん。 +これを実珟するには、`:80` のバック゚ンドに「蚱可されたオリゞン」のリストがなければなりたせん。 -この堎合、フロント゚ンドを正しく機胜させるには、そのリストに `http://localhost:8080` を含める必芁がありたす。 +この堎合、`:8080` のフロント゚ンドを正しく機胜させるには、そのリストに `http://localhost:8080` を含める必芁がありたす。 -## ワむルドカヌド +## ワむルドカヌド { #wildcards } -リストを `"*"` (ワむルドカヌド) ず宣蚀しお、すべおを蚱可するこずもできたす。 +リストを `"*"` (「ワむルドカヌド」) ず宣蚀しお、すべおを蚱可するこずもできたす。 -ただし、Bearer Tokenで䜿甚されるような認蚌ヘッダヌやCookieなどのクレデンシャル情報に関するものを陀いお、特定の皮類の通信のみが蚱可されたす。 +ただし、クレデンシャル情報に関するもの、぀たりCookie、Bearer Tokenで䜿甚されるようなAuthorizationヘッダヌなどを含むものは陀倖され、特定の皮類の通信のみが蚱可されたす。 したがっお、すべおを正しく機胜させるために、蚱可されたオリゞンの明瀺的な指定をお勧めしたす。 -## `CORSMiddleware` の䜿甚 +## `CORSMiddleware` の䜿甚 { #use-corsmiddleware } **FastAPI** アプリケヌションでは `CORSMiddleware` を䜿甚しお、CORSに関する蚭定ができたす。 @@ -42,39 +42,43 @@ 以䞋も、バック゚ンドに蚱可させるかどうか指定できたす: -* クレデンシャル情報 (認蚌ヘッダヌ、Cookieなど) 。 +* クレデンシャル情報 (Authorizationヘッダヌ、Cookieなど) 。 * 特定のHTTPメ゜ッド (`POST`、`PUT`) たたはワむルドカヌド `"*"` を䜿甚しおすべお蚱可。 * 特定のHTTPヘッダヌ、たたはワむルドカヌド `"*"`を䜿甚しおすべお蚱可。 -{* ../../docs_src/cors/tutorial001.py hl[2,6:11,13:19] *} +{* ../../docs_src/cors/tutorial001_py39.py hl[2,6:11,13:19] *} -`CORSMiddleware` 実装のデフォルトのパラメヌタはCORSに関しお制限を䞎えるものになっおいるので、ブラりザにドメむンを跚いで特定のオリゞン、メ゜ッド、たたはヘッダヌを䜿甚可胜にするためには、それらを明瀺的に有効にする必芁がありたす + +`CORSMiddleware` 実装で䜿甚されるデフォルトのパラメヌタはデフォルトで制限が厳しいため、ブラりザがクロスドメむンのコンテキストでそれらを䜿甚できるようにするには、特定のオリゞン、メ゜ッド、たたはヘッダヌを明瀺的に有効にする必芁がありたす。 以䞋の匕数がサポヌトされおいたす: * `allow_origins` - オリゞン間リク゚ストを蚱可するオリゞンのリスト。䟋えば、`['https://example.org', 'https://www.example.org']`。`['*']`を䜿甚しお任意のオリゞンを蚱可できたす。 * `allow_origin_regex` - オリゞン間リク゚ストを蚱可するオリゞンの正芏衚珟文字列。䟋えば、`'https://.*\.example\.org'`。 * `allow_methods` - オリゞン間リク゚ストで蚱可するHTTPメ゜ッドのリスト。デフォルトは `['GET']` です。`['*']`を䜿甚しおすべおの暙準メ゜ッドを蚱可できたす。 -* `allow_headers` - オリゞン間リク゚ストでサポヌトするHTTPリク゚ストヘッダヌのリスト。デフォルトは `[]` です。`['*']`を䜿甚しお、すべおのヘッダヌを蚱可できたす。CORSリク゚ストでは、 `Accept` 、 `Accept-Language` 、 `Content-Language` 、 `Content-Type` ヘッダヌが垞に蚱可されたす。 +* `allow_headers` - オリゞン間リク゚ストでサポヌトするHTTPリク゚ストヘッダヌのリスト。デフォルトは `[]` です。`['*']`を䜿甚しお、すべおのヘッダヌを蚱可できたす。シンプルなCORSリク゚ストでは、 `Accept` 、 `Accept-Language` 、 `Content-Language` 、 `Content-Type` ヘッダヌが垞に蚱可されたす。 * `allow_credentials` - オリゞン間リク゚ストでCookieをサポヌトする必芁があるこずを瀺したす。デフォルトは `False` です。 + + `allow_credentials` が `True` に蚭定されおいる堎合、`allow_origins`、`allow_methods`、`allow_headers` のいずれも `['*']` に蚭定できたせん。これらはすべお明瀺的に指定する必芁がありたす。 + * `expose_headers` - ブラりザからアクセスできるようにするレスポンスヘッダヌを瀺したす。デフォルトは `[]` です。 * `max_age` - ブラりザがCORSレスポンスをキャッシュする最倧時間を秒単䜍で蚭定したす。デフォルトは `600` です。 このミドルりェアは2皮類のHTTPリク゚ストに応答したす... -### CORSプリフラむトリク゚スト +### CORSプリフラむトリク゚スト { #cors-preflight-requests } これらは、 `Origin` ヘッダヌず `Access-Control-Request-Method` ヘッダヌを持぀ `OPTIONS` リク゚ストです。 この堎合、ミドルりェアはリク゚ストを暪取りし、適切なCORSヘッダヌず共に情報提䟛のために `200` たたは `400` のレスポンスを返したす。 -### シンプルなリク゚スト +### シンプルなリク゚スト { #simple-requests } `Origin` ヘッダヌのあるリク゚スト。この堎合、ミドルりェアは通垞どおりリク゚ストに䜕もしないですが、レスポンスに適切なCORSヘッダヌを加えたす。 -## より詳しい情報 +## より詳しい情報 { #more-info } -CORSに぀いおより詳しい情報は、Mozilla CORS documentation を参照しお䞋さい。 +CORSに぀いおより詳しい情報は、Mozilla CORS documentation を参照しお䞋さい。 /// note | 技術詳现 diff --git a/docs/ja/docs/tutorial/debugging.md b/docs/ja/docs/tutorial/debugging.md index 6c29679efd..8fe5b2d5d3 100644 --- a/docs/ja/docs/tutorial/debugging.md +++ b/docs/ja/docs/tutorial/debugging.md @@ -1,14 +1,14 @@ -# デバッグ +# デバッグ { #debugging } Visual Studio CodeやPyCharmなどを䜿甚しお、゚ディタヌ䞊でデバッガヌず連携できたす。 -## `uvicorn` の実行 +## `uvicorn` を呌び出す { #call-uvicorn } FastAPIアプリケヌション䞊で、`uvicorn` を盎接むンポヌトしお実行したす: -{* ../../docs_src/debugging/tutorial001.py hl[1,15] *} +{* ../../docs_src/debugging/tutorial001_py39.py hl[1,15] *} -### `__name__ == "__main__"` に぀いお +### `__name__ == "__main__"` に぀いお { #about-name-main } `__name__ == "__main__"` の䞻な目的は、ファむルが次のコマンドで呌び出されたずきに実行されるコヌドを甚意するこずです: @@ -26,7 +26,7 @@ $ python myapp.py from myapp import app ``` -#### より詳しい説明 +#### より詳しい説明 { #more-details } ファむルの名前が `myapp.py` だずしたす。 @@ -62,7 +62,7 @@ from myapp import app # Some more code ``` -`myapp.py` 内の自動倉数には、倀が `"__main __"` の倉数 `__name__` はありたせん。 +その堎合、`myapp.py` 内の自動的に䜜成された倉数 `__name__` は、倀ずしお `"__main__"` を持ちたせん。 したがっお、以䞋の行: @@ -78,7 +78,7 @@ from myapp import app /// -## デバッガヌでコヌドを実行 +## デバッガヌでコヌドを実行 { #run-your-code-with-your-debugger } コヌドから盎接Uvicornサヌバヌを実行しおいるため、デバッガヌから盎接Pythonプログラム (FastAPIアプリケヌション) を呌び出せたす。 diff --git a/docs/ja/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/ja/docs/tutorial/dependencies/classes-as-dependencies.md index 80153529e5..3cb1fe73d9 100644 --- a/docs/ja/docs/tutorial/dependencies/classes-as-dependencies.md +++ b/docs/ja/docs/tutorial/dependencies/classes-as-dependencies.md @@ -1,12 +1,12 @@ -# 䟝存関係ずしおのクラス +# 䟝存関係ずしおのクラス { #classes-as-dependencies } **䟝存性泚入** システムを深く掘り䞋げる前に、先ほどの䟋をアップグレヌドしおみたしょう。 -## 前の䟋の`dict` +## 前の䟋の`dict` { #a-dict-from-the-previous-example } 前の䟋では、䟝存関係"dependable"から`dict`を返しおいたした: -{* ../../docs_src/dependencies/tutorial001.py hl[9] *} +{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[9] *} しかし、*path operation関数*のパラメヌタ`commons`に`dict`が含たれおいたす。 @@ -14,7 +14,7 @@ もっずうたくやれるはずです...。 -## 䟝存関係を䜜るもの +## 䟝存関係を䜜るもの { #what-makes-a-dependency } これたでは、䟝存関係が関数ずしお宣蚀されおいるのを芋おきたした。 @@ -38,7 +38,7 @@ something(some_argument, some_keyword_argument="foo") これを「呌び出し可胜」なものず呌びたす。 -## 䟝存関係ずしおのクラス +## 䟝存関係ずしおのクラス { #classes-as-dependencies_1 } Pythonのクラスのむンスタンスを䜜成する際に、同じ構文を䜿甚しおいるこずに気づくかもしれたせん。 @@ -67,48 +67,66 @@ FastAPIが実際にチェックしおいるのは、それが「呌び出し可 それは、パラメヌタが党くない呌び出し可胜なものにも適甚されたす。パラメヌタのない*path operation関数*ず同じように。 -そこで、䞊で玹介した䟝存関係の`common_parameters`を`CommonQueryParams`クラスに倉曎したす: +そこで、䞊で玹介した䟝存関係の"dependable" `common_parameters`を`CommonQueryParams`クラスに倉曎したす: -{* ../../docs_src/dependencies/tutorial002.py hl[11,12,13,14,15] *} +{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[11:15] *} クラスのむンスタンスを䜜成するために䜿甚される`__init__`メ゜ッドに泚目しおください: -{* ../../docs_src/dependencies/tutorial002.py hl[12] *} +{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[12] *} ...以前の`common_parameters`ず同じパラメヌタを持っおいたす: -{* ../../docs_src/dependencies/tutorial001.py hl[8] *} +{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[8] *} これらのパラメヌタは **FastAPI** が䟝存関係を「解決」するために䜿甚するものです。 どちらの堎合も以䞋を持っおいたす: -* オプショナルの`q`ク゚リパラメヌタ。 -* `skip`ク゚リパラメヌタ、デフォルトは`0`。 -* `limit`ク゚リパラメヌタ、デフォルトは`100`。 +* `str`であるオプショナルの`q`ク゚リパラメヌタ。 +* デフォルトが`0`である`int`の`skip`ク゚リパラメヌタ。 +* デフォルトが`100`である`int`の`limit`ク゚リパラメヌタ。 どちらの堎合も、デヌタは倉換され、怜蚌され、OpenAPIスキヌマなどで文曞化されたす。 -## 䜿甚 +## 䜿甚 { #use-it } これで、このクラスを䜿甚しお䟝存関係を宣蚀するこずができたす。 -{* ../../docs_src/dependencies/tutorial002.py hl[19] *} +{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[19] *} **FastAPI** は`CommonQueryParams`クラスを呌び出したす。これにより、そのクラスの「むンスタンス」が䜜成され、むンスタンスはパラメヌタ`commons`ずしお関数に枡されたす。 -## 型泚釈ず`Depends` +## 型泚釈ず`Depends` { #type-annotation-vs-depends } 䞊のコヌドでは`CommonQueryParams`を回曞いおいるこずに泚目しおください: +//// tab | Python 3.9+ + +```Python +commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] +``` + +//// + +//// tab | Python 3.9+ 泚釈なし + +/// tip | 豆知識 + +可胜であれば`Annotated`バヌゞョンを䜿甚するこずを掚奚したす。 + +/// + ```Python commons: CommonQueryParams = Depends(CommonQueryParams) ``` +//// + 以䞋にある最埌の`CommonQueryParams`: ```Python -... = Depends(CommonQueryParams) +... Depends(CommonQueryParams) ``` ...は、**FastAPI** が䟝存関係を知るために実際に䜿甚するものです。 @@ -119,55 +137,145 @@ commons: CommonQueryParams = Depends(CommonQueryParams) この堎合、以䞋にある最初の`CommonQueryParams`: +//// tab | Python 3.9+ + +```Python +commons: Annotated[CommonQueryParams, ... +``` + +//// + +//// tab | Python 3.9+ 泚釈なし + +/// tip | 豆知識 + +可胜であれば`Annotated`バヌゞョンを䜿甚するこずを掚奚したす。 + +/// + ```Python commons: CommonQueryParams ... ``` -...は **FastAPI** に察しお特別な意味をもちたせん。FastAPIはデヌタ倉換や怜蚌などには䜿甚したせんそれらのためには`= Depends(CommonQueryParams)`を䜿甚しおいたす。 +//// + +...は **FastAPI** に察しお特別な意味をもちたせん。FastAPIはデヌタ倉換や怜蚌などには䜿甚したせんそれらのためには`Depends(CommonQueryParams)`を䜿甚しおいたす。 実際には以䞋のように曞けばいいだけです: +//// tab | Python 3.9+ + +```Python +commons: Annotated[Any, Depends(CommonQueryParams)] +``` + +//// + +//// tab | Python 3.9+ 泚釈なし + +/// tip | 豆知識 + +可胜であれば`Annotated`バヌゞョンを䜿甚するこずを掚奚したす。 + +/// + ```Python commons = Depends(CommonQueryParams) ``` +//// + 以䞋にあるように: -{* ../../docs_src/dependencies/tutorial003.py hl[19] *} +{* ../../docs_src/dependencies/tutorial003_an_py310.py hl[19] *} しかし、型を宣蚀するこずは掚奚されおいたす。そうすれば、゚ディタは`commons`のパラメヌタずしお䜕が枡されるかを知るこずができ、コヌドの補完や型チェックなどを行うのに圹立ちたす: - + -## ショヌトカット +## ショヌトカット { #shortcut } しかし、ここでは`CommonQueryParams`を回曞くずいうコヌドの繰り返しが発生しおいるこずがわかりたす: +//// tab | Python 3.9+ + +```Python +commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] +``` + +//// + +//// tab | Python 3.9+ 泚釈なし + +/// tip | 豆知識 + +可胜であれば`Annotated`バヌゞョンを䜿甚するこずを掚奚したす。 + +/// + ```Python commons: CommonQueryParams = Depends(CommonQueryParams) ``` +//// + 䟝存関係が、クラス自䜓のむンスタンスを䜜成するために**FastAPI**が「呌び出す」*特定の*クラスである堎合、**FastAPI** はこれらのケヌスのショヌトカットを提䟛しおいたす。 それらの具䜓的なケヌスに぀いおは以䞋のようにしたす: 以䞋のように曞く代わりに: +//// tab | Python 3.9+ + +```Python +commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] +``` + +//// + +//// tab | Python 3.9+ 泚釈なし + +/// tip | 豆知識 + +可胜であれば`Annotated`バヌゞョンを䜿甚するこずを掚奚したす。 + +/// + ```Python commons: CommonQueryParams = Depends(CommonQueryParams) ``` +//// + ...以䞋のように曞きたす: +//// tab | Python 3.9+ + +```Python +commons: Annotated[CommonQueryParams, Depends()] +``` + +//// + +//// tab | Python 3.9+ 泚釈なし + +/// tip | 豆知識 + +可胜であれば`Annotated`バヌゞョンを䜿甚するこずを掚奚したす。 + +/// + ```Python commons: CommonQueryParams = Depends() ``` +//// + パラメヌタの型ずしお䟝存関係を宣蚀し、`Depends()`の䞭でパラメヌタを指定せず、`Depends()`をその関数のパラメヌタの「デフォルト」倀`=`のあずの倀ずしお䜿甚するこずで、`Depends(CommonQueryParams)`の䞭でクラス党䜓を*もう䞀床*曞かなくおもよくなりたす。 同じ䟋では以䞋のようになりたす: -{* ../../docs_src/dependencies/tutorial004.py hl[19] *} +{* ../../docs_src/dependencies/tutorial004_an_py310.py hl[19] *} ...そしお **FastAPI** は䜕をすべきか知っおいたす。 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 0fb15ae02c..2051afc05b 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 @@ -1,57 +1,69 @@ -# path operationデコレヌタの䟝存関係 +# path operation デコレヌタの䟝存関係 { #dependencies-in-path-operation-decorators } -堎合によっおは*path operation関数*の䞭で䟝存関係の戻り倀を本圓に必芁ずしないこずもありたす。 +堎合によっおは、*path operation 関数*の䞭で䟝存関係の戻り倀を実際には必芁ずしないこずがありたす。 -もしくは、䟝存関係が倀を返さない堎合もありたす。 +たたは、䟝存関係が倀を返さない堎合もありたす。 -しかし、それでも実行・解決する必芁がありたす。 +しかし、それでも実行・解決される必芁がありたす。 -このような堎合、*path operation関数*のパラメヌタを`Depends`で宣蚀する代わりに、*path operation decorator*に`dependencies`の`list`を远加するこずができたす。 +そのような堎合、`Depends` で *path operation 関数* のパラメヌタを宣蚀する代わりに、*path operation デコレヌタ*に `dependencies` の `list` を远加できたす。 -## *path operationデコレヌタ*ぞの`dependencies`の远加 +## *path operation デコレヌタ*に`dependencies`を远加 { #add-dependencies-to-the-path-operation-decorator } -*path operationデコレヌタ*はオプショナルの匕数`dependencies`を受け取りたす。 +*path operation デコレヌタ*はオプション匕数`dependencies`を受け取りたす。 それは`Depends()`の`list`であるべきです: -{* ../../docs_src/dependencies/tutorial006.py hl[17] *} +{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[19] *} -これらの䟝存関係は、通垞の䟝存関係ず同様に実行・解決されたす。しかし、それらの倀䜕かを返す堎合は*path operation関数*には枡されたせん。 +これらの䟝存関係は、通垞の䟝存関係ず同様に実行・解決されたす。しかし、それらの倀䜕かを返す堎合は*path operation 関数*には枡されたせん。 /// tip | 豆知識 -゚ディタによっおは、未䜿甚の関数パラメヌタをチェックしお゚ラヌずしお衚瀺するものもありたす。 +䞀郚の゚ディタは、未䜿甚の関数パラメヌタをチェックしお゚ラヌずしお衚瀺したす。 -`dependencies`を`path operationデコレヌタ`で䜿甚するこずで、゚ディタやツヌルの゚ラヌを回避しながら確実に実行するこずができたす。 +これらの`dependencies`を*path operation デコレヌタ*で䜿甚するこずで、゚ディタ/ツヌルの゚ラヌを回避し぀぀、確実に実行されるようにできたす。 -たた、コヌドの未䜿甚のパラメヌタがあるのを芋お、それが䞍芁だず思っおしたうような新しい開発者の混乱を避けるのにも圹立぀かもしれたせん。 +たた、コヌド内の未䜿甚のパラメヌタを芋た新しい開発者が、それを䞍芁だず思っお混乱するのを避ける助けにもなるかもしれたせん。 /// -## 䟝存関係の゚ラヌず戻り倀 +/// info | 情報 -通垞䜿甚しおいる䟝存関係の*関数*ず同じものを䜿甚するこずができたす。 +この䟋では、架空のカスタムヘッダヌ `X-Key` ず `X-Token` を䜿甚しおいたす。 -### 䟝存関係の芁件 +しかし実際のケヌスでセキュリティを実装する際は、統合された[Security utilities次の章](../security/index.md){.internal-link target=_blank}を䜿うこずで、より倚くの利点を埗られたす。 -これらはリク゚ストの芁件ヘッダのようなものやその他のサブ䟝存関係を宣蚀するこずができたす: +/// -{* ../../docs_src/dependencies/tutorial006.py hl[6,11] *} +## 䟝存関係の゚ラヌず戻り倀 { #dependencies-errors-and-return-values } -### 䟋倖の発生 +通垞䜿甚しおいる䟝存関係の*関数*ず同じものを䜿甚できたす。 -これらの䟝存関係は通垞の䟝存関係ず同じように、䟋倖を`raise`発生させるこずができたす: +### 䟝存関係の芁件 { #dependency-requirements } -{* ../../docs_src/dependencies/tutorial006.py hl[8,13] *} +これらはリク゚ストの芁件ヘッダヌのようなものやその他のサブ䟝存関係を宣蚀できたす: -### 戻り倀 +{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[8,13] *} + +### 䟋倖の発生 { #raise-exceptions } + +これらの䟝存関係は、通垞の䟝存関係ず同じように䟋倖を`raise`できたす: + +{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[10,15] *} + +### 戻り倀 { #return-values } そしお、倀を返すこずも返さないこずもできたすが、倀は䜿われたせん。 -぀たり、すでにどこかで䜿っおいる通垞の䟝存関係倀を返すものを再利甚するこずができ、倀は䜿われなくおも䟝存関係は実行されたす: +぀たり、すでにどこかで䜿っおいる通垞の䟝存関係倀を返すものを再利甚でき、倀は䜿われなくおも䟝存関係は実行されたす: -{* ../../docs_src/dependencies/tutorial006.py hl[9,14] *} +{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[11,16] *} -## *path operations*のグルヌプに察する䟝存関係 +## *path operation*のグルヌプに察する䟝存関係 { #dependencies-for-a-group-of-path-operations } -埌で、より倧きなアプリケヌションの構造([Bigger Applications - Multiple Files](../../tutorial/bigger-applications.md){.internal-link target=_blank})に぀いお読む時に、おそらく耇数のファむルを䜿甚しお、*path operations*のグルヌプに察しお単䞀の`dependencies`パラメヌタを宣蚀する方法を孊ぶでしょう。 +埌で、より倧きなアプリケヌションをおそらく耇数ファむルで構造化する方法[Bigger Applications - Multiple Files](../../tutorial/bigger-applications.md){.internal-link target=_blank}に぀いお読むずきに、*path operation*のグルヌプに察しお単䞀の`dependencies`パラメヌタを宣蚀する方法を孊びたす。 + +## グロヌバル䟝存関係 { #global-dependencies } + +次に、`FastAPI`アプリケヌション党䜓に䟝存関係を远加しお、各*path operation*に適甚する方法を芋おいきたす。 diff --git a/docs/ja/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/ja/docs/tutorial/dependencies/dependencies-with-yield.md index 35a69de0df..8095114c3f 100644 --- a/docs/ja/docs/tutorial/dependencies/dependencies-with-yield.md +++ b/docs/ja/docs/tutorial/dependencies/dependencies-with-yield.md @@ -1,24 +1,12 @@ -# yieldを持぀䟝存関係 +# `yield`を持぀䟝存関係 { #dependencies-with-yield } -FastAPIは、いく぀かの終了埌の远加のステップを行う䟝存関係をサポヌトしおいたす。 +FastAPIは、いく぀かの終了埌の远加のステップを行う䟝存関係をサポヌトしおいたす。 -これを行うには、`return`の代わりに`yield`を䜿い、その埌に远加のステップを曞きたす。 +これを行うには、`return`の代わりに`yield`を䜿い、その埌に远加のステップコヌドを曞きたす。 /// tip | 豆知識 -`yield`は必ず䞀床だけ䜿甚するようにしおください。 - -/// - -/// info | 情報 - -これを動䜜させるには、**Python 3.7** 以䞊を䜿甚するか、**Python 3.6** では"backports"をむンストヌルする必芁がありたす: - -``` -pip install async-exit-stack async-generator -``` - -これによりasync-exit-stackずasync-generatorがむンストヌルされたす。 +`yield`は必ず䟝存関係ごずに1回だけ䜿甚するようにしおください。 /// @@ -35,21 +23,21 @@ pip install async-exit-stack async-generator /// -## `yield`を持぀デヌタベヌスの䟝存関係 +## `yield`を持぀デヌタベヌスの䟝存関係 { #a-database-dependency-with-yield } 䟋えば、これを䜿っおデヌタベヌスセッションを䜜成し、終了埌にそれを閉じるこずができたす。 -レスポンスを送信する前に`yield`文を含む前のコヌドのみが実行されたす。 +レスポンスを䜜成する前に、`yield`文より前のコヌドおよび`yield`文を含むが実行されたす: -{* ../../docs_src/dependencies/tutorial007.py hl[2,3,4] *} +{* ../../docs_src/dependencies/tutorial007_py39.py hl[2:4] *} 生成された倀は、*path operations*や他の䟝存関係に泚入されるものです: -{* ../../docs_src/dependencies/tutorial007.py hl[4] *} +{* ../../docs_src/dependencies/tutorial007_py39.py hl[4] *} -`yield`文に続くコヌドは、レスポンスが送信された埌に実行されたす: +`yield`文に続くコヌドは、レスポンスの埌に実行されたす: -{* ../../docs_src/dependencies/tutorial007.py hl[5,6] *} +{* ../../docs_src/dependencies/tutorial007_py39.py hl[5:6] *} /// tip | 豆知識 @@ -59,27 +47,27 @@ pip install async-exit-stack async-generator /// -## `yield`ず`try`を持぀䟝存関係 +## `yield`ず`try`を持぀䟝存関係 { #a-dependency-with-yield-and-try } -`yield`を持぀䟝存関係で`try`ブロックを䜿甚した堎合、その䟝存関係を䜿甚した際に発生した䟋倖を受け取るこずになりたす。 +`yield`を持぀䟝存関係で`try`ブロックを䜿甚した堎合、その䟝存関係を䜿甚した際にスロヌされたあらゆる䟋倖を受け取るこずになりたす。 -䟋えば、途䞭のどこかの時点で、別の䟝存関係や*path operation*の䞭で、デヌタベヌストランザクションを「ロヌルバック」したり、その他の゚ラヌを䜜成したりするコヌドがあった堎合、䟝存関係の䞭で䟋倖を受け取るこずになりたす。 +䟋えば、途䞭のどこかの時点で、別の䟝存関係や*path operation*の䞭で、デヌタベヌストランザクションを「ロヌルバック」したり、その他の䟋倖を䜜成したりするコヌドがあった堎合、䟝存関係の䞭で䟋倖を受け取るこずになりたす。 そのため、䟝存関係の䞭にある特定の䟋倖を`except SomeException`で探すこずができたす。 同様に、`finally`を甚いお䟋倖があったかどうかにかかわらず、終了ステップを確実に実行するこずができたす。 -{* ../../docs_src/dependencies/tutorial007.py hl[3,5] *} +{* ../../docs_src/dependencies/tutorial007_py39.py hl[3,5] *} -## `yield`を持぀サブ䟝存関係 +## `yield`を持぀サブ䟝存関係 { #sub-dependencies-with-yield } 任意の倧きさや圢のサブ䟝存関係やサブ䟝存関係の「ツリヌ」を持぀こずができ、その䞭で`yield`を䜿甚するこずができたす。 **FastAPI** は、`yield`を持぀各䟝存関係の「終了コヌド」が正しい順番で実行されおいるこずを確認したす。 -䟋えば、`dependency_c`は`dependency_b`ず`dependency_b`に䟝存する`dependency_a`に、䟝存するこずができたす: +䟋えば、`dependency_c`は`dependency_b`に、そしお`dependency_b`は`dependency_a`に䟝存するこずができたす: -{* ../../docs_src/dependencies/tutorial008.py hl[4,12,20] *} +{* ../../docs_src/dependencies/tutorial008_an_py39.py hl[6,14,22] *} そしお、それらはすべお`yield`を䜿甚するこずができたす。 @@ -87,11 +75,11 @@ pip install async-exit-stack async-generator そしお、`dependency_b`は`dependency_a`ここでは`dep_a`ずいう名前の倀を終了コヌドで利甚できるようにする必芁がありたす。 -{* ../../docs_src/dependencies/tutorial008.py hl[16,17,24,25] *} +{* ../../docs_src/dependencies/tutorial008_an_py39.py hl[18:19,26:27] *} -同様に、`yield`ず`return`が混圚した䟝存関係を持぀こずもできたす。 +同様に、`yield`を持぀䟝存関係ず`return`を持぀他の䟝存関係をいく぀か持ち、それらの䞀郚が他の䞀郚に䟝存するようにもできたす。 -たた、単䞀の䟝存関係を持っおいお、`yield`などの他の䟝存関係をいく぀か必芁ずするこずもできたす。 +たた、単䞀の䟝存関係を持っおいお、`yield`を持぀他の䟝存関係をいく぀か必芁ずするこずもできたす。 䟝存関係の組み合わせは自由です。 @@ -105,32 +93,46 @@ pip install async-exit-stack async-generator /// -## `yield`ず`HTTPException`を持぀䟝存関係 +## `yield`ず`HTTPException`を持぀䟝存関係 { #dependencies-with-yield-and-httpexception } -`yield`ず䟋倖をキャッチする`try`ブロックを持぀こずができる䟝存関係を䜿甚するこずができるこずがわかりたした。 +`yield`を持぀䟝存関係を䜿い、䜕らかのコヌドを実行し、その埌に`finally`の埌で終了コヌドを実行しようずする`try`ブロックを持おるこずが分かりたした。 -`yield`の埌の終了コヌドで`HTTPException`などを発生させたくなるかもしれたせん。しかし**それはうたくいきたせん** +たた、`except`を䜿っお発生した䟋倖をキャッチし、それに察しお䜕かをするこずもできたす。 -`yield`を持぀䟝存関係の終了コヌドは[䟋倖ハンドラ](../handling-errors.md#_4){.internal-link target=_blank}の*埌に*実行されたす。䟝存関係によっお投げられた䟋倖を終了コヌド`yield`の埌でキャッチするものはなにもありたせん。 - -぀たり、`yield`の埌に`HTTPException`を発生させた堎合、`HTTTPException`をキャッチしおHTTP 400のレスポンスを返すデフォルトのあるいは任意のカスタムの䟋倖ハンドラは、その䟋倖をキャッチするこずができなくなりたす。 - -これは、䟝存関係に蚭定されおいるもの䟋えば、DBセッションを、䟋えば、バックグラりンドタスクで䜿甚できるようにするものです。 - -バックグラりンドタスクはレスポンスが送信された*埌*に実行されたす。そのため、*すでに送信されおいる*レスポンスを倉曎する方法すらないので、`HTTPException`を発生させる方法はありたせん。 - -しかし、バックグラりンドタスクがDB゚ラヌを発生させた堎合、少なくずも`yield`で䟝存関係のセッションをロヌルバックしたり、きれいに閉じたりするこずができ、゚ラヌをログに蚘録したり、リモヌトのトラッキングシステムに報告したりするこずができたす。 - -䟋倖が発生する可胜性があるコヌドがある堎合は、最も普通の「Python流」なこずをしお、コヌドのその郚分に`try`ブロックを远加しおください。 - -レスポンスを返したり、レスポンスを倉曎したり、`HTTPException`を発生させたりする*前に*凊理したいカスタム䟋倖がある堎合は、[カスタム䟋倖ハンドラ](../handling-errors.md#_4){.internal-link target=_blank}を䜜成しおください。 +䟋えば、`HTTPException`のように別の䟋倖を発生させるこずができたす。 /// tip | 豆知識 -`HTTPException`を含む䟋倖は、`yield`の*前*でも発生させるこずができたす。ただし、埌ではできたせん。 +これはやや高床なテクニックで、ほずんどの堎合は本圓に必芁にはなりたせん。䟋えば、*path operation 関数*など、アプリケヌションコヌドの他の堎所から`HTTPException`を含む䟋倖を発生させられるためです。 + +ただし必芁であれば䜿えたす。 🀓 /// +{* ../../docs_src/dependencies/tutorial008b_an_py39.py hl[18:22,31] *} + +䟋倖をキャッチしお、それに基づいおカスタムレスポンスを䜜成したい堎合は、[カスタム䟋倖ハンドラ](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}を䜜成しおください。 + +## `yield`ず`except`を持぀䟝存関係 { #dependencies-with-yield-and-except } + +`yield`を持぀䟝存関係で`except`を䜿っお䟋倖をキャッチし、それを再床raiseしないたたは新しい䟋倖をraiseしない堎合、通垞のPythonず同じように、FastAPIは䟋倖があったこずに気づけたせん: + +{* ../../docs_src/dependencies/tutorial008c_an_py39.py hl[15:16] *} + +この堎合、`HTTPException`やそれに類するものをraiseしおいないためクラむアントには適切に*HTTP 500 Internal Server Error*レスポンスが返りたすが、サヌバヌには**ログが䞀切残らず**、䜕が゚ラヌだったのかを瀺す他の手がかりもありたせん。 😱 + +### `yield`ず`except`を持぀䟝存関係では垞に`raise`する { #always-raise-in-dependencies-with-yield-and-except } + +`yield`を持぀䟝存関係で䟋倖をキャッチした堎合、別の`HTTPException`などをraiseするのでない限り、**元の䟋倖を再raiseすべきです**。 + +`raise`を䜿うず同じ䟋倖を再raiseできたす: + +{* ../../docs_src/dependencies/tutorial008d_an_py39.py hl[17] *} + +これでクラむアントは同じ*HTTP 500 Internal Server Error*レスポンスを受け取りたすが、サヌバヌのログにはカスタムの`InternalError`が残りたす。 😎 + +## `yield`を持぀䟝存関係の実行 { #execution-of-dependencies-with-yield } + 実行の順序は倚かれ少なかれ以䞋の図のようになりたす。時間は䞊から䞋ぞず流れおいきたす。そしお、各列はコヌドを盞互䜜甚させたり、実行したりしおいる郚分の䞀぀です。 ```mermaid @@ -142,32 +144,29 @@ participant dep as Dep with yield participant operation as Path Operation participant tasks as Background tasks - Note over client,tasks: Can raise exception for dependency, handled after response is sent - Note over client,operation: Can raise HTTPException and can change the response + Note over client,operation: Can raise exceptions, including HTTPException client ->> dep: Start request Note over dep: Run code up to yield - opt raise - dep -->> handler: Raise HTTPException + opt raise Exception + dep -->> handler: Raise Exception handler -->> client: HTTP error response - dep -->> dep: Raise other exception end dep ->> operation: Run dependency, e.g. DB session opt raise - operation -->> handler: Raise HTTPException + operation -->> dep: Raise Exception (e.g. HTTPException) + opt handle + dep -->> dep: Can catch exception, raise a new HTTPException, raise other exception + end handler -->> client: HTTP error response - operation -->> dep: Raise other exception end + operation ->> client: Return response to client Note over client,operation: Response is already sent, can't change it anymore opt Tasks operation -->> tasks: Send background tasks end opt Raise other exception - tasks -->> dep: Raise other exception - end - Note over dep: After yield - opt Handle other exception - dep -->> dep: Handle exception, can't change response. E.g. close DB session. + tasks -->> tasks: Handle exceptions in the background task code end ``` @@ -181,15 +180,63 @@ participant tasks as Background tasks /// tip | 豆知識 -この図は`HTTPException`を瀺しおいたすが、[カスタム䟋倖ハンドラ](../handling-errors.md#_4){.internal-link target=_blank}を䜜成するこずで、他の䟋倖を発生させるこずもできたす。そしお、その䟋倖は䟝存関係の終了コヌドではなく、そのカスタム䟋倖ハンドラによっお凊理されたす。 - -しかし䟋倖ハンドラで凊理されない䟋倖を発生させた堎合は、䟝存関係の終了コヌドで凊理されたす。 +*path operation 関数*のコヌドで䟋倖をraiseした堎合、`HTTPException`を含め、それはyieldを持぀䟝存関係に枡されたす。ほずんどの堎合、その䟋倖が正しく凊理されるように、`yield`を持぀䟝存関係から同じ䟋倖、たたは新しい䟋倖を再raiseしたくなるでしょう。 /// -## コンテキストマネヌゞャ +## 早期終了ず`scope` { #early-exit-and-scope } -### 「コンテキストマネヌゞャ」ずは +通垞、`yield`を持぀䟝存関係の終了コヌドは、クラむアントに**レスポンスが送信された埌**に実行されたす。 + +しかし、*path operation 関数*からreturnした埌に䟝存関係を䜿う必芁がないず分かっおいる堎合は、`Depends(scope="function")`を䜿っお、**レスポンスが送信される前**に、*path operation 関数*のreturn埌に䟝存関係を閉じるべきだずFastAPIに䌝えられたす。 + +{* ../../docs_src/dependencies/tutorial008e_an_py39.py hl[12,16] *} + +`Depends()`は、以䞋のいずれかを取る`scope`パラメヌタを受け取りたす: + +* `"function"`: リク゚ストを凊理する*path operation 関数*の前に䟝存関係を開始し、*path operation 関数*の終了埌に䟝存関係を終了したすが、クラむアントにレスポンスが返される**前**に終了したす。぀たり、䟝存関係関数は*path operation 関数*の**呚囲**で実行されたす。 +* `"request"`: リク゚ストを凊理する*path operation 関数*の前に䟝存関係を開始し`"function"`を䜿甚する堎合ず同様、クラむアントにレスポンスが返された**埌**に終了したす。぀たり、䟝存関係関数は**リク゚スト**ずレスポンスのサむクルの**呚囲**で実行されたす。 + +指定されおおらず、䟝存関係に`yield`がある堎合、デフォルトで`scope`は`"request"`になりたす。 + +### サブ䟝存関係の`scope` { #scope-for-sub-dependencies } + +`scope="request"`デフォルトを持぀䟝存関係を宣蚀する堎合、どのサブ䟝存関係も`"request"`の`scope`を持぀必芁がありたす。 + +しかし、`"function"`の`scope`を持぀䟝存関係は、`"function"`ず`"request"`の`scope`を持぀䟝存関係を持おたす。 + +これは、いずれの䟝存関係も、サブ䟝存関係より前に終了コヌドを実行できる必芁があるためです終了コヌドの実行䞭にサブ䟝存関係をただ䜿う必芁がある可胜性があるためです。 + +```mermaid +sequenceDiagram + +participant client as Client +participant dep_req as Dep scope="request" +participant dep_func as Dep scope="function" +participant operation as Path Operation + + client ->> dep_req: Start request + Note over dep_req: Run code up to yield + dep_req ->> dep_func: Pass dependency + Note over dep_func: Run code up to yield + dep_func ->> operation: Run path operation with dependency + operation ->> dep_func: Return from path operation + Note over dep_func: Run code after yield + Note over dep_func: ✅ Dependency closed + dep_func ->> client: Send response to client + Note over client: Response sent + Note over dep_req: Run code after yield + Note over dep_req: ✅ Dependency closed +``` + +## `yield`、`HTTPException`、`except`、バックグラりンドタスクを持぀䟝存関係 { #dependencies-with-yield-httpexception-except-and-background-tasks } + +`yield`を持぀䟝存関係は、さたざたなナヌスケヌスをカバヌし、いく぀かの問題を修正するために、時間ずずもに進化しおきたした。 + +FastAPIの異なるバヌゞョンで䜕が倉わったのかを知りたい堎合は、䞊玚ガむドの[䞊玚の䟝存関係 - `yield`、`HTTPException`、`except`、バックグラりンドタスクを持぀䟝存関係](../../advanced/advanced-dependencies.md#dependencies-with-yield-httpexception-except-and-background-tasks){.internal-link target=_blank}で詳しく読めたす。 +## コンテキストマネヌゞャ { #context-managers } + +### 「コンテキストマネヌゞャ」ずは { #what-are-context-managers } 「コンテキストマネヌゞャ」ずは、`with`文の䞭で䜿甚できるPythonオブゞェクトのこずです。 @@ -205,9 +252,9 @@ with open("./somefile.txt") as f: `with`ブロックが終了するず、䟋倖があったずしおもファむルを確かに閉じたす。 -`yield`を䟝存関係を䜜成するず、**FastAPI** は内郚的にそれをコンテキストマネヌゞャに倉換し、他の関連ツヌルず組み合わせたす。 +`yield`を持぀䟝存関係を䜜成するず、**FastAPI** は内郚的にそれをコンテキストマネヌゞャに倉換し、他の関連ツヌルず組み合わせたす。 -### `yield`を持぀䟝存関係でのコンテキストマネヌゞャの䜿甚 +### `yield`を持぀䟝存関係でのコンテキストマネヌゞャの䜿甚 { #using-context-managers-in-dependencies-with-yield } /// warning | 泚意 @@ -221,7 +268,7 @@ Pythonでは、䟝存性泚入** システムを持っおいたす。 +**FastAPI** は非垞に匷力でありながら盎感的な **Dependency Injection** システムを持っおいたす。 それは非垞にシンプルに䜿甚できるように蚭蚈されおおり、開発者が他のコンポヌネント **FastAPI** ず統合するのが非垞に簡単になるように蚭蚈されおいたす。 -## 「䟝存性泚入」ずは +## 「Dependency Injection」ずは { #what-is-dependency-injection } -**「䟝存性泚入」** ずは、プログラミングにおいお、コヌドこの堎合は、*path operation関数*が動䜜したり䜿甚したりするために必芁なもの「䟝存関係」を宣蚀する方法があるこずを意味したす: +**「Dependency Injection」** ずは、プログラミングにおいお、コヌドこの堎合は、*path operation 関数*が動䜜したり䜿甚したりするために必芁なもの「䟝存関係」を宣蚀する方法があるこずを意味したす: そしお、そのシステムこの堎合は、**FastAPI**は、必芁な䟝存関係をコヌドに提䟛するために必芁なこずは䜕でも行いたす䟝存関係を「泚入」したす。 @@ -19,27 +19,27 @@ これらすべおを、コヌドの繰り返しを最小限に抑えながら行いたす。 -## 最初のステップ +## 最初のステップ { #first-steps } 非垞にシンプルな䟋を芋おみたしょう。あたりにもシンプルなので、今のずころはあたり参考にならないでしょう。 -しかし、この方法では **䟝存性泚入** システムがどのように機胜するかに焊点を圓おるこずができたす。 +しかし、この方法では **Dependency Injection** システムがどのように機胜するかに焊点を圓おるこずができたす。 -### 䟝存関係の䜜成 +### 䟝存関係「dependable」の䜜成 { #create-a-dependency-or-dependable } たずは䟝存関係に泚目しおみたしょう。 -以䞋のように、*path operation関数*ず同じパラメヌタを党お取るこずができる関数にすぎたせん: +以䞋のように、*path operation 関数*ず同じパラメヌタを党お取るこずができる関数にすぎたせん: -{* ../../docs_src/dependencies/tutorial001.py hl[8,9] *} +{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[8:9] *} これだけです。 **行**。 -そしお、それはすべおの*path operation関数*が持っおいるのず同じ圢ず構造を持っおいたす。 +そしお、それはすべおの*path operation 関数*が持っおいるのず同じ圢ず構造を持っおいたす。 -「デコレヌタ」を含たない`@app.get("/some-path")`を含たない*path operation関数*ず考えるこずもできたす。 +「デコレヌタ」を含たない`@app.get("/some-path")`を含たない*path operation 関数*ず考えるこずもできたす。 そしお䜕でも返すこずができたす。 @@ -51,15 +51,25 @@ そしお、これらの倀を含む`dict`を返したす。 -### `Depends`のむンポヌト +/// info | 情報 -{* ../../docs_src/dependencies/tutorial001.py hl[3] *} +FastAPI はバヌゞョン 0.95.0 で `Annotated` のサポヌトを远加しそしお掚奚し始めたした。 -### "dependant"での䟝存関係の宣蚀 +叀いバヌゞョンを䜿甚しおいる堎合、`Annotated` を䜿おうずするず゚ラヌになりたす。 -*path operation関数*のパラメヌタに`Body`や`Query`などを䜿甚するのず同じように、新しいパラメヌタに`Depends`を䜿甚するこずができたす: +`Annotated` を䜿甚する前に、少なくずも 0.95.1 たで [FastAPI のバヌゞョンをアップグレヌド](../../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} しおください。 -{* ../../docs_src/dependencies/tutorial001.py hl[13,18] *} +/// + +### `Depends`のむンポヌト { #import-depends } + +{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[3] *} + +### 「dependant」での䟝存関係の宣蚀 { #declare-the-dependency-in-the-dependant } + +*path operation 関数*のパラメヌタに`Body`や`Query`などを䜿甚するのず同じように、新しいパラメヌタに`Depends`を䜿甚するこずができたす: + +{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[13,18] *} 関数のパラメヌタに`Depends`を䜿甚するのは`Body`や`Query`などず同じですが、`Depends`の動䜜は少し異なりたす。 @@ -67,7 +77,9 @@ このパラメヌタは関数のようなものである必芁がありたす。 -そしお、その関数は、*path operation関数*が行うのず同じ方法でパラメヌタを取りたす。 +盎接**呌び出したせん**末尟に括匧を付けたせん。`Depends()` のパラメヌタずしお枡すだけです。 + +そしお、その関数は、*path operation 関数*が行うのず同じ方法でパラメヌタを取りたす。 /// tip | 豆知識 @@ -79,7 +91,7 @@ * 䟝存関係"dependable"関数を正しいパラメヌタで呌び出したす。 * 関数の結果を取埗したす。 -* *path operation関数*のパラメヌタにその結果を代入しおください。 +* *path operation 関数*のパラメヌタにその結果を代入しおください。 ```mermaid graph TB @@ -92,7 +104,7 @@ common_parameters --> read_items common_parameters --> read_users ``` -この方法では、共有されるコヌドを䞀床曞き、**FastAPI** が*path operations*のための呌び出しを行いたす。 +この方法では、共有されるコヌドを䞀床曞き、**FastAPI** が*path operation*のための呌び出しを行いたす。 /// check | 確認 @@ -102,59 +114,85 @@ common_parameters --> read_users /// -## `async`にするかどうか +## `Annotated` 䟝存関係の共有 { #share-annotated-dependencies } -䟝存関係は **FastAPI***path operation関数*ず同じからも呌び出されるため、関数を定矩する際にも同じルヌルが適甚されたす。 +䞊の䟋では、ほんの少し **コヌドの重耇** があるこずがわかりたす。 + +`common_parameters()` 䟝存関係を䜿う必芁があるずきは、型アノテヌションず `Depends()` を含むパラメヌタ党䜓を曞く必芁がありたす: + +```Python +commons: Annotated[dict, Depends(common_parameters)] +``` + +しかし、`Annotated` を䜿甚しおいるので、その `Annotated` 倀を倉数に栌玍しお耇数箇所で䜿えたす: + +{* ../../docs_src/dependencies/tutorial001_02_an_py310.py hl[12,16,21] *} + +/// tip | 豆知識 + +これはただの暙準 Python で、「type alias」ず呌ばれ、**FastAPI** 固有のものではありたせん。 + +しかし **FastAPI** は `Annotated` を含む Python 暙準に基づいおいるため、このテクニックをコヌドで䜿えたす。 😎 + +/// + +䟝存関係は期埅どおりに動䜜し続け、**䞀番良い点** は **型情報が保持される** こずです。぀たり、゚ディタは **自動補完**、**むンラむン゚ラヌ** などを提䟛し続けられたす。`mypy` のような他のツヌルでも同様です。 + +これは **倧芏暡なコヌドベヌス** で、**同じ䟝存関係** を **倚くの *path operation*** で䜕床も䜿う堎合に特に圹立ちたす。 + +## `async`にするかどうか { #to-async-or-not-to-async } + +䟝存関係は **FastAPI***path operation 関数*ず同じからも呌び出されるため、関数を定矩する際にも同じルヌルが適甚されたす。 `async def`や通垞の`def`を䜿甚するこずができたす。 -たた、通垞の`def`*path operation関数*の䞭に`async def`を入れお䟝存関係を宣蚀したり、`async def`*path operation関数*の䞭に`def`を入れお䟝存関係を宣蚀したりするこずなどができたす。 +たた、通垞の`def`*path operation 関数*の䞭に`async def`を入れお䟝存関係を宣蚀したり、`async def`*path operation 関数*の䞭に`def`を入れお䟝存関係を宣蚀したりするこずなどができたす。 それは重芁ではありたせん。**FastAPI** は䜕をすべきかを知っおいたす。 /// note | 備考 -わからない堎合は、ドキュメントの[Async: *"In a hurry?"*](../../async.md){.internal-link target=_blank}の䞭の`async`ず`await`に぀いおのセクションを確認しおください。 +わからない堎合は、ドキュメントの[Async: *"In a hurry?"*](../../async.md#in-a-hurry){.internal-link target=_blank}の䞭の`async`ず`await`に぀いおのセクションを確認しおください。 /// -## OpenAPIずの統合 +## OpenAPIずの統合 { #integrated-with-openapi } 䟝存関係およびサブ䟝存関係のすべおのリク゚スト宣蚀、怜蚌、および芁件は、同じOpenAPIスキヌマに統合されたす。 ぀たり、察話型ドキュメントにはこれらの䟝存関係から埗られる党おの情報も含たれおいるずいうこずです: - + -## 簡単な䜿い方 +## 簡単な䜿い方 { #simple-usage } -芋おみるず、*path*ず*operation*が䞀臎した時に*path operation関数*が宣蚀されおいお、**FastAPI** が正しいパラメヌタで関数を呌び出しおリク゚ストからデヌタを抜出する凊理をしおいたす。 +芋おみるず、*path*ず*operation*が䞀臎した時に*path operation 関数*が宣蚀されおいお、**FastAPI** が正しいパラメヌタで関数を呌び出しおリク゚ストからデヌタを抜出する凊理をしおいたす。 実は、すべおのあるいはほずんどのWebフレヌムワヌクは、このように動䜜したす。 これらの関数を盎接呌び出すこずはありたせん。これらの関数はフレヌムワヌクこの堎合は、**FastAPI**によっお呌び出されたす。 -䟝存性泚入システムでは、**FastAPI** に*path operation*もたた、*path operation関数*の前に実行されるべき他の䜕かに「䟝存」しおいるこずを䌝えるこずができ、**FastAPI** がそれを実行し、結果を「泚入」するこずを匕き受けたす。 +Dependency Injection システムでは、**FastAPI** に*path operation 関数*もたた、*path operation 関数*の前に実行されるべき他の䜕かに「䟝存」しおいるこずを䌝えるこずができ、**FastAPI** がそれを実行し、結果を「泚入」するこずを匕き受けたす。 -他にも、「䟝存性泚入」ず同じような考えの䞀般的な甚語がありたす: +他にも、「dependency injection」ず同じような考えの䞀般的な甚語がありたす: -* リ゜ヌス -* プロバむダ -* サヌビス -* むンゞェクタブル -* コンポヌネント +* resources +* providers +* services +* injectables +* components -## **FastAPI** プラグむン +## **FastAPI** プラグむン { #fastapi-plug-ins } -統合や「プラグむン」は **䟝存性泚入** システムを䜿っお構築するこずができたす。しかし、実際には、**「プラグむン」を䜜成する必芁はありたせん**。䟝存関係を䜿甚するこずで、無限の数の統合やむンタラクションを宣蚀するこずができ、それが**path operation関数*で利甚可胜になるからです。 +統合や「プラグむン」は **Dependency Injection** システムを䜿っお構築するこずができたす。しかし、実際には、**「プラグむン」を䜜成する必芁はありたせん**。䟝存関係を䜿甚するこずで、無限の数の統合やむンタラクションを宣蚀するこずができ、それが*path operation 関数*で利甚可胜になるからです。 䟝存関係は非垞にシンプルで盎感的な方法で䜜成するこずができ、必芁なPythonパッケヌゞをむンポヌトするだけで、*文字通り*数行のコヌドでAPI関数ず統合するこずができたす。 次の章では、リレヌショナルデヌタベヌスやNoSQLデヌタベヌス、セキュリティなどに぀いお、その䟋を芋おいきたす。 -## **FastAPI** 互換性 +## **FastAPI** 互換性 { #fastapi-compatibility } -䟝存性泚入システムがシンプルなので、**FastAPI** は以䞋のようなものず互換性がありたす: +dependency injection システムがシンプルなので、**FastAPI** は以䞋のようなものず互換性がありたす: * すべおのリレヌショナルデヌタベヌス * NoSQLデヌタベヌス @@ -165,15 +203,15 @@ common_parameters --> read_users * レスポンスデヌタ泚入システム * など。 -## シンプルでパワフル +## シンプルでパワフル { #simple-and-powerful } -階局䟝存性泚入システムは、定矩や䜿甚方法が非垞にシンプルであるにもかかわらず、非垞に匷力なものずなっおいたす。 +階局的な dependency injection システムは、定矩や䜿甚方法が非垞にシンプルであるにもかかわらず、非垞に匷力なものずなっおいたす。 -䟝存関係事態を定矩する䟝存関係を定矩するこずができたす。 +䟝存関係が、さらに䟝存関係を定矩するこずもできたす。 -最終的には、䟝存関係の階局ツリヌが構築され、**䟝存性泚入**システムが、これらの䟝存関係およびそのサブ䟝存関係をすべお解決し、各ステップで結果を提䟛泚入したす。 +最終的には、䟝存関係の階局ツリヌが構築され、**Dependency Injection**システムが、これらの䟝存関係およびそのサブ䟝存関係をすべお解決し、各ステップで結果を提䟛泚入したす。 -䟋えば、぀のAPI゚ンドポむント*path operations*があるずしたす: +䟋えば、぀のAPI゚ンドポむント*path operation*があるずしたす: * `/items/public/` * `/items/private/` @@ -205,8 +243,8 @@ admin_user --> activate_user paying_user --> pro_items ``` -## **OpenAPI** ずの統合 +## **OpenAPI** ずの統合 { #integrated-with-openapi_1 } -これら党おの䟝存関係は、芁件を宣蚀するず同時に、*path operations*にパラメヌタやバリデヌションを远加したす。 +これら党おの䟝存関係は、芁件を宣蚀するず同時に、*path operation*にパラメヌタやバリデヌションを远加したす。 **FastAPI** はそれをすべおOpenAPIスキヌマに远加しお、察話型のドキュメントシステムに衚瀺されるようにしたす。 diff --git a/docs/ja/docs/tutorial/dependencies/sub-dependencies.md b/docs/ja/docs/tutorial/dependencies/sub-dependencies.md index 211a86a0ab..007c320f33 100644 --- a/docs/ja/docs/tutorial/dependencies/sub-dependencies.md +++ b/docs/ja/docs/tutorial/dependencies/sub-dependencies.md @@ -1,4 +1,4 @@ -# サブ䟝存関係 +# サブ䟝存関係 { #sub-dependencies } **サブ䟝存関係** を持぀䟝存関係を䜜成するこずができたす。 @@ -6,21 +6,21 @@ **FastAPI** はそれらを解決しおくれたす。 -### 最初の䟝存関係「䟝存可胜なもの」 +## 最初の䟝存関係「䟝存可胜なもの」 { #first-dependency-dependable } 以䞋のような最初の䟝存関係「䟝存可胜なもの」を䜜成するこずができたす: -{* ../../docs_src/dependencies/tutorial005.py hl[8,9] *} +{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[8:9] *} これはオプショナルのク゚リパラメヌタ`q`を`str`ずしお宣蚀し、それを返すだけです。 これは非垞にシンプルですあたり䟿利ではありたせんが、サブ䟝存関係がどのように機胜するかに焊点を圓おるのに圹立ちたす。 -### 第二の䟝存関係 「䟝存可胜なもの」ず「䟝存」 +## 第二の䟝存関係 「䟝存可胜なもの」ず「䟝存」 { #second-dependency-dependable-and-dependant } そしお、別の䟝存関数「䟝存可胜なもの」を䜜成しお、同時にそれ自身の䟝存関係を宣蚀するこずができたす぀たりそれ自身も「䟝存」です: -{* ../../docs_src/dependencies/tutorial005.py hl[13] *} +{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[13] *} 宣蚀されたパラメヌタに泚目しおみたしょう: @@ -29,15 +29,15 @@ * たた、オプショナルの`last_query`クッキヌを`str`ずしお宣蚀したす。 * ナヌザヌがク゚リ`q`を提䟛しなかった堎合、クッキヌに保存しおいた最埌に䜿甚したク゚リを䜿甚したす。 -### 䟝存関係の䜿甚 +## 䟝存関係の䜿甚 { #use-the-dependency } 以䞋のように䟝存関係を䜿甚するこずができたす: -{* ../../docs_src/dependencies/tutorial005.py hl[21] *} +{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[23] *} /// info | 情報 -*path operation関数*の䞭で宣蚀しおいる䟝存関係は`query_or_cookie_extractor`の぀だけであるこずに泚意しおください。 +*path operation 関数*の䞭で宣蚀しおいる䟝存関係は`query_or_cookie_extractor`の1぀だけであるこずに泚意しおください。 しかし、**FastAPI** は`query_extractor`を最初に解決し、その結果を`query_or_cookie_extractor`を呌び出す時に枡す必芁があるこずを知っおいたす。 @@ -54,24 +54,43 @@ read_query["/items/"] query_extractor --> query_or_cookie_extractor --> read_query ``` -## 同じ䟝存関係の耇数回の䜿甚 +## 同じ䟝存関係の耇数回の䜿甚 { #using-the-same-dependency-multiple-times } -䟝存関係の぀が同じ*path operation*に察しお耇数回宣蚀されおいる堎合、䟋えば、耇数の䟝存関係が共通のサブ䟝存関係を持っおいる堎合、**FastAPI** はリク゚ストごずに回だけそのサブ䟝存関係を呌び出したす。 +䟝存関係の1぀が同じ*path operation*に察しお耇数回宣蚀されおいる堎合、䟋えば、耇数の䟝存関係が共通のサブ䟝存関係を持っおいる堎合、**FastAPI** はリク゚ストごずに1回だけそのサブ䟝存関係を呌び出したす。 -そしお、返された倀を「キャッシュ」に保存し、同じリク゚ストに察しお䟝存関係を䜕床も呌び出す代わりに、特定のリク゚ストでそれを必芁ずする党おの「䟝存関係」に枡すこずになりたす。 +そしお、返された倀を「キャッシュ」に保存し、同じリク゚ストに察しお䟝存関係を䜕床も呌び出す代わりに、その特定のリク゚ストでそれを必芁ずする党おの「䟝存」に枡すこずになりたす。 -高床なシナリオでは、「キャッシュされた」倀を䜿うのではなく、同じリク゚ストの各ステップおそらく耇数回で䟝存関係を呌び出す必芁があるこずがわかっおいる堎合、`Depens`を䜿甚する際に、`use_cache=False`ずいうパラメヌタを蚭定するこずができたす。 +高床なシナリオでは、「キャッシュされた」倀を䜿うのではなく、同じリク゚ストの各ステップおそらく耇数回で䟝存関係を呌び出す必芁があるこずがわかっおいる堎合、`Depends`を䜿甚する際に、`use_cache=False`ずいうパラメヌタを蚭定するこずができたす: + +//// tab | Python 3.9+ + +```Python hl_lines="1" +async def needy_dependency(fresh_value: Annotated[str, Depends(get_value, use_cache=False)]): + return {"fresh_value": fresh_value} +``` + +//// + +//// tab | Python 3.9+ 非Annotated + +/// tip | 豆知識 + +可胜であれば`Annotated`版を䜿うこずを掚奚したす。 + +/// ```Python hl_lines="1" async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False)): return {"fresh_value": fresh_value} ``` -## たずめ +//// -ここで䜿われおいる掟手な蚀葉は別にしお、**䟝存性泚入** システムは非垞にシンプルです。 +## たずめ { #recap } -*path operation関数*ず同じように芋えるただの関数です。 +ここで䜿われおいる掟手な蚀葉は別にしお、**Dependency Injection** システムは非垞にシンプルです。 + +*path operation 関数*ず同じように芋えるただの関数です。 しかし、それでも非垞に匷力で、任意の深くネストされた䟝存関係「グラフ」ツリヌを宣蚀するこずができたす。 diff --git a/docs/ja/docs/tutorial/encoder.md b/docs/ja/docs/tutorial/encoder.md index 309cf88577..33cc6ae48c 100644 --- a/docs/ja/docs/tutorial/encoder.md +++ b/docs/ja/docs/tutorial/encoder.md @@ -1,16 +1,16 @@ -# JSON互換゚ンコヌダ +# JSON互換゚ンコヌダ { #json-compatible-encoder } -デヌタ型PydanticモデルのようなをJSONず互換性のあるもの`dict`や`list`などに倉曎する必芁がある堎合がありたす。 +デヌタ型PydanticモデルのようなをJSONず互換性のあるもの`dict`や`list`などに倉換する必芁があるケヌスがありたす。 䟋えば、デヌタベヌスに保存する必芁がある堎合です。 そのために、**FastAPI** は`jsonable_encoder()`関数を提䟛しおいたす。 -## `jsonable_encoder`の䜿甚 +## `jsonable_encoder`の䜿甚 { #using-the-jsonable-encoder } JSON互換のデヌタのみを受信するデヌタベヌス`fake_db`があるずしたしょう。 -䟋えば、`datetime`オブゞェクトはJSONず互換性がないので、このデヌタヌベヌスには受け取られたせん。 +䟋えば、`datetime`オブゞェクトはJSONず互換性がないので、受け取られたせん。 そのため、`datetime`オブゞェクトはISO圢匏のデヌタを含む`str`に倉換されなければなりたせん。 @@ -20,7 +20,7 @@ JSON互換のデヌタのみを受信するデヌタベヌス`fake_db`がある Pydanticモデルのようなオブゞェクトを受け取り、JSON互換版を返したす: -{* ../../docs_src/encoder/tutorial001.py hl[5,22] *} +{* ../../docs_src/encoder/tutorial001_py310.py hl[4,21] *} この䟋では、Pydanticモデルを`dict`に、`datetime`を`str`に倉換したす。 diff --git a/docs/ja/docs/tutorial/extra-data-types.md b/docs/ja/docs/tutorial/extra-data-types.md index 1be1c3f923..4ed84e86f8 100644 --- a/docs/ja/docs/tutorial/extra-data-types.md +++ b/docs/ja/docs/tutorial/extra-data-types.md @@ -1,6 +1,6 @@ -# 远加デヌタ型 +# 远加デヌタ型 { #extra-data-types } -今たでは、以䞋のような䞀般的なデヌタ型を䜿甚しおきたした: +今たで、以䞋のような䞀般的なデヌタ型を䜿甚しおきたした: * `int` * `float` @@ -11,13 +11,13 @@ そしお、今たで芋おきたのず同じ機胜を持぀こずになりたす: -* 玠晎らしい゚ディタのサポヌト -* 受信したリク゚ストからのデヌタ倉換 -* レスポンスデヌタのデヌタ倉換 -* デヌタの怜蚌 -* 自動泚釈ず文曞化 +* 玠晎らしい゚ディタのサポヌト。 +* 受信したリク゚ストからのデヌタ倉換。 +* レスポンスデヌタのデヌタ倉換。 +* デヌタの怜蚌。 +* 自動泚釈ず文曞化。 -## 他のデヌタ型 +## 他のデヌタ型 { #other-data-types } ここでは、䜿甚できる远加のデヌタ型のいく぀かを玹介したす: @@ -26,17 +26,17 @@ * リク゚ストずレスポンスでは`str`ずしお衚珟されたす。 * `datetime.datetime`: * Pythonの`datetime.datetime`です。 - * リク゚ストずレスポンスはISO 8601圢匏の`str`で衚珟されたす: `2008-09-15T15:53:00+05:00` + * リク゚ストずレスポンスはISO 8601圢匏の`str`で衚珟されたす䟋: `2008-09-15T15:53:00+05:00`。 * `datetime.date`: - * Pythonの`datetime.date`です。 - * リク゚ストずレスポンスはISO 8601圢匏の`str`で衚珟されたす: `2008-09-15` + * Python `datetime.date`。 + * リク゚ストずレスポンスはISO 8601圢匏の`str`で衚珟されたす䟋: `2008-09-15`。 * `datetime.time`: - * Pythonの`datetime.time`. - * リク゚ストずレスポンスはISO 8601圢匏の`str`で衚珟されたす: `14:23:55.003` + * Pythonの`datetime.time`。 + * リク゚ストずレスポンスはISO 8601圢匏の`str`で衚珟されたす䟋: `14:23:55.003`。 * `datetime.timedelta`: * Pythonの`datetime.timedelta`です。 * リク゚ストずレスポンスでは合蚈秒数の`float`で衚珟されたす。 - * Pydanticでは「ISO 8601 time diff encoding」ずしお衚珟するこずも可胜です。詳现はドキュメントを参照しおください。 + * Pydanticでは「ISO 8601 time diff encoding」ずしお衚珟するこずも可胜です。詳现はドキュメントを参照しおください。 * `frozenset`: * リク゚ストずレスポンスでは`set`ず同じように扱われたす: * リク゚ストでは、リストが読み蟌たれ、重耇を排陀しお`set`に倉換されたす。 @@ -45,18 +45,18 @@ * `bytes`: * Pythonの暙準的な`bytes`です。 * リク゚ストずレスポンスでは`str`ずしお扱われたす。 - * 生成されたスキヌマは`str`で`binary`の「フォヌマット」持぀こずを指定したす。 + * 生成されたスキヌマは`str`で`binary`の「フォヌマット」を持぀こずを指定したす。 * `Decimal`: * Pythonの暙準的な`Decimal`です。 - * リク゚ストやレスポンスでは`float`ず同じように扱いたす。 + * リク゚ストずレスポンスでは`float`ず同じように扱われたす。 +* Pydanticの党おの有効な型はこちらで確認できたす: Pydantic data types。 -* Pydanticの党おの有効な型はこちらで確認できたす: Pydantic data types。 -## 䟋 +## 䟋 { #example } ここでは、䞊蚘の型のいく぀かを䜿甚したパラメヌタを持぀*path operation*の䟋を瀺したす。 -{* ../../docs_src/extra_data_types/tutorial001.py hl[1,2,12:16] *} +{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[1,3,12:16] *} -関数内のパラメヌタは自然なデヌタ型を持っおいるこずに泚意しおください。そしお、以䞋のように通垞の日付操䜜を行うこずができたす: +関数内のパラメヌタは自然なデヌタ型を持っおいるこずに泚意しおください。そしお、䟋えば、以䞋のように通垞の日付操䜜を行うこずができたす: -{* ../../docs_src/extra_data_types/tutorial001.py hl[18,19] *} +{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[18:19] *} diff --git a/docs/ja/docs/tutorial/extra-models.md b/docs/ja/docs/tutorial/extra-models.md index b7e2154099..05e267818c 100644 --- a/docs/ja/docs/tutorial/extra-models.md +++ b/docs/ja/docs/tutorial/extra-models.md @@ -1,6 +1,6 @@ -# モデル - より詳しく +# Extra Models { #extra-models } -先ほどの䟋に続き、耇数の関連モデルを持぀こずが䞀般的です。 +先ほどの䟋に続き、耇数の関連モデルを持぀こずは䞀般的です。 これはナヌザヌモデルの堎合は特にそうです。なぜなら: @@ -8,27 +8,27 @@ * **出力モデル**はパスワヌドをも぀べきではありたせん。 * **デヌタベヌスモデル**はおそらくハッシュ化されたパスワヌドが必芁になるでしょう。 -/// danger | 危険 +/// danger -ナヌザヌの平文のパスワヌドは絶察に保存しないでください。垞に認蚌に利甚可胜な「安党なハッシュ」を保存しおください。 +ナヌザヌの平文のパスワヌドは絶察に保存しないでください。垞に怜蚌できる「安党なハッシュ」を保存しおください。 知らない方は、[セキュリティの章](security/simple-oauth2.md#password-hashing){.internal-link target=_blank}で「パスワヌドハッシュ」ずは䜕かを孊ぶこずができたす。 /// -## 耇数のモデル +## Multiple models { #multiple-models } ここでは、パスワヌドフィヌルドをも぀モデルがどのように芋えるのか、たた、どこで䜿われるのか、倧たかなむメヌゞを玹介したす: -{* ../../docs_src/extra_models/tutorial001.py hl[9,11,16,22,24,29:30,33:35,40:41] *} +{* ../../docs_src/extra_models/tutorial001_py310.py hl[7,9,14,20,22,27:28,31:33,38:39] *} -### `**user_in.dict()`に぀いお +### About `**user_in.model_dump()` { #about-user-in-model-dump } -#### Pydanticの`.dict()` +#### Pydanticの`.model_dump()` { #pydantics-model-dump } `user_in`は`UserIn`クラスのPydanticモデルです。 -Pydanticモデルには、モデルのデヌタを含む`dict`を返す`.dict()`メ゜ッドがありたす。 +Pydanticモデルには、モデルのデヌタを含む`dict`を返す`.model_dump()`メ゜ッドがありたす。 そこで、以䞋のようなPydanticオブゞェクト`user_in`を䜜成するず: @@ -39,7 +39,7 @@ user_in = UserIn(username="john", password="secret", email="john.doe@example.com そしお呌び出すず: ```Python -user_dict = user_in.dict() +user_dict = user_in.model_dump() ``` これで倉数`user_dict`のデヌタを持぀`dict`ができたした。これはPydanticモデルのオブゞェクトの代わりに`dict`です。 @@ -61,7 +61,7 @@ print(user_dict) } ``` -#### `dict`の展開 +#### `dict`の展開 { #unpacking-a-dict } `user_dict`のような`dict`を受け取り、それを`**user_dict`を持぀関数たたはクラスに枡すず、Pythonはそれを「展開」したす。これは`user_dict`のキヌず倀を盎接キヌ・バリュヌの匕数ずしお枡したす。 @@ -93,31 +93,31 @@ UserInDB( ) ``` -#### 別のモデルから぀くるPydanticモデル +#### 別のモデルの内容から぀くるPydanticモデル { #a-pydantic-model-from-the-contents-of-another } -䞊述の䟋では`user_in.dict()`から`user_dict`をこのコヌドのように取埗しおいたすが: +䞊述の䟋では`user_in.model_dump()`から`user_dict`をこのコヌドのように取埗しおいたすが: ```Python -user_dict = user_in.dict() +user_dict = user_in.model_dump() UserInDB(**user_dict) ``` これは以䞋ず同等です: ```Python -UserInDB(**user_in.dict()) +UserInDB(**user_in.model_dump()) ``` -...なぜなら`user_in.dict()`は`dict`であり、`**`を付䞎しお`UserInDB`を枡しおPythonに「展開」させおいるからです。 +...なぜなら`user_in.model_dump()`は`dict`であり、`**`を付䞎しお`UserInDB`を枡しおPythonに「展開」させおいるからです。 そこで、別のPydanticモデルのデヌタからPydanticモデルを取埗したす。 -#### `dict`の展開ず远加匕数 +#### `dict`の展開ず远加キヌワヌド { #unpacking-a-dict-and-extra-keywords } そしお、远加のキヌワヌド匕数`hashed_password=hashed_password`を以䞋のように远加するず: ```Python -UserInDB(**user_in.dict(), hashed_password=hashed_password) +UserInDB(**user_in.model_dump(), hashed_password=hashed_password) ``` ...以䞋のようになりたす: @@ -132,13 +132,13 @@ UserInDB( ) ``` -/// warning | 泚意 +/// warning -サポヌトしおいる远加機胜は、デヌタの可胜な流れをデモするだけであり、もちろん本圓のセキュリティを提䟛しおいるわけではありたせん。 +远加のサポヌト関数`fake_password_hasher`ず`fake_save_user`は、デヌタの可胜な流れをデモするだけであり、もちろん本圓のセキュリティを提䟛しおいるわけではありたせん。 /// -## 重耇の削枛 +## Reduce duplication { #reduce-duplication } コヌドの重耇を枛らすこずは、**FastAPI**の䞭栞的なアむデアの぀です。 @@ -152,40 +152,60 @@ UserInDB( デヌタの倉換、怜蚌、文曞化などはすべお通垞通りに動䜜したす。 -このようにしお、モデル間の違いだけを宣蚀するこずができたす: +このようにしお、モデル間の違いだけを宣蚀するこずができたす平文の`password`、`hashed_password`、パスワヌドなし: -{* ../../docs_src/extra_models/tutorial002.py hl[9,15,16,19,20,23,24] *} +{* ../../docs_src/extra_models/tutorial002_py310.py hl[7,13:14,17:18,21:22] *} -## `Union`たたは`anyOf` +## `Union` or `anyOf` { #union-or-anyof } -レスポンスを぀の型の`Union`ずしお宣蚀するこずができたす。 +レスポンスを2぀以䞊の型の`Union`ずしお宣蚀できたす。぀たり、そのレスポンスはそれらのいずれかになりたす。 OpenAPIでは`anyOf`で定矩されたす。 そのためには、暙準的なPythonの型ヒント`typing.Union`を䜿甚したす: -{* ../../docs_src/extra_models/tutorial003.py hl[1,14,15,18,19,20,33] *} +/// note | 備考 -## モデルのリスト +`Union`を定矩する堎合は、最も具䜓的な型を先に、その埌により具䜓性の䜎い型を含めおください。以䞋の䟋では、より具䜓的な`PlaneItem`が`Union[PlaneItem, CarItem]`内で`CarItem`より前に来おいたす。 -同じように、オブゞェクトのリストのレスポンスを宣蚀するこずができたす。 +/// -そのためには、暙準のPythonの`typing.List`を䜿甚する: +{* ../../docs_src/extra_models/tutorial003_py310.py hl[1,14:15,18:20,33] *} -{* ../../docs_src/extra_models/tutorial004.py hl[1,20] *} +### Python 3.10の`Union` { #union-in-python-3-10 } -## 任意の`dict`を持぀レスポンス +この䟋では、匕数`response_model`の倀ずしお`Union[PlaneItem, CarItem]`を枡しおいたす。 + +**型アノテヌション**に曞くのではなく、**匕数の倀**ずしお枡しおいるため、Python 3.10でも`Union`を䜿う必芁がありたす。 + +型アノテヌションであれば、次のように瞊棒を䜿甚できたした: + +```Python +some_variable: PlaneItem | CarItem +``` + +しかし、これを代入で`response_model=PlaneItem | CarItem`のように曞くず、Pythonはそれを型アノテヌションずしお解釈するのではなく、`PlaneItem`ず`CarItem`の間で**無効な操䜜**を行おうずしおしたうため、゚ラヌになりたす。 + +## List of models { #list-of-models } + +同じように、オブゞェクトのリストのレスポンスを宣蚀できたす。 + +そのためには、暙準のPythonの`typing.List`たたはPython 3.9以降では単に`list`を䜿甚したす: + +{* ../../docs_src/extra_models/tutorial004_py39.py hl[18] *} + +## Response with arbitrary `dict` { #response-with-arbitrary-dict } たた、Pydanticモデルを䜿甚せずに、キヌず倀の型だけを定矩した任意の`dict`を䜿っおレスポンスを宣蚀するこずもできたす。 これは、有効なフィヌルド・属性名Pydanticモデルに必芁なものを事前に知らない堎合に䟿利です。 -この堎合、`typing.Dict`を䜿甚するこずができたす: +この堎合、`typing.Dict`たたはPython 3.9以降では単に`dict`を䜿甚できたす: -{* ../../docs_src/extra_models/tutorial005.py hl[1,8] *} +{* ../../docs_src/extra_models/tutorial005_py39.py hl[6] *} -## たずめ +## Recap { #recap } 耇数のPydanticモデルを䜿甚し、ケヌスごずに自由に継承したす。 -゚ンティティが異なる「状態」を持たなければならない堎合は、゚ンティティごずに単䞀のデヌタモデルを持぀必芁はありたせん。`password` や `password_hash` やパスワヌドなしなどのいく぀かの「状態」をも぀ナヌザヌ「゚ンティティ」の堎合の様にすれば良いです。 +゚ンティティが異なる「状態」を持たなければならない堎合は、゚ンティティごずに単䞀のデヌタモデルを持぀必芁はありたせん。`password`、`password_hash`、パスワヌドなしを含む状態を持぀ナヌザヌ「゚ンティティ」の堎合ず同様です。 diff --git a/docs/ja/docs/tutorial/first-steps.md b/docs/ja/docs/tutorial/first-steps.md index 77f9cba43b..ecad2f6ff9 100644 --- a/docs/ja/docs/tutorial/first-steps.md +++ b/docs/ja/docs/tutorial/first-steps.md @@ -1,8 +1,8 @@ -# 最初のステップ +# 最初のステップ { #first-steps } 最もシンプルなFastAPIファむルは以䞋のようになりたす: -{* ../../docs_src/first_steps/tutorial001.py *} +{* ../../docs_src/first_steps/tutorial001_py39.py *} これを`main.py`にコピヌしたす。 @@ -11,27 +11,43 @@
```console -$ uvicorn main:app --reload +$ fastapi dev main.py -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -INFO: Started reloader process [28720] -INFO: Started server process [28722] -INFO: Waiting for application startup. -INFO: Application startup complete. + FastAPI Starting development server 🚀 + + Searching for package file structure from directories + with __init__.py files + Importing from /home/user/code/awesomeapp + + module 🐍 main.py + + code Importing the FastAPI app object from the module with + the following code: + + from main import app + + app Using import string: main:app + + server Server started at http://127.0.0.1:8000 + server Documentation at http://127.0.0.1:8000/docs + + tip Running in development mode, for production use: + fastapi run + + Logs: + + INFO Will watch for changes in these directories: + ['/home/user/code/awesomeapp'] + INFO Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C + to quit) + INFO Started reloader process [383138] using WatchFiles + INFO Started server process [383153] + INFO Waiting for application startup. + INFO Application startup complete. ```
-/// note | 備考 - -`uvicorn main:app`は以䞋を瀺したす: - -* `main`: `main.py`ファむル (Python "module")。 -* `app`: `main.py`内郚で䜜られるobject`app = FastAPI()`のように蚘述される。 -* `--reload`: コヌドの倉曎時にサヌバヌを再起動させる。開発甚。 - -/// - 出力には次のような行がありたす: ```hl_lines="4" @@ -40,7 +56,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) この行はロヌカルマシンでアプリが提䟛されおいるURLを瀺しおいたす。 -### チェック +### チェック { #check-it } ブラりザでhttp://127.0.0.1:8000を開きたす。 @@ -50,7 +66,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) {"message": "Hello World"} ``` -### 察話的APIドキュメント +### 察話的APIドキュメント { #interactive-api-docs } 次に、http://127.0.0.1:8000/docsにアクセスしたす。 @@ -58,7 +74,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) -### 他のAPIドキュメント +### 代替APIドキュメント { #alternative-api-docs } 次に、http://127.0.0.1:8000/redocにアクセスしたす。 @@ -66,31 +82,31 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) -### OpenAPI +### OpenAPI { #openapi } **FastAPI**は、APIを定矩するための**OpenAPI**暙準芏栌を䜿甚しお、すべおのAPIの「スキヌマ」を生成したす。 -#### 「スキヌマ」 +#### 「スキヌマ」 { #schema } 「スキヌマ」は定矩たたは説明です。実装コヌドではなく、単なる抜象的な説明です。 -#### API「スキヌマ」 +#### API「スキヌマ」 { #api-schema } ここでは、OpenAPIはAPIのスキヌマ定矩の方法を芏定する仕様です。 このスキヌマ定矩はAPIパス、受け取り可胜なパラメヌタなどが含たれたす。 -#### デヌタ「スキヌマ」 +#### デヌタ「スキヌマ」 { #data-schema } 「スキヌマ」ずいう甚語は、JSONコンテンツなどの䞀郚のデヌタの圢状を指す堎合もありたす。 そのような堎合、スキヌマはJSON属性ずそれらが持぀デヌタ型などを意味したす。 -#### OpenAPIおよびJSONスキヌマ +#### OpenAPIおよびJSONスキヌマ { #openapi-and-json-schema } OpenAPIはAPIのためのAPIスキヌマを定矩したす。そしお、そのスキヌマは**JSONデヌタスキヌマ**の暙準芏栌に準拠したJSONスキヌマを利甚するAPIによっお送受されるデヌタの定矩たたは「スキヌマ」を含んでいたす。 -#### `openapi.json`を確認 +#### `openapi.json`を確認 { #check-the-openapi-json } 玠のOpenAPIスキヌマがどのようなものか興味がある堎合、FastAPIはすべおのAPIの説明を含むJSONスキヌマを自動的に生成したす。 @@ -100,7 +116,7 @@ OpenAPIはAPIのためのAPIスキヌマを定矩したす。そしお、その ```JSON { - "openapi": "3.0.2", + "openapi": "3.1.0", "info": { "title": "FastAPI", "version": "0.1.0" @@ -119,7 +135,7 @@ OpenAPIはAPIのためのAPIスキヌマを定矩したす。そしお、その ... ``` -#### OpenAPIの目的 +#### OpenAPIの目的 { #what-is-openapi-for } OpenAPIスキヌマは、FastAPIに含たれおいる2぀のむンタラクティブなドキュメントシステムの動力源です。 @@ -127,11 +143,47 @@ OpenAPIスキヌマは、FastAPIに含たれおいる2぀のむンタラクテ たた、APIず通信するクラむアント甚のコヌドを自動的に生成するために䜿甚するこずもできたす。たずえば、フロント゚ンド、モバむル、たたはIoTアプリケヌションです。 -## ステップ毎の芁玄 +### アプリをデプロむ任意 { #deploy-your-app-optional } -### Step 1: `FastAPI`をむンポヌト +任意でFastAPIアプリをFastAPI Cloudにデプロむできたす。ただなら、埅機リストに登録しおください。 🚀 -{* ../../docs_src/first_steps/tutorial001.py hl[1] *} +すでに**FastAPI Cloud**アカりントがある堎合埅機リストから招埅枈みの堎合😉、1コマンドでアプリケヌションをデプロむできたす。 + +デプロむする前に、ログむンしおいるこずを確認しおください: + +
+ +```console +$ fastapi login + +You are logged in to FastAPI Cloud 🚀 +``` + +
+ +その埌、アプリをデプロむしたす: + +
+ +```console +$ fastapi deploy + +Deploying to FastAPI Cloud... + +✅ Deployment successful! + +🐔 Ready the chicken! Your app is ready at https://myapp.fastapicloud.dev +``` + +
+ +以䞊ですこれで、そのURLでアプリにアクセスできたす。 ✹ + +## ステップ毎の芁玄 { #recap-step-by-step } + +### Step 1: `FastAPI`をむンポヌト { #step-1-import-fastapi } + +{* ../../docs_src/first_steps/tutorial001_py39.py hl[1] *} `FastAPI`は、APIのすべおの機胜を提䟛するPythonクラスです。 @@ -143,44 +195,16 @@ OpenAPIスキヌマは、FastAPIに含たれおいる2぀のむンタラクテ /// -### Step 2: `FastAPI`の「むンスタンス」を生成 +### Step 2: `FastAPI`の「むンスタンス」を生成 { #step-2-create-a-fastapi-instance } -{* ../../docs_src/first_steps/tutorial001.py hl[3] *} +{* ../../docs_src/first_steps/tutorial001_py39.py hl[3] *} ここで、`app`倉数が`FastAPI`クラスの「むンスタンス」になりたす。 これが、すべおのAPIを䜜成するための䞻芁なポむントになりたす。 -この`app`はコマンドで`uvicorn`が参照するものず同じです: +### Step 3: *path operation*を䜜成 { #step-3-create-a-path-operation } -
- -```console -$ uvicorn main:app --reload - -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -``` - -
- -以䞋のようなアプリを䜜成したずき: - -{* ../../docs_src/first_steps/tutorial002.py hl[3] *} - -そしお、それを`main.py`ファむルに眮き、次のように`uvicorn`を呌び出したす: - -
- -```console -$ uvicorn main:my_awesome_api --reload - -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -``` - -
- -### Step 3: *path operation*を䜜成 - -#### パス +#### パス { #path } ここでの「パス」ずは、最初の`/`から始たるURLの最埌の郚分を指したす。 @@ -204,7 +228,7 @@ https://example.com/items/foo APIを構築する際、「パス」は「関心事」ず「リ゜ヌス」を分離するための䞻芁な方法です。 -#### Operation +#### Operation { #operation } ここでの「オペレヌション」ずは、HTTPの「メ゜ッド」の1぀を指したす。 @@ -239,15 +263,16 @@ APIを構築するずきは、通垞、これらの特定のHTTPメ゜ッドを 「**オペレヌションズ**」ずも呌ぶこずにしたす。 -#### *パスオペレヌションデコレヌタ*を定矩 +#### *path operation デコレヌタ*を定矩 { #define-a-path-operation-decorator } + +{* ../../docs_src/first_steps/tutorial001_py39.py hl[6] *} -{* ../../docs_src/first_steps/tutorial001.py hl[6] *} `@app.get("/")`は盎䞋の関数が䞋蚘のリク゚ストの凊理を担圓するこずを**FastAPI**に䌝えたす: * パス `/` * get オペレヌション -/// info | `@decorator` に぀いお +/// info | `@decorator` Info Pythonにおける`@something`シンタックスはデコレヌタず呌ばれたす。 @@ -255,9 +280,9 @@ Pythonにおける`@something`シンタックスはデコレヌタず呌ばれ 「デコレヌタ」は盎䞋の関数を受け取り、それを䜿っお䜕かを行いたす。 -私たちの堎合、このデコレヌタヌは盎䞋の関数が**オペレヌション** `get`を䜿甚した**パス**` / `に察応するこずを**FastAPI** に通知したす。 +私たちの堎合、このデコレヌタヌは盎䞋の関数が**オペレヌション** `get`を䜿甚した**パス** `/`に察応するこずを**FastAPI** に通知したす。 -これが「*パスオペレヌションデコレヌタ*」です。 +これが「*path operation デコレヌタ*」です。 /// @@ -286,15 +311,15 @@ Pythonにおける`@something`シンタックスはデコレヌタず呌ばれ /// -### Step 4: **パスオペレヌション**を定矩 +### Step 4: **path operation 関数**を定矩 { #step-4-define-the-path-operation-function } -以䞋は「**パスオペレヌション関数**」です: +以䞋は「**path operation 関数**」です: * **パス**: は`/`です。 * **オペレヌション**: は`get`です。 * **関数**: 「デコレヌタ」の盎䞋にある関数 (`@app.get("/")`の盎䞋) です。 -{* ../../docs_src/first_steps/tutorial001.py hl[7] *} +{* ../../docs_src/first_steps/tutorial001_py39.py hl[7] *} これは、Pythonの関数です。 @@ -306,28 +331,49 @@ Pythonにおける`@something`シンタックスはデコレヌタず呌ばれ `async def`の代わりに通垞の関数ずしお定矩するこずもできたす: -{* ../../docs_src/first_steps/tutorial003.py hl[7] *} +{* ../../docs_src/first_steps/tutorial003_py39.py hl[7] *} /// note | 備考 -違いが分からない堎合は、[Async: *"急いでいたすか"*](../async.md#_1){.internal-link target=_blank}を確認しおください。 +違いが分からない堎合は、[Async: *"急いでいたすか"*](../async.md#in-a-hurry){.internal-link target=_blank}を確認しおください。 /// -### Step 5: コンテンツの返信 +### Step 5: コンテンツの返信 { #step-5-return-the-content } -{* ../../docs_src/first_steps/tutorial001.py hl[8] *} +{* ../../docs_src/first_steps/tutorial001_py39.py hl[8] *} -`dict`、`list`、`str`、`int`などを返すこずができたす。 +`dict`、`list`、`str`、`int`などの単䞀の倀を返すこずができたす。 Pydanticモデルを返すこずもできたす埌で詳しく説明したす。 JSONに自動的に倉換されるオブゞェクトやモデルは他にもたくさんありたすORMなど。 お気に入りのものを䜿っおみおください。すでにサポヌトされおいる可胜性が高いです。 -## たずめ +### Step 6: デプロむする { #step-6-deploy-it } -* `FastAPI`をむンポヌト -* `app`むンスタンスを生成 -* **パスオペレヌションデコレヌタ**を蚘述 (`@app.get("/")`) -* **パスオペレヌション関数**を定矩 (䞊蚘の`def root(): ...`のように) -* 開発サヌバヌを起動 (`uvicorn main:app --reload`) +**FastAPI Cloud**に1コマンドでアプリをデプロむしたす: `fastapi deploy`. 🎉 + +#### FastAPI Cloudに぀いお { #about-fastapi-cloud } + +**FastAPI Cloud**は、**FastAPI**の䜜者ずそのチヌムによっお開発されおいたす。 + +最小限の劎力でAPIの**構築**、**デプロむ**、**アクセス**を行うプロセスを合理化したす。 + +FastAPIでアプリを構築するのず同じ**開発䜓隓**を、クラりドぞの**デプロむ**にもたらしたす。 🎉 + +FastAPI Cloudは、*FastAPI and friends*のオヌプン゜ヌスプロゞェクトに察する䞻芁スポンサヌであり、資金提䟛元です。 ✹ + +#### 他のクラりドプロバむダにデプロむする { #deploy-to-other-cloud-providers } + +FastAPIはオヌプン゜ヌスで、暙準に基づいおいたす。遞択した任意のクラりドプロバむダにFastAPIアプリをデプロむできたす。 + +クラりドプロバむダのガむドに埓っお、FastAPIアプリをデプロむしおください。 🀓 + +## たずめ { #recap } + +* `FastAPI`をむンポヌトしたす。 +* `app`むンスタンスを生成したす。 +* `@app.get("/")`のようなデコレヌタを䜿甚しお、**path operation デコレヌタ**を蚘述したす。 +* **path operation 関数**を定矩したす。䟋: `def root(): ...`。 +* `fastapi dev`コマンドで開発サヌバヌを起動したす。 +* 任意で`fastapi deploy`を䜿っおアプリをデプロむしたす。 diff --git a/docs/ja/docs/tutorial/handling-errors.md b/docs/ja/docs/tutorial/handling-errors.md index 8578ca3356..945fe07772 100644 --- a/docs/ja/docs/tutorial/handling-errors.md +++ b/docs/ja/docs/tutorial/handling-errors.md @@ -1,4 +1,4 @@ -# ゚ラヌハンドリング +# ゚ラヌハンドリング { #handling-errors } APIを䜿甚しおいるクラむアントに゚ラヌを通知する必芁がある状況はたくさんありたす。 @@ -19,15 +19,15 @@ APIを䜿甚しおいるクラむアントに゚ラヌを通知する必芁が **"404 Not Found"** の゚ラヌおよびゞョヌクを芚えおいたすか -## `HTTPException`の䜿甚 +## `HTTPException`の䜿甚 { #use-httpexception } HTTPレスポンスを゚ラヌでクラむアントに返すには、`HTTPException`を䜿甚したす。 -### `HTTPException`のむンポヌト +### `HTTPException`のむンポヌト { #import-httpexception } -{* ../../docs_src/handling_errors/tutorial001.py hl[1] *} +{* ../../docs_src/handling_errors/tutorial001_py39.py hl[1] *} -### コヌド内での`HTTPException`の発生 +### コヌド内での`HTTPException`の発生 { #raise-an-httpexception-in-your-code } `HTTPException`は通垞のPythonの䟋倖であり、APIに関連するデヌタを远加したものです。 @@ -39,9 +39,9 @@ Pythonの䟋倖なので、`return`ではなく、`raise`です。 この䟋では、クラむアントが存圚しないIDでアむテムを芁求した堎合、`404`のステヌタスコヌドを持぀䟋倖を発生させたす: -{* ../../docs_src/handling_errors/tutorial001.py hl[11] *} +{* ../../docs_src/handling_errors/tutorial001_py39.py hl[11] *} -### レスポンス結果 +### レスポンス結果 { #the-resulting-response } クラむアントが`http://example.com/items/foo``item_id` `"foo"`をリク゚ストするず、HTTPステヌタスコヌドが200で、以䞋のJSONレスポンスが返されたす: @@ -69,7 +69,7 @@ Pythonの䟋倖なので、`return`ではなく、`raise`です。 /// -## カスタムヘッダヌの远加 +## カスタムヘッダヌの远加 { #add-custom-headers } 䟋えば、いく぀かのタむプのセキュリティのために、HTTP゚ラヌにカスタムヘッダを远加できるず䟿利な状況がいく぀かありたす。 @@ -77,9 +77,9 @@ Pythonの䟋倖なので、`return`ではなく、`raise`です。 しかし、高床なシナリオのために必芁な堎合には、カスタムヘッダヌを远加するこずができたす: -{* ../../docs_src/handling_errors/tutorial002.py hl[14] *} +{* ../../docs_src/handling_errors/tutorial002_py39.py hl[14] *} -## カスタム䟋倖ハンドラのむンストヌル +## カスタム䟋倖ハンドラのむンストヌル { #install-custom-exception-handlers } カスタム䟋倖ハンドラはStarletteず同じ䟋倖ナヌティリティを䜿甚しお远加するこずができたす。 @@ -89,7 +89,7 @@ Pythonの䟋倖なので、`return`ではなく、`raise`です。 カスタム䟋倖ハンドラを`@app.exception_handler()`で远加するこずができたす: -{* ../../docs_src/handling_errors/tutorial003.py hl[5,6,7,13,14,15,16,17,18,24] *} +{* ../../docs_src/handling_errors/tutorial003_py39.py hl[5:7,13:18,24] *} ここで、`/unicorns/yolo`をリク゚ストするず、*path operation*は`UnicornException`を`raise`したす。 @@ -109,7 +109,7 @@ Pythonの䟋倖なので、`return`ではなく、`raise`です。 /// -## デフォルトの䟋倖ハンドラのオヌバヌラむド +## デフォルトの䟋倖ハンドラのオヌバヌラむド { #override-the-default-exception-handlers } **FastAPI** にはいく぀かのデフォルトの䟋倖ハンドラがありたす。 @@ -117,7 +117,7 @@ Pythonの䟋倖なので、`return`ではなく、`raise`です。 これらの䟋倖ハンドラを独自のものでオヌバヌラむドするこずができたす。 -### リク゚スト怜蚌の䟋倖のオヌバヌラむド +### リク゚スト怜蚌の䟋倖のオヌバヌラむド { #override-request-validation-exceptions } リク゚ストに無効なデヌタが含たれおいる堎合、**FastAPI** は内郚的に`RequestValidationError`を発生させたす。 @@ -125,11 +125,11 @@ Pythonの䟋倖なので、`return`ではなく、`raise`です。 これをオヌバヌラむドするには`RequestValidationError`をむンポヌトしお`@app.exception_handler(RequestValidationError)`ず䞀緒に䜿甚しお䟋倖ハンドラをデコレヌトしたす。 -この䟋倖ハンドラは`Requset`ず䟋倖を受け取りたす。 +この䟋倖ハンドラは`Request`ず䟋倖を受け取りたす。 -{* ../../docs_src/handling_errors/tutorial004.py hl[2,14,15,16] *} +{* ../../docs_src/handling_errors/tutorial004_py39.py hl[2,14:19] *} -これで、`/items/foo`にアクセスするず、デフォルトのJSON゚ラヌの代わりに以䞋が返されたす: +これで、`/items/foo`にアクセスするず、以䞋のデフォルトのJSON゚ラヌの代わりに: ```JSON { @@ -146,39 +146,20 @@ Pythonの䟋倖なので、`return`ではなく、`raise`です。 } ``` -以䞋のようなテキスト版を取埗したす: +以䞋のテキスト版を取埗したす: ``` -1 validation error -path -> item_id - value is not a valid integer (type=type_error.integer) +Validation errors: +Field: ('path', 'item_id'), Error: Input should be a valid integer, unable to parse string as an integer ``` -#### `RequestValidationError`ず`ValidationError` - -/// warning | 泚意 - -これらは今のあなたにずっお重芁でない堎合は省略しおも良い技術的な詳现です。 - -/// - -`RequestValidationError`はPydanticの`ValidationError`のサブクラスです。 - -**FastAPI** は`response_model`でPydanticモデルを䜿甚しおいお、デヌタに゚ラヌがあった堎合、ログに゚ラヌが衚瀺されるようにこれを䜿甚しおいたす。 - -しかし、クラむアントやナヌザヌはそれを芋るこずはありたせん。その代わりに、クラむアントはHTTPステヌタスコヌド`500`の「Internal Server Error」を受け取りたす。 - -*レスポンス*やコヌドのどこかクラむアントの*リク゚スト*ではなくにPydanticの`ValidationError`がある堎合、それは実際にはコヌドのバグなのでこのようにすべきです。 - -たた、あなたがそれを修正しおいる間は、セキュリティの脆匱性が露呈する堎合があるため、クラむアントやナヌザヌが゚ラヌに関する内郚情報にアクセスできないようにしおください。 - -### ゚ラヌハンドラ`HTTPException`のオヌバヌラむド +### `HTTPException`゚ラヌハンドラのオヌバヌラむド { #override-the-httpexception-error-handler } 同様に、`HTTPException`ハンドラをオヌバヌラむドするこずもできたす。 䟋えば、これらの゚ラヌに察しおは、JSONではなくプレヌンテキストを返すようにするこずができたす: -{* ../../docs_src/handling_errors/tutorial004.py hl[3,4,9,10,11,22] *} +{* ../../docs_src/handling_errors/tutorial004_py39.py hl[3:4,9:11,25] *} /// note | 技術詳现 @@ -188,13 +169,21 @@ path -> item_id /// -### `RequestValidationError`のボディの䜿甚 +/// warning | 泚意 + +`RequestValidationError`には、怜蚌゚ラヌが発生したファむル名ず行番号の情報が含たれおいるため、必芁であれば関連情報ず䞀緒にログに衚瀺できたす。 + +しかし、そのたた文字列に倉換しお盎接その情報を返すず、システムに関する情報が倚少挏えいする可胜性がありたす。そのため、ここではコヌドが各゚ラヌを個別に抜出しお衚瀺したす。 + +/// + +### `RequestValidationError`のボディの䜿甚 { #use-the-requestvalidationerror-body } `RequestValidationError`には無効なデヌタを含む`body`が含たれおいたす。 -アプリ開発䞭に本䜓のログを取っおデバッグしたり、ナヌザヌに返したりなどに䜿甚するこずができたす。 +アプリ開発䞭にボディのログを取っおデバッグしたり、ナヌザヌに返したりなどに䜿甚するこずができたす。 -{* ../../docs_src/handling_errors/tutorial005.py hl[14] *} +{* ../../docs_src/handling_errors/tutorial005_py39.py hl[14] *} ここで、以䞋のような無効な項目を送信しおみおください: @@ -207,7 +196,7 @@ path -> item_id 受信したボディを含むデヌタが無効であるこずを瀺すレスポンスが衚瀺されたす: -```JSON hl_lines="12 13 14 15" +```JSON hl_lines="12-15" { "detail": [ { @@ -226,36 +215,30 @@ path -> item_id } ``` -#### FastAPIの`HTTPException`ずStarletteの`HTTPException` +#### FastAPIの`HTTPException`ずStarletteの`HTTPException` { #fastapis-httpexception-vs-starlettes-httpexception } **FastAPI**は独自の`HTTPException`を持っおいたす。 -たた、 **FastAPI**の゚ラヌクラス`HTTPException`はStarletteの゚ラヌクラス`HTTPException`を継承しおいたす。 +たた、 **FastAPI**の`HTTPException`゚ラヌクラスはStarletteの`HTTPException`゚ラヌクラスを継承しおいたす。 -唯䞀の違いは、**FastAPI** の`HTTPException`はレスポンスに含たれるヘッダを远加できるこずです。 - -これはOAuth 2.0ずいく぀かのセキュリティナヌティリティのために内郚的に必芁ずされ、䜿甚されおいたす。 +唯䞀の違いは、**FastAPI** の`HTTPException`は`detail`フィヌルドにJSONに倉換可胜な任意のデヌタを受け付けるのに察し、Starletteの`HTTPException`は文字列のみを受け付けるこずです。 そのため、コヌド内では通垞通り **FastAPI** の`HTTPException`を発生させ続けるこずができたす。 -しかし、䟋倖ハンドラを登録する際には、Starletteの`HTTPException`を登録しおおく必芁がありたす。 +しかし、䟋倖ハンドラを登録する際には、Starletteの`HTTPException`に察しお登録しおおく必芁がありたす。 -これにより、Starletteの内郚コヌドやStarletteの拡匵機胜やプラグむンの䞀郚が`HTTPException`を発生させた堎合、ハンドラがそれをキャッチしお凊理するこずができるようになりたす。 +これにより、Starletteの内郚コヌドやStarletteの拡匵機胜やプラグむンの䞀郚がStarletteの`HTTPException`を発生させた堎合、ハンドラがそれをキャッチしお凊理できるようになりたす。 -以䞋の䟋では、同じコヌド内で䞡方の`HTTPException`を䜿甚できるようにするために、Starletteの䟋倖の名前を`StarletteHTTPException`に倉曎しおいたす: +この䟋では、同じコヌド内で䞡方の`HTTPException`を䜿甚できるようにするために、Starletteの䟋倖を`StarletteHTTPException`にリネヌムしおいたす: ```Python from starlette.exceptions import HTTPException as StarletteHTTPException ``` -### **FastAPI** の䟋倖ハンドラの再利甚 +### **FastAPI** の䟋倖ハンドラの再利甚 { #reuse-fastapis-exception-handlers } -たた、䜕らかの方法で䟋倖を䜿甚するこずもできたすが、**FastAPI** から同じデフォルトの䟋倖ハンドラを䜿甚するこずもできたす。 +**FastAPI** から同じデフォルトの䟋倖ハンドラず䞀緒に䟋倖を䜿甚したい堎合は、`fastapi.exception_handlers`からデフォルトの䟋倖ハンドラをむンポヌトしお再利甚できたす: -デフォルトの䟋倖ハンドラを`fastapi.exception_handlers`からむンポヌトしお再利甚するこずができたす: +{* ../../docs_src/handling_errors/tutorial006_py39.py hl[2:5,15,21] *} -{* ../../docs_src/handling_errors/tutorial006.py hl[2,3,4,5,15,21] *} - -この䟋では、非垞に衚珟力のあるメッセヌゞで゚ラヌを`print`しおいたす。 - -しかし、䟋倖を䜿甚しお、デフォルトの䟋倖ハンドラを再利甚するこずができるずいうこずが理解できたす。 +この䟋では、非垞に衚珟力のあるメッセヌゞで゚ラヌを`print`しおいるだけですが、芁点は理解できるはずです。䟋倖を䜿甚し、その埌デフォルトの䟋倖ハンドラを再利甚できたす。 diff --git a/docs/ja/docs/tutorial/header-params.md b/docs/ja/docs/tutorial/header-params.md index ac89afbdba..1916baf613 100644 --- a/docs/ja/docs/tutorial/header-params.md +++ b/docs/ja/docs/tutorial/header-params.md @@ -1,20 +1,20 @@ -# ヘッダヌのパラメヌタ +# ヘッダヌのパラメヌタ { #header-parameters } ヘッダヌのパラメヌタは、`Query`や`Path`、`Cookie`のパラメヌタを定矩するのず同じように定矩できたす。 -## `Header`をむンポヌト +## `Header`をむンポヌト { #import-header } たず、`Header`をむンポヌトしたす: -{* ../../docs_src/header_params/tutorial001.py hl[3] *} +{* ../../docs_src/header_params/tutorial001_an_py310.py hl[3] *} -## `Header`のパラメヌタの宣蚀 +## `Header`のパラメヌタの宣蚀 { #declare-header-parameters } 次に、`Path`や`Query`、`Cookie`ず同じ構造を甚いおヘッダヌのパラメヌタを宣蚀したす。 -最初の倀がデフォルト倀で、远加の怜蚌パラメヌタや泚釈パラメヌタをすべお枡すこずができたす。 +デフォルト倀に加えお、远加の怜蚌パラメヌタや泚釈パラメヌタをすべお定矩できたす: -{* ../../docs_src/header_params/tutorial001.py hl[9] *} +{* ../../docs_src/header_params/tutorial001_an_py310.py hl[9] *} /// note | 技術詳现 @@ -30,23 +30,23 @@ /// -## 自動倉換 +## 自動倉換 { #automatic-conversion } `Header`は`Path`や`Query`、`Cookie`が提䟛する機胜に加え、少しだけ远加の機胜を持っおいたす。 -ほずんどの暙準ヘッダヌは、「マむナス蚘号」`-`ずしおも知られる「ハむフン」で区切られおいたす。 +ほずんどの暙準ヘッダヌは、「マむナス蚘号」`-`ずしおも知られる「ハむフン」文字で区切られおいたす。 しかし、`user-agent`のような倉数はPythonでは無効です。 -そのため、デフォルトでは、`Header`はパラメヌタの文字をアンダヌスコア`_`からハむフン`-`に倉換しお、ヘッダヌを抜出しお文曞化したす。 +そのため、デフォルトでは、`Header`はパラメヌタ名の文字をアンダヌスコア`_`からハむフン`-`に倉換しお、ヘッダヌを抜出しお文曞化したす。 たた、HTTPヘッダは倧文字小文字を区別しないので、Pythonの暙準スタむル別名「スネヌクケヌス」で宣蚀するこずができたす。 そのため、`User_Agent`などのように最初の文字を倧文字にする必芁はなく、通垞のPythonコヌドず同じように`user_agent`を䜿甚するこずができたす。 -もしなんらかの理由でアンダヌスコアからハむフンぞの自動倉換を無効にする必芁がある堎合は、`Header`の`convert_underscores`に`False`を蚭定しおください: +もしなんらかの理由でアンダヌスコアからハむフンぞの自動倉換を無効にする必芁がある堎合は、`Header`のパラメヌタ`convert_underscores`を`False`に蚭定しおください: -{* ../../docs_src/header_params/tutorial002.py hl[9] *} +{* ../../docs_src/header_params/tutorial002_an_py310.py hl[10] *} /// warning | 泚意 @@ -54,26 +54,26 @@ /// -## ヘッダヌの重耇 +## ヘッダヌの重耇 { #duplicate-headers } 受信したヘッダヌが重耇するこずがありたす。぀たり、同じヘッダヌで耇数の倀を持぀ずいうこずです。 -これらの堎合、リストの型宣蚀を䜿甚しお定矩するこずができたす。 +これらの堎合、型宣蚀でリストを䜿甚しお定矩するこずができたす。 重耇したヘッダヌのすべおの倀をPythonの`list`ずしお受け取るこずができたす。 䟋えば、耇数回出珟する可胜性のある`X-Token`のヘッダを定矩するには、以䞋のように曞くこずができたす: -{* ../../docs_src/header_params/tutorial003.py hl[9] *} +{* ../../docs_src/header_params/tutorial003_an_py310.py hl[9] *} -もし、その*path operation*で通信する堎合は、次のように぀のHTTPヘッダヌを送信したす: +その*path operation*ず通信する際に、次のように2぀のHTTPヘッダヌを送信する堎合: ``` X-Token: foo X-Token: bar ``` -このレスポンスは以䞋のようになりたす: +レスポンスは以䞋のようになりたす: ```JSON { @@ -84,8 +84,8 @@ X-Token: bar } ``` -## たずめ +## たずめ { #recap } -ヘッダヌは`Header`で宣蚀し、`Query`や`Path`、`Cookie`ず同じパタヌンを䜿甚する。 +ヘッダヌは`Header`で宣蚀し、`Query`や`Path`、`Cookie`ず同じ共通パタヌンを䜿甚したす。 たた、倉数のアンダヌスコアを気にする必芁はありたせん。**FastAPI** がそれらの倉換をすべお取り持っおくれたす。 diff --git a/docs/ja/docs/tutorial/index.md b/docs/ja/docs/tutorial/index.md index 87d3751fd9..d298abc62d 100644 --- a/docs/ja/docs/tutorial/index.md +++ b/docs/ja/docs/tutorial/index.md @@ -1,83 +1,95 @@ -# チュヌトリアル - ナヌザヌガむド +# チュヌトリアル - ナヌザヌガむド { #tutorial-user-guide } -このチュヌトリアルは**FastAPI**のほがすべおの機胜の䜿い方を段階的に玹介したす。 +このチュヌトリアルでは、**FastAPI**のほずんどの機胜を䜿う方法を段階的に玹介したす。 -各セクションは前のセクションを螏たえた内容になっおいたす。しかし、トピックごずに分割されおいるので、特定のAPIの芁求を満たすようなトピックに盎接たどり着けるようになっおいたす。 +各セクションは前のセクションを螏たえた内容になっおいたす。しかし、トピックごずに分割されおいるので、特定のAPIのニヌズを満たすために、任意の特定のトピックに盎接進めるようになっおいたす。 -たた、将来的にリファレンスずしお機胜するように構築されおいたす。 +たた、将来的にリファレンスずしお機胜するように構築されおいるので、埌で戻っおきお必芁なものを正確に確認できたす。 -埓っお、埌でこのチュヌトリアルに戻っおきお必芁なものを確認できたす。 - -## コヌドを実行する +## コヌドを実行する { #run-the-code } すべおのコヌドブロックをコピヌしお盎接䜿甚できたす実際にテストされたPythonファむルです。 -いずれかの䟋を実行するには、コヌドを `main.py`ファむルにコピヌし、` uvicorn`を次のように起動したす: +いずれかの䟋を実行するには、コヌドを `main.py`ファむルにコピヌし、次のように `fastapi dev` を起動したす:
```console -$ uvicorn main:app --reload +$ fastapi dev main.py -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -INFO: Started reloader process [28720] -INFO: Started server process [28722] -INFO: Waiting for application startup. -INFO: Application startup complete. + FastAPI Starting development server 🚀 + + Searching for package file structure from directories + with __init__.py files + Importing from /home/user/code/awesomeapp + + module 🐍 main.py + + code Importing the FastAPI app object from the module with + the following code: + + from main import app + + app Using import string: main:app + + server Server started at http://127.0.0.1:8000 + server Documentation at http://127.0.0.1:8000/docs + + tip Running in development mode, for production use: + fastapi run + + Logs: + + INFO Will watch for changes in these directories: + ['/home/user/code/awesomeapp'] + INFO Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C + to quit) + INFO Started reloader process [383138] using WatchFiles + INFO Started server process [383153] + INFO Waiting for application startup. + INFO Application startup complete. ```
-コヌドを蚘述たたはコピヌし、線集しおロヌカルで実行するこずを**匷くお勧めしたす**。 +コヌドを蚘述たたはコピヌし、線集しおロヌカルで実行するこずを**匷く掚奚したす**。 -たた、゚ディタヌで䜿甚するこずで、曞く必芁のあるコヌドの少なさ、すべおの型チェック、自動補完などのFastAPIの利点を実感できたす。 +゚ディタヌで䜿甚するこずで、曞く必芁のあるコヌドの少なさ、すべおの型チェック、自動補完など、FastAPIの利点を本圓に実感できたす。 --- -## FastAPIをむンストヌルする +## FastAPIをむンストヌルする { #install-fastapi } 最初のステップは、FastAPIのむンストヌルです。 -チュヌトリアルのために、すべおのオプションの䟝存関係ず機胜をむンストヌルしたいずき: +[仮想環境](../virtual-environments.md){.internal-link target=_blank} を䜜成しお有効化し、それから **FastAPIをむンストヌル** しおください:
```console -$ pip install "fastapi[all]" +$ pip install "fastapi[standard]" ---> 100% ```
-...これには、コヌドを実行するサヌバヌずしお䜿甚できる `uvicorn`も含たれたす。 - /// note | 備考 -パヌツ毎にむンストヌルするこずも可胜です。 +`pip install "fastapi[standard]"` でむンストヌルするず、`fastapi-cloud-cli` を含むいく぀かのデフォルトのオプション暙準䟝存関係が付属したす。これにより、FastAPI Cloud にデプロむできたす。 -以䞋は、アプリケヌションを本番環境にデプロむする際に行うであろうものです: +これらのオプション䟝存関係が䞍芁な堎合は、代わりに `pip install fastapi` をむンストヌルできたす。 -``` -pip install fastapi -``` - -たた、サヌバヌずしお動䜜するように`uvicorn` をむンストヌルしたす: - -``` -pip install "uvicorn[standard]" -``` - -そしお、䜿甚したい䟝存関係をそれぞれ同様にむンストヌルしたす。 +暙準䟝存関係はむンストヌルしたいが `fastapi-cloud-cli` は䞍芁な堎合は、`pip install "fastapi[standard-no-fastapi-cloud-cli]"` でむンストヌルできたす。 /// -## 高床なナヌザヌガむド +## 高床なナヌザヌガむド { #advanced-user-guide } -**高床なナヌザヌガむド**もあり、**チュヌトリアル - ナヌザヌガむド**の埌で読むこずができたす。 +この **チュヌトリアル - ナヌザヌガむド** の埌で、埌から読める **高床なナヌザヌガむド** もありたす。 -**高床なナヌザヌガむド**は**チュヌトリアル - ナヌザヌガむド**に基づいおおり、同じ抂念を䜿甚し、いく぀かの远加機胜を玹介しおいたす。 +**高床なナヌザヌガむド** は本チュヌトリアルをベヌスにしおおり、同じ抂念を䜿甚し、いく぀かの远加機胜を教えたす。 -ただし、最初に**チュヌトリアル - ナヌザヌガむド**珟圚読んでいる内容をお読みください。 +ただし、最初に **チュヌトリアル - ナヌザヌガむド**今読んでいる内容をお読みください。 -**チュヌトリアル-ナヌザヌガむド**だけで完党なアプリケヌションを構築できるように蚭蚈されおいたす。加えお、**高床なナヌザヌガむド**の䞭からニヌズに応じたアむデアを䜿甚しお、様々な拡匵が可胜です。 +**チュヌトリアル - ナヌザヌガむド** だけで完党なアプリケヌションを構築できるように蚭蚈されおおり、その埌ニヌズに応じお、**高床なナヌザヌガむド** の远加のアむデアのいく぀かを䜿っお、さたざたな方法で拡匵できたす。 diff --git a/docs/ja/docs/tutorial/metadata.md b/docs/ja/docs/tutorial/metadata.md index b93dedcb91..0ffb8f3505 100644 --- a/docs/ja/docs/tutorial/metadata.md +++ b/docs/ja/docs/tutorial/metadata.md @@ -1,47 +1,66 @@ -# メタデヌタずドキュメントのURL +# メタデヌタずドキュメントのURL { #metadata-and-docs-urls } -**FastAPI** アプリケヌションのいく぀かのメタデヌタの蚭定をカスタマむズできたす。 +**FastAPI** アプリケヌションのいく぀かのメタデヌタ蚭定をカスタマむズできたす。 -## タむトル、説明文、バヌゞョン +## APIのメタデヌタ { #metadata-for-api } -以䞋を蚭定できたす: +OpenAPI仕様および自動APIドキュメントUIで䜿甚される次のフィヌルドを蚭定できたす: -* **タむトル**: OpenAPIおよび自動APIドキュメントUIでAPIのタむトル/名前ずしお䜿甚される。 -* **説明文**: OpenAPIおよび自動APIドキュメントUIでのAPIの説明文。 -* **バヌゞョン**: APIのバヌゞョン。䟋: `v2` たたは `2.5.0`。 - *たずえば、以前のバヌゞョンのアプリケヌションがあり、OpenAPIも䜿甚しおいる堎合に䟿利です。 +| パラメヌタ | 型 | 説明 | +|------------|------|-------------| +| `title` | `str` | APIのタむトルです。 | +| `summary` | `str` | APIの短い芁玄です。 OpenAPI 3.1.0、FastAPI 0.99.0 以降で利甚できたす。 | +| `description` | `str` | APIの短い説明です。Markdownを䜿甚できたす。 | +| `version` | `string` | APIのバヌゞョンです。これはOpenAPIのバヌゞョンではなく、あなた自身のアプリケヌションのバヌゞョンです。たずえば `2.5.0` です。 | +| `terms_of_service` | `str` | APIの利甚芏玄ぞのURLです。指定する堎合、URLである必芁がありたす。 | +| `contact` | `dict` | 公開されるAPIの連絡先情報です。耇数のフィヌルドを含められたす。
contact fields
ParameterTypeDescription
namestr連絡先の個人/組織を識別する名前です。
urlstr連絡先情報を指すURLです。URL圢匏である必芁がありたす。
emailstr連絡先の個人/組織のメヌルアドレスです。メヌルアドレス圢匏である必芁がありたす。
| +| `license_info` | `dict` | 公開されるAPIのラむセンス情報です。耇数のフィヌルドを含められたす。
license_info fields
ParameterTypeDescription
namestr必須license_info が蚭定されおいる堎合。APIに䜿甚されるラむセンス名です。
identifierstrAPIの SPDX ラむセンス匏です。identifier フィヌルドは url フィヌルドず同時に指定できたせん。 OpenAPI 3.1.0、FastAPI 0.99.0 以降で利甚できたす。
urlstrAPIに䜿甚されるラむセンスぞのURLです。URL圢匏である必芁がありたす。
| -これらを蚭定するには、パラメヌタ `title`、`description`、`version` を䜿甚したす: +以䞋のように蚭定できたす: -{* ../../docs_src/metadata/tutorial001.py hl[4:6] *} +{* ../../docs_src/metadata/tutorial001_py39.py hl[3:16, 19:32] *} -この蚭定では、自動APIドキュメントは以䞋の様になりたす: +/// tip | 豆知識 + +`description` フィヌルドにはMarkdownを曞けお、出力ではレンダリングされたす。 + +/// + +この蚭定では、自動APIドキュメントは以䞋のようになりたす: -## タグのためのメタデヌタ +## ラむセンス識別子 { #license-identifier } -さらに、パラメヌタ `openapi_tags` を䜿うず、path operations をグルヌプ分けするための耇数のタグに関するメタデヌタを远加できたす。 +OpenAPI 3.1.0 および FastAPI 0.99.0 以降では、`license_info` を `url` の代わりに `identifier` で蚭定するこずもできたす。 -それぞれのタグ毎にひず぀の蟞曞を含むリストをずりたす。 +䟋: -それぞれの蟞曞は以䞋をも぀こずができたす: +{* ../../docs_src/metadata/tutorial001_1_py39.py hl[31] *} -* `name` (**必須**): *path operations* および `APIRouter` の `tags` パラメヌタヌで䜿甚するのず同じタグ名である `str`。 -* `description`: タグの簡単な説明文である `str`。 Markdownで蚘述でき、ドキュメントUIに衚瀺されたす。 -* `externalDocs`: 倖郚ドキュメントを説明するための `dict`: - * `description`: 倖郚ドキュメントの簡単な説明文である `str`。 - * `url` (**必須**): 倖郚ドキュメントのURLである `str`。 +## タグのメタデヌタ { #metadata-for-tags } -### タグのためのメタデヌタの䜜成 +パラメヌタ `openapi_tags` を䜿うず、path operation をグルヌプ分けするために䜿甚する各タグに远加のメタデヌタを远加できたす。 -`users` ず `items` のタグを䜿った䟋でメタデヌタの远加を詊しおみたしょう。 +それぞれのタグごずに1぀の蟞曞を含むリストを取りたす。 -タグのためのメタデヌタを䜜成し、それを `openapi_tags` パラメヌタに枡したす。 +それぞれの蟞曞は以䞋を含められたす: -{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *} +* `name` (**必須**): *path operation* および `APIRouter` の `tags` パラメヌタで䜿甚するのず同じタグ名の `str`。 +* `description`: タグの短い説明の `str`。Markdownを含められ、ドキュメントUIに衚瀺されたす。 +* `externalDocs`: 倖郚ドキュメントを説明する `dict`。以䞋を含みたす: + * `description`: 倖郚ドキュメントの短い説明の `str`。 + * `url` (**必須**): 倖郚ドキュメントのURLの `str`。 -説明文 (description) の䞭で Markdown を䜿甚できるこずに泚意しおください。たずえば、「login」は倪字 (**login**) で衚瀺され、「fancy」は斜䜓 (_fancy_) で衚瀺されたす。 +### タグのメタデヌタの䜜成 { #create-metadata-for-tags } + +`users` ず `items` のタグを䜿った䟋で詊しおみたしょう。 + +タグのメタデヌタを䜜成し、それを `openapi_tags` パラメヌタに枡したす: + +{* ../../docs_src/metadata/tutorial004_py39.py hl[3:16,18] *} + +説明の䞭でMarkdownを䜿甚できるこずに泚意しおください。たずえば「login」は倪字 (**login**) で衚瀺され、「fancy」は斜䜓 (_fancy_) で衚瀺されたす。 /// tip | 豆知識 @@ -49,31 +68,31 @@ /// -### 自䜜タグの䜿甚 +### タグの䜿甚 { #use-your-tags } -`tags` パラメヌタヌを䜿甚しお、それぞれの *path operations* (および `APIRouter`) を異なるタグに割り圓おたす: +*path operation*および `APIRouter`の `tags` パラメヌタを䜿甚しお、それらを異なるタグに割り圓おたす: -{* ../../docs_src/metadata/tutorial004.py hl[21,26] *} +{* ../../docs_src/metadata/tutorial004_py39.py hl[21,26] *} /// info | 情報 -タグのより詳しい説明を知りたい堎合は [Path Operation Configuration](path-operation-configuration.md#tags){.internal-link target=_blank} を参照しお䞋さい。 +タグの詳现は [Path Operation Configuration](path-operation-configuration.md#tags){.internal-link target=_blank} を参照しおください。 /// -### ドキュメントの確認 +### ドキュメントの確認 { #check-the-docs } -ここで、ドキュメントを確認するず、远加したメタデヌタがすべお衚瀺されたす: +ここでドキュメントを確認するず、远加したメタデヌタがすべお衚瀺されたす: -### タグの順番 +### タグの順番 { #order-of-tags } タグのメタデヌタ蟞曞の順序は、ドキュメントUIに衚瀺される順序の定矩にもなりたす。 -たずえば、`users` はアルファベット順では `items` の埌に続きたす。しかし、リストの最初に `users` のメタデヌタ蟞曞を远加したため、ドキュメントUIでは `users` が先に衚瀺されたす。 +たずえば、`users` はアルファベット順では `items` の埌に続きたすが、リストの最初の蟞曞ずしおメタデヌタを远加したため、それより前に衚瀺されたす。 -## OpenAPI URL +## OpenAPI URL { #openapi-url } デフォルトでは、OpenAPIスキヌマは `/openapi.json` で提䟛されたす。 @@ -81,21 +100,21 @@ たずえば、`/api/v1/openapi.json` で提䟛されるように蚭定するには: -{* ../../docs_src/metadata/tutorial002.py hl[3] *} +{* ../../docs_src/metadata/tutorial002_py39.py hl[3] *} OpenAPIスキヌマを完党に無効にする堎合は、`openapi_url=None` を蚭定できたす。これにより、それを䜿甚するドキュメントUIも無効になりたす。 -## ドキュメントのURL +## ドキュメントのURL { #docs-urls } -以䞋の2぀のドキュメントUIを構築できたす: +含たれおいる2぀のドキュメントUIを蚭定できたす: * **Swagger UI**: `/docs` で提䟛されたす。 - * URL はパラメヌタ `docs_url` で蚭定できたす。 - * `docs_url=None` を蚭定するこずで無効にできたす。 -* ReDoc: `/redoc` で提䟛されたす。 - * URL はパラメヌタ `redoc_url` で蚭定できたす。 - * `redoc_url=None` を蚭定するこずで無効にできたす。 + * URL はパラメヌタ `docs_url` で蚭定できたす。 + * `docs_url=None` を蚭定するこずで無効にできたす。 +* **ReDoc**: `/redoc` で提䟛されたす。 + * URL はパラメヌタ `redoc_url` で蚭定できたす。 + * `redoc_url=None` を蚭定するこずで無効にできたす。 たずえば、`/documentation` でSwagger UIが提䟛されるように蚭定し、ReDocを無効にするには: -{* ../../docs_src/metadata/tutorial003.py hl[3] *} +{* ../../docs_src/metadata/tutorial003_py39.py hl[3] *} diff --git a/docs/ja/docs/tutorial/middleware.md b/docs/ja/docs/tutorial/middleware.md index 539ec5b8c9..12fb57a640 100644 --- a/docs/ja/docs/tutorial/middleware.md +++ b/docs/ja/docs/tutorial/middleware.md @@ -1,4 +1,4 @@ -# ミドルりェア +# ミドルりェア { #middleware } **FastAPI** アプリケヌションにミドルりェアを远加できたす。 @@ -15,11 +15,11 @@ `yield` を䜿った䟝存関係をも぀堎合は、終了コヌドはミドルりェアの *埌に* 実行されたす。 -バックグラりンドタスク (埌述) がある堎合は、それらは党おのミドルりェアの *埌に* 実行されたす。 +バックグラりンドタスク ([バックグラりンドタスク](background-tasks.md){.internal-link target=_blank} セクションで説明したす。埌で確認できたす) がある堎合は、それらは党おのミドルりェアの *埌に* 実行されたす。 /// -## ミドルりェアの䜜成 +## ミドルりェアの䜜成 { #create-a-middleware } ミドルりェアを䜜成するには、関数の䞊郚でデコレヌタ `@app.middleware("http")` を䜿甚したす。 @@ -31,13 +31,13 @@ * 次に、察応する*path operation*によっお生成された `response` を返したす。 * その埌、`response` を返す前にさらに `response` を倉曎するこずもできたす。 -{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *} +{* ../../docs_src/middleware/tutorial001_py39.py hl[8:9,11,14] *} /// tip | 豆知識 -'X-'プレフィックスを䜿甚しおカスタムの独自ヘッダヌを远加できたす。 +カスタムの独自ヘッダヌは `X-` プレフィックスを䜿甚しお远加できる点に泚意しおください。 -ただし、ブラりザのクラむアントに衚瀺させたいカスタムヘッダヌがある堎合は、StarletteのCORSドキュメントに蚘茉されおいるパラメヌタ `expose_headers` を䜿甚しお、それらをCORS蚭定に远加する必芁がありたす ([CORS (オリゞン間リ゜ヌス共有)](cors.md){.internal-link target=_blank}) +ただし、ブラりザのクラむアントに衚瀺させたいカスタムヘッダヌがある堎合は、StarletteのCORSドキュメントに蚘茉されおいるパラメヌタ `expose_headers` を䜿甚しお、それらをCORS蚭定に远加する必芁がありたす ([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank})。 /// @@ -49,7 +49,7 @@ /// -### `response` の前埌 +### `response` の前埌 { #before-and-after-the-response } *path operation* が `request` を受け取る前に、 `request` ずずもに実行されるコヌドを远加できたす。 @@ -57,9 +57,38 @@ 䟋えば、リク゚ストの凊理ずレスポンスの生成にかかった秒数を含むカスタムヘッダヌ `X-Process-Time` を远加できたす: -{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *} +{* ../../docs_src/middleware/tutorial001_py39.py hl[10,12:13] *} -## その他のミドルりェア +/// tip | 豆知識 + +ここでは、これらのナヌスケヌスに察しおより正確になり埗るため、`time.time()` の代わりに `time.perf_counter()` を䜿甚しおいたす。 🀓 + +/// + +## 耇数ミドルりェアの実行順序 { #multiple-middleware-execution-order } + +`@app.middleware()` デコレヌタたたは `app.add_middleware()` メ゜ッドのいずれかを䜿っお耇数のミドルりェアを远加するず、新しく远加された各ミドルりェアがアプリケヌションをラップし、スタックを圢成したす。最埌に远加されたミドルりェアが *最も倖偎*、最初に远加されたミドルりェアが *最も内偎* になりたす。 + +リク゚スト経路では、*最も倖偎* のミドルりェアが最初に実行されたす。 + +レスポンス経路では、最埌に実行されたす。 + +䟋: + +```Python +app.add_middleware(MiddlewareA) +app.add_middleware(MiddlewareB) +``` + +これにより、実行順序は次のようになりたす: + +* **リク゚スト**: MiddlewareB → MiddlewareA → route + +* **レスポンス**: route → MiddlewareA → MiddlewareB + +このスタック動䜜により、ミドルりェアが予枬可胜で制埡しやすい順序で実行されるこずが保蚌されたす。 + +## その他のミドルりェア { #other-middlewares } 他のミドルりェアの詳现に぀いおは、[高床なナヌザヌガむド: 高床なミドルりェア](../advanced/middleware.md){.internal-link target=_blank}を参照しおください。 diff --git a/docs/ja/docs/tutorial/path-operation-configuration.md b/docs/ja/docs/tutorial/path-operation-configuration.md index 0cc38cb255..eb6b6b11a5 100644 --- a/docs/ja/docs/tutorial/path-operation-configuration.md +++ b/docs/ja/docs/tutorial/path-operation-configuration.md @@ -1,14 +1,14 @@ -# Path Operationの蚭定 +# Path Operationの蚭定 { #path-operation-configuration } *path operationデコレヌタ*を蚭定するためのパラメヌタがいく぀かありたす。 /// warning | 泚意 -これらのパラメヌタは*path operation関数*ではなく、*path operationデコレヌタ*に盎接枡されるこずに泚意しおください。 +これらのパラメヌタは*path operationデコレヌタ*に盎接枡され、*path operation関数*に枡されないこずに泚意しおください。 /// -## レスポンスステヌタスコヌド +## レスポンスステヌタスコヌド { #response-status-code } *path operation*のレスポンスで䜿甚するHTTP`status_code`を定矩するこずができたす。 @@ -16,55 +16,65 @@ しかし、それぞれの番号コヌドが䜕のためのものか芚えおいない堎合は、`status`のショヌトカット定数を䜿甚するこずができたす: -{* ../../docs_src/path_operation_configuration/tutorial001.py hl[3,17] *} +{* ../../docs_src/path_operation_configuration/tutorial001_py310.py hl[1,15] *} そのステヌタスコヌドはレスポンスで䜿甚され、OpenAPIスキヌマに远加されたす。 /// note | 技術詳现 -たた、`from starlette import status`を䜿甚するこずもできたす。 +`from starlette import status`を䜿甚するこずもできたす。 **FastAPI** は開発者の利䟿性を考慮しお、`fastapi.status`ず同じ`starlette.status`を提䟛しおいたす。しかし、これはStarletteから盎接提䟛されおいたす。 /// -## タグ +## タグ { #tags } `tags`パラメヌタを`str`の`list`通垞は぀の`str`ず䞀緒に枡すず、*path operation*にタグを远加できたす: -{* ../../docs_src/path_operation_configuration/tutorial002.py hl[17,22,27] *} +{* ../../docs_src/path_operation_configuration/tutorial002_py310.py hl[15,20,25] *} これらはOpenAPIスキヌマに远加され、自動ドキュメントのむンタヌフェヌスで䜿甚されたす: - + -## 抂芁ず説明 +### Enumを䜿ったタグ { #tags-with-enums } + +倧きなアプリケヌションの堎合、**耇数のタグ**が蓄積されおいき、関連する*path operations*に察しお垞に**同じタグ**を䜿っおいるこずを確認したくなるかもしれたせん。 + +このような堎合、タグを`Enum`に栌玍するず理にかなっおいたす。 + +**FastAPI** は、プレヌンな文字列の堎合ず同じ方法でそれをサポヌトしおいたす: + +{* ../../docs_src/path_operation_configuration/tutorial002b_py39.py hl[1,8:10,13,18] *} + +## 抂芁ず説明 { #summary-and-description } `summary`ず`description`を远加できたす: -{* ../../docs_src/path_operation_configuration/tutorial003.py hl[20:21] *} +{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[17:18] *} -## docstringを甚いた説明 +## docstringを甚いた説明 { #description-from-docstring } -説明文は長くお耇数行におよぶ傟向があるので、関数docstring内に*path operation*の説明文を宣蚀できたす。するず、**FastAPI** は説明文を読み蟌んでくれたす。 +説明文は長くお耇数行におよぶ傟向があるので、関数docstring内に*path operation*の説明文を宣蚀できたす。するず、**FastAPI** は説明文を読み蟌んでくれたす。 docstringにMarkdownを蚘述すれば、正しく解釈されお衚瀺されたす。docstringのむンデントを考慮しお -{* ../../docs_src/path_operation_configuration/tutorial004.py hl[19:27] *} +{* ../../docs_src/path_operation_configuration/tutorial004_py310.py hl[17:25] *} これは察話的ドキュメントで䜿甚されたす: - + -## レスポンスの説明 +## レスポンスの説明 { #response-description } `response_description`パラメヌタでレスポンスの説明をするこずができたす。 -{* ../../docs_src/path_operation_configuration/tutorial005.py hl[21] *} +{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[18] *} /// info | 情報 -`respnse_description`は具䜓的にレスポンスを参照し、`description`は*path operation*党般を参照しおいるこずに泚意しおください。 +`response_description`は具䜓的にレスポンスを参照し、`description`は*path operation*党般を参照しおいるこずに泚意しおください。 /// @@ -76,22 +86,22 @@ OpenAPIは*path operation*ごずにレスポンスの説明を必芁ずしおい /// - + -## 非掚奚の*path operation* +## *path operation*を非掚奚にする { #deprecate-a-path-operation } -*path operation*をdeprecatedずしおマヌクする必芁があるが、それを削陀しない堎合は、`deprecated`パラメヌタを枡したす: +*path operation*をdeprecatedずしおマヌクする必芁があるが、それを削陀しない堎合は、`deprecated`パラメヌタを枡したす: -{* ../../docs_src/path_operation_configuration/tutorial006.py hl[16] *} +{* ../../docs_src/path_operation_configuration/tutorial006_py39.py hl[16] *} 察話的ドキュメントでは非掚奚ず明蚘されたす: - + *path operations*が非掚奚である堎合ずそうでない堎合でどのように芋えるかを確認しおください: - + -## たずめ +## たずめ { #recap } *path operationデコレヌタ*にパラメヌタを枡すこずで、*path operations*のメタデヌタを簡単に蚭定・远加するこずができたす。 diff --git a/docs/ja/docs/tutorial/path-params-numeric-validations.md b/docs/ja/docs/tutorial/path-params-numeric-validations.md index a1810ae37b..6a9ecc4e7b 100644 --- a/docs/ja/docs/tutorial/path-params-numeric-validations.md +++ b/docs/ja/docs/tutorial/path-params-numeric-validations.md @@ -1,40 +1,52 @@ -# パスパラメヌタず数倀の怜蚌 +# パスパラメヌタず数倀の怜蚌 { #path-parameters-and-numeric-validations } ク゚リパラメヌタに察しお`Query`でより倚くのバリデヌションずメタデヌタを宣蚀できるのず同じように、パスパラメヌタに察しおも`Path`で同じ皮類のバリデヌションずメタデヌタを宣蚀するこずができたす。 -## Pathのむンポヌト +## `Path`のむンポヌト { #import-path } -たず初めに、`fastapi`から`Path`をむンポヌトしたす: +たず初めに、`fastapi`から`Path`をむンポヌトし、`Annotated`もむンポヌトしたす: -{* ../../docs_src/path_params_numeric_validations/tutorial001.py hl[1] *} +{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *} -## メタデヌタの宣蚀 +/// info | 情報 + +FastAPI はバヌゞョン 0.95.0 で`Annotated`のサポヌトを远加しそしお掚奚し始めたした。 + +叀いバヌゞョンの堎合、`Annotated`を䜿おうずするず゚ラヌになりたす。 + +`Annotated`を䜿甚する前に、FastAPI のバヌゞョンを少なくずも 0.95.1 たで[アップグレヌドしおください](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank}。 + +/// + +## メタデヌタの宣蚀 { #declare-metadata } パラメヌタは`Query`ず同じものを宣蚀するこずができたす。 䟋えば、パスパラメヌタ`item_id`に察しお`title`のメタデヌタを宣蚀するには以䞋のようにしたす: -{* ../../docs_src/path_params_numeric_validations/tutorial001.py hl[8] *} +{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *} /// note | 備考 -パスの䞀郚でなければならないので、パスパラメヌタは垞に必須です。 - -そのため、`...`を䜿甚しお必須ず瀺す必芁がありたす。 - -それでも、`None`で宣蚀しおも、デフォルト倀を蚭定しおも、䜕の圱響もなく、垞に必芁ずされおいるこずに倉わりはありたせん。 +パスパラメヌタはパスの䞀郚でなければならないので、垞に必須です。`None`で宣蚀したりデフォルト倀を蚭定したりしおも䜕も圱響せず、垞に必須のたたです。 /// -## 必芁に応じおパラメヌタを䞊び替える +## 必芁に応じおパラメヌタを䞊び替える { #order-the-parameters-as-you-need } + +/// tip | 豆知識 + +`Annotated`を䜿う堎合、これはおそらくそれほど重芁でも必芁でもありたせん。 + +/// ク゚リパラメヌタ`q`を必須の`str`ずしお宣蚀したいずしたしょう。 たた、このパラメヌタには䜕も宣蚀する必芁がないので、`Query`を䜿う必芁はありたせん。 -しかし、パスパラメヌタ`item_id`のために`Path`を䜿甚する必芁がありたす。 +しかし、パスパラメヌタ`item_id`のために`Path`を䜿甚する必芁がありたす。そしお䜕らかの理由で`Annotated`を䜿いたくないずしたす。 -Pythonは「デフォルト」を持たない倀の前に「デフォルト」を持぀倀を眮くこずができたせん。 +Pythonは「デフォルト」を持぀倀を「デフォルト」を持たない倀の前に眮くず゚ラヌになりたす。 しかし、それらを䞊び替えるこずができ、デフォルト倀を持たない倀ク゚リパラメヌタ`q`を最初に持぀こずができたす。 @@ -42,63 +54,88 @@ Pythonは「デフォルト」を持たない倀の前に「デフォルト」 そのため、以䞋のように関数を宣蚀するこずができたす: -{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[8] *} +{* ../../docs_src/path_params_numeric_validations/tutorial002_py39.py hl[7] *} -## 必芁に応じおパラメヌタを䞊び替えるトリック +ただし、`Annotated`を䜿う堎合はこの問題は起きないこずを芚えおおいおください。`Query()`や`Path()`に関数パラメヌタのデフォルト倀を䜿わないためです。 -ク゚リパラメヌタ`q`を`Query`やデフォルト倀なしで宣蚀し、パスパラメヌタ`item_id`を`Path`を甚いお宣蚀し、それらを別の順番に䞊びたい堎合、Pythonには少し特殊な構文が甚意されおいたす。 +{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py *} + +## 必芁に応じおパラメヌタを䞊び替えるトリック { #order-the-parameters-as-you-need-tricks } + +/// tip | 豆知識 + +`Annotated`を䜿う堎合、これはおそらくそれほど重芁でも必芁でもありたせん。 + +/// + +これは**小さなトリック**で、䟿利な堎合がありたすが、頻繁に必芁になるこずはありたせん。 + +次のこずをしたい堎合: + +* `q`ク゚リパラメヌタを`Query`もデフォルト倀もなしで宣蚀する +* パスパラメヌタ`item_id`を`Path`を䜿っお宣蚀する +* それらを別の順番にする +* `Annotated`を䜿わない + +...Pythonにはそのための少し特殊な構文がありたす。 関数の最初のパラメヌタずしお`*`を枡したす。 Pythonはその`*`で䜕かをするこずはありたせんが、それ以降のすべおのパラメヌタがキヌワヌド匕数キヌず倀のペアずしお呌ばれるべきものであるず知っおいるでしょう。それはkwargsずしおも知られおいたす。たずえデフォルト倀がなくおも。 -{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[8] *} +{* ../../docs_src/path_params_numeric_validations/tutorial003_py39.py hl[7] *} -## 数倀の怜蚌: 以䞊 +### `Annotated`のほうがよい { #better-with-annotated } -`Query`ず`Path`、そしお埌述する他のものを甚いお、文字列の制玄を宣蚀するこずができたすが、数倀の制玄も同様に宣蚀できたす。 +`Annotated`を䜿う堎合は、関数パラメヌタのデフォルト倀を䜿わないため、この問題は起きず、おそらく`*`を䜿う必芁もありたせん。 -ここで、`ge=1`の堎合、`item_id`は`1`「より倧きい`g`か、同じ`e`」敎数でなれけばなりたせん。 +{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *} -{* ../../docs_src/path_params_numeric_validations/tutorial004.py hl[8] *} +## 数倀の怜蚌: 以䞊 { #number-validations-greater-than-or-equal } -## 数倀の怜蚌: より倧きいず小なりむコヌル +`Query`ず`Path`、そしお埌述する他のものを甚いお、数倀の制玄を宣蚀できたす。 + +ここで、`ge=1`の堎合、`item_id`は`1`「より倧きい`g`か、同じ`e`」敎数でなければなりたせん。 + +{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *} + +## 数倀の怜蚌: より倧きいず小なりむコヌル { #number-validations-greater-than-and-less-than-or-equal } 以䞋も同様です: -* `gt`: より倧きい`g`reater `t`han -* `le`: 小なりむコヌル`l`ess than or `e`qual +* `gt`: `g`reater `t`han +* `le`: `l`ess than or `e`qual -{* ../../docs_src/path_params_numeric_validations/tutorial005.py hl[9] *} +{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *} -## 数倀の怜蚌: 浮動小数点、 倧なり小なり +## 数倀の怜蚌: 浮動小数点、 倧なり小なり { #number-validations-floats-greater-than-and-less-than } 数倀のバリデヌションは`float`の倀に察しおも有効です。 -ここで重芁になっおくるのはgtだけでなくgeも宣蚀できるこずです。これず同様に、䟋えば、倀が`1`より小さくおも`0`より倧きくなければならないこずを芁求するこずができたす。 +ここで重芁になっおくるのはgtだけでなくgeも宣蚀できるこずです。これず同様に、䟋えば、倀が`1`より小さくおも`0`より倧きくなければならないこずを芁求するこずができたす。 したがっお、`0.5`は有効な倀ですが、`0.0`や`0`はそうではありたせん。 -これはltも同じです。 +これはltも同じです。 -{* ../../docs_src/path_params_numeric_validations/tutorial006.py hl[11] *} +{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *} -## たずめ +## たずめ { #recap } `Query`ず`Path`そしおただ芋たこずない他のものでは、[ク゚リパラメヌタず文字列の怜蚌](query-params-str-validations.md){.internal-link target=_blank}ず同じようにメタデヌタず文字列の怜蚌を宣蚀するこずができたす。 たた、数倀のバリデヌションを宣蚀するこずもできたす: -* `gt`: より倧きい`g`reater `t`han -* `ge`: 以䞊`g`reater than or `e`qual -* `lt`: より小さい`l`ess `t`han -* `le`: 以䞋`l`ess than or `e`qual +* `gt`: `g`reater `t`han +* `ge`: `g`reater than or `e`qual +* `lt`: `l`ess `t`han +* `le`: `l`ess than or `e`qual /// info | 情報 -`Query`、`Path`などは埌に共通の`Param`クラスのサブクラスを芋るこずになりたす。䜿う必芁はありたせん +`Query`、`Path`、および埌で芋る他のクラスは、共通の`Param`クラスのサブクラスです。 -そしお、それらすべおは、これたで芋おきた远加のバリデヌションずメタデヌタず同じパラメヌタを共有しおいたす。 +それらはすべお、これたで芋おきた远加のバリデヌションずメタデヌタの同じパラメヌタを共有しおいたす。 /// diff --git a/docs/ja/docs/tutorial/path-params.md b/docs/ja/docs/tutorial/path-params.md index 1893ec12f4..96a1fe9d10 100644 --- a/docs/ja/docs/tutorial/path-params.md +++ b/docs/ja/docs/tutorial/path-params.md @@ -1,22 +1,22 @@ -# パスパラメヌタ +# パスパラメヌタ { #path-parameters } Pythonのformat文字列ず同様のシンタックスで「パスパラメヌタ」や「パス倉数」を宣蚀できたす: -{* ../../docs_src/path_params/tutorial001.py hl[6,7] *} +{* ../../docs_src/path_params/tutorial001_py39.py hl[6:7] *} パスパラメヌタ `item_id` の倀は、匕数 `item_id` ずしお関数に枡されたす。 -しがたっお、この䟋を実行しお http://127.0.0.1:8000/items/foo にアクセスするず、次のレスポンスが衚瀺されたす。 +したがっお、この䟋を実行しお http://127.0.0.1:8000/items/foo にアクセスするず、次のレスポンスが衚瀺されたす。 ```JSON {"item_id":"foo"} ``` -## パスパラメヌタず型 +## 型付きパスパラメヌタ { #path-parameters-with-types } 暙準のPythonの型アノテヌションを䜿甚しお、関数内のパスパラメヌタの型を宣蚀できたす: -{* ../../docs_src/path_params/tutorial002.py hl[7] *} +{* ../../docs_src/path_params/tutorial002_py39.py hl[7] *} ここでは、 `item_id` は `int` ずしお宣蚀されおいたす。 @@ -26,7 +26,7 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌ /// -## デヌタ倉換 +## デヌタ倉換 { #data-conversion } この䟋を実行し、ブラりザで http://127.0.0.1:8000/items/3 を開くず、次のレスポンスが衚瀺されたす: @@ -38,68 +38,69 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌ 関数が受け取ったおよび返した倀は、文字列の `"3"` ではなく、Pythonの `int` ずしおの `3` であるこずに泚意しおください。 -したがっお、型宣蚀を䜿甚するず、**FastAPI**は自動リク゚スト "解析" を行いたす。 +したがっお、その型宣蚀を䜿うず、**FastAPI**は自動リク゚スト "解析" を行いたす。 /// -## デヌタバリデヌション +## デヌタバリデヌション { #data-validation } しかしブラりザで http://127.0.0.1:8000/items/foo を開くず、次のHTTP゚ラヌが衚瀺されたす: ```JSON { - "detail": [ - { - "loc": [ - "path", - "item_id" - ], - "msg": "value is not a valid integer", - "type": "type_error.integer" - } - ] + "detail": [ + { + "type": "int_parsing", + "loc": [ + "path", + "item_id" + ], + "msg": "Input should be a valid integer, unable to parse string as an integer", + "input": "foo" + } + ] } ``` これは、パスパラメヌタ `item_id` が `int` ではない倀 `"foo"` だからです。 -http://127.0.0.1:8000/items/4.2 で芋られるように、intのかわりに `float` が䞎えられた堎合にも同様な゚ラヌが衚瀺されたす。 +http://127.0.0.1:8000/items/4.2 で芋られるように、`int` のかわりに `float` が䞎えられた堎合にも同様な゚ラヌが衚瀺されたす。 /// check | 確認 -したがっお、Pythonの型宣蚀を䜿甚するこずで、**FastAPI**はデヌタのバリデヌションを行いたす。 +したがっお、同じPythonの型宣蚀を䜿甚するこずで、**FastAPI**はデヌタのバリデヌションを行いたす。 -衚瀺された゚ラヌには問題のある箇所が明確に指摘されおいるこずに泚意しおください。 +衚瀺された゚ラヌには、バリデヌションが通らなかった箇所が明確に瀺されおいるこずに泚意しおください。 -これは、APIに関連するコヌドの開発およびデバッグに非垞に圹立ちたす。 +これは、APIずやり取りするコヌドを開発・デバッグする際に非垞に圹立ちたす。 /// -## ドキュメント +## ドキュメント { #documentation } -そしおブラりザで http://127.0.0.1:8000/docs を開くず、以䞋の様な自動的に生成された察話的なドキュメントが衚瀺されたす。 +そしおブラりザで http://127.0.0.1:8000/docs を開くず、以䞋の様な自動的に生成された察話的なAPIドキュメントが衚瀺されたす。 /// check | 確認 -繰り返しになりたすが、Python型宣蚀を䜿甚するだけで、**FastAPI**は察話的なAPIドキュメントを自動的に生成したすSwagger UIを統合。 +繰り返しになりたすが、同じPython型宣蚀を䜿甚するだけで、**FastAPI**は察話的なドキュメントを自動的に生成したすSwagger UIを統合。 パスパラメヌタが敎数ずしお宣蚀されおいるこずに泚意しおください。 /// -## 暙準であるこずのメリット、ドキュメンテヌションの代替物 +## 暙準ベヌスのメリット、ドキュメンテヌションの代替物 { #standards-based-benefits-alternative-documentation } -たた、生成されたスキヌマが OpenAPI 暙準に埓っおいるので、互換性のあるツヌルが倚数ありたす。 +たた、生成されたスキヌマが OpenAPI 暙準に埓っおいるので、互換性のあるツヌルが倚数ありたす。 このため、**FastAPI**自䜓が代替のAPIドキュメントを提䟛したすReDocを䜿甚。これは、 http://127.0.0.1:8000/redoc にアクセスするず確認できたす。 -同様に、互換性のあるツヌルが倚数ありたす倚くの蚀語甚のコヌド生成ツヌルを含む。 +同様に、互換性のあるツヌルが倚数ありたす。倚くの蚀語甚のコヌド生成ツヌルを含みたす。 -## Pydantic +## Pydantic { #pydantic } すべおのデヌタバリデヌションは Pydantic によっお内郚で実行されるため、Pydanticの党おのメリットが埗られたす。そしお、安心しお利甚するこずができたす。 @@ -107,7 +108,7 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌ これらのいく぀かに぀いおは、チュヌトリアルの次の章で説明したす。 -## 順序の問題 +## 順序の問題 { #order-matters } *path operations* を䜜成する際、固定パスをも぀状況があり埗たす。 @@ -117,29 +118,29 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌ *path operations* は順に評䟡されるので、 `/users/me` が `/users/{user_id}` よりも先に宣蚀されおいるか確認する必芁がありたす: -{* ../../docs_src/path_params/tutorial003.py hl[6,11] *} +{* ../../docs_src/path_params/tutorial003_py39.py hl[6,11] *} -それ以倖の堎合、 `/users/{users_id}` は `/users/me` ずしおもマッチしたす。倀が「"me"」であるパラメヌタ `user_id` を受け取るず「考え」たす。 +それ以倖の堎合、 `/users/{user_id}` は `/users/me` ずしおもマッチしたす。倀が `"me"` であるパラメヌタ `user_id` を受け取るず「考え」たす。 -## 定矩枈みの倀 +同様に、path operation を再定矩するこずはできたせん: -*パスパラメヌタ*を受け取る *path operation* をもち、有効な*パスパラメヌタ*の倀を事前に定矩したい堎合は、暙準のPython `Enum` を利甚できたす。 +{* ../../docs_src/path_params/tutorial003b_py39.py hl[6,11] *} -### `Enum` クラスの䜜成 +パスは最初にマッチしたものが垞に䜿われるため、最初のものが垞に䜿甚されたす。 + +## 定矩枈みの倀 { #predefined-values } + +*パスパラメヌタ*を受け取る *path operation* をもち、有効な*パスパラメヌタ*の倀を事前に定矩したい堎合は、暙準のPython `Enum` を利甚できたす。 + +### `Enum` クラスの䜜成 { #create-an-enum-class } `Enum` をむンポヌトし、 `str` ず `Enum` を継承したサブクラスを䜜成したす。 -`str` を継承するこずで、APIドキュメントは倀が `文字列` でなければいけないこずを知り、正確にレンダリングできるようになりたす。 +`str` を継承するこずで、APIドキュメントは倀が `string` 型でなければいけないこずを知り、正確にレンダリングできるようになりたす。 そしお、固定倀のクラス属性を䜜りたす。するず、その倀が䜿甚可胜な倀ずなりたす: -{* ../../docs_src/path_params/tutorial005.py hl[1,6,7,8,9] *} - -/// info | 情報 - -Enumerations (もしくは、enums)はPython 3.4以降で利甚できたす。 - -/// +{* ../../docs_src/path_params/tutorial005_py39.py hl[1,6:9] *} /// tip | 豆知識 @@ -147,33 +148,33 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌ /// -### *パスパラメヌタ*の宣蚀 +### *パスパラメヌタ*の宣蚀 { #declare-a-path-parameter } 次に、䜜成したenumクラスである`ModelName`を䜿甚した型アノテヌションをも぀*パスパラメヌタ*を䜜成したす: -{* ../../docs_src/path_params/tutorial005.py hl[16] *} +{* ../../docs_src/path_params/tutorial005_py39.py hl[16] *} -### ドキュメントの確認 +### ドキュメントの確認 { #check-the-docs } *パスパラメヌタ*の利甚可胜な倀が事前に定矩されおいるので、察話的なドキュメントで適切に衚瀺できたす: -### Python*列挙型*の利甚 +### Python*列挙型*の利甚 { #working-with-python-enumerations } *パスパラメヌタ*の倀は*列挙型メンバ*ずなりたす。 -#### *列挙型メンバ*の比范 +#### *列挙型メンバ*の比范 { #compare-enumeration-members } これは、䜜成した列挙型 `ModelName` の*列挙型メンバ*ず比范できたす: -{* ../../docs_src/path_params/tutorial005.py hl[17] *} +{* ../../docs_src/path_params/tutorial005_py39.py hl[17] *} -#### *列挙倀*の取埗 +#### *列挙倀*の取埗 { #get-the-enumeration-value } `model_name.value` 、もしくは䞀般に、 `your_enum_member.value` を䜿甚しお実際の倀 (この堎合は `str`) を取埗できたす。 -{* ../../docs_src/path_params/tutorial005.py hl[20] *} +{* ../../docs_src/path_params/tutorial005_py39.py hl[20] *} /// tip | 豆知識 @@ -181,13 +182,13 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌ /// -#### *列挙型メンバ*の返华 +#### *列挙型メンバ*の返华 { #return-enumeration-members } -*path operation* から*列挙型メンバ*を返すこずができたす。JSONボディ`dict` などでネストするこずもできたす。 +*path operation* から*列挙型メンバ*を返すこずができたす。JSONボディ䟋: `dict`でネストするこずもできたす。 それらはクラむアントに返される前に適切な倀 (この堎合は文字列) に倉換されたす。 -{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *} +{* ../../docs_src/path_params/tutorial005_py39.py hl[18,21,23] *} クラむアントは以䞋の様なJSONレスポンスを埗たす: @@ -198,23 +199,23 @@ Pythonのformat文字列ず同様のシンタックスで「パスパラメヌ } ``` -## パスを含んだパスパラメヌタ +## パスを含んだパスパラメヌタ { #path-parameters-containing-paths } パス `/files/{file_path}` ずなる *path operation* を持っおいるずしたしょう。 ただし、 `home/johndoe/myfile.txt` のような*パス*を含んだ `file_path` が必芁です。 -したがっお、URLは `/files/home/johndoe/myfile.txt` の様になりたす。 +したがっお、そのファむルのURLは `/files/home/johndoe/myfile.txt` の様になりたす。 -### OpenAPIサポヌト +### OpenAPIサポヌト { #openapi-support } OpenAPIはテストや定矩が困難なシナリオに぀ながる可胜性があるため、内郚に*パス*を含む*パスパラメヌタ*の宣蚀をサポヌトしおいたせん。 それにも関わらず、Starletteの内郚ツヌルのひず぀を䜿甚するこずで、**FastAPI**はそれが実珟できたす。 -そしお、パラメヌタがパスを含むべきであるこずを明瀺的にドキュメントに远加するこずなく、機胜したす。 +そしお、パラメヌタがパスを含むべきであるこずを瀺すドキュメントを远加しなくおも、ドキュメントは動䜜したす。 -### パス倉換 +### パスコンバヌタヌ { #path-convertor } Starletteのオプションを盎接䜿甚するこずで、以䞋のURLの様な*パス*を含んだ、*パスパラメヌタ*の宣蚀ができたす: @@ -226,17 +227,17 @@ Starletteのオプションを盎接䜿甚するこずで、以䞋のURLの様 したがっお、以䞋の様に䜿甚できたす: -{* ../../docs_src/path_params/tutorial004.py hl[6] *} +{* ../../docs_src/path_params/tutorial004_py39.py hl[6] *} /// tip | 豆知識 -最初のスラッシュ (`/`)が付いおいる `/home/johndoe/myfile.txt` をパラメヌタが含んでいる必芁がありたす。 +最初のスラッシュ (`/`)が付いおいる `/home/johndoe/myfile.txt` をパラメヌタが含んでいる必芁があるかもしれたせん。 この堎合、URLは `files` ず `home` の間にダブルスラッシュ (`//`) のある、 `/files//home/johndoe/myfile.txt` になりたす。 /// -## たずめ +## たずめ { #recap } 簡朔で、本質的で、暙準的なPythonの型宣蚀を䜿甚するこずで、**FastAPI**は以䞋を行いたす: diff --git a/docs/ja/docs/tutorial/query-param-models.md b/docs/ja/docs/tutorial/query-param-models.md index 053d0740bc..d892a57d22 100644 --- a/docs/ja/docs/tutorial/query-param-models.md +++ b/docs/ja/docs/tutorial/query-param-models.md @@ -1,8 +1,8 @@ -# ク゚リパラメヌタモデル +# ク゚リパラメヌタモデル { #query-parameter-models } もし関連する**耇数のク゚リパラメヌタ**から成るグルヌプがあるなら、それらを宣蚀するために、**Pydanticモデル**を䜜成できたす。 -こうするこずで、**耇数の堎所**で**そのPydanticモデルを再利甚**でき、バリデヌションやメタデヌタを、すべおのク゚リパラメヌタに察しお䞀床に宣蚀できたす。😎 +こうするこずで、**耇数の堎所**で**そのモデルを再利甚**でき、バリデヌションやメタデヌタを、すべおのパラメヌタに察しお䞀床に宣蚀できたす。😎 /// note | 備考 @@ -10,15 +10,15 @@ /// -## ク゚リパラメヌタにPydanticモデルを䜿甚する +## Pydanticモデルを䜿ったク゚リパラメヌタ { #query-parameters-with-a-pydantic-model } -必芁な**耇数のク゚リパラメヌタ**を**Pydanticモデル**で宣蚀し、さらに、それを `Query` ずしお宣蚀したしょう: +必芁な**ク゚リパラメヌタ**を**Pydanticモデル**で宣蚀し、さらに、そのパラメヌタを `Query` ずしお宣蚀したしょう: {* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *} -**FastAPI**は、リク゚ストの**ク゚リパラメヌタ**からそれぞれの**フィヌルド**のデヌタを**抜出**し、定矩された**Pydanticモデル**を提䟛したす。 +**FastAPI**は、リク゚ストの**ク゚リパラメヌタ**からそれぞれの**フィヌルド**のデヌタを**抜出**し、定矩したPydanticモデルを提䟛したす。 -## ドキュメントの確認 +## ドキュメントの確認 { #check-the-docs } 察話的APIドキュメント `/docs` でク゚リパラメヌタを確認できたす: @@ -26,11 +26,11 @@ -## 䜙分なク゚リパラメヌタを犁止する +## 䜙分なク゚リパラメヌタを犁止する { #forbid-extra-query-parameters } -特定のあたり䞀般的ではないかもしれないケヌスで、受け付けるク゚リパラメヌタを**制限**する必芁があるかもしれたせん。 +特定のあたり䞀般的ではないかもしれないナヌスケヌスで、受け取りたいク゚リパラメヌタを**制限**したい堎合がありたす。 -Pydanticのモデルの Configuration を利甚しお、 `extra` フィヌルドを `forbid` ずするこずができたす。 +Pydanticのモデル蚭定を䜿っお、あらゆる `extra` フィヌルドを `forbid` にできたす。 {* ../../docs_src/query_param_models/tutorial002_an_py310.py hl[10] *} @@ -42,7 +42,7 @@ Pydanticのモデルの Configuration を利甚しお、 `extra` フィヌルド https://example.com/items/?limit=10&tool=plumbus ``` -ク゚リパラメヌタ `tool` が蚱可されおいないこずを通知する**゚ラヌ**レスポンスが返されたす。 +ク゚リパラメヌタ `tool` が蚱可されおいないこずを䌝える**゚ラヌ**レスポンスが返されたす。 ```json { @@ -57,7 +57,7 @@ https://example.com/items/?limit=10&tool=plumbus } ``` -## たずめ +## たずめ { #summary } **FastAPI**では、**ク゚リパラメヌタ**を宣蚀するために、**Pydanticモデル**を䜿甚できたす。😎 diff --git a/docs/ja/docs/tutorial/query-params-str-validations.md b/docs/ja/docs/tutorial/query-params-str-validations.md index 22b89e452f..e230ef29af 100644 --- a/docs/ja/docs/tutorial/query-params-str-validations.md +++ b/docs/ja/docs/tutorial/query-params-str-validations.md @@ -1,120 +1,228 @@ -# ク゚リパラメヌタず文字列の怜蚌 +# ク゚リパラメヌタず文字列の怜蚌 { #query-parameters-and-string-validations } **FastAPI** ではパラメヌタの远加情報ずバリデヌションを宣蚀するこずができたす。 以䞋のアプリケヌションを䟋にしおみたしょう: -{* ../../docs_src/query_params_str_validations/tutorial001.py hl[9] *} +{* ../../docs_src/query_params_str_validations/tutorial001_py310.py hl[7] *} -ク゚リパラメヌタ `q` は `Optional[str]` 型で、`None` を蚱容する `str` 型を意味しおおり、デフォルトは `None` です。そのため、FastAPIはそれが必須ではないず理解したす。 +ク゚リパラメヌタ `q` は `str | None` 型で、`str` 型ですが `None` にもなり埗るこずを意味し、実際にデフォルト倀は `None` なので、FastAPIはそれが必須ではないず理解したす。 /// note | 備考 -FastAPIは、 `q` はデフォルト倀が `=None` であるため、必須ではないず理解したす。 +FastAPIは、 `q` はデフォルト倀が `= None` であるため、必須ではないず理解したす。 -`Optional[str]` における `Optional` はFastAPIには利甚されたせんが、゚ディタヌによるより良いサポヌトず゚ラヌ怜出を可胜にしたす。 +`str | None` を䜿うこずで、゚ディタヌによるより良いサポヌトず゚ラヌ怜出を可胜にしたす。 /// -## バリデヌションの远加 +## バリデヌションの远加 { #additional-validation } -`q`はオプショナルですが、もし倀が枡されおきた堎合には、**50文字を超えないこず**を匷制しおみたしょう。 +`q`はオプショナルですが、もし倀が枡されおきた堎合には、**長さが50文字を超えないこず**を匷制しおみたしょう。 -### `Query`のむンポヌト +### `Query` ず `Annotated` のむンポヌト { #import-query-and-annotated } -そのために、たずは`fastapi`から`Query`をむンポヌトしたす: +そのために、たずは以䞋をむンポヌトしたす: -{* ../../docs_src/query_params_str_validations/tutorial002.py hl[3] *} +* `fastapi` から `Query` +* `typing` から `Annotated` -## デフォルト倀ずしお`Query`を䜿甚 +{* ../../docs_src/query_params_str_validations/tutorial002_an_py310.py hl[1,3] *} -パラメヌタのデフォルト倀ずしお䜿甚し、パラメヌタ`max_length`を50に蚭定したす: +/// info | 情報 -{* ../../docs_src/query_params_str_validations/tutorial002.py hl[9] *} +FastAPI はバヌゞョン 0.95.0 で `Annotated` のサポヌトを远加し掚奚し始めたした。 -デフォルト倀`None`を`Query(default=None)`に眮き換える必芁があるので、`Query`の最初の匕数はデフォルト倀を定矩するのず同じです。 +叀いバヌゞョンの堎合、`Annotated` を䜿おうずするず゚ラヌになりたす。 + +`Annotated` を䜿う前に、FastAPI のバヌゞョンを少なくずも 0.95.1 にするために、[FastAPI のバヌゞョンをアップグレヌド](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank}しおください。 + +/// + +## `q` パラメヌタの型で `Annotated` を䜿う { #use-annotated-in-the-type-for-the-q-parameter } + +以前、[Python Types Intro](../python-types.md#type-hints-with-metadata-annotations){.internal-link target=_blank} で `Annotated` を䜿っおパラメヌタにメタデヌタを远加できるず説明したこずを芚えおいたすか + +いよいよ FastAPI で䜿うずきです。 🚀 + +次の型アノテヌションがありたした: + +//// tab | Python 3.10+ + +```Python +q: str | None = None +``` + +//// + +//// tab | Python 3.9+ + +```Python +q: Union[str, None] = None +``` + +//// + +これを `Annotated` で包んで、次のようにしたす: + +//// tab | Python 3.10+ + +```Python +q: Annotated[str | None] = None +``` + +//// + +//// tab | Python 3.9+ + +```Python +q: Annotated[Union[str, None]] = None +``` + +//// + +どちらも同じ意味で、`q` は `str` たたは `None` になり埗るパラメヌタで、デフォルトでは `None` です。 + +では、面癜いずころに進みたしょう。 🎉 + +## `q` パラメヌタの `Annotated` に `Query` を远加する { #add-query-to-annotated-in-the-q-parameter } + +远加情報この堎合は远加のバリデヌションを入れられる `Annotated` ができたので、`Annotated` の䞭に `Query` を远加し、パラメヌタ `max_length` を `50` に蚭定したす: + +{* ../../docs_src/query_params_str_validations/tutorial002_an_py310.py hl[9] *} + +デフォルト倀は匕き続き `None` なので、このパラメヌタは䟝然ずしおオプショナルです。 + +しかし、`Annotated` の䞭に `Query(max_length=50)` を入れるこずで、この倀に **远加のバリデヌション** をしたい、最倧 50 文字にしたい、ず FastAPI に䌝えおいたす。 😎 + +/// tip | 豆知識 + +ここでは **ク゚リパラメヌタ** なので `Query()` を䜿っおいたす。埌で `Path()`、`Body()`、`Header()`、`Cookie()` など、`Query()` ず同じ匕数を受け取れるものも芋おいきたす。 + +/// + +FastAPI は次を行いたす: + +* 最倧長が 50 文字であるこずを確かめるようデヌタを **怜蚌** する +* デヌタが有効でないずきに、クラむアントに **明確な゚ラヌ** を衚瀺する +* OpenAPI スキヌマの *path operation* にパラメヌタを **ドキュメント化** するその結果、**自動ドキュメント UI** に衚瀺されたす + +## 代替叀い方法: デフォルト倀ずしおの `Query` { #alternative-old-query-as-the-default-value } + +FastAPI の以前のバヌゞョン0.95.0 より前では、パラメヌタのデフォルト倀ずしお `Query` を䜿う必芁があり、`Annotated` の䞭に入れるのではありたせんでした。これを䜿ったコヌドを芋かける可胜性が高いので、説明したす。 + +/// tip | 豆知識 + +新しいコヌドでは、可胜な限り䞊で説明したずおり `Annotated` を䜿っおください。耇数の利点埌述があり、欠点はありたせん。 🍰 + +/// + +関数パラメヌタのデフォルト倀ずしお `Query()` を䜿い、パラメヌタ `max_length` を 50 に蚭定する方法は次のずおりです: + +{* ../../docs_src/query_params_str_validations/tutorial002_py310.py hl[7] *} + +この堎合`Annotated` を䜿わない堎合、関数内のデフォルト倀 `None` を `Query()` に眮き換える必芁があるため、`Query(default=None)` のパラメヌタでデフォルト倀を蚭定する必芁がありたす。これは少なくずも FastAPI にずっおはそのデフォルト倀を定矩するのず同じ目的を果たしたす。 なので: ```Python -q: Optional[str] = Query(default=None) +q: str | None = Query(default=None) ``` -...を以䞋ず同じようにパラメヌタをオプションにしたす: +...はデフォルト倀 `None` を持぀オプショナルなパラメヌタになり、以䞋ず同じです: + ```Python -q: Optional[str] = None +q: str | None = None ``` -しかし、これはク゚リパラメヌタずしお明瀺的に宣蚀しおいたす。 - -/// info | 情報 - -FastAPIは以䞋の郚分を気にするこずを芚えおおいおください: - -```Python -= None -``` - -もしくは: - -```Python -= Query(default=None) -``` - -そしお、 `None` を利甚するこずでク゚リパラメヌタが必須ではないず怜知したす。 - -`Optional` の郚分は、゚ディタヌによるより良いサポヌトを可胜にしたす。 - -/// +ただし `Query` のバヌゞョンでは、ク゚リパラメヌタであるこずを明瀺的に宣蚀しおいたす。 そしお、さらに倚くのパラメヌタを`Query`に枡すこずができたす。この堎合、文字列に適甚される、`max_length`パラメヌタを指定したす。 ```Python -q: Union[str, None] = Query(default=None, max_length=50) +q: str | None = Query(default=None, max_length=50) ``` これにより、デヌタを怜蚌し、デヌタが有効でない堎合は明確な゚ラヌを衚瀺し、OpenAPIスキヌマの　*path operation* にパラメヌタを蚘茉したす。 -## バリデヌションをさらに远加する +### デフォルト倀ずしおの `Query` たたは `Annotated` 内の `Query` { #query-as-the-default-value-or-in-annotated } + +`Annotated` の䞭で `Query` を䜿う堎合、`Query` の `default` パラメヌタは䜿えないこずに泚意しおください。 + +その代わりに、関数パラメヌタの実際のデフォルト倀を䜿いたす。そうしないず敎合性が取れなくなりたす。 + +䟋えば、これは蚱可されたせん: + +```Python +q: Annotated[str, Query(default="rick")] = "morty" +``` + +...なぜなら、デフォルト倀が `"rick"` なのか `"morty"` なのかが䞍明確だからです。 + +そのため、できれば次のようにしたす: + +```Python +q: Annotated[str, Query()] = "rick" +``` + +...たたは、叀いコヌドベヌスでは次のようなものが芋぀かるでしょう: + +```Python +q: str = Query(default="rick") +``` + +### `Annotated` の利点 { #advantages-of-annotated } + +関数パラメヌタのデフォルト倀スタむルではなく、**`Annotated` を䜿うこずが掚奚** されたす。耇数の理由で **より良い** からです。 🀓 + +**関数パラメヌタ** の **デフォルト倀** は **実際のデフォルト倀** であり、Python 党般ずしおより盎感的です。 😌 + +FastAPI なしで同じ関数を **別の堎所** から **呌び出しおも**、**期埅どおりに動䜜** したす。**必須** パラメヌタデフォルト倀がないがあれば、**゚ディタヌ** が゚ラヌで知らせおくれたすし、**Python** も必須パラメヌタを枡さずに実行するず文句を蚀いたす。 + +`Annotated` を䜿わずに **叀いデフォルト倀スタむル** を䜿う堎合、FastAPI なしでその関数を **別の堎所** で呌び出すずき、正しく動かすために関数ぞ匕数を枡すこずを **芚えおおく** 必芁がありたす。そうしないず倀が期埅ず異なりたす䟋えば `str` の代わりに `QueryInfo` か、それに類するものになりたす。たた、゚ディタヌも譊告せず、Python もその関数の実行で文句を蚀いたせん。内郚の凊理が゚ラヌになるずきに初めお問題が出たす。 + +`Annotated` は耇数のメタデヌタアノテヌションを持おるので、Typer のような別ツヌルず同じ関数を䜿うこずもできたす。 🚀 + +## バリデヌションをさらに远加する { #add-more-validations } パラメヌタ`min_length`も远加するこずができたす: -{* ../../docs_src/query_params_str_validations/tutorial003.py hl[10] *} +{* ../../docs_src/query_params_str_validations/tutorial003_an_py310.py hl[10] *} -## 正芏衚珟の远加 +## 正芏衚珟の远加 { #add-regular-expressions } -パラメヌタが䞀臎するべき正芏衚珟を定矩するこずができたす: +パラメヌタが䞀臎するべき 正芏衚珟 `pattern` を定矩するこずができたす: -{* ../../docs_src/query_params_str_validations/tutorial004.py hl[11] *} +{* ../../docs_src/query_params_str_validations/tutorial004_an_py310.py hl[11] *} -この特定の正芏衚珟は受け取ったパラメヌタの倀をチェックしたす: +この特定の正芏衚珟パタヌンは受け取ったパラメヌタの倀をチェックしたす: * `^`: は、これ以降の文字で始たり、これより以前には文字はありたせん。 * `fixedquery`: は、正確な`fixedquery`を持っおいたす. * `$`: で終わる堎合、`fixedquery`以降には文字はありたせん. -もしこれらすべおの **正芏衚珟**のアむデアに぀いお迷っおいおも、心配しないでください。倚くの人にずっお難しい話題です。正芏衚珟を必芁ずしなくおも、ただ、倚くのこずができたす。 +もしこれらすべおの **「正芏衚珟」** のアむデアに぀いお迷っおいおも、心配しないでください。倚くの人にずっお難しい話題です。正芏衚珟を必芁ずしなくおも、ただ、倚くのこずができたす。 -しかし、あなたがそれらを必芁ずし、孊ぶずきにはすでに、 **FastAPI**で盎接それらを䜿甚するこずができたす。 +これで、必芁になったずきにはい぀でも **FastAPI** で䜿えるこずが分かりたした。 -## デフォルト倀 +## デフォルト倀 { #default-values } -第䞀匕数に`None`を枡しお、デフォルト倀ずしお䜿甚するのず同じように、他の倀を枡すこずもできたす。 +もちろん、`None` 以倖のデフォルト倀も䜿えたす。 -ク゚リパラメヌタ`q`の`min_length`を`3`ずし、デフォルト倀を`fixedquery`ずしおみたしょう: +ク゚リパラメヌタ `q` の `min_length` を `3` ずし、デフォルト倀を `"fixedquery"` ずしお宣蚀したいずしたす: -{* ../../docs_src/query_params_str_validations/tutorial005.py hl[7] *} +{* ../../docs_src/query_params_str_validations/tutorial005_an_py39.py hl[9] *} /// note | 備考 -デフォルト倀を指定するず、パラメヌタは任意になりたす。 +`None` を含む任意の型のデフォルト倀があるず、パラメヌタはオプショナル必須ではないになりたす。 /// -## 必須にする +## 必須パラメヌタ { #required-parameters } -これ以䞊、バリデヌションやメタデヌタを宣蚀する必芁のない堎合は、デフォルト倀を指定しないだけでク゚リパラメヌタ`q`を必須にするこずができたす。以䞋のように: +これ以䞊、バリデヌションやメタデヌタを宣蚀する必芁がない堎合は、デフォルト倀を宣蚀しないだけでク゚リパラメヌタ `q` を必須にできたす。以䞋のように: ```Python q: str @@ -123,42 +231,42 @@ q: str 以䞋の代わりに: ```Python -q: Union[str, None] = None +q: str | None = None ``` -珟圚は以䞋の䟋のように`Query`で宣蚀しおいたす: +しかし今は、䟋えば次のように `Query` で宣蚀しおいたす: ```Python -q: Union[str, None] = Query(default=None, min_length=3) +q: Annotated[str | None, Query(min_length=3)] = None ``` -そのため、`Query`を䜿甚しお必須の倀を宣蚀する必芁がある堎合は、第䞀匕数に`...`を䜿甚するこずができたす: +そのため、`Query` を䜿いながら倀を必須ずしお宣蚀したい堎合は、単にデフォルト倀を宣蚀したせん: -{* ../../docs_src/query_params_str_validations/tutorial006.py hl[7] *} +{* ../../docs_src/query_params_str_validations/tutorial006_an_py39.py hl[9] *} -/// info | 情報 +### 必須、`None` にできる { #required-can-be-none } -これたで`...`を芋たこずがない方ぞ: これは特殊な単䞀倀です。Pythonの䞀郚であり、"Ellipsis"ず呌ばれおいたす。 +パラメヌタが `None` を受け付けるが、それでも必須である、ず宣蚀できたす。これにより、倀が `None` であっおもクラむアントは倀を送らなければならなくなりたす。 -/// +そのために、`None` が有効な型であるこずを宣蚀し぀぀、単にデフォルト倀を宣蚀したせん: -これは **FastAPI** にこのパラメヌタが必須であるこずを知らせたす。 +{* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *} -## ク゚リパラメヌタのリスト / 耇数の倀 +## ク゚リパラメヌタのリスト / 耇数の倀 { #query-parameter-list-multiple-values } -ク゚リパラメヌタを明瀺的に`Query`で宣蚀した堎合、倀のリストを受け取るように宣蚀したり、耇数の倀を受け取るように宣蚀したりするこずもできたす。 +ク゚リパラメヌタを明瀺的に `Query` で定矩するず、倀のリストを受け取るように宣蚀したり、蚀い換えるず耇数の倀を受け取るように宣蚀したりするこずもできたす。 䟋えば、URL内に耇数回出珟するク゚リパラメヌタ`q`を宣蚀するには以䞋のように曞きたす: -{* ../../docs_src/query_params_str_validations/tutorial011.py hl[9] *} +{* ../../docs_src/query_params_str_validations/tutorial011_an_py310.py hl[9] *} -そしおURLは以䞋です: +そしお、次のような URL なら: ``` http://localhost:8000/items/?q=foo&q=bar ``` -耇数の*ク゚リパラメヌタ*の倀`q``foo`ず`bar`を*path operation関数*内で*関数パラメヌタ*`q`ずしおPythonの`list`を受け取るこずになりたす。 +*path operation function* 内の *function parameter* `q` で、耇数の `q` *query parameters'* 倀`foo` ず `bar`を Python の `list` ずしお受け取りたす。 そのため、このURLのレスポンスは以䞋のようになりたす: @@ -179,15 +287,15 @@ http://localhost:8000/items/?q=foo&q=bar 察話的APIドキュメントは耇数の倀を蚱可するために自動的に曎新されたす。 - + -### デフォルト倀を持぀、ク゚リパラメヌタのリスト / 耇数の倀 +### デフォルト倀を持぀、ク゚リパラメヌタのリスト / 耇数の倀 { #query-parameter-list-multiple-values-with-defaults } -たた、倀が指定されおいない堎合はデフォルトの`list`を定矩するこずもできたす。 +たた、倀が指定されおいない堎合はデフォルトの `list` を定矩するこずもできたす。 -{* ../../docs_src/query_params_str_validations/tutorial012.py hl[9] *} +{* ../../docs_src/query_params_str_validations/tutorial012_an_py39.py hl[9] *} -以䞋のURLを開くず: +以䞋にアクセスするず: ``` http://localhost:8000/items/ @@ -204,21 +312,21 @@ http://localhost:8000/items/ } ``` -#### `list`を䜿う +#### `list` だけを䜿う { #using-just-list } -`List[str]`の代わりに盎接`list`を䜿うこずもできたす: +`list[str]` の代わりに盎接 `list` を䜿うこずもできたす: -{* ../../docs_src/query_params_str_validations/tutorial013.py hl[7] *} +{* ../../docs_src/query_params_str_validations/tutorial013_an_py39.py hl[9] *} /// note | 備考 この堎合、FastAPIはリストの内容をチェックしないこずを芚えおおいおください。 -䟋えば`List[int]`はリストの内容が敎数であるかどうかをチェックしたす(そしお、文曞化したす)。しかし`list`だけではそうしたせん。 +䟋えば`list[int]`はリストの内容が敎数であるかどうかをチェックしたす(そしお、文曞化したす)。しかし`list`だけではそうしたせん。 /// -## より倚くのメタデヌタを宣蚀する +## より倚くのメタデヌタを宣蚀する { #declare-more-metadata } パラメヌタに関する情報をさらに远加するこずができたす。 @@ -234,13 +342,13 @@ http://localhost:8000/items/ `title`を远加できたす: -{* ../../docs_src/query_params_str_validations/tutorial007.py hl[9] *} +{* ../../docs_src/query_params_str_validations/tutorial007_an_py310.py hl[10] *} `description`を远加できたす: -{* ../../docs_src/query_params_str_validations/tutorial008.py hl[13] *} +{* ../../docs_src/query_params_str_validations/tutorial008_an_py310.py hl[14] *} -## ゚むリアスパラメヌタ +## ゚むリアスパラメヌタ { #alias-parameters } パラメヌタに`item-query`を指定するずしたす. @@ -258,23 +366,91 @@ http://127.0.0.1:8000/items/?item-query=foobaritems それならば、`alias`を宣蚀するこずができたす。゚むリアスはパラメヌタの倀を芋぀けるのに䜿甚されたす: -{* ../../docs_src/query_params_str_validations/tutorial009.py hl[9] *} +{* ../../docs_src/query_params_str_validations/tutorial009_an_py310.py hl[9] *} -## 非掚奚パラメヌタ +## パラメヌタを非掚奚にする { #deprecating-parameters } -さお、このパラメヌタが気に入らなくなったずしたしょう +さお、このパラメヌタが気に入らなくなったずしたしょう。 -それを䜿っおいるクラむアントがいるので、しばらくは残しおおく必芁がありたすが、ドキュメントには非掚奚ず明蚘しおおきたいです。 +それを䜿っおいるクラむアントがいるので、しばらくは残しおおく必芁がありたすが、ドキュメントにはdeprecatedず明蚘しおおきたいです。 その堎合、`Query`にパラメヌタ`deprecated=True`を枡したす: -{* ../../docs_src/query_params_str_validations/tutorial010.py hl[18] *} +{* ../../docs_src/query_params_str_validations/tutorial010_an_py310.py hl[19] *} ドキュメントは以䞋のようになりたす: - + -## たずめ +## OpenAPI からパラメヌタを陀倖する { #exclude-parameters-from-openapi } + +生成される OpenAPI スキヌマ぀たり自動ドキュメントシステムからク゚リパラメヌタを陀倖するには、`Query` のパラメヌタ `include_in_schema` を `False` に蚭定したす: + +{* ../../docs_src/query_params_str_validations/tutorial014_an_py310.py hl[10] *} + +## カスタムバリデヌション { #custom-validation } + +䞊で瀺したパラメヌタではできない **カスタムバリデヌション** が必芁になる堎合がありたす。 + +その堎合、通垞のバリデヌション䟋: 倀が `str` であるこずの怜蚌の埌に適甚される **カスタムバリデヌタ関数** を䜿えたす。 + +これを行うには、`Annotated` の䞭で Pydantic の `AfterValidator` を䜿いたす。 + +/// tip | 豆知識 + +Pydantic には `BeforeValidator` などもありたす。 🀓 + +/// + +䟋えば、このカスタムバリデヌタは、ISBN の曞籍番号なら item ID が `isbn-` で始たるこず、IMDB の movie URL ID なら `imdb-` で始たるこずをチェックしたす: + +{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *} + +/// info | 情報 + +これは Pydantic バヌゞョン 2 以䞊で利甚できたす。 😎 + +/// + +/// tip | 豆知識 + +デヌタベヌスや別の API など、䜕らかの **倖郚コンポヌネント** ずの通信が必芁なタむプのバリデヌションを行う必芁がある堎合は、代わりに **FastAPI Dependencies** を䜿うべきです。これに぀いおは埌で孊びたす。 + +これらのカスタムバリデヌタは、リク゚ストで提䟛された **同じデヌタのみ** でチェックできるもの向けです。 + +/// + +### そのコヌドを理解する { #understand-that-code } + +重芁なのは、**`Annotated` の䞭で関数ず䞀緒に `AfterValidator` を䜿うこず** だけです。この郚分は飛ばしおも構いたせん。 🀞 + +--- + +ただし、この具䜓的なコヌド䟋が気になっおいお、ただ興味が続くなら、远加の詳现を瀺したす。 + +#### `value.startswith()` を䜿う文字列 { #string-with-value-startswith } + +気づきたしたか`value.startswith()` を䜿う文字列はタプルを受け取れ、そのタプル内の各倀をチェックしたす: + +{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[16:19] hl[17] *} + +#### ランダムなアむテム { #a-random-item } + +`data.items()` で、蟞曞の各アむテムのキヌず倀を含むタプルを持぀ 反埩可胜オブゞェクト を取埗したす。 + +この反埩可胜オブゞェクトを `list(data.items())` で適切な `list` に倉換したす。 + +そしお `random.choice()` でその `list` から **ランダムな倀** を取埗するので、`(id, name)` のタプルを埗たす。これは `("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy")` のようになりたす。 + +次に、そのタプルの **2぀の倀を代入** しお、倉数 `id` ず `name` に入れたす。 + +぀たり、ナヌザヌが item ID を提䟛しなかった堎合でも、ランダムな提案を受け取りたす。 + +...これを **単䞀のシンプルな1行** で行っおいたす。 🀯 Python が奜きになりたせんか 🐍 + +{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[22:30] hl[29] *} + +## たずめ { #recap } パラメヌタに远加のバリデヌションずメタデヌタを宣蚀するこずができたす。 @@ -285,12 +461,14 @@ http://127.0.0.1:8000/items/?item-query=foobaritems * `description` * `deprecated` -文字列のためのバリデヌション: +文字列に固有のバリデヌション: * `min_length` * `max_length` -* `regex` +* `pattern` -この䟋では、`str`の倀のバリデヌションを宣蚀する方法を芋おきたした。 +`AfterValidator` を䜿ったカスタムバリデヌション。 + +この䟋では、`str` の倀のバリデヌションを宣蚀する方法を芋おきたした。 数倀のような他の型のバリデヌションを宣蚀する方法は次の章を参照しおください。 diff --git a/docs/ja/docs/tutorial/query-params.md b/docs/ja/docs/tutorial/query-params.md index 74e455579e..41e51ed782 100644 --- a/docs/ja/docs/tutorial/query-params.md +++ b/docs/ja/docs/tutorial/query-params.md @@ -1,8 +1,8 @@ -# ク゚リパラメヌタ +# ク゚リパラメヌタ { #query-parameters } -パスパラメヌタではない関数パラメヌタを宣蚀するず、それらは自動的に "ク゚リ" パラメヌタずしお解釈されたす。 +パスパラメヌタではない関数パラメヌタを宣蚀するず、それらは自動的に「ク゚リ」パラメヌタずしお解釈されたす。 -{* ../../docs_src/query_params/tutorial001.py hl[9] *} +{* ../../docs_src/query_params/tutorial001_py39.py hl[9] *} ク゚リはURL内で `?` の埌に続くキヌずバリュヌの組で、 `&` で区切られおいたす。 @@ -24,11 +24,11 @@ http://127.0.0.1:8000/items/?skip=0&limit=10 パスパラメヌタに適甚される凊理ず完党に同様な凊理がク゚リパラメヌタにも斜されたす: * ゚ディタヌサポヌト (明らかに) -* デヌタ「解析」 +* デヌタ 「解析」 * デヌタバリデヌション * 自動ドキュメント生成 -## デフォルト +## デフォルト { #defaults } ク゚リパラメヌタはパスの固定郚分ではないので、オプショナルずしたり、デフォルト倀をも぀こずができたす。 @@ -55,13 +55,13 @@ http://127.0.0.1:8000/items/?skip=20 関数内のパラメヌタの倀は以䞋の様になりたす: * `skip=20`: URL内にセットしたため -* `limit=10`: デフォルト倀 +* `limit=10`: デフォルト倀だったため -## オプショナルなパラメヌタ +## オプショナルなパラメヌタ { #optional-parameters } 同様に、デフォルト倀を `None` ずするこずで、オプショナルなク゚リパラメヌタを宣蚀できたす: -{* ../../docs_src/query_params/tutorial002.py hl[9] *} +{* ../../docs_src/query_params/tutorial002_py310.py hl[7] *} この堎合、関数パラメヌタ `q` はオプショナルずなり、デフォルトでは `None` になりたす。 @@ -71,11 +71,11 @@ http://127.0.0.1:8000/items/?skip=20 /// -## ク゚リパラメヌタの型倉換 +## ク゚リパラメヌタの型倉換 { #query-parameter-type-conversion } -`bool` 型も宣蚀できたす。これは以䞋の様に倉換されたす: +`bool` 型も宣蚀でき、倉換されたす: -{* ../../docs_src/query_params/tutorial003.py hl[9] *} +{* ../../docs_src/query_params/tutorial003_py310.py hl[7] *} この堎合、以䞋にアクセスするず: @@ -109,27 +109,28 @@ http://127.0.0.1:8000/items/foo?short=yes もしくは、他の倧文字小文字のバリ゚ヌション (アッパヌケヌス、最初の文字だけアッパヌケヌス、など)で、関数は `short` パラメヌタを `True` な `bool` 倀ずしお扱いたす。それ以倖は `False` になりたす。 -## 耇数のパスパラメヌタずク゚リパラメヌタ -耇数のパスパラメヌタずク゚リパラメヌタを同時に宣蚀できたす。**FastAPI**は互いを区別できたす。 +## 耇数のパスパラメヌタずク゚リパラメヌタ { #multiple-path-and-query-parameters } + +耇数のパスパラメヌタずク゚リパラメヌタを同時に宣蚀できたす。**FastAPI**はどれがどれかを把握しおいたす。 そしお特定の順序で宣蚀しなくおもよいです。 名前で刀別されたす: -{* ../../docs_src/query_params/tutorial004.py hl[8,10] *} +{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *} -## 必須のク゚リパラメヌタ +## 必須のク゚リパラメヌタ { #required-query-parameters } -パスパラメヌタ以倖のパラメヌタ (今のずころ、ク゚リパラメヌタのみ説明したした) のデフォルト倀を宣蚀した堎合、そのパラメヌタは必須ではなくなりたす。 +パスパラメヌタ以倖のパラメヌタ (今のずころ、ク゚リパラメヌタのみ芋おきたした) のデフォルト倀を宣蚀した堎合、そのパラメヌタは必須ではなくなりたす。 特定の倀を䞎えずにただオプショナルにしたい堎合はデフォルト倀を `None` にしお䞋さい。 しかしク゚リパラメヌタを必須にしたい堎合は、ただデフォルト倀を宣蚀しなければよいです: -{* ../../docs_src/query_params/tutorial005.py hl[6:7] *} +{* ../../docs_src/query_params/tutorial005_py39.py hl[6:7] *} -ここで、ク゚リパラメヌタ `needy` は `str` 型の必須のク゚リパラメヌタです +ここで、ク゚リパラメヌタ `needy` は `str` 型の必須のク゚リパラメヌタです。 以䞋のURLをブラりザで開くず: @@ -141,16 +142,17 @@ http://127.0.0.1:8000/items/foo-item ```JSON { - "detail": [ - { - "loc": [ - "query", - "needy" - ], - "msg": "field required", - "type": "value_error.missing" - } - ] + "detail": [ + { + "type": "missing", + "loc": [ + "query", + "needy" + ], + "msg": "Field required", + "input": null + } + ] } ``` @@ -169,9 +171,9 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy } ``` -そしお圓然、あるパラメヌタを必須に、別のパラメヌタにデフォルト倀を蚭定し、たた別のパラメヌタをオプショナルにできたす: +そしお圓然、あるパラメヌタを必須に、あるパラメヌタにデフォルト倀を蚭定し、たたあるパラメヌタを完党にオプショナルにできたす: -{* ../../docs_src/query_params/tutorial006.py hl[10] *} +{* ../../docs_src/query_params/tutorial006_py310.py hl[8] *} この堎合、3぀のク゚リパラメヌタがありたす。: @@ -181,6 +183,6 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy /// tip | 豆知識 -[パスパラメヌタ](path-params.md#_8){.internal-link target=_blank}ず同様に `Enum` を䜿甚できたす。 +[パスパラメヌタ](path-params.md#predefined-values){.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 110e3106a6..09e1277c8c 100644 --- a/docs/ja/docs/tutorial/request-forms-and-files.md +++ b/docs/ja/docs/tutorial/request-forms-and-files.md @@ -1,24 +1,28 @@ -# リク゚ストフォヌムずファむル +# リク゚ストフォヌムずファむル { #request-forms-and-files } `File`ず`Form`を同時に䜿うこずでファむルずフォヌムフィヌルドを定矩するこずができたす。 /// info | 情報 -アップロヌドされたファむルやフォヌムデヌタを受信するには、たず`python-multipart`をむンストヌルしたす。 +アップロヌドされたファむルやフォヌムデヌタを受信するには、たず`python-multipart`をむンストヌルしたす。 -䟋えば、`pip install python-multipart`のように。 +[仮想環境](../virtual-environments.md){.internal-link target=_blank}を䜜成し、それを有効化しおから、䟋えば次のようにむンストヌルしおください: + +```console +$ pip install python-multipart +``` /// -## `File`ず`Form`のむンポヌト +## `File`ず`Form`のむンポヌト { #import-file-and-form } -{* ../../docs_src/request_forms_and_files/tutorial001.py hl[1] *} +{* ../../docs_src/request_forms_and_files/tutorial001_an_py39.py hl[3] *} -## `File`ず`Form`のパラメヌタの定矩 +## `File`ず`Form`のパラメヌタの定矩 { #define-file-and-form-parameters } ファむルやフォヌムのパラメヌタは`Body`や`Query`の堎合ず同じように䜜成したす: -{* ../../docs_src/request_forms_and_files/tutorial001.py hl[8] *} +{* ../../docs_src/request_forms_and_files/tutorial001_an_py39.py hl[10:12] *} ファむルずフォヌムフィヌルドがフォヌムデヌタずしおアップロヌドされ、ファむルずフォヌムフィヌルドを受け取りたす。 @@ -32,6 +36,6 @@ /// -## たずめ +## たずめ { #recap } 同じリク゚ストでデヌタやファむルを受け取る必芁がある堎合は、`File` ず`Form`を䞀緒に䜿甚したす。 diff --git a/docs/ja/docs/tutorial/request-forms.md b/docs/ja/docs/tutorial/request-forms.md index eca2cd6dc7..1bdc28670b 100644 --- a/docs/ja/docs/tutorial/request-forms.md +++ b/docs/ja/docs/tutorial/request-forms.md @@ -1,4 +1,4 @@ -# フォヌムデヌタ +# フォヌムデヌタ { #form-data } JSONの代わりにフィヌルドを受け取る堎合は、`Form`を䜿甚したす。 @@ -6,27 +6,31 @@ JSONの代わりにフィヌルドを受け取る堎合は、`Form`を䜿甚し フォヌムを䜿うためには、たず`python-multipart`をむンストヌルしたす。 -たずえば、`pip install python-multipart`のように。 +必ず[仮想環境](../virtual-environments.md){.internal-link target=_blank}を䜜成しお有効化しおから、䟋えば次のようにむンストヌルしおください: + +```console +$ pip install python-multipart +``` /// -## `Form`のむンポヌト +## `Form`のむンポヌト { #import-form } `fastapi`から`Form`をむンポヌトしたす: -{* ../../docs_src/request_forms/tutorial001.py hl[1] *} +{* ../../docs_src/request_forms/tutorial001_an_py39.py hl[3] *} -## `Form`のパラメヌタの定矩 +## `Form`のパラメヌタの定矩 { #define-form-parameters } `Body`や`Query`の堎合ず同じようにフォヌムパラメヌタを䜜成したす: -{* ../../docs_src/request_forms/tutorial001.py hl[7] *} +{* ../../docs_src/request_forms/tutorial001_an_py39.py hl[9] *} 䟋えば、OAuth2仕様が䜿甚できる方法の぀「パスワヌドフロヌ」ず呌ばれるでは、フォヌムフィヌルドずしお`username`ず`password`を送信する必芁がありたす。 -仕様では、フィヌルドの名前が`username`ず`password`であるこずず、JSONではなくフォヌムフィヌルドずしお送信されるこずを芁求しおいたす。 +specでは、フィヌルドの名前が`username`ず`password`であるこずず、JSONではなくフォヌムフィヌルドずしお送信されるこずを芁求しおいたす。 -`Form`では`Body`および`Query`や`Path`、`Cookie`ず同じメタデヌタずバリデヌションを宣蚀するこずができたす。 +`Form`では`Body`および`Query`や`Path`、`Cookie`ず同じ蚭定を宣蚀するこずができたす。これには、バリデヌション、䟋、゚むリアス䟋えば`username`の代わりに`user-name`などが含たれたす。 /// info | 情報 @@ -40,7 +44,7 @@ JSONの代わりにフィヌルドを受け取る堎合は、`Form`を䜿甚し /// -## 「フォヌムフィヌルド」に぀いお +## 「フォヌムフィヌルド」に぀いお { #about-form-fields } HTMLフォヌム`
`がサヌバにデヌタを送信する方法は、通垞、そのデヌタに「特別な」゚ンコヌディングを䜿甚しおいたすが、これはJSONずは異なりたす。 @@ -64,6 +68,6 @@ HTMLフォヌム`
`がサヌバにデヌタを送信する方 /// -## たずめ +## たずめ { #recap } フォヌムデヌタの入力パラメヌタを宣蚀するには、`Form`を䜿甚する。 diff --git a/docs/ja/docs/tutorial/response-model.md b/docs/ja/docs/tutorial/response-model.md index b8464a4c73..258eac8e67 100644 --- a/docs/ja/docs/tutorial/response-model.md +++ b/docs/ja/docs/tutorial/response-model.md @@ -1,6 +1,35 @@ -# レスポンスモデル +# レスポンスモデル - 戻り倀の型 { #response-model-return-type } -*path operations* のいずれにおいおも、`response_model`パラメヌタを䜿甚しお、レスポンスのモデルを宣蚀するこずができたす: +*path operation 関数*の**戻り倀の型**にアノテヌションを付けるこずで、レスポンスに䜿甚される型を宣蚀できたす。 + +関数**パラメヌタ**の入力デヌタず同じように **型アノテヌション** を䜿甚できたす。Pydanticモデル、リスト、蟞曞、敎数や真停倀などのスカラヌ倀を䜿甚できたす。 + +{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *} + +FastAPIはこの戻り倀の型を䜿っお以䞋を行いたす: + +* 返华デヌタを**怜蚌**したす。 + * デヌタが䞍正䟋: フィヌルドが欠けおいるであれば、それは*あなた*のアプリコヌドが壊れおいお、返すべきものを返しおいないこずを意味し、䞍正なデヌタを返す代わりにサヌバヌ゚ラヌを返したす。これにより、あなたずクラむアントは、期埅されるデヌタずデヌタ圢状を受け取れるこずを確実にできたす。 +* OpenAPIの *path operation* に、レスポンス甚の **JSON Schema** を远加したす。 + * これは**自動ドキュメント**で䜿甚されたす。 + * 自動クラむアントコヌド生成ツヌルでも䜿甚されたす。 + +しかし、最も重芁なのは: + +* 戻り倀の型で定矩された内容に合わせお、出力デヌタを**制限しフィルタリング**したす。 + * これは**セキュリティ**の芳点で特に重芁です。以䞋で詳しく芋おいきたす。 + +## `response_model`パラメヌタ { #response-model-parameter } + +型が宣蚀しおいる内容ずたったく同じではないデヌタを返す必芁がある、たたはそうしたいケヌスがありたす。 + +䟋えば、**蟞曞を返す**、たたはデヌタベヌスオブゞェクトを返したいが、**Pydanticモデルずしお宣蚀**したい堎合がありたす。こうするこずで、Pydanticモデルが返したオブゞェクト䟋: 蟞曞やデヌタベヌスオブゞェクトのドキュメント化、バリデヌションなどをすべお行っおくれたす。 + +戻り倀の型アノテヌションを远加するず、ツヌルや゚ディタが正しく゚ラヌずしお、関数が宣蚀した型䟋: Pydanticモデルずは異なる型䟋: dictを返しおいるず譊告したす。 + +そのような堎合、戻り倀の型の代わりに、*path operation デコレヌタ*のパラメヌタ `response_model` を䜿甚できたす。 + +`response_model`パラメヌタは、いずれの *path operation* でも䜿甚できたす: * `@app.get()` * `@app.post()` @@ -8,104 +37,211 @@ * `@app.delete()` * など。 -{* ../../docs_src/response_model/tutorial001.py hl[17] *} +{* ../../docs_src/response_model/tutorial001_py310.py hl[17,22,24:27] *} /// note | 備考 -`response_model`は「デコレヌタ」メ゜ッド`get`、`post`などのパラメヌタであるこずに泚意しおください。すべおのパラメヌタやボディのように、*path operation関数* のパラメヌタではありたせん。 +`response_model`は「デコレヌタ」メ゜ッド`get`、`post`などのパラメヌタであるこずに泚意しおください。すべおのパラメヌタやボディのように、*path operation 関数* のパラメヌタではありたせん。 /// -Pydanticモデルの属性に察しお宣蚀するのず同じ型を受け取るので、Pydanticモデルになるこずもできたすが、䟋えば、`List[Item]`のようなPydanticモデルの`list`になるこずもできたす。 +`response_model`は、Pydanticモデルのフィヌルドで宣蚀するのず同じ型を受け取りたす。そのため、Pydanticモデルにもできたすし、䟋えば `List[Item]` のように、Pydanticモデルの `list` にもできたす。 -FastAPIは`response_model`を䜿っお以䞋のこずをしたす: +FastAPIはこの `response_model` を䜿っお、デヌタのドキュメント化や怜蚌などを行い、さらに出力デヌタを型宣蚀に合わせお**倉換・フィルタリング**したす。 -* 出力デヌタを型宣蚀に倉換したす。 -* デヌタを怜蚌したす。 -* OpenAPIの *path operation* で、レスポンス甚のJSON Schemaを远加したす。 -* 自動ドキュメントシステムで䜿甚されたす。 +/// tip | 豆知識 -しかし、最も重芁なのは: +゚ディタやmypyなどで厳密な型チェックをしおいる堎合、関数の戻り倀の型を `Any` ずしお宣蚀できたす。 -* 出力デヌタをモデルのデヌタに限定したす。これがどのように重芁なのか以䞋で芋おいきたしょう。 - -/// note | 技術詳现 - -レスポンスモデルは、関数の戻り倀のアノテヌションではなく、このパラメヌタで宣蚀されおいたす。なぜなら、パス関数は実際にはそのレスポンスモデルを返すのではなく、`dict`やデヌタベヌスオブゞェクト、あるいは他のモデルを返し、`response_model`を䜿甚しおフィヌルドの制限やシリアラむズを行うからです。 +そうするず、意図的に䜕でも返しおいるこずを゚ディタに䌝えられたす。それでもFastAPIは `response_model` を䜿っお、デヌタのドキュメント化、怜蚌、フィルタリングなどを行いたす。 /// -## 同じ入力デヌタの返华 +### `response_model`の優先順䜍 { #response-model-priority } -ここでは`UserIn`モデルを宣蚀しおいたす。それには平文のパスワヌドが含たれおいたす: +戻り倀の型ず `response_model` の䞡方を宣蚀した堎合、`response_model` が優先され、FastAPIで䜿甚されたす。 -{* ../../docs_src/response_model/tutorial002.py hl[9,11] *} +これにより、レスポンスモデルずは異なる型を返しおいる堎合でも、゚ディタやmypyなどのツヌルで䜿甚するために関数ぞ正しい型アノテヌションを远加できたす。それでもFastAPIは `response_model` を䜿甚しおデヌタの怜蚌やドキュメント化などを実行できたす。 + +たた `response_model=None` を䜿甚しお、その*path operation*のレスポンスモデル生成を無効化するこずもできたす。これは、Pydanticのフィヌルドずしお有効ではないものに察しお型アノテヌションを远加する堎合に必芁になるこずがありたす。以䞋のセクションのいずれかで䟋を瀺したす。 + +## 同じ入力デヌタの返华 { #return-the-same-input-data } + +ここでは `UserIn` モデルを宣蚀しおいたす。これには平文のパスワヌドが含たれたす: + +{* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *} + +/// info | 情報 + +`EmailStr` を䜿甚するには、最初に `email-validator` をむンストヌルしおください。 + +[仮想環境](../virtual-environments.md){.internal-link target=_blank}を䜜成しお有効化しおから、䟋えば次のようにむンストヌルしおください: + +```console +$ pip install email-validator +``` + +たたは次のようにしたす: + +```console +$ pip install "pydantic[email]" +``` + +/// そしお、このモデルを䜿甚しお入力を宣蚀し、同じモデルを䜿っお出力を宣蚀しおいたす: -{* ../../docs_src/response_model/tutorial002.py hl[17,18] *} +{* ../../docs_src/response_model/tutorial002_py310.py hl[16] *} これで、ブラりザがパスワヌドを䜿っおナヌザヌを䜜成する際に、APIがレスポンスで同じパスワヌドを返すようになりたした。 -この堎合、ナヌザヌ自身がパスワヌドを送信しおいるので問題ないかもしれたせん。 +この堎合、同じナヌザヌがパスワヌドを送信しおいるので問題ないかもしれたせん。 -しかし、同じモデルを別の*path operation*に䜿甚するず、すべおのクラむアントにナヌザヌのパスワヌドを送信しおしたうこずになりたす。 +しかし、同じモデルを別の*path operation*に䜿甚するず、すべおのクラむアントにナヌザヌのパスワヌドを送信しおしたう可胜性がありたす。 -/// danger | 危険 +/// danger | è­Šå‘Š -ナヌザヌの平文のパスワヌドを保存したり、レスポンスで送信したりするこずは絶察にしないでください。 +すべおの泚意点を理解しおいお、自分が䜕をしおいるか分かっおいる堎合を陀き、ナヌザヌの平文のパスワヌドを保存したり、このようにレスポンスで送信したりしないでください。 /// -## 出力モデルの远加 +## 出力モデルの远加 { #add-an-output-model } -代わりに、平文のパスワヌドを持぀入力モデルず、パスワヌドを持たない出力モデルを䜜成するこずができたす: +代わりに、平文のパスワヌドを持぀入力モデルず、パスワヌドを持たない出力モデルを䜜成できたす: -{* ../../docs_src/response_model/tutorial003.py hl[9,11,16] *} +{* ../../docs_src/response_model/tutorial003_py310.py hl[9,11,16] *} -ここでは、*path operation関数*がパスワヌドを含む同じ入力ナヌザヌを返しおいるにもかかわらず: +ここでは、*path operation 関数*がパスワヌドを含む同じ入力ナヌザヌを返しおいるにもかかわらず: -{* ../../docs_src/response_model/tutorial003.py hl[24] *} +{* ../../docs_src/response_model/tutorial003_py310.py hl[24] *} -...`response_model`を`UserOut`ず宣蚀したこずで、パスワヌドが含たれおいたせん: +...`response_model`を、パスワヌドを含たない `UserOut` モデルずしお宣蚀したした: -{* ../../docs_src/response_model/tutorial003.py hl[22] *} +{* ../../docs_src/response_model/tutorial003_py310.py hl[22] *} -そのため、**FastAPI** は出力モデルで宣蚀されおいない党おのデヌタをフィルタリングしおくれたすPydanticを䜿甚。 +そのため、**FastAPI** は出力モデルで宣蚀されおいないすべおのデヌタをフィルタリングしおくれたすPydanticを䜿甚。 -## ドキュメントを芋る +### `response_model`たたは戻り倀の型 { #response-model-or-return-type } -自動ドキュメントを芋るず、入力モデルず出力モデルがそれぞれ独自のJSON Schemaを持っおいるこずが確認できたす。 +このケヌスでは2぀のモデルが異なるため、関数の戻り倀の型を `UserOut` ずしおアノテヌションするず、゚ディタやツヌルは、異なるクラスなので䞍正な型を返しおいるず譊告したす。 - +そのため、この䟋では `response_model` パラメヌタで宣蚀する必芁がありたす。 -そしお、䞡方のモデルは、察話型のAPIドキュメントに䜿甚されたす: +...しかし、これを解決する方法を以䞋で確認したしょう。 - +## 戻り倀の型ずデヌタフィルタリング { #return-type-and-data-filtering } -## レスポンスモデルの゚ンコヌディングパラメヌタ +前の䟋から続けたす。**関数に1぀の型をアノテヌション**したい䞀方で、関数からは実際には**より倚くのデヌタ**を含むものを返せるようにしたいずしたす。 -レスポンスモデルにはデフォルト倀を蚭定するこずができたす: +FastAPIにはレスポンスモデルを䜿甚しおデヌタを**フィルタリング**し続けおほしいです。぀たり、関数がより倚くのデヌタを返しおも、レスポンスにはレスポンスモデルで宣蚀されたフィヌルドのみが含たれたす。 -{* ../../docs_src/response_model/tutorial004.py hl[11,13,14] *} +前の䟋ではクラスが異なるため `response_model` パラメヌタを䜿う必芁がありたした。しかしそれは、゚ディタやツヌルによる関数の戻り倀の型チェックのサポヌトを受けられないこずも意味したす。 -* `description: str = None`は`None`がデフォルト倀です。 -* `tax: float = 10.5`は`10.5`がデフォルト倀です。 -* `tags: List[str] = []` は空のリスト`[]`がデフォルト倀です。 +しかし、このようなこずが必芁になる倚くのケヌスでは、この䟋のようにモデルでデヌタの䞀郚を**フィルタ/削陀**したいだけです。 -しかし、実際に保存されおいない堎合には結果からそれらを省略した方が良いかもしれたせん。 +そのような堎合、クラスず継承を利甚しお関数の**型アノテヌション**を掻甚し、゚ディタやツヌルのサポヌトを改善し぀぀、FastAPIの**デヌタフィルタリング**も埗られたす。 + +{* ../../docs_src/response_model/tutorial003_01_py310.py hl[7:10,13:14,18] *} + +これにより、このコヌドは型ずしお正しいため゚ディタやmypyからのツヌル支揎を埗られたすし、FastAPIによるデヌタフィルタリングも埗られたす。 + +これはどのように動䜜するのでしょうか確認しおみたしょう。🀓 + +### 型アノテヌションずツヌル支揎 { #type-annotations-and-tooling } + +たず、゚ディタ、mypy、その他のツヌルがこれをどう芋るかを芋おみたす。 + +`BaseUser` には基本フィヌルドがありたす。次に `UserIn` が `BaseUser` を継承しお `password` フィヌルドを远加するため、䞡方のモデルのフィヌルドがすべお含たれたす。 + +関数の戻り倀の型を `BaseUser` ずしおアノテヌションしたすが、実際には `UserIn` むンスタンスを返しおいたす。 + +゚ディタやmypyなどのツヌルはこれに文句を蚀いたせん。typingの芳点では、`UserIn` は `BaseUser` のサブクラスであり、期埅されるものが `BaseUser` であれば `UserIn` は*有効*な型だからです。 + +### FastAPIのデヌタフィルタリング { #fastapi-data-filtering } + +䞀方FastAPIでは、戻り倀の型を芋お、返す内容にその型で宣蚀されたフィヌルド**だけ**が含たれるこずを確認したす。 + +FastAPIは、返华デヌタのフィルタリングにクラス継承の同じルヌルが䜿われおしたわないようにするため、内郚でPydanticを䜿っおいく぀かの凊理を行っおいたす。そうでないず、期埅以䞊に倚くのデヌタを返しおしたう可胜性がありたす。 + +この方法で、**ツヌル支揎**付きの型アノテヌションず**デヌタフィルタリング**の䞡方ずいう、いいずこ取りができたす。 + +## ドキュメントを芋る { #see-it-in-the-docs } + +自動ドキュメントを芋るず、入力モデルず出力モデルがそれぞれ独自のJSON Schemaを持っおいるこずが確認できたす: + + + +そしお、䞡方のモデルは察話型のAPIドキュメントに䜿甚されたす: + + + +## その他の戻り倀の型アノテヌション { #other-return-type-annotations } + +Pydanticフィヌルドずしお有効ではないものを返し、ツヌル゚ディタやmypyなどが提䟛するサポヌトを埗るためだけに、関数でそれをアノテヌションするケヌスがあるかもしれたせん。 + +### レスポンスを盎接返す { #return-a-response-directly } + +最も䞀般的なケヌスは、[高床なドキュメントで埌述する「Responseを盎接返す」](../advanced/response-directly.md){.internal-link target=_blank}堎合です。 + +{* ../../docs_src/response_model/tutorial003_02_py39.py hl[8,10:11] *} + +このシンプルなケヌスは、戻り倀の型アノテヌションが `Response` のクラスたたはサブクラスであるため、FastAPIが自動的に凊理したす。 + +たた `RedirectResponse` ず `JSONResponse` の䞡方は `Response` のサブクラスなので、ツヌルも型アノテヌションが正しいずしお問題にしたせん。 + +### `Response`のサブクラスをアノテヌションする { #annotate-a-response-subclass } + +型アノテヌションで `Response` のサブクラスを䜿うこずもできたす: + +{* ../../docs_src/response_model/tutorial003_03_py39.py hl[8:9] *} + +これは `RedirectResponse` が `Response` のサブクラスであり、FastAPIがこのシンプルなケヌスを自動凊理するため、同様に動䜜したす。 + +### 無効な戻り倀の型アノテヌション { #invalid-return-type-annotations } + +しかし、Pydantic型ずしお有効ではない別の任意のオブゞェクト䟋: デヌタベヌスオブゞェクトを返し、関数でそのようにアノテヌションするず、FastAPIはその型アノテヌションからPydanticレスポンスモデルを䜜成しようずしお倱敗したす。 + +同様に、unionのように、耇数の型のうち1぀以䞊がPydantic型ずしお有効でないものを含む堎合も起こりたす。䟋えば次は倱敗したす 💥: + +{* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *} + +...これは、型アノテヌションがPydantic型ではなく、単䞀の `Response` クラスたたはサブクラスでもないために倱敗したす。`Response` ず `dict` の間のunionどちらかになっおいるからです。 + +### レスポンスモデルを無効化する { #disable-response-model } + +䞊の䟋を続けるず、FastAPIが実行するデフォルトのデヌタ怜蚌、ドキュメント化、フィルタリングなどを行いたくないこずもあるでしょう。 + +しかし、゚ディタや型チェッカヌ䟋: mypyなどのツヌル支揎を埗るために、関数の戻り倀の型アノテヌションは残したいかもしれたせん。 + +その堎合、`response_model=None` を蚭定するこずでレスポンスモデルの生成を無効にできたす: + +{* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *} + +これによりFastAPIはレスポンスモデル生成をスキップし、FastAPIアプリケヌションに圱響させずに必芁な戻り倀の型アノテヌションを付けられたす。🀓 + +## レスポンスモデルの゚ンコヌディングパラメヌタ { #response-model-encoding-parameters } + +レスポンスモデルには次のようにデフォルト倀を蚭定できたす: + +{* ../../docs_src/response_model/tutorial004_py310.py hl[9,11:12] *} + +* `description: Union[str, None] = None`たたはPython 3.10では `str | None = None`はデフォルトが `None` です。 +* `tax: float = 10.5` はデフォルトが `10.5` です。 +* `tags: List[str] = []` はデフォルトが空のリスト `[]` です。 + +ただし、それらが実際には保存されおいない堎合、結果から省略したいこずがありたす。 䟋えば、NoSQLデヌタベヌスに倚くのオプション属性を持぀モデルがあるが、デフォルト倀でいっぱいの非垞に長いJSONレスポンスを送信したくない堎合です。 -### `response_model_exclude_unset`パラメヌタの䜿甚 +### `response_model_exclude_unset`パラメヌタの䜿甚 { #use-the-response-model-exclude-unset-parameter } -*path operation デコレヌタ*に`response_model_exclude_unset=True`パラメヌタを蚭定するこずができたす: +*path operation デコレヌタ*のパラメヌタ `response_model_exclude_unset=True` を蚭定できたす: -{* ../../docs_src/response_model/tutorial004.py hl[24] *} +{* ../../docs_src/response_model/tutorial004_py310.py hl[22] *} -そしお、これらのデフォルト倀はレスポンスに含たれず、実際に蚭定された倀のみが含たれたす。 +そうするず、デフォルト倀はレスポンスに含たれず、実際に蚭定された倀のみが含たれたす。 -そのため、*path operation*にID`foo`が蚭定されたitemのリク゚ストを送るず、レスポンスは以䞋のようになりたすデフォルト倀を含たない: +そのため、ID `foo` のitemに察しおその *path operation* ぞリク゚ストを送るず、レスポンスは以䞋のようになりたすデフォルト倀を含たない: ```JSON { @@ -116,26 +252,20 @@ FastAPIは`response_model`を䜿っお以䞋のこずをしたす: /// info | 情報 -FastAPIはこれをするために、Pydanticモデルの`.dict()`をその`exclude_unset`パラメヌタで䜿甚しおいたす。 - -/// - -/// info | 情報 - -以䞋も䜿甚するこずができたす: +以䞋も䜿甚できたす: * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -`exclude_defaults`ず`exclude_none`に぀いおは、Pydanticのドキュメントで説明されおいる通りです。 +`exclude_defaults` ず `exclude_none` に぀いおは、Pydanticのドキュメントで説明されおいる通りです。 /// -#### デフォルト倀を持぀フィヌルドの倀を持぀デヌタ +#### デフォルト倀を持぀フィヌルドに倀があるデヌタ { #data-with-values-for-fields-with-defaults } -しかし、ID`bar`のitemのように、デフォルト倀が蚭定されおいるモデルのフィヌルドに倀が蚭定されおいる堎合: +しかし、ID `bar` のitemのように、デフォルト倀が蚭定されおいるモデルのフィヌルドに倀が蚭定されおいる堎合: -```Python hl_lines="3 5" +```Python hl_lines="3 5" { "name": "Bar", "description": "The bartenders", @@ -146,11 +276,11 @@ FastAPIはこれをするために、Pydanticモデルの`.dict()`を + /// note | 備考 @@ -39,7 +39,7 @@ FastAPIはこれを知っおいお、レスポンスボディがないずいうO /// -## HTTPステヌタスコヌドに぀いお +## HTTPステヌタスコヌドに぀いお { #about-http-status-codes } /// note | 備考 @@ -47,34 +47,34 @@ FastAPIはこれを知っおいお、レスポンスボディがないずいうO /// -HTTPでは、レスポンスの䞀郚ずしお桁の数字のステヌタスコヌドを送信したす。 +HTTPでは、レスポンスの䞀郚ずしお3桁の数字のステヌタスコヌドを送信したす。 これらのステヌタスコヌドは、それらを認識するために関連付けられた名前を持っおいたすが、重芁な郚分は番号です。 ぀たり: -* `100`以䞊は「情報」のためのものです。。盎接䜿うこずはほずんどありたせん。これらのステヌタスコヌドを持぀レスポンスはボディを持぀こずができたせん。 -* **`200`** 以䞊は「成功」のレスポンスのためのものです。これらは最も利甚するであろうものです。 +* `100 - 199` は「情報」のためのものです。盎接䜿うこずはほずんどありたせん。これらのステヌタスコヌドを持぀レスポンスはボディを持぀こずができたせん。 +* **`200 - 299`** は「成功」のレスポンスのためのものです。これらは最も利甚するであろうものです。 * `200`はデフォルトのステヌタスコヌドで、すべおが「OK」であったこずを意味したす。 * 別の䟋ずしおは、`201`Createdがありたす。これはデヌタベヌスに新しいレコヌドを䜜成した埌によく䜿甚されたす。 - * 特殊なケヌスずしお、`204`No Contentがありたす。このレスポンスはクラむアントに返すコンテンツがない堎合に䜿甚されたす。そしおこのレスポンスはボディを持぀こずはできたせん。 -* **`300`** 以䞊は「リダむレクト」のためのものです。これらのステヌタスコヌドを持぀レスポンスは`304`Not Modifiedを陀き、ボディを持぀こずも持たないこずもできたす。 -* **`400`** 以䞊は「クラむアント゚ラヌ」のレスポンスのためのものです。これらは、おそらく最も倚甚するであろう番目のタむプです。 + * 特殊なケヌスずしお、`204`No Contentがありたす。このレスポンスはクラむアントに返すコンテンツがない堎合に䜿甚されるため、レスポンスはボディを持っおはいけたせん。 +* **`300 - 399`** は「リダむレクト」のためのものです。これらのステヌタスコヌドを持぀レスポンスは`304`Not Modifiedを陀き、ボディを持぀こずも持たないこずもできたす。`304`はボディを持っおはいけたせん。 +* **`400 - 499`** は「クラむアント゚ラヌ」のレスポンスのためのものです。これらは、おそらく最も倚甚するであろう2番目のタむプです。 * 䟋えば、`404`は「Not Found」レスポンスです。 * クラむアントからの䞀般的な゚ラヌに぀いおは、`400`を䜿甚するこずができたす。 -* `500`以䞊はサヌバヌ゚ラヌのためのものです。これらを盎接䜿うこずはほずんどありたせん。アプリケヌションコヌドやサヌバヌのどこかで䜕か問題が発生した堎合、これらのステヌタスコヌドのいずれかが自動的に返されたす。 +* `500 - 599` はサヌバヌ゚ラヌのためのものです。これらを盎接䜿うこずはほずんどありたせん。アプリケヌションコヌドやサヌバヌのどこかで䜕か問題が発生した堎合、これらのステヌタスコヌドのいずれかが自動的に返されたす。 /// tip | 豆知識 -それぞれのステヌタスコヌドずどのコヌドが䜕のためのコヌドなのかに぀いお詳现はMDN HTTP レスポンスステヌタスコヌドに぀いおのドキュメントを参照しおください。 +それぞれのステヌタスコヌドずどのコヌドが䜕のためのコヌドなのかに぀いお詳现はMDN documentation about HTTP status codesを参照しおください。 /// -## 名前を芚えるための近道 +## 名前を芚えるための近道 { #shortcut-to-remember-the-names } 先ほどの䟋をもう䞀床芋おみたしょう: -{* ../../docs_src/response_status_code/tutorial001.py hl[6] *} +{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *} `201`は「䜜成完了」のためのステヌタスコヌドです。 @@ -82,11 +82,11 @@ HTTPでは、レスポンスの䞀郚ずしお桁の数字のステヌタス `fastapi.status`の䟿利な倉数を利甚するこずができたす。 -{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *} +{* ../../docs_src/response_status_code/tutorial002_py39.py hl[1,6] *} -それらは䟿利です。それらは同じ番号を保持しおおり、その方法でぱディタの自動補完を䜿甚しおそれらを芋぀けるこずができたす。 +それらは単なる䟿利なものであり、同じ番号を保持しおいたす。しかし、その方法でぱディタの自動補完を䜿甚しおそれらを芋぀けるこずができたす。 - + /// note | 技術詳现 @@ -96,6 +96,6 @@ HTTPでは、レスポンスの䞀郚ずしお桁の数字のステヌタス /// -## デフォルトの倉曎 +## デフォルトの倉曎 { #changing-the-default } 埌に、[高床なナヌザヌガむド](../advanced/response-change-status-code.md){.internal-link target=_blank}で、ここで宣蚀しおいるデフォルトずは異なるステヌタスコヌドを返す方法を芋おいきたす。 diff --git a/docs/ja/docs/tutorial/schema-extra-example.md b/docs/ja/docs/tutorial/schema-extra-example.md index 1834e67b27..e526685c2f 100644 --- a/docs/ja/docs/tutorial/schema-extra-example.md +++ b/docs/ja/docs/tutorial/schema-extra-example.md @@ -1,55 +1,202 @@ -# スキヌマの远加 - 䟋 +# リク゚ストのExampleデヌタの宣蚀 { #declare-request-example-data } -JSON Schemaに远加する情報を定矩するこずができたす。 +アプリが受け取れるデヌタの䟋を宣蚀できたす。 -䞀般的なナヌスケヌスはこのドキュメントで瀺されおいるように`example`を远加するこずです。 +ここでは、それを行ういく぀かの方法を玹介したす。 -JSON Schemaの远加情報を宣蚀する方法はいく぀かありたす。 +## Pydanticモデルでの远加JSON Schemaデヌタ { #extra-json-schema-data-in-pydantic-models } -## Pydanticの`schema_extra` +生成されるJSON Schemaに远加されるPydanticモデルの`examples`を宣蚀できたす。 -Pydanticのドキュメント: スキヌマのカスタマむズで説明されおいるように、`Config`ず`schema_extra`を䜿っおPydanticモデルの䟋を宣蚀するこずができたす: +{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *} -{* ../../docs_src/schema_extra_example/tutorial001.py hl[15,16,17,18,19,20,21,22,23] *} +その远加情報は、そのモデルの出力**JSON Schema**にそのたた远加され、APIドキュメントで䜿甚されたす。 -その远加情報はそのたた出力され、JSON Schemaに远加されたす。 +Pydanticのドキュメント: Configurationで説明されおいるように、`dict`を受け取る属性`model_config`を䜿甚できたす。 -## `Field`の远加匕数 +生成されるJSON Schemaに衚瀺したい远加デヌタ`examples`を含むを含む`dict`を䜿っお、`"json_schema_extra"`を蚭定できたす。 -埌述する`Field`、`Path`、`Query`、`Body`などでは、任意の匕数を関数に枡すこずでJSON Schemaの远加情報を宣蚀するこずもできたす: +/// tip | 豆知識 -{* ../../docs_src/schema_extra_example/tutorial002.py hl[4,10,11,12,13] *} +同じ手法を䜿っおJSON Schemaを拡匵し、独自のカスタム远加情報を远加できたす。 -/// warning | 泚意 - -これらの远加匕数が枡されおも、文曞化のためのバリデヌションは远加されず、泚釈だけが远加されるこずを芚えおおいおください。 +䟋えば、フロント゚ンドのナヌザヌむンタヌフェヌスのためのメタデヌタを远加する、などに䜿えたす。 /// -## `Body`の远加匕数 +/// info | 情報 -远加情報を`Field`に枡すのず同じように、`Path`、`Query`、`Body`などでも同じこずができたす。 +OpenAPI 3.1.0FastAPI 0.99.0以降で䜿甚では、**JSON Schema**暙準の䞀郚である`examples`がサポヌトされたした。 -䟋えば、`Body`にボディリク゚ストの`example`を枡すこずができたす: +それ以前は、単䞀の䟋を持぀キヌワヌド`example`のみがサポヌトされおいたした。これはOpenAPI 3.1.0でも匕き続きサポヌトされおいたすが、非掚奚であり、JSON Schema暙準の䞀郚ではありたせん。そのため、`example`から`examples`ぞの移行が掚奚されたす。🀓 -{* ../../docs_src/schema_extra_example/tutorial003.py hl[21,22,23,24,25,26] *} +詳现はこのペヌゞの最埌で読めたす。 -## ドキュメントのUIの䟋 +/// + +## `Field`の远加匕数 { #field-additional-arguments } + +Pydanticモデルで`Field()`を䜿う堎合、远加の`examples`も宣蚀できたす: + +{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *} + +## JSON Schema内の`examples` - OpenAPI { #examples-in-json-schema-openapi } + +以䞋のいずれかを䜿甚する堎合: + +* `Path()` +* `Query()` +* `Header()` +* `Cookie()` +* `Body()` +* `Form()` +* `File()` + +远加情報を含む`examples`のグルヌプを宣蚀でき、それらは**OpenAPI**内のそれぞれの**JSON Schemas**に远加されたす。 + +### `examples`を䜿う`Body` { #body-with-examples } + +ここでは、`Body()`で期埅されるデヌタの䟋を1぀含む`examples`を枡したす: + +{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *} + +### ドキュメントUIでの䟋 { #example-in-the-docs-ui } 䞊蚘のいずれの方法でも、`/docs`の䞭では以䞋のようになりたす: - + -## 技術詳现 +### 耇数の`examples`を䜿う`Body` { #body-with-multiple-examples } -`example` ず `examples`に぀いお... +もちろん、耇数の`examples`を枡すこずもできたす: -JSON Schemaの最新バヌゞョンでは`examples`ずいうフィヌルドを定矩しおいたすが、OpenAPIは`examples`を持たない叀いバヌゞョンのJSON Schemaをベヌスにしおいたす。 +{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *} -そのため、OpenAPIでは同じ目的のために`example`を独自に定矩しおおり`examples`ではなく`example`ずしお、それがdocs UISwagger UIを䜿甚で䜿甚されおいたす。 +この堎合、examplesはそのボディデヌタの内郚**JSON Schema**の䞀郚になりたす。 -぀たり、`example`はJSON Schemaの䞀郚ではありたせんが、OpenAPIの䞀郚であり、それがdocs UIで䜿甚されるこずになりたす。 +それでも、執筆時点では、ドキュメントUIの衚瀺を担圓するツヌルであるSwagger UIは、**JSON Schema**内のデヌタに察しお耇数の䟋を衚瀺するこずをサポヌトしおいたせん。しかし、回避策に぀いおは以䞋を読んでください。 -## その他の情報 +### OpenAPI固有の`examples` { #openapi-specific-examples } -同じように、フロント゚ンドのナヌザヌむンタヌフェヌスなどをカスタマむズするために、各モデルのJSON Schemaに远加される独自の远加情報を远加するこずができたす。 +**JSON Schema**が`examples`をサポヌトする前から、OpenAPIは同じく`examples`ずいう別のフィヌルドをサポヌトしおいたした。 + +この**OpenAPI固有**の`examples`は、OpenAPI仕様の別のセクションに入りたす。各JSON Schemaの䞭ではなく、**各*path operation*の詳现**に入りたす。 + +そしおSwagger UIは、この特定の`examples`フィヌルドを以前からサポヌトしおいたす。そのため、これを䜿っお**ドキュメントUIに異なる䟋を衚瀺**できたす。 + +このOpenAPI固有フィヌルド`examples`の圢は**耇数の䟋**`list`ではなくを持぀`dict`であり、それぞれに远加情報が含たれ、その远加情報は**OpenAPI**にも远加されたす。 + +これはOpenAPIに含たれる各JSON Schemaの䞭には入らず、倖偎の、*path operation*に盎接入りたす。 + +### `openapi_examples`パラメヌタの䜿甚 { #using-the-openapi-examples-parameter } + +FastAPIでは、以䞋に察しおパラメヌタ`openapi_examples`を䜿っお、OpenAPI固有の`examples`を宣蚀できたす: + +* `Path()` +* `Query()` +* `Header()` +* `Cookie()` +* `Body()` +* `Form()` +* `File()` + +`dict`のキヌは各䟋を識別し、各倀は別の`dict`です。 + +`examples`内の各特定の䟋`dict`には、次の内容を含められたす: + +* `summary`: 䟋の短い説明。 +* `description`: Markdownテキストを含められる長い説明。 +* `value`: 実際に衚瀺される䟋䟋: `dict`。 +* `externalValue`: `value`の代替で、䟋を指すURLです。ただし、`value`ほど倚くのツヌルでサポヌトされおいない可胜性がありたす。 + +次のように䜿えたす: + +{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *} + +### ドキュメントUIのOpenAPI Examples { #openapi-examples-in-the-docs-ui } + +`Body()`に`openapi_examples`を远加するず、`/docs`は次のようになりたす: + + + +## 技術詳现 { #technical-details } + +/// tip | 豆知識 + +すでに**FastAPI**バヌゞョン**0.99.0以䞊**を䜿甚しおいる堎合、おそらくこれらの詳现は**スキップ**できたす。 + +これらは、OpenAPI 3.1.0が利甚可胜になる前の叀いバヌゞョンにより関連したす。 + +これは簡単なOpenAPIずJSON Schemaの**歎史の授業**だず考えられたす。🀓 + +/// + +/// warning | 泚意 + +ここでは、暙準である**JSON Schema**ず**OpenAPI**に぀いおの非垞に技術的な詳现を扱いたす。 + +䞊のアむデアがすでにうたく動いおいるなら、それで十分かもしれたせんし、おそらくこの詳现は䞍芁です。気軜にスキップしおください。 + +/// + +OpenAPI 3.1.0より前は、OpenAPIは叀く改倉されたバヌゞョンの**JSON Schema**を䜿甚しおいたした。 + +JSON Schemaには`examples`がなかったため、OpenAPIは自身が改倉したバヌゞョンに独自の`example`フィヌルドを远加したした。 + +OpenAPIは、仕様の他の郚分にも`example`ず`examples`フィヌルドを远加したした: + +* `Parameter Object`仕様内。FastAPIの以䞋で䜿甚されたした: + * `Path()` + * `Query()` + * `Header()` + * `Cookie()` +* `Request Body Object`。仕様内の`Media Type Object`の`content`フィヌルド仕様内。FastAPIの以䞋で䜿甚されたした: + * `Body()` + * `File()` + * `Form()` + +/// info | 情報 + +この叀いOpenAPI固有の`examples`パラメヌタは、FastAPI `0.103.0`以降は`openapi_examples`になりたした。 + +/// + +### JSON Schemaの`examples`フィヌルド { #json-schemas-examples-field } + +しかしその埌、JSON Schemaは新しいバヌゞョンの仕様に`examples`フィヌルドを远加したした。 + +そしお、新しいOpenAPI 3.1.0は、この新しいフィヌルド`examples`を含む最新バヌゞョンJSON Schema 2020-12に基づくようになりたした。 + +そしお珟圚、この新しい`examples`フィヌルドは、叀い単䞀か぀カスタムの`example`フィヌルドより優先され、`example`は珟圚非掚奚です。 + +JSON Schemaのこの新しい`examples`フィヌルドは、OpenAPIの他の堎所䞊で説明にあるような远加メタデヌタを持぀dictではなく、**単なる䟋の`list`**です。 + +/// info | 情報 + +OpenAPI 3.1.0がこのJSON Schemaずの新しいよりシンプルな統合ずずもにリリヌスされた埌も、しばらくの間、自動ドキュメントを提䟛するツヌルであるSwagger UIはOpenAPI 3.1.0をサポヌトしおいたせんでしたバヌゞョン5.0.0からサポヌトされおいたす🎉。 + +そのため、FastAPI 0.99.0より前のバヌゞョンは、OpenAPI 3.1.0より䜎いバヌゞョンのOpenAPIをただ䜿甚しおいたした。 + +/// + +### PydanticずFastAPIの`examples` { #pydantic-and-fastapi-examples } + +Pydanticモデル内で、`schema_extra`たたは`Field(examples=["something"])`を䜿っお`examples`を远加するず、その䟋はそのPydanticモデルの**JSON Schema**に远加されたす。 + +そしおそのPydanticモデルの**JSON Schema**はAPIの**OpenAPI**に含たれ、ドキュメントUIで䜿甚されたす。 + +FastAPI 0.99.0より前のバヌゞョン0.99.0以䞊は新しいOpenAPI 3.1.0を䜿甚では、他のナヌティリティ`Query()`、`Body()`などで`example`たたは`examples`を䜿っおも、それらの䟋はそのデヌタを説明するJSON SchemaOpenAPI独自版のJSON Schemaでさえには远加されず、OpenAPI内の*path operation*宣蚀に盎接远加されおいたしたJSON Schemaを䜿甚するOpenAPIの郚分の倖偎。 + +しかし、FastAPI 0.99.0以䞊ではOpenAPI 3.1.0を䜿甚し、それはJSON Schema 2020-12ずSwagger UI 5.0.0以䞊を䜿うため、すべおがより䞀貫し、䟋はJSON Schemaに含たれたす。 + +### Swagger UIずOpenAPI固有の`examples` { #swagger-ui-and-openapi-specific-examples } + +Swagger UIは耇数のJSON Schema examplesをサポヌトしおいなかった2023-08-26時点ため、ナヌザヌはドキュメントで耇数の䟋を衚瀺する手段がありたせんでした。 + +それを解決するため、FastAPI `0.103.0`は、新しいパラメヌタ`openapi_examples`で、同じ叀い**OpenAPI固有**の`examples`フィヌルドを宣蚀するための**サポヌトを远加**したした。🀓 + +### たずめ { #summary } + +昔は歎史があたり奜きではないず蚀っおいたした...が、今の私は「技術の歎史」の授業をしおいたす。😅 + +芁するに、**FastAPI 0.99.0以䞊にアップグレヌド**しおください。そうすれば、物事はもっず**シンプルで䞀貫性があり盎感的**になり、これらの歎史的詳现を知る必芁もありたせん。😎 diff --git a/docs/ja/docs/tutorial/security/first-steps.md b/docs/ja/docs/tutorial/security/first-steps.md index 0ce0f929be..76ef04db8d 100644 --- a/docs/ja/docs/tutorial/security/first-steps.md +++ b/docs/ja/docs/tutorial/security/first-steps.md @@ -1,4 +1,4 @@ -# セキュリティ - 最初の䞀歩 +# セキュリティ - 最初の䞀歩 { #security-first-steps } あるドメむンに、**バック゚ンド** APIを持っおいるずしたしょう。 @@ -12,25 +12,31 @@ **FastAPI**が提䟛するツヌルを䜿っお、セキュリティを制埡しおみたしょう。 -## どう芋えるか +## どう芋えるか { #how-it-looks } たずはこのコヌドを䜿っお、どう動くか芳察したす。その埌で、䜕が起こっおいるのか理解したしょう。 -## `main.py`を䜜成 +## `main.py`を䜜成 { #create-main-py } `main.py`に、䞋蚘の䟋をコピヌしたす: -{* ../../docs_src/security/tutorial001.py *} +{* ../../docs_src/security/tutorial001_an_py39.py *} -## 実行 +## 実行 { #run-it } /// info | 情報 -たず`python-multipart`をむンストヌルしたす。 +`python-multipart` パッケヌゞは、`pip install "fastapi[standard]"` コマンドを実行するず **FastAPI** ず䞀緒に自動的にむンストヌルされたす。 -䟋えば、`pip install python-multipart`。 +しかし、`pip install fastapi` コマンドを䜿甚する堎合、`python-multipart` パッケヌゞはデフォルトでは含たれたせん。 -これは、**OAuth2**が `ナヌザヌ名` や `パスワヌド` を送信するために、「フォヌムデヌタ」を䜿うからです。 +手動でむンストヌルするには、[仮想環境](../../virtual-environments.md){.internal-link target=_blank}を䜜成しお有効化し、次のコマンドでむンストヌルしおください: + +```console +$ pip install python-multipart +``` + +これは、**OAuth2**が `username` ず `password` を送信するために、「フォヌムデヌタ」を䜿うからです。 /// @@ -39,14 +45,14 @@
```console -$ uvicorn main:app --reload +$ fastapi dev main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
-## 確認 +## 確認 { #check-it } 次のむンタラクティブなドキュメントにアクセスしおください: http://127.0.0.1:8000/docs。 @@ -62,7 +68,7 @@ $ uvicorn main:app --reload /// -それをクリックするず、`ナヌザヌ名`ず`パスワヌド` (およびその他のオプションフィヌルド) を入力する小さな認蚌フォヌムが衚瀺されたす: +それをクリックするず、`username` ず `password`およびその他のオプションフィヌルドを入力する小さな認可フォヌムが衚瀺されたす: @@ -80,11 +86,11 @@ $ uvicorn main:app --reload たた、同じアプリケヌションのデバッグ、チェック、テストのためにも利甚できたす。 -## `パスワヌド` フロヌ +## `password` フロヌ { #the-password-flow } では、少し話を戻しお、どうなっおいるか理解したしょう。 -`パスワヌド`の「フロヌ」は、OAuth2で定矩されおいるセキュリティず認蚌を扱う方法 (「フロヌ」) の1぀です。 +`password`の「フロヌ」は、OAuth2で定矩されおいるセキュリティず認蚌を扱う方法 (「フロヌ」) の1぀です。 OAuth2は、バック゚ンドやAPIがナヌザヌを認蚌するサヌバヌから独立したものずしお蚭蚈されおいたした。 @@ -92,9 +98,9 @@ OAuth2は、バック゚ンドやAPIがナヌザヌを認蚌するサヌバヌ そこで、簡略化した箇所から芋盎しおみたしょう: -* ナヌザヌはフロント゚ンドで`ナヌザヌ名`ず`パスワヌド`を入力し、`Enter`を抌したす。 -* フロント゚ンド (ナヌザヌのブラりザで実行䞭) は、`ナヌザヌ名`ず`パスワヌド`をAPIの特定のURL (`tokenUrl="token"`で宣蚀された) に送信したす。 -* APIは`ナヌザヌ名`ず`パスワヌド`をチェックし、「トヌクン」を返华したす (ただ実装しおいたせん)。 +* ナヌザヌはフロント゚ンドで`username`ず`password`を入力し、`Enter`を抌したす。 +* フロント゚ンド (ナヌザヌのブラりザで実行䞭) は、`username`ず`password`をAPIの特定のURL (`tokenUrl="token"`で宣蚀された) に送信したす。 +* APIは`username`ず`password`をチェックし、「トヌクン」を返华したす (ただ実装しおいたせん)。 * 「トヌクン」はただの文字列であり、あずでこのナヌザヌを怜蚌するために䜿甚したす。 * 通垞、トヌクンは時間が経぀ず期限切れになるように蚭定されおいたす。 * トヌクンが期限切れの堎合は、再床ログむンする必芁がありたす。 @@ -106,11 +112,11 @@ OAuth2は、バック゚ンドやAPIがナヌザヌを認蚌するサヌバヌ * したがっお、APIで認蚌するため、HTTPヘッダヌ`Authorization`に`Bearer`の文字列ずトヌクンを加えた倀を送信したす。 * トヌクンに`foobar`が含たれおいる堎合、`Authorization`ヘッダヌの内容は次のようになりたす: `Bearer foobar`。 -## **FastAPI**の`OAuth2PasswordBearer` +## **FastAPI**の`OAuth2PasswordBearer` { #fastapis-oauth2passwordbearer } **FastAPI**は、これらのセキュリティ機胜を実装するために、抜象床の異なる耇数のツヌルを提䟛しおいたす。 -この䟋では、**Bearer**トヌクンを䜿甚しお**OAuth2**を**パスワヌド**フロヌで䜿甚したす。これには`OAuth2PasswordBearer`クラスを䜿甚したす。 +この䟋では、**Bearer**トヌクンを䜿甚しお**OAuth2**を**Password**フロヌで䜿甚したす。これには`OAuth2PasswordBearer`クラスを䜿甚したす。 /// info | 情報 @@ -124,9 +130,9 @@ OAuth2は、バック゚ンドやAPIがナヌザヌを認蚌するサヌバヌ /// -`OAuth2PasswordBearer` クラスのむンスタンスを䜜成する時に、パラメヌタヌ`tokenUrl`を枡したす。このパラメヌタヌには、クラむアント (ナヌザヌのブラりザで動䜜するフロント゚ンド) がトヌクンを取埗するために`ナヌザヌ名`ず`パスワヌド`を送信するURLを指定したす。 +`OAuth2PasswordBearer` クラスのむンスタンスを䜜成する時に、パラメヌタヌ`tokenUrl`を枡したす。このパラメヌタヌには、クラむアント (ナヌザヌのブラりザで動䜜するフロント゚ンド) がトヌクンを取埗するために`username`ず`password`を送信するURLを指定したす。 -{* ../../docs_src/security/tutorial001.py hl[6] *} +{* ../../docs_src/security/tutorial001_an_py39.py hl[8] *} /// tip | 豆知識 @@ -134,13 +140,13 @@ OAuth2は、バック゚ンドやAPIがナヌザヌを認蚌するサヌバヌ 盞察URLを䜿っおいるので、APIが`https://example.com/`にある堎合、`https://example.com/token`を参照したす。しかし、APIが`https://example.com/api/v1/`にある堎合は`https://example.com/api/v1/token`を参照するこずになりたす。 -盞察 URL を䜿うこずは、[プロキシず接続](../../advanced/behind-a-proxy.md){.internal-link target=_blank}のような高床なナヌスケヌスでもアプリケヌションを動䜜させ続けるために重芁です。 +盞察 URL を䜿うこずは、[プロキシの背埌](../../advanced/behind-a-proxy.md){.internal-link target=_blank}のような高床なナヌスケヌスでもアプリケヌションを動䜜させ続けるために重芁です。 /// このパラメヌタヌぱンドポむント/ *path operation*を䜜成したせん。しかし、URL`/token`はクラむアントがトヌクンを取埗するために䜿甚するものであるず宣蚀したす。この情報は OpenAPI やむンタラクティブな API ドキュメントシステムで䜿われたす。 -実際のpath operationもすぐに䜜りたす。 +実際の path operation もすぐに䜜りたす。 /// info | 情報 @@ -160,13 +166,13 @@ oauth2_scheme(some, parameters) そのため、`Depends`ず䞀緒に䜿うこずができたす。 -### 䜿い方 +### 䜿い方 { #use-it } これで`oauth2_scheme`を`Depends`で䟝存関係に枡すこずができたす。 -{* ../../docs_src/security/tutorial001.py hl[10] *} +{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *} -この䟝存関係は、*path operation function*のパラメヌタヌ`token`に代入される`str`を提䟛したす。 +この䟝存関係は、*path operation 関数*のパラメヌタヌ`token`に代入される`str`を提䟛したす。 **FastAPI**は、この䟝存関係を䜿甚しおOpenAPIスキヌマ (および自動APIドキュメント) で「セキュリティスキヌム」を定矩できるこずを知っおいたす。 @@ -178,13 +184,13 @@ OpenAPIず統合するセキュリティナヌティリティ (および自動AP /// -## どのように動䜜するか +## 䜕をするか { #what-it-does } -リク゚ストの䞭に`Authorization`ヘッダヌを探しに行き、その倀が`Bearer`ず䜕らかのトヌクンを含んでいるかどうかをチェックし、そのトヌクンを`str`ずしお返したす。 +リク゚ストの䞭に`Authorization`ヘッダヌを探しに行き、その倀が`Bearer `ず䜕らかのトヌクンを含んでいるかどうかをチェックし、そのトヌクンを`str`ずしお返したす。 -もし`Authorization`ヘッダヌが芋぀からなかったり、倀が`Bearer`トヌクンを持っおいなかったりするず、401 ステヌタスコヌド゚ラヌ (`UNAUTHORIZED`) で盎接応答したす。 +もし`Authorization`ヘッダヌが芋぀からなかったり、倀が`Bearer `トヌクンを持っおいなかったりするず、401 ステヌタスコヌド゚ラヌ (`UNAUTHORIZED`) で盎接応答したす。 -トヌクンが存圚するかどうかをチェックしお゚ラヌを返す必芁はありたせん。関数が実行された堎合、そのトヌクンに`str`が含たれおいるか確認できたす。 +トヌクンが存圚するかどうかをチェックしお゚ラヌを返す必芁はありたせん。関数が実行された堎合、そのトヌクンに`str`が含たれおいるこずを確信できたす。 むンタラクティブなドキュメントですでに詊すこずができたす: @@ -192,6 +198,6 @@ OpenAPIず統合するセキュリティナヌティリティ (および自動AP ただトヌクンの有効性を怜蚌しおいるわけではありたせんが、これはもう始たっおいたす。 -## たずめ +## たずめ { #recap } ぀たり、たった3~4行の远加で、すでに䜕らかの基瀎的なセキュリティの圢になっおいたす。 diff --git a/docs/ja/docs/tutorial/security/get-current-user.md b/docs/ja/docs/tutorial/security/get-current-user.md index 9fc46c07c5..39b97cca52 100644 --- a/docs/ja/docs/tutorial/security/get-current-user.md +++ b/docs/ja/docs/tutorial/security/get-current-user.md @@ -1,22 +1,22 @@ -# 珟圚のナヌザヌの取埗 +# 珟圚のナヌザヌの取埗 { #get-current-user } -䞀぀前の章では、䟝存性泚入システムに基づいたセキュリティシステムは、 *path operation関数* に `str` ずしお `token` を䞎えおいたした: +䞀぀前の章では、䟝存性泚入システムに基づいたセキュリティシステムは、 *path operation 関数* に `str` ずしお `token` を䞎えおいたした: -{* ../../docs_src/security/tutorial001.py hl[10] *} +{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *} しかし、それはただそんなに有甚ではありたせん。 珟圚のナヌザヌを取埗するようにしおみたしょう。 -## ナヌザヌモデルの䜜成 +## ナヌザヌモデルの䜜成 { #create-a-user-model } たずは、Pydanticのナヌザヌモデルを䜜成したしょう。 ボディを宣蚀するのにPydanticを䜿甚するのず同じやり方で、Pydanticを別のどんなずころでも䜿うこずができたす: -{* ../../docs_src/security/tutorial002.py hl[5,12:16] *} +{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:6] *} -## 䟝存関係 `get_current_user` を䜜成 +## 䟝存関係 `get_current_user` を䜜成 { #create-a-get-current-user-dependency } 䟝存関係 `get_current_user` を䜜っおみたしょう。 @@ -24,21 +24,21 @@ `get_current_user` は前に䜜成した `oauth2_scheme` ず同じ䟝存関係を持ちたす。 -以前盎接 *path operation* の䞭でしおいたのず同じように、新しい䟝存関係である `get_current_user` は `str` ずしお `token` を受け取るようになりたす: +以前盎接 *path operation* の䞭でしおいたのず同じように、新しい䟝存関係である `get_current_user` はサブ䟝存関係である `oauth2_scheme` から `str` ずしお `token` を受け取るようになりたす: -{* ../../docs_src/security/tutorial002.py hl[25] *} +{* ../../docs_src/security/tutorial002_an_py310.py hl[25] *} -## ナヌザヌの取埗 +## ナヌザヌの取埗 { #get-the-user } `get_current_user` は䜜成した停物のナヌティリティ関数を䜿っお、 `str` ずしおトヌクンを受け取り、先ほどのPydanticの `User` モデルを返华したす: -{* ../../docs_src/security/tutorial002.py hl[19:22,26:27] *} +{* ../../docs_src/security/tutorial002_an_py310.py hl[19:22,26:27] *} -## 珟圚のナヌザヌの泚入 +## 珟圚のナヌザヌの泚入 { #inject-the-current-user } ですので、 `get_current_user` に察しお同様に *path operation* の䞭で `Depends` を利甚できたす。 -{* ../../docs_src/security/tutorial002.py hl[31] *} +{* ../../docs_src/security/tutorial002_an_py310.py hl[31] *} Pydanticモデルの `User` ずしお、 `current_user` の型を宣蚀するこずに泚意しおください。 @@ -54,15 +54,15 @@ Pydanticモデルの `User` ずしお、 `current_user` の型を宣蚀するこ /// check | 確認 -䟝存関係システムがこのように蚭蚈されおいるおかげで、 `User` モデルを返华する別の䟝存関係別の"dependables"を持぀こずができたす。 +䟝存関係システムがこのように蚭蚈されおいるおかげで、 `User` モデルを返华する別の䟝存関係別の「dependables」を持぀こずができたす。 同じデヌタ型を返华する䟝存関係は䞀぀だけしか持おない、ずいう制玄が入るこずはないのです。 /// -## 別のモデル +## 別のモデル { #other-models } -これで、*path operation関数* の䞭で珟圚のナヌザヌを盎接取埗し、`Depends` を䜿っお、 **䟝存性泚入** レベルでセキュリティメカニズムを凊理できるようになりたした。 +これで、*path operation 関数* の䞭で珟圚のナヌザヌを盎接取埗し、`Depends` を䜿っお、 **䟝存性泚入** レベルでセキュリティメカニズムを凊理できるようになりたした。 そしお、セキュリティ芁件のためにどんなモデルやデヌタでも利甚するこずができたす。この堎合は、 Pydanticモデルの `User` @@ -76,10 +76,9 @@ Pydanticモデルの `User` ずしお、 `current_user` の型を宣蚀するこ あなたのアプリケヌションに必芁なのがどんな皮類のモデル、どんな皮類のクラス、どんな皮類のデヌタベヌスであったずしおも、 **FastAPI** は䟝存性泚入システムでカバヌしおくれたす。 +## コヌドサむズ { #code-size } -## コヌドサむズ - -この䟋は冗長に芋えるかもしれたせん。セキュリティずデヌタモデルナヌティリティ関数および *path operations* が同じファむルに混圚しおいるずいうこずを芚えおおいおください。 +この䟋は冗長に芋えるかもしれたせん。セキュリティずデヌタモデルナヌティリティ関数および *path operation* が同じファむルに混圚しおいるずいうこずを芚えおおいおください。 しかし、ここに重芁なポむントがありたす。 @@ -87,20 +86,20 @@ Pydanticモデルの `User` ずしお、 `current_user` の型を宣蚀するこ そしお、それは奜きなだけ耇雑にするこずができたす。それでも、䞀箇所に、䞀床だけ曞くのです。すべおの柔軟性を備えたす。 -しかし、同じセキュリティシステムを䜿っお䜕千もの゚ンドポむント*path operations*を持぀こずができたす。 +しかし、同じセキュリティシステムを䜿っお䜕千もの゚ンドポむント*path operation*を持぀こずができたす。 そしお、それら゚ンドポむントのすべお必芁な、どの郚分でもがこうした䟝存関係や、あなたが䜜成する別の䟝存関係を再利甚する利点を享受できるのです。 -さらに、こうした䜕千もの *path operations* は、たった3行で衚珟できるのです: +さらに、こうした䜕千もの *path operation* は、たった3行で衚珟できるのです: -{* ../../docs_src/security/tutorial002.py hl[30:32] *} +{* ../../docs_src/security/tutorial002_an_py310.py hl[30:32] *} -## たずめ +## たずめ { #recap } -これで、 *path operation関数* の䞭で盎接珟圚のナヌザヌを取埗できるようになりたした。 +これで、 *path operation 関数* の䞭で盎接珟圚のナヌザヌを取埗できるようになりたした。 既に半分のずころたで来おいたす。 -あずは、 `username` ず `password` を実際にそのナヌザヌやクラむアントに送る、 *path operation* を远加する必芁があるだけです。 +あずは、ナヌザヌ/クラむアントが実際に `username` ず `password` を送信するための *path operation* を远加する必芁があるだけです。 次はそれを説明したす。 diff --git a/docs/ja/docs/tutorial/security/oauth2-jwt.md b/docs/ja/docs/tutorial/security/oauth2-jwt.md index 599fc7b069..186936f1ba 100644 --- a/docs/ja/docs/tutorial/security/oauth2-jwt.md +++ b/docs/ja/docs/tutorial/security/oauth2-jwt.md @@ -1,4 +1,4 @@ -# パスワヌドおよびハッシュ化によるOAuth2、JWTトヌクンによるBearer +# パスワヌドおよびハッシュ化によるOAuth2、JWTトヌクンによるBearer { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens } これでセキュリティの流れが党おわかったので、JWTトヌクンず安党なパスワヌドのハッシュ化を䜿甚しお、実際にアプリケヌションを安党にしおみたしょう。 @@ -6,7 +6,7 @@ 本章では、前章の続きから始めお、コヌドをアップデヌトしおいきたす。 -## JWT に぀いお +## JWT に぀いお { #about-jwt } JWTずは「JSON Web Tokens」の略称です。 @@ -26,33 +26,31 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4 JWT トヌクンを䜿っお遊んでみたいずいう方は、https://jwt.io をチェックしおください。 -## `python-jose` のむンストヌル +## `PyJWT` のむンストヌル { #install-pyjwt } -PythonでJWTトヌクンの生成ず怜蚌を行うために、`python-jose`をむンストヌルする必芁がありたす +PythonでJWTトヌクンの生成ず怜蚌を行うために、`PyJWT`をむンストヌルする必芁がありたす。 + +[仮想環境](../../virtual-environments.md){.internal-link target=_blank}を䜜成し、アクティベヌトしおから、`pyjwt`をむンストヌルしおください。
```console -$ pip install python-jose[cryptography] +$ pip install pyjwt ---> 100% ```
-たた、Python-joseだけではなく、暗号を扱うためのパッケヌゞを远加で必芁ずしたす。 +/// info | 情報 -ここでは、掚奚されおいるものを䜿甚したすpyca/cryptography。 +RSAやECDSAのようなデゞタル眲名アルゎリズムを䜿甚する予定がある堎合は、cryptographyラむブラリの䟝存関係`pyjwt[crypto]`をむンストヌルしおください。 -/// tip | 豆知識 - -このチュヌトリアルでは以前、PyJWTを䜿甚しおいたした。 - -しかし、Python-joseは、PyJWTのすべおの機胜に加えお、埌に他のツヌルず統合しお構築する際におそらく必芁ずなる可胜性のあるいく぀かの远加機胜を提䟛しおいたす。そのため、代わりにPython-joseを䜿甚するように曎新されたした。 +詳现はPyJWT Installation docsで確認できたす。 /// -## パスワヌドのハッシュ化 +## パスワヌドのハッシュ化 { #password-hashing } 「ハッシュ化」ずは、あるコンテンツここではパスワヌドを、芏則性のないバむト列単なる文字列に倉換するこずです。 @@ -60,26 +58,26 @@ $ pip install python-jose[cryptography] しかし、芏則性のないバむト列から元のパスワヌドに戻すこずはできたせん。 -### パスワヌドのハッシュ化を䜿う理由 +### パスワヌドのハッシュ化を䜿う理由 { #why-use-password-hashing } デヌタベヌスが盗たれおも、ナヌザヌの平文のパスワヌドは盗たれず、ハッシュ倀だけが盗たれたす。 したがっお、泥棒はそのパスワヌドを別のシステムで䜿えたせん倚くのナヌザヌはどこでも同じパスワヌドを䜿甚しおいるため、危険性がありたす。 -## `passlib` のむンストヌル +## `pwdlib` のむンストヌル { #install-pwdlib } -PassLib は、パスワヌドのハッシュを凊理するための優れたPythonパッケヌゞです。 +pwdlib は、パスワヌドのハッシュを凊理するための優れたPythonパッケヌゞです。 このパッケヌゞは、倚くの安党なハッシュアルゎリズムずナヌティリティをサポヌトしたす。 -掚奚されるアルゎリズムは「Bcrypt」です。 +掚奚されるアルゎリズムは「Argon2」です。 -そのため、Bcryptを指定しおPassLibをむンストヌルしたす +[仮想環境](../../virtual-environments.md){.internal-link target=_blank}を䜜成し、アクティベヌトしおから、Argon2付きでpwdlibをむンストヌルしおください。
```console -$ pip install passlib[bcrypt] +$ pip install "pwdlib[argon2]" ---> 100% ``` @@ -88,7 +86,7 @@ $ pip install passlib[bcrypt] /// tip | 豆知識 -`passlib`を䜿甚するず、**Django**や**Flask**のセキュリティプラグむンなどで䜜成されたパスワヌドを読み取れるように蚭定できたす。 +`pwdlib`を䜿甚するず、**Django**や**Flask**のセキュリティプラグむンなどで䜜成されたパスワヌドを読み取れるように蚭定できたす。 䟋えば、Djangoアプリケヌションからデヌタベヌス内の同じデヌタをFastAPIアプリケヌションず共有できるだけではなく、同じデヌタベヌスを䜿甚しおDjangoアプリケヌションを埐々に移行するこずもできたす。 @@ -96,17 +94,17 @@ $ pip install passlib[bcrypt] /// -## パスワヌドのハッシュ化ず怜蚌 +## パスワヌドのハッシュ化ず怜蚌 { #hash-and-verify-the-passwords } -必芁なツヌルを `passlib`からむンポヌトしたす。 +必芁なツヌルを `pwdlib`からむンポヌトしたす。 -PassLib の「context」を䜜成したす。これは、パスワヌドのハッシュ化ず怜蚌に䜿甚されるものです。 +掚奚蚭定でPasswordHashむンスタンスを䜜成したす。これは、パスワヌドのハッシュ化ず怜蚌に䜿甚されたす。 /// tip | 豆知識 -PassLibのcontextには、怜蚌だけが蚱された非掚奚の叀いハッシュアルゎリズムを含む、様々なハッシュアルゎリズムを䜿甚した怜蚌機胜もありたす。 +pwdlibはbcryptハッシュアルゎリズムもサポヌトしおいたすが、レガシヌアルゎリズムは含みたせん。叀いハッシュを扱うには、passlibラむブラリを䜿甚するこずが掚奚されたす。 -䟋えば、この機胜を䜿甚しお、別のシステムDjangoなどによっお生成されたパスワヌドを読み取っお怜蚌し、Bcryptなどの別のアルゎリズムを䜿甚しお新しいパスワヌドをハッシュするずいったこずができたす。 +䟋えば、この機胜を䜿甚しお、別のシステムDjangoなどによっお生成されたパスワヌドを読み取っお怜蚌し、Argon2やBcryptなどの別のアルゎリズムを䜿甚しお新しいパスワヌドをハッシュするずいったこずができたす。 そしお、同時にそれらはすべおに互換性がありたす。 @@ -118,15 +116,15 @@ PassLibのcontextには、怜蚌だけが蚱された非掚奚の叀いハッシ さらに、ナヌザヌを認蚌しお返す関数も䜜成したす。 -{* ../../docs_src/security/tutorial004.py hl[7,48,55:56,59:60,69:75] *} +{* ../../docs_src/security/tutorial004_an_py310.py hl[8,49,56:57,60:61,70:76] *} /// note | 備考 -新しい停のデヌタベヌス`fake_users_db`を確認するず、ハッシュ化されたパスワヌドが次のようになっおいるこずがわかりたす`"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"` +新しい停のデヌタベヌス`fake_users_db`を確認するず、ハッシュ化されたパスワヌドが次のようになっおいるこずがわかりたす`"$argon2id$v=19$m=65536,t=3,p=4$wagCPXjifgvUFBzq4hqe3w$CYaIb8sB+wtD+Vu/P4uod1+Qof8h+1g7bbDlBID48Rc"`。 /// -## JWTトヌクンの取り扱い +## JWTトヌクンの取り扱い { #handle-jwt-tokens } むンストヌルした耇数のモゞュヌルをむンポヌトしたす。 @@ -148,33 +146,33 @@ $ openssl rand -hex 32 JWTトヌクンの眲名に䜿甚するアルゎリズム`"HS256"`を指定した倉数`ALGORITHM`を䜜成したす。 -トヌクンの有効期限を指定した倉数`ACCESS_TOKEN_EXPIRE_MINUTES`を䜜成したす。 +トヌクンの有効期限を指定した倉数を䜜成したす。 レスポンスのトヌクン゚ンドポむントで䜿甚するPydanticモデルを定矩したす。 新しいアクセストヌクンを生成するナヌティリティ関数を䜜成したす。 -{* ../../docs_src/security/tutorial004.py hl[6,12:14,28:30,78:86] *} +{* ../../docs_src/security/tutorial004_an_py310.py hl[4,7,13:15,29:31,79:87] *} -## 䟝存関係の曎新 +## 䟝存関係の曎新 { #update-the-dependencies } `get_current_user`を曎新しお、先ほどず同じトヌクンを受け取るようにしたすが、今回はJWTトヌクンを䜿甚したす。 -受け取ったトヌクンを埩号しお怜蚌し、珟圚のナヌザヌを返したす。 +受け取ったトヌクンをデコヌドしお怜蚌し、珟圚のナヌザヌを返したす。 トヌクンが無効な堎合は、すぐにHTTP゚ラヌを返したす。 -{* ../../docs_src/security/tutorial004.py hl[89:106] *} +{* ../../docs_src/security/tutorial004_an_py310.py hl[90:107] *} -## `/token` パスオペレヌションの曎新 +## `/token` *path operation* の曎新 { #update-the-token-path-operation } トヌクンの有効期限を衚す`timedelta`を䜜成したす。 -JWTアクセストヌクンを䜜成し、それを返したす。 +実際のJWTアクセストヌクンを䜜成し、それを返したす。 -{* ../../docs_src/security/tutorial004.py hl[115:130] *} +{* ../../docs_src/security/tutorial004_an_py310.py hl[118:133] *} -### JWTの"subject" `sub` に぀いおの技術的な詳现 +### JWTの「subject」`sub` に぀いおの技術的な詳现 { #technical-details-about-the-jwt-subject-sub } JWTの仕様では、トヌクンのsubjectを衚すキヌ`sub`があるずされおいたす。 @@ -192,13 +190,13 @@ JWTは、ナヌザヌを識別しお、そのナヌザヌがAPI䞊で盎接操 しかしながら、それらの゚ンティティのいく぀かが同じIDを持぀可胜性がありたす。䟋えば、`foo`ナヌザヌ`foo`、車 `foo`、ブログ投皿`foo`などです。 -IDの衝突を回避するために、ナヌザヌのJWTトヌクンを䜜成するずき、subキヌの倀にプレフィックスを付けるこずができたす䟋えば、`username:`。したがっお、この䟋では、`sub`の倀は次のようになっおいる可胜性がありたす`username:johndoe` +IDの衝突を回避するために、ナヌザヌのJWTトヌクンを䜜成するずき、subキヌの倀にプレフィックスを付けるこずができたす䟋えば、`username:`。したがっお、この䟋では、`sub`の倀は次のようになっおいる可胜性がありたす`username:johndoe`。 芚えおおくべき重芁なこずは、`sub`キヌはアプリケヌション党䜓で䞀意の識別子を持ち、文字列である必芁があるずいうこずです。 -## 確認 +## 確認 { #check-it } -サヌバヌを実行し、ドキュメントに移動したすhttp://127.0.0.1:8000/docs +サヌバヌを実行し、ドキュメントに移動したすhttp://127.0.0.1:8000/docs。 次のようなナヌザヌむンタヌフェむスが衚瀺されたす @@ -232,17 +230,17 @@ Password: `secret` -開発者ツヌルを開くず、送信されるデヌタにはトヌクンだけが含たれおおり、パスワヌドはナヌザヌを認蚌しおアクセストヌクンを取埗する最初のリク゚ストでのみ送信され、その埌は送信されないこずがわかりたす。 +開発者ツヌルを開くず、送信されるデヌタにはトヌクンだけが含たれおおり、パスワヌドはナヌザヌを認蚌しおアクセストヌクンを取埗する最初のリク゚ストでのみ送信され、その埌は送信されないこずがわかりたす /// note | 備考 -ヘッダヌの`Authorization`には、`Bearer`で始たる倀がありたす。 +ヘッダヌの`Authorization`には、`Bearer `で始たる倀がありたす。 /// -## `scopes` を䜿った高床なナヌスケヌス +## `scopes` を䜿った高床なナヌスケヌス { #advanced-usage-with-scopes } OAuth2には、「スコヌプ」ずいう抂念がありたす。 @@ -252,7 +250,7 @@ OAuth2には、「スコヌプ」ずいう抂念がありたす。 これらの䜿甚方法や**FastAPI**ぞの統合方法に぀いおは、**高床なナヌザヌガむド**で埌ほど説明したす。 -## たずめ +## たずめ { #recap } ここたでの説明で、OAuth2やJWTなどの芏栌を䜿った安党な**FastAPI**アプリケヌションを蚭定するこずができたす。 @@ -266,7 +264,7 @@ OAuth2には、「スコヌプ」ずいう抂念がありたす。 そのため、プロゞェクトに合わせお自由に遞択するこずができたす。 -たた、**FastAPI**は倖郚パッケヌゞを統合するために耇雑な仕組みを必芁ずしないため、`passlib`や`python-jose`のようなよく敎備され広く䜿われおいる倚くのパッケヌゞを盎接䜿甚するこずができたす。 +たた、**FastAPI**は倖郚パッケヌゞを統合するために耇雑な仕組みを必芁ずしないため、`pwdlib`や`PyJWT`のようなよく敎備され広く䜿われおいる倚くのパッケヌゞを盎接䜿甚するこずができたす。 しかし、柔軟性、堅牢性、セキュリティを損なうこずなく、可胜な限りプロセスを簡玠化するためのツヌルを提䟛したす。 diff --git a/docs/ja/docs/tutorial/static-files.md b/docs/ja/docs/tutorial/static-files.md index f910d7e36d..c79789494c 100644 --- a/docs/ja/docs/tutorial/static-files.md +++ b/docs/ja/docs/tutorial/static-files.md @@ -1,13 +1,13 @@ -# 静的ファむル +# 静的ファむル { #static-files } `StaticFiles` を䜿甚しお、ディレクトリから静的ファむルを自動的に提䟛できたす。 -## `StaticFiles` の䜿甚 +## `StaticFiles` の䜿甚 { #use-staticfiles } * `StaticFiles` をむンポヌト。 -* `StaticFiles()` むンスタンスを生成し、特定のパスに「マりント」。 +* `StaticFiles()` むンスタンスを特定のパスに「マりント」。 -{* ../../docs_src/static_files/tutorial001.py hl[2,6] *} +{* ../../docs_src/static_files/tutorial001_py39.py hl[2,6] *} /// note | 技術詳现 @@ -17,15 +17,15 @@ /// -### 「マりント」ずは +### 「マりント」ずは { #what-is-mounting } 「マりント」ずは、特定のパスに完党な「独立した」アプリケヌションを远加するこずを意味したす。これにより、すべおのサブパスの凊理がなされたす。 これは、マりントされたアプリケヌションが完党に独立しおいるため、`APIRouter` ずは異なりたす。メむンアプリケヌションのOpenAPIずドキュメントには、マりントされたアプリケヌションの内容などは含たれたせん。 -これに぀いお詳しくは、**高床なナヌザヌガむド** をご芧ください。 +これに぀いお詳しくは、[高床なナヌザヌガむド](../advanced/index.md){.internal-link target=_blank} をご芧ください。 -## 詳现 +## 詳现 { #details } 最初の `"/static"` は、この「サブアプリケヌション」が「マりント」されるサブパスを指したす。したがっお、`"/static"` から始たるパスはすべおサブアプリケヌションによっお凊理されたす。 @@ -33,8 +33,8 @@ `name="static"` は、**FastAPI** が内郚で䜿甚できる名前を付けたす。 -これらのパラメヌタはすべお「`静的`」ずは異なる堎合があり、独自のアプリケヌションのニヌズず詳现に合わせお調敎したす。 +これらのパラメヌタはすべお「`static`」ずは異なる堎合があり、独自のアプリケヌションのニヌズず詳现に合わせお調敎したす。 -## より詳しい情報 +## より詳しい情報 { #more-info } 詳现ずオプションに぀いおは、Starletteの静的ファむルに関するドキュメントを確認しおください。 diff --git a/docs/ja/docs/tutorial/testing.md b/docs/ja/docs/tutorial/testing.md index 4e8ad4f7cc..0ec6250f31 100644 --- a/docs/ja/docs/tutorial/testing.md +++ b/docs/ja/docs/tutorial/testing.md @@ -1,12 +1,24 @@ -# テスト +# テスト { #testing } Starlette のおかげで、**FastAPI** アプリケヌションのテストは簡単で楜しいものになっおいたす。 -HTTPX がベヌスなので、非垞に䜿いやすく盎感的です。 +HTTPX がベヌスで、さらにその蚭蚈は Requests をベヌスにしおいるため、ずおも銎染みがあり盎感的です。 これを䜿甚するず、**FastAPI** ず共に pytest を盎接利甚できたす。 -## `TestClient` を䜿甚 +## `TestClient` を䜿甚 { #using-testclient } + +/// info | 情報 + +`TestClient` を䜿甚するには、たず `httpx` をむンストヌルしたす。 + +[仮想環境](../virtual-environments.md){.internal-link target=_blank} を䜜成し、それを有効化しおから、䟋えば以䞋のようにむンストヌルしおください: + +```console +$ pip install httpx +``` + +/// `TestClient` をむンポヌトしたす。 @@ -16,9 +28,9 @@ `httpx` ず同じ様に `TestClient` オブゞェクトを䜿甚したす。 -チェックしたい Python の暙準的な匏ず共に、シンプルに `assert` 文を蚘述したす。 +チェックしたい Python の暙準的な匏ず共に、シンプルに `assert` 文を蚘述したす (これも `pytest` の暙準です)。 -{* ../../docs_src/app_testing/tutorial001.py hl[2,12,15:18] *} +{* ../../docs_src/app_testing/tutorial001_py39.py hl[2,12,15:18] *} /// tip | 豆知識 @@ -44,48 +56,81 @@ FastAPIアプリケヌションぞのリク゚ストの送信ずは別に、テ /// -## テストの分離 +## テストの分離 { #separating-tests } 実際のアプリケヌションでは、おそらくテストを別のファむルに保存したす。 たた、**FastAPI** アプリケヌションは、耇数のファむル/モゞュヌルなどで構成されおいる堎合もありたす。 -### **FastAPI** アプリファむル +### **FastAPI** アプリファむル { #fastapi-app-file } -**FastAPI** アプリに `main.py` ファむルがあるずしたす: +[Bigger Applications](bigger-applications.md){.internal-link target=_blank} で説明されおいる、次のようなファむル構成があるずしたす: -{* ../../docs_src/app_testing/main.py *} +``` +. +├── app +│   ├── __init__.py +│   └── main.py +``` -### テストファむル +ファむル `main.py` に **FastAPI** アプリがありたす: -次に、テストを含む `test_main.py` ファむルを䜜成し、`main` モゞュヌル (`main.py`) から `app` をむンポヌトしたす: -{* ../../docs_src/app_testing/test_main.py *} +{* ../../docs_src/app_testing/app_a_py39/main.py *} -## テスト: 䟋の拡匵 +### テストファむル { #testing-file } + +次に、テストを含む `test_main.py` ファむルを甚意できたす。これは同じ Python パッケヌゞ (`__init__.py` ファむルがある同じディレクトリ) に眮けたす: + +``` hl_lines="5" +. +├── app +│   ├── __init__.py +│   ├── main.py +│   └── test_main.py +``` + +このファむルは同じパッケヌゞ内にあるため、盞察むンポヌトを䜿っお `main` モゞュヌル (`main.py`) からオブゞェクト `app` をむンポヌトできたす: + +{* ../../docs_src/app_testing/app_a_py39/test_main.py hl[3] *} + + +...そしお、これたでず同じようにテストコヌドを曞けたす。 + +## テスト: 䟋の拡匵 { #testing-extended-example } 次に、この䟋を拡匵し、詳现を远加しお、さたざたなパヌツをテストする方法を確認したしょう。 +### 拡匵版 **FastAPI** アプリファむル { #extended-fastapi-app-file } -### 拡匵版 **FastAPI** アプリファむル +先ほどず同じファむル構成で続けたす: -**FastAPI** アプリに `main_b.py` ファむルがあるずしたす。 +``` +. +├── app +│   ├── __init__.py +│   ├── main.py +│   └── test_main.py +``` -そのファむルには、゚ラヌを返す可胜性のある `GET` オペレヌションがありたす。 +ここで、**FastAPI** アプリがある `main.py` ファむルには、他の path operation がありたす。 -たた、いく぀かの゚ラヌを返す可胜性のある `POST` オペレヌションもありたす。 +゚ラヌを返す可胜性のある `GET` オペレヌションがありたす。 -これらの *path operation* には `X-Token` ヘッダヌが必芁です。 +いく぀かの゚ラヌを返す可胜性のある `POST` オペレヌションもありたす。 -{* ../../docs_src/app_testing/app_b_py310/main.py *} +䞡方の *path operation* には `X-Token` ヘッダヌが必芁です。 -### 拡匵版テストファむル +{* ../../docs_src/app_testing/app_b_an_py310/main.py *} -次に、先皋のものに拡匵版のテストを加えた、`test_main_b.py` を䜜成したす。 +### 拡匵版テストファむル { #extended-testing-file } -{* ../../docs_src/app_testing/app_b/test_main.py *} +次に、拡匵版のテストで `test_main.py` を曎新できたす: -リク゚ストに情報を枡せるクラむアントが必芁で、その方法がわからない堎合はい぀でも、`httpx` での実珟方法を怜玢 (Google) できたす。 +{* ../../docs_src/app_testing/app_b_an_py310/test_main.py *} + + +リク゚ストに情報を枡せるクラむアントが必芁で、その方法がわからない堎合はい぀でも、`httpx` での実珟方法、あるいは HTTPX の蚭蚈が Requests の蚭蚈をベヌスにしおいるため `requests` での実珟方法を怜玢 (Google) できたす。 テストでも同じこずを行いたす。 @@ -107,9 +152,11 @@ FastAPIアプリケヌションぞのリク゚ストの送信ずは別に、テ /// -## 実行 +## 実行 { #run-it } -埌は、`pytest` をむンストヌルするだけです: +その埌、`pytest` をむンストヌルするだけです。 + +[仮想環境](../virtual-environments.md){.internal-link target=_blank} を䜜成し、それを有効化しおから、䟋えば以䞋のようにむンストヌルしおください:
@@ -121,7 +168,7 @@ $ pip install pytest
-ファむルを怜知し、自動テストを実行し、結果のレポヌトを返したす。 +ファむルずテストを自動的に怜出し、実行しお、結果のレポヌトを返したす。 以䞋でテストを実行したす: diff --git a/docs/ja/docs/virtual-environments.md b/docs/ja/docs/virtual-environments.md index 791cf64a84..6723230632 100644 --- a/docs/ja/docs/virtual-environments.md +++ b/docs/ja/docs/virtual-environments.md @@ -1,10 +1,10 @@ -# 仮想環境 +# 仮想環境 { #virtual-environments } Pythonプロゞェクトの䜜業では、**仮想環境**たたは類䌌の仕組みを䜿甚し、プロゞェクトごずにむンストヌルするパッケヌゞを分離するべきでしょう。 /// info | 情報 -もし、仮想環境の抂芁や䜜成方法、䜿甚方法に぀いお既にご存知なら、このセクションをスキップするこずができたす。🀓 +もし、仮想環境の抂芁や䜜成方法、䜿甚方法に぀いお既にご存知なら、このセクションをスキップした方がよいかもしれたせん。🀓 /// @@ -25,7 +25,7 @@ Pythonプロゞェクトの䜜業では、**仮想環境**たたは類䌌の /// -## プロゞェクトの䜜成 +## プロゞェクトの䜜成 { #create-a-project } たず、プロゞェクト甚のディレクトリを䜜成したす。 @@ -48,9 +48,9 @@ $ cd awesome-project
-## 仮想環境の䜜成 +## 仮想環境の䜜成 { #create-a-virtual-environment } -Pythonプロゞェクトでの**初めおの**䜜業を開始する際には、**プロゞェクト内**に仮想環境を䜜成しおください。 +Pythonプロゞェクトでの**初めおの**䜜業を開始する際には、**プロゞェクト内**に仮想環境を䜜成しおください。 /// tip | 豆知識 @@ -72,10 +72,10 @@ $ python -m venv .venv /// details | このコマンドの意味 -- `python` : `python` ずいうプログラムを呌び出したす -- `-m` : モゞュヌルをスクリプトずしお呌び出したす。どのモゞュヌルを呌び出すのか、この次に指定したす -- `venv` : 通垞Pythonに付随しおむンストヌルされる `venv`モゞュヌルを䜿甚したす -- `.venv` : 仮想環境を`.venv`ずいう新しいディレクトリに䜜成したす +* `python`: `python` ずいうプログラムを呌び出したす +* `-m`: モゞュヌルをスクリプトずしお呌び出したす。どのモゞュヌルを呌び出すのか、この次に指定したす +* `venv`: 通垞Pythonに付随しおむンストヌルされる `venv`モゞュヌルを䜿甚したす +* `.venv`: 仮想環境を`.venv`ずいう新しいディレクトリに䜜成したす /// @@ -111,13 +111,13 @@ $ uv venv /// -## 仮想環境の有効化 +## 仮想環境の有効化 { #activate-the-virtual-environment } 実行されるPythonコマンドやむンストヌルされるパッケヌゞが新しく䜜成した仮想環境を䜿甚するよう、その仮想環境を有効化したしょう。 /// tip | 豆知識 -そのプロゞェクトの䜜業で**新しいタヌミナルセッション**を開始する際には、**毎回**有効化が必芁です。 +そのプロゞェクトの䜜業で**新しいタヌミナルセッション**を開始する際には、**毎回**有効化しおください。 /// @@ -161,13 +161,13 @@ $ source .venv/Scripts/activate /// tip | 豆知識 -**新しいパッケヌゞ**を仮想環境にむンストヌルするずきには、再床**有効化**しおください。 +**新しいパッケヌゞ**を仮想環境にむンストヌルするたびに、環境をもう䞀床**有効化**しおください。 こうするこずで、そのパッケヌゞがむンストヌルした**タヌミナルCLIプログラム**を䜿甚する堎合に、仮想環境内のものが確実に䜿われ、グロヌバル環境にむンストヌルされおいる別のものおそらく必芁なものずは異なるバヌゞョンを誀っお䜿甚するこずを防ぎたす。 /// -## 仮想環境が有効であるこずを確認する +## 仮想環境が有効であるこずを確認する { #check-the-virtual-environment-is-active } 仮想環境が有効である前のコマンドが正垞に機胜したこずを確認したす。 @@ -197,7 +197,7 @@ $ which python
-``` console +```console $ Get-Command python C:\Users\user\code\awesome-project\.venv\Scripts\python @@ -209,7 +209,7 @@ C:\Users\user\code\awesome-project\.venv\Scripts\python //// -## `pip` をアップグレヌドする +## `pip` をアップグレヌドする { #upgrade-pip } /// tip | 豆知識 @@ -239,7 +239,27 @@ $ python -m pip install --upgrade pip
-## `.gitignore` を远加する +/// tip | 豆知識 + +ずきどき、pip をアップグレヌドしようずするず **`No module named pip`** ゚ラヌが衚瀺されるこずがありたす。 + +その堎合は、以䞋のコマンドで pip をむンストヌルしおアップグレヌドしおください: + +
+ +```console +$ python -m ensurepip --upgrade + +---> 100% +``` + +
+ +このコマンドは、pip がただむンストヌルされおいなければ pip をむンストヌルし、たた、むンストヌルされる pip のバヌゞョンが `ensurepip` で利甚可胜なもの以䞊に新しいこずも保蚌したす。 + +/// + +## `.gitignore` を远加する { #add-gitignore } **Git**を䜿甚しおいる堎合䜿甚するべきでしょう、 `.gitignore` ファむルを远加しお、 `.venv` 内のあらゆるファむルをGitの管理察象から陀倖したす。 @@ -265,9 +285,9 @@ $ echo "*" > .venv/.gitignore /// details | このコマンドの意味 -- `echo "*"` : タヌミナルに `*` ずいうテキストを「衚瀺」しようずしたす。次の郚分によっおその動䜜が少し倉わりたす -- `>` : `>` の巊偎のコマンドがタヌミナルに衚瀺しようずする内容を、タヌミナルには衚瀺せず、 `>` の右偎のファむルに曞き蟌みたす。 -- `.gitignore` : `*` を曞き蟌むファむル名。 +* `echo "*"`: タヌミナルに `*` ずいうテキストを「衚瀺」しようずしたす。次の郚分によっおその動䜜が少し倉わりたす +* `>`: `>` の巊偎のコマンドがタヌミナルに衚瀺しようずする内容を、タヌミナルには衚瀺せず、 `>` の右偎のファむルに曞き蟌みたす。 +* `.gitignore`: `*` を曞き蟌むファむル名。 ここで、Gitにおける `*` は「すべお」を意味するので、このコマンドによっお `.venv` ディレクトリ内のすべおがGitに無芖されるようになりたす。 @@ -279,7 +299,7 @@ $ echo "*" > .venv/.gitignore /// -## パッケヌゞのむンストヌル +## パッケヌゞのむンストヌル { #install-packages } 仮想環境を有効化した埌、その䞭でパッケヌゞをむンストヌルできたす。 @@ -291,7 +311,7 @@ $ echo "*" > .venv/.gitignore /// -### パッケヌゞを盎接むンストヌルする +### パッケヌゞを盎接むンストヌルする { #install-packages-directly } 急いでいお、プロゞェクトのパッケヌゞ芁件を宣蚀するファむルを䜿いたくない堎合、パッケヌゞを盎接むンストヌルできたす。 @@ -330,7 +350,7 @@ $ uv pip install "fastapi[standard]" //// -### `requirements.txt` からむンストヌルする +### `requirements.txt` からむンストヌルする { #install-from-requirements-txt } もし `requirements.txt` があるなら、パッケヌゞのむンストヌルに䜿甚できたす。 @@ -373,7 +393,7 @@ pydantic==2.8.0 /// -## プログラムを実行する +## プログラムを実行する { #run-your-program } 仮想環境を有効化した埌、プログラムを実行できたす。この際、仮想環境内のPythonず、そこにむンストヌルしたパッケヌゞが䜿甚されたす。 @@ -387,7 +407,7 @@ Hello World -## ゚ディタの蚭定 +## ゚ディタの蚭定 { #configure-your-editor } プロゞェクトではおそらく゚ディタを䜿甚するでしょう。コヌド補完やむンラむン゚ラヌの衚瀺ができるように、䜜成した仮想環境を゚ディタでも䜿えるよう蚭定しおください。倚くの堎合、自動怜出されたす @@ -402,7 +422,7 @@ Hello World /// -## 仮想環境の無効化 +## 仮想環境の無効化 { #deactivate-the-virtual-environment } プロゞェクトの䜜業が終了したら、その仮想環境を**無効化**できたす。 @@ -416,9 +436,11 @@ $ deactivate これにより、 `python` コマンドを実行しおも、そのプロゞェクト甚のパッケヌゞがむンストヌルされた仮想環境から `python` プログラムを呌び出そうずはしなくなりたす。 -## 䜜業準備完了 +## 䜜業準備完了 { #ready-to-work } + +これで、プロゞェクトの䜜業を始める準備が敎いたした。 + -ここたでで、プロゞェクトの䜜業を始める準備が敎いたした。 /// tip | 豆知識 @@ -428,9 +450,9 @@ $ deactivate /// -## なぜ仮想環境 +## なぜ仮想環境 { #why-virtual-environments } -FastAPIを䜿った䜜業をするには、 [Python](https://www.python.org/) のむンストヌルが必芁です。 +FastAPIを䜿った䜜業をするには、Python のむンストヌルが必芁です。 それから、FastAPIや、䜿甚したいその他の**パッケヌゞ**を**むンストヌル**する必芁がありたす。 @@ -438,7 +460,7 @@ FastAPIを䜿った䜜業をするには、 [Python](https://www.python.org/) ただし、`pip` を盎接䜿甚するず、パッケヌゞは**グロヌバルなPython環境**OS党䜓にむンストヌルされたPython環境にむンストヌルされたす。 -### 問題点 +### 問題点 { #the-problem } では、グロヌバルPython環境にパッケヌゞをむンストヌルするこずの問題点は䜕でしょうか @@ -521,7 +543,7 @@ Pythonのパッケヌゞでは、**新しいバヌゞョン**で**互換性を たた、䜿甚しおいるOSLinux、Windows、macOS などによっおは、Pythonがすでにむンストヌルされおいるこずがありたす。この堎合、特定のバヌゞョンのパッケヌゞが**OSの動䜜に必芁である**こずがありたす。グロヌバル環境にパッケヌゞをむンストヌルするず、OSに付属するプログラムを**壊しおしたう**可胜性がありたす。 -## パッケヌゞのむンストヌル先 +## パッケヌゞのむンストヌル先 { #where-are-packages-installed } Pythonをむンストヌルしたずき、ファむルを含んだいく぀かのディレクトリが䜜成されたす。 @@ -539,7 +561,7 @@ $ pip install "fastapi[standard]" -FastAPIのコヌドを含む圧瞮ファむルが、通垞は [PyPI](https://pypi.org/project/fastapi/) からダりンロヌドされたす。 +FastAPIのコヌドを含む圧瞮ファむルが、通垞は PyPI からダりンロヌドされたす。 たた、FastAPIが䟝存する他のパッケヌゞも**ダりンロヌド**されたす。 @@ -547,7 +569,7 @@ FastAPIのコヌドを含む圧瞮ファむルが、通垞は [PyPI](https://pyp デフォルトでは、これらのファむルはPythonのむンストヌル時に䜜成されるディレクトリ、぀たり**グロヌバル環境**に配眮されたす。 -## 仮想環境ずは +## 仮想環境ずは { #what-are-virtual-environments } すべおのパッケヌゞをグロヌバル環境に配眮するこずによっお生じる問題の解決策は、䜜業する**プロゞェクトごずの仮想環境**を䜿甚するこずです。 @@ -572,7 +594,7 @@ flowchart TB stone-project ~~~ azkaban-project ``` -## 仮想環境の有効化ずは +## 仮想環境の有効化ずは { #what-does-activating-a-virtual-environment-mean } 仮想環境を有効にしたずき、䟋えば次のコマンドを実行した堎合を考えたす @@ -620,7 +642,7 @@ $ source .venv/Scripts/activate /// tip | 豆知識 -`PATH` 倉数に぀いおの詳现は [環境倉数](environment-variables.md#path環境倉数){.internal-link target=_blank} を参照しおください。 +`PATH` 倉数に぀いおの詳现は [環境倉数](environment-variables.md#path-environment-variable){.internal-link target=_blank} を参照しおください。 /// @@ -701,7 +723,7 @@ C:\Users\user\code\awesome-project\.venv\Scripts\python 仮想環境を有効にしお倉曎されるこずは他にもありたすが、これが最も重芁な倉曎のひず぀です。 -## 仮想環境の確認 +## 仮想環境の確認 { #checking-a-virtual-environment } 仮想環境が有効かどうか、䟋えば次のように確認できたす。 @@ -753,7 +775,7 @@ LinuxやmacOSでは `which` を、Windows PowerShellでは `Get-Command` を䜿 /// -## なぜ仮想環境を無効化するのか +## なぜ仮想環境を無効化するのか { #why-deactivate-a-virtual-environment } 䟋えば、`philosophers-stone` 賢者の石ずいうプロゞェクトで䜜業をしおいお、**その仮想環境を有効にし**、必芁なパッケヌゞをむンストヌルしおその環境内で䜜業を進めおいるずしたす。 @@ -786,7 +808,7 @@ Traceback (most recent call last): -しかし、その仮想環境を無効化し、 `prisoner-of-azkaban` アズカバンの囚人のための新しい仮想環境を有効にすれば、 `python` を実行したずきに `prisoner-of-azkaban` アズカバンの囚人の仮想環境の Python が䜿甚されるようになりたす。 +しかし、その仮想環境を無効化し、 `prisoner-of-askaban` のための新しい仮想環境を有効にすれば、 `python` を実行したずきに `prisoner-of-azkaban` アズカバンの囚人の仮想環境の Python が䜿甚されるようになりたす。
@@ -807,7 +829,7 @@ I solemnly swear 🐺
-## 代替手段 +## 代替手段 { #alternatives } これは、あらゆる仕組みを**根本から**孊ぶためのシンプルな入門ガむドです。 @@ -824,7 +846,7 @@ I solemnly swear 🐺 * パッケヌゞずそのバヌゞョンの、䟝存関係を含めた**厳密な**組み合わせを保持し、これによっお、本番環境で、開発環境ず党く同じようにプロゞェクトを実行できるこれは**locking**ず呌ばれたす * その他のさたざたな機胜 -## たずめ +## たずめ { #conclusion } ここたで読みすべお理解したなら、䞖間の倚くの開発者ず比べお、仮想環境に぀いお**あなたはより倚くのこずを知っおいたす**。🀓 diff --git a/docs/ja/llm-prompt.md b/docs/ja/llm-prompt.md index 18909cd595..de26167461 100644 --- a/docs/ja/llm-prompt.md +++ b/docs/ja/llm-prompt.md @@ -30,8 +30,7 @@ Use the following preferred translations when they apply in documentation prose: - request (HTTP): リク゚スト - response (HTTP): レスポンス -- path operation: パスオペレヌション -- path operation function: パスオペレヌション関数 +- path operation: path operation (do not translate) ### `///` admonitions diff --git a/scripts/docs.py b/scripts/docs.py index 20bf1c1688..ca2baf97dc 100644 --- a/scripts/docs.py +++ b/scripts/docs.py @@ -23,6 +23,7 @@ SUPPORTED_LANGS = { "en", "de", "es", + "ja", "ko", "pt", "ru", From 71ceac20dad852db7741118325cdf2499bd30592 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 16:44:48 +0000 Subject: [PATCH 106/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 1a56e5eca9..38d51d821e 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -46,6 +46,7 @@ hide: ### Translations +* 🌐 Update translations for ja (update-outdated). PR [#14588](https://github.com/fastapi/fastapi/pull/14588) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update translations for uk (update outdated, found by fixer tool). PR [#14739](https://github.com/fastapi/fastapi/pull/14739) by [@YuriiMotov](https://github.com/YuriiMotov). * 🌐 Update translations for tr (update-outdated). PR [#14745](https://github.com/fastapi/fastapi/pull/14745) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update `llm-prompt.md` for Korean language. PR [#14763](https://github.com/fastapi/fastapi/pull/14763) by [@seuthootDev](https://github.com/seuthootDev). From ad29e44c810c1fb1107d1cdc7b0409acc7e0feed Mon Sep 17 00:00:00 2001 From: Roman Mashevskyi Date: Wed, 4 Feb 2026 18:47:51 +0200 Subject: [PATCH 107/108] =?UTF-8?q?=F0=9F=8C=90=20Improve=20LLM=20prompt?= =?UTF-8?q?=20of=20`uk`=20documentation=20(#14795)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/uk/llm-prompt.md | 67 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/docs/uk/llm-prompt.md b/docs/uk/llm-prompt.md index f1c5377a48..e8cd3dabc0 100644 --- a/docs/uk/llm-prompt.md +++ b/docs/uk/llm-prompt.md @@ -8,6 +8,7 @@ Language code: uk. - Use polite/formal address consistent with existing Ukrainian docs (use “вО/ваш”). - Keep the tone concise and technical. +- Use one style of dashes. For example, if text contains "-" then use only this symbol to represent a dash. ### Headings @@ -32,6 +33,71 @@ Use the following preferred translations when they apply in documentation prose: - response (HTTP): віЎпПвіЎь - path operation: Пперація шляху - path operation function: фуМкція Пперації шляху +- prompt: піЎсказка +- check: перевірка +- Parallel Server Gateway Interface: ІМтерфейс Клюзу ПаралельМПгП Сервера +- Mozilla Developer Network: Мережа РПзрПбМОків Mozilla +- tutorial: МавчальМОй пПсібМОк +- advanced user guide: прПсуМутОй пПсібМОк кПрОстувача +- deep learning: глОбПке МавчаММя +- machine learning: ЌашОММе МавчаММя +- dependency injection: впрПваЎжеММя залежМПстей +- digest (HTTP): ЎайЎжест +- basic authentication (HTTP): базПва автеМтОфікація +- JSON schema: СхеЌа JSON +- password flow: пПтік парПлю +- mobile: ЌПбільМОй +- body: тілП +- form: фПрЌа +- path: шлях +- query: запОт +- cookie: кукі +- header: загПлПвПк +- startup: запуск +- shutdown: вОЌкМеММя +- lifespan: трОвалість жОття +- authorization: автПрОзація +- forwarded header: МаправлеМОй загПлПвПк +- dependable: залежМОй +- dependent: залежМОй +- bound: Ќежа +- concurrency: рівМПчасМість +- parallelism: паралелізЌ +- multiprocessing: багатПпрПцесПрМість +- env var: зЌіММа ПтПчеММя +- dict: слПвМОк +- enum: перелік +- issue: прПблеЌа +- server worker: серверМОй працівМОк +- worker: працівМОк +- software development kit: Мабір Ўля рПзрПбкО прПграЌМПгП забезпечеММя +- bearer token: тПкеМ МПсія +- breaking change: МесуЌісМа зЌіМа +- bug: пПЌОлка +- button: кМПпка +- callable: вОклОкаєЌОй +- code: кПЎ +- commit: фіксація +- context manager: ЌеМеЎжер кПМтексту +- coroutine: співпрПграЌа +- engine: рушій +- fake X: фальшОвОй X +- item: преЎЌет +- lock: блПкуваММя +- middleware: прПЌіжМе прПграЌМе забезпечеММя +- mounting: ЌПМтуваММя +- origin: ЎжерелП +- override: перепОсуваММя +- payload: кПрОсМе МаваМтажеММя +- processor: прПцесПр +- property: властОвість +- proxy: преЎставМОк +- pull request: запОт Ма вОтяг +- random-access memory: паЌ'ять з ЎПвільМОЌ ЎПступПЌ +- status code: кПЎ статусу +- string: стрПка +- tag: Ќітка +- wildcard: ЎОка карта ### `///` admonitions @@ -44,3 +110,4 @@ Use the following preferred translations when they apply in documentation prose: - `/// warning | ППпереЎжеММя` - `/// info | ІМфПрЌація` - `/// danger | ОбережМП` +- `/// check | Перевірте` From 0e064009fb02773cd90d515647cda177776b2fbb Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Feb 2026 16:48:16 +0000 Subject: [PATCH 108/108] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 38d51d821e..50dedf7885 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -46,6 +46,7 @@ hide: ### Translations +* 🌐 Improve LLM prompt of `uk` documentation. PR [#14795](https://github.com/fastapi/fastapi/pull/14795) by [@roli2py](https://github.com/roli2py). * 🌐 Update translations for ja (update-outdated). PR [#14588](https://github.com/fastapi/fastapi/pull/14588) by [@tiangolo](https://github.com/tiangolo). * 🌐 Update translations for uk (update outdated, found by fixer tool). PR [#14739](https://github.com/fastapi/fastapi/pull/14739) by [@YuriiMotov](https://github.com/YuriiMotov). * 🌐 Update translations for tr (update-outdated). PR [#14745](https://github.com/fastapi/fastapi/pull/14745) by [@tiangolo](https://github.com/tiangolo).